jorgex-stack 1.0.21 → 1.0.23

package/README.md

@@ -24,6 +24,8 @@ 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).
+
 ### Modes: Human and Programmatic
 
 `install` and `sync` accept two mutually-exclusive installation modes. The choice is global (not per runtime) and is saved in `~/.jorgex-stack/install-mode.json` on first run; subsequent `sync` calls reuse it. Re-run `install` with `--mode` to switch.

package/dist/cli.js

@@ -614,11 +614,17 @@ ${agent.body}`,
   planMainConfig(canonical, ctx) {
     const file = path7.join(ctx.configDir, "opencode.json");
     const { pluginsDir } = this.paths(ctx.configDir);
-    const content = upsertJson(readTextIfExists(file), (root) => {
+    const original = readTextIfExists(file);
+    const contentSource = original === null || original.trim() === "" ? null : original;
+    const isFreshConfig = contentSource === null;
+    const content = upsertJson(contentSource, (root) => {
       root["$schema"] ??= "https://opencode.ai/config.json";
       const defaults = loadCanonicalDefaults(ctx.stackDir)["opencode"];
-      if (defaults?.["permission"] !== void 0 && !("permission" in root)) {
+      if (isFreshConfig && defaults?.["permission"] !== void 0) {
         root["permission"] = defaults["permission"];
+        ctx.warnings.push(
+          "OpenCode: fresh config enables read-anywhere via external_directory:*; edits, web egress and arbitrary bash remain approval-gated, but broad local reads can expose secrets not covered by deny rules."
+        );
       }
       const mcp = root["mcp"] ??= {};
       for (const [name, server] of Object.entries(canonical.servers)) {
@@ -818,12 +824,19 @@ ${agent.body}`,
   planHooks(canonical, ctx) {
     const actions = [];
     const { scriptsDir } = this.paths(ctx.configDir);
+    const original = readTextIfExists(path8.join(ctx.configDir, "settings.json"));
+    const contentSource = original === null || original.trim() === "" ? null : original;
     const settingsFile = path8.join(ctx.configDir, "settings.json");
-    let content = upsertNativeHooks(readTextIfExists(settingsFile), canonical, scriptsDir);
+    let content = upsertNativeHooks(contentSource, canonical, scriptsDir);
     const defaults = loadCanonicalDefaults(ctx.stackDir)["claude-code"];
-    if (defaults?.["permissions"] !== void 0) {
+    if (contentSource === null && defaults?.["permissions"] !== void 0) {
       content = upsertJson(content, (root) => {
-        if (!("permissions" in root)) root["permissions"] = defaults["permissions"];
+        if (root["permissions"] === void 0) {
+          root["permissions"] = defaults["permissions"];
+          ctx.warnings.push(
+            "Claude Code: fresh config enables read-anywhere via Read/Grep/Glob allow rules; shell, writes and web egress remain approval-gated, but broad local reads can expose secrets not covered by deny rules."
+          );
+        }
       });
     }
     actions.push({ kind: "write", target: settingsFile, content });
@@ -1026,13 +1039,52 @@ ${body}`
   },
   planMainConfig(canonical, ctx) {
     const file = path9.join(ctx.configDir, "config.toml");
-    let content = readTextIfExists(file);
-    const defaults = loadCanonicalDefaults(ctx.stackDir)["codex"] ?? {};
-    for (const [key, value] of Object.entries(defaults)) {
-      if (content !== null && new RegExp(`^\\s*${key}\\s*=`, "m").test(content)) continue;
-      const line = `${key} = ${tomlString(String(value))}
+    const original = readTextIfExists(file);
+    const contentSource = original === null || original.trim() === "" ? null : original;
+    let content = contentSource;
+    if (contentSource === null) {
+      const defaults = loadCanonicalDefaults(ctx.stackDir)["codex"] ?? {};
+      for (const [key, value] of Object.entries(defaults)) {
+        const line = `${key} = ${tomlString(String(value))}
 `;
-      content = content === null ? line : line + content;
+        content = content === null ? line : line + content;
+      }
+      ctx.warnings.push(
+        "Codex: fresh config enables read-anywhere via the jorgex-read-anywhere permission profile; broad local reads can expose secrets not covered by deny rules."
+      );
+      content = upsertTomlSection(content, "permissions.jorgex-read-anywhere", 'extends = ":workspace"');
+      content = upsertTomlSection(
+        content,
+        "permissions.jorgex-read-anywhere.filesystem",
+        [
+          '":root" = "read"',
+          '"*.env" = "deny"',
+          '"*.env.*" = "deny"',
+          '"~/.ssh/**" = "deny"',
+          '"~/.aws/credentials" = "deny"',
+          '"~/.npmrc" = "deny"',
+          '"~/.git-credentials" = "deny"',
+          '"**/id_rsa" = "deny"',
+          '"**/id_ed25519" = "deny"',
+          '"**/*.pem" = "deny"',
+          '"**/*.key" = "deny"'
+        ].join("\n")
+      );
+      content += [
+        '\n[permissions.jorgex-read-anywhere.filesystem.":workspace_roots"]',
+        '"." = "write"',
+        '"*.env" = "deny"',
+        '"*.env.*" = "deny"',
+        '".ssh/**" = "deny"',
+        '".aws/credentials" = "deny"',
+        '".npmrc" = "deny"',
+        '".git-credentials" = "deny"',
+        '"**/id_rsa" = "deny"',
+        '"**/id_ed25519" = "deny"',
+        '"**/*.pem" = "deny"',
+        '"**/*.key" = "deny"',
+        ""
+      ].join("\n");
     }
     for (const [name, server] of Object.entries(canonical.servers)) {
       const section = `mcp_servers.${name}`;

package/package.json

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

@@ -29,5 +29,6 @@ Una sola fuente por agente. El instalador los traduce al formato de cada runtime
 ## Convenciones de contenido
 
 - Todo subagente termina con el **Result contract** (Status / Delegations / Risks) — el orchestrator lo procesa.
+- **Incertidumbre crítica no se improvisa**: si una decisión puede hacer la tarea incorrecta, el subagente devuelve `Status: blocked`/`partial` con **una pregunta concreta** al main agent/orchestrator dentro del Result contract; el trabajo de otro especialista sigue yendo como delegación normal. La regla completa está en la skill `agent-delegation`.
 - Las delegaciones usan el formato `→ [agent]: [work] — [paths] — [inputs]` (skill `agent-delegation`).
 - El flujo de trabajo lo define la skill `work-lifecycle`: `work/{nombre}/plan.md` es el tablero de estado y se mantiene entre merges intermedios; las specs de tareas (`work/{nombre}/task/{NN}`), los resultados de fase (`work/{nombre}/{fase}`), los checkpoints de PR (`work/{nombre}/pr/{NN}`) y el cierre final (`work/{nombre}/done`) viven en Engram. Los subagentes reciben topic_key + título, nunca la tarea inline.

package/stack/agents/implementer.md

@@ -13,7 +13,7 @@ You implement real changes. You don't stop at analysis, you don't answer with ju
 
 **Mandatory first action**: load the `agent-delegation` skill.
 
-**Never run destructive git** (`reset`, `clean`, `checkout --`, `restore`, `push --force`) — it can discard work or rewrite history. Commit forward; if you think you need to discard or reset repo state, stop and ask the user.
+**Never run destructive git** (`reset`, `clean`, `checkout --`, `restore`, `push --force`) — it can discard work or rewrite history. Commit forward; if you think you need to discard or reset repo state, stop and ask the main agent/orchestrator.
 
 **Conditional skill**:
 
@@ -26,6 +26,7 @@ You usually receive a clear design (often from an analyst), and the project's st
 1. **Confirm the libraries you'll actually use** when you're unsure of the exact one or its API: check `package.json` (or the equivalent manifest) and the touched files — e.g. state (Zustand, Redux), data-fetching (TanStack Query, SWR), forms, styling, ORM. Use each library's real API and patterns; don't hand-roll what a present library already does.
 2. **Mirror existing conventions**: look at the files you'll touch and their neighbors, and follow their style, patterns and imports. Don't introduce a new pattern without need.
 3. **Load `lean-code` before non-trivial code**: use it as the ladder before you add a helper, wrapper, abstraction, or dependency. Ask whether the code is needed at all, whether stdlib/native/project helpers already solve it, and whether a smaller change works.
+4. **For task-critical uncertainty, follow `agent-delegation`**: verify narrowly, do the safe part if it is clear, and route one concrete question to the main agent/orchestrator instead of improvising.
 
 ## Contract
 

package/stack/agents/orchestrator.md

@@ -19,7 +19,7 @@ INIT → EXPLORE → SPEC → PLAN → EXECUTE → VERIFY → SHIP → CLOSE
 
 ### Autonomy
 
-The human drives the flow UP TO the plan: the idea, the PRD review and the plan review are interactive. Once the plan is approved, EXECUTE → VERIFY → SHIP run **autonomously** — no questions, no confirmation pauses: plan approval authorizes commits, pushes to the work branch and the PR creation. Control returns to the user at CLOSE. Merging the PR is NEVER yours: it always requires an explicit user order. For multi-PR work, each merge is a checkpoint; keep `work/{name}/PRD.md` and `plan.md` alive until the roadmap is finished.
+The human drives the flow UP TO the plan: the idea, the PRD review and the plan review are interactive. Once the plan is approved, EXECUTE → VERIFY → SHIP run **autonomously** — no confirmation pauses: plan approval authorizes commits, pushes to the work branch and the PR creation. Task-critical uncertainty from a subagent is an operational blocker, not a pause in autonomy: answer from existing context first; only if the decision genuinely cannot be made from available context may you ask the user, then relaunch with explicit guidance. Control returns to the user at CLOSE. Merging the PR is NEVER yours: it always requires an explicit user order. For multi-PR work, each merge is a checkpoint; keep `work/{name}/PRD.md` and `plan.md` alive until the roadmap is finished.
 
 ## 1. INIT
 
@@ -109,6 +109,8 @@ Load the `agent-delegation` skill: it defines the available subagents, the scope
 Every subagent ends with a **Result contract** (Status / Delegations / Risks). Process it:
 
 - For each `→ [agent]: ...` line, launch the corresponding specialist.
+- If a subagent reports `partial`, keep the safe work and relaunch only what still needs guidance.
+- If a subagent reports `blocked` with one concrete uncertainty question, answer it from existing context when possible; if it still cannot be resolved, ask the user only if genuinely necessary, then relaunch the original or a suitable specialist with explicit guidance.
 - Don't declare a phase done while a delegation line remains unprocessed.
 - If Status is `partial` or `blocked`, resolve the cause before moving on.
 

package/stack/agents/tester.md

@@ -13,7 +13,7 @@ Your job is to describe behavior with tests, fix broken tests, and verify they f
 
 **Mandatory first action**: load the `tdd` and `agent-delegation` skills.
 
-**Never run destructive git** (`reset`, `clean`, `checkout --`, `restore`, `push --force`) — it can discard work or rewrite history. Commit forward; if you think you need to discard or reset repo state, stop and ask the user.
+**Never run destructive git** (`reset`, `clean`, `checkout --`, `restore`, `push --force`) — it can discard work or rewrite history. Commit forward; if you think you need to discard or reset repo state, stop and ask the main agent/orchestrator.
 
 ## Before writing tests
 
@@ -22,6 +22,8 @@ Don't assume a framework. The test command and conventions are often already in
 - **Runner and utilities**: `package.json` scripts/deps (vitest, jest, etc.), config files, or the language's standard tooling (pytest, go test, etc.).
 - **Existing tests**: mirror their file location, naming, assertion style and helpers. Don't invent a stack if the repo already has one.
 
+If task-critical uncertainty could make the task wrong, verify narrowly and follow `agent-delegation`: do the safe part when it is clear, then route one concrete question to the main agent/orchestrator instead of improvising.
+
 ## Scope
 
 - RED: write tests that fail first.

package/stack/agents/translator.md

@@ -13,7 +13,7 @@ You handle translations, multi-language text and integration with the project's
 
 **Mandatory first action**: load the `agent-delegation` skill.
 
-**Never run destructive git** (`reset`, `clean`, `checkout --`, `restore`, `push --force`) — it can discard work or rewrite history. Commit forward; if you think you need to discard or reset repo state, stop and ask the user.
+**Never run destructive git** (`reset`, `clean`, `checkout --`, `restore`, `push --force`) — it can discard work or rewrite history. Commit forward; if you think you need to discard or reset repo state, stop and ask the main agent/orchestrator.
 
 **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.
 
@@ -24,6 +24,8 @@ You handle translations, multi-language text and integration with the project's
 - sync locales
 - adapt copy across languages
 
+If task-critical uncertainty could make the text wrong, verify narrowly and follow `agent-delegation`: do the safe part when it is clear, then route one concrete question to the main agent/orchestrator instead of improvising.
+
 ## First: detect the real system
 
 Before translating, identify what exists:

package/stack/config/defaults.json

@@ -1,17 +1,36 @@
 {
-  "$comment": "Permisos por defecto del stack: casi todo permitido, lo destructivo pregunta o se bloquea. REGLA DE ORO: cada bloque se escribe SOLO si el usuario aún no tiene esa clave en su config — si ya la tiene (suya o ajustada después), el sync no la toca jamás. Quitar o editar estos valores tras el install es seguro: pasan a ser config del usuario.",
+  "$comment": "Permisos por defecto del stack: cada bloque se escribe SOLO en config fresca o vacía; una config existente no se auto-expande jamás. OpenCode fresh default permite leer fuera del cwd, pero deja edit/bash en ask salvo allow explícito para lecturas seguras.",
   "opencode": {
     "permission": {
-      "edit": "allow",
-      "read": "allow",
+      "edit": "ask",
+      "read": {
+        "*": "allow",
+        "*.env": "deny",
+        "*.env.*": "deny",
+        "*.env.example": "allow",
+        "*/.ssh/*": "deny",
+        "*/.aws/credentials": "deny",
+        "*/.npmrc": "deny",
+        "*/.git-credentials": "deny",
+        "*/id_rsa": "deny",
+        "*/id_ed25519": "deny",
+        "*.pem": "deny",
+        "*.key": "deny"
+      },
+      "external_directory": {
+        "*": "allow"
+      },
       "glob": "allow",
       "grep": "allow",
       "list": "allow",
       "lsp": "allow",
-      "webfetch": "allow",
-      "websearch": "allow",
+      "webfetch": "ask",
+      "websearch": "ask",
       "bash": {
-        "*": "allow",
+        "*": "ask",
+        "git diff*": "ask",
+        "git log*": "allow",
+        "git status*": "allow",
         "rm *": "ask",
         "del *": "ask",
         "rmdir *": "ask",
@@ -25,13 +44,28 @@
   },
   "claude-code": {
     "permissions": {
-      "allow": ["Bash", "Edit", "Write", "WebFetch", "WebSearch"],
-      "ask": ["Bash(rm:*)", "Bash(rmdir:*)", "Bash(del:*)", "Bash(git push --force:*)"],
-      "deny": ["Bash(format:*)", "Bash(mkfs:*)", "Bash(dd:*)", "Bash(shred:*)", "Read(./.env)", "Read(./.env.*)"]
+      "allow": ["Read", "Grep", "Glob"],
+      "ask": ["Bash", "Edit", "Write", "WebFetch", "WebSearch", "Bash(rm:*)", "Bash(rmdir:*)", "Bash(del:*)", "Bash(git push --force:*)"],
+      "deny": [
+        "Bash(format:*)",
+        "Bash(mkfs:*)",
+        "Bash(dd:*)",
+        "Bash(shred:*)",
+        "Read(//**/.env)",
+        "Read(//**/.env.*)",
+        "Read(//**/.ssh/**)",
+        "Read(//**/.aws/credentials)",
+        "Read(//**/.npmrc)",
+        "Read(//**/.git-credentials)",
+        "Read(//**/id_rsa)",
+        "Read(//**/id_ed25519)",
+        "Read(//**/*.pem)",
+        "Read(//**/*.key)"
+      ]
     }
   },
   "codex": {
     "approval_policy": "on-request",
-    "sandbox_mode": "workspace-write"
+    "default_permissions": "jorgex-read-anywhere"
   }
 }

package/stack/modes/programmatic/agent-delegation.addendum.md

@@ -6,3 +6,6 @@
 - Delegations must be strings in the final JSON `delegations[]` array, using `agent: work — paths — inputs`.
 - Do not emit Markdown delegation lines.
 - Use the strict final JSON handoff.
+- `delegations[]` is only for work that belongs to another specialist; uncertainty questions go in `summary` or `risks`, not in `delegations[]`.
+- If task-critical uncertainty could make the task wrong, set `status` to `blocked` and include one concrete question to the main agent/orchestrator, with what you checked and the decision needed.
+- If the safe path is clear, do the safe part and report the remainder as `partial`.

package/stack/modes/programmatic/orchestrator.addendum.md

@@ -6,6 +6,8 @@
 - The final assistant response must be exactly one strict JSON object.
 - Do not wrap the final JSON in Markdown fences or prose.
 - Process the final JSON object's `delegations[]` array; each item must be a string in the form `agent: work — paths — inputs`. Ignore Markdown delegation lines outside JSON.
+- If a subagent reports `partial`, keep the safe work and relaunch only what still needs guidance.
+- If a subagent reports `blocked` and includes one concrete question in `summary` or `risks`, answer it from existing context when possible; if it still cannot be resolved from context, ask the user only if genuinely necessary, then relaunch the original or a suitable specialist with explicit guidance.
 - Required keys: `status`, `decision`, `confidence`, `summary`, `risks`, `next_steps`, `delegations`.
 - `status` is one of `done`, `partial`, `blocked` and `decision` is a short string.
 - `confidence` is a number between 0 and 1.

package/stack/modes/programmatic/subagent.addendum.md

@@ -7,6 +7,8 @@
 - Return a terse, structured handoff that is easy to parse.
 - Use the strict final JSON handoff.
 - Any delegation must live in the JSON `delegations[]` array as a string in the form `agent: work — paths — inputs`; do not emit Markdown delegation lines outside JSON.
+- `delegations[]` is only for specialist work. If task-critical uncertainty could make the task wrong, set `status` to `blocked` and put one concrete question to the main agent/orchestrator in `summary` or `risks`, including what you checked and the decision needed.
+- If the safe path is clear, do the safe part and report the remainder as `partial`.
 - Required keys: `status`, `decision`, `confidence`, `summary`, `risks`, `next_steps`, `delegations`.
 - `status` is one of `done`, `partial`, `blocked`.
 - `risks`, `next_steps`, and `delegations` are arrays of strings.

package/stack/skills/agent-delegation/SKILL.md

@@ -9,11 +9,14 @@ description: Regla universal de delegación entre subagentes. Usar cuando durant
 
 Si durante tu tarea encuentras trabajo que pertenece a otro especialista, **no lo absorbas**. Haz solo tu parte y reporta el resto.
 
+If task-critical uncertainty is small, verify only what is needed. If the safe path is clear, do that part and report the rest as `partial`. If task-critical uncertainty can make the task wrong, stop before risky edits and return `blocked` with one concrete question to the main agent/orchestrator: what you checked, what decision is needed, and the recommended option or tradeoff if you know it. Do not improvise.
+
 Importante sobre el mecanismo:
 
 - Tú (subagente) **no lanzas a otros subagentes**. Solo el agente principal (orquestador) puede invocarlos.
 - No te salgas de tu scope para "ayudar". Si algo no te corresponde, lo dejas sin hacer y lo delegas.
 - Las delegaciones van **en tu output final**, en el formato de abajo. El orquestador las lee y decide a quién invocar.
+- `delegations` are only for work that belongs to another specialist; uncertainty questions are not delegations.
 
 ## Agentes disponibles