@web42/stask 0.1.5

package/commands/qa.mjs

@@ -0,0 +1,183 @@
+/**
+ * stask qa — Submit QA verdict for a task.
+ *
+ * Usage: stask qa <task-id> --report <path> [--screenshots <dir>] [--verdict PASS|FAIL|PASS_WITH_ISSUES]
+ */
+
+import path from 'path';
+import fs from 'fs';
+import { createHash } from 'crypto';
+import { execSync } from 'child_process';
+import { CONFIG, getWorkspaceLibs } from '../lib/env.mjs';
+import { withTransaction } from '../lib/tx.mjs';
+import { syncTaskToSlack } from '../lib/slack-row.mjs';
+import { getAutoAssign, getLeadAgent } from '../lib/roles.mjs';
+
+const TRIGGER_SQL = `
+  CREATE TRIGGER validate_status_transition
+  BEFORE UPDATE OF status ON tasks WHEN OLD.status != NEW.status
+  BEGIN SELECT CASE
+    WHEN OLD.status = 'Done' THEN RAISE(ABORT, 'Cannot transition from Done')
+    WHEN OLD.status = 'To-Do' AND NEW.status NOT IN ('In-Progress','Blocked') THEN RAISE(ABORT, 'Invalid from To-Do')
+    WHEN OLD.status = 'In-Progress' AND NEW.status NOT IN ('Testing','Blocked') THEN RAISE(ABORT, 'Invalid from In-Progress')
+    WHEN OLD.status = 'Testing' AND NEW.status NOT IN ('Ready for Human Review','In-Progress','Blocked') THEN RAISE(ABORT, 'Invalid from Testing')
+    WHEN OLD.status = 'Ready for Human Review' AND NEW.status NOT IN ('Done','In-Progress','Blocked') THEN RAISE(ABORT, 'Invalid from RHR')
+    WHEN OLD.status = 'Blocked' AND NEW.status NOT IN ('To-Do','In-Progress','Testing','Ready for Human Review') THEN RAISE(ABORT, 'Invalid from Blocked')
+  END; END;
+`;
+
+function parseArgs(argv) {
+  const args = { taskId: argv[0] };
+  for (let i = 1; i < argv.length; i++) {
+    if (argv[i] === '--report' && argv[i + 1]) args.report = argv[++i];
+    else if (argv[i] === '--screenshots' && argv[i + 1]) args.screenshots = argv[++i];
+    else if (argv[i] === '--verdict' && argv[i + 1]) args.verdict = argv[++i];
+  }
+  return args;
+}
+
+export async function run(argv) {
+  const args = parseArgs(argv);
+
+  if (!args.taskId || !args.report) {
+    console.error('Usage: stask qa <task-id> --report <path> [--screenshots <dir>] [--verdict PASS|FAIL]');
+    process.exit(1);
+  }
+
+  const verdict = (args.verdict || 'PASS').toUpperCase();
+  if (!['PASS', 'FAIL', 'PASS_WITH_ISSUES'].includes(verdict)) {
+    console.error('ERROR: Verdict must be PASS, FAIL, or PASS_WITH_ISSUES');
+    process.exit(1);
+  }
+
+  const libs = await getWorkspaceLibs();
+  const ws = CONFIG.specsDir;
+
+  const task = libs.trackerDb.findTask(args.taskId);
+  if (!task) { console.error(`ERROR: Task ${args.taskId} not found`); process.exit(1); }
+  if (task['Status'] !== 'Testing') { console.error(`ERROR: ${args.taskId} is "${task['Status']}". Must be "Testing".`); process.exit(1); }
+
+  // Upload QA report
+  const registry = libs.fileUploader.loadRegistry(CONFIG.registryPath);
+
+  async function uploadAndRegister(filePath) {
+    const relPath = filePath.startsWith('shared/') ? filePath : path.relative(ws, path.resolve(filePath));
+    const fullPath = path.resolve(ws, relPath);
+    if (!fs.existsSync(fullPath)) return null;
+    const content = fs.readFileSync(fullPath);
+    const hash = createHash('sha256').update(content).digest('hex').slice(0, 16);
+    const existing = registry.files[relPath];
+    if (existing && existing.hash === hash && existing.fileId) return { fileId: existing.fileId, relPath };
+    const filename = path.basename(relPath);
+    const fileId = await libs.slackApi.uploadFile(filename, content);
+    registry.files[relPath] = { fileId, hash, title: filename, uploadedAt: new Date().toISOString(), sizeBytes: content.length };
+    return { fileId, relPath };
+  }
+
+  const reportResult = await uploadAndRegister(args.report);
+  if (!reportResult) { console.error(`ERROR: QA report not found: ${args.report}`); process.exit(1); }
+  console.log(`Uploaded report: ${reportResult.fileId}`);
+
+  // Bundle screenshots
+  const allFileIds = [reportResult.fileId];
+  const screenshotsDir = args.screenshots || path.join(path.dirname(path.resolve(ws, reportResult.relPath)), 'screenshots');
+  const screenshotsDirFull = path.resolve(ws, screenshotsDir.startsWith('shared/') ? screenshotsDir : path.relative(ws, path.resolve(screenshotsDir)));
+
+  if (fs.existsSync(screenshotsDirFull)) {
+    const imageFiles = fs.readdirSync(screenshotsDirFull).filter(f => /\.(png|jpg|jpeg|gif|webp)$/i.test(f)).sort();
+    if (imageFiles.length > 0) {
+      const reportFullPath = path.resolve(ws, reportResult.relPath);
+      const zipName = `${args.taskId}-qa-bundle.zip`;
+      const zipPath = path.join(path.dirname(reportFullPath), zipName);
+      try {
+        if (fs.existsSync(zipPath)) fs.unlinkSync(zipPath);
+        execSync(`zip -j "${zipPath}" "${reportFullPath}"`, { stdio: 'pipe' });
+        const imgPaths = imageFiles.map(f => `"${path.join(screenshotsDirFull, f)}"`).join(' ');
+        execSync(`zip -j "${zipPath}" ${imgPaths}`, { stdio: 'pipe' });
+        const zipContent = fs.readFileSync(zipPath);
+        const zipFileId = await libs.slackApi.uploadFile(zipName, zipContent, 'application/zip');
+        allFileIds.push(zipFileId);
+        const zipRelPath = path.relative(ws, zipPath);
+        const zipHash = createHash('sha256').update(zipContent).digest('hex').slice(0, 16);
+        registry.files[zipRelPath] = { fileId: zipFileId, hash: zipHash, title: zipName, uploadedAt: new Date().toISOString(), sizeBytes: zipContent.length };
+      } catch (err) { console.error(`WARNING: Failed to create zip: ${err.message}`); }
+    }
+  }
+
+  libs.fileUploader.saveRegistry(CONFIG.registryPath, registry);
+
+  // Determine outcome
+  const currentFailCount = task['qa_fail_count'] || 0;
+  const reportRef = allFileIds.map(id => `(${id})`).join(' ');
+  let newStatus, newAssignee;
+  const updates = {};
+
+  if (verdict !== 'FAIL') {
+    updates[`qa_report_${currentFailCount + 1}`] = reportRef;
+    // QA PASS → stays in Testing, reassigned to Lead.
+    // Lead creates a rich PR with full context, then transitions to RHR.
+    newStatus = 'Testing';
+    newAssignee = getLeadAgent();
+  } else if (currentFailCount + 1 >= CONFIG.maxQaRetries) {
+    updates[`qa_report_${currentFailCount + 1}`] = reportRef;
+    updates.qa_fail_count = currentFailCount + 1;
+    newStatus = 'Blocked';
+    newAssignee = CONFIG.human.name;
+    console.error(`QA failed ${currentFailCount + 1} times. Escalating to ${CONFIG.human.name}.`);
+  } else {
+    updates[`qa_report_${currentFailCount + 1}`] = reportRef;
+    updates.qa_fail_count = currentFailCount + 1;
+    newStatus = 'In-Progress';
+    newAssignee = getLeadAgent();
+    console.error(`QA failure #${currentFailCount + 1}/${CONFIG.maxQaRetries}. Back to ${newAssignee} for fixes.`);
+  }
+
+  updates.status = newStatus;
+  if (newAssignee) updates.assigned_to = newAssignee;
+
+  await withTransaction(
+    (db, libs) => {
+      libs.trackerDb.updateTask(args.taskId, updates);
+
+      // Cascade to subtasks
+      const subtasks = libs.trackerDb.getSubtasks(args.taskId);
+      const cascaded = [];
+      if (subtasks.length > 0) {
+        db.exec('DROP TRIGGER IF EXISTS validate_status_transition');
+        try {
+          for (const sub of subtasks) {
+            if (sub['Status'] === 'Done' || sub['Status'] === newStatus) continue;
+            const subUpdates = [newStatus];
+            let sql = 'UPDATE tasks SET status = ?';
+            if (newAssignee && newStatus !== 'In-Progress') { sql += ', assigned_to = ?'; subUpdates.push(newAssignee); }
+            sql += ' WHERE task_id = ?';
+            subUpdates.push(sub['Task ID']);
+            db.prepare(sql).run(...subUpdates);
+            cascaded.push(sub['Task ID']);
+          }
+        } finally {
+          db.exec(TRIGGER_SQL);
+        }
+      }
+
+      const bundleNote = allFileIds.length > 1 ? ' + bundle zip' : '';
+      libs.trackerDb.addLogEntry(args.taskId, `${args.taskId} "${task['Task Name']}": QA ${verdict} by QA. Report: ${reportResult.fileId}${bundleNote}. Testing → ${newStatus}.`);
+
+      const updatedTask = libs.trackerDb.findTask(args.taskId);
+      const cascadedTasks = cascaded.map(id => libs.trackerDb.findTask(id));
+      return { taskRow: updatedTask, cascadedTasks };
+    },
+    async ({ taskRow, cascadedTasks }, db) => {
+      const allOps = [];
+      const { slackOps } = await syncTaskToSlack(db, taskRow);
+      allOps.push(...slackOps);
+      for (const sub of cascadedTasks) {
+        if (!sub) continue;
+        try { const { slackOps: subOps } = await syncTaskToSlack(db, sub); allOps.push(...subOps); } catch {}
+      }
+      return allOps;
+    }
+  );
+
+  console.log(`${args.taskId}: QA ${verdict} | Testing → ${newStatus} | Attachments: ${allFileIds.length}`);
+}

