pi-dev-team 0.2.0

package/docs/upstream/telemetry-ci-access.md

@@ -0,0 +1,129 @@
+# Giving CI read access to the telemetry repo
+
+To make the cost-regression gate (#171) — and any future rollup-based gate —
+enforce against **real** data, CI needs to **read** the private `agent-telemetry`
+repo and build the cross-machine rollup. This doc sets that up with least
+privilege: **read-only, single-repo, revocable**, and with no write access to
+your data.
+
+Companion docs: [`telemetry-repo-security.md`](telemetry-repo-security.md) (how
+machines *write* digests) and the watermark/sync flow in `/session-review`.
+
+## Principle
+
+- CI only ever **reads** the digest database — it never writes telemetry.
+- The credential is scoped to the **one** `agent-telemetry` repo, **read-only**,
+  and can be revoked without touching anything else.
+- The raw `~/.claude/projects` transcripts are never involved; CI consumes the
+  already-sanitized, metrics-only digest.
+
+## Recommended: a read-only deploy key
+
+A deploy key authorizes an SSH key for a **single repository**. The credential
+model — why per-repo, per-machine keys over account-wide SSH keys or classic
+PATs — is documented canonically in
+[`telemetry-repo-security.md`](telemetry-repo-security.md); the one difference
+here is that CI's key is **read-only** so it can clone but never push.
+
+### 1. Generate a dedicated keypair (locally)
+
+```bash
+ssh-keygen -t ed25519 -f ./telemetry-ci -N "" -C "agentic-dev-team CI read-only"
+# produces:  telemetry-ci  (private)   telemetry-ci.pub  (public)
+```
+
+### 2. Add the PUBLIC key to `agent-telemetry` as a read-only deploy key
+
+GitHub → `agent-telemetry` → Settings → Deploy keys → **Add deploy key**:
+
+- Title: `agentic-dev-team CI (read-only)`
+- Key: contents of `telemetry-ci.pub`
+- **Leave "Allow write access" UNCHECKED** ← this is what keeps CI read-only.
+
+### 3. Add the PRIVATE key to `agentic-dev-team` as an Actions secret
+
+GitHub → `agentic-dev-team` → Settings → Secrets and variables → Actions →
+**New repository secret**:
+
+- Name: `TELEMETRY_DEPLOY_KEY`
+- Value: contents of `telemetry-ci` (the private key)
+
+Then delete the local key files (`rm telemetry-ci telemetry-ci.pub`) — GitHub now
+holds both halves where they belong.
+
+### 4. Consume it in the workflow
+
+This wiring is **already in place** — see the `cost-regression` job in
+[`.github/workflows/plugin-tests.yml`](https://github.com/bdfinst/agentic-dev-team/blob/main/.github/workflows/plugin-tests.yml).
+The job loads the key, clones the data repo read-only, builds a per-session cost
+series from the digests, and runs the regression check against it. The
+credential steps are gated so fork PRs and Dependabot PRs (neither of which get
+secret access) skip them and fall back to the blocking self-test:
+
+```yaml
+  cost-regression:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install python3 + jq
+        run: sudo apt-get update && sudo apt-get install -y jq python3
+      # Secrets are NOT exposed to forked-PR runs, nor to Dependabot-triggered
+      # runs even when the PR isn't from a fork (see caveat) — gate on both:
+      - name: Load telemetry deploy key (read-only)
+        if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.head.repo.fork == false && github.actor != 'dependabot[bot]') }}
+        uses: webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.TELEMETRY_DEPLOY_KEY }}
+      - name: Clone telemetry (read-only) and build the cross-machine cost baseline
+        if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.head.repo.fork == false && github.actor != 'dependabot[bot]') }}
+        run: |
+          git clone --depth 1 git@github.com:bdfinst/agent-telemetry.git /tmp/telemetry
+          python3 plugins/dev-team/scripts/session_report.py --profile maintainer \
+            --cost-log /tmp/telemetry/digests -o /tmp/telemetry-cost-log.jsonl
+          echo "COST_BASELINE_LOG=/tmp/telemetry-cost-log.jsonl" >> "$GITHUB_ENV"
+      - name: Run cost-regression check (via ci-local)
+        run: bash scripts/ci-local.sh --only=chk_cost_regression
+```
+
+> Why `--cost-log` and not `--rollup`? The regression meter
+> (`cost_meter.py regression`) compares the **latest** session against the
+> rolling mean of priors, so it needs a *time-ordered per-session series*, not a
+> single aggregate. `session_report.py --profile maintainer --cost-log <digests>` emits exactly that
+> (`{"total":{"cost_usd":..}}` records, oldest→newest, deduped on `session_id`).
+> The real cross-machine check is **warn-only** — a non-deterministic meter must
+> not hard-fail an unrelated code PR.
+
+## Alternative: a fine-grained PAT (read-only)
+
+If you prefer HTTPS, use a **fine-grained** PAT — same credential model as
+[`telemetry-repo-security.md`](telemetry-repo-security.md) Option B, but scoped
+**Contents: Read-only** since CI never writes. Store it as the
+`TELEMETRY_DEPLOY_KEY` (or `TELEMETRY_TOKEN`) secret and clone via
+`https://x-access-token:${TOKEN}@github.com/bdfinst/agent-telemetry.git`. Prefer
+the deploy key — tightest scope (one repo, read-only) and no account-level
+token.
+
+## Security notes and caveats
+
+- **Read-only, by construction.** The deploy key has no write access, so a leak
+  exposes *read* of one private metrics repo — never write, never your account.
+- **Fork-PR and Dependabot-PR caveat (important).** GitHub does not expose
+  secrets to workflows triggered by pull requests from forks, and it withholds
+  the same secrets from Dependabot-triggered runs even when the PR's head
+  branch is not a fork (Dependabot PRs are treated as untrusted for this
+  purpose). So the cost gate runs on branches in this repo and on internal
+  human PRs, but **not** on fork PRs or Dependabot PRs — those fall back to the
+  mechanism self-test. For a solo/private setup this is a non-issue; documented so
+  the coverage boundary is honest.
+- **Rotation.** To rotate: generate a new key, add it, update the secret, delete
+  the old deploy key. To revoke entirely: delete the deploy key on
+  `agent-telemetry` — CI loses read access immediately, nothing else affected.
+- **Never echo the key** in workflow logs; `ssh-agent` keeps it out of the
+  environment dump.
+
+## What this unblocks
+
+- **#171** — the cost-regression gate compares each run against the real
+  cross-machine baseline instead of only self-testing the mechanism.
+- Any future gate that wants cross-machine rollup data in CI (the same clone +
+  `--rollup` pattern).

package/docs/upstream/telemetry-repo-security.md

@@ -0,0 +1,120 @@
+# Telemetry repository — security & setup
+
+The cross-machine telemetry repo (Delta D, #178) is a **private append-only
+database**, not a code repo. This doc explains how to wire it up so machines can
+write to it directly — **no pull-request toil for data** — while keeping access
+least-privilege and revocable.
+
+## The model: treat the repo like a database
+
+- **One writer-owned file per machine:** `digests/<host>/session-digest.jsonl`.
+  Because no two machines touch the same file, concurrent writes never conflict —
+  the same property a per-shard append log gives a database.
+- **Direct writes to the default branch.** Each machine does
+  `extract → commit → pull --rebase → push`. There is **no PR**, because review
+  adds toil with no security value over append-only, non-executable metric rows.
+- **Producer-enforced privacy.** The extractor emits metrics only — counts,
+  ratios, token numbers, model ids, and a project **basename** (never a path,
+  prompt, command, or code). The repo is a sink for already-sanitized data.
+
+## Repository settings
+
+Configure the data repo (e.g. `agent-telemetry`) like this:
+
+| Setting | Value | Why |
+|---|---|---|
+| Visibility | **Private** | It holds your usage metrics; never make it public. |
+| Branch protection on default branch | **Off** (no "Require a pull request before merging", no required reviews, no required status checks) | Machines push data directly; a PR gate would block every sync. |
+| Push access | **Only you / your machines** (see deploy keys below) | Least privilege. |
+| Contents | **Metrics JSONL only** | No code runs from here; keep it that way. |
+
+There is intentionally **no CI and no merge queue** on this repo — it is data, so
+the dev-team quality gates (which guard *code*) do not apply.
+
+## Authentication — least privilege, per machine
+
+Do **not** point this at your account-wide SSH key or a classic personal access
+token with `repo` scope: either would grant every machine access to *all* your
+repositories. Use one of these, scoped to **this repo only**:
+
+### Option A — per-host deploy key (recommended)
+
+A deploy key is an SSH key authorized for a **single repository**, so a machine
+that can write telemetry cannot touch anything else.
+
+```bash
+# On each machine:
+ssh-keygen -t ed25519 -f ~/.ssh/agent-telemetry -N "" -C "telemetry-$(hostname -s)"
+cat ~/.ssh/agent-telemetry.pub
+# GitHub → agent-telemetry repo → Settings → Deploy keys → Add deploy key
+#   - paste the public key
+#   - CHECK "Allow write access"
+```
+
+Point git at that key for this repo (so it isn't used for anything else):
+
+```bash
+# ~/.ssh/config
+Host agent-telemetry.github.com
+  HostName github.com
+  IdentityFile ~/.ssh/agent-telemetry
+  IdentitiesOnly yes
+```
+
+…and set the remote to that host alias:
+`git@agent-telemetry.github.com:<owner>/agent-telemetry.git`.
+
+**Revocation:** lose a laptop → delete that one deploy key. Other machines are
+unaffected, and nothing else of yours was ever exposed.
+
+### Option B — fine-grained personal access token
+
+If you prefer HTTPS: create a **fine-grained** PAT scoped to **only** the
+`agent-telemetry` repository with **Repository permissions → Contents: Read and
+write** and nothing else. Store it in a credential helper (macOS Keychain, git
+credential manager) — never in plaintext or in the repo. Prefer one token per
+machine so tokens are individually revocable.
+
+> Avoid classic PATs and broad SSH keys. The whole point is that a compromised
+> telemetry credential leaks *metrics for one repo*, not your code or account.
+
+## Configure dev-team to use it
+
+Tell the plugin where the repo is (the `/session-review` skill will prompt and
+write this for you on first run):
+
+```bash
+# Env var (highest precedence):
+export DEV_TEAM_TELEMETRY_REMOTE="git@agent-telemetry.github.com:<owner>/agent-telemetry.git"
+
+# …or the config file ~/.claude/.dev-team/telemetry.json:
+{ "remote": "git@agent-telemetry.github.com:<owner>/agent-telemetry.git" }
+```
+
+Optional keys / env vars: `clone` / `DEV_TEAM_TELEMETRY_CLONE` (local working
+clone, default `~/.claude/.dev-team/agent-telemetry`) and `host` /
+`DEV_TEAM_TELEMETRY_HOST` (label, default `hostname -s`).
+
+Then sync:
+
+```bash
+scripts/telemetry-sync.sh --check   # validate config (no network)
+scripts/telemetry-sync.sh           # extract -> commit -> pull --rebase -> push
+```
+
+## What is and isn't protected
+
+- **Protected by design:** access is per-repo and per-machine (revocable); writes
+  are conflict-free; the repo is private; only sanitized metrics ever leave a
+  machine; raw `~/.claude/projects/**` transcripts never leave.
+- **Your responsibility:** keep the repo private, keep deploy keys/tokens scoped
+  and rotated, and don't add collaborators who shouldn't see your usage metrics.
+
+## Why no PR gate is the right call here
+
+PRs exist to review *changes to code that will execute*. This repo stores
+append-only, non-executable metric rows in per-host files. A PR per sync would be
+pure toil — it cannot catch a "bug" (there is no logic), and the privacy boundary
+is enforced upstream by the extractor, not by a reviewer. So: gate the **code**
+that produces the data (the dev-team repo's CI does), and let the **data** flow
+directly into its database.

package/docs/upstream/test-evaluation.md

@@ -0,0 +1,277 @@
+# Test Evaluation and Architecture
+
+This document explains how to evaluate how an existing application is tested and design a path toward a fast, deterministic, config-free CI gate that fully validates behavior — including cross-service interaction — without standing up the rest of the system.
+
+**On this page:** [Purpose](#purpose) ·
+[Tools and Their Altitudes](#tools-and-their-altitudes) ·
+[The Evaluation Workflow](#the-evaluation-workflow) ·
+[When the Tests Aren't in the Repo](#when-the-tests-arent-in-the-repo) ·
+[Key Principles](#key-principles) · [Sample Invocations](#sample-invocations) ·
+[Reference Files](#reference-files).
+
+## Purpose
+
+The test evaluation workflow answers two questions: "how well is this application tested today?" and "what would a CD-aligned test architecture look like?" The result is an assessed gap list and a concrete migration path, not generated test code. Implementation of the migration goes to `/plan` or `/build`.
+
+---
+
+## Tools and Their Altitudes
+
+Four tools operate at different scopes. Use the one that matches what you need.
+
+| What you want | Tool | Altitude | Direction |
+|---|---|---|---|
+| Advise on how to test a specific module or hard-to-test unit | `test-design-advisor` skill | Unit / module | Forward (design) |
+| Review test files in a changeset for smells, quality, and a suite-wide Farley Score | `/test-design` | Per-file / changeset | Backward (review) |
+| Audit the whole test suite's strategy, quadrant coverage, and automation maturity | `test-health` skill | Whole suite | Strategic rollup |
+| Assess the application's test strategy against CD: per-component types, pre-merge gate determinism | `cd-test-architecture` skill | Whole application | Architecture |
+| Consolidated analyze-then-improve orchestrator — lightweight by default, opts into heavier capabilities (Gherkin, mutation, refactor-for-testability) only when asked; always baselines before changing tests; ships a 10-section executive-summary report | `/test-improve` | Whole repository | Remediation |
+
+**`test-design-advisor`** works at the module level: assess testability blockers, place each behavior on the pyramid, choose the right test double, and produce a behavior-preserving refactor sequence to introduce seams. It does not write tests. **Vocabulary is locked to MinimumCD** (static analysis / unit / component / contract / integration / E2E); prefer "contract test" over "narrow integration test" and gloss the alias once if it must be used. **The pyramid is a cost heuristic, not a target shape** — the advisor never emits "current shape vs recommended shape" tables or per-layer target counts; placements are per-behavior with a two-direction justification (why not the layer above or below). Any E2E placement must satisfy the [E2E justification gate](#the-e2e-justification-gate).
+
+**`/test-design`** is the orchestrator command for the changeset-level workflow. It dispatches `test-review` (tactical quality: missing assertions, non-determinism mechanics, mock hygiene) and `test-smell-review` (design-level smells: xUnit smell taxonomy, double selection, pyramid placement) in parallel, scores **every existing test in the suite** with the **Farley Score** (via the `farley-score` skill — 8 properties, weighted 1–10), then optionally runs `test-design-advisor` for production code that has no tests or hard-to-test units. The aggregated report carries the headline Farley score independent of the changeset scope.
+
+**`test-health`** is the **strategic-altitude** rollup over the whole repository. It maps coverage to the Agile Testing Quadrants, evaluates the suite's shape against the architecture, rolls up automation maturity and flaky-test signals, and produces an ordered improvement plan. It **delegates rather than re-derives**: CD-determinism + pipeline placement come from `cd-test-architecture`, per-file findings + Farley Score come from `/test-design`, assertion strength on critical-logic modules comes from `mutation-testing`. Use this for "audit our tests" / "test strategy review" / "is our testing healthy?".
+
+**`cd-test-architecture`** works at the application level: inventory components and test suites, classify against the six MinimumCD test types, identify CD-fitness gaps, recommend a per-component target architecture (with the [E2E justification gate](#the-e2e-justification-gate) applied to every E2E recommendation), and produce a migration path. It does not write tests or edit code.
+
+**`/test-improve`** is the **consolidated remediation altitude** — a ten-phase (0-9) orchestrator (approach contract → baseline → optional Gherkin → analyze → plan fixes → improve-without-refactoring → refactor decision → optional refactor-for-testability → validate → executive-summary report). It defaults to lightweight ceremony (mutation off, BDD `none`, no-refactor) and prompts for heavier capabilities on demand. Phase 1 (Analyze) delegates the entire analysis to `/test-health`, which in turn folds in `cd-test-architecture` (advisory), `/test-design`, and `mutation-testing` — Phase 1 runs after Baseline and Derive Gherkin so `/test-health` can use documented-but-untested Gherkin scenarios as a coverage signal. See the workflow diagram in [Architecture](agent-architecture.md#test-improvement-workflow-test-improve).
+
+**How they compose.** Start at the altitude that matches the question. `test-health` calls `/test-design`, `cd-test-architecture`, and `mutation-testing` internally — when the question is strategic, do not dispatch the lower-altitude tools yourself. `/test-design` calls `test-design-advisor` internally when `--advise` applies. `/test-improve` delegates its entire Phase 1 (analyze) to `/test-health` — when the question is "how do we get from this assessment to passing CD gates?", start with `/test-improve` and let it dispatch the analysis itself. When two altitudes plausibly fit, prefer the higher one and let it delegate down.
+
+---
+
+## The Evaluation Workflow
+
+The `cd-test-architecture` skill follows these steps. Run it with `/cd-test-architecture <path>`.
+
+### Step 1: Inventory the application's components
+
+Map each deployable or testable surface and assign it a pattern from `knowledge/component-test-patterns.md`:
+
+- **UI** — User Interface
+- **Services** — API Provider, API Consumer, Event Consumer, Event Producer, Stateful Service, CLI/Library
+- **Batch** — Scheduled Job
+
+A real system is usually several of these. Each surface is assessed separately.
+
+### Step 2: Inventory and classify existing tests
+
+Find every test suite in the repo. For each, record: MinimumCD type, what it actually exercises, whether it is deterministic, and what it requires to run (DB URL, broker, downstream service, secrets, sleep, real clock).
+
+If in-repo tests are sparse, the application is not necessarily untested — see Step 2b (locate and harvest out-of-repo tests) before concluding.
+
+### Step 2b: Locate and harvest out-of-repo tests
+
+When `--external-tests <path-or-repo-or-description>` is given, treat the external location as the current specification of intended behavior:
+
+- **Other-repo suites** — read and classify just like in-repo tests; note they can't gate this component's merges.
+- **Postman/Insomnia/`.http` collections** — extract each request + assertion as an API contract and scenario.
+- **Manual scripts or spreadsheets** — extract each step as a behavior to automate.
+
+This produces a behavior inventory that becomes the basis for improvement, not the destination.
+
+### Step 3: Diagnose CD-fitness gaps
+
+Flag, with evidence:
+
+- Out-of-repo or third-party-runner testing (anti-pattern — see below)
+- Manual / non-repeatable testing
+- Tests mistyped as "unit" that require real dependencies
+- Configured-dependency tests that can't run in a clean CI gate
+- Coverage gaps (success + failure modes not covered at any deterministic layer)
+- Doubles with no validation loop (drift risk)
+- No consumer resilience tests (the component assumes the provider holds)
+- Inverted pyramid shape (integration/E2E doing what component tests should)
+
+### Step 4: Recommend the target architecture
+
+Per component: which test types cover which layers, what to double to run pre-merge without configuration, which success scenarios and failure modes to cover, the double-validation loop, and the pipeline stage for each test type (pre-merge gate, Stage 1/2, out-of-band, or post-deploy).
+
+The recommendation applies the [E2E justification gate](#the-e2e-justification-gate) to every E2E test. The pyramid is treated as a cost heuristic — no per-layer target counts are recommended; if the shape is pathological (ice-cream cone, hourglass, cupcake), the pathology and the behaviors that suffer from it are named, not a numeric redistribution.
+
+### Step 5: Produce a migration path
+
+Ordered lowest-risk first, each step independently shippable. The spine is **baseline before refactor**: get behavior under test at existing seams *without changing code*, then refactor under that green baseline. When tests are out-of-repo, the harvested behaviors feed that baseline. Typical full sequence:
+
+1. **Characterization baseline (no refactoring)** — outside-in tests at the outermost reachable seam that lock in current behavior; reproduce any harvested out-of-repo/manual behaviors here. Get green.
+2. Introduce owned adapters and seams **under the baseline** (DDD skills suggest where boundaries belong)
+3. Add in-memory doubles + component tests reproducing the baselined behaviors
+4. Add contract tests pinning request/response boundaries
+5. Add consumer resilience tests (verify the component survives a provider break)
+6. Add scheduled provider-contract verification against a test environment
+7. Move real-dependency tests off the gate to adapter integration or out-of-band
+8. Add post-deploy checks
+9. Decommission out-of-repo/manual suites and the coarse characterization tests as their behaviors land in the deterministic gate
+
+### Step 6: Report
+
+Output goes to `.dev-team-reports/cd-test-architecture-<app>.md`. Tables, not prose: components and patterns, current tests and their CD-fitness, gaps, target architecture, pre-merge gate composition, migration path, next steps.
+
+---
+
+## When the Tests Aren't in the Repo
+
+An application may have little or no in-repo testing and instead be covered by suites in another repo, a third-party runner, Postman or Insomnia collections, or manual scripts. This is an **anti-pattern** regardless of how thorough the external coverage is:
+
+- The tests **cannot gate the component's own merges** — the build can go green while behavior is broken.
+- The tests are **not versioned with the code** they verify; a code change and its test change can't move together.
+- External suites are usually **non-deterministic and environment-coupled**, so they could never serve as a pre-merge gate anyway.
+- **Manual scripts are not repeatable** — they're a checklist, not a regression net.
+
+This does not mean the external coverage is worthless. It is the **current specification of intended behavior** — the best available basis for improvement.
+
+To include it in the assessment, point the skill at it:
+
+```
+/cd-test-architecture <path> --external-tests <postman-collection.json>
+/cd-test-architecture <path> --external-tests <path-to-other-repo>
+/cd-test-architecture <path> --external-tests "manual regression scripts in Confluence, linked here: ..."
+```
+
+The skill harvests those sources as a behavior inventory (Step 2b — locate and harvest out-of-repo tests) and builds the migration path around re-expressing each behavior as a deterministic, in-repo, gated test:
+
+| External source | Re-expressed as |
+|---|---|
+| Postman request + assertion | Component or contract test |
+| Manual UI script | UI component test (real browser, network stubbed) |
+| Other-repo E2E covering this component | In-repo component test + thin post-deploy smoke |
+
+Each external case is decommissioned once its behavior lands in the gate.
+
+If in-repo tests are sparse but no `--external-tests` location is given, the skill will **ask** where the application is actually tested before drawing any conclusions.
+
+---
+
+## Key Principles
+
+### Pre-merge gate: deterministic tests only
+
+The gate that blocks a merge may contain **only** static analysis, unit, component, and contract tests. These are deterministic and need nothing configured. Integration and end-to-end tests are non-deterministic by nature and never gate a merge. A test that needs a database URL, broker, downstream service, or environment secrets to run is mis-typed — re-classify or convert it.
+
+The corollary is that E2E is the last resort, not a quota. The [E2E justification gate](#the-e2e-justification-gate) ensures recommendations don't propose E2E "for completeness" or "to round out the pyramid" — if a contract, component, or resilience test can cover a behavior, that's where it goes.
+
+### The E2E justification gate
+
+This is the single rule every tool and workflow step below applies to any E2E recommendation. An E2E test is recommended **only** when all four conditions hold:
+
+1. A contract test cannot pin the boundary.
+2. A component test with doubles cannot exercise the behavior.
+3. A resilience test cannot cover the failure mode.
+4. The behavior is a critical multi-component user journey.
+
+An E2E recommendation that fails any of (1)–(3) is replaced with the cheaper layer that *can* cover it. **E2E is never a pre-merge gate.**
+
+### Run CI without configuring dependencies
+
+The component test is the workhorse of a CD gate. The pattern is consistent across every component type:
+
+1. Assemble the **real component** — actual handlers, domain logic, orchestration — in-process.
+2. Replace only what the team doesn't control with **in-memory doubles**: in-memory repository for the database, in-memory bus for the broker, stubbed adapter for downstream services, injected fixed clock.
+3. Drive it through its **public interface** — HTTP handlers, message handler, job entrypoint, UI via a real browser with the network stubbed.
+4. Assert **observable outcomes** — status, persisted state, emitted event, rendered output — never internal call sequences.
+
+The result: fast (no I/O), deterministic (no real systems, controlled clock), zero configuration of the surrounding system — while still validating real behavior end-to-end within the component boundary.
+
+### The adapter rule
+
+Wrap every third-party client (SDK, HTTP client, broker client, DB driver) in a thin adapter the team owns. Double the adapter in component tests — never mock the third-party SDK directly. Adapter integration tests then exercise the real adapter against a real container to confirm the adapter's correctness.
+
+### Do not depend on provider cooperation
+
+Consumer-driven contract verification where the provider runs your contract in their pipeline only works with close collaboration and enforced tooling. Assume you do not have that. The defense you own:
+
+1. **Contract tests** (pre-merge) pin the request you send and the response shape you depend on, against the adapter double.
+2. **Scheduled provider-contract verification in a test environment** — you run your pinned contract against the provider's real non-prod endpoint on a schedule, out-of-band, owned by your team. This detects a provider break when it happens, not at your next unrelated deploy.
+3. **Resilience component tests** (pre-merge) verify the consumer survives a broken contract: timeouts enforce, retries and circuit breakers behave, malformed responses are handled, the caller gets a documented response with no partial state.
+
+Provider-side verification of your contract is a bonus if they offer it — not the mechanism to rely on.
+
+### Baseline before refactor (legacy code)
+
+Legacy code is code without tests (regardless of age). When a component is poorly tested, **do not lead with refactoring**:
+
+1. **Find the testable seams** — places where behavior can be observed or substituted without editing the code (HTTP handler, CLI entrypoint, message handler, exported function, existing injection points).
+2. **Write the best outside-in tests achievable now, without refactoring** — characterization tests at the outermost reachable seam that lock in current behavior. This is a behavior baseline, not yet a clean gate.
+3. **Get the baseline green** — your safety net.
+4. **Refactor to improve testability under green** — introduce adapters and seams, push checks down to deterministic component/unit tests. Never change behavior and structure in the same step.
+5. **Let the domain guide the target** — the `domain-driven-design` and `domain-analysis` skills suggest where boundaries and seams should land.
+
+The mechanics live in the [`legacy-code`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/legacy-code/SKILL.md) skill; this workflow places it in the CD test architecture. An assessment of an under-tested component therefore returns two things: the outside-in baseline writable today, and the refactor sequence that improves testability afterward.
+
+---
+
+## Sample Invocations
+
+```bash
+# Full application assessment
+/cd-test-architecture ./src
+
+# Scope to one component
+/cd-test-architecture ./src --component payment-service
+
+# Include existing CI config in the assessment
+/cd-test-architecture ./src --ci .github/workflows/ci.yml
+
+# Application tested primarily via Postman collections
+/cd-test-architecture ./src --external-tests ./test-collections/api-tests.postman_collection.json
+
+# Application tested in another repo
+/cd-test-architecture ./src --external-tests "../qa-repo/e2e/payment-service"
+
+# Per-file / changeset review + suite-wide Farley Score (current working tree or staged changes)
+/test-design
+
+# Per-file review scoped to a directory
+/test-design --path src/payments
+
+# Per-file review of changes since a branch
+/test-design --since main
+
+# Force the advisor to run (also auto-triggers when production code has few/no tests)
+/test-design --advise
+
+# Unit/module design advice (advisory — does not write tests)
+# The test-design-advisor worker skill is dispatched via /test-design; a
+# single-file target auto-fires the advisor.
+/test-design --advise --path src/payments/PaymentProcessor.ts
+
+# Strategic suite-wide audit — delegates to cd-test-architecture, /test-design, and mutation-testing
+/test-health
+/test-health --path src/payments
+
+# Assertion strength on critical-logic modules
+/mutation-testing
+```
+
+---
+
+## Reference Files
+
+| File | What it defines |
+|---|---|
+| [`agents/qa-engineer.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/qa-engineer.md) | The Senior SDET agent that routes strategic test requests to these skills |
+| [`agents/test-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/test-review.md) | The tactical per-file test-quality review agent |
+| [`agents/test-smell-review.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/agents/test-smell-review.md) | The smell-detection review agent |
+| [`knowledge/cd-test-architecture.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/cd-test-architecture.md) | Six MinimumCD test types, the pre-merge gate rule, out-of-repo anti-pattern, component test pattern, adapter rule, double validation, determinism techniques |
+| [`knowledge/component-test-patterns.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/component-test-patterns.md) | Per-component patterns: UI, API Provider, API Consumer, Event Consumer, Event Producer, Stateful Service, CLI/Library, Scheduled Job |
+| [`knowledge/database-test-patterns.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/database-test-patterns.md) | Database test isolation + teardown: Database Sandbox, Transaction Rollback / Table Truncation Teardown, Fake-first rule for data-logic tests |
+| [`knowledge/dependency-breaking-techniques.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/dependency-breaking-techniques.md) | Feathers' full 24-technique catalog for getting legacy code under test (behavior-preserving seams, seam type + risk) |
+| [`knowledge/legacy-test-strategy.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/legacy-test-strategy.md) | Where to test legacy code: effect reasoning, effect sketches, interception/pinch points; plus editing-safety techniques |
+| [`knowledge/microservice-testing.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/microservice-testing.md) | Contract and CDC testing across independently-deployable services |
+| [`knowledge/test-automation-maturity.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/test-automation-maturity.md) | Maturity ladder consumed by `test-health` for the strategic rollup |
+| [`knowledge/test-automation-principles.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/test-automation-principles.md) | Goals + named Principles of Test Automation — the rubric for *why* a test is good or bad; grounds smell severity |
+| [`knowledge/test-doubles.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/test-doubles.md) | Dummy / stub / spy / mock / fake selection, Configurable vs. Hard-Coded form, Test-Specific Subclass, state-vs-behavior verification |
+| [`knowledge/test-matrix-examples/`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/test-matrix-examples/) | Worked, stack-specific placement matrices the advisor adapts (Spring Boot, Django batch, React/Node SPA, SSR + HTMX, .NET API fronting gRPC) |
+| [`knowledge/test-pyramid.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/test-pyramid.md) | Pyramid layer responsibilities and shape anti-patterns |
+| [`knowledge/test-smells.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/test-smells.md) | xUnit smell taxonomy: code, behavior, and project smells |
+| [`knowledge/testing-quadrants.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/testing-quadrants.md) | Agile Testing Quadrants — what each quadrant protects; consumed by `test-health` |
+| [`knowledge/value-patterns.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/knowledge/value-patterns.md) | Test-data sourcing: Literal / Derived / Generated Value + Dummy Object |
+| [`skills/cd-test-architecture/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/cd-test-architecture/SKILL.md) | The application-level assessment skill |
+| [`skills/domain-driven-design/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/domain-driven-design/SKILL.md) | Suggests target boundaries/seams for the post-baseline refactor |
+| [`skills/legacy-code/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/legacy-code/SKILL.md) | Characterization testing + dependency-breaking: the baseline-before-refactor procedure |
+| [`skills/mutation-testing/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/mutation-testing/SKILL.md) | Assertion-strength check (do tests catch real bugs?); folded into `test-health` |
+| [`skills/test-design/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/test-design/SKILL.md) | The `/test-design` orchestrator skill — dispatches review agents, scores with Farley, optionally invokes the advisor |
+| [`skills/test-design-advisor/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/test-design-advisor/SKILL.md) | The unit/module design advisor skill |
+| [`skills/farley-score/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/farley-score/SKILL.md) | Farley Score — Dave Farley's 8 properties scored 1–10, called by `/test-design` Step 3 (Score the in-scope tests via Farley Score) |
+| [`skills/test-health/SKILL.md`](https://github.com/bdfinst/agentic-dev-team/blob/main/plugins/dev-team/skills/test-health/SKILL.md) | Strategic suite-wide rollup; delegates to `cd-test-architecture`, `/test-design`, `mutation-testing` |