jorgex-stack 1.0.13 → 1.0.15

package/README.md

@@ -71,7 +71,7 @@ Operational state:
 
 ## Status
 
-The CLI is complete and the real migration has been executed (F6); the stack is the only configuration source. Versions are published automatically to [npm](https://www.npmjs.com/package/jorgex-stack) according to the flow described in [Publishing](#publishing). The design, decisions (D1-D9), and roadmap are in [PRD.md](PRD.md).
+The CLI is complete and the real migration has been executed; the stack is the only configuration source. Versions are published automatically to [npm](https://www.npmjs.com/package/jorgex-stack) according to the flow described in [Publishing](#publishing).
 
 ## Publishing
 
@@ -79,12 +79,10 @@ Releases are triggered by push/merge to `main` and GitHub Actions; there is also
 
 - **Automatic patch**: if the push to `main` contains publishable changes and the current `package.json` version already exists on npm, the workflow finds the first free patch (`x+1`, `x+2`, ...), commits `chore(release): bump version to v...`, and publishes. If tag `v<package.version>` already exists, it uses that point as the accumulated base; otherwise, it falls back to `github.event.before`. Obsolete runs are aborted after `git fetch origin main --tags` if `origin/main` no longer matches `GITHUB_SHA`.
 - **Manual recovery**: a manual run on `main` with `release_sha` publishes that SHA if it does not exist on npm yet, without bumping again; if the version already exists on npm but tag `v<version>` is missing, the workflow fails and forces a rerun with `release_sha=<published sha>` to avoid tagging `origin/main`. `release_sha` must be a full 40-hex SHA and belong to `main`; mutable refs (`main`, tags, `main~1`) are rejected. If you do not pass `release_sha`, `validate` resolves `origin/main` once, exposes it as `target_sha`, and `bump` uses that validated SHA. Recovery does not bypass the `.github/workflows/*` guard: if the diff mixes workflows with publishable changes, split the release or perform the tag/publish manually with elevated permissions. If there is no reachable previous release tag to reconstruct the range, the workflow fails closed and requires manual intervention.
-- **No release**: changes only in `work/`, `worktrees/`, tests, or files not listed as publishable (`src/`, `stack/`, `upstreams.json`, `package.json`, `pnpm-lock.yaml`, `tsconfig.json`, `tsup.config.ts`, `README.md`, `PRD.md`) do not create a release.
+- **No release**: changes only in `work/`, `worktrees/`, tests, or docs (`README.md`, `docs/`) do not create a release. The publishable set that does trigger one is `src/`, `stack/`, `upstreams.json`, `package.json`, `pnpm-lock.yaml`, `tsconfig.json`, and `tsup.config.ts`.
 - **Manual minor and major**: explicit bump in `package.json` in the PR (the workflow detects that the next patch already exists on npm and requires the bump).
 - **OIDC / trusted publishing**: the publishing job uses `id-token: write` and `setup-node` `registry-url`; the bump/push job only has `contents: write`; `tag-release` only writes `contents` and does not use OIDC. There is no `NPM_TOKEN` or `NODE_AUTH_TOKEN` in any secret. `tag-release` only runs if `publish` was `success` or `skipped` with `tag_needed=true`, and keeps its SHA validation as the final defense. The only exception to the "always pnpm" rule is `npm pack --dry-run --ignore-scripts` and `npm publish --ignore-scripts --provenance` in the final step, for registry compatibility and hardening.
 
-Design details are in [PRD §7.6](PRD.md).
-
 ## Development
 
 Requirements: Node >= 22.5 and pnpm (never npm). Goal Mode uses `node:sqlite` in tests/Node CLI and OpenCode uses `bun:sqlite` at runtime.

package/dist/cli.js

@@ -1323,6 +1323,7 @@ function planPlugins(adapter, ctx) {
       );
       content = content.replace(/"\{\{ENGRAM_PROTOCOL\}\}"/g, JSON.stringify(protocol));
     }
+    content = content.replace(/(from\s+["'])(\.{1,2}\/[^"']+?)\.js(["'])/g, "$1$2.ts$3");
     if (content === raw) return { kind: "copy", source: sourceFile, target };
     return { kind: "write", target, content };
   });

