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

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

<!-- Generated by gz agent sync — do not edit -->

<!-- rule-version: 0.1.0 -->

# Guardrail Feedback Prose (gzkit)

> **Rule version:** `0.1.0` — initial authoring under ADR-0.0.70 (Buetow
> adoption): the feedback text IS the prompt a human would otherwise have
> typed; engineer it as one.

## Invariant

**Every fail-closed hook and validator emits agent-actionable three-part recovery prose: what failed, why it is forbidden (cited rule/invariant), the governed next step (runnable command or named ceremony).** A bare exit code, a raw traceback, or
an error dump without recovery prose forces the consuming agent to reconstruct
the operator's intent from training memory — the precise vibing surface gzkit
exists to close. (Buetow, Beyond Coding Podcast 2026-06-10: "you base the
feedback encodes the prompt that you would write as a human.")

| Part | Content | Bad example | Good example |
|------|---------|-------------|--------------|
| **What failed** | The concrete finding: file, line, check name, observed value | `exit 3` | `F401 src/x.py:1 unused import` |
| **Why it is forbidden** | The binding rule, invariant, or ADR the failure violates — cited, not paraphrased | "lint error" | "gzkit forbids ending a turn while the cheap deterministic tier is red (AGENTS.md Never #5)" |
| **Governed next step** | A runnable command or named ceremony that recovers — never "see docs" | "fix it" | "fix the findings, verify with `uv run ruff check <files>`, then end the turn" |

## Scope

Binds every fail-closed surface: blocking hooks under `.claude/hooks/`
(exit 2 + stderr), `gz validate` scopes (exit 3 diagnostics), ceremony gates,
and pre-commit/pre-push guards. Advisory (non-blocking) surfaces SHOULD follow
the same bar but are not fail-closed by this rule.

## First enforcement consumer

`stop-turn-feedback.py` (ADR-0.0.70, OBPI-0.0.70-01) — its block prose is
asserted against this bar by `tests/hooks/test_stop_turn_feedback.py`
(REQ-0.0.70-03-02). New fail-closed surfaces add an equivalent assertion in
their covering tests.

## Do Not

- Do not exit non-zero with no stderr prose (the consuming agent sees only a
  number)
- Do not dump raw findings without the why — findings without the cited rule
  invite the agent to argue with the check instead of fixing the cause
- Do not name a next step that is not runnable or not a registered ceremony
  ("see documentation", "contact the operator") when a concrete command exists
- Do not inline full sub-tool stderr past ~20 lines — trim and name the re-run
  command instead (precedent: closeout-proof re-run-command ruling, ADR-0.0.69)

## Mechanical promotion path

This rule is **Promotable**: a future `gz validate` scope can assert the
three-part shape on hook/validator output fixtures once catch evidence
accumulates (named future candidate in ADR-0.0.70 § Decision; deliberately not
shipped there — an inferential prose-grader is weaker than a real enforcement
consumer). Until then the bar binds at authoring time and via covering tests.
