jorgex-stack 1.2.3 → 1.3.0

package/README.md

@@ -49,7 +49,7 @@ For development from a clone, run the same commands through `pnpm cli <command>`
 
 Every command supports `--dry-run`, `--yes`, and `--target-dir <dir>` for testing without touching the real config. Writes create automatic backups and verify idempotency; merges into user config are surgical (marked markdown sections, JSON/TOML upserts), so user-owned content is never touched.
 
-Runtime defaults are documented in [docs/references/permissions.md](docs/references/permissions.md) for permissions and [docs/references/models.md](docs/references/models.md) for provider-aware model selection, Codex tiers, and orchestrator inheritance. OpenCode has no provider defaults.
+Runtime defaults are documented in [docs/references/permissions.md](docs/references/permissions.md) for permissions and [docs/references/models.md](docs/references/models.md) for the Sol primary default, field-level ownership and independent subagent routing. OpenCode remains provider-agnostic for subagents; its primary defaults to the OpenAI OAuth model `openai/gpt-5.6-sol` unless the user replaces it.
 
 ### Modes: Human and Programmatic
 
@@ -97,7 +97,7 @@ Programmatic mode does **not** provide:
 
 ### Pi runtime
 
-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.
+Pi is package-managed rather than file-managed. Stack supports the exact published package **`jorgex-pi@0.3.0`** and keeps Pi out of the adapter/component manifest and model map.
 
 ```bash
 pnpm dlx jorgex-stack install --agents pi
@@ -107,11 +107,13 @@ 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. 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.
+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.3.0", "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.3.0`. 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.
+
+The package owns Pi's native primary-model projection: `openai-codex/gpt-5.6-sol`, with a local `contextWindow` request of 872K. It merges only missing compatible fields, records field ownership in `PI_CODING_AGENT_DIR/jorgex-pi/sol-lifecycle.v1.json`, and cleanup removes only still-owned canonical values. Stack does not duplicate that settings/models logic. The 872K value is local OAuth metadata until a real long-context smoke test confirms backend acceptance; it is not the API context limit.
 
 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.
