Governance Runbook (gzkit)¶

Purpose: Operator procedures for executing GovZero workflows in gzkit: ADR/OBPI lifecycle work, reconciliation, closeout, audit, and parity maintenance.

Version: GovZero v6 extraction surface Scope: Governance operations in this repository Companion: Operator Runbook (daily execution loop)

This document is procedural ("how to"), not policy ("what the rules are"). Canonical policy remains in docs/governance/GovZero/**.

Governance Quick Reference¶

Status and health¶

Bash

uv run gz status --table
uv run gz adr status ADR-<X.Y.Z> --json
uv run gz adr report
uv run gz state --json
uv run gz adr audit-check ADR-<X.Y.Z>
uv run gz adr covers-check ADR-<X.Y.Z>
uv run gz gates --adr ADR-<X.Y.Z>
uv run gz obpi status OBPI-<X.Y.Z-NN>
uv run gz roles
uv run gz personas list               # List agent personas
uv run gz personas list --json         # List personas as JSON

Lifecycle execution¶

Bash

uv run gz init                        # Initialize governance scaffolding
uv run gz prd                         # Create Product Requirements Document
uv run gz constitute                  # Create constitution artifact
uv run gz plan create <name> --semver X.Y.Z  # Create an ADR
uv run gz plan audit OBPI-<X.Y.Z-NN> # Structural prereq check for plan alignment
uv run gz specify                     # Create implementation brief (OBPI)
uv run gz obpi pipeline OBPI-<X.Y.Z-NN>  # Execute OBPI pipeline
uv run gz obpi audit OBPI-<X.Y.Z-NN> # Gather evidence and record in audit ledger
uv run gz obpi reconcile OBPI-<X.Y.Z-NN> # Fail-closed reconciliation
uv run gz obpi withdraw OBPI-<X.Y.Z-NN> --reason "..." # Withdraw OBPI from counts
uv run gz obpi lock claim OBPI-<X.Y.Z-NN>  # Claim OBPI work lock
uv run gz obpi lock release OBPI-<X.Y.Z-NN> # Release OBPI work lock
uv run gz obpi lock check OBPI-<X.Y.Z-NN>  # Check if OBPI is locked
uv run gz obpi lock list               # List active OBPI work locks
uv run gz obpi complete OBPI-<X.Y.Z-NN> --attestation-text "<verbatim user words — session evidence>"
uv run gz obpi emit-receipt OBPI-<X.Y.Z-NN> --event completed --attestor "<name>" --evidence-json '{...}'
uv run gz flags                       # Display feature flags
uv run gz flag explain <flag>         # Inspect one flag
uv run gz migrate-semver              # Record SemVer rename events
uv run gz register-adrs               # Register existing ADR packages

Skill-based entry points:

Text Only

/gz-adr-create
/gz-adr-manager   # compatibility alias for /gz-adr-create
/gz-obpi-brief
/gz-obpi-pipeline OBPI-<X.Y.Z-NN>
/gz-obpi-reconcile ADR-<X.Y.Z>
/gz-adr-recon ADR-<X.Y.Z>
/gz-adr-sync

Validation and proof surfaces¶

Bash

uv run gz cli audit
uv run gz check-config-paths
uv run gz validate --documents --surfaces
uv run gz preflight                           # Detect stale artifacts
uv run gz obpi validate --adr ADR-<X.Y.Z> --authored
uv run gz adr evaluate ADR-<X.Y.Z>
uv run gz readiness evaluate
uv run gz parity check
uv run mkdocs build --strict

Cross-repo defect routing¶

When a defect or enhancement against a gzkit-owned surface (the gz CLI, schemas under src/gzkit/schemas/, validator scopes, ledger event semantics, files under .gzkit/** or src/gzkit/**, rules under .gzkit/rules/**) is surfaced from inside a consuming repository, the canonical wrapper is:

Bash

uv run gz issue file --title T --body "<gzkit-surface description>" --defect [--dry-run]
uv run gz issue file --title T --body "<gzkit-surface description>" --enhancement [--dry-run]

The wrapper auto-stamps a provenance trailer and routes against tvproductions/gzkit regardless of the consuming repo's git remote. Bodies without a gzkit-surface marker (gz <verb>, .gzkit/, src/gzkit/, gzkit.<module>) are hard-rejected with exit 1. Doctrine: .gzkit/rules/gh-cli.md § Cross-repo filing. Operator runbook entry: docs/user/runbook.md § Cross-Repo Defect Filing.

Concepts¶

Gate system¶

Gate	Name	Verification
1	ADR recorded	`uv run gz validate --documents`
2	TDD	`uv run gz test`
3	Docs	`uv run gz lint` + `uv run mkdocs build --strict`
4	BDD	`features/` scenarios if present
5	Human attestation	`uv run gz attest ADR-<X.Y.Z> --status completed`

Lane rule: lite requires Gates 1-2; heavy requires Gates 1-5.

Layered trust¶

See State Doctrine for the full three-layer model, five authority rules, and conflict decision table.

Layer	Trust source	Typical tooling
1	Runtime evidence generation	`gz implement`, `gz gates`, `gz adr audit-check`
2	Ledger-driven reconciliation	`/gz-obpi-reconcile`, `/gz-adr-recon`, `gz audit`
3	File sync and indexing	`/gz-obpi-sync`, `/gz-adr-sync`, `gz agent sync control-surfaces`

Persona framing¶

Every agent context frame includes a mandatory ## Persona section (ADR-0.0.11). Persona files live in .gzkit/personas/ as structured markdown with YAML frontmatter defining composable traits, anti-traits, and a behavioral grounding statement.

Key constraints:

Persona frames describe behavioral identity — values, craftsmanship standards, and relationship to the work
Never use generic expertise claims ("You are an expert X developer") — the PRISM study shows these degrade accuracy while adding no knowledge
Traits compose orthogonally per the PERSONA/ICLR 2026 framework

Commands:

Bash

uv run gz personas list               # Enumerate defined personas
uv run gz personas list --json         # Machine-readable output

Where persona appears:

Surface	Location
Agent contract	`AGENTS.md` § Persona
ADR context frames	`## Persona` section in each ADR
Persona files	`.gzkit/personas/*.md`

Storage tier escalation¶

Moving data from Tier A/B to Tier C is a tier escalation — a Heavy-lane decision requiring its own ADR. See Storage Tiers Reference for full definitions and the exhaustive storage catalog.

Rule: No Tier C storage dependency (database, external server, protocol) may be introduced without an explicit Heavy-lane ADR authorizing the escalation.

Anti-pattern to watch for: A Tier B cache (derived/rebuildable) that gradually accumulates state not derivable from Tier A sources — silently becoming Tier C without governance authorization. Periodic rebuild tests (delete Tier B, rebuild, verify no data loss) guard against this drift.

Feature flag system¶

Feature flags are transition controls — mechanisms for routing between old and new behavior during migration, with the explicit expectation that the old path and the toggle will be removed. They are not A/B experiments or analytics features. See Feature Flags Reference for the full specification.

Categories:

Category	Purpose	Deadline type
`release`	Transient feature gates	`remove_by`
`ops`	Operational kill switches	`review_by`
`migration`	Internal representation transitions	`remove_by`
`development`	Incomplete work gating (default `false`)	`remove_by`

Lifecycle: Every flag has a deadline. A CI time-bomb test fails if any flag is past its deadline, enforcing cleanup discipline.

Commands:

Bash

uv run gz flags                       # List all flags with resolved values and sources
uv run gz flags --stale               # Show only overdue flags (past review/remove dates)
uv run gz flag explain <key>          # Full metadata for one flag (category, owner, deadlines)

Persona control surface¶

Personas define behavioral identity for pipeline agents. Files live in .gzkit/personas/ as markdown with YAML frontmatter.

Schema: name, traits (list), anti-traits (list), grounding (text).

Read-only contract: gz personas list enumerates personas without mutation. No commands exist to create, edit, or switch personas at runtime.

Pipeline integration: The pipeline dispatch layer reads .gzkit/personas/{role}.md at dispatch boundaries and passes the persona body as extra_context to the subagent prompt.

Exemplar: .gzkit/personas/implementer.md ships with the repository.

Cross-project persona workflow¶

Validating persona portability in an external GovZero-governed repository (ADR-0.0.13 item 6):

Initialize the target project (creates .gzkit/personas/ with defaults):
Bash
```
cd ../airlineops
uv run gz init
```

Verify persona files were scaffolded:

Bash

ls .gzkit/personas/
# Expected: default-agent.md  default-reviewer.md

Validate personas against the portable schema:
Bash
```
uv run gz validate --surfaces
```

Sync personas to vendor mirrors:

Bash

uv run gz agent sync control-surfaces
ls .claude/personas/

Confirm no gzkit-specific content leaked:

Bash

grep -ri "gzkit\|obpi\|pipeline" .gzkit/personas/
# Expected: no output (exit 1)

Key constraint: The target project's persona content must be project-specific. Default personas are starters that projects customize to reflect their workflow. If the portable surface requires gzkit source modifications to work in an external project, the surface is broken (REQ-0.0.13-06-07).

OBPI discipline¶

OBPI is the atomic implementation unit.
ADR status is a roll-up of OBPI completion plus attestation.
Lane inheritance: kind and lane are orthogonal axes (ADR-0.0.17 § Decision #2). Attestation rigor keys on lane: if the parent ADR is heavy-lane (any kind), human attestation is required for all OBPIs regardless of their individual lane designation. Foundation-kind ADRs additionally follow the attestation walkthrough doctrine in ADR-0.0.18 regardless of lane.

ADR series selection¶

When creating or promoting an ADR, pick the next available version in the correct series:

0.0.x (Foundation): Infrastructure, governance framework, developer tooling. No GitHub releases.
0.x.0+ (Feature): User-facing capability, external contracts, observable behavior changes. Release tags created on validation.

Workflow: Create or Promote ADR¶

When: New governance work must be planned.

Skill shortcuts for ADR creation and planning:

/gz-design — collaborative design dialogue that produces ADR artifacts (use before formal creation)
/gz-adr-create — create and book a GovZero ADR with OBPI briefs
/gz-adr-promote — promote a pool ADR into canonical package structure
/gz-adr-evaluate — score ADR quality and run red-team challenges before proceeding
Inspect active and pending ADR state.

Bash

uv run gz status --table

If promoting from pool, use deterministic promotion.

Bash

uv run gz adr promote ADR-pool.<slug> --semver X.Y.Z --status proposed

Create or update OBPI briefs for checklist items.

Text Only

/gz-obpi-brief

Validate briefs are authored (not template stubs).

Bash

uv run gz obpi validate --adr ADR-<X.Y.Z> --authored

Evaluate ADR and OBPI quality before proceeding.

Bash

uv run gz adr evaluate ADR-<X.Y.Z>

A NO GO verdict blocks pipeline execution. Address action items and re-evaluate.

5b. Pre-execution reasoning when quality signals are weak.

When /gz-adr-evaluate returns a low score, or when an OBPI's implementation pass has ambiguous scope, scaffold an 8-section reasoning walkthrough before continuing into Step 6. The CLI is deterministic — every byte of the scaffold is rendered, never generated by an LLM.

Two upstream skills route operators here:

gz-adr-evaluate flags low-score dimensions (Problem Clarity, Decision Justification, Architectural Alignment, etc.) in its output and recommends gz justify so the missing reasoning is authored before the ADR is taken to defense.
gz-obpi-pipeline at the Stage 1→2 Confidence Gate routes the agent to gz justify when self-reported confidence in the planned implementation is below 90%. This gate mechanizes Prime Directive invariant 11 (AGENTS.md § Behavior Rules — Always, item 7): "If you are less than 90% sure of the direction, ask the human before proceeding." The walkthrough is the structured form of that ask.

Bash

# Anchor on a GHI, an OBPI, or a free-text draft
uv run gz justify <anchor> --save

# Validate the filled walkthrough before citing in attestation
uv run gz justify validate artifacts/justify/<saved-file>.md

The validate subverb exits 0 only when every _[To be filled]_ block is closed; exit 1 lists which sections remain unfilled. Citing a validated walkthrough in OBPI Key Proof or ADR Evidence preserves the operator's pre-implementation reasoning rather than post-hoc reconstruction (per .claude/rules/attestation-enrichment.md).

See /gz-justify and commands/justify.md for the full walkthrough protocol.

Validate artifact and document integrity.

Bash

uv run gz validate --documents
uv run gz check-config-paths

Workflow: OBPI Increment¶

When: Implementing one checklist item.

Skill shortcuts for OBPI execution:

/gz-obpi-pipeline — post-plan execution pipeline (implement, verify, present, sync)
/gz-obpi-brief — generate a new OBPI brief with correct headers and evidence stubs
/gz-obpi-lock — claim or release OBPI work locks for multi-agent coordination
/gz-plan-audit — pre-flight audit to verify plan aligns with OBPI brief scope
/gz-specify — create OBPI briefs linked to parent ADR items
Orient on current state and the parent ADR.

Bash

uv run gz adr status ADR-<X.Y.Z> --json
uv run gz status --table

Validate the target brief is authored (not a template stub).

Bash

uv run gz obpi validate <path-to-brief> --authored

Plan the OBPI and exit plan mode with an approved plan.
Invoke the OBPI execution pipeline.

Text Only

/gz-obpi-pipeline OBPI-<X.Y.Z-NN>

Use compatibility entry points when implementation or verification already exists:

Text Only

/gz-obpi-pipeline OBPI-<X.Y.Z-NN> --from=verify
/gz-obpi-pipeline OBPI-<X.Y.Z-NN> --from=ceremony

Inside the pipeline, implement + verify Gate 2 (+ Gate 3 when docs change).

Bash

uv run gz implement --adr ADR-<X.Y.Z>
uv run gz gates --adr ADR-<X.Y.Z>
uv run gz lint

Present the OBPI acceptance ceremony before marking the brief Completed.
Sync audit and ADR table state after the ceremony.

Pipeline rules:

verify -> reviewer dispatch -> ceremony -> sync is mandatory
Heavy-lane work (any kind) stays fail-closed on human attestation; foundation-kind work (any lane) additionally follows ADR-0.0.18 walkthrough discipline
if concurrent execution is needed before lock parity exists, stop with BLOCKERS

Reviewer agent protocol (ADR-0.23.0)¶

After verification passes and before the ceremony, the pipeline dispatches an independent reviewer agent with fresh context to verify the OBPI delivery:

The reviewer receives: OBPI brief, closing argument, changed files, doc files
The reviewer produces a structured assessment:
promises-met — yes/no per requirement, with evidence
docs-quality — substantive / boilerplate / missing
closing-argument-quality — earned / echoed / missing
verdict — PASS / CONCERNS / FAIL
The assessment is stored as REVIEW-OBPI-X.Y.Z-NN.md in the ADR's briefs/ directory
The Stage 4 ceremony presents the assessment to the human attestor

The reviewer is read-only and does not fix problems — it identifies them. A FAIL verdict does not block the pipeline; the human attestor decides.

Bash

# Verify reviewer assessment artifact exists after pipeline
ls docs/design/adr/**/briefs/REVIEW-OBPI-*.md

