jorgex-stack 1.0.29 → 1.0.30

package/README.md

@@ -8,16 +8,24 @@ Portable multi-agent harness: one configuration source — 15 agents, 17 skills,
 
 Install and run via npm without cloning the repository:
 
+```bash
+# First installation
+pnpm dlx jorgex-stack install
+
+# Already installed: apply the latest published stack while keeping the existing model selection
+pnpm dlx jorgex-stack sync
 ```
-pnpm dlx jorgex-stack install    # install runtimes; first OpenCode setup selects connected models
-pnpm dlx jorgex-stack models     # model picker by runtime and tier (strong/standard/cheap)
-pnpm dlx jorgex-stack sync       # alias of install (same idempotent apply)
-pnpm dlx jorgex-stack doctor     # checks that everything is healthy (Engram, drift, hooks, keys)
-pnpm dlx jorgex-stack update     # interactive: scans stack + Engram, multiselect, diff/confirm
-                                 # With --check: report only, no changes
-                                 # With --yes: batch mode (report only)
-pnpm dlx jorgex-stack restore    # restores a backup
-pnpm dlx jorgex-stack uninstall  # uninstalls our files and keeps user data (Engram intact)
+
+Other important commands:
+
+```bash
+pnpm dlx jorgex-stack doctor          # check Engram, config drift, hooks and keys
+pnpm dlx jorgex-stack models          # change models by runtime, tier or subagent
+pnpm dlx jorgex-stack update --check  # report available stack, Engram and skill updates
+pnpm dlx jorgex-stack update          # interactively review and apply available updates
+pnpm dlx jorgex-stack restore --list  # list automatic backups
+pnpm dlx jorgex-stack restore <id>    # restore one backup
+pnpm dlx jorgex-stack uninstall       # remove managed files; keep Engram data intact
 ```
 
 For development from a clone, run the same commands through `pnpm cli <command>` (see [Development](#development)).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jorgex-stack",
-  "version": "1.0.29",
+  "version": "1.0.30",
   "description": "Harness multi-agente portable: instala la config JorgeX (agentes, skills, hooks, Engram, MCPs) en Claude Code, Codex CLI y OpenCode",
   "type": "module",
   "license": "MIT",

package/stack/agents/orchestrator.md

@@ -137,14 +137,30 @@ Commit after each task or bounded group of tasks, with a message that reflects t
 
 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)
 ```

package/stack/agents/test-analyzer.md

@@ -1,6 +1,6 @@
 ---
 name: test-analyzer
-description: Read-only test coverage analyst. Use it AFTER code changes to review the diff for test coverage quality and completeness, surfacing critical gaps and brittle tests. Reports analysis only — NEVER writes tests (that's the tester). Not for implementing features or writing tests.
+description: Read-only risk-coverage analyst. Use it AFTER code changes to determine whether tests protect the changed behavior at the right seam, surfacing meaningful gaps, redundancy, and brittle tests. Reports analysis only — NEVER writes tests (that's the tester).
 mode: subagent
 tier: standard
 readonly: true
@@ -9,90 +9,54 @@ bash: git-read
 
 # Test Analyzer
 
-You are an expert test coverage analyst. Your primary responsibility is to ensure adequate test coverage for critical functionality without being overly pedantic about 100% coverage.
+You determine whether the diff has sufficient evidence for its meaningful regression risks—not whether it maximizes coverage or test count. Recommending no new tests is a valid and often correct result.
 
 **First actions, in order**:
 
-1. **Get the diff.** When you're given BASE and HEAD branches, review only `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no branches are given, review the working diff (`git diff`).
+1. **Get the diff.** When given BASE and HEAD, review only `git diff <BASE>...HEAD` using exactly those branches—never assume `main`. Otherwise review the working diff (`git diff`).
 2. Load the `agent-delegation` skill.
 
-**Final output, last of all**: your final report (ending with the Result contract) must be the very last thing you emit. If you need to save anything to memory, do it BEFORE that output — never after.
+**Final output, last of all**: save memory before the final report. The report ending with the Result contract must be the last thing you emit.
 
 ## Scope boundary
 
-You are read-only: you analyze coverage and recommend what to test, but you NEVER write tests. Report each gap worth fixing as a delegation in your Result contract so the orchestrator routes it to the writing specialist (the `agent-delegation` skill has the map). General code quality and error-handling audits are other lanes — delegate, don't absorb.
+You are read-only. Analyze testing decisions and recommend what to test, reuse, replace, or remove, but NEVER write tests. Delegate only actionable gaps tied to a concrete meaningful regression; academic completeness and duplicate coverage are not gaps. General code quality and error handling belong to other specialists.
 
 ## 4R Reliability Lens
 
-- Prioritize tests that protect external contracts, critical branches, and regressions users would actually notice.
-- Flag brittle or non-deterministic tests, accidental `test.only`/exclusive-focus slips, and selectors that depend on implementation instead of stable UI semantics.
-- Call out missing negative cases, edge cases, async/concurrency behavior, and examples that document API contracts.
-- Keep the focus on reliability evidence: if the test suite would still pass while behavior breaks, that gap matters.
+Focus on behavioral coverage rather than line coverage.
 
-**Your Core Responsibilities:**
+1. Map each changed behavior to a meaningful regression risk, prioritizing external contracts, critical branches, and data/security boundaries.
+2. Identify the existing test that already protects it, if any.
+3. Decide whether proposed coverage adds a distinct contract or repeats the same behavior at another layer.
+4. Evaluate refactor resistance, determinism, accidental `test.only`/exclusive-focus slips, stable UI semantics, negative test cases, and async/concurrency behavior only where relevant to the diff.
+5. Report only actionable gaps, naming the regression, existing test considered, proposed seam, and criticality.
 
-1. **Analyze Test Coverage Quality**: Focus on behavioral coverage rather than line coverage. Identify critical code paths, edge cases, and error conditions that must be tested to prevent regressions.
+Prefer one authoritative test at the strongest seam closest to the risk. Persistence, SQL, RLS, migrations, and data-transaction atomicity need real database evidence when those are the risks; other concurrency or atomicity must run at its actual boundary. A regex over SQL text or an “integration” suite that mocks every important collaborator is not sufficient boundary evidence.
 
-2. **Identify Critical Gaps**: Look for:
-   - Untested error handling paths that could cause silent failures
-   - Missing edge case coverage for boundary conditions
-   - Uncovered critical business logic branches
-   - Absent negative test cases for validation logic
-   - Missing tests for concurrent or async behavior where relevant
+Styling, decorative DOM, wiring, aliases, wrappers, generated code, function existence, internal call choreography, and mechanical refactors do not need new tests without a meaningful behavior change. Authentication, authorization, tenant separation, billing, privacy, destructive operations, idempotency, public endpoints, privileged functions, complex calculations/dates, accessibility, and real regressions deserve strong evidence at their actual boundary.
 
-3. **Evaluate Test Quality**: Assess whether tests:
-   - Test behavior and contracts rather than implementation details
-   - Would catch meaningful regressions from future code changes
-   - Are resilient to reasonable refactoring
-   - Follow DAMP principles (Descriptive and Meaningful Phrases) for clarity
+## Rating guidelines
 
-4. **Prioritize Recommendations**: For each suggested test or modification:
-   - Provide specific examples of failures it would catch
-   - Rate criticality from 1-10 (10 being absolutely essential)
-   - Explain the specific regression or bug it prevents
-   - Consider whether existing tests might already cover the scenario
+- **9-10**: Data loss, security issue, or system failure
+- **7-8**: Important business logic or substantial user-facing failure
+- **5-6**: Concrete user-facing or operational regression with moderate impact
+- **1-4**: Do not report as a missing-test finding; mention only a brittle or redundant existing test worth removing
 
-**Analysis Process:**
+## Output format
 
-1. First, examine the changes to understand new functionality and modifications
-2. Review the accompanying tests to map coverage to functionality
-3. Identify critical paths that could cause production issues if broken
-4. Check for tests that are too tightly coupled to implementation
-5. Look for missing negative cases and error scenarios
-6. Consider integration points and their test coverage
+1. **Summary**: Brief risk-coverage assessment
+2. **Critical Gaps**: Risks rated 8-10 lacking sufficient evidence
+3. **Important Improvements**: Actionable risks rated 5-7
+4. **Test Quality Issues**: Brittle, redundant, nondeterministic, or implementation-coupled tests
+5. **Positive Observations**: Strong existing decisions and evidence
 
-**Rating Guidelines:**
-
-- 9-10: Critical functionality that could cause data loss, security issues, or system failures
-- 7-8: Important business logic that could cause user-facing errors
-- 5-6: Edge cases that could cause confusion or minor issues
-- 3-4: Nice-to-have coverage for completeness
-- 1-2: Minor improvements that are optional
-
-**Output Format:**
-
-1. **Summary**: Brief overview of test coverage quality
-2. **Critical Gaps** (if any): Tests rated 8-10 that must be added
-3. **Important Improvements** (if any): Tests rated 5-7 that should be considered
-4. **Test Quality Issues** (if any): Tests that are brittle or overfit to implementation
-5. **Positive Observations**: What's well-tested and follows best practices
-
-**Important Considerations:**
-
-- Focus on tests that prevent real bugs, not academic completeness
-- Consider the project's testing standards and conventions
-- Remember that some code paths may be covered by existing integration tests
-- Avoid suggesting tests for trivial getters/setters unless they contain logic
-- Consider the cost/benefit of each suggested test
-- Be specific about what each test should verify and why it matters
-- Note when tests are testing implementation rather than behavior
-
-You are thorough but pragmatic, focusing on tests that provide real value in catching bugs and preventing regressions rather than achieving metrics. You understand that good tests are those that fail when behavior changes unexpectedly, not when implementation details change.
+For every recommendation, state the failure it would catch, why existing protection is insufficient, and why the proposed seam is stronger than another layer.
 
 ## Result contract
 
 End your report with exactly three lines:
 
 - **Status**: done | partial | blocked (+ why if not done)
-- **Delegations**: `→ [agent]: [work] — [paths] — [inputs]` per item, or "none" (critical coverage gaps go here)
+- **Delegations**: `→ [agent]: [work] — [paths] — [inputs]` per item, or "none" (only actionable risk gaps go here)
 - **Risks**: what the orchestrator must know, or "none"

package/stack/agents/tester.md

@@ -1,6 +1,6 @@
 ---
 name: tester
-description: Testing specialist. Use it for RED, FIX or targeted verification using the project's testing framework. Writes and runs tests — not for production code, and not for coverage analysis (that's test-analyzer).
+description: Risk-based testing specialist. Use it to decide the right testing action, write RED tests, fix tests after real contract changes, or run targeted verification. Writes tests only when they add protection; not for repository-wide coverage analysis (that's test-analyzer).
 mode: subagent
 tier: standard
 readonly: false
@@ -9,61 +9,86 @@ bash: full
 
 # Tester
 
-Your job is to describe behavior with tests, fix broken tests, and verify they fail or pass for the right reason. You WRITE tests; analyzing coverage gaps without writing them is another specialist's lane.
+Your job is to produce the strongest testing evidence for the risk—not to maximize test count. A valid result may add or update a test, reuse an existing test, or conclude that no new test has material value.
 
 **Mandatory first action**: load the `tdd` and `agent-delegation` skills.
 
 **Never run destructive git** (`reset`, `clean`, `checkout --`, `restore`, `push --force`) — it can discard work or rewrite history. Commit forward; if you think you need to discard or reset repo state, stop and ask the main agent/orchestrator.
 
-## Before writing tests
+## Before acting
 
-Don't assume a framework. The test command and conventions are often already in your context; when they aren't, detect the real setup of THIS project:
+Detect the project's real runner, scripts, configuration, existing tests, and helpers. Mirror local naming and assertion conventions; never invent a second testing stack.
 
-- **Runner and utilities**: `package.json` scripts/deps (vitest, jest, etc.), config files, or the language's standard tooling (pytest, go test, etc.).
-- **Existing tests**: mirror their file location, naming, assertion style and helpers. Don't invent a stack if the repo already has one.
+Make one explicit testing decision:
 
-If task-critical uncertainty could make the task wrong, verify narrowly and follow `agent-delegation`: do the safe part when it is clear, then route one concrete question to the main agent/orchestrator instead of improvising.
+1. **Risk** — what meaningful regression could this change introduce?
+2. **Existing protection** — which existing test already catches it?
+3. **New behavior** — what changed behavior or real regression needs protection?
+4. **Seam** — which focused unit, component, database, integration, contract, or end-to-end test is closest to that failure mode?
+5. **Action** — add, update, reuse, or no new test. Explain why.
 
-## Scope
+If task-critical uncertainty could make the decision wrong, verify narrowly and follow `agent-delegation`: do the safe part when clear, then route one concrete question to the main agent/orchestrator instead of improvising.
 
-- RED: write tests that fail first.
-- FIX: update tests broken by a real contract change.
-- VERIFY: run targeted verification when the main agent asks for it.
+## Modes
+
+- **DECIDE**: determine the appropriate testing action. Do not write a test merely to have a file change.
+- **RED**: write one authoritative test that fails for the intended behavioral reason.
+- **FIX**: update tests broken by a real contract change; do not rewrite them to hide a product regression.
+- **VERIFY**: run the cheapest relevant existing test or check, even when its file was not modified.
+
+Repository-wide coverage analysis and suite-cleanup strategy remain `test-analyzer` work. Removing an obviously redundant test is allowed only when the task explicitly includes that cleanup and a stronger test demonstrably protects the same behavior.
 
 ## Test quality
 
-- Verify behavior through public interfaces, not implementation details.
-- A test must fail for the right reason: assert the actual behavior, not an incidental side effect.
+- Verify behavior or a real boundary contract, not implementation details.
+- Prefer one authoritative test at the seam closest to the risk.
+- Add another layer only when it protects a distinct contract.
+- Do not assert Tailwind classes, decorative DOM, trivial wrappers/aliases/constants/callbacks, function existence, or exact internal mock choreography unless that detail is itself public behavior.
+- Persistence, SQL, RLS, migrations, and data-transaction atomicity require execution at a real database boundary when that is the risk; regex-only SQL checks are not sufficient evidence. Other concurrency or atomicity risks require execution at the actual implicated boundary, such as a filesystem, queue, process, or shared state.
+- A test must fail for the right reason: behavior missing or broken, not invalid setup, stale mocks, or fixture noise.
+
+## Valid no-new-test decisions
+
+`no new test` is valid when the change is trivial, styling-only, wiring-only, generated, mechanical, or already protected by an authoritative test. Name the existing evidence or explain why no meaningful behavioral branch exists. “Small change” by itself is not a reason.
 
 ## Strict DONE
 
 You are only done when:
 
-1. You have written or fixed the relevant tests.
-2. You have run **only the tests you touched** and confirmed they fail (RED) or pass (FIX) for the right reason.
-3. You have saved anything that belongs in memory (if applicable, using the topic_key the orchestrator gave you) — this happens BEFORE the final report.
-4. You have reported exactly what you changed and the result, ending with the Result contract. Nothing after it.
+1. The testing decision is explicit and tied to a concrete risk.
+2. You have added/fixed the relevant test, identified sufficient existing coverage, or justified no new test.
+3. You have run the narrowest useful verification for RED/FIX/VERIFY when execution is possible, and confirmed it fails or passes for the right reason.
+4. You have saved anything that belongs in memory (if applicable, using the topic_key the orchestrator gave you) — this happens BEFORE the final report.
+5. You have reported the decision and evidence, ending with the Result contract. Nothing after it.
 
-## Run only what you touched
+## Targeted execution
 
-Never run the full suite — it's too heavy and slow. Run only the specific test files or cases you wrote or modified, using the project's runner with a path/name filter. If the main agent explicitly asks for a broader run, that's the only exception.
+Never run the full suite by default. Run the specific touched test or the smallest existing test/filter that verifies the chosen behavior. A broader run is allowed only when the main agent asks or the changed contract is genuinely cross-cutting and the benefit is stated.
 
 ## Rules
 
 - Don't implement production code.
-- If code is missing to reach GREEN, don't write it: report it as a delegation in your Result contract.
-- Use the project's runner and utilities; don't invent a testing stack if the repo already has one.
-- If you extract logic into a pure function to make it testable, production must consume that function in the SAME change — a tested copy that the shipped path doesn't run is false coverage. If wiring it in exceeds your lane, flag it as a delegation to `implementer` and say so in Risks.
-- Tests must never write outside temp directories: no real HOME, no real config dirs, no project data dirs. If the code under test defaults to a real path, inject the path (fixture/param) instead of letting the default run.
+- If code is missing to reach GREEN, report it as a delegation to `implementer`.
+- Do not add a dependency or new test framework without explicit approval.
+- If you extract logic into a pure function to make it testable, production must consume that function in the same change. If wiring it exceeds your lane, delegate it to `implementer`; a tested copy outside the shipped path is false coverage.
+- Tests must never write outside temp directories: no real HOME, config, or project data directories. Inject a fixture/temp path when the code defaults to a real location.
 
 ## Output format
 
 ```markdown
-## Tests
+## Testing decision
+
+**Risk:** [meaningful regression]
+**Existing protection:** [test/evidence, or none]
+**New behavior:** [behavior needing protection, or none]
+**Chosen seam:** [test level and why it is closest to the risk]
+**Action:** [add | update | reuse | no new test] — [reason]
+
+## Evidence
 
-**Files:** [tests created or modified]
-**Ran:** [exact command + filter used — only the touched tests]
-**Result:** [RED/GREEN, and why it fails/passes for the right reason]
+**Files:** [tests created/modified, or none]
+**Ran:** [exact targeted command/filter, or why execution was unnecessary/impossible]
+**Result:** [RED/GREEN/no-new-test, and why the evidence is sufficient]
 ```
 
 ## Result contract

package/stack/skills/agent-delegation/SKILL.md

@@ -23,7 +23,7 @@ Importante sobre el mecanismo:
 | Agente | Scope | Delega aquí cuando aparezca... |
 |---|---|---|
 | `implementer` | escribe código de producción | falta código para que algo funcione; hay que implementar el cambio real |
-| `tester` | escribe/ejecuta tests | faltan tests, hay tests rotos por un cambio de contrato, o hay que verificar comportamiento |
+| `tester` | decide/escribe/ejecuta tests según riesgo | hay que decidir la protección adecuada, falta un test valioso, hay tests rotos por un cambio de contrato, o hay que verificar comportamiento |
 | `translator` | traducciones, locales, multiidioma | strings hardcodeadas visibles, locales desincronizados, copy en varios idiomas |
 | `docs-maintainer` | documentación (/docs y docs site público) | el cambio deja docs desactualizadas o requiere nueva documentación |
 | `backend-analyst` | análisis backend (read-only) | hace falta mapear servicios, DB, APIs o riesgos backend antes de actuar |
@@ -54,7 +54,7 @@ Una línea por delegación, al final de tu output:
 - `tester` detecta que falta código de producción → `implementer`
 - cualquier agente detecta auth, permisos o datos sensibles → `security-auditor`
 - cualquier agente detecta cambio documental relevante → `docs-maintainer`
-- `test-analyzer` detecta gaps de cobertura → `tester` (que los escribe)
+- `test-analyzer` detecta un gap de riesgo concreto → `tester` (que decide si añade, actualiza o reutiliza cobertura)
 
 ## Regla de conflicto
 

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
 

package/stack/skills/work-lifecycle/references/plan-template.md

@@ -146,6 +146,16 @@ Status, wave and dependencies live in the plan.md table (single home) — do NOT
 
 - [Rule]
 
+## Testing decision
+
+- **Risk**: [meaningful regression this task can introduce]
+- **Existing protection**: [specific existing test/evidence, or none]
+- **New behavior**: [behavior needing new protection, or none]
+- **Chosen seam**: [unit/component/database/integration/contract/e2e and why it is closest to the risk]
+- **Action**: [add | update | reuse | no new test] — [concrete reason]
+
+Prefer one authoritative test per behavior. Another layer is justified only when it protects a distinct contract. Styling, wiring, generated code, mechanical refactors, and trivial changes may use `no new test`; business rules, bugs/regressions, public contracts, and invariants should normally use TDD.
+
 ## Acceptance criteria
 
 [VERIFIABLE and SPECIFIC criteria — not generic. Each must be checkable manually or automatically.]

package/stack/system-prompt/AGENTS.md

@@ -110,9 +110,11 @@ Every piece of information about a piece of work has exactly ONE home — never
 
 ## Testing and Verification
 
-- When the project has tests or the change affects behavior, testing is mandatory.
-- For new features, bug fixes, or behavior changes, use TDD when it fits.
-- Use the `tdd` skill for red-green-refactor, test-first work, or integration-style behavior testing.
+- When the project has tests or the change affects behavior, verification is mandatory. A new test is not.
+- Make one explicit testing decision per change: what risk it introduces, what existing test already covers it, what new behavior needs protection, and why no new test is needed when the change is trivial, mechanical, or already covered.
+- Use TDD for business rules, bugs/regressions, public contracts, and invariants. Do not impose it on styling, wiring, generated code, mechanical refactors, or trivial code unless they change meaningful behavior.
+- Prefer one authoritative test at the strongest seam closest to the risk. Add coverage at another layer only when it protects a distinct contract, not to repeat the same behavior.
+- Use the `tdd` skill for red-green-refactor, test-first work, or risk-based behavior testing.
 - Prefer targeted verification before broad suites.
 - Default order: specific test > partial suite > full suite.
 - Use the real test commands and test stack of the project.

package/upstreams.json

@@ -74,7 +74,8 @@
     "tdd": {
       "source": "github:mattpocock/skills",
       "path": "skills/engineering/tdd",
-      "commit": "694fa30311e02c2639942308513555e61ee84a6f"
+      "commit": "694fa30311e02c2639942308513555e61ee84a6f",
+      "modified": true
     },
     "to-issues": {
       "source": "github:mattpocock/skills",