+The 24-hour npm maturity rule applies only to real managed installation or consumption of the new Pi package. Development, PR validation, merge and Stack publication may proceed immediately against the exact verified artifact; installing it on a real user scope before 24 hours requires Jorge's explicit exception.
 
 `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).
 

package/dist/cli.js

@@ -365,6 +365,44 @@ function upsertJson(existing, mutate) {
   mutate(root);
   return JSON.stringify(root, null, 2) + "\n";
 }
+function tomlRootEnd(lines) {
+  const mask = multilineStringMask(lines);
+  const index = lines.findIndex((line, lineIndex) => !mask[lineIndex] && headerName(line) !== null);
+  return index === -1 ? lines.length : index;
+}
+function rootKeyLineIndex(lines, key) {
+  const end = tomlRootEnd(lines);
+  const mask = multilineStringMask(lines);
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(`^\\s*(?:${escaped}|"${escaped}"|'${escaped}')\\s*=`);
+  return lines.slice(0, end).findIndex((line, index) => !mask[index] && pattern.test(line));
+}
+function hasTomlRootKey(existing, key) {
+  if (existing === null || existing === "") return false;
+  return rootKeyLineIndex(existing.replace(/\r\n/g, "\n").split("\n"), key) !== -1;
+}
+function upsertTomlRootKeyIfMissing(existing, key, value) {
+  if (hasTomlRootKey(existing, key)) return existing;
+  const eol = existing?.includes("\r\n") ? "\r\n" : "\n";
+  const normalized = (existing ?? "").replace(/\r\n/g, "\n");
+  const lines = normalized === "" ? [] : normalized.split("\n");
+  const index = tomlRootEnd(lines);
+  lines.splice(index, 0, `${key} = ${value}`);
+  return lines.join(eol);
+}
+function removeTomlRootKeyIfExact(existing, key, value) {
+  const eol = existing.includes("\r\n") ? "\r\n" : "\n";
+  const normalized = existing.replace(/\r\n/g, "\n");
+  const lines = normalized.split("\n");
+  const index = rootKeyLineIndex(lines, key);
+  if (index === -1) return existing;
+  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const escapedValue = value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const exact = new RegExp(`^\\s*(?:${escapedKey}|"${escapedKey}"|'${escapedKey}')\\s*=\\s*${escapedValue}\\s*(?:#.*)?$`);
+  if (!exact.test(lines[index])) return existing;
+  lines.splice(index, 1);
+  return lines.join(eol);
+}
 function headerName(line) {
   const match = /^\s*\[\s*([^\]]+?)\s*\]\s*(#.*)?$/.exec(line);
   if (!match) return null;
@@ -415,14 +453,15 @@ ${body.trim()}
   return result.endsWith("\n") ? result : result + "\n";
 }
 function removeTomlSection(existing, section) {
+  const eol = existing.includes("\r\n") ? "\r\n" : "\n";
   const lines = existing.split(/\r?\n/);
   const found = findTomlSection(lines, section);
   if (found === null) return existing;
   let realStart = found.start;
   while (realStart > 0 && lines[realStart - 1].trim() === "") realStart--;
-  const result = [...lines.slice(0, realStart), ...lines.slice(found.end)].join("\n");
+  const result = [...lines.slice(0, realStart), ...lines.slice(found.end)].join(eol);
   if (result.trim() === "") return "";
-  return result.endsWith("\n") ? result : result + "\n";
+  return result.endsWith(eol) ? result : result + eol;
 }
 function readTomlSection(existing, section) {
   if (existing === null) return null;
@@ -524,6 +563,34 @@ function isManagedOptionalStdioServer(server, value) {
   const expectedCommand = [server.command, ...server.args ?? []];
   return Object.keys(current).length === 2 && current.type === "local" && Array.isArray(current.command) && current.command.length === expectedCommand.length && current.command.every((arg, index) => arg === expectedCommand[index]);
 }
+var PRIMARY_MODEL = "openai/gpt-5.6-sol";
+var PRIMARY_MODEL_ID = "gpt-5.6-sol";
+var PRIMARY_LIMITS = { context: 872e3, input: 744e3, output: 128e3 };
+var PRIMARY_MODEL_FIELD = "model";
+var PRIMARY_PROVIDER_FIELD = "provider";
+var PRIMARY_OPENAI_FIELD = "provider.openai";
+var PRIMARY_MODELS_FIELD = "provider.openai.models";
+var PRIMARY_SOL_FIELD = `provider.openai.models.${PRIMARY_MODEL_ID}`;
+var PRIMARY_LIMIT_PREFIX = `provider.openai.models.${PRIMARY_MODEL_ID}.limit`;
+function objectValue(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function ensureObject(parent, key, fieldPath) {
+  if (parent[key] === void 0) parent[key] = {};
+  const value = objectValue(parent[key]);
+  if (value === null) throw new Error(`OpenCode: '${fieldPath}' debe ser un objeto; corr\xEDgelo antes de reintentar sync.`);
+  return value;
+}
+function ensureOwnedPrimaryObject(parent, key, field, owned, changes) {
+  const created = parent[key] === void 0;
+  const value = ensureObject(parent, key, field);
+  if (created && owned?.has(field) !== true) changes.push({ field, owned: true });
+  return value;
+}
+function pruneEmpty(parent, key) {
+  const value = objectValue(parent[key]);
+  if (value !== null && Object.keys(value).length === 0) delete parent[key];
+}
 var opencodeAdapter = {
   id: "opencode",
   name: "OpenCode",
@@ -656,8 +723,30 @@ ${agent.body}`,
     const contentSource = original === null || original.trim() === "" ? null : original;
     const isFreshConfig = contentSource === null;
     const mcpOwnership = [];
+    const primaryModelOwnership = [];
     const content = upsertJson(contentSource, (root) => {
       root["$schema"] ??= "https://opencode.ai/config.json";
+      if (root[PRIMARY_MODEL_FIELD] === void 0) {
+        root[PRIMARY_MODEL_FIELD] = PRIMARY_MODEL;
+        if (ctx.ownedPrimaryModelFields?.has(PRIMARY_MODEL_FIELD) !== true) {
+          primaryModelOwnership.push({ field: PRIMARY_MODEL_FIELD, owned: true });
+        }
+      } else if (typeof root[PRIMARY_MODEL_FIELD] !== "string" || root[PRIMARY_MODEL_FIELD].trim() === "") {
+        throw new Error("OpenCode: 'model' debe ser un identificador provider/model no vac\xEDo; corr\xEDgelo antes de reintentar sync.");
+      }
+      const provider = ensureOwnedPrimaryObject(root, "provider", PRIMARY_PROVIDER_FIELD, ctx.ownedPrimaryModelFields, primaryModelOwnership);
+      const openai = ensureOwnedPrimaryObject(provider, "openai", PRIMARY_OPENAI_FIELD, ctx.ownedPrimaryModelFields, primaryModelOwnership);
+      const models = ensureOwnedPrimaryObject(openai, "models", PRIMARY_MODELS_FIELD, ctx.ownedPrimaryModelFields, primaryModelOwnership);
+      const sol = ensureOwnedPrimaryObject(models, PRIMARY_MODEL_ID, PRIMARY_SOL_FIELD, ctx.ownedPrimaryModelFields, primaryModelOwnership);
+      const limit = ensureOwnedPrimaryObject(sol, "limit", PRIMARY_LIMIT_PREFIX, ctx.ownedPrimaryModelFields, primaryModelOwnership);
+      for (const [key, value] of Object.entries(PRIMARY_LIMITS)) {
+        if (limit[key] !== void 0) continue;
+        limit[key] = value;
+        const field = `${PRIMARY_LIMIT_PREFIX}.${key}`;
+        if (ctx.ownedPrimaryModelFields?.has(field) !== true) {
+          primaryModelOwnership.push({ field, owned: true });
+        }
+      }
       const defaults = loadCanonicalDefaults(ctx.stackDir)["opencode"];
       if (isFreshConfig && defaults?.["permission"] !== void 0) {
         root["permission"] = defaults["permission"];
@@ -722,7 +811,13 @@ ${agent.body}`,
         }
       }
     });
