pi-dev-team 0.2.0

package/knowledge/dependency-breaking-techniques.md

@@ -0,0 +1,116 @@
+# Dependency-Breaking Techniques
+
+Reference file for the `legacy-code` skill, the `test-design-advisor` skill, and the `test-smell-review` agent. When code can't be placed in a test harness, you need a **seam** — a place to substitute a collaborator or behavior without rewriting the code. This is the full catalog of behavior-preserving moves that *create* such a seam, so you can get legacy code under test before changing it.
+
+Source: Michael Feathers, *Working Effectively with Legacy Code* (2005), Ch. 25 *Dependency-Breaking Techniques* (plus the Sprout/Wrap moves from Ch. 6). Language-agnostic; some techniques are specific to a language family and are marked.
+
+Core principle: **break the smallest dependency that gets the code under test, and preserve behavior while doing it.** Every break is temporary scaffolding — once tests exist, refactor toward a real design (constructor injection, ports). Prefer the lowest-risk technique that works; reach for `Extract Method` first when nothing else presents a seam.
+
+See `legacy-code` (the procedure: Legacy Code Change Algorithm, seam types, characterization tests), `legacy-test-strategy.md` (where to test — effect reasoning, pinch points), and `testability-patterns.md` (the *target* design these scaffold toward).
+
+---
+
+## How to choose
+
+```
+What is blocking the test?
+├─ A collaborator created INSIDE the class/method
+│   ├─ created in the constructor → Parameterize Constructor / Supersede Instance Variable
+│   ├─ created in a method        → Parameterize Method / Extract and Override Factory Method
+│   └─ obtained via a call        → Extract and Override Call / Extract and Override Getter
+│
+├─ A concrete TYPE you can't substitute
+│   └─ Extract Interface / Extract Implementer, then Subclass and Override Method
+│
+├─ A GLOBAL / singleton / static
+│   └─ Encapsulate Global References · Replace Global Reference with Getter ·
+│      Introduce Static Setter · Introduce Instance Delegator
+│
+├─ The class is too big / method too long to instantiate or run
+│   └─ Sprout Method/Class · Wrap Method/Class · Break Out Method Object · Expose Static Method
+│
+├─ A parameter you can't construct or sense through
+│   └─ Adapt Parameter · Primitivize Parameter · Pull Up Feature · Push Down Dependency
+│
+└─ Procedural / compiled / interpreted language with few OO seams
+    └─ Link Substitution · Replace Function with Function Pointer ·
+       Definition Completion · Template Redefinition · Text Redefinition
+```
+
+---
+
+## The catalog
+
+### Add behavior without touching the untested code (Ch. 6)
+
+| Technique | What it does | Seam | Risk |
+|-----------|-------------|------|------|
+| **Sprout Method** | Put new behavior in a new method, call it from the existing one | object | low |
+| **Sprout Class** | Put new behavior (needing its own state/logic) in a new class, call into it | object | low–med |
+| **Wrap Method** | Rename the original, add a new method that calls it plus the new behavior | object | low |
+| **Wrap Class** | A new class (decorator) wraps the original; callers see the new behavior transparently | object | medium |
+
+### Break a created/obtained collaborator
+
+| Technique | What it does | Seam | Risk |
+|-----------|-------------|------|------|
+| **Parameterize Constructor** | Move a constructor-created dependency to a constructor parameter | object | low |
+| **Parameterize Method** | Pass in an object a method creates internally, rather than `new`-ing it | object | low |
+| **Extract and Override Call** | Move a problem call into its own method, override it in a test subclass | object | low |
+| **Extract and Override Factory Method** | Move `new` out of a constructor into an overridable factory method | object | medium |
+| **Extract and Override Getter** | Serve a dependency through a getter, override it to return a fake (C++ where factory-method override is unsafe) | object | medium |
+| **Supersede Instance Variable** | Add a setter to replace an instance variable built in the constructor (when override isn't viable) | object | medium |
+
+### Substitute a type
+
+| Technique | What it does | Seam | Risk |
+|-----------|-------------|------|------|
+| **Extract Interface** | Pull an interface off a concrete class so a fake can implement it. The safest OO break — the compiler catches missteps | object | low |
+| **Extract Implementer** | The inverse rename: keep the interface name, rename the class to the implementer | object | low |
+| **Subclass and Override Method** | Subclass the real class in the test and override the seam method. The core OO technique — many others are variations | object | medium |
+
+### Tame globals, singletons, and statics
+
+| Technique | What it does | Seam | Risk |
+|-----------|-------------|------|------|
+| **Encapsulate Global References** | Gather references to a global behind a class you can fake or relink | object/link | medium |
+| **Replace Global Reference with Getter** | Read a global through an overridable getter instead of directly | object | low |
+| **Introduce Static Setter** | Add a setter so a singleton's instance can be replaced in tests | object | medium |
+| **Introduce Instance Delegator** | Add instance methods that delegate to static ones, so callers can be given a fake | object | low |
+| **Expose Static Method** | Promote logic that uses no instance state to a static method you can test without instantiating | — | low |
+
+### Work around hard parameters and big methods
+
+| Technique | What it does | Seam | Risk |
+|-----------|-------------|------|------|
+| **Adapt Parameter** | Wrap a hard-to-fake parameter type behind a narrow interface you control | object | medium |
+| **Primitivize Parameter** | Add a free function that does the work against primitive data, called by a thin method — a temporary step toward a real test | object | medium |
+| **Break Out Method Object** | Move a long method into its own class whose fields are the locals/params, so it can be instantiated and tested | object | medium |
+| **Pull Up Feature** | Pull the cluster you need to test into an abstract superclass, away from the problem dependencies | object | medium |
+| **Push Down Dependency** | Push the problem dependencies down into a new subclass, leaving a testable abstract parent | object | medium |
+
+### Non-OO / compiled / interpreted seams
+
+| Technique | What it does | Seam | Risk |
+|-----------|-------------|------|------|
+| **Link Substitution** | Link the test against an alternative implementation of a library/object | link | medium |
+| **Replace Function with Function Pointer** | Indirect a function call through a pointer you can repoint in tests (C) | link | medium |
+| **Definition Completion** | Provide a test-only definition for a header-declared function/class (C/C++) | preprocessing | high |
+| **Template Redefinition** | Substitute a dependency's type via a template parameter at compile time (C++) | preprocessing | medium |
+| **Text Redefinition** | Redefine a method's body at run time in a dynamic language (Ruby, etc.) | preprocessing | medium |
+
+---
+
+## Most common in practice
+
+The legacy-code skill keeps a shortlist for the day-to-day cases; the rest of the catalog is here when those don't fit. The everyday set: **Extract Interface**, **Parameterize Constructor**, **Subclass and Override Method**, **Extract and Override Call/Factory Method**, **Sprout/Wrap Method**, and **Adapt Parameter**. Reach into the long tail (globals, non-OO, parameter, and big-method groups) when the everyday break doesn't present a seam.
+
+---
+
+## How this connects to the rest of the toolkit
+
+- **`legacy-code` skill** — owns the procedure (Change Algorithm, seam types, characterization tests); this file is its technique reference.
+- **`legacy-test-strategy.md`** — *where* to place the test (effect reasoning, interception/pinch points) once a seam exists.
+- **`testability-patterns.md`** — the production-code *target* design (constructor injection, interface extraction, Humble Object) these temporary breaks scaffold toward; a break is a means, the seam family there is the end.
+- **`test-doubles.md`** — once a seam exists, the double that fills it (Stub/Spy/Mock/Fake), including Test-Specific Subclass (the double form of Subclass and Override Method).
+- **`test-automation-principles.md`** — *Design for Testability* and *Don't Modify the SUT*: override only the seam, never behavior the test is verifying.

package/knowledge/deployment-pipeline.md

@@ -0,0 +1,86 @@
+# Deployment Pipeline Anatomy
+
+Reference for the structure of a deployment pipeline and the configuration and
+environment discipline it depends on. Source: *Continuous Delivery* (Humble &
+Farley) Ch.5 (anatomy), Ch.2 (configuration management), Ch.11 (infrastructure
+and environments). Advisory — the plugin designs and assesses pipelines; the
+test-gate mechanics live in `cd-test-architecture.md`.
+
+A deployment pipeline is the automated manifestation of the process for getting
+software from version control to the user. Each change enters once and is either
+proven releasable or rejected.
+
+## The stages
+
+A change flows through ordered stages; success in one triggers the next.
+
+| Stage | Purpose | Gate |
+|-------|---------|------|
+| **Commit** | Compile, unit + component + contract tests, static analysis. Fast (minutes). | Blocks merge — see `cd-test-architecture.md` |
+| **Acceptance** | Automated acceptance tests against a production-like deploy of the built artifact | Behavior matches the executable spec |
+| **Capacity / nonfunctional** | Performance, load, and resilience tests as a stage, not an afterthought | Meets the agreed budgets |
+| **Manual / UAT** | Exploratory testing, demos, showcases — on demand | Human judgment |
+| **Release** | Push-button deploy of the *same* artifact to production | Approved; smoke test green |
+
+## The pipeline principles
+
+- **Build your binaries only once.** Compile and package in the commit stage,
+  store the artifact in a repository (not in version control), and **promote the
+  same binary** through every stage. Never rebuild from source per environment —
+  a rebuilt binary is a different binary.
+- **Binaries are environment-agnostic.** Separate code (constant across
+  environments) from configuration (varies per environment). A binary that only
+  runs in one environment is a defect.
+- **Deploy the same way to every environment.** Dev, test, and production use the
+  identical automated deploy process, so it is rehearsed hundreds of times before
+  a production release.
+- **Smoke-test every deployment.** An automated post-deploy check confirms the app
+  and its dependencies (DB, message bus, external services) are up. After unit
+  tests, this is the most valuable test you have.
+- **Deploy into a copy of production.** Test/CI environments match production in
+  infrastructure, OS config/patches, app stack, and relevant data state.
+- **Each change propagates instantly.** The first stage triggers on every
+  check-in; each stage triggers the next on success — no nightly batching. When
+  busy, build off the most recent set of changes.
+- **Cycle time is the primary global metric** (commit → releasable). Apply the
+  Theory of Constraints: find the bottleneck stage and elevate it. Coverage,
+  defect counts, and build duration are secondary diagnostics. Radiate them.
+- **The pipeline is part of the product.** Build it incrementally; version,
+  test, and refactor it with the same care as the application.
+
+## Configuration management (Ch.2)
+
+| Practice | What it means |
+|----------|---------------|
+| **One version-controlled source per environment** | Deploy-time config lives in a single source (properties files / directory service / database), selected per environment by hostname or env var. One source for all apps in all environments. |
+| **No config in the binary** | The same artifact reads its config from the environment; no per-environment builds. |
+| **Secrets are not in version control** | Inject secrets at deploy/runtime (a secret store / vault / sealed env); never bake credentials into the image or commit them. (See `docker-image-audit` for image-level checks.) |
+| **Config is testable** | A wrong or missing config value should fail fast at startup (a smoke test), not silently. |
+
+## Infrastructure and environments (Ch.11)
+
+- **Specify desired state as version-controlled configuration** — OS install
+  definitions, middleware, network, data-center automation. Provisioning is
+  automated so any environment can be re-created from scratch to a known-good
+  state in a predictable time.
+- **All environments are production-like** and managed with the *identical*
+  techniques used for production.
+- **Know the actual state** through instrumentation and monitoring; infrastructure
+  should self-correct toward the desired state.
+- **Lock down production.** Only the pipeline changes it — giving a complete audit
+  trail of who changed what, when. No manual changes on production.
+
+## Scope note (advisory boundary)
+
+This plugin **designs and assesses** pipelines and **plans** changes to fit them.
+It does not author IaC stacks (Terraform/Helm), operate artifact repositories, or
+execute deployments. Recommend those; don't simulate them.
+
+## How this connects to the rest of the toolkit
+
+- **`cd-test-architecture.md`** — the commit-stage gate's test types and
+  determinism rules; this file places that gate inside the whole pipeline.
+- **`release-strategies.md`** — what the release stage actually does (blue-green,
+  canary, rollback, decouple deploy from release).
+- **`cd-maturity-model.md`** — cycle time, traceability (build-once + hash), and
+  production lock-down are scored there as you move up the model.

package/knowledge/design-smells.md

@@ -0,0 +1,122 @@
+# Design Smells
+
+Reference file for structure-review and naming-review agents. Use the smell → pattern table to make findings actionable: every finding should name the smell, quote the code, name the remediation pattern, and include a refactor sketch.
+
+---
+
+## Design Smells → Pattern Mapping
+
+| Smell | Signature in code | Remediation pattern |
+|---|---|---|
+| **Switch on type discriminator** | `switch (type) { case A: ...; case B: ...; }` or `if (x is A) ... else if (x is B) ...` repeated across multiple methods | **Replace Conditional with Polymorphism** → Strategy (behavior-driven) or State (lifecycle-driven) |
+| **If/else cascade on type/state** | Same shape as above in `if`/`elif` form | Same: Replace Conditional with Polymorphism |
+| **Long parameter list** | Function with 5+ parameters; reader can't recall positional meanings | **Introduce Parameter Object** — bundle related params into a named request/options type |
+| **Data clumps** | Same group of 3+ parameters or fields travels together everywhere (`firstName, lastName, dob`) | **Extract Class / Value Object** — the clump is an unnamed concept |
+| **Primitive obsession** | Business concepts modeled as raw strings/numbers (`string customerId`, `int amount`) | **Value Object** — typed wrapper with validation and equality |
+| **Magic number / magic string** | Literals like `if (retries > 3)` or `if (status == "PND")` | **Replace Magic Literal** — extract named constant or enum; promote to Value Object when it carries business meaning |
+| **Flag argument** | `process(true, false)` — boolean params that switch method behavior | **Split Method** — one method per branch; the flag is hiding two operations |
+| **Long method** | Method >20 lines, often readable only with sub-section comments | **Extract Method** — each sub-section comment becomes a named method call |
+| **Feature envy** | Method on class A reaches deeply into class B's data (`b.x.y.z`) | **Move Method** — relocate to class B where the data lives |
+| **Shotgun surgery** | One conceptual change requires edits in 5+ unrelated classes | **Move Method / Move Field** — consolidate responsibility into one class |
+| **Divergent change** | One class changes for many different reasons (auth, persistence, formatting) | **Extract Class** along the change axes — one class per reason-to-change |
+| **Refused bequest** | Subclass overrides many parent methods to no-op or throw "not supported" | **Replace Inheritance with Composition** — the subclass needs *some* of the parent API; expose those via a member |
+| **Speculative generality** | Abstract base classes or interfaces with only one implementation and no near-term plan for a second | **Inline Class** — collapse the abstraction; re-introduce when a second implementation appears |
+| **Megaclass** | Class with 30+ public methods, multiple responsibilities, `*Manager`/`*Service`/`*Helper` suffix | **Extract Class** along responsibility lines; apply SRP |
+| **Reinvented built-in / helper** | A hand-written loop or expression recomputes a standard-library operation (min, max, sum, copy, reverse, clamp) or duplicates a named helper that already exists in the module | **Use the platform** — replace with the built-in / existing helper so the algorithm reads top-down (see cheat-sheet below) |
+| **Open-coded idiom** | The same non-trivial boolean or arithmetic expression (e.g. `Math.abs(x - y) > tol`) appears 3+ times inline instead of behind a named predicate | **Extract Method** — name the idiom (`withinTolerance`) so each call site states intent, not mechanics |
+
+## Reinvented Built-in Cheat-Sheet
+
+The "use the platform" smell is **language-agnostic** — recognize the *concept*
+(a hand-rolled standard operation), then map it to the project's language. Flag
+only as a `suggestion`; this is a readability call, not a correctness bug.
+
+| Language | Hand-rolled → built-in (examples) |
+|---|---|
+| JS/TS | min/max scan → `Math.min(...xs)` / `Math.max(...xs)`; accumulator loop → `reduce`; `0 - x` → unary `-x`; copy loop → spread / `slice` |
+| Python | min/max scan → `min()` / `max()`; accumulator loop → `sum()`; reimplemented `itertools` / `collections` helper |
+| Java | loop → `Stream.min/max`, `Collectors`, `Math.max` |
+| C# | loop → LINQ `Min` / `Max` / `Sum` / `Aggregate` |
+| Go | loop → `min` / `max` **built-ins (Go 1.21+ only)**, `slices` / `maps` packages |
+
+### What NOT to flag (reinvented built-in)
+
+- A manual min/max (or similar) loop in a language/version that lacks the
+  built-in — e.g. **Go before 1.21** has no `min`/`max`; the loop is idiomatic.
+  Confirm the built-in exists for the project's language *and version* first.
+- A hand-rolled form with a comment or context marking it a deliberate hot-path
+  optimization (avoiding intermediate allocation, the spread argument-count
+  limit, etc.) — confidence `none`, do not flag.
+- C or other environments with no standard library for the operation.
+
+## What NOT to Flag
+
+- A `switch` over a closed enumeration where adding a case is rare (e.g., `DayOfWeek`, `HttpMethod`) — polymorphism adds ceremony without benefit
+- A method whose extraction would only add a name without reducing cognitive load
+- A 6-parameter constructor in a DI-injected class where all 6 are collaborators (not data clumps) — Parameter Object applies to *data* clumps, not dependency lists
+- Speculative generality concerns on code that *will* gain a second adapter this sprint (per the team's roadmap)
+
+---
+
+## Finding Format
+
+When surfacing a design smell as a finding:
+
+```
+Severity: error (blocks testing or hides a bug) | warning (impedes change) | suggestion (stylistic)
+Smell: <smell name from table above>
+File: path/to/file.ext:LINE
+Code: <2-5 line quote of actual code>
+Pattern: <recommended pattern>
+Fix: <refactor sketch — 1-3 sentences on what the change looks like>
+```
+
+---
+
+## Naming Offender Catalog
+
+### Abbreviations that obscure intent
+
+| Offender | Fix | Notes |
+|---|---|---|
+| `getEffDate` | `getEffectiveDate` | `Eff` is an internal abbreviation |
+| `calcAmt` | `calculateAmount` | Two abbreviations + missing what amount |
+| `OrderMgr` | `OrderRepository` or `OrderShippingService` | `Mgr` is vacuous — replace with the actual role |
+| `tmpResult` | `intermediateTotal` | `tmp` reveals nothing about what it holds |
+| `proc` / `Proc` | `processor` / `PaymentProcessor` | Spell out domain roles |
+| `m_orderId` / `g_orderId` | `_orderId` (private) / `orderId` (local) | Hungarian prefix residue |
+
+### Generic verbs that hide intent
+
+| Offender | Fix | Reason |
+|---|---|---|
+| `processOrder` | `submitOrder` / `confirmOrder` / `cancelOrder` | "Process" hides which lifecycle step |
+| `handleException` | `logAndSwallow` / `rethrowAsFault` / `retryWithBackoff` | "Handle" hides the actual policy |
+| `doWork` | (the verb that names the work) | "Do" reveals nothing |
+| `manage*` (`manageCart`, `manageInventory`) | Split into named operations: `addItem`, `removeItem` | "Manage" at class level is a smell; split into named methods |
+| `update*` without qualifier | `markAsShipped` / `recordPayment` | "Update" hides which fields change and why |
+| `execute` (outside Command/Strategy pattern) | The specific action | OK on `ICommand.execute()`; suspect elsewhere |
+
+### Misleading names
+
+| Offender | Why it misleads | Fix |
+|---|---|---|
+| `getCustomerOrThrow` returning null | Name says throw, code says null | Use `tryGetCustomer(out)` or actually throw |
+| `isValid` that mutates state | "is" implies pure query | Split: `validate()` (mutates) + `isValid` (pure) |
+| `save()` that may no-op | Name implies always-persists | `persistIfDirty()` or `flushPendingChanges()` |
+| `cancel*` that emits an event but doesn't cancel state | Misnamed | `requestCancellation()` |
+
+### Type-encoded names
+
+| Offender | Fix |
+|---|---|
+| `stringList`, `intCount`, `boolIsActive` | `names` / `list`, `count`, `isActive` |
+| `ICustomerInterface`, `OrderClass` | `ICustomer`, `Order` |
+
+### What NOT to flag
+
+- Loop counters: `i`, `j`, `k` are conventional
+- Lambda parameters with single use: `x => x.id` doesn't need `customer => customer.id`
+- Industry-standard acronyms: `HttpClient`, `XmlReader`, `JsonSerializer`, `SqlConnection`, `JWT`
+- Domain-standard acronyms defined in the project's glossary (`.plans/domain/`)
+- Test method names following `MethodName_Scenario_ExpectedResult` convention

package/knowledge/directory-enumeration.md

@@ -0,0 +1,38 @@
+# Directory Enumeration
+
+## The rule
+
+**Never `Read` a directory path to check whether something exists or to see
+what it contains.** `Read` expects a file; pointed at a directory it throws
+`EISDIR`. This hazard fires whenever an instruction says *what* to detect
+("no plan files exist in `plans/`", "no spec artifacts found", "no `agents/`
+directory") without saying *how* — the model reaches for the nearest tool
+(`Read`) instead of the correct one.
+
+**Use `Glob` for existence checks and enumeration:**
+
+- Existence of a known directory: `Glob(".claude/**")`, `Glob("plans/**")`.
+- Enumerating a directory's contents: `Glob("agents/*.md")`,
+  `Glob("docs/specs/**/*.md")`.
+- Checking for one specific candidate file: a targeted `Read` of that exact
+  path is fine (e.g. `Read("docs/specs/foo/spec.md")`) — the hazard is only
+  `Read`-ing the *directory itself*, not a known filename inside it.
+
+An empty `Glob` result means "not present" — no directory read is needed to
+reach that conclusion.
+
+## Why this is shared, not local
+
+This same hazard has been independently discovered and locally patched three
+times (agent-roster enumeration, `--path` target resolution, `## Skip`
+existence probing) before this file existed. Citing this file from any
+Skip/detection section that implies "check whether X exists" prevents a
+fourth local fix.
+
+## How this connects to the rest of the toolkit
+
+Cited by `skills/code-review/SKILL.md` and by review-agent/skill Skip or
+detection sections that probe for a directory's presence or contents
+(`claude-setup-review`, `progress-guardian`, `spec-compliance-review`, the
+`continue` skill) — add a citation here rather than re-explaining the
+mechanism inline.

package/knowledge/domain-modeling.md

@@ -0,0 +1,123 @@
+# Domain Modeling Patterns
+
+Reference file for the domain-review agent. Read this before starting
+analysis to apply DDD assessment patterns.
+
+## Exploration Patterns
+
+Map the project structure before detecting issues.
+
+### Entity / Model discovery
+
+| Glob pattern | What it finds |
+|--------------|---------------|
+| `**/domain/**`, `**/entities/**`, `**/models/**`, `**/aggregates/**` | Domain layer |
+| `**/services/**`, `**/application/**`, `**/usecases/**`, `**/handlers/**` | Application layer |
+| `**/repositories/**`, `**/dal/**`, `**/persistence/**`, `**/infrastructure/**` | Data access layer |
+| `**/dto/**`, `**/dtos/**`, `**/responses/**`, `**/contracts/**`, `**/api/**`, `**/viewmodels/**` | Transfer objects |
+
+### ORM marker detection
+
+| Language | Grep patterns |
+|----------|---------------|
+| JS/TS | `@Entity`, `@Table`, `@Column`, `@Document` |
+| C# | `[Table]`, `[Key]`, `[Column]`, `DbContext`, `DbSet<` |
+| Java | `@Entity`, `@Table`, `@MappedSuperclass`, `@Repository` |
+
+### Boundary entry point detection
+
+| Language | Grep patterns |
+|----------|---------------|
+| JS/TS | `express`, `fastify`, `Request, Response` |
+| C# | `ControllerBase`, `[ApiController]`, `IActionResult` |
+| Java | `@RestController`, `@Controller`, `@RequestMapping` |
+
+### Application service detection
+
+| Language | Grep patterns |
+|----------|---------------|
+| JS/TS | `@Injectable`, `@Service`, class names ending in `Service` |
+| C# | Class names ending in `Service`, `Handler`, `UseCase` |
+| Java | `@Service`, `@Component`, class names ending in `Service`, `Handler` |
+
+If none of these patterns yield files, return skip.
+
+## Anti-Pattern Recognition
+
+### Business Logic Misplacement
+
+Logic belongs in the domain layer. Flag when found in:
+
+| Wrong location | Signal |
+|---------------|--------|
+| Controllers/routes | Discount calculations, validation rules, authorization logic in route handlers |
+| Repositories/DAL | Business rules in SQL queries, computed columns, trigger-like logic |
+| Application services | Rules that should be on an entity or domain service (application services orchestrate, they don't own rules) |
+
+Exception: domain services legitimately own rules that span multiple entities.
+
+### Anemic Domain Model
+
+Entities that are pure data holders (only getters/setters) while services
+contain all behavior. Signs:
+
+- Entity has 10+ properties but 0 methods beyond accessors
+- Service methods that take an entity, inspect its state, and return a decision
+- External callers setting status fields directly instead of calling intention-revealing methods (`order.status = 'paid'` vs `order.markPaid()`)
+
+### Abstraction Leaks
+
+| Leak type | Signal |
+|-----------|--------|
+| ORM in domain | Domain objects with `@Column`, `[Table]`, persistence annotations |
+| HTTP in domain | Domain objects importing `Request`, `Response`, HTTP status codes |
+| Infrastructure in domain | Domain layer importing database clients, message queues, file I/O |
+
+### Boundary Violations
+
+| Violation | Signal |
+|-----------|--------|
+| Missing DTOs | Domain entities returned directly from API endpoints |
+| Cross-context coupling | Direct imports between bounded contexts instead of events/shared kernel |
+| Aggregate boundary bypass | Reaching into an aggregate's child entities directly |
+
+### Implicit Concepts (missing Specification / Policy)
+
+A named business rule hiding inside scattered conditionals. Surface it as a Specification or Policy object.
+
+| Signal | What it implies |
+|--------|-----------------|
+| The same multi-clause boolean (`if a && b && !c`) duplicated in 2+ places | A domain rule with a name the experts already use — extract to a specification/policy object |
+| A rule expressed as a comment (`// orders over $X to a new address need review`) but enforced ad hoc | The concept exists in language but not in the model |
+| A boolean-returning method on a service that inspects another object's fields | Tell-don't-ask + a candidate specification owned by the domain |
+
+Only flag duplication or comment-encoded rules you can point to. A single, local condition is not a missing specification.
+
+### Construction Without Invariants (missing Factory)
+
+| Signal | What it implies |
+|--------|-----------------|
+| Public constructor / object literal that lets a caller build an invalid aggregate (required field unset, two fields that must agree set independently) | Construction invariant is unenforced — a factory or a guarding constructor should make the object valid-on-creation |
+| The same multi-step assembly of an aggregate repeated across call sites | Creation logic belongs in one factory, not copied into clients |
+
+Do not flag simple objects that are valid by plain construction — a factory there is overhead.
+
+### Supple Design Smells (domain model only)
+
+Scope these to **domain entities, value objects, and domain services** — general purity/coupling elsewhere belongs to `js-fp-review` and `structure-review`, not here.
+
+| Smell | Signal | Fix direction |
+|-------|--------|---------------|
+| Not intention-revealing | A domain method named for *how* not *what* (`recalc`, `doProcess`), or a boolean flag parameter that switches behavior (`price(true)`) | Rename to the domain verb; split the two behaviors |
+| Side effect in a query | A method on a value object or entity that both mutates state and returns a value (violates command-query separation) | Separate the command from the query; value objects expose only side-effect-free operations |
+| Mutable value object | A type used as a value (money, range, coordinate) with public setters or in-place mutation | Make it immutable; return new instances |
+| Unenforced invariant | An entity/aggregate whose invariant is asserted by callers rather than guarded internally | Move the invariant into the type (constructor, factory, or guarded mutator) |
+
+### Ubiquitous Language Drift
+
+Flag only internal inconsistency observable in code:
+
+- Same concept with different names across modules (`Order` / `Purchase` / `Transaction`)
+- Generic names where domain terms exist (`process`, `handle`, `data`, `info`, `manager`)
+
+Do not flag terminology as wrong based on assumed business language.

package/knowledge/evidence-bundle.md

@@ -0,0 +1,90 @@
+# Evidence Bundle
+
+A structured "what was checked, and what wasn't" statement carried by `/build`'s
+final output and `/pr`'s PR body. Verification here is a stack of scoped
+verifiers — unit suite, type check, lint, review agents, coverage delta,
+runtime verification (sub-step 4.9), Farley score — not one boolean. A green checkmark alone
+over-claims: it says checks passed but not what each one actually verified,
+what it structurally cannot verify for this diff, which regions remain
+untested, or what risk was consciously accepted. The bundle closes that gap.
+
+**Reporting only — no new checks.** The bundle is assembled entirely from data
+the pipeline already produces: quality-gate outputs, `.claude/metrics/review-value.jsonl`,
+`metrics/verify-log.jsonl`, coverage baseline/delta files, and gate-bypass audit
+lines already written to the build/PR output. Assembling it never re-runs a
+check, never invokes a tool "just to build the bundle."
+
+Reference form: `${CLAUDE_PLUGIN_ROOT}/knowledge/evidence-bundle.md`.
+
+## The four fixed sections
+
+Always present, in this order, with these exact headers. **Degradation rule**:
+when a section has no data, it states why (e.g. "not measured — no coverage
+tool detected") — it is never dropped. All four headers always appear even on
+a run with nothing to report in one of them.
+
+| Section | Content | Data source (already produced) |
+|---|---|---|
+| Checks run | One row per verifier: exact command executed + result summary | `/pr` Step 2 gate commands/output; `/build` Step 5 suite output, Step 6 review status, Step 7 Farley score |
+| Scope notes | What the executed suite does NOT verify for this diff | Review agents dispatched vs. skipped; gate steps reported "not applicable"; `metrics/verify-log.jsonl` `skipped` reasons; absent tools (coverage, mutation) |
+| Untested regions | Coverage-derived statement of what the diff leaves unexercised | `baseline-coverage.json` + `coverage-history.json` line/branch % and delta; diff-scoped uncovered files from a coverage report artifact when one exists; "not measured" when none exists |
+| Residual risks | Consciously accepted risk, derived-first | Deferred/escalated findings (`.claude/metrics/review-value.jsonl`), gate-bypass audit lines, structural-review waivers, negative coverage-delta warnings; author-judged prose may be appended but never substitutes for the derived rows |
+
+## Skeleton
+
+```markdown
+## Evidence Bundle
+
+**Checks run**
+- `<exact command>` — <result summary>
+- `<exact command>` — <result summary>
+(N checks total; showing top N — see full log at <pointer> if truncated)
+
+**Scope notes**
+- <what this suite does not cover for this diff, one line each>
+
+**Untested regions**
+- <line/branch % + delta, or diff-scoped uncovered files, or "not measured — <reason>">
+
+**Residual risks**
+- <deferred/escalated finding, waiver, or bypass line — or "None identified" only when every derived source is empty>
+```
+
+## Degradation examples
+
+- No coverage tool detected:
+  `Untested regions: not measured — no coverage tool detected in this repo.`
+  paired with a matching Scope note: `Scope notes: coverage delta unavailable — no coverage baseline exists for this repo.`
+- No deferred/escalated findings, no waivers, no bypass lines, no negative
+  coverage delta: `Residual risks: None identified — no deferred findings, waivers, or bypass lines this run.`
+- Non-interactive bypass recorded during the run: fold the audit line in verbatim,
+  e.g. `Residual risks: Acceptance-criteria gate auto-passed with 1 flagged criterion (non-interactive) — no human gate.`
+
+## Line budget
+
+Target **under ~40 lines** in a PR body. When a section's data would exceed
+that, collapse to counts plus a pointer to the full log rather than growing
+unbounded — e.g. `12 checks run, 12 passed (full command log in build output above)`
+instead of listing all 12 rows.
+
+## Assembly is per-command, not handed off
+
+`/build` assembles its bundle from its own run's Step 5/6/7 outputs at Step 8.
+`/pr` assembles its bundle from its own Step 2 quality-gate results plus
+on-disk pipeline data (metrics files, coverage files) at its own runtime —
+never from a handoff file written by `/build`. Running `/pr` standalone (no
+preceding `/build` in the session) still produces a complete bundle; sections
+degrade per the rule above wherever the on-disk data doesn't cover a source
+that only `/build`'s in-session steps would have (e.g. Farley score).
+
+## Boundaries
+
+- Does not persist to `.claude/metrics/` or `.claude/memory/` — every underlying datum already
+  persists in its own source file; a persisted bundle would duplicate that
+  audit trail.
+- `/code-review`'s own report keeps its existing contract
+  (`knowledge/review-template.md`); it is one **input** to the bundle's Checks
+  run section, not a carrier of the bundle itself.
+- Never displaces the PR body's closing keywords (`Closes #N` / `Part of #`)
+  or its other sections (`## Summary`, `## Quality Gate`, `## Decisions &
+  Assumptions`, `## Test Plan`) — it is added alongside them.