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

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

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

<!-- rule-version: 0.3.1 -->

# Complexity Doctrine (gzkit)

> **Rule version:** `0.3.1` — renamed prohibited `## Corpus Anti-Patterns` heading → `## Corpus Disqualifiers` (OBPI-0.0.54-04 shape conformance pass).

## Invariant

**gzkit calibrates complexity decisions against an empirically-grounded corpus
of well-architected Python projects, distilled into doctrine prose and citable
numeric boundaries.** The corpus is operator-curated against this selection
methodology, not agent-pattern-matched from training corpus. Distilled
characteristics ship as gzkit doctrine; downstream foundation ADRs
(0.0.28 / 0.0.29 / 0.0.30) cite the doctrine, not the corpus directly.

The corpus is a *learning relationship*, not an *adoption relationship* —
gzkit measures click's design metrics to inform CLI doctrine; gzkit does not
depend on click. These are independent relationships and conflating them is
the canonical training-corpus failure mode.

## Selection Criteria (binding — all must hold)

Projects qualify for the exemplar corpus only when **ALL** of the following
criteria hold:

1. **Longevity:** >= 5 years active development OR explicitly archived as reference.
2. **Maintenance health:** active releases in last 12 months OR project declares done state.
3. **Practitioner reputation:** cited in PEPs, published reference works, or recurring conference talks — NOT by GitHub-star count.
4. **Pure-Python predominance:** Python content >= 80% of LOC; excludes thin C/Rust wrappers.
5. **Author craftsmanship signal:** maintainer shows design discipline (PEP authorship, design talks); agent nominates, operator witnesses.
6. **Project doctrine fitness:** project does not contradict gzkit canon (Stdlib-First, `forbid-pytest`); the pytest-mention demerit closes this failure class.
7. **Pinned commit SHA:** pinned to a specific commit SHA at corpus-authoring time; no floating-HEAD entries.

## Corpus Disqualifiers (binding — any disqualifies)

1. **Post-hoc fitting:** selecting projects that confirm a pre-decided threshold.
2. **GitHub-star count:** popularity is not a design-quality signal.
3. **Only modern projects:** loses the "test of time" signal across Python eras.
4. **Only legacy projects:** misses current best-practice idioms; corpus must span eras.
5. **Monoculture:** all from the same domain over-fits to one idiom.
6. **Agent-supplied list from training memory:** corpus is doctrine and must be operator-witnessed.
7. **Doctrine-incompatible inclusion:** including any project that violates gzkit's existing doctrinal commitments.

## Distillation Cadence (binding)

Re-distillation fires on **any** of three triggers:

1. **Annual calendar default:** Python ecosystem evolves on roughly annual cycles.
2. **Signal trigger:** advisor verdict-frequency drift > 25% from baseline; 6-month minimum guard prevents thrashing.
3. **Judgment trigger:** operator ad-hoc trigger when a ground-breaking project warrants corpus amendment.

Distillation is agent-driven, human-reviewed and attested/corrected:

1. Agent drafts metric-aggregate prose per metric (median, p75, p90, p95, p99
   with inter-project variance commentary).
2. Operator adds the practitioner-eye observation.
3. Joint authoring of actionable characteristics per metric: numeric boundary
   (corpus percentile + absolute number at that percentile), qualitative band
   (comfortable craft / investigate / refactor), doctrinal frame.
4. Agent proposes classifier rule-table boundary updates; operator audits.
5. Diff against previous distillation: any boundary that moved > 10% gets
   explicit operator narration.
6. Output: `docs/governance/complexity/distilled-characteristics-{date}.md`.
   Previous documents are preserved (never overwritten) — doctrine evolution
   has a permanent audit trail.

## Citation Contract (binding)

Downstream foundation ADRs (0.0.28 / 0.0.29 / 0.0.30) **MUST** cite the
distilled-characteristics document, **NOT** the raw distributions and **NOT**
the corpus (`data/exemplar_corpus.json`) directly.

### Canonical tuple (binding)

The citation is a three-field tuple
`(distilled_characteristics_path, section_anchor, corpus_revision)`,
codified by the Pydantic `Citation` model at
`src/gzkit/complexity/citation.py` (frozen, `extra="forbid"`) and mirrored
by the JSON Schema at `src/gzkit/schemas/complexity_citation.json`
(`additionalProperties: false`). The tuple is the only valid citation
shape; raw distributions, the corpus registry, and free-form prose
references are explicitly forbidden.

Canonical string form (consumed by `parse_citation`):

```
docs/governance/complexity/distilled-characteristics-2026-05-04.md § radon-cc (corpus revision 1)
```

Field constraints:

- `distilled_characteristics_path` is a relative path under
  `docs/governance/complexity/` ending in `.md`.
- `section_anchor` is a slugified anchor string identifying the metric
  section within the cited document.
- `corpus_revision` is a positive integer matching the
  `corpus_revision` frontmatter of the cited document.

### Percentile + absolute pairing (binding)

Every cited boundary MUST appear as **both** a percentile-of-corpus
**AND** the absolute-number-at-that-percentile (e.g. p90 = 7), paired
together; citing either form alone is a contract violation.

### Refresh portability (binding)

Citation valid at `corpus_revision = N` and `N + 1` (supported window of
two revisions per `DEFAULT_SUPPORTED_WINDOW` at
`src/gzkit/complexity/citation.py`); out of date at `N + 2`. The
link-integrity validator (`gz validate --complexity-doctrine-links`,
OBPI-0.0.27-07) flags but does NOT auto-rewrite.

