@magnusekdahl/parallix 1.2.0 → 1.3.0

package/lib/tools/backlog.ts

@@ -0,0 +1,835 @@
+import fs from 'fs';
+import path from 'path';
+import { git } from '../core/git.js';
+import { WORKFLOW_AGENT_NAMES } from '../agents/agents.js';
+import * as fmt from '../core/fmt.js';
+import { resolveTaskStorage } from '../core/product-config.js';
+
+/** @returns {readonly string[]} */
+function getSupportedAgents() {
+  return WORKFLOW_AGENT_NAMES;
+}
+
+/** @param {string} [rootDir] @returns {{tasksDir: string, completedDir: string, archiveTasksDir: string}} */
+function getTaskStorage(rootDir = process.cwd()) {
+  return resolveTaskStorage(rootDir);
+}
+
+/**
+ * @param {string} slug
+ * @param {string} [rootDir]
+ * @returns {string[]}
+ */
+function findTaskFiles(slug: string, rootDir: string = process.cwd()): string[] {
+  const { tasksDir, completedDir, archiveTasksDir: archivedDir } = getTaskStorage(rootDir);
+  const sortByBacklogState = (filePath: string) => {
+    if (filePath.startsWith(tasksDir + path.sep)) {return 0;}
+    if (filePath.startsWith(completedDir + path.sep)) {return 1;}
+    if (filePath.startsWith(archivedDir + path.sep)) {return 2;}
+    return 3;
+  };
+
+  /** @param {string} dir */
+  const scan = (dir: string) => {
+    if (!fs.existsSync(dir)) {return [];}
+    const files = fs.readdirSync(dir);
+    const normalizedSlug = slug.toLowerCase();
+    return files
+      .filter((f: string) => f.toLowerCase().startsWith(normalizedSlug))
+      .map((f: string) => path.join(dir, f));
+  };
+
+  const matches = [...scan(tasksDir), ...scan(completedDir), ...scan(archivedDir)];
+  return matches.sort((a, b) => sortByBacklogState(a) - sortByBacklogState(b) || a.localeCompare(b));
+}
+
+/**
+ * @param {string} slug
+ * @param {string} [rootDir]
+ * @returns {{ok: boolean, taskFile?: string, matches: string[], reason?: string}}
+ */
+function resolveTaskFile(slug: string, rootDir: string = process.cwd()) {
+  let matches = findTaskFiles(slug, rootDir);
+  const normalizedId = slug.toUpperCase();
+  const { tasksDir, completedDir, archiveTasksDir: archivedDir } = getTaskStorage(rootDir);
+  /** @param {string[]} candidateMatches */
+  const preferSameTaskInHigherPriorityDir = (candidateMatches: string[]) => {
+    if (candidateMatches.length < 2) {return null;}
+    const [preferred, ...rest] = candidateMatches;
+    return rest.every((match: string) => path.basename(match) === path.basename(preferred)) ? preferred : null;
+  };
+
+  /** @param {string[]} candidateFiles @param {string} targetId */
+  const findById = (candidateFiles: string[], targetId: string) => {
+    return candidateFiles.filter((f: string) => {
+      try {
+        const content = fs.readFileSync(f, 'utf8');
+        const idMatch = content.match(/^id:\s*([^\r\n]+)/m);
+        return idMatch && idMatch[1].trim().toUpperCase() === targetId;
+      } catch (_) {
+        return false;
+      }
+    });
+  };
+
+  if (matches.length === 0) {
+    // Hardening: If no prefix match, search ALL task files for an exact ID match
+    const allFiles = [
+      ...(fs.existsSync(tasksDir) ? fs.readdirSync(tasksDir).map(f => path.join(tasksDir, f)) : []),
+      ...(fs.existsSync(completedDir) ? fs.readdirSync(completedDir).map(f => path.join(completedDir, f)) : []),
+      ...(fs.existsSync(archivedDir) ? fs.readdirSync(archivedDir).map(f => path.join(archivedDir, f)) : []),
+    ].filter(f => f.endsWith('.md'));
+
+    const idMatches = findById(allFiles, normalizedId);
+    if (idMatches.length === 1) {
+      return { ok: true, taskFile: idMatches[0], matches: idMatches };
+    }
+
+    // Still no match? Try base task ID if slug has a suffix (e.g., task-1004-modern -> TASK-1004)
+    const baseTaskMatch = slug.match(/^(task-\d+)/i);
+    if (baseTaskMatch) {
+      const baseId = baseTaskMatch[1].toUpperCase();
+      const baseMatches = findById(allFiles, baseId);
+      if (baseMatches.length === 1) {
+        return { ok: true, taskFile: baseMatches[0], matches: baseMatches };
+      }
+      if (baseMatches.length > 1) {
+        const preferred = preferSameTaskInHigherPriorityDir(baseMatches);
+        if (preferred) {
+          return { ok: true, taskFile: preferred, matches: baseMatches };
+        }
+        return { ok: false, reason: 'ambiguous', matches: baseMatches };
+      }
+    }
+
+    return { ok: false, reason: 'missing', matches: idMatches };
+  }
+
+  if (matches.length === 1) {
+    // Even if one prefix match exists, verify it doesn't conflict with another ID match
+    // or just return it if it's the only one.
+    return { ok: true, taskFile: matches[0], matches };
+  }
+
+  // Preference 1: Exact frontmatter id: match (e.g., id: TASK-093)
+  const idMatches = findById(matches, normalizedId);
+
+  if (idMatches.length === 1) {
+    return { ok: true, taskFile: idMatches[0], matches: idMatches };
+  }
+  if (idMatches.length > 1) {
+    const preferred = preferSameTaskInHigherPriorityDir(idMatches);
+    if (preferred) {
+      return { ok: true, taskFile: preferred, matches: idMatches };
+    }
+    return { ok: false, reason: 'ambiguous', matches: idMatches };
+  }
+
+  // Fallback: If no ID matches but we have filename-prefix matches, 
+  // we only allow it if it's unambiguous.
+  return { ok: false, reason: 'ambiguous', matches };
+}
+
+/**
+ * @param {string} slug
+ * @param {string} [rootDir]
+ * @returns {string|undefined|null}
+ */
+function findTaskFile(slug: string, rootDir: string = process.cwd()) {
+  const result = resolveTaskFile(slug, rootDir);
+  return result.ok ? result.taskFile : null;
+}
+
+/**
+ * @param {{ok: boolean, taskFile?: string, matches: string[], reason?: string}} result
+ * @param {string} slug
+ * @param {Function} [log]
+ */
+function reportTaskResolution(result: {ok: boolean, taskFile?: string, matches: string[], reason?: string}, slug: string, log: Function = fmt.log.plain) {
+  if (result.ok) {return;}
+  const { tasksDir, completedDir } = getTaskStorage(process.cwd());
+  const taskHint = path.relative(process.cwd(), tasksDir).split(path.sep).join('/');
+  const completedHint = path.relative(process.cwd(), completedDir).split(path.sep).join('/');
+
+  if (result.reason === 'ambiguous') {
+    log(fmt.status('FAIL', `Backlog task resolution is ambiguous for slug: ${fmt.slug(slug)}`));
+    log(fmt.status('INFO', 'Multiple candidates found:'));
+    result.matches.forEach((m: string) => log(`  - ${m}`));
+    log(fmt.status('INFO', 'Repair: Ensure only one task has the filename prefix or matching "id:" frontmatter.'));
+  } else {
+    log(fmt.status('FAIL', `Backlog task for ${fmt.slug(slug)} not found in ${fmt.path(taskHint)}/ or ${fmt.path(completedHint)}/.`));
+    log(fmt.status('INFO', 'Create the task file first.'));
+    log(fmt.status('INFO', 'Repair: create the task with your task adapter, or add a markdown task file manually.'));
+    log(fmt.status('INFO', `Manual fallback: create ${fmt.path(`${taskHint}/${slug} - <title>.md`)} with frontmatter id ${fmt.bold(slug.toUpperCase())}.`));
+  }
+}
+
+/** @param {string} file @returns {string|null} */
+function taskIdFromFilename(file: string) {
+  // Extract ID from filename prefix (e.g., task-093 or task-093.01)
+  const filenameMatch = file.match(/^(task-\d+(?:\.\d+)?)/i);
+  return filenameMatch ? filenameMatch[1].toUpperCase() : null;
+}
+
+/**
+ * @param {string} [rootDir]
+ * @param {string} [slug]
+ * @returns {{file: string, type: string, taskId?: string, canonicalFile?: string}[]}
+ */
+function checkBacklogIntegrity(rootDir: string = process.cwd(), slug: string | null = null) {
+  const { tasksDir, completedDir, archiveTasksDir: archivedDir } = getTaskStorage(rootDir);
+  const issues = [];
+  const normalizedSlug = slug ? slug.toLowerCase() : null;
+
+  // Track where each task id lives so we can detect the same id appearing in
+  // both backlog/tasks/ and backlog/completed/ (or backlog/archive/) — the
+  // reorder-recreates-completed-task defect (TASK-1343). The completed/archive
+  // copy is canonical; a backlog/tasks/ copy alongside it is stale.
+  const tasksLocations = new Map();      // id -> rel path in tasks/
+  const canonicalLocations = new Map();  // id -> rel path in completed|archive
+
+  /** @param {string} dir @param {{canonical?: boolean}} [opts] */
+  const scan = (dir: string, { canonical = false }: { canonical?: boolean } = {}) => {
+    if (!fs.existsSync(dir)) {return;}
+    const files = fs.readdirSync(dir).filter((f: string) => f.endsWith('.md'));
+    for (const file of files) {
+      if (normalizedSlug && !file.toLowerCase().startsWith(normalizedSlug)) {
+        continue;
+      }
+      const filePath = path.join(dir, file);
+      const filenameId = taskIdFromFilename(file);
+      if (!filenameId) {continue;}
+      const relPath = path.relative(rootDir, filePath);
+
+      if (canonical) {
+        if (!canonicalLocations.has(filenameId)) {canonicalLocations.set(filenameId, relPath);}
+      } else if (!tasksLocations.has(filenameId)) {
+        tasksLocations.set(filenameId, relPath);
+      }
+
+      try {
+        const content = fs.readFileSync(filePath, 'utf8');
+
+        // Extract ID from frontmatter
+        const idMatch = content.match(/^id:\s*([^\r\n]+)/m);
+        if (idMatch) {
+          const frontmatterId = idMatch[1].trim().toUpperCase();
+          if (frontmatterId !== filenameId) {
+            issues.push({
+              file: relPath,
+              type: 'id-mismatch',
+              filenameId,
+              frontmatterId
+            });
+          }
+        }
+      } catch (_) {
+        // ignore read errors
+      }
+    }
+  };
+
+  scan(tasksDir);
+  scan(completedDir, { canonical: true });
+  scan(archivedDir, { canonical: true });
+
+  for (const [id, taskPath] of tasksLocations) {
+    const canonicalPath = canonicalLocations.get(id);
+    if (canonicalPath) {
+      issues.push({
+        file: taskPath,
+        type: 'duplicate-completed',
+        taskId: id,
+        canonicalFile: canonicalPath
+      });
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Drop backlog/tasks/ copies of task ids whose canonical record already lives
+ * in backlog/completed/ or backlog/archive/. Used to make any board mutation
+ * (reorder / ordinal write) completed- and archive-aware: the completed copy is
+ * treated as canonical and the stale backlog/tasks/ copy is removed. Returns
+ * the list of removed { taskId, file, canonicalFile } records. See TASK-1343.
+ */
+function pruneStaleBacklogDuplicates(rootDir = process.cwd()) {
+  const removed = [];
+  const duplicates = checkBacklogIntegrity(rootDir)
+    .filter(issue => issue.type === 'duplicate-completed');
+
+  for (const dup of duplicates) {
+    const absPath = path.join(rootDir, dup.file);
+    try {
+      if (fs.existsSync(absPath)) {
+        fs.rmSync(absPath);
+        removed.push({ taskId: dup.taskId, file: dup.file, canonicalFile: dup.canonicalFile });
+      }
+    } catch (_) {
+      // ignore removal errors; the integrity gate will still surface the duplicate
+    }
+  }
+
+  return removed;
+}
+
+/** @param {string} taskFilePath @returns {string|null} */
+function getTaskStatus(taskFilePath: string) {
+  if (!taskFilePath || !fs.existsSync(taskFilePath)) {return null;}
+  const content = fs.readFileSync(taskFilePath, 'utf8');
+
+  // Try YAML first
+  const yamlMatch = content.match(/^status:\s*([^\r\n]+)/m);
+  if (yamlMatch) {
+    return yamlMatch[1].trim().toLowerCase();
+  }
+
+  // Try rendered format
+  const statusMatch = content.match(/^Status:\s*(.*)$/m);
+  if (statusMatch) {
+    return statusMatch[1].replace(/^[○●\(\)\s]+/, '').trim().toLowerCase();
+  }
+
+  return null;
+}
+
+/** @param {string} taskFilePath @param {string} newStatus @returns {boolean} */
+function setTaskStatus(taskFilePath: string, newStatus: string) {
+  if (!taskFilePath || !fs.existsSync(taskFilePath)) {return false;}
+  let content = fs.readFileSync(taskFilePath, 'utf8');
+
+  // Update YAML
+  const yamlMatch = content.match(/^status:\s*([^\r\n]+)/m);
+  if (yamlMatch) {
+    content = content.replace(/^status:\s*.*$/m, `status: ${newStatus}`);
+  }
+
+  // Update rendered status line (e.g., "Status: ○ backlog")
+  // Map internal status to display markers if needed, but for now just text update
+  const statusMatch = content.match(/^Status:\s*(.*)$/m);
+  if (statusMatch) {
+    const original = statusMatch[1];
+    // Keep markers like ○ if they exist
+    const markerMatch = original.match(/^([○●\(\)\s]+)/);
+    const marker = markerMatch ? markerMatch[1] : '';
+    content = content.replace(/^Status:\s*.*$/m, `Status: ${marker}${newStatus}`);
+  }
+
+  fs.writeFileSync(taskFilePath, content, 'utf8');
+  return true;
+}
+
+/**
+ * @param {string} slug
+ * @param {string} [rootDir]
+ * @returns {boolean}
+ */
+function completeTask(slug: string, rootDir: string = process.cwd()): boolean {
+  const resolution = resolveTaskFile(slug, rootDir);
+  if (!resolution.ok) {return false;}
+
+  const taskFilePath = /** @type {string} */ (resolution.taskFile);
+  if (!taskFilePath) {return false;}
+  const fileName = path.basename(taskFilePath);
+  const { tasksDir, completedDir } = getTaskStorage(rootDir);
+
+  if (!taskFilePath.includes(tasksDir)) {
+    // Already in completed or somewhere else
+    setTaskStatus(taskFilePath, 'done');
+    return true;
+  }
+
+  if (!fs.existsSync(completedDir)) {
+    fs.mkdirSync(completedDir, { recursive: true });
+  }
+
+  const targetPath = path.join(completedDir, fileName);
+
+  // Set status before moving
+  setTaskStatus(taskFilePath, 'done');
+
+  fs.renameSync(taskFilePath, targetPath);
+  return true;
+}
+
+/**
+ * Internal helper to parse assignee families from YAML frontmatter content.
+ * Supports inline array, simple inline, and block formats.
+ */
+/**
+ * @param {string} content
+ * @returns {{matched: boolean, families: string[]}}
+ */
+function parseAssigneeFamilies(content: string) {
+  let families: string[] = /** @type {string[]} */ ([]);
+  let matched = false;
+
+  const lineMatch = content.match(/^assignee:[ \t]*(.*)$/m);
+  if (lineMatch) {
+    const rest = lineMatch[1].trim();
+    if (rest) {
+      matched = true;
+      // It's some kind of inline form
+      const rawValues = rest.startsWith('[') && rest.endsWith(']')
+        ? rest.slice(1, -1)
+        : rest;
+
+      families = rawValues.split(',')
+        .map((s: string) => s.trim().replace(/^['"]|['"]$/g, '').replace(/^@/, ''))
+        .filter((s: string) => s.length > 0);
+    }
+  }
+
+  if (!matched) {
+    // Try block form
+    const blockMatch = content.match(/^assignee:[ \t]*[\r\n]+((?:\s+-\s+.+[\r\n]*)+)/m);
+    if (blockMatch) {
+      matched = true;
+      families = blockMatch[1].split(/[\r\n]+/)
+        .map((line: string) => line.trim())
+        .filter((line: string) => line.startsWith('-'))
+        .map((line: string) => line.substring(1).trim().replace(/^['"]|['"]$/g, '').replace(/^@/, ''))
+        .filter((s: string) => s.length > 0);
+    }
+  }
+
+  return { matched, families };
+}
+
+/**
+ * @param {string} taskFilePath
+ * @param {string} message
+ * @param {string} [rootDir]
+ * @returns {boolean|null|void}
+ */
+function commitTaskFileUpdate(taskFilePath: string, message: string, rootDir: string = process.cwd()) {
+  if (!taskFilePath || !fs.existsSync(taskFilePath)) {return;}
+  // Run `git add/commit` against the worktree the caller intended (rootDir),
+  // not whichever branch process.cwd() happens to have checked out. All
+  // worktrees share one git object store, so the only thing that pins the
+  // commit to the correct mission branch is the `-C <rootDir>` working dir.
+  // Fall back to the task file's directory if rootDir isn't supplied or the
+  // task file lives outside it (defensive: keeps the add/commit consistent).
+  const gitDir = (rootDir && taskFilePath.startsWith(path.resolve(rootDir) + path.sep))
+    ? rootDir
+    : path.dirname(taskFilePath);
+  const relativeTaskPath = path.relative(gitDir, taskFilePath);
+  try {
+    git(['-C', gitDir, 'add', relativeTaskPath]);
+    const result = git(['-C', gitDir, 'commit', '-m', message]);
+    if (result.status !== 0) {
+      // If there's nothing to commit (e.g. no change), git commit exits with status 1
+      // but we should check if it was really a failure or just no-op.
+      const statusResult = git(['-C', gitDir, 'status', '--porcelain', relativeTaskPath]);
+      if (statusResult.stdout.trim() === '') {
+        return true; // No-op is success
+      }
+      fmt.log.warn(`Failed to commit task update: ${result.stderr}`);
+      return false;
+    }
+    return true;
+  } catch (/** @type {unknown} */ e) {
+    fmt.log.fail(`Git error during task update: ${(e as Error).message}`);
+    return false;
+  }
+}
+
+/** @param {string} taskFilePath @returns {boolean} */
+function clearTaskAgentAssignee(taskFilePath: string) {
+  if (!taskFilePath || !fs.existsSync(taskFilePath)) {return false;}
+  let content = fs.readFileSync(taskFilePath, 'utf8');
+  if (!content.match(/^assignee:/m)) {return false;}
+
+  const { families } = parseAssigneeFamilies(content);
+  const supportedAgents = getSupportedAgents();
+
+  // Separate agent families from human assignees
+  const agentFamilies = families.filter((f: string) => supportedAgents.includes(f.toLowerCase()));
+  const humanFamilies = families.filter((f: string) => !supportedAgents.includes(f.toLowerCase()));
+
+  // If there are no agent families to clear, nothing to do — preserve human assignees
+  if (agentFamilies.length === 0) {
+    // Write back the human-only assignee list
+    if (humanFamilies.length > 0) {
+      const hasBlockForm = content.match(/^assignee:[ \t]*[\r\n]+/);
+      if (humanFamilies.length === families.length) {
+        // All families were human; no change needed
+        return false;
+      }
+      // Remove agent families and write back human-only
+      let newAssigneeLine;
+      if (hasBlockForm) {
+        newAssigneeLine = 'assignee:\n' + humanFamilies.map((f: string) => `  - ${f}`).join('\n') + '\n';
+      } else {
+        newAssigneeLine = `assignee: [${humanFamilies.join(', ')}]`;
+      }
+
+      if (content.match(/^assignee:\s*\[.*?\]/m)) {
+        content = content.replace(/^assignee:\s*\[.*?\]/m, newAssigneeLine);
+      } else if (content.match(/^assignee:[ \t]*[\r\n]+((?:[ \t]+-[ \t]+.+[\r\n]*)+)/m)) {
+        content = content.replace(/^assignee:[ \t]*[\r\n]+((?:[ \t]+-[ \t]+.+[\r\n]*)+)/m, newAssigneeLine);
+      } else {
+        content = content.replace(/^assignee:[ \t]*.*$/m, newAssigneeLine);
+      }
+
+      fs.writeFileSync(taskFilePath, content, 'utf8');
+      return true;
+    }
+    return false;
+  }
+
+  const hasBlockForm = content.match(/^assignee:\s*\n((?:\s+-\s+.+\r?\n?)+)/m);
+
+  if (!hasBlockForm) {
+    // Inline array form: replace with human-only agents
+    const newAssignee = humanFamilies.length > 0 ? `[${humanFamilies.join(', ')}]` : '[]';
+    content = content.replace(/^assignee:\s*\[.*?\]/m, `assignee: ${newAssignee}`);
+  } else {
+    // Block form: remove agent lines, keep human lines
+    let newBlock = content.replace(/^assignee:[ \t]*[\r\n]+/m, 'assignee:\n');
+    const blockLines = newBlock.match(/^assignee:\n((?:\s+-\s+.+\n?)*)/m);
+    if (blockLines) {
+      const keptLines = blockLines[1].split('\n').filter(line => {
+        const m = line.match(/^\s+-\s+(.+)/);
+        if (!m) {return line.trim() === '';}
+        const family = m[1].trim().replace(/^['"]|['"]$/g, '');
+        return !supportedAgents.includes(family.toLowerCase());
+      }).join('\n');
+      newBlock = newBlock.replace(/^assignee:\n((?:\s+-\s+.+\n?)*)/m, 'assignee:\n' + keptLines);
+      if (newBlock.endsWith('assignee:\n') || newBlock.endsWith('assignee: \n') || newBlock.endsWith('assignee:\n\n')) {
+        newBlock = newBlock.replace(/assignee:\s*\n\s*$/, 'assignee: []\n');
+      }
+      content = newBlock;
+    } else {
+      content = content.replace(/^assignee:\s*\[.*?\]/m, `assignee: []`);
+    }
+  }
+
+  fs.writeFileSync(taskFilePath, content, 'utf8');
+  return true;
+}
+
+/**
+ * Transition a task to a new status, optionally enforcing an implementer,
+ * restoring a prior assignee, or clearing agent assignees,
+ * and commit the change to the mission branch.
+ */
+/**
+ * @param {string} slug
+ * @param {string} newStatus
+ * @param {{implementer?: string|null, clearAssignee?: boolean, rootDir?: string, log?: Function}} [opts]
+ * @returns {boolean}
+ */
+function transitionTask(slug: string, newStatus: string, { implementer = null, clearAssignee = false, rootDir = process.cwd(), log = fmt.log.plain }: { implementer?: string | null | undefined, clearAssignee?: boolean, rootDir?: string, log?: Function } = {} as any) {
+  const resolution = resolveTaskFile(slug, rootDir);
+  if (!resolution.ok) {
+    log(fmt.status('WARN', `Could not transition task ${fmt.slug(slug)}: ${resolution.reason}`));
+    return false;
+  }
+
+  const taskFile = resolution.taskFile as string;
+
+  // Guard: reject suffixed slugs (e.g. "task-1048-regress") to prevent
+  // resolveTaskFile's base-ID fallback from silently committing to the
+  // wrong task file when the slug's base ID does not match the resolved
+  // file's frontmatter id.  See TASK-1265 for the original incident.
+  const slugHasSuffix = /^(task-\d+)-/i.test(slug);
+  if (slugHasSuffix) {
+    log(fmt.status('WARN',
+      `Task ${fmt.slug(slug)} rejected: slug "${slug}" has a suffix; ` +
+      'use the exact task id instead to avoid committing to the wrong file.'));
+    return false;
+  }
+
+  let changed = false;
+
+  if (implementer) {
+    if (enforceTaskAssignee(taskFile, implementer)) {
+      changed = true;
+    }
+  } else if (clearAssignee) {
+    if (clearTaskAgentAssignee(taskFile)) {
+      changed = true;
+    }
+  }
+
+  const currentStatus = getTaskStatus(taskFile);
+  if (currentStatus !== newStatus) {
+    if (setTaskStatus(taskFile, newStatus)) {
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    let msg = `backlog(${slug}): transition to ${newStatus}`;
+    if (implementer) {msg += ` and implementer=${implementer}`;}
+    
+    if (commitTaskFileUpdate(taskFile, msg, rootDir)) {
+      log(fmt.status('PASS', `Task ${fmt.slug(slug)} transitioned to ${newStatus}${implementer ? ' (assignee=' + fmt.agent(implementer) + ')' : ''} and committed.`));
+      return true;
+    }
+    return false;
+  }
+
+  return true; // Already in the desired state
+}
+
+/** @param {string} taskFilePath @returns {string|null} */
+function getTaskAssignee(taskFilePath: string) {
+  if (!taskFilePath || !fs.existsSync(taskFilePath)) {return null;}
+  const content = fs.readFileSync(taskFilePath, 'utf8');
+  const { families } = parseAssigneeFamilies(content);
+  return families.length > 0 ? families[0] : null;
+}
+
+/** @param {string} taskFilePath @returns {string|null} */
+function getTaskImplementer(taskFilePath: string) {
+  if (!taskFilePath || !fs.existsSync(taskFilePath)) {return null;}
+  const content = fs.readFileSync(taskFilePath, 'utf8');
+  const { families } = parseAssigneeFamilies(content);
+
+  const normalizedFamilies = families.map((f: string) => f.toLowerCase());
+  const supportedAgents = getSupportedAgents();
+  return normalizedFamilies.find((f: string) => supportedAgents.includes(f)) || null;
+}
+
+/** @param {string} taskFilePath @param {string} field @returns {string|null} */
+function getTaskFrontmatterValue(taskFilePath: string, field: string) {
+  if (!taskFilePath || !fs.existsSync(taskFilePath)) {return null;}
+  const content = fs.readFileSync(taskFilePath, 'utf8');
+  const pattern = new RegExp(`^${field}:\\s*([^\\r\\n]+)`, 'mi');
+  const match = content.match(pattern);
+  if (!match) {return null;}
+  const value = match[1].trim().replace(/^['"]|['"]$/g, '');
+  return value || null;
+}
+
+const CLASSIFICATION_LABELS = new Set(['ai_sdlc', 'user_value', 'unknown']);
+
+/**
+ * Parse all labels from a task file's frontmatter, supporting both block
+ * and inline YAML formats. Returns a lowercased array of label strings.
+ * When both formats are present, block labels take precedence (inline is
+ * treated as a fallback when no block labels are found).
+ */
+/** @param {string} taskFilePath */
+function getTaskLabels(taskFilePath: string) {
+  if (!taskFilePath || !fs.existsSync(taskFilePath)) {return [];}
+  const content = fs.readFileSync(taskFilePath, 'utf8');
+
+  const blockMatch = content.match(/^labels:[ \t]*[\r\n]+((?:\s+-\s+.+[\r\n]*)+)/m);
+  if (blockMatch) {
+    return blockMatch[1].split(/[\r\n]+/)
+      .map(line => line.trim())
+      .filter(line => line.startsWith('-'))
+      .map(line => line.substring(1).trim().replace(/^['"]|['"]$/g, ''))
+      .map(s => s.toLowerCase())
+      .filter(s => s.length > 0);
+  }
+
+  const inlineMatch = content.match(/^labels:[ \t]*\[(.*?)\]/m);
+  if (inlineMatch) {
+    return inlineMatch[1].split(',')
+      .map(s => s.trim().replace(/^['"]|['"]$/g, ''))
+      .map(s => s.toLowerCase())
+      .filter(s => s.length > 0);
+  }
+
+  return [];
+}
+
+/** @param {string} taskFilePath */
+function getTaskClassification(taskFilePath: string) {
+  if (!taskFilePath || !fs.existsSync(taskFilePath)) {return null;}
+  const labels = getTaskLabels(taskFilePath);
+  const matches = new Set();
+  for (const label of labels) {
+    if (CLASSIFICATION_LABELS.has(label)) {matches.add(label);}
+  }
+  return matches.size === 1 ? [...matches][0] : null;
+}
+
+/** @param {string} taskFilePath */
+function hasBugLabel(taskFilePath: string) {
+  const labels = getTaskLabels(taskFilePath);
+  return labels.includes('bug');
+}
+
+
+/**
+ * @param {string} taskFilePath
+ * @param {string} agentFamily
+ * @param {{promote?: boolean}} [opts]
+ * @returns {boolean}
+ */
+function setTaskAssignee(taskFilePath: string, agentFamily: string, { promote = true }: { promote?: boolean } = {} as any) {
+  if (!taskFilePath || !fs.existsSync(taskFilePath)) {return false;}
+  let content = fs.readFileSync(taskFilePath, 'utf8');
+
+  const { matched, families } = parseAssigneeFamilies(content);
+
+  if (matched) {
+    const lowerAgentFamily = agentFamily.toLowerCase();
+    const existingIndex = families.findIndex((f: string) => f.toLowerCase() === lowerAgentFamily);
+
+    if (existingIndex !== 0) {
+      if (existingIndex !== -1) {
+        if (!promote) {return false;} // Already in the list, and we don't want to move it
+        // Remove existing to promote to first
+        families.splice(existingIndex, 1);
+      }
+
+      if (promote) {
+        families.unshift(agentFamily);
+      } else {
+        families.push(agentFamily);
+      }
+
+      const newAssignees = `assignee: [${families.join(', ')}]`;
+
+      // Replace whatever form was there with a normalized inline array form
+      if (content.match(/^assignee:\s*\[.*?\]/m)) {
+        content = content.replace(/^assignee:\s*\[.*?\]/m, newAssignees);
+      } else if (content.match(/^assignee:\s*\n((?:\s+-\s+.+\r?\n?)+)/m)) {
+        content = content.replace(/^assignee:\s*\n((?:\s+-\s+.+\r?\n?)+)/m, newAssignees + '\n');
+      } else {
+        // Fallback for simple form
+        content = content.replace(/^assignee:\s*.*$/m, newAssignees);
+      }
+
+      fs.writeFileSync(taskFilePath, content, 'utf8');
+      return true;
+    }
+    return false; // Already authoritative (at index 0)
+  }
+
+  // No assignee line exists — insert one after the id frontmatter line
+  const insertMatch = content.match(/^(id:.*)/m);
+  if (insertMatch && insertMatch.index !== undefined) {
+    const insertPos = insertMatch.index + insertMatch[0].length;
+    const newLine = '\nassignee: [' + agentFamily + ']';
+    content = content.slice(0, insertPos) + newLine + content.slice(insertPos);
+    fs.writeFileSync(taskFilePath, content, 'utf8');
+    return true;
+  }
+
+  return false;
+}
+
+/** @param {string} taskFilePath @param {string} agentFamily @returns {boolean} */
+function setTaskImplementer(taskFilePath: string, agentFamily: string) {
+  if (!taskFilePath || !fs.existsSync(taskFilePath)) {return false;}
+  let content = fs.readFileSync(taskFilePath, 'utf8');
+
+  const { matched, families } = parseAssigneeFamilies(content);
+  // Separate humans from recognized agents
+  const supportedAgents = getSupportedAgents();
+  const preservedFamilies = families.filter(f => !supportedAgents.includes(f.toLowerCase()));
+  // To ensure the new implementer is authoritative for getTaskImplementer(),
+  // it MUST be the first recognized agent in the list.
+  const nextFamilies = [agentFamily, ...preservedFamilies];
+
+  if (matched) {
+    const normalizedCurrent = families.map((f: string) => f.toLowerCase());
+    const normalizedNext = nextFamilies.map((f: string) => f.toLowerCase());
+    // Check if the first agent is already the one we want to set
+    if (normalizedCurrent.length > 0 && normalizedCurrent[0] === agentFamily.toLowerCase()) {
+      // If the rest of the list is also the same, it's a no-op
+      if (normalizedCurrent.length === normalizedNext.length &&
+          normalizedCurrent.every((f, /** @type {number} */ i) => f === normalizedNext[i])) {
+        return false;
+      }
+    }
+
+    const newAssignees = `assignee: [${nextFamilies.join(', ')}]`;
+
+    if (content.match(/^assignee:\s*\[.*?\]/m)) {
+      content = content.replace(/^assignee:\s*\[.*?\]/m, newAssignees);
+    } else if (content.match(/^assignee:\s*\n((?:\s+-\s+.+\r?\n?)+)/m)) {
+      content = content.replace(/^assignee:\s*\n((?:\s+-\s+.+\r?\n?)+)/m, newAssignees + '\n');
+    } else {
+      content = content.replace(/^assignee:\s*.*$/m, newAssignees);
+    }
+
+    fs.writeFileSync(taskFilePath, content, 'utf8');
+    return true;
+  }
+
+  const insertMatch = content.match(/^(id:.*)/m);
+  if (insertMatch && insertMatch.index !== undefined) {
+    const insertPos = insertMatch.index + insertMatch[0].length;
+    const newLine = '\nassignee: [' + agentFamily + ']';
+    content = content.slice(0, insertPos) + newLine + content.slice(insertPos);
+    fs.writeFileSync(taskFilePath, content, 'utf8');
+    return true;
+  }
+
+  return false;
+}
+
+/** @param {string} taskFilePath @param {string} agentFamily @returns {boolean} */
+function enforceTaskAssignee(taskFilePath: string, agentFamily: string) {
+  if (!taskFilePath || !fs.existsSync(taskFilePath)) {return false;}
+  let content = fs.readFileSync(taskFilePath, 'utf8');
+
+  const { families } = parseAssigneeFamilies(content);
+  if (families.length === 1 && families[0] === agentFamily) {return true;}
+
+  const newAssignee = `assignee: [${agentFamily}]`;
+
+  if (content.match(/^assignee:[ \t]*[\r\n]+((?:[ \t]+-[ \t]+.+[\r\n]*)+)/m)) {
+    content = content.replace(/^assignee:[ \t]*[\r\n]+((?:[ \t]+-[ \t]+.+[\r\n]*)+)/m, newAssignee + '\n');
+  } else if (content.match(/^assignee:[ \t]*.*$/m)) {
+    content = content.replace(/^assignee:[ \t]*.*$/m, newAssignee);
+  } else {
+    const insertMatch = content.match(/^(id:.*)/m);
+    if (!insertMatch || insertMatch.index === undefined) {return false;}
+    const insertPos = insertMatch.index + insertMatch[0].length;
+    content = content.slice(0, insertPos) + '\n' + newAssignee + content.slice(insertPos);
+  }
+
+  fs.writeFileSync(taskFilePath, content, 'utf8');
+  return true;
+}
+
+/** @param {string} taskFilePath @returns {string[]} */
+function getAcceptanceCriteria(taskFilePath: string) {
+  if (!taskFilePath || !fs.existsSync(taskFilePath)) {return [];}
+  const content = fs.readFileSync(taskFilePath, 'utf8');
+  const sectionMatch = content.match(/## Acceptance Criteria\s*\n([\s\S]*?)(?:\n## |\nDefinition of Done:|\n---\n|$)/);
+  if (!sectionMatch) {return [];}
+
+  return sectionMatch[1]
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => /^- \[[ xX]\]/.test(line));
+}
+
+
+export { findTaskFiles };
+export { findTaskFile };
+export { resolveTaskFile };
+export { reportTaskResolution };
+export { checkBacklogIntegrity };
+export { pruneStaleBacklogDuplicates };
+export { getTaskStorage };
+export { getTaskStatus };
+export { setTaskStatus };
+export { transitionTask };
+export { commitTaskFileUpdate };
+export { completeTask };
+export { getTaskAssignee };
+export { getTaskImplementer };
+export { getTaskFrontmatterValue };
+export { getTaskClassification };
+export { getTaskLabels };
+export { hasBugLabel };
+export { setTaskAssignee };
+export { setTaskImplementer };
+export { enforceTaskAssignee };
+export { getAcceptanceCriteria };
+export { parseAssigneeFamilies };
+export { clearTaskAgentAssignee };
+;