Workflow: Reconciliation and Drift Detection¶

When: Before closeout, after multi-session work, or when status drift is suspected.

Skill shortcuts for reconciliation (run in trust order — Layer 2 before Layer 3):

/gz-obpi-reconcile — audit briefs against evidence, fix stale metadata, write ledger proof (Layer 2)
/gz-adr-recon — reconcile ADR/OBPI evidence state from ledger outputs (Layer 2)
/gz-adr-sync — reconcile ADR files with ledger registration and status views (Layer 3)
/gz-obpi-sync — sync OBPI status in ADR table from brief source files (Layer 3)

Run in trust order:

Text Only

/gz-obpi-reconcile ADR-<X.Y.Z>   # Layer 2
/gz-adr-recon ADR-<X.Y.Z>        # Layer 2
/gz-adr-sync                     # Layer 3

Then verify no unresolved evidence gaps:

Bash

uv run gz adr audit-check ADR-<X.Y.Z>
uv run gz adr status ADR-<X.Y.Z> --json

If audit-check fails, fix the referenced OBPI brief evidence and rerun until PASS.

Workflow: ADR Closeout and Audit¶

When: All linked OBPIs are completed and evidenced.

Skill shortcuts for the closeout and audit ceremony:

/gz-adr-closeout-ceremony — execute the full closeout ceremony protocol for human attestation
/gz-closeout — initiate ADR closeout with evidence context
/gz-attest — record human attestation with prerequisite enforcement
/gz-audit — run strict post-attestation reconciliation audits (only after attestation)
/gz-adr-audit — Gate-5 audit templates and procedure for ADR verification
Pre-closeout blocking check.

