---
id: PRD-GZKIT-1.0.0
status: Draft
semver: 1.0.0
date: 2026-01-22
---

# Product Requirements Document: gzkit 1.0.0

## Problem Statement

AI-assisted development creates a drift problem: humans approve work they didn't verify, attest to artifacts they didn't read, and gradually become rubber stamps for agent-generated output. Existing tools either ignore governance entirely or bury it in ceremony that agents route around.

gzkit exists to keep the human at index zero—first in priority, final in authority.

## North Star

A governance-aware CLI that makes human oversight the path of least resistance—where attestation is meaningful, traceability is automatic, and agents operate within explicit architectural constraints.

## Invariants

See [Section 15: Invariants](#15-invariants) for the complete list of non-negotiable constraints.

## Gate Mapping

See [Section 16: Gate Mapping](#16-gate-mapping) for verification requirements.

## Attestation Block

See [Section 18: Attestation Block](#18-attestation-block) for attestation status.

---

## 1. Document Information

- Product/Feature Name: gzkit (GovZero Kit) 1.0.0
- Author(s): JB
- Date Created: 2026-01-13
- Last Updated: 2026-01-22
- Version: 0.3 (Draft - GovZero Depth Expansion)
- Constitution: [gzkit Charter](../../user/charter.md)
- Lane: Heavy (external CLI contract)

---

## 2. Overview

### Summary

gzkit is a Python CLI that implements the GovZero development covenant methodology. It provides spec-kit-inspired phase commands (constitute, specify, plan, implement, analyze) with Five Gates enforcement, enabling humans to maintain architectural authority over AI-assisted development.

### Goals & Objectives

- Provide a daily-driver CLI for managing development covenants
- Implement spec-kit phase model with GovZero Five Gates
- Support Lite (Gates 1-2) and Heavy (Gates 1-5) lanes
- Scaffold and validate governance artifacts (constitutions, briefs, ADRs, audits)
- Enforce human attestation as non-bypassable closeout
- Enable effective project/product design, execution, and ongoing governance

### Non-Goals

- AI/ML framework or model integration
- Automated attestation or approval
- Replacement for human judgment
- Multi-agent orchestration
- Full spec-kit feature parity (gzkit is GovZero-native, not a spec-kit clone)

---

## 2.1 Ubiquitous Language

<!-- gzkit-namespace glossary entries. Each entry conforms to UbiquitousLanguageTerm schema (ADR-0.0.43):
     term, scope (cross-cutting | <bc-slug>), definition (≥10 chars), provenance (list of ADR IDs).
     Backticked `gz-glossary-<term>` markers in prose resolve here. -->

### Cross-cutting

- **term:** `rubric-dimension` · **scope:** cross-cutting · **provenance:** ADR-0.51.0-skill-tuning-feedback-loop, ADR-0.0.57-foundation-adr-nominal-id-triage
  **definition:** A named axis along which a rubric scores an artifact, with associated weight and pass-threshold; the basis for the structured-dimension scoring pattern shared across `gz adr evaluate`, Optimize, and Triage skills.
- **term:** `rubric-finding` · **scope:** cross-cutting · **provenance:** ADR-0.51.0-skill-tuning-feedback-loop, ADR-0.0.57-foundation-adr-nominal-id-triage
  **definition:** A specific actionable observation produced when a rubric dimension scores below a calibrated threshold; cites the prose or behavior fragment that caused the deduction.
- **term:** `evidence-citation` · **scope:** cross-cutting · **provenance:** ADR-0.51.0-skill-tuning-feedback-loop, ADR-0.0.57-foundation-adr-nominal-id-triage
  **definition:** A pointer from a rubric finding or triage ranking to its source artifact (GHI ID, insight record, file:line, ADR ID); enables auditability and prevents narrative-only justification.

### Skill Evaluation

- **term:** `evaluation-episode` · **scope:** skill-evaluation · **provenance:** ADR-0.51.0-skill-tuning-feedback-loop
  **definition:** A single run of the Optimize chore evaluating a baseline-vs-candidate skill version against a hard goal basket and producing rubric scores and findings.
- **term:** `hard-basket` · **scope:** skill-evaluation · **provenance:** ADR-0.51.0-skill-tuning-feedback-loop
  **definition:** A reproducible set of failure cases drawn from agent-insights, skill_feedback events, OBPI friction, wrong-skill invocations, and ARB-backed failures, used to test whether a candidate skill edit improves observed behavior.
- **term:** `dry-run-walkthrough` · **scope:** skill-evaluation · **provenance:** ADR-0.51.0-skill-tuning-feedback-loop
  **definition:** An evaluator narration of the tool calls a skill would issue against a reference task, scored on call-shape fidelity without actually executing the tools.
- **term:** `tool-fidelity` · **scope:** skill-evaluation · **provenance:** ADR-0.51.0-skill-tuning-feedback-loop
  **definition:** The degree to which an evaluator's predicted tool-call shape (tool name, argument structure, order) matches the contract the skill is designed to drive; weighted to zero for non-tool-operating skills.
- **term:** `baseline-vs-candidate` · **scope:** skill-evaluation · **provenance:** ADR-0.51.0-skill-tuning-feedback-loop
  **definition:** The pairing of a current skill version (baseline) against a proposed edit (candidate), evaluated against the same hard basket to attribute behavior change to the edit.
- **term:** `prior-opinion-trail` · **scope:** skill-evaluation · **provenance:** ADR-0.51.0-skill-tuning-feedback-loop
  **definition:** The append-only sequence of past Optimize attestations recorded in SKILL.md frontmatter, naming evaluator model, date, content-hash, and findings; persists evaluation genealogy across model cycles.

### Governance Triage

- **term:** `triage-rubric` · **scope:** governance-triage · **provenance:** ADR-0.0.57-foundation-adr-nominal-id-triage, ADR-0.0.48-gz-adr-pool-triage
  **definition:** The structured scoring system that converts pool/foundation ADR backlog records into ranked recommendations using insights-signal-count, ghi-occurrence-count, and feature-unblocking-count dimensions.
- **term:** `insights-signal-count` · **scope:** governance-triage · **provenance:** ADR-0.0.57-foundation-adr-nominal-id-triage, ADR-0.0.48-gz-adr-pool-triage
  **definition:** Count of records in `.gzkit/insights/agent-insights.jsonl` whose scope references the candidate ADR; structured signal source for triage ranking, not LLM-prose ranking.
- **term:** `ghi-occurrence-count` · **scope:** governance-triage · **provenance:** ADR-0.0.57-foundation-adr-nominal-id-triage, ADR-0.0.48-gz-adr-pool-triage
  **definition:** Count of open GHIs whose body or title references the candidate ADR's identifier; structured signal of operator friction with the gap the ADR addresses.
- **term:** `feature-unblocking-count` · **scope:** governance-triage · **provenance:** ADR-0.0.57-foundation-adr-nominal-id-triage
  **definition:** Count of pool or feature ADRs whose `depends_on` frontmatter references the candidate foundation ADR; measures how many downstream items are blocked by this foundation's absence. Highest-weight dimension in the rubric scoring formula (weight 5 vs 3 for insights and 2 for GHI).
- **term:** `port-adapter-reclassification-flag` · **scope:** governance-triage · **provenance:** ADR-0.0.48-gz-adr-pool-triage, ADR-0.0.57-foundation-adr-nominal-id-triage
  **definition:** Triage output that marks a pool ADR whose scope matches hexagonal-port characteristics (authors an invariant, prerequisite for features) and recommends promotion as foundation kind rather than feature.
- **term:** `nominal-identifier` · **scope:** governance-triage · **provenance:** ADR-0.0.57-foundation-adr-nominal-id-triage
  **definition:** A governance ID component whose value uniquely identifies the artifact but carries no ordering semantics; pool slugs, GHI numbers, and foundation 0.0.x third components are nominal identifiers; feature ADR versions are genuine semver.

## 2.2 Bounded Contexts

<!-- Each entry conforms to BoundedContextDeclaration schema (ADR-0.0.43):
     slug, purpose (≥10 chars), owner_persona (registered persona), lifecycle_state, dm_ref, introduced_in. -->

- **slug:** `skill-evaluation` · **owner_persona:** main-session · **lifecycle_state:** active · **dm_ref:** _(none yet)_ · **introduced_in:** ADR-0.51.0-skill-tuning-feedback-loop
  **purpose:** Empirically score skill behavior (control-surface text) against observed failure classes using cross-model-family evaluators, producing reproducible signals for trim-and-recalibrate decisions across model cycles.

- **slug:** `governance-triage` · **owner_persona:** main-session · **lifecycle_state:** active · **dm_ref:** _(none yet)_ · **introduced_in:** ADR-0.0.57-foundation-adr-nominal-id-triage
  **purpose:** Rank governance backlogs (pool ADRs, foundation ADRs) by impact and structured signals so highest-value next-work surfaces as a reproducible ephemeral report rather than recall-based agent narration.

## 2.3 Context Map

<!-- Each entry conforms to ContextMapEntry schema (ADR-0.0.43):
     from, to, type (Evans-7 + Vernon Partnership + Big-Ball-of-Mud), description (≥10 words). -->

- **from:** `skill-evaluation` · **to:** `governance-triage` · **type:** `shared-kernel`
  **description:** Both contexts share a kernel of rubric vocabulary (`rubric-dimension`, `rubric-finding`, `evidence-citation`) registered as cross-cutting terms; changes to the shared kernel require coordination across both contexts to preserve scoring consistency.

---

## 3. Context & Background

### Business Context

gzkit is the extracted governance methodology from AirlineOps, intended as a standalone tool for any project adopting the GovZero discipline.

### Lineage

| Source | Contribution |
|--------|--------------|
| **Spec-kit** (GitHub) | Phase model: constitute → specify → plan → implement → analyze |
| **GovZero Charter** | Five Gates, Lane Doctrine, Attestation Terms |
| **Zero Doctrine** | Human as index zero, Q&A imperative, ceremony-as-debt |
| **BEADS** (Yegge) | JSONL ledger, dependency tracking, queryable state |
| **GSD** (glittercowboy) | STATE.md pattern, persistent context across sessions |
| **airlineops/opsdev** | Ledger append patterns, governance guards |

### Target Users

| Persona | Need |
|---------|------|
| **Architect** | Maintain design authority while leveraging AI assistance |
| **Student** | Learn governance-aware development methodology |
| **Team Lead** | Establish covenant discipline across a team |
| **Solo Developer** | Self-impose rigor on AI-assisted projects |

---

## 4. Scope

### In Scope (1.0.0)

**Phase Commands:**

- `gz init` — scaffold project structure, `.gzkit.json`, and ledger
- `gz prd` — create PRD via mandatory Q&A interview (Major intent carrier)
- `gz constitute` — create/validate constitution artifacts
- `gz specify <brief>` — create brief from template
- `gz plan <adr>` — create ADR via mandatory Q&A interview, scaffold ADR folder structure
- `gz specify <brief> --parent <adr> --item <n>` — create one OBPI brief per ADR checklist item (One Brief Per Item)
- `gz implement` — verify gates (tests, docs, BDD)
- `gz closeout <adr>` — execute closeout ceremony protocol (agent becomes passive presenter)
- `gz attest` — record human attestation after direct observation
- `gz audit` — generate audit artifacts (post-attestation)

**OBPI Discipline (One Brief Per Item):**

- Each ADR checklist item maps to exactly one OBPI brief
- Sequential, zero-gap numbering: `OBPI-0.1.0-01`, `OBPI-0.1.0-02`, etc.
- Pre-release identifiers: `0.1.0-obpi.03` (SemVer compliant)
- OBPIs are planned work; GHIs (GitHub Issues) are emergent work discovered during execution
- `gz specify --parent ADR-... --item <n>` creates compliant OBPI briefs from ADR checklist items

**Mandatory Q&A Interview:**

- PRD and ADR creation REQUIRE structured interview process
- Interview shapes/steers document content (not just metadata collection)
- Q&A transcript preserved as an embedded `## Q&A Transcript` section in the document body

**Closeout Ceremony Protocol:**

- Triggered by `gz closeout <adr>` or human phrase ("begin closeout")
- Agent becomes passive presenter (mode transition)
- Agent presents paths and commands ONLY, never outcomes or summaries
- Human executes commands and observes directly (no mediated observation)
- Human provides explicit attestation: Completed | Completed—Partial | Dropped
- Audit runs AFTER attestation (reconciliation only, not proof)

**ADR Folder Structure (ADR-Contained Layout):**

```
docs/design/adr/{foundation|pre-release|<major>.0}/ADR-X.Y.Z-{slug}/
  ADR-X.Y.Z-{slug}.md           # Intent document
  ADR-CLOSEOUT-FORM.md          # Closeout ceremony workspace
  obpis/
    OBPI-X.Y.Z-01-*.md          # One per checklist item
    OBPI-X.Y.Z-02-*.md
  audit/
    AUDIT.md                    # Post-attestation audit log
```

**Control Surface Generation:**

- `gz sync` generates agent control surfaces from governance canon
- CLAUDE.md — Claude Code contract (constraint-forward)
- AGENTS.md — Universal agent contract (all vendors)
- Precedence hierarchy: AGENTS.md > vendor-specific > task prompt > skills

**State & Inspection:**

- `gz state` — render current state from ledger (human-readable)
- `gz state --json` — dump current state (machine-readable)
- `gz state --blocked` — show blocked items and why
- `gz state --ready` — show items ready for work
- `gz status` — display gate status for current work
- `gz gates` — run gate checks and report results

**Ledger System:**

- `.gzkit/ledger.jsonl` — append-only event log
- Implicit writes from all `gz` commands
- Event schema versioning (`gzkit.ledger.v1`)
- Dependency tracking (parent, blocks, blocked_by)

**Claude Hooks Integration:**

- `.claude/settings.json` — hook configuration
- `.claude/hooks/` — hook scripts
- PostToolUse hooks for governance artifact edits
- PreToolUse hooks for constraint enforcement

**Configuration:**

- `.gzkit.json` configuration with Lite/Heavy mode
- Template customization
- Path configuration for artifacts

### Out of Scope (1.0.0)

- CI/CD pipeline integration (documented but not automated)
- GitHub Actions workflows
- Remote/cloud governance storage
- Multi-repo governance
- IDE plugins

---

## 5. User Stories & Use Cases

### User Stories

| ID | Story |
|----|-------|
| US-001 | As an architect, I want to initialize a project with governance structure, so that I have a covenant from day one. |
| US-002 | As an architect, I want to create a constitution, so that I have a north star to reference. |
| US-003 | As an architect, I want to create briefs from templates, so that work is scoped before implementation. |
| US-004 | As an architect, I want to create ADRs linked to briefs, so that design decisions trace to requirements. |
| US-005 | As an architect, I want to see gate status at a glance, so that I know what's blocking closeout. |
| US-006 | As an architect, I want to run gate checks, so that I can verify compliance before attestation. |
| US-007 | As an architect, I want to record attestation explicitly, so that my approval is non-repudiable. |
| US-008 | As an architect, I want to generate audit artifacts, so that governance is traceable. |

### Primary Use Case: Daily Driving

**Scenario**: Architect uses gzkit throughout a feature lifecycle.

```
gz init my-project                    # Day 0: scaffold
gz constitute                         # Day 0: establish north star
gz specify add-user-auth              # Day 1: scope the work
gz plan ADR-0.1.0 --brief add-user-auth   # Day 1: design decision
# ... implement feature ...
gz status                             # Day N: check progress
gz gates                              # Day N: verify compliance
gz attest                             # Day N: human closeout
gz audit ADR-0.1.0                    # Day N: generate audit
```

**Outcome**: Complete traceability from intent to attestation.

---

## 6. Functional Requirements

### FR-001: Project Initialization

`gz init [project-name]` SHALL:

- Create `.gzkit.json` configuration file with sensible defaults
- Create `.gzkit/ledger.jsonl` (empty ledger file)
- Create `.claude/settings.json` with hook configuration
- Create `.claude/hooks/` directory with ledger-writer script
- Create `docs/constitutions/` directory
- Create `docs/briefs/` directory
- Create `docs/adr/` directory
- Create `docs/audit/` directory
- Create `docs/prd/` directory
- Append `project_init` event to ledger
- Fail with clear error if structure already exists (no silent overwrite)

### FR-002: PRD Management

`gz prd [name]` SHALL:

- Run mandatory Q&A interview to shape PRD content
- Create PRD from hardened template populated with interview answers
- Embed the Q&A transcript in the PRD body as a `## Q&A Transcript` section
- Link PRD to constitution
- Append `prd_created` event to ledger
- Support `--template` flag for custom templates
- Refuse to create PRD without completing interview (no `--skip-interview`)

### FR-003: Constitution Management

`gz constitute [name]` SHALL:

- Create constitution from template if not exists
- Validate constitution structure if exists
- Report validation errors with file:line references
- Append `constitution_created` event to ledger
- Support `--template` flag for custom templates

### FR-004: Brief Creation

`gz specify <brief-name>` SHALL:

- Create brief from template in configured briefs directory
- Insert constitution reference automatically
- Generate unique brief ID
- Append `brief_created` event to ledger with `parent` reference
- Fail if constitution does not exist

### FR-005: ADR Creation

`gz plan <adr-name>` SHALL:

- Run mandatory Q&A interview to shape ADR content (including checklist items)
- Create ADR folder structure: `docs/design/adr/{foundation|pre-release|<major>.0}/ADR-X.Y.Z-{slug}/`
- Create ADR document from template populated with interview answers
- Create `obpis/` subdirectory for OBPIs
- Create `audit/` subdirectory for post-attestation audit
- Create `ADR-CLOSEOUT-FORM.md` template
- Embed the Q&A transcript in the ADR body as a `## Q&A Transcript` section
- Link to specified brief(s) via `--brief` flag
- Determine lane (Lite/Heavy) from interview
- Append `adr_created` event to ledger with `parent` and `blocks` references
- Fail if referenced brief does not exist
- Refuse to create ADR without completing interview

### FR-005a: OBPI Brief Creation

`gz specify <brief-name> --parent <adr-id> --item <n>` SHALL:

- Parse ADR checklist items from ADR document
- Generate one OBPI brief for the selected checklist item (One Brief Per Item discipline)
- Use sequential, zero-gap numbering: `OBPI-X.Y.Z-01`, `OBPI-X.Y.Z-02`, etc.
- Place OBPIs in `docs/design/adr/{foundation|pre-release|<major>.0}/ADR-X.Y.Z-{slug}/obpis/`
- Populate OBPI template with:
  - Parent ADR reference
  - Checklist item number and description
  - Lane (inherited from ADR)
  - Gate evidence placeholders
- Append `obpi_created` events to ledger for each OBPI
- Require `--item <n>` for checklist mapping
- Fail if ADR has no checklist items

### FR-005b: Closeout Ceremony

`gz closeout <adr-id>` SHALL:

- Verify all OBPIs are complete (acceptance criteria met)
- Enter closeout mode (agent behavior transition)
- Present evidence paths and commands ONLY (no outcomes):
  - Gate 1: ADR document path
  - Gate 2: Test command (`uv run -m unittest`)
  - Gate 3: Docs command (`uv run mkdocs build --strict`) (Heavy only)
  - Gate 4: BDD command (`uv run behave`) (Heavy only)
  - Gate 5: Awaiting human attestation (Heavy only)
- Wait for explicit human attestation term
- Record attestation in ADR-CLOSEOUT-FORM.md
- Append `closeout_initiated` event to ledger
- NOT run audit (audit is post-attestation via `gz audit`)

### FR-006: Gate Verification

`gz implement` SHALL:

- Run Gate 2 (TDD): execute test suite, report coverage
- Run Gate 3 (Docs): validate markdown, check links (Heavy only)
- Run Gate 4 (BDD): execute acceptance scenarios (Heavy only)
- Append `gate_checked` events to ledger for each gate
- Report gate status with pass/fail and evidence references
- Exit non-zero if any required gate fails

`gz gates` SHALL:

- Run all applicable gates for current lane
- Display results in terminal
- Append `gate_checked` events to ledger
- Support `--gate <n>` to run specific gate

### FR-007: State Management

`gz state` SHALL:

- Parse `.gzkit/ledger.jsonl` and compute current state
- Display dependency graph of artifacts (PRD → Brief → ADR)
- Support `--json` for machine-readable output
- Support `--blocked` to show items with unresolved dependencies
- Support `--ready` to show items ready for work
- NOT write to ledger (read-only operation)

### FR-008: Status Display

`gz status` SHALL:

- Display current lane (Lite/Heavy)
- Display active ADR(s) and their gate status
- Display blocking issues with file:line references
- Support `--json` for machine-readable output

### FR-009: Attestation Recording

`gz attest` SHALL:

- Prompt for attestation term (Completed / Partial / Dropped)
- Validate required gates are passing (per lane)
- Record attestation with timestamp and identity in ADR
- Append `attested` event to ledger with term and identity
- Refuse to attest if gates failing (without `--force`)
- Support `--reason` for Partial/Dropped rationale

### FR-010: Audit Generation

`gz audit` SHALL:

- Generate audit artifact from ADR and gate evidence
- Include attestation record
- Include gate results with evidence links
- Append `audit_generated` event to ledger
- Write to configured audit directory

### FR-011: Ledger System

The ledger system SHALL:

- Store events in `.gzkit/ledger.jsonl` as append-only JSONL
- Use schema versioning (`gzkit.ledger.v1`)
- Include `ts` (ISO 8601 UTC), `event`, `id`, and event-specific fields
- Support `parent` field for dependency tracking
- Support `blocks` and `blocked_by` fields for work coordination
- Be implicitly written by all `gz` commands (no explicit ledger calls)
- Be queryable via `gz state` command

**Event types:**

| Event | Fields | Trigger |
|-------|--------|---------|
| `project_init` | `id`, `ts` | `gz init` |
| `prd_created` | `id`, `parent`, `ts` | `gz prd` |
| `constitution_created` | `id`, `ts` | `gz constitute` |
| `brief_created` | `id`, `parent`, `ts` | `gz specify` |
| `adr_created` | `id`, `parent`, `blocks`, `ts` | `gz plan` |
| `gate_checked` | `adr`, `gate`, `status`, `evidence`, `ts` | `gz implement`, `gz gates` |
| `attested` | `adr`, `term`, `by`, `ts` | `gz attest` |
| `audit_generated` | `adr`, `path`, `ts` | `gz audit` |
| `artifact_edited` | `path`, `session`, `ts` | Claude hook (PostToolUse) |

### FR-012: Claude Hooks Integration

`gz init` SHALL scaffold Claude hooks:

- `.claude/settings.json` with PostToolUse hook configuration
- `.claude/hooks/ledger-writer.py` script

The ledger-writer hook SHALL:

- Fire on PostToolUse for Edit and Write tools
- Match governance artifact patterns:
  - `docs/adr/**/*.md`
  - `docs/briefs/**/*.md`
  - `docs/prd/**/*.md`
  - `docs/constitutions/**/*.md`
  - `docs/audit/**/*.md`
- Append `artifact_edited` event to ledger
- Include session ID for traceability
- Exit 0 on success (non-blocking)

PreToolUse hooks MAY:

- Block edits to closed/attested ADRs
- Warn on edits to constitution without explicit flag
- Enforce constraint violations

---

## 7. Non-Functional Requirements

### Performance

- All commands SHALL complete in <5 seconds on standard hardware
- No network calls required for core functionality

### Determinism

- Same inputs SHALL produce same outputs
- Template rendering SHALL be reproducible
- Only attestation timestamps are non-deterministic (by design)

### Explainability

- Every gate failure SHALL trace to specific file:line evidence
- Every attestation SHALL record human identity and timestamp
- Every audit SHALL link to source artifacts

### Accessibility

- CLI SHALL support `--no-color` for accessibility
- CLI SHALL support `--quiet` for scripting
- All output SHALL be screen-reader compatible (no ASCII art)

---

## 8. Dependencies

### Runtime

| Dependency | Purpose |
|------------|---------|
| Python 3.13.x | Runtime |
| Click | CLI framework |
| Pydantic | Configuration validation |
| json (stdlib) | JSON parsing |

### Development

| Dependency | Purpose |
|------------|---------|
| uv | Package management |
| ruff | Linting and formatting |
| ty | Type checking |
| unittest | Testing |

### External

- None (no network dependencies for core functionality)

---

## 9. Risks & Assumptions

### Risks

| Risk | Impact | Mitigation |
|------|--------|------------|
| Scope creep | Delays 1.0.0 | Strict In Scope enforcement; defer to 2.0.0 |
| Template complexity | User confusion | Start minimal; iterate based on feedback |
| Adoption friction | Low usage | One-screen docs; graduate course validation |
| Over-ceremony | User rejection | Lite lane as default; Heavy only when needed |

### Assumptions

- Users have Python 3.13.x and uv installed
- Users accept Markdown as primary artifact format
- Users understand (or will learn) basic governance concepts
- Terminal/CLI interaction is acceptable (no GUI required)

---

## 10. Acceptance Criteria

### AC-001: Initialization

- [ ] `gz init test-project` creates all required directories and `.gzkit.json`
- [ ] `gz init` in existing gzkit project fails with clear error
- [ ] Generated `.gzkit.json` is valid and parseable

### AC-002: Constitution

- [ ] `gz constitute` creates constitution from template
- [ ] `gz constitute --validate` reports errors for malformed constitution
- [ ] Constitution contains required sections (per template)

### AC-003: Brief Creation

- [ ] `gz specify my-feature` creates brief in configured directory
- [ ] Brief contains constitution reference
- [ ] Brief has unique ID
- [ ] Command fails if no constitution exists

### AC-004: ADR Creation

- [ ] `gz plan ADR-0.1.0 --brief my-feature` runs mandatory Q&A interview
- [ ] Interview answers populate ADR template
- [ ] ADR body carries the Q&A transcript as a `## Q&A Transcript` section
- [ ] ADR folder structure created: `docs/design/adr/pre-release/ADR-0.1.0-{slug}/`
- [ ] `obpis/` and `audit/` subdirectories created
- [ ] `ADR-CLOSEOUT-FORM.md` template created
- [ ] ADR contains brief linkage
- [ ] ADR contains checklist items from interview
- [ ] ADR declares lane (Lite/Heavy) from interview
- [ ] Command fails if referenced brief does not exist
- [ ] Command fails if interview not completed (no skip option)

### AC-004a: OBPI Generation

- [ ] `gz specify setup-db --parent ADR-0.1.0 --item 1` parses checklist item mapping from ADR
- [ ] One OBPI brief created per checklist item
- [ ] OBPIs numbered sequentially: `OBPI-0.1.0-01`, `OBPI-0.1.0-02`, etc.
- [ ] OBPIs placed in `docs/design/adr/pre-release/ADR-0.1.0-{slug}/obpis/`
- [ ] Each OBPI contains parent ADR reference and checklist item mapping
- [ ] `obpi_created` events appended to ledger
- [ ] Command fails if ADR has no checklist items

### AC-004b: Closeout Ceremony

- [ ] `gz closeout ADR-0.1.0` verifies all OBPIs complete
- [ ] Closeout presents evidence paths and commands only (no outcomes)
- [ ] Closeout waits for explicit human attestation term
- [ ] Attestation term recorded in ADR-CLOSEOUT-FORM.md
- [ ] `closeout_initiated` event appended to ledger
- [ ] Audit does NOT run during closeout (post-attestation only)

### AC-005: Gate Verification

- [ ] `gz implement` runs applicable gates
- [ ] Gate failures include file:line evidence
- [ ] Exit code reflects gate status
- [ ] `gz gates --gate 2` runs only Gate 2

### AC-006: Status Display

- [ ] `gz status` shows lane and gate status
- [ ] `gz status --json` outputs valid JSON
- [ ] Blocking issues show file:line references

### AC-007: Attestation

- [ ] `gz attest` prompts for term
- [ ] Attestation records timestamp and identity
- [ ] `gz attest` fails if gates not passing (without `--force`)
- [ ] `gz attest --force` overrides with warning

### AC-008: Audit Generation

- [ ] `gz audit ADR-0.1.0` generates audit artifact
- [ ] Audit includes attestation record
- [ ] Audit includes gate evidence links

### AC-009: PRD Management

- [ ] `gz prd PRD-GZKIT-1.0.0` runs mandatory Q&A interview
- [ ] Interview answers populate PRD template
- [ ] PRD body carries the Q&A transcript as a `## Q&A Transcript` section
- [ ] PRD contains all hardened sections (invariants, gate mapping, Q&A, attestation)
- [ ] `prd_created` event appended to ledger
- [ ] PRD links to constitution
- [ ] Command fails if interview not completed (no skip option)

### AC-010: State Management

- [ ] `gz state` parses ledger and displays current state
- [ ] `gz state --json` outputs valid JSON
- [ ] `gz state --blocked` shows items with unresolved dependencies
- [ ] `gz state --ready` shows items ready for work
- [ ] State display shows dependency graph (PRD → Brief → ADR)

### AC-011: Ledger System

- [ ] `.gzkit/ledger.jsonl` created by `gz init`
- [ ] All `gz` commands append events to ledger
- [ ] Events include `schema`, `event`, `ts` fields
- [ ] Ledger is append-only (no modifications)
- [ ] Events are valid JSONL (one JSON object per line)

### AC-012: Claude Hooks

- [ ] `gz init` creates `.claude/settings.json` with hook config
- [ ] `gz init` creates `.claude/hooks/ledger-writer.py`
- [ ] Hook fires on Edit/Write to governance artifacts
- [ ] Hook appends `artifact_edited` event to ledger
- [ ] Hook includes session ID in event

---

## 11. Success Metrics

| Metric | Target |
|--------|--------|
| Commands functional | 11/11 (init, prd, constitute, specify, plan, implement, gates, state, status, attest, audit) |
| Ledger operational | All commands append events |
| Hooks operational | PostToolUse fires on governance artifact edits |
| Test coverage | ≥40% |
| Docs build | Passes |
| Type check | Passes (ty strict) |
| Demo workflow | Completable by student unassisted |

---

## 12. Rollout & Release Plan

### Phase 1: MVP (0.1.0)

Target: Graduate course demo

- `gz init` with ledger and hooks scaffolding
- `gz prd`, `gz constitute`, `gz specify`, `gz plan`
- `gz state`, `gz status`, `gz attest`
- Minimal templates (PRD, constitution, brief, ADR)
- Ledger system (append-only JSONL)
- Claude hooks (PostToolUse ledger-writer)
- One-screen docs per command

### Phase 2: Gates (0.2.0)

- `gz implement` with Gate 2 (TDD)
- `gz gates` command
- Gate evidence linking
- `gate_checked` events in ledger

### Phase 3: Canon Extraction (0.3.0)

- Reconcile governance artifacts with airlineops canonical GovZero patterns
- Port canonical templates with 1:1 fidelity and identify drift
- Establish a sync mechanism so canon updates flow without manual translation

### Phase 4: Skill Capability Mirroring (0.4.0)

- Canonical skill source in `.gzkit/skills`
- Agent-native mirror propagation (`.agents`, `.claude`, `.github`)
- Sync behavior and control-surface path hardening

### Phase 5: Skill Lifecycle Governance (0.5.0)

- Skill taxonomy and lifecycle metadata contract
- Policy-backed parity verification (`gz skill audit`)
- Lifecycle transition and maintenance/deprecation operations

### Phase 6: Audit (0.6.0)

- `gz audit` with audit generation
- Audit templates
- Evidence aggregation from ledger
- `audit_generated` events

### Phase 7: Release (1.0.0)

- All 11 commands functional
- Templates hardened
- Ledger fully operational
- Hooks fully operational
- Documentation complete
- Graduate course validated

---

## 13. Open Questions

- [ ] Should `gz status` read from git state or explicit markers?
- [ ] What's the minimum viable constitution template?
- [ ] Should attestation support GPG signing?
- [ ] Should `gz implement` run tests directly or defer to configured command?
- [ ] How should multi-ADR projects display status?

---

## 14. References

| Document | Purpose |
|----------|---------|
| [gzkit Charter](../../user/charter.md) | Constitution |
| [RFC-GZKIT-FOUNDATION](../../user/sources/RFC-GZKIT-FOUNDATION-airlineops.md) | Origin RFC |
| [GovZero Release Doctrine](../../user/sources/govzero-release-doctrine-airlineops.md) | SemVer governance |
| [GitHub Spec-kit](https://github.com/github/spec-kit) | Phase model lineage |
| [BEADS](https://github.com/steveyegge/beads) | Ledger/state tracking lineage |
| [GSD](https://github.com/glittercowboy/get-shit-done) | Context engineering lineage |
| [Claude Code Hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) | Hook integration reference |

---

## 15. Invariants

These constraints are non-negotiable. Agents MUST reason against them.

| ID | Invariant |
|----|-----------|
| INV-001 | Human attestation CANNOT be automated or bypassed |
| INV-002 | Gate 5 REQUIRES explicit human action |
| INV-003 | Briefs MUST reference constitution |
| INV-004 | ADRs MUST link to briefs |
| INV-005 | Attestation terms MUST be canonical (Completed / Partial / Dropped) |
| INV-006 | All commands MUST be deterministic (same input → same output, except timestamps) |
| INV-007 | Lite lane enforces Gates 1-2 ONLY; Heavy lane enforces Gates 1-5; Gate 5 is Heavy-only |
| INV-008 | Gate failures MUST include file:line evidence |
| INV-009 | Ledger MUST be append-only; existing events CANNOT be modified |
| INV-010 | All `gz` commands MUST append events to ledger implicitly |
| INV-011 | Ledger events MUST include ISO 8601 UTC timestamp |
| INV-012 | Claude hooks MUST NOT block on ledger write failure (best-effort) |
| INV-013 | PRDs MUST be bound to Major versions |
| INV-014 | ADRs MUST link to parent PRD or Brief |
| INV-015 | PRD and ADR creation MUST use mandatory Q&A interview |
| INV-016 | Q&A transcripts MUST be preserved as artifacts |
| INV-017 | Each ADR checklist item MUST map to exactly one OBPI (One Brief Per Item) |
| INV-018 | OBPI numbering MUST be sequential with zero gaps |
| INV-019 | Closeout ceremony MUST precede attestation for Heavy lane |
| INV-020 | During closeout, agent MUST present paths/commands only, NEVER outcomes |
| INV-021 | Human MUST observe directly during closeout (no mediated observation) |
| INV-022 | Audit runs AFTER attestation (reconciliation, not proof) |
| INV-023 | Alignment chain MUST hold: Intent (ADR/OBPI) ↔ Code (behavior) ↔ Docs (claims) |
| INV-024 | Primary proof artifacts MUST be user documentation, command manpages, and an operator runbook |

---

## 16. Gate Mapping

This PRD is verified through the following gates:

| Gate | Evidence |
|------|----------|
| Gate 1 (ADR) | This PRD + downstream ADRs |
| Gate 2 (TDD) | `uv run -m unittest discover tests` passes; ≥40% coverage |
| Gate 3 (Docs) | `uv run mkdocs build` passes; user docs, command manpages, and operator runbook are current |
| Gate 4 (BDD) | CLI contract scenarios pass (Heavy lane) |
| Gate 5 (Human) | Attestation block below completed by human |

---

## 17. Q&A Record

Q&A that shaped this PRD (per Human Discipline):

| Date | Question | Answer | Questioner |
|------|----------|--------|------------|
| 2026-01-13 | Does 0.1.0 need a PRD or is RFC sufficient? | PRD required; RFC is source material | Agent |
| 2026-01-13 | What's minimum viable for grad course demo? | 6 commands: init, constitute, specify, plan, status, attest | Human |
| 2026-01-13 | Is Charter the constitution? | Yes; Charter = Constitution, North Star = Spec/PRD | Human |
| 2026-01-13 | Should PRD be Major-bound? | Yes; PRD-GZKIT-1.0.0 defines the Major target | Human |
| 2026-01-13 | How do PRDs work across Majors? | Expand TOWARDS next Major; shipped PRD becomes baseline | Human |
| 2026-01-13 | Should gzkit have a `gz prd` command? | Yes; PRD is part of covenant, should scaffold like other artifacts | Human |
| 2026-01-13 | Should gzkit track state like BEADS/GSD? | Yes; JSONL ledger with `gz state` to query | Human |
| 2026-01-13 | How to prevent agent forgetting ledger? | Implicit writes from all `gz` commands + Claude hooks | Agent |
| 2026-01-13 | Should we use SQLite cache like BEADS? | Uncertain; JSONL sufficient for MVP, SQLite optional | Human |
| 2026-01-13 | How to track ADR/OBPI/GHI closure? | Claude hooks (PostToolUse) append to ledger on artifact edits | Human |
| 2026-01-22 | Does Lite lane include Gate 5? | NO. Lite = Gates 1-2 only. Gate 5 is Heavy-only. | Human |
| 2026-01-22 | What is an OBPI? | One Brief Per Item - atomic work unit mapping 1:1 to ADR checklist item | Agent (from airlineops) |
| 2026-01-22 | What is closeout ceremony? | Mode transition where agent becomes passive presenter; human observes directly | Agent (from airlineops) |
| 2026-01-22 | Should Q&A interview be mandatory? | YES. Interview shapes PRD/ADR; transcript preserved as artifact | Human |
| 2026-01-22 | Should gzkit mirror airlineops patterns or innovate? | COMBINE: mandatory Q&A (gzkit innovation) + extract airlineops patterns (OBPI, closeout, etc.) | Human |
| 2026-01-22 | What's the test progression for gzkit? | gzkit (dogfood) → flightops (apply) → airlineops (re-integrate to genesis) | Human |
| 2026-01-22 | Should we update PRD or create ADRs for new requirements? | Update PRD first. PRDs expand TOWARDS Major; ADRs implement PRD requirements. | Agent (per GovZero guidance) |
| 2026-01-22 | What is the alignment chain? | Intent (ADR/OBPI) ↔ Code (behavior) ↔ Docs (claims) - all three must hold | Agent (from airlineops) |
| 2026-01-13 | How to track ADR/OBPI/GHI closure? | Claude hooks (PostToolUse) append to ledger on artifact edits | Human |

---

## 18. Attestation Block

**Status**: Draft

| Field | Value |
|-------|-------|
| Attestation Term | — |
| Attested By | — |
| Attested At | — |
| Evidence | — |

Human attestation required before promotion to Accepted.
