apply-test-doubles

# Apply Test Doubles Role: worker. Applies `../cd-test-architecture/SKILL.md`'s Step 4b build-vs-document decision logic against a resolved report — one already saved on disk, or a fresh one produced by assessing a target — without re-running the full Steps 0-6 assessment when a valid report already exists. You have been invoked with the `/apply-test-doubles` command. ## Parse Arguments Arguments: an optional positional `<report-path-or-target>`, an optional `--component <name>`, and an optional `--yes`. - `<report-path-or-target>` — a path to a previously saved `/cd-test-architecture` report, or a target application/repo path to assess when no such report exists yet. May be omitted entirely — see the absent-path row below. - `--yes` — run non-interactively: this step's own re-entrant Step 4b prompt (Step 2) is skipped, per `human-oversight-protocol`'s `--yes` / `DEV_TEAM_AUTO_APPROVE=1` / no-TTY convention — see Step 2 for the exact per-component behavior. - `--component <name>` — scope processing to one named component. Applied as a post-hoc filter over the resolved report's already-existing rows, identically on both paths — **never** forwarded as `cd-test-architecture`'s own `--component` argument on the target path. A single-component-scoped target-path assessment can legitimately produce no report **file** at all (`cd-test-architecture`'s Output is `.dev-team-reports/cd-test-architecture-<app>.md`, "or chat for a single component"), which would leave this skill's own fast path with nothing to read — so the target-path self-invocation always assesses the full target, and `--component` narrows the result afterward, identically to the fast path. ## Steps ### 1. Resolve report or target Every invocation resolves to exactly one **report** before anything else in this skill runs — either an existing one read directly (the fast path), or a fresh one produced by assessing a target (the target path). This is one branch point, not two independently-described procedures: whichever state below applies, resolution ends at the same "read the report" step. **Resolution states:** | `<report-path-or-target>` | Resolves to | Path | |---|---|---| | Absent | the current repo, passed to `/cd-test-architecture` as an explicit resolved cwd/repo path argument — never a bare invocation, which would trigger `cd-test-architecture`'s own interactive target prompt | target | | Given, non-empty, resolves to no file or directory on disk | the given string, passed to `/cd-test-architecture` as its explicit target argument | target | | Given, resolves to an existing directory | the given directory, passed to `/cd-test-architecture` as its explicit target argument — a directory is not a report; there is no file there to read | target | | Given, resolves to an existing file | that file, checked against the structural validity check below | fast (if valid) / target (if not) | **Target path.** Invoke `/cd-test-architecture` against the resolved target (current repo / given string / given directory) — a full-target assessment, never scoped by `--component` at invocation (see Parse Arguments above for why) — always forwarding `--yes` so its own inline Step 4b prompt never fires; this skill's own re-entrant Step 4b step (a later step of this skill) is the sole place the operator is prompted, on both paths uniformly. `cd-test-architecture`'s own error handling governs an unresolvable target string; this skill does not duplicate that validation. Resolve the fresh report at `.dev-team-reports/cd-test-architecture-<app>.md`, per `../cd-test-architecture/SKILL.md`'s own Output Path rule (cited, not restated), then proceed through the fast path below exactly as an existing report would — including the `--component <name>` filter, applied post-hoc there. **Structural validity check (existing-file case only).** A real `cd-test-architecture` report carries three markers, checked together as one cohesive procedure — not three independently-worded checks that could drift out of sync with each other: 1. The `# CD Test Architecture` title line. 2. The `### Target architecture (per component)` heading — level 3, with the `(per component)` suffix. 3. A `Build/Document status` column in that section's table. All three present → the fast path: read that report's Target architecture table directly, and do not invoke `/cd-test-architecture`. Missing any one of the three takes the target path too, treating the file's path string as a target to assess — not a malformed-report error. **Fast path: locate the companion setup guide.** Locate the companion setup-guide artifact (`.dev-team-reports/cd-test-architecture-<app>-test-double-setup.md`, #1436) via the resolved report's own `**Target**` header field — the `<app>` value recorded in the report's content — never by the report file's name on disk, so a renamed or relocated report still resolves its companion file correctly. This intentionally differs from how `cd-test-architecture` itself names the companion file at write time (from the main report's own filename, per `../cd-test-architecture/SKILL.md`'s Path rule): that skill always knows the filename it is about to give the main report, so deriving from it is reliable; this skill instead reads a report whose file may have been renamed or relocated since it was written, so it cannot trust the on-disk filename and must recover `<app>` from content instead. **Before interpolating `<app>` into a path, slugify it** (strip or reject `/`, `\`, `..`, and a leading `~`) and confirm the resulting path still resolves inside `.dev-team-reports/`; if it would not, treat the companion file as not found (the non-error cases below) rather than writing outside that directory. When no companion file is found at the derived path, state plainly which of two non-error cases applies: - The resolved report's Target architecture table has zero off-gate-eligible rows (no row with a non-blank `Build/Document status` cell) — nothing was ever expected to be written for this report; take no further action. - The report has eligible rows but predates #1436 (no companion file was ever written for it) — state this plainly, then create the setup-guide artifact fresh at the derived path, exactly as `cd-test-architecture` itself would on a first run. ### 2. Apply Step 4b's decision logic This step is the **only** place a decision is made this invocation, regardless of which path produced the resolved report: - **Fast path** — Steps 0, 1, 2, 2b, 3, 3b, 4, 5, and 6 never ran at all this invocation; the resolved report was already sitting on disk and was read directly, including Step 4's own recommendations — this step reads what Step 4 already concluded, it does not re-derive it. - **Target path** — those same steps did run, as part of producing the fresh report (the `/cd-test-architecture` self-invocation in Step 1 above), but their own inline Step 4b was a no-op — every row defaulted to `Document-only` with no prompt — because Step 1 already forwards `--yes`. This step is still the first and only place the operator is actually prompted. **Cite, don't restate — the one architecturally significant decision in this skill, made explicit so it survives independent of any one plan document.** Apply exactly the decision procedure in `../cd-test-architecture/SKILL.md`'s `### 4b. Build-vs-document decision (off-gate adapter test doubles)` heading — its Database-specific branch, its Downstream-service branch, and that branch's library-vs-hand-rolled sub-question — as the single source of the build-vs-document branching rules. That procedure is not restated here. This citation was chosen over physically relocating Step 4b's content into a shared file: Step 4b's already-reviewed, multi-branch prose (its Database-specific branch, Downstream-service branch, and their sub-question) would otherwise need extracting into a new home touching every existing `cd-test-architecture` test file, for a purely organizational move this skill's actual scope doesn't require; citing it in place fully satisfies "don't duplicate the branching rules" without that blast radius. **Off-gate-eligibility parsing rule — cited from `cd-test-architecture`'s own Output section, not independently derived.** `../cd-test-architecture/SKILL.md`'s Target architecture table documentation states that a row's `Build/Document status` cell is set to one of the three enum values only for a row Step 4 flagged as needing an off-gate adapter test double; an unflagged row carries no value in that cell at all. A component is therefore off-gate-eligible **iff** it has at least one Target architecture row with a non-blank `Build/Document status` cell — this skill cites that blank-vs-set convention rather than asserting it as an independent rule. **Every eligible component is re-offered, regardless of prior status.** Every off-gate-eligible component is re-offered this decision on every run, regardless of its currently-recorded `Build/Document status` — including a component already resolved to `Build (testcontainers)` or `Build (Fake)` — so the operator may change a prior decision. **`--component <name>` scoping.** When `--component <name>` was given and it matches an off-gate-eligible component (per the parsing rule above), only that component's row resolves through this decision — no other component's row is touched. When no `--component` was given, every off-gate-eligible component in the resolved report is processed in one batched pass, mirroring Step 4b's own batching rule (cited, not restated). **Unmatched or non-eligible `--component <name>`.** Two distinct cases, both stated by the exact name given, with no action taken — never a fuzzy or nearest-match substitution: 1. `<name>` does not appear anywhere in the resolved report's Target architecture table — state that `<name>` was not found in the resolved report, and take no further action. 2. `<name>` appears in the report but has no Target architecture row with a non-blank `Build/Document status` cell — state that `<name>` has no build-vs-document decision to apply, and take no further action. **Zero eligible components.** Same family of outcome as the two cases above, just with no `--component` name to name: when the batched pass (no `--component`) or the named lookup (`--component <name>`, once past the unmatched/non-eligible check above) finds no off-gate-eligible component, state that there is nothing to apply and take no further action. **Non-interactive behavior for this step's own prompt.** Per `human-oversight-protocol`'s `--yes` / `DEV_TEAM_AUTO_APPROVE=1` / no-TTY convention (the same convention `cd-test-architecture`'s own Step 4b documents at its Parse Arguments section): under any of those conditions, surface no prompt for this step either. A component with **no prior recorded decision** defaults to `Document-only`, exactly mirroring what a non-interactive `cd-test-architecture` run would have produced; a component with an **existing recorded decision** is left exactly as recorded, not silently re-resolved to `Document-only` — this step never reports an outcome that contradicts what the report already says. Either way, no Story is proposed and no report write-back happens (see Step 3) for a component this run did not actually decide. **Version-skew advisory (non-blocking).** Resolve the currently installed plugin version with the same resolver `/version` already uses: ```bash sh "$CLAUDE_PLUGIN_ROOT/hooks/py.sh" "$CLAUDE_PLUGIN_ROOT/hooks/lib/plugin_version.py" ``` This prints one line on success, e.g. `dev-team@bfinster v10.4.0 (scope: user)` — parse the version out of the token between `v` and ` (scope:` (here, `10.4.0`). If the resolver instead exits non-zero (plugin not installed, or the install record is missing/malformed), prints nothing, or the parsed value is the literal `unknown` (its own fallback when the version field is absent), emit no advisory and proceed silently — never fabricate a comparison from a value the resolver itself couldn't resolve. Otherwise, compare the resolved version against the resolved report's Provenance `` `dev-team` plugin version `` field (exact field name and formatting per `knowledge/report-template.md`'s Provenance section). If they differ, emit one non-blocking advisory line naming both versions — e.g. "this report was generated by dev-team vX.Y.Z; you're running vA.B.C — Step 4b's decision logic may have changed since this report was written." — before applying Step 4b's current logic, then proceed unchanged. This never blocks or alters the decision logic itself. ### 3. Dispatch `cd-test-architecture` is advisory only (its own Constraints: "it proposes a downstream Story, it never invokes `/build` or edits code directly") — Step 4b's live invocation proposes a Story within its own report/chat output (Step 6's only documented output channel), never as a separate file. This step's dispatch mechanics match that exactly, plus one write-back this skill's own premise requires that Step 4b's live invocation has no reason to need: 1. **Write back the resolved report's `Build/Document status` cell** for each component this run resolved, updating the on-disk report in place so it reflects the new decision — matching the **full cell contract** `../cd-test-architecture/SKILL.md`'s Output section defines (cited above), not just the enum value: a `Build (Fake)` write carries that branch's caveat verbatim in the same cell (the hand-rolled or library-backed variant, per the Downstream-service branch, cited not restated), and when the library-vs-hand-rolled sub-question resolves a tool, the `Double (to run config-free)` column is updated to name it, per the Output section's own tool-citation rule. A row reverting to `Document-only` or `Build (testcontainers)`, or a `Build (Fake)` row whose sub-question now resolves to hand-rolled, has any previously-written caveat text removed from the status cell **and** any previously-cited tool name removed from the `Double (to run config-free)` column — both cells always reflect only the current decision, never a stale one layered under it. Without this write-back, the report and any Story proposed below would disagree about what was just decided, and the next `/apply-test-doubles` run against the same report would re-read the stale status. This write-back is unique to this skill: Step 4b's live invocation writes the cell once, at report-creation time, and never needs to revise it. If the write fails (permission, read-only path), state that plainly and surface the resolved decisions in chat instead — per `knowledge/report-output-location.md`'s non-fatal-write convention, never proceed as if the write succeeded. The report's own header and Provenance block (`knowledge/report-template.md`) are deliberately left untouched by this write-back — they continue to describe the original assessment run, not this later revision; the version-skew advisory (Step 2) compares against that same original-run Provenance value on every subsequent invocation, which stays meaningful since a write-back only ever changes a recorded outcome, never Step 4b's own decision logic. 2. **For a component resolving to a Build outcome, propose a Story** — rendered as output text, using exactly the title and description conventions `../cd-test-architecture/SKILL.md`'s Database-specific branch and Downstream-service branch already define (cited from Step 2's own citation above, not restated here). This is advisory only, identical in kind to Step 4b's own live invocation — it never invokes `/build` or writes a Story file itself. 3. **The setup-guide artifact (#1436)'s per-component *inclusion* is independent of this decision; its *Classification* is not.** `../cd-test-architecture/SKILL.md`'s Companion section states a component's section is included regardless of whether the operator chose Document-only for it (cited, not restated) — this step never adds or removes a section on that basis. But that same section's Classification is keyed to the resolved Build variant and, for a Downstream-service `Build (Fake)` row, the library-vs-hand-rolled sub-question's answer (cited from the Companion section's own Classification rule, not restated) — both of which Step 2 explicitly lets the operator change. When this run changes a component's Classification (e.g. `Build (testcontainers)` ↔ `Build (Fake)`, or a different library resolves than the guide currently records), re-emit that component's setup-guide section per the Classification rule so the guide never names a tool the report no longer recommends. A component whose Classification is unchanged this run has its setup-guide section left as-is. 4. **This proposed Story is advisory chat/report output only — there is no automated materialization path today, the same as Step 4b's own live invocation.** `../issues-from-assessment/SKILL.md` derives its own Stories directly from the Target architecture table (one per (component, layer), per its own Step 2), independent of the Build/Document decision or this step's proposed Story text — it is not a consumer of what this step just proposed, and this skill does not invent a second materialization mechanism to bridge that gap. An operator who wants this proposed Story tracked creates it themselves from the proposed text, exactly as they would from a live `cd-test-architecture` run. **Single ready-to-run command.** Invocation is exactly `/apply-test-doubles <path>` — `--component <name>` is the only other **scoping** argument (`--yes`, per Parse Arguments, controls interactivity, not scope), matching what #1436's setup-guide artifact already emits with the real path filled in. No other argument is ever required.