py-gzkit 0.32.0

GovZero Kit: A Development Covenant for Human-AI Collaboration

gzkit

GovZero Kit: A Development Covenant for Human-AI Collaboration

Documentation Release Notes Roadmap

gzkit is cognitive infrastructure for extended human-AI collaboration-a protocol that preserves human intent across agent context boundaries, gives agents constraints to reason against, creates verification loops both parties trust, and reserves final judgment for humans.

Why gzkit?

Modern AI-assisted development faces a structural problem: agents are powerful but context-bound. They drift without constraints, forget across sessions, and can't distinguish between "should do" and "could do." Humans provide intent and judgment but can't scale execution.

gzkit bridges this gap by formalizing the collaboration:

Role	Human	Agent
Intent	Originates	Interprets, clarifies
Constraints	Defines, enforces	Operates within, flags violations
Exploration	Guides	Executes, surfaces options
Judgment	Final authority	Proposes, explains tradeoffs
Memory	Long-term, cross-project	Session-bound, needs scaffolding
Verification	Attests	Generates evidence

Three Concerns

gzkit spans three distinct but interrelated concerns:

Concern	Purpose	Primary Audience
Specification	Invariants, constraints, acceptance criteria	Agent (grounding)
Methodology	Phases, workflows, checkpoints	Process (structure)
Governance	Authority, attestation, audit	Human (oversight)

Specification is agent-native: explicit constraints, declarative intent, immutable canon.

Methodology is process-native: phases, gates, verification loops.

Governance is human-native: attestation rituals, authority boundaries, audit ceremonies.

All three are necessary. Specification without governance drifts. Governance without methodology is theater. Methodology without specification is arbitrary.

Boundary

gzkit is a governance meta-harness and agent runner for governed human-AI work. A vendor harness turns a model into an agent; gzkit operates one tier up, wrapping agent harnesses such as Codex, Claude Code, Copilot, and adjacent tools with deterministic governance surfaces, evidence capture, gate enforcement, and human attestation.

gzkit is not a generic framework that asks humans to assemble arbitrary agent chains. It ships an opinionated covenant for deciding whether agent work is justified, verified, and complete. If gzkit grows a machine-readable workflow specification surface, its canonical form is JSON that describes gzkit stages, gate prerequisites, evidence requirements, and ledger events. Workflow specification should make the covenant more executable, not replace it with a YAML-style automation DSL.

The Covenant

gzkit implements a development covenant-a binding agreement between human and agent:

1. Human defines intent through canon, ADRs, and acceptance criteria
2. Agent operates within constraints and flags potential violations
3. Verification is mutual through tests, checks, and evidence
4. Human attests completion after observing artifacts
5. Artifacts survive sessions preserving intent across context boundaries. Gzkit operates as a constitutional framework for human‑agent collaboration: humans serve as the Legislature (defining intent, constraints, and final judgment), agents act as the Executive (executing within bounds and generating evidence), and tests/BDD function as the Judiciary (verifying compliance and enforcing the constitution).

This is not "AI governance" in the compliance sense. It's a protocol for productive partnership.

Lineage

gzkit evolved from:

• GitHub spec-kit - the constitute → specify → plan → implement → analyze phase model
• GovZero - governance framework developed in AirlineOps through ~100 work items of iterative learning
• Claude Code conventions - CLAUDE.md patterns for agent-native constraint specification

See docs/lineage.md for full heritage.

Five Gates

Work flows through five gates, adapted by lane (Lite or Heavy):

Gate	Name	Purpose
1	ADR	Record intent and tradeoffs before implementation
2	TDD	Red-Green-Refactor: tests derived from spec, not implementation
3	Docs	Ensure documentation describes actual behavior
4	BDD	Verify external contracts through acceptance tests
5	Human	Human observes artifacts and attests completion

Lite lane (internal changes): Gates 1, 2

Heavy lane (external contracts): Gates 1, 2, 3, 4, 5

Workflow Lifecycle

  DEFINE        PLAN          BUILD         VERIFY        ATTEST        RELEASE
 ┌──────┐    ┌──────┐    ┌──────────┐    ┌──────┐    ┌──────┐    ┌──────────┐
 │Design│───▶│  ADR │───▶│ Pipeline │───▶│Gates │───▶│Human │───▶│ Closeout │
 │ PRD  │    │ OBPI │    │ TDD Impl │    │Check │    │Attest│    │ Release  │
 └──────┘    └──────┘    └──────────┘    └──────┘    └──────┘    └──────────┘
  gz-design   gz-adr-      gz-obpi-       gz-check    gz-adr-     gz-patch-
  gz-prd      create       pipeline       gz-gates    closeout-   release
              gz-obpi-     gz-obpi-       gz-validate ceremony
              specify      simplify

Skill Catalog

Category	Skills
ADR Lifecycle	gz-adr-create, gz-adr-evaluate, gz-adr-promote, gz-adr-status, gz-design, gz-plan
ADR Operations	gz-adr-autolink, gz-adr-emit-receipt, gz-adr-map, gz-adr-recon, gz-adr-sync
ADR Audit & Closeout	gz-adr-audit, gz-adr-closeout-ceremony, gz-patch-release
OBPI Pipeline	gz-obpi-lock, gz-obpi-pipeline, gz-obpi-reconcile, gz-obpi-simplify, gz-obpi-specify, gz-plan-audit
Governance Infrastructure	gz-constitute, gz-gates, gz-implement, gz-init, gz-prd, gz-state, gz-status, gz-validate
Agent & Repository	git-sync, gz-agent-sync, gz-check-config-paths, gz-migrate-semver, gz-session-handoff, gz-tidy
Code Quality	gz-check, gz-chore-runner, gz-cli-audit
Routing	gz-skill-router

For details on any skill, read its SKILL.md in .gzkit/skills/<skill-name>/.

Installation

# Using uv (recommended)
uv tool install py-gzkit

# Or pip
pip install py-gzkit

Quick Start

# Initialize gzkit in a project
gz init

# Create a new ADR
gz plan create feature --title "Feature description"

# Check gate status
gz status

# Run verification
gz check

Configuration

gzkit uses .gzkit.json for project configuration:

{
  "mode": "lite",
  "paths": {
    "canon": "docs/canon",
    "adrs": "docs/adr",
    "specs": "docs/specs"
  }
}

Documentation

• Charter - The covenant itself
• Lineage - Heritage from spec-kit and GovZero
• Concepts - The three concerns explained
• Genesis - Origin story and founding conversation

Philosophy

Governance is verification, not celebration.

gzkit treats governance as executable documentation. All state lives in Markdown, validated by a Python CLI. The meta-harness is human-centric, auditable, and version-controlled.

Prompts are code. Constraints are first-class. Human attestation is the final gate.

License

MIT