jorgex-stack 1.2.2 → 1.2.4

package/README.md

@@ -97,7 +97,7 @@ Programmatic mode does **not** provide:
 
 ### Pi runtime
 
-Pi is package-managed rather than file-managed. Stack supports the exact tested pair **Pi 0.84.2 + `jorgex-pi@0.1.0`** and keeps Pi out of the adapter/component manifest and model map.
+Pi is package-managed rather than file-managed. Stack supports the exact published package **`jorgex-pi@0.2.2`** and keeps Pi out of the adapter/component manifest and model map.
 
 ```bash
 pnpm dlx jorgex-stack install --agents pi
@@ -107,10 +107,12 @@ pnpm dlx jorgex-stack sync --agents pi
 pnpm dlx jorgex-stack uninstall --agents pi
 ```
 
-Stack downloads the frozen registry tarball, verifies its exact size plus SHA-256/SHA-512, backs up Pi's `settings.json`, and only then asks Pi to install that local file. Pi's own package-manager invocation is the narrow runtime exception to the repository's pnpm-only rule; the Stack lifecycle never launches npm directly. A scope-bound receipt under `~/.jorgex-stack/pi-receipt.json` records ownership only after the package runner reports a healthy install. Manual, duplicate, divergent, partial, corrupt, copied-to-another-scope, or unknown-history state fails closed and is never adopted or removed silently.
+Stack downloads the frozen registry tarball, verifies its exact size plus SHA-256/SHA-512, backs up Pi's `settings.json`, and only then asks Pi to install that local file. Pi's own package-manager invocation is the narrow runtime exception to the repository's pnpm-only rule; the Stack lifecycle never launches npm directly. The managed Pi package entry is the exact source object `{ "source": "npm:jorgex-pi@0.2.2", "skills": [] }`: Pi discovers the canonical shared skills from `~/.agents/skills`, so the package copy is disabled and does not create duplicate skill loading. A scope-bound receipt under `~/.jorgex-stack/pi-receipt.json` records ownership only after the package runner reports a healthy install and stores the verified Engram executable as `engram.binary`, using the schema v1 consumed by `jorgex-pi@0.2.2`. Receipts created before the Engram binding existed require deliberate removal with the previous Stack release followed by reinstall; they are never adopted automatically. Manual, duplicate, divergent, partial, corrupt, copied-to-another-scope, or unknown-history state fails closed and is never adopted or removed silently.
 
 Engram remains mandatory and user-owned. An existing binary is preserved. Interactive install may offer the existing native `brew`/`go`/release channel with a default-No confirmation; `--yes` and non-TTY installs fail with a remedy when Engram is absent. No Pi lifecycle operation updates or deletes the Engram database or memories. Under `--target-dir`, Stack accepts only `<target>/bin/engram`, isolates Pi/Home/XDG/AppData/temp/npm-cache paths inside the target, and never consults the host Engram or Pi configuration.
 
+The 24-hour npm maturity rule applies to the managed adoption boundary: development and PR validation may start against the exact published artifact, but merging the adoption PR, publishing that Stack adoption, and running the real managed installation wait until the package has been public for at least 24 hours unless Jorge explicitly documents an exception in the PR.
+
 `update --agents pi` only runs the Pi package lifecycle; it does not enter the global Stack updater. `update --check --agents pi` is a read-only Pi doctor. Uninstall runs package cleanup, backs up Pi's settings before removal, removes only the exact receipt-owned package after verifying absence, and preserves all companion/user state. Full behavior, failure states and troubleshooting are in [docs/references/pi-runtime.md](docs/references/pi-runtime.md).
 
 ### Browser automation

package/dist/cli.js

@@ -3755,13 +3755,19 @@ function parsePackageSources(settingsJson) {
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
     const packages = Reflect.get(parsed, "packages");
     if (!Array.isArray(packages)) return null;
-    const sources = packages.map(packageSource);
-    return sources.every((source) => source !== null) ? sources : null;
+    const sources = packages.map((entry) => ({ entry, source: packageSource(entry) }));
+    return sources.every((value) => value.source !== null) ? sources : null;
   } catch {
     return null;
   }
 }