package/commands/session.mjs

@@ -0,0 +1,76 @@
+/**
+ * stask session — Manage session locks.
+ *
+ * Usage:
+ *   stask session claim <task-id> --agent <name> --session-id <id>
+ *   stask session release <task-id> [--session-id <id>]
+ *   stask session status [<task-id>]
+ */
+
+import { withDb } from '../lib/tx.mjs';
+import { claimTask, releaseTask, getSessionStatus, cleanStaleSessions } from '../lib/session-tracker.mjs';
+
+function parseArgs(argv) {
+  const args = { subcommand: argv[0] };
+  for (let i = 1; i < argv.length; i++) {
+    if (argv[i] === '--agent' && argv[i + 1]) args.agent = argv[++i];
+    else if (argv[i] === '--session-id' && argv[i + 1]) args.sessionId = argv[++i];
+    else if (!argv[i].startsWith('-') && !args.taskId) args.taskId = argv[i];
+  }
+  return args;
+}
+
+export async function run(argv) {
+  const args = parseArgs(argv);
+
+  if (!args.subcommand || !['claim', 'release', 'status'].includes(args.subcommand)) {
+    console.error('Usage: stask session <claim|release|status> [<task-id>] [--agent X] [--session-id Y]');
+    process.exit(1);
+  }
+
+  await withDb((db) => {
+    if (args.subcommand === 'claim') {
+      if (!args.taskId || !args.agent || !args.sessionId) {
+        console.error('Usage: stask session claim <task-id> --agent <name> --session-id <id>');
+        process.exit(1);
+      }
+      const result = claimTask(db, args.taskId, args.agent, args.sessionId);
+      if (result.ok) {
+        console.log(result.message);
+      } else {
+        console.error(`BLOCKED: ${result.message}`);
+        process.exit(1);
+      }
+    }
+
+    else if (args.subcommand === 'release') {
+      if (!args.taskId) {
+        console.error('Usage: stask session release <task-id> [--session-id <id>]');
+        process.exit(1);
+      }
+      const result = releaseTask(db, args.taskId, args.sessionId);
+      console.log(result.message);
+    }
+
+    else if (args.subcommand === 'status') {
+      // Clean stale sessions first
+      const cleaned = cleanStaleSessions(db);
+      if (cleaned > 0) console.error(`Cleaned ${cleaned} stale session(s)`);
+
+      const sessions = getSessionStatus(db, args.taskId);
+      if (sessions.length === 0) {
+        console.log(args.taskId ? `No active session for ${args.taskId}.` : 'No active sessions.');
+        return;
+      }
+
+      console.log('Task ID     Agent       Session ID                       Age   Stale');
+      console.log('─'.repeat(75));
+      for (const s of sessions) {
+        const staleFlag = s.isStale ? 'YES' : '';
+        console.log(
+          `${s.task_id.padEnd(12)}${s.agent.padEnd(12)}${s.session_id.padEnd(33)}${String(s.ageMinutes + 'm').padEnd(6)}${staleFlag}`
+        );
+      }
+    }
+  });
+}

