jorgex-stack 1.2.3 → 1.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jorgex-stack",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "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/code-reviewer.md

@@ -13,8 +13,9 @@ You are an expert code reviewer specializing in modern software development acro
 
 **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`).
-2. Load the `agent-delegation` skill.
+1. **Load the work context when provided.** If the caller gives you an exact work context path, read only its `PRD.md` and `plan.md` before inspecting the diff. Use them to understand the goal, non-goals, constraints, success criteria and current PR slice. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
+2. **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`).
+3. 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.
 

package/stack/agents/code-simplifier.md

@@ -15,9 +15,10 @@ You are read-only: you analyze recently modified code and **propose** refinement
 
 **First actions, in order**:
 
-1. **Resolve scope.** If you're given an audit scope (repo/path root), audit only that path and do not fall back to `git diff`. Otherwise, when you're given BASE and HEAD branches, review only `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no audit scope or branches are given, review the working diff (`git diff`).
-2. Load the `lean-code` skill.
-3. Load the `agent-delegation` skill.
+1. **Load the work context when provided.** If the caller gives you an exact work context path, read only its `PRD.md` and `plan.md` before inspecting the diff. Use them to understand the goal, non-goals, constraints, success criteria and current PR slice. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
+2. **Resolve scope.** If you're given an audit scope (repo/path root), audit only that path and do not fall back to `git diff`. Otherwise, when you're given BASE and HEAD branches, review only `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no audit scope or branches are given, review the working diff (`git diff`).
+3. Load the `lean-code` skill.
+4. 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.
 

package/stack/agents/comment-fixer.md

@@ -14,8 +14,9 @@ You fix comments directly instead of reporting suggestions: trivial comment work
 
 **First actions, in order**:
 
-1. **Get the diff.** When you're given BASE and HEAD branches, work only on `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no branches are given, work on the working diff (`git diff`).
-2. Load the `agent-delegation` skill.
+1. **Load the work context when provided.** If the caller gives you an exact work context path, read only its `PRD.md` and `plan.md` before inspecting the diff. Use them to understand the goal, non-goals, constraints, success criteria and current PR slice. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
+2. **Get the diff.** When you're given BASE and HEAD branches, work only on `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no branches are given, work on the working diff (`git diff`).
+3. 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.
 

package/stack/agents/security-auditor.md

@@ -11,8 +11,9 @@ bash: git-read
 
 **First actions, in order**:
 
-1. **Get the diff.** When you're given BASE and HEAD branches, audit only `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no branches are given, audit the working diff (`git diff`).
-2. Load the `agent-delegation` skill.
+1. **Load the work context when provided.** If the caller gives you an exact work context path, read only its `PRD.md` and `plan.md` before inspecting the diff. Use them to understand the goal, non-goals, constraints, success criteria and current PR slice. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
+2. **Get the diff.** When you're given BASE and HEAD branches, audit only `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no branches are given, audit the working diff (`git diff`).
+3. 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.
 

package/stack/agents/silent-failure-hunter.md

@@ -13,8 +13,9 @@ You are an elite error handling auditor with zero tolerance for silent failures
 
 **First actions, in order**:
 
-1. **Get the diff.** When you're given BASE and HEAD branches, audit only `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no branches are given, audit the working diff (`git diff`).
-2. Load the `agent-delegation` skill.
+1. **Load the work context when provided.** If the caller gives you an exact work context path, read only its `PRD.md` and `plan.md` before inspecting the diff. Use them to understand the goal, non-goals, constraints, success criteria and current PR slice. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
+2. **Get the diff.** When you're given BASE and HEAD branches, audit only `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no branches are given, audit the working diff (`git diff`).
+3. 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.
 

package/stack/agents/test-analyzer.md

@@ -13,9 +13,10 @@ You determine whether the diff has sufficient evidence for its meaningful regres
 
 **First actions, in order**:
 
