Skip to content

Objective specification template

Use this template for every Objective. An Objective is a versioned contract in Git (level 2): it fixes WHAT, WHY and DONE before execution and is the review basis after it. Copy the section skeleton below; keep every section — write "none" rather than deleting one.

Front matter (mandatory)

---
id: PROJ-<DOMAIN>-<NNN>           # DocOps validator ID_RE (ARCH|ADR|SVC|RUN|PROC|PROJ|REF|SEC):
                                  # PROJ is the catalog pill; stable, never reused
title: <one line>
type: project
status: active                    # active | completed | deprecated
owner: <owning role: wetopi-lead>
summary: >
  <one line, retrieval-friendly>
objective_id: OBJ-<DOMAIN>-<NNN>  # additional contract field: the objective's
                                  # own stable identifier, echoed in the body
scope: [<areas>]
tags: [<tags>]
related: [<IDs>]
authoritative_sources:            # where the implementation/authority lives
  - repo: <repo>
    path: <path>
last_verified: <date>
---

IDs follow the DocOps convention. The objective lives in docs/objectives/active/OBJ-<DOMAIN>-<NNN>.md and moves to completed/ (unchanged) when DONE.

Body skeleton

# OBJ-<DOMAIN>-<NNN>: <title>

**Objective ID:** OBJ-<DOMAIN>-<NNN>
**Status:** active | completed | deprecated
**Drafted by:** <Architect/THINK actor>  — **Owned by:** wetopi-lead (OWN)

## Outcome            <- WHAT success looks like, one paragraph, testable
## Context            <- WHY: forces, prior decisions, requirements authority
## Decisions          <- bound-for-executor decisions, each numbered (D1, D2…)
## Acceptance criteria (DONE)   <- numbered ACs, each independently checkable
## Verification contract       <- per-AC evidence + source of truth table;
                                  missing evidence => AC not met (fail-closed)
## Constraints        <- hard limits: allowlists, git discipline, gates
## Boundaries         <- what this objective does not touch
## Stop conditions    <- when to halt and block instead of proceeding
## Review boundaries  <- who reviews, rounds limit, who never approves own work
## Out of scope       <- explicit non-goals
## Promotion matrix   <- result -> ADR/status/section-move mapping

Rules (from the governance model — ADR-0008, proposed)

  • Ownership: the Architect (THINK) drafts; the Lead (OWN) lands it via reviewed PR, executes and maintains the ledger; workers (DO) implement inside boundaries; an independent reviewer (JUDGE) verifies. The Architect has NO Git write.
  • Evidence requirements: every AC names its evidence and its source of truth in the verification contract. Verifiable evidence only — command outputs, PR state, validator results — never "it should work".
  • Fail-closed: missing reviewer, missing verdict, incomplete evidence, gate failure, or an unexpected file ⇒ the objective is blocked, never silently accepted. goal_mode never substitutes for review.
  • No-secret policy / no live state: the objective document and the whole objectives section NEVER contain live snapshots, .env, auth.json, tokens, connection URLs, credential hashes, pool output or any secret. Reference the credential path/identity instead (Infisical path, profile name) — never the value.
  • Git/Kanban/Ledger relationships (L2 vs L1): Git is the level-2 versioned contract — this document plus evidence references only. Kanban and the Work Ledger are the level-1 live operational state and stay OUTSIDE Git. The Execution Ledger is written ONLY by the Lead (single writer, level 1) and cross-references the objective's commit/PR SHAs and card IDs. State authority flows board → ledger → Git references (live state recorded in the ledger; Git receives only contracts and evidence references, never live state): live board and ledger state is NEVER copied into Git — no snapshots, no status mirrors, no regenerated live-state files. See ADR-0008 (Decisions 3) and the architecture doc (level-1 / level-2 relationship).