pi-dev-team 0.2.0

package/knowledge/references/csharp-http-client-testing.md

@@ -0,0 +1,264 @@
+# C# HTTP client testing — fast, deterministic, pre-merge
+
+Reference for testing a .NET service's **outbound** HTTP layer (`HttpClient`,
+the **API Consumer** side of `knowledge/component-test-patterns.md` →
+*API Consumer*). The canonical seam is `HttpMessageHandler`. The hand-rolled
+stub implementation of that seam (below) makes the HTTP layer a pure
+function of inputs: no sockets, no ports, no Kestrel, microsecond-fast,
+bit-for-bit reproducible. WireMock.Net (see "WireMock.Net — the preferred
+pre-merge double when installed" below) fills the same seam through a real
+loopback HTTP server instead — same DI injection point, different traffic
+shape; see that section for the honest trade-off.
+
+This is the .NET realization of the **Adapter Rule** from
+`knowledge/cd-test-architecture.md#the-adapter-rule-own-your-boundaries`:
+wrap each third-party HTTP API in a thin team-owned adapter, then double the
+adapter (or its `HttpMessageHandler`) in component and contract tests.
+
+For testing the **inbound** HTTP surface (your own ASP.NET Core endpoints — the
+API Provider side), use `WebApplicationFactory<TEntryPoint>` instead; see
+`knowledge/test-stack-profiles/dotnet.md` → Component / Service row. This
+reference is for the *outbound* direction.
+
+## The core pattern: stub HttpMessageHandler
+
+`HttpClient` delegates every request to its `HttpMessageHandler.SendAsync`.
+Subclass `HttpMessageHandler` (or `DelegatingHandler`) and return canned
+responses keyed off the incoming request. The whole transport stack
+collapses to a function `HttpRequestMessage -> HttpResponseMessage`.
+
+```csharp
+public sealed class StubHttpMessageHandler : HttpMessageHandler
+{
+    private readonly Func<HttpRequestMessage, CancellationToken, Task<HttpResponseMessage>> _handler;
+    public List<HttpRequestMessage> Requests { get; } = new();
+
+    public StubHttpMessageHandler(
+        Func<HttpRequestMessage, CancellationToken, Task<HttpResponseMessage>> handler)
+        => _handler = handler;
+
+    protected override Task<HttpResponseMessage> SendAsync(
+        HttpRequestMessage request, CancellationToken ct)
+    {
+        Requests.Add(request);
+        return _handler(request, ct);
+    }
+}
+```
+
+Inject via `new HttpClient(handler) { BaseAddress = ... }` into the
+adapter under test. The captured `Requests` list is the spy surface for
+request-shape assertions; the handler delegate is the stub surface for
+response control.
+
+## Wiring with IHttpClientFactory (production parity)
+
+When the production code uses `IHttpClientFactory` / typed clients (the
+recommended .NET pattern since 2.1), preserve the DI graph and swap only the
+leaf handler:
+
+```csharp
+services.AddHttpClient<UserClient>(c => c.BaseAddress = new Uri("https://api.test/"))
+        .ConfigurePrimaryHttpMessageHandler(() => stubHandler);
+```
+
+Same `HttpClient` lifetime, same delegating-handler chain (auth, logging,
+retry), only the bottom of the stack changes. This keeps tests honest about
+the middleware that production runs.
+
+## What to assert (drive from the contract, not the internals)
+
+A consumer's contract is two-sided: the *request it builds* and the
+*response shape it depends on*. Assert both, structurally:
+
+- **Request shape** — method, path, query string, headers, body. Deserialize
+  JSON bodies and compare structurally; never string-match request bodies
+  (whitespace, member ordering, and culture-formatted numbers all flake).
+- **Response handling** — success deserialization (including optional and
+  unknown fields per Postel's Law), non-2xx → typed exceptions, empty
+  bodies, malformed JSON, content-type mismatches.
+- **Cross-cutting** — auth headers, correlation/idempotency keys,
+  trace-context propagation, cancellation propagation, deadline/timeout
+  enforcement.
+- **Retry sequences** — queue a deterministic sequence
+  (e.g. `503, 503, 200`); assert the request count and the final outcome.
+
+Map these onto the API Consumer success/failure list in
+`knowledge/component-test-patterns.md#api-consumer` — the patterns there are
+the source of truth for *what* to cover; this file is *how* to cover it on
+.NET.
+
+## Keep it deterministic
+
+Two recurring sources of flake in HTTP-client tests:
+
+- **Time.** Inject `TimeProvider` (built-in since .NET 8) — never call
+  `DateTime.UtcNow`, `DateTimeOffset.Now`, or `Task.Delay` directly in
+  application logic. In tests, drive `FakeTimeProvider` (from
+  `Microsoft.Extensions.TimeProvider.Testing`) forward explicitly. Mirrors
+  the determinism rule in
+  `knowledge/cd-test-architecture.md#determinism-techniques-minimal-tooling`.
+- **Polly jitter / backoff.** When the adapter uses Polly (the .NET resilience
+  pipeline) for retry, circuit-breaker, or timeout, configure the pipeline
+  with the **same** `TimeProvider`. Polly v8 accepts `TimeProvider` directly
+  in its `ResiliencePipelineBuilder` — retries then advance *virtual* time,
+  not wall-clock, so a "wait 30s then retry" policy completes in
+  microseconds without `Thread.Sleep`.
+
+Combined with the stub handler, the entire outbound HTTP layer — including
+retries, timeouts, and circuit-breakers — is a pure function of inputs.
+
+## Testing Polly resilience policies deterministically
+
+This is the canonical setup for the consumer-resilience component tests
+required by `knowledge/component-test-patterns.md` → API Consumer §
+*Failure modes*:
+
+```csharp
+var time = new FakeTimeProvider();
+var responses = new Queue<HttpResponseMessage>(new[]
+{
+    new HttpResponseMessage(HttpStatusCode.ServiceUnavailable),
+    new HttpResponseMessage(HttpStatusCode.ServiceUnavailable),
+    new HttpResponseMessage(HttpStatusCode.OK) { Content = JsonContent.Create(payload) },
+});
+var handler = new StubHttpMessageHandler((_, _) => Task.FromResult(responses.Dequeue()));
+
+var pipeline = new ResiliencePipelineBuilder<HttpResponseMessage>()
+    .AddRetry(new HttpRetryStrategyOptions { /* ... */ })
+    .ConfigureTelemetry(NullLoggerFactory.Instance)
+    .Build(); // bind TimeProvider via DI in production wiring
+
+// drive: advance virtual time across each backoff window; assert request count == 3 and final result OK.
+```
+
+The same shape proves circuit-breaker open/half-open/closed transitions and
+timeout enforcement without any real wall-clock waits.
+
+## Where it sits on the pyramid
+
+Map directly to `knowledge/cd-test-architecture.md` § *The Six Test Types*:
+
+| Behavior under test | MinimumCD layer | Tool |
+|---|---|---|
+| Pure logic in the adapter (header building, query-string construction, response mapping) | **Unit** (solitary) | xUnit + the adapter constructed directly, no `HttpClient` needed |
+| Adapter speaks the wire correctly to a doubled transport: builds the right request, parses the canned response, maps non-2xx to typed errors | **Contract** | xUnit + `StubHttpMessageHandler` |
+| Resilience policy (retry/backoff/circuit-breaker/timeout) survives a doubled provider failure | **Component** (resilience) | xUnit + `StubHttpMessageHandler` + `FakeTimeProvider` + Polly bound to that `TimeProvider` |
+| Adapter against the real provider API (in-house or third-party) in a non-prod test environment | **Scheduled provider verification** (out-of-band) | xUnit/console job vs the provider's real endpoint, **never pre-merge** |
+| Multi-service journey across real deployed components | **E2E** (post-deploy smoke) | Playwright for .NET — only when the four-condition E2E justification gate from `knowledge/cd-test-architecture.md#the-e2e-justification-gate` is satisfied |
+
+Contract and component tests with the stub handler are **deterministic and
+pre-merge** per
+`knowledge/cd-test-architecture.md#the-pre-merge-gate-rule`. The scheduled
+provider-verification job is the **detection** half of
+`knowledge/cd-test-architecture.md#double-validation-keeping-doubles-honest`;
+the resilience component test is the **survival** half — both are required
+regardless of ownership: assume the provider can break the contract without
+warning even when it's the same team's, per the universal rule in
+`knowledge/component-test-patterns.md#api-consumer`.
+
+## Off-the-shelf alternatives to the hand-rolled stub
+
+The hand-rolled `StubHttpMessageHandler` is usually enough and has zero
+dependencies. Two libraries cover larger or noisier surfaces:
+
+- **`RichardSzalay.MockHttp`** — fluent matcher API (`When(...).Respond(...)`).
+  Good when one test method exercises many endpoints and inline matching
+  beats a delegate's `switch`.
+- **`Moq.Contrib.HttpClient`** — extensions for treating
+  `HttpMessageHandler` as a `Mock<>`. Good when the team already uses Moq
+  pervasively and prefers one mocking idiom across the suite.
+
+Either library is a stylistic choice over the hand-rolled stub, **not** an
+escalation up the pyramid; both still test the same `HttpMessageHandler`
+seam in-process, deterministically.
+
+## WireMock.Net — the preferred pre-merge double when installed
+
+When installed, WireMock.Net is the **preferred** pre-merge double for this
+seam — not the hand-rolled `StubHttpMessageHandler` above, which remains the
+**backup** for when WireMock.Net is declined or unavailable. This is not an
+in-process/no-socket claim: verified against WireMock's own docs, the
+no-HTTP-layer `DirectCallHttpServer` mode ("Running Without the HTTP
+Server") is a **WireMock-for-Java-only** feature — WireMock.Net's
+`WireMockServer.Start()` always binds a real HTTP listener on localhost, on
+an ephemeral port. What actually makes it pre-merge-safe despite that real
+socket: it runs **same-process, localhost-only, on an ephemeral port, with
+no separately-managed external server or container** — fast and
+deterministic enough for the pre-merge gate, even though it is not a true
+in-memory transport. See `knowledge/virtual-service-libraries.md` for the
+full per-stack catalog and the preferred/backup interaction model this file
+is one instance of.
+
+**Reconciling this with the seam framing above and the anti-pattern below.**
+The opening thesis's "no sockets, no ports, no Kestrel" description applies
+to the hand-rolled `StubHttpMessageHandler`, not to this seam universally —
+WireMock.Net fills the same `HttpMessageHandler` seam, through the same DI
+injection point, but the actual network path is a real loopback HTTP
+request, not an in-memory interception. That is a different claim from the
+"Kestrel on a random port" anti-pattern the `What to avoid` section below
+still flags: that anti-pattern hosts your own application's real inbound
+pipeline (or an ad hoc hand-rolled HTTP host) as the downstream fake, with
+no purpose-built stub tooling. WireMock.Net, by contrast, is purpose-built
+stub tooling — request/response matching and expectation configuration are
+its entire job — launched and torn down within the same test process
+lifecycle, with no separately-managed external server or container to
+configure. The honest trade-off: a real loopback socket is being traded for
+that purpose-built tooling and faster iteration than hand-rolling a host —
+not for the absence of sockets, DNS, or the network stack, which this file
+does not claim WireMock.Net avoids.
+
+## What to avoid for unit and component tests
+
+These are integration/E2E tooling — fast feedback isn't what they're for,
+so they don't belong on the pre-merge gate (see
+`knowledge/cd-test-architecture.md#the-pre-merge-gate-rule`):
+
+- **`WebApplicationFactory<T>` to test an outbound client.** It spins up
+  the *server* in-process. The seam you want is below the client, not above
+  the server. Use it for the API Provider side (inbound HTTP); use the
+  stub handler for the API Consumer side.
+- **Kestrel on a random port + a real HTTP request.** You are now testing
+  the network stack and DNS, not your code. Slow, OS-dependent, flaky.
+- **MockServer for unit tests.** Unlike WireMock.Net (see above), MockServer
+  is typically run as a separately-managed remote or containerized service.
+  Reserve it for the **adapter-integration** layer (out-of-band, on a
+  schedule) where the network behavior itself is under test — TLS, HTTP/2,
+  proxy, real timeouts.
+
+## Common smells in C# HTTP-consumer tests
+
+Catalogued so `test-smell-review` and `test-design-advisor` can map a
+finding to the .NET-specific fix:
+
+- **Mocking `HttpClient` directly** (e.g. with Moq). `HttpClient` is a
+  sealed/non-virtual surface in practice; mocking it requires reflection
+  hacks or `InternalsVisibleTo`, both of which are test workarounds for a
+  missing production seam. Wrap it in an adapter and double the
+  `HttpMessageHandler` instead. (`knowledge/test-doubles.md` rule:
+  never invent a test-only seam to dodge a missing production one.)
+- **Mocking the third-party SDK directly** instead of an owned adapter.
+  Same pattern, same fix — Adapter Rule applies.
+- **`DateTime.UtcNow` in retry/expiry logic** without `TimeProvider`. The
+  test must `Thread.Sleep` (or worse, give up determinism). Inject the
+  clock.
+- **`Thread.Sleep`/`Task.Delay` in tests** to wait for retries. Always a
+  symptom of (a) above. Use `FakeTimeProvider` and Polly bound to it.
+- **String-matching JSON request bodies.** Deserialize structurally; the
+  test breaks on whitespace and culture otherwise.
+- **Asserting against the adapter's internal calls** (e.g. with a behaviour
+  verification mock) instead of the request that crossed the seam. The
+  contract is the request bytes the SUT *would emit*, not which method on
+  the SDK it called. Prefer state verification of `Requests` captured by
+  the stub handler.
+
+## Boundaries
+
+This file covers .NET-specific *mechanics* for the API Consumer pattern.
+The pattern itself — coverage layers, success/failure scenarios, double
+validation loop, pipeline placement — lives in
+`knowledge/component-test-patterns.md#api-consumer` and is language-agnostic.
+For the broader stack picture (which tool at which layer on .NET), see
+`knowledge/test-stack-profiles/dotnet.md`. For a worked example using this
+pattern end-to-end, see
+`knowledge/test-matrix-examples/dotnet-http-consumer.md`.

package/knowledge/release-strategies.md

@@ -0,0 +1,74 @@
+# Release Strategies
+
+Reference for releasing changes with low risk and zero downtime. Source:
+*Continuous Delivery* (Humble & Farley) Ch.10, plus the version-control
+techniques from Ch.14 that keep mainline releasable. This file is advisory — the
+plugin recommends and plans for these patterns; it does not execute deployments.
+
+The governing distinction: **deploy ≠ release.** Deploying puts code on a server;
+releasing exposes behavior to users. Keep them separate so you can deploy
+continuously and release on a business decision.
+
+## Decouple deployment from release
+
+| Technique | What it does | Use when |
+|-----------|--------------|----------|
+| **Feature toggle / flag** | Ship code dark; turn behavior on at runtime without a deploy | Incremental delivery of an unfinished feature; instant kill-switch |
+| **Branch by abstraction** | Introduce an abstraction over the thing being replaced, migrate callers behind it on mainline, then delete the old path | Large changes that would otherwise need a long-lived branch |
+| **Dark launching** | Run new code paths in production against real traffic without showing results to users | Validate capacity/behavior before exposure |
+| **Keep mainline releasable** | Every commit leaves trunk shippable; hide incomplete work behind toggles/abstractions rather than branching | Always — this is what makes continuous delivery possible |
+
+Toggles are **inventory**: remove each one once the feature is permanent. Stale
+flags are a liability (untested combinations, dead branches).
+
+## Deployment patterns
+
+| Pattern | How it works | Rollback | Trade-off |
+|---------|--------------|----------|-----------|
+| **Blue-green** | Two identical production environments; release by switching the router to the idle one | Switch the router back | Needs double the capacity (or shared data tier handled carefully) |
+| **Canary** | Roll the new version to a small subset of servers/users first; widen as confidence grows | Stop and route back to the old version | Requires routing control + per-cohort metrics; A/B and capacity testing for free |
+| **Rolling** | Replace instances in batches behind a load balancer | Roll the batches back | Both versions run at once — needs backward-compatible data + contracts |
+| **Recreate** | Stop old, start new | Redeploy previous version | Incurs downtime; only where an outage window is acceptable |
+
+Keep **as few versions in production as possible** — ideally two (old + new)
+during a transition. Every concurrent version multiplies the compatibility matrix.
+
+## Rollback is a practiced capability, not a hope
+
+- **Always be able to roll back.** Back up production state before a release and
+  *rehearse* the rollback before every release — an untested rollback is not a
+  rollback.
+- The simplest reliable rollback is **redeploying the last known-good version**
+  from scratch through the same pipeline.
+- Data makes rollback hard: pair this with expand/contract migrations
+  (`database-change-management.md`) so the schema is compatible with the version
+  you roll back to.
+- Prefer **rolling back over hot-fixing** a bad release. Emergency fixes still go
+  through the standard pipeline — never hand-patch production.
+
+## Keeping mainline releasable (Ch.14)
+
+- **Develop on trunk; commit at least daily.** Long-lived feature branches are
+  opposed to continuous integration — they cause merge hell and hide integration
+  risk until late.
+- Make large changes as **small incremental steps on mainline** using feature
+  hiding, componentization, or branch by abstraction — not a branch.
+- **Branch only for release, for a spike, or in extremis.** A release branch
+  takes only critical fixes, merged back to mainline immediately; it replaces the
+  anti-pattern of a code freeze.
+
+## Planning hook
+
+When `/plan` decomposes a feature, prefer slices that keep trunk releasable at
+every step: land the change behind a toggle or behind an abstraction, sequence
+data changes as expand-before-contract, and avoid a slice that is only shippable
+once the whole feature is done.
+
+## How this connects to the rest of the toolkit
+
+- **`database-change-management.md`** — the data-tier half of every pattern here;
+  rolling, blue-green, and canary all require a schema compatible across versions.
+- **`deployment-pipeline.md`** — these patterns ride on a pipeline that builds the
+  artifact once and promotes it; the deploy mechanism is identical per environment.
+- **`cd-maturity-model.md`** — decoupling deploy from release and practiced
+  rollback are what move the "environments & deployment" practice area up the model.

package/knowledge/report-output-location.md

@@ -0,0 +1,117 @@
+# Report Output Location
+
+`.dev-team-reports/` is the shared location convention for dev-team's
+human-invoked report-writing skills — `/review-agent`, `/code-review`
+(interactive mode), `/triage`, and `/session-review`. It is a **literal,
+hardcoded directory name** — it is not an environment variable, and it is
+not currently overridable.
+
+**Boundary: dated human-invoked reports vs. skill-internal scratch state.**
+A skill lands here when a human directly invokes it to produce a durable,
+readable deliverable (a review, a triage record, a session digest). Skills
+that write bare `metrics/`/`memory/` scratch data for their *own* internal
+bookkeeping — not a human-facing report — stay outside this convention even
+when the word "report" appears in their name or output; see each such
+skill's own path documentation for its rationale.
+
+This file defines *where* reports go. `knowledge/report-template.md` defines
+*what's inside* them (shared header/footer/empty-section contract) — the two
+concerns compose independently.
+
+## Write-scope rule
+
+Only a **top-level human invocation** writes to `.dev-team-reports/`:
+
+- `/review-agent <agent>` writes `.dev-team-reports/<agent>.md` — **unless**
+  `--internal` is passed (the orchestrator-internal dispatch signal; `/build`
+  is the only sanctioned caller today).
+- `/code-review` (interactive, no `--json`) writes
+  `.dev-team-reports/code-review.md` — **unless** `--internal` is passed (the
+  sanctioned callers today are `/build`'s Step 6 backstop review and
+  `/test-improve`'s Phase 5/7 end-of-phase review loop — see below for
+  `/ship`'s Step 5, a deliberate, documented exception that keeps writing
+  the report) or `--json` is passed (CI/`/pr` callers — `--json` never
+  writes a file, full stop).
+- `/triage` writes `.dev-team-reports/triage/<slug>.md` unconditionally — it
+  has no orchestrator-internal caller today.
+- `/session-review` writes `.dev-team-reports/session-review-<date>.md` (or
+  `--out`) unconditionally — it has no orchestrator-internal caller today.
+
+`--internal` and `--json` are orthogonal flags on `/code-review`: `--json`
+governs output format and bypasses the review-fix loop; `--internal` only
+suppresses the `.dev-team-reports/` write and has no effect on the fix loop
+or output format.
+
+## Report exception: /ship
+
+`/ship`'s Step 5 ("Review") dispatches `/code-review` with neither
+`--internal` nor `--json` — so it writes `.dev-team-reports/code-review.md`
+by default, unlike `/build`'s Step 6 and `/test-improve`'s Phase 5/7 review
+loop above. This is a **deliberate, stated exception** to the "only a
+top-level human invocation writes" rule, not an unaudited gap (issue #982):
+
+`/ship` is itself `user-invocable: true` and is only ever entered by a
+human directly typing `/ship` — but so is `/build`, whose own internal
+Step 6 dispatch is suppressed, so being human-typed at the top isn't by
+itself what earns the exception. The stronger distinguishing factor is
+**frequency and scope, not surfacing**: `/build`'s Step 7.5 evidence bundle
+does surface the Step 6 `/code-review` *status* back to the human at
+completion (a pass/fail line, not the artifact itself), and `/test-improve`
+similarly surfaces its review outcome in each phase's evidence file — so
+"no human-facing surfacing at all" is not the real dividing line. What
+actually differs: `/build`'s Step 6 and `/test-improve`'s per-phase loop
+each run **multiple times across a session** (once per build, once per
+`/test-improve` phase) against a **diff-scoped** slice of the total change —
+a `.dev-team-reports/code-review.md` write from either would represent only
+one slice's worth of review, repeatedly overwritten, not "the latest state
+for this repo." `/ship`'s Step 5 runs **once**, at the end of the whole
+shipped feature, over the **full accumulated diff** — the one point in the
+pipeline where a durable, complete review artifact is both meaningful and
+non-redundant. Reinforcing this: `/code-review`'s own step-6 "exception (b)"
+(which skips the interactive fix-or-report prompt for callers "running
+inside `/build` or `/pr`") does not name `/ship` either — `/ship`'s dispatch
+is genuinely interactive today, consistent with a human being present for
+this one-time gate rather than an orchestrator-internal backstop.
+
+## Fixed filenames: overwrite vs. never-overwrite
+
+`/review-agent` and `/code-review` write a **fixed, per-workflow filename**
+that is **overwritten on every run** (`.dev-team-reports/<agent>.md`,
+`.dev-team-reports/code-review.md`) — safe to overwrite because each file
+represents "the latest state for this repo," not a history. Both skills
+print a confirmation line noting the overwrite (`Report written:
+.dev-team-reports/<name>.md (replaced previous run)`) so this is visible at
+the point of use, not only here.
+
+`/triage` is the deliberate exception: `.dev-team-reports/triage/<slug>.md`
+is **never overwritten** — a same-slug collision appends `-2`, `-3`, … up to
+`-99`. This is safe and necessary because, unlike a single repo's "latest
+review state," multiple distinct bugs can be triaged concurrently and each
+deserves its own durable record.
+
+## Write failures are always non-fatal
+
+A `.dev-team-reports/` write failure (permission/read-only) is reported to
+chat but never blocks or alters the skill's existing primary output — the
+JSON result and chat summary for `/review-agent`, the prose summary for
+`/code-review`, and the temp-file/chat fallback for `/triage`. The file
+write is strictly additive.
+
+## Gitignored by default, with a tracked exception for report data
+
+`.dev-team-reports/` is gitignored by default — both in this repo's own
+`.gitignore` and in `/project-init`'s JS-scaffold `.gitignore` template for
+newly-provisioned target repos — matching the existing treatment of
+`reports/` and the prior `.triage/` convention it replaces. Both use the
+same anchored deny-all + re-included tracked-exception shape (`/.dev-team-reports/*`
+followed by `!/.dev-team-reports/test-improve/`), not a blanket directory
+ignore — `/test-improve`'s `<slug>/data/` sibling directory (issue #1412) is
+git-tracked, and each artifact under it is written there directly, atomically,
+at the point of capture (never copied there later from a separate working
+location), so its report is a pure function of tracked data and regeneratable
+from a fresh checkout.
+
+## Related
+
+- `knowledge/report-template.md` — the shared header/footer/empty-section
+  content contract for what goes *inside* a report written to this location.

package/knowledge/report-pdf-integration.md

@@ -0,0 +1,63 @@
+# The `--pdf` flag on report-producing skills
+
+The single contract for the `--pdf` pass-through, shared by every skill that
+writes a Markdown report (`/code-review`, `/test-health`,
+`/cd-test-architecture`, `/triage`, `/harness-audit`, `/repo-review`). Each
+skill references this file rather than restating the behavior, so the
+wording never drifts.
+
+This file defines *how `--pdf` behaves*. `hooks/lib/report_pdf.py` is the render
+engine it calls; [`report-to-pdf.md`](report-to-pdf.md) is the underlying
+recipe; [`report-output-location.md`](report-output-location.md) details the
+`.dev-team-reports/` write rules — the per-skill paths are in the table below.
+
+## Contract
+
+When a skill is invoked with `--pdf`:
+
+1. **Render the report this run actually wrote — not a fixed path.** After the
+   skill has written its Markdown report, resolve the concrete path that run
+   produced (each skill knows its own — see the table below) and render it:
+
+   ```bash
+   sh "$CLAUDE_PLUGIN_ROOT/hooks/py.sh" "$CLAUDE_PLUGIN_ROOT/hooks/lib/report_pdf.py" <the-report-path-just-written>
+   ```
+
+   The module prints a `Rendering PDF via <engine>…` progress line (the
+   render can take several seconds on a cold headless-Chrome start), then one
+   result line. Surface the output; on success it states the sibling PDF path
+   and the engine used.
+
+2. **No report written → no-op with a message, never an error.** If the run
+   wrote no Markdown report (see the no-file modes below), do **not** invoke the
+   module. State plainly: `--pdf: no report file was written this run, nothing to render.` and continue. This is a no-op, not a failure.
+
+3. **No engine available → skip, never fail.** If `report_pdf.py` finds no PDF
+   engine it exits 0 with an install hint and leaves the Markdown untouched.
+   `--pdf` never changes the skill's own exit status or primary output — PDF is
+   strictly additive.
+
+4. **`--json` output stays pure.** When a skill also runs in a machine-readable
+   `--json` mode, all `--pdf` status text (progress, skip, no-op) goes to
+   **stderr** so stdout remains valid JSON for scripted callers.
+
+**Distinct wording — keep these two cases lexically separate** so a reader can
+self-diagnose which they hit:
+
+- **skip** (no engine): `No PDF engine found. Install one, …` (from the module).
+- **no-op** (no report file written): `--pdf: no report file was written this run, nothing to render.`
+
+## Per-skill report path and no-file modes
+
+| Skill | Report path this run wrote | `--pdf` no-op when |
+|-------|----------------------------|--------------------|
+| `/code-review` | `.dev-team-reports/code-review.md` | `--json` or `--internal` (no file written) |
+| `/triage` | `.dev-team-reports/triage/<slug>.md` (the path just written) | never — it always writes a file |
+| `/test-health` | `.dev-team-reports/test-health-<date>.md` | never — it always writes a file |
+| `/cd-test-architecture` | `.dev-team-reports/cd-test-architecture-<app>.md` | single-component **chat-only** run (no file) |
+| `/harness-audit` | `.dev-team-reports/harness-audit-<date>.md`, or the `--output <path>` override | never — it always writes a file |
+| `/repo-review` | `.dev-team-reports/repo-review.md` | `--json` (no file written) |
+
+A new report-producing skill inherits `--pdf` by adding a row here, documenting
+`--pdf` in its `argument-hint`, and calling `report_pdf.py` on the path it wrote
+— no new render logic.

package/knowledge/report-print.css

@@ -0,0 +1,129 @@
+/* report-print.css — bundled print stylesheet for dev-team report PDFs (#1114).
+ *
+ * Applied by hooks/lib/report_pdf.py when converting any .dev-team-reports/*.md
+ * (or reports/*.md) to a shareable PDF. Goals: accent-colored headings,
+ * zebra-striped bordered tables, monospace chips for `file:line`, sane @page
+ * margins, and no clipped wide cells or mid-row page breaks.
+ */
+
+@page {
+  size: A4;
+  margin: 18mm 16mm;
+}
+
+:root {
+  --accent: #2563eb;
+  --accent-dark: #1e3a8a;
+  --border: #d0d7de;
+  --zebra: #f6f8fa;
+  --chip-bg: #eef1f5;
+  --ink: #1f2328;
+}
+
+html {
+  -webkit-print-color-adjust: exact;
+  print-color-adjust: exact;
+}
+
+body {
+  font-family: -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  font-size: 10.5pt;
+  line-height: 1.5;
+  color: var(--ink);
+  margin: 0;
+}
+
+h1,
+h2,
+h3,
+h4 {
+  color: var(--accent-dark);
+  line-height: 1.25;
+  page-break-after: avoid; /* never orphan a heading at the foot of a page */
+}
+
+h1 {
+  font-size: 20pt;
+  border-bottom: 3px solid var(--accent);
+  padding-bottom: 0.2em;
+}
+
+h2 {
+  font-size: 15pt;
+  border-bottom: 1px solid var(--border);
+  padding-bottom: 0.15em;
+}
+
+h3 {
+  font-size: 12.5pt;
+}
+
+a {
+  color: var(--accent);
+}
+
+/* Inline code / `file:line` chips — monospace, tinted, and allowed to wrap so a
+ * long path never clips out of a table cell. */
+code {
+  font-family: "SF Mono", "Cascadia Code", Consolas, "Liberation Mono", monospace;
+  font-size: 0.9em;
+  background: var(--chip-bg);
+  padding: 0.08em 0.35em;
+  border-radius: 4px;
+  word-break: break-all;
+  overflow-wrap: anywhere;
+}
+
+pre {
+  background: var(--zebra);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 0.75em 1em;
+  overflow-x: auto;
+  white-space: pre-wrap; /* wrap long lines instead of clipping */
+  word-break: break-word;
+  page-break-inside: avoid;
+}
+
+pre code {
+  background: none;
+  padding: 0;
+}
+
+table {
+  border-collapse: collapse;
+  width: 100%;
+  margin: 0.75em 0;
+  font-size: 9.5pt;
+  table-layout: fixed; /* honor width so wide cells wrap rather than overflow */
+}
+
+th,
+td {
+  border: 1px solid var(--border);
+  padding: 0.4em 0.6em;
+  text-align: left;
+  vertical-align: top;
+  word-break: break-word;
+  overflow-wrap: anywhere; /* wide file:line cells wrap, never clip */
+}
+
+th {
+  background: var(--accent);
+  color: #ffffff;
+}
+
+tbody tr:nth-child(even) {
+  background: var(--zebra); /* zebra striping */
+}
+
+tr {
+  page-break-inside: avoid; /* keep a row whole across a page boundary */
+}
+
+blockquote {
+  border-left: 4px solid var(--accent);
+  margin: 0.75em 0;
+  padding: 0.2em 1em;
+  color: #57606a;
+}