jorgex-stack 1.0.1 → 1.0.3

package/stack/commands/lean-audit.md

@@ -0,0 +1,59 @@
+---
+description: Manual read-only lean audit — resolves repo/path scope, runs a cheap scope/routing scan, launches code-simplifier always and the relevant analysts conditionally, then reports ranked lean findings.
+---
+
+Run a manual lean audit. Your job as the main agent: determine WHAT to audit, resolve the exact repo/path scope, decide which subagents apply, and launch them in parallel.
+
+## 0. Determine the audit target
+
+User input (may be empty): {{input}}
+
+- If the input names a repo or a path → audit that repo/subtree.
+- If the input is empty or ambiguous: do a quick, cheap situation scan first — current repo root (`git rev-parse --show-toplevel`), current branch (`git rev-parse --abbrev-ref HEAD`), and the most likely changed area from the user's prompt — then ASK the user what to audit before launching anything, offering only the options that actually apply.
+- If the input points to a PR or a diff → stop: `/lean-audit` is not a PR review command; use `/xreview` for diffs and PRs.
+
+## 1. Resolve scope
+
+- Print the chosen repo/path scope and why it was selected.
+- If the input is a path, audit that subtree.
+- If the input is a repo root, audit the repo from that root downward.
+- If you are inside a worktree, use that worktree as the scope unless the user named a different path.
+
+## 2. Cheap scope/routing scan
+
+Before launching subagents, do a quick scan for obvious routing signals in the scope:
+
+- changed file names and top-level directories
+- obvious code/test/docs boundaries
+- areas that likely need code-simplifier vs analyst passes
+- anything that changes which subagents should run
+
+Use the scan to route work, not to judge bloat or rewrite anything. Code-simplifier owns the lean/anti-bloat findings.
+
+## 3. Launch the remaining subagents in PARALLEL
+
+All subagents are CONDITIONAL and read-only. Launch one only when the scope indicates it applies. Pass every one EXACTLY:
+
+- the audit scope: repo root / path root, verbatim
+- the instruction: audit only that scope — never broaden it, and never apply fixes
+
+Subagents and their triggers:
+
+1. Task(subagent_type='code-simplifier') — always; this is the lean/anti-bloat pass
+2. Task(subagent_type='backend-analyst') — if the scope includes backend, DB, APIs, server logic, or data flows
+3. Task(subagent_type='frontend-analyst') — if the scope includes UI, hooks, state, rendering, or client-side flows
+4. Task(subagent_type='type-design-analyzer') — if the scope changes types, interfaces, schemas, or contracts
+
+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.
+
+## 4. Synthesize
+
+After the relevant subagents complete, synthesize their findings into a unified report:
+
+- Scope used and how it was chosen
+- Subagents run vs skipped (with reason)
+- Ranked findings: delete, stdlib, native/platform, reuse, yagni, shrink
+- What should be deferred because it is out of scope or too risky for this audit
+- Positive findings
+
+Do not apply fixes. This command only audits and reports.

package/stack/commands/xreview.md

