jorgex-stack 1.0.29 → 1.0.31

package/stack/skills/orchestrator/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: orchestrator
+description: Main coordinator for non-trivial tasks. Designs, plans and delegates to specialized subagents. Use it when the work spans several layers, several files or requires coordination. Invoke to switch into orchestrator mode and apply its flow to the current task.
+---
+
+# Orchestrator
+
+You coordinate the work. You think, design, split and delegate according to the **Delegation map**. Don't stay implementing yourself except for minimal documentation or coordination tasks.
+
+## Phases
+
+```text
+INIT → EXPLORE → SPEC → PLAN → EXECUTE → VERIFY → SHIP → CLOSE
+```
+
+### Autonomy
+
+The human drives the flow UP TO the plan: the idea, the PRD review and the plan review are interactive. Once the plan is approved, EXECUTE → VERIFY → SHIP run **autonomously** — no confirmation pauses: plan approval authorizes commits, pushes to the work branch, draft PR creation, final review, and the draft-to-ready transition after verification. Task-critical uncertainty from a subagent is an operational blocker, not a pause in autonomy: answer from existing context first; only if the decision genuinely cannot be made from available context may you ask the user, then relaunch with explicit guidance. Control returns to the user at CLOSE. Merging the PR is NEVER yours: it always requires an explicit user order. For multi-PR work, each merge is a checkpoint; keep `work/{name}/PRD.md` and `plan.md` alive until the roadmap is finished. Dependent PRs are sequential: after a checkpoint merge, update the production branch and create the next worktree/branch from that updated base.
+
+## 1. INIT
+
+- Load previous context from Engram memory: for non-trivial reads, delegate to the `engram` subagent (`mem_context` / `mem_search` filtered to the task).
+- Identify the project's constraints.
+- Detect whether there is documentation, issues or artifacts already created.
+
+## 2. EXPLORE
+
+Launch analysts according to scope:
+
+- `backend-analyst` if it affects backend, DB, APIs or server functions
+- `frontend-analyst` if it affects UI, hooks, state or rendering
+- `security-auditor` if the area is sensitive
+
+## Base rule
+
+- Your priority is to delegate.
+- If a task has a clear subagent scope, delegate.
+- If previous context is needed, gather context or analyze before deciding implementation.
+
+### Delegation triggers
+
+Once a task crosses any of these thresholds, delegating stops being optional:
+
+| Trigger | Expected behavior |
+| --- | --- |
+| Reading 4+ files just to understand a flow | Delegate exploration to the matching analyst. |
+| Wrong cwd, git/worktree accident, confusing test or env failure | Stop; re-explore with fresh context before continuing. |
+| Long session with accumulating complexity | Pause and re-plan or delegate — or state explicitly why not. |
+
+The goal is not ceremony: it is one responsible coordinator, one writer per scope, deterministic feedback while the diff is evolving, and fresh eyes at the PR boundary.
+
+## 3. SPEC
+
+- Synthesize findings.
+- Propose a simple approach.
+- Clarify only the real ambiguities.
+- Apply the `lean-code` skill as a scope gate for any code-bearing task: ask whether the code is needed at all, whether stdlib/native/project helpers already solve it, and whether the smallest obvious change is enough.
+- Backlog items phrased as "consider/evaluate X" are questions, not requirements: answer them HERE — who consumes it, what real case needs it — before they enter the PRD as committed scope. A contract nobody consumes is born dead; drop it or defer it explicitly instead of inheriting it as a fact.
+- Create the PRD before moving to PLAN (see PRD rules).
+
+### PRD rules
+
+The PRD is **mandatory by default** when you work as orchestrator. If you were invoked, the work is non-trivial (several layers, several files or coordination) and deserves a spec before executing. The PRD captures decisions before implementing and leaves traceability towards the tasks.
+
+Use the `to-prd` skill to turn the current context into the PRD (`work/{name}/PRD.md`) before planning execution.
+
+**Escape valve (measurable)**: skip the PRD only if one of these applies:
+
+- the user explicitly asks to skip it, or
+- ALL of these hold: the change touches ≤ 3 files, AND stays in a single layer (only backend, only frontend, only docs…), AND changes no public contract (API, schema, exported types consumed elsewhere). In that case, consider returning the work to the normal flow instead of orchestrating.
+
+If you skip it, say so explicitly and state which condition applied.
+
+When presenting the PRD for review, offer a disposable HTML view (rules in the `work-lifecycle` skill).
+
+If the work is large enough to benefit from explicit vertical slices, use the `to-issues` skill after the PRD to split it into independently executable slices before detailed planning.
+
+## 4. PLAN
+
+- Use the PRD as the base input for planning (it normally exists; only absent if the escape valve was used).
+- If a slice breakdown exists from `to-issues`, use it as the structure for planning and task sequencing.
+- Divide the work into clear tasks.
+- One task = one agent = one scope.
+- For tasks that add or grow code, record the lean-code outcome in the task spec/acceptance criteria so implementer and simplifier apply the same ladder.
+- The PRD does not replace the plan or task breakdown: the PRD captures decisions; the plan and tasks turn those decisions into executable work.
+- Materialize the plan per the Work state rules: `work/{name}/plan.md` with the task table, plus one `mem_save` per task with its full self-contained spec (templates in the `work-lifecycle` skill).
+- When presenting the plan for review, offer a disposable HTML view (rules in the `work-lifecycle` skill). Requested changes go to plan.md; delete the HTML once the plan is approved, before EXECUTE.
+
+## Work state
+
+The `work-lifecycle` skill is the single source of this flow. Summary — every piece has exactly ONE home:
+
+- `work/{name}/` (gitignored, exists only while the work is in progress) holds the human-reviewed artifacts: `PRD.md` and `plan.md`. They stay resident across intermediate PR merges; `plan.md` is the ONLY task status board — flip statuses with surgical edits; don't re-read the whole plan after every task (re-read it on resume).
+- The full spec of each atomic task → Engram, one `mem_save` per task under `work/{name}/task/{NN}`. When you delegate a task, pass the subagent its topic_key + title — never the task content inline; it retrieves the spec itself.
+- Phase outcomes, decisions and PR checkpoints → Engram under `work/{name}/{phase}` and `work/{name}/pr/{NN}`; tell each subagent which topic_key to use for its saves.
+- Pending work → the project's single `work/backlog` topic_key, or issues (`to-issues`) if the project uses a tracker. Never a TODOs folder. For Engram, you are the **single writer**: before every change, retrieve the exact observation with `mem_get_observation`, preserve unrelated entries, send the complete content with `mem_update`, then read it again to verify. Never write it concurrently or use a blind topic-key upsert. Do not split it into per-item memories until Engram supports complete paginated topic-prefix listing.
+- On final close: `mem_save` the outcome under `work/{name}/done`, move the PRD to the project's docs only if it has lasting documentation value, then delete `work/{name}/`. `work/{name}/done` is only for the last PR / final outcome. History is memory + git.
+
+## Delegation map
+
+Load the `agent-delegation` skill: it defines the available subagents, the scope of each and when to delegate. It is the single source of the agent map — don't duplicate the list here.
+
+Every subagent follows its active result contract. Process it:
+
+- Launch every specialist named by the active delegation field or format.
+- A delegation is unfinished work in another scope, not a request to append a generic quality pipeline. Normal handoffs between `implementer` and `tester` do not by themselves justify reviewers or analyzers.
+- If a subagent reports `partial`, keep the safe work and relaunch only what still needs guidance.
+- If a subagent reports `blocked` with one concrete uncertainty question, answer it from existing context when possible; if it still cannot be resolved, ask the user only if genuinely necessary, then relaunch the original or a suitable specialist with explicit guidance.
+- Don't declare a phase done while a delegation remains unprocessed.
+- If the reported status is `partial` or `blocked`, resolve the cause before moving on.
+
+## 5. EXECUTE
+
+### Worktree
+
+Before the first task, create a git worktree for this work and run the ENTIRE execution inside it — implementation, tests, commits and pushes happen there, never on the user's main checkout.
+
+Canonical location is mandatory: resolve the project root with `git rev-parse --show-toplevel`, ensure `worktrees/` is ignored in the repo-local `.git/info/exclude`, create `worktrees/` inside that root if needed, and create the worktree at `<project-root>/worktrees/<canonical-name>` for single-PR work or `<project-root>/worktrees/<canonical-name>-prNN` for multi-PR checkpoints (branch = worktree name). Do not create worktrees next to the repo, in the repo root, under `work/`, or in any external temp/shared folder.
+
+Every delegation prompt must state the worktree path as the ONLY allowed write root. After each writer subagent finishes, verify the user's main checkout is still clean (`git status` there); if the subagent wrote outside the worktree, STOP, move those changes into the worktree (patch/apply) and restore the main checkout before continuing. Subagent obedience is not a safety boundary — this check is.
+
+### Commit cadence
+
+Commit after each task or bounded group of tasks, with a message that reflects that task — the branch history must map to the plan. Never accumulate the whole work into one giant commit at the end.
+
+### Draft PR cadence
+
+- After the first coherent commit, push the branch and create the PR against its real base with `gh pr create --draft`. Do not wait until SHIP to open it.
+- Keep every code change, commit and push inside the draft phase. The PR remains draft until the code, applicable version bump, local tests, project quality command (`pnpm qa:quality` when defined), Vercel preview when applicable, final diff, and full review are complete.
+- Never push to a ready PR. If a ready PR needs changes, first run `gh pr ready --undo <number>`, then modify and push while draft and repeat VERIFY and the final review before readying it again.
+
+### Handoff rule
+
+The analyst's **Recommendation** is the implementer's input. Sequence: analyst (map + design) → you turn it into tasks → `implementer`/`tester` execute. Don't launch `implementer` on an area no analyst has mapped unless the design is already clear from existing context.
+
+### Testing decision
+
+Every implementation task needs a testing decision, not automatically a new test. Establish:
+
+- the meaningful regression risk introduced by the change
+- the existing test that already protects it, if any
+- the new or changed behavior that needs protection
+- the strongest seam closest to that risk
+- the action: TDD/new test, update, reuse existing coverage, or no new test with a concrete trivial/mechanical/already-covered reason
+
+Prefer one authoritative test per behavior. Another layer is justified only when it protects a distinct contract. The task spec carries this decision so `tester` and `implementer` do not invent different strategies.
+
+### TDD mode
+
+Use for business rules, bugs/regressions, public contracts, invariants, security/data boundaries, or other behavior whose risk warrants new protection.
+
+```text
+tester (RED) → implementer (GREEN/REFACTOR)
+```
+
+### Direct mode
+
+Use for styling, wiring, generated code, mechanical refactors, trivial code, or changes already covered by an authoritative test. Direct mode still runs the cheapest sufficient verification and records why no new test was needed.
+
+```text
+implementer (direct change)
+```
+
+### Special delegations
+
+- `translator` for translations or multilingual visible text
+- `docs-maintainer` for documentation
+- `security-auditor` for sensitive review
+
+### Verification cadence
+
+Deterministic checks are the routine feedback loop while implementation is in progress: run the relevant tests, lint and typecheck/build checks at the cheapest seam that can catch the section's regressions. Verify by bounded, coherent sections (e.g. when a wave completes), not after every small change — and don't defer everything to a single big-bang check at the end either.
+
+Each writer verifies its own bounded area (e.g. its test file). The orchestrator runs shared checks such as the global typecheck once when the wave closes, never concurrently or repeatedly through several writers. Reserve the full suite for VERIFY unless a wave changed broad cross-cutting behavior and an earlier run has a concrete benefit.
+
+### Early-review budget
+
+An early review during EXECUTE is an **exception**, not a default phase. Use it only when there is a concrete risk that deterministic checks cannot cover and the feedback can materially change the remaining implementation. Typical candidates are a sensitive authorization boundary, a destructive migration, subtle concurrency/state consistency, or a broad public contract change.
+
+- State the exact risk and the bounded diff section to inspect before launching anyone.
+- Use the single most relevant specialist. Do not load the `xreview` skill or run a generic multi-agent panel during EXECUTE.
+- Run at most one early review per bounded critical section, after that section is coherent rather than after each task inside it.
+- Do not launch `code-reviewer`, `code-simplifier`, `test-analyzer` or `silent-failure-hunter` merely because a writer finished, a test task completed, several files changed or a commit is due.
+- File count, writer completion, commit, push, or draft PR creation are not early-review triggers. The review boundary is the final candidate SHA while the PR is still draft, immediately before `gh pr ready` in SHIP.
+
+## 6. VERIFY
+
+- Validate against the plan's **Success criteria** in plan.md and tick the ones that pass. Tests passing is NOT enough: a criterion left unmet means the work is not done, even with a green suite.
+- Run the minimum verification that is sufficient.
+- Reserve heavy suites for cases where they provide real value or the project requires them.
+- Before SHIP, ensure all applicable preflight work is complete: code, version bump, local tests, the project's quality command (`pnpm qa:quality` when defined), and Vercel preview review when the project uses Vercel. React Doctor is manual/local, never assumed to be a GitHub Actions gate.
+- If something fails, go back to EXECUTE with fix tasks.
+- **Anti-thrashing**: max 3 attempts per failing task or criterion. If the third attempt still fails, STOP retrying — document what was tried and why it fails (save it under the work's topic_key), then re-plan the task with a different approach or stop and report the blocker. A hard blocker is the one legitimate reason to interrupt the autonomous run; retrying blindly is never one.
+
+## 7. SHIP (automatic)
+
+When the plan is fully applied and VERIFY passes:
+
+1. Confirm the draft PR exists, the worktree is clean, and the draft head matches the local HEAD. Inspect the final diff against the PR's real base.
+2. Load and run the portable `xreview` skill against that final diff while the PR is still draft. This is the one multi-agent review per PR and the definitive review boundary; draft PR creation is not. Process the report by its three levels:
+   - **Critical Issues (must fix)**: apply ALL of them — the PR must not reach merge with these open.
+   - **Important Improvements (should fix)**: apply the ones worth doing now, at your judgment.
+   - **Suggestions (nice to have)**: apply only if trivial and safe.
+3. Every finding you decide NOT to apply now goes to the project's `work/backlog` single topic_key — one line each: what + why deferred. Apply the safe serialized backlog protocol above; subagents only return candidate lines.
+4. For what you DO apply: add the new tasks to plan.md and one `mem_save` per task spec, execute them as in EXECUTE, re-verify, and push the fixes while the PR remains draft. Re-run the `xreview` skill only if the fixes materially changed the reviewed diff or introduced a materially different risk; ordinary finding fixes need deterministic re-verification, not another panel.
+5. Once code, verification, preview, final diff, and review are complete, record the candidate SHA and mark the PR ready exactly once with `gh pr ready <number>`.
+6. Determine whether the project has PR checks configured by inspecting project configuration such as workflows, rulesets or integrations. If the project has PR checks configured, wait for the complete Quality Gates, run `gh pr checks <number>`, and verify they pass for the recorded candidate SHA. If no PR checks are configured, confirm and record their absence; it does not block the merge. An empty `gh pr checks` result immediately after ready is not evidence that no checks are configured. In either case, do not push while the PR is ready. Immediately before reporting or merging, compare `gh pr view --json headRefOid` with the recorded candidate SHA.
+7. If any fix is needed, run `gh pr ready --undo <number>` before editing, return to EXECUTE, and repeat the full verification, review, ready, and — when configured — gate cycle. Never treat checks from an older SHA as merge evidence.
+
+## 8. CLOSE
+
+- STOP here and hand control back to the user only after configured Quality Gates pass for the latest commit, or after confirming that the project has no PR checks configured: report the candidate SHA, check result or confirmed absence, review findings applied vs deferred to `work/backlog`, and whether manual testing is advisable (recommend it for big or user-facing changes; small well-tested changes may not need it).
+- NEVER merge the PR yourself — merge only on an explicit user order. After each intermediate merge: persist the checkpoint to `work/{name}/pr/{NN}`, update `plan.md`, and keep `work/{name}/` alive. After the final merge: persist the final outcome to memory, clean up `work/{name}/` and remove the worktree (see Work state).
+- If the repo has its own skill for the closing steps (release, deploy, git, cleanup), that skill takes precedence over the default behavior.
+
+## Task rule
+
+A task must correspond to a single agent and a single scope. Don't mix production, tests, docs and translations in the same task.
+
+## Operational rules
+
+- The coordinator must not mix scopes in a single task.
+- Read-only agents can run in parallel.
+- Write agents only run in parallel if they don't touch the same files.
+
+## Closing rule
+
+Don't declare the task finished if you have only analyzed or planned. There must be real execution by the subagents or a concrete blocker.

package/stack/skills/tdd/SKILL.md

@@ -1,109 +1,91 @@
 ---
 name: tdd
-description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+description: Risk-based test-driven development with a red-green-refactor loop. Use for business rules, bugs/regressions, public contracts, invariants, or explicit test-first work; not automatically for styles, wiring, or mechanical changes.
 ---
 
 # Test-Driven Development
 
-## Philosophy
+## Core principle
 
-**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
+Tests protect behavior and risk, not files, layers, or coverage percentages. A change needs a **testing decision**, not automatically a new test.
 
-**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
+For every change, establish:
 
-**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
+1. **Risk** — what meaningful failure could this change introduce?
+2. **Existing protection** — which existing test already catches it, if any?
+3. **New behavior** — what changed contract or regression needs new protection?
+4. **Seam** — what is the strongest test closest to that risk?
+5. **Decision** — add/update a test, reuse existing coverage, or add no test with a concrete reason.
 
-See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+One behavior should normally have one authoritative test. Test it again at another layer only when that layer protects a distinct contract.
 
-## Anti-Pattern: Horizontal Slices
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for boundary-double guidance.
 
-**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
+## When to use TDD
 
-This produces **crap tests**:
+Use red-green-refactor when the change defines or repairs:
 
-- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
-- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
-- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
-- You outrun your headlights, committing to test structure before understanding the implementation
+- Business rules, calculations, validation, dates, or time zones
+- A real bug/regression
+- Public API, event, schema, or protocol contracts
+- Authentication, authorization, RLS, tenant separation, billing, privacy, or data integrity
+- Destructive, concurrent, atomic, or idempotent behavior
+- Important accessibility or user interactions
 
-**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
+Do not impose TDD merely because a file changed. Styling, decorative DOM, wiring, aliases, wrappers, generated code, mechanical refactors, and trivial callbacks usually need existing verification or no new test unless they change meaningful behavior.
 
-```
-WRONG (horizontal):
-  RED:   test1, test2, test3, test4, test5
-  GREEN: impl1, impl2, impl3, impl4, impl5
-
-RIGHT (vertical):
-  RED→GREEN: test1→impl1
-  RED→GREEN: test2→impl2
-  RED→GREEN: test3→impl3
-  ...
-```
-
-## Workflow
+## Choose the seam from the risk
 
-### 1. Planning
+Use the cheapest seam that can fail for the real regression:
 
-When exploring the codebase, use the project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching.
+- Pure rule or calculation → focused unit/module test
+- Component interaction or accessibility contract → component/browser test through stable semantics
+- Persistence, SQL, RLS, migration, or data-transaction atomicity → real database/integration test
+- Other concurrency or atomicity → execute at the implicated filesystem, queue, process, or shared-state boundary
+- Public endpoint or privileged function → contract/integration test at that boundary
+- Critical cross-system user journey → end-to-end test
 
-Before writing any code:
+“Integration-style” is not inherently stronger. A broad test full of mocks may be weaker than a focused rule test, while a regex over SQL text is weaker than executing the database behavior it claims to protect.
 
-- [ ] Confirm with user what interface changes are needed
-- [ ] Confirm with user which behaviors to test (prioritize)
-- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
-- [ ] Design interfaces for [testability](interface-design.md)
-- [ ] List the behaviors to test (not implementation steps)
-- [ ] Get user approval on the plan
+## Anti-pattern: horizontal slices
 
-Ask: "What should the public interface look like? Which behaviors are most important to test?"
+Do not write all tests first and then all implementation. This outruns what has been learned and encourages tests of imagined shapes.
 
-**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
+Use vertical tracer bullets for each behavior that merits new protection:
 
-### 2. Tracer Bullet
-
-Write ONE test that confirms ONE thing about the system:
-
-```
-RED:   Write test for first behavior → test fails
-GREEN: Write minimal code to pass → test passes
+```text
+RED → one test fails for the intended behavioral reason
+GREEN → minimal production change makes it pass
+REFACTOR → improve structure while behavior stays green
 ```
 
-This is your tracer bullet - proves the path works end-to-end.
+Then repeat for the next distinct behavior. Do not create separate tests merely to split assertions that describe one coherent outcome.
 
-### 3. Incremental Loop
+## Workflow
 
-For each remaining behavior:
+### 1. Make the testing decision
 
-```
-RED:   Write next test → fails
-GREEN: Minimal code to pass → passes
-```
+Complete the five-part decision under **Core principle**. If no new protection is warranted, record the reason and run the cheapest sufficient verification; otherwise continue to RED.
 
-Rules:
+### 2. RED, when new protection is warranted
 
-- One test at a time
-- Only enough code to pass current test
-- Don't anticipate future tests
-- Keep tests focused on observable behavior
+Write one test that fails because the behavior is missing or broken—not because setup, mocks, or fixtures are wrong.
 
-### 4. Refactor
+### 3. GREEN
 
-After all tests pass, look for [refactor candidates](refactoring.md):
+Write only enough production code to satisfy the behavior. Do not anticipate speculative cases.
 
-- [ ] Extract duplication
-- [ ] Deepen modules (move complexity behind simple interfaces)
-- [ ] Apply SOLID principles where natural
-- [ ] Consider what new code reveals about existing code
-- [ ] Run tests after each refactor step
+### 4. Refactor
 
-**Never refactor while RED.** Get to GREEN first.
+Refactor only while green. Remove duplication in production and tests, and delete lower-value tests when a stronger test now protects the same behavior.
 
-## Checklist Per Cycle
+## Checklist
 
-```
-[ ] Test describes behavior, not implementation
-[ ] Test uses public interface only
-[ ] Test would survive internal refactor
-[ ] Code is minimal for this test
-[ ] No speculative features added
+```text
+[ ] When new protection is warranted, RED fails for the intended behavioral reason
+[ ] The chosen seam observes behavior or the real boundary at risk
+[ ] Another layer would protect a distinct contract, not duplicate this one
+[ ] Mocks do not encode internal call choreography
+[ ] No-test decisions have a concrete trivial/mechanical/already-covered reason
+[ ] Production code is minimal and non-speculative
 ```

package/stack/skills/tdd/mocking.md

@@ -1,59 +1,34 @@
-# When to Mock
+# Boundary Doubles and Mocks
 
-Mock at **system boundaries** only:
+Mocks are a cost/risk tradeoff, not a goal or a categorical ban.
 
-- External APIs (payment, email, etc.)
-- Databases (sometimes - prefer test DB)
-- Time/randomness
-- File system (sometimes)
+## Prefer real behavior when practical
 
-Don't mock:
+Use real owned code when it is fast, deterministic, safe, and easy to set up. Mocking internal collaborators just to assert call choreography couples the test to implementation and can let broken behavior pass.
 
-- Your own classes/modules
-- Internal collaborators
-- Anything you control
+Prefer real test infrastructure when the risk lives there:
 
-## Designing for Mockability
+- RLS, SQL, migrations, transactions, and data-transaction atomicity → test database
+- Other concurrency or atomicity → the actual filesystem, queue, process, or shared-state boundary
+- Filesystem semantics → isolated temp directory
+- Serialization/protocol parsing → real encoder/decoder
 
-At system boundaries, design interfaces that are easy to mock:
+## Use a boundary double when it is the reliable seam
 
-**1. Use dependency injection**
+A fake, stub, or mock is appropriate for a boundary that is unavailable, expensive, nondeterministic, destructive, or controlled by a third party:
 
-Pass external dependencies in rather than creating them internally:
+- Payment, email, identity, or other external APIs
+- Time, randomness, process execution, or network failures
+- A slow service when its protocol—not its implementation—is the contract under test
 
-```typescript
-// Easy to mock
-function processPayment(order, paymentClient) {
-  return paymentClient.charge(order.total);
-}
+Assert only the boundary contract needed by the behavior: payload, headers, idempotency key, returned error mapping, or observable result. Avoid exhaustive call counts and ordering unless the external protocol requires them.
 
-// Hard to mock
-function processPayment(order) {
-  const client = new StripeClient(process.env.STRIPE_KEY);
-  return client.charge(order.total);
-}
-```
+## Keep doubles simple
 
-**2. Prefer SDK-style interfaces over generic fetchers**
+- Inject the narrow boundary instead of mocking a large internal module graph.
+- Return one explicit shape per scenario.
+- Do not rebuild production branching logic inside the mock.
+- If every important collaborator is mocked, do not call the suite integration testing.
+- Prefer a reusable fake only after repeated real need; do not create abstraction for a single test.
 
-Create specific functions for each external operation instead of one generic function with conditional logic:
-
-```typescript
-// GOOD: Each function is independently mockable
-const api = {
-  getUser: (id) => fetch(`/users/${id}`),
-  getOrders: (userId) => fetch(`/users/${userId}/orders`),
-  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
-};
-
-// BAD: Mocking requires conditional logic inside the mock
-const api = {
-  fetch: (endpoint, options) => fetch(endpoint, options),
-};
-```
-
-The SDK approach means:
-- Each mock returns one specific shape
-- No conditional logic in test setup
-- Easier to see which endpoints a test exercises
-- Type safety per endpoint
+The question is not “can this be mocked?” It is “which setup gives the strongest evidence for this risk at acceptable cost?”

package/stack/skills/tdd/tests.md

@@ -1,61 +1,59 @@
-# Good and Bad Tests
+# Choosing Valuable Tests
 
-## Good Tests
+## One behavior, one authoritative seam
 
-**Integration-style**: Test through real interfaces, not mocks of internal parts.
+Choose the seam from the regression you need to catch.
 
 ```typescript
-// GOOD: Tests observable behavior
-test("user can checkout with valid cart", async () => {
-  const cart = createCart();
-  cart.add(product);
-  const result = await checkout(cart, paymentMethod);
-  expect(result.status).toBe("confirmed");
+// Pure pricing rule: a focused module test is closest to the risk.
+test("applies the reduced tax rate to eligible items", () => {
+  expect(calculateTax(eligibleItem)).toBe(4.2);
 });
 ```
 
-Characteristics:
+```typescript
+// User interaction: verify the accessible outcome, not DOM decoration.
+test("submits a valid checkout", async () => {
+  await user.click(screen.getByRole("button", { name: "Pay" }));
+  expect(await screen.findByText("Payment confirmed")).toBeVisible();
+});
+```
 
-- Tests behavior users/callers care about
-- Uses public API only
-- Survives internal refactors
-- Describes WHAT, not HOW
-- One logical assertion per test
+```sql
+-- Tenant isolation: execute against a real test database with two users.
+-- Regex matching a CREATE POLICY statement does not prove RLS behavior.
+```
 
-## Bad Tests
+Characteristics of valuable tests:
 
-**Implementation-detail tests**: Coupled to internal structure.
+- Catch a concrete user, business, security, data, or contract regression
+- Observe a public interface or the real boundary at risk
+- Survive an internal refactor
+- Use the narrowest reliable setup
+- Add a second layer only for a different contract
 
-```typescript
-// BAD: Tests implementation details
-test("checkout calls paymentService.process", async () => {
-  const mockPayment = jest.mock(paymentService);
-  await checkout(cart, payment);
-  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
-});
-```
+## Low-value and redundant tests
 
-Red flags:
+Avoid tests whose only purpose is to assert:
 
-- Mocking internal collaborators
-- Testing private methods
-- Asserting on call counts/order
-- Test breaks when refactoring without behavior change
-- Test name describes HOW not WHAT
-- Verifying through external means instead of interface
+- Tailwind classes, decorative DOM, or incidental markup
+- That a wrapper, alias, constant, callback, or function exists
+- Exact internal call counts/order when the observable result is what matters
+- The same behavior already protected at a stronger seam
+- SQL policy or migration correctness exclusively through text/regex shape
+- “Integration” while every important collaborator is mocked
 
 ```typescript
-// BAD: Bypasses interface to verify
-test("createUser saves to database", async () => {
-  await createUser({ name: "Alice" });
-  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
-  expect(row).toBeDefined();
-});
+// BAD: locks internal choreography.
+expect(paymentService.charge).toHaveBeenCalledTimes(1);
+expect(emailService.send).toHaveBeenCalledAfter(paymentService.charge);
 
-// GOOD: Verifies through interface
-test("createUser makes user retrievable", async () => {
-  const user = await createUser({ name: "Alice" });
-  const retrieved = await getUser(user.id);
-  expect(retrieved.name).toBe("Alice");
-});
+// BETTER: assert the contract callers rely on.
+expect(result).toMatchObject({ status: "confirmed", receiptId: expect.any(String) });
 ```
+
+Exact calls are valid only when the call itself is the external contract—for example, the precise payload sent to a payment provider or an idempotency key required by its protocol.
+
+## Valid no-new-test decisions
+
+A change may need no new test when it is styling-only, mechanical, generated, already covered by an authoritative test, or has no meaningful behavioral branch. State the reason and run the cheapest existing verification that could catch an accidental break.

package/stack/skills/to-prd/SKILL.md

@@ -9,7 +9,9 @@ This skill takes the current conversation context and codebase understanding and
 
 1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching.
 
-2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can.
+2. Sketch out the seams at which you're going to test the feature. Prefer an existing seam when it is strong enough, and choose the closest seam that can fail for the concrete regression risk. Introduce a new seam only when existing ones cannot provide reliable evidence.
+
+Do not choose from a fixed test pyramid or a requirement to add tests. Prefer one authoritative test at the strongest seam closest to the risk; another layer is justified only for a distinct contract. Record existing coverage and valid no-new-test decisions for trivial, mechanical, generated, styling, or wiring changes.
 
 Check with the user that these seams match their expectations.
 
@@ -67,9 +69,13 @@ Keep this static: describe the planned delivery slices, not the current state.
 
 A list of testing decisions that were made. Include:
 
-- A description of what makes a good test (only test external behavior, not implementation details)
-- Which modules will be tested
-- Prior art for the tests (i.e. similar types of tests in the codebase)
+- The meaningful regression risk introduced by each behavior change
+- Which existing tests already protect it
+- Which new behavior requires protection
+- The chosen seam and why it is closest to the risk
+- Why another layer would protect a distinct contract rather than duplicate the same behavior
+- Why no new test is needed for trivial, mechanical, generated, styling, wiring, or already-covered changes
+- Prior art for the selected tests (i.e. similar valuable tests in the codebase)
 
 ## Out of Scope