package/commands/show.mjs

@@ -0,0 +1,61 @@
+/**
+ * stask show — Show task details.
+ *
+ * Usage: stask show <task-id> [--log]
+ */
+
+import { withDb } from '../lib/tx.mjs';
+
+export async function run(argv) {
+  const taskId = argv[0];
+  const showLog = argv.includes('--log');
+
+  if (!taskId) {
+    console.error('Usage: stask show <task-id> [--log]');
+    process.exit(1);
+  }
+
+  await withDb((db, libs) => {
+    const task = libs.trackerDb.findTask(taskId);
+    if (!task) { console.error(`ERROR: Task ${taskId} not found`); process.exit(1); }
+
+    console.log(`Task ${task['Task ID']}: ${task['Task Name']}`);
+    console.log(`${'─'.repeat(60)}`);
+    console.log(`  Status:      ${task['Status']}`);
+    console.log(`  Assigned To: ${task['Assigned To']}`);
+    console.log(`  Type:        ${task['Type']}`);
+    console.log(`  Parent:      ${task['Parent']}`);
+    console.log(`  Spec:        ${task['Spec']}`);
+    console.log(`  Worktree:    ${task['Worktree']}`);
+    console.log(`  PR:          ${task['PR']}`);
+
+    if (task['QA Report 1'] !== 'None') console.log(`  QA Report 1: ${task['QA Report 1']}`);
+    if (task['QA Report 2'] !== 'None') console.log(`  QA Report 2: ${task['QA Report 2']}`);
+    if (task['QA Report 3'] !== 'None') console.log(`  QA Report 3: ${task['QA Report 3']}`);
+    if (task['Blocker'] !== 'None') console.log(`  Blocker:     ${task['Blocker']}`);
+
+    console.log(`  Created:     ${task['created_at']}`);
+    console.log(`  Updated:     ${task['updated_at']}`);
+
+    // Subtasks
+    const subtasks = libs.trackerDb.getSubtasks(taskId);
+    if (subtasks.length > 0) {
+      console.log(`\nSubtasks (${subtasks.length}):`);
+      for (const sub of subtasks) {
+        const marker = sub['Status'] === 'Done' ? '[x]' : '[ ]';
+        console.log(`  ${marker} ${sub['Task ID']}: ${sub['Task Name']} (${sub['Status']}, ${sub['Assigned To']})`);
+      }
+    }
+
+    // Log
+    if (showLog) {
+      const entries = libs.trackerDb.getLogForTask(taskId);
+      if (entries.length > 0) {
+        console.log(`\nLog (${entries.length} entries):`);
+        for (const e of entries.reverse()) {
+          console.log(`  [${e.created_at}] ${e.message}`);
+        }
+      }
+    }
+  });
+}

