jorgex-stack 1.0.28 → 1.0.30

package/stack/scripts/post-pr-review.cjs

@@ -1,158 +1,141 @@
 #!/usr/bin/env node
 /**
- * Global PostToolUse hook: gh pr create
+ * Global PostToolUse guardrail for the PR draft → ready lifecycle.
  *
- * Injects a conditional multi-agent review request after a PR is created.
- * Generic and project-agnostic: no version bump, no React Doctor, no project paths.
+ * The historical filename is intentionally preserved so sync can migrate the
+ * existing hook entry instead of leaving an orphan in user configuration.
+ * The hook never infers success or PR state from command text: PostToolUse
+ * payloads are not consistent enough across runtimes to prove either.
  *
- * The review subagents are CONDITIONAL — only the ones relevant to the diff run.
- * Mirrors the `/xreview` command logic so both stay aligned: comment-fixer first
- * (committed before the analysts), then the read-only analysts in parallel. 4R
- * stays internal (Reliability / Resilience / Readability / Risk), not a separate
- * report section, taxonomy, or extra agents.
- *
- * Payload compatibility (stdin JSON), so the same script works on every runtime:
+ * Payload compatibility (stdin JSON):
  * - Claude Code hooks: { tool_name: "Bash", tool_input: { command: "..." }, cwd }
  * - Codex hooks:       { tool_name: "shell", tool_input: { command: [...] }, cwd }
  * - OpenCode bridge:   { tool: "bash", args: { command: "..." }, directory }
  *
- * Output (single channel per runtime, so the bridge never duplicates it):
- * - OpenCode bridge payload → plain message on stderr.
- * - Claude Code / Codex payload → JSON additionalContext on stdout.
- * Exit 0 always.
+ * Output uses one channel per runtime and the script always exits 0.
  */
 
-const { execSync } = require('child_process');
-const path = require('path');
-
-const DEFAULT_BASE_BRANCH = 'main';
-const BASE_BRANCH_SOURCE = Object.freeze({
-  GH: 'gh',
-  ORIGIN_HEAD: 'origin-head',
-  DEFAULT: 'default',
-});
-
 function writeWarning(message) {
   process.stderr.write(`post-pr-review: warning: ${message}\n`);
 }
 
