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

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

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+// Unit tests for sync-tasks.mjs
+// Run: node template/.claude/scripts/sync-tasks.test.mjs
+import { toActiveForm } from './sync-tasks.mjs';
+
+let failed = 0;
+let passed = 0;
+
+function assert(cond, msg) {
+  if (cond) { passed++; } else { failed++; console.error(`  FAIL: ${msg}`); }
+}
+
+function assertEq(actual, expected, msg) {
+  const a = JSON.stringify(actual);
+  const e = JSON.stringify(expected);
+  if (a === e) { passed++; } else {
+    failed++;
+    console.error(`  FAIL: ${msg}\n    expected: ${e}\n    actual:   ${a}`);
+  }
+}
+
+console.log('# toActiveForm');
+assertEq(toActiveForm('Start work'),                    'Starting work',                  'simple verb');
+assertEq(toActiveForm('Write fix and test'),            'Writing fix and test',           'e-drop');
+assertEq(toActiveForm('Run the tests'),                 'Running the tests',              'double consonant');
+assertEq(toActiveForm('Identify race condition'),       'Identifying race condition',     'y-keep');
+assertEq(toActiveForm('Complete work'),                 'Completing work',                'e-drop on Complete');
+assertEq(toActiveForm('Reproduce on iOS Safari'),       'Reproducing on iOS Safari',      'e-drop multi-word');
+assertEq(toActiveForm('Fix bug'),                       'Fixing bug',                     'simple');
+
+import { parseTasksSection } from './sync-tasks.mjs';
+
+const SAMPLE_WITH_TASKS = `---
+type: session-tracker
+name: demo
+---
+
+# Work Session
+
+## Tasks
+
+> Linked: gh:42 — Auth timeout on mobile
+
+- [x] Start work
+- [x] Reproduce on iOS Safari
+- [ ] Identify race condition
+- [ ] Complete work
+
+## Progress
+
+(stuff)
+`;
+
+const SAMPLE_NO_TASKS = `---
+type: session-tracker
+name: demo
+---
+
+# Work Session
+
+## Progress
+
+(stuff)
+`;
+
+const SAMPLE_NO_LINK = `---
+type: session-tracker
+name: demo
+---
+
+## Tasks
+
+- [x] Start work
+- [ ] Complete work
+`;
+
+console.log('\n# parseTasksSection');
+assertEq(
+  parseTasksSection(SAMPLE_WITH_TASKS).linked,
+  { id: 'gh:42', title: 'Auth timeout on mobile' },
+  'parses linked blockquote'
+);
+assertEq(
+  parseTasksSection(SAMPLE_WITH_TASKS).todos.length,
+  4,
+  'parses 4 todos'
+);
+assertEq(
+  parseTasksSection(SAMPLE_WITH_TASKS).todos[0],
+  { content: 'Start work', activeForm: 'Starting work', status: 'completed' },
+  'first todo completed'
+);
+assertEq(
+  parseTasksSection(SAMPLE_WITH_TASKS).todos[2],
+  { content: 'Identify race condition', activeForm: 'Identifying race condition', status: 'pending' },
+  'pending todo'
+);
+assertEq(
+  parseTasksSection(SAMPLE_NO_TASKS),
+  { linked: null, todos: [] },
+  'missing section returns empty'
+);
+assertEq(
+  parseTasksSection(SAMPLE_NO_LINK).linked,
+  null,
+  'no blockquote → linked: null'
+);
+assertEq(
+  parseTasksSection(SAMPLE_NO_LINK).todos.length,
+  2,
+  'no blockquote → still parses todos'
+);
+
+import { renderTasksSection, enforceBookends } from './sync-tasks.mjs';
+
+console.log('\n# enforceBookends');
+assertEq(
+  enforceBookends([]).map(t => t.content),
+  ['Start work', 'Complete work'],
+  'empty list → bookends inserted'
+);
+assertEq(
+  enforceBookends([
+    { content: 'Do thing', activeForm: 'Doing thing', status: 'pending' },
+  ]).map(t => t.content),
+  ['Start work', 'Do thing', 'Complete work'],
+  'middle task gets wrapped in bookends'
+);
+assertEq(
+  enforceBookends([
+    { content: 'Complete work', activeForm: 'Completing work', status: 'pending' },
+    { content: 'Do thing', activeForm: 'Doing thing', status: 'pending' },
+    { content: 'Start work', activeForm: 'Starting work', status: 'completed' },
+  ]).map(t => t.content),
+  ['Start work', 'Do thing', 'Complete work'],
+  'misplaced bookends moved to ends'
+);
+assertEq(
+  enforceBookends([{ content: 'Start work', activeForm: 'Starting work', status: 'completed' }])[0].status,
+  'completed',
+  'preserves Start work status when present'
+);
+assertEq(
+  enforceBookends([])[0].status,
+  'completed',
+  'inserted Start work defaults to completed'
+);
+assertEq(
+  enforceBookends([])[1].status,
+  'pending',
+  'inserted Complete work defaults to pending'
+);
+
+console.log('\n# renderTasksSection');
+assertEq(
+  renderTasksSection({
+    linked: null,
+    todos: [
+      { content: 'Start work', activeForm: 'Starting work', status: 'completed' },
+      { content: 'Do thing', activeForm: 'Doing thing', status: 'pending' },
+      { content: 'Complete work', activeForm: 'Completing work', status: 'pending' },
+    ],
+  }),
+  '## Tasks\n\n- [x] Start work\n- [ ] Do thing\n- [ ] Complete work\n',
+  'no link → no blockquote'
+);
+assertEq(
+  renderTasksSection({
+    linked: { id: 'gh:42', title: 'Auth timeout on mobile' },
+    todos: [
+      { content: 'Start work', activeForm: 'Starting work', status: 'completed' },
+      { content: 'Complete work', activeForm: 'Completing work', status: 'pending' },
+    ],
+  }),
+  '## Tasks\n\n> Linked: gh:42 — Auth timeout on mobile\n\n- [x] Start work\n- [ ] Complete work\n',
+  'with link → blockquote rendered'
+);
+assertEq(
+  renderTasksSection({
+    linked: { id: 'gh:42', title: null },
+    todos: [
+      { content: 'Start work', activeForm: 'Starting work', status: 'completed' },
+      { content: 'Complete work', activeForm: 'Completing work', status: 'pending' },
+    ],
+  }),
+  '## Tasks\n\n> Linked: gh:42\n\n- [x] Start work\n- [ ] Complete work\n',
+  'link with null title → bare ID'
+);
+
+import { writeTasksToSession } from './sync-tasks.mjs';
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+console.log('\n# writeTasksToSession');
+
+function withTempSession(initialContent, fn) {
+  const dir = mkdtempSync(join(tmpdir(), 'sync-tasks-'));
+  const file = join(dir, 'session.md');
+  writeFileSync(file, initialContent);
+  try { fn(file); } finally { rmSync(dir, { recursive: true, force: true }); }
+}
+
+const FRESH_SESSION = `---
+type: session-tracker
+name: demo
+workItem: gh:42
+---
+
+
+# Work Session: demo
+
+description here.
+
+## Progress
+
+(Updated as the session progresses)
+`;
+
+withTempSession(FRESH_SESSION, (file) => {
+  writeTasksToSession(file, {
+    linked: { id: 'gh:42', title: 'Auth timeout on mobile' },
+    todos: [],
+  });
+  const after = readFileSync(file, 'utf-8');
+  assert(after.includes('## Tasks'), 'inserts ## Tasks section');
+  assert(after.includes('> Linked: gh:42 — Auth timeout on mobile'), 'inserts blockquote');
+  assert(after.includes('- [x] Start work'), 'inserts Start work bookend');
+  assert(after.includes('- [ ] Complete work'), 'inserts Complete work bookend');
+  assert(after.includes('## Progress'), 'preserves Progress heading');
+  assert(after.includes('(Updated as the session progresses)'), 'preserves Progress body');
+  assert(after.startsWith('---\ntype: session-tracker'), 'preserves frontmatter');
+});
+
+const SESSION_WITH_TASKS = `---
+type: session-tracker
+name: demo
+---
+
+
+# Work Session: demo
+
+## Tasks
+
+- [x] Start work
+- [ ] Old task
+- [ ] Complete work
+
+## Progress
+
+original progress text
+`;
+
+withTempSession(SESSION_WITH_TASKS, (file) => {
+  writeTasksToSession(file, {
+    linked: null,
+    todos: [
+      { content: 'Start work', activeForm: 'Starting work', status: 'completed' },
+      { content: 'New task', activeForm: 'Doing new task', status: 'in_progress' },
+      { content: 'Complete work', activeForm: 'Completing work', status: 'pending' },
+    ],
+  });
+  const after = readFileSync(file, 'utf-8');
+  assert(after.includes('- [-] New task'), 'replaced with new task (in_progress → [-])');
+  assert(!after.includes('- [ ] Old task'), 'old task removed');
+  assert(after.includes('original progress text'), 'preserves Progress body');
+  const taskHeadingCount = (after.match(/^## Tasks$/gm) || []).length;
+  assertEq(taskHeadingCount, 1, 'exactly one ## Tasks section after rewrite');
+});
+
+withTempSession(FRESH_SESSION, (file) => {
+  const input = {
+    linked: { id: 'gh:42', title: 'Auth timeout on mobile' },
+    todos: [
+      { content: 'Reproduce', activeForm: 'Reproducing', status: 'completed' },
+      { content: 'Fix it', activeForm: 'Fixing it', status: 'pending' },
+    ],
+  };
+  writeTasksToSession(file, input);
+  const round = parseTasksSection(readFileSync(file, 'utf-8'));
+  assertEq(round.linked, input.linked, 'round-trip linked');
+  assertEq(round.todos.length, 4, 'round-trip todos length (with bookends)');
+  assertEq(round.todos[1].content, 'Reproduce', 'round-trip middle task content');
+  assertEq(round.todos[2].status, 'pending', 'round-trip middle task status');
+});
+
+console.log('\n# in_progress round-trip');
+
+withTempSession(FRESH_SESSION, (file) => {
+  const input = {
+    linked: null,
+    todos: [
+      { content: 'Doing thing', activeForm: 'Doing thing', status: 'in_progress' },
+    ],
+  };
+  writeTasksToSession(file, input);
+  const after = readFileSync(file, 'utf-8');
+  assert(after.includes('- [-] Doing thing'), 'in_progress renders as [-]');
+  const round = parseTasksSection(after);
+  const middle = round.todos.find(t => t.content === 'Doing thing');
+  assertEq(middle.status, 'in_progress', 'in_progress round-trips losslessly');
+});
+
+import { execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const SCRIPT_PATH = join(dirname(fileURLToPath(import.meta.url)), 'sync-tasks.mjs');
+
+console.log('\n# CLI');
+
+withTempSession(FRESH_SESSION, (file) => {
+  const input = JSON.stringify({
+    todos: [
+      { content: 'Start work', activeForm: 'Starting work', status: 'completed' },
+      { content: 'Test thing', activeForm: 'Testing thing', status: 'in_progress' },
+      { content: 'Complete work', activeForm: 'Completing work', status: 'pending' },
+    ],
+  });
+  execFileSync('node', [SCRIPT_PATH, '--write', file], {
+    input,
+    encoding: 'utf-8',
+  });
+  const written = readFileSync(file, 'utf-8');
+  assert(written.includes('- [-] Test thing'), 'CLI --write rendered task (in_progress → [-])');
+
+  const out = execFileSync('node', [SCRIPT_PATH, '--read', file], {
+    encoding: 'utf-8',
+  });
+  const parsed = JSON.parse(out);
+  assertEq(parsed.todos.length, 3, 'CLI --read returns 3 todos');
+  assertEq(parsed.todos[1].content, 'Test thing', 'CLI --read content');
+});
+
+withTempSession('not a session file\n', (file) => {
+  let threw = false;
+  try {
+    execFileSync('node', [SCRIPT_PATH, '--read', file], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch (e) {
+    threw = true;
+    assert(e.stderr.includes('Not a session') || e.stderr.includes('frontmatter'), 'errors on non-session file');
+  }
+  assert(threw, 'CLI throws on non-session file');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/template/.claude/settings.json

@@ -6,15 +6,21 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/workspace-update-check.mjs",
+            "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/workspace-update-check.mjs",
             "timeout": 5000,
             "statusMessage": "Checking for workspace updates..."
           },
           {
             "type": "command",
-            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/session-start.mjs",
+            "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/session-start.mjs",
             "timeout": 30000,
             "statusMessage": "Syncing workspace..."
+          },
+          {
+            "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/version-freshness-check.mjs",
+            "timeout": 5000,
+            "statusMessage": "Checking template freshness..."
           }
         ]
       }
@@ -24,7 +30,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/subagent-start.mjs",
+            "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/subagent-start.mjs",
             "timeout": 5000,
             "statusMessage": "Loading shared context..."
           }
@@ -36,7 +42,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/pre-compact.mjs",
+            "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/pre-compact.mjs",
             "timeout": 5000,
             "statusMessage": "Checking for uncaptured context..."
           }
@@ -48,7 +54,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/post-compact.mjs",
+            "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/post-compact.mjs",
             "timeout": 5000
           }
         ]
