pi-dev-team 0.2.0

package/knowledge/internal-collaborator-doubling.md

@@ -0,0 +1,101 @@
+# Internal-Collaborator Doubling: The Blocker Rule
+
+Reference file for `test-review`, `test-smell-review`, `test-design-advisor`,
+the internal-double detector (#2127), and the authoring lane
+(`software-engineer`, `qa-engineer`, `/build`, `/test-driven-development`).
+This is the **single normative source** for when doubling a collaborator
+declared in the project's own first-party source is admissible. Every
+consumer cites this file by path; none restates it.
+
+Source: epic #2123.
+
+## The rule
+
+In any test at or below the component layer, **a collaborator declared in
+the project's own first-party source stays real.** A double standing in for
+one is admissible only when that collaborator matches a blocker below.
+
+There is no test-type exemption. "Solitary unit test" stops being a licence
+to double everything and becomes "a unit test whose every double names a
+blocker."
+
+## The three blockers (exhaustive)
+
+Each is a property of **the collaborator**, never of the test. A double is
+the fallback in all three — making the boundary explicit and injecting it is
+preferred.
+
+| # | Blocker | Holds when | Preferred remedy before doubling |
+|---|---|---|---|
+| **B1** | Out-of-process handle | The collaborator holds or opens a handle beyond this process — socket, DB connection, URL, file handle, broker channel, subprocess | Double the leaf it wraps, not the collaborator |
+| **B2** | Ambient state | It reads non-injectable ambient state — clock, RNG/GUID, env, hostname, cwd, locale | Inject a value or port; double only if injection is not yet available |
+| **B3** | Prohibitive real cost | Real execution makes the test non-viable at this layer's speed — production-factor KDF, deliberate retry backoff, heavy computation | Parameterize the cost so the real code path still runs |
+
+## Non-reasons (normative, so the rule is falsifiable)
+
+None of the following, alone, is a blocker — doubling on their basis alone
+is inadmissible:
+
+- "This test isn't about X" / "I only want this branch"
+- "Setup is easier" / "the double was faster to write"
+- "The collaborator has its own tests"
+- "It's an injected interface" — and the type's name: `*Service`, `*Client`,
+  `*Provider`, `*Gateway`, `*Manager`, `*Repository` say nothing about which
+  side of a boundary a type sits on
+- Forcing an error path that is unreachable through the public interface —
+  treat that as evidence the handling is dead or the seam is wrong, not as a
+  blocker
+
+## Patching internal functions
+
+Reaching into a module to replace a function (`unittest.mock.patch`,
+`vi.spyOn`, monkeypatching a module attribute) is the same defect in a worse
+form: it needs no seam, so it applies zero design pressure and couples the
+test to the callee's name and location. It is **never** admissible under
+B1–B3. Where a blocker genuinely applies, extract the boundary and inject
+it.
+
+## The waiver
+
+An admitted double carries an inline comment marker at the double site,
+naming the blocker and the reason. Comments are the one mechanism every
+stack has, and colocating the waiver with the double is what stops it
+drifting from the code it justifies:
+
+```
+// double-waiver: B1 — SmtpGateway holds the SMTP socket
+var mail = Substitute.For<ISmtpGateway>();
+
+# double-waiver: B2 — reads the system clock
+with patch("billing.clock.now") as now:
+
+// double-waiver: B3 — Argon2 at prod work factor (~800ms)
+const hasher = vi.mocked(passwordHasher)
+```
+
+**Visibility, not sign-off.** The waiver needs no separate approval step.
+The author states the blocker; the reviewer challenges it like any other
+line of the diff, and `test-smell-review` judges whether the claim is true.
+B1 and B2 doubles are common (DB, clock, HTTP), so an approval gate on each
+would make the rule a bottleneck rather than a backstop.
+
+## A declaration never exempts
+
+`solitary` and `sociable` both survive as vocabulary, redefined: a
+**sociable** unit test uses its real collaborators; a **solitary** unit test
+is one whose every double names a blocker. Neither exempts the
+internal-collaborator rule, and neither does any other test-type
+declaration.
+
+This is worth stating explicitly because "solitary" historically *meant*
+the exemption being removed here. Test-type declarations are **descriptive,
+never permissive**.
+
+## See also
+
+`test-doubles.md`'s "Common Misuses" table already flags mocking a
+collaborator internal to the SUT's own component as a boundary-selection
+error; `component-test-patterns.md`'s core principle ("double only the
+systems the team doesn't control") gestures at the same idea. This file is
+the rule those two already point toward, made unconditional and mechanically
+checkable.

package/knowledge/legacy-test-strategy.md

@@ -0,0 +1,71 @@
+# Legacy Test Strategy — Where to Test & How to Edit Safely
+
+Reference file for the `legacy-code` and `test-design-advisor` skills. Breaking a dependency (`dependency-breaking-techniques.md`) gets code *into* a harness; this file answers the two questions that come before and after: **where do I put the tests** (so they actually sense the change I'm making) and **how do I edit without breaking anything** while I get there. This is the legacy-code counterpart of test-architecture design — placing verification where it has leverage.
+
+Source: Michael Feathers, *Working Effectively with Legacy Code* (2005) — Ch. 11 *What Methods Should I Test?*, Ch. 12 *I Need to Make Many Changes in One Area*, Ch. 13 *Characterization Tests*, Ch. 23 *How Do I Know That I'm Not Breaking Anything?*. Language-agnostic.
+
+Core principle: **reason about effects before you write a test.** In tangled code with no tests, knowing *what your change can affect* and *where you can observe it* is the skill everything else depends on.
+
+---
+
+## 1. Reason about effects
+
+Every functional change has a chain of effects that propagates outward — through the methods that call the changed code — until it reaches a place you can observe, or stops because nothing downstream depends on it. To decide what to test, trace that chain.
+
+For a piece of code, list **everything that, if changed, would change a result returned by any of its methods**:
+
+- mutable state held by reference (a collection passed to a constructor and kept — callers can mutate it later),
+- objects in that state that can themselves be altered or replaced,
+- and *exclude* what genuinely can't change the outcome (e.g. an immutable string field — `getName` always returns the same value).
+
+This is **effect reasoning**: a learnable skill, done without tools, that tells you which methods are worth testing for a given change.
+
+## 2. Draw an effect sketch
+
+An **effect sketch** is a small directed graph: bubbles for data and methods, arrows from a cause to what it affects. Sketch it for the change you intend to make. The sketch reveals:
+
+- **Fan-out** — one piece of data affecting several methods. You can then *choose* which method to test through. Prefer the one that exercises the most behavior (the richest endpoint), so fewer tests cover more.
+- **Hidden classes** — clusters of methods/fields that only talk to each other form a natural encapsulation boundary and suggest an Extract Class.
+- **Simplification feedback** — removing tiny duplication often collapses endpoints (a method that starts calling another internally now gets exercised whenever the other is tested), making testing decisions easier.
+
+> Encapsulation is a tool for understanding, not an end in itself. Several dependency-breaking techniques *reduce* encapsulation; when encapsulation and test coverage conflict, bias toward coverage — good tests let you reason about the code more directly, and you can often recover encapsulation later.
+
+## 3. Find interception & pinch points
+
+- **Interception point** — any point where you can detect the effect of a change. Start at the change point and trace effects outward; each observable spot is a candidate. The nearest one isn't always the best — judgment call.
+- **Pinch point** — a *narrowing* in the effect sketch: a place where tests against one or two methods detect changes across many. It's a natural encapsulation boundary and the ideal place to anchor characterization tests before invasive work — write tests there, carve out an "oasis," then change freely behind it.
+- **Key question** for any candidate: *"If I break this method, will I be able to sense it here?"* If yes, it's a usable interception point.
+- **When no pinch point exists** (the sketch is a tangled tree): you're probably changing too much at once. Narrow to one or two change points, or test individual changes as close to the change as you can.
+- **Pinch-point trap** — don't let characterization tests anchored at a high pinch point *stay* as mini-integration tests. They're scaffolding to enable change; once the area is malleable, push verification down into narrower unit tests and let the broad tests go.
+
+## 4. Write the characterization tests
+
+A characterization test documents what the code **actually does**, not what it *should* do. The heuristic:
+
+1. Write tests for the area where you'll make the change — as many cases as you need to understand current behavior.
+2. Then target the **specific things you're about to change** and write tests that pin them.
+3. If you're extracting or moving functionality, write tests that verify those behaviors **exist and are connected** on a case-by-case basis — confirm you're exercising the code you'll move and that it's wired correctly (exercise the conversions).
+
+Procedure for one test: call the code, let it fail, read the actual output from the failure, then set the assertion to that observed value. Repeat until the change area and its immediate dependencies are covered. (The fuller procedure lives in the `legacy-code` skill.)
+
+---
+
+## 5. Edit safely while getting there (Ch. 23)
+
+Before tests are in place, these habits keep behavior intact:
+
+| Technique | The discipline | Why it helps |
+|-----------|----------------|--------------|
+| **Lean on the Compiler** | Make a declaration change (rename/retype) and let compile errors enumerate every site that must change | Turns the compiler into a worklist; you can't forget a usage |
+| **Preserve Signatures** | When extracting/moving code, keep parameter lists identical — copy whole signatures rather than retyping | Avoids transcription errors; lets you cut-and-paste blocks wholesale during invasive refactoring |
+| **Single-Goal Editing** | Do exactly one thing at a time; when you notice another change, write it on a list and finish the current one first | "Programming is the art of doing one thing at a time" — prevents the half-finished-thrash that breaks integration |
+| **Hyperaware Editing** | Know whether each keystroke changes behavior or not; pair programming and a sub-second test loop sustain this flow state | The feedback loop that makes change-without-tests survivable until tests exist |
+
+---
+
+## How this connects to the rest of the toolkit
+
+- **`dependency-breaking-techniques.md`** — once effect reasoning tells you *where* to intercept, those techniques create the seam to put a test there.
+- **`legacy-code` skill** — owns the Legacy Code Change Algorithm and characterization-test procedure; this file deepens its "find test points" step.
+- **`test-design-advisor` skill** — uses effect/pinch reasoning to recommend the lowest-leverage-cost place to verify hard-to-test code.
+- **`test-automation-principles.md`** — *Verify One Condition per Test* and Defect Localization are why you push pinch-point tests down to narrow units once the area is malleable.

package/knowledge/long-run-waiting.md

@@ -0,0 +1,66 @@
+# Waiting on Long-Running Work
+
+Read before arming any timer, monitor, or self-re-arming check-in for a job
+that outlives a single turn: mutation runs, long evals, CI jobs, full test
+suites, watched PRs. Skills that reference this file: `/long-eval`,
+`/mutation-testing`, `/stryker-xunit-v2-shim`, `/ci-debugging`, `/ship`.
+
+## Pick the waiting mechanism first
+
+| Situation | Mechanism |
+| --- | --- |
+| The job emits a stream (log file, command output) and you want the event the moment it appears | A monitor on that stream, with an exit condition — never an unbounded `tail -f` |
+| The job's progress is only readable by re-running a status command | A scheduled wake-up whose body re-runs that status command |
+| A wake could be missed (container recycle, dropped notification) | A scheduled wake-up as a **backstop**, in addition to the primary signal |
+| Anything | **Never** a foreground `sleep`/`while true` in Bash — it burns the turn and cannot survive a recycle |
+
+The tool that arms a scheduled wake-up is **surface-specific** — a session may
+expose a wake-up scheduler, a `send_later`-style reminder, a cron-style
+Routine, or none of them. Use whichever the session actually exposes; if none
+does, say so and fall back to reporting status when the operator next asks.
+Do not synthesize a wait out of `sleep`.
+
+## The scheduled wake-up calling contract
+
+Every scheduler in this family takes the **work to do on wake** as a required
+argument. There is no "just wait, no instructions" call shape. Concretely, on
+the Remote runtime's `ScheduleWakeup`:
+
+- `prompt` (**required**) — the instruction re-issued when the timer fires.
+  This is the whole point of the call: the wake-up replays the prompt, it does
+  not resume some remembered intent.
+- `reason` (**required**) — one short sentence on what is being waited for.
+- `delaySeconds` — clamped to `[60, 3600]`.
+- `stop: true` — ends the loop. This is the **only** shape that may omit
+  `prompt`, and it takes **no other fields**.
+
+**The failure this prevents:** calling the scheduler with only a delay (or
+only a reason) fails with
+
+```
+Error: `prompt` is required when `stop` is not true.
+```
+
+and — the part that actually costs you — **no timer is armed**. A backstop that
+errored is a backstop that never fires, so a missed wake is never recovered and
+the run looks stalled with nothing scheduled to notice. Two call shapes, both
+complete:
+
+- **Arm / re-arm:** `delaySeconds` + `prompt` + `reason`.
+- **Stand down:** `stop: true` alone.
+
+Ending a check-in loop means the second shape. Passing a `reason` that explains
+why you are stopping — with no `stop: true` — is the same malformed call as
+above, not a stop.
+
+## Re-arming loops
+
+A check-in that is supposed to repeat must carry its own continuation: the
+`prompt` you pass has to re-issue the same status-check-and-re-arm instruction,
+because the next firing starts from that prompt and nothing else.
+
+State the terminal condition inside the prompt, so the loop can end itself —
+"stop re-arming once `status` reports `DONE`, or if the operator said stop"
+— and end it with a `stop: true` call, not by silently letting the last wake
+pass. A loop with no terminal condition in its own prompt runs until the
+operator kills it.

package/knowledge/microservice-testing.md

@@ -0,0 +1,71 @@
+# Microservice Testing Strategy
+
+Reference file for `test-smell-review` and the `test-design-advisor` skill. Distributed systems add failure modes a single-process pyramid doesn't cover: the network between services, and the *agreement* between a service and its consumers. This file covers the layers and the contract-testing discipline that keep independently-deployable services from breaking each other.
+
+Source: Martin Fowler / Toby Clemson, "Testing Strategies in a Microservice Architecture" (martinfowler.com/articles/microservice-testing/). Complements `test-pyramid.md`.
+
+> For CD-pipeline framing — the determinism→pre-merge-gate rule, running CI without configuring dependencies, and per-component (UI/service/batch) patterns — see `cd-test-architecture.md` and `component-test-patterns.md`. Note those use MinimumCD vocabulary, where "integration test" specifically means *validating that contract doubles still match reality* (post-merge), which is narrower than this file's usage.
+
+Core principle: **independent deployability requires that no service can be broken by another service's change without a test catching it first.** End-to-end tests are too slow and flaky to be that safety net at scale. Contract tests are — but only when paired with *scheduled verification of those contracts against the real provider* (because you cannot depend on the provider to honor or verify a contract; see the reality check below).
+
+---
+
+## The Layers (per service)
+
+| Layer | Scope | What it verifies | Doubles |
+|-------|-------|------------------|---------|
+| **Unit** | A single class/function | Internal logic, branches, edge cases | Collaborators doubled |
+| **Integration** | A module + one external it owns | The adapter works against a real DB/broker/HTTP peer (test container) | Real external, isolated instance |
+| **Component** | One whole service, in isolation | The service meets *its own* API contract end to end, internals real | The service's downstream deps stubbed (in-process or network-level) |
+| **Contract** | The consumer↔provider agreement | Both sides still agree on request/response shape & semantics | A pact, verified independently on each side |
+| **End-to-end** | Several real services together | A critical cross-service journey works | None — real deployments |
+
+The shape is the same pyramid: lots of unit/integration, a layer of component tests per service, a thin layer of E2E for journeys. The new and load-bearing layer is **Contract**.
+
+---
+
+## Consumer-Driven Contracts (CDC)
+
+The mechanism that lets services deploy independently:
+
+1. The **consumer** writes tests describing exactly the requests it makes and the responses it depends on → this produces a **contract** (a "pact").
+2. The contract is shared with the **provider** (a broker, a repo, an artifact).
+3. The **provider** runs the contract against itself in *its* CI. If a provider change would break that consumer, the provider's build goes red — before deploy, without the consumer present.
+4. Each side tests against the contract in **isolation**: the consumer stubs the provider per the contract; the provider replays the contract against the real implementation.
+
+Why this beats E2E for integration safety:
+
+- Fast and deterministic — no shared environment, no orchestrating N services.
+- Failure points at the exact broken expectation, not "something in the journey failed."
+- The provider learns it broke a consumer **at build time**, which is what makes independent deploys safe.
+
+> **Reality check — don't depend on step 3.** The full CDC loop above only works when teams collaborate closely *and* use tooling that enforces provider-side verification. For any provider you don't control, **assume that doesn't exist**: assume the provider can break the contract without versioning and that you won't discover it until an incident — usually during your next unrelated deploy, which then takes the blame. The defense you actually own is to run *your* pinned contract against the provider's real endpoint **in a test environment on a schedule, out-of-band**, so a break is detected when it happens and attributed to the provider, not to your undelivered changes. And because you assume the provider *will* break, test that your consumer **survives** it (timeouts, retries, circuit breaker, drifted-response handling). Provider-side verification is a bonus when available, never the mechanism you rely on. See `cd-test-architecture.md` → Double Validation for the CD-pipeline formulation.
+
+---
+
+## What to test where (microservice heuristics)
+
+- **Business logic** → unit, in the owning service. Never via another service.
+- **Serialization / DB mapping / broker plumbing** → integration tests with a real instance (test container), not mocks of the driver.
+- **"Does my service honor its own API?"** → component test, internals real, downstreams stubbed.
+- **"Do I and the service I call still agree?"** → a contract test you own (pins what you send/expect), plus **scheduled verification of it against the provider's real test endpoint**. Provider-side verification too, if available. This replaces most cross-service E2E.
+- **"Does this critical journey work end to end?"** → a *small number* of E2E tests for the highest-value journeys only.
+
+---
+
+## Smells specific to distributed testing (flag these)
+
+| Smell | Signal | Fix |
+|-------|--------|-----|
+| **E2E as the integration net** | Cross-service correctness relies on a large E2E suite; no contract tests | Introduce contract tests + scheduled provider verification; shrink E2E to journeys |
+| **Unmonitored provider contract** | Consumer stubs a provider's response, but nobody runs that contract against the real provider on a schedule | Run *your* contract against the provider's real test endpoint on a schedule, out-of-band — don't wait for your next deploy (or the provider's cooperation) to discover a break |
+| **Consumer can't survive a break** | Consumer assumes the provider's contract holds; no timeout/retry/circuit-breaker/drifted-response tests | Test that the consumer degrades gracefully — assume the provider *will* break without versioning |
+| **Stubs that lie** | Hand-written stubs of a downstream that aren't derived from / checked against the real contract | Pin the stub with a contract test; verify it against the real provider on a schedule |
+| **Shared integration environment for correctness** | Tests pass/fail based on the state of a shared staging system | Isolate: component tests with stubbed downstreams + contract tests |
+| **Cross-service unit test** | A "unit" test spins up or calls a second real service to check this service's logic | Double the boundary; move true cross-service checks to contract/E2E |
+
+## Boundaries
+
+- Not every codebase is microservices. For a monolith or library, `test-pyramid.md` is sufficient — apply this file only when there are independently-deployable services with network boundaries between them.
+- Contract testing is the recommendation for service↔service agreements; don't flag the *absence* of E2E tests as a defect when contracts cover the integration. The point is independent deployability, achieved by whichever combination provides it.
+- A small, curated E2E suite is healthy. Flag E2E *over-reliance* (it's the integration safety net), not E2E existence.

package/knowledge/model-pricing.json

@@ -0,0 +1,23 @@
+{
+  "_comment": "Per-million-token USD pricing for the cost meter (issue #102). Keyed by model snapshot ID (and tier alias). input/output are $ per 1M tokens; cache_write_multiplier (5-min TTL) and cache_read_multiplier are applied to the input rate per Anthropic's prompt-caching pricing (write 1.25x, read 0.1x). Source: Claude API reference, cached 2026-08-05; 5-family rates from the claude-api skill model catalog (Opus 5 $5/$25, Fable 5 and Mythos 5 $10/$50, Sonnet 5 $3/$15 standard), cached 2026-08-05. Claude Sonnet 5 carries an introductory rate of $2/$10 per MTok through 2026-08-31; the $3/$15 entered here is the standard post-intro sticker (the named instrument uses the durable rate, and over-reporting is the safe direction for a budget ceiling). A model absent from `models` prices at $0.00, which silently disables any cost cap built on this file for exactly the model doing the work — claude-opus-5 was missing while it was this repo's default, so /autoship's --max-cost-usd read 4.7% of real spend (issue #1830). Anything absent here is now named in each cost-metering record's `unpriced_models` field and by tests/repo/test_cost_meter.py; add new model IDs in the same commit that starts using them. cache_write_multiplier covers the 5-minute TTL only — the 1-hour TTL is 2x, which this file does not model. Update when pricing changes; this is the named instrument for any cost claim.",
+  "source": "platform.claude.com/docs/en/pricing (via claude-api skill cache 2026-08-05)",
+  "cache_write_multiplier": 1.25,
+  "cache_read_multiplier": 0.1,
+  "models": {
+    "claude-opus-5":     { "input": 5.0, "output": 25.0 },
+    "claude-opus-4-8":   { "input": 5.0, "output": 25.0 },
+    "claude-opus-4-7":   { "input": 5.0, "output": 25.0 },
+    "claude-opus-4-6":   { "input": 5.0, "output": 25.0 },
+    "claude-fable-5":    { "input": 10.0, "output": 50.0 },
+    "claude-mythos-5":   { "input": 10.0, "output": 50.0 },
+    "claude-sonnet-5":   { "input": 3.0, "output": 15.0 },
+    "claude-sonnet-4-6": { "input": 3.0, "output": 15.0 },
+    "claude-haiku-4-5":  { "input": 1.0, "output": 5.0 },
+    "claude-haiku-4-5-20251001": { "input": 1.0, "output": 5.0 }
+  },
+  "aliases": {
+    "opus": "claude-opus-5",
+    "sonnet": "claude-sonnet-5",
+    "haiku": "claude-haiku-4-5"
+  }
+}

package/knowledge/mutation-score-formulas.md

@@ -0,0 +1,60 @@
+# Mutation score formulas
+
+Canonical formulas for `mutation-kill` (the autonomous survivor-kill agent)
+and the `/mutation-testing` skill (advisory scoring/reporting). Both compute
+identical numbers from a mutation report's `Killed`/`Survived`/`Timeout`/
+`NoCoverage` counts — this file is the single definition so the two never
+drift on naming or arithmetic.
+
+## Honest vs. reported score
+
+Mutation tools count **timed-out** mutations as "killed." They are not — a
+score inflated by timeouts is not evidence of good tests (observed: one run
+scored 61.3% "killed," 76% of which were timeouts; targeted tests that let
+those mutations *complete* instead of timing out dropped the honest score to
+30.36%). This is a separate observed incident from the worked example in
+`skills/mutation-testing/SKILL.md`'s Output format section (23.0% honest vs.
+61.3% claimed, 999/1305 timeouts) — both are real, independently sourced
+illustrations of the same failure mode, not one canonical figure restated
+inconsistently.
+
+```
+honest_score   = Killed / (Killed + Survived + NoCoverage)
+reported_score = (Killed + Timeout) / (Killed + Survived + Timeout + NoCoverage)
+```
+
+Same formula, two fixed field names — not free-to-unify synonyms:
+`mutation_report.py` emits the dataclass field `reported_score`;
+`skills/mutation-testing/SKILL.md`'s `--emit-json` machine-readable output
+key is `claimed_score` (a stable, versioned schema — see that file's
+Machine-readable output section). Both name what the mutation tool's own
+report/HTML prints. **`honest_score` is the only number that gates a round
+or a file** — Timeout stays out of the numerator. Report both, so a reviewer
+comparing them sees an honest gap (numerator delta) rather than a formula
+mismatch. `Timeout` and `NoCoverage` counts always print separately
+alongside both scores.
+
+## Raw vs. adjusted score (accepted survivors)
+
+When one or more survivors are marked `status: "accepted"` (a real, killable
+mutant deliberately deferred this pass — distinct from `"equivalent"`), also
+print:
+
+```
+raw_score      = honest_score (unchanged)
+adjusted_score = Killed / (Killed + (Survived - Accepted) + NoCoverage)
+```
+
+Label both clearly (e.g. `Raw: 68.57% (24/35) · Adjusted for 11 accepted
+survivors: 100% (24/24)`), plus a per-mutant "Accepted Survivors (deferred)"
+table (file, line, operator, reason). Never let `adjusted_score` stand
+alone — `raw_score` plus the reason table is what keeps a documented
+deferral from silently vanishing.
+
+## NoCoverage is a first-class signal
+
+Each `NoCoverage → Killed` conversion improves the score as much as killing
+a `Survived` mutant — and NoCoverage paths are usually easier, because
+**any** test that reaches the line kills the mutant (no specific-value
+assertion required). Prioritize NoCoverage coverage before attacking hard
+Survived mutations.

package/knowledge/object-calisthenics.md

@@ -0,0 +1,147 @@
+# Object Calisthenics
+
+Nine rules for writing clean, maintainable, testable object-oriented code. Apply to **business domain code** — exempt DTOs, config classes, test builders, and framework boilerplate.
+
+Source: Jeff Bay, "Object Calisthenics" (*The ThoughtWorks Anthology*, Pragmatic Bookshelf, 2008)
+
+---
+
+## The Rules
+
+### 1. One Level of Indentation Per Method
+
+If a method has nested `if`/`for`/`while`, extract the inner block into a named method.
+
+```
+// BAD
+function processPayments(payments) {
+  for payment in payments:
+    if payment.isEligible:
+      if payment.amount > 0:
+        submit(payment)
+}
+
+// GOOD
+function processPayments(payments) {
+  for payment in payments:
+    processIfEligible(payment)
+}
+```
+
+### 2. Don't Use the ELSE Keyword
+
+Replace `if/else` with guard clauses (early returns) or polymorphism.
+
+```
+// BAD
+function calculateShipping(method):
+  if method == "express": return weight * 2.5
+  else if method == "overnight": return 25.0
+  else: return 0
+
+// GOOD — guard clauses
+function calculateShipping(method):
+  if method == "express": return weight * 2.5
+  if method == "overnight": return 25.0
+  return 0
+```
+
+### 3. Wrap All Primitives and Strings
+
+Domain-meaningful primitives become value objects with validation.
+
+```
+// BAD
+createOrder(customerId: string, amount: decimal, email: string)
+
+// GOOD
+createOrder(customerId: CustomerId, amount: Money, email: EmailAddress)
+```
+
+### 4. First-Class Collections
+
+Any class with a collection field should contain no other fields. The collection gets its own class with domain behavior.
+
+```
+// BAD
+class BatchProcessor:
+  payments: List<Payment>
+  batchId: string   // mixing concerns
+
+// GOOD
+class PaymentBatch:
+  payments: List<Payment>   // the ONLY field
+  total(): Money
+  eligiblePayments(): List<Payment>
+```
+
+### 5. One Dot Per Line (Law of Demeter)
+
+Don't chain through object graphs. Each method call should be on the immediate collaborator.
+
+```
+// BAD — reaching through the graph
+city = order.customer.address.city
+
+// GOOD — ask the immediate object
+city = order.shippingCity   // Order delegates to its own data
+```
+
+### 6. Don't Abbreviate
+
+Names should be intention-revealing. If a name is too long, the class may have too many responsibilities.
+
+```
+// BAD
+proc = new Proc()
+txn = getTxn(id)
+amt = calcAmt(txn)
+
+// GOOD
+processor = new PaymentProcessor()
+transaction = getTransaction(id)
+amount = calculateAmount(transaction)
+```
+
+### 7. Keep All Entities Small
+
+- Classes: under 200 lines
+- Methods: under 20 lines
+- Packages/modules: under 15 classes
+
+If a class exceeds these limits, it likely violates SRP — extract responsibilities.
+
+### 8. No Classes with More Than Two Instance Variables
+
+The spirit: classes should be small and focused. In practice, aim for fewer than five fields. More than five is a strong signal for Extract Class.
+
+### 9. No Getters/Setters/Properties (Tell, Don't Ask)
+
+Move behavior into the object that owns the data instead of exposing data for others to operate on.
+
+```
+// BAD — asking for data, deciding externally
+if account.balance >= amount:
+  account.balance -= amount
+
+// GOOD — telling the object what to do
+account.withdraw(amount)   // Account enforces its own invariants
+```
+
+---
+
+## Applying Pragmatically
+
+These are training exercises, not absolute laws. Use them as design pressure:
+
+| Rule | Always Apply | Pragmatic Exceptions |
+|---|---|---|
+| One indentation level | Yes | Complex LINQ / stream expressions |
+| No ELSE | Yes | Simple boolean returns |
+| Wrap primitives | For domain values | Infrastructure code, DTOs |
+| First-class collections | When collection has behavior | Simple DTOs |
+| One dot per line | At domain boundaries | Fluent APIs, builders |
+| Don't abbreviate | Yes | Industry-standard acronyms (HTTP, SQL, ID, JWT) |
+| Small classes | Yes | EF/ORM configurations, test fixtures |
+| Few instance variables | As design pressure | Aggregate roots may need more |
+| No getters | At domain boundaries | DTOs, serialization, view models |

package/knowledge/oracle-provenance.md

@@ -0,0 +1,94 @@
+# Oracle Provenance
+
+## Purpose
+
+Classifies each test's expected value by how that value was determined. The classification drives whether the test verifies *correctness* (the system matches an independent standard) or merely *stability* (the system matches its own prior output).
+
+## Taxonomy
+
+### SPEC-DERIVED
+
+The expected value is traceable to an external specification, standard, or documented requirement. Examples:
+
+- Expected output computed from a written requirement (`// per RFC 7231, §6.3.1`)
+- Value cited in acceptance criteria or a user story
+- Result mandated by a protocol or industry standard
+- Expected value from a product specification document
+
+### INDEPENDENT
+
+The expected value was computed independently of the system under test. Examples:
+
+- Result of a hand calculation (`// 42 = 6 * 7, manually verified`)
+- Output of a reference implementation written separately
+- Value from a trusted external data source (known test vectors, published test cases)
+
+### CIRCULAR
+
+The expected value was captured from the system's own current output — golden files, snapshots, or assertions that encode "what we produce today." There is no external justification that this output is correct.
+
+Examples:
+
+- Snapshot / golden file assertions (Jest `toMatchSnapshot()`, `.toMatchInlineSnapshot()`, approved-files frameworks, `verify()` calls in ApprovalTests)
+- Assertions written by recording a baseline run (`received → expected` copy)
+- Assertions that exactly echo what the system returned when first observed, with no independent derivation
+- AI-generated assertions that reproduce observed output without verifying it against a specification
+
+## Detection Heuristics
+
+### Identifying CIRCULAR oracles
+
+Look for these signals at the assertion call site:
+
+| Language / Framework | Circular oracle pattern |
+|---|---|
+| Jest (JS/TS) | `expect(x).toMatchSnapshot()`, `expect(x).toMatchInlineSnapshot(...)` |
+| Jest (JS/TS) | Snapshot files in `__snapshots__/` |
+| Vitest | `expect(x).toMatchSnapshot()`, `expect(x).toMatchInlineSnapshot(...)` |
+| C# / ApprovalTests | `Approvals.Verify(...)`, `ApprovalTests.Verify(...)` |
+| C# / Snapshooter | `Snapshot.Match(...)` |
+| Python / syrupy | `assert result == snapshot` |
+| Any | Assertion comment says "baseline", "captured from prod", "recorded output" |
+| Any | Test file in `__snapshots__/` or `snapshots/` subdirectory with no rationale comment |
+
+### Identifying INDEPENDENT / SPEC-DERIVED oracles
+
+Positive signals:
+
+- A comment citing a spec section, issue number, RFC, or requirement ID near the assertion
+- An inline formula or derivation comment (`// expected = base * rate = 100 * 0.07 = 7.0`)
+- A reference to a separately written oracle function not based on the SUT
+- A test named after a known algorithm or well-specified behavior
+
+### When to flag AI-generated assertions as CIRCULAR
+
+If the test was generated by an AI tool (comment, commit message, or file header says so) and the expected values match what the system produced with no additional derivation, classify as CIRCULAR — the AI captured the current output, not a verified specification.
+
+## Suite-level Ratio and Quality Cap
+
+Count the oracle class for each assertion in scope:
+
+```
+circular_ratio = circular_count / total_assertions
+```
+
+| Circular ratio | Effect on finding |
+|---|---|
+| < 20 % | Note at suggestion level — consider adding provenance comments |
+| 20 – 50 % | Warning — suite has meaningful circular-oracle contamination |
+| > 50 % | Error — suite is circular-oracle-dominated; Test Quality contribution for the affected file is capped at 60 (out of 100) |
+
+A circular-oracle-dominated suite verifies stability, not correctness. A system can regress silently and all snapshots will still pass after update.
+
+## Coordination with test-smell-review
+
+`test-smell-review` already flags snapshot tests as a named smell ("Snapshot Overuse"). When both agents run together:
+
+- `test-smell-review` owns the *smell* signal (overuse, brittleness of snapshots).
+- `test-review` owns the *oracle-provenance* signal (correctness vs. stability, quality cap).
+
+Do not double-report the same snapshot assertion. If `test-smell-review` is running in the same session, `test-review` should note the oracle-provenance ratio in the summary without re-listing each individual snapshot as a separate finding.
+
+## Relationship to Farley Score
+
+The Farley Score's "Necessary" property — tests that fail only when real bugs exist — correlates with SPEC-DERIVED and INDEPENDENT oracles. A circular oracle can remain green after introducing a regression if the snapshot is updated. When the oracle-provenance ratio is available, it may inform "Necessary" scoring.