Superpowers Engineering Harness v0.2.7

简体中文

v0.2.7 current release; risk-adaptive behavior, task ownership, finding-aware review recovery, evidence run/attach, Gate preflight, dual-axis readiness, and auditable complexity review are included in this release. Decision and Interface Contracts now use task-scoped Gate participation, explicit cross-task interface reuse, validated Decision references, safe supersession, and canonical artifact identifiers. Product test/build evidence freshness uses the product workspace fingerprint, not .harness/ control-plane writes. Covered tests canonicalize to repository-root paths.

Routing: Q0 answers without task; Q1 / FAST uses RED/fix/GREEN/Light Gate; Q2 / STANDARD and Q3 / STRICT use full contract/review/Gate workflow.

Architecture: big picture

Engineering Harness is deterministic control plane around Superpowers development workflows. It does not replace agent or worker skills. It persists task state, requires proof, and prevents an agent from declaring work done without gate approval.

Why

AI coding workflows commonly fail when context is lost, completion is self-declared, tests/evidence are stale, review findings are never reproduced, repair loops do not converge, or correct code contains unnecessary complexity.

Harness turns these into persisted, checkable controls:

State + Contract + Invariant + Executable Test + Evidence + Deterministic Gate

Design model

Layer	Responsibility
Model	Worker that reasons and changes code
Superpowers	Development workflow: design, planning, TDD, review
Engineering Harness	Controller: state, contracts, evidence, findings, gate
Tests / compiler / gate	Source of truth

Harness is suitable for agentic feature and bug-fix delivery. It is not a replacement for CI, security scanning, or human architecture decisions.

Version evolution

v0.1    State + Evidence + Gate
  ↓
v0.2    Minimal Implementation + Complexity Review
  ↓
v0.2.3  Q0/Q1/Q2/Q3 risk-adaptive workflow
  ↓
v0.2.4  Test Plan → executable binding → fresh evidence
  ↓
v0.2.6  Production Diagnosability Contract + DIAG Finding + Gate
  ↓
v0.2.7  Task Ownership + Review Convergence + Gate Readiness
        + product freshness / canonical covered tests

Engineering Quality

                         Requirement
                             │
                             ▼
          Contract / Invariants / Test Plan
                             │
                             ▼
                    Implementation
                             │
          ┌──────────────────┼──────────────────┐
          ▼                  ▼                  ▼
     Correctness        Maintainability    Diagnosability
       Tests         Complexity Review   Logs / Trace Context
          │                  │                  │
          └──────────────────┼──────────────────┘
                             ▼
                  Evidence + Review + Findings
                             │
                             ▼
                 Deterministic Quality Gate
                             │
                             ▼
                            DONE

Harness controls state, proof, Finding lifecycle, and Gate. Agent judges business semantics and logging quality. Harness does not provide logger SDK, OpenTelemetry, APM, automatic log insertion, or universal source scanning.

Workflow

Requirement
  ↓
Risk classification (CREATED → CLASSIFIED) → Task Contract (CLASSIFIED → PLANNED)
  ↓
Minimal Implementation Check — PREVENT
  ↓
Implementation / TDD (IMPLEMENTING)
  ↓
Verification + fresh evidence (VERIFYING)
  ↓
Complexity Reviewer — DETECT
  ↓
Adversarial review / finding reproduction (REVIEWING)
  ↓
Quality Gate (GATING)
  ↓
CONVERGED → DONE

Iron laws:

1. Task state lives in .harness/current-task.yaml, never only model context.
2. Fixed state machine controls transitions.
3. Gate PASS is required before CONVERGED → DONE.
4. Confirmed bugs require regression tests.
5. Evidence is fresh and bound to current Git HEAD/workspace.
6. Bounded iteration ends in ESCALATED, not infinite repair.

Quick start

Install worker workflows, Harness skills, and deterministic CLI:

pi install git:github.com/obra/superpowers
pi install git:github.com/yezhwi/superpowers-engineering-harness
pip install -e /path/to/superpowers-engineering-harness

Initialize target repository, then start each session from persisted state:

cd your-project
harness init
harness status

Ask agent to work through Harness, for example:

Use Engineering Harness to fix this bug: cancelling an order twice issues two refunds.

For Pi, open new session after installing skills. Skills load at session start.

Daily operations

Security boundary: harness evidence run --command executes shell syntax (shell=True) as trusted text entered directly by local Harness operator.

Never forward remote requests, configuration values, API payloads, CI metadata, or other untrusted input to this option. Internal _collect is unsupported internal API, not Python access control or provenance proof.

Gate and Finding contract: Only harness gate evaluates or persists product Gate results; direct python scripts/quality_gate.py is disabled. Persisted Findings require an explicit category (adversarial, diagnosability, complexity, or interface); category-less legacy records fail with MIGRATION_REQUIRED. finding.schema.json was removed; use category-specific schemas.

Normal success path (review outcome PASS performs REVIEWING → GATING):

