---
id: PLN-0037
ticket: runtime-edge-test-plan
title: Plan - Runtime Edge Coverage Governance Foundation
status: open
created: 2026-04-20
completed:
tags: [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:

- global coverage gate continuity;
- 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 global 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`.

**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 without changing the authoritative global 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`.

**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.

**How:**
Keep the current global Jenkins gate unchanged while ensuring produced artifacts are sufficient for domain inspection.
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 without replacing the global `llvm-cov` gate.
- [ ] Review guidance explicitly states when domain tests are mandatory.
- [ ] Domain baselines are represented in a form that can start at `0` and increase later.
- [ ] Existing global coverage enforcement remains intact.

## 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.

## Riscos

- Overdesigning domain evidence collection before real reviewer usage patterns exist.
- Accidentally creating a second competing coverage authority instead of a reviewer aid.
- Spreading policy text across too many documents and making the rule hard to find.