# Counter-bearing Coverage Provenance Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Align repository coverage provenance names and static classification with the counters that Vitest/V8 actually emits, without making claims about JavaScript runtime executability.

**Architecture:** The inventory parser classifies source files only by whether their top-level AST contains statements known to receive V8 counters. Coverage evaluation requires exact agreement between that static counter-bearing/counterless partition and producer rows, while policy-sensitive modules must remain counter-bearing. The JSON artifact exposes the same terminology as the inventory and diagnostics.

**Tech Stack:** TypeScript 7, Node.js 24, `@babel/eslint-parser`, Vitest 4, V8 coverage.

## Global Constraints

- Runtime declarations/initializers and direct execution statements are counter-bearing.
- Type-only modules, `import type {}`, `import {}`, bare side-effect imports, value imports, named value re-exports, and star value re-exports are counterless under the observed Vitest/V8 producer.
- Counterless does not mean non-executable; code, artifacts, diagnostics, tests, and documentation must not make that claim.
- Exact all-zero rows are accepted only for statically counterless modules.
- Critical and high-risk policy modules cannot be counterless.
- All source edits use `apply_patch` and behavior changes follow RED-GREEN TDD.

---

### Task 1: Lock the Vitest/V8 classifier contract with RED tests

**Files:**
- Modify: `tests/unit/risk-coverage.test.ts`

**Interfaces:**
- Consumes: `buildProductionModuleInventory()` and `evaluateRiskCoverage()`.
- Produces: expectations for `counterBearingModules`, `counterlessModules`, `counterBearingTotal`, `instrumentedCounterBearingTotal`, `counterlessTotal`, and `counterlessModules`.

- [x] **Step 1: Rename the test inventory helper and artifact assertions to the desired API.**

```ts
function inventory(
  files: readonly string[],
  generatedExclusions: readonly string[] = [],
  counterlessModules: readonly string[] = [],
): ProductionModuleInventory {
  return {
    files,
    preExclusionTotal: files.length + generatedExclusions.length,
    generatedExclusions,
    counterBearingModules: files.filter((file) => !counterlessModules.includes(file)),
    counterlessModules,
  };
}
```

- [x] **Step 2: Add a real-source inventory regression table.**

```ts
const counterlessSources = {
  "import-type-empty.ts": "import type {} from './a.ts';\n",
  "import-value-empty.ts": "import {} from './a.ts';\n",
  "import-side-effect.ts": "import './a.ts';\n",
  "import-value.ts": "import { a } from './a.ts';\n",
  "reexport-named.ts": "export { a } from './a.ts';\n",
  "reexport-star.ts": "export * from './a.ts';\n",
};
```

Assert every key appears in `counterlessModules`, while `export const runtimeValue = 1` and `void globalThis` appear in `counterBearingModules`.

- [x] **Step 3: Run the focused test and verify RED.**

Run: `./node_modules/.bin/vitest run tests/unit/risk-coverage.test.ts --reporter=dot`

Expected: TypeScript/test failures because the counter-bearing API fields do not exist and the current bare import classifier is executable-labelled.

### Task 2: Rename and align static coverage provenance

**Files:**
- Modify: `scripts/lib/risk-coverage.ts`
- Modify: `tests/unit/risk-coverage.test.ts`

**Interfaces:**
- Consumes: Babel `Program.body` nodes and parsed Istanbul/V8 counters.
- Produces: `hasCoverageCounterBearingStatements(source, relativePath)`, a complete `counterBearingModules`/`counterlessModules` partition, and consistently named `RiskCoverageResult` fields.

- [x] **Step 1: Implement the minimal classifier needed by the RED cases.**

`ImportDeclaration`, `ExportAllDeclaration`, and export declarations without a local declaration return `false`; `importKind === "type"` therefore remains counterless even with an empty specifier list. Runtime declarations/initializers and direct statements return `true`.

- [x] **Step 2: Rename inventory, evaluator sets, totals, diagnostics, and policy guards.**

Use these exact artifact fields: `counterBearingTotal`, `instrumentedCounterBearingTotal`, `counterlessTotal`, `counterlessModules`. Use diagnostics containing `counter-bearing`, `counterless`, and `policy-sensitive module cannot be counterless`; remove executable/non-executable terminology from the risk-coverage implementation and tests.

- [x] **Step 3: Run focused GREEN verification.**

Run: `./node_modules/.bin/vitest run tests/unit/risk-coverage.test.ts tests/unit/risk-coverage-files.test.ts tests/unit/bounded-body-reader.test.ts --reporter=dot`

Expected: all focused tests pass and both static partition directions remain fail-closed.

### Task 3: Refresh documentation, repository evidence, and removal evidence

**Files:**
- Modify: `docs/testing/frontend-platform-testing-strategy.md`
- Modify: `.superpowers/sdd/2026-08-01-quality-architecture-remediation/task-1-report.md`
- Modify: `.superpowers/sdd/2026-08-01-quality-architecture-remediation/progress.md`

**Interfaces:**
- Consumes: root and sample-removal checker output after Task 2.
- Produces: documented V8 counter-bearing semantics and current 285/285 plus 268/268 evidence.

- [x] **Step 1: Document that counterless imports/re-exports may execute at runtime but receive no file counters in the observed producer.**

- [x] **Step 2: Run relevant verification.**

```sh
./node_modules/.bin/tsc --noEmit -p tsconfig.node.json
./node_modules/.bin/tsc --noEmit -p tsconfig.test.json
./node_modules/.bin/eslint scripts/lib/risk-coverage.ts tests/unit/risk-coverage.test.ts --max-warnings=0
node scripts/check-risk-coverage.ts
corepack pnpm test:sample-removal
git diff --check
```

Expected root checker: `Risk coverage: PASS (285/285 production modules, 80 thresholds)`.

Expected removal checker: `Risk coverage: PASS (268/268 production modules, 76 thresholds)`; the already-known dependency-cruiser architecture diagnostic may remain the sole removal failure.

- [x] **Step 3: Commit the independently verified follow-up.**

```sh
git add docs/superpowers/plans/2026-08-02-counter-bearing-coverage-provenance.md docs/testing/frontend-platform-testing-strategy.md scripts/lib/risk-coverage.ts tests/unit/risk-coverage.test.ts
git commit -m "refactor: align coverage counter provenance"
```

## Self-review

- Spec coverage: terminology, import/re-export edge cases, policy diagnostics, artifact fields, root/removal evidence, report, and ledger are each assigned above.
- Placeholder scan: no deferred implementation or unspecified test step remains.
- Type consistency: inventory and result names use `counterBearing*`/`counterless*` throughout; the classifier is `hasCoverageCounterBearingStatements`.