# Harness Architecture: Big Picture

Superpowers Engineering Harness is deterministic control plane around agent development work. Agents and skills make engineering judgments. Harness persists artifacts, validates relations, controls state transitions, and blocks unsupported completion claims.

```text
User requirement
      │
      ▼
Task Contract
Requirements + Invariants + Risk + Test Plan + Observability
      │
      ▼
State machine
CREATED → CLASSIFIED → SPECIFYING → PLANNED → IMPLEMENTING
                                      │              │
                                      │              └─ TDD / Finding lifecycle
                                      ▼
VERIFYING → REVIEWING → GATING → CONVERGED → DONE
     │            │          │
     │            │          └─ Gate: evidence + freshness + findings + Contracts
     │            └─ complexity / diagnosability / code review
     └─ deterministic test and build proof
```

## Control-plane boundary

```text
Agent / skill
  - interpret requirement
  - inspect source
  - propose Contract, review, Finding, test, fix
  - run approved commands

Harness
  - persist canonical artifacts
  - validate schema and cross-artifact semantics
  - stage/publish review artifacts
  - enforce legal state transitions
  - calculate product evidence freshness separately from control-plane integrity
  - fail-close Gate
```

Harness does not replace code review, business judgment, logging framework choice, or source-code implementation.

## Canonical artifacts

```text
.harness/
├── current-task.yaml       task, state, risk, authorizations, Git baseline
├── requirements.yaml       acceptance requirements and test bindings
├── invariants.yaml         non-negotiable properties and test bindings
├── observability.yaml      Q2/Q3 diagnosability Contract
├── findings/               one Finding per canonical YAML artifact
├── evidence/               command proof, review proof, freshness identity
├── gate.yaml               Gate projection
└── .staging/               uncommitted multi-artifact publish sets
```

Artifacts are source of truth. Status is projection, not separate truth.

## v0.2.7 ownership and convergence

`scope.owned_paths` defines review/verification ownership. `scope.protected_user_paths` remains part of product workspace freshness, but never enters task review scope without explicit adoption.

Product test/build evidence uses the product workspace fingerprint (code, tests, dependencies, non-control-plane config). `.harness/` task state, evidence files, review outcomes, and requirement/invariant verification metadata use a separate control-plane fingerprint and do not stale product proof. Covered tests canonicalize to repository-root paths so subproject cwd selectors bind to test-plan paths.

Diagnosability reviewers publish proposals, not persistent findings. Harness validates, deduplicates, allocates `FND-NNN`, and atomically writes finding plus review evidence mapping. A FIXED finding returns to REVIEWING only through `harness finding resume-review`.

Evidence references resolve ID, filename, canonical relative path, or canonical absolute path. `evidence run` executes commands; `evidence attach` imports complete external provenance without command execution.

Gate assessment separates `quality` from `release_readiness`. A quality PASS is MR-ready only when readiness is READY; DRAFT_ONLY never emits Ready MR output.

## Core proof loops

```text
Requirement → executable test binding → fresh Evidence → Gate

Review failure → Finding → reproduce RED → fix GREEN → verify → Gate

Already on the reference branch → GREEN evidence → verify-existing
                               → ordinary bugfix still RED → GREEN

Diagnosability Contract → scope-bound review → DIAG Finding when failed
                       → static-compliance closure → Gate
```

A test that is not bound to Requirement/Invariant is useful regression coverage, but does not prove a Contract item. Evidence that is stale, mismatched, or missing required coverage does not satisfy Gate.

## Risk routing

```text
Q0  answer only; no Harness task
Q1  FAST: RED / fix / GREEN / Light Gate; already-implemented work may use
    verify-existing (valid persisted record + GREEN, no forged RED) from CLASSIFIED or PLANNED;
    requires_reproduction leaves CLASSIFIED for normal finding/reproduce workflow
Q2  STANDARD: Task Contract, verification, review, Gate
Q3  STRICT: Q2 plus mandatory non-sentinel Observability Contract and fresh diagnosability review
```

Risk can escalate but never downgrade. User authorization controls Harness actions such as commit, push, and release; it does not prove external actions did not occur. Harness never executes a full-suite test command: only impact-related verification is allowed, even when AGENTS.md requests otherwise. Related test evidence is append-only by command and covered-test identity; Gate unions fresh coverage records. `VERIFYING → REVIEWING` performs Gate freshness preflight, and STANDARD/STRICT plans reject missing declared test target files before implementation.

## Diagnosability review integrity

```text
Review input
      │
      ▼
input validation
      │
      ▼
readiness validation
Contract + Findings + Scope + Git HEAD + product workspace fingerprint
      │
      ▼
.harness/.staging/<operation-id>/
      │
      ▼
publish canonical Findings + review evidence
      │
      ▼
Gate / Finding closure
```

Failed checks require linked, in-scope DIAG Findings. Contract mismatch, unsupported `not_applicable`, stale review identity, and invalid Finding linkage fail closed. A review with failed checks routes to DEFECT; it cannot make Gate pass.

## Release boundary

```text
Feature complete
→ focused verification
→ review / Gate PASS
→ version + changelog
→ impact-related verification only
→ package checks
→ commit + push
→ immutable annotated tag
→ GitHub Release
```

Never move published tags. A fix after release becomes next patch release.