jorgex-stack 1.0.23 → 1.0.25

package/README.md

@@ -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.
 
-Permission defaults by runtime (what gets installed, what stays custom, and the read-anywhere limitations) are documented in [docs/references/permissions.md](docs/references/permissions.md).
+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.
 
 ### Modes: Human and Programmatic
 

package/dist/cli.js

@@ -179,21 +179,22 @@ function resolveAgentModel(models, agentName, tier) {
 }
 var DEFAULT_MODEL_MAP = {
   opencode: {
-    strong: { model: "openai/gpt-5.4", variant: "high" },
-    standard: { model: "openai/gpt-5.4-mini", variant: "high" },
-    cheap: { model: "minimax/MiniMax-M3" }
+    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" },
     cheap: { model: "haiku" }
   },
-  // Codex: "default" = no fijar modelo (usa el del CLI, que OpenAI actualiza
-  // solo — D6); variant → model_reasoning_effort.
+  // El primary (orchestrator) no usa estos tiers: tanto el profile de CLI como
+  // la skill de la app heredan el modelo elegido por el usuario. Estos defaults
+  // son solo para subagentes; variant → model_reasoning_effort.
   codex: {
-    strong: { model: "default", variant: "high" },
-    standard: { model: "default", variant: "medium" },
-    cheap: { model: "default", variant: "low" }
+    strong: { model: "gpt-5.6-terra", variant: "xhigh" },
+    standard: { model: "gpt-5.6-terra", variant: "xhigh" },
+    cheap: { model: "gpt-5.6-luna", variant: "medium" }
   }
 };
 function modelMapFile() {
@@ -2842,7 +2843,15 @@ import * as p5 from "@clack/prompts";
 var TIERS = ["strong", "standard", "cheap"];
 var EFFORTS = ["low", "medium", "high", "xhigh"];
 var CLAUDE_ALIASES = ["fable", "opus", "sonnet", "haiku", "inherit"];
-var CODEX_MODELS = ["default", "gpt-5.5", "gpt-5.4", "gpt-5.4-mini"];
+var CODEX_MODELS = [
+  "default",
+  "gpt-5.6-sol",
+  "gpt-5.6-terra",
+  "gpt-5.6-luna",
+  "gpt-5.5",
+  "gpt-5.4",
+  "gpt-5.4-mini"
+];
 var CODEX_CUSTOM = "__custom__";
 var CANCEL = /* @__PURE__ */ Symbol("cancel");
 function opencodeLiveModels(binPath) {

package/package.json

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