package/package.json

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

@@ -116,7 +116,9 @@ Every subagent ends with a **Result contract** (Status / Delegations / Risks). P
 
 ### Worktree
 
-Before the first task, create a git worktree for this work (branch = canonical name) and run the ENTIRE execution inside it — implementation, tests, commits and pushes happen there, never on the user's main checkout.
+Before the first task, create a git worktree for this work and run the ENTIRE execution inside it — implementation, tests, commits and pushes happen there, never on the user's main checkout.
+
+Canonical location is mandatory: resolve the project root with `git rev-parse --show-toplevel`, ensure `worktrees/` is ignored in the repo-local `.git/info/exclude`, create `worktrees/` inside that root if needed, and create the worktree at `<project-root>/worktrees/<canonical-name>` (branch = canonical name). Do not create worktrees next to the repo, in the repo root, under `work/`, or in any external temp/shared folder.
 
 Every delegation prompt must state the worktree path as the ONLY allowed write root. After each writer subagent finishes, verify the user's main checkout is still clean (`git status` there); if the subagent wrote outside the worktree, STOP, move those changes into the worktree (patch/apply) and restore the main checkout before continuing. Subagent obedience is not a safety boundary — this check is.
 

package/stack/plugins/opencode/engram.ts

@@ -16,12 +16,30 @@
 
 import type { Plugin } from "@opencode-ai/plugin"
 
+declare const Bun: {
+  which?: (bin: string) => string | null
+  spawnSync: (args: string[]) => { exitCode: number; stdout?: { toString(): string } | string }
+  spawn: (args: string[], options?: Record<string, unknown>) => unknown
+  file: (path: string) => { exists: () => Promise<boolean> }
+}
+
 // ─── Configuration ───────────────────────────────────────────────────────────
 
 const ENGRAM_PORT = parseInt(process.env.ENGRAM_PORT ?? "7437")
 const ENGRAM_URL = `http://127.0.0.1:${ENGRAM_PORT}`
 // "{{ENGRAM_BIN}}" lo resuelve el instalador con el binario detectado (D7).
