@ulysses-ai/create-workspace 0.21.0-beta.0 → 0.23.0-beta.0

package/template/_claude/scripts/trackers/gitlab-issues.mjs

@@ -0,0 +1,276 @@
+// GitLab Issues adapter. Wraps the `glab` CLI via an injectable spawnFn
+// (mirrors trackers/github-issues.mjs). Issue IDs are opaque strings of the
+// form "gl:N" — adapters outside this file don't need to parse them;
+// routing is handled by interface.mjs.
+//
+// The repo is a `group/sub/project` path (any depth); a self-managed
+// instance is selected with `host` in the tracker config (GITLAB_HOST for
+// glab, --hostname for `glab api`), defaulting to gitlab.com.
+
+import '../../lib/require-node.mjs';
+import { spawnSync as nodeSpawnSync } from 'node:child_process';
+import { AlreadyAssignedError } from './interface.mjs';
+
+const GITLAB_DEFAULT_HOST = 'gitlab.com';
+
+const STANDARD_LABELS = [
+  { name: 'bug', color: 'd73a4a' },
+  { name: 'feat', color: 'a2eeef' },
+  { name: 'chore', color: 'cfd3d7' },
+  { name: 'P1', color: 'b60205' },
+  { name: 'P2', color: 'fbca04' },
+  { name: 'P3', color: '0e8a16' },
+];
+
+export function createGitlabAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
+  const repo = resolveRepo(config, spawnFn);
+  const host = typeof config?.host === 'string' && config.host ? config.host : GITLAB_DEFAULT_HOST;
+  let loginCache = null;
+
+  function glab(args, { input } = {}) {
+    // GITLAB_HOST always names the resolved instance — always, because an
+    // exported foreign value must not leak into a gitlab.com run — and
+    // aims the -R/--repo slugs at it.
+    const env = { ...process.env, GITLAB_HOST: host };
+    const result = spawnFn('glab', args, {
+      input,
+      encoding: 'utf-8',
+      env,
+      stdio: input !== undefined ? ['pipe', 'pipe', 'pipe'] : ['inherit', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0) {
+      throw new Error(`glab ${args.join(' ')} failed: ${(result.stderr || '').trim()}`);
+    }
+    return result.stdout || '';
+  }
+
+  // `glab api` resolves its host from the CWD's git remote, not from
+  // GITLAB_HOST, so the resolved host is always passed explicitly.
+  function apiArgs(path) {
+    return ['api', path, '--hostname', host];
+  }
+
+  // Paged walk over a `glab api` list endpoint — 100 at a time until a
+  // short page. The list subcommands fetch a single page and cannot
+  // express the server-side filters some of these calls need, so `glab
+  // api` does both jobs.
+  function apiListAll(path, params = []) {
+    const found = [];
+    for (let page = 1; ; page += 1) {
+      const query = [...params, 'per_page=100', `page=${page}`].join('&');
+      const batch = JSON.parse(glab(apiArgs(`${path}?${query}`)));
+      if (!Array.isArray(batch)) {
+        throw new Error(`glab api ${path} returned a non-list: ${JSON.stringify(batch).slice(0, 80)}`);
+      }
+      found.push(...batch);
+      if (batch.length < 100) break;
+    }
+    return found;
+  }
+
+  function currentUser() {
+    if (loginCache) return loginCache;
+    loginCache = JSON.parse(glab(apiArgs('user'))).username;
+    return loginCache;
+  }
+
+  function normalize(raw) {
+    return {
+      id: `gl:${raw.iid}`,
+      number: raw.iid,
+      title: raw.title,
+      body: raw.description || '',
+      state: (raw.state || '').toLowerCase() === 'closed' ? 'closed' : 'open',
+      assignees: (raw.assignees || []).map((a) => a.username),
+      labels: (raw.labels || []).map((l) => (typeof l === 'string' ? l : l.name)),
+      milestone: raw.milestone?.title ?? null,
+      url: raw.web_url,
+      createdAt: raw.created_at,
+      updatedAt: raw.updated_at,
+    };
+  }
+
+  function parseIssueNumber(issueId) {
+    const m = issueId.match(/^gl:(\d+)$/);
+    if (!m) throw new Error(`Not a GitLab issue ID: ${issueId}`);
+    return parseInt(m[1], 10);
+  }
+
+  async function listAssignedToMe() {
+    const me = currentUser();
+    // `glab issue list` defaults to open issues; JSON output is -O here,
+    // -F on the single-entity commands.
+    const stdout = glab(['issue', 'list', '--repo', repo, '--assignee', me, '-O', 'json', '--per-page', '100']);
+    return JSON.parse(stdout).map(normalize);
+  }
+
+  async function listUnassigned() {
+    // The API's server-side `assignee_id=None` filter, paged to the end —
+    // a client-side filter over one `issue list` page saw only the first
+    // hundred open issues.
+    return apiListAll(`projects/${encodeURIComponent(repo)}/issues`, ['state=opened', 'assignee_id=None'])
+      .map(normalize);
+  }
+
+  async function getIssue(issueId) {
+    const num = parseIssueNumber(issueId);
+    const stdout = glab(['issue', 'view', String(num), '--repo', repo, '-F', 'json']);
+    return normalize(JSON.parse(stdout));
+  }
+
+  async function claim(issueId) {
+    const me = currentUser();
+    const issue = await getIssue(issueId);
+    const others = issue.assignees.filter((a) => a !== me);
+    if (others.length > 0) {
+      throw new AlreadyAssignedError(issueId, others);
+    }
+    if (!issue.assignees.includes(me)) {
+      // --assignee replaces the assignee list; with no other assignees
+      // (checked above) that is exactly "assign me".
+      glab(['issue', 'update', String(issue.number), '--repo', repo, '--assignee', me]);
+      return getIssue(issueId);
+    }
+    return issue;
+  }
+
+  async function createIssue({ title, body = '', labels = [], milestone = null }) {
+    const args = ['issue', 'create', '--repo', repo, '--title', title, '--description', body, '--yes'];
+    if (labels.length > 0) args.push('--label', labels.join(','));
+    if (milestone) args.push('--milestone', milestone);
+    const stdout = glab(args);
+    const m = stdout.match(/\/-\/issues\/(\d+)/);
+    if (!m) throw new Error(`Could not parse issue number from: ${stdout.trim()}`);
+    return getIssue(`gl:${m[1]}`);
+  }
+
+  async function comment(issueId, body) {
+    const num = parseIssueNumber(issueId);
+    // glab has no --body-file: the message travels as an argv element.
+    glab(['issue', 'note', String(num), '--repo', repo, '--message', body]);
+  }
+
+  // A closing reference for MR bodies: `#N` closes an issue in the MR's own
+  // project, `group/sub/project#N` reaches one living elsewhere — the same
+  // shapes github-issues renders, with GitLab's full-path reference for the
+  // cross-project case. No `fromRepo` means the MR is in this adapter's own
+  // project.
+  function issueRef(issueId, { fromRepo } = {}) {
+    const num = parseIssueNumber(issueId);
+    return fromRepo && fromRepo !== repo ? `${repo}#${num}` : `#${num}`;
+  }
+
+  // The canonical URL for an issue — what a cross-forge reference needs
+  // (a `group/sub#N` reference cannot resolve on a GitHub PR), minted from
+  // the same host/repo every other URL here is built from.
+  function issueUrl(issueId) {
+    const num = parseIssueNumber(issueId);
+    return `https://${host}/${repo}/-/issues/${num}`;
+  }
+
+  async function closeIssue(issueId, { comment: commentBody } = {}) {
+    const num = parseIssueNumber(issueId);
+    if (commentBody) {
+      glab(['issue', 'note', String(num), '--repo', repo, '--message', commentBody]);
+    }
+    glab(['issue', 'close', String(num), '--repo', repo]);
+  }
+
+  async function ensureLabels() {
+    // No --force equivalent: labels that exist are left as they are, so
+    // this stays idempotent without rewriting a team's chosen colors.
+    const stdout = glab(['label', 'list', '--repo', repo, '-F', 'json', '--per-page', '100']);
+    const existing = new Set(JSON.parse(stdout).map((l) => l.name));
+    for (const { name, color } of STANDARD_LABELS) {
+      if (existing.has(name)) continue;
+      glab(['label', 'create', '--repo', repo, '--name', name, '--color', `#${color}`]);
+    }
+  }
+
+  // `glab milestone create` prints human text (it has no JSON output flag),
+  // and `milestone list` fetches a single page — so listing goes through
+  // the API paged to the end, and a create is verified by re-listing
+  // rather than by parsing what glab printed.
+  async function ensureMilestone({ title, description = '', dueOn = null } = {}) {
+    if (!title) throw new Error('ensureMilestone: title is required');
+    const findByTitle = () => apiListAll(`projects/${encodeURIComponent(repo)}/milestones`)
+      .find((m) => m.title === title);
+    const existing = findByTitle();
+    if (existing) return normalizeMilestone(existing);
+    const args = ['milestone', 'create', '--repo', repo, '--title', title];
+    if (description) args.push('--description', description);
+    if (dueOn) args.push('--due-date', dueOn);
+    glab(args);
+    const created = findByTitle();
+    if (!created) {
+      throw new Error(`milestone "${title}" was not in the milestone list after glab milestone create`);
+    }
+    return normalizeMilestone(created);
+  }
+
+  return {
+    listAssignedToMe,
+    listUnassigned,
+    getIssue,
+    claim,
+    createIssue,
+    comment,
+    closeIssue,
+    issueRef,
+    issueUrl,
+    ensureLabels,
+    ensureMilestone,
+    get identity() { return `gitlab-issues:${repo}`; },
+  };
+}
+
+function normalizeMilestone(raw) {
+  return {
+    number: raw.id,
+    title: raw.title,
+    description: raw.description || '',
+    state: raw.state === 'closed' ? 'closed' : 'open', // GitLab says "active"
+    dueOn: raw.due_date || null,
+    url: raw.web_url,
+  };
+}
+
+// Like github-issues.mjs's resolveRepo, kept local so the adapter stands
+// alone: gitlab.com plus the configured self-managed host, scp-style and
+// scheme URLs (an explicit non-default port stays in the host, so `host`
+// can carry it — gitlab.example.com:8443), nested groups at any depth,
+// optional .git suffix.
+const DEFAULT_PORTS = { https: 443, http: 80, ssh: 22, git: 9418 };
+const SCHEME_URL_RE = /^(?<scheme>https?|ssh|git):\/\/(?:[^@/]+@)?(?<host>[^:/]+)(?::(?<port>\d+))?\/(?<path>.+)$/;
+
+function resolveRepo(config, spawnFn) {
+  if (config?.repo && config.repo !== 'auto') return config.repo;
+  const result = spawnFn('git', ['remote', 'get-url', 'origin'], { encoding: 'utf-8' });
+  if (result.status !== 0) {
+    throw new Error(`git remote get-url failed: ${(result.stderr || '').trim()}`);
+  }
+  const hosts = [GITLAB_DEFAULT_HOST, ...(config?.host ? [String(config.host).toLowerCase()] : [])];
+  const s = result.stdout.trim().replace(/\/+$/, '');
+  let host = null;
+  let path = null;
+  const scp = s.match(/^[^@/]+@([^:/]+):(.+)$/); // scp-style: git@host:path
+  if (scp) {
+    host = scp[1].toLowerCase();
+    path = scp[2];
+  } else {
+    const m = s.match(SCHEME_URL_RE);
+    if (m) {
+      const { scheme, host: h, port } = m.groups;
+      // A non-default port stays part of the host so it can match a
+      // configured host that carries one; a default port drops, so
+      // github.com:443-style URLs still resolve.
+      host = (port && Number(port) !== DEFAULT_PORTS[scheme] ? `${h}:${port}` : h).toLowerCase();
+      path = m.groups.path;
+    }
+  }
+  if (host && path && hosts.includes(host)) {
+    const segments = path.replace(/\.git$/, '').split('/').filter(Boolean);
+    if (segments.length >= 2) return segments.join('/');
+  }
+  throw new Error(`Cannot parse GitLab remote: ${result.stdout.trim()}`);
+}

package/template/_claude/scripts/trackers/interface.mjs

@@ -11,6 +11,7 @@
 
 import '../../lib/require-node.mjs';
 import { createGithubAdapter } from './github-issues.mjs';
+import { createGitlabAdapter } from './gitlab-issues.mjs';
 
 export class AlreadyAssignedError extends Error {
   constructor(issueId, assignees) {
@@ -28,6 +29,8 @@ export function createTracker(config, options = {}) {
   switch (config.type) {
     case 'github-issues':
       return createGithubAdapter(config, options);
+    case 'gitlab-issues':
+      return createGitlabAdapter(config, options);
     default:
       throw new Error(`Unknown tracker type: ${config.type}`);
   }

package/template/_claude/skills/complete-work/SKILL.md

@@ -13,15 +13,16 @@ Finalize the active work session. Handles all project repos (code changes, PRs)
 
 Read the active-session pointer from `.claude/.active-session.json` in the current worktree. If it is present, this chat runs inside a session worktree: continue with this flow unchanged.
 
-If no pointer is present, run work-model detection — this covers the task model, whose chats run at the workspace root (the launcher), not inside a worktree:
+If no pointer is present, run work-model detection — this covers lane chats, which run at the workspace root (the launcher) rather than inside a worktree, for both lifecycles:
 
 ```bash
-node "{launcher-root}/.claude/scripts/task-worktree.mjs" --root "{launcher-root}" --detect --chat "{chat}"
+node "{launcher-root}/.claude/scripts/task-worktree.mjs" --root "{launcher-root}" --detect --chat "{chat}" [--session-id "{id}"]
 ```
 
 - `{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, 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`.
+- `{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 and the session id alone. Detection also matches this chat's session id against each `work-sessions/*/workspace/session.md` `chatSessions` list, so a lane chat that drove an old-model session by path is findable from the launcher. Pass `--session-id` when the id is known from somewhere else; otherwise it resolves from the chat record's `sessionId`, then `$CLAUDE_CODE_SESSION_ID`, in that order.
+- `model: session` → continue with this flow (read the session tracker as below), taking `{session-name}` from the detect result's `sessionName`. When detection ran at the launcher the result instead carries `source: "chat-sessions"` and a `sessions` list — present the entries (each `{ name, branch, workItem, status }`) and ask which to finish; `{session-name}` is the chosen entry's `name`.
+- `model: mixed` → this chat has open tasks AND sessions its id is registered in. List both — each session as `{name} ({status}, {branch})`, each task group as `{branch}` (grouping by branch as below) — and ask which to finish. A session continues this session flow with that `{session-name}`; a task goes to **Task completion (session model v2)**.
 - `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."
 
@@ -376,6 +377,8 @@ Reached from Step 1 when detection says `model: task`. The state is the branch,
 
 If several tasks are open, ask the user which one to complete — group by branch; a multi-repo task is several entries sharing a branch — and complete one branch at a time.
 
+Notes meant for another chat are not drawer notes. The drawer is per-chat and machine-local — no other chat can read it, and this machine is its only copy — so nothing in it survives a handoff. Anything the next chat (or the operator, from another machine) needs to continue this task — decisions, gotchas, where work stopped — goes on the linked issue as a comment through the tracker adapter (`await tracker.comment("{workItem}", body)`), where every chat can read it.
+
 0. **Pre-flight: the worktrees must be clean.** For each `{worktree}` of the chosen task, `git -C "{worktree}" status --porcelain` must be empty. If it is not, stop here — before the rebase — and ask the user to commit or discard: rebasing over uncommitted work silently invalidates it.
 
 1. **Rebase each task worktree onto its base** — `origin/{defaultBranch}` for a `forge` repo (`git -C "{worktree}" fetch origin`, then `git -C "{worktree}" rebase "origin/{defaultBranch}"`), the local `{defaultBranch}` for a `local` repo (`git -C "{worktree}" rebase "{defaultBranch}"`; no fetch — there is no remote to fetch from). 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.

package/template/_claude/skills/migrate-sessions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: migrate-sessions
-description: Migrate this workspace from the session lifecycle to the task lifecycle — inventory old work sessions, decide each one with the operator, finish or archive them, and switch workspace.json to the task model. Runs only inside the current workspace; never deletes anything.
+description: Migrate this workspace from the session lifecycle to the task lifecycle — inventory old work sessions, decide each one with the operator, finish or archive them (empty orphan shells only: remove), and switch workspace.json to the task model. Runs only inside the current workspace; the script never deletes anything.
 ---
 
 # Migrate Sessions
@@ -19,12 +19,18 @@ node .claude/scripts/migrate-sessions.mjs --inventory
 
 Read-only. Present the stderr table plus each session's proposal with its reasons and warnings. Say plainly that the proposals are proposals — evidence and a starting point, not decisions. Pay particular attention to the per-remote state shown per worktree (`same`, `ahead +N`, `behind -N`, `diverged +N/-M`, `not-fetched`, `unknown`) and to `unbacked` warnings: they change what Finish and Archive mean for that session. Each worktree also lists every configured remote with its exact URL — read those before any backup decision: `origin:none` means only that the remote holds no copy of this branch, never that the repo has no remote, and an `origin` that is really a third-party upstream shows its URL right there. Entries shown as `foreign` (symlinked) are never acted on — surface them for manual reconciliation.
 
+Three more kinds of evidence change what you propose:
+
+- **Fetch age** — every worktree line ends `fetch:…` with the age of its repo's last fetch, and anything over a day draws a `stale-fetch` warning: the commits-ahead and content counts ride on tracking refs frozen at that fetch. Tell the operator to fetch first, or re-run with `--inventory --fetch`, which fetches each touched source clone before inspecting it. A fetch is read-only with respect to the workspace's own state — it moves no local branch and touches no worktree, only refs/remotes/* and the object store — and a repo with no origin or an unreachable one is recorded as skipped or failed, never fatal.
+- **Open chats** — `chat open?` on a session (with a `chat-open` warning) means its tracker records a chat session with no `ended:` — a chat may still be working in it. Confirm with the operator before proposing Archive.
+- **External worktrees** — a trailing section lists worktrees the workspace's repos register outside the workspace root (a scratch checkout in tmp, a directory elsewhere). They belong to no session: nothing in this migration prunes, moves, or removes them, and you never should either — including by hand, because `git worktree prune` has no path filter and would drop their records.
+
 ## 2. Decide per session, with the operator — one at a time
 
 For each session, lay out its evidence and ask the operator which way to go. Never infer the decision from the proposal. The options:
 
-- **Finish** (typical for MERGEABLE) — resume the session with `/start-work`, then run `/complete-work`; its own merge confirmation applies there. But if the inventory shows a **diverged** remote for that session, say so *before* the operator chooses Finish: `/complete-work`'s plain push will be rejected, and pushing the rewritten history needs `--force-with-lease` — which you run only on the operator's explicit yes naming the branch. Never force silently.
-- **Archive** (typical for ABANDONED, a broken shell, or a MERGEABLE the operator gives up on) — take it out of the active lifecycle without destroying anything. Three steps, in this order, each its own decision:
+- **Finish** (typical for MERGEABLE, and the default offer for READY_TO_COMPLETE — a session `/complete-work` stopped partway through: tracker already stripped, worktrees still live, branch often already pushed) — resume it with `/start-work` (its walk lists sessions by their tracker, so a stripped one will not appear — name it and re-create a minimal tracker from the inventory's branch/repos before continuing), then run `/complete-work`; its own merge confirmation applies there. But if the inventory shows a **diverged** remote for that session, say so *before* the operator chooses Finish: `/complete-work`'s plain push will be rejected, and pushing the rewritten history needs `--force-with-lease` — which you run only on the operator's explicit yes naming the branch. Never force silently.
+- **Archive** (typical for ABANDONED, an ORPHAN_SHELL that still holds files, or a MERGEABLE the operator gives up on) — take it out of the active lifecycle without destroying anything. When the inventory shows `chat open?`, confirm with the operator that the chat is really done before offering Archive — a live chat's uncommitted work would ride into the archive unseen. Three steps, in this order, each its own decision:
   1. **Clear uncommitted work.** `--archive` refuses when any of the session's worktrees has uncommitted or untracked changes — an edited `session.md` counts — and names them, because edits buried uncommitted in an archive are invisible to every later merge or PR. Offer the operator: commit them to the session branch first (`git -C {worktree} add -A`, then `git -C {worktree} commit -m "…"` — per dirty worktree), discard them explicitly (`git -C {worktree} restore …` / `git -C {worktree} clean …`), or, on an explicit yes, re-run with `--allow-uncommitted` to archive them mid-edit. Do this before the backup: the backup tags committed tips only, so committing first brings those edits under the backup, while anything archived with `--allow-uncommitted` is NOT in it.
   2. **Offer a backup.** Archiving keeps everything on this machine; a backup adds an off-machine copy of the session's commits, and it is what makes a later deletion safe. It covers the committed tips as they stand after step 1. Plain `--backup` creates `drain/{session}/…` tags locally and pushes nothing — for a repo whose only remote is one the operator does not own, that local tag IS the backup. Pushing is a separate, explicitly allowed step:
      ```bash
@@ -32,6 +38,10 @@ For each session, lay out its evidence and ask the operator which way to go. Nev
      ```
      With no allow flag this pushes nothing and exits non-zero, listing per repo the tag and the exact URL(s) it would push to. Approve against the push URL, not the fetch URL: a remote whose push URL differs from its fetch URL shows both, and the script refuses to push there on `--remote-allow-all` — only an explicit `--remote-allow {repo}={remote}` naming it proceeds. Walk the operator through every URL and ask per repo. **Never push backup tags to a remote the operator does not own — a third-party upstream, a read-only mirror, an unfamiliar push URL; pushing `drain/*` tags there publishes the session's commits somewhere foreign.** On yes for repos they do own, re-run adding `--remote-allow {repo}={remote}` per repo (`.` is the workspace repo; `--remote-allow-all` only when every listed URL is their own) and show what was pushed. Declining is fine — the archive still keeps everything locally.
   3. **Archive after an explicit yes naming the session:** `node .claude/scripts/migrate-sessions.mjs --archive --session {name}`. The whole session folder moves to `{sessions}/.archived/{name}--{timestamp}/` and git's worktree links are repaired to follow it — every commit, uncommitted edit, untracked or ignored file, and embedded repository comes along. If the move or the repair fails, the session is put back and the result says whether every link was verified. The session's branches stay checked out in the archived worktrees, so a new task cannot reuse those branch names until the archive is deleted. The archive refuses, touching nothing, when a directory in the folder cannot be read, when the folder holds a worktree of a repository outside this workspace, or when it holds a submodule checkout (its link cannot be repaired) — surface the reason; for a submodule the options are Finish or Keep. Relay any `warnings` (relative symlinks that pointed outside the session no longer resolve after the move).
+- **Remove** (only an ORPHAN_SHELL the inventory marked empty — no worktree, nothing but empty directories, so there is nothing to archive). The command re-verifies emptiness itself and refuses, touching nothing, if any file or symlink has appeared since the inventory; a refusal means switch to Archive:
+  ```bash
+  node -e "const fs=require('fs');const p=process.argv[1];const empty=d=>fs.readdirSync(d,{withFileTypes:true}).every(e=>e.isDirectory()&&empty(d+'/'+e.name));if(!empty(p)){console.error(p+' is not empty — left alone');process.exit(1)}fs.rmSync(p,{recursive:true});console.log('removed empty shell '+p)" work-sessions/{name}
+  ```
 - **Keep** (typical for ACTIVE, and the only sane answer for UNKNOWN) — leave it; it completes later under the session lifecycle.
 
 Unbacked commits (present on no remote) are safe in an archive — they are only ever at risk when someone deletes one. Say so when you archive such a session, and offer the backup.
@@ -48,7 +58,13 @@ The switch procedure:
    ```bash
    node .claude/scripts/migrate-sessions.mjs --enable-task-model --root .claude/worktrees/chore-enable-task-model
    ```
-3. Land the change. With a forge-hosted remote, commit there, open a PR through the workspace's normal flow, and pull the launcher after merge. Without one (`git -C . remote -v` shows no remote this workspace can open PRs against), land it locally — commit in the worktree, fast-forward the launcher's default branch, remove the worktree:
+3. Land the change the way any task lands. A forge-hosted remote (GitHub, GitLab) means a PR/MR through `task-pr.mjs` — the launcher's default branch is protected on a real forge, so landing directly on it is not an option anyway. Commit in the worktree, write a short PR body (what changed, how it was verified) to a scratch file under `workspace-scratchpad/`, then create, ask before merging, and pull the launcher after the merge:
+   ```bash
+   node .claude/scripts/task-pr.mjs --create --root . --branch chore/enable-task-model \
+     --repo . --body-file .=workspace-scratchpad/switch-pr.md --out workspace-scratchpad/switch-prs.json
+   node .claude/scripts/task-pr.mjs --merge --root . --prs workspace-scratchpad/switch-prs.json
+   ```
+   Only a workspace whose repo has no remote at all (`git -C . remote -v` empty) lands locally — commit in the worktree, fast-forward the launcher's default branch, remove the worktree:
    ```bash
    git -C .claude/worktrees/chore-enable-task-model add workspace.json
    git -C .claude/worktrees/chore-enable-task-model commit -m "chore: switch to the task lifecycle"

package/template/_claude/skills/release/SKILL.md

@@ -23,19 +23,22 @@ Release notes come from the forge. GitHub's generated notes (merged PR titles) a
 Ask which repo to release — read `repos` from `workspace.json` and default to the entry with `"primary": true`. If no version was given, ask the bump kind (patch/minor/major) after showing the merged PRs since the last tag, so the operator can judge the impact:
 
 ```bash
-git -C repos/{repo} describe --tags --abbrev=0
+git -C repos/{repo} describe --tags --abbrev=0        # v{previous}
+git -C repos/{repo} log -1 --format=%cI v{previous}   # the previous tag's commit time
 ```
 
-Then call the forge adapter's `prList` with a merged-after search bounded by that tag's date (e.g. `merged:>{date}`). Pre-v1.0 breaking changes are a minor bump.
+Then call the forge adapter's `prList` with `state: 'merged'`, `base:` the repo's default branch, and a merged-after search bounded by that tag's commit time — the full `%cI` timestamp (e.g. `merged:>2026-05-01T10:00:00Z`), never a bare date, which would sweep in every PR merged later the same day. `base` matters because PRs merged into other branches are not this release. If the returned list carries `truncated: true`, older PRs may sit beyond the fetched page — say so and re-query with a higher `limit` before judging the bump. Pre-v1.0 breaking changes are a minor bump.
 
-**Step 2: Preflight the tag**
+**Step 2: Preflight the tag and the forge**
 
-If `v{version}` already exists on origin, stop and ask — reuse it, investigate with `forge.releaseView`, or pick another version. Never force-push a tag.
+Two checks before anything is pushed. First the tag: if `v{version}` already exists on origin, stop and ask — reuse it, investigate with `forge.releaseView`, or pick another version. Never force-push a tag.
 
 ```bash
 git -C repos/{repo} ls-remote --exit-code origin refs/tags/v{version}
 ```
 
+Second the release path. Build the repo's forge with `forgeConfigForRepo(root, '{repo}', ws)` from `.claude/scripts/merge-mode.mjs` — it picks the adapter from the repo's own origin, so a GitLab repo gets the gitlab adapter whatever `workspace.forge` says — and decide now who creates the release (Step 5): the repo's CI, or this skill. If the flow needs something the forge cannot do, stop here — past this point the tag is pushed, and a publish that cannot run is much harder to unwind.
+
 **Step 3: Bump on a branch**
 
 Create a task worktree for the release branch:
@@ -48,7 +51,7 @@ If the repo has a `package.json` with a `version`, set it to `{version}` (edit t
 
 **Step 4: Merge**
 
-Push the branch and open a PR through the forge adapter — per-repo `createForge({ ...ws.workspace?.forge, repo: '{owner}/{name}' })` with head `release/v{version}`. Ask `Merge? [Y/n]`, then merge (squash, delete branch).
+Push the branch and open a PR through the same per-repo forge (`forgeConfigForRepo` from Step 2) with head `release/v{version}`. Ask `Merge? [Y/n]`, then merge (squash, delete branch).
 
 **Step 5: Tag and publish**
 
@@ -60,15 +63,28 @@ git -C repos/{repo} tag v{version}
 git -C repos/{repo} push origin v{version}
 ```
 
-Who creates the release depends on the repo. If `.github/workflows/publish.yml` exists and itself creates the release (it contains `gh release create`, `softprops/action-gh-release`, or `actions/create-release`), the workflow owns the release — do not call `releaseCreate`; racing it duplicates the release or fails. Instead find and watch its run with `workflowRunFind` / `workflowRunWatch` — retry the find up to 5 times with 3 s backoff (the run may not be registered the moment the tag lands); a failed run is reported to the operator, not thrown — then confirm the release exists with `forge.releaseView({ tag: 'v{version}', repo })`.
+Who creates the release depends on the repo, and the CI check is per-forge:
+
+- **GitHub**: `.github/workflows/publish.yml` that itself creates the release (it contains `gh release create`, `softprops/action-gh-release`, or `actions/create-release`) owns the release — do not call `releaseCreate`; racing it duplicates the release or fails. Instead find and watch its run with `workflowRunFind` / `workflowRunWatch` — retry the find up to 5 times with 3 s backoff (the run may not be registered the moment the tag lands); a failed run is reported to the operator, not thrown.
+- **GitLab**: `.gitlab-ci.yml` with a `release:` keyword block (a release-cli job) owns the release the same way — do not call `releaseCreate`; find and watch the tag's pipeline with `workflowRunFind({ workflow: 'ci.yml', branch: 'v{version}' })` / `workflowRunWatch` (the workflow name is ignored — one pipeline per ref).
+
+Either way, confirm the release exists with `forge.releaseView({ tag: 'v{version}', repo })`.
 
-Otherwise the skill creates the release itself:
+Otherwise the skill creates the release itself — on GitHub the forge generates the notes; on GitLab it cannot (`NOT_SUPPORTED`), so the notes come from the same query Step 1 ran:
 
 ```js
+// GitHub
 await forge.releaseCreate({ tag: 'v{version}', repo, generateNotes: true });
+// GitLab — notes come from the skill, not the forge. tagTime is the %cI of
+// v{previous}; base excludes MRs merged into other branches.
+const merged = await forge.prList({ state: 'merged', base: '{default branch}',
+  search: `merged:>${tagTime}`, repo });
+if (merged.truncated) warn('older MRs may be missing — raise limit and re-query');
+await forge.releaseCreate({ tag: 'v{version}', repo, generateNotes: false,
+  notes: merged.map((p) => `- ${p.title}`).join('\n') });
 ```
 
-If a `publish.yml` without release creation exists, still find and watch its run the same way.
+If a `publish.yml` (or a publish job) without release creation exists, still find and watch its run the same way.
 
 **Step 6: Tear down and report**
 

package/template/_claude/skills/setup-tracker/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-tracker
-description: Configure an issue tracker for this workspace — writes workspace.json → tracker block and initializes labels. GitHub Issues is the only backend shipped; others can be added by dropping an adapter at .claude/scripts/trackers/{type}.mjs. Runnable during /workspace-init or standalone.
+description: Configure an issue tracker for this workspace — writes workspace.json → tracker block and initializes labels. GitHub Issues and GitLab Issues are the shipped backends; others can be added by dropping an adapter at .claude/scripts/trackers/{type}.mjs. Runnable during /workspace-init or standalone.
 ---
 
 # Setup Tracker
@@ -10,7 +10,7 @@ Wire this workspace up to an external issue tracker. The tracker becomes the sou
 ## Prerequisites
 
 - `.claude/rules/work-item-tracking.md` should be active. If missing, warn but continue.
-- The adapter for the chosen backend must exist at `.claude/scripts/trackers/{type}.mjs`. The template ships `github-issues.mjs`.
+- The adapter for the chosen backend must exist at `.claude/scripts/trackers/{type}.mjs`. The template ships `github-issues.mjs` and `gitlab-issues.mjs`.
 
 ## Flow
 
@@ -20,15 +20,16 @@ Read `workspace.json` → `workspace.tracker`. If already configured: "Tracker i
 
 ### Step 2: Pick a backend
 
-Ask: "Which issue tracker?"
+Offer the backend that matches the workspace's own remote first — run `git -C {workspace-root} remote get-url origin` and suggest GitLab Issues when the host is `gitlab.com` or the workspace's configured GitLab `host`, GitHub Issues otherwise. Then ask: "Which issue tracker?"
 1. GitHub Issues (shipped)
-2. Linear — not yet supported
-3. Jira — not yet supported
-4. None — skip
+2. GitLab Issues (shipped)
+3. Linear — not yet supported
+4. Jira — not yet supported
+5. None — skip
 
-For (2) and (3): tell the user the adapter isn't shipped and exit. To add one, write a module at `.claude/scripts/trackers/{type}.mjs` that implements the contract in `.claude/scripts/trackers/interface.mjs`.
+For (3) and (4): tell the user the adapter isn't shipped and exit. To add one, write a module at `.claude/scripts/trackers/{type}.mjs` that implements the contract in `.claude/scripts/trackers/interface.mjs`.
 
-For (4): exit — no changes.
+For (5): exit — no changes.
 
 ### Step 3: GitHub Issues configuration
 
@@ -96,14 +97,47 @@ For (4): exit — no changes.
    ```
    Expected: empty list (no tickets yet) or the existing ones if the repo already had issues.
 
-### Step 4: Report
+### Step 4: GitLab Issues configuration
+
+1. **Verify `glab` auth.** Run `glab auth status`. For a self-managed instance, walk through `glab auth login --hostname {host}`. Do not proceed until authenticated.
+
+2. **Resolve the target project.** Default to the workspace's own git remote (`git -C {workspace-root} remote get-url origin`, parsed as above). Ask: "Use `{group/sub/project}` for issues, or a different project?" Accept any nested `group/sub/project` path.
+
+   GitLab projects have issues enabled by default, so there is no equivalent of the GitHub `hasIssuesEnabled` check.
+
+3. **Write `workspace.json`:**
+   ```json
+   {
+     "workspace": {
+       "tracker": {
+         "type": "gitlab-issues",
+         "repo": "{group/sub/project}",
+         "host": "{host}"
+       }
+     }
+   }
+   ```
+   Include `"host"` only for a self-managed instance — omit it for gitlab.com. Preserve all other fields. Commit:
+   ```bash
+   git add workspace.json
+   git commit -m "chore: configure gitlab-issues tracker on {group/sub/project}"
+   ```
+
+4. **Initialize labels and (optionally) milestones** exactly as in Step 3 — the one-liners go through `createTracker`, so the same commands work against GitLab.
+
+5. **Verify:**
+   ```bash
+   glab issue list --repo {group/sub/project} --per-page 5
+   ```
+
+### Step 5: Report
 
 ```
 Tracker configured:
-  Type: github-issues
+  Type: {github-issues | gitlab-issues}
   Repo: {slug}
   Labels: bug, feat, chore, P1, P2, P3
-  Milestones: {list or "(none — add via GitHub UI or gh api)"}
+  Milestones: {list or "(none — add via the forge UI)"}
 
 Next: run /start-work to pick or create an issue and begin.
 ```
@@ -113,5 +147,5 @@ Next: run /start-work to pick or create an issue and begin.
 - The workspace repo is the default target — no separate `workspace-{project}` repo needed.
 - Issues track everything across all project repos in the workspace. Cross-repo work items live in one place.
 - One-way integration: the tracker is the source of truth. Skills read and write via the adapter; nothing else reflects tracker state locally.
-- If `gh auth login` later expires, skill flows will surface `gh` errors — re-run `gh auth login` and try again.
+- If CLI auth later expires, skill flows will surface `gh`/`glab` errors — re-run `gh auth login` (or `glab auth login --hostname {host}`) and try again.
 - Adding a new backend: write an adapter module at `.claude/scripts/trackers/{type}.mjs` implementing the interface in `interface.mjs`, then add a case in the `createTracker` switch statement.

package/template/_claude/skills/start-work/SKILL.md

@@ -21,7 +21,20 @@ New work as a task: one tracker issue, one branch, one worktree per repo the wor
 
 If `workspace.tracker` is absent, say tracking is off and skip step 1 — but still ask for the type (`bug` / `feat` / `chore`) and a one-line description, because the type picks the branch prefix — then continue with steps 2–6. What that costs: without a tracker there is no `workItem` and no issue to close at completion — the task is still recorded on the chat record (with no work item, keyed by repo + branch), so `/complete-work` finds it from the launcher like any other task.
 
-1. **Identify or create the tracker issue and claim it.** If the invocation's arguments already name an issue — `gh:N`, `#N`, or an issue URL — normalize it to the adapter's id (`#42` and a `.../issues/42` URL both mean `gh:42`), fetch it with `tracker.getIssue(id)`, claim it when it is not yet assigned to you (with the same `ALREADY_ASSIGNED` handling as the fallback pick below), and skip the candidate list entirely. Otherwise, list the candidates — the same adapter calls as Flow: Blank steps 3–6:
+1. **Identify or create the tracker issue and claim it.** If the invocation's arguments already name an issue — `gh:N`, `#N`, or an issue URL — normalize it to the adapter's id (`#42` and a `.../issues/42` URL both mean `gh:42`) and fetch it with `tracker.getIssue(id)`. Then check whether the issue already has a task before claiming anything — another chat may have started it (gh:188):
+
+   ```bash
+   node .claude/scripts/chat-record.mjs --root . --owner "{workItem}"
+   ```
+
+   Exit 1 means no chat owns a task for the issue: claim it when it is not yet assigned to you (with the same `ALREADY_ASSIGNED` handling as the fallback pick below) and skip the candidate list entirely. Exit 0 prints `{ chat, branch, repos }` — a task exists. First make sure its worktrees are there: run step 4's `--create` for each of `repos`; over an existing branch or worktree `--create` REUSES what it finds (`created: false`) — it never fails or duplicates. Then ask the operator which way to take it:
+   - **Adopt into this chat** — record the task with step 5's `--add-task`, and remove it from the old chat's record (`--remove-task --chat "{owner.chat}"` with the same selectors) only when the operator says that chat is done with it. While both chats still work the task, both records legitimately list it — the branch and worktrees are shared, not duplicated.
+   - **Leave it with the owner** — message the owning chat via SendMessage using the name `--owner` printed (the record name doubles as the session-registry name SendMessage reaches a chat by) and stop here.
+   - When `--owner` names this chat, it is a resume of your own task: reuse the worktrees as above and continue.
+
+   Notes another chat will need to continue the task never go in this chat's drawer — the drawer is per-chat and machine-local. Put them on the issue as a comment (`await tracker.comment("{workItem}", body)`), where any chat can read them.
+
+   When the invocation's arguments name no issue, list the candidates — the same adapter calls as Flow: Blank steps 3–6 (an issue picked from the list gets the same `--owner` check once its id is known):
 
    ```javascript
    import { createTracker } from './.claude/scripts/trackers/interface.mjs';
@@ -91,7 +104,7 @@ If `workspace.tracker` is absent, say tracking is off and skip step 1 — but st
    - Workspace: `work-sessions/{name}/workspace/`
    - For each repo in `repos:` frontmatter: `work-sessions/{name}/workspace/repos/{repo}/`
    - If any are missing, recreate from the branch
-3. The session-start hook automatically registers each chat in the session tracker's `chatSessions` frontmatter when Claude opens in a worktree. Verify the current chat is registered — if not (e.g., the hook didn't fire), append an entry using the invocation shown under "Create work session" below (the helper is an importable library, not a CLI).
+3. The session-start hook automatically registers each chat in the session tracker's `chatSessions` frontmatter when Claude opens in a worktree. A lane chat resuming from the launcher is never opened there, so the hook cannot register it. Verify the current chat is registered — from either starting point — and when it is not, append an entry using the invocation shown under "Create work session" below (the helper is an importable library, not a CLI). Take the chat's UUID from this chat's record: `node .claude/scripts/chat-record.mjs --root . --read "{chat}"` prints it as `sessionId` (the `Chat record:` hook line names `{chat}`). The id matters — it is what `/complete-work` later matches this session by from the launcher.
 
    Each `chatSessions` entry has this shape:
    ```yaml

package/template/_claude/skills/workspace-init/SKILL.md

@@ -126,6 +126,12 @@ Also install these top-level files from the payload:
 
 **Per-repo CLAUDE.md stubs:** For each repo in `workspace.json`, check if `repos/{repo}/CLAUDE.md` exists. If not, ask "Scaffold a CLAUDE.md for {repo}? [Y/n]". If yes, write a blank stub from `.workspace-update/repo-claude.md.tmpl`, substituting `{{repo-name}}` with the repo name. The stub body is comment text only — no workspace-specific content — and its `## Commands` section is where you will add repo-specific test, lint, and build commands.
 
+**Write the template baseline** now that the components are installed, so future `/workspace-update` runs can tell template changes from local edits (three-way classification):
+```bash
+node .claude/scripts/classify-update.mjs --root . --write-baseline --payload .workspace-update
+```
+It hashes the payload's verbatim files — run it before Step 15 deletes the payload.
+
 **Commit:** `git commit -m "feat: install template components from payload"`
 
 ### Step 6: Activate optional rules