-    return [{ kind: "write", target: file, content, ...mcpOwnership.length > 0 ? { mcpOwnership } : {} }];
+    return [{
+      kind: "write",
+      target: file,
+      content,
+      ...mcpOwnership.length > 0 ? { mcpOwnership } : {},
+      ...primaryModelOwnership.length > 0 ? { primaryModelOwnership } : {}
+    }];
   },
   planUnmerge(mcp, hooks, ctx) {
     const actions = [];
@@ -738,7 +833,40 @@ ${agent.body}`,
     const config = readTextIfExists(configFile);
     if (config !== null) {
       const mcpOwnership = [];
+      const primaryModelOwnership = [];
       const content = upsertJson(config, (root) => {
+        if (ctx.ownedPrimaryModelFields?.has(PRIMARY_MODEL_FIELD) === true) {
+          if (root[PRIMARY_MODEL_FIELD] === PRIMARY_MODEL) delete root[PRIMARY_MODEL_FIELD];
+          primaryModelOwnership.push({ field: PRIMARY_MODEL_FIELD, owned: false });
+        }
+        const provider = objectValue(root["provider"]);
+        const openai = provider === null ? null : objectValue(provider["openai"]);
+        const models = openai === null ? null : objectValue(openai["models"]);
+        const sol = models === null ? null : objectValue(models[PRIMARY_MODEL_ID]);
+        const limit = sol === null ? null : objectValue(sol["limit"]);
+        if (limit !== null) {
+          for (const [key, value] of Object.entries(PRIMARY_LIMITS)) {
+            const field = `${PRIMARY_LIMIT_PREFIX}.${key}`;
+            if (ctx.ownedPrimaryModelFields?.has(field) !== true) continue;
+            if (limit[key] === value) delete limit[key];
+          }
+        }
+        if (sol !== null && ctx.ownedPrimaryModelFields?.has(PRIMARY_LIMIT_PREFIX) === true) pruneEmpty(sol, "limit");
+        if (models !== null && ctx.ownedPrimaryModelFields?.has(PRIMARY_SOL_FIELD) === true) pruneEmpty(models, PRIMARY_MODEL_ID);
+        if (openai !== null && ctx.ownedPrimaryModelFields?.has(PRIMARY_MODELS_FIELD) === true) pruneEmpty(openai, "models");
+        if (provider !== null && ctx.ownedPrimaryModelFields?.has(PRIMARY_OPENAI_FIELD) === true) pruneEmpty(provider, "openai");
+        if (ctx.ownedPrimaryModelFields?.has(PRIMARY_PROVIDER_FIELD) === true) pruneEmpty(root, "provider");
+        const managedFields = [
+          PRIMARY_PROVIDER_FIELD,
+          PRIMARY_OPENAI_FIELD,
+          PRIMARY_MODELS_FIELD,
+          PRIMARY_SOL_FIELD,
+          PRIMARY_LIMIT_PREFIX,
+          ...Object.keys(PRIMARY_LIMITS).map((key) => `${PRIMARY_LIMIT_PREFIX}.${key}`)
+        ];
+        for (const field of managedFields) {
+          if (ctx.ownedPrimaryModelFields?.has(field) === true) primaryModelOwnership.push({ field, owned: false });
+        }
         const mcpBlock = root["mcp"];
         if (mcpBlock) {
           for (const [name, server] of Object.entries(mcp.servers)) {
@@ -761,7 +889,13 @@ ${agent.body}`,
           else root["plugin"] = kept;
         }
       });
-      actions.push({ kind: "write", target: configFile, content, ...mcpOwnership.length > 0 ? { mcpOwnership } : {} });
+      actions.push({
+        kind: "write",
+        target: configFile,
+        content,
+        ...mcpOwnership.length > 0 ? { mcpOwnership } : {},
+        ...primaryModelOwnership.length > 0 ? { primaryModelOwnership } : {}
+      });
     }
     const hooksFile = path7.join(ctx.configDir, "hooks.json");
     const hooksJson = readTextIfExists(hooksFile);
