@ulysses-ai/create-workspace 0.23.3-beta.0 → 0.24.0-beta.0

package/template/_claude/scripts/template-merge.mjs

@@ -45,6 +45,12 @@
 //     "out":          "<resolved output dir>",
 //     "templateBase": "<resolved base dir, or null when none was staged>" }
 //
+// A differs file registered in .claude/template-modifications.json carries
+// its recorded reason (gh:194): merged/conflicted entries gain a `reason`
+// field, and a noBase path becomes { path, reason } — unregistered entries
+// keep the plain shapes above, so the skill can show WHY a file differs at
+// each per-file decision.
+//
 // Merged text — conflict markers `<<<<<<< local` / `>>>>>>> template`
 // included — lands ONLY in the output dir. Applying an approved result is
 // /workspace-update's job: copying the file into the workspace one
@@ -184,7 +190,16 @@ export function mergeTemplateFiles({ root, payload = null, baseline = null, out
   }
 
   const classification = classifyUpdate({ root: absRoot, payload: absPayload, baseline });
-  const differsSet = new Set(classification.differs);
+  // differs entries are plain paths, or { file, reason } for paths with a
+  // registered modification (gh:194). Normalize to one shape and keep the
+  // reasons so they ride along on the merge output.
+  const differsFiles = classification.differs.map((e) => (typeof e === 'string' ? e : e.file));
+  const reasonByFile = new Map(
+    classification.differs
+      .filter((e) => typeof e === 'object' && typeof e.reason === 'string')
+      .map((e) => [e.file, e.reason]),
+  );
+  const differsSet = new Set(differsFiles);
   const baseDir = join(absPayload, TEMPLATE_BASE_DIR);
 
   const result = {
@@ -196,7 +211,7 @@ export function mergeTemplateFiles({ root, payload = null, baseline = null, out
     templateBase: existsSync(baseDir) ? baseDir : null,
   };
 
-  let targets = classification.differs;
+  let targets = differsFiles;
   if (files !== null) {
     const wanted = files.split(',').map((s) => s.trim()).filter(Boolean);
     targets = [];
@@ -208,6 +223,7 @@ export function mergeTemplateFiles({ root, payload = null, baseline = null, out
 
   const { baseline: resolvedBaseline } = resolveBaseline({ root: absRoot, payload: absPayload, baseline });
   for (const rel of targets) {
+    const reason = reasonByFile.get(rel);
     const local = join(absRoot, rel);
     const template = join(absPayload, rel);
     const base = join(baseDir, rel);
@@ -216,12 +232,12 @@ export function mergeTemplateFiles({ root, payload = null, baseline = null, out
       continue;
     }
     if (!existsSync(base)) {
-      result.noBase.push(rel);
+      result.noBase.push(reason === undefined ? rel : { path: rel, reason });
       continue;
     }
     const baselineHash = resolvedBaseline ? resolvedBaseline.files[rel] : undefined;
     if (baselineHash !== undefined && hashBytes(readFileSync(base)) !== baselineHash) {
-      result.noBase.push(rel);
+      result.noBase.push(reason === undefined ? rel : { path: rel, reason });
       continue;
     }
     const merge = mergeTrio(local, base, template);
@@ -233,6 +249,7 @@ export function mergeTemplateFiles({ root, payload = null, baseline = null, out
     mkdirSync(dirname(outFile), { recursive: true });
     writeFileSync(outFile, merge.bytes);
     const entry = { path: rel, conflicts: merge.conflicts, out: outFile };
+    if (reason !== undefined) entry.reason = reason;
     if (merge.conflicts === 0) result.merged.push(entry);
     else result.conflicted.push(entry);
   }

package/template/_claude/scripts/template-modifications.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// Reader for .claude/template-modifications.json — the workspace's registry
+// of how it deliberately diverges from the template (gh:194).
+//
+// Shape (paths relative to .claude/; on read, backslashes become '/', and a
+// leading "./" or ".claude/" on a key or entry is tolerated and stripped, so
+// ".claude\rules\core.md", "./rules/core.md", and "rules/core.md" are the
+// same key):
+//   {
+//     "localFiles": ["skills/my-skill/**", "rules/my-rule.md"],
+//     "modifications": { "rules/core.md": "kept our stricter lint gate" }
+//   }
+//
+// The registry covers .claude/ paths only — root files (CLAUDE.md,
+// .mcp.json, .claudeignore) are handled by their own merge paths — so a key
+// that escapes .claude/ ('../CLAUDE.md', an absolute path) names nothing it
+// governs: it reports in `ignoredKeys` for the operator to fix instead of
+// sitting silently inert, and a key that normalizes away ('.', '.claude/')
+// is dropped.
+//
+// localFiles — files this workspace owns outright: never offered by
+//   /workspace-update, neither as an update nor as a removal. Semantics are
+//   unchanged from the workspace.json → workspace.localFiles array the field
+//   migrates from.
+// modifications — deliberate edits to files the template still owns: they
+//   keep updating (three-way merge when both sides changed), and the
+//   recorded reason is shown whenever the file comes up for a decision, so
+//   "why does this file differ?" survives the person who made the edit.
+//
+// The file is workspace-owned: the template never ships or overwrites it.
+// An upgrade payload carries no copy, and classify-update treats the path
+// like the baseline — never as a template removal.
+//
+// Legacy fallback, for one release: workspaces that predate the file keep
+// their data in workspace.json — `workspace.localFiles` (the old array) and
+// `workspace.templateModifications` (an improvised path→reason map some
+// workspaces adopted before the file existed). Both are read here so
+// nothing breaks before /workspace-update migrates them; `legacyKeys` names
+// the ones still present so the skill and the maintenance audit can offer
+// the migration. Where the file and a legacy key both carry data, the file
+// wins per modification path and the localFiles arrays union — a
+// half-finished migration never loses an exclusion or hides a reason.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export const TEMPLATE_MODIFICATIONS_PATH = '.claude/template-modifications.json';
+
+// workspace.json keys the file replaces. `localFiles` is the documented
+// pre-gh:194 array; `templateModifications` is the improvised map.
+export const LEGACY_KEYS = ['localFiles', 'templateModifications'];
+
+// Normalize one registry path — a localFiles entry or a modifications key —
+// to a .claude/-relative posix path: Windows backslashes become '/', repeated
+// leading './' segments collapse, then leading '.claude/' prefixes strip.
+// Returns '' when nothing usable remains ('.', '.claude/') and null when the
+// path escapes .claude/ ('../CLAUDE.md', absolute paths, drive letters) —
+// the caller reports those in ignoredKeys (gh:194).
+function normalizeRel(value) {
+  const posix = value
+    .replace(/\\/g, '/')
+    .replace(/^(?:\.\/)+/, '')
+    .replace(/^(?:\.claude\/)+/, '');
+  if (posix === '' || posix === '.') return '';
+  if (posix === '..' || posix.startsWith('../')
+    || posix.startsWith('/') || /^[A-Za-z]:/.test(posix)) {
+    return null;
+  }
+  return posix;
+}
+
+// `ignored` collects the raw, as-written keys that escape .claude/.
+function normalizeLocalFiles(entries, ignored) {
+  if (!Array.isArray(entries)) return [];
+  const out = [];
+  for (const entry of entries) {
+    if (typeof entry !== 'string' || entry.length === 0) continue;
+    const rel = normalizeRel(entry);
+    if (rel === null) { ignored.push(entry); continue; }
+    if (rel !== '') out.push(rel);
+  }
+  return out;
+}
+
+function normalizeModifications(map, ignored) {
+  if (map === null || typeof map !== 'object' || Array.isArray(map)) return {};
+  const out = {};
+  for (const [key, reason] of Object.entries(map)) {
+    if (typeof reason !== 'string' || reason.length === 0) continue;
+    const rel = normalizeRel(key);
+    if (rel === null) { ignored.push(key); continue; }
+    if (rel !== '') out[rel] = reason;
+  }
+  return out;
+}
+
+/**
+ * Read the workspace's template-modification registry: the file first, the
+ * legacy workspace.json keys filling whatever it doesn't carry. Returns:
+ *   localFiles    — normalized .claude/-relative paths/globs, unioned
+ *   modifications — { '.claude/-relative path': reason }, the file winning
+ *                   per path, keys sorted for deterministic output
+ *   ignoredKeys   — raw keys that escape .claude/ (they cover nothing the
+ *                   registry governs), sorted, from either field or source
+ *   legacyKeys    — LEGACY_KEYS still present in workspace.json (the
+ *                   migration is unfinished; /workspace-update offers it)
+ *   parseError    — message when the file exists but doesn't parse. Its
+ *                   content is then treated as absent — never guessed at —
+ *                   so the legacy keys alone apply and the callers surface
+ *                   the error.
+ */
+export function readTemplateModifications(root) {
+  const absRoot = resolve(root);
+  let ws = null;
+  try {
+    const config = JSON.parse(readFileSync(join(absRoot, 'workspace.json'), 'utf8'));
+    if (config?.workspace && typeof config.workspace === 'object') ws = config.workspace;
+  } catch { /* no workspace.json (or unparseable — the audit reports that) */ }
+
+  const legacyKeys = ws !== null
+    ? LEGACY_KEYS.filter((k) => Object.prototype.hasOwnProperty.call(ws, k))
+    : [];
+  const ignored = [];
+  const localFiles = normalizeLocalFiles(ws?.localFiles, ignored);
+  let modifications = normalizeModifications(ws?.templateModifications, ignored);
+
+  let parseError = null;
+  const filePath = join(absRoot, TEMPLATE_MODIFICATIONS_PATH);
+  if (existsSync(filePath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('not a JSON object');
+      }
+      for (const entry of normalizeLocalFiles(parsed.localFiles, ignored)) {
+        if (!localFiles.includes(entry)) localFiles.push(entry);
+      }
+      modifications = { ...modifications, ...normalizeModifications(parsed.modifications, ignored) };
+    } catch (err) {
+      parseError = err instanceof Error ? err.message : String(err);
+    }
+  }
+
+  const sorted = Object.keys(modifications).sort();
+  return {
+    localFiles,
+    modifications: Object.fromEntries(sorted.map((k) => [k, modifications[k]])),
+    ignoredKeys: [...new Set(ignored)].sort(),
+    legacyKeys,
+    parseError,
+  };
+}

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

@@ -4,7 +4,7 @@
 
 import '../../lib/require-node.mjs';
 import { spawnSync as nodeSpawnSync } from 'node:child_process';
-import { AlreadyAssignedError } from './interface.mjs';
+import { AlreadyAssignedError, resolveEpicLabelPrefix } from './interface.mjs';
 
 const ISSUE_FIELDS = 'number,title,body,state,assignees,labels,milestone,url,createdAt,updatedAt';
 
@@ -17,6 +17,11 @@ const STANDARD_LABELS = [
   { name: 'P3', color: '0e8a16' },
 ];
 
+// Epic labels share one colour so they read as a family in the UI;
+// createEpic never rewrites a label that already exists, so a team that
+// recolours theirs keeps their choice.
+const EPIC_LABEL_COLOR = '5319e7';
+
 export function createGithubAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
   const repo = resolveRepo(config, spawnFn);
   let loginCache = null;
@@ -144,6 +149,105 @@ export function createGithubAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
     return normalizeMilestone(created);
   }
 
+  // ---- Epics --------------------------------------------------------------
+  // Label mode: an epic is a single label `epicLabelPrefix + name` on every
+  // issue in it, so an issue carries exactly one epic and `listEpicIssues`
+  // is a label query. GitHub has no native epic object — sub-issues could
+  // back a native mode one day, but until then `epics: "native"` fails
+  // loudly per call rather than degrading to labels, because a team that
+  // asked for native must find out, not silently get label semantics.
+  const epicLabelPrefix = resolveEpicLabelPrefix(config);
+
+  function requireLabelEpics(method) {
+    if (config?.epics === 'native') {
+      throw new Error(
+        `github-issues does not support epics: "native" (${method}) — GitHub has no epic object; `
+        + `sub-issues may back one later. Set workspace.tracker.epics to "label" (or remove it) `
+        + `to use ${epicLabelPrefix}* labels.`,
+      );
+    }
+  }
+
+  function isEpicLabel(name) {
+    return name.startsWith(epicLabelPrefix) && name !== epicLabelPrefix;
+  }
+
+  async function listEpics({ state } = {}) {
+    // `state` exists for signature parity with native mode — a label has no
+    // state, so every epic label is listed.
+    requireLabelEpics('listEpics');
+    // `--paginate` concatenates raw JSON pages into invalid JSON; the `--jq`
+    // filter runs per page and streams names one per line, so both the walk
+    // and the parse stay well-formed. (`gh label list --limit N` silently
+    // caps at N — gh:195.)
+    const stdout = gh(['api', '--paginate', `repos/${repo}/labels`, '--jq', '.[].name']);
+    return stdout.split('\n')
+      .map((name) => name.trim())
+      .filter(isEpicLabel)
+      .map((name) => ({ name: name.slice(epicLabelPrefix.length), native: false }));
+  }
+
+  // GitHub treats label names case-insensitively, so epic names match the
+  // same way — and the label's own casing wins, so every later write uses
+  // the canonical form.
+  async function getEpic(name) {
+    const wanted = String(name).toLowerCase();
+    return (await listEpics()).find((e) => e.name.toLowerCase() === wanted) ?? null;
+  }
+
+  async function requireEpic(name) {
+    const epic = await getEpic(name);
+    if (!epic) {
+      throw new Error(`Unknown epic "${name}" — create it with createEpic() first (assignment never mints epics).`);
+    }
+    return epic;
+  }
+
+  async function createEpic({ name, description = '' } = {}) {
+    requireLabelEpics('createEpic');
+    if (!name) throw new Error('createEpic: name is required');
+    const existing = await getEpic(name);
+    if (existing) return existing;
+    const args = ['label', 'create', `${epicLabelPrefix}${name}`, '--repo', repo, '--color', EPIC_LABEL_COLOR];
+    if (description) args.push('--description', description);
+    gh(args);
+    return { name, native: false };
+  }
+
+  // Exactly one epic per issue: stale epic labels (anything that is not the
+  // target) drop and the target adds only when absent — one edit carries
+  // both halves, and null strips every epic label.
+  async function setIssueEpic(issueId, name) {
+    requireLabelEpics('setIssueEpic');
+    const num = parseIssueNumber(issueId);
+    let toAdd = null;
+    if (name !== null && name !== undefined) {
+      toAdd = `${epicLabelPrefix}${(await requireEpic(name)).name}`; // canonical casing
+    }
+    const issue = await getIssue(issueId);
+    const current = issue.labels.filter(isEpicLabel);
+    const stale = toAdd === null ? current : current.filter((l) => l !== toAdd);
+    const needsAdd = toAdd !== null && !current.includes(toAdd);
+    if (stale.length === 0 && !needsAdd) return;
+    const args = ['issue', 'edit', String(num), '--repo', repo];
+    for (const label of stale) args.push('--remove-label', label);
+    if (needsAdd) args.push('--add-label', toAdd);
+    gh(args);
+  }
+
+  async function listEpicIssues(name, { state = 'open' } = {}) {
+    requireLabelEpics('listEpicIssues');
+    if (!['open', 'closed', 'all'].includes(state)) {
+      throw new Error(`listEpicIssues: state must be "open", "closed" or "all" — got "${state}"`);
+    }
+    const epic = await requireEpic(name);
+    const stdout = gh([
+      'issue', 'list', '--repo', repo, '--label', `${epicLabelPrefix}${epic.name}`,
+      '--state', state, '--limit', '1000', '--json', ISSUE_FIELDS,
+    ]);
+    return JSON.parse(stdout).map(normalize);
+  }
+
   return {
     listAssignedToMe,
     listUnassigned,
@@ -155,6 +259,11 @@ export function createGithubAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
     issueRef,
     ensureLabels,
     ensureMilestone,
+    listEpics,
+    getEpic,
+    createEpic,
+    setIssueEpic,
+    listEpicIssues,
     get identity() { return `github-issues:${repo}`; },
   };
 }

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

@@ -9,7 +9,7 @@
 
 import '../../lib/require-node.mjs';
 import { spawnSync as nodeSpawnSync } from 'node:child_process';
-import { AlreadyAssignedError } from './interface.mjs';
+import { AlreadyAssignedError, resolveEpicLabelPrefix } from './interface.mjs';
 
 const GITLAB_DEFAULT_HOST = 'gitlab.com';
 
@@ -22,6 +22,12 @@ const STANDARD_LABELS = [
   { name: 'P3', color: '0e8a16' },
 ];
 
+// Epic labels share one colour so they read as a family in the UI;
+// createEpic never rewrites a label that already exists (there is no
+// --force here anyway), so a team that recolours theirs keeps their
+// choice. Native epics ignore it — GitLab owns their appearance.
+const EPIC_LABEL_COLOR = '5319e7';
+
 export function createGitlabAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
   const repo = resolveRepo(config, spawnFn);
   const host = typeof config?.host === 'string' && config.host ? config.host : GITLAB_DEFAULT_HOST;
@@ -39,7 +45,12 @@ export function createGitlabAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
       stdio: input !== undefined ? ['pipe', 'pipe', 'pipe'] : ['inherit', 'pipe', 'pipe'],
     });
     if (result.status !== 0) {
-      throw new Error(`glab ${args.join(' ')} failed: ${(result.stderr || '').trim()}`);
+      const err = new Error(`glab ${args.join(' ')} failed: ${(result.stderr || '').trim()}`);
+      // Callers that classify failures (nativeEpicCall) must look at the
+      // stderr alone — the argv in the message can contain numbers that
+      // merely look like status codes (an epic iid of 404, say).
+      err.stderr = (result.stderr || '').trim();
+      throw err;
     }
     return result.stdout || '';
   }
@@ -222,6 +233,209 @@ export function createGitlabAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
     return normalizeMilestone(created);
   }
 
+  // ---- Epics --------------------------------------------------------------
+  // Label mode (default) mirrors github-issues: one `epicLabelPrefix + name`
+  // label per epic, exactly one epic per issue. Native mode
+  // (workspace.tracker.epics: "native") uses GitLab's group epics instead —
+  // the group is the project path minus its last segment — and needs
+  // Premium/Ultimate: without it the group-epic endpoints answer 403 (404
+  // when the group itself is missing or out of reach). Either must surface
+  // as a clear pointer back to label mode, never a silent fallback — a
+  // native-configured team that quietly got labels would have epics living
+  // in two places. (This speaks the epics REST API, deprecated in favor of
+  // the work-item epics API as of GitLab 17.0, because glab has no
+  // high-level epic commands; the endpoints still serve.)
+  const nativeEpics = config?.epics === 'native';
+  const epicLabelPrefix = resolveEpicLabelPrefix(config);
+
+  // Epics live at the group level in native mode; a single-segment project
+  // path has no group to hang them on.
+  function epicGroup() {
+    const segments = repo.split('/');
+    if (segments.length < 2) {
+      throw new Error(`cannot derive a group for native epics from project "${repo}" — epics live at the group level`);
+    }
+    return segments.slice(0, -1).join('/');
+  }
+
+  // Epic iids are unique only within their group, so native epic paths name
+  // the epic's group — its numeric id when the entity carries one (the
+  // listing and an issue's embedded epic both do), the configured group
+  // path otherwise.
+  function epicGroupRef(groupId) {
+    return groupId != null ? String(groupId) : encodeURIComponent(epicGroup());
+  }
+
+  function isEpicLabel(name) {
+    return name.startsWith(epicLabelPrefix) && name !== epicLabelPrefix;
+  }
+
+  // Runs a native-epic call and translates glab's 403/404 into an
+  // actionable error pointing at label mode; any other failure passes
+  // through untouched. Only the stderr is classified — the argv baked into
+  // the message can contain numbers that merely look like status codes.
+  function nativeEpicCall(run) {
+    try {
+      return run();
+    } catch (e) {
+      const where = e.stderr ?? e.message;
+      if (!/\b40[34]\b|Forbidden|Not Found/i.test(where)) throw e;
+      throw new Error(
+        `native epics are unavailable for group "${epicGroup()}" on ${host} — typically no `
+        + `Premium/Ultimate licence, or the group is missing. Set workspace.tracker.epics to "label" `
+        + `(or remove it) to use ${epicLabelPrefix}* labels instead. Underlying error: ${e.message}`,
+      );
+    }
+  }
+
+  const nativeEpicState = (raw) => (raw.state === 'closed' ? 'closed' : 'open');
+
+  async function listEpics({ state = 'open' } = {}) {
+    if (nativeEpics) {
+      // Descendants and ancestors excluded: an iid collision with another
+      // group's epic must never be mistaken for this group's epic. Closed
+      // epics drop out of the default listing — a done epic is not a
+      // picker choice — but stay reachable via state: "all".
+      const epics = nativeEpicCall(() => apiListAll(
+        `groups/${encodeURIComponent(epicGroup())}/epics`,
+        ['include_descendant_groups=false', 'include_ancestor_groups=false'],
+      ));
+      return epics
+        .map((e) => ({
+          name: e.title, id: e.iid, native: true, url: e.web_url,
+          state: nativeEpicState(e), groupId: e.group_id,
+        }))
+        .filter((e) => state === 'all' || e.state === state);
+    }
+    // Label mode has no epic state; the option exists for signature parity.
+    const labels = await apiListAll(`projects/${encodeURIComponent(repo)}/labels`);
+    return labels
+      .map((l) => l.name)
+      .filter(isEpicLabel)
+      .map((name) => ({ name: name.slice(epicLabelPrefix.length), native: false }));
+  }
+
+  // GitLab treats label names — and epic titles for our purposes —
+  // case-insensitively, so epic names match the same way; the existing
+  // object's own casing wins, so every later write uses the canonical form.
+  async function getEpic(name) {
+    const wanted = String(name).toLowerCase();
+    return (await listEpics({ state: 'all' }))
+      .find((e) => e.name.toLowerCase() === wanted) ?? null;
+  }
+
+  async function requireEpic(name) {
+    const epic = await getEpic(name);
+    if (!epic) {
+      throw new Error(`Unknown epic "${name}" — create it with createEpic() first (assignment never mints epics).`);
+    }
+    return epic;
+  }
+
+  async function createEpic({ name, description = '' } = {}) {
+    if (!name) throw new Error('createEpic: name is required');
+    const existing = await getEpic(name);
+    if (existing) return existing;
+    if (nativeEpics) {
+      const args = ['api', `groups/${encodeURIComponent(epicGroup())}/epics`, '-X', 'POST', '-f', `title=${name}`];
+      if (description) args.push('-f', `description=${description}`);
+      args.push('--hostname', host);
+      const raw = JSON.parse(nativeEpicCall(() => glab(args)));
+      return {
+        name: raw.title, id: raw.iid, native: true, url: raw.web_url,
+        state: nativeEpicState(raw), groupId: raw.group_id,
+      };
+    }
+    const args = ['label', 'create', '--repo', repo, '--name', `${epicLabelPrefix}${name}`, '--color', `#${EPIC_LABEL_COLOR}`];
+    if (description) args.push('--description', description);
+    glab(args);
+    return { name, native: false };
+  }
+
+  // Native identity is group + iid together — the same iid under another
+  // group is a different epic. Without a group_id on one side, the iid is
+  // all there is to compare.
+  function sameNativeEpic(rawEpic, epic) {
+    if (!rawEpic || rawEpic.iid !== epic.id) return false;
+    if (rawEpic.group_id != null && epic.groupId != null) return rawEpic.group_id === epic.groupId;
+    return true;
+  }
+
+  // Exactly one epic per issue, both modes. Label mode writes one atomic
+  // PUT — add_labels/remove_labels change only the named labels, so a
+  // concurrent label edit on the same issue is not clobbered the way a
+  // read-modify-write of the full set would be; the read happens only for
+  // no-op detection and to learn which epic labels to drop. Native mode
+  // assigns through the epic-issue endpoints: assigning POSTs the issue's
+  // global id (GitLab unassigns its previous epic server-side), and
+  // unassigning DELETEs the association id, which only the epic's own
+  // issue list carries.
+  async function setIssueEpic(issueId, name) {
+    const num = parseIssueNumber(issueId);
+    const epic = name === null || name === undefined ? null : await requireEpic(name);
+    const raw = JSON.parse(glab(['issue', 'view', String(num), '--repo', repo, '-F', 'json']));
+
+    if (nativeEpics) {
+      if (epic) {
+        if (sameNativeEpic(raw.epic, epic)) return; // already there
+        nativeEpicCall(() => glab([
+          'api', `groups/${epicGroupRef(epic.groupId)}/epics/${epic.id}/issues/${raw.id}`,
+          '-X', 'POST', '--hostname', host,
+        ]));
+        return;
+      }
+      // The current epic may belong to an ancestor group — its own group,
+      // not the tracker's, is where the association lives.
+      const current = raw.epic ?? (raw.epic_iid != null ? { iid: raw.epic_iid } : null);
+      if (!current) return;
+      const groupRef = epicGroupRef(current.group_id);
+      nativeEpicCall(() => {
+        const members = apiListAll(`groups/${groupRef}/epics/${current.iid}/issues`);
+        const association = members.find((i) => i.id === raw.id);
+        if (association) {
+          glab([
+            'api', `groups/${groupRef}/epics/${current.iid}/issues/${association.epic_issue_id}`,
+            '-X', 'DELETE', '--hostname', host,
+          ]);
+        }
+      });
+      return;
+    }
+
+    const current = (raw.labels || []).map((l) => (typeof l === 'string' ? l : l.name));
+    const epicLabels = current.filter(isEpicLabel);
+    const toAdd = epic === null ? null : `${epicLabelPrefix}${epic.name}`; // canonical casing
+    const remove = toAdd === null ? epicLabels : epicLabels.filter((l) => l !== toAdd);
+    const add = toAdd !== null && !current.includes(toAdd) ? toAdd : null;
+    if (remove.length === 0 && add === null) return;
+    const args = ['api', `projects/${encodeURIComponent(repo)}/issues/${num}`, '-X', 'PUT'];
+    if (remove.length > 0) args.push('-f', `remove_labels=${remove.join(',')}`);
+    if (add !== null) args.push('-f', `add_labels=${add}`);
+    args.push('--hostname', host);
+    glab(args);
+  }
+
+  async function listEpicIssues(name, { state = 'open' } = {}) {
+    if (!['open', 'closed', 'all'].includes(state)) {
+      throw new Error(`listEpicIssues: state must be "open", "closed" or "all" — got "${state}"`);
+    }
+    const epic = await requireEpic(name);
+    // The API spells it "opened"; closed and all pass through as-is.
+    const gitlabState = state === 'open' ? 'opened' : state;
+    if (nativeEpics) {
+      // The epic-issue list endpoint has no state filter of its own.
+      const members = nativeEpicCall(() =>
+        apiListAll(`groups/${epicGroupRef(epic.groupId)}/epics/${epic.id}/issues`));
+      return members
+        .filter((i) => state === 'all' || i.state === gitlabState)
+        .map(normalize);
+    }
+    return apiListAll(
+      `projects/${encodeURIComponent(repo)}/issues`,
+      [`labels=${encodeURIComponent(`${epicLabelPrefix}${epic.name}`)}`, `state=${gitlabState}`],
+    ).map(normalize);
+  }
+
   return {
     listAssignedToMe,
     listUnassigned,
@@ -234,6 +448,11 @@ export function createGitlabAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
     issueUrl,
     ensureLabels,
     ensureMilestone,
+    listEpics,
+    getEpic,
+    createEpic,
+    setIssueEpic,
+    listEpicIssues,
     get identity() { return `gitlab-issues:${repo}`; },
   };
 }

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

@@ -8,6 +8,39 @@
 //       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.
+//
+// Epic method contract (gh:195) — every adapter implements all five:
+//
+//   listEpics({ state } = { state: 'open' }) → Epic[] — { name, id?,
+//     native, url?, state? }. `id`, `state` and `groupId` only exist in
+//     native mode; a closed GitLab epic is filtered out unless state is
+//     "all". Label mode has no epic state and ignores the option.
+//   getEpic(name) → the Epic, or null when absent. Names match
+//     case-insensitively — both forges treat labels that way — and the
+//     returned name is the label's own casing.
+//   createEpic({ name, description? }) → the Epic, creating only when no
+//     epic of that name exists in any casing (idempotent) — epics are
+//     created deliberately, never as a side effect of assigning an issue.
+//   setIssueEpic(issueId, name | null)
+//     An issue carries exactly one epic: assigning replaces any current
+//     epic, null removes it. An unknown name throws — a typo must never
+//     mint an epic.
+//   listEpicIssues(name, { state }) → Issue[], state "open" | "closed" |
+//     "all" (default open; anything else throws).
+//
+// Modes: label mode (default, both adapters) represents an epic as the
+// label `epicLabelPrefix + name` — default prefix "epic:", configurable
+// via workspace.tracker.epicLabelPrefix, which must end with a delimiter
+// (resolveEpicLabelPrefix enforces that) — carried by every issue in the
+// epic. Native mode (GitLab only, workspace.tracker.epics: "native") uses
+// group epics and needs Premium/Ultimate; without it the group-epic
+// endpoints answer 403/404, which must surface as a clear error pointing
+// at label mode — never a silent fallback, or epics would silently live
+// in two places. Epic iids are unique only within their group, so native
+// epics are pinned to the tracker group's own (descendant and ancestor
+// groups excluded) and matched by group and iid together. GitHub has no
+// native epic object: `epics: "native"` throws from every epic method
+// there (sub-issues may back one later).
 
 import '../../lib/require-node.mjs';
 import { createGithubAdapter } from './github-issues.mjs';
@@ -22,6 +55,20 @@ export class AlreadyAssignedError extends Error {
   }
 }
 
+// Shared epic-label-prefix resolution (gh:195): `epicLabelPrefix` from the
+// tracker config, defaulting to "epic:". A prefix must end with a delimiter
+// (":", "-", "/") — a trailing alphanumeric would slice epic names at an
+// arbitrary character and make label↔name mapping ambiguous.
+export function resolveEpicLabelPrefix(config) {
+  const prefix = typeof config?.epicLabelPrefix === 'string' && config.epicLabelPrefix
+    ? config.epicLabelPrefix
+    : 'epic:';
+  if (/[a-z0-9]$/i.test(prefix)) {
+    throw new Error(`tracker.epicLabelPrefix "${prefix}" must end with a delimiter such as ":" or "-"`);
+  }
+  return prefix;
+}
+
 export function createTracker(config, options = {}) {
   if (!config || typeof config !== 'object') {
     throw new Error('No tracker configured — pass workspace.json\'s workspace.tracker block.');