-function formatGitRef(value) {
-  const ref = String(value);
-  return /^[A-Za-z0-9._/-]+$/.test(ref) ? ref : `'${ref.replace(/'/g, "'\\''")}'`;
-}
-
-function resolveBaseBranch(cwd) {
-  try {
-    const base = execSync('gh pr view --json baseRefName --jq .baseRefName', {
-      cwd,
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-      timeout: 8_000,
-    }).trim();
-    if (base) return { branch: base, source: BASE_BRANCH_SOURCE.GH };
-  } catch {
-    // PR not yet discoverable; fall back below.
+function shellCommandSegments(command) {
+  const segments = [];
+  let tokens = [];
+  let token = "";
+  let quote = null;
+  let started = false;
+
+  const pushToken = () => {
+    if (!started) return;
+    tokens.push(token);
+    token = "";
+    started = false;
+  };
+  const pushSegment = () => {
+    pushToken();
+    if (tokens.length > 0) segments.push(tokens);
+    tokens = [];
+  };
+
+  for (const character of command) {
+    if (quote !== null) {
+      if (character === quote) quote = null;
+      else token += character;
+      started = true;
+    } else if (character === '"' || character === "'") {
+      quote = character;
+      started = true;
+    } else if (character === "\r" || character === "\n") {
+      pushSegment();
+    } else if (/\s/.test(character)) {
+      pushToken();
+    } else if (character === ";" || character === "&" || character === "|") {
+      pushSegment();
+    } else {
+      token += character;
+      started = true;
+    }
   }
+  pushSegment();
+  return segments;
+}
 
-  try {
-    const originHead = execSync('git symbolic-ref refs/remotes/origin/HEAD', {
-      cwd,
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-      timeout: 10_000,
-    }).trim();
-    if (originHead) {
-      return {
-        branch: originHead.replace(/^refs\/remotes\/origin\//, ''),
-        source: BASE_BRANCH_SOURCE.ORIGIN_HEAD,
-      };
+function skipRepoOptions(tokens, start) {
+  let index = start;
+  while (index < tokens.length) {
+    const option = tokens[index];
+    if (option === "-R" || option === "--repo") {
+      if (tokens[index + 1] === undefined) return false;
+      index += 2;
+    } else if (/^(?:-R|--repo=).+/i.test(option)) {
+      index += 1;
+    } else {
+      break;
     }
-  } catch {
-    // ignore
   }
+  return index;
+}
+
+function isLifecycleSegment(tokens) {
+  if (!/(?:^|[\\/])gh(?:\.exe)?$/i.test(tokens[0] ?? "")) return false;
+
+  let index = skipRepoOptions(tokens, 1);
+  if (tokens[index]?.toLowerCase() !== "pr") return false;
+  index = skipRepoOptions(tokens, index + 1);
 
-  return { branch: DEFAULT_BASE_BRANCH, source: BASE_BRANCH_SOURCE.DEFAULT };
+  const action = tokens[index]?.toLowerCase();
+  return action === "create" || action === "ready";
 }
 
-let raw = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', (chunk) => (raw += chunk));
-process.stdin.on('end', () => {
+function isPrLifecycleCommand(command) {
+  const segments = Array.isArray(command)
+    ? [command.map(String)]
+    : shellCommandSegments(String(command));
+  return segments.some(isLifecycleSegment);
+}
+
+const message = `<pr-lifecycle-state-required>
+A \`gh pr create\` or \`gh pr ready\` command was attempted. Do not infer success or PR state from the command text. Resolve the current PR and run \`gh pr view --json number,isDraft,headRefOid\` before the next action.
+
+- If the PR should still be under development, it must be draft. If it is ready, run \`gh pr ready --undo <number>\` before any change or push.
+- While draft, finish code, the applicable version bump, local tests, \`pnpm qa:quality\` when defined, Vercel preview review when applicable, final diff inspection, and the full review on the candidate SHA.
+- If the PR is actually ready, do not push. If the project has PR checks configured, wait for the complete Quality Gates, run \`gh pr checks <number>\`, and verify the checked headRefOid is the candidate SHA.
+- If no PR checks are configured, confirm that from project configuration such as workflows, rulesets or integrations, and record it; their absence does not block the merge. An empty \`gh pr checks\` result immediately after ready is not evidence that no checks are configured.
+- Immediately before reporting or merging, compare \`gh pr view --json headRefOid\` with the recorded candidate SHA. Merge still requires explicit user approval.
+</pr-lifecycle-state-required>`;
+
+let raw = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => (raw += chunk));
+process.stdin.on("end", () => {
   let data = {};
   try {
-    data = JSON.parse(raw || '{}');
+    data = JSON.parse(raw || "{}");
   } catch {
-    writeWarning('invalid JSON payload; skipping review hook.');
+    writeWarning("invalid JSON payload; skipping PR lifecycle hook.");
     process.exit(0);
   }
 
-  const toolName = String(data.tool_name || data.tool || '').toLowerCase();
-  const SHELL_TOOLS = ['bash', 'shell', 'local_shell', 'powershell'];
-  const commandValue = data?.tool_input?.command ?? data?.args?.command ?? '';
-  // Codex passes the shell command as an argv array; the rest as a string.
-  const rawToolCommand = Array.isArray(commandValue) ? commandValue.join(' ') : String(commandValue);
-  const toolCommand = rawToolCommand.toLowerCase();
-
-  if (!SHELL_TOOLS.includes(toolName) || !toolCommand.includes('gh pr create')) {
+  const toolName = String(data.tool_name || data.tool || "").toLowerCase();
+  const shellTools = ["bash", "shell", "local_shell", "powershell"];
+  const commandValue = data?.tool_input?.command ?? data?.args?.command ?? "";
+  if (!shellTools.includes(toolName) || !isPrLifecycleCommand(commandValue)) {
     process.exit(0);
   }
 
-  const scriptDir = __dirname;
-  const projectDir = data.cwd || data.directory || path.resolve(scriptDir, '..');
-  const resolution = resolveBaseBranch(projectDir);
-  const baseBranch = resolution.branch;
-  const baseRef = formatGitRef(baseBranch);
-  const diffScope = `git diff ${baseRef}...HEAD`;
-  const isConfirmed = resolution.source === BASE_BRANCH_SOURCE.GH;
-  const baseSummary = isConfirmed
-    ? `BASE (PR target, confirmed via gh pr view): ${baseBranch}`
-    : `BASE (PR target, NOT confirmed — fallback guess): ${baseBranch}. Before anything else, re-resolve it yourself: run \`gh pr view --json baseRefName --jq .baseRefName\` (the PR exists now; this hook may have raced its creation) and use THAT as BASE. Keep ${baseBranch} only if it still fails. Work is often done in sub-branches whose PR does NOT target the default branch — reviewing against the wrong BASE produces a huge, useless diff.`;
-
-  const message = `<post-pr-review-required>
-A PR was just created. Run a conditional multi-agent review BEFORE reporting back to the user.
-
-${baseSummary}
-HEAD: the current branch / worktree (resolve with \`git rev-parse --abbrev-ref HEAD\`).
-
-1. Routing only (lightweight): list changed file NAMES with \`${diffScope} --name-only\` to decide which subagents apply. Do NOT load the full diff into your own context.
-
-   Sanity check: if that list is far larger than the work just done (hundreds of files, unrelated areas), BASE is almost certainly wrong — STOP, re-resolve the PR base with \`gh pr view\`, and only continue when the diff matches the actual work.
-
-2. Comment pass FIRST (conditional): if the diff adds or changes comments/docstrings, run comment-fixer ALONE before the analysts — it edits comments in place (comments only, never code). If it changed anything, comment-fixer itself never commits — YOU commit its fixes to the PR branch BEFORE launching the analysts, staging ONLY the files it touched (never -a/-A: don't sweep unrelated working-tree changes), so the diff they fetch is already clean of comment noise; push them together with whatever the review produces, or on their own if nothing else needs fixing. If the commit can't be made, leave the edits uncommitted and say so in the report. If the diff touches no comments, skip it.
-
-3. The remaining subagents are CONDITIONAL, read-only, and each fetches its OWN diff. Launch in PARALLEL (with your runtime's delegation mechanism) ONLY the relevant ones, passing each EXACTLY the BASE and HEAD branches and the instruction: review only \`${diffScope}\` — never assume \`main\`, use the BASE/HEAD given.
-   - test-analyzer — only if the diff touches tests or code that should be tested
-   - silent-failure-hunter — only if the diff includes error handling, try/catch, fallbacks, or async flows
-   - type-design-analyzer — only if the diff changes types, interfaces, schemas, or public contracts
-   - code-reviewer — for general code quality whenever non-trivial source code changed
-   - code-simplifier — only if the diff introduces complexity worth simplifying; this is the lean/anti-bloat pass for diffs and PRs
-   - security-auditor — only if the diff touches auth, authorization, permissions, secrets/credentials, sensitive data, input validation, webhooks, or other security-critical flows
-
-   If none of a subagent's triggers are present, skip it. Always state which subagents ran and which were skipped and why.
-
- 4. After the relevant subagents complete, synthesize a unified report:
-  Use 4R internally (Reliability / Resilience / Readability / Risk) as a checklist while synthesizing; do not add a separate 4R section or taxonomy to the final report.
-   - BASE and HEAD used
-   - Subagents run vs skipped (with reason)
-   - Critical Issues (must fix)
-   - Important Improvements (should fix)
-   - Suggestions (nice to have)
-   - Changes already applied (comment fixes: committed to the PR branch, or left uncommitted for working-tree reviews)
-   - Positive Findings
-</post-pr-review-required>`;
-
-  // Un solo canal por runtime: el bridge de OpenCode recoge stdout Y stderr,
-  // así que emitir por ambos duplicaría el mensaje.
   const isOpenCodeBridge = data.tool !== undefined && data.tool_name === undefined;
   if (isOpenCodeBridge) {
-    process.stderr.write(message + '\n');
+    process.stderr.write(`${message}\n`);
   } else {
-    // Claude Code / Codex PostToolUse leen additionalContext del stdout JSON.
     process.stdout.write(
-      JSON.stringify({
+      `${JSON.stringify({
         additionalContext: message,
-        hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: message },
-      }) + '\n',
+        hookSpecificOutput: {
+          hookEventName: "PostToolUse",
+          additionalContext: message,
+        },
+      })}\n`,
     );
   }
   process.exit(0);

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.