@ulysses-ai/create-workspace 0.16.0-beta.1 → 0.17.0-beta.0

package/template/.claude/scripts/forges/github.mjs

@@ -0,0 +1,210 @@
+// GitHub forge adapter. Wraps the `gh` CLI via an injectable spawnFn so
+// tests can mock without spawning a real subprocess (mirrors the pattern
+// in trackers/github-issues.mjs).
+//
+// All operations target a single default `repo` resolved at construction
+// time from `config.repo` (e.g. `"owner/name"`) or from the local git
+// origin remote when `config.repo` is unset or `"auto"`. Per-call `repo`
+// overrides allow targeting a different repo when needed.
+
+import '../../lib/require-node.mjs';
+import { spawnSync as nodeSpawnSync } from 'node:child_process';
+import {
+  PrNotFound,
+  ReleaseNotFound,
+  WorkflowNotFound,
+  MergeRejected,
+} from './interface.mjs';
+
+const PR_VIEW_FIELDS = 'number,url,state,title,mergeable,mergeStateStatus,reviewDecision,headRefName,baseRefName,isDraft,mergedAt';
+
+export function createGithubAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
+  const defaultRepo = resolveRepo(config, spawnFn);
+
+  function gh(args, { input } = {}) {
+    const result = spawnFn('gh', args, {
+      input,
+      encoding: 'utf-8',
+      stdio: input !== undefined ? ['pipe', 'pipe', 'pipe'] : ['inherit', 'pipe', 'pipe'],
+    });
+    return result;
+  }
+
+  function ghOrThrow(args, opts) {
+    const result = gh(args, opts);
+    if (result.status !== 0) {
+      throw new Error(`gh ${args.join(' ')} failed: ${(result.stderr || '').trim()}`);
+    }
+    return result.stdout || '';
+  }
+
+  function repoFor(override) {
+    return override || defaultRepo;
+  }
+
+  async function prCreate({ title, body = '', draft = false, base, head, repo }) {
+    if (!title) throw new Error('prCreate: title is required');
+    const args = ['pr', 'create', '--repo', repoFor(repo), '--title', title, '--body-file', '-'];
+    if (draft) args.push('--draft');
+    if (base) args.push('--base', base);
+    if (head) args.push('--head', head);
+    const stdout = ghOrThrow(args, { input: body }).trim();
+    // gh pr create prints the PR URL on success; sometimes preceded by warnings.
+    const url = stdout.split('\n').filter(Boolean).pop();
+    const m = url.match(/\/pull\/(\d+)/);
+    if (!m) throw new Error(`Could not parse PR number from gh output: ${stdout}`);
+    const number = parseInt(m[1], 10);
+    return { id: `${repoFor(repo)}#${number}`, url, number };
+  }
+
+  async function prMerge({ id, strategy = 'merge', deleteBranch = false, repo }) {
+    if (!id) throw new Error('prMerge: id is required');
+    const { number, repo: parsedRepo } = parsePrId(id, repoFor(repo));
+    const args = ['pr', 'merge', String(number), '--repo', parsedRepo];
+    switch (strategy) {
+      case 'merge': args.push('--merge'); break;
+      case 'squash': args.push('--squash'); break;
+      case 'rebase': args.push('--rebase'); break;
+      default: throw new Error(`prMerge: unknown strategy: ${strategy}`);
+    }
+    if (deleteBranch) args.push('--delete-branch');
+    const result = gh(args);
+    if (result.status !== 0) {
+      const stderr = (result.stderr || '').trim();
+      // Distinguish "not found" from "rejected" so callers can react.
+      if (/not\s+found|could\s+not\s+resolve/i.test(stderr)) {
+        throw new PrNotFound(id);
+      }
+      throw new MergeRejected(id, stderr || 'gh pr merge exited non-zero');
+    }
+    return { merged: true, url: `https://github.com/${parsedRepo}/pull/${number}` };
+  }
+
+  async function prView({ id, repo, json }) {
+    if (!id) throw new Error('prView: id is required');
+    const { number, repo: parsedRepo } = parsePrId(id, repoFor(repo));
+    const fields = json || PR_VIEW_FIELDS;
+    const result = gh(['pr', 'view', String(number), '--repo', parsedRepo, '--json', fields]);
+    if (result.status !== 0) {
+      const stderr = (result.stderr || '').trim();
+      if (/not\s+found|could\s+not\s+resolve/i.test(stderr)) {
+        throw new PrNotFound(id);
+      }
+      throw new Error(`gh pr view failed: ${stderr}`);
+    }
+    const raw = JSON.parse(result.stdout);
+    return {
+      id,
+      number: raw.number,
+      url: raw.url,
+      state: raw.state,
+      title: raw.title,
+      mergeable: raw.mergeable,
+      mergeStateStatus: raw.mergeStateStatus,
+      reviewDecision: raw.reviewDecision,
+      headRefName: raw.headRefName,
+      baseRefName: raw.baseRefName,
+      isDraft: raw.isDraft,
+      mergedAt: raw.mergedAt,
+      _raw: raw,
+    };
+  }
+
+  async function releaseView({ tag, repo }) {
+    if (!tag) throw new Error('releaseView: tag is required');
+    const target = repoFor(repo);
+    const result = gh(['release', 'view', tag, '--repo', target, '--json', 'name,tagName,url,publishedAt,isDraft,isPrerelease']);
+    if (result.status !== 0) {
+      const stderr = (result.stderr || '').trim();
+      if (/release\s+not\s+found|not\s+found/i.test(stderr)) {
+        throw new ReleaseNotFound(tag);
+      }
+      throw new Error(`gh release view failed: ${stderr}`);
+    }
+    const raw = JSON.parse(result.stdout);
+    return {
+      tag: raw.tagName,
+      name: raw.name,
+      url: raw.url,
+      publishedAt: raw.publishedAt,
+      isDraft: raw.isDraft,
+      isPrerelease: raw.isPrerelease,
+    };
+  }
+
+  async function workflowRunFind({ workflow, branch, repo, limit = 1 }) {
+    if (!workflow) throw new Error('workflowRunFind: workflow is required');
+    const target = repoFor(repo);
+    const args = [
+      'run', 'list',
+      '--repo', target,
+      '--workflow', workflow,
+      '--limit', String(limit),
+      '--json', 'databaseId,status,conclusion,url,headBranch,createdAt',
+    ];
+    if (branch) args.push('--branch', branch);
+    const result = gh(args);
+    if (result.status !== 0) {
+      throw new Error(`gh run list failed: ${(result.stderr || '').trim()}`);
+    }
+    const runs = JSON.parse(result.stdout);
+    if (runs.length === 0) return null;
+    const first = runs[0];
+    return {
+      runId: String(first.databaseId),
+      status: first.status,
+      conclusion: first.conclusion,
+      url: first.url,
+      branch: first.headBranch,
+      createdAt: first.createdAt,
+    };
+  }
+
+  async function workflowRunWatch({ runId, repo, exitStatus = false }) {
+    if (!runId) throw new Error('workflowRunWatch: runId is required');
+    const target = repoFor(repo);
+    const args = ['run', 'watch', String(runId), '--repo', target];
+    if (exitStatus) args.push('--exit-status');
+    const result = gh(args);
+    if (result.status === 0) return { exitCode: 0 };
+    // Distinguish "couldn't find" from "ran but failed".
+    const stderr = (result.stderr || '').trim();
+    if (/not\s+found|could\s+not\s+find/i.test(stderr)) {
+      throw new WorkflowNotFound({ runId });
+    }
+    // `--exit-status` makes gh exit non-zero on workflow failure; surface
+    // that without throwing so callers can record the failure URL.
+    return { exitCode: result.status, stderr };
+  }
+
+  return {
+    prCreate,
+    prMerge,
+    prView,
+    releaseView,
+    workflowRunFind,
+    workflowRunWatch,
+    get identity() { return `github:${defaultRepo}`; },
+  };
+}
+
+// "owner/name#NUMBER" or just NUMBER (defaulting to the adapter's repo).
+function parsePrId(id, fallbackRepo) {
+  if (typeof id === 'number') return { number: id, repo: fallbackRepo };
+  const m1 = String(id).match(/^(?<repo>[^#\s]+\/[^#\s]+)#(?<number>\d+)$/);
+  if (m1) return { number: parseInt(m1.groups.number, 10), repo: m1.groups.repo };
+  const m2 = String(id).match(/^#?(\d+)$/);
+  if (m2) return { number: parseInt(m2[1], 10), repo: fallbackRepo };
+  throw new Error(`Unparseable PR id: ${id}`);
+}
+
+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 m = result.stdout.trim().match(/github\.com[:/]([^/]+)\/([^/.]+?)(?:\.git)?$/);
+  if (!m) throw new Error(`Cannot parse GitHub remote: ${result.stdout.trim()}`);
+  return `${m[1]}/${m[2]}`;
+}

package/template/.claude/scripts/forges/gitlab.mjs

@@ -0,0 +1,19 @@
+// GitLab forge adapter — stub. Reserved as the next sibling of github.mjs
+// so the discovery pattern stays uniform: workspaces opting into GitLab
+// set `workspace.forge.type: gitlab` in workspace.json and get a clear
+// "not implemented" error pointing at the gap, rather than silently
+// routing through GitHub.
+//
+// When implemented, this adapter wraps the `glab` CLI the same way
+// github.mjs wraps `gh`: same method surface (prCreate, prMerge, prView,
+// releaseView, workflowRunFind, workflowRunWatch), same spawnFn-injectable
+// shape for testability, same error types from interface.mjs.
+
+import { ForgeError } from './interface.mjs';
+
+export function createGitlabAdapter(config /* , options */) {
+  throw new ForgeError(
+    'GitLab forge adapter is not implemented yet. Set workspace.forge.type to "github", or contribute a glab-based adapter at .claude/scripts/forges/gitlab.mjs following the shape of github.mjs.',
+    'NOT_IMPLEMENTED',
+  );
+}

package/template/.claude/scripts/forges/interface.mjs

@@ -0,0 +1,113 @@
+// Forge adapter interface. Skills import only from this module.
+//
+// Where `trackers/` covers issue lifecycle (issues, comments, labels,
+// milestones), `forges/` covers cross-cutting repo-host operations:
+// pull requests, releases, and workflow runs. The two abstractions are
+// intentionally separate — a workspace could in principle mix
+// (e.g. `github-issues` tracker + `gitlab` forge), though the common
+// case is forge = same host as tracker.
+//
+// Method contracts:
+//
+//   prCreate({ title, body, draft = false, base, head, repo? })
+//     → { id, url, number }
+//   prMerge({ id, strategy = 'merge', deleteBranch = false, repo? })
+//     → { merged: true, url }
+//     strategy: 'merge' | 'squash' | 'rebase'
+//   prView({ id, repo?, json? })
+//     → { id, url, state, mergeable, mergeStateStatus, reviewDecision, title }
+//     json may name additional fields to pass through
+//   releaseView({ tag, repo? })
+//     → { tag, url, name, publishedAt }
+//     throws ReleaseNotFound if the tag has no release
+//   workflowRunFind({ workflow, branch, repo?, limit = 1 })
+//     → { runId, status, conclusion, url } | null
+//   workflowRunWatch({ runId, repo?, exitStatus = false })
+//     → { exitCode }
+//     exitStatus: when true, the underlying command exits non-zero on
+//     workflow failure; the adapter still returns the exit code rather
+//     than throwing — callers decide how to handle a failed run.
+//
+// `repo` defaults: each adapter resolves a default repo at construction
+// time (e.g. from `workspace.forge.repo` or the local git origin remote);
+// callers pass `repo` only when targeting a different one.
+//
+// All methods are async and may throw `ForgeError` subclasses on
+// adapter-detectable failures. Raw spawn failures throw `Error`.
+
+import '../../lib/require-node.mjs';
+import { createGithubAdapter } from './github.mjs';
+import { createGitlabAdapter } from './gitlab.mjs';
+
+export class ForgeError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'ForgeError';
+    this.code = code;
+  }
+}
+
+export class PrNotFound extends ForgeError {
+  constructor(id) {
+    super(`Pull request not found: ${id}`, 'PR_NOT_FOUND');
+    this.name = 'PrNotFound';
+    this.id = id;
+  }
+}
+
+export class ReleaseNotFound extends ForgeError {
+  constructor(tag) {
+    super(`Release not found for tag: ${tag}`, 'RELEASE_NOT_FOUND');
+    this.name = 'ReleaseNotFound';
+    this.tag = tag;
+  }
+}
+
+export class WorkflowNotFound extends ForgeError {
+  constructor(query) {
+    super(`Workflow run not found: ${JSON.stringify(query)}`, 'WORKFLOW_NOT_FOUND');
+    this.name = 'WorkflowNotFound';
+    this.query = query;
+  }
+}
+
+export class MergeRejected extends ForgeError {
+  constructor(id, reason) {
+    super(`Merge rejected for ${id}: ${reason}`, 'MERGE_REJECTED');
+    this.name = 'MergeRejected';
+    this.id = id;
+    this.reason = reason;
+  }
+}
+
+// createForge takes the `workspace.forge` config block. If the block is
+// absent (`undefined`/`null`), default to GitHub — this matches the
+// migration story documented in `.claude/rules/forge-operations.md`:
+// existing workspaces predate the field, so an unset value means
+// "behave as you always have." A workspace that wants to opt out of
+// forge operations entirely should set `workspace.forge: false`;
+// callers passing `false` will get a no-op throw on every method.
+export function createForge(config, options = {}) {
+  if (config === false) {
+    throw new ForgeError(
+      'Forge operations disabled — set workspace.forge in workspace.json to enable.',
+      'FORGE_DISABLED',
+    );
+  }
+  const resolved = config ?? { type: 'github' };
+  if (typeof resolved !== 'object') {
+    throw new ForgeError(
+      `Invalid workspace.forge config: expected object, got ${typeof resolved}`,
+      'INVALID_CONFIG',
+    );
+  }
+  const type = resolved.type ?? 'github';
+  switch (type) {
+    case 'github':
+      return createGithubAdapter(resolved, options);
+    case 'gitlab':
+      return createGitlabAdapter(resolved, options);
+    default:
+      throw new ForgeError(`Unknown forge type: ${type}`, 'UNKNOWN_TYPE');
+  }
+}

package/template/.claude/settings.json

@@ -92,25 +92,17 @@
           }
         ]
       }
