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

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

# ADR Audit (gzkit)

Purpose: verify ADR completion claims using reproducible evidence.

## Audit sequence

1. Verify linked OBPI evidence:

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

2. Run quality checks:

```bash
uv run gz lint
uv run gz test
uv run gz typecheck
uv run mkdocs build --strict
```

3. Run closeout/audit lifecycle in order:

```bash
uv run gz closeout ADR-<X.Y.Z> --dry-run
uv run gz attest ADR-<X.Y.Z> --status completed
uv run gz audit ADR-<X.Y.Z>
```

4. Emit audit receipt:

```bash
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.
- If audit-check fails, fix brief evidence first and rerun.
- Keep `docs/user/runbook.md` and `docs/governance/governance_runbook.md` aligned with runtime behavior.

# GitHub CLI Guardrails (gzkit)

Use `gh` only when explicitly requested by the user, an active brief, or closeout protocol.

## Allowed commands

```bash
gh auth status
gh issue create --label defect --title "..." --body "..."
gh issue list --search "ADR-X.Y.Z" --state open
gh issue close <number> --comment "Resolved by ADR-X.Y.Z closeout."
gh release create vX.Y.Z --title "vX.Y.Z" --notes-file RELEASE_NOTES.md
```

## Prohibited without explicit approval

- Repository/org settings mutations
- Secret/token management
- Force pushes
- Merging PRs without explicit human authorization

## Defect tracking requirement

When a defect cannot be fixed in the current patch:

1. `gh issue create --label defect ...`
2. Link the issue in the relevant ADR/OBPI evidence section.
