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

package/README.md

@@ -89,8 +89,8 @@ Four things, in the order you'll touch them:
 A scaffolded workspace with:
 
 - **14 skills** covering the workflow lifecycle, releases, handoffs, and maintenance
-- **8 active rules** + **8 optional `.skip` rules** for behaviors you can opt into
-- **10 hooks** for SessionStart, SubagentStart, PreCompact, WorktreeCreate, and the rest of the small set the conventions rely on
+- **9 active rules** + **9 optional `.skip` rules** for behaviors you can opt into
+- **9 hooks** for SessionStart, SubagentStart, PreCompact, and the rest of the small set the conventions rely on
 - A **`shared-context/`** memory system with three visibility levels: locked (team truths), root (team-visible ephemerals), user-scoped (personal)
 - Conventions for **multi-repo work sessions** with isolated git worktrees, parallelizable from separate terminals
 

package/lib/init.mjs

@@ -105,6 +105,25 @@ export async function initWorkspace(targetDir) {
     }
   }
 
+  // Set up .claudeignore
+  const payloadClaudeignore = join(payloadDir, '.claudeignore');
+  const claudeignorePath = join(targetDir, '.claudeignore');
+  if (existsSync(payloadClaudeignore)) {
+    if (existsSync(claudeignorePath)) {
+      const existing = readFileSync(claudeignorePath, 'utf-8');
+      const template = readFileSync(payloadClaudeignore, 'utf-8');
+      const existingLines = new Set(existing.split('\n').map(l => l.trim()));
+      const newLines = template.split('\n').filter(l => l.trim() && !existingLines.has(l.trim()));
+      if (newLines.length > 0) {
+        writeFileSync(claudeignorePath, existing.trimEnd() + '\n\n# From workspace template\n' + newLines.join('\n') + '\n');
+        console.log('  Merged template entries into .claudeignore');
+      }
+    } else {
+      cpSync(payloadClaudeignore, claudeignorePath);
+      console.log('  Created .claudeignore');
+    }
+  }
+
   console.log(`
   Workspace initialized (v${toVersion}).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulysses-ai/create-workspace",
-  "version": "0.16.0-beta.1",
+  "version": "0.17.0-beta.0",
   "description": "A workspace convention for Claude Code: sessions, handoffs, and shared context as files in git",
   "keywords": [
     "claude",

package/template/.claude/hooks/session-end.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 // SessionEnd hook — mark this chat's `ended` timestamp in the session
-// tracker and append a small safety-net note to the session.md body.
-import { appendFileSync, mkdirSync, existsSync } from 'fs';
+// tracker, append a small safety-net note to the session.md body, and
+// write a disk-durable reflection record if the session.md ## Progress
+// section contains heuristic correction-pattern sentences.
+import { appendFileSync, mkdirSync, existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { execSync } from 'child_process';
 import {
@@ -71,6 +73,70 @@ if (pointer && sessionId) {
       } catch {
         // Non-fatal
       }
+
+      // Disk-durable reflection sub-step (BP-10).
+      // Read the ## Progress section of session.md (last 2000 chars max),
+      // scan for heuristic correction-pattern sentences, and write any
+      // candidates to workspace-scratchpad/session-reflect.json. The file
+      // is gitignored (workspace-scratchpad/ is in _gitignore). We do NOT
+      // emit additionalContext for this — per the canonical known limitation,
+      // additionalContext does not always reach Claude. Disk is the primary
+      // durable output.
+      try {
+        const sessionContent = readFileSync(trackerPath, 'utf8');
+
+        // Extract ## Progress section — find the section and take last 2000 chars.
+        const progressMatch = sessionContent.match(/^## Progress\s*\n([\s\S]*?)(?=\n^##|\s*$)/m);
+        const progressText = progressMatch
+          ? progressMatch[1].slice(-2000)
+          : sessionContent.slice(-2000);
+
+        // Split into sentences on '. ' or '.\n' boundaries.
+        const sentences = progressText
+          .split(/(?<=\.)\s+|\n/)
+          .map(s => s.trim())
+          .filter(s => s.length > 10);
+
+        // Correction-pattern keywords — case-insensitive.
+        const correctionPatterns = [
+          /actually/i,
+          /instead of/i,
+          /the right way is/i,
+          /i was wrong/i,
+          /correction:/i,
+        ];
+
+        const candidates = sentences
+          .filter(sentence => correctionPatterns.some(re => re.test(sentence)))
+          .map(text => ({ text, source: '## Progress' }));
+
+        if (candidates.length > 0) {
+          if (!existsSync(scratchpadDir)) mkdirSync(scratchpadDir, { recursive: true });
+          const reflectPath = join(scratchpadDir, 'session-reflect.json');
+
+          // Read existing records to append (create-or-append pattern).
+          let records = [];
+          if (existsSync(reflectPath)) {
+            try {
+              records = JSON.parse(readFileSync(reflectPath, 'utf8'));
+              if (!Array.isArray(records)) records = [records];
+            } catch {
+              records = [];
+            }
+          }
+
+          records.push({
+            sessionId: sessionId || `ts-${Date.now()}`,
+            date: new Date().toISOString(),
+            workSession: pointer.name,
+            candidates,
+          });
+
+          writeFileSync(reflectPath, JSON.stringify(records, null, 2), 'utf8');
+        }
+      } catch {
+        // Non-fatal — reflection is best-effort.
+      }
     }
   }
 }

package/template/.claude/rules/config-review.md.skip

@@ -0,0 +1,29 @@
+# Config Review Cadence
+
+Opt-in reminder to review `.claude` component files on a regular schedule. Activate by removing the `.skip` extension (`mv config-review.md.skip config-review.md`). Add it back to deactivate.
+
+## When to review
+
+Review the files in `.claude/rules/`, `.claude/skills/*/SKILL.md`, `.claude/agents/*.md`, and `.claude/hooks/*.mjs` after each major model release and at least every 180 days. Claude Code evolves quickly — conventions that matched platform behavior six months ago may no longer be accurate, optimal, or even meaningful.
+
+The 180-day threshold is not arbitrary: it corresponds to roughly two major Claude model generations. Conventions written for an older model generation can silently mis-steer the newer one without anyone noticing, because the file still runs without error.
+
+## Connection to /maintenance
+
+The `/maintenance` skill's **Component age check** (step 7 in the Cleanup section) surfaces which files have drifted past 180 days by reading their frontmatter `updated:` field. Files without an `updated:` field are skipped — the check is incremental and only flags files that have opted in by carrying the field.
+
+When `/maintenance` reports stale components, the recommended action is to open each flagged file, read it against the current Claude Code documentation and platform behavior, update the content where needed, and bump `updated:` to today.
+
+## Why this ships as .skip
+
+Review cadence is org-specific. A solo maintainer doing active weekly development may want a shorter cadence; a team with a slower release cycle may need a longer one; some workspaces may defer review entirely to a dedicated maintenance session. Making this rule mandatory by default would encode one team's preference as a universal constraint — exactly the failure mode described in `product-bias-risk.md`.
+
+Activate the rule only if your team wants the reminder to appear in every session. If 180 days is wrong for your cadence, edit the threshold in the rule body after activating it.
+
+## Activating
+
+```
+mv .claude/rules/config-review.md.skip .claude/rules/config-review.md
+```
+
+Once active, this reminder loads into every session context. To deactivate, rename it back.

package/template/.claude/rules/forge-operations.md

@@ -0,0 +1,107 @@
+Activate this rule if the workspace creates PRs, watches CI runs, or interacts with releases from skills. Sibling to `work-item-tracking.md` (which covers issues); together they cover everything a workspace needs to do against a code-hosting forge.
+
+# Forge Operations
+
+When a workspace has a forge configured, all pull-request, release, and workflow-run operations from skills and scripts go through the adapter at `.claude/scripts/forges/{type}.mjs`. Skills never call `gh` (or `glab`, or any forge CLI) inline.
+
+## Why the abstraction
+
+- **Swap by config.** Moving from GitHub to GitLab is a `workspace.json` field change plus an adapter file — not a sweep across six skill files.
+- **Testable.** The adapter takes an injectable `spawnFn`; unit tests mock subprocess calls instead of running them.
+- **One vocabulary.** Skills reason about `forge.prCreate`, `forge.prMerge`, `forge.workflowRunFind`, `forge.workflowRunWatch`, `forge.releaseView` regardless of backend. Failure modes share typed errors (`PrNotFound`, `MergeRejected`, `WorkflowNotFound`, `ReleaseNotFound`) instead of every callsite parsing stderr.
+
+## Configuration
+
+`workspace.json` → `workspace.forge`:
+
+```json
+{
+  "workspace": {
+    "forge": {
+      "type": "github"
+    }
+  }
+}
+```
+
+- `type` — identifies the adapter module at `.claude/scripts/forges/{type}.mjs`. `github` is the default and the only fully-implemented adapter today. `gitlab.mjs` ships as a stub that throws `NOT_IMPLEMENTED` with a contribution pointer.
+- `repo` (optional) — adapter-specific. For `github`, the `owner/name` slug to target. When unset or `"auto"`, the adapter resolves the repo from the local git `origin` remote.
+
+Absence of `workspace.forge` is treated as `{ type: 'github' }` (back-compat for workspaces that predate the field). Setting `workspace.forge: false` explicitly disables forge operations — every adapter method then throws `FORGE_DISABLED`.
+
+## Adapter interface (for Claude)
+
+Import from `.claude/scripts/forges/interface.mjs`:
+
+```javascript
+import { createForge, PrNotFound, MergeRejected, WorkflowNotFound, ReleaseNotFound } 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);
+
+// Pull request lifecycle
+const pr = await forge.prCreate({
+  title: 'feat: add forge adapter',
+  body: 'long-form body',
+  draft: false,                // omit or false for normal PRs; true for /pause-work drafts
+  base: 'main',                // optional; defaults to repo default branch
+  head: 'feature/forge',       // optional; defaults to current branch
+});                            // → { id: 'owner/repo#42', url, number }
+
+await forge.prMerge({
+  id: pr.id,
+  strategy: 'squash',          // 'merge' | 'squash' | 'rebase'
+  deleteBranch: true,
+});
+
+const view = await forge.prView({ id: pr.id });
+// → { state, mergeable, mergeStateStatus, reviewDecision, ... }
+
+// Releases (lookup only — release creation lives in the workflow tag-push)
+const release = await forge.releaseView({ tag: 'v1.2.3' });
+// → { tag, name, url, publishedAt, isDraft, isPrerelease }
+// throws ReleaseNotFound if the tag has no release
+
+// Workflow runs (used by /complete-work to follow the publish workflow)
+const run = await forge.workflowRunFind({
+  workflow: 'publish.yml',
+  branch: 'v1.2.3',
+  limit: 1,
+});                            // → { runId, status, conclusion, url } | null
+const result = await forge.workflowRunWatch({
+  runId: run.runId,
+  exitStatus: true,            // true: exit non-zero on workflow failure
+});                            // → { exitCode } — does NOT throw on workflow failure
+```
+
+All methods are async. Adapter-detectable failures throw typed errors; raw spawn failures throw `Error`.
+
+## Skill behavior
+
+Skills that interact with forge operations:
+
+- **`/pause-work`** — creates draft PRs via `forge.prCreate({ draft: true })`.
+- **`/complete-work`** — creates PRs, merges them with `strategy: 'squash'`, and (release sessions only) finds + watches the publish workflow via `workflowRunFind` + `workflowRunWatch`. Uses `releaseView` to investigate existing tag conflicts before re-tagging.
+
+Skills outside that list do not call the forge adapter; they either don't touch the forge or they touch it for tracker-setup-specific operations that are deliberately scoped out (see below).
+
+## What this rule does NOT cover
+
+- **Issue lifecycle.** Issues, comments, labels, milestones live in `work-item-tracking.md` via the tracker adapter at `.claude/scripts/trackers/{type}.mjs`. The two abstractions are intentionally separate.
+- **Tracker-setup repo configuration.** `/setup-tracker` uses `gh repo view --json hasIssuesEnabled` and `gh api repos/{slug} -X PATCH -f has_issues=true` to inspect and enable the Issues feature on a GitHub repo. Those are GitHub-API-specific setup operations, not the cross-cutting PR/release ops the forge abstraction targets. A GitLab user running `/setup-tracker` would follow a different setup flow entirely, so wrapping these in the forge adapter would create a leaky abstraction. They remain direct `gh` calls.
+- **`gh repo view` as a remote-type probe.** `/complete-work` uses `gh repo view` to detect whether a remote is a GitHub remote (separately from any PR operation that follows). This is a one-line capability check, not an operation that benefits from forge wrapping. It stays direct.
+- **Repo creation.** `gh repo create` (in `/sync-work` and `/workspace-init` setup narratives) is an interactive one-off used when a workspace lacks a remote. No forge adapter method for it — pointing users at a wrapped form when none exists would be worse than the current direct mention.
+- **Manual operator recovery.** `gh run rerun`, `gh run view`, `gh release view` referenced in `/release` recovery guidance are documented for an operator at a terminal investigating a failed publish. The forge adapter is for *skill code*, not the manual recovery prose.
+
+## Migration
+
+Existing workspaces predate `workspace.forge`. They continue to work because `createForge(undefined)` defaults to `{ type: 'github' }`. The `/maintenance` audit surfaces a notice when `workspace.tracker.type === 'github-issues'` and `workspace.forge` is unset, suggesting the explicit value — a one-line `workspace.json` addition with no behavior change.
+
+A workspace switching to GitLab implements `.claude/scripts/forges/gitlab.mjs` against the interface (the stub file documents the shape) and sets `workspace.forge.type: 'gitlab'`. No skill rewrite is required; the abstraction does the routing.
+
+## What this rule does NOT do
+
+- Does not prescribe a specific forge type. Adapter choice is per workspace.
+- Does not replace forge-native features (PR comments, review-requested webhooks, branch protection settings) — those remain UI / direct-CLI territory.
+- Does not promise that every `gh` capability is wrapped. The adapter covers the operations the template's skills actually perform. New operations land via additive interface methods, not by skills going around the adapter.

package/template/.claude/rules/goal-driven-work.md

@@ -107,6 +107,19 @@ The evaluator's "no, awaiting review" response after a gated phase does not bypa
 
 `gate: auto` is allowed in the format but discouraged in v1. Earn it after the workflow has been exercised at least once on the work in question.
 
+## Gate-budget interaction and turn-budget sizing
+
+A goal's `turn_budget` is a backstop that counts every orchestrator turn — including the short "awaiting your gate decision" exchanges that happen at every `gate: review` phase. The `/goal` evaluator re-pings the session whenever it tries to settle without the completion condition being met, and each ping consumes a turn. Concretely: a multi-phase gated goal whose author is away for stretches can spend a meaningful fraction of its budget *idling at gates* rather than advancing work. A run with six `gate: review` phases burned roughly half of a 150-turn budget on gate-idle pings before the actual work completed.
+
+This is a structural property of `/goal` + review gates, not a per-goal accident. Plan for it:
+
+- **Drop `gate: review` from early phases when the human is expected to be away for stretches.** Research, crossref, spec, and plan phases produce artifacts that the final session→main PR consumes anyway. The integration-branch model (`main` untouched until `/complete-work` opens the final PR for human review) already provides one strong human review point; piling per-phase gates on top of that, with no human watching, just burns budget. Set those phases to `gate: auto` when the run will be unattended.
+- **Keep `gate: review` for phases with irreversible side effects or for phases whose outcome reshapes subsequent phases.** A spec gate that lets the human reprioritize the ranked execution list before `executing-plans` walks it is worth its cost; a research-synthesis gate that just rubber-stamps a matrix the human will see again in the final PR is not.
+- **Size `turn_budget` for the worst case you actually expect.** If every phase is `gate: auto`: budget ≈ (estimated work-turns) × 1.2 (small headroom for retries). If any phases are `gate: review` and the human may be unavailable for hours: multiply the work-turn estimate by **2–3×** to absorb gate-idle pings, or raise the budget mid-goal by editing the goal artifact's `completion_condition` and `turn_budget` fields. The Stop-hook condition string is fixed from the original `/goal` invocation; raising `turn_budget` in the artifact keeps the auditable source-of-truth correct for resume but does not change the running evaluator's text — the user can re-run the (updated) `## Start command` to refresh it after `/goal clear`.
+- **If the goal stops on the backstop mid-work because of gate-idle waste, that is the system working as designed.** `claude --resume` plus re-running the `## Start command` continues from durable phase state; phase artifacts and per-phase `status: complete` markers survive. Do not treat backstop-stop as a failure of the goal.
+
+This guidance is workspace-side mitigation only. The underlying friction — the evaluator pinging during gate-idle — is `/goal` harness behavior, not workspace code. A cleaner fix (suspend the evaluator at review gates so it does not re-ping until a new user message arrives) is tracked separately and would obsolete the multiplier above when it lands.
+
 ## Integration branch and per-phase sub-PRs
 
 While a `/goal`-driven session is running, the session branch (`feature/{session-name}`) acts as the goal's integration branch. Main is untouched until `/complete-work` opens the final session→main PR for human review. This is the key autonomy boundary: phase agents can merge their own work, repeatedly, throughout the goal — but only into the integration branch, never into main.

package/template/.claude/rules/workspace-structure.md

@@ -47,6 +47,16 @@ Canonical content is verbatim-loaded into every session via `CLAUDE.md` → `@wo
 
 Inflight session state lives inside the session worktree at `work-sessions/{name}/workspace/session.md`, not in `workspace-context/`. Workspace-context is for knowledge that outlives any individual session.
 
+## Dynamic context loading (hooks)
+
+Two hooks extend static `CLAUDE.md` loading with context that varies per session and per invocation:
+
+- **`session-start.mjs`** (`SessionStart` hook): reads the active session pointer from `workspace-scratchpad/` and injects the current session's name, branch, linked work item, and shared context catalog into Claude's context. The injection is conditional — if no session is active, or if the relevant fields are absent from the session frontmatter, nothing is added. This avoids noise in non-session contexts (e.g., a quick launcher query).
+
+- **`subagent-start.mjs`** (`SubagentStart` hook): reads every file under `workspace-context/shared/locked/` and injects their content into subagent context. A `subagentContextMaxBytes` field in `workspace.json` (default 10240) acts as a byte-budget fallback — if the total locked content exceeds the budget, files are truncated in reverse-priority order rather than silently dropped. This ensures subagents that never load `CLAUDE.md` still receive canonical team truths.
+
+Both hooks are at `.claude/hooks/session-start.mjs` and `.claude/hooks/subagent-start.mjs`. They are registered as Node.js scripts — cross-platform, no shell dependency.
+
 ## Spec and Plan Locations — MANDATORY OVERRIDE
 
 **Specs, plans, and goal artifacts MUST be written at the top of the active session's workspace worktree, not to `docs/superpowers/` or any other location.**
@@ -97,3 +107,31 @@ Local-only personal drafts get an additional `local-only-` prefix (e.g., `local-
 - `workspace-scratchpad/` is for disposable files only — session log, hook debug output, temporary pointers.
 - Project worktrees are nested inside the workspace worktree's real `repos/` directory — no symlink.
 - Hand edits to `index.md`, `canonical.md`, or any per-user `team-member/{user}/index.md` are overwritten by `build-workspace-context.mjs`. Update source files (or their `description:` frontmatter) instead.
+
+## Per-repo commands
+
+Per-repo test, lint, and build commands belong in `repos/{repo}/CLAUDE.md` under a `## Commands` section. This scopes Claude's command invocations to the specific repo rather than triggering monorepo-wide runs that may time out or produce irrelevant output. The `/workspace-init` skill scaffolds a blank `repos/{repo}/CLAUDE.md` stub with a `## Commands` placeholder — fill it in once the repo is cloned.
+
+## Explore before editing
+
+Before modifying files in a large or unfamiliar codebase, use read-only tools to map the affected surface. The workflow: dispatch a researcher-type subagent to read, grep, and navigate the codebase; have it return a summary of the affected files, callers, and dependencies; then edit only after the map is established.
+
+The `researcher.md` agent enforces this pattern mechanically via `disallowedTools: [Edit, Write, Bash]` — it can read and search but cannot change anything. Use it for initial exploration, then hand the findings back to the main agent for the actual edit. This avoids partial edits that break callers, catches ripple effects before they happen, and keeps the edit surface as small as possible.
+
+## Launching Claude from a project worktree
+
+Claude can be launched from any directory, and it walks up the filesystem loading every `CLAUDE.md` it finds. This means starting `claude` from `work-sessions/{name}/workspace/repos/{repo}/` loads both the per-repo conventions (from `repos/{repo}/CLAUDE.md`, if it exists) and the full workspace conventions (from the workspace `CLAUDE.md` further up the tree) — all without extra configuration.
+
+For repo-focused work — debugging a single service, reviewing a specific module, running targeted tests — launching from the project worktree gives Claude a tighter codebase context. It sees the repo's own file tree first and reaches workspace-level conventions by traversal. The session hooks still fire (they read from `workspace-scratchpad/`, which is always relative to the workspace root), and `session.md` and all session artifacts remain at the workspace worktree top.
+
+This is purely a launch-point choice; no workspace configuration changes are needed to enable it.
+
+## Grep vs LSP
+
+Two complementary search strategies cover different parts of the navigation surface:
+
+- **Grep / Ripgrep** — searches file content as text. Fast, requires no server, and works across any file type. Use for free-text pattern search: finding a string literal, locating config values, scanning comments, searching across heterogeneous files. The downside: no language awareness — a search for `_toMs` matches comments, string literals, and variable names alike, producing false positives that require manual filtering.
+
+- **LSP tools (`mcp__lsp__*`)** — powered by a running Language Server Protocol server that has indexed the codebase. LSP understands the language's type system and scope rules, so `find-all-references` on `_toMs` returns only actual symbol usages, not textual coincidences. Go-to-definition, rename-symbol, and callers/callees are accurate even across files and module boundaries. The tradeoff: requires a running LSP MCP server configured in `.mcp.json`.
+
+The practical rule: reach for Grep first when you don't know where to look or when the pattern is not a symbol. Switch to LSP when you have a specific symbol and need precise cross-file navigation — especially before refactoring or understanding a call graph. The `researcher.md` agent lists the LSP tool among its allowed tools; activating LSP requires adding the appropriate language server to `.mcp.json` (see the MCP servers step in `/workspace-init`).

package/template/.claude/scripts/cleanup-work-session.mjs

@@ -11,9 +11,23 @@
 // Workspace-first removal silently deletes the nested project worktrees'
 // .git files and leaves orphan worktree records in the project repos.
 // The safe order keeps both sides of the relationship in sync.
+//
+// State discovery is defensive: the session tracker (session.md) may have
+// been stripped by /complete-work Step 7 before this script runs, leaving
+// no `repos:` or `branch:` to read. When that happens we discover repos
+// from the work-sessions/{name}/workspace/repos/ directory listing and the
+// branch from `git branch --show-current` on the workspace worktree —
+// BEFORE removing anything. Without that, the per-repo loops silently
+// no-op and the script reports success while leaving orphans behind
+// (gh:119).
+//
+// `success: true` means VERIFIED: every project worktree record is gone
+// (no prunable entries left over), every local branch is deleted, and the
+// session folder is removed. The script post-verifies all of these and
+// surfaces any leftover state as an error rather than swallowing it.
 import '../lib/require-node.mjs';
 import { execSync } from 'child_process';
-import { existsSync } from 'fs';
+import { existsSync, readdirSync, statSync } from 'fs';
 import { join } from 'path';
 import {
   getWorkspaceRoot,
@@ -36,74 +50,198 @@ if (!sessionName) {
 }
 
 const root = getWorkspaceRoot(import.meta.url);
-const tracker = readSessionTracker(root, sessionName);
-const repos = normalizeRepos(tracker?.repos);
-const branch = tracker?.branch;
 const reposDir = join(root, 'repos');
 const sessionFolder = sessionFolderPath(root, sessionName);
 const wsWorktree = join(sessionFolder, 'workspace');
 
 const removed = [];
+const skipped = [];
 const errors = [];
 
-// Step 1: Remove each project worktree FIRST, from its project repo
-for (const repo of repos) {
-  const projWorktree = join(wsWorktree, 'repos', repo);
-  const repoDir = join(reposDir, repo);
-  if (existsSync(projWorktree)) {
+// === Discovery: where session.md is silent or missing, fall back to disk ===
+//
+// The tracker may have been stripped before this script runs. Read whatever
+// is still there, then fill gaps from the live worktree state.
+
+const tracker = readSessionTracker(root, sessionName);
+let repos = normalizeRepos(tracker?.repos);
+let branch = tracker?.branch || null;
+
+// If repos is empty, discover from work-sessions/{name}/workspace/repos/.
+// That directory is the workspace worktree's nested-project-worktrees dir;
+// each entry is one project repo this session checked out.
+if (repos.length === 0) {
+  const nestedReposDir = join(wsWorktree, 'repos');
+  if (existsSync(nestedReposDir)) {
     try {
-      execSync(`git worktree remove "${projWorktree}" --force`, { cwd: repoDir, stdio: 'pipe' });
-      removed.push(`project worktree ${repo}`);
+      const discovered = readdirSync(nestedReposDir).filter((entry) => {
+        try {
+          return statSync(join(nestedReposDir, entry)).isDirectory();
+        } catch {
+          return false;
+        }
+      });
+      if (discovered.length > 0) {
+        repos = discovered;
+        skipped.push({
+          step: 'discovery',
+          reason: `Tracker missing repos; discovered ${discovered.length} from ${nestedReposDir}: ${discovered.join(', ')}`,
+        });
+      }
     } catch (err) {
-      errors.push(`Failed to remove ${repo} worktree: ${err.message}`);
+      skipped.push({ step: 'discovery', reason: `Failed to list ${nestedReposDir}: ${err.message}` });
     }
   }
 }
 
-// Step 2: Remove the workspace worktree AFTER project worktrees are gone
+// If branch is missing, ask the workspace worktree itself.
+if (!branch && existsSync(wsWorktree)) {
+  try {
+    branch = execSync('git rev-parse --abbrev-ref HEAD', { cwd: wsWorktree, stdio: 'pipe', encoding: 'utf-8' }).trim();
+    if (branch) {
+      skipped.push({ step: 'discovery', reason: `Tracker missing branch; discovered from worktree: ${branch}` });
+    }
+  } catch (err) {
+    skipped.push({ step: 'discovery', reason: `Failed to read branch from ${wsWorktree}: ${err.message}` });
+  }
+}
+
+// === Step 1: Remove each project worktree FIRST, from its project repo ===
+for (const repo of repos) {
+  const projWorktree = join(wsWorktree, 'repos', repo);
+  const repoDir = join(reposDir, repo);
+  if (!existsSync(projWorktree)) {
+    skipped.push({ step: 'remove-project-worktree', repo, reason: `${projWorktree} does not exist` });
+    continue;
+  }
+  if (!existsSync(repoDir)) {
+    errors.push(`Cannot remove ${repo} worktree: source clone missing at ${repoDir}`);
+    continue;
+  }
+  try {
+    execSync(`git worktree remove "${projWorktree}" --force`, { cwd: repoDir, stdio: 'pipe' });
+    removed.push(`project worktree ${repo}`);
+  } catch (err) {
+    errors.push(`Failed to remove ${repo} worktree: ${err.message.trim()}`);
+  }
+}
+
+// === Step 2: Remove the workspace worktree AFTER project worktrees are gone ===
 if (existsSync(wsWorktree)) {
   try {
     execSync(`git worktree remove "${wsWorktree}" --force`, { cwd: root, stdio: 'pipe' });
     removed.push('workspace worktree');
   } catch (err) {
-    errors.push(`Failed to remove workspace worktree: ${err.message}`);
+    errors.push(`Failed to remove workspace worktree: ${err.message.trim()}`);
   }
+} else {
+  skipped.push({ step: 'remove-workspace-worktree', reason: `${wsWorktree} does not exist` });
 }
 
-// Step 3: Prune each project repo to mop up orphans from any prior misuses
+// === Step 3: Prune each project repo to mop up orphans ===
 for (const repo of repos) {
   const repoDir = join(reposDir, repo);
+  if (!existsSync(repoDir)) continue;
   try {
     execSync('git worktree prune', { cwd: repoDir, stdio: 'pipe' });
-  } catch {
-    // Non-fatal — prune is a safety net
+  } catch (err) {
+    // Prune is a safety net, but if it fails on a repo we touched, surface
+    // it — verification below will catch leftover orphans either way.
+    errors.push(`Prune failed in ${repo}: ${err.message.trim()}`);
   }
 }
 
-// Step 4: Delete local branches
+// === Step 4: Delete local branches ===
 if (branch) {
   for (const repo of repos) {
     const repoDir = join(reposDir, repo);
+    if (!existsSync(repoDir)) continue;
     try {
-      execSync(`git branch -D "${branch}"`, { cwd: repoDir, stdio: 'pipe' });
+      execSync(`git branch --list "${branch}"`, { cwd: repoDir, stdio: 'pipe', encoding: 'utf-8' });
     } catch {
-      // Non-fatal — branch may already be gone or refuse to delete
+      continue; // Repo broken; verification will catch downstream impact.
+    }
+    const exists = execSync(`git branch --list "${branch}"`, { cwd: repoDir, encoding: 'utf-8' }).trim();
+    if (!exists) continue; // Already gone (e.g., gh pr merge --delete-branch did it).
+    try {
+      execSync(`git branch -D "${branch}"`, { cwd: repoDir, stdio: 'pipe' });
+    } catch (err) {
+      errors.push(`Failed to delete branch ${branch} in ${repo}: ${err.message.trim()}`);
     }
   }
+  // Same for the workspace repo (root).
   try {
-    execSync(`git branch -D "${branch}"`, { cwd: root, stdio: 'pipe' });
+    const exists = execSync(`git branch --list "${branch}"`, { cwd: root, encoding: 'utf-8' }).trim();
+    if (exists) {
+      try {
+        execSync(`git branch -D "${branch}"`, { cwd: root, stdio: 'pipe' });
+      } catch (err) {
+        errors.push(`Failed to delete branch ${branch} in workspace repo: ${err.message.trim()}`);
+      }
+    }
   } catch {
-    // Non-fatal
+    // workspace root not a git repo — unusual, skip.
   }
 }
 
-// Step 5: Delete the whole work-sessions/{name}/ folder. The session.md,
-// specs, plans, and any local-only artifacts vanish. Their content was
-// archived into release notes by /complete-work before this script ran.
-deleteSessionFolder(root, sessionName);
+// === Step 5: Delete the whole work-sessions/{name}/ folder ===
+try {
+  deleteSessionFolder(root, sessionName);
+} catch (err) {
+  errors.push(`Failed to delete session folder ${sessionFolder}: ${err.message.trim()}`);
+}
+
+// === Post-verification: success means VERIFIED, not "no try/catch threw" ===
+//
+// Without these checks, an empty repos list (the gh:119 root cause) lets
+// every silent skip add up to a "success" output while leaving orphans
+// behind. The verification turns silent skips into honest errors.
+
+if (existsSync(sessionFolder)) {
+  errors.push(`Session folder still present after cleanup: ${sessionFolder}`);
+}
+
+const wsPath = wsWorktree; // canonical path the worktree had
+for (const repo of repos) {
+  const repoDir = join(reposDir, repo);
+  if (!existsSync(repoDir)) continue;
+  let wtList = '';
+  try {
+    wtList = execSync('git worktree list --porcelain', { cwd: repoDir, encoding: 'utf-8' });
+  } catch (err) {
+    errors.push(`Could not list worktrees in ${repo}: ${err.message.trim()}`);
+    continue;
+  }
+  if (wtList.includes('prunable')) {
+    errors.push(`Prunable worktree record remains in ${repo} after cleanup (gh:119 symptom)`);
+  }
+  if (wtList.includes(wsPath)) {
+    errors.push(`${repo} still has a worktree record referencing the session path`);
+  }
+  if (branch) {
+    const branchStill = execSync(`git branch --list "${branch}"`, { cwd: repoDir, encoding: 'utf-8' }).trim();
+    if (branchStill) {
+      errors.push(`Branch ${branch} still present in ${repo} after cleanup`);
+    }
+  }
+}
+
+if (branch) {
+  try {
+    const branchStill = execSync(`git branch --list "${branch}"`, { cwd: root, encoding: 'utf-8' }).trim();
+    if (branchStill) {
+      errors.push(`Branch ${branch} still present in workspace repo after cleanup`);
+    }
+  } catch {
+    // not a git repo — already noted
+  }
+}
 
 console.log(JSON.stringify({
   success: errors.length === 0,
   removed,
+  skipped: skipped.length > 0 ? skipped : undefined,
   errors: errors.length > 0 ? errors : undefined,
 }));
+
+if (errors.length > 0) process.exit(1);