@ulysses-ai/create-workspace 0.13.0-beta.1 → 0.14.0-beta.1

package/README.md

@@ -1,5 +1,8 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/ukt-solutions/create-ulysses-workspace/main/docs/assets/logo.png" alt="Ulysses Workspace" width="220">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ukt-solutions/create-ulysses-workspace/main/docs/assets/logo-dark.png">
+    <img src="https://raw.githubusercontent.com/ukt-solutions/create-ulysses-workspace/main/docs/assets/logo.png" alt="Ulysses Workspace" width="220">
+  </picture>
 </p>
 
 # @ulysses-ai/create-workspace
@@ -86,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
-- **6 active rules** + **8 optional `.skip` rules** for behaviors you can opt into
-- **8 hooks** for SessionStart, SubagentStart, PreCompact, WorktreeCreate, and the rest of the small set the conventions rely on
+- **7 active rules** + **8 optional `.skip` rules** for behaviors you can opt into
+- **9 hooks** for SessionStart, SubagentStart, PreCompact, WorktreeCreate, 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
 
@@ -131,6 +134,15 @@ The eleven [chapters](https://github.com/ukt-solutions/create-ulysses-workspace/
 
 In active pre-1.0 development. Used as dogfood and validated against external workspaces. Conventions and CLI flags are stable; small refinements continue. v1.0 will mark a stability commitment.
 
+## Feedback
+
+Beta testers, early adopters, and anyone curious — feedback of any shape is genuinely wanted.
+
+- **Bugs, rough edges, "this didn't do what I expected"** → [open an issue](https://github.com/ukt-solutions/create-ulysses-workspace/issues/new)
+- **Design questions, "why does it work this way?", ideas for new skills or rules** → [start a discussion](https://github.com/ukt-solutions/create-ulysses-workspace/discussions)
+
+First-hand reports of the scaffold-and-go-for-it experience are the single most useful thing at this stage — especially anything that surprised you, tripped you up, or felt like friction the CLI could have caught.
+
 ## License
 
 MIT

package/package.json

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

package/template/.claude/hooks/_bash-output-advisory.test.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// Unit tests for bash-output-advisory.mjs pattern detection.
+// Run: node .claude/hooks/_bash-output-advisory.test.mjs
+import { detectNoisyPattern } from './bash-output-advisory.mjs';
+
+let failed = 0;
+let passed = 0;
+
+function shouldWarn(command, label) {
+  const result = detectNoisyPattern(command);
+  if (result) {
+    passed++;
+  } else {
+    failed++;
+    console.error(`  FAIL: ${label}\n    command: ${command}\n    expected an advisory, got null`);
+  }
+}
+
+function shouldNotWarn(command, label) {
+  const result = detectNoisyPattern(command);
+  if (!result) {
+    passed++;
+  } else {
+    failed++;
+    console.error(`  FAIL: ${label}\n    command: ${command}\n    expected null, got: ${result}`);
+  }
+}
+
+// === Test runners ===
+shouldWarn('npm test', 'bare npm test');
+shouldWarn('npm run test', 'bare npm run test');
+shouldWarn('yarn test', 'bare yarn test');
+shouldWarn('pnpm test', 'bare pnpm test');
+shouldWarn('bun test', 'bare bun test');
+shouldWarn('cargo test', 'bare cargo test');
+shouldWarn('npm test --coverage', 'npm test with non-scoping flag');
+
+shouldNotWarn('npm test path/to/file.test.mjs', 'npm test with file path');
+shouldNotWarn('npm test src/', 'npm test with directory');
+shouldNotWarn('npm test -- --grep auth', 'npm test with -- args');
+shouldNotWarn('npm test myFile.test.js', 'npm test with bare filename');
+shouldNotWarn('npm test | grep FAIL', 'npm test piped to grep');
+shouldNotWarn('npm test | head -50', 'npm test piped to head');
+shouldNotWarn('cargo test auth_module', 'cargo test with module filter');
+
+// === grep -r ===
+shouldWarn('grep -r "pattern" .', 'bare grep -r');
+shouldWarn('grep --recursive "pattern" src/', 'grep --recursive long form');
+shouldWarn('grep -rn "TODO" .', 'grep -rn (recursive + line numbers)');
+
+shouldNotWarn('grep -r --include="*.js" pattern .', 'grep -r with --include');
+shouldNotWarn('grep -r pattern . --exclude="*.log"', 'grep -r with --exclude');
+shouldNotWarn('grep "pattern" file.txt', 'non-recursive grep');
+
+// === find on broad anchors ===
+shouldWarn('find /', 'find on root');
+shouldWarn('find ~', 'find on home tilde');
+shouldWarn('find $HOME', 'find on $HOME');
+
+shouldNotWarn('find / -name "*.log"', 'find / with -name');
+shouldNotWarn('find ~ -path "*node_modules*" -prune', 'find ~ with -path');
+shouldNotWarn('find . -type f', 'find on cwd');
+shouldNotWarn('find ./src -name "*.ts"', 'find on relative subdir');
+
+// === cat on log-shaped files ===
+shouldWarn('cat server.log', 'cat .log file');
+shouldWarn('cat events.jsonl', 'cat .jsonl file');
+shouldWarn('cat trace.ndjson', 'cat .ndjson file');
+shouldWarn('cat path/to/big.log', 'cat .log in subdir');
+
+shouldNotWarn('cat package.json', 'cat package.json');
+shouldNotWarn('cat README.md', 'cat README');
+shouldNotWarn('cat src/index.ts', 'cat source file');
+shouldNotWarn('cat server.log | tail -50', 'cat .log piped to tail');
+
+// === redirected output (always allowed) ===
+shouldNotWarn('npm test > /tmp/test-output.txt', 'npm test redirected to file');
+shouldNotWarn('grep -r foo . > out.txt', 'grep -r redirected to file');
+shouldNotWarn('find / 2>&1 | tee /tmp/find.txt', 'find piped to tee');
+
+// === unrelated commands ===
+shouldNotWarn('git status', 'git status');
+shouldNotWarn('ls -la', 'ls');
+shouldNotWarn('echo hello', 'echo');
+shouldNotWarn('node --version', 'node version');
+
+console.log(`Passed: ${passed}, Failed: ${failed}`);
+if (failed > 0) process.exit(1);

package/template/.claude/hooks/bash-output-advisory.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// PreToolUse hook — soft advisory for known-noisy bash commands.
+//
+// Does NOT modify the command. Emits a one-line additionalContext nudge so
+// the model can choose to scope the command before executing. Patterns are
+// deliberately narrow — false positives train the model to ignore the hook.
+//
+// Add patterns sparingly. The cost of a missed nudge is one bloated tool
+// result; the cost of crying wolf is a permanently-ignored hook.
+import { fileURLToPath } from 'url';
+import { readStdin, respond } from './_utils.mjs';
+
+// Only run the hook body when invoked directly (not when imported by tests).
+const isEntry = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+if (isEntry) {
+  const input = await readStdin();
+  if (input.tool_name !== 'Bash') {
+    respond();
+    process.exit(0);
+  }
+
+  const command = (input.tool_input?.command || '').trim();
+  if (!command) {
+    respond();
+    process.exit(0);
+  }
+
+  const advisory = detectNoisyPattern(command);
+  if (advisory) {
+    respond(`Bash advisory: ${advisory} Consider scoping the command (path, filter, or pipe to head/tail/grep) before running.`);
+  } else {
+    respond();
+  }
+}
+
+export function detectNoisyPattern(command) {
+  // Already piped to a bounding command — caller knows what they're doing.
+  if (/\|\s*(head|tail|grep|rg|wc|less|more)\b/.test(command)) return null;
+  // Output already redirected to a file — not consuming context.
+  if (/(?:^|\s)(?:>|>>|\|\s*tee)\s+\S/.test(command)) return null;
+
+  // 1. Bare test runners with no scope.
+  // Matches `npm test`, `npm run test`, `yarn test`, `pnpm test`, `bun test`, `cargo test`
+  // followed by nothing, or only by recognized flags that don't constrain output.
+  const testRunner = /^(?:npm(?:\s+run)?|yarn|pnpm|bun)\s+test\b(.*)$/.exec(command)
+    || /^cargo\s+test\b(.*)$/.exec(command);
+  if (testRunner) {
+    const tail = testRunner[1];
+    // A scope is any non-flag positional arg (path, filename, or test-name filter).
+    // Flags that don't constrain output (--coverage, --watch, --verbose, --bail) don't count.
+    const hasScope = tail.split(/\s+/).some(arg => arg && !arg.startsWith('-'));
+    if (!hasScope) {
+      return 'Bare test-runner invocation will produce all-tests output.';
+    }
+  }
+
+  // 2. Recursive grep without an include filter.
+  // Note: ripgrep (`rg`) is recursive by default and respects .gitignore, so a
+  // bare `rg pattern .` is usually fine. We only flag classic `grep -r`.
+  if (/^grep\s+(?:-\w*r\w*|-r\b|--recursive\b)/.test(command)
+      && !/--include[=\s]|--exclude[=\s]/.test(command)) {
+    return 'Recursive grep without --include can return thousands of matches.';
+  }
+
+  // 3. find on a home/root anchor without a name/path constraint.
+  if (/^find\s+(?:\/|~|\$HOME|\$\{HOME\})(?:\s|$)/.test(command)
+      && !/-(?:name|iname|path|ipath|regex)\b/.test(command)) {
+    return 'find on a broad anchor without -name/-path enumerates the whole tree.';
+  }
+
+  // 4. cat on log-shaped files.
+  if (/^cat\s+\S*\.(?:log|jsonl|ndjson)\b/.test(command)) {
+    return 'Log-shaped files are often large.';
+  }
+
+  return null;
+}

package/template/.claude/rules/task-list-mirroring.md

@@ -0,0 +1,69 @@
+# Task List Mirroring
+
+The Claude Code `TodoWrite` checklist is a live mirror of the workspace lifecycle. The durable backing store is a `## Tasks` section in `session.md`, round-tripped by `.claude/scripts/sync-tasks.mjs`. This rule defines the contract.
+
+## Why
+
+`TodoWrite` is conversation-scoped — it disappears at the end of every chat. To make it useful for multi-chat work sessions, it needs a durable store that survives chat restarts, machine switches, and pause/resume cycles. `session.md` already lives on the session branch and travels with `git push`/`git pull`, so it's the natural home.
+
+## The `## Tasks` schema
+
+Anchored after `## Pre-session context` (if present) and before `## Progress`:
+
+```
+## Tasks
+
+> Linked: gh:42 — Auth timeout on mobile
+
+- [x] Start work
+- [x] Reproduce on iOS Safari
+- [ ] Identify race condition in token refresh
+- [ ] Complete work
+```
+
+- The heading is exactly `## Tasks`.
+- Optional first line is a blockquote `> Linked: {workItem-id} — {issue-title}`. Present iff `workItem:` is set in frontmatter.
+- Each task is one checkbox line. Three statuses: `- [ ]` pending, `- [-]` in_progress, `- [x]` completed. No nesting.
+- The bookends `Start work` and `Complete work` are always present, at positions 1 and N.
+
+The `- [-]` marker is non-standard GFM — GitHub's web renderer shows it as literal text rather than a checkbox. That's acceptable because `session.md` lives on session branches and is mostly read in editors (where Obsidian, JetBrains, and similar renderers do treat `[-]` as in-progress). The tradeoff buys lossless `in_progress` round-trip across chats.
+
+## Helper invocations
+
+```bash
+# Read: emits TodoWrite-shaped JSON.
+node .claude/scripts/sync-tasks.mjs --read <session.md>
+
+# Write: takes TodoWrite-shaped JSON on stdin, rewrites the section atomically.
+node .claude/scripts/sync-tasks.mjs --write <session.md>
+```
+
+The helper enforces bookends on write — Claude doesn't need to remember to include them, and any misplacement is silently corrected.
+
+## When to flush (write to disk)
+
+**Lifecycle moments — always:**
+- `/start-work` (blank): seed `## Tasks` with bookends + (if linked) tracker reference.
+- `/start-work` (resume): read-only — populate `TodoWrite` from `## Tasks`.
+- `/pause-work`: flush before the auto-commit.
+- `/complete-work`: flush before release-note synthesis.
+- `/handoff`, `/braindump`: include a snapshot of current `TodoWrite` state in the captured artifact.
+
+**Mid-session — after meaningful change:**
+- A new task was added.
+- A task moved to `completed`.
+- A task moved to `in_progress`.
+
+Trivial edits (renaming, reordering) do **not** trigger a flush — they ride on the next lifecycle commit.
+
+## What NOT to do
+
+- Do not edit the `## Tasks` section by hand or with `Edit` — always go through the helper. Manual edits will be overwritten and may miss the bookend invariant.
+- Do not add nested checkboxes — `TodoWrite` is flat, and the round-trip ignores nesting.
+- Do not omit the bookends — the helper auto-inserts them, but explicit is better than implicit.
+- Do not flush every keystroke — that creates pointless file churn. Flush on meaningful change or lifecycle moment.
+- Do not flush from inside a subagent — subagents have ephemeral context; only the main agent maintains the canonical `TodoWrite` state for the session.
+
+## Concurrency model
+
+Multi-chat-on-same-session is rare but possible. Each chat maintains its own `TodoWrite`; flushes write the file and the last writer wins. This matches the existing `## Progress` model. If you notice a divergence, the disk version is authoritative — restart your chat to reseed.

package/template/.claude/rules/token-economics.md.skip

@@ -1,6 +1,6 @@
 # Token Economics
 
-Activate this rule for token-aware behavior — cost-conscious model selection, context efficiency, and waste reduction.
+Activate this rule for token-aware behavior — cost-conscious model selection, context efficiency, command discipline, and waste detection.
 
 ## Model Selection
 
@@ -18,14 +18,29 @@ Activate this rule for token-aware behavior — cost-conscious model selection,
 - If a tool result is large and mostly irrelevant, note what matters and move on
 - Prefer exact file paths over glob searches when you know where things are
 
-## Waste Detection
+## Command Discipline
 
-- Flag when context is heavy with resolved discussions that could be compacted
-- Suggest /braindump to offload discussion into files, freeing context for work
-- Note when subagent context is bloated relative to the task size
-- If locked context exceeds the 10KB target, mention it
+The single biggest source of session bloat is bash output you didn't bound. The model has to read every line that comes back, and there's no after-the-fact way to truncate it.
+
+- Don't run unbounded commands. Pipe to `head`, `tail`, or `grep` first.
+- For test runs, prefer scoped invocations: `npm test path/to/file.test.mjs` over bare `npm test`. If you only need failures, pipe through `grep -E "FAIL|✗|Error"`.
+- For `find` and `grep -r` / `rg -r`, always supply a constraint (`-name`, `-path`, `--include`, `-g`). Bare `find ~/` against home is almost never what you want.
+- For inspecting a large file, write to a tmp file and grep into it rather than `cat`ing the whole thing into context.
+- For long-running processes (servers, watchers), use `run_in_background: true` and stream with the Monitor tool — don't let stdout pile up in a single tool result.
+- Do not claim a task is done before running its tests. The cost of a forgotten test run is a follow-up cycle that bloats the session more than the test would have.
+
+## Ghost-Token Detection
+
+"Ghost tokens" are context spend you can't see in any single tool result — structural bloat that accumulates across the session. Watch for:
+
+- **Unused skills.** A loaded skill that you never invoke costs input tokens every turn. If a workspace ships skills you don't use in the current task, that's silent overhead.
+- **Oversized locked context.** `shared-context/locked/` is injected into every session and every subagent. If it grows past 5% of the active model's context window, flag it (yellow); past 15%, treat as red. Absolute byte count is a weak proxy — duplicated coverage and stale references matter more.
+- **Unused MCP servers.** Each MCP server's tool list is in your prompt whether you call it or not. If a server is registered but never used in this workspace's flow, surface it for cleanup.
+- **Resolved discussions still in context.** If the conversation has worked through a long debate that's now settled, that text is still occupying the window. Suggest `/braindump` to offload it into a file.
+- **Subagent context bloat.** A subagent prompt that ships more context than the task requires wastes tokens twice — once for the subagent, once for the dispatching model that wrote the prompt.
 
 ## Compaction Awareness
 
-- When approaching compaction threshold, prioritize capturing over continuing
-- After compaction, avoid re-reading files that were already discussed — check shared-context first
+- When approaching the compaction threshold, prioritize capturing over continuing. A `/braindump` or `/handoff` *before* compaction preserves reasoning that gets summarized away.
+- After compaction, avoid re-reading files that were already discussed — check `shared-context/` and the session tracker first.
+- The `PreCompact` hook will prompt for capture; treat that prompt as a real checkpoint, not a dismissable nag.

package/template/.claude/scripts/sync-tasks.mjs

@@ -0,0 +1,234 @@
+// Mirror TodoWrite ↔ session.md ## Tasks section.
+// Round-trips a flat task list across chats by persisting it on the session branch.
+
+import { readFileSync, writeFileSync, renameSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { readSessionFile } from '../lib/session-frontmatter.mjs';
+import { createTracker } from './trackers/interface.mjs';
+
+const IRREGULARS = {
+  // Pre-built map for verbs whose gerund isn't a clean suffix transform.
+  // Add entries as needed; the rule of thumb is "if the test catches it, fix here".
+};
+
+export function toActiveForm(content) {
+  const trimmed = content.trim();
+  const firstSpace = trimmed.indexOf(' ');
+  const verb = firstSpace === -1 ? trimmed : trimmed.slice(0, firstSpace);
+  const rest = firstSpace === -1 ? '' : trimmed.slice(firstSpace);
+
+  const lower = verb.toLowerCase();
+  if (IRREGULARS[lower]) return IRREGULARS[lower] + rest;
+
+  let gerund;
+  if (verb.endsWith('e') && !verb.endsWith('ee')) {
+    gerund = verb.slice(0, -1) + 'ing';
+  } else if (
+    verb.length >= 3 &&
+    /[aeiou]/.test(verb[verb.length - 2]) &&
+    !/[aeiouwxy]/.test(verb[verb.length - 1])
+  ) {
+    // CVC pattern → double the final consonant (Run → Running)
+    // Skip when ending in w/x/y (Show → Showing, Fix → Fixing).
+    gerund = verb + verb[verb.length - 1] + 'ing';
+  } else {
+    gerund = verb + 'ing';
+  }
+
+  return gerund + rest;
+}
+
+const TASKS_HEADING = '## Tasks';
+const LINK_PREFIX = '> Linked:';
+
+export function parseTasksSection(sessionMdContent) {
+  const lines = sessionMdContent.split('\n');
+  const startIdx = lines.findIndex(l => l.trim() === TASKS_HEADING);
+  if (startIdx === -1) return { linked: null, todos: [] };
+
+  // Section runs until the next "## " heading or EOF.
+  let endIdx = lines.length;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    if (lines[i].startsWith('## ')) { endIdx = i; break; }
+  }
+
+  const sectionLines = lines.slice(startIdx + 1, endIdx);
+  let linked = null;
+  const todos = [];
+
+  for (const line of sectionLines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    if (trimmed.startsWith(LINK_PREFIX)) {
+      const rest = trimmed.slice(LINK_PREFIX.length).trim();
+      const dashIdx = rest.indexOf(' — ');
+      if (dashIdx === -1) {
+        linked = { id: rest, title: null };
+      } else {
+        linked = { id: rest.slice(0, dashIdx).trim(), title: rest.slice(dashIdx + 3).trim() };
+      }
+      continue;
+    }
+
+    const checkboxMatch = trimmed.match(/^- \[([ x\-])\] (.+)$/);
+    if (checkboxMatch) {
+      const marker = checkboxMatch[1];
+      const status = marker === 'x' ? 'completed' : marker === '-' ? 'in_progress' : 'pending';
+      const content = checkboxMatch[2].trim();
+      todos.push({ content, activeForm: toActiveForm(content), status });
+    }
+  }
+
+  return { linked, todos };
+}
+
+const START_BOOKEND = { content: 'Start work', activeForm: 'Starting work', status: 'completed' };
+const END_BOOKEND   = { content: 'Complete work', activeForm: 'Completing work', status: 'pending' };
+
+export function enforceBookends(todos) {
+  const middle = [];
+  let foundStart = null;
+  let foundEnd = null;
+  for (const t of todos) {
+    if (t.content === 'Start work') foundStart = t;
+    else if (t.content === 'Complete work') foundEnd = t;
+    else middle.push(t);
+  }
+  return [
+    foundStart || { ...START_BOOKEND },
+    ...middle,
+    foundEnd || { ...END_BOOKEND },
+  ];
+}
+
+export function renderTasksSection({ linked, todos }) {
+  const safe = enforceBookends(todos);
+  const lines = ['## Tasks', ''];
+  if (linked) {
+    if (linked.title) {
+      lines.push(`> Linked: ${linked.id} — ${linked.title}`);
+    } else {
+      lines.push(`> Linked: ${linked.id}`);
+    }
+    lines.push('');
+  }
+  for (const t of safe) {
+    const box = t.status === 'completed' ? '[x]' : t.status === 'in_progress' ? '[-]' : '[ ]';
+    lines.push(`- ${box} ${t.content}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+export function writeTasksToSession(filePath, taskState) {
+  const original = readFileSync(filePath, 'utf-8');
+  const newSection = renderTasksSection(taskState);
+  const updated = spliceTasksSection(original, newSection);
+
+  // Atomic write: temp file in same dir + rename.
+  const tmp = filePath + '.tmp-sync-tasks';
+  writeFileSync(tmp, updated);
+  renameSync(tmp, filePath);
+}
+
+function spliceTasksSection(content, newSection) {
+  const lines = content.split('\n');
+  const startIdx = lines.findIndex(l => l.trim() === '## Tasks');
+
+  if (startIdx === -1) {
+    // Insert before ## Progress if present, else append before EOF.
+    const progressIdx = lines.findIndex(l => l.trim() === '## Progress');
+    if (progressIdx !== -1) {
+      const before = lines.slice(0, progressIdx).join('\n').replace(/\n+$/, '\n');
+      const after = lines.slice(progressIdx).join('\n');
+      return before + '\n' + newSection + '\n' + after;
+    }
+    // No Progress section — append at end.
+    return content.replace(/\n*$/, '\n\n') + newSection;
+  }
+
+  // Find end of existing ## Tasks section (next ## heading or EOF).
+  let endIdx = lines.length;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    if (lines[i].startsWith('## ')) { endIdx = i; break; }
+  }
+
+  const before = lines.slice(0, startIdx).join('\n');
+  const after = endIdx < lines.length ? lines.slice(endIdx).join('\n') : '';
+  const beforeTrimmed = before.replace(/\n+$/, '\n');
+  return beforeTrimmed + '\n' + newSection + (after ? '\n' + after : '');
+}
+
+export async function resolveLinked(filePath, { tracker } = {}) {
+  const { fields } = readSessionFile(filePath);
+  if (!fields.workItem) return null;
+  const id = fields.workItem;
+  if (!tracker) return { id, title: null };
+  try {
+    const issue = await tracker.getIssue(id);
+    return { id, title: issue?.title || null };
+  } catch {
+    return { id, title: null };
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const mode = args[0];
+  const filePath = args[1];
+
+  if (!mode || !filePath || (mode !== '--read' && mode !== '--write')) {
+    console.error('Usage: sync-tasks.mjs --read|--write <session.md>');
+    process.exit(2);
+  }
+
+  let fields;
+  try {
+    fields = readSessionFile(filePath).fields;
+  } catch (e) {
+    console.error(`Not a session file: ${e.message}`);
+    process.exit(2);
+  }
+  if (fields.type !== 'session-tracker') {
+    console.error(`Not a session-tracker file (type=${fields.type})`);
+    process.exit(2);
+  }
+
+  let tracker = null;
+  try {
+    const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
+    if (ws.workspace?.tracker) tracker = createTracker(ws.workspace.tracker);
+  } catch {
+    // No workspace.json or no tracker configured — skip.
+  }
+
+  if (mode === '--read') {
+    const content = readFileSync(filePath, 'utf-8');
+    const parsed = parseTasksSection(content);
+    if (!parsed.linked) {
+      parsed.linked = await resolveLinked(filePath, { tracker });
+    }
+    process.stdout.write(JSON.stringify(parsed, null, 2) + '\n');
+    return;
+  }
+
+  const stdin = await readStdin();
+  const input = JSON.parse(stdin);
+  const linked = input.linked ?? await resolveLinked(filePath, { tracker });
+  writeTasksToSession(filePath, { linked, todos: input.todos || [] });
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', chunk => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch(e => { console.error(e); process.exit(1); });
+}