jorgex-stack 1.0.12 → 1.0.14

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

@@ -855,7 +855,7 @@ ${agent.body}`,
             continue;
           }
           const command = server.command === "{{ENGRAM_BIN}}" ? ctx.engramBin : server.command;
-          servers[name] = { command, args: server.args ?? [] };
+          servers[name] = { type: "stdio", command, args: server.args ?? [] };
         } else {
           const previous = servers[name];
           const headers = {};

package/package.json

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