Skip to content

OBJ-HARNESS-V31-001: Harness V3.1 pilot — versioned objective governance end-to-end

Objective ID: OBJ-HARNESS-V31-001 Project doc (PROJ-HARNESS-V31-001): the DocOps project pill for this objective is the front matter of this very document (id: PROJ-HARNESS-V31-001, objective_id: OBJ-HARNESS-V31-001) — see Project index for where project pills live. Status: Active (in execution) Drafted by: Architect (THINK role) — provenance: plan review R1 (REQUEST_CHANGES, plan replaced) and R2 (t_fa409c84, REQUEST_CHANGES; its three required corrections are incorporated in this delivery — no APPROVE is claimed) Owned by: wetopi-lead (OWN role)

Outcome

The V3.1 governance mechanism is proven end-to-end on this very objective: the WHAT/WHY/DONE you are reading is a versioned Git contract (this document, landed via reviewed PR), the execution is cardized on the Kanban board, the delivery is independently reviewed fail-closed, and the operator's verdict on ADR-0008 is recorded explicitly — including a possible REJECT. Success is NOT "V3.1 accepted"; success is "the mechanism ran honestly and the verdict is explicit".

Context

  • Phases 0–4 exposed the two structural risks this objective addresses (work definition trapped in mutable operational state; definer/executor self-confirmation). Full reasoning: ADR-0008 Context.
  • Requirements authority: the objective's scope decisions follow the plan review rounds (R1 verdict REQUEST_CHANGES, replaced plan; R2 verdict t_fa409c84: REQUEST_CHANGES, not APPROVE) plus the independent content review. This delivery incorporates the R2 required corrections — no docs/decisions/ validator exemption for the new ADR (canonical legacy-exempt set only), ADR-0008 must be accepted (not merely proposed) and merged before P2, and the Qwen economics gate uses a like-for-like direct GPT/Lead baseline — WITHOUT claiming an R2 APPROVE that never happened (stop condition below records the honest state).
  • The current harness (Hermes Kanban lanes) continues to operate normally; V3.1 runs as a pilot alongside it.

Decisions (bound for the executor)

  • D1 — Git Objective is the level-2 versioned contract; Kanban/Work Ledger stay level-1 operational state. Never copy live state into Git.
  • D2 — The Architect drafted WHAT/WHY/DONE and has no Git write; the documentation PR is a separate Lead/Docs handoff task.
  • D3 — No build/docs card applies or destroys infrastructure; apply stays in authorized ops cards with the human gate.
  • D4 — Review is conditional and fail-closed; goal_mode never substitutes for the JUDGE gate and stays DISABLED for real Objectives until the P2 smoke passes its full fail-closed contract (enablement gate in Gates; contract in the governance doc); Qwen local is capability-gated AND economics-gated (paired 3-fixture benchmark, ≤1.20× aggregate, zero cloud/fallback, 3/3 ACs) and may be excluded without weakening any other gate or blocking the role design.
  • D5 — ADR-0008 opens proposed; after independent PR APPROVE it receives a narrow in-PR proposed→accepted transition (front matter, human status, index — atomic, gates re-run). This card never merges; P2 cannot start until main contains the accepted ADR and consistent navigation. V3.1 is NOT standing governance until the pilot verdict.

Acceptance criteria (DONE)

  • AC1 — docs/decisions/ADR-0008-harness-v31-objective-governance.md exists as proposed with full DocOps front matter, deciding explicitly: THINK/OWN/DO/JUDGE separation; Architect no-Git-write; Lead acquisition/ledger; L1/L2 split; build-vs-apply separation; conditional fail-closed review (no goal_mode substitution); Qwen local capability + economics gates with possible exclusion; the ADR lifecycle/merge gate (proposed → in-PR accepted transition after independent APPROVE); backup/restore and rollback triggers; alternatives, consequences, honest limits.
  • AC2 — docs/agents/harness-v31-governance.md documents roles, the Architect capability boundary, degraded routing, gates and the fail-closed state machine.
  • AC3 — This objective document (OBJ-HARNESS-V31-001) is the first active objective, with the standard objective front matter plus objective_id: OBJ-HARNESS-V31-001.
  • AC4 — Both templates exist: REF-OBJECTIVE-SPEC-TEMPLATE (IDs, ownership, evidence requirements, fail-closed, no-secret policy, Git/Kanban/Ledger relationships) and PROC-EXECUTION-LEDGER-TEMPLATE (single Lead writer, status/next-action, card IDs, commit/PR links, evidence, reviews, blockers, backup/restore locator; no live-config or secret content).
  • AC5 — docs/objectives/index.md explains that Objectives are versioned contracts — not a second Kanban, not a ledger in Git.
  • AC6 — Decisions and Agents section indexes plus mkdocs.yml nav cover Objectives and ADR-0006/0007/0008 (the 0006/0007 nav gap is fixed without modifying ADR content).
  • AC7 — All DocOps gates pass on the branch: validator regenerates docs/generated/catalog.yaml; --check-only exits 0; scripts/regen-catalog.py is a no-op; mkdocs build --strict exits 0 with no new warnings vs the main baseline; diff matches the exact change allowlist.
  • AC8 — A PR to main carries exactly the allowlisted files, is verified remotely (gh api: URL, number, base, SHA, file list), stays UNMERGED, and the independent review verdict is recorded (max two rounds; then Lead/operator decide).

