Skip to main content
Documentation menu

Prefix: CQV- Catalog: v1.1 deltas (additive to v1.0 Code Quality & Validation). What it measures: whether automated checks that run before tests still hold when the subject is a product portfolio — one shared quality config, one import graph, and one forbidden-pattern ratchet — instead of a pile of per-application forks.

v1.0 already covers linters, formatters, strict types, pre-commit hooks, escape hatches, structured logging in production paths, import order, and complexity gates. These v1.1 criteria add the portfolio-scale contracts an agent needs once it is changing more than one application in the same product.

Criteria in this pillar

CQV-100 — Shared quality config as a package

  • Level: 3 · Scope: portfolio · Check: deterministic
  • Lint, format, and typecheck configuration live in a versioned shared package (or equivalent workspace library) that every application in the portfolio consumes. Per-application forks are enumerated, justified, and owned.
  • Rationale: when each application copies its own linter config, agents learn a different quality contract on every hop. A shared package makes the contract one artifact an agent can read and one version an assessor can pin.
  • Evidence expected: a published config package (or workspace path) imported by every application; exception list of forks with owner and reason; CI fails an application that silently stops consuming the shared config.

CQV-110 — Exported APIs documented

  • Level: 3 · Scope: application · Check: deterministic
  • Public exports carry language-idiomatic documentation comments (TSDoc, JSDoc, PEP 257, or equivalent). A lint plugin or equivalent gate fails the build when a newly exported symbol has no doc comment.
  • Rationale: agents treat exported signatures as the contract they may call. An undocumented export is an undocumented contract, and the agent will invent a meaning.
  • Evidence expected: lint plugin or type-doc gate configured on exported symbols; CI fails a new undocumented export; existing public API is at or above the documented coverage floor.

CQV-120 — Unused-export and dead-code gate

  • Level: 4 · Scope: application · Check: deterministic
  • CI fails on unused exports, unused files, or unreachable code in production paths. Test fixtures and generated code may be excluded by an explicit, reviewed list.
  • Rationale: dead code is where agents copy the wrong pattern. A gate that deletes or flags unused exports keeps the surface an agent can call equal to the surface the humans intended.
  • Evidence expected: knip, ts-prune, ruff unused, or equivalent configured in CI; at least one threshold that fails the job; exclusion list is committed and reviewed.

CQV-130 — Dependency direction enforced

  • Level: 4 · Scope: portfolio · Check: deterministic
  • Import boundaries are linted: applications may depend on shared packages; shared packages MUST NOT depend on applications; circular package graphs fail CI. Layer rules inside an application (for example UI must not import persistence) are declared in the same config.
  • Rationale: a portfolio without a directed graph is a ball of mud an agent cannot change safely. Direction lint turns "please don't import that" into a machine-checkable invariant.
  • Evidence expected: dependency-cruiser, ESLint no-restricted-imports, Nx module-boundary, or equivalent config in CI; a documented layer map; CI fails a forbidden import.

CQV-140 — Forbidden-pattern ratchet

  • Level: 4 · Scope: portfolio · Check: deterministic
  • A committed allowlist ratchet fails CI when a forbidden pattern (banned APIs, raw design tokens, spec copy that names a commercial vendor, or equivalent) appears outside enumerated exceptions. Adding a hit requires shrinking the allowlist or fixing the call site, not growing silent debt.
  • Rationale: portfolio-wide invariants die when each application is allowed "just this once". A ratchet makes the exception list converge, which is the only way an agent can trust that yesterday's rule still holds tomorrow.
  • Evidence expected: a lint or grep script in CI with a committed allowlist; new hits fail the job; the allowlist is reviewed and does not grow without a tracked exception.