Skip to content

ADR-0008: Harness V3.1 objective governance — versioned Git Objectives with separated THINK, OWN, DO and JUDGE

Date: 2026-08-30 Status: Accepted (2026-08-30). Lifecycle completed per the build-p1 spec v2: the ADR opened as proposed for independent review; the independent content review reached APPROVE (round 2, t_f5f1fb23) with green CI, and this narrow in-PR transition updates front matter, this human status line and the decisions index atomically, with all DocOps gates re-run. Landing the pilot is NOT automatic standing governance — V3.1 becoming standing governance is recorded only after the accepted ADR is merged and the pilot verdict is in, per the promotion matrix of OBJ-HARNESS-V31-001.

Context

Wetopi is built and operated by an AI-agent harness (Hermes Kanban lanes: discovery / build / ops / senior / approver) supervised by one human operator. Two structural risks have surfaced during Phases 0–4:

  1. Work definition lives only in operational state. The Kanban board (and the Work Ledger that will supersede it) is excellent for live coordination but is mutable, profile-local, and not reviewable as a versioned contract. WHAT we are building, WHY, and the definition of DONE deserve a reviewed, versioned, auditable source that survives board churn.
  2. One agent can currently both define and judge work. Without a role separation, the harness risks self-confirmation: the agent that wrote a plan also reviews it, and execution shortcuts (auto-continuation, degraded lanes, capability substitutions) can silently weaken review discipline.

Harness V3.1 is the pilot that addresses both: versioned Git Objectives plus a strict role separation. This ADR records the governance decisions; ARCH-HARNESS-V31-GOVERNANCE documents the operating model (roles, gates, degraded routing, fail-closed state machine); OBJ-HARNESS-V31-001 is the first Objective exercising the mechanism end-to-end.

This ADR follows the accepted decision conventions (ADR-0003 among them) and does not modify any infrastructure responsibility split — it is agent-governance only. It is consistent with ADR-0003's principle of separate, explicit sources of truth per lifecycle.

Decision

  1. Role separation THINK / OWN / DO / JUDGE. Harness work is split into four non-overlapping roles:
Role Lane / actor Responsibility Explicitly NOT allowed
THINK (Architect) architect capability (e.g. an architect-designated profile or the operator acting as architect) Define WHAT, WHY and DONE as an Objective Draft: outcome, context, acceptance criteria, verification contract, constraints, boundaries, stop conditions Git write, execution, card claiming, review of own draft
OWN (Lead) wetopi-lead Acquire the accepted Objective, decompose it into cards, dispatch, maintain the Execution Ledger, own the documentation handoff Authoring the Objective's WHAT/WHY/DONE it did not receive; judging deliveries
DO (workers) wetopi-build, wetopi-senior, wetopi-ops (read-only ops) Implement cards within objective boundaries, self-validate, deliver evidence Applying/destroying real infrastructure from build cards; approving own work
JUDGE (independent review) wetopi-approver or a reviewer that did not implement Verify deliveries against the Objective's verification contract; record verdicts (APPROVE / REQUEST_CHANGES / REJECT) Implementing; merging without operator authority

  1. The Architect has no Git write. The Architect produces the Objective Draft (WHAT/WHY/DONE) and hands it to the Lead. The draft enters Git only through a separate Lead/Docs task that opens the documentation PR. This PR — not the draft itself — is the reviewed, mergeable artifact. The Architect may propose, comment, and answer questions, but never pushes branches or commits.

  2. Lead acquires and maintains execution. Once an Objective is accepted, the Lead OWNs its execution: decomposition into cards, assignment to lanes, the Execution Ledger (single-writer, Lead-owned), and the documentation PRs that land Objective artifacts in Git. The Kanban board and Work Ledger remain the operational state (level 1); the Git Objective is the versioned contract (level 2). The ledger references the Objective (commit/PR SHA); the Objective never copies ledger state. Never copied into Git: live snapshots, .env, auth.json, tokens, connection URLs, credential hashes, pool output, or any secret — Git holds contracts and evidence references, never live operational state (DocOps §1 authority model preserved).

  3. Build/PR is separated from apply. No build or documentation card applies or destroys real infrastructure. Apply runs only from explicitly authorized ops cards following reviewed runbooks with the human gate — the standing platform rule. The Objective layer does not change it: an Objective's verification contract may REQUIRE an apply as a follow-up ops card, but the build/PR deliverable itself never executes one.

  4. Review is conditional and fail-closed. A delivery is NOT done until its verification contract passes independent review. If the reviewer is unavailable, the verdict is missing, or evidence is incomplete, the outcome is blocked, never silently accepted. goal_mode (automatic goal continuation) never substitutes for review — it may drive a worker's iteration budget, but the JUDGE step remains a separate, human-supervised gate. goal_mode is additionally capability-gated like Qwen local: it stays DISABLED for real Objectives until a non-mutating P2 smoke proves the fail-closed contract — DONE requires AC evidence + Lead audit + independent APPROVE (never auto-done); CONTINUE/FAIL honor a bounded turn budget; provider timeout/offline and any failure land Blocked and leave goal_mode disabled; restarts deduplicate to a single reconciled run; no external mutation in any case. It remains disabled on any failure; the full enablement gate and smoke contract are specified in ARCH-HARNESS-V31-GOVERNANCE

  5. Qwen local is capability-gated and may remain excluded. Local-model participants (Qwen via Ollama) may take part in the pilot only if a capability gate passes (adequate reasoning/verbosity for the assigned role) AND the economics gate of Decision 9 passes. If either fails or availability degrades (e.g. multi-day provider cooldowns), Qwen local is simply excluded — exclusion never weakens any other gate and never blocks the role design; work routes to available capable lanes or blocks, fail-closed.

  6. Backup, restoration and rollback triggers. The level-1 operational stores (Kanban DB, Work Ledger) are backed up on a defined schedule with a documented restore procedure (ledger template carries the backup/restore locator field). The level-2 Git contract is its own backup (branch/PR history). Rollback triggers — any of these invalidates the pilot state and invokes recovery: (a) a secret or live credential detected in Git → immediate revert of the offending commit plus credential rotation; (b) an unreviewed or unverified merge reached main → revert, re-review; (c) an Objective or its ADR contradicts an accepted ADR or the master plan → block the objective, amend or abandon; (d) the generated catalog drifts from the source front matter → regenerate and re-run gates before further merges.

  7. ADR lifecycle and merge gate. This ADR opens as proposed for independent review of the real PR diff. After an independent APPROVE verdict, the Lead authorizes a narrow in-PR transition to accepted: front matter status, the human Status line and the decisions index updated atomically, all DocOps gates re-run. Only after that transition (with a green branch check and a current approval) is the PR mergeable — and even then this build card does not merge; the merge is a separate operator-gated act. No P2 work starts until main contains the accepted ADR with consistent index/navigation.

  8. Qwen economics gate (routability, optional participant). Qwen local is additionally subject to an economics gate before routing any pilot work to it: a paired benchmark on the same three non-mutating fixtures recording wall_time_validated for the direct GPT/Lead run and for the Qwen + Lead audit/rework run. Qwen is routable only if ALL hold: 3/3 fixture ACs pass under Qwen; Qwen invokes zero cloud/GPT fallback calls; and the aggregate Qwen (including audit/rework) is ≤ 1.20× the direct baseline's validated wall time. Any failure ⇒ Qwen excluded — exclusion never blocks the role design.

  9. Status discipline. Even after accepted, the pilot still has to run: Harness V3.1 becomes the standing governance only if the operator confirms it after the pilot verdict (promotion matrix of OBJ-HARNESS-V31-001). Nothing in this document retires the existing lane model, and no V3.1 mechanism may be treated as accepted precedent for other work until then.