@@ -1,80 +1,82 @@
----
-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
----
-
-Run a comprehensive multi-agent review. Your job as the main agent: determine WHAT to review, resolve the exact diff, decide which subagents apply, and launch them in parallel.
-
-## 0. Determine the review target
-
-User input (may be empty): {{input}}
-
-- 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.
-- If the input names files/paths/areas → review the changes touching those paths.
-- If the input is empty or ambiguous: do a quick, cheap situation scan first — uncommitted changes (`git status --short`), current branch, open PR for it (`gh pr view --json baseRefName --jq .baseRefName`) — and ASK the user what to review before launching anything, offering only the options that actually apply:
-  1. Uncommitted work (`git diff` + `git diff --staged`)
-  2. The current branch against its base (say which base you detected and how)
-  3. Against a specific branch they name
-  4. An existing PR
-  5. Specific files or areas
-
-Do NOT guess silently: a review against the wrong target wastes every subagent and buries the user in irrelevant findings.
-
-## 1. Resolve BASE and HEAD (branch/PR reviews)
-
-HEAD is the current branch / worktree being worked on (`git rev-parse --abbrev-ref HEAD`).
-
-BASE is the branch the work will merge into. Do NOT default to `main` — work is often done in sub-branches whose PR targets another branch. Resolve BASE in this order:
-
-1. The branch the user chose in step 0, if any.
-2. If the current branch has an open GitHub PR, its base branch (`gh pr view --json baseRefName --jq .baseRefName`).
-3. Otherwise, inspect local and `origin/*` branches and choose the branch directly underneath the current branch: the candidate whose merge-base with HEAD is newest/closest to HEAD, excluding the current branch itself and its remote tracking ref.
-4. If still unsure, ask the user — never silently fall back to `main`.
-
-Print the chosen BASE and HEAD and why BASE was selected. (For working-tree reviews there is no BASE: the scope is `git diff` + `git diff --staged`.)
-
-## 2. Decide routing (lightweight)
-
-List only the changed file NAMES to decide routing — do NOT load the full diff into your own context:
-`git diff <BASE>...HEAD --name-only` (or `git diff --name-only` + `git diff --staged --name-only` for working-tree reviews).
-
-Sanity check: if that list is far larger than the work being reviewed (hundreds of files, unrelated areas), BASE is almost certainly wrong — STOP, re-resolve it (step 1), and only continue when the diff matches the actual work. Reviewing against the wrong BASE makes every finding worthless.
-
-## 3. 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), so the analysts then review a diff already clean of comment noise instead of re-reporting it or mistaking its edits for contamination.
-
-- Pass it the same scope (BASE/HEAD or working diff) as everyone else.
-- If it changed anything and the scope is a committed diff (branch/PR): comment-fixer itself never commits — YOU commit its fixes to the reviewed branch before launching the analysts, staging ONLY the files it touched (never `-a`/`-A`: don't sweep unrelated working-tree changes into the commit). If the commit can't be made (branch checked out elsewhere, hook rejection), leave the edits uncommitted and say so in the report.
-- For working-tree reviews: leave its edits uncommitted (they join the user's pending work) and say so in the report.
-- If the diff touches no comments, skip it and move on.
-
-## 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:
-
-- 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
-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
-
-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.
-
-## 5. Synthesize
-
-After the relevant subagents complete, synthesize their findings into a unified report:
-
-- Review scope used (BASE/HEAD or working diff) and how it was chosen
-- 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 branch, or left uncommitted for working-tree reviews)
-- Positive Findings
+---
+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
+---
+
+Run a comprehensive multi-agent review. Your job as the main agent: determine WHAT to review, resolve the exact diff, decide which subagents apply, and launch them in parallel.
+
+## 0. Determine the review target
+
+User input (may be empty): {{input}}
+
+- 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.
+- If the input names files/paths/areas → review the changes touching those paths.
+- If the input is empty or ambiguous: do a quick, cheap situation scan first — uncommitted changes (`git status --short`), current branch, open PR for it (`gh pr view --json baseRefName --jq .baseRefName`) — and ASK the user what to review before launching anything, offering only the options that actually apply:
+  1. Uncommitted work (`git diff` + `git diff --staged`)
+  2. The current branch against its base (say which base you detected and how)
+  3. Against a specific branch they name
+  4. An existing PR
+  5. Specific files or areas
+
+Do NOT guess silently: a review against the wrong target wastes every subagent and buries the user in irrelevant findings.
+
+## 1. Resolve BASE and HEAD (branch/PR reviews)
+
+HEAD is the current branch / worktree being worked on (`git rev-parse --abbrev-ref HEAD`).
+
+BASE is the branch the work will merge into. Do NOT default to `main` — work is often done in sub-branches whose PR targets another branch. Resolve BASE in this order:
+
+1. The branch the user chose in step 0, if any.
+2. If the current branch has an open GitHub PR, its base branch (`gh pr view --json baseRefName --jq .baseRefName`).
+3. Otherwise, inspect local and `origin/*` branches and choose the branch directly underneath the current branch: the candidate whose merge-base with HEAD is newest/closest to HEAD, excluding the current branch itself and its remote tracking ref.
+4. If still unsure, ask the user — never silently fall back to `main`.
+
+Print the chosen BASE and HEAD and why BASE was selected. (For working-tree reviews there is no BASE: the scope is `git diff` + `git diff --staged`.)
+
+## 2. Decide routing (lightweight)
+
+List only the changed file NAMES to decide routing — do NOT load the full diff into your own context:
+`git diff <BASE>...HEAD --name-only` (or `git diff --name-only` + `git diff --staged --name-only` for working-tree reviews).
+
+Sanity check: if that list is far larger than the work being reviewed (hundreds of files, unrelated areas), BASE is almost certainly wrong — STOP, re-resolve it (step 1), and only continue when the diff matches the actual work. Reviewing against the wrong BASE makes every finding worthless.
+
+## 3. 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), so the analysts then review a diff already clean of comment noise instead of re-reporting it or mistaking its edits for contamination.
+
+- Pass it the same scope (BASE/HEAD or working diff) as everyone else.
+- If it changed anything and the scope is a committed diff (branch/PR): comment-fixer itself never commits — YOU commit its fixes to the reviewed branch before launching the analysts, staging ONLY the files it touched (never `-a`/`-A`: don't sweep unrelated working-tree changes into the commit). If the commit can't be made (branch checked out elsewhere, hook rejection), leave the edits uncommitted and say so in the report.
+- For working-tree reviews: leave its edits uncommitted (they join the user's pending work) and say so in the report.
+- If the diff touches no comments, skip it and move on.
+
+## 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:
+
+- 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
+
+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.
+
+`/lean-audit` is a separate manual repo/path command, not post-PR automation. Do not route it from here.
+
+## 5. Synthesize
+
+After the relevant subagents complete, synthesize their findings into 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.
+
+- Review scope used (BASE/HEAD or working diff) and how it was chosen
+- 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 branch, or left uncommitted for working-tree reviews)
+- Positive Findings

package/stack/hooks/hooks.json

@@ -1,18 +1,18 @@
-{
-  "$comment": "Hooks canónicos del stack. Formato base = Claude Code (code.claude.com/docs/en/hooks). Traducción por adapter en install: Claude Code → merge en ~/.claude/settings.json (clave hooks) · Codex → ~/.codex/hooks.json (el usuario debe aprobarlos después con /hooks) · OpenCode → plugin puente stack/plugins/opencode/hooks.ts con su propio hooks.json. Extensión propia 'x-command-includes': filtro por substring del comando bash que el puente de OpenCode aplica antes de ejecutar el script; en Claude Code y Codex el filtro lo aplica el propio script (sale con exit 0 si el comando no aplica). El placeholder {{SCRIPTS_DIR}} lo resuelve el instalador a la ruta real donde queden instalados los scripts del stack.",
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Bash|PowerShell",
-        "x-command-includes": "gh pr create",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"{{SCRIPTS_DIR}}/post-pr-review.cjs\"",
-            "timeout": 30
-          }
-        ]
-      }
-    ]
-  }
-}
+{
+  "$comment": "Hooks canónicos del stack. Formato base = Claude Code (code.claude.com/docs/en/hooks). Traducción por adapter en install: Claude Code → merge en ~/.claude/settings.json (clave hooks) · Codex → ~/.codex/hooks.json (el usuario debe aprobarlos después con /hooks) · OpenCode → plugin puente stack/plugins/opencode/hooks.ts con su propio hooks.json. Extensión propia 'x-command-includes': filtro por substring del comando bash que el puente de OpenCode aplica antes de ejecutar el script; en Claude Code y Codex el filtro lo aplica el propio script (sale con exit 0 si el comando no aplica). El placeholder {{SCRIPTS_DIR}} lo resuelve el instalador a la ruta real donde queden instalados los scripts del stack.",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash|PowerShell",
+        "x-command-includes": "gh pr create",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"{{SCRIPTS_DIR}}/post-pr-review.cjs\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -1,156 +1,159 @@
-#!/usr/bin/env node
-/**
- * Global PostToolUse hook: gh pr create
- *
- * 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 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.
- *
- * Payload compatibility (stdin JSON), so the same script works on every runtime:
- * - 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.
- */
-
-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.
-  }
-
-  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,
-      };
-    }
-  } catch {
-    // ignore
-  }
-
-  return { branch: DEFAULT_BASE_BRANCH, source: BASE_BRANCH_SOURCE.DEFAULT };
-}
-
-let raw = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', (chunk) => (raw += chunk));
-process.stdin.on('end', () => {
-  let data = {};
-  try {
-    data = JSON.parse(raw || '{}');
-  } catch {
-    writeWarning('invalid JSON payload; skipping review 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')) {
-    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
-   - 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:
-   - 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');
-  } else {
-    // Claude Code / Codex PostToolUse leen additionalContext del stdout JSON.
-    process.stdout.write(
-      JSON.stringify({
-        additionalContext: message,
-        hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: message },
-      }) + '\n',
-    );
-  }
-  process.exit(0);
-});
+#!/usr/bin/env node
+/**
+ * Global PostToolUse hook: gh pr create
+ *
+ * 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 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:
+ * - 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.
+ */
+
+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.
+  }
+
+  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,
+      };
+    }
+  } catch {
+    // ignore
+  }
+
+  return { branch: DEFAULT_BASE_BRANCH, source: BASE_BRANCH_SOURCE.DEFAULT };
+}
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => (raw += chunk));
+process.stdin.on('end', () => {
+  let data = {};
+  try {
+    data = JSON.parse(raw || '{}');
+  } catch {
+    writeWarning('invalid JSON payload; skipping review 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')) {
+    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');
+  } else {
+    // Claude Code / Codex PostToolUse leen additionalContext del stdout JSON.
+    process.stdout.write(
+      JSON.stringify({
+        additionalContext: message,
+        hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: message },
+      }) + '\n',
+    );
+  }
+  process.exit(0);
+});