jorgex-stack 1.0.27 → 1.0.29

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.27",
+  "version": "1.0.29",
   "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
 
@@ -48,12 +48,10 @@ Once a task crosses any of these thresholds, delegating stops being optional:
 | Trigger | Expected behavior |
 | --- | --- |
 | Reading 4+ files just to understand a flow | Delegate exploration to the matching analyst. |
-| Touching 2+ non-trivial files | One writer (`implementer`) per scope; fresh `code-reviewer` pass before closing. |
-| Commit, push or PR after code changes | Run `code-reviewer` on the diff unless it is trivial docs/text. |
 | Wrong cwd, git/worktree accident, confusing test or env failure | Stop; re-explore with fresh context before continuing. |
 | Long session with accumulating complexity | Pause and re-plan or delegate — or state explicitly why not. |
 
-The goal is not ceremony: it is one responsible coordinator, one writer per scope, and fresh eyes before anything ships.
+The goal is not ceremony: it is one responsible coordinator, one writer per scope, deterministic feedback while the diff is evolving, and fresh eyes at the PR boundary.
 
 ## 3. SPEC
 
@@ -109,6 +107,7 @@ Load the `agent-delegation` skill: it defines the available subagents, the scope
 Every subagent ends with a **Result contract** (Status / Delegations / Risks). Process it:
 
 - For each `→ [agent]: ...` line, launch the corresponding specialist.
+- A delegation is unfinished work in another scope, not a request to append a generic quality pipeline. Normal handoffs between `implementer` and `tester` do not by themselves justify reviewers or analyzers.
 - If a subagent reports `partial`, keep the safe work and relaunch only what still needs guidance.
 - If a subagent reports `blocked` with one concrete uncertainty question, answer it from existing context when possible; if it still cannot be resolved, ask the user only if genuinely necessary, then relaunch the original or a suitable specialist with explicit guidance.
 - Don't declare a phase done while a delegation line remains unprocessed.
@@ -128,6 +127,12 @@ 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.
@@ -152,15 +157,26 @@ implementer (direct change)
 
 ### Verification cadence
 
-Verify by bounded, coherent sections (e.g. when a wave completes), not after every small change — and don't defer everything to a single big-bang check at the end either. Launch a verification subagent only when its trigger area actually changed in that section.
+Deterministic checks are the routine feedback loop while implementation is in progress: run the relevant tests, lint and typecheck/build checks at the cheapest seam that can catch the section's regressions. Verify by bounded, coherent sections (e.g. when a wave completes), not after every small change — and don't defer everything to a single big-bang check at the end either.
+
+Each writer verifies its own bounded area (e.g. its test file). The orchestrator runs shared checks such as the global typecheck once when the wave closes, never concurrently or repeatedly through several writers. Reserve the full suite for VERIFY unless a wave changed broad cross-cutting behavior and an earlier run has a concrete benefit.
+
+### Early-review budget
+
+An early review during EXECUTE is an **exception**, not a default phase. Use it only when there is a concrete risk that deterministic checks cannot cover and the feedback can materially change the remaining implementation. Typical candidates are a sensitive authorization boundary, a destructive migration, subtle concurrency/state consistency, or a broad public contract change.
 
-In parallel waves, each writer's minimum verification is its own bounded area (e.g. its test file) PLUS the project's global typecheck when one exists — typecheck is cheap, global, and catches cross-file breakage that per-area runs miss. The full suite runs once per wave, by the orchestrator, when the wave closes — never concurrently by several writers.
+- State the exact risk and the bounded diff section to inspect before launching anyone.
+- Use the single most relevant specialist. Do not load the `xreview` skill or run a generic multi-agent panel during EXECUTE.
+- Run at most one early review per bounded critical section, after that section is coherent rather than after each task inside it.
+- Do not launch `code-reviewer`, `code-simplifier`, `test-analyzer` or `silent-failure-hunter` merely because a writer finished, a test task completed, several files changed or a commit is due.
+- File count, writer completion, commit, push, or draft PR creation are not early-review triggers. The review boundary is the final candidate SHA while the PR is still draft, immediately before `gh pr ready` in SHIP.
 
 ## 6. VERIFY
 
 - Validate against the plan's **Success criteria** in plan.md and tick the ones that pass. Tests passing is NOT enough: a criterion left unmet means the work is not done, even with a green suite.
 - Run the minimum verification that is sufficient.
 - Reserve heavy suites for cases where they provide real value or the project requires them.
