pi-dev-team 0.2.0

package/knowledge/ai-friendly-repo-guidelines.md

@@ -0,0 +1,67 @@
+# AI-Friendly Repository Guidelines
+
+Rubric of repo conventions that improve Claude Code's effectiveness. Canonical
+source for the `/agent-readiness` criteria `D5_claude_md_size`,
+`D6_layered_context`, `D7_reference_implementation` and
+`B5_composite_check_command`; the scanner's evidence strings link to the anchors
+below. Other agents (`claude-setup-review`, `setup`) can cite this file instead
+of re-describing the rubric.
+
+These conventions are heuristics: they measure how cheaply an agent can load the
+right context and verify its own work, not code quality. The scanner audits only;
+it never edits the target repo.
+
+## Layered Context Architecture
+
+Agents pay for every line of always-loaded context and for every wrong guess made
+without it. Keep the always-loaded layer small and push detail down to where it
+applies.
+
+- **Keep the root `CLAUDE.md` short (about 200 lines or fewer).** Every session
+  loads it in full; past the ceiling, rules compete for attention and later ones
+  are followed less reliably. Scored by `D5_claude_md_size`.
+- **Layer context hierarchically.** Put directory-specific rules in nested
+  `CLAUDE.md` files or `.claude/rules/*.md` so they load only when that area is
+  touched. Scored by `D6_layered_context`.
+- **Move procedures and reference material out of `CLAUDE.md`.** Link to skills,
+  knowledge files or docs loaded on demand rather than inlining them.
+- **Name a canonical reference implementation.** Point at one well-made module or
+  test as the pattern to copy; agents imitate what they are shown. Flagged for
+  human review as `D7_reference_implementation` because whether the pointer is
+  well chosen is a judgment call.
+
+## Deterministic Verification & Fast Feedback Loops
+
+An agent can only converge on a correct change if it can check its work quickly
+and get the same answer every time.
+
+- **Expose one composite check command.** A single `check`, `verify`, `ci` or
+  `all` target that runs lint and tests lets the agent verify in one step and
+  matches what CI runs. Scored by `B5_composite_check_command`.
+- **Make single-target test runs possible.** Running one test file or test by
+  name keeps the inner loop seconds long (deferred criterion
+  `T4_single_command`).
+- **Prefer deterministic checks over model judgment.** A linter, type checker or
+  test suite gives a binary answer; use them as the gate before any review agent.
+- **Keep the loop fast.** Slow suites get skipped or truncated by agents;
+  split slow integration tests from the fast default path.
+
+## Navigable Repository Layout
+
+Agents find code by searching names and paths. A predictable layout reduces the
+reads needed to locate the right file.
+
+- **Colocate or mirror tests with source.** A test next to (or at a mirrored path
+  of) the code it covers is found in one lookup (follow-up criterion, not yet
+  scored).
+- **Keep directory depth shallow.** Deep nesting hides files and inflates path
+  tokens (follow-up criterion, not yet scored).
+- **Use descriptive, conventional names** for files and directories so a grep on
+  the domain term lands on the right module.
+- **Exclude generated and vendored trees** from search paths so agents do not
+  wander into build output.
+
+## Source
+
+Synthesized from Anthropic's published Claude Code guidance on memory files and
+verification loops and from this repo's own conventions. Tracked in issue #2178.

package/knowledge/architecture-assessment.md