package/commands/spec-update.mjs

@@ -0,0 +1,61 @@
+/**
+ * stask spec-update — Re-upload edited spec and update DB.
+ *
+ * Usage: stask spec-update <task-id> --spec <path>
+ */
+
+import path from 'path';
+import fs from 'fs';
+import { createHash } from 'crypto';
+import { CONFIG, getWorkspaceLibs } from '../lib/env.mjs';
+import { withTransaction } from '../lib/tx.mjs';
+import { syncTaskToSlack } from '../lib/slack-row.mjs';
+
+export async function run(argv) {
+  const taskId = argv[0];
+  let specPath;
+  for (let i = 1; i < argv.length; i++) {
+    if (argv[i] === '--spec' && argv[i + 1]) specPath = argv[++i];
+  }
+
+  if (!taskId || !specPath) {
+    console.error('Usage: stask spec-update <task-id> --spec <path>');
+    process.exit(1);
+  }
+
+  const libs = await getWorkspaceLibs();
+  const ws = CONFIG.specsDir;
+
+  const task = libs.trackerDb.findTask(taskId);
+  if (!task) { console.error(`ERROR: Task ${taskId} not found`); process.exit(1); }
+
+  const relPath = specPath.startsWith('shared/') ? specPath : path.relative(ws, path.resolve(specPath));
+  const fullPath = path.resolve(ws, relPath);
+  if (!fs.existsSync(fullPath)) { console.error(`ERROR: Spec not found: ${relPath}`); process.exit(1); }
+
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const registry = libs.fileUploader.loadRegistry(CONFIG.registryPath);
+  const filename = path.basename(relPath);
+  const hash = createHash('sha256').update(content).digest('hex').slice(0, 16);
+  const fileId = await libs.slackApi.uploadFile(filename, content);
+  registry.files[relPath] = { fileId, hash, title: filename, uploadedAt: new Date().toISOString(), sizeBytes: Buffer.byteLength(content, 'utf-8') };
+  libs.fileUploader.saveRegistry(CONFIG.registryPath, registry);
+
+  const specName = relPath.replace(/^shared\//, '');
+  const specValue = libs.validate.formatSpecValue(specName, fileId);
+
+  await withTransaction(
+    (db, libs) => {
+      libs.trackerDb.updateTask(taskId, { spec: specValue });
+      libs.trackerDb.addLogEntry(taskId, `${taskId} spec updated: ${specValue}`);
+      const updated = libs.trackerDb.findTask(taskId);
+      return { taskRow: updated };
+    },
+    async ({ taskRow }, db) => {
+      const { slackOps } = await syncTaskToSlack(db, taskRow);
+      return slackOps;
+    }
+  );
+
+  console.log(`${taskId}: Spec updated → ${fileId}`);
+}

package/commands/subtask-create.mjs

@@ -0,0 +1,62 @@
+/**
+ * stask subtask create — Create a subtask under a parent task.
+ *
+ * Usage: stask subtask create --parent <task-id> --name "..." --assign <agent> [--type Task|Bug]
+ */
+
+import { getWorkspaceLibs } from '../lib/env.mjs';
+import { withTransaction } from '../lib/tx.mjs';
+import { syncSubtaskToSlack } from '../lib/slack-row.mjs';
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--parent' && argv[i + 1]) args.parent = argv[++i];
+    else if (argv[i] === '--name' && argv[i + 1]) args.name = argv[++i];
+    else if (argv[i] === '--assign' && argv[i + 1]) args.assign = argv[++i];
+    else if (argv[i] === '--type' && argv[i + 1]) args.type = argv[++i];
+  }
+  return args;
+}
+
+export async function run(argv) {
+  const args = parseArgs(argv);
+
+  if (!args.parent || !args.name || !args.assign) {
+    console.error('Usage: stask subtask create --parent <task-id> --name "Name" --assign <agent> [--type Task|Bug]');
+    process.exit(1);
+  }
+
+  const result = await withTransaction(
+    (db, libs) => {
+      const parent = libs.trackerDb.findTask(args.parent);
+      if (!parent) throw new Error(`Parent task ${args.parent} not found`);
+      if (parent['Status'] !== 'To-Do') throw new Error(`Parent ${args.parent} is "${parent['Status']}". Must be "To-Do" to create subtasks.`);
+
+      const subtaskId = libs.trackerDb.getNextSubtaskId(args.parent);
+      const parentSpec = parent['Spec'];
+
+      libs.trackerDb.insertTask({
+        task_id: subtaskId,
+        task_name: args.name,
+        status: 'To-Do',
+        assigned_to: args.assign,
+        spec: parentSpec,
+        type: args.type || 'Task',
+        parent_id: args.parent,
+      });
+
+      libs.trackerDb.addLogEntry(subtaskId, `${subtaskId} "${args.name}" created under ${args.parent}. Assigned: ${args.assign}.`);
+
+      const taskRow = libs.trackerDb.findTask(subtaskId);
+      return { subtaskId, taskRow, parentSpec };
+    },
+    async ({ taskRow }, db) => {
+      const { slackOps } = await syncSubtaskToSlack(db, taskRow);
+      return slackOps;
+    }
+  );
+
+  const specFileId = result.parentSpec.match(/\((\w+)\)$/)?.[1] || result.parentSpec;
+  console.log(`Created ${result.subtaskId}: "${args.name}" | Parent: ${args.parent} | Assigned: ${args.assign} | Spec: ${specFileId}`);
+}

