ultra-builder-pro-cli 0.5.0

package/mcp-server/tests/staleness.test.cjs

@@ -0,0 +1,190 @@
+'use strict';
+
+// Phase 5.3 — Task staleness consumer:
+//   • markTasksStaleBySpecSections: UPDATE pending tasks whose trace_to
+//     matches a changed spec section → stale=1 + task_stale_marked event.
+//   • consumeSpecChangedEvents: pulls unprocessed spec_changed events from
+//     the event stream and applies the rule above, advancing a cursor.
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { initStateDb, closeStateDb } = require('../lib/state-db.cjs');
+const ops = require('../lib/state-ops.cjs');
+const projector = require('../lib/projector.cjs');
+
+function freshDb() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-stale-'));
+  const file = path.join(dir, 'state.db');
+  const init = initStateDb(file);
+  return { dir, db: init.db };
+}
+
+function teardown(dir, db) {
+  try { closeStateDb(db); } catch (_) { /* ignore */ }
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_) { /* ignore */ }
+}
+
+function seed(db, id, { trace_to, status = 'pending' } = {}) {
+  ops.createTask(db, { id, title: `task ${id}`, type: 'feature', priority: 'P2', trace_to });
+  if (status !== 'pending') ops.patchTask(db, id, { status });
+}
+
+test('markTasksStaleBySpecSections: marks pending tasks with matching trace_to', () => {
+  const { dir, db } = freshDb();
+  try {
+    seed(db, 't-prod', { trace_to: 'product' });
+    seed(db, 't-arch', { trace_to: 'arch' });
+    seed(db, 't-exec', { trace_to: 'exec' });
+
+    const result = ops.markTasksStaleBySpecSections(db, ['product']);
+    assert.equal(result.marked_count, 1);
+    assert.deepEqual(result.marked_ids, ['t-prod']);
+
+    assert.equal(ops.readTask(db, 't-prod').stale, true);
+    assert.equal(ops.readTask(db, 't-arch').stale, false);
+    assert.equal(ops.readTask(db, 't-exec').stale, false);
+  } finally { teardown(dir, db); }
+});
+
+test('markTasksStaleBySpecSections: multi-section update', () => {
+  const { dir, db } = freshDb();
+  try {
+    seed(db, 't-a', { trace_to: 'product' });
+    seed(db, 't-b', { trace_to: 'arch' });
+    seed(db, 't-c', { trace_to: 'exec' });
+
+    const result = ops.markTasksStaleBySpecSections(db, ['product', 'arch']);
+    assert.equal(result.marked_count, 2);
+    assert.ok(result.marked_ids.includes('t-a'));
+    assert.ok(result.marked_ids.includes('t-b'));
+    assert.equal(ops.readTask(db, 't-c').stale, false);
+  } finally { teardown(dir, db); }
+});
+
+test('markTasksStaleBySpecSections: skips non-pending tasks', () => {
+  const { dir, db } = freshDb();
+  try {
+    seed(db, 't-running', { trace_to: 'product' });
+    ops.patchTask(db, 't-running', { status: 'in_progress' });
+
+    seed(db, 't-done', { trace_to: 'product' });
+    ops.patchTask(db, 't-done', { status: 'in_progress' });
+    ops.patchTask(db, 't-done', { status: 'completed' });
+
+    seed(db, 't-pending', { trace_to: 'product' });
+
+    const result = ops.markTasksStaleBySpecSections(db, ['product']);
+    assert.equal(result.marked_count, 1);
+    assert.deepEqual(result.marked_ids, ['t-pending']);
+  } finally { teardown(dir, db); }
+});
+
+test('markTasksStaleBySpecSections: emits task_stale_marked event per task', () => {
+  const { dir, db } = freshDb();
+  try {
+    seed(db, 't-e1', { trace_to: 'product' });
+    seed(db, 't-e2', { trace_to: 'product' });
+
+    const { events: before } = ops.subscribeEventsSince(db, { since_id: 0, limit: 500 });
+    ops.markTasksStaleBySpecSections(db, ['product']);
+    const { events: after } = ops.subscribeEventsSince(db, { since_id: 0, limit: 500 });
+
+    const marked = after.slice(before.length).filter((e) => e.type === 'task_stale_marked');
+    assert.equal(marked.length, 2);
+    const taskIds = marked.map((e) => e.task_id).sort();
+    assert.deepEqual(taskIds, ['t-e1', 't-e2']);
+  } finally { teardown(dir, db); }
+});
+
+test('markTasksStaleBySpecSections: idempotent — re-mark already-stale task does not double-emit', () => {
+  const { dir, db } = freshDb();
+  try {
+    seed(db, 't-idem', { trace_to: 'product' });
+    ops.markTasksStaleBySpecSections(db, ['product']);
+
+    const { events: before } = ops.subscribeEventsSince(db, { since_id: 0, limit: 500 });
+    ops.markTasksStaleBySpecSections(db, ['product']);
+    const { events: after } = ops.subscribeEventsSince(db, { since_id: 0, limit: 500 });
+
+    const newEvents = after.slice(before.length);
+    const marked = newEvents.filter((e) => e.type === 'task_stale_marked');
+    assert.equal(marked.length, 0, 'should not re-emit for already-stale task');
+  } finally { teardown(dir, db); }
+});
+
+test('consumeSpecChangedEvents: processes queued events and advances cursor', () => {
+  const { dir, db } = freshDb();
+  try {
+    seed(db, 't-c1', { trace_to: 'product' });
+    seed(db, 't-c2', { trace_to: 'arch' });
+
+    ops.appendEvent(db, { type: 'spec_changed', payload: { sections: ['product'] } });
+    ops.appendEvent(db, { type: 'spec_changed', payload: { sections: ['arch'] } });
+
+    const result = ops.consumeSpecChangedEvents(db, { since_id: 0 });
+    assert.equal(result.processed, 2);
+    assert.ok(result.next_since_id > 0);
+    assert.equal(ops.readTask(db, 't-c1').stale, true);
+    assert.equal(ops.readTask(db, 't-c2').stale, true);
+  } finally { teardown(dir, db); }
+});
+
+test('consumeSpecChangedEvents: cursor prevents reprocessing', () => {
+  const { dir, db } = freshDb();
+  try {
+    seed(db, 't-cur', { trace_to: 'product' });
+    ops.appendEvent(db, { type: 'spec_changed', payload: { sections: ['product'] } });
+
+    const first = ops.consumeSpecChangedEvents(db, { since_id: 0 });
+    assert.equal(first.processed, 1);
+
+    // second call from the new cursor — no new spec_changed events.
+    const second = ops.consumeSpecChangedEvents(db, { since_id: first.next_since_id });
+    assert.equal(second.processed, 0);
+    assert.equal(second.next_since_id, first.next_since_id);
+  } finally { teardown(dir, db); }
+});
+
+test('consumeSpecChangedEvents: ignores non-spec_changed events', () => {
+  const { dir, db } = freshDb();
+  try {
+    seed(db, 't-other', { trace_to: 'product' });
+    ops.appendEvent(db, { type: 'task_failure', task_id: 't-other', payload: { reason: 'noise' } });
+
+    const result = ops.consumeSpecChangedEvents(db, { since_id: 0 });
+    assert.equal(result.processed, 0);
+    assert.equal(ops.readTask(db, 't-other').stale, false);
+  } finally { teardown(dir, db); }
+});
+
+test('projector: stale task context md carries STALE banner before body', () => {
+  const { dir, db } = freshDb();
+  const rootDir = dir;
+  try {
+    seed(db, 't-proj', { trace_to: 'product' });
+    ops.markTasksStaleBySpecSections(db, ['product']);
+
+    const result = projector.projectContext(db, 't-proj', {}, { rootDir });
+    const text = fs.readFileSync(result.path, 'utf8');
+    // Banner goes after YAML frontmatter end + blank line.
+    const frontmatterEnd = text.indexOf('\n---', 3);
+    assert.ok(frontmatterEnd > 0, 'frontmatter should exist');
+    const body = text.slice(frontmatterEnd + 4);
+    assert.match(body, /⚠️\s*STALE/, 'stale banner should render');
+    assert.match(body, /spec/i, 'banner should mention spec');
+  } finally { teardown(dir, db); }
+});
+
+test('projector: non-stale task context md has no STALE banner', () => {
+  const { dir, db } = freshDb();
+  try {
+    seed(db, 't-fresh', { trace_to: 'product' });
+    const result = projector.projectContext(db, 't-fresh', {}, { rootDir: dir });
+    const text = fs.readFileSync(result.path, 'utf8');
+    assert.doesNotMatch(text, /STALE/);
+  } finally { teardown(dir, db); }
+});