@@ -0,0 +1,96 @@
+# Architecture Assessment Patterns
+
+Reference file for the arch-review agent. Read this before starting
+analysis to apply architectural compliance patterns.
+
+## Exploration Patterns
+
+Map the architectural landscape before detecting issues.
+
+### Discovery sequence
+
+1. **ADRs**: Glob for `**/adr/**`, `**/adrs/**`, `**/decisions/**`, `docs/adr*`
+2. **Architecture docs**: Glob for `docs/architecture.md`, `docs/arch*.md`, `ARCHITECTURE.md`, `README.md`
+3. **Layer definitions**: Glob for `**/domain/**`, `**/application/**`, `**/infrastructure/**`, `**/presentation/**`, `**/api/**`, `**/ui/**`
+4. **Import patterns**: Grep for cross-layer imports
+
+If no architecture documentation and no discernible layered structure exists, return skip.
+
+## ADR Compliance Checks
+
+| Check | How to detect |
+|-------|---------------|
+| Prohibited library | ADR says "do not use X"; code imports X |
+| Mandated pattern bypass | ADR requires event sourcing/hexagonal ports; code uses direct calls |
+| Unreflected reversal | ADR decision reversed in code but ADR status not `Superseded` |
+
+## Layer Boundary Rules
+
+Standard layered architecture enforces dependency direction:
+`presentation → application → domain ← infrastructure`
+
+| Violation | Signal |
+|-----------|--------|
+| Infrastructure → Domain | ORM entity imported by domain service |
+| Domain → Application | Domain layer importing application service types |
+| Domain → Infrastructure | Domain importing database clients, HTTP clients |
+| Presentation → Domain direct | UI importing domain internals, bypassing use cases |
+| Cross-context direct | One bounded context importing domain types from another |
+
+Flag: the specific import statement, source file, target file, and which boundary is crossed.
+
+## Dependency Direction Checks
+
+| Check | Signal |
+|-------|--------|
+| New circular dependency | Module A imports B, B imports A (where previously unidirectional) |
+| Leaf node violation | A utility/shared module now depends on core business logic |
+| Unwrapped third-party | Third-party library used directly in domain/application layer without interface |
+
+## Pattern Consistency Checks
+
+Flag when new code diverges from established patterns for the same concern:
+
+| Concern | Inconsistency signal |
+|---------|---------------------|
+| Data access | Repository pattern used elsewhere, direct DB access in new code |
+| Cross-context communication | Events used elsewhere, direct calls in new code |
+| Error handling | Result types used elsewhere, exceptions in new code (or vice versa) |
+| Duplicate abstractions | Two repository base classes, two HTTP client wrappers |
+
+## Prohibited Practice Detection
+
+Grep for patterns that architecture docs explicitly ban:
+
+| Pattern | When prohibited |
+|---------|----------------|
+| `new` infrastructure objects in domain | If docs prohibit constructor coupling |
+| Direct `fetch`/`axios`/`HttpClient` outside adapter layer | If docs mandate HTTP abstraction |
+| Direct DB client calls outside repository layer | If docs mandate repository pattern |
+
+## Database Change Safety
+
+When the changeset includes schema migrations or DDL, a change must keep every release deployable and reversible. Fuller treatment: `knowledge/database-change-management.md`.
+
+| Signal | Risk | Fix direction |
+|--------|------|---------------|
+| `DROP`/`RENAME` of a column/table the same release's app still reads or writes | Breaks running instances mid-rollout; blocks rollback | Split into expand/contract across releases (add new, dual-write, switch reads, drop later) |
+| Roll-forward migration with no paired roll-back script | The release cannot be rolled back | Author and test the reversal |
+| New `NOT NULL` column or constraint added without a backfill step | Migration fails or long-locks on real data | Add nullable → backfill → enforce in a later release |
+| App code and schema assumed to deploy atomically | Old app instances error mid-rollout | Make the change backward-compatible (expand first) |
+| Manual SQL in a runbook instead of a versioned migration script | No audit trail; not reproducible; drifts across environments | Move into a versioned migration in version control |
+
+Flag the migration file and the coupled application code. Scope to migration/DDL changes only; ordinary data-access code is out of scope here.
+
+## MCP-Enhanced Analysis
+
+If a code knowledge graph MCP is available (e.g., GitNexus):
+
+| Tool | Purpose |
+|------|---------|
+| `list_repos` | Discover ecosystem — what other repos exist |
+| `query` | Map cross-repo dependencies — who calls this service |
+| `context` | 360-degree view of key entry points |
+| `impact` | Quantify blast radius of architectural changes |
+
+Fall back to local Grep/Read if unavailable.

package/knowledge/artifact-lifecycle.md

