pi-dev-team 0.2.0

package/skills/coverage-baseline/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: coverage-baseline
+description: >-
+  Multi-workflow coverage baseline worker. Detects the repo's coverage tool
+  from its build manifest, runs it, records the resulting line+branch
+  percentages as the baseline, and posts the number to the parent issue (or
+  local `FEATURE.md`). This number is the floor every later phase must improve
+  on. Called by `/test-improve` (Phase 2) via `--workflow test-improve`.
+argument-hint: "<repo-path> [--parent <issue-url>] [--repo-slug <slug>] [--workflow <name>]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write
+---
+
+# Coverage Baseline
+
+Role: worker. Captures the true baseline coverage of the repo *after* cannot-fail tests have been disabled so the floor isn't inflated by tautologies.
+
+You have been invoked with the `/coverage-baseline` command.
+
+## Parse Arguments
+
+Arguments: $ARGUMENTS
+
+- Positional: `<repo-path>`.
+- `--parent <issue-url>` — parent issue URL on the resolved tracker (or empty for local-files mode).
+- `--repo-slug <slug>` — namespace under `.claude/memory/<workflow>/`.
+- `--workflow <name>` — the workflow namespace under `.claude/memory/`. Defaults to `test-improve`. Orchestrators pass their own namespace (e.g. `/test-improve` passes `test-improve` for its Phase-2 baseline).
+
+If `<repo-path>` is absent, ask the operator.
+
+## Steps
+
+### 1. Detect the coverage tool
+
+Read the build manifest at the repo root and pick the appropriate command:
+
+| Manifest | Default coverage command |
+|---|---|
+| `package.json` (JS/TS) | `npm test -- --coverage` (or `pnpm test --coverage`, `yarn test --coverage`) — or, when a workspace signal is present (a root `workspaces` field, `pnpm-workspace.yaml`, or `lerna.json`), multi-project discovery (see [Step 1a](#1a-multi-project-discovery-net-solutions-jsts-workspaces--java-multi-module-builds)) |
+| `pyproject.toml` / `setup.py` | `pytest --cov=. --cov-report=json` |
+| `pom.xml` | `mvn test jacoco:report` — or, when the root `pom.xml` declares `<modules>`, multi-project discovery (see [Step 1a](#1a-multi-project-discovery-net-solutions-jsts-workspaces--java-multi-module-builds)) |
+| `build.gradle*` | `./gradlew test jacocoTestReport` — or, when `settings.gradle`/`settings.gradle.kts` declares `include(...)`, multi-project discovery (see [Step 1a](#1a-multi-project-discovery-net-solutions-jsts-workspaces--java-multi-module-builds)) |
+| `*.csproj` | `dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=json` — or, when a `.sln` is present at the repo root, multi-project discovery (see [Step 1a](#1a-multi-project-discovery-net-solutions-jsts-workspaces--java-multi-module-builds)) |
+| `Cargo.toml` | `cargo llvm-cov --json` |
+| `go.mod` | `go test -coverprofile=coverage.out ./...` + `go tool cover -func=coverage.out` |
+
+If the repo has its own coverage script (e.g. `npm run coverage`, `make coverage`), prefer that — detect via `package.json#scripts.coverage`, the `Makefile`, or a documented run target in `README.md`. If detection is ambiguous, ask the operator for the exact command. This override does not apply to the `.sln`/`.csproj`, `pom.xml`, or `build.gradle*` rows above — each of those rows' discovery scripts always re-derives the project/module list itself, per-run, regardless of any repo-level coverage script.
+
+### 1a. Multi-project discovery (.NET solutions, JS/TS workspaces & Java multi-module builds)
+
+Replaces the single frozen coverage command above for a multi-project .NET
+solution, JS/TS workspace, or Java multi-module build — closing the gap where
+a hand-picked,
+never-revisited inclusion list caused a real coverage delta to be
+underreported (issue #1759). **Implementation detail** — the discovery,
+bootstrap/drift-check, weighted-merge, and persist mechanics below:
+[`references/multi-project-discovery.md`](references/multi-project-discovery.md),
+mirroring the `../coverage-delta/references/mutation-gate.md` precedent. This
+section pins the contract surface (script names, the hard-failure rule, and
+the exact message templates) that reviewers and tests depend on; the
+reference file holds the mechanics. `coverage-delta`'s own Step 2 links to
+the same reference file rather than re-deriving this a third time.
+
+**.NET** — when a `.sln` file exists at the repo root, run
+`${CLAUDE_PLUGIN_ROOT}/scripts/coverage_discovery_dotnet.py`'s
+`discover_dotnet_projects(repo_root)` instead of the single `dotnet test`
+command above. It returns every project in the solution, each classified
+`TEST`, `AMBIGUOUS`, or `NOT_TEST` (`coverage_config.TestClassification`).
+
+**JS/TS** — when the root `package.json` declares a `workspaces` field, or a
+`pnpm-workspace.yaml`/`lerna.json` is present, run
+`${CLAUDE_PLUGIN_ROOT}/scripts/coverage_discovery_js.py`'s
+`discover_js_packages(repo_root)` instead of the single `npm test --
+--coverage` command above. It returns every resolved workspace package, each
+classified `TEST` or `NOT_TEST`.
+
+**Java** — when a root `pom.xml` declares `<modules>` (Maven), or a
+`settings.gradle`/`settings.gradle.kts` declares `include(...)` (Gradle), run
+`${CLAUDE_PLUGIN_ROOT}/scripts/coverage_discovery_java.py`'s
+`discover_java_modules(repo_root)` instead of the single `mvn test
+jacoco:report` / `./gradlew test jacocoTestReport` command above. Maven takes
+precedence when both signals are present (no cross-merge). It returns every
+module in the build graph — recursively through Maven aggregator modules —
+each classified `TEST`, `AMBIGUOUS`, or `NOT_TEST`. `TEST` requires BOTH a
+`src/test/java`/`src/test/kotlin` directory AND a JUnit/TestNG dependency
+declared on a test configuration in the module's OWN build file; a test-source
+directory whose framework dependency is only inherited (a parent POM, a Gradle
+`subprojects {}` block, a convention plugin) is `AMBIGUOUS`, never silently
+`NOT_TEST`.
+
+Any of the three discovery functions can return `coverage_config.DISCOVERY_NOT_APPLICABLE`
+(no `.sln` / no workspace signal / no multi-module signal — see Step 1b below: the repo is
+single-project and unaffected by anything in this section) or
+`coverage_config.discovery_error(...)` for a tooling/parsing failure — treat
+a `discovery_error` exactly like an existing Step 3 coverage-run failure
+(surface the error, write no baseline, stop). That is a genuine tool
+failure, not the actionable config gap the hard-failure block below
+describes, so it stays on Step 3's existing path rather than growing a
+third failure shape.
+
+**Config path.** `coverage-config.json` is read from and written to the exact
+resolved path `.dev-team-reports/<workflow>/<slug>/data/coverage-config.json`
+— the SAME path Step 5 below persists it to, and the SAME path `coverage-delta`'s
+Step 2a reads it from. There is no ambiguity: both skills operate on the
+identical file.
+
+When discovery returns a real project/package list, call, in this order:
+
+1. **Zero-real-test-project check** — if no discovered entry needs
+   accounting (`coverage_config.needs_accounting`) at all — every project
+   classifies `NOT_TEST` — stop immediately, before touching
+   `coverage-config.json` or `baseline-coverage.json`, with the exact
+   message: `"Coverage capture stopped: no real test project was discovered
+   in this <solution|workspace|multi-module build> — cannot establish a
+   coverage floor. If this repo has test projects, verify they reference
+   Microsoft.NET.Test.Sdk (for .NET), use jest/vitest/mocha+nyc/c8 (for
+   JS/TS), or declare a JUnit/TestNG dependency alongside a
+   src/test/java|kotlin directory (for Java) so discovery can recognize
+   them; otherwise there is no coverage floor to capture."`
+   (`<solution|workspace|multi-module build>` resolved to whichever stack
+   applies).
+   Write no baseline.
+2. `coverage_config.load_or_bootstrap(config_path, discovered, now_iso)` —
+   loads `coverage-config.json` if present (verbatim, unmodified), or
+   bootstraps it (every accounted-for project `included`, zero `excluded`)
+   if absent. On bootstrap, print the returned `notice` verbatim before
+   proceeding — this call never touches any existing `baseline-coverage.json`.
+3. `coverage_config.drift_check(config, discovered)`:
+   - If it raises `ValueError` (a malformed-but-parseable `included`/
+     `excluded` shape — e.g. present but not a list), print the
+     exception's message **verbatim, as its own named block**, and stop
+     without writing a baseline.
+   - On `hard_failure` (an unaccounted-for or conflicting project), print
+     `hard_failure_message` **verbatim, as its own distinct, named block**
+     headed `Coverage capture stopped:` — **never** folded into or reusing
+     Step 3's "Run coverage" failure wording (`Surface the first error.` /
+     `Do NOT write a baseline. The floor must be a true measurement.`).
+     This failure class has a concrete fix (edit `coverage-config.json` to
+     add the named project to `included` or `excluded`) that Step 3's
+     generic wording doesn't carry. Stop; write no baseline.
+4. On success (`hard_failure` is `False`), run the stack's coverage command
+   **per included project** (never once per repo), parse each project's
+   report with `coverage_report_parse.parse(report_path)` (auto-detects the
+   format — lcov, cobertura, clover, jacoco-csv, istanbul-summary,
+   istanbul-final, coverage-py, or coverlet — and returns one
+   `CoverageRecord` per source file), sum each project's records with
+   `coverage_report_parse.aggregate(records)` into that project's single
+   `CoverageRecord`, and call
+   `coverage_config.weighted_merge(project_reports)` — passing the list of
+   per-project `CoverageRecord`s directly, no dict translation needed — to
+   produce the merged `line_pct`/`branch_pct` that Step 4/5 record as the
+   baseline. This same shared parser is what `coverage_gap_ranking.py` uses
+   for its per-module ranking, so there is one implementation of "what a
+   coverage report means," not a second copy re-derived per run.
+
+   **Check the result before using it.** `weighted_merge` returns either the
+   merged `{"line_pct": ..., "branch_pct": ...}` dict, or the shared
+   `discovery_error(...)` shape (`{"signal": "error", "message": ...}`) when
+   any per-project report is missing a required raw count field —
+   `weighted_merge` already validates report completeness internally, so
+   there is no separate pre-validation step for the caller. Discriminate
+   with `if "signal" in merged:` — on a hit, print `merged["message"]`
+   verbatim and stop without writing a baseline; only proceed to Step 4/5
+   when the `"signal"` key is absent.
+
+### 1b. Single-project and mixed-stack repos are unaffected
+
+A `.csproj` repo with no `.sln`, or a `package.json` with no workspace
+signal (no `workspaces` field, no `pnpm-workspace.yaml`, no `lerna.json`),
+takes the pre-existing single-command path from the table above completely
+unchanged — no discovery call, and no `coverage-config.json` write, ever.
+
+A repo containing **both** a `.sln` and a workspace-configured
+`package.json` is explicitly **out of scope** for multi-project discovery:
+the manifest table above already resolves to a single tool via first-match
+order, unchanged by this feature — no new cross-stack merge behavior is
+introduced, and neither discovery script runs for the other stack's files.
+
+### 2. Existing-baseline guard
+
+Check whether `.dev-team-reports/<workflow>/<slug>/data/baseline-coverage.json` already exists for the resolved slug. This existing-baseline guard is this worker's application of the shared existing-tracked-artifact re-capture guard — the canonical definition and rationale live once in `knowledge/decision-defaults.md`'s "Re-capture: keep vs. overwrite an existing tracked artifact" axis; this step cites that axis for the *why* and spells out the operational branches below so an executing agent doesn't need to open a second file mid-task to know what to do.
+
+Applied here:
+
+- **No existing file, or overwrite chosen** — proceed to Step 3 (Run coverage) and the rest of the normal flow.
+- **Existing file, interactive session** — prompt keep/overwrite (default keep). An answer that is neither "keep" nor "overwrite" (case-insensitive) re-prompts with the identical choice — never falls back silently to either option, no retry limit, no timeout.
+- **Existing file, non-interactive** (no usable TTY, or `DEV_TEAM_AUTO_APPROVE=1`) — keep the existing baseline automatically; both log the auto-decision and echo it to run output, not only record it to a file.
+- **Existing file is malformed or corrupt** (fails to parse as JSON — e.g. left over from a prior interrupted write) — treat it as absent, never as a baseline to keep. Emit a warning naming why a fresh capture is happening, then proceed to Step 3.
+- **On keep** — skip straight to Step 7 (Report). Reuse the existing file's `tool`, `line_pct`, and `branch_pct`, and report its `captured_at` instead of a freshly captured timestamp. Do not dispatch a coverage run.
+
+### 3. Run coverage
+
+Run the chosen command from `<repo-path>`. Capture stdout, stderr, and the exit code.
+
+If the run fails:
+
+- Surface the first error.
+- Do NOT write a baseline. The floor must be a true measurement.
+- Stop.
+
+### 4. Parse line + branch percentages
+
+**Only resolve the tool → report-file-path mapping by hand.** That part
+genuinely needs human/agent judgment about where each tool writes its
+output; the parsing itself does not — use the same shared parser Step 1a's
+multi-project merge already calls, never a hand-rolled per-tool reader.
+
+Resolve the report path for the detected tool:
+
+- Istanbul / Jest / Vitest → `coverage/coverage-summary.json` (preferred).
+  **If absent** (the `json-summary` reporter wasn't enabled — see #1086), do
+  not abort. Fall back, in order, to whichever of these exists first:
+  `coverage/coverage-final.json`, `coverage/lcov.info`,
+  `coverage/clover.xml`. Note which report was used (`raw_report`) in the
+  persisted baseline, and recommend the operator run `/setup` (which now
+  checks coverage readiness) or add the `json-summary` reporter so future
+  runs use the canonical summary.
+- pytest-cov → `coverage.json`.
+- JaCoCo → `target/site/jacoco/jacoco.csv`.
+- Coverlet → `coverage.json` (the assembly → file → class → method JSON reporter).
+
+Then parse it with the shared parser — same call, same vocabulary, as
+Step 1a:
+
+```python
+records = coverage_report_parse.parse(report_path)  # auto-detects lcov,
+                                                      # cobertura, clover,
+                                                      # jacoco-csv,
+                                                      # istanbul-summary,
+                                                      # istanbul-final,
+                                                      # coverage-py, or
+                                                      # coverlet
+total = coverage_report_parse.aggregate(records)     # one CoverageRecord
+line_pct = 100 * total.covered_statements / total.total_statements
+branch_pct = (
+    100 * total.covered_branches / total.total_branches
+    if total.total_branches
+    else None
+)
+```
+
+`coverage_report_parse.parse`/`aggregate` raise `ReportError` on an
+unrecognized or unreadable report, and on a recognized format that parses to
+zero records (a misdetected/malformed report, not a genuine 0% measurement)
+— treat either exactly like an existing Step 3 coverage-run failure: surface
+the error, write no baseline, stop.
+
+**cargo-llvm-cov and Go are not covered by the shared parser** — both use
+tool-specific output shapes (`cargo llvm-cov --json`'s own schema; `go tool
+cover -func`'s plain-text summary) that `coverage_report_parse` does not
+recognize, so these two keep their own hand-parsed rules rather than a
+parser call that doesn't exist yet:
+
+- cargo-llvm-cov → `--json` → `data[0].totals.lines.percent`, `…branches.percent`.
+- Go → `go tool cover -func` → `total:` line; branch coverage isn't native, report `null` and flag.
+
+### 5. Persist the baseline
+
+Write `.dev-team-reports/<workflow>/<slug>/data/baseline-coverage.json` directly to tracked storage, via temp-file-then-rename (write to `<path>.tmp` then `mv -f <path>.tmp <path>`) — never a direct, non-atomic write. "Tracked" depends on the resolved `<workflow>` having a matching `.gitignore` re-include: today only `!/.dev-team-reports/test-improve/` exists, so this write is genuinely git-tracked for the `test-improve` caller; a future caller passing a different `--workflow` value would need its own `.gitignore` exception added first, or this write silently lands in ignored space despite the tracked-storage framing above.
+
+```bash
+BASELINE=".dev-team-reports/<workflow>/<slug>/data/baseline-coverage.json"
+mkdir -p "$(dirname "$BASELINE")"
+cat > "${BASELINE}.tmp" <<'JSON'
+{
+  "phase": 2,
+  "captured_at": "<ISO-8601>",
+  "tool": "jest",
+  "line_pct": 41.2,
+  "branch_pct": 28.7,
+  "raw_report": "coverage/coverage-summary.json",
+  "disabled_test_count": 47
+}
+JSON
+mv -f "${BASELINE}.tmp" "$BASELINE"
+```
+
+**Multi-project repos only** (Step 1a ran): additionally persist
+`.dev-team-reports/<workflow>/<slug>/data/coverage-config.json` — the
+`config` dict Step 1a's `load_or_bootstrap`/`drift_check` resolved (the
+just-bootstrapped config on a first run, or the existing config read
+verbatim on every later run) — via `coverage_config.atomic_write_json`, the
+same temp-file-then-rename idiom as `baseline-coverage.json` above. This
+step is skipped entirely for single-project repos (Step 1b) — no
+`coverage-config.json` is written for them.
+
+`disabled_test_count` is included **only** when `.claude/memory/<workflow>/<slug>/disabled-tests.json` exists (present when a caller ran `/test-audit-disable` first); omit the field otherwise. `phase` carries the calling workflow's phase number when it has one, and may be omitted for workflows without numbered phases.
+
+Append a baseline summary to the workflow's baseline memory file (for `/test-improve`, `.claude/memory/<workflow>/<slug>/phase-2.md`; other workflows write to their own baseline phase file). Just the coverage block — auditing is a separate worker. This is process bookkeeping, distinct from the baseline data file above, and is unaffected by the atomic-write change.
+
+### 6. Post to the parent
+
+**Tracker mode** — append a markdown block to the parent issue's description (the resolved CLI was recorded in Phase 1):
+
+```markdown
+## Phase-2 baseline (captured <ISO-8601>)
+- Coverage tool: <tool>
+- Line: <pct>%
+- Branch: <pct>% (or "not native — see notes")
+- Cannot-fail tests disabled in Phase 3: <count> (omit this line when no `disabled-tests.json` exists for the workflow)
+- Quality targets: line ≥ 90% · branch ≥ 90% · mutants = 0 · determinism = 100% · wall-clock = fastest achievable
+```
+
+Use the same CLI pattern Phase 1 resolved. Examples:
+
+```bash
+# GitHub
+gh issue edit <parent-id> --body-file <(gh issue view <parent-id> --json body -q .body; echo; cat phase-2-block.md)
+
+# Azure DevOps
+az boards work-item update --id <parent-id> --description "$(az boards work-item show --id <parent-id> --query 'fields."System.Description"' -o tsv)<append>"
+
+# GitLab
+glab issue note add <parent-iid> --message "$(cat phase-2-block.md)"
+
+# Jira
+acli jira workitem comment add --key <parent-key> --body "$(cat phase-2-block.md)"
+```
+
+**Local-files mode** — append the block to `.claude/plans/<workflow>/FEATURE.md` under a `## Metrics history` heading (create the heading if missing).
+
+### 7. Report
+
+Print:
+
+- Line %, branch %.
+- The path to `baseline-coverage.json`.
+- The destination (parent issue URL or `FEATURE.md`).
+- A reminder that the orchestrator's human gate runs next.
+
+## Notes
+
+- Coverage tools may legitimately differ by repo; never replace the repo's own script with a generic one unless detection fails. Operator override always wins for the coverage command/flags — but never for the `.sln`/`.csproj` row's discovered project set, which is always re-derived per run regardless of any operator-supplied command.
+- The "fastest pre-merge wall-clock" target is not captured here — that's recorded by `/quality-targets-converge` once the full suite is in place. Baseline is line + branch only.
+- For Go (and any tool without native branch coverage), `branch_pct` is `null` and `phase-2.md` flags the gap so the operator can decide whether to install an alternate coverage tool or waive the target.

package/skills/coverage-baseline/references/multi-project-discovery.md

@@ -0,0 +1,202 @@
+# Multi-project coverage discovery — implementation detail
+
+`coverage-baseline`'s Step 1a (.NET `.sln` / JS-TS workspace / Java
+multi-module rows) and Step 5 (persist), and `coverage-delta`'s Step 2, are
+the **contract surface**: when a `.sln` is present (.NET), a workspace signal
+is present (JS/TS), or a multi-module signal is present (Java),
+discovery runs fresh every call, bootstraps or drift-checks
+`coverage-config.json` against it, and — on success — weighted-merges the
+included projects'/packages' coverage into one number. The contract surface
+owns the script names, the hard-failure rule, the schema keys, and the exact
+message templates because that is what reviewers and tests depend on; this
+file holds the mechanics — mirroring the
+`../../coverage-delta/references/mutation-gate.md` precedent (issue #1759).
+
+Every function named below lives in `${CLAUDE_PLUGIN_ROOT}/scripts/`:
+`coverage_config.py` (shared: bootstrap, drift-check, weighted merge,
+measurement-basis notice, and the `read_and_screen_xml` entity-expansion
+screen every XML-parsing stack routes through), `coverage_discovery_dotnet.py`
+(.NET), `coverage_discovery_js.py` (JS/TS), `coverage_discovery_java.py`
+(Java: Maven + Gradle).
+
+## 1. Discovery step (stack-specific; everything after this is shared)
+
+| Stack | Trigger | Call |
+| --- | --- | --- |
+| .NET | a `.sln` file exists at the repo root | `${CLAUDE_PLUGIN_ROOT}/scripts/coverage_discovery_dotnet.py`'s `discover_dotnet_projects(repo_root)` |
+| JS/TS | root `package.json#workspaces`, or `pnpm-workspace.yaml`, or `lerna.json` is present | `${CLAUDE_PLUGIN_ROOT}/scripts/coverage_discovery_js.py`'s `discover_js_packages(repo_root)` |
+| Java | root `pom.xml` declares `<modules>` (Maven), or `settings.gradle`/`settings.gradle.kts` declares `include(...)` (Gradle). Maven wins when both are present — no cross-merge | `${CLAUDE_PLUGIN_ROOT}/scripts/coverage_discovery_java.py`'s `discover_java_modules(repo_root)` |
+
+Both return one of three shapes:
+
+- A list of `{"path": <opaque identity string>, "classification":
+  TestClassification}` entries on success. `path` is the exact,
+  unmodified string the discovery function produced — never
+  normalized, case-folded, or separator-translated when later matched
+  against `included`/`excluded` (`coverage_config`'s identity contract).
+- `coverage_config.DISCOVERY_NOT_APPLICABLE` — no `.sln` / no workspace
+  signal / no multi-module signal. The repo is single-project for this stack; neither discovery nor
+  any of the steps below run. See `SKILL.md` Step 1b.
+- `coverage_config.discovery_error(message)` — a tooling/parsing failure
+  (`dotnet` missing, a malformed `.csproj`, an unsupported
+  `pnpm-workspace.yaml` shape, etc.). Treat this exactly like an existing
+  Step 3 ("Run coverage") failure: surface `message`, write no baseline,
+  stop. This is a genuine tool failure, not the actionable config gap the
+  hard-failure block below describes — it deliberately reuses Step 3's
+  existing failure *behavior*, not a third failure shape.
+
+## 2. Zero-real-test-project check
+
+Before touching `coverage-config.json` at all, check whether **any**
+discovered entry needs accounting:
+
+```python
+any(coverage_config.needs_accounting(entry["classification"]) for entry in discovered)
+```
+
+If this is `False` — every discovered project/package classified
+`NOT_TEST` — stop immediately with the exact message (never write
+`coverage-config.json` or `baseline-coverage.json` on this path):
+
+```
+Coverage capture stopped: no real test project was discovered in this <solution|workspace|multi-module build> — cannot establish a coverage floor. If this repo has test projects, verify they reference Microsoft.NET.Test.Sdk (for .NET), use jest/vitest/mocha+nyc/c8 (for JS/TS), or declare a JUnit/TestNG dependency alongside a src/test/java|kotlin directory (for Java) so discovery can recognize them; otherwise there is no coverage floor to capture.
+```
+
+`<solution|workspace>` resolves to `solution` for .NET, `workspace` for
+JS/TS. This is a diagnosable message, not a silent empty baseline: it names
+the exact markers discovery recognizes for both stacks, so a repo whose
+tests use an unrecognized runner gets an actionable next step instead of a
+gap that looks like "no tests exist."
+
+## 3. Bootstrap / drift-check step
+
+```python
+config, notice = coverage_config.load_or_bootstrap(config_path, discovered, now_iso)
+```
+
+- **Config absent (or malformed)** — bootstrapped fresh from `discovered`
+  (every accounted-for entry `included`, zero `excluded`, tagged
+  `bootstrapped_at`). Print `notice` verbatim. This call never touches any
+  existing `baseline-coverage.json` — the previously-captured value, if
+  any, is left exactly as it was.
+- **Config present** — read back verbatim, unmodified. `notice` is `None`.
+
+Then, always:
+
+```python
+drift = coverage_config.drift_check(config, discovered)
+```
+
+- `drift["hard_failure"]` `True` (an unaccounted-for or conflicting
+  project) — print `drift["hard_failure_message"]` **verbatim, as its own
+  distinct, named block** headed `Coverage capture stopped:`. **Never**
+  fold this into or reuse Step 3's "Run coverage" failure wording
+  (`Surface the first error.` / `Do NOT write a baseline. The floor must
+  be a true measurement.`) — this failure class has a concrete,
+  actionable fix (edit `coverage-config.json`) that Step 3's generic
+  wording doesn't carry, and the two message bodies are textually
+  distinct by construction (`drift_check`'s messages always open with
+  `Coverage capture stopped: <N> discovered project(s)...` or `...are
+  listed in both...`, never Step 3's phrasing). Stop; write no baseline.
+- `drift["hard_failure"]` `False` — proceed to the merge step below.
+  `drift["stale_warning_message"]`, when non-`None`, is a non-blocking
+  signal (excluded entries that no longer match discovery) —
+  `coverage-baseline` does not print it (that is `coverage-delta`'s job,
+  which re-derives discovery on every later call and surfaces staleness
+  there); `coverage-baseline` only needs the `hard_failure` branch above.
+
+## 4. Weighted-merge step
+
+For each path in `config["included"]`, run the stack's coverage command
+**per included project/package** (never once for the whole repo), then parse
+its report with `${CLAUDE_PLUGIN_ROOT}/scripts/coverage_report_parse.py`'s
+`parse(report_path)` — it auto-detects the format (lcov, cobertura,
+jacoco-csv, istanbul-summary, istanbul-final, coverage-py, or **coverlet**)
+and returns one `CoverageRecord` per source file, already in `weighted_merge`'s
+`{covered_statements, total_statements, covered_branches, total_branches}`
+vocabulary. Sum a project's records into its single per-project entry with
+`aggregate(records)`. This is the same shared parser
+`coverage_gap_ranking.py` uses for its per-module ranking (issue #1873) —
+including Coverlet's nested assembly -> file -> class -> method JSON layout,
+so multi-project .NET merge needs no operator-supplied wrapper.
+
+Feed the collected per-project `CoverageRecord`s to `weighted_merge`
+directly — no dict translation needed, since both already use the same
+field names — then check its
+result before using it — `weighted_merge` already validates report
+completeness internally (a report missing a required raw count field returns
+the shared `discovery_error(...)` shape rather than raising), so there is no
+separate pre-validation step for the caller to duplicate:
+
+```python
+merged = coverage_config.weighted_merge(project_reports)
+if "signal" in merged:
+    # A per-project report was missing a required raw count field. merged is
+    # the shared discovery_error(...) shape: {"signal": "error", "message":
+    # ...}. Print merged["message"] verbatim and stop without writing a
+    # baseline — never proceed with a null/0 baseline.
+    ...
+# Otherwise merged is {"line_pct": <float|None>, "branch_pct": <float|None>}.
+```
+
+`weighted_merge` sums covered/total across every included project **before**
+dividing — never a per-project average — so a large, well-covered project
+and a small, poorly-covered one merge to the size-weighted percentage, not
+the midpoint of the two percentages. `merged` is Step 4/5's baseline
+`line_pct`/`branch_pct`.
+
+## 5. Persist step
+
+`baseline-coverage.json` is written exactly as Step 5 already documents
+(temp-file-then-rename), using `merged`'s `line_pct`/`branch_pct`.
+
+Additionally, for a multi-project repo, persist
+`.dev-team-reports/<workflow>/<slug>/data/coverage-config.json` — `config`
+from step 3 above — via `coverage_config.atomic_write_json(config_path,
+config)`, the identical temp-file-then-rename idiom. Single-project repos
+(Step 1b) skip this write entirely — no `coverage_config.py` function is
+ever called for them, and no `coverage-config.json` file appears in their
+`data/` directory.
+
+## Single-project and mixed-stack repos are unaffected
+
+A `.csproj` repo with no `.sln`, or a `package.json` with no workspace
+signal, never reaches any function in this file — Step 1's existing
+single-command path runs exactly as it did before this feature existed.
+
+A repo with **both** a `.sln` and a workspace-configured `package.json` is
+out of scope: `coverage-baseline`'s existing manifest table resolves to a
+single tool via first-match order, unchanged by this feature. No function
+in this file is ever called for the losing stack, and no cross-stack merge
+is introduced.
+
+## Adding a fourth stack
+
+Each stack gets its own `coverage_discovery_<stack>.py` implementing
+`discover_<stack>_<units>(repo_root)` against the three return shapes in §1.
+Deliberately **not** a strategy/registry abstraction: the stacks share only
+leaf helpers (the result signals, `TestClassification`, the XML screen, the
+containment predicate `is_within`, and the XML-namespace stripper
+`local_name`), while enumeration, trigger precedence, the classification
+predicate, and the identity string all differ per stack by design. A new
+stack reuses the shared leaf helpers in `coverage_config.py` rather than
+re-implementing them — the Java stack shipped its first revision without the
+entity-expansion screen the .NET stack already had, and more than one stack
+independently open-coded its own containment check and namespace stripper,
+which is the drift a shared helper exists to prevent (issues #1839/#1848/#1851).
+
+Two rules every stack follows, learned from #1759 and #1765:
+
+- **A declared-but-unusable build graph is a `discovery_error`, never a
+  classification.** A missing module directory, a declared-but-empty module
+  list, or a settings file with no recognizable declaration must fail loudly:
+  classifying it `NOT_TEST` makes `needs_accounting` false and drops it from
+  operator accounting silently. (Stack-specific judgement still applies to what
+  counts as unusable — a Maven `<module>` with no POM is broken because `mvn`
+  itself fails on it, while a Gradle subproject directory with no build file is
+  a legitimate container project.)
+- **An inherited or conditional marker is `AMBIGUOUS`, never `TEST` and never
+  `NOT_TEST`.** Discovery never evaluates inheritance (an MSBuild `Condition`,
+  a parent POM's `<dependencyManagement>`, a Gradle `subprojects {}` block, a
+  BOM version pin); it reports the ambiguity and lets `drift_check` force an
+  operator decision.