@web42/stask 0.1.5

package/lib/guards.mjs

@@ -0,0 +1,261 @@
+/**
+ * guards.mjs — Pre-transition guards.
+ *
+ * Two types of guards:
+ *   - setup:  Can create side effects (worktree, PR). Run first.
+ *             Returns { pass, reason } — if fail, transition stops.
+ *   - check:  Read-only validation. Run after setup.
+ *             Returns { pass, reason } — if fail, transition stops.
+ *
+ * Guards are registered per target status. A transition fails if ANY
+ * guard fails — all reasons are collected and reported.
+ */
+
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { CONFIG, LIB_DIR, getWorkspaceLibs } from './env.mjs';
+
+// ─── Setup guards (create side effects) ────────────────────────────
+
+/**
+ * Create worktree for parent task moving to In-Progress.
+ * Checks out a feature branch based on current main.
+ */
+function setupWorktree(task, libs) {
+  const wt = parseWorktree(task);
+  if (wt) return { pass: true }; // already has one
+
+  try {
+    const result = execFileSync(process.execPath, [path.join(LIB_DIR, 'worktree-create.mjs'), task['Task ID']], {
+      encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    console.error(`  ${result.trim()}`);
+
+    // Verify it was set
+    const refreshed = libs.trackerDb.findTask(task['Task ID']);
+    if (!refreshed || refreshed['Worktree'] === 'None') {
+      return { pass: false, reason: 'Worktree creation ran but worktree was not set in DB.' };
+    }
+
+    // Update the task object so subsequent guards see the worktree
+    task['Worktree'] = refreshed['Worktree'];
+    return { pass: true };
+  } catch (err) {
+    return { pass: false, reason: `Worktree creation failed: ${err.stderr || err.message}` };
+  }
+}
+
+/**
+ * Create draft PR for parent task moving to Ready for Human Review.
+ */
+function setupPR(task, libs) {
+  if (task['PR'] !== 'None') return { pass: true }; // already has one
+
+  try {
+    const result = execFileSync(process.execPath, [path.join(LIB_DIR, 'pr-create.mjs'), task['Task ID']], {
+      encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    console.error(`  ${result.trim()}`);
+
+    const refreshed = libs.trackerDb.findTask(task['Task ID']);
+    if (!refreshed || refreshed['PR'] === 'None') {
+      return { pass: false, reason: 'PR creation ran but PR URL was not set in DB.' };
+    }
+
+    task['PR'] = refreshed['PR'];
+    return { pass: true };
+  } catch (err) {
+    return { pass: false, reason: `Draft PR creation failed: ${err.stderr || err.message}` };
+  }
+}
+
+// ─── Check guards (read-only validation) ───────────────────────────
+
+/**
+ * Task must not be assigned to human (needs approve first).
+ * Only applies when coming FROM To-Do (initial approval gate).
+ * Review cycles (RHR → In-Progress) skip this — the transition
+ * itself reassigns to the lead.
+ */
+function requireApproved(task) {
+  if (task['Status'] === 'To-Do' && task['Assigned To'] === CONFIG.human.name) {
+    return { pass: false, reason: `Still assigned to ${CONFIG.human.name}. Use "stask approve" first.` };
+  }
+  return { pass: true };
+}
+
+/**
+ * Task must have a PR before moving to Ready for Human Review.
+ * Richard creates this manually via `gh pr create`.
+ */
+function requirePR(task) {
+  if (task['PR'] === 'None' || !task['PR']) {
+    return { pass: false, reason: 'No PR found. Create a draft PR with `gh pr create --draft` first.' };
+  }
+  return { pass: true };
+}
+
+/**
+ * All subtasks must be Done before parent can move to Testing.
+ */
+function allSubtasksDone(task, libs) {
+  const subtasks = libs.trackerDb.getSubtasks(task['Task ID']);
+  if (subtasks.length === 0) return { pass: true };
+
+  const notDone = subtasks.filter(s => s['Status'] !== 'Done');
+  if (notDone.length === 0) return { pass: true };
+
+  const summary = notDone.map(s => `${s['Task ID']} (${s['Status']}, ${s['Assigned To']})`).join(', ');
+  return { pass: false, reason: `${notDone.length} subtask(s) not Done: ${summary}` };
+}
+
+/**
+ * Worktree must have no uncommitted changes.
+ */
+function worktreeClean(task) {
+  const wt = parseWorktree(task);
+  if (!wt) return { pass: true };
+
+  try {
+    const status = execFileSync('git', ['status', '--porcelain'], {
+      cwd: wt.path, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+
+    if (status === '') return { pass: true };
+
+    const lines = status.split('\n');
+    return {
+      pass: false,
+      reason: `Uncommitted changes in worktree (${lines.length} file(s)):\n${lines.map(l => `    ${l}`).join('\n')}`,
+    };
+  } catch (err) {
+    return { pass: false, reason: `Could not check worktree: ${err.message}` };
+  }
+}
+
+/**
+ * Worktree must have no unpushed commits.
+ */
+function worktreePushed(task) {
+  const wt = parseWorktree(task);
+  if (!wt) return { pass: true };
+
+  try {
+    const upstream = execFileSync('git', ['rev-parse', '--abbrev-ref', '@{u}'], {
+      cwd: wt.path, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+
+    const unpushed = execFileSync('git', ['log', `${upstream}..HEAD`, '--oneline'], {
+      cwd: wt.path, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+
+    if (unpushed === '') return { pass: true };
+
+    const commits = unpushed.split('\n');
+    return {
+      pass: false,
+      reason: `${commits.length} unpushed commit(s) in worktree:\n${commits.map(c => `    ${c}`).join('\n')}`,
+    };
+  } catch (err) {
+    // No upstream = branch was never pushed
+    try {
+      const commits = execFileSync('git', ['log', '--oneline'], {
+        cwd: wt.path, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+      }).trim();
+      if (commits) {
+        return { pass: false, reason: `Branch "${parseWorktree(task).branch}" has never been pushed to remote.` };
+      }
+    } catch {}
+    return { pass: false, reason: `Could not check push state: ${err.message}` };
+  }
+}
+
+// ─── Guard registry ────────────────────────────────────────────────
+
+/**
+ * Guards mapped to target status.
+ *
+ * Each entry has:
+ *   - name: displayed in output
+ *   - type: 'check' (read-only, runs first) or 'setup' (side effects, runs after all checks pass)
+ *   - fn: (task, libs) => { pass, reason }
+ *
+ * Only parent tasks run guards.
+ */
+const GUARDS = {
+  'In-Progress': [
+    { name: 'require_approved',  type: 'check', fn: requireApproved },
+    { name: 'setup_worktree',    type: 'setup', fn: setupWorktree },
+  ],
+  'Testing': [
+    { name: 'all_subtasks_done', type: 'check', fn: allSubtasksDone },
+    { name: 'worktree_clean',    type: 'check', fn: worktreeClean },
+    { name: 'worktree_pushed',   type: 'check', fn: worktreePushed },
+  ],
+  'Ready for Human Review': [
+    { name: 'worktree_clean',    type: 'check', fn: worktreeClean },
+    { name: 'worktree_pushed',   type: 'check', fn: worktreePushed },
+    { name: 'setup_pr',          type: 'setup', fn: setupPR },
+  ],
+};
+
+// ─── Public API ────────────────────────────────────────────────────
+
+/**
+ * Run all guards for a transition. Returns { ok, failures[] }.
+ *
+ * Execution order:
+ *   1. All check guards run first (read-only). Collects all failures.
+ *   2. If ANY check fails → stop. No setup guards run.
+ *   3. If all checks pass → run setup guards (side effects).
+ *      If a setup fails → stop immediately.
+ */
+export function runGuards(task, newStatus, libs) {
+  const isParent = task['Parent'] === 'None';
+  if (!isParent) return { ok: true, failures: [] };
+
+  const guards = GUARDS[newStatus];
+  if (!guards) return { ok: true, failures: [] };
+
+  const checks = guards.filter(g => g.type === 'check');
+  const setups = guards.filter(g => g.type === 'setup');
+  const failures = [];
+
+  // Phase 1: Run all checks (read-only)
+  for (const guard of checks) {
+    const result = guard.fn(task, libs);
+    if (!result.pass) {
+      failures.push({ name: guard.name, reason: result.reason });
+      console.error(`  GUARD ${guard.name}: FAIL — ${result.reason}`);
+    } else {
+      console.error(`  GUARD ${guard.name}: OK`);
+    }
+  }
+
+  // If any check failed, don't run setups
+  if (failures.length > 0) return { ok: false, failures };
+
+  // Phase 2: Run setups (side effects) — stop on first failure
+  for (const guard of setups) {
+    const result = guard.fn(task, libs);
+    if (!result.pass) {
+      failures.push({ name: guard.name, reason: result.reason });
+      console.error(`  GUARD ${guard.name}: FAIL — ${result.reason}`);
+      break;
+    } else {
+      console.error(`  GUARD ${guard.name}: OK`);
+    }
+  }
+
+  return { ok: failures.length === 0, failures };
+}
+
+// ─── Helpers ───────────────────────────────────────────────────────
+
+function parseWorktree(task) {
+  const wt = task['Worktree'];
+  if (!wt || wt === 'None') return null;
+  const match = wt.match(/^(.+?)\s+\((.+)\)$/);
+  if (match) return { branch: match[1].trim(), path: match[2].trim() };
+  return null;
+}

package/lib/pr-create.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * pr-create.mjs — Create a draft PR for a task in Ready for Human Review.
+ *
+ * Usage: node pr-create.mjs <task-id>
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import {
+  findTask, updateTask, addLogEntry, parseWorktreeValue, WORKSPACE_DIR,
+} from './tracker-db.mjs';
+import { parseSpecValue } from './validate.mjs';
+import { CONFIG } from './env.mjs';
+
+const GH = 'gh';
+
+const taskId = process.argv[2];
+
+if (!taskId) {
+  console.error('Usage: node pr-create.mjs <task-id>');
+  process.exit(1);
+}
+
+const task = findTask(taskId);
+
+if (!task) {
+  console.error(`ERROR: Task ${taskId} not found`);
+  process.exit(1);
+}
+
+if (task['Status'] !== 'Ready for Human Review' && task['Status'] !== 'Testing') {
+  console.error(`ERROR: Task ${taskId} is "${task['Status']}". Must be "Testing" or "Ready for Human Review" to create a PR.`);
+  process.exit(1);
+}
+
+if (task['PR'] !== 'None') {
+  console.log(`PR already exists for ${taskId}: ${task['PR']}. Skipping.`);
+  process.exit(0);
+}
+
+const wt = parseWorktreeValue(task['Worktree']);
+if (!wt) {
+  console.error(`ERROR: Task ${taskId} has no worktree. Cannot create PR without a branch.`);
+  process.exit(1);
+}
+
+const { branch, path: wtPath } = wt;
+
+// Check for existing PR on this branch
+try {
+  const existingPr = execSync(
+    `${GH} pr list --head "${branch}" --json url --jq ".[0].url"`,
+    { cwd: wtPath, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+  ).trim();
+
+  if (existingPr) {
+    updateTask(taskId, { pr: existingPr });
+    addLogEntry(taskId, `${taskId} "${task['Task Name']}": Linked existing PR ${existingPr}.`);
+        console.log(`${taskId}: PR linked | ${existingPr}`);
+    process.exit(0);
+  }
+} catch {}
+
+// Build PR body
+let specContent = '';
+const specInfo = parseSpecValue(task['Spec']);
+if (specInfo?.filename) {
+  const specPath = path.join(WORKSPACE_DIR, 'shared', specInfo.filename);
+  if (fs.existsSync(specPath)) {
+    specContent = fs.readFileSync(specPath, 'utf-8');
+  }
+}
+
+let acceptanceCriteria = '';
+if (specContent) {
+  const acMatch = specContent.match(/##\s*Acceptance Criteria[\s\S]*?(?=\n##|\n---|\Z)/i);
+  if (acMatch) acceptanceCriteria = acMatch[0].trim();
+}
+
+const qaReport = task['QA Report 1'] || 'None';
+const prTitle = `[${taskId}] ${task['Task Name']}`;
+const prBody = `## Task: ${taskId} — ${task['Task Name']}
+
+**Type:** ${task['Type']}
+**QA Report:** ${qaReport !== 'None' ? 'Passed' : 'N/A'}
+
+${acceptanceCriteria ? `## Acceptance Criteria\n\n${acceptanceCriteria}\n` : ''}
+---
+
+*Created by the task framework. Review comments will be routed to the team automatically.*`;
+
+// Push branch
+try {
+  execSync(`git push -u origin "${branch}"`, { cwd: wtPath, stdio: 'pipe' });
+  console.log(`Pushed branch: ${branch}`);
+} catch (err) {
+  const errMsg = err.stderr?.toString() || err.message;
+  if (!errMsg.includes('Everything up-to-date')) {
+    console.error(`WARNING: Push issue: ${errMsg}`);
+  }
+}
+
+// Detect base branch
+let baseBranch = 'dev';
+try {
+  execSync('git rev-parse --verify dev', { cwd: wtPath, stdio: 'pipe' });
+} catch {
+  baseBranch = 'main';
+}
+
+// Create draft PR
+let prUrl;
+try {
+  prUrl = execSync(
+    `${GH} pr create --draft --base ${baseBranch} --head "${branch}" --title "${prTitle.replace(/"/g, '\\"')}" --body "${prBody.replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`,
+    { cwd: wtPath, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+  ).trim();
+} catch (err) {
+  const urlMatch = (err.stdout?.toString() || '').match(/(https:\/\/github\.com\/[^\s]+)/);
+  if (urlMatch) {
+    prUrl = urlMatch[1];
+  } else {
+    console.error(`ERROR: Failed to create PR: ${err.stderr?.toString() || err.message}`);
+    process.exit(1);
+  }
+}
+
+updateTask(taskId, { pr: prUrl });
+addLogEntry(taskId, `${taskId} "${task['Task Name']}": Draft PR created at ${prUrl}.`);
+
+console.log(`${taskId}: Draft PR created | ${prUrl}`);

package/lib/pr-status.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * pr-status.mjs — Stateless PR query: fetch comments and merge status from GitHub.
+ *
+ * Usage: node pr-status.mjs <task-id>
+ *
+ * No local state files. GitHub is the single source of truth.
+ * Returns yanComments + otherComments for the heartbeat to act on.
+ */
+
+import { execSync } from 'child_process';
+import { findTask } from './tracker-db.mjs';
+import { CONFIG } from './env.mjs';
+
+const GH = 'gh';
+const YAN_GITHUB = CONFIG.human.githubUsername;
+
+const taskId = process.argv[2];
+
+if (!taskId) {
+  console.error('Usage: node pr-status.mjs <task-id>');
+  process.exit(1);
+}
+
+const task = findTask(taskId);
+if (!task) {
+  console.error(`ERROR: Task ${taskId} not found`);
+  process.exit(1);
+}
+
+const prUrl = task['PR'];
+if (!prUrl || prUrl === 'None') {
+  console.error(`ERROR: Task ${taskId} has no PR URL`);
+  process.exit(1);
+}
+
+const prMatch = prUrl.match(/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/);
+if (!prMatch) {
+  console.error(`ERROR: Could not parse PR URL: ${prUrl}`);
+  process.exit(1);
+}
+
+const [, owner, repo, prNumber] = prMatch;
+
+// ─── Fetch PR info ────────────────────────────────────────────────
+
+let prInfo;
+try {
+  prInfo = JSON.parse(execSync(
+    `${GH} api repos/${owner}/${repo}/pulls/${prNumber}`,
+    { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+  ));
+} catch (err) {
+  console.error(`ERROR: Could not fetch PR info: ${err.message}`);
+  process.exit(1);
+}
+
+const isDraft = prInfo.draft === true;
+const isMerged = prInfo.merged === true;
+const prState = prInfo.state;
+
+// ─── Fetch all comments ───────────────────────────────────────────
+
+let issueComments = [];
+try {
+  issueComments = JSON.parse(execSync(
+    `${GH} api repos/${owner}/${repo}/issues/${prNumber}/comments --paginate`,
+    { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+  ));
+} catch {}
+
+let reviewComments = [];
+try {
+  reviewComments = JSON.parse(execSync(
+    `${GH} api repos/${owner}/${repo}/pulls/${prNumber}/comments --paginate`,
+    { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+  ));
+} catch {}
+
+let reviews = [];
+try {
+  reviews = JSON.parse(execSync(
+    `${GH} api repos/${owner}/${repo}/pulls/${prNumber}/reviews --paginate`,
+    { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+  ));
+} catch {}
+
+// ─── Normalize and split by author ────────────────────────────────
+
+const allComments = [
+  ...issueComments.map(c => ({
+    id: c.id, type: 'issue', author: c.user?.login || 'unknown',
+    body: c.body, path: null, line: null, createdAt: c.created_at,
+    updatedAt: c.updated_at, htmlUrl: c.html_url,
+  })),
+  ...reviewComments.map(c => ({
+    id: c.id, type: 'review', author: c.user?.login || 'unknown',
+    body: c.body, path: c.path, line: c.line || c.original_line,
+    createdAt: c.created_at, updatedAt: c.updated_at, htmlUrl: c.html_url,
+  })),
+  ...reviews.filter(r => r.body && r.body.trim()).map(r => ({
+    id: r.id, type: 'pr-review', author: r.user?.login || 'unknown',
+    body: r.body, path: null, line: null, createdAt: r.submitted_at,
+    updatedAt: r.submitted_at, htmlUrl: r.html_url,
+    reviewState: r.state,
+  })),
+];
+
+const yanComments = allComments.filter(c => c.author === YAN_GITHUB);
+const otherComments = allComments.filter(c => c.author !== YAN_GITHUB);
+
+const output = {
+  taskId, prUrl, isDraft, isMerged, state: prState,
+  totalComments: allComments.length,
+  yanComments,
+  otherComments,
+};
+
+console.log(JSON.stringify(output, null, 2));

package/lib/roles.mjs

@@ -0,0 +1,85 @@
+/**
+ * roles.mjs — Role-based auto-assign resolution from config.
+ *
+ * Auto-assign rules are derived from roles, not hardcoded names:
+ * - To-Do → human
+ * - In-Progress → lead (parent task ownership; subtasks keep builder assignments via cascade logic)
+ * - Testing → qa agent
+ * - Ready for Human Review → human
+ * - Blocked → human
+ * - Done → keep current
+ */
+
+import { CONFIG } from './env.mjs';
+
+/**
+ * Find the agent name for a given role.
+ * Returns the display name (capitalized) or null if not found.
+ */
+export function getAgentByRole(role) {
+  for (const [name, agent] of Object.entries(CONFIG.agents)) {
+    if (agent.role === role) {
+      return name.charAt(0).toUpperCase() + name.slice(1);
+    }
+  }
+  return null;
+}
+
+/**
+ * Get the auto-assign target for a status transition.
+ * Returns agent display name or null (keep current).
+ */
+export function getAutoAssign(status) {
+  switch (status) {
+    case 'To-Do':
+    case 'Blocked':
+      return CONFIG.human.name;
+    case 'Ready for Human Review':
+      return null; // keep current assignee — preserves builder ownership
+    case 'Testing':
+      return getAgentByRole('qa');
+    case 'In-Progress':
+      return getAgentByRole('lead');
+    case 'Done':
+      return null; // keep current
+    default:
+      return null;
+  }
+}
+
+/**
+ * Get the Slack user ID for an agent or human name.
+ */
+export function getSlackUserId(name) {
+  if (!name) return null;
+  const lower = name.toLowerCase();
+  if (lower === CONFIG.human.name.toLowerCase()) return CONFIG.human.slackUserId;
+  const agent = CONFIG.agents[lower];
+  return agent?.slackUserId || null;
+}
+
+/**
+ * Get the lead agent name (for delegation after approval).
+ */
+export function getLeadAgent() {
+  return getAgentByRole('lead');
+}
+
+/**
+ * Reverse lookup: Slack user ID → display name.
+ */
+export function getNameBySlackUserId(userId) {
+  if (!userId) return null;
+  if (userId === CONFIG.human.slackUserId) return CONFIG.human.name;
+  for (const [name, agent] of Object.entries(CONFIG.agents)) {
+    if (agent.slackUserId === userId) return name.charAt(0).toUpperCase() + name.slice(1);
+  }
+  return null;
+}
+
+/**
+ * Check if a status requires human assignment override.
+ */
+export function isHumanReviewStatus(status) {
+  return status === 'Ready for Human Review' || status === 'Blocked';
+}