@@ -0,0 +1,57 @@
+# Artifact Lifecycle States
+
+This file defines the lifecycle state model for tracked plugin artifacts (skills,
+agents). States are maintained in `~/.claude/metrics/artifact-usage.json`
+(home-scoped, never a project-scoped path) and consumed by the
+`/artifact-lifecycle` skill to report and propose transitions.
+
+## States
+
+### active
+An artifact used within the last 30 days. No lifecycle transition is needed.
+
+### stale
+An artifact **not used in more than 30 days** (i.e., `days_since_used >= 30` and
+`< 90`). Stale artifacts are candidates for disabling — add them to
+`## Disabled Skills` in project `CLAUDE.md` so they do not load into context
+until deliberately re-enabled.
+
+### archived
+An artifact **not used in more than 90 days** (i.e., `days_since_used >= 90`).
+Archive candidates should be evaluated for permanent removal from the active set.
+
+## Lifecycle Thresholds
+
+| State | Threshold |
+|-------|-----------|
+| active | `last_used_at` < 30 days ago |
+| stale | `last_used_at` >= 30 days ago (and < 90 days) |
+| archived | `last_used_at` >= 90 days ago |
+
+Both boundaries are **inclusive**: an artifact last used exactly 30 days ago is
+stale; an artifact last used exactly 90 days ago is an archive candidate.
+
+## Pinned Exemption
+
+Artifacts listed under `## Pinned Skills` in `CLAUDE.md` are exempt from all
+lifecycle transitions regardless of `last_used_at`. A pinned artifact is excluded
+from the Stale Skills and Archive Candidates sections of `/artifact-lifecycle`
+output and is never proposed for disabling or removal.
+
+## ~/.claude/metrics/artifact-usage.json Schema
+
+```json
+{
+  "<artifact-name>": {
+    "use_count": 5,
+    "last_used_at": "2026-06-01T12:00:00Z",
+    "lifecycle": "active"
+  }
+}
+```
+
+The `lifecycle` field is initialised to `"active"` on first write and preserved
+on subsequent upserts — a manually-set `"stale"` value is not overwritten when
+the artifact is next used. The `/artifact-lifecycle` skill computes effective
+lifecycle from `last_used_at` rather than from this stored field, so the stored
+value is informational only.

package/knowledge/cd-maturity-model.md

@@ -0,0 +1,82 @@
+# Continuous Delivery Maturity Model
+
+Reference for assessing and improving an organization's delivery capability.
+Source: *Continuous Delivery* (Humble & Farley) Ch.15. Use it to locate where a
+team is, pick the one area worth improving next, and define the outcome that
+proves the improvement landed.
+
+This measures **delivery capability** (can this team release small changes safely
+and often?). It is a *different axis* from the agent-readiness scorecard
+(`skills/agent-readiness/`), which measures how ready a repo is for AI-agent
+work. A repo can score high on one and low on the other; assess them separately.
+
+## The six practice areas
+
+Maturity is read per area, not as a single number — a team is usually uneven.
+
+| Practice area | What it covers |
+|---------------|----------------|
+| **Build management & CI** | Build automation, trunk-based CI, fast feedback, build discipline |
+| **Environments & deployment** | Automated provisioning, identical deploy everywhere, release strategies, rollback |
+| **Release management & compliance** | Change/approval flow, traceability, audit through the pipeline |
+| **Testing** | Automated test strategy across the pyramid, deterministic gates |
+| **Data management** | Scripted, versioned, reversible migrations; managed test data |
+| **Configuration management** | Everything in version control; config per environment; secrets handling |
+
+## The five levels
+
+| Level | Name | Signal |
+|-------|------|--------|
+| **3** | Optimizing | Teams continuously improve the process; cycle time and stability are measured and trending down/up |
+| **2** | Quantitatively managed | Process metrics gathered and used to make decisions; risk understood |
+| **1** | Consistent | Automated processes applied across the whole lifecycle, used by everyone |
+| **0** | Repeatable | Process documented and partly automated; results repeatable |
+| **−1** | Regressive | Processes ad hoc, manual, unrepeatable; results unpredictable |
+
+Score each of the six areas against the five levels to get a profile, not a grade.
+
+## How to improve (the Deming cycle)
+
+1. **Map the value stream** — commit to release — and find the most painful /
+   slowest area. Improve *that*, not everything at once.
+2. **Define acceptance criteria** for the improvement (a measurable outcome).
+3. **Implement** the smallest change that moves the area up a level.
+4. **Measure** against the criteria; **retrospect**; roll the change out
+   incrementally. Repeat. Never try to jump all areas to the top level at once.
+
+## The outcomes to target
+
+The model is a means; these are the ends. Track them directly:
+
+| Metric | What it tells you |
+|--------|-------------------|
+| **Cycle time** (commit → releasable) | The primary global signal; the Theory-of-Constraints lens for finding the bottleneck |
+| **Deployment frequency** | How small and frequent changes are |
+| **Change failure rate** | Quality of the gate; stability of releases |
+| **Mean time to restore (MTTR)** | Strength of rollback / recovery |
+
+The last three plus lead time are the DORA four key metrics; cycle time is the
+internal lens that explains them.
+
+## Guiding principles
+
+- **Prefer automation over documentation.** An automated script is executable
+  documentation that must work and stays current; a document proving you did
+  something doesn't guarantee you did.
+- **Compliance *through* the pipeline, not against it.** The pipeline is the best
+  audit trail — lock down privileged environments, require approvals, and build
+  authorization/auditing into the deploy path. Build binaries once and hash them
+  to prove production matches source.
+- **Release as often as possible** — at least every iteration, even with no users
+  yet. "If it hurts, do it more frequently." Iterative, incremental delivery is
+  the core of risk management.
+- **Don't work in silos.** Favor cross-functional teams; treat change management
+  as risk management with a remediation (back-out) plan and an acceptance test per
+  change.
+
+## How this connects to the rest of the toolkit
+
+- **`deployment-pipeline.md`** / **`release-strategies.md`** / **`database-change-management.md`**
+  — the practices that move the environments, deployment, and data areas up the model.
+- **`cd-test-architecture.md`** — the testing area's gate.
+- **`skills/agent-readiness/`** — the orthogonal axis (AI-agent readiness); cross-reference, don't conflate.

