pi-dev-team 0.2.0

package/knowledge/codegraph-vs-graphify.md

@@ -0,0 +1,192 @@
+# CodeGraph, Repowise, and Graphify
+
+Three optional, complementary code-intelligence tools may show up in a
+project this plugin operates on. None is required — a project may have any
+subset (including none), and nothing in the plugin assumes any of them
+exists. When present, they let agents read verified skeletons, resolved call
+graphs, modification risk, and decision rationale instead of re-reading whole
+files and grepping for callers — cheaper and more accurate. When absent, the
+grant is inert and agents fall back to `Read`/`Grep`/`Glob`.
+
+## What each tool is
+
+### CodeGraph
+
+Third-party tool (<https://github.com/colbymchenry/codegraph>). Builds a
+tree-sitter AST index of source code into a local SQLite database
+(`.codegraph/codegraph.db`). Code-symbols-only — it indexes functions,
+classes, and call relationships, not prose or non-code artifacts. Queries
+(callers, callees, impact analysis) run sub-millisecond against the local
+index. It has no knowledge of documentation, schemas, or infrastructure
+files.
+
+### Repowise
+
+A codebase-documentation / wiki engine (`repowise` on PyPI) that indexes a
+repository into a queryable knowledge base and exposes it as an **MCP
+server**. Its tools answer *contextual* questions about the code rather than
+raw structural ones: `get_overview` returns an architecture-level summary of
+the whole workspace; `get_context` / `get_symbol` return documented context
+and verified skeletons for a file, module, or symbol; `search_codebase` is
+semantic (natural-language) search; `get_answer` answers a free-form question
+against the indexed wiki; `get_risk` estimates the modification risk of a
+change; `get_why` surfaces the recorded architectural-decision rationale
+behind a piece of code; `get_health` reports code-health signals (churn,
+complexity, coverage-adjacent risk) and `get_dead_code` flags unreferenced
+code — both workspace-scoped rather than file-scoped, so they run over the
+whole indexed repo instead of a single symbol. It can index without any LLM
+API key (a keyless index), writing its store under `.repowise/`. Because it
+layers documentation, risk, rationale, and workspace-wide health signals on
+top of structure, it complements CodeGraph's pure call-graph view.
+
+### Graphify
+
+A knowledge-graph tool (`graphifyy` on PyPI) that is multi-modal: it ingests
+code *and* docs, PDFs, schemas, infra files, images, and video into one
+graph, using both semantic (embedding-based) and structural (AST/reference)
+extraction. Output is a queryable graph (`graphify-out/graph.json`) plus a
+plain-language `GRAPH_REPORT.md` and an interactive HTML view, with
+community detection to surface cross-document relationships. Because it
+spans code and non-code content, it is the better tool for
+architecture-level and onboarding questions, not just "what calls this
+function."
+
+## How each is installed and invoked here
+
+### CodeGraph
+
+- Offered opt-in during `/project-init`'s Step 4c
+  ([`skills/project-init/SKILL.md`](../skills/project-init/SKILL.md)) as part
+  of the keyless CodeGraph + Repowise all-or-none pair (Graphify is a separate
+  opt-in — see below): the skill checks `command -v codegraph` and the
+  presence of `.codegraph/`, and when the pair
+  is accepted **installs the CLI keylessly** (`npm install -g
+  @colbymchenry/codegraph`) and builds the index non-interactively
+  (`codegraph init .`, no `-i`), recording the choice in
+  `.claude/init-state.json` (issue #1134).
+- **Strictly personal, user-level tooling — never committed.** Once
+  initialized, the skill prints the manual command
+  (`claude mcp add codegraph -- codegraph serve --mcp`) for the user to
+  register the `codegraph` MCP server at **user scope**, exposing a single
+  tool, `codegraph_explore` (`mcp__codegraph__explore`), to Claude Code
+  sessions on that machine. One call returns the verbatim source of the
+  relevant symbols grouped by file, the call path among them, and a
+  blast-radius summary of what depends on them — Read-equivalent output, but
+  with structure attached. Nothing is written to a project-tracked
+  `.mcp.json`, and `.codegraph/` is never committed — only
+  `.codegraph/codegraph.db` stays gitignored and machine-local, per project.
+- `hooks/code_intelligence_nudge.py` (PreToolUse on `Read`/`Grep`/`Glob`)
+  recommends `codegraph_explore` over multi-file Read/Grep/Glob exploration
+  whenever `.codegraph/` exists and no CodeGraph tool has been used yet in
+  the current turn; see
+  [`docs/code-intelligence-nudge.md`](../docs/code-intelligence-nudge.md)
+  for the full sentinel mechanism. `hooks/codegraph_bootstrap.py`
+  (SessionStart) rebuilds the local `.db` on a fresh clone when
+  `.codegraph/` is committed but the machine-local database is missing.
+
+### Repowise
+
+- Offered opt-in during `/project-init`'s Step 4c
+  ([`skills/project-init/SKILL.md`](../skills/project-init/SKILL.md)),
+  alongside CodeGraph as one **all-or-none** keyless pair (Graphify is a
+  separate opt-in, offered after this pair — see below).
+- Installed keyless (`uv`/`pipx`/`pip`), it indexes without prompting for an
+  LLM API key and stores its index under `.repowise/`, which is gitignored so
+  the index never clutters the repo.
+- Registered as an MCP server, it exposes
+  `mcp__plugin_repowise_repowise__{get_overview,get_context,get_symbol,search_codebase,get_answer,get_risk,get_why,get_health,get_dead_code}`
+  (and more) to Claude Code sessions.
+- **Server-name coupling caveat.** The tool names agents grant use the literal
+  server prefix `mcp__plugin_repowise_repowise__*`. If a given install exposes
+  Repowise under a different MCP server name, those grants are **inert** — no
+  error, agents just fall back to `Read`/`Grep`/`Glob`. Keep the fallback in
+  mind wherever a Repowise tool is assumed.
+
+### Graphify
+
+- A repo-level tool with its own native `/graphify` skill
+  (`.claude/skills/graphify/SKILL.md` in this repo), not part of the
+  `dev-team` plugin's shipped skill set.
+- Also offered opt-in during `/project-init`'s Step 4c, after the keyless
+  CodeGraph + Repowise pair. **Only Graphify's AST pass builds keyless** —
+  `graphify extract .` is full extraction (AST + semantic LLM pass) and is the
+  target invocation, producing the `graph.json` the agents traverse (issue
+  #1224); a model/API key with a working backend is required for the semantic
+  pass, which is what indexes docs and images, not just community names and
+  inferred edges (issue #1483). Without a working backend, use
+  `graphify extract . --code-only` instead — a degraded, code-only graph, not
+  the full multi-modal index. When accepted, the skill runs full extraction
+  when a key/backend is available (or `graphify update .` when a graph already
+  exists), falling back to `--code-only` when it is not, and offers the
+  further label/`--mode deep` enrichment add-ons only on top of a successful
+  full extraction; when graphify is absent, consuming agents fall back to
+  `Read`/`Grep`/`Glob`.
+- Build a graph with `graphify extract .` (or the full `/graphify` pipeline),
+  which writes `graphify-out/graph.json` (gitignored) plus
+  `graphify-out/GRAPH_REPORT.md` and an HTML visualization.
+- Query the graph with `graphify query "<question>"` (broad, BFS-style
+  context), `graphify path "<A>" "<B>"` (shortest path between two
+  concepts), and `graphify explain "<concept>"` (plain-language explanation
+  of a single node).
+- PreToolUse nudge hooks in `.claude/settings.json` (this repo's own,
+  separate from the plugin's `code-intelligence-nudge`) steer codebase
+  questions toward `graphify query` when `graphify-out/graph.json` already
+  exists.
+- Keep the graph current after edits with `graphify update .`
+  (incremental, AST-only, no LLM cost).
+
+## When to use which
+
+- **CodeGraph** for fast structural queries while editing — callers,
+  callees, impact analysis, sub-millisecond lookups against a local SQLite
+  index of code symbols.
+- **Repowise** for *contextual* code questions — documented context and
+  verified skeletons (`get_context`/`get_symbol`), semantic search
+  (`search_codebase`), modification risk (`get_risk`), decision rationale
+  (`get_why`), and workspace-wide code health/dead-code signals
+  (`get_health`/`get_dead_code`). Reach for it when the question is "what
+  does this do / why does it exist / how risky is changing it / how healthy
+  is this area," not "who calls it."
+- **Graphify** for architecture and onboarding questions that span code
+  *and* docs, schemas, and infrastructure — anything broader than "who
+  calls this function."
+
+### Routing precedence
+
+This is guidance for the *model* choosing which tool to reach for — it is
+not hook-enforced logic; nothing in `code_intelligence_nudge.py` inspects
+the question text, since only the model sees the natural-language task
+behind a Read/Grep/Glob call. When more than one tool is indexed, prefer in
+this order:
+
+1. **Non-code content** (docs, schemas, infra, cross-artifact questions) →
+   **Graphify**.
+2. **Risk, rationale, code health, or dead code** → **Repowise**.
+3. **Pure structure or call-graph** (who calls this, what does this affect)
+   → **CodeGraph**.
+
+The three overlap only lightly: CodeGraph is the fastest for pure call
+graphs, Repowise adds documentation/risk/rationale over structure, and
+Graphify is the widest net across non-code artifacts. Prefer whichever is
+present for the question at hand; use more than one when they're all indexed.
+
+## None is guaranteed to be present
+
+All three are optional and independently adopted per project:
+
+- CodeGraph requires an explicit `/project-init` opt-in and a successful
+  `codegraph init`; a project can decline both the install and the init
+  prompts and never have `.codegraph/`.
+- Repowise requires the `/project-init` code-lookup-tools opt-in and a
+  keyless index; a project can decline it and never have `.repowise/` or the MCP
+  server registered — and even when installed, the grant is inert if the
+  server name differs (see the coupling caveat above).
+- Graphify requires someone to run `/graphify` (or `graphify extract`) at
+  least once; a project can go its entire life without `graphify-out/`.
+
+Plugin behavior must not assume any of the three exists. The
+`code-intelligence-nudge` hook already fails open when none of the three
+are present, Repowise/CodeGraph MCP grants are inert when their servers are
+absent, and no shipped `dev-team` skill or agent depends on
+`graphify-out/` being present. `Read`/`Grep`/`Glob` is the always-available
+fallback.

package/knowledge/component-test-patterns.md

@@ -0,0 +1,139 @@
+# Component Test Patterns
+
+Reference file for the `cd-test-architecture` skill. Per-component-type testing patterns for a CD pipeline. Builds on `cd-test-architecture.md` (the six test types, the pre-merge determinism rule, the adapter rule, and double validation) — read that first.
+
+Source: MinimumCD Applied Testing Strategies — component patterns (beyond.minimumcd.org/docs/testing/applied-testing-strategies/patterns/). These are recommended starting points, not mandates: drop items that don't apply, add what a component clearly needs.
+
+Core principle for every pattern: **assemble the real component, double only the systems the team doesn't control, drive through the public interface, assert observable outcomes.** — and, at or below the component layer, no *internal* collaborator either, per the full blocker rule in `internal-collaborator-doubling.md`. Everything below is a specialization of that.
+
+---
+
+## Identify the Component's Pattern
+
+| If the component… | Pattern | Group |
+|---|---|---|
+| renders data and accepts user interaction against backend APIs | **User Interface** | UI |
+| exposes endpoints and owns its data store, no outbound internal calls | **API Provider** | Services |
+| exposes endpoints **and** calls upstream services | **API Consumer** | Services |
+| consumes messages from a broker | **Event Consumer** | Services |
+| publishes messages to a broker | **Event Producer** | Services |
+| holds long-lived in-memory state (cache, aggregate, coordinator, websocket gateway) | **Stateful Service** | Services |
+| is a binary/package invoked via CLI or imported API | **CLI / Library** | Services |
+| is triggered by cron/queue/scheduler to process data and write output | **Scheduled Job** | Batch |
+
+A real system is often several of these; test each surface by its pattern.
+
+---
+
+## UI
+
+### User Interface
+
+Renders data and accepts interaction against backend APIs.
+
+- **Coverage layers:** pure rendering (solitary unit) → component composition (sociable unit) → feature behavior in the DOM (component tests in a real browser, backend stubbed at the network layer) → backend HTTP client (consumer-side contract tests) → a small set of E2E happy paths against real backends (post-deploy).
+- **Isolation (run without the backend configured):** drive the UI in a real browser engine; stub the backend **at the network layer** (e.g. Playwright `page.route`). The same fixtures later serve E2E smoke. Do **not** use an in-memory DOM shim (JSDOM) for feature tests — it trades accuracy for false positives on layout/event timing.
+- **Success scenarios:** critical flows via keyboard + mouse; valid input submits; loading states; empty/populated/overflow states; i18n (long translations, RTL); responsive breakpoints.
+- **Failure modes:** every API call's 4xx/5xx/network/timeout; validation messages (screen-reader announced); token expiry mid-session → re-auth; permission denied; stale data after cross-tab deletes; slow (3G) network; concurrent-edit/optimistic-lock UX; back-button nav; automated WCAG scan.
+- **Double validation:** backend stubs must match real endpoints — pin them with contract tests pre-merge, then run **scheduled verification of those contracts against the real backend in a test environment** to detect drift when it happens (not at your next deploy). If the backend is the same team's, provider-side verification in its pipeline is a bonus; don't depend on it for backends you don't control. Post-deploy E2E smoke catches drift the contracts didn't pin.
+- **Pipeline:** unit + component (headless browser) + consumer contract tests in Stage 1; visual regression Stage 1/2; E2E smoke post-deploy (blocks rollout, not build); RUM + synthetics in prod.
+
+---
+
+## Services
+
+### API Provider
+
+Exposes endpoints, owns its data store, no outbound internal calls.
+
+- **Coverage layers:** HTTP/API surface (component + provider contract) → domain logic (solitary/sociable unit + component) → persistence adapter (sociable unit + adapter integration + component) → external database (doubled in component; real engine in adapter integration).
+- **Isolation:** assemble the full app with an **in-memory repository** and in-memory event bus; drive through HTTP handlers; assert status, persisted state, emitted events.
+- **Success scenarios:** documented endpoints return expected shape/status for valid input; auth succeeds for valid creds/tokens; pagination/filter/sort; idempotent ops idempotent, non-idempotent create exactly one; success-path side effects (events, audit).
+- **Failure modes:** malformed input (bad JSON, missing/extra fields, type errors); out-of-range/unicode; authz failures (missing/expired token, insufficient scope, cross-tenant); not-found returns 404 not 500; concurrency conflicts with correct status; persistence failure without partial commit; rate-limit/size enforcement; idempotency under retry.
+- **Double validation:** adapter integration tests run against a real instance of the **production database engine** via testcontainers (matching version + extensions) — never an SQLite shim for a Postgres prod; provider contract verification confirms the API still satisfies every consumer expectation.
+- **Pipeline:** unit + sociable unit pre-commit/Stage 1; component Stage 1; adapter integration out-of-band on a schedule, regardless of ownership; provider contract verification in CD contract/boundary stage.
+
+### API Consumer
+
+Exposes endpoints **and** calls upstream services. The most failure-prone distributed pattern — give it the most attention.
+
+- **Coverage layers:** inbound HTTP surface → domain/orchestration (composes calls) → **resilience policy** (retry, circuit breaker, timeout, fallback) → outbound HTTP client (request build, response parse, headers, deadlines) → persistence adapter → external DB (doubled/real) → downstream service (doubled in pipeline, real out-of-band).
+- **Isolation (run without the upstream configured):** wrap the upstream client in a **team-owned thin adapter**; double the adapter in component tests. Drive each failure through the client double.
+- **Success scenarios:** constructs right URL/headers/body/auth/timeout; parses success incl. optional/unknown fields; composes multiple downstream calls (sequence/parallel); caching within TTL + refresh after expiry; trace-context propagation.
+- **Failure modes:** **timeout** (deadline enforces, caller gets documented response e.g. 504, no partial commit); connection refused (retry count + backoff → fallback/error); 5xx retried only when retryable; 4xx mapped to documented behavior, generally not retried, 429 respects `Retry-After`; malformed/drifted response per Postel's Law; circuit breaker opens under sustained failure, fast-fails, recovers on half-open probe; partial multi-call failure → compensation/rollback/documented partial success.
+- **Double validation (do not depend on provider cooperation):** assume the provider can break the contract without versioning and that you won't know until an incident. (1) consumer-side contract tests pin request + response shape, block the build; (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 deploys — this is the primary defense, attributing a break to the provider when it happens rather than to your next unrelated change; (3) adapter integration tests exercise the real outbound client against controlled states (testcontainers) — asserts the *adapter*, not the dependency; (4) resilience component tests (above) prove the consumer **survives** a broken contract, not just detects it. Provider-side verification of your contract is a bonus *if* they offer it — never relied upon.
+- **Anti-pattern:** mocking the third-party SDK directly instead of wrapping + doubling an owned adapter.
+- **Pipeline:** consumer contract + resilience component tests (fault injection) Stage 1; adapter integration out-of-band on a schedule, decoupled from deploys — regardless of whether the dependency is in-house or third-party/other-team, never in-band; post-deploy checks scheduled.
+- **Stack-specific mechanics — .NET:** the canonical pre-merge seam is `HttpMessageHandler` (stubbed + wired via `IHttpClientFactory.ConfigurePrimaryHttpMessageHandler`); WireMock.Net is the preferred implementation of that seam when installed, with the hand-rolled stub kept as backup. See `references/csharp-http-client-testing.md` and the worked matrix in `test-matrix-examples/dotnet-http-consumer.md`. (Other stacks: Node / Nock preferred, MSW as a documented fallback; JVM / WireMock; Python / VCR.py preferred, `responses`/`httpx` mock as a documented fallback. `virtual-service-libraries.md` is the single source of truth for the per-stack preferred/backup catalog — cite it rather than restating tool names here; add to a stack profile as needed.)
+
+### Event Consumer
+
+Consumes messages from a broker (Kafka/SQS/RabbitMQ/PubSub).
+
+- **Coverage layers:** message handler (solitary unit) → idempotency & ordering (component) → dead-letter / poison-message (component) → backpressure (resilience component) → broker client (adapter integration vs real broker container) → external broker & schema registry (doubled in component; contract + post-deploy synthetic publish).
+- **Isolation (run without the broker):** replace the broker with a double; drive the handler with messages directly.
+- **Success scenarios:** well-formed message → expected state change + documented downstream event; batch policy honored; replay from offset reproduces identical end state; documented schema versions accepted.
+- **Failure modes:** poison message → DLQ with correlation id, consumer survives; duplicate delivery → exactly one record (idempotency); out-of-order per documented policy; mid-batch failure → offsets uncommitted, no data loss; schema skew per version policy; backpressure (slow, don't OOM); rebalancing strands no in-flight messages.
+- **Double validation:** adapter integration tests vs a real broker container the team controls (Docker Kafka, ElasticMQ, Redpanda) assert the adapter speaks the protocol (not broker ordering — that's the broker's job); schema-registry doubles validated via contract tests + post-deploy checks vs the real registry.
+- **Pipeline:** handler unit + component Stage 1; adapter integration out-of-band on a schedule — regardless of whether the broker is team-controlled or managed/third-party; post-deploy synthetic publishes out-of-band.
+
+### Event Producer
+
+Publishes messages to a broker (often paired with a consumer in the same service).
+
+- **Coverage layers:** publish logic (unit) → publish contract (contract test pins message schema) → broker client adapter (adapter integration) → external broker (doubled; post-deploy synthetic).
+- **Isolation:** double the broker adapter; assert the message that *would* be published (shape, key, headers, idempotency).
+- **Success/failure:** correct schema/partition-key/headers on the happy path; publish failure → documented retry/outbox behavior, no silent drop; transactional outbox prevents loss on crash between state-write and publish.
+- **Double validation:** message schema pinned by contract (consumers verify); adapter integration vs real broker container; post-deploy synthetic publish.
+- **Pipeline:** unit + contract Stage 1; adapter integration out-of-band on a schedule, regardless of ownership; post-deploy synthetic.
+
+### Stateful Service
+
+Long-lived in-memory state: caches, aggregates, coordinators, websocket gateways, real-time engines.
+
+- **Coverage layers:** state-machine logic (solitary unit) → persistence & recovery (component with doubled persistence) → single-node concurrency (component) → replication & leader election (cluster tests with real consensus library) → memory bounds (soak) → connection lifecycle (component) → external persistence engine (doubled in component; real engine in adapter integration, out-of-band).
+- **Isolation:** double persistence; control time and event ordering to make concurrency deterministic.
+- **Success scenarios:** transitions follow documented state machine; state rebuilds identically after restart; replication lag within budget.
+- **Failure modes:** crash mid-write → consistent state on restart, no torn writes; concurrent mutations serialize without lost updates; network partition → minority steps down with documented reconciliation; memory pressure → evicts per policy, no OOM; idle connections close cleanly with documented reconnect.
+- **Double validation:** persistence doubles validated by adapter integration against the real persistence engine, out-of-band; consensus doubles validated by cluster testcontainer tests, out-of-band.
+- **Pipeline:** unit + component Stage 1; adapter integration (persistence recovery) out-of-band on a schedule, regardless of ownership; cluster tests out-of-band on a schedule, regardless of ownership; soak + chaos out-of-pipeline vs deployed instances.
+
+### CLI / Library
+
+Binary or package consumed via CLI or an exported API.
+
+- **Coverage layers:** public-interface behavior (unit/component invoking the real surface) → process startup for a CLI (deployed-binary test invoking the real artifact) → any external deps via owned adapters.
+- **Isolation:** test through the public invocation surface (args/stdin/stdout/exit codes for a CLI; exported functions for a library); double external deps via adapters.
+- **Success/failure:** documented commands/flags produce documented output + exit code; bad args → documented error + non-zero exit; stdin/stdout/stderr contracts; backward-compatible public API (the consumer's contract).
+- **Double validation:** a small set of deployed-binary tests invoke the real built artifact to catch packaging/startup gaps unit tests miss. Unlike Scheduled Job's equivalent check (out-of-band, below), this smoke is deterministic enough to gate in-band when it exercises only the artifact itself — startup, arg parsing, exit codes — with no external system configured: any external dep it does call is already behind an owned adapter (per Isolation above), so the smoke carries none of the source/sink/scheduler coupling that pushes Scheduled Job's version out-of-band.
+- **Pipeline:** unit + component Stage 1; deployed-binary smoke Stage 1/2.
+
+---
+
+## Batch
+
+### Scheduled Job
+
+Triggered by cron/queue/scheduler to process data and write output/state.
+
+- **Coverage layers:** pure transformation (solitary unit, no I/O) → job orchestration (component: idempotency, partial-failure recovery, checkpointing, time-window logic) → source/sink adapters (adapter integration vs real container or WireMock) → process startup (deployed-binary test invoking the real artifact) → scheduling integration (out-of-band vs the real scheduler in non-prod) → observability (assertions in component tests).
+- **Isolation (run without real data stores or the scheduler):** field-level in-memory fakes for sources/sinks seeded in the test; **inject the clock** (`Clock.fixed(Instant.parse(...), ZoneOffset.UTC)`); invoke the job entrypoint directly rather than via the scheduler.
+- **Success scenarios:** representative input → expected output (report/db update/published message); idempotency (running twice for the same logical period → same result, no duplicates); checkpoint resume without reprocessing; time-window correctness across DST and month/year boundaries; empty input → valid empty report; output conforms to documented schema.
+- **Failure modes:** source unavailable → clean failure with documented exit code, no partial output, safely re-runnable; sink unavailable → no source state change; partial-write → idempotency keys / transactional outbox prevent duplicates on retry; slow run → alertable, locking prevents overlapping runs; malformed records → log context + configured policy (skip/dead-letter/fail); timezone bugs tested via injected clock; concurrent runs → locking/partitioning; mid-run crash → resume from consistent checkpoint.
+- **Double validation:** one out-of-band real-clock check validates production clock wiring (catches "tests UTC, prod container-local"); source/sink contracts pin the shape, post-deploy checks confirm ongoing alignment; a real-scheduler check in non-prod confirms entrypoint discovery, cron timing, env/secret resolution, concurrency policy.
+- **Pipeline:** unit + component + contract Stage 1; adapter integration out-of-band on a schedule, regardless of ownership; small deployed-binary set out-of-band on a schedule; real-clock + real-scheduler checks out-of-band scheduled vs non-prod; post-deploy synthetic invocation verifies it ran, processed records, met SLO.
+
+---
+
+## Quick Reference: Isolation Strategy by Pattern
+
+| Pattern | Double to run pre-merge without config | Validated by |
+|---------|----------------------------------------|--------------|
+| User Interface | Network-layer backend stub (real browser) | Consumer contracts + post-deploy E2E |
+| API Provider | In-memory repository + event bus | Adapter integration (real DB container) + provider contracts |
+| API Consumer | Owned adapter over upstream client | 4-layer: consumer contract + adapter integration + provider verify + post-deploy |
+| Event Consumer | Broker double | Adapter integration (real broker container) + schema contracts |
+| Event Producer | Broker adapter double | Message contract + adapter integration + post-deploy synthetic |
+| Stateful Service | Persistence double + controlled time/ordering | Adapter integration + cluster testcontainers |
+| CLI / Library | Adapters over external deps | Deployed-binary smoke |
+| Scheduled Job | In-memory source/sink fakes + injected clock | Adapter integration + real-clock + real-scheduler out-of-band |

package/knowledge/database-change-management.md

@@ -0,0 +1,80 @@
+# Database Change Management
+
+Reference for evolving a schema while keeping every release candidate
+deployable and every change reversible. Source: *Continuous Delivery* (Humble &
+Farley) Ch.12. This file is about **changing** the database safely in a CD
+pipeline; for **testing** against a database see `database-test-patterns.md`.
+
+The governing rule: **a schema change must never block a deploy or a rollback.**
+The application and the database evolve on independent clocks, so any single
+change must work with both the old and the new application version.
+
+## Everything is a versioned, scripted migration
+
+- The database has a **version** (a row in a `schema_version` / `migrations`
+  table). A migration tool (Flyway, Liquibase, `dbmate`, Rails/Alembic/EF
+  migrations) computes which scripts to apply to move from the current version to
+  the target and runs them at deploy time.
+- Every change is a **script in version control** — initialization and each
+  migration. No manual SQL against any environment, including production. The
+  scripts provision any database in the pipeline from empty to current.
+- Each forward (roll-forward) script has a matching **roll-back script**. Test
+  both: applying then reverting a migration must return the schema to its prior
+  shape.
+
+## Expand / contract (the parallel-change pattern)
+
+A change that would break the running application if applied in one step is split
+into backward-compatible phases. This is the core technique for zero-downtime.
+
+| Phase | What happens | Compatibility |
+|-------|--------------|---------------|
+| **Expand** | Add the new structure (new column/table/index) without removing the old. Backfill data. New and old code both work. | Deploy independently of the app |
+| **Migrate** | Ship app code that writes to both old and new, reads new. Backfill completes. | Old code still works |
+| **Contract** | Once no running app version references the old structure, drop it in a later release. | Only after the app no longer needs it |
+
+Example — rename `qty` → `quantity`: add `quantity` (expand) → dual-write and
+backfill → switch reads → drop `qty` in a subsequent release (contract). The
+rename is never a single `ALTER ... RENAME` that breaks the deployed app.
+
+## Make changes reversible without data loss
+
+| Change | Reversible approach |
+|--------|---------------------|
+| Drop column/table | Copy data to a temp/archive table first (preserve keys + constraints); the roll-back restores from it. Never drop in the same release that stops using it. |
+| Narrow a type / add NOT NULL | Add nullable, backfill, enforce in a later release once data is clean |
+| Add a constraint | Validate existing data first; add as `NOT VALID` then validate, so the lock is short |
+| Destructive data fix | Snapshot affected rows before the change so the roll-back script can replay them |
+
+For zero-downtime where transactions are in flight, prefer **cache-and-replay**
+or a blue-green database (backup/restore on the standby) over an in-place
+destructive change.
+
+## Decouple database change from application change
+
+- Design the app so the database can migrate **independently** of the app upgrade
+  — the schema is at a version the current *and* next app version both accept.
+- Let the data owner (DBA or the owning team) evolve the schema incrementally;
+  the app does not assume the two deploy atomically.
+- For shared or orchestrated databases, rehearse the change in a production-like
+  (SIT) environment before production.
+
+## Detection — flag these in review
+
+| Signal | Risk | Fix direction |
+|--------|------|---------------|
+| A migration that `DROP`s or `RENAME`s a column/table referenced by the same release's app code | Breaks running app during rollout; blocks rollback | Split into expand/contract across releases |
+| A roll-forward script with no roll-back script | Cannot roll back the release | Author the paired reversal; test it |
+| `NOT NULL` / new constraint added without a backfill step | Migration fails or locks on real data | Add nullable → backfill → enforce later |
+| App code and schema assumed to deploy atomically (read of a column added in the same deploy) | Old app instances error mid-rollout | Make the change backward-compatible (expand first) |
+| Manual SQL in a runbook instead of a versioned script | No audit trail, not reproducible, drifts across environments | Move into a migration script in version control |
+
+## How this connects to the rest of the toolkit
+
+- **`database-test-patterns.md`** — how to *test* against a database (isolation,
+  teardown, real-vs-fake); this file is how to *change* one safely.
+- **`release-strategies.md`** — expand/contract is the data-tier counterpart of
+  decoupling deploy from release; blue-green and canary assume the schema is
+  compatible across the versions running side by side.
+- **`deployment-pipeline.md`** — migrations run as an automated, scripted step of
+  the same deploy process in every environment.

package/knowledge/database-test-patterns.md

@@ -0,0 +1,79 @@
+# Database Test Patterns
+
+Reference file for the `cd-test-architecture` and `test-design-advisor` skills and the `test-smell-review` agent. Tests that touch a real database are the most common source of Erratic Tests, Test Run Wars, and Slow Tests — and the hardest to make safe for a CD pipeline. This file covers how to **isolate**, **tear down**, and **avoid** database state so persistence tests stay independent and repeatable.
+
+Source: Gerard Meszaros, *xUnit Test Patterns* (xunitpatterns.com) — Ch. 13 *Testing with Databases* and Ch. 25 *Database Patterns*. Language- and engine-agnostic.
+
+Core principle: **a database test must leave the world exactly as it found it, and must not collide with any other test or test run.** State that leaks across tests creates order-dependence (Interacting Tests); state shared across concurrent runs creates Test Run Wars. The whole game is isolation + reliable teardown — or removing the database from the test entirely.
+
+---
+
+## First question: does this test need a real database at all?
+
+Most logic that *uses* data does not need to test the *database engine*. Push the decision down:
+
+```
+What is actually under test?
+├─ Business logic that happens to read/write data
+│   └─ Replace persistence with a Fake (in-memory repository / In-Memory Database).
+│      Fast, deterministic, pre-merge-gate safe. This is the default. (see test-doubles.md)
+│
+├─ The mapping/queries themselves (ORM config, SQL, schema constraints)
+│   └─ A real database IS the SUT — use the isolation + teardown patterns below.
+│
+└─ Stored procedures / DB-side logic
+    └─ Stored Procedure Test against a real engine, isolated per run.
+```
+
+A suite that spins up the whole database to test ordinary domain logic is the **Slow Tests** smell with a side of fragility. Reserve real-DB tests for the cases where the persistence layer itself is the thing being verified.
+
+---
+
+## Isolation: keep test runs from colliding
+
+| Pattern | What it does | Trade-off |
+|---------|-------------|-----------|
+| **Database Sandbox** | Each developer / CI runner gets its **own** database, so no two runs share rows | The baseline. Without it, concurrent runs cause Test Run Wars |
+| → *Dedicated Database Sandbox* | A separate lightweight DB instance per user/runner | Most flexible (schema changes allowed); needs a per-runner instance |
+| → *DB Schema per Test Runner* | One engine, a separate **schema** per runner; an Immutable Shared Fixture can live in a common schema | Cheaper; users can't diverge the structure |
+
+A Sandbox separates *runs* from each other; it does **not** make the tests *within* a run independent — that still requires a Fresh Fixture per test plus the teardown below.
+
+---
+
+## Teardown: undo what the test did
+
+Pick the cheapest teardown that fully restores state. Prefer rollback; fall back to truncation.
+
+| Pattern | How it cleans up | Use when | Caveats |
+|---------|------------------|----------|---------|
+| **Transaction Rollback Teardown** | Run the whole test in a transaction; roll back at the end so nothing commits | A Fresh-Fixture test on an engine with rollback; **fastest** and schema-change-proof | The SUT must **never commit** — it must run inside a transaction owned by a *Humble Transaction Controller* (`testability-patterns.md`). A stray commit silently defeats it |
+| **Table Truncation Teardown** | Delete/truncate the tables the test populated | The SUT commits, or rollback isn't usable | Must truncate in FK-safe order; more teardown code to maintain |
+| **Delete-by-key / scoped cleanup** | Remove just the rows this test created (often via *Automated Teardown* tracking inserted keys) | Targeted cleanup in a shared schema | Easy to miss a table → leaked state |
+
+Rule of thumb: **Transaction Rollback Teardown** when the design permits it (and design *toward* permitting it via a Humble Transaction Controller); **Table Truncation Teardown** when commits are unavoidable.
+
+---
+
+## Stored Procedure Test
+
+When logic lives in the database (procedures, triggers, functions), it still deserves a test: arrange inputs in tables/parameters, invoke the procedure, verify the returned result set or the resulting table state, then tear down (rollback or truncation). Treat the procedure as the SUT and apply the same isolation. Note that DB-side logic is harder to keep under the pyramid's fast layers — prefer moving non-trivial logic *out* of the database where the team's primary tooling can test it (*Ensure Commensurate Effort*, `test-automation-principles.md`).
+
+---
+
+## CD pipeline placement
+
+- A real database makes a test roughly **an order of magnitude slower** than an in-memory equivalent — Meszaros cites ~50× for round-trips. That cost decides pipeline stage.
+- **Pre-merge gate:** Fake/in-memory persistence (deterministic, no external config). This is where the bulk of data-touching tests belong.
+- **Later stage:** the narrow band of real-DB tests that verify mapping/schema/procedures, running against a per-runner Sandbox with rollback or truncation teardown.
+- A database test that needs a human to seed data or reset state is the **Manual Intervention** smell and cannot gate a pipeline — automate the setup or it doesn't ship. See `cd-test-architecture.md` for the determinism→stage rule this feeds into.
+
+---
+
+## How this connects to the rest of the toolkit
+
+- **`cd-test-architecture.md`** — owns the determinism→pipeline-stage decision; this file supplies the persistence-specific isolation/teardown that makes a DB test gate-eligible.
+- **`test-doubles.md`** — the Fake Object (in-memory DB/repository) that lets most data-logic tests avoid a real database entirely.
+- **`testability-patterns.md`** — the *Humble Transaction Controller* (a Humble Object) that Transaction Rollback Teardown depends on.
+- **`test-smells.md`** — Erratic Test (Test Run War, Interacting Tests), Slow Tests, Manual Intervention: the smells unmanaged database state produces.
+- **`test-strategy.md` / `fixture-construction.md`** — Fresh vs. Shared Fixture and Automated Teardown, the general machinery this specializes for databases.

package/knowledge/decision-defaults.md

@@ -0,0 +1,88 @@
+# Decision Defaults
+
+High-reversal-cost decision axes that recur across tasks and, when guessed wrong,
+force an interrupt and rework. For each axis: the trigger that raises it, the default
+stance, and what to confirm before committing. Screen every non-trivial request
+against this list during discovery; surface any ambiguous axis in a single upfront
+batch — **each with its recommended default attached** — rather than guessing and
+being corrected later. A surfaced axis with no recommended default is incomplete: it
+makes the user do the deciding from a blank, which is the menu anti-pattern this list
+exists to prevent. State your best answer for each axis and let the user override it.
+
+These are defaults, not laws — an explicit user instruction always wins. The point is
+to resolve the axis *before* building, not to relitigate it mid-stream.
+
+**Non-interactive runs.** When no human can answer the upfront batch (headless
+`/plan`/`/build`, `--yes`, `DEV_TEAM_AUTO_APPROVE=1`), surfacing degrades to
+recording: take the recommended default for every ambiguous axis, state each axis and
+stance in the plan (and, via `/pr`, the PR body) — and **never take a non-default
+stance on any axis without an explicit user instruction**. A non-default stance with
+nobody present to confirm it is a guess, not a decision; if the task appears to
+require one, that is an escalation, not an assumption.
+
+## Destructive shape: replace vs. merge
+
+Trigger: a request writes config, settings, dotfiles, or installer output where prior
+content may exist. Default: **recommend merge — preserve existing content** — because
+it is the reversible option; a clean replace discards prior settings and is hard to
+undo. Surface the choice before acting, but always with that merge default attached —
+never a bare "merge or replace?". Confirm: does the user want existing content
+preserved (merge, the recommended default) or overwritten (replace)? When unstated and
+the target is non-trivial, surface the choice with the merge default and proceed once
+it is resolved; do not silently act in either direction.
+
+## Format fidelity: preserve the native format
+
+Trigger: handling a vector or structured asset (SVG, source diagram, lossless data).
+Default: preserve the native, lossless form; do not down-convert (for example, SVG to
+PNG) for convenience. Confirm: if a conversion seems necessary, name the reason and
+get agreement before doing it.
+
+## Evolution: migrate vs. edit a stub in place
+
+Trigger: a target has been renamed, deprecated, or replaced by a successor (a plugin,
+module, or file with a forwarding stub). Default: migrate to the current target rather
+than editing the deprecated stub in place. Confirm: verify which artifact is canonical
+before changing it — a stub edit that looks done can leave the real target untouched.
+
+## Integration: auto-merge vs. direct-to-trunk
+
+Trigger: landing changes on a shared branch. Default: open a PR and use auto-merge
+gated on green checks rather than merging directly to trunk. Confirm: only merge
+directly when the user has asked for it; a direct merge can bypass checks and lose work.
+
+## Scope: touch only what was requested
+
+Trigger: a request names specific files, slides, or targets. Default: change only
+those; do not expand scope to adjacent items. Confirm: if neighboring changes seem
+warranted, propose them separately rather than folding them in unasked.
+
+## Re-capture: keep vs. overwrite an existing tracked artifact
+
+Trigger: a worker is about to re-run an expensive capture for an artifact that
+already has a tracked copy for the same key (e.g. a coverage baseline, a mutation
+history entry, a benchmark snapshot). Default: **keep** — recommend reuse of the
+existing tracked artifact, and confirm before discarding what may be a comparison
+baseline. Overwriting without confirmation risks silently invalidating the
+baseline every later phase measures against.
+
+Mechanics:
+
+- **Interactive**: prompt keep/overwrite with default keep. An unrecognized answer
+  (anything other than "keep" or "overwrite", case-insensitive) re-prompts with the
+  identical choice — never silently falls back to either option. There is no retry
+  limit and no timeout; the guard keeps re-prompting until it receives "keep" or
+  "overwrite".
+- **Non-interactive** (no usable TTY, or `DEV_TEAM_AUTO_APPROVE=1`): keep the
+  existing tracked artifact automatically, without prompting. The auto-decision is
+  both **logged** (to the worker's own record/audit trail) **and echoed** to run
+  output — a decision recorded only to a file the operator never sees is not an
+  auto-decision the operator can trust.
+- **Existing file is malformed or corrupt**: if the existing tracked artifact fails to parse
+  (e.g. invalid JSON from a prior interrupted write), treat it as absent — never
+  silently keep a file that cannot be read back. Emit a warning naming why a fresh
+  capture is happening.
+
+Confirm: on overwrite, replace the tracked artifact with the fresh capture; on keep
+(or an equivalent non-interactive default), skip the expensive capture entirely and
+reuse the existing artifact's recorded values.