> See [`docs/governance/complexity/complexity-doctrine-rationale.md`](../../docs/governance/complexity/complexity-doctrine-rationale.md) for selection criteria extended rationale, project-doctrine fitness worked example, citation pairing details, and refresh portability.

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

<!-- rule-version: 0.4.0 -->

# Complexity Thresholds (gzkit)

> **Rule version:** `0.4.0` — GHI #469: corrected `> See [...]` pointer paths from file-relative `../../docs/...` to repo-root-relative `docs/...` so `gz validate --pointer-anchors` resolves them correctly (ADR-0.0.33 Invariant 3).

## Data source-of-truth

The runtime threshold data lives in [`complexity-thresholds.json`](complexity-thresholds.json), a sibling of this file under `.gzkit/rules/`. The Pydantic loader (`gzkit.complexity.thresholds.load_threshold_table`) reads JSON; the JSON Schema mirror is at `src/gzkit/schemas/complexity_thresholds.json`. This narrative file carries doctrine prose (invariant, vocabulary, bootstrap carve-out, amendment protocol) and binds to the data via the shared identifier `complexity-thresholds`.

## Citation

The data file binds to the corpus-measured boundaries in
[`docs/governance/complexity/distilled-characteristics-2026-05-04.md`](../../docs/governance/complexity/distilled-characteristics-2026-05-04.md)
at `corpus_revision: 1`. Canonical-string form:

```
docs/governance/complexity/distilled-characteristics-2026-05-04.md § radon-cc (corpus revision 1)
```

> See [`docs/governance/complexity/complexity-thresholds-rationale.md`](../../docs/governance/complexity/complexity-thresholds-rationale.md) for citation contract details, bootstrap carve-out rationale, amendment protocol, refresh portability, and anti-patterns.

## Invariant

**gzkit publishes one canonical threshold table whose every entry is a
`(metric, percentile-band, absolute-number, trigger-semantic)` tuple cited
from the current distilled-characteristics document.** The trigger-semantic
vocabulary is fixed at three values (`block` / `warn` / `advise`); the
mapping per metric per band is operator-amendable doctrine. Downstream
surfaces — xenon-as-gate, the complexity advisor (ADR-0.0.29), and the
authoring-time guidance surface (ADR-0.0.30) — consume the table; none of
them owns its own thresholds. A new threshold authority appearing
anywhere else is doctrine drift by another name.

Every metric MUST carry a `block` band; a metric without a `block` band
is prose, not a threshold. `warn` and `advise` bands are optional but
recommended for full coverage.

## Trigger-Semantic Vocabulary (binding)

Exactly three values are accepted by the schema. The vocabulary is
foundation doctrine; amendments require ADR-0.0.28 ceremony, not a rule
body edit.

| Value | Effect on downstream consumer surfaces |
|-------|----------------------------------------|
| `block` | The metric crossing this band fails the gate. Xenon-as-gate exits 3; the build does not pass. |
| `warn` | The metric crossing this band surfaces an advisor recommendation (ADR-0.0.29). The build proceeds; the advisor diagnosis lands in the developer's session. |
| `advise` | The metric crossing this band feeds the authoring-guidance surface only (ADR-0.0.30). No advisor invocation; no build effect. |

A fourth value (e.g. `info`, `fatal`, `debug`) is forbidden — adding a
state with no consumer surface is the foundation-doctrine version of dead
code (ADR-0.0.28 § Alternative #5).

## Per-metric thresholds — see the data file

The per-metric `(corpus_percentile, absolute_number, trigger_semantic)`
rows previously rendered as markdown tables in this file now live in
[`complexity-thresholds.json`](complexity-thresholds.json) as the
runtime source of truth. The data file declares twelve canonical
metrics covered by the gzkit complexity-doctrine cluster:

- `radon_cc`, `radon_mi`, `radon_hal_volume`, `radon_hal_difficulty`,
  `radon_hal_effort`, `radon_raw_nloc`, `radon_raw_lloc`
- `lizard_nloc`, `lizard_param_count`, `lizard_nesting_depth`,
  `lizard_ccn`
- `cohesion_lcom4`

Each metric must declare at least a `block` band; the loader fails
closed when a canonical metric is missing a block-band row. Three
metrics carry bootstrap absolutes per the carve-out below.

## Bootstrap absolutes (REQ-11 carve-out -- one-shot)

Three metrics in the data file carry bootstrap absolutes not derived
from the cited corpus distillation:

- `radon_mi` -- inverted polarity (GHI #405)
- `lizard_nesting_depth` -- parser defect, all-zero corpus (GHI #404)
- `cohesion_lcom4` -- parser defect, all-zero corpus (GHI #404)

> See [rationale doc](docs/governance/complexity/complexity-thresholds-rationale.md#bootstrap-absolutes-req-11-carve-out----one-shot) for the full carve-out contract and one-shot semantics.

## Operator-amendable mapping protocol

Amendments to `(metric, band, trigger)` mappings flow through the doctrine-amendment-protocol stub (ADR-0.0.27 OBPI-02). **Silent edits are forbidden** by the validator (OBPI-0.0.28-03 -- `gz validate --complexity-thresholds`).

> See [rationale doc](docs/governance/complexity/complexity-thresholds-rationale.md#operator-amendable-mapping-protocol) for the full amendment protocol.