-    ],
-    "WorktreeCreate": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"${CLAUDE_PROJECT_DIR:-$PWD}\"; else echo \"${CLAUDE_PROJECT_DIR:-$PWD}\"; fi)\"/.claude/hooks/worktree-create.mjs",
-            "timeout": 5000,
-            "statusMessage": "Checking for stale worktrees..."
-          }
-        ]
-      }
     ]
   },
+  "worktree": {
+    "baseRef": "head"
+  },
   "permissions": {
     "allow": [
       "Bash(git:*)",
       "Bash(ls:*)"
-    ]
+    ],
+    "deny": []
   },
   "enabledPlugins": {
     "playwright@claude-plugins-official": false

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

@@ -218,16 +218,27 @@ The push shape is the same as 9a — what differs is the merge mechanics in Step
 
 #### Step 10a: GitHub remotes — create PRs, unified summary, merge
 
-Create one PR per project repo plus one workspace PR:
+Create one PR per project repo plus one workspace PR. PR operations go through the forge adapter (`.claude/scripts/forges/interface.mjs`), not `gh` directly — see `.claude/rules/forge-operations.md` for the contract. The adapter resolves the target repo from `workspace.forge.repo` or the local git remote.
 
-```bash
-# For each repo in the tracker's repos with a GitHub remote:
-cd work-sessions/{session-name}/workspace/repos/{repo}
-gh pr create --title "{type}: {description}" --body "..."
+```javascript
+import { createForge } from './.claude/scripts/forges/interface.mjs';
+import { readFileSync } from 'node:fs';
 
-# Workspace PR — from the workspace worktree
-cd work-sessions/{session-name}/workspace
-gh pr create --title "context: {session-name} work session" --body "..."
+const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
+const forge = createForge(ws.workspace?.forge);
+
+// For each repo in the tracker's repos with a GitHub remote, from
+// work-sessions/{session-name}/workspace/repos/{repo}:
+const projectPr = await forge.prCreate({
+  title: `${type}: ${description}`,
+  body: prBody,  // synthesized release notes + verification section
+});
+
+// Workspace PR — from the workspace worktree:
+const workspacePr = await forge.prCreate({
+  title: `context: ${sessionName} work session`,
+  body: workspacePrBody,
+});
 ```
 
 Present unified summary:
@@ -254,15 +265,21 @@ WORKSPACE: {workspace-name}
 Merge all? [Y/n]
 ```
 
-If yes — merge all PRs atomically:
-```bash
-# For each project PR:
-gh pr merge {pr-number} --merge
+If yes — merge all PRs atomically through the forge adapter:
+
+```javascript
+// For each project PR returned from Step 10a's prCreate calls:
+await forge.prMerge({ id: projectPr.id, strategy: 'squash', deleteBranch: true });
+
+// Workspace PR:
+await forge.prMerge({ id: workspacePr.id, strategy: 'squash', deleteBranch: true });
+```
 
-# Workspace PR:
-gh pr merge {workspace-pr-number} --merge
+`strategy: 'squash'` matches the workspace convention from `post-release-discipline` (`create-ulysses-workspace` requires linear history, so squash is the only strategy that merges cleanly; squash also lifts the PR body into the commit message). `deleteBranch: true` cleans the remote feature branch on success.
 
-# Pull all repos to their default branches
+Then pull all repos to their default branches (still plain git):
+
+```bash
 # For each repo in the tracker's repos:
 cd repos/{repo} && git pull origin {repo-branch}
 cd {main-workspace-root} && git pull origin main
@@ -274,7 +291,7 @@ The next three sub-substeps run only when the session branch starts with `releas
 
 Derive the version tag from the branch name by stripping the `release/` prefix (so `release/v0.15.0-beta.0` yields `v0.15.0-beta.0`). For each project repo whose `package.json` declares a `version` field, verify that version matches the derived tag. The workspace repo is **never** tagged — only project repos with publishable `package.json` files get tagged, since the tag triggers `.github/workflows/publish.yml` in that project repo. If a project repo's `package.json` version doesn't match the release tag, skip that repo with a warning rather than failing the whole completion flow — the mismatch usually means `/release` was run against a different version than the branch name suggests, and the user needs to investigate before publishing.
 
-Before tagging, preflight against origin: if `v{version}` already exists remotely, surface the conflict to the user with three explicit recovery options — **Reuse** (skip to 10a.2 if the existing tag points at the right commit), **Replace** (`git push origin --delete v{version}` then re-run 10a.1), or **Investigate** (`gh release view v{version}` to see what shipped). Do **not** silently force-push the tag; an existing tag means a published artifact, and overwriting it without confirmation can corrupt the npm registry's view of the release history.
+Before tagging, preflight against origin: if `v{version}` already exists remotely, surface the conflict to the user with three explicit recovery options — **Reuse** (skip to 10a.2 if the existing tag points at the right commit), **Replace** (`git push origin --delete v{version}` then re-run 10a.1), or **Investigate** (`forge.releaseView({ tag: 'v{version}', repo: '{org}/{repo}' })` — or `gh release view v{version}` as a manual fallback — to see what shipped). Do **not** silently force-push the tag; an existing tag means a published artifact, and overwriting it without confirmation can corrupt the npm registry's view of the release history.
 
 If the tag is absent on origin, tag the merge commit (HEAD on `{default-branch}` after the prior `git pull origin {default-branch}`) and push the tag. The tag push triggers `.github/workflows/publish.yml`.
 
@@ -305,7 +322,8 @@ for repo in {project-repos-with-package-json}; do
     # Tag exists. Surface to user with three options:
     # 1. Reuse — skip to 10a.2 if the existing tag points at the right commit.
     # 2. Replace — `git push origin --delete $version_tag` then re-run 10a.1.
-    # 3. Investigate — `gh release view $version_tag` to see what shipped.
+    # 3. Investigate — call forge.releaseView({ tag: '$version_tag' }) — or
+    #    `gh release view $version_tag` as a manual fallback — to see what shipped.
     # Do NOT silently force-push.
     echo "Tag $version_tag already exists on origin. Aborting with recovery options."
     return 1
@@ -319,27 +337,39 @@ done
 
 **Step 10a.2: Watch the publish workflow (release sessions only)**
 
-For each project repo tagged in 10a.1, find and follow the `publish.yml` workflow run on GitHub. The workflow takes a moment to register against the new tag — poll `gh run list` up to 5 times with a 3-second backoff before giving up. Once the run is found, attach with `gh run watch` so the maintainer sees progress live alongside the unified summary. Append `|| true` to the watch command so a workflow failure does **not** abort the rest of `/complete-work`: the maintainer still needs to see the unified summary, including the failure URL, to decide whether to rerun, redo the release, or roll the tag back. If no run registers within the retry window, log a warning with the manual investigation command and continue.
+For each project repo tagged in 10a.1, find and follow the `publish.yml` workflow run on GitHub. The workflow takes a moment to register against the new tag — poll up to 5 times with a 3-second backoff before giving up. Once the run is found, attach with `workflowRunWatch` so the maintainer sees progress live alongside the unified summary. The adapter's `exitStatus: true` makes the underlying `gh run watch --exit-status` exit non-zero on workflow failure; the adapter returns the exit code via `res.exitCode` instead of throwing, so a failure does **not** abort the rest of `/complete-work` — the maintainer still needs to see the unified summary, including the failure URL, to decide whether to rerun, redo the release, or roll the tag back. If no run registers within the retry window, log a warning with the manual investigation command and continue.
 
-```bash
-# Retry up to 5 times with 3-second backoff — the run takes a moment to register.
-for i in 1 2 3 4 5; do
-  run_id=$(gh run list \
-    --repo {org}/{repo} \
-    --workflow publish.yml \
-    --branch "$version_tag" \
-    --limit 1 \
-    --json databaseId \
-    --jq '.[0].databaseId')
-  if [ -n "$run_id" ]; then break; fi
-  sleep 3
-done
+```javascript
+import { createForge } from './.claude/scripts/forges/interface.mjs';
+import { readFileSync } from 'node:fs';
 
-if [ -z "$run_id" ]; then
-  echo "Warning: no publish workflow run found for $version_tag after 15s. Investigate via 'gh run list'."
-else
-  gh run watch "$run_id" --exit-status --repo {org}/{repo} || true
-fi
+const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
+const forge = createForge(ws.workspace?.forge);
+
+// Retry up to 5 times with 3-second backoff — the run takes a moment to register.
+let run = null;
+for (let i = 0; i < 5; i++) {
+  run = await forge.workflowRunFind({
+    workflow: 'publish.yml',
+    branch: versionTag,        // e.g. 'v0.15.0-beta.0'
+    repo: `${org}/${repo}`,
+    limit: 1,
+  });
+  if (run) break;
+  await new Promise(r => setTimeout(r, 3000));
+}
+
+if (!run) {
+  console.warn(`Warning: no publish workflow run found for ${versionTag} after 15s. Investigate via 'gh run list --workflow publish.yml --branch ${versionTag}'.`);
+} else {
+  const result = await forge.workflowRunWatch({
+    runId: run.runId,
+    repo: `${org}/${repo}`,
+    exitStatus: true,
+  });
+  // result.exitCode === 0 on success; non-zero on workflow failure (NOT thrown).
+  // result.exitCode and run.url feed into the unified summary in Step 10a.3.
+}
 ```
 
 **Step 10a.3: Update the unified summary (release sessions only)**
@@ -354,7 +384,7 @@ PUBLISH ({repo}):
   Published: {dist-tag}@{version} on npm
 ```
 
-Pull `Status` from the `gh run watch` exit code (success when the watch returned 0, failure otherwise). Pull `Published: {dist-tag}@{version}` from the workflow's published-package output if available; if the workflow failed before publishing, omit the `Published:` line and rely on `Status: failure` plus the workflow URL to point the maintainer at the failure.
+Pull `Status` from the watch result's `exitCode` (success when `result.exitCode === 0`, failure otherwise). Pull `Workflow` from `run.url` captured in 10a.2. Pull `Published: {dist-tag}@{version}` from the workflow's published-package output if available; if the workflow failed before publishing, omit the `Published:` line and rely on `Status: failure` plus the workflow URL to point the maintainer at the failure.
 
 #### Step 10b: Local / bare / other remotes — local merge flow
 

package/template/.claude/skills/maintenance/SKILL.md

@@ -108,22 +108,36 @@ Report one of:
 
 Active recommendations. Flags problems and suggests fixes, but asks before acting.
 
-### 7. Stale context
+### 7. Component age check
+
+Scan the following file sets for a YAML frontmatter `updated:` field:
+- `.claude/rules/*.md` (active rules only — `.md.skip` files are included too, since the rule content can still drift)
+- `.claude/skills/*/SKILL.md`
+- `.claude/agents/*.md`
+- `.claude/hooks/*.mjs`
+
+For each file that has an `updated:` field, compute the age in days from today. If the age exceeds 180 days, flag the file as a stale component candidate. Print the file name, the `updated:` date, and the age in days so the contributor knows how far the file has drifted.
+
+Files without an `updated:` field are skipped — the check is opt-in and activates the discipline incrementally as contributors add frontmatter to the files they own. To start tracking a file, add `updated: <today>` to its frontmatter; the check will surface it if it goes stale.
+
+When stale candidates are found, surface them as warnings in the output format and link to `config-review.md.skip` (in `.claude/rules/`) as the opt-in rule that documents the review cadence and rationale.
+
+### 8. Stale context
 - Ephemeral files not updated in 7+ days — suggest resolve, update, or archive
 - `work-sessions/{name}/` folders whose worktrees are gone — suggest cleanup
 - Session trackers whose branches have been merged — suggest `/complete-work` post-flight cleanup
 - Braindumps that overlap significantly — suggest merging (e.g., "workspace-branching.md and persistent-work-sessions.md cover the same topic")
 - Handoffs referencing deleted branches — suggest resolve or remove
 
-### 8. Context reconciliation
+### 9. Context reconciliation
 - Read recent workspace-context writes (last session or last N files by updated date)
 - For each, scan other workspace-context files for references that are now stale
 - Surface: "{file} says X but {newer-file} now says Y. Update {file}?"
 - This is the capture-time cross-check, run retroactively instead of inline
 
-### 9. Canonical budget triage
+### 10. Canonical budget triage
 
-This step runs only when the post-regen `--check` from step 8 still reports `selectionStatus: 'over-budget'`. If the regular regen pass cleared the budget — or if `--check` was already `ok`, `trimmed`, or `stubbed` after step 8 — skip this step entirely.
+This step runs only when the post-regen `--check` from step 9 still reports `selectionStatus: 'over-budget'`. If the regular regen pass cleared the budget — or if `--check` was already `ok`, `trimmed`, or `stubbed` after step 9 — skip this step entirely.
 
 The rest of cleanup is suggestion-list-with-confirmation: surface a candidate, ask before applying, move on. Triage is the one meaningfully more interactive surface in `/maintenance`. It runs as a small REPL: present the budget state and a triage menu, take one action, re-run `--check`, present the menu again with the new state. No suggestion is auto-applied; every action is the user's choice.
 
@@ -168,7 +182,19 @@ For each chosen action:
 
 Trim markers and demotions only matter for `priority: reference` files — `<!-- canonical:trim -->` spans on a `priority: critical` file are inert until the file is demoted. The triage flow never auto-decides which file to demote or which section to wrap; it surfaces the data, presents options, and waits.
 
-### 10. Health metrics
+### 11. Forge configuration
+
+Read `workspace.json`. If `workspace.tracker?.type === 'github-issues'` and `workspace.forge` is unset, emit a notice (not an error):
+
+```
+ℹ workspace.json has tracker.type='github-issues' but no workspace.forge field.
+  Skills default to GitHub forge operations; add `"forge": {"type": "github"}`
+  to workspace.json to make the choice explicit. See .claude/rules/forge-operations.md.
+```
+
+This is migration guidance for workspaces created before the `forge` field landed — the field is back-compat with a sensible default, so the unset case is not a bug, just an opportunity to make the implicit explicit. If `workspace.forge.type` is set to a value with no adapter at `.claude/scripts/forges/{type}.mjs`, that IS an error and goes in the Issues section.
+
+### 12. Health metrics
 - Canonical budget — read from the same `--check` invocation as step 5. Reported as `current / budget` bytes with the selection status (e.g., `full`, `2 reference files trimmed`). Over-budget cases are deferred to the cleanup triage flow rather than re-reported here.
 - Number of ephemeral files — flag if accumulating without resolution
 - Session log stats (if `workspace-scratchpad/session-log.jsonl` exists):
@@ -215,7 +241,7 @@ OK (5):
 5. Check git state (worktrees, branches, remotes)
 6. Run `node .claude/scripts/build-workspace-context.mjs --check --root .` — capture status. Exit `0` = clean and within budget, `1` = artifact missing or stale, `2` = artifacts current but canonical body over budget. The `canonical` block in the JSON output drives both the audit budget line and the cleanup triage decision.
 7. Read session-log.jsonl if it exists
-8. If cleanup mode: regenerate the workspace-context auto-files if stale (index.md, canonical.md, per-user team-member indexes); compare files pairwise for overlap; scan for stale cross-references. If post-regen `--check` reports `over-budget`, enter the canonical-budget triage flow described in cleanup step 9.
+8. If cleanup mode: regenerate the workspace-context auto-files if stale (index.md, canonical.md, per-user team-member indexes); compare files pairwise for overlap; scan for stale cross-references. If post-regen `--check` reports `over-budget`, enter the canonical-budget triage flow described in cleanup step 10.
 9. Compile and present findings grouped by severity
 
 ## Notes

package/template/.claude/skills/pause-work/SKILL.md

@@ -95,16 +95,33 @@ git push -u origin {branch}
 
 ### Step 7: Create draft PRs
 
-```bash
-# For each repo in the tracker's repos:
-cd work-sessions/{session-name}/workspace/repos/{repo}
-gh pr create --draft --title "WIP: {description}" --body "Work in progress. Session paused."
+PR creation goes through the forge adapter (`.claude/scripts/forges/interface.mjs`), not directly through `gh` — see `.claude/rules/forge-operations.md` for the contract and why. The adapter resolves the target repo from `workspace.forge.repo` or the local git remote.
 
-# Workspace repo — from the workspace worktree
-gh pr create --draft --title "context: {session-name} (paused)" --body "Workspace context for paused session."
+```javascript
+import { createForge } from './.claude/scripts/forges/interface.mjs';
+import { readFileSync } from 'node:fs';
+
+const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
+const forge = createForge(ws.workspace?.forge);
+
+// For each repo in the tracker's repos, from work-sessions/{session-name}/workspace/repos/{repo}:
+const projectPr = await forge.prCreate({
+  title: `WIP: ${description}`,
+  body: 'Work in progress. Session paused.',
+  draft: true,
+});
+console.log(projectPr.url);
+
+// Workspace repo — from the workspace worktree:
+const workspacePr = await forge.prCreate({
+  title: `context: ${sessionName} (paused)`,
+  body: 'Workspace context for paused session.',
+  draft: true,
+});
+console.log(workspacePr.url);
 ```
 
-If PRs already exist, update them to draft status if needed.
+If PRs already exist, update them to draft status if needed (use `gh pr ready --undo` directly until a `forge.prSetDraft` method lands — that's tracked as a future forge adapter extension, not blocking here).
 
 ### Step 8: Confirm