+- Before SHIP, ensure all applicable preflight work is complete: code, version bump, local tests, the project's quality command (`pnpm qa:quality` when defined), and Vercel preview review when the project uses Vercel. React Doctor is manual/local, never assumed to be a GitHub Actions gate.
 - If something fails, go back to EXECUTE with fix tasks.
 - **Anti-thrashing**: max 3 attempts per failing task or criterion. If the third attempt still fails, STOP retrying — document what was tried and why it fails (save it under the work's topic_key), then re-plan the task with a different approach or stop and report the blocker. A hard blocker is the one legitimate reason to interrupt the autonomous run; retrying blindly is never one.
 
@@ -168,18 +184,20 @@ In parallel waves, each writer's minimum verification is its own bounded area (e
 
 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. The post-PR hook fires the conditional multi-agent review automatically — let it run and wait for the unified report. If the hook does NOT fire (no review instruction arrives after the PR is created), don't skip the review: launch `/xreview` yourself against the PR's base, with the same scope the hook would have used.
-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 were large.
+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/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",

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/work-lifecycle/SKILL.md

@@ -41,6 +41,18 @@ Every piece of work gets a **canonical kebab-case name** when it starts (e.g. `c
 - Task status lives ONLY in the task table: flip it (⬜ → ✅) with a surgical edit when the task closes. PR status/evidence lives ONLY in the PR roadmap table. Do not mirror task progress into memory, and do not re-read the whole plan after every task — it is already in context; re-read it on resume.
 - For multi-PR work, resume from the first PR/task not done in the roadmap/table. For single-PR work, the canonical name worktree/branch is enough and the roadmap collapses to one checkpoint.
 
+## Pull request lifecycle
+
+1. Start from the updated production branch in the canonical worktree/branch. Keep one concrete objective per PR.
+2. Implement one coherent first slice, commit it, push the work branch, and open the PR immediately as draft with `gh pr create --draft`.
+3. Continue implementation, commits and pushes only while the PR is draft. Draft means the code can still change; ready means the current SHA is the candidate to merge.
+4. Before ready, complete every applicable preflight item: code, version bump, local tests, project quality command (`pnpm qa:quality` when defined), Vercel preview review when the project uses Vercel, final diff inspection, and full PR review.
+5. Mark ready once with `gh pr ready <number>`. If the project has PR checks configured, wait for Quality Gates, run `gh pr checks <number>`, and verify the checks belong to the latest commit. 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.
+6. Never push to a ready PR. If it needs changes, first run `gh pr ready --undo <number>`, then modify and push while draft, repeat preflight and review, mark ready again, and wait for a fresh complete gate when checks are configured.
+7. Merge only after explicit user approval. When PR checks are configured, their passing result must match the current candidate SHA.
+
+Dependent PRs are sequential: merge one checkpoint, update the production branch, then create the next worktree/branch from that updated base. Do not stack a dependent PR from an unmerged work branch unless the human explicitly chooses a stacked-PR strategy.
+
 ## HTML review view (on demand)
 
 When presenting the PRD or the plan for human review on non-trivial work, OFFER a disposable HTML view (e.g. side-by-side approach comparison for the PRD, task table + dependency graph for the plan). Rules:

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

@@ -41,6 +41,8 @@ The full spec of each task is NOT a file: it lives in Engram, one observation pe
 > This is the live PR-level board: scope, PR status, and merge evidence live here.
 > Task-level status stays in the task table below.
 > Full checkpoint history lives in Engram under `work/[name]/pr/[NN]`.
+> PR status advances: ⬜ Pending → 📝 Draft → 🔍 Reviewed → ⏳ Ready / gates when configured → ✅ Merged.
+> If a ready PR changes, return it to Draft with `gh pr ready --undo`, clear stale gate evidence, and repeat review plus configured gates for the new SHA. If no PR checks are configured, confirm that from project configuration and record their absence instead of blocking 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.
 
 | PR | Scope | Branch | Worktree | Base | Status | Merge evidence |
 |----|-------|--------|----------|------|--------|----------------|

package/stack/{commands/xreview.md → skills/xreview/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+name: xreview
 description: Conditional multi-agent code review — determines what to review (asking if unclear), resolves the exact diff, and launches only the relevant subagents in parallel
 ---
 
@@ -6,7 +7,7 @@ Run a comprehensive multi-agent review. Your job as the main agent: determine WH
 
 ## 0. Determine the review target
 
-User input (may be empty): {{input}}
+Review target (may be empty): use the invocation context or the explicit target supplied by the caller.
 
 - If the input names a branch → review `git diff <that-branch>...HEAD`.
 - If the input references a PR (number or URL) → use that PR's base branch as BASE.
@@ -51,19 +52,19 @@ If the diff adds or changes comments/docstrings, run `comment-fixer` ALONE befor
 
 ## 4. Launch the remaining subagents in PARALLEL
 
-All subagents are CONDITIONAL: launch one only when the changed files indicate it applies. Run them in PARALLEL via the Task tool. Each subagent fetches its OWN diff; all are read-only. Pass every one EXACTLY:
+All subagents are CONDITIONAL: launch one only when the changed files indicate it applies. Run them in PARALLEL via the delegation mechanism available in the current runtime. Each subagent fetches its OWN diff; all are read-only. Pass every one EXACTLY:
 
 - the review scope: BASE and HEAD branches (verbatim), or "working diff" for uncommitted work
 - the instruction: review only that scope — never assume `main`, use the scope given
 
 Subagents and their triggers:
 
-1. Task(subagent_type='test-analyzer') — only if the diff touches tests or code that should be tested
-2. Task(subagent_type='silent-failure-hunter') — only if the diff includes error handling, try/catch, fallbacks, or async flows
-3. Task(subagent_type='type-design-analyzer') — only if the diff changes types, interfaces, schemas, or public contracts
-4. Task(subagent_type='code-reviewer') — for general code quality whenever non-trivial source code changed
-5. Task(subagent_type='code-simplifier') — only if the diff introduces complexity worth simplifying; this is the lean/anti-bloat pass for diffs and PRs
-6. Task(subagent_type='security-auditor') — only if the diff touches auth, authorization, permissions, secrets/credentials, sensitive data, input validation, webhooks, or other security-critical flows
+1. `test-analyzer` — only if the diff touches tests or code that should be tested
+2. `silent-failure-hunter` — only if the diff includes error handling, try/catch, fallbacks, or async flows
+3. `type-design-analyzer` — only if the diff changes types, interfaces, schemas, or public contracts
+4. `code-reviewer` — for general code quality whenever non-trivial source code changed
+5. `code-simplifier` — only if the diff introduces complexity worth simplifying; this is the lean/anti-bloat pass for diffs and PRs
+6. `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 and note that it was skipped. Always state which subagents ran and which were skipped and why.
 

package/stack/system-prompt/AGENTS.md

@@ -125,7 +125,12 @@ Every piece of information about a piece of work has exactly ONE home — never
 - Commit per task or per bounded group of tasks — small, separate commits whose history maps to the work; never everything in one giant commit.
 - Never push code or behavior changes directly to production branches (main/master or the repo's protected/release branches): those always go through a work branch + PR. Pushing a work branch or a worktree branch is fine without asking.
 - Exception: TRIVIAL changes — docs, typos, content removal, config text with no behavior or code-logic impact — may be committed and pushed directly to the production branch. When in doubt about whether a change is trivial, it is not: use a PR.
-- Creating a pull request is fine without asking.
+- Start each non-trivial PR from an updated production branch in its canonical worktree/branch, and keep one concrete objective per PR. Dependent PRs are sequential: merge the first, update the production branch, then create the next branch from it.
+- After the first coherent commit, push the work branch and always open the PR as draft with `gh pr create --draft`. Creating and pushing the work branch and draft PR is fine without asking.
+- Keep the PR in draft while its code can still change. All subsequent commits and pushes happen while draft; never push to a ready PR.
+- Before ready, complete all applicable preflight work: code, version bump, local tests, the project's quality command (`pnpm qa:quality` when defined), Vercel preview review when the project uses Vercel, final diff inspection, and the full PR review. React Doctor is manual/local, not a GitHub Actions gate.
+- Mark the PR ready only once the current SHA is the candidate to merge: `gh pr ready <number>`. If the project has PR checks configured, wait for Quality Gates, run `gh pr checks <number>`, and verify the checks belong to the latest commit before reporting it mergeable. 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.
+- If a ready PR needs any code or behavior change, first run `gh pr ready --undo <number>`, then modify and push while draft, repeat the full local verification and review, mark ready again, and wait for a fresh complete gate when PR checks are configured. Never push to a ready PR and merge without repeating the applicable cycle.
 - Merging a PR ALWAYS requires an explicit user request — no exceptions, in any flow.
 - Before commit or push, review `git status`, `git diff`, and `git log --oneline -10`.
 - Never add AI signatures, `Co-Authored-By`, or agent mentions.