package/mcp-server/tests/state-ops.test.cjs

@@ -0,0 +1,286 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { initStateDb, closeStateDb } = require('../lib/state-db.cjs');
+const ops = require('../lib/state-ops.cjs');
+
+function tmpDb() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-ops-'));
+  return { dir, file: path.join(dir, 'state.db') };
+}
+
+function freshDb() {
+  const t = tmpDb();
+  const init = initStateDb(t.file);
+  return { ...t, db: init.db };
+}
+
+test('createTask inserts a row, defaults status=pending, emits task_created', () => {
+  const { dir, db } = freshDb();
+  try {
+    const out = ops.createTask(db, {
+      id: 'task-001', title: 'first task', type: 'feature', priority: 'P1',
+    });
+    assert.equal(out.id, 'task-001');
+    assert.equal(out.status, 'pending');
+    const events = db.prepare('SELECT type, task_id FROM events').all();
+    assert.equal(events.length, 1);
+    assert.equal(events[0].type, 'task_created');
+    assert.equal(events[0].task_id, 'task-001');
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('createTask rejects duplicates with DUPLICATE_TASK_ID', () => {
+  const { dir, db } = freshDb();
+  try {
+    ops.createTask(db, { id: 'dup', title: 'one', type: 'feature', priority: 'P0' });
+    assert.throws(
+      () => ops.createTask(db, { id: 'dup', title: 'two', type: 'feature', priority: 'P0' }),
+      (e) => e.code === 'DUPLICATE_TASK_ID',
+    );
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('updateTaskStatus enforces the legal transition graph', () => {
+  const { dir, db } = freshDb();
+  try {
+    ops.createTask(db, { id: 't', title: 'x', type: 'feature', priority: 'P0' });
+
+    // pending → in_progress allowed
+    const t1 = ops.updateTaskStatus(db, 't', 'in_progress');
+    assert.equal(t1.status, 'in_progress');
+
+    // in_progress → completed allowed
+    const t2 = ops.updateTaskStatus(db, 't', 'completed');
+    assert.equal(t2.status, 'completed');
+
+    // completed → pending forbidden
+    assert.throws(
+      () => ops.updateTaskStatus(db, 't', 'pending'),
+      (e) => e.code === 'ILLEGAL_STATUS_TRANSITION',
+    );
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('patchTask updates JSON arrays + flags + status atomically', () => {
+  const { dir, db } = freshDb();
+  try {
+    ops.createTask(db, { id: 'p1', title: 'patch me', type: 'feature', priority: 'P2' });
+    const out = ops.patchTask(db, 'p1', {
+      files_modified: ['a.ts', 'b.ts'],
+      session_id: 'ses_1',
+      stale: true,
+      status: 'in_progress',
+    });
+    assert.deepEqual(out.files_modified, ['a.ts', 'b.ts']);
+    assert.equal(out.session_id, 'ses_1');
+    assert.equal(out.stale, true);
+    assert.equal(out.status, 'in_progress');
+
+    const types = db.prepare('SELECT type FROM events ORDER BY id').all().map((r) => r.type);
+    assert.deepEqual(types, ['task_created', 'task_started']);
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('patchTask rejects unknown fields', () => {
+  const { dir, db } = freshDb();
+  try {
+    ops.createTask(db, { id: 'r', title: 'r', type: 'feature', priority: 'P1' });
+    assert.throws(
+      () => ops.patchTask(db, 'r', { mystery: 1 }),
+      (e) => e.code === 'VALIDATION_ERROR',
+    );
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('appendEvent + subscribeEventsSince produces monotonic cursor with no gaps', () => {
+  const { dir, db } = freshDb();
+  try {
+    for (let i = 0; i < 10; i++) {
+      ops.appendEvent(db, {
+        type: 'task_created', task_id: `t-${i}`, payload: { i },
+      });
+    }
+    const first = ops.subscribeEventsSince(db, { since_id: 0, limit: 4 });
+    assert.equal(first.events.length, 4);
+    assert.equal(first.events[0].id, 1);
+    assert.equal(first.next_since_id, 4);
+
+    const second = ops.subscribeEventsSince(db, { since_id: first.next_since_id, limit: 100 });
+    assert.equal(second.events.length, 6);
+    assert.equal(second.events[0].id, 5);
+    assert.equal(second.next_since_id, 10);
+
+    const empty = ops.subscribeEventsSince(db, { since_id: second.next_since_id });
+    assert.equal(empty.events.length, 0);
+    assert.equal(empty.next_since_id, second.next_since_id);
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('subscribeEventsSince filters by type', () => {
+  const { dir, db } = freshDb();
+  try {
+    ops.appendEvent(db, { type: 'task_created', task_id: 'a' });
+    ops.appendEvent(db, { type: 'task_started', task_id: 'a' });
+    ops.appendEvent(db, { type: 'task_completed', task_id: 'a' });
+    const r = ops.subscribeEventsSince(db, { since_id: 0, types: ['task_completed'] });
+    assert.equal(r.events.length, 1);
+    assert.equal(r.events[0].type, 'task_completed');
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('createSession requires existing task and emits session_spawned', () => {
+  const { dir, db } = freshDb();
+  try {
+    assert.throws(
+      () => ops.createSession(db, {
+        sid: 's', task_id: 'missing', runtime: 'claude',
+        worktree_path: '/tmp/wt', artifact_dir: '/tmp/art',
+      }),
+      (e) => e.code === 'TASK_NOT_FOUND',
+    );
+
+    ops.createTask(db, { id: 'have', title: 'h', type: 'feature', priority: 'P1' });
+    const ses = ops.createSession(db, {
+      sid: 's1', task_id: 'have', runtime: 'claude',
+      worktree_path: '/tmp/wt', artifact_dir: '/tmp/art', lease_seconds: 60,
+    });
+    assert.equal(ses.sid, 's1');
+    assert.equal(ses.status, 'running');
+    const evt = db.prepare(`SELECT type FROM events WHERE session_id = 's1'`).get();
+    assert.equal(evt.type, 'session_spawned');
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('updateSession status=completed emits session_closed', () => {
+  const { dir, db } = freshDb();
+  try {
+    ops.createTask(db, { id: 'k', title: 'k', type: 'feature', priority: 'P1' });
+    ops.createSession(db, {
+      sid: 'sx', task_id: 'k', runtime: 'codex',
+      worktree_path: '/tmp/wt', artifact_dir: '/tmp/art',
+    });
+    const out = ops.updateSession(db, 'sx', { status: 'completed' });
+    assert.equal(out.status, 'completed');
+    const types = db.prepare(`SELECT type FROM events WHERE session_id = 'sx' ORDER BY id`).all().map((r) => r.type);
+    assert.deepEqual(types, ['session_spawned', 'session_closed']);
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('listActiveSessions returns only running rows for a task', () => {
+  const { dir, db } = freshDb();
+  try {
+    ops.createTask(db, { id: 'm', title: 'm', type: 'feature', priority: 'P1' });
+    ops.createSession(db, { sid: 'a', task_id: 'm', runtime: 'claude', worktree_path: '/tmp/a', artifact_dir: '/tmp/a' });
+    ops.createSession(db, { sid: 'b', task_id: 'm', runtime: 'codex',  worktree_path: '/tmp/b', artifact_dir: '/tmp/b' });
+    ops.updateSession(db, 'a', { status: 'completed' });
+    const active = ops.listActiveSessions(db, { task_id: 'm' });
+    assert.equal(active.length, 1);
+    assert.equal(active[0].sid, 'b');
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('deleteTask refuses when a session is bound unless force=true', () => {
+  const { dir, db } = freshDb();
+  try {
+    ops.createTask(db, { id: 'dl', title: 'd', type: 'feature', priority: 'P1' });
+    ops.patchTask(db, 'dl', { session_id: 'ses_x' });
+    assert.throws(
+      () => ops.deleteTask(db, 'dl'),
+      (e) => e.code === 'SESSION_ACTIVE',
+    );
+    const r = ops.deleteTask(db, 'dl', { force: true });
+    assert.equal(r.ok, true);
+    assert.equal(ops.readTask(db, 'dl'), null);
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('listTasks filters by status / tag', () => {
+  const { dir, db } = freshDb();
+  try {
+    ops.createTask(db, { id: 'a', title: 'a', type: 'feature', priority: 'P0', tag: 'main' });
+    ops.createTask(db, { id: 'b', title: 'b', type: 'bugfix',  priority: 'P1', tag: 'feat-x' });
+    ops.createTask(db, { id: 'c', title: 'c', type: 'feature', priority: 'P2', tag: 'main' });
+    ops.updateTaskStatus(db, 'a', 'in_progress');
+
+    const inProg = ops.listTasks(db, { status: 'in_progress' });
+    assert.equal(inProg.length, 1);
+    assert.equal(inProg[0].id, 'a');
+
+    const onMain = ops.listTasks(db, { tag: 'main' });
+    assert.equal(onMain.length, 2);
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('tx() rolls back on error so events are not partially written', () => {
+  const { dir, db } = freshDb();
+  try {
+    ops.createTask(db, { id: 'r', title: 'r', type: 'feature', priority: 'P1' });
+    const before = db.prepare('SELECT COUNT(*) AS n FROM events').get().n;
+    assert.throws(() => ops.tx(db, () => {
+      db.prepare(`INSERT INTO events (type) VALUES ('task_created')`).run();
+      throw new Error('boom');
+    }));
+    const after = db.prepare('SELECT COUNT(*) AS n FROM events').get().n;
+    assert.equal(after, before, 'rollback must remove the partial event row');
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('listStaleTasks finds running sessions whose heartbeat is older than grace', () => {
+  const { dir, db } = freshDb();
+  try {
+    ops.createTask(db, { id: 'k', title: 'k', type: 'feature', priority: 'P0' });
+    ops.createSession(db, { sid: 'old', task_id: 'k', runtime: 'claude', worktree_path: '/tmp/o', artifact_dir: '/tmp/o' });
+    db.prepare(`UPDATE sessions SET heartbeat_at = '2000-01-01T00:00:00.000Z' WHERE sid = 'old'`).run();
+    const stale = ops.listStaleTasks(db, 60);
+    assert.equal(stale.length, 1);
+    assert.equal(stale[0].id, 'k');
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/mcp-server/tests/tagged-tasks.test.cjs

@@ -0,0 +1,163 @@
+'use strict';
+
+// Phase 7.2 — Tagged task lists:
+//   • deriveBranchTag(cwd) — git HEAD → sanitized tag
+//   • switchTaskTag(db, task_id, new_tag) — update tag + emit event
+//   • createTask auto-derives tag from cwd when not provided
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { initStateDb, closeStateDb } = require('../lib/state-db.cjs');
+const ops = require('../lib/state-ops.cjs');
+
+function mkRepo(branch = 'main') {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-tag-repo-'));
+  execFileSync('git', ['init', '-q', '-b', branch], { cwd: dir });
+  execFileSync('git', ['config', 'user.email', 't@t'], { cwd: dir });
+  execFileSync('git', ['config', 'user.name', 't'], { cwd: dir });
+  fs.writeFileSync(path.join(dir, 'README.md'), '# r\n');
+  execFileSync('git', ['add', '-A'], { cwd: dir });
+  execFileSync('git', ['commit', '-q', '-m', 'seed'], { cwd: dir });
+  return dir;
+}
+
+function checkout(repoRoot, branch) {
+  execFileSync('git', ['checkout', '-q', '-b', branch], { cwd: repoRoot });
+}
+
+function freshDb(repoRoot) {
+  const dbPath = path.join(repoRoot, '.ultra', 'state.db');
+  const init = initStateDb(dbPath);
+  return init.db;
+}
+
+function teardown(dir, db) {
+  try { closeStateDb(db); } catch (_) { /* ignore */ }
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_) { /* ignore */ }
+}
+
+test('deriveBranchTag: main branch → "main"', () => {
+  const repo = mkRepo('main');
+  try { assert.equal(ops.deriveBranchTag(repo), 'main'); }
+  finally { fs.rmSync(repo, { recursive: true, force: true }); }
+});
+
+test('deriveBranchTag: feat/auth → "feat-auth" (slash sanitized)', () => {
+  const repo = mkRepo('main');
+  try {
+    checkout(repo, 'feat/auth');
+    assert.equal(ops.deriveBranchTag(repo), 'feat-auth');
+  } finally { fs.rmSync(repo, { recursive: true, force: true }); }
+});
+
+test('deriveBranchTag: detached HEAD → null', () => {
+  const repo = mkRepo('main');
+  try {
+    const sha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repo, encoding: 'utf8' }).trim();
+    execFileSync('git', ['checkout', '-q', sha], { cwd: repo });
+    assert.equal(ops.deriveBranchTag(repo), null);
+  } finally { fs.rmSync(repo, { recursive: true, force: true }); }
+});
+
+test('deriveBranchTag: non-git directory → null', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-nongit-'));
+  try { assert.equal(ops.deriveBranchTag(dir), null); }
+  finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('deriveBranchTag: sanitizes special chars (/ → -, @ dropped)', () => {
+  const repo = mkRepo('main');
+  try {
+    checkout(repo, 'release/v1.2@staging');
+    // Sanitized: slashes → hyphens, @ stripped
+    const tag = ops.deriveBranchTag(repo);
+    assert.match(tag, /^release-v1\.2.staging$/);
+    assert.ok(!tag.includes('/'));
+  } finally { fs.rmSync(repo, { recursive: true, force: true }); }
+});
+
+test('createTask: auto-derives tag from cwd branch when not supplied', () => {
+  const repo = mkRepo('main');
+  const db = freshDb(repo);
+  try {
+    checkout(repo, 'feat/billing');
+    const task = ops.createTask(db, {
+      id: 't-auto', title: 'autotag', type: 'feature', priority: 'P1', _cwd: repo,
+    });
+    assert.equal(task.tag, 'feat-billing');
+  } finally { teardown(repo, db); }
+});
+
+test('createTask: explicit tag wins over auto-derivation', () => {
+  const repo = mkRepo('main');
+  const db = freshDb(repo);
+  try {
+    checkout(repo, 'feat/a');
+    const task = ops.createTask(db, {
+      id: 't-explicit', title: 'explicit', type: 'feature', priority: 'P1',
+      tag: 'custom-tag', _cwd: repo,
+    });
+    assert.equal(task.tag, 'custom-tag');
+  } finally { teardown(repo, db); }
+});
+
+test('createTask: non-git cwd → tag remains null', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-task-nongit-'));
+  const db = freshDb(dir);
+  try {
+    const task = ops.createTask(db, {
+      id: 't-nogit', title: 'n/a', type: 'feature', priority: 'P1', _cwd: dir,
+    });
+    assert.equal(task.tag, null);
+  } finally { teardown(dir, db); }
+});
+
+test('switchTaskTag: updates tag + emits task_tag_changed event', () => {
+  const repo = mkRepo('main');
+  const db = freshDb(repo);
+  try {
+    ops.createTask(db, { id: 't-sw', title: 'switch me', type: 'feature', priority: 'P1', tag: 'old' });
+    const { events: before } = ops.subscribeEventsSince(db, { since_id: 0, limit: 500 });
+    const result = ops.switchTaskTag(db, 't-sw', 'new-tag');
+    assert.equal(result.tag, 'new-tag');
+    const task = ops.readTask(db, 't-sw');
+    assert.equal(task.tag, 'new-tag');
+
+    const { events: after } = ops.subscribeEventsSince(db, { since_id: 0, limit: 500 });
+    const newEvents = after.slice(before.length);
+    assert.ok(newEvents.some((e) => e.type === 'task_tag_changed' && e.task_id === 't-sw'));
+  } finally { teardown(repo, db); }
+});
+
+test('switchTaskTag: missing task → TASK_NOT_FOUND', () => {
+  const repo = mkRepo('main');
+  const db = freshDb(repo);
+  try {
+    assert.throws(
+      () => ops.switchTaskTag(db, 'nope', 'x'),
+      (err) => err instanceof ops.StateOpsError && err.code === 'TASK_NOT_FOUND',
+    );
+  } finally { teardown(repo, db); }
+});
+
+test('listTasks: filter by tag returns only matching', () => {
+  const repo = mkRepo('main');
+  const db = freshDb(repo);
+  try {
+    ops.createTask(db, { id: 'ta', title: 'a', type: 'feature', priority: 'P1', tag: 'auth' });
+    ops.createTask(db, { id: 'tb', title: 'b', type: 'feature', priority: 'P1', tag: 'billing' });
+    ops.createTask(db, { id: 'tc', title: 'c', type: 'feature', priority: 'P1', tag: 'auth' });
+
+    const auth = ops.listTasks(db, { tag: 'auth' });
+    assert.equal(auth.length, 2);
+    assert.ok(auth.every((t) => t.tag === 'auth'));
+
+    const billing = ops.listTasks(db, { tag: 'billing' });
+    assert.equal(billing.length, 1);
+  } finally { teardown(repo, db); }
+});