---
applyTo: "docs/governance/complexity/**, data/exemplar_corpus.json, src/gzkit/complexity/**, .gzkit/rules/complexity-doctrine.md"
---
<!-- 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.