Rationale

  • A versioned WHAT/WHY/DONE gives the operator a reviewable contract BEFORE execution and an auditable record AFTER it; Kanban alone gives neither (cards are rewritten, completed runs are summarized).
  • Separating the definer from the executor and both from the judge is the cheapest available defense against self-confirmation bias in an agent-operated system.
  • Fail-closed semantics trade throughput for correctness: a stalled review is a visible blocker the operator can resolve, whereas a silently weakened gate is invisible until it fails in production.
  • The capability gate on local models encodes an honest limit: a model that cannot sustain the required reasoning depth must not be scheduled into a governance role just because it is available.

Consequences

  • Positive: objectives become reviewable, durable contracts; review independence is structural, not aspirational; secrets and live state stay out of Git by contract; degraded conditions surface as visible blockers instead of silent substitutions.
  • Negative: more ceremony per objective (draft, handoff, PR, review, verdict) — meaningful overhead for small tasks, so Objectives are reserved for multi-card, cross-component work; small work stays Kanban-only. Review availability can bottleneck delivery (fail-closed by design). A second source (Git contract) can drift from the live board if the Lead neglects the ledger cross-references — drift is mitigated by review, not by copying state into Git.
  • Neutral: the Architect role needs a profile (or operator mode) with deliberately no Git credentials; this is an operational setup detail owned by the Lead.

Alternatives considered

Alternative Why rejected
Objectives as Kanban cards only (no Git contract) Keeps WHAT/WHY/DONE in mutable operational state; no reviewed contract; no versioned audit trail.
Full independence: every card independently reviewed Prohibitive review cost for the pilot's size; Objectives batch the review at the contract and delivery boundaries instead.
goal_mode auto-completion as the acceptance signal Substitutes a heuristic judge for independent review; explicitly rejected (Decision 5).
A dedicated objectives database / RAG store Heavier than the pilot needs; Git + generated catalog already provide versioning and retrieval; revisit if objective count grows.
Wait for agent-services planes before governing Governance gaps identified in Phases 0–4 exist today; the pilot is deliberately lightweight so it runs on the current Kanban harness.

Migration / implementation notes

  • Phase P1 (this PR, unmerged): ADR-0008 (proposed), the governance architecture doc, the objectives section with the first active Objective (OBJ-HARNESS-V31-001) and both templates; nav and catalog regenerated; independent review of the real PR diff (max two rounds).
  • P1 closure: after independent APPROVE, the narrow in-PR proposed→accepted transition (Decision 8) with all gates re-run; the PR becomes mergeable but this card does not merge — the merge is the operator's separate act.
  • Phase P2 (pilot run): starts ONLY after main contains the accepted ADR with consistent index/navigation. The Lead executes OBJ-HARNESS-V31-001 end-to-end under the mechanism; deviations and evidence are recorded in the Execution Ledger (level 1), not here.
  • Phase P3 (verdict): operator confirmation after the pilot → V3.1 becomes standing governance (objective moved to completed/) or the pilot is closed with lessons recorded.
  • Rollback = Decision 7 triggers; the docs revert via normal Git revert of the objective's merge, and level-1 stores restore from backup.