package/commands/subtask-done.mjs

@@ -0,0 +1,80 @@
+/**
+ * stask subtask done — Builder marks their subtask as Done.
+ *
+ * Usage: stask subtask done <subtask-id>
+ *
+ * If all siblings are Done → auto-transitions parent to Testing.
+ */
+
+import { getWorkspaceLibs } from '../lib/env.mjs';
+import { withTransaction } from '../lib/tx.mjs';
+import { syncTaskToSlack } from '../lib/slack-row.mjs';
+
+const TRIGGER_SQL = `
+  CREATE TRIGGER validate_status_transition
+  BEFORE UPDATE OF status ON tasks WHEN OLD.status != NEW.status
+  BEGIN SELECT CASE
+    WHEN OLD.status = 'Done' THEN RAISE(ABORT, 'Cannot transition from Done')
+    WHEN OLD.status = 'To-Do' AND NEW.status NOT IN ('In-Progress','Blocked') THEN RAISE(ABORT, 'Invalid transition from To-Do')
+    WHEN OLD.status = 'In-Progress' AND NEW.status NOT IN ('Testing','Blocked') THEN RAISE(ABORT, 'Invalid transition from In-Progress')
+    WHEN OLD.status = 'Testing' AND NEW.status NOT IN ('Ready for Human Review','In-Progress','Blocked') THEN RAISE(ABORT, 'Invalid transition from Testing')
+    WHEN OLD.status = 'Ready for Human Review' AND NEW.status NOT IN ('Done','In-Progress','Blocked') THEN RAISE(ABORT, 'Invalid transition from Ready for Human Review')
+    WHEN OLD.status = 'Blocked' AND NEW.status NOT IN ('To-Do','In-Progress','Testing','Ready for Human Review') THEN RAISE(ABORT, 'Invalid transition from Blocked')
+  END; END;
+`;
+
+export async function run(argv) {
+  const subtaskId = argv[0];
+
+  if (!subtaskId) {
+    console.error('Usage: stask subtask done <subtask-id>');
+    process.exit(1);
+  }
+
+  const libs = await getWorkspaceLibs();
+  const subtask = libs.trackerDb.findTask(subtaskId);
+
+  if (!subtask) { console.error(`ERROR: Task ${subtaskId} not found`); process.exit(1); }
+  if (subtask['Parent'] === 'None') { console.error(`ERROR: ${subtaskId} is not a subtask. Use "stask transition" for top-level tasks.`); process.exit(1); }
+  if (subtask['Status'] !== 'In-Progress') { console.error(`ERROR: ${subtaskId} is "${subtask['Status']}". Must be "In-Progress".`); process.exit(1); }
+
+  const parentId = subtask['Parent'];
+
+  await withTransaction(
+    (db, libs) => {
+      db.exec('DROP TRIGGER IF EXISTS validate_status_transition');
+      try {
+        db.prepare('UPDATE tasks SET status = ? WHERE task_id = ?').run('Done', subtaskId);
+      } finally {
+        db.exec(TRIGGER_SQL);
+      }
+
+      libs.trackerDb.addLogEntry(subtaskId, `${subtaskId} "${subtask['Task Name']}": In-Progress → Done. Marked complete by builder.`);
+      const updated = libs.trackerDb.findTask(subtaskId);
+      return { subtaskId, taskRow: updated };
+    },
+    async ({ taskRow }, db) => {
+      const { slackOps } = await syncTaskToSlack(db, taskRow);
+      return slackOps;
+    }
+  );
+
+  console.log(`${subtaskId}: "${subtask['Task Name']}" | In-Progress → Done`);
+
+  // Check siblings — auto-transition parent if all Done
+  const siblings = libs.trackerDb.getSubtasks(parentId);
+  const parent = libs.trackerDb.findTask(parentId);
+
+  if (!parent) { console.error(`WARNING: Parent ${parentId} not found.`); return; }
+
+  const allDone = siblings.length > 0 && siblings.every(s => s['Status'] === 'Done');
+
+  if (allDone) {
+    console.log(`All subtasks of ${parentId} are Done. Auto-transitioning parent to Testing...`);
+    const { run: runTransition } = await import('./transition.mjs');
+    await runTransition([parentId, 'Testing']);
+  } else {
+    const remaining = siblings.filter(s => s['Status'] !== 'Done');
+    console.log(`${remaining.length} subtask(s) still pending: ${remaining.map(s => `${s['Task ID']} (${s['Status']})`).join(', ')}`);
+  }
+}

