gz complexity advise¶

Trigger-time complexity advisor diagnosis for files and directories.

NAME¶

gz complexity advise — analyze a file or directory for complexity-band crossings and emit a doctrinal diagnosis (archetype, authority, proof range, recommended move) for each crossing.

SYNOPSIS¶

Text Only

gz complexity advise <path> [--json] [--quiet] [--verbose] [--dry-run]
                            [--auto-chain] [--rule-path PATH]
                            [--attest-intrinsic --reason REASON --attestor NAME]

DESCRIPTION¶

gz complexity advise is the operator-facing trigger-time response surface introduced by ADR-0.0.29 (the third foundation in the four-ADR complexity-doctrine cluster). The verb loads the canonical threshold table at .gzkit/rules/complexity-thresholds.json (ADR-0.0.28), measures per-function radon_cc for every Python file under <path> via radon's Python API (radon.complexity.cc_visit), and runs the OBPI-0.0.29-02 :class:DiagnosisEngine against each band crossing.

For every crossing, the engine emits an AdvisorDiagnosis carrying:

the canonical refactor archetype (one of ten enumerated values per ADR-0.0.29 § Decision rationale #2),
the cited doctrinal authority (Fowler / Martin / Page-Jones / Constantine — the four-authority canon ADR-0.0.27 binds),
a non-empty proof tuple linking to the responsible AST nodes / line ranges (verdict ↔ proof binding per ADR-0.0.29 § Decision rationale #5),
the recommended-move excerpt sourced from the active distilled-characteristics document (never fabricated).

Default output is structured human-readable prose; --json mode emits the canonical Pydantic serialization as a JSON array. --auto-chain selects the condensed commit-time presentation used for a trigger-fired run.

OPTIONS¶

<path> — File or directory to analyze. Directories are walked recursively for *.py files; non-Python files are skipped.
--json — Emit the diagnosis list as a JSON array (one AdvisorDiagnosis object per crossing). Validates against src/gzkit/schemas/advisor_diagnosis.json.
--quiet — Errors only; no progress output.
--verbose — Debug output (per-file analysis trace).
--dry-run — Reserved; analysis is read-only and dry-run is a no-op.
--auto-chain — Condensed commit-time presentation for a trigger-fired run. The OBPI-0.0.29-05 pre-commit hook runs the advisor in its own process and does not pass this flag.
--rule-path PATH — Override the threshold rule path. Default is .gzkit/rules/complexity-thresholds.json. Test injection only; production runs use the default.
--attest-intrinsic — Commit-time intrinsic attestation path. Requires <path> in <file_path>:<qualname> form. Checks that the named function crosses a threshold band, then requires TTY + ATTEST confirmation before emitting one intrinsic-complexity-attestation ledger event. Headless invocations are refused (exit 1).
--reason REASON — Human-readable rationale for the intrinsic attestation (required with --attest-intrinsic).
--attestor NAME — Attestor handle, never a real name (required with --attest-intrinsic). Defaults to authorship.attestor_handle in .gzkit.json when set (GHI #1036).
--help, -h — Show usage and exit 0.

EXIT CODES¶

Code	Meaning
0	Success — no crossings, or all crossings stayed at advise/warn band
1	User / config error (bad path, malformed flags)
2	System / IO error (missing threshold table, AST parse failure, engine cannot resolve cited distilled-characteristics)
3	Policy breach — one or more `block`-band crossings

EXAMPLES¶

Bash

gz complexity advise src/gzkit/commands/validate.py
gz complexity advise src/gzkit/ --json
gz complexity advise tests/ --quiet
gz complexity advise src/gzkit/commands/engine.py:QueryOptimizer.plan \
    --attest-intrinsic \
    --reason "Irreducibly complex state-machine optimizer; CC=24 is the floor" \
    --attestor "g0"