Bash

uv run gz adr audit-check ADR-<X.Y.Z>

Closeout ceremony initiation (dry-run first, then live).

Bash

uv run gz closeout ADR-<X.Y.Z> --dry-run
uv run gz closeout ADR-<X.Y.Z>

Human attestation.

Bash

uv run gz attest ADR-<X.Y.Z> --status completed

Post-attestation audit and accounting.

Bash

uv run gz audit ADR-<X.Y.Z>
uv run gz adr emit-receipt ADR-<X.Y.Z> --event validated --attestor "<Human Name>" --evidence-json '{"scope":"ADR-<X.Y.Z>","date":"YYYY-MM-DD"}'

Rules:

Do not run gz audit before attestation.
Do not treat passing checks as implied attestation.
Record attestation terms explicitly (Completed, Completed — Partial: <reason>, Dropped — <reason>).
REQ-coverage gate (ADR-0.0.25): gz obpi complete exits 3 when any REQ in the closing brief's ## Acceptance Criteria lacks a passing @covers-decorated test. Use uv run gz covers OBPI-<X.Y.Z-NN> to check coverage before invoking completion. The same gate mirrors to gz adr emit-receipt --event closed: an ADR cannot close while any OBPI has an unwaived REQ gap. Override: --accept-uncovered REQ-ID --accept-uncovered-reason REASON (requires --attestor-present; records obpi_completion_uncovered_accept ledger event).

