@ulysses-ai/create-workspace 0.18.0-beta.0 → 0.19.0-beta.0

package/template/_claude/scripts/task-pr.mjs

@@ -0,0 +1,447 @@
+#!/usr/bin/env node
+// PR creation and merge for the task lifecycle (gh:163).
+//
+// The task path of /complete-work used to end with two hand-written
+// JavaScript blocks — one to push and open a PR per repo, one to merge them
+// in order and close the issue. Every run re-typed them, and every
+// re-typing was a fresh chance to drop a guard: origins must be parsed
+// before anything is pushed, body files must exist for every repo that
+// gets a PR, and the workspace PR must never merge ahead of the project
+// PRs it describes. This script is those blocks written once.
+//
+// It runs from the launcher and owns only this slice: the rebase and the
+// drawer routing happen in the skill's earlier steps, and teardown stays
+// in task-worktree.mjs --remove.
+//
+// Usage:
+//   node task-pr.mjs --create --root <launcher> --branch <branch>
+//                    [--work-item gh:N] [--chat <name> | --repo <r> ...]
+//                    --body-file <repo>=<path> ... [--out <file>]
+//                    [--force-with-lease]
+//   node task-pr.mjs --merge --root <launcher> --prs <json-from-create>
+//                    [--work-item gh:N]
+//
+// --create resolves the task's repos from the chat record's entries for
+// the branch (--chat) or from repeated --repo flags, skips repos whose
+// branch has no commits over origin/{default} (reported as empty), pushes
+// each remaining branch, and opens one PR per repo through a per-repo
+// forge. The PR title is the linked issue's title when --work-item is
+// given, else the branch's first commit subject; the body is the repo's
+// body file with `Closes <ref>` appended. Prints `{ prs, empty, pushed }`
+// and, with --out, writes the same JSON to a file — a mid-run failure
+// still writes what has landed so far, so the state survives the error.
+// A repo that already has an open PR for the branch gets it reused, so a
+// re-run never opens a duplicate.
+//
+// --merge merges the project PRs first (squash, delete branch), the
+// workspace PR only when every project merge succeeded — a PR the forge
+// reports as already MERGED counts as done and is not merged again, which
+// is what makes re-running after a partial failure safe. An empty or
+// malformed PRs file is refused outright: no PRs means nothing to merge
+// and nothing to close. Once every PR is merged the launcher is pulled
+// --ff-only — only when it sits on the workspace default branch (else
+// pullSkipped), and a failed pull is reported as pullFailed in the JSON
+// rather than an error, because the merges stand and the issue still
+// closes — and then the linked issue closes with a Merged: comment. On a
+// merge failure it stops and names the PRs still open.
+
+import '../lib/require-node.mjs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { taskWorktreePath, defaultBranchFor, WORKSPACE_REPO } from './task-worktree.mjs';
+import { readRecord } from './chat-record.mjs';
+import { createForge } from './forges/interface.mjs';
+import { createTracker } from './trackers/interface.mjs';
+
+function isMainModule(metaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(metaUrl)) === realpathSync(process.argv[1]);
+  } catch { return false; }
+}
+
+// Same remote shapes the forge adapters resolve a repo from. A URL that
+// does not match is not forge-hosted, and this path supports forge-hosted
+// repos only — a local/bare remote has no PR concept to aim at.
+const FORGE_REMOTE_RE = /github\.com[:/]([^/]+)\/([^/.]+?)(?:\.git)?$/;
+
+function parseForgeRemote(url) {
+  const m = String(url).trim().match(FORGE_REMOTE_RE);
+  return m ? { owner: m[1], name: m[2] } : null;
+}
+
+function readWorkspace(rootDir) {
+  try {
+    return JSON.parse(readFileSync(join(rootDir, 'workspace.json'), 'utf-8'));
+  } catch {
+    throw new Error(`cannot read ${join(rootDir, 'workspace.json')} — is --root the launcher?`);
+  }
+}
+
+// `workspace.forge: false` is an explicit opt-out; spreading it into a
+// per-repo config would silently produce a default GitHub forge instead.
+function assertForgeEnabled(ws) {
+  if (ws?.workspace?.forge === false) {
+    throw new Error('workspace.forge is false — forge operations are disabled here. Nothing was pushed; open the PR by hand.');
+  }
+}
+
+// Branch names become refs, refspecs, and (via the slug) paths; git's own
+// format check is the authority, and its --branch variant also rejects
+// names a later git call could mistake for an option. It needs no
+// repository, so it runs before any other git call this script makes.
+function assertBranchName(gitFn, branch) {
+  const res = gitFn('git', ['check-ref-format', '--branch', branch], { encoding: 'utf8' });
+  if (res.error || res.status !== 0) throw new Error(`invalid branch name: ${branch}`);
+}
+
+// The --prs file may have been written by a BOM-emitting writer (PowerShell
+// redirection among them); JSON.parse chokes on the marker, so strip it.
+function stripBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+function writeOut(path, payload) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+
+function gitCheck(gitFn, cwd, args) {
+  const res = gitFn('git', ['-C', cwd, ...args], { encoding: 'utf8' });
+  if (res.error) throw new Error(`git: ${res.error.message}`);
+  return res;
+}
+
+function gitOut(gitFn, cwd, args) {
+  const res = gitCheck(gitFn, cwd, args);
+  if (res.status !== 0) {
+    throw new Error(`git -C ${cwd} ${args.join(' ')} failed: ${String(res.stderr || '').trim()}`);
+  }
+  return String(res.stdout || '').trim();
+}
+
+// The merge base for "is this branch empty" and for the fallback PR title.
+// origin/{default} is the truth the PR will merge against; the local branch
+// covers a repo whose remote-tracking ref is missing.
+function baseRefFor(gitFn, worktree, defaultBranch) {
+  for (const ref of [`origin/${defaultBranch}`, defaultBranch]) {
+    if (gitCheck(gitFn, worktree, ['rev-parse', '--verify', '--quiet', ref]).status === 0) return ref;
+  }
+  return null;
+}
+
+function commitsOverBase(gitFn, worktree, branch, defaultBranch) {
+  const base = baseRefFor(gitFn, worktree, defaultBranch);
+  // No base ref at all: the branch cannot be proven empty, so it proceeds.
+  if (!base) return null;
+  return parseInt(gitOut(gitFn, worktree, ['rev-list', '--count', `${base}..${branch}`]), 10) || 0;
+}
+
+function firstCommitSubject(gitFn, worktree, branch, defaultBranch) {
+  const base = baseRefFor(gitFn, worktree, defaultBranch);
+  const range = base ? `${base}..${branch}` : branch;
+  const subjects = gitOut(gitFn, worktree, ['log', '--reverse', '--format=%s', range])
+    .split(/\r?\n/).filter((l) => l.trim() !== '');
+  if (subjects.length > 0) return subjects[0].trim();
+  return gitOut(gitFn, worktree, ['log', '-1', '--format=%s', branch]);
+}
+
+function pushBranch(gitFn, worktree, repo, branch, { forceWithLease = false } = {}) {
+  // `--` ends option parsing so the refspec can never read as a flag — git
+  // accepts it on push. It is deliberately NOT used on the rev-parse /
+  // rev-list / log calls, where git would flip the argument to a path.
+  const res = gitCheck(gitFn, worktree, [
+    'push', '-u', 'origin', ...(forceWithLease ? ['--force-with-lease'] : []), '--', branch,
+  ]);
+  if (res.status === 0) return;
+  const stderr = String(res.stderr || '').trim();
+  if (!forceWithLease && /non-fast-forward|fetch first/i.test(stderr)) {
+    throw new Error(
+      `repo "${repo}": push rejected as non-fast-forward — the branch already exists on origin and the rebase rewrote it. Confirm and re-run with --force-with-lease; this script never forces on its own.`,
+    );
+  }
+  throw new Error(`repo "${repo}": git push failed: ${stderr}`);
+}
+
+function resolveTaskRepos(rootDir, { chat, branch, repos }) {
+  if (repos.length > 0) return [...new Set(repos)];
+  if (!chat) {
+    throw new Error("--create needs the task's repos: pass --chat <name> (its record entries for the branch) or repeat --repo");
+  }
+  const rec = readRecord(rootDir, chat);
+  const entries = (rec?.tasks ?? []).filter((t) => t.branch === branch && t.repo);
+  if (entries.length === 0) {
+    throw new Error(`chat record "${chat}" has no task entries for branch ${branch} — pass --repo explicitly`);
+  }
+  return [...new Set(entries.map((t) => t.repo))];
+}
+
+async function createPrs(args, deps) {
+  assertBranchName(deps.gitFn, args.branch);
+  const rootDir = resolve(args.root);
+  const ws = readWorkspace(rootDir);
+  assertForgeEnabled(ws);
+
+  const targets = resolveTaskRepos(rootDir, args).map((repo) => {
+    const worktree = taskWorktreePath(rootDir, repo, args.branch);
+    if (!existsSync(worktree)) {
+      throw new Error(`no task worktree at ${worktree} for repo "${repo}" — create it with task-worktree.mjs --create`);
+    }
+    return {
+      repo, worktree, isWorkspace: repo === WORKSPACE_REPO,
+      defaultBranch: defaultBranchFor(rootDir, repo, deps.gitFn),
+    };
+  });
+
+  for (const t of targets) t.commits = commitsOverBase(deps.gitFn, t.worktree, args.branch, t.defaultBranch);
+  const empty = targets.filter((t) => t.commits === 0).map((t) => t.repo);
+  const active = targets.filter((t) => t.commits !== 0);
+
+  // Every guard runs before the first push: a repo whose origin cannot
+  // host a PR, or whose body file is missing, must stop the whole task
+  // with nothing pushed and nothing half-opened.
+  for (const t of active) {
+    const url = gitOut(deps.gitFn, t.worktree, ['remote', 'get-url', 'origin']);
+    const parsed = parseForgeRemote(url);
+    if (!parsed) {
+      throw new Error(`repo "${t.repo}": origin (${url}) is not a forge-hosted repository — stopped before pushing anything. Complete this repo under the session model.`);
+    }
+    Object.assign(t, parsed);
+  }
+  for (const t of active) {
+    const bodyFile = args.bodyFiles.get(t.repo);
+    if (!bodyFile) {
+      throw new Error(`repo "${t.repo}" has commits to merge but no --body-file — one is required for every repo that gets a PR`);
+    }
+    if (!existsSync(bodyFile)) {
+      throw new Error(`repo "${t.repo}": body file not found: ${bodyFile}`);
+    }
+  }
+
+  let issueTitle = null;
+  let issueRefs = null;
+  if (args.workItem) {
+    const tracker = deps.trackerFactory(ws.workspace?.tracker);
+    issueTitle = (await tracker.getIssue(args.workItem)).title;
+    issueRefs = new Map(active.map((t) => [t.repo, tracker.issueRef(args.workItem, { fromRepo: `${t.owner}/${t.name}` })]));
+  }
+
+  const prs = [];
+  const pushed = [];
+  try {
+    for (const t of active) {
+      pushBranch(deps.gitFn, t.worktree, t.repo, args.branch, { forceWithLease: args.forceWithLease });
+      pushed.push(t.repo);
+    }
+
+    for (const t of active) {
+      const forge = deps.forgeFactory({ ...(ws.workspace?.forge ?? {}), repo: `${t.owner}/${t.name}` });
+      // Idempotency: a re-run must not open a second PR for a branch that
+      // already has one open against the same base. Reuse it as-is —
+      // re-titling or re-bodying an existing PR is a decision, not a
+      // default, and the one already open is the one reviewers watch.
+      const existing = (await forge.prList({ state: 'open', head: args.branch, base: t.defaultBranch }))
+        .find((p) => p.headRefName === args.branch && p.baseRefName === t.defaultBranch);
+      const title = issueTitle ?? firstCommitSubject(deps.gitFn, t.worktree, args.branch, t.defaultBranch);
+      let body = readFileSync(args.bodyFiles.get(t.repo), 'utf8').replace(/\s*$/, '');
+      if (issueRefs) body = `${body}\n\nCloses ${issueRefs.get(t.repo)}\n`;
+      const pr = existing ?? await forge.prCreate({ title, body, head: args.branch, base: t.defaultBranch });
+      prs.push({
+        repo: t.repo, owner: t.owner, name: t.name,
+        number: pr.number, id: pr.id, url: pr.url, isWorkspace: t.isWorkspace,
+      });
+    }
+  } catch (err) {
+    // A failure after the first push must not lose the run's state: the
+    // pushes and PRs that landed go to --out so a re-run (or a --merge of
+    // what exists) starts from reality. Before the first push nothing has
+    // happened, and an earlier run's file stays untouched rather than
+    // being clobbered with a no-op result.
+    if (args.out && (pushed.length > 0 || prs.length > 0)) {
+      writeOut(args.out, { prs, empty, pushed });
+    }
+    throw err;
+  }
+  const result = { prs, empty, pushed };
+  if (args.out) writeOut(args.out, result);
+  return result;
+}
+
+async function mergePrs(args, deps) {
+  const rootDir = resolve(args.root);
+  const ws = readWorkspace(rootDir);
+  assertForgeEnabled(ws);
+
+  let parsed;
+  try {
+    parsed = JSON.parse(stripBom(readFileSync(args.prs, 'utf-8')));
+  } catch (err) {
+    throw new Error(`cannot read PRs file ${args.prs}: ${err.message}`);
+  }
+  // An empty or malformed file is a refusal, not a no-op: with nothing to
+  // merge there is nothing that earns an issue close, and "Merged: " with
+  // no URLs would tell the tracker a lie.
+  if (!parsed || !Array.isArray(parsed.prs)) {
+    throw new Error(`PRs file ${args.prs} is malformed — expected the JSON from a --create run ({ prs: [...] })`);
+  }
+  const prs = parsed.prs;
+  if (prs.length === 0) {
+    throw new Error(`PRs file ${args.prs} lists no PRs — nothing to merge and nothing to close; --merge refuses to close an issue on an empty merge`);
+  }
+  for (const p of prs) {
+    if (!p || !p.owner || !p.name || !p.id) {
+      throw new Error(`PRs file entry is missing owner/name/id: ${JSON.stringify(p)}`);
+    }
+  }
+  const forgeFor = (p) => deps.forgeFactory({ ...(ws.workspace?.forge ?? {}), repo: `${p.owner}/${p.name}` });
+
+  // State first, so a re-run knows what an earlier run already finished.
+  // A PR the forge reports MERGED is done; anything else is offered to
+  // prMerge, which reports its own failure if the PR cannot merge. If the
+  // view itself fails, fall through to the merge attempt — that path
+  // produces the honest error when something is genuinely wrong.
+  const alreadyMerged = new Set();
+  for (const p of prs) {
+    try {
+      const view = await forgeFor(p).prView({ id: p.id });
+      if (view?.state === 'MERGED') alreadyMerged.add(p.id);
+    } catch { /* state unknown — the merge attempt below decides */ }
+  }
+
+  const merged = [];
+  const failures = [];
+  for (const p of prs.filter((x) => !x.isWorkspace)) {
+    if (alreadyMerged.has(p.id)) { merged.push(p); continue; }
+    try {
+      await forgeFor(p).prMerge({ id: p.id, strategy: 'squash', deleteBranch: true });
+      merged.push(p);
+    } catch (err) { failures.push(`${p.repo}: ${err.message}`); }
+  }
+  const workspacePr = prs.find((x) => x.isWorkspace) ?? null;
+  if (failures.length === 0 && workspacePr) {
+    if (alreadyMerged.has(workspacePr.id)) {
+      merged.push(workspacePr);
+    } else {
+      try {
+        await forgeFor(workspacePr).prMerge({ id: workspacePr.id, strategy: 'squash', deleteBranch: true });
+        merged.push(workspacePr);
+      } catch (err) { failures.push(`${workspacePr.repo}: ${err.message}`); }
+    }
+  }
+  if (failures.length > 0) {
+    const open = prs.filter((p) => !merged.includes(p)).map((p) => `${p.repo}: ${p.url}`);
+    throw new Error(
+      `merge stopped (${failures.join('; ')}). PRs still open: ${open.join(', ')}. The workspace PR is never merged ahead of the project PRs — fix the failure and re-run --merge.`,
+    );
+  }
+
+  // Every PR in the file is merged from here on. The launcher pull is a
+  // convenience, not a gate: it happens only when the launcher sits on the
+  // workspace default branch, a failure is a reported flag rather than an
+  // error (the merges stand and the issue still closes), and the user is
+  // told to pull by hand before teardown.
+  const result = { merged: merged.map(({ repo, number, url }) => ({ repo, number, url })), closed: null };
+  const launcherBranch = gitOut(deps.gitFn, rootDir, ['branch', '--show-current']) || '(detached HEAD)';
+  if (launcherBranch !== defaultBranchFor(rootDir, WORKSPACE_REPO, deps.gitFn)) {
+    result.pullSkipped = `launcher on ${launcherBranch}`;
+  } else {
+    const pull = gitCheck(deps.gitFn, rootDir, ['pull', '--ff-only']);
+    if (pull.status !== 0) result.pullFailed = true;
+  }
+
+  if (args.workItem) {
+    const tracker = deps.trackerFactory(ws.workspace?.tracker);
+    await tracker.closeIssue(args.workItem, { comment: `Merged: ${merged.map((p) => p.url).join(' ')}` });
+    result.closed = args.workItem;
+  }
+  return result;
+}
+
+const MODE_FLAGS = new Set(['--create', '--merge']);
+const VALUE_FLAGS = new Set(['--root', '--branch', '--work-item', '--chat', '--prs', '--out']);
+
+function parseArgs(argv) {
+  const args = {
+    root: '.', mode: null, branch: null, workItem: null, chat: null,
+    repos: [], bodyFiles: new Map(), prs: null, out: null, forceWithLease: false,
+  };
+  const rest = argv.slice(2);
+  const value = (i, flag) => {
+    const v = rest[i + 1];
+    if (v === undefined || v.startsWith('--')) throw new Error(`${flag} requires a value`);
+    return v;
+  };
+  for (let i = 0; i < rest.length; i += 1) {
+    const a = rest[i];
+    if (MODE_FLAGS.has(a)) {
+      if (args.mode) throw new Error(`only one of --create, --merge may be given (already have --${args.mode})`);
+      args.mode = a.slice(2);
+      continue;
+    }
+    if (a === '--repo') { args.repos.push(value(i, a)); i += 1; continue; }
+    if (a === '--body-file') {
+      const v = value(i, a);
+      const eq = v.indexOf('=');
+      if (eq <= 0) throw new Error(`--body-file expects <repo>=<path>, got: ${v}`);
+      args.bodyFiles.set(v.slice(0, eq), v.slice(eq + 1));
+      i += 1;
+      continue;
+    }
+    if (a === '--force-with-lease') { args.forceWithLease = true; continue; }
+    if (VALUE_FLAGS.has(a)) {
+      args[a.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = value(i, a);
+      i += 1;
+      continue;
+    }
+    throw new Error(`unknown argument: ${a}`);
+  }
+  if (!args.mode) throw new Error('one of --create, --merge is required');
+  if (args.mode === 'create') {
+    if (!args.branch) throw new Error('--create requires --branch');
+    if (!args.chat && args.repos.length === 0) throw new Error('--create requires --chat or at least one --repo');
+    if (args.prs) throw new Error('--prs is only valid with --merge');
+  } else {
+    if (!args.prs) throw new Error('--merge requires --prs');
+    for (const flag of ['branch', 'chat']) {
+      if (args[flag]) throw new Error(`--${flag} is only valid with --create`);
+    }
+    if (args.repos.length > 0) throw new Error('--repo is only valid with --create');
+    if (args.bodyFiles.size > 0) throw new Error('--body-file is only valid with --create');
+    if (args.forceWithLease) throw new Error('--force-with-lease is only valid with --create');
+    if (args.out) throw new Error('--out is only valid with --create');
+  }
+  return args;
+}
+
+/**
+ * Run one task-pr command. `argv` is a process.argv-shaped array; `deps`
+ * is injectable so tests can fake git, the forge, and the tracker:
+ *   { gitFn, forgeFactory, trackerFactory }
+ * Resolves with the command's JSON result; throws on any failure.
+ */
+async function run(argv, deps = {}) {
+  const resolved = {
+    gitFn: spawnSync,
+    forgeFactory: createForge,
+    trackerFactory: createTracker,
+    ...deps,
+  };
+  const args = parseArgs(argv);
+  return args.mode === 'create' ? createPrs(args, resolved) : mergePrs(args, resolved);
+}
+
+async function main() {
+  const out = await run(process.argv);
+  process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+}
+
+if (isMainModule(import.meta.url)) {
+  main().catch((err) => {
+    process.stderr.write(`task-pr: ${err.message}\n`);
+    process.exit(2);
+  });
+}
+
+export { run, parseArgs, parseForgeRemote };

package/template/{.claude → _claude}/scripts/trackers/github-issues.mjs

@@ -107,6 +107,16 @@ export function createGithubAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
     gh(['issue', 'comment', String(num), '--repo', repo, '--body-file', '-'], { input: body });
   }
 
