Pillar — Code Quality & Validation

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.

v1.0 Code Quality & Validation — the published CQV-010 through CQV-090 criteria.
v1.1 pillars — draft catalog, including these deltas and the six new pillar stubs.
v1.0 specification — the published standard.

Criteria in this pillar

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.

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.

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.

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.

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.