jorgex-stack 1.0.24 → 1.0.26

package/README.md

@@ -9,7 +9,7 @@ Portable multi-agent harness: one configuration source — 15 agents, 17 skills,
 Install and run via npm without cloning the repository:
 
 ```
-pnpm dlx jorgex-stack install    # apply config to your runtimes (interactive pick; idempotent, removes orphans)
+pnpm dlx jorgex-stack install    # install runtimes; first OpenCode setup selects connected models
 pnpm dlx jorgex-stack models     # model picker by runtime and tier (strong/standard/cheap)
 pnpm dlx jorgex-stack sync       # alias of install (same idempotent apply)
 pnpm dlx jorgex-stack doctor     # checks that everything is healthy (Engram, drift, hooks, keys)
@@ -24,7 +24,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 model selection, GPT-5.6 subagent tiers, and orchestrator inheritance.
+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.
 
 ### Modes: Human and Programmatic
 
@@ -52,6 +52,8 @@ Flags:
 
   This installs into all detected runtimes. To be explicit, add `--agents opencode,claude-code,codex` or a comma-separated subset. Always pass `--mode programmatic`; without `--mode`, `--yes` and non-TTY installs default to `human`.
 
+  OpenCode also requires an existing selection in `~/.jorgex-stack/model-map.json`; run `pnpm dlx jorgex-stack models --agents opencode` interactively once before a headless install.
+
 - `--mode human` cannot be combined with `--subagent-concurrency`.
 - Without `--mode`, the first run asks interactively; `--yes`, non-TTY, and `--target-dir` default to `human`.
 - `pnpm dlx jorgex-stack sync` reuses the saved mode; pass `--mode` to change and save the preference.

package/dist/cli.js

@@ -178,11 +178,6 @@ function resolveAgentModel(models, agentName, tier) {
   };
 }
 var DEFAULT_MODEL_MAP = {
-  opencode: {
-    strong: { model: "openai/gpt-5.6-terra", variant: "xhigh" },
-    standard: { model: "openai/gpt-5.6-terra", variant: "xhigh" },
-    cheap: { model: "openai/gpt-5.6-luna", variant: "medium" }
-  },
   "claude-code": {
     strong: { model: "fable" },
     standard: { model: "sonnet" },
@@ -209,7 +204,7 @@ function loadModelMap() {
   } catch {
     return DEFAULT_MODEL_MAP;
   }
-  const merged = {};
+  const merged = { ...fromDisk };
   for (const id of Object.keys(DEFAULT_MODEL_MAP)) {
     merged[id] = { ...DEFAULT_MODEL_MAP[id], ...fromDisk[id] ?? {} };
   }
@@ -1649,7 +1644,8 @@ async function runInstall(opts) {
     }
     const models = modelMap[id];
     if (!models) {
-      p.log.warn(`${adapter.name}: sin model-map para este runtime \u2014 omitido.`);
+      p.log.error(`${adapter.name}: sin modelos seleccionados \u2014 ejecuta 'jorgex-stack models --agents ${id}'.`);
+      exitCode = 1;
       continue;
     }
     const ctx = {
@@ -2867,8 +2863,12 @@ function agentsByTier() {
   }
   return grouped;
 }
+function isCompleteRuntimeModelMap(models) {
+  return TIERS.every((tier) => models[tier]?.model);
+}
 async function askModel(det, subject, current) {
   if (det.id === "codex") {
+    if (!current) throw new Error("Codex requiere un model-map base.");
     const effort = await p5.select({
       message: `${det.name} \xB7 ${subject} \u2014 reasoning effort`,
       options: EFFORTS.map((v) => ({ value: v, label: v })),
@@ -2902,16 +2902,18 @@ async function askModel(det, subject, current) {
   }
   const optionsList = det.options;
   const options = optionsList.map((m) => ({ value: m, label: m }));
-  if (!optionsList.includes(current.model)) options.unshift({ value: current.model, label: `${current.model} (actual)` });
+  if (current && !optionsList.includes(current.model)) {
+    options.unshift({ value: current.model, label: `${current.model} (actual)` });
+  }
   const choice = await p5.select({
     message: `${det.name} \xB7 ${subject} \u2014 modelo`,
     options,
-    initialValue: current.model,
+    initialValue: current?.model,
     maxItems: 12
   });
   if (p5.isCancel(choice)) return CANCEL;
   if (det.id === "claude-code") return { model: choice };
-  const keptCurrent = choice === current.model && current.variant ? current.variant : null;
+  const keptCurrent = current && choice === current.model && current.variant ? current.variant : null;
   const variant = await p5.select({
     message: `${det.name} \xB7 ${subject} \u2014 reasoning effort (variant; solo si el modelo lo soporta)`,
     options: [
@@ -2926,12 +2928,16 @@ async function askModel(det, subject, current) {
 }
 async function runModelsPicker(opts) {
   const file = ensureModelMapFile();
+  const map = loadModelMap();
   if (opts.yes || !process.stdout.isTTY) {
-    console.log(`Model-map en ${file} (defaults). Ed\xEDtalo o ejecuta 'models' sin --yes para el picker.`);
+    if (opts.runtimes.includes("opencode") && !map.opencode) {
+      console.error("OpenCode requiere selecci\xF3n interactiva desde los proveedores conectados; ejecuta 'models --agents opencode' sin --yes.");
+      return 1;
+    }
+    console.log(`Model-map en ${file}. Ed\xEDtalo o ejecuta 'models' sin --yes para el picker.`);
     return 0;
   }
   p5.intro("jorgex-stack models \u2014 modelos por tier o por subagente");
-  const map = loadModelMap();
   const grouped = agentsByTier();
   const tierLine = (tier) => grouped[tier].join(", ");
   const agentCount = TIERS.reduce((n, tier) => n + grouped[tier].length, 0);
@@ -2960,7 +2966,10 @@ async function runModelsPicker(opts) {
       p5.log.warn("OpenCode: no se pudo listar `opencode models` \u2014 se mantiene la selecci\xF3n actual.");
       continue;
     }
-    const runtimeMap = { ...map[det.id] };
+    const existingRuntimeMap = map[det.id];
+    const runtimeMap = {
+      ...existingRuntimeMap
+    };
     p5.log.message(
       `${det.name} \u2014 tiers y sus subagentes:
   strong   \u2192 ${tierLine("strong")}
