prometeu-runtime/discussion/workflow/plans/PLN-0037-runtime-edge-coverage-governance-foundation.md

id	ticket	title	status	created	completed	tags
PLN-0037	runtime-edge-test-plan	Plan - Runtime Edge Coverage Governance Foundation	done	2026-04-20	2026-04-20	tests coverage governance ci

Briefing

This plan operationalizes the governance layer of DEC-0020. Its goal is to turn the decision into concrete review and CI mechanics without changing the underlying coverage toolchain.

Decisions de Origem

• DEC-0020

Alvo

Define the repository-level mechanics for:

• domain coverage gate enforcement in CI;
• domain-scoped coverage evidence during review;
• baseline tracking that can start at 0 per domain and tighten later;
• reviewer-visible rules for when domain tests are mandatory.

Escopo

• Add repository commands or scripts for domain-oriented coverage evidence collection.
• Add repository-facing documentation that explains the domain gate plus domain evidence workflow.
• Align CI/coverage outputs with the new governance model without replacing llvm-cov.

Fora de Escopo

• Expanding firmware tests.
• Refactoring the monolithic runtime suite.
• Introducing hard domain coverage percentages above baseline 0.
• Replacing Jenkins or cargo llvm-cov.

Plano de Execucao

Step 1 - Define the domain evidence interface

What: Define how contributors and reviewers gather coverage evidence for system/runtime, fs, asset/bank, firmware, and host-dependent.

How: Add one repository-visible command path that produces:

• existing global HTML/XML/JSON coverage artifacts;
• a documented procedure for mapping changed files/modules to one of the canonical domains;
• an initial baseline format that records per-domain coverage starting from 0;
• a CI-friendly command that fails when a domain baseline is not met.

File(s):

• Makefile
• scripts/
• README.md or another repository-facing process document if more appropriate

Step 2 - Add domain evidence helpers

What: Introduce helper commands or scripts that make domain evidence collection reproducible.

How: Prefer simple wrappers over new tooling. For example:

• capture llvm-cov JSON/HTML consistently;
• filter or summarize target files/modules for a domain;
• emit review-friendly evidence artifacts while also enforcing the authoritative domain gate.

File(s):

• Makefile
• scripts/

Step 3 - Document the PR acceptance rule

What: Publish the decision’s review contract in a place visible during development.

How: Document that any PR touching a canonical domain must either:

• update/add tests for that domain; or
• justify why the observable contract did not change.

Document that domain coverage evidence is mandatory review input even when domain thresholds are still at baseline 0. Document that Jenkins consumes the repository helper target directly instead of re-implementing the gate inline.

File(s):

• README.md
• optional repo process document if the repository has a better canonical location

Step 4 - Align CI outputs with the governance model

What: Make the existing coverage pipeline clearly compatible with domain review and domain-based CI failure.

How: Make Jenkins call a repository helper target that runs the coverage pipeline, produces the existing artifacts, and fails from domain baselines. If needed, archive additional summaries or helper outputs generated by the new scripts.

File(s):

• files/config/Jenkinsfile
• Makefile

Criterios de Aceite

• The repository exposes a documented way to collect domain-oriented coverage evidence and enforce domain baselines in CI.
• Review guidance explicitly states when domain tests are mandatory.
• Domain baselines are represented in a form that can start at 0 and increase later.
• Jenkins uses a repository-owned helper target for the coverage gate.

Tests / Validacao

Automated

• Validate all added helper commands locally.
• Run the existing coverage pipeline end to end after the helper changes.

Evidence

• Show that the global coverage artifacts still build.
• Show an example of domain evidence collection for at least one domain.
• Show that the domain gate fails when a baseline is missed.

Riscos

• Overdesigning domain evidence collection before real reviewer usage patterns exist.
• Letting Jenkins re-encode policy logic instead of consuming the repository helper target.
• Spreading policy text across too many documents and making the rule hard to find.