-const ENGRAM_BIN = process.env.ENGRAM_BIN ?? Bun.which("engram") ?? "{{ENGRAM_BIN}}"
+const ENGRAM_BIN = "{{ENGRAM_BIN}}"
+
+export function resolveEngramBin(installerBin = ENGRAM_BIN): string {
+  const envBin = process.env.ENGRAM_BIN
+  if (envBin) return envBin
+
+  const bun = globalThis as typeof globalThis & { Bun?: { which?: (bin: string) => string | null } }
+  const bunBin = bun.Bun?.which?.("engram")
+  if (bunBin) return bunBin
+
+  return installerBin !== "{{ENGRAM_BIN}}" ? installerBin : "engram"
+}
 
 // Engram's own MCP tools — don't count these as "tool calls" for session stats
 const ENGRAM_TOOLS = new Set([
@@ -60,6 +78,7 @@ async function engramFetch(
       headers: opts.body ? { "Content-Type": "application/json" } : undefined,
       body: opts.body ? JSON.stringify(opts.body) : undefined,
     })
+    if (!res.ok) return null
     return await res.json()
   } catch {
     // Engram server not running — silently fail
@@ -126,6 +145,7 @@ function stripPrivateTags(str: string): string {
 export const Engram: Plugin = async (ctx) => {
   const oldProject = ctx.directory.split(/[\\/]/).pop() ?? "unknown"
   const project = extractProjectName(ctx.directory)
+  const engramBin = resolveEngramBin()
 
   // Track tool counts per session (in-memory only, not critical)
   const toolCounts = new Map<string, number>()
@@ -145,12 +165,12 @@ export const Engram: Plugin = async (ctx) => {
    *
    * Silently skips sub-agent sessions (tracked in `subAgentSessions`).
    */
-  async function ensureSession(sessionId: string): Promise<void> {
-    if (!sessionId || knownSessions.has(sessionId)) return
+  async function ensureSession(sessionId: string): Promise<boolean> {
+    if (!sessionId) return false
+    if (knownSessions.has(sessionId)) return true
     // Do not register sub-agent sessions in Engram (issue #116).
-    if (subAgentSessions.has(sessionId)) return
-    knownSessions.add(sessionId)
-    await engramFetch("/sessions", {
+    if (subAgentSessions.has(sessionId)) return false
+    const session = await engramFetch("/sessions", {
       method: "POST",
       body: {
         id: sessionId,
@@ -158,13 +178,18 @@ export const Engram: Plugin = async (ctx) => {
         directory: ctx.directory,
       },
     })
+
+    if (session === null) return false
+
+    knownSessions.add(sessionId)
+    return true
   }
 
   // Try to start engram server if not running
   const running = await isEngramRunning()
   if (!running) {
     try {
-      Bun.spawn([ENGRAM_BIN, "serve"], {
+      Bun.spawn([engramBin, "serve"], {
         stdout: "ignore",
         stderr: "ignore",
         stdin: "ignore",
@@ -192,7 +217,7 @@ export const Engram: Plugin = async (ctx) => {
     const manifestFile = `${ctx.directory}/.engram/manifest.json`
     const file = Bun.file(manifestFile)
     if (await file.exists()) {
-      Bun.spawn([ENGRAM_BIN, "sync", "--import"], {
+      Bun.spawn([engramBin, "sync", "--import"], {
         cwd: ctx.directory,
         stdout: "ignore",
         stderr: "ignore",
@@ -206,7 +231,7 @@ export const Engram: Plugin = async (ctx) => {
   return {
     // ─── Event Listeners ───────────────────────────────────────────
 
-    event: async ({ event }) => {
+    event: async ({ event }: { event: { type: string; properties?: unknown } }) => {
       // --- Session Created ---
       if (event.type === "session.created") {
         // Bug fix (#116): session data is nested under event.properties.info,
@@ -254,7 +279,7 @@ export const Engram: Plugin = async (ctx) => {
     // output.message is typed as UserMessage (role:"user" already guaranteed).
     // output.parts contains TextPart[] with the actual message text.
 
-    "chat.message": async (input, output) => {
+    "chat.message": async (input: any, output: any) => {
       // Skip sub-agent sessions — they inflate session counts (issue #116)
       if (subAgentSessions.has(input.sessionID)) return
 
@@ -262,8 +287,8 @@ export const Engram: Plugin = async (ctx) => {
 
       // Extract text from parts (type:"text")
       const content = output.parts
-        .filter((p) => p.type === "text")
-        .map((p) => (p as any).text ?? "")
+        .filter((p: any) => p.type === "text")
+        .map((p: any) => p.text ?? "")
         .join("\n")
         .trim()
 
@@ -276,15 +301,17 @@ export const Engram: Plugin = async (ctx) => {
 
       // Only capture non-trivial prompts (>10 chars)
       if (finalContent.length > 10) {
-        await ensureSession(sessionId)
-        await engramFetch("/prompts", {
-          method: "POST",
-          body: {
-            session_id: sessionId,
-            content: stripPrivateTags(truncate(finalContent, 2000)),
-            project,
-          },
-        })
+        const sessionReady = await ensureSession(sessionId)
+        if (sessionReady) {
+          await engramFetch("/prompts", {
+            method: "POST",
+            body: {
+              session_id: sessionId,
+              content: stripPrivateTags(truncate(finalContent, 2000)),
+              project,
+            },
+          })
+        }
       }
     },
 
@@ -294,13 +321,13 @@ export const Engram: Plugin = async (ctx) => {
     // Passive capture: when a Task tool completes, POST its output to
     // the passive capture endpoint so the server extracts learnings.
 
-    "tool.execute.after": async (input, output) => {
+    "tool.execute.after": async (input: any, output: any) => {
       if (ENGRAM_TOOLS.has(input.tool.toLowerCase())) return
 
       // input.sessionID comes from OpenCode — always available
       const sessionId = input.sessionID
-      if (sessionId) {
-        await ensureSession(sessionId)
+      const sessionReady = sessionId ? await ensureSession(sessionId) : false
+      if (sessionReady && sessionId) {
         toolCounts.set(sessionId, (toolCounts.get(sessionId) ?? 0) + 1)
       }
 
@@ -308,7 +335,7 @@ export const Engram: Plugin = async (ctx) => {
       // (OpenCode reports the tool name in lowercase: "task")
       if (input.tool.toLowerCase() === "task" && output && sessionId) {
         const text = typeof output === "string" ? output : JSON.stringify(output)
-        if (text.length > 50) {
+        if (text.length > 50 && sessionReady) {
           await engramFetch("/observations/passive", {
             method: "POST",
             body: {
@@ -332,7 +359,7 @@ export const Engram: Plugin = async (ctx) => {
     // block at the beginning. By concatenating, we avoid adding extra system
     // messages that would break these models. See: GitHub issue #23.
 
-    "experimental.chat.system.transform": async (_input, output) => {
+    "experimental.chat.system.transform": async (_input: any, output: any) => {
       if (output.system.length > 0) {
         output.system[output.system.length - 1] += "\n\n" + MEMORY_INSTRUCTIONS
       } else {
@@ -348,7 +375,7 @@ export const Engram: Plugin = async (ctx) => {
     // 2. Inject context from previous sessions into the compaction prompt
     // 3. Tell the compressor to remind the new agent to save memories
 
-    "experimental.session.compacting": async (input, output) => {
+    "experimental.session.compacting": async (input: any, output: any) => {
       if (input.sessionID) {
         await ensureSession(input.sessionID)
       }

package/stack/plugins/opencode/worktree.ts

@@ -1,4 +1,5 @@
 import type { Plugin } from "@opencode-ai/plugin";
+import path from "node:path";
 
 interface WorktreePluginConfig {
   setupScript?: string;
@@ -19,12 +20,22 @@ interface ScriptResult {
 const isAbsolutePath = (value: string) =>
   /^[a-zA-Z]:[\\/]/.test(value) || value.startsWith("/");
 
+const isWindowsPath = (value: string) => /^[a-zA-Z]:[\\/]/.test(value);
+
+const toSlashes = (value: string) => value.replace(/\\/g, "/");
+
 const joinProjectPath = (directory: string, target: string) => {
-  const normalizedDirectory = directory.replace(/[\\/]+$/, "");
-  const normalizedTarget = target.replace(/^[\\/]+/, "").replace(/\\/g, "/");
+  const normalizedDirectory = toSlashes(directory).replace(/[\\/]+$/, "");
+  const normalizedTarget = toSlashes(target).replace(/^[\\/]+/, "");
   return `${normalizedDirectory}/${normalizedTarget}`;
 };
 
+const resolvePath = (base: string, target: string) => {
+  const api = isWindowsPath(base) || isWindowsPath(target) ? path.win32 : path.posix;
+  const resolved = api.resolve(base, target);
+  return toSlashes(resolved);
+};
+
 const resolveProjectPath = (directory: string, target?: string) => {
   if (!target) return undefined;
   return isAbsolutePath(target) ? target : joinProjectPath(directory, target);
@@ -250,10 +261,28 @@ const parseWorktreePath = (command: string) => {
 };
 
 const getWorktreeName = (worktreePath: string) => {
-  const segments = worktreePath.replace(/\\/g, "/").split("/").filter(Boolean);
+  const segments = toSlashes(worktreePath).split("/").filter(Boolean);
   return segments[segments.length - 1] || null;
 };
 
+const normalizePath = (value: string) =>
+  toSlashes(value).replace(/\/+$/, "");
+
+const samePath = (left: string, right: string) => {
+  const normalizedLeft = normalizePath(left);
+  const normalizedRight = normalizePath(right);
+  if (isWindowsPath(normalizedLeft) || isWindowsPath(normalizedRight)) {
+    return normalizedLeft.toLowerCase() === normalizedRight.toLowerCase();
+  }
+  return normalizedLeft === normalizedRight;
+};
+
+const getCommandCwd = (args: Record<string, unknown>, directory: string) => {
+  const cwd = args.workdir || args.cwd;
+  if (typeof cwd !== "string" || cwd.length === 0) return directory;
+  return isAbsolutePath(cwd) ? cwd : resolvePath(directory, cwd);
+};
+
 const replaceToken = (value: string, token: string, replacement: string) =>
   value.split(token).join(replacement);
 
@@ -313,14 +342,11 @@ export const WorktreePlugin: Plugin = async ({ $, client, directory }) => {
         const args = input.args || {};
         const command = args.command || "";
         const commandLower = command.toLowerCase();
-        const pathContains = (
-          config.pathContains || "worktrees/"
+        const pathContains = toSlashes(
+          config.pathContains || "worktrees/",
         ).toLowerCase();
 
-        if (
-          !commandLower.includes("git worktree add") ||
-          !commandLower.includes(pathContains)
-        ) {
+        if (!commandLower.includes("git worktree add")) {
           return;
         }
 
@@ -334,9 +360,25 @@ export const WorktreePlugin: Plugin = async ({ $, client, directory }) => {
 
         const gitRoot = await $`git rev-parse --show-toplevel`.text();
         const projectRoot = String(gitRoot).trim().replace(/\\/g, "/");
-        const absoluteWorktreePath = isAbsolutePath(parsedWorktreePath)
-          ? parsedWorktreePath.replace(/\\/g, "/")
-          : joinProjectPath(projectRoot, parsedWorktreePath);
+        const commandCwd = getCommandCwd(args, directory);
+        const absoluteWorktreePath = resolvePath(commandCwd, parsedWorktreePath);
+        const expectedWorktreePath = joinProjectPath(
+          projectRoot,
+          `worktrees/${worktreeName}`,
+        );
+
+        if (!samePath(absoluteWorktreePath, expectedWorktreePath)) {
+          appendToolOutput(output, [
+            `Worktree path is not canonical: ${absoluteWorktreePath}`,
+            `Use the project-local path instead: ${expectedWorktreePath}`,
+            "Canonical rule: <project-root>/worktrees/<canonical-name>.",
+          ]);
+          return;
+        }
+
+        if (!normalizePath(absoluteWorktreePath).toLowerCase().includes(pathContains)) {
+          return;
+        }
 
         const setupScript = resolveProjectPath(directory, config.setupScript);
         if (setupScript) {

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

@@ -33,7 +33,8 @@ Every piece of work gets a **canonical kebab-case name** when it starts (e.g. `c
 
 ## Executing
 
-- Execution happens inside a git worktree created for the work (branch = canonical name); the user's main checkout stays untouched until merge.
+- Execution happens inside a git worktree created for the work; the user's main checkout stays untouched until merge.
+- Worktree path is fixed: first resolve the project 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>` (branch = canonical name). Never place worktrees in the repo root, next to the repo, under `work/`, or outside the project.
 - Delegation handoff: the subagent receives its **topic_key + task title**, never the task content inline. It retrieves the spec itself (`mem_search` → `mem_get_observation`).
 - The subagent saves its phase outcome under the topic_key the orchestrator gave it (`work/{name}/{phase}`) BEFORE its final report.
 - Task status lives ONLY in the plan.md table: flip it (⬜ → ✅) with a surgical edit when the task closes. Do not mirror statuses into memory, and do not re-read the whole plan after every task — it is already in context; re-read it on resume.

package/stack/system-prompt/AGENTS.md

@@ -91,6 +91,7 @@ docs/
 Every piece of information about a piece of work has exactly ONE home — never two. The `work-lifecycle` skill is the single source of this flow.
 
 - In-progress work lives in `work/{name}/` (gitignored): `PRD.md` + `plan.md`. plan.md is the ONLY task status board — update statuses with surgical edits. An empty `work/` means nothing is half-done.
+- Execution worktrees always live inside the current project's root under `worktrees/{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>`; never create worktrees next to the repo, in the repo root, under `work/`, or in external temp/shared folders.
 - Full task specs, phase outcomes and history live in Engram: `work/{name}/task/{NN}`, `work/{name}/{phase}`, `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.
 - On 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}/`. History is memory + git — no archive folders.