Verification contract (how DONE is proven)

Evidence Source of truth
PR exists, open, unmerged, base=main, exact file list gh api repos/wetopi-platform/docs/pulls output preserved in the run record
DocOps validator clean + catalog current validator exit 0 (--check-only), regen-catalog.py exit 0 (no-op), both outputs preserved
mkdocs strict clean, no new warnings mkdocs build --strict exit 0 on branch; INFO/warning lines diffed against the preserved main baseline log
No secrets / no live state in the diff manual inspection recorded in the delivery evidence; git diff --check clean
Independent review verdict JUDGE verdict comment/record on the delivery (APPROVE / REQUEST_CHANGES / REJECT)
Operator verdict on ADR-0008 explicit operator statement recorded on ADR-0008 status (in this PR or its successor)

Any missing evidence ⇒ the corresponding AC is NOT met (fail-closed).

Constraints

  • Exact change allowlist (no file outside it; need for more = stop and block the card, no scope expansion): the 12 files listed in the build card P1.
  • Git discipline: branch docs/obj-harness-v31-governance from origin/main; no push to main, no force push, no remote merge/rebase, no touching other repos; semantic commit.
  • DocOps Same Change rule; templates from ai-hub/skills/docops/templates/ conventions; material docs carry full front matter with valid IDs.
  • Spanish/English: content follows the repo's established language (the cards are Spanish-authored; curated docs are English, as existing ADRs).

Boundaries

  • Documentation + Git ONLY. No Hermes profile changes, no cron, no Qwen scheduling, no goal_mode configuration, no infrastructure, no apply/destroy, no other repos.
  • The Architect's draft and R2 review are input, not artifacts to copy verbatim; this document is the versioned contract distilled from them.

Stop conditions

  • Plan review R2 (t_fa409c84) returned REQUEST_CHANGES, not APPROVE. The original stop discipline stands: R2 approval was the intended start precondition and was NOT met. The objective is NOT auto-blocked by that history alone only because this delivery incorporates the three R2 required corrections (validation-exemption fix, accepted-ADR-before-P2 gate, like-for-like economics baseline), recorded in Context; starting execution without those corrections, or misrepresenting the R2 verdict as APPROVE, remains prohibited.
  • DocOps/MkDocs gate failure or a NEW warning vs baseline (stop; fix or block, never merge with new warnings).
  • Any required file outside the allowlist (stop, block, explain).
  • Credential/permission insufficient for repo push or PR creation.
  • Secret or live-state content detected in the diff (stop, remove, evaluate rollback trigger ADR-0008 D7a).
  • Contradiction with ADR-0003 or another accepted ADR (stop, block).
  • PR not remotely verifiable via gh api (stop, block).

Review boundaries

  • Reviewer: independent JUDGE (not the implementer; wetopi-approver or Lead-appointed substitute). Maximum TWO review rounds on the PR; if still unresolved, the Lead/operator decide (escalate or abandon).
  • The Architect may answer questions on intent but never approves its own draft's landing.
  • The operator is the final acceptance authority (ADR-0008 status).

Out of scope

  • Any V3.1 mechanism change to live Hermes profiles, cron or model routing (separate, post-acceptance work).
  • Migrating existing Kanban history into objectives.
  • Building agent-services planes, RAG or objective tooling beyond the Markdown+Git pilot.
  • Accepting ADR-0008 on the reviewers' or workers' own authority.

Promotion matrix

ADR gate (P1, merge): the ADR opens proposed; after an independent PR APPROVE, a narrow in-PR proposed→accepted transition (front matter, human status, decisions index — atomic, gates re-run) makes the PR mergeable. This card never merges; the merge is the operator's act. No P2 card is created/unblocked until main contains the accepted ADR with consistent index/navigation.

Qwen economics gate (routability): paired benchmark over the same three non-mutating fixtures recording wall_time_validated for the direct GPT/Lead run and the Qwen + Lead audit/rework run. Qwen local is routable ONLY if: 3/3 fixture ACs pass under Qwen; zero cloud/GPT fallback calls; aggregate Qwen time ≤ 1.20× the direct baseline. Any failure ⇒ Qwen excluded, without blocking the role design.

Pilot result mapping:

Pilot result ADR-0008 This objective Section move
Mechanism proven, verdict positive accepted (in-PR transition per P1 gate; operator merges) status: completed verdict recorded here active/ → completed/ (new PR, file unchanged otherwise)
Mechanism proven, verdict negative as decided by the operator (rejected possible; lessons kept) status: completed, rejection recorded active/ → completed/
Mechanism NOT proven (gates failed, stop conditions hit) stays proposed (or rejected if operator so decides) stays active/blocked with evidence until operator resolution none until resolution
Abandoned by rollback trigger per trigger outcome status: deprecated with reason as decided by the operator