@@ -1019,6 +1153,10 @@ import fs5 from "fs";
 function tomlString(value) {
   return JSON.stringify(value);
 }
+var PRIMARY_MODEL2 = '"gpt-5.6-sol"';
+var PRIMARY_CONTEXT_WINDOW = "872000";
+var PRIMARY_MODEL_FIELD2 = "model";
+var PRIMARY_CONTEXT_FIELD = "model_context_window";
 function tomlMultiline(value) {
   if (value.includes("'''")) return JSON.stringify(value);
   return `'''
@@ -1137,6 +1275,7 @@ ${body}`
     const contentSource = original === null || original.trim() === "" ? null : original;
     let content = contentSource;
     const mcpOwnership = [];
+    const primaryModelOwnership = [];
     if (contentSource === null) {
       const defaults = loadCanonicalDefaults(ctx.stackDir)["codex"] ?? {};
       for (const [key, value] of Object.entries(defaults)) {
@@ -1181,6 +1320,18 @@ ${body}`
         ""
       ].join("\n");
     }
+    if (!hasTomlRootKey(content, PRIMARY_MODEL_FIELD2)) {
+      content = upsertTomlRootKeyIfMissing(content, PRIMARY_MODEL_FIELD2, PRIMARY_MODEL2);
+      if (ctx.ownedPrimaryModelFields?.has(PRIMARY_MODEL_FIELD2) !== true) {
+        primaryModelOwnership.push({ field: PRIMARY_MODEL_FIELD2, owned: true });
+      }
+    }
+    if (!hasTomlRootKey(content, PRIMARY_CONTEXT_FIELD)) {
+      content = upsertTomlRootKeyIfMissing(content, PRIMARY_CONTEXT_FIELD, PRIMARY_CONTEXT_WINDOW);
+      if (ctx.ownedPrimaryModelFields?.has(PRIMARY_CONTEXT_FIELD) !== true) {
+        primaryModelOwnership.push({ field: PRIMARY_CONTEXT_FIELD, owned: true });
+      }
+    }
     for (const [name, server] of Object.entries(canonical.servers)) {
       const section = `mcp_servers.${name}`;
       const existing = readTomlSection(content, section);
@@ -1237,7 +1388,13 @@ args = [${(server.args ?? []).map(tomlString).join(", ")}]`);
     }
     if (content === null) return [];
     if (!content.endsWith("\n")) content += "\n";
-    return [{ kind: "write", target: file, content, ...mcpOwnership.length > 0 ? { mcpOwnership } : {} }];
+    return [{
+      kind: "write",
+      target: file,
+      content,
+      ...mcpOwnership.length > 0 ? { mcpOwnership } : {},
+      ...primaryModelOwnership.length > 0 ? { primaryModelOwnership } : {}
+    }];
   },
   planUnmerge(mcp, hooks, ctx) {
     const actions = [];
@@ -1253,6 +1410,15 @@ args = [${(server.args ?? []).map(tomlString).join(", ")}]`);
     const config = readTextIfExists(configFile);
     if (config !== null) {
       let content = config;
+      const primaryModelOwnership = [];
+      if (ctx.ownedPrimaryModelFields?.has(PRIMARY_MODEL_FIELD2) === true) {
+        content = removeTomlRootKeyIfExact(content, PRIMARY_MODEL_FIELD2, PRIMARY_MODEL2);
+        primaryModelOwnership.push({ field: PRIMARY_MODEL_FIELD2, owned: false });
+      }
+      if (ctx.ownedPrimaryModelFields?.has(PRIMARY_CONTEXT_FIELD) === true) {
+        content = removeTomlRootKeyIfExact(content, PRIMARY_CONTEXT_FIELD, PRIMARY_CONTEXT_WINDOW);
+        primaryModelOwnership.push({ field: PRIMARY_CONTEXT_FIELD, owned: false });
+      }
       const mcpOwnership = [];
       for (const [name, server] of Object.entries(mcp.servers)) {
         const section = `mcp_servers.${name}`;
@@ -1267,7 +1433,13 @@ args = [${(server.args ?? []).map(tomlString).join(", ")}]`);
           mcpOwnership.push({ server: name, owned: false });
         }
       }
-      actions.push({ kind: "write", target: configFile, content, ...mcpOwnership.length > 0 ? { mcpOwnership } : {} });
+      actions.push({
+        kind: "write",
+        target: configFile,
+        content,
+        ...mcpOwnership.length > 0 ? { mcpOwnership } : {},
+        ...primaryModelOwnership.length > 0 ? { primaryModelOwnership } : {}
+      });
     }
     const hooksFile = path9.join(ctx.configDir, "hooks.json");
     const hooksJson = readTextIfExists(hooksFile);