harness status
harness transition IMPLEMENTING
harness evidence run --type unit_test --command "pytest tests/test_cancel.py"
harness transition VERIFYING
harness review complexity --file review.yaml
harness transition REVIEWING
harness review outcome PASS --reason-code REVIEW_CLEAN
harness gate
# inspect DECISION: CONVERGED, then:
harness transition DONE

Blocked recovery path (harness gate emits DECISION: CONTINUE; Gate persists blockers and harness resume derives target):

harness gate
# after DECISION: CONTINUE
harness resume

Before VERIFYING, record impact and related tests. Full suite needs explicit authorization:

harness impact add-change src/orders/cancel.py
harness impact add-test tests/test_cancel.py::test_duplicate_cancel_single_refund
harness authorize full-suite
harness evidence run --type unit_test --scope full_suite --command "pytest"

Recover interrupted work with harness status; Harness resumes from .harness/current-task.yaml. Gate recovery derives target from blocker code, not persisted recover_to. Review reasons are controlled: use REVIEW_CLEAN, TEST_COVERAGE_INSUFFICIENT, EVIDENCE_INCOMPLETE, INVARIANT_UNPROVEN, TEST_SCOPE_INSUFFICIENT, LOGIC_ERROR, REGRESSION, CONTRACT_VIOLATION, or INVARIANT_VIOLATION for matching outcome.

Risk-adaptive workflow (v0.2.3)

• Q0: direct answer; no Harness task.
• Q1 / FAST: narrow, low-risk work only. Classify explicitly; FAST still needs task-level failing RED and passing GREEN evidence, then Light Gate. It skips impact, complexity review, requirements, and invariants ceremony.
• Q2 / STANDARD and Q3 / STRICT: use current full Harness workflow. Risk may only escalate, never downgrade.

harness task classify --level Q1 --scope low --contract none --data none \
  --authorization none --security none --concurrency none --deployment none
harness transition IMPLEMENTING
# collect a failing regression proof before fix, then passing proof after fix
harness evidence run --type unit_test --phase red --covered-test tests/test_x.py::test_x --command "pytest tests/test_x.py::test_x"
harness evidence run --type unit_test --phase green --covered-test tests/test_x.py::test_x --command "pytest tests/test_x.py::test_x"
harness transition VERIFYING
harness transition GATING
harness gate

FAST does not grant external actions. Authorizations are independent per task; grant only requested action:

harness authorize commit
harness authorize full-suite
harness authorize push
# also: create-mr, ready-mr, merge, deploy; revoke with revoke-<action>

Evidence reuse, soft budgets, local telemetry, and fixture benchmarks are available. Remote telemetry and external-agent benchmark claims are unavailable.

FAST repository verification

FAST always requires RED/GREEN plus fresh build evidence by default. Configure project-specific checks under gate.fast.verification; typecheck is opt-in:

fast:
  verification:
    build: required
    typecheck: optional

Missing, failed, or stale required evidence blocks with FAST_REPOSITORY_VERIFICATION_MISSING and returns to verification. Authorization grants control Harness actions only; Harness cannot detect actions executed outside Harness.

Decision records and Interface-first contracts

Consequential user choices persist outside chat history. Agent proposes facts, options, recommendation, reasons, trade-offs, and impact; user confirmation becomes an immutable Decision Record. Review active decisions at session startup:

harness decision propose --topic cache --question "Which cache?" --context "Redis exists" --option local="in-process" --option redis="shared" --recommend redis --reason "existing infrastructure"
harness decision accept DEC-001 --option redis
harness decision list

External/public API, SDK, plugin, event, CLI, and cross-module service boundaries need Interface Contract before implementation. Declare consumers, input/output/error semantics, compatibility, and verification. Known breaking change needs explicit approval; private helpers need no contract.

harness interface declare --name orders-api --kind http --consumer web-client --input "request schema" --output "response schema" --error "stable codes" --compatibility compatible --rationale "additive field"
harness impact add-interface INT-001 --kind http --consumer web-client --compatibility compatible --contract-id INT-001

Q1 external-interface impact fails with PUBLIC_INTERFACE_RISK_ESCALATION_REQUIRED; escalate explicitly. Gate blocks unresolved decisions, missing interface contract/compatibility/verification, and unapproved known breaking change.

FAST risk boundaries

FAST never infers API/security risk from keywords. Declare changed-risk paths in .harness/risk-boundaries.yaml:

