Validation toolchain¶

Validation is layered by authority and dispatched from the resolved Composition component set.

1. .template-composition/validate_composition.py validates the Composition lock and managed/generated material integrity.
2. scripts/validate_contracts.py validates all registered JSON documents/schemas and shared Web foundation contracts plus Webapp surface/application-route/state invariants when artifact.webapp-core is selected.
3. validate_contract_evolution.py validates the generated registry, version histories, and migration inventory when lifecycle.contract-evolution is selected.
4. validate_implementation_evidence.py validates artifact-neutral evidence mechanics when lifecycle.implementation-evidence is selected.
5. scripts/validate_webapp_evidence.py adds Webapp-specific target coverage and browser-proof strength for the shared browser baseline plus Webapp surface, application-route, and state behavior families when artifact.webapp-core is selected.
6. release-execution, release-evidence, and release-bundle validation is selected only when those lifecycle components are present in the lock.

.template-composition/validate.py is the self-contained consumer entrypoint for these layers. It runs Composition-state validation first, reads resolved_components from the validated lock, and dispatches only validators registered for those selected components. The managed validation registry and every invoked validator entrypoint are themselves lock-bound Composition materials. Merely finding a release contract or validator file in the repository does not activate release validation.

Before switching implementation evidence to product mode, python scripts/scaffold_webapp_evidence.py emits a deterministic non-canonical worklist for every current Webapp behavior evidence target. It writes only to standard output and does not modify contracts/implementation-evidence.json. This separation is intentional: template mode makes no product requirement claim; planning mode stores the stable requirement ledger before implementation records exist; product mode activates the implementation/evidence graph. Capture explicit caller-visible requirements in planning mode before coding, preserve those IDs, then fill generated record skeletons with concrete implementation locators, proof metadata, commands, and release gates when moving to product mode.

Current Webapp behavior evidence coverage is about the product that exists now: shared browser-identity proof target plus every declared surface, application-route behavior, UI state, viewport, and input capability requires a record. Browser identity requires browser-backed executable proof that the standard favicon link is emitted and the declared asset is observed; the contract declaration by itself is not implementation proof. In planning mode, browser-sensitive targets must be bound into the requirement ledger with browser-level proof intent. In product mode, browser-sensitive targets require positive and negative browser-level proof backed by an authoritative command whose execution capabilities include browser. Provider contract-version history is not a fresh product implementation obligation. A product may additionally record a contract-transition when it actually needs migration evidence; scripts/validate_webapp_evidence.py accepts only transitions registered by the current behavior-domain contract manifest, while generic implementation-evidence validation verifies the referenced transition exists. The scaffold therefore does not generate historical transition records merely because the Provider evolved before the product was created.

The scaffold and scripts/validate_webapp_evidence.py share scripts/webapp_evidence_targets.py, so target derivation has one Webapp-specific implementation rather than duplicated generator and validator rules. PWA installability, application-icon, offline/freshness, and update proof families remain separately owned by capability.pwa; selecting that capability adds its own validator rather than extending the generic implementation-evidence schema.

Browser proof prerequisites are diagnosed separately from proof validation. scripts/browser_prerequisite_diagnostics.py classifies caller-observed browser binary, WebDriver, browser/driver compatibility, and localhost-sandbox states without probing or weakening evidence requirements itself. When a canonical deferred proof references an authoritative command whose execution capabilities include browser, the lifecycle projection may expose Webapp's managed diagnose-browser-prerequisites action. Its exact argv is declared in .template-composition/webapp-actions.json; callers replace only the declared observation placeholders, while the provider dispatcher owns diagnostic flags, ordering, implementation path, and structured output. This diagnostic never converts a deferred browser proof into verified evidence by itself.

The supplied managed GitHub Actions workflow sets up Python and then invokes python .template-composition/validate.py .. The runner self-provisions and reuses the isolated validation runtime from the exact dependency set carried by the managed Composition validation registry. This keeps CI on the same selected-component-aware path used by consumer validation without maintaining a second handwritten validator sequence or dependency-install step in workflow YAML.

Product-mode release evidence and release bundles are different: their semantics are intentionally bound to one exact product candidate revision. Ordinary repository validation reports those checks as deferred rather than guessing a revision from file existence or a GitHub event SHA. A product-owned release operation must run the release-evidence and release-bundle validators with --expected-revision <candidate-sha> after selecting the exact candidate revision.

Validation runtime requirements are carried inside the lock-bound managed validation registry. The isolated validation environment is cached outside the product repository, so Composition does not select or modify the product runtime, dependency manifest, or package manager merely to validate the repository.