@@ -1753,6 +1925,7 @@ import fs14 from "fs";
 import path20 from "path";
 var PLAYWRIGHT_CLI_PREFERENCE_VERSION = 1;
 var DEVTOOLS_MCP_PREFERENCE_VERSION = 1;
+var PRIMARY_MODEL_OWNERSHIP_VERSION = 1;
 function readPreference(file) {
   try {
     return { raw: fs14.readFileSync(file, "utf8"), errorCode: null };
@@ -1794,6 +1967,9 @@ function savePlaywrightCliPreference(file, enabled) {
 function devtoolsMcpPreferenceFile(stateDir = dataDir()) {
   return path20.join(stateDir, "devtools-mcp.json");
 }
+function primaryModelOwnershipFile(stateDir = dataDir()) {
+  return path20.join(stateDir, "primary-model.json");
+}
 function isRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -1864,6 +2040,67 @@ function saveDevtoolsMcpOwnership(file, runtime, server, owned) {
   }
   saveDevtoolsMcpState(file, state);
 }
+function parsePrimaryModelOwnership(raw) {
+  try {
+    const value = JSON.parse(raw);
+    if (!isRecord(value) || value.version !== PRIMARY_MODEL_OWNERSHIP_VERSION || !isRecord(value.owned)) return null;
+    const owned = {};
+    for (const [runtime, configs] of Object.entries(value.owned)) {
+      if (!isRuntimeId(runtime) || !isRecord(configs)) return null;
+      const markedConfigs = {};
+      for (const [configDir, fields] of Object.entries(configs)) {
+        if (configDir === "" || !isRecord(fields)) return null;
+        const markedFields = {};
+        for (const [field, state] of Object.entries(fields)) {
+          if (field === "" || state !== true) return null;
+          markedFields[field] = true;
+        }
+        if (Object.keys(markedFields).length > 0) markedConfigs[configDir] = markedFields;
+      }
+      if (Object.keys(markedConfigs).length > 0) owned[runtime] = markedConfigs;
+    }
+    return { version: PRIMARY_MODEL_OWNERSHIP_VERSION, owned };
+  } catch {
+    return null;
+  }
+}
+function loadPrimaryModelOwnershipState(file) {
+  const empty = { version: PRIMARY_MODEL_OWNERSHIP_VERSION, owned: {} };
+  const { raw } = readPreference(file);
+  return raw === null ? empty : parsePrimaryModelOwnership(raw) ?? empty;
+}
+function primaryModelOwnershipError(file = primaryModelOwnershipFile()) {
+  const { raw, errorCode } = readPreference(file);
+  if (errorCode !== null) {
+    return `Primary model: no se pudo leer el ownership en ${file} (${errorCode}). Corrige o borra ese archivo antes de reintentar.`;
+  }
+  if (raw === null || parsePrimaryModelOwnership(raw) !== null) return null;
+  return `Primary model: ownership inv\xE1lido en ${file}. Corrige o borra ese archivo antes de reintentar.`;
+}
+function primaryModelConfigKey(configDir) {
+  const resolved = path20.resolve(configDir);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function loadPrimaryModelOwnership(file, runtime, configDir) {
+  const key = primaryModelConfigKey(configDir);
+  return new Set(Object.keys(loadPrimaryModelOwnershipState(file).owned[runtime]?.[key] ?? {}));
+}
+function savePrimaryModelOwnership(file, runtime, configDir, field, owned) {
+  const error = primaryModelOwnershipError(file);
+  if (error !== null) throw new Error(error);
+  const state = loadPrimaryModelOwnershipState(file);
+  const key = primaryModelConfigKey(configDir);
+  if (owned) {
+    ((state.owned[runtime] ??= {})[key] ??= {})[field] = true;
+  } else {
+    delete state.owned[runtime]?.[key]?.[field];
+    if (state.owned[runtime]?.[key] !== void 0 && Object.keys(state.owned[runtime][key]).length === 0) {
+      delete state.owned[runtime][key];
+    }
+    if (state.owned[runtime] !== void 0 && Object.keys(state.owned[runtime]).length === 0) delete state.owned[runtime];
+  }
+  writeText(file, JSON.stringify(state) + "\n");
+}
 function browserPreferenceErrors(stateDir = dataDir()) {
   return [
     playwrightCliPreferenceError(playwrightCliPreferenceFile(stateDir)),
@@ -1913,14 +2150,18 @@ function ownedMcpServers(runtime, useBrowserPreferences = true) {
   const file = devtoolsMcpPreferenceFile();
   return loadDevtoolsMcpOwnership(file, runtime, DEVTOOLS_MCP_SERVER) ? /* @__PURE__ */ new Set([DEVTOOLS_MCP_SERVER]) : /* @__PURE__ */ new Set();
 }
-function persistMcpOwnershipChanges(runtime, plan) {
+function persistConfigurationOwnershipChanges(runtime, configDir, plan) {
   const latest = /* @__PURE__ */ new Map();
+  const primary = /* @__PURE__ */ new Map();
   for (const action of plan) {
     if (action.kind !== "write") continue;
     for (const change of action.mcpOwnership ?? []) latest.set(change.server, change.owned);
+    for (const change of action.primaryModelOwnership ?? []) primary.set(change.field, change.owned);
   }
   const file = devtoolsMcpPreferenceFile();
   for (const [server, owned] of latest) saveDevtoolsMcpOwnership(file, runtime, server, owned);
+  const primaryFile = primaryModelOwnershipFile();
+  for (const [field, owned] of primary) savePrimaryModelOwnership(primaryFile, runtime, configDir, field, owned);
 }
 function makeContext(adapter, configDir, mode = DEFAULT_INSTALL_MODE_PREFERENCE, useBrowserPreferences = true) {
   const models = loadModelMap()[adapter.id];
@@ -1935,7 +2176,8 @@ function makeContext(adapter, configDir, mode = DEFAULT_INSTALL_MODE_PREFERENCE,
     warnings: [],
     enabledMcpServers: enabledMcpServers(adapter.id, void 0, useBrowserPreferences),
     playwrightCliEnabled: useBrowserPreferences && loadPlaywrightCliPreference() === true,
-    ownedMcpServers: ownedMcpServers(adapter.id, useBrowserPreferences)
+    ownedMcpServers: ownedMcpServers(adapter.id, useBrowserPreferences),
+    ownedPrimaryModelFields: useBrowserPreferences ? loadPrimaryModelOwnership(primaryModelOwnershipFile(), adapter.id, configDir) : /* @__PURE__ */ new Set()
   };
 }
 function buildPlan(adapter, ctx) {
@@ -1960,11 +2202,11 @@ function diffPlan(plan) {
     return { action, status: sameFileContent(action.source, action.target) ? "unchanged" : "update" };
   });
 }
-function applyChanges(changes, onMcpOwnershipWritten) {
+function applyChanges(changes, onOwnershipWritten) {
   for (const { action } of changes) {
     if (action.kind === "write") {
       writeText(action.target, action.content);
-      if (action.mcpOwnership !== void 0) onMcpOwnershipWritten?.(action);
+      if (action.mcpOwnership !== void 0 || action.primaryModelOwnership !== void 0) onOwnershipWritten?.(action);
     } else copyFile(action.source, action.target);
   }
 }
@@ -1998,10 +2240,10 @@ async function runInstall(opts) {
   const engramBin = detectEngram();
   const modePreference = opts.mode === void 0 ? opts.targetDir === void 0 ? loadInstallModePreference() : DEFAULT_INSTALL_MODE_PREFERENCE : normalizeInstallModePreference(opts.mode);
   const useManifest = opts.targetDir === void 0;
-  const preferenceErrors = useManifest ? browserPreferenceErrors() : [];
+  const preferenceErrors = useManifest ? [...browserPreferenceErrors(), primaryModelOwnershipError()].filter((error) => error !== null) : [];
   if (preferenceErrors.length > 0) {
     for (const error of preferenceErrors) p.log.error(error);
-    p.outro("Install cancelado: corrige las preferencias de navegador antes de reintentar.");
+    p.outro("Install cancelado: corrige el estado de configuraci\xF3n indicado arriba antes de reintentar.");
     return 1;
   }
   const toolPlan = opts.playwrightToolConsent === void 0 ? null : resolvePlaywrightToolPlan({
@@ -2051,7 +2293,8 @@ async function runInstall(opts) {
       warnings: [],
       enabledMcpServers: enabledMcpServers(id, opts.devtoolsMcpSelection?.[id], useManifest),
       playwrightCliEnabled: projectPlaywrightPrompt || useManifest && loadPlaywrightCliPreference() === true,
-      ownedMcpServers: ownedMcpServers(id, useManifest)
+      ownedMcpServers: ownedMcpServers(id, useManifest),
+      ownedPrimaryModelFields: useManifest ? loadPrimaryModelOwnership(primaryModelOwnershipFile(), id, configDir) : /* @__PURE__ */ new Set()
     };
     const persistDevtoolsSelection = () => {
       const selection = opts.devtoolsMcpSelection?.[id];
@@ -2092,7 +2335,7 @@ async function runInstall(opts) {
     };
     if (changes.length === 0 && orphans.length === 0) {
       writeManifest();
-      if (useManifest) persistMcpOwnershipChanges(id, plan);
+      if (useManifest) persistConfigurationOwnershipChanges(id, configDir, plan);
       persistDevtoolsSelection();
       p.log.success(`${adapter.name}: ya al d\xEDa (idempotente).`);
       successfulRuns++;
@@ -2114,7 +2357,7 @@ async function runInstall(opts) {
     }
     const backup = useManifest ? createBackup([...updates.map((c) => c.action.target), ...orphans], `install-${id}`) : null;
     if (backup) p.log.info(`Backup: ${backup.id} (${backup.files.length} archivos)`);
-    applyChanges(changes, useManifest ? (action) => persistMcpOwnershipChanges(id, [action]) : void 0);
+    applyChanges(changes, useManifest ? (action) => persistConfigurationOwnershipChanges(id, configDir, [action]) : void 0);
     const pruneRoot = useManifest ? HOME : path21.dirname(configDir);
     for (const orphan of orphans) {
       fs15.rmSync(orphan, { force: true });
@@ -2128,7 +2371,7 @@ async function runInstall(opts) {
       exitCode = 1;
     } else {
       writeManifest();
-      if (useManifest) persistMcpOwnershipChanges(id, plan);
+      if (useManifest) persistConfigurationOwnershipChanges(id, configDir, plan);
       persistDevtoolsSelection();
       p.log.success(`${adapter.name}: ${changes.length} archivos aplicados y verificados (idempotente).`);
       successfulRuns++;
@@ -2211,10 +2454,10 @@ function resolvePlaywrightUninstallPlan(input) {
 async function runUninstall(opts) {
   p2.intro(`jorgex-stack ${opts.dryRun ? "uninstall (dry-run)" : "uninstall"}`);
   const useBrowserPreferences = opts.targetDir === void 0;
-  const preferenceErrors = useBrowserPreferences ? browserPreferenceErrors() : [];
+  const preferenceErrors = useBrowserPreferences ? [...browserPreferenceErrors(), primaryModelOwnershipError()].filter((error) => error !== null) : [];
   if (preferenceErrors.length > 0) {
     for (const error of preferenceErrors) p2.log.error(error);
-    p2.outro("Uninstall cancelado: corrige las preferencias de navegador antes de reintentar.");
+    p2.outro("Uninstall cancelado: corrige el estado de configuraci\xF3n indicado arriba antes de reintentar.");
     return 1;
   }
   const stackDir = stackRoot();
@@ -2306,6 +2549,14 @@ async function runUninstall(opts) {
         for (const change of action.mcpOwnership ?? []) {
           saveDevtoolsMcpOwnership(devtoolsMcpPreferenceFile(), id, change.server, change.owned);
         }
+        for (const change of action.primaryModelOwnership ?? []) {
+          savePrimaryModelOwnership(primaryModelOwnershipFile(), id, configDir, change.field, change.owned);
+        }
+      }
+    }
+    if (usingRealConfig) {
+      for (const field of ctx.ownedPrimaryModelFields ?? []) {
+        savePrimaryModelOwnership(primaryModelOwnershipFile(), id, configDir, field, false);
       }
     }
     if (usingRealConfig) removeRuntimeManifest(id);
@@ -2395,6 +2646,11 @@ async function runDoctor() {
   }
   if (!fs17.existsSync(modelMapFile())) p3.log.info("model-map: a\xFAn no creado (se crea en el primer install o con 'models').");
   const preferenceErrors = browserPreferenceErrors();
+  const primaryOwnershipError = primaryModelOwnershipError();
+  if (primaryOwnershipError !== null) {
+    p3.log.error(primaryOwnershipError);
+    problems++;
+  }
   if (preferenceErrors.length > 0) {
     for (const error of preferenceErrors) p3.log.error(error);
     problems += preferenceErrors.length;
@@ -3724,11 +3980,31 @@ import { createHash } from "crypto";
 import path29 from "path";
 var REQUIRED_CAPABILITIES = /* @__PURE__ */ new Set([
   "foundation-contract-v1",
-  "runner-json-v1"
+  "runner-json-v1",
+  "managed-primary-model-v1"
+]);
+var ALLOWED_EXTERNAL_WRITES = /* @__PURE__ */ new Set([
+  "settings.json",
+  "models.json",
+  "jorgex-pi/sol-lifecycle.v1.json"
 ]);
 function sameRecord(left, right) {
   return JSON.stringify(left) === JSON.stringify(right);
 }
+function managedExternalWritesAreSafe(writes) {
+  if (writes.length !== ALLOWED_EXTERNAL_WRITES.size) return false;
+  const seen = /* @__PURE__ */ new Set();
+  for (const write of writes) {
+    if (write === null || typeof write !== "object" || Array.isArray(write)) return false;
+    if (Object.keys(write).sort().join(",") !== "owner,relativePath,root,semantics") return false;
+    if (write.owner !== "jorgex-pi" || write.root !== "PI_CODING_AGENT_DIR") return false;
+    if (typeof write.relativePath !== "string" || !ALLOWED_EXTERNAL_WRITES.has(write.relativePath)) return false;
+    if (/^(?:[A-Za-z]:|[\\/])/.test(write.relativePath) || write.relativePath.split(/[\\/]/).includes("..")) return false;
+    if (typeof write.semantics !== "string" || write.semantics.trim() === "" || seen.has(write.relativePath)) return false;
+    seen.add(write.relativePath);
+  }
+  return seen.size === ALLOWED_EXTERNAL_WRITES.size;
+}
 function ownership(receipt) {
   return { receipt, adapters: false, manifest: false, modelMap: false };
 }
@@ -3823,7 +4099,7 @@ function parseReceipt(receiptJson, candidate, 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);
+  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 && managedExternalWritesAreSafe(candidate.contract.managedExternalWrites) && [...REQUIRED_CAPABILITIES].every((capability) => candidate.contract.capabilities.includes(capability)) && sameRecord(candidate.tarball, observed);
 }
 function planPiPackageLifecycle(input) {
   if (!candidateIsValid(input.candidate, input.observedTarball)) {
@@ -4072,16 +4348,16 @@ function runPiPackageManagedOperation(input, deps) {
 var PI_RUNTIME_CANDIDATE = {
   package: {
     name: "jorgex-pi",
-    version: "0.2.2",
-    source: "npm:jorgex-pi@0.2.2"
+    version: "0.3.0",
+    source: "npm:jorgex-pi@0.3.0"
   },
   provenance: {
-    commit: "99631aa3712f51a625d196e949e48e27f55031a2"
+    commit: "cc8c66f1254e3f7a7c7f4679a30e7a0c7627498c"
   },
   tarball: {
-    bytes: 89101513,
-    sha256: "e1c6b63719995cf7ba2c96c3b753f19d8f2f0be74f2af9bc319576b7383913f4",
-    sha512: "7b81dc1eb6030d562c70857dcf739798df94c88bddd240b2752c558fc1d21403faa411aa88e182a01664a17e06e2caeef35f1507eff45c97f4acc521469c45a1"
+    bytes: 89104529,
+    sha256: "13919b9aaed407e4e08c774cd24a496d3befbd91de6aafd37725fd7263963a3b",
+    sha512: "85c9adf038e8a0e826009fc8cffe23006688c184a43602d81e29807516073e604b0e451bd8f6883f1d352fb858d232acd593d72af67689b8ef5f7467f17fc096"
   },
   pi: {
     testedVersions: ["0.84.2"]
@@ -4099,7 +4375,8 @@ var PI_RUNTIME_CANDIDATE = {
       "mcp-adapter-v1",
       "engram-runtime-tools-v1",
       "runner-json-v1",
-      "tui-branding-v1"
+      "tui-branding-v1",
+      "managed-primary-model-v1"
     ],
     runner: {
       bin: "jorgex-pi",
@@ -4107,7 +4384,26 @@ var PI_RUNTIME_CANDIDATE = {
       schemaVersion: 1,
       maxStdoutBytes: 65536
     },
-    managedExternalWrites: []
+    managedExternalWrites: [
+      {
+        owner: "jorgex-pi",
+        root: "PI_CODING_AGENT_DIR",
+        relativePath: "settings.json",
+        semantics: "merge a missing or matching partial defaultProvider=openai-codex and defaultModel=gpt-5.6-sol pair; preserve foreign halves; cleanup removes only receipt-owned exact values"
+      },
+      {
+        owner: "jorgex-pi",
+        root: "PI_CODING_AGENT_DIR",
+        relativePath: "models.json",
+        semantics: "merge missing providers.openai-codex.modelOverrides.gpt-5.6-sol.contextWindow=872000; cleanup removes only receipt-owned exact values"
+      },
+      {
+        owner: "jorgex-pi",
+        root: "PI_CODING_AGENT_DIR",
+        relativePath: "jorgex-pi/sol-lifecycle.v1.json",
+        semantics: "record field, container, and file ownership; remove the receipt when empty"
+      }
+    ]
   }
 };
 var PI_RUNTIME_REGISTRY = {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jorgex-stack",
-  "version": "1.2.3",
-  "description": "Harness multi-agente portable: instala la config JorgeX (agentes, skills, hooks, Engram, MCPs) en Claude Code, Codex CLI y OpenCode",
+  "version": "1.3.0",
+  "description": "Harness multi-agente portable: instala la config JorgeX (agentes, skills, hooks, Engram, MCPs) en Claude Code, Codex CLI, OpenCode y Pi",
   "type": "module",
   "license": "MIT",
   "repository": {

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.