package/knowledge/cd-test-architecture.md

@@ -0,0 +1,190 @@
+# CD Test Architecture
+
+Reference file for the `cd-test-architecture` skill and the `test-design-advisor` skill. Defines a test architecture aligned to a Continuous Delivery pipeline: **fast, deterministic tests, with minimal tooling, that fully validate behavior — including how a component interacts with other services — and run in CI without configuring the rest of the system the component depends on.**
+
+Source vocabulary: MinimumCD Practice Guide — Test Types (beyond.minimumcd.org/docs/testing/test-types/) and Applied Testing Strategies (beyond.minimumcd.org/docs/testing/applied-testing-strategies/). Component-specific patterns are in `component-test-patterns.md`.
+
+Core principle: **a pre-merge gate may contain only deterministic tests.** A test that depends on a system the team doesn't control — or that must be configured to run — is non-deterministic and belongs out of the merge path. The way to keep behavior coverage in the gate anyway is to replace uncontrolled systems with test doubles, and to keep those doubles honest with a separate validation loop.
+
+---
+
+## The Six Test Types
+
+| Type | Verifies | Dependencies | Deterministic? | Pre-merge gate? | Pipeline stage |
+|------|----------|--------------|----------------|-----------------|----------------|
+| **Static analysis** | Non-running code: security, complexity, best-practice | none | yes | **yes** | Stage 1 |
+| **Unit** | A unit of behavior through its public interface (what it does, not how) | isolated (doubles) | yes | **yes** | Stage 1 |
+| **Component** | A single component through its public interface, with systems the team doesn't control replaced by doubles | doubles for uncontrolled systems | yes | **yes** | Stage 1 |
+| **Contract** | Interface boundaries with external systems, using doubles (a.k.a. narrow integration). Pins the request sent + response shape depended on | doubles; *validated by integration* | yes | **yes** | Stage 1 |
+| **Integration** | That the contract's doubles still match the real system. Exercises real external dependencies | real systems | **no** | **never** | Out-of-band / scheduled, regardless of ownership |
+| **End-to-end** | Two or more real components up to the full system | real components | **no** | **never** | Post-deploy smoke; never gates the build |
+
+**Unit** has two shapes: *solitary* (all collaborators doubled) and *sociable* (real in-process collaborators, only true boundaries doubled). Both are deterministic and pre-merge, but **sociable is the default**: a solitary unit test is one whose every double names a blocker (B1/B2/B3), not a free choice — see `internal-collaborator-doubling.md` for the full rule.
+
+---
+
+## The Pre-Merge Gate Rule
+
+Pre-merge (the gate that blocks a merge) contains **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 (real systems, real network, shared state) and **never gate a merge**. They run:
+
+- **Out-of-band / scheduled, always** — regardless of whether the dependency is a team-controlled container (a testcontainers-hosted real engine or broker) the build could spin up itself, or a third-party API, managed broker, or another team's service. A locally-run container running the real dependency is still a real system: real network, real state, non-deterministic — ownership of the dependency changes nothing about that, so it never earns an in-band exception. This is distinct from a record-and-replay virtual-service double *of* that dependency (WireMock, WireMock.Net, Nock, VCR.py, go-vcr — per `virtual-service-libraries.md`): a virtual-service double replays canned interactions with no real network call to the dependency, so it is deterministic and pre-merge-gate-eligible — only a container or instance running the real dependency itself is out-of-band/scheduled.
+- **Post-deploy** for end-to-end smoke of critical journeys against real backends — blocking rollout, not the build.
+
+If a "unit test" needs a database URL, a broker, a downstream service, or environment secrets to run, it is mis-typed — it's an integration test wearing a unit test's name. Re-type it or convert it to a component test with doubles.
+
+---
+
+## Tests Must Live With the Code (out-of-repo testing is an anti-pattern)
+
+A component's tests belong **in the component's repository and pipeline**. When a component has little or no in-repo testing and is instead verified by suites in another repo, a separate QA runner, Postman/Insomnia collections, or manual scripts, that is an **anti-pattern — regardless of how thorough the external coverage is** — because:
+
+- It **cannot gate the component's own merges** — the build can go green while the behavior is broken.
+- It is **not versioned with the code** it verifies, so the two drift; a code change and its test change can't move together.
+- It is usually **non-deterministic and environment-coupled** (shared environments, real dependencies, human steps), so it could never be 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** and the best available basis for improvement. The move is:
+
+1. **Harvest** the external coverage into an in-repo behavior inventory: each Postman request → an API contract + scenario; each manual step → a behavior to automate; each other-repo test → a behavior to reproduce locally.
+2. **Re-express** each behavior as the lowest-layer deterministic in-repo test that covers it (see `component-test-patterns.md`), running in the component's own gate.
+3. **Decommission** the external/manual case once its behavior is covered in the gate.
+
+A user should be able to point the assessment at where the external tests live (`--external-tests`); treat that location as source material, not as the destination.
+
+---
+
+## How Component Tests Run Without Configuring Dependencies
+
+The component test is the workhorse of a CD gate. The pattern, consistent across every component type:
+
+1. **Assemble the real component** — the actual handlers, domain logic, and orchestration — in-process.
+2. **Replace only what the team doesn't control** with in-memory doubles: the database (in-memory repository), the message broker (in-memory bus), downstream services (stubbed adapter), the clock (injected fixed clock), the scheduler.
+3. **Drive it through its public interface** — HTTP handlers, the message handler, the job entrypoint, the UI via a real browser with the network stubbed.
+4. **Assert on observable outcomes** — status, persisted state, emitted event, rendered output — never on internal call sequences or private methods.
+
+This yields tests that are fast (no I/O, no network), deterministic (no real systems, controlled clock), and need zero configuration of the surrounding system — while still validating real behavior end to end *within the component boundary*, including how it would interact with its collaborators (verified by contract, made real by integration).
+
+---
+
+## The Adapter Rule (own your boundaries)
+
+Wrap every third-party client (SDK, HTTP client, broker client, DB driver) in **a thin adapter the team owns**, then double the *adapter* in component tests — never mock the third-party SDK directly. The adapter is the seam:
+
+- **Component tests** double the adapter → fast, deterministic, no real dependency.
+- **Adapter integration tests** exercise the real adapter against a real container → assert the *adapter's* correctness (it speaks the protocol, builds the right request), not the dependency's behavior.
+
+This keeps the mock surface small, stable, and owned, and localizes every "the real thing changed" failure to one place.
+
+---
+
+## Outside-In First: Baseline Before Refactor
+
+You rarely start from a clean slate. When a component is poorly tested or untested ("legacy" = code without tests, regardless of age), **do not lead with refactoring.** The sequence that protects behavior:
+
+1. **Find the testable seams.** A seam is a place where behavior can be observed or substituted *without editing the code under test* — an HTTP handler, a CLI entrypoint, a message handler, an exported function, an existing injection point (object seams via interfaces/polymorphism; link seams via DI/module substitution). The outermost seam you can drive is usually the best starting point.
+2. **Write the best outside-in tests achievable now, without refactoring.** At the outermost reachable seam, write characterization tests that exercise the component as fully as possible and lock in its *current* observable behavior — even if you must tolerate some real dependencies or coarse assertions at first. The goal is a **behavior baseline**, not yet a clean CD gate.
+3. **Get the baseline green.** This is the safety net.
+4. **Now refactor to improve testability — under green.** Introduce adapters and seams (the Adapter Rule, `testability-patterns.md`), push checks down to deterministic component/unit tests, and tighten assertions. **Never change behavior and structure in the same step** (`legacy-code` skill). The baseline catches regressions the refactor might introduce.
+5. **Let the domain guide the target structure.** Use the DDD skills (`domain-driven-design`, `domain-analysis`) to suggest where boundaries, ports, and seams *should* go — so the refactor moves toward a sound domain model, not just toward testability.
+
+So an assessment recommends two things per under-tested component: **(a) the best outside-in test we can write today without touching the code** (immediate baseline), and **(b) the refactor sequence that improves testability afterward**, gated by that baseline. The full procedure lives in the `legacy-code` skill; this is its place in the CD test architecture.
+
+---
+
+## Double Validation (keeping doubles honest)
+
+A double that drifts from reality gives false confidence — the central risk of double-based isolation. Keeping a double honest has two independent jobs: **detect** when reality diverges, and **survive** the divergence when it happens.
+
+### Do not depend on provider cooperation
+
+Consumer-driven contract verification — where the *provider* runs your contract in *their* pipeline and is blocked from deploying a breaking change — only works when teams collaborate closely and use tooling that enforces it. **Assume you do not have that.** Design the strategy for the realistic case:
+
+- The provider can break the contract **without versioning**, at any time, with no notice.
+- Their production contract is **assumed broken until proven otherwise** — and you typically discover the break during your *next unrelated deploy*, which then wrongly implicates your change and burns an incident investigating the wrong thing.
+
+So provider-side verification is a *nice-to-have if the provider offers it* — never the mechanism you rely on.
+
+### The defense you own
+
+1. **Contract test** (pre-merge) pins the request the consumer sends and the response shape it depends on, against the adapter double. Blocks the build. This keeps *your* side stable and documents exactly what you assume of the provider.
+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**, decoupled from your deploy cadence. This is the primary defense: it detects a provider break **when it happens**, not when you next ship, so the break is attributed to the provider and not to your undelivered changes. Owned and run by your team; requires no provider cooperation.
+3. **Adapter integration test** (out-of-band, on a schedule — never in-band, regardless of ownership) runs the adapter against a real container of the production engine/broker (matching version + extensions) to confirm the double's protocol assumptions hold — see The Pre-Merge Gate Rule above.
+4. **Resilience verified by component tests** (pre-merge) — because you assume the provider *will* break, the consumer must be tested to **survive** it: timeouts enforce, retries/backoff/circuit-breaker behave, malformed or drifted responses are handled per Postel's Law, and the caller gets a documented response with no partial state. Detection (step 2) tells you it broke; resilience keeps you up until it's fixed.
+
+Doubles without steps 2 and 4 are a smell (see `microservice-testing.md` → "Stubs that lie", `test-smells.md` → behavior smells). The classic failure is a hand-written double that the team *assumes* still matches a provider nobody is checking.
+
+---
+
+## Determinism Techniques (minimal tooling)
+
+- **Inject the clock.** Replace system time with a fixed clock in every time-dependent test (`Clock.fixed(...)`). Keep exactly one out-of-band real-clock check to confirm production wiring (catches "tests use UTC, prod uses container local time").
+- **Inject randomness.** Same discipline for RNG and ID generation.
+- **No sleeps.** Never `sleep` to await; drive time and async deterministically.
+- **Real browser, stubbed network (UI).** Run UI component tests in a real engine (Chromium/Firefox/WebKit) with the backend stubbed at the network layer — not an in-memory DOM shim, which trades accuracy for speed and produces false positives on layout/timing.
+- **In-memory doubles over heavyweight test infra** for the gate. Reserve containers for adapter integration, off the merge path.
+
+---
+
+## Terminology Reconciliation (read this if you also use the Fowler files)
+
+This file uses **MinimumCD vocabulary**, which differs from the Fowler-based `test-pyramid.md` and `microservice-testing.md`:
+
+| Term | MinimumCD (this file) | Fowler (`test-pyramid.md`) |
+|------|----------------------|----------------------------|
+| **Component test** | Whole component through its public interface, uncontrolled systems doubled, **deterministic, pre-merge** | "Component / Service" — similar intent |
+| **Contract test** | Doubles that pin the boundary, **pre-merge**, validated by integration | Consumer-driven contract — same idea |
+| **Integration test** | Exercises real deps **specifically to validate the doubles**, non-deterministic, **post-merge only** | Broader: any test of a unit + one real external |
+| **Pre-merge gate** | Determinism is the gating criterion | Implicit in "fast tests at the base" |
+
+When advising for a CD pipeline, **prefer this file's framing** — the determinism→pre-merge axis is the organizing principle. Use the Fowler files for the general layering heuristic and the doubles taxonomy (`test-doubles.md`).
+
+## Boundaries
+
+- "Minimal tooling" means prefer in-memory doubles + a real browser + testcontainers for adapter checks — not a sprawl of test frameworks. Don't recommend heavyweight orchestration (full docker-compose of the system) for the gate; that's exactly the configured-dependency dependency this architecture removes.
+- These are starting points, not mandates. Real components have details these layers don't capture; drop items that don't apply and add what a component clearly needs.
+- This file defines the *architecture*. Per-component specifics (what to double, which failure modes) are in `component-test-patterns.md`.
+
+## The Pyramid Is a Cost Heuristic, Not a Target Shape
+
+The pyramid expresses that tests get more expensive — slower, flakier, longer
+feedback — as scope grows. It is not a silhouette to match.
+
+- **Never** produce "current shape vs recommended shape" tables or per-layer
+  target counts ("200 unit, 80 contract, 20 E2E"). The pyramid is not a quota.
+- The only valid framing is **per-behavior**: "this behavior is verified at
+  layer X; the lowest layer that could verify it is Y; here is why X." Justify
+  in both directions — a unit/component pick states why a higher layer would be
+  redundant; an integration/E2E pick states why a contract or component test
+  cannot cover the behavior.
+- If a suite shape is genuinely pathological (ice-cream cone, hourglass,
+  cupcake — see `test-pyramid.md#anti-patterns`), name the pathology and the
+  behaviors it harms. Do not propose a numeric redistribution.
+
+This is the canonical statement of the rule. Agents and skills cite this
+section rather than restating it.
+
+## The E2E Justification Gate
+
+E2E tests are non-deterministic and never gate a pre-merge build (see
+[The Pre-Merge Gate Rule](#the-pre-merge-gate-rule)). Never recommend an E2E
+test "for completeness" or "to round out the pyramid." Before recommending E2E
+for any behavior, document that **all four** conditions hold:
+
+1. A **contract test** cannot pin the boundary that catches this behavior.
+2. A **component test** with doubles cannot exercise it via the component's
+   public interface.
+3. A **resilience test** (timeout / retry / circuit-breaker / malformed
+   response) cannot cover the failure mode.
+4. The behavior is a **critical user journey across multiple real components**
+   that cannot be decomposed.
+
+If conditions 1–3 can cover the behavior, recommend that test instead and record
+one sentence on why E2E was *not* chosen. If only condition 4 applies, the
+recommendation must name the user journey, why contract + component + resilience
+together are insufficient, and the pipeline stage (post-deploy smoke, **never**
+pre-merge).
+
+This is the canonical statement of the gate. Agents and skills cite this section
+rather than restating the four conditions.

package/knowledge/ci-cd-file-scope.md

@@ -0,0 +1,24 @@
+# CI/CD file scope
+
+## Glob list
+
+The canonical glob list for "files that carry CI/CD pipeline configuration."
+Security-relevant content in these files (leaked secrets, `continue-on-error`
+on a security gate, overly broad `permissions:`) often escapes a normal
+`src/` tree walk, so any scan that claims to cover CI/CD must walk these
+paths explicitly — including up to the repo root in a monorepo, since a
+workflow file can live outside the scanned subtree.
+
+- `.github/workflows/*.{yml,yaml}` (GitHub Actions)
+- `.gitlab-ci.yml` + `.gitlab/**/*.{yml,yaml}` (GitLab CI)
+- `.circleci/config.yml` (CircleCI)
+- `azure-pipelines.yml` + `.azure-pipelines/**/*.{yml,yaml}` (Azure Pipelines)
+- `bitbucket-pipelines.yml`
+- `Jenkinsfile` + `jenkinsfile.d/**/*` (Jenkins)
+
+## Empty-scan reporting
+
+If a target has no files in any of these classes, record an empty scan
+result (e.g. `"ci_dirs_scanned": []`) rather than silently omitting the
+field — a reader must be able to tell "no CI files in scope" from "CI scope
+wasn't checked."