boundaries:
  q2: [src/**/api/**, schemas/**]
  q3: [auth/**, permissions/**, migrations/**]

Business changes without policy block with RISK_REVALIDATION_POLICY_MISSING; boundary changes above Q1 block with RISK_ESCALATION_REQUIRED. Escalate explicitly:

harness task escalate --level Q2 --reason "public contract changed"

docs/, tests/, test/, and root Markdown-only changes do not require policy.

Evidence reuse

Reuse is explicit and same-task only:

harness evidence run --type build --command "python -m pip wheel . --no-deps" --reuse-if-valid

EVIDENCE_REUSED means no command ran. Reuse needs prior success plus exact command/proof identity, unchanged HEAD and product workspace fingerprint, and exact runtime. Any mismatch runs command normally.

Product evidence freshness and covered-test paths

Test/build evidence is fresh against the product workspace fingerprint (product code, tests, dependencies, and non-control-plane config). A separate control-plane fingerprint covers .harness/ task state, evidence files, review outcomes, and requirement/invariant verification metadata.

Writing control-plane records does not stale product proof. After collecting related tests, harness requirement verify, harness invariant verify, complexity/diagnosability review, and harness review outcome may update .harness/ without forcing a product-test rerun. Editing product code, product tests, or in-scope non-control-plane config still marks evidence EVIDENCE_WORKSPACE_STALE. Tampered evidence payload, invalid bindings, and invalid control-plane schema still block Gate; those failures are not reported as product-test stale.

Covered tests store repository-root canonical paths. A command that cds into a subproject still binds to the test-plan path:

harness evidence run --type unit_test --scope related \
  --covered-test backend/tests/foo.py \
  --command "sh -lc 'cd backend && pytest tests/foo.py'"

harness evidence run --type unit_test --scope related \
  --covered-test agents-frontend/src/__tests__/foo.spec.ts \
  --command "sh -lc 'cd agents-frontend && npx vitest run src/__tests__/foo.spec.ts'"

The same test run from repo root or the subproject directory stores the same canonical covered-test path. Collection rejects a canonical path that does not exist, escapes the repository, uses an invalid relative cd, or was not selected by the command (COVERED_TEST_NOT_EXECUTED, COVERED_TEST_PATH_INVALID). Older evidence that stored a cwd-relative selector still binds; the next collection migrates it to the canonical path.

Adaptive operations

Evidence blockers recover through harness resume; review test gaps use harness review outcome VERIFICATION_GAP --reason-code TEST_COVERAGE_INSUFFICIENT. Do not use direct state shortcuts.

FAST evidence budgets are soft: test 2, build 1, repeated retry 1. Over budget requires all override fields:

harness evidence run --type build --command "python -m pip wheel ." --budget-override-reason "new evidence" --budget-override-evidence build.json --budget-override-hypothesis "packaging path"

Local-only telemetry: harness telemetry show. It measures elapsed_seconds, harness_command_calls, and evidence counts. Agent metrics remain unavailable: token_estimate: null, tool calls/search rounds null. Run fixture validation: harness benchmark run --fixtures benchmarks/fixtures.

Compare recorded baseline/adaptive artifacts:

harness benchmark compare --fixtures benchmarks/fixtures --baseline baseline-artifacts --adaptive adaptive-artifacts

Comparison requires every fixture-required correctness field to be true in both artifacts. Missing proof is INCONCLUSIVE, not correctness preserved. Harness does not run or attest external agent runs, tokens, or tool calls.

Automatic orchestration

When Engineering Harness Skill controls a task, it automatically invokes Minimal Implementation Check in PLANNED, records impact analysis before VERIFYING, and invokes Complexity Reviewer after green verification but before REVIEWING. State guards reject skipped records. Full-suite authorization remains an explicit human decision.

v0.2: necessary complexity

Before implementation, Minimal Implementation Check records Decision Ladder result. Search in order: existence, repository reuse, stdlib, platform-native capability, installed dependency, local implementation, then minimum new abstraction.

harness check minimal --file minimal-implementation.yaml

After verification, Complexity Reviewer inspects changed diff and may create evidence-backed CPLX-* findings only for DELETE, REUSE, STDLIB, NATIVE, YAGNI, or SHRINK.

harness review complexity --file complexity-review.yaml
# Optional override: harness review complexity --base origin/main --file complexity-review.yaml

Open HIGH complexity findings block gate. MEDIUM and LOW findings are advisory. Necessary security, authorization, audit, compatibility, migration, accessibility, and NFR complexity is not automatically over-engineering. Complexity review defaults to task Git baseline, covering committed, staged, unstaged, and relevant untracked changes; --base is an explicit override.

Production diagnosability (v0.2.6)

Q0 skips diagnosability. Q1 may perform an agent advisory business-ID, exception-context, and sensitive-data check; it is routing-only, not persisted Core/Gate proof. Q2 requires .harness/observability.yaml and harness review diagnosability only when the Contract is required. Q3 always requires valid applicability and fresh review evidence. Harness validates artifacts and Gate state; it does not provide a logging SDK, OpenTelemetry, automatic log insertion, or universal source scanning.

Dependencies and token use

Harness depends on Superpowers worker skills, especially brainstorming, writing-plans, TDD, review, and verification. Harness controls their delivery loop; it does not duplicate them.

Caveman Mode is recommended to reduce agent output tokens. Keep code, commands, errors, evidence, and state technically complete.

Docs and development

• Architecture: big picture
• Evidence freshness and test path binding
• v0.2.2 flow hardening design
• v0.2 design
• Worked lifecycle example
• Historical v0.1 implementation guide

python -m pytest tests/ -q

License

Apache-2.0 © 2026 Yezhiwei