-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 `tdd` skill. Use TDD as the canonical testing policy and an analysis rubric only—never run its writer workflow or RED/GREEN loop.
-3. Load the `agent-delegation` skill.
+1. **Load the work context when provided.** If the caller gives you an exact work context path, read only its `PRD.md` and `plan.md` before inspecting the diff. Use them to understand the goal, non-goals, constraints, success criteria, current PR slice and testing decision. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
+2. **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`).
+3. Load the `tdd` skill. Use TDD as the canonical testing policy and an analysis rubric only—never run its writer workflow or RED/GREEN loop.
+4. Load the `agent-delegation` skill.
 
 **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.
 

package/stack/agents/type-design-analyzer.md

@@ -13,8 +13,9 @@ You are a type design expert with extensive experience in large-scale software a
 
 **First actions, in order**:
 
-1. **Resolve scope.** If you're given an audit scope (repo/path root), inspect only type/interface/schema/contract definitions in that path and do not fall back to `git diff`. Otherwise, when you're given BASE and HEAD branches, review only `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no audit scope or branches are given, review the working diff (`git diff`).
-2. Load the `agent-delegation` skill.
+1. **Load the work context when provided.** If the caller gives you an exact work context path, read only its `PRD.md` and `plan.md` before inspecting the diff. Use them to understand the goal, non-goals, constraints, success criteria and current PR slice. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
+2. **Resolve scope.** If you're given an audit scope (repo/path root), inspect only type/interface/schema/contract definitions in that path and do not fall back to `git diff`. Otherwise, when you're given BASE and HEAD branches, review only `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no audit scope or branches are given, review the working diff (`git diff`).
+3. 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.
 

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Global PostToolUse guardrail for the PR draft → ready lifecycle.
+ * Global PostToolUse guardrail for PR readiness transitions.
  *
  * The historical filename is intentionally preserved so sync can migrate the
  * existing hook entry instead of leaving an orphan in user configuration.
@@ -77,7 +77,7 @@ function skipRepoOptions(tokens, start) {
   return index;
 }
 
-function isLifecycleSegment(tokens) {
+function isReadinessTransitionSegment(tokens) {
   if (!/(?:^|[\\/])gh(?:\.exe)?$/i.test(tokens[0] ?? "")) return false;
 
   let index = skipRepoOptions(tokens, 1);
@@ -85,21 +85,56 @@ function isLifecycleSegment(tokens) {
   index = skipRepoOptions(tokens, index + 1);
 
   const action = tokens[index]?.toLowerCase();
-  return action === "create" || action === "ready";
+  const args = tokens.slice(index + 1).map((token) => token.toLowerCase());
+  const readBooleanFlag = (names, valueFlags = []) => {
+    let value;
+    for (let offset = 0; offset < args.length; offset += 1) {
+      const arg = args[offset];
+      if (arg === "--") break;
+      if (valueFlags.includes(arg)) {
+        offset += 1;
+        continue;
+      }
+      if (valueFlags.some((name) => arg.startsWith(`${name}=`))) continue;
+      if (names.some((name) => arg === name)) {
+        value = true;
+        continue;
+      }
+      for (const name of names) {
+        if (!arg.startsWith(`${name}=`)) continue;
+        const flagValue = arg.slice(name.length + 1);
+        if (["true", "t", "1"].includes(flagValue)) value = true;
+        if (["false", "f", "0"].includes(flagValue)) value = false;
+      }
+    }
+    return value;
+  };
+
+  if (action === "ready") return readBooleanFlag(["--undo"], ["-R", "--repo"]) !== true;
+  if (action !== "create" && action !== "new") return false;
+
+  const createValueFlags = [
+    "-R", "--repo", "-a", "--assignee", "-B", "--base", "-b", "--body",
+    "-F", "--body-file", "-H", "--head", "-l", "--label", "-m", "--milestone",
+    "-p", "--project", "--recover", "-r", "--reviewer", "-T", "--template", "-t", "--title",
+  ];
+  const createsDraft = readBooleanFlag(["--draft", "-d"], createValueFlags) === true;
+  return !createsDraft;
 }
 
-function isPrLifecycleCommand(command) {
+function isPrReadinessCommand(command) {
   const segments = Array.isArray(command)
     ? [command.map(String)]
     : shellCommandSegments(String(command));
-  return segments.some(isLifecycleSegment);
+  return segments.some(isReadinessTransitionSegment);
 }
 
 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.
+A PR readiness transition was attempted through \`gh pr create\` without \`--draft\` or through \`gh pr ready\`. 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.
+- The review boundary is the final draft diff. If the full review was not already completed, ensure the PR is draft (run \`gh pr ready --undo <number>\` if necessary), finish code, the applicable version bump, local tests, \`pnpm qa:quality\` when defined, Vercel preview review when applicable, and final diff inspection.
+- Load and run the portable \`xreview\` skill against that exact final diff. When an orchestrator owns an active work context, it must pass the exact \`work/{name}\` to every reviewer.
+- After fixing findings, repeat xreview only when the fixes materially change the diff or introduce a distinct risk. For ordinary fixes, explicit evidence of the prior review plus deterministic verification is sufficient even though \`headRefOid\` changed.
 - 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.
@@ -120,7 +155,7 @@ process.stdin.on("end", () => {
   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)) {
+  if (!shellTools.includes(toolName) || !isPrReadinessCommand(commandValue)) {
     process.exit(0);
   }
 

package/stack/skills/orchestrator/SKILL.md

@@ -197,7 +197,7 @@ An early review during EXECUTE is an **exception**, not a default phase. Use it
 When the plan is fully applied and VERIFY passes:
 
 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:
+2. Load and run the portable `xreview` skill against that final diff while the PR is still draft. Use the exact active `work/{name}` already established for this work and include it verbatim as the work context in every review subagent prompt; never infer it from the branch or scan other `work/*` folders. 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.

package/stack/skills/xreview/SKILL.md

@@ -41,21 +41,29 @@ List only the changed file NAMES to decide routing — do NOT load the full diff
 
 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)
+## 3. Preserve the work context
+
+When running inside the orchestrator's SHIP phase, the main agent already owns the exact active `work/{name}`. Preserve it as the review context and pass it verbatim to every review subagent. Do not infer a work name from the branch or search `work/*`; several pieces of work may be active at once.
+
+For a manual xreview without an explicit work context, continue without PRD/plan context and state that it was unavailable. Never choose a work folder silently.
+
+## 4. 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.
+- When the orchestrator supplied one, pass it the same exact work context path as every other review subagent.
 - 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
+## 5. 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 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
+- when the orchestrator supplied one, the exact work context path verbatim — never a guessed or discovered alternative
 
 Subagents and their triggers:
 
@@ -70,7 +78,7 @@ If none of a subagent's triggers are present, skip it and note that it was skipp
 
 `/lean-audit` is a separate manual repo/path command, not post-PR automation. Do not route it from here.
 
-## 5. Synthesize
+## 6. 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.