jorgex-stack 1.0.19 → 1.0.21

package/README.md

@@ -83,7 +83,7 @@ GitHub authentication: requests use `GH_TOKEN`/`GITHUB_TOKEN` from the environme
 
 ### OpenCode Goal Mode
 
-Goal Mode is an OpenCode plugin for long-running goals: multiple sessions, multiple slices, multiple worktrees, and, when needed, multiple PRs. It is not meant for short tasks. If the change fits without extended autonomy, do not use `/goal`.
+The normal work-lifecycle already supports multi-PR plans: `work/{name}/PRD.md` and `plan.md` stay alive across intermediate merges, `work/{name}/pr/{NN}` stores each checkpoint, and `work/{name}/done` is reserved for the final close. Goal Mode is separate: an OpenCode plugin for long-running goals, multiple sessions, multiple slices, multiple worktrees, and, when needed, multiple PRs. It is not meant for short tasks. If the change fits without extended autonomy, do not use `/goal`.
 
 It only exists in OpenCode. Claude Code and Codex do not receive it.
 

package/package.json

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

@@ -30,4 +30,4 @@ Una sola fuente por agente. El instalador los traduce al formato de cada runtime
 
 - Todo subagente termina con el **Result contract** (Status / Delegations / Risks) — el orchestrator lo procesa.
 - Las delegaciones usan el formato `→ [agent]: [work] — [paths] — [inputs]` (skill `agent-delegation`).
-- El flujo de trabajo lo define la skill `work-lifecycle` (PRD D9): `work/{nombre}/plan.md` es el tablero de estado; las specs de tareas (`work/{nombre}/task/{NN}`), los resultados de fase (`work/{nombre}/{fase}`) y el backlog (`work/backlog`) viven en Engram. Los subagentes reciben topic_key + título, nunca la tarea inline.
+- 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/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.
+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.
 
 ## 1. INIT
 
@@ -96,11 +96,11 @@ If the work is large enough to benefit from explicit vertical slices, use the `t
 
 The `work-lifecycle` skill is the single source of this flow. Summary — every piece has exactly ONE home:
 
-- `work/{name}/` (gitignored, exists only while the work is in progress) holds the human-reviewed artifacts: `PRD.md` and `plan.md`. 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).
+- `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 and decisions → Engram under `work/{name}/{phase}`; tell each subagent which topic_key to use for its saves.
+- 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.
-- On 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}/`. History is memory + git.
+- 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
 
@@ -118,7 +118,7 @@ Every subagent ends with a **Result contract** (Status / Delegations / Risks). P
 
 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.
+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>` for single-PR work or `<project-root>/worktrees/<canonical-name>-prNN` for multi-PR checkpoints (branch = worktree 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.
 
@@ -178,7 +178,7 @@ When the plan is fully applied and VERIFY passes:
 ## 8. CLOSE
 
 - STOP here and hand control back to the user: report what shipped, review findings applied vs deferred to `work/backlog`, and whether manual testing is advisable (recommend it for big or user-facing changes; small well-tested changes may not need it).
-- NEVER merge the PR yourself — merge only on an explicit user order. After the merge: persist the outcome to memory, clean up `work/{name}/` and remove the worktree (see Work state).
+- NEVER merge the PR yourself — merge only on an explicit user order. After each intermediate merge: persist the checkpoint to `work/{name}/pr/{NN}`, update `plan.md`, and keep `work/{name}/` alive. After the final merge: persist the final outcome to memory, clean up `work/{name}/` and remove the worktree (see Work state).
 - If the repo has its own skill for the closing steps (release, deploy, git, cleanup), that skill takes precedence over the default behavior.
 
 ## Task rule

package/stack/hooks/hooks.json

@@ -12,6 +12,16 @@
             "timeout": 30
           }
         ]
+      },
+      {
+        "matcher": "Bash|PowerShell|EnterWorktree|ExitWorktree",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"{{SCRIPTS_DIR}}/repair-worktree-config.cjs\"",
+            "timeout": 10
+          }
+        ]
       }
     ]
   }

package/stack/plugins/opencode/worktree.ts

@@ -5,7 +5,6 @@ interface WorktreePluginConfig {
   setupScript?: string;
   docsReminderScript?: string;
   pathContains?: string;
-  branchPrefix?: string;
   reminderLines?: string[];
 }
 