-function expectedReceipt(candidate, state, scope) {
+function isExactManagedPackage(entry, source) {
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return false;
+  const keys = Object.keys(entry);
+  const skills = Reflect.get(entry, "skills");
+  return keys.length === 2 && keys.includes("source") && keys.includes("skills") && Reflect.get(entry, "source") === source && Array.isArray(skills) && skills.length === 0;
+}
+function expectedReceipt(candidate, state, scope, engramBin) {
   return {
     schemaVersion: 1,
     state,
@@ -3770,21 +3776,52 @@ function expectedReceipt(candidate, state, scope) {
       tarball: candidate.tarball,
       provenance: candidate.provenance
     },
-    scope
+    scope,
+    engram: { binary: engramBin }
   };
 }
-function parseReceipt(receiptJson, candidate, scope) {
+function parseReceiptShape(receiptJson) {
   try {
     const parsed = JSON.parse(receiptJson);
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const schemaVersion = Reflect.get(parsed, "schemaVersion");
+    if (schemaVersion !== 1) return null;
     const state = Reflect.get(parsed, "state");
-    if (state !== "installing" && state !== "installed") return null;
-    const expected = expectedReceipt(candidate, state, scope);
-    return sameRecord(parsed, expected) ? expected : null;
+    const candidate = Reflect.get(parsed, "candidate");
+    if (state !== "installing" && state !== "installed" || candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) {
+      return null;
+    }
+    const packageValue = Reflect.get(candidate, "package");
+    const tarball = Reflect.get(candidate, "tarball");
+    const provenance = Reflect.get(candidate, "provenance");
+    const scope = Reflect.get(parsed, "scope");
+    const engram = Reflect.get(parsed, "engram");
+    if (packageValue === null || typeof packageValue !== "object" || tarball === null || typeof tarball !== "object" || provenance === null || typeof provenance !== "object" || scope === null || typeof scope !== "object" || Array.isArray(scope)) {
+      return null;
+    }
+    const source = Reflect.get(packageValue, "source");
+    const name = Reflect.get(packageValue, "name");
+    const version = Reflect.get(packageValue, "version");
+    const scopeKind = Reflect.get(scope, "kind");
+    const codingAgentDir = Reflect.get(scope, "codingAgentDir");
+    if (name !== "jorgex-pi" || typeof version !== "string" || typeof source !== "string" || source !== `npm:jorgex-pi@${version}` || scopeKind !== "real" && scopeKind !== "target-dir" || typeof codingAgentDir !== "string") {
+      return null;
+    }
+    if (engram === void 0) return "upgrade-required";
+    if (engram === null || typeof engram !== "object" || Array.isArray(engram) || typeof Reflect.get(engram, "binary") !== "string" || !path29.isAbsolute(Reflect.get(engram, "binary"))) {
+      return null;
+    }
+    return parsed;
   } catch {
     return null;
   }
 }
+function parseReceipt(receiptJson, candidate, scope, engramBin) {
+  const parsed = parseReceiptShape(receiptJson);
+  if (parsed === null || parsed === "upgrade-required") return parsed;
+  const expected = expectedReceipt(candidate, parsed.state, scope, engramBin);
+  return sameRecord(parsed, expected) ? expected : null;
+}
 function candidateIsValid(candidate, observed) {
   return candidate.package.name === "jorgex-pi" && candidate.package.source === `npm:${candidate.package.name}@${candidate.package.version}` && candidate.contract.schemaVersion === 1 && candidate.contract.runner.schemaVersion === 1 && candidate.contract.runner.bin === "jorgex-pi" && candidate.contract.runner.maxStdoutBytes === 65536 && candidate.contract.managedExternalWrites.length === 0 && [...REQUIRED_CAPABILITIES].every((capability) => candidate.contract.capabilities.includes(capability)) && sameRecord(candidate.tarball, observed);
 }
@@ -3798,21 +3835,26 @@ function planPiPackageLifecycle(input) {
   if (input.engramBin === null) return blocked(input, "engram-missing");
   const sources = parsePackageSources(input.pi.settingsJson);
   if (sources === null) return blocked(input, "settings-corrupt");
-  const matchingSources = sources.filter(isJorgeXPiSource);
-  const exactSources = matchingSources.filter((source) => source === input.candidate.package.source);
+  const matchingSources = sources.filter(({ source }) => isJorgeXPiSource(source));
+  const exactSources = matchingSources.filter(({ source }) => source === input.candidate.package.source);
   if (exactSources.length > 1) return blocked(input, "duplicate-package");
-  if (matchingSources.some((source) => source !== input.candidate.package.source)) {
+  if (matchingSources.some(({ source }) => source !== input.candidate.package.source)) {
     return blocked(input, "source-divergent");
   }
   let receipt = null;
   if (input.receiptJson !== null) {
-    receipt = parseReceipt(input.receiptJson, input.candidate, {
+    const parsedReceipt = parseReceipt(input.receiptJson, input.candidate, {
       kind: input.scope.kind,
       codingAgentDir: path29.resolve(input.scope.codingAgentDir)
-    });
-    if (receipt === null) return blocked(input, "receipt-corrupt");
+    }, input.engramBin);
+    if (parsedReceipt === "upgrade-required") return blocked(input, "receipt-upgrade-required");
+    if (parsedReceipt === null) return blocked(input, "receipt-corrupt");
+    receipt = parsedReceipt;
     if (receipt.state === "installing") return blocked(input, "partial-state");
-    if (exactSources.length !== 1) return blocked(input, "partial-state");
+    const exactSource = exactSources[0];
+    if (exactSources.length !== 1 || exactSource === void 0 || !isExactManagedPackage(exactSource.entry, input.candidate.package.source)) {
+      return blocked(input, "source-divergent");
+    }
   }
   if (exactSources.length === 1 && receipt === null) {
     return {
@@ -3839,7 +3881,7 @@ function planPiPackageLifecycle(input) {
     receipt: expectedReceipt(input.candidate, "installing", {
       kind: input.scope.kind,
       codingAgentDir: path29.resolve(input.scope.codingAgentDir)
-    }),
+    }, input.engramBin),
     ownership: ownership(true)
   };
 }
@@ -3910,47 +3952,25 @@ function executePiPackageLifecycle(input, deps) {
   }
   return { kind: "models", models: { mode: "inherit-session", tiers: ["strong", "standard", "cheap"] } };
 }
-function readReceiptCandidate(receiptJson) {
-  try {
-    const parsed = JSON.parse(receiptJson);
-    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
-    const schemaVersion = Reflect.get(parsed, "schemaVersion");
-    const state = Reflect.get(parsed, "state");
-    const candidate = Reflect.get(parsed, "candidate");
-    if (schemaVersion !== 1 || state !== "installing" && state !== "installed" || candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) {
-      return null;
-    }
-    const packageValue = Reflect.get(candidate, "package");
-    const tarball = Reflect.get(candidate, "tarball");
-    const provenance = Reflect.get(candidate, "provenance");
-    const scope = Reflect.get(parsed, "scope");
-    if (packageValue === null || typeof packageValue !== "object" || tarball === null || typeof tarball !== "object" || provenance === null || typeof provenance !== "object" || scope === null || typeof scope !== "object" || Array.isArray(scope)) {
-      return null;
-    }
-    const source = Reflect.get(packageValue, "source");
-    const name = Reflect.get(packageValue, "name");
-    const version = Reflect.get(packageValue, "version");
-    if (name !== "jorgex-pi" || typeof version !== "string" || typeof source !== "string" || source !== `npm:jorgex-pi@${version}`) {
-      return null;
-    }
-    const scopeKind = Reflect.get(scope, "kind");
-    const codingAgentDir = Reflect.get(scope, "codingAgentDir");
-    if (scopeKind !== "real" && scopeKind !== "target-dir" || typeof codingAgentDir !== "string") return null;
-    return parsed;
-  } catch {
-    return null;
-  }
+function receiptUpgradeRequired() {
+  return {
+    kind: "blocked",
+    reason: "receipt-upgrade-required",
+    remedy: "El receipt no enlaza Engram; usa la versi\xF3n anterior de Stack para desinstalarlo y luego reinstala."
+  };
 }
 function validateOwnedOperationState(input) {
   const sources = parsePackageSources(input.detected.settingsJson);
   if (sources === null) return { kind: "blocked", reason: "settings-corrupt" };
-  const matchingSources = sources.filter(isJorgeXPiSource);
+  const matchingSources = sources.filter(({ source: source2 }) => isJorgeXPiSource(source2));
   if (matchingSources.length > 1) return { kind: "blocked", reason: "duplicate-package" };
   if (input.receiptJson === null) {
     return { kind: "blocked", reason: matchingSources.length === 1 ? "manual-existing" : "source-divergent" };
   }
-  const receipt = readReceiptCandidate(input.receiptJson);
-  if (receipt === null) return { kind: "blocked", reason: "receipt-corrupt" };
+  const parsedReceipt = parseReceiptShape(input.receiptJson);
+  if (parsedReceipt === "upgrade-required") return receiptUpgradeRequired();
+  if (parsedReceipt === null) return { kind: "blocked", reason: "receipt-corrupt" };
+  const receipt = parsedReceipt;
   if (receipt.state !== "installed") return { kind: "blocked", reason: "partial-state" };
   const accepted = input.registry.acceptedCandidates ?? [input.registry.candidate];
   if (!accepted.some((candidate) => sameRecord(receipt.candidate, {
@@ -3963,8 +3983,12 @@ function validateOwnedOperationState(input) {
   if (receipt.scope.kind !== (input.paths.targetDir ? "target-dir" : "real") || path29.resolve(receipt.scope.codingAgentDir) !== path29.resolve(input.paths.codingAgentDir)) {
     return { kind: "blocked", reason: "source-divergent" };
   }
+  if (input.engramBin !== null && path29.resolve(receipt.engram.binary) !== path29.resolve(input.engramBin)) {
+    return { kind: "blocked", reason: "receipt-corrupt" };
+  }
   const source = receipt.candidate.package.source;
-  if (matchingSources.length !== 1 || matchingSources[0] !== source) {
+  const matchingSource = matchingSources[0];
+  if (matchingSources.length !== 1 || matchingSource === void 0 || matchingSource.source !== source || !isExactManagedPackage(matchingSource.entry, source)) {
     return { kind: "blocked", reason: "source-divergent" };
   }
   return { receipt, source };
@@ -4048,16 +4072,16 @@ function runPiPackageManagedOperation(input, deps) {
 var PI_RUNTIME_CANDIDATE = {
   package: {
     name: "jorgex-pi",
-    version: "0.1.0",
-    source: "npm:jorgex-pi@0.1.0"
+    version: "0.2.2",
+    source: "npm:jorgex-pi@0.2.2"
   },
   provenance: {
-    commit: "791db79e33efd6661899995b5491e4dff5caa363"
+    commit: "99631aa3712f51a625d196e949e48e27f55031a2"
   },
   tarball: {
-    bytes: 89066153,
-    sha256: "6243bf8e3a8dbe7be9103d7ca9b03e196c41ac9eef6578f47ea6d03655366feb",
-    sha512: "07590abec9e9594b001e28d75eb810259c4088f9f2f6d1d5b9fe456bb2d15a7259ff31ee225d5f1f59b27a1c337a1f1f8e3e57089656bf7bbad966e653110ddd"
+    bytes: 89101513,
+    sha256: "e1c6b63719995cf7ba2c96c3b753f19d8f2f0be74f2af9bc319576b7383913f4",
+    sha512: "7b81dc1eb6030d562c70857dcf739798df94c88bddd240b2752c558fc1d21403faa411aa88e182a01664a17e06e2caeef35f1507eff45c97f4acc521469c45a1"
   },
   pi: {
     testedVersions: ["0.84.2"]
@@ -4074,7 +4098,8 @@ var PI_RUNTIME_CANDIDATE = {
       "goal-continuation-v1",
       "mcp-adapter-v1",
       "engram-runtime-tools-v1",
-      "runner-json-v1"
+      "runner-json-v1",
+      "tui-branding-v1"
     ],
     runner: {
       bin: "jorgex-pi",
@@ -4134,11 +4159,11 @@ async function resolvePiEngramRequirement(input, deps) {
     remedy: "La instalaci\xF3n termin\xF3, pero Engram no qued\xF3 detectable; configura ENGRAM_BIN."
   } : { kind: "existing", bin: detected, scope: "host" };
 }
-function flatCandidateReceipt(candidate, scope, state) {
+function flatCandidateReceipt(candidate, scope, state, engramBin) {
   const match = /^npm:jorgex-pi@([^\s]+)$/.exec(candidate.source);
   const packageValue = candidate.package ?? {
     name: "jorgex-pi",
-    version: match?.[1] ?? "0.1.0",
+    version: match?.[1] ?? PI_RUNTIME_CANDIDATE.package.version,
     source: candidate.source
   };
   return {
@@ -4149,7 +4174,8 @@ function flatCandidateReceipt(candidate, scope, state) {
       tarball: { bytes: candidate.bytes, sha256: candidate.sha256, sha512: candidate.sha512 },
       provenance: candidate.provenance ?? { commit: PI_RUNTIME_CANDIDATE.provenance.commit }
     },
-    scope
+    scope,
+    engram: { binary: engramBin }
   };
 }
 function normalizeInstalledSource(settingsJson, alias, canonical) {
@@ -4158,8 +4184,9 @@ function normalizeInstalledSource(settingsJson, alias, canonical) {
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
     const packages = Reflect.get(parsed, "packages");
     if (!Array.isArray(packages)) return null;
-    if (packages.filter((entry) => entry === alias).length !== 1 || packages.includes(canonical)) return null;
-    Reflect.set(parsed, "packages", packages.map((entry) => entry === alias ? canonical : entry));
+    const hasCanonical = packages.some((entry) => entry === canonical || entry !== null && typeof entry === "object" && !Array.isArray(entry) && Reflect.get(entry, "source") === canonical);
+    if (packages.filter((entry) => entry === alias).length !== 1 || hasCanonical) return null;
+    Reflect.set(parsed, "packages", packages.map((entry) => entry === alias ? { source: canonical, skills: [] } : entry));
     return JSON.stringify(parsed);
   } catch {
     return null;
@@ -4179,7 +4206,7 @@ function healthyDoctor(stdout, stderr, packageRunner, candidate) {
 }
 function installPiFromVerifiedTarball(input, deps) {
   const paths = input.targetDir === void 0 ? userPaths(input.engramBin, input.piExecutable) : targetPaths(input.targetDir, input.engramBin, input.piExecutable);
-  const destination = input.targetDir === void 0 ? path30.join(dataDir(), "packages", "jorgex-pi-0.1.0.tgz") : path30.join(path30.resolve(input.targetDir), "downloads", "jorgex-pi-0.1.0.tgz");
+  const destination = input.targetDir === void 0 ? path30.join(dataDir(), "packages", `jorgex-pi-${PI_RUNTIME_CANDIDATE.package.version}.tgz`) : path30.join(path30.resolve(input.targetDir), "downloads", `jorgex-pi-${PI_RUNTIME_CANDIDATE.package.version}.tgz`);
   const artifact = deps.download(destination);
   if (artifact.bytes !== input.candidate.bytes || artifact.sha256 !== input.candidate.sha256 || artifact.sha512 !== input.candidate.sha512) {
     return { kind: "blocked", reason: "tarball-integrity" };
@@ -4189,7 +4216,7 @@ function installPiFromVerifiedTarball(input, deps) {
     kind: input.targetDir === void 0 ? "real" : "target-dir",
     codingAgentDir: path30.resolve(paths.codingAgentDir)
   };
-  const installing = flatCandidateReceipt(input.candidate, scope, "installing");
+  const installing = flatCandidateReceipt(input.candidate, scope, "installing", input.engramBin);
   deps.writeReceiptAtomic(`${JSON.stringify(installing)}
 `);
   const alias = `npm:jorgex-pi@file:${artifact.path}`;
@@ -4210,7 +4237,7 @@ function installPiFromVerifiedTarball(input, deps) {
   if (doctor.exitCode !== 0 || !healthyDoctor(doctor.stdout, doctor.stderr, paths.packageRunner, input.candidate)) {
     return { kind: "blocked", reason: "runner-unhealthy" };
   }
-  const receipt = flatCandidateReceipt(input.candidate, scope, "installed");
+  const receipt = flatCandidateReceipt(input.candidate, scope, "installed", input.engramBin);
   deps.writeReceiptAtomic(`${JSON.stringify(receipt)}
 `);
   return { kind: "installed", receipt };
@@ -4430,11 +4457,11 @@ async function acquirePiTarball(destination) {
   }
   fs22.mkdirSync(path30.dirname(destination), { recursive: true });
   const partial = `${destination}.partial-${process.pid}`;
-  const response = await fetch("https://registry.npmjs.org/jorgex-pi/-/jorgex-pi-0.1.0.tgz", {
+  const response = await fetch(`https://registry.npmjs.org/jorgex-pi/-/jorgex-pi-${PI_RUNTIME_CANDIDATE.package.version}.tgz`, {
     redirect: "error",
     headers: { accept: "application/octet-stream" }
   });
-  if (!response.ok || response.body === null) throw new Error(`No se pudo descargar jorgex-pi@0.1.0 (${response.status}).`);
+  if (!response.ok || response.body === null) throw new Error(`No se pudo descargar jorgex-pi@${PI_RUNTIME_CANDIDATE.package.version} (${response.status}).`);
   const descriptor = fs22.openSync(partial, "wx", 384);
   let bytes = 0;
   try {
@@ -4501,7 +4528,7 @@ async function runPiRuntimeSystem(input) {
         remedy: "Instala Engram o configura un ENGRAM_BIN absoluto antes de reintentar."
       };
     }
-    const destination = input.targetDir === void 0 ? path30.join(dataDir(), "packages", "jorgex-pi-0.1.0.tgz") : path30.join(path30.resolve(input.targetDir), "downloads", "jorgex-pi-0.1.0.tgz");
+    const destination = input.targetDir === void 0 ? path30.join(dataDir(), "packages", `jorgex-pi-${PI_RUNTIME_CANDIDATE.package.version}.tgz`) : path30.join(path30.resolve(input.targetDir), "downloads", `jorgex-pi-${PI_RUNTIME_CANDIDATE.package.version}.tgz`);
     let artifact;
     try {
       artifact = await acquirePiTarball(destination);

package/package.json

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