Quality Gates & Enforcement (CRAIG)

Every String / Option<String> / Vec<String> field on a deserialize-side DTO (request body, query string) carries a [garde(length(max = <CONST>))] cap plus a mirrored [schema(max_length = <literal>)] (or #[param(max_length = <literal>)] on IntoParams structs). The 13 canonical cap constants live in craig-validation:

utoipa literal requirement. utoipa 5.4’s [schema(max_length = …​)] and [param(max_length = …​)] macros reject const-ident expressions — they require integer literals. The garde side stays canonical ([garde(length(max = NAME_MAX))]); the utoipa side mirrors the literal ([schema(max_length = 100)]). This dup is intentional and bounded; a future garde/utoipa cap-sync xtask lint will guard the pair.

Special-cases. Use the named constant unless concrete evidence (DB column ceiling, RFC reference, real-world data) demands a different cap. When deviating, use a literal and add a // #486 special-case: <reason> comment immediately above the attribute pair. CreateCourtOrderRequest.court_name / UpdateCourtOrderRequest.court_name use literal 200 (compound jurisdictional names) — established precedent.

Cousin-field uniformity. Fields with the same semantic role across cousin DTOs (admin_unit on Create/Update for cases / referrals / reports) MUST share one cap — NAME_MAX for admin_unit cousin fields. The MR 5 workflow caught one cousin asymmetry mid-sweep (CreateReportRequest.admin_unit was a survey miss); cousin reviews are part of every per-file sweep.

Handler wiring. Every handler accepting a Validate-derived DTO calls payload.validate()? (or query.validate()?) immediately after the Json/Query extractor and BEFORE the authz check + parent-resource existence checks. The From<garde::Report> for ApiError impl in craig-common::validation converts validation failures into RFC 9457 ApiError::Validation (HTTP 422) with a per-field errors extension. Note: garde 0.22’s Validate::validate(&self) takes NO context arg under Context = () — use body.validate()?, not body.validate(&())?.

Scope as of MR 1-6 (2026-05-29): all 72 String fields in craig-cases-contracts are length-capped. craig-exchange-contracts surveyed in MR 6 contains zero unbounded String DTOs (the crate’s surface is the ExchangeAdapter trait + ExchangeAdapterKind enum; no request/response DTOs). Inline service api/ DTOs (210 fields across 4 stateful services) + partner-* crates (147 fields) + craig-intake-sdk (52 fields) are tracked as a separate follow-up — they fall outside #486’s craig-*-contracts scope and warrant their own audit ticket.

Partner-crate scope (#1461, 2026-08-15): the cargo xtask lints dto-length walk derives its partner-crate list from a crates/craig-partner-* directory glob — every partner crate present AND every future one is lint-covered automatically (the earlier hardcoded list silently omitted four crates: cprs / stars / doe-slds, whose 41 unbounded fields were annotated when the glob closed the gap, and audit, which carries no DTO structs). A unit test pins the glob against the live crates/ listing, and an unreadable crates/ fails the lint loudly rather than passing it vacuously.

Cargo.toml’s `[workspace.lints.clippy] table turns the §Style + §Errors rules above into mechanically-enforced compiler errors. Member crates inherit via [lints] workspace = true. Today’s set (post-Plan-M Tier 1 + Tier 2, 2026-06-05):

All deny at workspace level. Test-only suppression for the panicking-call + silent-discard + Plan M Step 7/8/9 lints is scoped via #![cfg_attr(test, allow(…​))] on each lib/main root, leaving production code deny-enforced. xtask validate runs clippy with -D warnings for defense-in-depth.

Nine code-quality budgets (B1–B8, with B3 split into B3a/B3b) are tracked by cargo xtask quality-budgets, locked at xtask/quality-budgets.lock, and enforced as a blocking gate at the xtask validate quality-budgets step (pre-push battery) + .gitlab-ci.yml ci-tests job. A budget regression — actual > ceiling, where ceiling is the lock when set (else the threshold; see § Semantic note) — blocks merge.

B8 — duplicate-block budget (copy-paste DRY class, 889). Counts near-duplicate impl/fn bodies in production /src/: each non-test body ≥ 40 normalized tokens is reduced to a structural signature (identifiers + literals erased; control-flow keywords, punctuation, and nesting kept), and the metric is the redundant-copy count — for each group of ≥ 2 identical signatures, group_size − 1. Coarse by design: it caps the *size of the copy-paste class, it does not localize it. Seeded at the current count and shrink-only — a B8 regression is fixed by a real refactor (dedup into a shared helper), never** an autonomous lock-raise. It creates downward pressure on the partner-adapter / CLI-wrapper / registry families the 2026-06-28 prevention-gap analysis flagged. Test modules ([cfg(test)]) and tests/ dirs are excluded so volatile test boilerplate can’t flap a merge-blocking gate.

B6 — redundant dep installs is host-independent (#991, 2026-08-04). The count is parsed from Cargo.lock — total entries minus distinct names (Σ per-name N−1) — NOT from cargo tree, whose default --target filter is the host triple and made the count OS-dependent (a Windows dev box counted the windows- stack a Linux host never saw, tripping the blocking gate on a clean main; ADR-007 names Windows a supported dev platform). The metric definition is therefore *all-targets: the lockfile’s resolved set for every platform, identical text on every host. The re-seed moved the lock 65→59 — lower, because the old tree-output scrape double-counted repeated (name, version) lines across tree sections, so the switch is also a correctness fix for the stated N−1 semantic. A fixture-lockfile unit test pins the parse (b6_counts_redundant_versions_from_a_fixed_lockfile), so host sensitivity cannot silently return.

cargo xtask lints fn-name-and is enforced as a blocking gate at xtask validate step fn-name-and (pre-push battery) + .gitlab-ci.yml ci-tests job. The lint scans every production fn name in crates/, services/, tools/, xtask/ (excluding tests/ directories and #[cfg(test)] modules, plus target/) for and outside the operand-pattern allowlist (and_or / _and_one / _and_two / _and_three / _and_n / _and_back / _and_friends). Drift in either direction blocks merge: new violations not on the opt-out list, OR stale opt-out entries whose fn has been renamed/decomposed/removed.

This gate is a proxy, not a cohesion proof. It catches only the and naming tell — it cannot catch a single-noun-but-multi-purpose function, e.g. a process_record that secretly validates, persists, AND emits an event. A green gate does not establish that a function does one thing; that remains a human-review concern (the J6 cohesion question in the pre-commit protocol), with the workspace clippy::cognitive_complexity = "deny" lint as a partial multi-branch backstop.

cargo xtask axis-coverage is enforced as a blocking gate at xtask validate step axis-coverage (pre-push battery) + .gitlab-ci.yml ci-tests job — one of the blocking code-quality gates alongside quality-budgets, fn-name-and, and the boundary lints (route-role-coverage, no-transitional-allows, mq-topology, …; each has its own section on this page). It guarantees every integration test declares which behavioral axis it exercises, so the test corpus can’t silently accrete happy-path-only cases.

Every [test] / [tokio::test] in an integration file must be tagged with a // @axis: <X> comment on one of the lines immediately above the test attribute (or end its fn name in _happy / _sad / _evil), where <X> is exactly one of six tokens:

chaos is not a valid token. A test under one of the legacy directory conventions (tests/{concurrency,recovery,fault,security}/) inherits its axis from the directory and needs no inline tag.

cargo xtask invariants runs the zero-rows SQL catalog under crates/craig-test-lib/sql/invariants/<service>/.sql (each file is a SELECT that MUST return zero rows; non-zero rows are a violation) against the seeded + test-exercised devstack DBs. Since #860 it is *wired into the pre-push battery at the xtask validate invariants step (invariants::run_gate), immediately after the integration suite has exercised the DBs. CI is force-merged, so this blocking gate lives in pre-push, not CI.

Curated blocking subset. Only invariant NAMES in BLOCKING_INVARIANTS (in xtask/src/cmd/invariants.rs) fail the gate; every other catalogued invariant is report-only (printed, non-failing). The blocking set holds only invariants that are green by construction against a fresh devstack:

Report-only invariants include grace-window/timing checks (retried_never_reterminal, stuck_pending_transactions) and invariants tracking still-open fixes (validated_with_errors → #782, null_rule_output → #785) — a known-open defect must not red-gate the battery. Promote a report-only invariant into BLOCKING_INVARIANTS only once its fix has landed and it is green against a fresh devstack. Preview the gate outcome manually with cargo xtask invariants --gate; a full non-gated report is cargo xtask invariants. The financial↔placement cross-DB "void every payment on an ended placement" invariant (#776) is not expressible in this single-DB sweeper and is covered by integration tests instead.

cargo xtask verify-seed --expect {keyless,keyed} verifies the devstack seed’s field-encryption state against the mode the caller asserts (never auto-detected — an auto gate would pass a silent key-mount failure vacuously). It re-checks the craig-seed one-shot completed (a state-aware poll, not the old exit-code-only read that misclassified a still-running container; when the exited container has been pruned — routine docker container prune housekeeping — the durable _seed_marker sql-phase row the seed transaction committed stands in as the completion evidence, #1420) and asserts, on the raw craig_cases DB, that every covered column and crypto_key_lineage.kcv matches the expected mode. It is wired into the pre-push battery at the xtask validate devstack phase (--expect keyed, before the mutating integration suite) and, non-blocking, into the .gitlab-ci.yml pentest job (allow_failure, main/schedule). Both call sites assert --expect keyed since C7 (#987) activated devstack encryption; the CI side receives the key from the repo-committed encrypted store, decrypted by devstack/ci/write-field-key.sh with the masked+protected CRAIG_CI_AGE_KEY identity in the pinned devtools container (ADR-048 §D5 as amended by ADR-064 U7, #1385 — an unset variable is a hard error, never a keyless CI devstack). Run manually against a running devstack with cargo xtask verify-seed --expect keyed (add CRAIG_CASES__DATABASE_URL=… to skip port reconciliation).

Agent context lives in tiers, each pointing DOWN to the next when it doesn’t answer a question:

The failure this guards against (the #613 right-sizing): a doc re-grows into a catalog that duplicates Antora and drifts stale. The gates target the structure that lets facts go stale, not the facts themselves (undecidable):

The doc-pointer-integrity gate keeps CLAUDE.md’s pointers valid so the canonical detail stays in Antora (near the source it describes) where it can’t rot in a second place. (Before the 2026-06 template resync this tier also held .claude/docs/ thin-index docs guarded by a B8 agent-doc-index size budget; that layer was retired when conventions moved to .claude/rules/ + the standards module and the project docs moved into Antora ROOT.) See the delivery-protocol standard § Context Hygiene for the upstream policy.

Wired at the cargo xtask validate tracing-pii-fields step (blocking, phase_code_security_lints). A single tracing field interpolating a child’s name/DOB/address/SSN/phone/email is a reportable PII incident for a CCWIS. The 2026-08-24 three-agent sweep (cases 26 sites / financial+placement 61 / intake 38 + fleet census 556) found ONE real finding — intake’s redact_upstream_error logging the full raw upstream body at WARN (SHINES/cases 4xx bodies can echo submitted SSNs/names) — plus two contingent raw-value echoes in the NCANDS export warns; all fixed with shape-only logging (length + SHA-256 prefix). This gate keeps the fleet clean:

Implementation: xtask/src/cmd/lints.rs::run_tracing_pii_fields + tracing_pii_tests.

Two gates wired at cargo xtask validate (blocking, phase_code_security_lints):

Serialize-credentials (cargo xtask lints serialize-credentials) — a heuristic tripwire over the wire-name surface, and its doc says so. Named fields of Serialize-deriving structs AND enum variants (derives seen through cfg_attr) whose ident or serde(rename) wire name contains secret | password | token | api_key | auth_config | signing_key | client_secret | private_key | credential | bearer | verifier | nonce must either #[serde(skip_serializing)] or carry a per-field // serialize-credential: <reason> marker on the line DIRECTLY above (per-field, never per-struct; stale markers fail; empty reasons fail). The 17 seed markers across 10 files are the auditable inventory of every place credential-shaped material intentionally serializes (sweep tokens, idempotency occurrence tokens, the CLI/test-lib token caches, the encrypted WebSession cookie, PkceState’s PKCE verifier + OIDC nonce, the one-time `IssueKeyResponse.api_key, the hash-only PartnerIntentV1.auth_config). Test-only items are excluded by cfg predicate; craig-test-lib is deliberately NOT path-exempt here. Recorded false-negatives: flatten chains, manual impl Serialize, non-use aliasing.

Store-model response baseline (cargo xtask lints store-model-baseline) — a COARSE TEXTUAL per-file ratchet over handlers returning store models directly: xtask/store-model-responses.toml maps each services/*/src file to its count of lines containing both Json< and store::models:: (48 files / 153 sites at seed). Any file above its count — or any new file above zero — fails and is NEVER blessable; below is stale and --bless rewrites DOWNWARD only. The claim is exactly "no per-file growth of the textual pattern": aliased imports and multiline generics under-/over-count, same-file swaps are the recorded residue, and the empty [counts] table is the desired end state.

Wired at the cargo xtask validate advisory-ignore-audit step (blocking, phase_doc_lints; pure file parse, no subprocess). cargo-deny/cargo-audit (pre-push hook + CI) remain the advisory-DB layer — a Cargo.lock "liveness" check was reviewed and REJECTED as unsound (a crate name persists in the lock after upgrading past an advisory). The gate enforces the structural contract they cannot:

The record parser is hand-rolled over the raw array region (TOML parsing discards comments) and proptested: totality over line soup, generated well-formed records accepted, any dropped marker rejected. CI hygiene shipped with the gate: the cargo-audit job’s rules:changes now watches deny.toml + .cargo/audit.toml, so a config-only MR re-runs the advisory scan. Implementation: xtask/src/cmd/lints.rs::run_advisory_ignore_audit + advisory_ignore_audit_tests.

Wired at the cargo xtask validate parse-prop-coverage step (blocking, phase_code_security_lints). Three layers, each closing a gaming vector the wave-1 review proved against weaker designs:

The #1575 second census layer covers the erased AUDIT-decode seam the adapter census misses: every partner crate’s src/lib.rs must expose a PUBLIC audit_payload_from_value free fn (dispatch crate: PartnerAuditEvent::decode_jsonb), each needing a compiled proptest! whose tokens call the fn BY NAME — the call sites are type-inferred (serde_json::from_value, no turbofish), so the signature-anchored fn name is the only reliable token. Seed floor 12 (11 per-partner fns + decode_jsonb); same reachability rule; the totality properties live in each crate’s tests/parse_never_panics.rs (arb-JSON documents; ssa-solq’s pre-existing property is string-shaped — same totality tier, same token).

Escape hatch: // allow-no-parse-prop: <reason> on the line above the anchoring declaration (the type Inbound, or the audit-decode fn signature) — the reason MUST cite a #NNN issue. The properties execute in the pre-push full battery — the sole functional-correctness gate; CI’s ci-tests job runs the --lib --bins subset, which never compiles tests/ targets, and its prose says so (#1577 corrected the claim; the selection deliberately stays). Implementation: xtask/src/cmd/lints.rs::run_parse_prop_coverage + parse_prop_coverage_tests.

Wired at the cargo xtask validate workspace-dep-inheritance step (blocking, phase_doc_lints — pure TOML, no compile). Membership authority is the workspace itself: [workspace].members minus .exclude, expanded from the root manifest (never fixed directory lists), with a 66-member seed floor. Three checks over dependencies/dev-dependencies/build-dependencies and every [target.*] variant:

Seed state: 66 members, ~1,210 dependency declarations, 0 violations, 3 exceptions (rules-client/xtask reqwest feature-subtraction, intake-sdk tokio leaf-slimming; the craig-web rand-divergence entry retired with the #1574 migration). Implementation: xtask/src/cmd/lints.rs::run_workspace_dep_inheritance + workspace_dep_inheritance_tests.

Wired at the cargo xtask validate reqwest-client-new step (blocking). #866 (epic &63) rebuilt the #771 line scanner as a syn visitor over the workspace-member source surface (membership from [workspace].members minus .exclude — tools/ and plugins/ included):

Implementation: xtask/src/cmd/lints.rs::{scan_reqwest_constructions, reconcile_builder_allowlist} + the reqwest_construction_tests module.

Every .route(…​) inside the protected_routes block in services/craig-web/src/main.rs MUST carry one of:

Without one of these markers, cargo xtask lints route-role-coverage (wired into xtask validate) bails the build. A new route added under protected_routes without an explicit gate or carve-out is a violation — the lint exists so the caseworker+ default cannot silently absorb a higher-privilege handler.

The carve-out marker may live on the .route( opening line OR on any line inside the call (rustfmt sometimes wraps the comment inside the parens — both placements are equivalent for the lint). For multi-line routes the canonical placement is on a line immediately below the .route( opener.

Background: this lint is the build-time guarantee that #476’s per-route role gates can’t be silently bypassed by a future contributor. See ADR-027 for the underlying role model.

cargo xtask lints mq-topology is a blocking xtask validate step (epic &75 C4, ADR-003 §Amendment #1198). Raw AMQP queue/exchange declaration tokens are allowed only in crates/craig-mq/src/, crates/craig-test-lib/src/, or test paths (tests/ at the repo root or any nested /tests/ directory) — a declaration anywhere else would bypass the queue_args choke-point that pins every CRAIG queue x-queue-type=classic, silently falling to the broker/vhost default queue type.

Honest scope: this is a crate-boundary convention gate. It does not prove in-boundary declarations carry the right arguments — that guarantee is queue_args + its full-table equality unit pins inside craig-mq. The scan is uniform-by-token (comments and string literals count — the sibling lints' bluntness trade), enumerates tracked *.rs only, and its two needles exist in xtask source only in split-literal form: an own-source unit test turns red if a contiguous token ever lands in lints.rs. Recorded residuals: declarations made through the RabbitMQ management HTTP API and non-Rust code are out of scope.

Remedy when it fires: declare queues through craig_mq::Subscriber (subscribe/ subscribe_exclusive/subscribe_dlq); exchanges are operator-owned topology (#1202) and are never declared from service code; test-support declares belong in craig-test-lib (declare_core_exchanges) or a tests/ path.

Blocking xtask validate step (and in CI via ci-tests, whose path rules include .sops.yaml + secrets/** so a store-only rotation MR still runs it): the repo-committed encrypted secrets store must stay structurally sound. Enforced: strict .sops.yaml grammar (exactly creation_rules with compiling path_regex + canonical-bech32 age recipients, plus a parser-differential tripwire — the lint’s YAML view and the store tooling’s own recipient parser must agree or the gate fails closed); encrypted-only ciphertext (every leaf ENC[AES256_GCM,…], diagnostics name keys only — never values); .sops.yaml↔ciphertext recipient parity; a split-form age secret-key needle over both surfaces; and NO non-YAML artifacts under secrets/ (the walk is filesystem-side, so untracked decrypt residue fails). Armed from day one — a missing store is itself a violation (partial-revert guard).

Remedy when it fires: recipient changes go through cargo xtask secrets add-recipient / remove-recipient, store edits through cargo xtask secrets edit; never hand-edit either surface. Run cargo xtask lints sops-policy for the full list, cargo xtask secrets check for the non-disclosing store verification.

Blocking xtask validate step (cargo xtask release-artifact-gate, folded into the pre-push battery): the contested-environment fault-injection seams (craig-mq/fault-injection, craig-crypto/fault-injection, craig-store/test-util) add hook fields to real production structs but MUST stay out of every release artifact. They ship default-off and activate ONLY through dev-dependencies (a crate’s own integration tests self-dev-dep with the feature; cross-crate consumers dev-dep craig-test-lib with its fault-injection forwarding feature). The gate walks cargo tree -e normal,build (normal + build deps only — dev-deps excluded) over the Dockerfile’s release -p service set (parsed from the cargo build line, the single source of truth) AND xtask, and fails if any forbidden (crate, feature) pair is active. Honest claim (ADR-067 §D4): "absent from release artifacts and every normal-dependency graph, machine-enforced" — NOT "impossible" (the seams compile under --all-features, by design).

Remedy when it fires: a normal (non-dev) dependency enabled a host crate’s fault feature — make that edge a dev-dependency, or drop the feature from it. Run cargo xtask release-artifact-gate for the offending (crate, feature) pairs.

Two blocking xtask validate steps that BRACKET the integration battery, plus the standalone cargo xtask program-gate:

The fault layer is REQUIRED for the same battery (fault-preflight --required), so a run cannot go green with the fault sidecar absent. validate --skip-devstack never reaches either step (its substitute battery is --lib --bins) and is the one sanctioned fault-optional mode.

Remedy when it fires:

Honest limits, recorded in the module doc and the runbook rather than implied away: the per-class floor is enforced only for the classes that emit records today (#1546), the armed⇒fired check is only as sharp as the recorders that observe firing (#1547), and the self-test check pins EXISTENCE, not behavior.

AI agents trend toward recommending older, heavily-documented tools over newer, better alternatives. When making architectural recommendations, always perform web research for current state of the art (see the delivery-protocol standard). Known stale defaults to watch for:

This list is a living document. When you catch an outdated recommendation, add it here.