<!-- Generated by gzkit — do not edit manually -->
# src/gzkit Agent Instructions

> Shared subtree rules. See root `AGENTS.md` for project-wide governance.

# Chores Workflow (gzkit)

> **Purpose:** Enable agents to run repository chores effectively with clear, repeatable command sequences, aligned to gzkit guardrails.

## Core Principles

| Principle           | Description                                     |
| ------------------- | ----------------------------------------------- |
| **Plan-first**      | Generate or refresh a chore plan before any run |
| **Lite by default** | Fast lane (<=60s), unit tests only              |
| **Small diffs**     | Touch only files in scope for the chore         |
| **CLI evidence**    | Never use raw SQL for attestation               |

## Command Sequences

### 1. Discover Chores

```bash
uv run gz chores list
uv run gz chores show <chore_slug>
```

### 2. Plan & Advise

```bash
uv run gz chores plan <chore_slug> --replace
uv run gz chores advise <chore_slug>
```

### 3. Apply Advice

1. **Read advice** — Identify discrete actions
2. **Create TODO list** — Exactly one item in-progress at a time
3. **Implement surgically** — Minimal diffs, preserve behavior
4. **Validate locally** — Lint, typecheck, tests
5. **Sync if green** — Commit/push after validation passes

```bash
uv run ruff check . --fix && uv run ruff format .
uvx ty check . --exclude 'features/**'
uv run -m unittest -q
```

## Evidence & Attestation

### Correct Evidence (CLI commands only)

```bash
uv run gz gates
uv run behave features/<feature>.feature --tags=@schema
```

### Prohibited Evidence

- Raw SQL statements
- Direct DB queries for attestation
- Bypassing CLI interface

# Gate 5 Runbook-Code Covenant (gzkit)

Documentation is a first-class deliverable and must track behavior changes in the same patch set.

## Three-layer documentation model

| Layer | Location | Purpose |
|---|---|---|
| Operator runbook | `docs/user/runbook.md` | daily execution workflow |
| Governance runbook | `docs/governance/governance_runbook.md` | governance-maintainer workflow |
| Command docs | `docs/user/commands/**` | command contracts and examples |

## Required updates when behavior changes

- Update command docs and examples.
- Update runbook flows and verification commands.
- Ensure attestation language remains explicit where required.

## Validation bundle

```bash
uv run gz lint
uv run gz validate --documents --surfaces
uv run mkdocs build --strict
```

## Anti-patterns

- Do not leave placeholder output examples.
- Do not update code without docs when command output changes.
- Do not declare completion without explicit human attestation for heavy/foundation scope.
