clean-architecture-backend-template/docs/superpowers/specs/2026-08-02-p2-verification-governance-refactoring-design.md

P2 Verification Governance Refactoring Design

Goal

Remove the remaining fail-open verification paths without changing production behavior or adding unadopted runtime capabilities. P2 strengthens qualification tasks, tracked contract resources, CI parser evidence, JSON Schema conformance, registry ownership, and bounded documentation debt.

Scope and sequence

1. Move strict qualification Test registration to each owner leaf through one shared convention.
2. Resolve tracked repository contract resources from an explicit repository root and fail when tracked files or directories are absent.
3. Exercise the real gate-matrix shell validator through isolated mutation fixtures.
4. Validate every Redis program manifest with the committed Draft 2020-12 schema.
5. Make the tracked registry set explicit, resolve every required_test identifier, and govern temporary runbook stubs with owners and expiry dates.
6. Apply bounded P2 cleanup: module-doc link coverage, migration-neutral gate labels, and deterministic outbound HTTP timeout tests.

Each item is independently reviewable. A later item may reuse infrastructure from an earlier item, but no batch may weaken an existing check while waiting for a subsequent batch.

Qualification convention

The owner project applies gradle/strict-qualification-test.gradle and registers its own exact qualification tasks. The root project only aggregates absolute task paths and validates resulting JUnit XML.

Every strict qualification task must:

• name at least one required FQCN;
• depend on compilation and fail before test execution when any required class file is absent;
• use exact JUnit filters with no-match and no-discovery failures enabled;
• force fresh execution in UTC and emit JUnit XML;
• reject skipped tests and require a positive, failure-free XML count.

This applies to conditional transports, Messaging evidence lanes, object-storage release lanes, the Poster migration lane, and the app-bootstrap conditional-composition proof. Ordinary optional or quarantine tests are deliberately excluded.

Repository contract resources

app-bootstrap injects ca.repository.root into contract tests. A package-private resolver normalizes the root, rejects traversal, and exposes requireTrackedFile and requireTrackedDirectory. Missing tracked resources are assertion failures, never assumptions. Assumptions remain valid only for truly optional external infrastructure.

CI parser evidence

The gate-matrix validator accepts an optional repository-root argument. Contract tests construct a minimal temporary repository fixture and invoke the actual shell script. Mutations for deceptive step names, execution-suppressing flags, missing or duplicated gates, and unregistered tasks must produce non-zero exits with stable diagnostics. Java must not contain a second parser.

Schema and registry governance

• Redis manifests are validated by a Draft 2020-12 implementation in addition to existing catalog cross-checks.
• A registry catalog has an exact one-to-one relationship with tracked docs/registries/*.yaml.
• Stable required_test IDs resolve through a tracked catalog to a single owner Gradle path and source test/method. Unknown, duplicate, and dangling mappings fail.
• Temporary runbook stubs are listed in tracked debt data with owner, issue, start, and sunset. Missing or expired debt entries fail.

Non-goals

• No GraphQL feature schema, cost/depth policy, gRPC TLS/streaming, WebSocket relay, or other production capability is introduced.
• No lockfile consolidation, version-catalog migration, JVM test-suite migration, or broad module boundary change is included.
• Root Gradle capability extraction and a typed settings/build registry model remain separate refactors unless their benefit can be proven without expanding this verification change.

Verification

Each batch starts with a focused failing contract and finishes with its owner check. Final verification runs root test, check, architecture/dependency/runtime membership gates, CI shell validators, dependency locks, public-path/env gates, and git diff --check.