@@ -59,12 +65,17 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/workspace-update-check.mjs",
+            "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/workspace-update-check.mjs",
+            "timeout": 5000
+          },
+          {
+            "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/repo-write-detection.mjs",
             "timeout": 5000
           },
           {
             "type": "command",
-            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/repo-write-detection.mjs",
+            "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/bash-output-advisory.mjs",
             "timeout": 5000
           }
         ]
@@ -75,7 +86,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/session-end.mjs",
+            "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/session-end.mjs",
             "timeout": 15000,
             "statusMessage": "Saving session state..."
           }
@@ -87,7 +98,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/worktree-create.mjs",
+            "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..."
           }

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

@@ -72,6 +72,21 @@ updated: {YYYY-MM-DD}
 3. If multiple topics: "I see discussion about {topic-1} and {topic-2}. Split into separate braindumps?"
 4. Proceed with named flow for each
 
+## Include task snapshot
+
+If an active session exists (detected via `.claude/.active-session.json`), include a `## Tasks at capture time` section in the braindump artifact with a snapshot of the current `TodoWrite` state:
+
+```markdown
+## Tasks at capture time
+
+- [x] Start work
+- [x] Reproduce on iOS Safari
+- [ ] Identify race condition
+- [ ] Complete work
+```
+
+Use the same GFM checkbox format as `session.md`'s `## Tasks` section (just `content` and `status` per task — no `activeForm` field, no blockquote line) and render it inline in the braindump. Do NOT call `sync-tasks.mjs --write` — braindumps are snapshots, not the canonical store.
+
 ## Updating Existing Braindumps
 
 When updating, rewrite as a fresh snapshot (coherent-revisions rule). The updated braindump should read as if written in one pass.