Workflow: Task-Level Governance¶

When: Managing TASK entities (fourth tier: ADR > OBPI > REQ > TASK).

Bash

uv run gz task list OBPI-<X.Y.Z-NN>              # List tasks for an OBPI
uv run gz task start TASK-<id>                    # Start a pending task
uv run gz task complete TASK-<id>                 # Complete an in-progress task
uv run gz task block TASK-<id> --reason "..."     # Block with reason
uv run gz task escalate TASK-<id> --reason "..."  # Escalate with reason

Workflow: Chores and Maintenance¶

When: Running scheduled maintenance, code quality checks, or repository hygiene.

Skill shortcuts for maintenance workflows:

/gz-chore-runner — run a chore end-to-end (show, plan, advise, execute, validate)
/gz-check — run full quality checks in one pass (lint, typecheck, test, docs)
/gz-arb — quality evidence workflow with structured JSON receipts
/gz-tidy — run maintenance checks and cleanup routines

Bash

uv run gz chores list                      # List declared chores
uv run gz chores show <slug>               # Display CHORE.md for one chore
uv run gz chores advise <slug>             # Dry-run criteria and report status
uv run gz chores plan <slug>               # Show plan details for one chore
uv run gz chores run <slug>                # Execute and log one chore
uv run gz chores audit --all               # Audit log presence for all chores
uv run gz chores propose-ghi <slug>        # File GHIs for unfiled cluster proposals in proofs/