@@ -2978,7 +2987,7 @@ async function runModelsPicker(opts) {
     if (p5.isCancel(mode)) return cancelled();
     if (mode === "tier") {
       for (const tier of TIERS) {
-        const asked = await askModel(det, `tier ${tier} (${tierLine(tier)})`, runtimeMap[tier]);
+        const asked = await askModel(det, `tier ${tier} (${tierLine(tier)})`, existingRuntimeMap?.[tier]);
         if (asked === CANCEL) return cancelled();
         runtimeMap[tier] = asked;
       }
@@ -2991,10 +3000,15 @@ async function runModelsPicker(opts) {
     } else {
       const overrides = { ...runtimeMap.overrides ?? {} };
       for (const tier of TIERS) {
-        const base = runtimeMap[tier];
+        let base = runtimeMap[tier];
         for (const name of grouped[tier]) {
-          const asked = await askModel(det, `${name} (tier ${tier})`, resolveAgentModel(runtimeMap, name, tier));
+          const current = existingRuntimeMap ? resolveAgentModel(existingRuntimeMap, name, tier) : void 0;
+          const asked = await askModel(det, `${name} (tier ${tier})`, current);
           if (asked === CANCEL) return cancelled();
+          if (!base) {
+            base = asked;
+            runtimeMap[tier] = base;
+          }
           const sameAsTier = asked.model === base.model && (asked.variant ?? "") === (base.variant ?? "");
           if (sameAsTier) {
             delete overrides[name];
@@ -3009,6 +3023,9 @@ async function runModelsPicker(opts) {
       if (Object.keys(overrides).length > 0) runtimeMap.overrides = overrides;
       else delete runtimeMap.overrides;
     }
+    if (!isCompleteRuntimeModelMap(runtimeMap)) {
+      throw new Error(`${det.name}: selecci\xF3n de modelos incompleta.`);
+    }
     map[det.id] = runtimeMap;
   }
   writeText(file, JSON.stringify(map, null, 2) + "\n");
@@ -3052,6 +3069,18 @@ function readPackageMetadata() {
 // src/cli.ts
 var VERSION = readPackageVersion();
 var COMMANDS = ["install", "sync", "models", "update", "doctor", "restore", "uninstall"];
+async function ensureOpenCodeModelsForInstall(command, flags, runtimes) {
+  if (!runtimes.includes("opencode") || loadModelMap().opencode) return true;
+  const canPrompt = command === "install" && !flags.yes && !flags.dryRun && process.stdout.isTTY;
+  if (canPrompt) {
+    const code = await runModelsPicker({ yes: false, runtimes: ["opencode"] });
+    if (code === 0 && loadModelMap().opencode) return true;
+  }
+  console.error(
+    "OpenCode no tiene modelos configurados. Ejecuta 'jorgex-stack models --agents opencode' de forma interactiva antes de install/sync."
+  );
+  return false;
+}
 function parseFlags(args) {
   const flags = {
     agents: [],
@@ -3204,9 +3233,9 @@ function printHelp() {
 Uso: pnpm dlx jorgex-stack [comando] [opciones]
 
 Comandos:
-  install     Instala el stack en los runtimes elegidos (default, interactivo)
-  sync        Re-aplica la config (idempotente; alias de install)
-  models      Picker de modelos por tier (OpenCode: lista en vivo de 'opencode models')
+  install     Instala el stack; OpenCode fresh exige elegir modelos conectados
+  sync        Re-aplica la config y el model-map existente (idempotente; sin picker)
+  models      Picker por tier o subagente (OpenCode: 'opencode models' en vivo)
   update      --check: compara stack/Engram/skills con sus upstreams
   doctor      Estado: Engram, drift de config, hooks de Codex, key de context7
   restore     --list para ver backups \xB7 'restore <id>' para restaurar
@@ -3266,6 +3295,10 @@ Flags disponibles: jorgex-stack --help`
         process.exitCode = 1;
         return;
       }
+      if (!await ensureOpenCodeModelsForInstall(command, flags, runtimes)) {
+        process.exitCode = 1;
+        return;
+      }
       process.exitCode = await runInstall({ runtimes, targetDir: flags.targetDir, dryRun: flags.dryRun, yes: flags.yes, mode });
       return;
     }

package/package.json

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

package/stack/agents/orchestrator.md

@@ -99,7 +99,7 @@ The `work-lifecycle` skill is the single source of this flow. Summary — every
 - `work/{name}/` (gitignored, exists only while the work is in progress) holds the human-reviewed artifacts: `PRD.md` and `plan.md`. They stay resident across intermediate PR merges; `plan.md` is the ONLY task status board — flip statuses with surgical edits; don't re-read the whole plan after every task (re-read it on resume).
 - The full spec of each atomic task → Engram, one `mem_save` per task under `work/{name}/task/{NN}`. When you delegate a task, pass the subagent its topic_key + title — never the task content inline; it retrieves the spec itself.
 - Phase outcomes, decisions and PR checkpoints → Engram under `work/{name}/{phase}` and `work/{name}/pr/{NN}`; tell each subagent which topic_key to use for its saves.
-- Pending work → the project's single `work/backlog` topic_key (one upserted list), or issues (`to-issues`) if the project uses a tracker. Never a TODOs folder.
+- Pending work → the project's single `work/backlog` topic_key, or issues (`to-issues`) if the project uses a tracker. Never a TODOs folder. For Engram, you are the **single writer**: before every change, retrieve the exact observation with `mem_get_observation`, preserve unrelated entries, send the complete content with `mem_update`, then read it again to verify. Never write it concurrently or use a blind topic-key upsert. Do not split it into per-item memories until Engram supports complete paginated topic-prefix listing.
 - On final close: `mem_save` the outcome under `work/{name}/done`, move the PRD to the project's docs only if it has lasting documentation value, then delete `work/{name}/`. `work/{name}/done` is only for the last PR / final outcome. History is memory + git.
 
 ## Delegation map
@@ -173,7 +173,7 @@ When the plan is fully applied and VERIFY passes:
    - **Critical Issues (must fix)**: apply ALL of them — the PR must not reach merge with these open.
    - **Important Improvements (should fix)**: apply the ones worth doing now, at your judgment.
    - **Suggestions (nice to have)**: apply only if trivial and safe.
-3. Every finding you decide NOT to apply now goes to the project's `work/backlog` single topic_key — one line each: what + why deferred.
+3. Every finding you decide NOT to apply now goes to the project's `work/backlog` single topic_key — one line each: what + why deferred. Apply the safe serialized backlog protocol above; subagents only return candidate lines.
 4. For what you DO apply: add the new tasks to plan.md and one `mem_save` per task spec, execute them as in EXECUTE, re-verify, and push the fixes to the PR branch.
 5. The review fires once per PR creation — pushing fixes does not re-trigger it. Re-run `/xreview` only if the fixes were large.
 

package/stack/skills/work-lifecycle/SKILL.md

@@ -21,7 +21,7 @@ Every piece of work gets a **canonical kebab-case name** when it starts (e.g. `c
 | PR checkpoint outcome | Engram `work/{name}/pr/{NN}` | Intermediate PR merge record |
 | Phase outcomes, decisions, findings | Engram `work/{name}/{phase}` | History — must survive the folder and compactions |
 | Final outcome | Engram `work/{name}/done` | Permanent record of what shipped after the last PR |
-| Pending / backlog items | Engram `work/backlog` — ONE key per project | All pending ideas in a single upserted list |
+| Pending / backlog items | Engram `work/backlog` — ONE key per project | All pending ideas in one serialized list |
 
 `work/` is **scaffolding, not product**: add it to the project's `.gitignore`. It contains ONLY work in progress — an empty `work/` means nothing is half-done. No `1-TODOs/`, no `3-finalized/`, no phase subfolders.
 
@@ -51,7 +51,18 @@ When presenting the PRD or the plan for human review on non-trivial work, OFFER
 
 ## Pending work (backlog)
 
-All pending or future work of a project lives under the SINGLE topic_key `work/backlog` (upsert): one list, each item a short title + one-liner. Never one topic_key per idea, never a TODOs folder. When an item starts, it graduates: remove it from the backlog and create its `work/{name}/`. Review findings deliberately NOT applied also land here, one line each (what + why deferred).
+All pending or future work of a project lives under the SINGLE topic_key `work/backlog`: one list, each item a short title + one-liner. Never one topic_key per idea, never a TODOs folder. When an item starts, it graduates: remove it from the backlog and create its `work/{name}/`. Review findings deliberately NOT applied also land here, one line each (what + why deferred).
+
+### Safe backlog mutation
+
+Engram replaces an observation's complete content on both `mem_update` and a `mem_save` topic-key upsert. Until Engram offers complete, paginated listing by topic-key prefix, use this serialized protocol for every backlog add, edit or removal:
+
+1. The active coordinator/orchestrator is the **single writer**. Subagents return candidate backlog lines; they never mutate `work/backlog` themselves. Never run backlog writes concurrently.
+2. Find the exact `work/backlog` observation, then call `mem_get_observation` to read its full, untruncated content. If it does not exist, create it once with `mem_save`.
+3. Change only the intended lines while preserving every unrelated entry, then call `mem_update` on that exact observation ID with the **complete content**. Never send only the delta and never use a blind `mem_save` upsert for an existing backlog.
+4. Call `mem_get_observation` again and **verify** both the intended change and the preserved entries.
+
+Engram has no atomic append or compare-and-swap, so concurrent writers can still lose data even if both read first. Do not split items into `work/backlog/{slug}` yet: `mem_search` is capped and has no paginated topic-prefix listing, so older active items could become invisible. Once that capability exists, one observation per item is the preferred migration. If the project has an issue tracker, use issues instead now and do not keep an Engram backlog too.
 
 If the project manages work through an issue tracker, issues (`to-issues`) take this role instead — don't keep both.
 
@@ -91,6 +102,7 @@ For single-PR work, the PR checkpoint and final work close happen together: one
 - Don't mix several distinct pieces of work under the same name/topic_key.
 - Same evolving phase → same topic_key (upsert). Different phases and different tasks must not overwrite each other.
 - Never persist the same artifact in two homes — no file + memory copies, no hybrid writes.
+- Treat `work/backlog` as the exceptional serialized list described above; ordinary topic-key upserts are not a safe substitute for its read-modify-write protocol.
 
 ## Legacy `work/` folders
 

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

@@ -161,7 +161,7 @@ Status, wave and dependencies live in the plan.md table (single home) — do NOT
 
 ## Backlog entry — Template (`work/backlog`)
 
-ONE observation per project holds every pending idea (topic_key `work/backlog`, upserted). Each item is just:
+ONE observation per project holds every pending idea (topic_key `work/backlog`). Each item is just:
 
 ```markdown
 - **[short title]** — [one-line description of the idea and its value]
@@ -169,6 +169,8 @@ ONE observation per project holds every pending idea (topic_key `work/backlog`,
 
 When an item starts, remove it from this list and create its `work/[name]/`.
 
+Mutation is serialized: the coordinator is the single writer, reads the exact observation with `mem_get_observation`, preserves all unrelated lines, sends the complete content through `mem_update`, then reads it again to verify. Never send a delta or use a blind topic-key upsert. See **Safe backlog mutation** in the parent skill for the full protocol and the current reason not to use one observation per item.
+
 ---
 
 ## Task creation rules

package/stack/system-prompt/AGENTS.md

@@ -93,7 +93,7 @@ Every piece of information about a piece of work has exactly ONE home — never
 - In-progress work lives in `work/{name}/` (gitignored): `PRD.md` + `plan.md`. They stay there across intermediate PR merges; `plan.md` is the ONLY task status board — update statuses with surgical edits. An empty `work/` means nothing is half-done.
 - Execution worktrees and their branches always use the same name. Resolve the root with `git rev-parse --show-toplevel`, ensure `worktrees/` is ignored in the repo-local `.git/info/exclude`, then create/use `<project-root>/worktrees/<canonical-name>` for single-PR work or `<project-root>/worktrees/<canonical-name>-prNN` for multi-PR checkpoints; never create worktrees next to the repo, in the repo root, under `work/`, or in external temp/shared folders.
 - Full task specs, phase outcomes, PR checkpoints and history live in Engram: `work/{name}/task/{NN}`, `work/{name}/{phase}`, `work/{name}/pr/{NN}`, `work/{name}/done`. Subagents receive a topic_key + title, never the task content inline.
-- Pending work: the project's single `work/backlog` topic_key (one upserted list — never one key per idea), or issues (`to-issues`) if the project uses a tracker. Never a TODOs folder.
+- Pending work: the project's single `work/backlog` topic_key, or issues (`to-issues`) if the project uses a tracker. Never a TODOs folder. The coordinator/orchestrator is its **single writer**: retrieve the exact observation with `mem_get_observation`, preserve unrelated entries, send the complete content with `mem_update`, then read it again to verify; never mutate it concurrently or use a blind topic-key upsert. Do not split it into one memory per item until Engram supports complete paginated topic-prefix listing.
 - On intermediate PR merge: save the checkpoint under `work/{name}/pr/{NN}` and keep `work/{name}/` alive for the remaining PRs.
 - On final close: save the outcome under `work/{name}/done`, move the PRD to the project's docs only if it has lasting value, then delete `work/{name}/`. `work/{name}/done` is the final outcome only. History is memory + git — no archive folders.
 

package/stack/system-prompt/engram-protocol.md

@@ -42,6 +42,8 @@ Use the `engram` subagent for non-trivial memory reads — it filters and return
 
 Work tracking follows the `work-lifecycle` skill: `work/{name}/plan.md` (file) is the only status board; memory holds the task specs (`work/{name}/task/{NN}`), phase outcomes (`work/{name}/{phase}`), PR checkpoints (`work/{name}/pr/{NN}`), and the final outcome in `work/{name}/done` only after the last PR; the project backlog stays under the single key `work/backlog`. Subagents retrieve their task by the topic_key the orchestrator passes them and save their phase outcome under the topic_key they were given BEFORE their final report.
 
+`work/backlog` has a stricter mutation rule because Engram replaces complete content rather than applying a patch. The coordinator/orchestrator is the **single writer**; subagents only return candidates. Before every add, edit or removal, locate the exact observation and call `mem_get_observation`; preserve all unrelated entries, pass the complete content to `mem_update`, then read it again to verify. Never write it concurrently and never use a blind `mem_save` upsert. Separate `work/backlog/{slug}` memories are not safe yet because Engram lacks complete paginated topic-prefix listing; use tracker issues instead when available.
+
 ## Before ending a session
 
 Call `mem_session_summary` with: Goal, Instructions, Discoveries, Accomplished, Next Steps, Relevant Files. This is NOT optional — without it the next session starts blind.