package/template/.claude/skills/build-docs-site/SKILL.md

@@ -298,7 +298,7 @@ Reuse aggressively — if the same concept appears in multiple chapters, import
 
 - **CSS variables in SVG fill don't paint reliably** — always use `className={cls.fill.X}`, never `fill={...}`. The primitives already do this.
 - **Bulk migration regressions** — if you wrote chapter components with `fill={colors.X}` and need to migrate, run `python3 .claude/skills/build-docs-site/scripts/bulk-fill-migration.py {chapters-dir}`. The script handles duplicate `className=`, missing imports, and reports variable-bound fills for manual review.
-- **Playwright viewport screenshots lie** — if a screenshot is blank, use DOM inspection via `browser_evaluate` before assuming the diagram is broken.
+- **Automated viewport screenshots can lie** — if a screenshot from the browser automation tool comes back blank, inspect the DOM via the tool's evaluate hook before assuming the diagram is broken.
 - **Arrowhead markers don't theme-switch** — acceptable cosmetic mismatch, or render two markers with media query switching.
 - **SSR for browser-only diagrams** — wrap any diagram that uses browser APIs in `<BrowserOnly>` with a function child. The primitives don't need this; it only matters if a chapter component uses `window` or `document`.
 

package/template/.claude/skills/build-docs-site/checklists/pitfalls.md