Frontmatter-ledger reconciliation (ADR-0.0.16 OBPI-03):

Bash

uv run gz frontmatter reconcile --dry-run  # Preview ledger-wins rewrites
uv run gz frontmatter reconcile            # Apply rewrites; emit receipt under artifacts/receipts/frontmatter-coherence/
uv run gz frontmatter reconcile --json     # Receipt JSON to stdout

Maintenance gate commands:

Bash

uv run gz tidy                             # Run maintenance checks
uv run gz format                           # Auto-format code
uv run gz typecheck                        # Static type checks
uv run gz drift                            # Detect spec-test-code drift
uv run gz covers ADR-<X.Y.Z>              # Trace test-to-requirement coverage
uv run gz skill new <name>                 # Create a new skill scaffold
uv run gz skill list                       # List all discovered skills
uv run gz interview                        # Run interactive governance interviews

Workflow: Session Handoffs¶

When (MUST):

Session ending with incomplete OBPI work
Scope switch between ADRs
Explicit human request

See /gz-session-handoff for full details on creating and resuming session handoffs with staleness classification.

Procedure:

Text Only

/gz-session-handoff CREATE
/gz-session-handoff RESUME

Staleness handling:

Fresh (<24h) resume directly.
Slightly stale (24-72h) resume with explicit verification.
Stale (>72h) or Very stale (>7d) require human re-validation before proceeding.