@@ -290,7 +289,6 @@ export const WorktreePlugin: Plugin = async ({ $, client, directory }) => {
   let config: WorktreePluginConfig = {
     setupScript: "scripts/setup-worktree.ps1",
     pathContains: "worktrees/",
-    branchPrefix: "feature/",
     reminderLines: [],
   };
 
@@ -356,7 +354,7 @@ export const WorktreePlugin: Plugin = async ({ $, client, directory }) => {
         const worktreeName = getWorktreeName(parsedWorktreePath);
         if (!worktreeName) return;
 
-        const branchName = `${config.branchPrefix || "feature/"}${worktreeName}`;
+        const branchName = worktreeName;
 
         // .quiet() suppresses stderr to prevent noisy TUI logs from git calls
         const gitRoot = await $`git rev-parse --show-toplevel`.quiet().text();
@@ -372,7 +370,7 @@ export const WorktreePlugin: Plugin = async ({ $, client, directory }) => {
           appendToolOutput(output, [
             `Worktree path is not canonical: ${absoluteWorktreePath}`,
             `Use the project-local path instead: ${expectedWorktreePath}`,
-            "Canonical rule: <project-root>/worktrees/<canonical-name>.",
+            "Canonical rule: <project-root>/worktrees/<canonical-name> or <project-root>/worktrees/<canonical-name>-prNN.",
           ]);
           return;
         }

package/stack/scripts/repair-worktree-config.cjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// Repara la config de git que el harness de worktrees de los agentes puede dejar
+// corrupta cuando hay varios worktrees activos en la misma sesion:
+//   - core.bare=true en el repo principal  -> rompe rev-parse --show-toplevel / marca (bare)
+//   - core.worktree apuntando a OTRO worktree -> show-toplevel/status/add operan sobre
+//     el working-tree equivocado (branch/HEAD/git-dir siguen correctos: sintoma enganoso)
+//
+// GATE DE ALCANCE: el bug SOLO lo causa el harness de worktrees, asi que este guardian
+// solo actua en repos con worktrees ENLAZADOS. Un repo normal (o uno con layout legitimo
+// --separate-git-dir sin worktrees) NUNCA se toca, aunque el hook se publique y corra en
+// cada tool call de cualquier repo.
+//
+// El directorio del proyecto se toma del payload de stdin (data.cwd/directory/
+// activeWorktreePath), igual que post-pr-review.cjs: en OpenCode el hook se ejecuta con
+// cwd = dir de config, no el del proyecto, asi que fiarse de process.cwd() no repararia
+// el repo correcto. Fallback a process.cwd() (Claude Code / Codex ya corren ahi).
+//
+// Cross-agent (Claude Code / Codex / OpenCode) y cross-platform: node puro, sin deps.
+// Idempotente, INDEPENDIENTE del cwd de escritura (opera con --file sobre rutas absolutas),
+// fail-open y exit 0 SIEMPRE (un guardian nunca debe bloquear una tool). Como el guardian
+// hermano (block-destructive-git.cjs), un fail-open deja rastro en stderr para ser diagnosticable.
+
+const { execFileSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const TAG = "[repair-worktree-config]";
+
+/** Ejecuta git en `cwd` y devuelve stdout recortado, o null si falla (fail-open). */
+function git(args, cwd) {
+  try {
+    return execFileSync("git", args, {
+      cwd: cwd || undefined,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Diagnostico a stderr (no bloquea): un no-op/fallo silencioso es indetectable. */
+function warn(message) {
+  try {
+    process.stderr.write(`${TAG} ${message}\n`);
+  } catch {
+    /* stderr cerrado: no hay nada que hacer */
+  }
+}
+
+/** .git comun (compartido por todos los worktrees). Fiable aun con core.worktree
+ *  envenenado: este afecta al work-tree, no al git-dir. */
+function gitCommonDir(cwd) {
+  const abs = git(["rev-parse", "--path-format=absolute", "--git-common-dir"], cwd);
+  if (abs) return abs;
+  const rel = git(["rev-parse", "--git-common-dir"], cwd);
+  return rel ? path.resolve(cwd, rel) : null;
+}
+
+/** Quita core.worktree de `file` si esta puesto. Devuelve la etiqueta reparada o null.
+ *  Verifica el resultado: un unset fallido se avisa por stderr y NO se reporta reparado.
+ *  Las ops --file son independientes del cwd (rutas absolutas). */
+function unsetWorktree(file, label) {
+  if (!git(["config", "--file", file, "--get", "core.worktree"])) return null;
+  if (git(["config", "--file", file, "--unset-all", "core.worktree"]) === null) {
+    warn(`fallo al quitar core.worktree(${label}) - sigue puesto en ${file}`);
+    return null;
+  }
+  return `core.worktree(${label})`;
+}
+
+function repair(cwd) {
+  const common = gitCommonDir(cwd);
+  if (!common) {
+    // Distinguir "git no disponible" de "no es un repo": un guardian muerto por
+    // falta de git seria un no-op PERMANENTE e invisible en cada tool call.
+    if (git(["--version"], cwd) === null) {
+      warn("git no esta disponible en el PATH - el guardian no puede reparar");
+    }
+    return;
+  }
+  if (!fs.existsSync(common)) return;
+
+  // Gate de alcance: solo repos con worktrees enlazados (donde el bug es posible).
+  let entries = [];
+  try {
+    entries = fs
+      .readdirSync(path.join(common, "worktrees"), { withFileTypes: true })
+      .filter((entry) => entry.isDirectory());
+  } catch {
+    /* repo sin worktrees enlazados */
+  }
+  if (entries.length === 0) return;
+
+  const sharedCfg = path.join(common, "config");
+  const repaired = [];
+
+  // 1) core.bare -> false si quedo en true. Solo en layout normal (.git): nunca
+  //    tocamos un repo genuinamente bare (cuyo git-dir no se llama ".git").
+  if (
+    path.basename(common) === ".git" &&
+    git(["config", "--file", sharedCfg, "--get", "core.bare"]) === "true"
+  ) {
+    if (git(["config", "--file", sharedCfg, "core.bare", "false"]) === null) {
+      warn(`fallo al forzar core.bare=false en ${sharedCfg}`);
+    } else {
+      repaired.push("core.bare(shared)");
+    }
+  }
+
+  // 2) core.worktree en el config compartido (caso sin extensions.worktreeConfig)
+  const shared = unsetWorktree(sharedCfg, "shared");
+  if (shared) repaired.push(shared);
+
+  // 3) core.worktree en cada config.worktree por-worktree (caso worktreeConfig activo)
+  for (const entry of entries) {
+    const cw = path.join(common, "worktrees", entry.name, "config.worktree");
+    if (!fs.existsSync(cw)) continue;
+    const perWorktree = unsetWorktree(cw, entry.name);
+    if (perWorktree) repaired.push(perWorktree);
+  }
+
+  if (repaired.length > 0) {
+    process.stdout.write(`${TAG} reparado: ${repaired.join(", ")}\n`);
+  }
+}
+
+/** Directorio del proyecto desde el payload del hook; fallback a process.cwd(). */
+function resolveCwd(data) {
+  const candidate =
+    data && (data.activeWorktreePath || data.worktreePath || data.cwd || data.directory);
+  return typeof candidate === "string" && candidate ? candidate : process.cwd();
+}
+
+function run(data) {
+  try {
+    repair(resolveCwd(data));
+  } catch (error) {
+    // fail-open: nunca bloquear una tool, pero deja rastro del fallo del propio guardian.
+    warn(`error inesperado: ${error && error.message ? error.message : String(error)}`);
+  }
+  process.exit(0);
+}
+
+// Los 3 runtimes entregan el payload del hook por stdin (JSON). Sin stdin (ejecucion
+// manual/TTY) no bloqueamos: reparamos contra process.cwd().
+if (process.stdin.isTTY) {
+  run({});
+} else {
+  let raw = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => (raw += chunk));
+  process.stdin.on("end", () => {
+    let data = {};
+    try {
+      data = JSON.parse(raw || "{}");
+    } catch {
+      data = {};
+    }
+    run(data);
+  });
+  process.stdin.on("error", () => run({}));
+}

package/stack/skills/to-prd/SKILL.md

@@ -53,6 +53,16 @@ Do NOT include specific file paths or code snippets. They may end up being outda
 
 Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
 
+## Delivery / PR Roadmap
+
+This section captures the intended PR split only. Live status, checkpoints, and task progress belong in `plan.md`.
+
+1. PR 01 — [scope / outcome]
+2. PR 02 — [scope / outcome]
+3. PR 03 — [scope / outcome]
+
+Keep this static: describe the planned delivery slices, not the current state.
+
 ## Testing Decisions
 
 A list of testing decisions that were made. Include:

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

@@ -1,6 +1,6 @@
 ---
 name: work-lifecycle
-description: Single source for how a piece of work is tracked and advances — PRD and plan as files in work/{name}/ while in progress; task specs, phase outcomes and history in Engram memory. Use when starting, tracking, resuming or closing a piece of work, or when deciding where a PRD, plan, task or backlog item should live.
+description: Single source for how a piece of work is tracked and advances — PRD and plan as files in work/{name}/ while in progress; task specs, phase outcomes, PR checkpoints and history in Engram memory. Use when starting, tracking, resuming or closing a piece of work, or when deciding where a PRD, plan, task or backlog item should live.
 ---
 
 # Work Lifecycle
@@ -9,7 +9,7 @@ One rule kills duplication: **every piece of information has exactly ONE home**.
 
 ## Identity
 
-Every piece of work gets a **canonical kebab-case name** when it starts (e.g. `checkout-refactor`), shared with the branch if applicable. The name stays the same across its whole life — it is the key to everything else.
+Every piece of work gets a **canonical kebab-case name** when it starts (e.g. `checkout-refactor`), shared with the single-PR branch/worktree name and the base name for multi-PR checkpoints. The name stays the same across its whole life — it is the key to everything else.
 
 ## Where everything lives
 
@@ -18,8 +18,9 @@ Every piece of work gets a **canonical kebab-case name** when it starts (e.g. `c
 | PRD | `work/{name}/PRD.md` | Written once, reviewed by the human |
 | Plan (goal, approach, task board) | `work/{name}/plan.md` | The status board: humans glance at it; statuses flip with surgical edits |
 | Full spec of each atomic task | Engram `work/{name}/task/{NN}` | Only subagents consume it; visible from any worktree |
+| 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 |
+| 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 |
 
 `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.
@@ -28,16 +29,17 @@ Every piece of work gets a **canonical kebab-case name** when it starts (e.g. `c
 
 1. Pick the canonical name and create `work/{name}/`. If the item came from the backlog, remove it from `work/backlog` in the same step.
 2. Produce the PRD with the `to-prd` skill → `work/{name}/PRD.md`. The human reviews it there.
-3. Write `work/{name}/plan.md` (structure in `references/plan-template.md`): goal, chosen approach, success criteria, and the task table — number, title, one-line description, status, wave, deps.
+3. Write `work/{name}/plan.md` (structure in `references/plan-template.md`): goal, chosen approach, success criteria, PR roadmap, and the task table — number, PR, title, one-line description, status, wave, deps.
 4. Save the full spec of each atomic task to memory: one `mem_save` per task with topic_key `work/{name}/task/{NN}` (content structure in `references/plan-template.md`).
 
 ## Executing
 
 - 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.
+- 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>` for single-PR work or `<project-root>/worktrees/<canonical-name>-prNN` for multi-PR checkpoints, with the branch matching the worktree 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.
+- Task status lives ONLY in the task table: flip it (⬜ → ✅) with a surgical edit when the task closes. PR status/evidence lives ONLY in the PR roadmap table. Do not mirror task progress into memory, and do not re-read the whole plan after every task — it is already in context; re-read it on resume.
+- For multi-PR work, resume from the first PR/task not done in the roadmap/table. For single-PR work, the canonical name worktree/branch is enough and the roadmap collapses to one checkpoint.
 
 ## HTML review view (on demand)
 
@@ -61,13 +63,28 @@ If the project manages work through an issue tracker, issues (`to-issues`) take
 
 ## Closing
 
-When the work is finalized (e.g. PR created and merged into its target branch):
+There are two close levels:
+
+### PR checkpoint
+
+When an intermediate PR is merged:
+
+1. `mem_save` under `work/{name}/pr/{NN}`: what merged, what remains, and any blockers.
+2. Update the PR roadmap and task statuses in `work/{name}/plan.md`.
+3. Delete that PR's worktree if appropriate.
+4. Keep `work/{name}/` alive for the remaining PRs.
+
+### Final work close
+
+When all PRs are merged, cancelled, or deferred:
 
 1. `mem_save` under `work/{name}/done`: outcome, what shipped, anything left pending.
 2. If the PRD has lasting documentation value, move it to where the project keeps docs (e.g. `docs/`); otherwise its key decisions already live in `done`.
-3. **Delete `work/{name}/`** and remove the work's worktree. Nothing to archive — git has the code, memory has the story.
+3. **Delete `work/{name}/`** and remove the remaining worktree(s). Nothing to archive — git has the code, memory has the story.
 4. `mem_session_summary` covers the session as usual.
 
+For single-PR work, the PR checkpoint and final work close happen together: one merge, one `work/{name}/done`, then cleanup.
+
 ## Rules
 
 - One piece of work = one canonical name, stable across its whole life.

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

@@ -1,6 +1,6 @@
 # Plan & Task Templates
 
-Templates for the two artifacts of a piece of work: `plan.md` (file — the status board) and the atomic tasks (Engram observations). `[name]` is the canonical kebab-case name shared by `work/[name]/`, the branch and every topic_key.
+Templates for the two artifacts of a piece of work: `plan.md` (file — the status board) and the atomic tasks (Engram observations). `[name]` is the canonical kebab-case name shared by `work/[name]/` and every topic_key. PR branches/worktrees derive from it: `[name]` for single-PR work, `[name]-prNN` for multi-PR checkpoints.
 
 ---
 
@@ -36,6 +36,19 @@ The full spec of each task is NOT a file: it lives in Engram, one observation pe
 
 [Why it wasn't chosen]
 
+## PR Roadmap
+
+> This is the live PR-level board: scope, PR status, and merge evidence live here.
+> Task-level status stays in the task table below.
+> Full checkpoint history lives in Engram under `work/[name]/pr/[NN]`.
+
+| PR | Scope | Branch | Worktree | Base | Status | Merge evidence |
+|----|-------|--------|----------|------|--------|----------------|
+| 01 | [scope] | [branch] | [worktree] | [base] | ⬜ | [evidence] |
+| 02 | [scope] | [branch] | [worktree] | [base] | ⬜ | [evidence] |
+
+> Intermediate PRs do not delete `work/[name]/`; only the final close does.
+
 ## Success criteria
 
 - [ ] [Verifiable behavior 1]
@@ -45,14 +58,16 @@ The full spec of each task is NOT a file: it lives in Engram, one observation pe
 ## Tasks
 
 > Full spec of task NN → Engram topic_key `work/[name]/task/NN`.
-> Status lives ONLY in this table — update it with a surgical edit per task.
-
-| # | Task | One-liner | Status | Wave | Deps |
-|---|------|-----------|--------|------|------|
-| 01 | [descriptive name] | [one-line description] | ⬜ | 1 | — |
-| 02 | [descriptive name] | [one-line description] | ⬜ | 1 | — |
-| 03 | [descriptive name] | [one-line description] | ⬜ | 2 | 01 |
-| 04 | [descriptive name] | [one-line description] | ⬜ | 2 | 01, 02 |
+> Task status lives ONLY in this table — update it with a surgical edit per task.
+> PR status/evidence lives in the PR Roadmap above.
+> Map each task to the PR that carries it; intermediate PRs keep `work/[name]/` alive.
+
+| # | PR | Task | One-liner | Status | Wave | Deps |
+|---|----|------|-----------|--------|------|------|
+| 01 | 01 | [descriptive name] | [one-line description] | ⬜ | 1 | — |
+| 02 | 01 | [descriptive name] | [one-line description] | ⬜ | 1 | — |
+| 03 | 02 | [descriptive name] | [one-line description] | ⬜ | 2 | 01 |
+| 04 | 02 | [descriptive name] | [one-line description] | ⬜ | 2 | 01, 02 |
 
 **Statuses**: ⬜ Pending → 🔴 RED → 🟢 GREEN → 🔍 Review → ✅ Done
 ```

package/stack/system-prompt/AGENTS.md

@@ -90,11 +90,12 @@ 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.
+- 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.
-- 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.
+- 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

@@ -40,7 +40,7 @@ Use the `engram` subagent for non-trivial memory reads — it filters and return
 
 ## Work state
 
-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}`), the final `work/{name}/done`, and the project backlog 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 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.
 
 ## Before ending a session