jorgex-stack 1.0.28 → 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/dist/cli.js

@@ -591,9 +591,34 @@ ${agent.body}`,
     }
     const hooksFile = path7.join(ctx.configDir, "hooks.json");
     const content = upsertJson(readTextIfExists(hooksFile), (root) => {
-      const after = root["tool.execute.after"] ??= {};
-      const bash = after["bash"] ??= {};
+      const afterValue = root["tool.execute.after"] ??= {};
+      if (afterValue === null || typeof afterValue !== "object" || Array.isArray(afterValue)) {
+        ctx.warnings.push("opencode: tool.execute.after no es un objeto; hooks gestionados omitidos.");
+        return;
+      }
+      const after = afterValue;
+      const bashValue = after["bash"];
+      if (bashValue !== void 0 && !Array.isArray(bashValue) && (bashValue === null || typeof bashValue !== "object")) {
+        ctx.warnings.push("opencode: tool.execute.after.bash no es un array ni un mapa; hooks gestionados omitidos.");
+        return;
+      }
+      const bash = Array.isArray(bashValue) ? { "*": bashValue } : bashValue ?? {};
+      after["bash"] = bash;
+      const managedScripts = new Set(Object.values(bashEntries).flat());
+      for (const [includes, scripts] of Object.entries(bash)) {
+        if (!Array.isArray(scripts)) continue;
+        const preserved = scripts.filter(
+          (script) => typeof script !== "string" || !managedScripts.has(script)
+        );
+        if (preserved.length > 0) bash[includes] = preserved;
+        else delete bash[includes];
+      }
       for (const [includes, scripts] of Object.entries(bashEntries)) {
+        const current = bash[includes];
+        if (current !== void 0 && !Array.isArray(current)) {
+          ctx.warnings.push(`opencode: trigger bash '${includes}' no es un array; hook gestionado omitido.`);
+          continue;
+        }
         const list = bash[includes] ??= [];
         for (const s of scripts) if (!list.includes(s)) list.push(s);
       }
@@ -2084,7 +2109,7 @@ async function downloadRepoTarball(repo, sha, destDir, validateSubdir) {
 import fs18 from "fs";
 import path23 from "path";
 import { execFileSync as execFileSync3 } from "child_process";
-var PROTECTED_SKILLS = /* @__PURE__ */ new Set(["agent-delegation", "work-lifecycle"]);
+var PROTECTED_SKILLS = /* @__PURE__ */ new Set(["agent-delegation", "work-lifecycle", "xreview"]);
 function sameTextContentNormalized(a, b) {
   const ba = fs18.readFileSync(a);
   const bb = fs18.readFileSync(b);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jorgex-stack",
-  "version": "1.0.28",
+  "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

@@ -19,7 +19,7 @@ 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 and the PR creation. 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.
+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
 
@@ -127,18 +127,40 @@ Every delegation prompt must state the worktree path as the ONLY allowed write r
 
 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)
 ```
@@ -160,16 +182,17 @@ Each writer verifies its own bounded area (e.g. its test file). The orchestrator
 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 run `/xreview` or a generic multi-agent panel during EXECUTE.
+- 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 PR creation are not early-review triggers. PR creation has its own single review boundary in SHIP.
+- 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.
 
@@ -177,18 +200,20 @@ An early review during EXECUTE is an **exception**, not a default phase. Use it
 
 When the plan is fully applied and VERIFY passes:
 
-1. Push the work branch (commits already exist per task from EXECUTE) and create the PR (`gh pr create`) against its real base — no permission needed for either. This is the one multi-agent review per PR: the post-PR hook fires it automatically, so let it run and wait for the unified report. If the hook does NOT fire (no review instruction arrives after the PR is created), launch `/xreview` yourself against the PR's base with the same scope; never run both.
-2. Process the report by its three levels:
+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 to the PR branch.
-5. The review fires once per PR creation — pushing fixes does not re-trigger it. Re-run `/xreview` 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.
+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: report what shipped, 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).
+- 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.
 

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/commands/claude-code/xreview.md

@@ -0,0 +1,5 @@
+---
+description: Run the portable xreview skill against a branch, PR, working diff, or explicit path scope
+---
+
+Load the `xreview` skill and run its complete review flow for this target: {{input}}

package/stack/commands/opencode/xreview.md

@@ -0,0 +1,5 @@
+---
+description: Run the portable xreview skill against a branch, PR, working diff, or explicit path scope
+---
+
+Load the `xreview` skill and run its complete review flow for this target: {{input}}

package/stack/hooks/hooks.json

@@ -4,7 +4,7 @@
     "PostToolUse": [
       {
         "matcher": "Bash|PowerShell",
-        "x-command-includes": "gh pr create",
+        "x-command-includes": "gh",
         "hooks": [
           {
             "type": "command",