Workflow: Parity Maintenance Against AirlineOps¶

When: Weekly cadence, before pool ADR promotion, or after canonical governance changes in AirlineOps.

Filter rule:

Apply the Parity Intake Rubric to each candidate import before implementation.
Resolve canonical root deterministically and fail closed.

Bash

test -d ../airlineops && test -d .

Run parity-scan ritual checks.

Bash

uv run gz cli audit
uv run gz check-config-paths
uv run gz adr audit-check ADR-<target>
uv run mkdocs build --strict

Write dated reports.
docs/proposals/REPORT-airlineops-parity-YYYY-MM-DD.md
docs/proposals/REPORT-airlineops-govzero-mining-YYYY-MM-DD.md
Convert each Missing, Divergent, or high-impact Partial item into tracked ADR/OBPI follow-up.

Compatibility note:

gz-adr-create is canonical in gzkit.
gz-adr-manager is retained as a legacy alias for cross-repository parity.

Workflow: Skill Maintenance and Deprecation Operations¶

When: Weekly hygiene cadence, before ADR closeout touching skills, or when deprecating/retiring any skill.

Skill shortcuts for agent and skill infrastructure:

/gz-agent-sync — synchronize generated control surfaces and skill mirrors after updates
/gz-cli-audit — audit CLI documentation coverage and headings
Run lifecycle audit with explicit cadence threshold.

Bash

uv run gz skill audit --json --max-review-age-days 90