package/commands/sync-daemon.mjs

@@ -0,0 +1,134 @@
+/**
+ * sync-daemon.mjs — Manage the background sync daemon.
+ *
+ * Usage:
+ *   stask sync-daemon start   — Start the daemon (fork detached)
+ *   stask sync-daemon stop    — Stop the daemon (SIGTERM via PID file)
+ *   stask sync-daemon status  — Check if daemon is running
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { spawn } from 'child_process';
+import { CONFIG } from '../lib/env.mjs';
+
+const STASK_HOME = CONFIG.staskHome;
+const PID_FILE = path.resolve(STASK_HOME, 'sync-daemon.pid');
+const DAEMON_SCRIPT = path.resolve(CONFIG.staskRoot, 'lib', 'sync-daemon.mjs');
+const LOG_FILE = path.resolve(STASK_HOME, 'logs', 'sync-daemon.log');
+
+export async function run(argv) {
+  const subCmd = argv[0];
+  switch (subCmd) {
+    case 'start':  return start();
+    case 'stop':   return stop();
+    case 'status': return status();
+    default:
+      console.error('Usage: stask sync-daemon <start|stop|status>');
+      process.exit(1);
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────
+
+function readPid() {
+  try {
+    return parseInt(fs.readFileSync(PID_FILE, 'utf-8').trim(), 10);
+  } catch (_) {
+    return null;
+  }
+}
+
+function isAlive(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Start the daemon as a detached child process.
+ */
+export function startDaemon() {
+  const pid = readPid();
+  if (isAlive(pid)) return pid; // Already running
+
+  // Clean up stale PID file
+  if (pid) {
+    try { fs.unlinkSync(PID_FILE); } catch (_) {}
+  }
+
+  // Ensure log dir
+  const logDir = path.dirname(LOG_FILE);
+  if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
+
+  // Open log file for stdout/stderr
+  const logFd = fs.openSync(LOG_FILE, 'a');
+
+  const child = spawn(process.execPath, [DAEMON_SCRIPT], {
+    detached: true,
+    stdio: ['ignore', logFd, logFd],
+    env: { ...process.env },
+  });
+  child.unref();
+
+  return child.pid;
+}
+
+// ─── Subcommands ──────────────────────────────────────────────────
+
+function start() {
+  const pid = readPid();
+  if (isAlive(pid)) {
+    console.log(`Sync daemon already running (PID ${pid})`);
+    return;
+  }
+
+  const newPid = startDaemon();
+  console.log(`Sync daemon started (PID ${newPid})`);
+}
+
+function stop() {
+  const pid = readPid();
+  if (!pid || !isAlive(pid)) {
+    console.log('Sync daemon is not running');
+    try { fs.unlinkSync(PID_FILE); } catch (_) {}
+    return;
+  }
+
+  process.kill(pid, 'SIGTERM');
+  console.log(`Sent SIGTERM to sync daemon (PID ${pid})`);
+
+  // Wait briefly for cleanup
+  let tries = 10;
+  const check = () => {
+    if (!isAlive(pid) || --tries <= 0) {
+      if (isAlive(pid)) {
+        console.error('Daemon did not stop in time');
+      } else {
+        console.log('Sync daemon stopped');
+      }
+      return;
+    }
+    setTimeout(check, 200);
+  };
+  check();
+}
+
+function status() {
+  const pid = readPid();
+  if (pid && isAlive(pid)) {
+    const interval = CONFIG.syncIntervalSeconds || 60;
+    console.log(`Sync daemon is running (PID ${pid}, interval ${interval}s)`);
+    console.log(`Log: ${LOG_FILE}`);
+  } else {
+    console.log('Sync daemon is not running');
+    if (pid) {
+      // Stale PID file
+      try { fs.unlinkSync(PID_FILE); } catch (_) {}
+    }
+  }
+}