@@ -121,15 +121,15 @@ If the build fails on `cls is not defined`, manually add `cls` to the import lin
 
 ---
 
-## 3. Playwright viewport screenshot quirks
+## 3. Automated viewport screenshots can lie
 
 ### Symptom
 
-Playwright viewport-cropped screenshots of diagram regions come back blank, even though the diagrams render correctly when you visit the page in a real browser.
+Viewport-cropped screenshots of diagram regions come back blank from the browser automation tool, even though the diagrams render correctly when you load the page in a real browser.
 
 ### Cause
 
-Best guess: scroll position and viewport sizing interact in Playwright's screenshot path such that the diagram region falls outside the captured viewport even when the visible browser shows it. Never fully diagnosed — the workaround is sufficient.
+Scroll position and viewport sizing interact with the automated screenshot path such that the diagram region falls outside the captured frame even when the visible browser shows it. The exact interaction varies by tool and rarely rewards deep diagnosis — the workaround below is always sufficient.
 
 ### Fix
 
@@ -140,7 +140,7 @@ Best guess: scroll position and viewport sizing interact in Playwright's screens
    await page.screenshot({ fullPage: true });
    ```
 
-2. **DOM inspection via `browser_evaluate`** (fastest, most authoritative):
+2. **DOM inspection via the automation tool's evaluate hook** (fastest, most authoritative):
    ```js
    const rect = document.querySelector('.dx-fill-primary');
    console.log({