If stale review findings exist, update canonical .gzkit/skills/*/SKILL.md:
set last_reviewed to current review date,
confirm owner remains accurate,
re-run audit until stale findings are zero.
If a skill is deprecated or retired, ensure metadata evidence is present:
deprecation_replaced_by
deprecation_migration
deprecation_communication
deprecation_announced_on
retired_on (retired only)
Sync mirrors from canonical source of truth.

Bash

uv run gz agent sync control-surfaces
uv run gz skill audit

Rules:

Canonical .gzkit/skills is authoritative; mirrors are derived artifacts.
Do not deprecate/retire without communication and migration evidence.
Do not bypass stale review failures; they are blocking policy failures.

Workflow: Git Sync Ritual¶

Use /git-sync for the guarded repository sync ritual with lint/test gates.

Bash

uv run gz git-sync
uv run gz git-sync --apply --lint --test

Rules:

No --no-verify.
No force push.
Keep governance docs, runbook, and command references synchronized in the same change set.

Workflow: Readiness-Driven Design¶

Use /gz-state to query artifact relationships and readiness state, or /gz-validate to validate governance artifacts against schema rules.

Bash

uv run gz readiness audit
uv run gz readiness audit --json > docs/proposals/AUDIT-agent-readiness-gzkit-YYYY-MM-DD.json

Use readiness as a design input, not a one-time score:

Run gz readiness audit before parity extraction or major governance edits.
Cross-check findings against docs/user/reference/agent-input-disciplines.md and record which discipline/primitive each gap maps to.
Capture a dated audit artifact in docs/proposals/.
Convert the top three gaps into tracked ADR/OBPI follow-up work.
Use Gate 2 (TDD) and Gate 4 (BDD) evidence as primary inputs for acceptance/evaluation improvements.
Re-run readiness after implementation and record score delta in the same proposal.
Only claim maturity improvements when quality gates (gz check) also pass.

Quick Governance Checklist¶

Before starting OBPI work¶

[ ] uv run gz status --table
[ ] uv run gz adr status ADR-<X.Y.Z> --json
[ ] Brief scope and acceptance criteria reviewed
[ ] Existing handoff reviewed if present
[ ] No Tier C dependency introduced without ADR authorization (Storage Tiers)

Before requesting ADR closeout¶

[ ] /gz-obpi-reconcile ADR-<X.Y.Z> complete
[ ] /gz-adr-recon ADR-<X.Y.Z> complete
[ ] uv run gz adr audit-check ADR-<X.Y.Z> passes
[ ] uv run gz closeout ADR-<X.Y.Z> --dry-run reviewed
[ ] No unaudited tier escalation (Tier A/B to C requires Heavy-lane ADR)

After closeout¶

[ ] uv run gz attest ADR-<X.Y.Z> --status completed
[ ] uv run gz audit ADR-<X.Y.Z>
[ ] ADR-level receipt emitted
[ ] /gz-adr-sync run

Persona Design Principles¶

Persona is a governed control surface stored in .gzkit/personas/ (ADR-0.0.11). Agent identity framing mechanistically affects which behavioral clusters activate during inference — it is engineering, not decoration.

Three operator-relevant principles:

Don't claim expertise — frame behavioral identity. Generic expert personas ("You are an expert X developer") decrease accuracy by 3.6pp (PRISM study). Instead, describe values, craftsmanship standards, and relationship to the work.
Traits compose orthogonally. Multiple behavioral traits combine without interference (PERSONA/ICLR 2026). Design persona frames as composable trait specifications with structured YAML frontmatter, not monolithic character descriptions.
Virtue-ethics framing over prohibition lists. Frame positive behavioral identity (curiosity, thoroughness, craftsmanship) rather than listing what NOT to do. The model infers a complete persona from the identity frame — prohibitions imply inclination.

Trait Composition Rules¶

Traits compose by orthogonal concatenation — each trait activates an independent behavioral dimension without interfering with existing traits. The canonical composition operation is implemented in src/gzkit/personas.py and follows this deterministic template:

Text Only

[grounding text verbatim]

You are {trait-1}: {description from Behavioral Anchors}

You are {trait-2}: {description from Behavioral Anchors}

What this persona does NOT do:
- {anti-trait-1}: {description from Anti-patterns}

Composition rules:

Grounding first. The grounding field is emitted verbatim as the opening behavioral anchor — it sets the persona's relationship to the work.
Traits in declaration order. Each trait from the traits list is emitted as You are {name}: {description} when a ## Behavioral Anchors section provides a description, or You are {name}. otherwise.
Anti-trait suppression. Anti-traits are collected under What this persona does NOT do: with descriptions from the ## Anti-patterns section when available. Anti-traits define behavior that is actively suppressed — not merely absent.
Conflict rejection. If two traits conflict (e.g., "move-fast" vs "meticulous"), the anti-trait mechanism rejects the conflicting trait at validation time rather than attempting runtime resolution.
Determinism. Two implementers given the same persona file MUST derive the same resulting persona frame. No randomness, no ordering heuristics.

Exemplar: .gzkit/personas/implementer.md exercises all composition rules with four traits and three anti-traits.

Full research synthesis: docs/design/research-persona-selection-agent-identity.md Governing ADR: ADR-0.0.11 — Persona-Driven Agent Identity Frames

Governance Runbook (gzkit)¶

Governance Quick Reference¶

Status and health¶

Lifecycle execution¶

Validation and proof surfaces¶

Cross-repo defect routing¶

Concepts¶

Gate system¶

Layered trust¶

Persona framing¶

Storage tier escalation¶

Feature flag system¶

Persona control surface¶

Cross-project persona workflow¶

OBPI discipline¶

ADR series selection¶

Workflow: Create or Promote ADR¶

Workflow: OBPI Increment¶

Reviewer agent protocol (ADR-0.23.0)¶

Workflow: Reconciliation and Drift Detection¶

Workflow: ADR Closeout and Audit¶

Workflow: Task-Level Governance¶

Workflow: Chores and Maintenance¶

Workflow: Session Handoffs¶

Workflow: Parity Maintenance Against AirlineOps¶

Workflow: Skill Maintenance and Deprecation Operations¶

Workflow: Git Sync Ritual¶

Workflow: Readiness-Driven Design¶

Quick Governance Checklist¶

Before starting OBPI work¶

Before requesting ADR closeout¶

After closeout¶

Persona Design Principles¶

Trait Composition Rules¶

Reference Links¶