+  // A closing reference for PR bodies: `#N` closes an issue in the PR's own
+  // repo, `owner/repo#N` reaches one living elsewhere. GitHub only honors a
+  // bare `#N` when the PR and the issue share a repo, so callers pass the
+  // PR's repo as fromRepo and this decides which shape closes the right
+  // issue. No `fromRepo` means the PR is in this adapter's own repo.
+  function issueRef(issueId, { fromRepo } = {}) {
+    const num = parseIssueNumber(issueId);
+    return fromRepo && fromRepo !== repo ? `${repo}#${num}` : `#${num}`;
+  }
+
   async function closeIssue(issueId, { comment: commentBody } = {}) {
     const num = parseIssueNumber(issueId);
     if (commentBody) {
@@ -142,6 +152,7 @@ export function createGithubAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
     createIssue,
     comment,
     closeIssue,
+    issueRef,
     ensureLabels,
     ensureMilestone,
     get identity() { return `github-issues:${repo}`; },

package/template/{.claude → _claude}/scripts/trackers/interface.mjs

@@ -1,5 +1,13 @@
 // Tracker adapter interface. Skills import only from this module.
 // See design-tracker-abstraction.md for the full Issue shape and method contracts.
+//
+// Method contract added alongside task-pr.mjs (gh:163):
+//
+//   issueRef(issueId, { fromRepo })
+//     → the closing reference for a PR body: "#N" when fromRepo is (or
+//       defaults to) this adapter's own repo, "owner/repo#N" otherwise —
+//       only the first form closes an issue in the PR's own repo, so a PR
+//       in any other repo must name the tracker's repo explicitly.
 
 import '../../lib/require-node.mjs';
 import { createGithubAdapter } from './github-issues.mjs';

package/template/{.claude → _claude}/skills/braindump/SKILL.md

@@ -30,6 +30,7 @@ Under the task model — `workspace.sessionModel` is `"task"` in `workspace.json
 
 - Default behavior: write `braindump_{topic}.md` directly into that chat's drawer at `workspace-scratchpad/chats/{chat}/` — the drawer sits outside `workspace-context/`, so `capture-context.mjs` is not involved
 - No commit for drawer writes: the drawer is gitignored and machine-local; `/complete-work` lists it and asks what to promote into `workspace-context/`
+- While a task is active, add `workItem: {id}` to the file's frontmatter: `/complete-work` offers a drawer item only to the task that owns it, so the tag keeps this capture out of another task's promotion list
 
 When called from the workspace root with no active session — every other case, including a `sessionModel: "session"` workspace (the `Chat record:` line is injected in every chat, so it alone does not select the drawer):
 

package/template/{.claude → _claude}/skills/complete-work/SKILL.md

@@ -20,7 +20,7 @@ node "{launcher-root}/.claude/scripts/task-worktree.mjs" --root "{launcher-root}
 ```
 
 - `{launcher-root}` is the absolute path on the `Workspace root:` line the SessionStart hook injects. If that line is absent, derive it from git: run `git rev-parse --git-common-dir` (when it prints a relative path, resolve it against the cwd) and take its parent directory. That derivation lands on the source clone `…/repos/{repo}` when run from inside a **project** task worktree — there the launcher is two levels up; from inside a `.` worktree (`.claude/worktrees/{slug}`) the parent already is the launcher.
-- `{chat}` is the name from the `Chat record:` line the SessionStart hook injects. If that line is absent, omit `--chat` — detection then relies on cwd alone.
+- `{chat}` is the name from the `Chat record:` line the SessionStart hook injects. If that line is absent, run `node .claude/scripts/chat-record.mjs --whoami --root "{launcher-root}"` first — compaction can drop the hook line, and this recovers the name by matching the chat's session id against the records. When that too prints nothing (exit 1), omit `--chat` — detection then relies on cwd alone.
 - `model: session` → continue with this flow (read the session tracker as below), taking `{session-name}` from the detect result's `sessionName`.
 - `model: task` → go to **Task completion (session model v2)**. The result's `tasks` come from the chat record; if several are open, ask the user which one to complete — group by branch, a multi-repo task is several entries sharing a branch.
 - `model: none` → "No active work session. Nothing to complete."
@@ -379,7 +379,7 @@ If several tasks are open, ask the user which one to complete — group by branc
 
 1. **Rebase each task worktree onto `origin/{defaultBranch}`** (`git -C "{worktree}" fetch origin`, then `git -C "{worktree}" rebase "origin/{defaultBranch}"`). Freshness first: the PR in step 3 must describe the branch as it will merge. If conflicts arise, STOP and present them — do not auto-resolve.
 
-2. **Route durable thinking.** List anything in the chat drawer `{launcher-root}/workspace-scratchpad/chats/{chat}/` and ask which items should graduate into `workspace-context/`. If nothing is chosen, skip this step — no `.` worktree is needed yet. Do NOT invoke `/promote`: it writes relative to cwd and commits per item, which at the launcher lands on the default branch — exactly the hole this flow closes, and it does not know about drawer items. For the chosen items, first create the workspace worktree on the task's branch and record it alongside the project entries:
+2. **Route durable thinking.** List the chat drawer `{launcher-root}/workspace-scratchpad/chats/{chat}/` and ask which items should graduate into `workspace-context/`. The offer is filtered by task: an item whose frontmatter carries a `workItem:` is listed only when it names this task's `{workItem}`, an item with no `workItem:` is always listed, and an item tagged for another open task is not this completion's to promote — it belongs to that task's completion. Leftovers of an earlier completion attempt are never offered: the `pr-{slug}-*.md` bodies and the `prs-{slug}.json` state file are step 3–4 machinery, not thinking. Drafting skills (`/braindump`, `/handoff`, designs and plans) tag their drawer writes with `workItem:` while a task is active so this filter has something to filter on. If nothing is chosen, skip this step — no `.` worktree is needed yet. Do NOT invoke `/promote`: it writes relative to cwd and commits per item, which at the launcher lands on the default branch — exactly the hole this flow closes, and it does not know about drawer items. For the chosen items, first create the workspace worktree on the task's branch and record it alongside the project entries:
 
    ```bash
    node "{launcher-root}/.claude/scripts/task-worktree.mjs" --root "{launcher-root}" --create --repo "." --branch "{branch}"
@@ -396,58 +396,18 @@ If several tasks are open, ask the user which one to complete — group by branc
 
    The drawer is per-chat, so it survives task teardown — but it is machine-local and backed up nowhere, and this review, with the work fresh in mind, is the moment to decide what graduates. Items left behind are not lost, only unreviewed.
 
-3. **Check each origin, push, then open one PR per repo through the forge adapter** — never `gh pr` directly. The workspace repo (`.`) is handled exactly like a project repo: same origin check and push in `{workspace-worktree}`, same PR, with `wsForge` — the per-repo forge constructed from the workspace worktree's own origin — yielding `wsPr`. First, drop empty branches: for every repo of the task, `.` included when its worktree exists, run
+3. **Write one PR body per repo into the drawer, then create every PR with `task-pr.mjs --create`** — never `gh pr` directly. For each repo of the task, `{worktree}` included when it exists, write `{launcher-root}/workspace-scratchpad/chats/{chat}/pr-{slug}-{repo}.md` (with `{repo}` rendered as `workspace` for `.`). Each body carries a short summary of what changed and why, then a `## Verification` section stating how the change was checked — the commands run and their results. The drawer is machine-local and gitignored, so these files never touch a branch, and `--create` requires one for every repo whose branch has commits. Then one command does the rest:
 
    ```bash
-   git -C "{worktree}" rev-list --count "origin/{defaultBranch}..{branch}"
+   node "{launcher-root}/.claude/scripts/task-pr.mjs" --create --root "{launcher-root}" --branch "{branch}" \
+     --work-item "{workItem}" --chat "{chat}" \
+     --body-file "{repo}={launcher-root}/workspace-scratchpad/chats/{chat}/pr-{slug}-{repo}.md" \
+     --out "{launcher-root}/workspace-scratchpad/chats/{chat}/prs-{slug}.json"
    ```
 
-   and if the count is `0`, skip push and PR for that repo entirely — it is torn down in step 5 like any other. A workspace branch that collected no promotions gets no PR. Then, in order: the origin decides whether this path can proceed at all (nothing is pushed to a repo this path cannot finish), and the forge is constructed per repo so it aims at the worktree's own remote, never the launcher's.
+   Omit `--work-item` when the task has none, and repeat `--body-file` once per repo. `--chat` resolves the task's repos from this chat's record entries for the branch; when detection came from cwd alone, pass `--repo "{repo}"` once per repo instead. The script skips repos whose branch has no commits over `origin/{defaultBranch}` (reporting them as `empty` — no push, no PR, no body file needed, torn down in step 5 like any other; a workspace branch that collected no promotions gets no PR), parses each worktree's own origin into `{owner}/{name}` and stops **before pushing anything** if any origin is not forge-hosted — such a repo is completed under the session model — then pushes `-u origin {branch}` and opens one PR per remaining repo through a per-repo forge aimed at that worktree's own remote, never the launcher's. The workspace repo (`.`) is handled exactly like a project repo. The PR title is the linked issue's title, or the branch's first commit subject without a `{workItem}`; the body is the drawer file with `Closes <ref>` appended, where `<ref>` is `#N` when the PR's repo is the tracker's repo and `{tracker-repo}#N` otherwise — only the first form closes an issue in the PR's own repo. If the push is rejected as non-fast-forward — the branch already existed on origin and step 1's rebase rewrote it — the script stops and says so; ask the user, and only on explicit confirmation re-run the same command with `--force-with-lease` (the script never forces on its own). If `workspace.forge` is `false` in `workspace.json`, the script refuses before pushing anything: forge operations are disabled in this workspace and the PR is opened by hand. `--out` writes the run's JSON to `prs-{slug}.json` for step 4 — `{ prs: [{ repo, owner, name, number, id, url, isWorkspace }], empty: [repo…], pushed: [repo…] }`, printed to stdout as well — instead of shell redirection, so the command is identical on every shell. The run is idempotent: a repo whose branch already has an open PR against `{defaultBranch}` gets that PR reused, never duplicated, and if the run fails partway the file still records what was pushed and opened so far — fix the cause and re-run the same command; it completes the set.
 
-   ```bash
-   git -C "{worktree}" remote get-url origin   # → parse {owner}/{name} FIRST
-   ```
-
-   If the URL does not parse into `{owner}/{name}` (a local/bare remote) or is a forge the adapter does not support, STOP before pushing anything: the task path supports forge-hosted repos only in this stage — complete that repo under the session model.
-
-   ```bash
-   git -C "{worktree}" push -u origin "{branch}"
-   ```
-
-   If the push is rejected as non-fast-forward — the branch already existed on origin and step 1 rebased it — ask the user before retrying with `git -C "{worktree}" push --force-with-lease`. Never force without asking.
-
-   If `workspace.forge` is `false` in `workspace.json`, STOP here: forge operations are disabled in this workspace — the push above is done, the PR is opened by hand.
-
-   ```javascript
-   // Run from {launcher-root} (see above). Imports stay relative: an absolute
-   // path is not a valid ESM specifier on Windows.
-   import { createForge } from './.claude/scripts/forges/interface.mjs';
-   import { createTracker } from './.claude/scripts/trackers/interface.mjs';
-   import { readFileSync } from 'node:fs';
-   const ws = JSON.parse(readFileSync('{launcher-root}/workspace.json', 'utf-8'));
-
-    // Constructed per repo, so the adapter never resolves the launcher's own remote.
-    const forge = createForge({ ...ws.workspace?.forge, repo: '{owner}/{name}' });
-    // For the workspace repo (.): from the workspace worktree's own origin.
-    const wsForge = createForge({ ...ws.workspace?.forge, repo: '{ws-owner}/{ws-name}' });
-
-    // PR title: the linked issue's title — tracker.getIssue(workItem).title —
-    // or, with no workItem, the subject of the branch's first commit beyond
-    // the base: git log "origin/{defaultBranch}..HEAD" --reverse --format=%s
-    // (run in "{worktree}").
-    const title = workItem
-      ? (await createTracker(ws.workspace.tracker).getIssue(workItem)).title
-      : firstCommitSubject;
-
-    // PR body: one line per commit from
-    // git -C "{worktree}" log "origin/{defaultBranch}..HEAD" --oneline,
-    // then a blank line and `Closes {workItem}` when a workItem exists.
-    const pr = await forge.prCreate({ title, body, head: '{branch}', base: '{defaultBranch}' });
-    // The workspace PR, when step 3 did not skip "." as empty:
-    const wsPr = await wsForge.prCreate({ title: `context: {branch} task`, body: workspacePrBody, head: '{branch}', base: '{defaultBranch}' });
-    ```
-
-4. **Ask before merging, then merge, then close the linked issue.** Present a summary per repo that got a PR — the workspace repo included — and ask once:
+4. **Ask before merging, then run `task-pr.mjs --merge`, which also closes the linked issue.** When step 3 reported `prs: []` — every repo was empty — there is nothing to merge: skip this step, say so, and leave the linked issue open for the user to decide (close it by hand, or keep the task going); `--merge` itself refuses an empty PRs file for exactly that reason. Otherwise present a summary per repo that got a PR — the workspace repo included — built from `--create`'s output, and ask once:
 
    ```
    Task complete:
@@ -466,30 +426,14 @@ If several tasks are open, ask the user which one to complete — group by branc
 
    On "n", stop: the PRs stay open and the worktrees, branches, and record entries stay in place — say so.
 
-   On "y", merge the project PRs first, each through the same per-repo forge. **If any project merge fails, do NOT merge the workspace PR** — stop, report the failure, and leave every unmerged PR open for retry: the workspace branch's promoted context describes the project merges and must never merge ahead of them. Merge must also precede close, because an issue closed before its PR merges points at work that never landed.
-
-   ```javascript
-   for (const pr of projectPrs) {
-     await forge.prMerge({ id: pr.id, strategy: 'squash', deleteBranch: true });
-   }
-   if (wsPr) await wsForge.prMerge({ id: wsPr.id, strategy: 'squash', deleteBranch: true }); // workspace PR, last
-   ```
-
-   Pull the launcher only after the workspace PR actually merged — it is still on its default branch, waiting on that merge; when `.` had no PR, pull after the project merges instead:
+   On "y":
 
    ```bash
-   git -C "{launcher-root}" pull --ff-only
-   ```
-
-   Then close the linked issue — only if a `{workItem}` exists — with a one-line comment naming the merged PR URL(s):
-
-   ```javascript
-   const tracker = createTracker(ws.workspace.tracker);
-   const comment = `Merged: ${prUrls.join(' ')}`; // prUrls = the .url of each PR merged above
-   await tracker.closeIssue(workItem, { comment });
+   node "{launcher-root}/.claude/scripts/task-pr.mjs" --merge --root "{launcher-root}" \
+     --prs "{launcher-root}/workspace-scratchpad/chats/{chat}/prs-{slug}.json" --work-item "{workItem}"
    ```
 
-   Without a `{workItem}` (no tracker, or the task was never recorded), skip the close and say so.
+   The script checks each PR's state first, then merges the project PRs (squash, delete branch), then the workspace PR only when every project merge succeeded — the workspace branch's promoted context describes the project merges and must never merge ahead of them. A PR the forge already reports as merged counts as done and is never merged twice, which is what makes a re-run safe: the run that finally gets every PR merged also does the pull and the close. The launcher is pulled `--ff-only` only when it sits on the workspace default branch — it waited there on the workspace merge, and a project-only task pulls after the project merges; when it sits on some other branch the JSON reports `pullSkipped: "launcher on <branch>"`, and a failed pull is reported as `pullFailed: true` rather than an error, because the merges stand and the issue still closes — in both cases tell the user to pull the launcher by hand before step 5. The close comes last, with a one-line comment naming the merged PR URL(s): merge precedes close because an issue closed before its PR merges points at work that never landed; without a `{workItem}` (no tracker, or the task was never recorded) the close is skipped and the script says so. On any merge failure the script stops, names the PRs still open, and exits non-zero — nothing is torn down, and re-running `--merge` once the failure is fixed is safe. After a successful merge, delete the drawer's `pr-{slug}-*.md` body files and the spent `prs-{slug}.json`.
 
 5. **Tear down only what finished — worktree first, then the record entry**, and only for a repo whose PR merged in step 4, or whose branch was empty and never pushed in step 3; the workspace repo included (`--repo "."`). If a repo's push, PR, or merge failed, or the user declined the merge, leave that repo's worktree, branch, and record entry exactly in place and say so: `--delete-branch` would otherwise `branch -D` commits that exist nowhere but the local worktree. For `.` the script never deletes the branch checked out at the launcher root.