pi-dev-team 0.2.0

package/skills/quality-gate-pipeline/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: quality-gate-pipeline
+description: Unified quality gate for agent output — self-validation, verification evidence, and review-correction loops. Consolidates accuracy-validation, verification-before-completion, and task-review-correction into a single three-phase pipeline. Use before delivery, at completion, and during rework.
+role: worker
+user-invocable: true
+---
+
+# Quality Gate Pipeline
+
+## Overview
+
+Single quality gate that every agent passes through before output is accepted. Replaces three formerly separate skills (accuracy-validation, verification-before-completion, task-review-correction) with a unified pipeline of three phases that run in sequence.
+
+## Constraints
+
+- Do not deliver output containing unverified claims; pause and verify first
+- Do not claim completion without fresh verification evidence from this session
+- Do not reference test results or tool output from earlier in the conversation — re-run and show current output
+- Do not substitute reasoning or explanation for actual evidence
+- Max 3 review-correction cycles before escalating to the Orchestrator
+- Each correction cycle must reduce total defect count; flat or increasing defects trigger escalation
+
+## The Three Phases
+
+### Phase 1: Self-Validation (before delivery)
+
+Every agent runs this checklist mentally before presenting output.
+
+**Factual Accuracy**
+
+- [ ] All file paths referenced actually exist (verify with tool, don't assume)
+- [ ] All function/class/variable names match what's in the codebase
+- [ ] Version numbers, API signatures, and config values are verified, not recalled from training
+- [ ] No statistics or citations are fabricated
+- [ ] Claims about an external tool or product's UI (menu paths, button/control labels, screen layouts, settings locations) are backed by a citation the agent actually has — a fetched doc, a user-provided screenshot/description, or tool output — not recalled from training as if current and authoritative. When no citation exists, say so plainly (e.g. "I don't have a verified/current view of this menu — check the tool's current UI") rather than describing specifics; this is the same **Low** confidence fallback as any other recalled/guessed claim (see Confidence Assessment below).
+
+**Instruction Fidelity**
+
+- [ ] Output addresses what the user actually asked, not a reinterpretation
+- [ ] All acceptance criteria from the task are met
+- [ ] No scope creep beyond the request
+- [ ] Constraints from the agent persona are respected
+
+**Internal Consistency**
+
+- [ ] No contradictions within the output
+- [ ] Code samples compile/run conceptually (correct syntax, valid imports)
+- [ ] Referenced earlier decisions are accurately recalled (if unsure, re-read from .claude/memory/)
+
+**Confidence Assessment**
+
+| Confidence | Meaning | Action |
+| --- | --- | --- |
+| **High** | Verified via tool output or direct file read | Deliver as-is |
+| **Medium** | Inferred from context, not directly verified | Flag with caveat |
+| **Low** | Recalled from training or guessed | Verify before delivering, or mark as unverified |
+
+**Hallucination Detection Signals**
+
+Strong signals (likely hallucination):
+
+- Referencing a file, function, or API that was never read in this session
+- Quoting specific numbers without a source
+- Describing behavior that contradicts tool observations
+- Generating imports for packages not in dependencies
+- Describing a specific control, menu path, or screen in an external tool/product without a citation the agent can point to
+
+When a signal fires: **Pause** → **Verify** (use tools) → **Correct** → **Log** (`hallucination_detected: true` in metrics)
+
+### Phase 2: Verification Evidence (before completion claims)
+
+**Iron Law**: No completion claims without fresh verification evidence. Skipping any step is falsification, not verification.
+
+**The Gate Function**:
+
+1. **IDENTIFY** — What command proves your claim? (e.g., `npm test`, `cargo build`)
+2. **RUN** — Execute the command fresh and completely. Not from cache, not from memory.
+3. **READ** — Read the complete output and exit code. Don't skim.
+4. **VERIFY** — Does the output actually confirm your claim? If not, report actual status.
+5. **ONLY THEN** — Make the claim, with supporting evidence pasted.
+
+**Required Evidence (all tasks)**:
+
+1. **Tests pass**: Run the **whole** test suite. Paste output with pass/fail counts.
+2. **Build succeeds**: If the project has a build step, run it. Paste output.
+3. **Lint clean**: If the project has a linter, run it. Paste output.
+4. **No regressions**: Test count should not decrease.
+5. **Coverage & Mutation (necessary-not-sufficient)**: Coverage thresholds and mutation score gate entry but do not alone gate exit. Saturating at 100% line coverage and 1.0 mutation score on small slices is expected and does not indicate structural quality. They are required to pass but are not the final signal.
+6. **Structural Quality gate**: Before claiming "done", the work must carry a clean-or-triaged `structure-review` signal (nesting depth, cognitive load, and async-pattern judgment are folded into this lens, #2093). Options:
+   - **Clean**: The agent produced no `error`/`warning` findings on the latest diff.
+   - **Triaged**: Every `error`/`warning` finding is logged as a deferred item (with owner + tracking reference) per the Phase 3 exit criteria — and surfaced in the completion summary.
+   - **Waiver**: For hotfixes, documentation-only changes, or work pre-approved by the Orchestrator as out-of-scope for structural review, include a waiver statement: `structural-review-waiver: <reason>` in the completion summary. Waivers are surfaced, not hidden.
+
+**Quality Ownership**: green means the **entire suite**, not just the tests your
+change touched. A failing test is a failing test **regardless of whether this change
+caused it** — "already broken" / "not my diff" is not a pass. A red signal you
+observe must be **fixed**, or **explicitly surfaced and triaged** (file an issue, or
+record a quarantine with a reason via `/triage`) and reported as **not green**.
+Never claim completion over a red suite by attributing the failure to someone else's
+change. You own the quality state you can see, not just your delta.
+
+**Additional Evidence by task type**:
+
+| Task Type | Additional Evidence |
+| ----------- | ------------------- |
+| Bug fix | Red-green cycle: failing test → passing test |
+| New feature | Feature working via test output or demo command |
+| Refactor | Same test count, same pass count |
+| Config change | Config loads without error |
+| Documentation | Commands/code blocks in doc actually work |
+| Agent work | Inspect VCS diff independently — don't trust self-report |
+
+**Evidence Format**:
+
+```
+## Verification
+- Tests: `npm test` → 47 passed, 0 failed (output below)
+- Build: `npm run build` → success, 0 warnings
+- Lint: `npm run lint` → 0 errors, 0 warnings
+```
+
+**Red Flag Language** — stop and verify when you catch yourself saying:
+
+- "should work now" / "should be fixed" / "probably" / "I believe"
+- Expressing satisfaction before running verification
+- Preparing commits without verification output
+
+### Phase 3: Review-Correction Loop (post-delivery rework)
+
+Activated when output is returned for rework, during peer review, or when self-reviewing before delivery (complements Phase 1).
+
+**Defect Severity**:
+
+| Severity | Definition | Required Action |
+| --- | --- | --- |
+| **Critical** | Wrong, breaks functionality, contradicts requirements | Immediate correction, block delivery |
+| **Major** | Significant gap in completeness or correctness | Correct before acceptance |
+| **Minor** | Small inaccuracy, suboptimal approach | Correct if time permits |
+| **Cosmetic** | Formatting, naming, style | Bundle with next change |
+
+**Correction Scope**:
+
+- **Isolated fix**: Self-contained; fix doesn't affect other outputs
+- **Cascading fix**: Implies other outputs may also be wrong; verify related work
+- **Rework**: Fundamental approach flawed; redo from requirements
+
+**Review Checklist**:
+
+1. Requirements compliance — all acceptance criteria addressed, no silent scope changes
+2. Correctness — intended result, edge cases handled, no regressions
+3. Completeness — all files touched, no TODOs remain, integration points addressed
+4. Consistency — matches project conventions, no contradictions
+5. Quality — appropriately simple, readable, sufficient documentation
+
+**Iteration Rules**:
+
+- Max 3 review-correction cycles before escalation
+- Each cycle must reduce total defect count
+- If defects increase or stay flat after 2 cycles, escalate to Orchestrator
+- Exit criteria: all critical and major defects **resolved** (fixed and re-verified). Minor defects may be **deferred** — but deferred ≠ resolved: each must be logged with an owner and a tracking reference and **surfaced in the completion summary**, never folded into "done." A slice carrying deferred items is "complete with known follow-ups," not silently "complete."
+
+**Escalation**: Summarize defect pattern and attempted corrections → escalate to Orchestrator for re-routing → log with `escalation_reason` in task metrics.
+
+## When to Apply Each Phase
+
+| Situation | Phases to run |
+| ----------- | -------------- |
+| Initial development, about to deliver | Phase 1 → Phase 2 |
+| Claiming task completion | Phase 2 (at minimum) |
+| Output returned for rework | Phase 3 → Phase 2 |
+| Peer-reviewing another agent's output | Phase 1 (as reviewer) → Phase 3 if defects found |
+| Trivial one-line fix | Phase 2 only (verify it works) |
+
+## Output
+
+Phase 1: Confidence-scored validation — report failures only.
+Phase 2: Verification evidence block with tool output.
+Phase 3: Defect table (severity, scope, status: fixed/deferred/escalated).
+
+## Integration
+
+- **Performance Metrics**: `hallucination_detected`, `rework_cycles`, `defects_found` are logged automatically by `hooks/task_completion_metrics.py` on task completion — no skill-level logging step needed. To surface non-default values, populate `.claude/session-metrics.json` with the relevant fields before the session ends.
+- **Context Summarization**: When context is high, increase Phase 1 rigor
+- **Human Oversight Protocol**: Escalation from Phase 3 feeds into the approval gate system

package/skills/quality-targets-converge/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: quality-targets-converge
+description: >-
+  Multi-workflow convergence worker. Closes the gap between the current test
+  suite and the four quality targets (line+branch coverage ≥ 90%, zero
+  surviving mutants, 100% deterministic, fastest pre-merge wall-clock
+  achievable on-machine). Each iteration reads the latest measurements,
+  picks the largest gap, and dispatches the smallest action that moves it.
+  Stops only when all four targets are green or each gap is explicitly
+  waived by the operator with a recorded reason. Called by `/test-improve`
+  (Phase 8) via `--workflow test-improve`.
+argument-hint: "<repo-path> [--parent <issue-url>] [--repo-slug <slug>] [--workflow <name>] [--max-iterations <n>] [--refactor-mode <no-refactor|refactor-allowed>]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Skill(coverage-delta *), Skill(mutation-testing *)
+---
+
+# Quality Targets Converge
+
+Role: worker. The convergence close-out loop. Reads coverage, mutation, determinism, and wall-clock measurements; picks the largest gap; dispatches the smallest action that moves it; re-measures; repeats. The operator gates the loop and can waive any individual target.
+
+You have been invoked with the `/quality-targets-converge` command.
+
+## Parse Arguments
+
+Arguments: $ARGUMENTS
+
+- Positional: `<repo-path>`.
+- `--parent <issue-url>` — parent issue URL (or empty).
+- `--repo-slug <slug>` — `.claude/memory/<workflow>/` namespace.
+- `--workflow <name>` — the workflow namespace under `.claude/memory/` and `.claude/plans/`. Defaults to `test-improve`. Callers pass their own namespace so parallel runs stay quarantined.
+- `--max-iterations <n>` — safety cap. Default 10. The operator can extend mid-run.
+- `--refactor-mode <no-refactor|refactor-allowed>` — gates whether Step 4's
+  "coverage gap, no existing seam" action may propose a paired
+  `[Refactor-for-testability]` Story (see Step 4). **Default
+  `refactor-allowed`** when the flag is absent or carries an unrecognized
+  value — this preserves today's unconditional-propose behavior for callers
+  other than `/test-improve` that don't pass the flag. Whenever the default
+  fires because the flag was absent or unrecognized, print
+  `"refactor-mode not specified by caller — defaulting to refactor-allowed"`
+  (naming the unrecognized value received, if any) so a caller that forgot
+  to wire the flag is visible in the run output rather than silently
+  indistinguishable from one that explicitly wants `refactor-allowed`.
+
+**Path templates.** Every filesystem path in the Steps below carries `<workflow>` as a placeholder; the skill interpolates the resolved `--workflow` value at run time. There is no literal workflow-name string inside a path.
+
+## Steps
+
+### 1. Load targets
+
+Read `.dev-team/quality-targets.json` if it exists; otherwise use defaults:
+
+```json
+{
+  "line_pct_min": 90,
+  "branch_pct_min": 90,
+  "surviving_mutants_max": 0,
+  "determinism_runs": 5,
+  "determinism_required_pass_rate": 1.0,
+  "wall_clock_target_seconds": null
+}
+```
+
+`wall_clock_target_seconds = null` means "fastest achievable" — the loop tracks it but does not gate on a number.
+
+### 2. Measure all four dimensions
+
+In one pass before the loop body:
+
+- **Coverage** — invoke `/coverage-delta <repo> --workflow <workflow>` (no `--story`). Result lives in `.dev-team-reports/<workflow>/<slug>/data/coverage-history.json`.
+- **Mutation scope — branch-vs-base changed set (cumulative, NOT whole-repo).** Phase-8 validation measures mutation only over the code this branch changed, accumulated across every session on the branch — never the whole repo (issue #1208). Resolve the scope in three moves:
+
+  1. **Resolve the branch base** (same idiom as `/build`'s Farley-Score step — `skills/build/SKILL.md` Step 7 sub-step 1): `git merge-base HEAD origin/HEAD`, falling back to `origin/main`, then `main`, `master`, `develop`. **Degenerate-base guard (issue #916):** treat **base == HEAD, or every candidate ref unresolvable** (single-branch / no-remote repo where `merge-base` fails outright, or every commit landed directly on the fallback branch so `merge-base` resolves to HEAD) as a resolution **failure**, not a valid base. On resolution failure, fall back to the plan's recorded plan-start anchor — the same anchor `/build` resolves against (issue #865): `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/build_rollback_point.py get-by-symbolic --path .claude/memory/build-rollback.json --symbolic plan-start --repo <repo> --ancestor-of HEAD` (the `--repo`/`--ancestor-of` args reject a stale `plan-start` from an unrelated earlier build). If a qualifying entry is found, use its `sha` as `<base>`. If none is found, print `Branch-base resolution degraded — cannot bound the changed set; scoping to the full in-scope component list this run.` and scope to the full in-scope component list **only as a surfaced last resort** — so a widened run is visible in the output, never a silent whole-repo default.
+  2. **Cumulative changed set:** `git diff --name-only <base>...HEAD` (three-dot — everything the branch added since it forked, across all sessions, not just the last commit).
+  3. **Scope is the source covered by the changed TESTS, not just changed source files.** A test-improvement branch commonly changes no production source at all, so mapping only changed `*.ts`/`*.py`/etc. would scope to nothing. From the changed set, take every changed **test** file and resolve the production source it exercises: a co-located `X.spec.ts` / `X.test.ts` maps to its sibling `X.ts` (same basename, same directory); an a11y / contract / integration spec that names no co-located sibling maps to the first-party production modules it **imports** (parse the spec's import statements, drop third-party paths). Union that resolved-source set with any changed production source files. That union is the mutation `--scope`.
+
+- **Mutation — reuse rule (applied BEFORE the fresh `/mutation-testing` invocation below).** The upstream phase already measured mutation per `[Component tests]` Story; that evidence is in `.dev-team-reports/<workflow>/<slug>/data/mutation-history.json`. Use it instead of re-running mutation against files (from the branch-scoped set above) the upstream phase already exercised:
+
+  1. For each in-scope file, look up the most recent entry in `mutation-history.json`.
+  2. Compare the entry's `captured_at` to the file's last committer date: `git log -1 --format=%cI -- <file>` (committer date — not file mtime. Uncommitted edits intentionally won't trigger re-measure; convergence runs over committed code).
+  3. If the entry post-dates the file's last commit AND `status != "tool_unavailable"`, **reuse** the entry's `survivors_after` as the current count. Drop the file from the `--scope` glob passed to the fresh `/mutation-testing` run below.
+  4. Otherwise (no entry, stale entry, or prior `status: "tool_unavailable"`) — measure the file fresh in the next bullet. The fresh result is written back to `.dev-team-reports/<workflow>/<slug>/data/mutation-history.json` as a **synthetic entry** with `story: "converge-<iteration>"` so within-iteration reuse works and so the next iteration sees the same evidence the upstream phase would have.
+
+  **Backward compatibility — `mutation-history.json` absent.** Workflows that pre-date this contract have no upstream mutation evidence. When the file is absent, fall through to measuring fresh: the next bullet runs `/mutation-testing` over every file **in the branch-vs-base changed set** defined above — the reuse rule is opportunistic, not required, but absence of history never widens the run back to whole-repo.
+
+- **Mutation (fresh measurement on files the reuse rule didn't cover).** Invoke `/mutation-testing <repo> --scope <remaining-files> --workflow-managed-approval --emit-json <tmp>` (where `<remaining-files>` is the branch-scoped set minus the files the reuse rule covered). Parse the surviving-mutant list from its JSON output (filter `status: "equivalent"` AND `status: "accepted"` — both carry a `reason` and neither counts against convergence). Capture file + line + mutant operator for each survivor. Write back each freshly-measured file as a synthetic entry to `.dev-team-reports/<workflow>/<slug>/data/mutation-history.json` (see reuse rule above) via **temp-file-then-rename** (write to `<path>.tmp` then `mv -f <path>.tmp <path>`) — the same idiom [`coverage-delta/SKILL.md`](../coverage-delta/SKILL.md) Step 2b uses for the same now-shared, git-tracked file, so both writers stay safe against interleaved writes.
+
+- **Unmeasurable modules — held at baseline, never dropped (issue #1208, criterion 4).** A module `/mutation-testing` cannot finish — reported OOM, or a tool crash, or a run so slow that `mutation-testing`'s per-mutant wall-clock timeout (which counts a timed-out *mutant* as killed) still leaves the whole *module's* score unestablished — must NOT be silently omitted and must NOT be reported with an invented number. Instead:
+
+  1. First retry the module's **non-static** subset with `ignoreStatic` (static initializers are the common OOM trigger); if that subset now measures, use it and mark only the static remainder held-at-baseline.
+  2. For whatever still cannot be measured, **hold it at its persisted baseline count** — the `survivors_after` recorded for that file in `baseline-mutation.json` / `mutation-history.json` — and record it in the snapshot's `held_at_baseline` list.
+  3. Report it in Step 6 verbatim as **"held at baseline (could not measure — needs ≥N GB agent)"** — never as a fresh zero, never dropped from the module list.
+
+- **Whole-repo score via splice over the persisted baseline (issue #1208, criterion 2).** Report BOTH the branch-scoped result AND a whole-repo number, but do **not** re-run the whole repo to obtain it. The whole-repo score is a **splice**: the freshly-measured changed files (above) layered over the **persisted per-file baseline** for every untouched file. The baseline of record is `baseline-mutation.json` plus the per-file `survivors_after` in `mutation-history.json` (see `/coverage-delta`'s [`references/mutation-gate.md`](../coverage-delta/references/mutation-gate.md)). Both files are written directly to `.dev-team-reports/<workflow>/<slug>/data/` at capture/append time — `baseline-mutation.json` by `/test-improve` Phase 2 (`/mutation-testing` owns no persistence of its own), `mutation-history.json` by `/coverage-delta` (other agents are landing those write paths concurrently) — so the splice source is always available for every convergence session.
+
+- **Determinism** — re-run the test suite `determinism_runs` times. Capture: pass rate, the names of any test that failed in some runs but passed in others, the total wall-clock per run (lowest = current baseline).
+
+- **Wall-clock** — already captured as part of determinism. Take the median.
+
+Write the snapshot to `.claude/memory/<workflow>/<slug>/converge-<iteration>.json`:
+
+```json
+{
+  "iteration": <n>,
+  "captured_at": "<ISO-8601>",
+  "line_pct": …, "branch_pct": …,
+  "surviving_mutants": [ { "file":…, "line":…, "op":… }, … ],
+  "surviving_mutants_whole_repo_spliced": <count>,
+  "held_at_baseline": [ { "module":…, "baseline_survivors":…, "reason": "oom|timeout|tool_crash" }, … ],
+  "mutation_scope": {
+    "base_ref":              "<sha>",
+    "changed_test_files":    <count>,
+    "resolved_source_files": <count>
+  },
+  "mutation_reuse": {
+    "reused_from_history": <count>,
+    "measured_fresh":      <count>,
+    "total_files":         <count>
+  },
+  "determinism_pass_rate": …, "flaky_tests": [ … ],
+  "wall_clock_median_sec": …, "wall_clock_runs": [ …, … ]
+}
+```
+
+The operator-visible iteration report (Step 6) names the cost saving directly: `mutation: reused N, measured M` — without that line, the reuse rule is invisible and the operator can't tell whether upstream mutation evidence actually paid off.
+
+### 3. Compute the gap to each target
+
+For each of the four, compute "distance to target":
+
+- Line: `target - current` (clamped at 0).
+- Branch: `target - current`.
+- Mutants: the **whole-repo spliced score** (`surviving_mutants_whole_repo_spliced`) — survivors in the branch-scoped changed set plus the persisted-baseline survivor counts held for every untouched module and every held-at-baseline / unmeasurable module. Gate `surviving_mutants_max` on this spliced number, never on a partial branch-only count, so a convergence run is judged against the whole repo's honest score.
+- Determinism: `determinism_runs - passes`.
+- Wall-clock: tracked, not gated unless the operator set a number.
+
+### 4. Pick the largest gap + dispatch the smallest action
+
+Use this priority order (matches the spec's order of operations) when two gaps tie:
+
+1. Determinism (a flaky suite invalidates every other metric).
+2. Surviving mutants (coverage you can't trust isn't coverage).
+3. Line + branch coverage.
+4. Wall-clock (only if the operator set a target).
+
+For the picked gap, dispatch the smallest action — by emitting a recommendation, not by editing code (the actual edit happens via `/build` against a downstream Story):
+
+| Gap | Smallest action |
+| --- | --- |
+| Flaky test | Identify the source of non-determinism (real clock, RNG, sleep, shared state, order dependence). Propose a downstream Story to remove it. |
+| Surviving mutant on a covered line | The test asserts coverage but not behavior; propose a downstream Story to add the specific assertion that kills this mutant. |
+| Surviving mutant on an uncovered line | Propose a downstream Story to add a test that hits the line *and* asserts the behavior. |
+| Coverage gap on a single file, existing seam | Propose a downstream Story to add a component test for the uncovered branch at the existing seam. |
+| Coverage gap on a single file, no existing seam, `--refactor-mode refactor-allowed` | Propose a paired `[Refactor-for-testability]` Story (today's behavior, unchanged). |
+| Coverage gap on a single file, no existing seam, `--refactor-mode no-refactor` | Do **not** propose a `[Refactor-for-testability]` Story — the operator already closed that decision at Phase 6. Instead, write an entry (seam-needed / behavior-gained / estimated-risk) to `.dev-team-reports/<workflow>/<slug>/refactor-backlog.md`, appending to the file Phase 6 writes if it already exists rather than creating a second backlog file. |
+| Behavior-preserving (invariant) test refactor — a `done()`→`async`/`await` rewrite, a real-timer→`fakeAsync` migration, a callback→promise conversion that changes no assertion and kills no mutant | **Skip it — do not dispatch a Story.** These migrations preserve test semantics, so they close no coverage / mutation / determinism gap; dispatching work for them is pure churn. Log the skip with its rationale to `.dev-team-reports/<workflow>/<slug>/refactor-backlog.md` (the same backlog the no-refactor row appends to) as `invariant-refactor-skipped: <file> — <migration> — no gap closed`, so the decision is auditable rather than silent. |
+| Wall-clock regression | Identify the slowest tests (top 10). Propose a Story to swap a local container for an in-memory double where both prove the behavior. |
+
+**Invariant refactors are skipped, not dispatched (issue #1208).** The "behavior-preserving (invariant) test refactor" row exists because a convergence loop scanning changed tests will encounter semantics-preserving migrations. They change no assertion and kill no mutant, so they close no target gap — proposing a Story for them only adds churn. Skip them and log the rationale to the backlog so the skip is auditable rather than silent.
+
+**Gherkin binding for proposed component tests.** When the smallest action is "add a component test" (the surviving-mutant rows, or the coverage-gap-with-existing-seam row above), first check `.claude/memory/<workflow>/<slug>/gherkin-bindings.json` for an approved Scenario covering that behavior at the relevant public surface:
+
+- **Scenario exists** — the proposed Story extends the matching `[Component tests]` Story rather than creating a new one. The recommendation cites `<feature-file>::<scenario-name>` and the test added in `/build` binds to that scenario in the binding mode recorded in `phase-0.md`.
+- **Scenario is missing** — do NOT invent a Scenario inside a downstream Story. Pause the convergence loop and hand back to the orchestrator: the operator remains the single author of intent, and the Gherkin surface must be updated via the workflow's standard Phase-2 sign-off before this loop resumes. Do not open ad-hoc amendment Stories from inside this worker; that route would bypass the human gate and is intentionally not available here.
+
+This keeps the approved Gherkin as the single source of intended behavior even when convergence discovers a gap. The operator stays the only author of intent.
+
+Each recommendation lands as a new child issue on the parent (via the same CLI dispatch convention as `/issues-from-assessment`) or as a new file under `.claude/plans/<workflow>/phase-7/`. The orchestrator then drives `/build` against each.
+
+### 5. Re-measure + decide whether to loop
+
+After `/build` closes the dispatched Story:
+
+- Re-measure (Step 2).
+- If all four targets met → exit loop, mark the close-out Story Done.
+- If `--max-iterations` reached → halt, print current state, ask the operator to waive remaining gaps or extend.
+- Otherwise → next iteration.
+
+### 6. Post the converge history
+
+Append a markdown block to the parent (or `FEATURE.md`):
+
+```markdown
+### Convergence iteration <n> (<ISO-8601>)
+- Coverage: line <pct>% (target 90%) · branch <pct>% (target 90%)
+- Surviving mutants (branch-scoped changed set): <n> (target 0)  ·  mutation: reused <N>, measured <M>
+- Surviving mutants (whole-repo, spliced over persisted baseline): <n>  ·  Δ vs baseline: <±n>
+- Held at baseline (could not measure — needs ≥N GB agent): <module list, or "none">
+- Determinism: <passes>/<runs> (target <runs>/<runs>)
+- Wall-clock median: <sec>s (target: fastest achievable / <n>s if set)
+- Largest gap: <dimension>
+- Dispatched: <story title / id>
+```
+
+Same CLI pattern as `/coverage-baseline` and `/coverage-delta`.
+
+### 6b. Gherkin effectiveness roll-up (conditional)
+
+When `.claude/memory/<workflow>/<slug>/gherkin.md` exists (Phase 3 ran — see
+`/gherkin-derive`), run the roll-up after every iteration's re-measure so
+there is a standing signal on whether the derived scenarios track real
+coverage/mutation movement (issue #1296):
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/gherkin_effectiveness_rollup.py" \
+  --gherkin-md .claude/memory/<workflow>/<slug>/gherkin.md \
+  --bindings-json .claude/memory/<workflow>/<slug>/gherkin-bindings.json \
+  --baseline-coverage .dev-team-reports/<workflow>/<slug>/data/baseline-coverage.json \
+  --current-coverage <this iteration's coverage measurement> \
+  --baseline-mutation .dev-team-reports/<workflow>/<slug>/data/baseline-mutation.json \
+  --current-mutation <this iteration's mutation measurement> \
+  --out .claude/metrics/gherkin-derive-effectiveness.jsonl
+```
+
+Omit any flag whose file doesn't exist for this run (e.g. no
+`gherkin-bindings.json` when the workflow only derived scenarios via
+`/gherkin-derive` and never ran `/gherkin-public`) — the script degrades
+gracefully and still records provenance/binding-mode per scenario with the
+correlated field left `null`. When `gherkin.md` is absent (binding mode
+`none`, or Phase 3 never ran), skip this step entirely — there is nothing
+to roll up. This is a metrics side-effect only; it never changes convergence
+gaps or which action Step 4 dispatches.
+
+### 7. Waiver handling
+
+If the operator chooses to waive a target:
+
+- Capture the reason verbatim.
+- Record it in `.claude/memory/<workflow>/<slug>/waivers.json`.
+- Append a `**Waived**: <target> — <reason> (<ISO-8601>)` line to the parent issue / `FEATURE.md`.
+
+A waiver counts as "met" for the loop's exit condition but is surfaced in the orchestrator's final Report.
+
+### 8. Report
+
+Print:
+
+- Current state of all four dimensions.
+- Whether the loop converged, halted, or is mid-iteration.
+- Any waivers recorded.
+- The path to `converge-<iteration>.json` and to `waivers.json` (if any).
+- The path to `.claude/metrics/gherkin-derive-effectiveness.jsonl` when Step 6b ran.
+
+## Examples / Integration
+
+- `/test-improve` invokes this worker from Phase 8 with `--workflow test-improve`; paths resolve as `.claude/memory/test-improve/<slug>/` and `.claude/plans/test-improve/phase-8/`, with tracked evidence (coverage/mutation history, baselines) under `.dev-team-reports/test-improve/<slug>/data/`.
+- `/test-improve` invokes this worker from Phase 8 with `--workflow test-improve`; the same template resolves with `<workflow>` = `test-improve`.
+
+## Notes
+
+- This worker does not write tests or edit production code. Its output is recommendations + dispatched Stories that `/build` then implements. That keeps the workflow's "every change goes through a Story with Acceptance Criteria" invariant intact.
+- The 10-iteration default is a backstop, not a target. Most repos should converge in 3–5; persistent failure to converge means the dispatched actions aren't the smallest — surface the loop to the operator for a strategy decision.
+- Wall-clock is measured but only gated when the operator sets a number; the spec's "fastest achievable" phrasing is reported as the trend across iterations.
+- Adding a new workflow caller means passing a new `--workflow <name>` value; no path edits inside this skill are required because paths are templated.
+- **Locating seams and existing tests (Step 4).** When determining whether a coverage gap has an existing seam or which test exercises a given line/mutant, prefer CodeGraph/Repowise over raw `Grep` — they return the actual call graph rather than a text match, which is what distinguishes a real seam from a coincidental identifier match. See [`knowledge/codegraph-vs-graphify.md`](../../knowledge/codegraph-vs-graphify.md) for tool selection and the fallback contract.

package/skills/repo-review/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: repo-review
+description: >-
+  Whole-repository drift review for the review agents that a per-diff
+  /code-review pass cannot meaningfully evaluate — accumulated file/CLAUDE.md
+  size drift, AI-provenance verification debt, harness-config completeness,
+  and cross-file frontend component duplication. Use when the user asks for a
+  "repo review", "drift review", "whole-tree review", wants to check
+  accumulated size/token drift, verification debt, or duplicated frontend
+  components across the WHOLE codebase rather than a single diff, or
+  periodically (e.g. every N merged PRs) to catch drift no single diff-scoped
+  review would surface. Report-only — never gates a commit.
+argument-hint: "[--path <dir>] [--json] [--pdf]"
+user-invocable: true
+allowed-tools: Read, Write, Grep, Glob, AskUserQuestion, Agent, Bash(git rev-list *), Bash(git rev-parse *), Bash(sh *)
+---
+
+# Repo Review
+
+Role: orchestrator. Route work to review agents; do not review code yourself.
+
+**Why this skill exists (#1733, #1735).** `/code-review` dispatches its panel
+per diff. Four agents' findings are properties of the *whole tree* — absolute
+size, accumulated drift, or the full component inventory — not of any single
+diff's delta, so a diff-scoped pass either can't see the pattern they exist to
+catch (a file that crept past a size threshold over 10 separate small PRs) or
+re-derives a whole-codebase judgment independently on every review. This
+skill runs those four agents against the whole repository instead, on a
+cadence the operator controls (manual invocation today — see "Cadence" below),
+and writes a report rather than gating anything.
+
+**Not `/code-review`.** No staging, no gate-hash, no `.pr-review-passed` write,
+no interactive fix loop, no pre-flight lint/typecheck/secret-scan gates —
+there is no commit to gate. This is a read-only report, structurally closer
+to `/harness-audit`/`/co-evolution-audit` than to `/code-review`.
+
+## Orchestrator constraints
+
+1. **Do not review code yourself.** Delegate all analysis to the four agents below.
+2. **Fixed roster — not resolver-selected.** Unlike `/code-review`'s `select_lenses.py`-driven panel, this skill's roster is fixed and unconditional (see Roster). Do not add or drop agents based on file type; each agent's own `## Skip` clause handles the case where it has nothing to say.
+3. **Write the report to a file.** Present only the summary table and next-steps in chat — do not repeat the full report.
+4. **Be concise.** Tables and JSON, no preambles, no filler.
+
+## Parse Arguments
+
+Arguments: $ARGUMENTS
+
+| Flag | Behavior |
+| --- | --- |
+| `--path <dir>` | Review only files under this directory (still whole-subtree, not a diff) |
+| `--json` | Emit aggregated JSON to stdout instead of prose; writes no report file |
+| `--pdf` | After the report is written, render a sibling PDF via `hooks/lib/report_pdf.py`. No-op under `--json` (no report file is written) |
+| (no flags) | Review the whole repository |
+
+## Steps
+
+### 1. Determine target files
+
+`--path <dir>`: `Glob("<dir>/**/*")`, excluding `node_modules`, `.git`, `dist`, `build`, `coverage`. No `--path`: the whole repository, same exclusions. **Never `Read` a directory path directly** — `Read` on a directory throws `EISDIR`; always enumerate with `Glob`. See `${CLAUDE_PLUGIN_ROOT}/knowledge/directory-enumeration.md`.
+
+**Scope validation** (mirrors `/code-review`'s own table, without its sliced-mode machinery — that is a `--path`-narrowing hint here, not an auto-engaged mode):
+
+| File count | Action |
+| --- | --- |
+| ≤500 | Proceed |
+| >500 | Warn: "Reviewing {N} files — consider `--path` to narrow scope, or expect a slower, larger-context pass." Proceed anyway — this skill has no sliced-mode equivalent to fall back to. |
+
+### 2. Load drift state
+
+Read `.claude/memory/repo-review-state.json` if it exists: `{"last_commit": "<sha>", "last_run_at": "<ISO 8601>"}`.
+
+**Validate `last_commit` before it touches a shell command — this file is not trusted input.** It is written by step 7 below, but nothing stops a hostile PR from committing its own `.claude/memory/repo-review-state.json` (see step 7's `.gitignore` note) with an arbitrary string in `last_commit`, which a maintainer's later `/repo-review` run would then read. Treat any value that does not match `^[0-9a-fA-F]{7,40}$` exactly like "no prior state" — do not interpolate it into a command. Only once it matches that pattern, confirm it is actually reachable and count commits since it, in one call with no pipe:
+
+```bash
+git rev-list --count "<validated-sha>"..HEAD
+```
+
+A non-zero exit (unreachable commit — e.g. history was rewritten) is the same "no prior state" case as a missing file: carry `null` for the drift count, not an error. Carry the count (or `null` if there is no prior state, the repo is not a git repository, `last_commit` failed validation, or it is no longer reachable) into the report as the drift signal. This is informational only — it does not gate or skip anything, and a missing/unreadable/invalid state file is not an error, just "first run."
+
+**Known limitation, accepted by design:** the read here (step 2) and the write in step 7 are not atomic. Two `/repo-review` invocations racing on the same repository can lose one's drift-state update to the other. Since the count is informational only — never gating or blocking anything — this is an accepted limitation, not a defect to fix: at most it costs one run's drift signal, never a wrong review result.
+
+**Cadence (#1735 non-goal, addressed minimally here).** This skill is
+invoked manually — there is no scheduled trigger, matching the existing
+`/harness-audit` and `/co-evolution-audit` precedent of pure on-demand
+invocation rather than a cron-style mechanism. The commits-since-last-audit
+count above is what lets an operator decide *for themselves* whether enough
+has changed to be worth another pass (or wire it into their own CI cadence,
+e.g. "run every 50 merged PRs") without this skill inventing a scheduler.
+
+### 3. Confirm agent-dispatch capability
+
+Before dispatching anything, confirm the `Agent`/`Task` tool is present in this toolset. If it is not: **STOP.** Do not review the files yourself as a substitute — report which capability is missing and that this skill cannot run until re-invoked from a session that has it. Do not write a report claiming a review ran.
+
+### 4. Dispatch the fixed roster
+
+Spawn all four as parallel subagents in a single message using the `Agent` tool. Every one of these was **removed from `/code-review`'s per-diff panel** for the same reason (#1733) — do not re-add them there; this skill is where they run now.
+
+| Agent | Why whole-tree, not per-diff |
+| --- | --- |
+| `token-efficiency-review` | File length, CLAUDE.md size, LLM anti-patterns are properties of absolute size/drift, invisible to a single diff |
+| `ai-provenance-review` | "Verification debt" and "regeneration risk" are trend/accumulation metrics by definition |
+| `claude-setup-review` | Reviews the harness (CLAUDE.md, rules, skills, agent frontmatter), not the changeset |
+| `component-architecture-review` | Cross-file duplication/reusable-component extraction is best judged against the *entire* component inventory. **Note:** this agent also stays in `/code-review`'s per-diff panel, narrowed to newly-*added* component files only (`Scope: added-only`, #1733) — its dispatch here is unconditional and independent of that narrower rule. |
+
+**Context payload**: enumerate the target files and directory tree once (step 1 already did this) and pass the same full files + tree to every agent — no diff exists to describe, so there is no changed-file list to pass, unlike `/code-review`'s `project-structure` payload. Pass each agent's declared `model:`/`effort:` frontmatter unchanged, per `agents/orchestrator.md` → Model/Effort Resolution (ADR 0026). Skip an agent's dispatch only if step 1's target set is empty.
+
+**Per-agent output**: the shared contract in [`../../knowledge/review-agent-output-contract.md`](../../knowledge/review-agent-output-contract.md), wrapped with `agentName`/`modelTier` — same envelope `/code-review` uses, so tooling that already parses one parses the other.
+
+Wait for all four to complete before aggregating.
+
+### 5. Aggregate and score
+
+Consolidate findings the same way `/code-review` step 5c does: when multiple agents flag the same `file:line`, one `topFindings` entry with `severity` = the highest single enum, `agents` = the reporting agents array. No slash/comma-joined severities.
+
+Score overall health with the general-case formula from [`../../knowledge/review-rubric.md`](../../knowledge/review-rubric.md) § Health Score Calculation (0 fail AND ≤2 warn = 🟢; 1-2 fail OR 3+ warn = 🟠; 3+ fail = 🔴) — the rubric's category-weight table names other agents and does not apply here; use only the general pass/warn/fail counting rule. `skip` results are excluded from scoring, same as `/code-review`.
+
+### 6. Generate report
+
+**`--json`**: emit the aggregated JSON object (same shape as `/code-review`'s `--json` output — see [`../code-review/output-format.md`](../code-review/output-format.md#aggregated-json-result-json-flag), plus a top-level `commitsSinceLastAudit` field from step 2) to **stdout**. Write no file. Stop — do not proceed to step 7.
+
+**Otherwise**, emit a prose summary:
+
+```
+# Repo Review — <date>
+
+Scope: <whole repository | `--path <dir>`>
+Commits since last audit: <N | "first run">
+
+## Health: <🟢|🟠|🔴>
+
+| Agent | Status | Issues |
+| --- | --- | --- |
+| token-efficiency-review | ... | ... |
+| ai-provenance-review | ... | ... |
+| claude-setup-review | ... | ... |
+| component-architecture-review | ... | ... |
+
+## Top Findings
+
+<topFindings table — file:line, severity, agents, message>
+```
+
+### 7. Write the report and update drift state
+
+**Skip this step entirely if `--json`** (already stopped in step 6).
+
+Write the prose summary to `.dev-team-reports/repo-review.md`, creating the directory if absent, overwriting any existing file — write it even when every agent passed clean. Print `Report written: .dev-team-reports/repo-review.md` (or `(replaced previous run)` when a file already existed). A write failure (permission/read-only) is non-fatal: report `Cannot write .dev-team-reports/repo-review.md: <error>` and continue.
+
+Then, if the target was a git repository, update the drift state for next run: run `git rev-parse HEAD` and write `.claude/memory/repo-review-state.json` (creating `.claude/memory/` if absent) as `{"last_commit": "<that sha>", "last_run_at": "<current ISO 8601 timestamp>"}`, overwriting any prior state. If the target is not a git repository, skip this write — there is no commit to anchor the next drift count to.
+
+**This repository's own `.gitignore` covers that path already** (step 2's trust-boundary note relies on it). A downstream project running this skill from the plugin should add an equivalent ignore rule for `.claude/memory/repo-review-state.json` — it is a per-run, regeneratable artifact, and leaving it trackable reopens the exact commit-and-plant precondition step 2 defends against.
+
+**`--pdf`**: when passed and a report file was written this run, render it per `knowledge/report-pdf-integration.md`:
+
+```bash
+sh "$CLAUDE_PLUGIN_ROOT/hooks/py.sh" "$CLAUDE_PLUGIN_ROOT/hooks/lib/report_pdf.py" .dev-team-reports/repo-review.md
+```
+
+No-op (state the reason, do nothing else) when no report file was written this run.