@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-workflow-state-helpers.mjs

@@ -0,0 +1,456 @@
+import { createWorkflowStateArtifactHelpers } from './runtime-workflow-state-artifacts.mjs';
+import { createWorkflowStateSummaryHelpers } from './runtime-workflow-state-summary.mjs';
+import { createWorkflowStateValidationHelpers } from './runtime-workflow-state-validation.mjs';
+
+export function createRuntimeWorkflowStateHelpers(deps) {
+  const {
+    fs,
+    path,
+    process,
+    ensureRoot,
+    workflowPath,
+    readWorkflow,
+    writeWorkflow,
+    writeJsonEnvelope,
+    artifactFileNames,
+    taskArtifactFileNames,
+    stateDirectoryName,
+    taskArtifactsDirectoryName,
+    allowedStatuses,
+    allowedTaskStatuses,
+    allowedReviewStatuses,
+    taskIdRequirement,
+    validateTaskId,
+  } = deps;
+
+  const {
+    asList,
+    scalarValue,
+    collectList,
+    validateState,
+    normalizeTasks,
+    tasksFromState,
+  } = createWorkflowStateValidationHelpers({
+    allowedStatuses,
+    allowedTaskStatuses,
+    allowedReviewStatuses,
+    taskIdRequirement,
+    validateTaskId,
+  });
+
+  const {
+    readinessCounts,
+    workflowSummary,
+    jsonTaskSummaries,
+  } = createWorkflowStateSummaryHelpers({
+    stateDirectoryName,
+    taskArtifactsDirectoryName,
+    taskArtifactFileNames,
+    allowedReviewStatuses,
+    validateTaskId,
+    asList,
+    tasksFromState,
+    taskSummaryStatus,
+    taskReadinessSummaryLine,
+    taskReadinessMap,
+    reviewSummaryStatus,
+  });
+
+  const {
+    markdownList,
+    generateArtifacts,
+    generateTaskArtifacts,
+    filterTaskArtifacts,
+  } = createWorkflowStateArtifactHelpers({
+    artifactFileNames,
+    taskArtifactFileNames,
+    asList,
+    tasksFromState,
+    taskReadinessMap,
+  });
+
+function taskSummaryStatus(tasks) {
+  if (tasks.length === 0) return 'not recorded';
+  if (tasks.some((task) => task.status === 'blocked')) return 'blocked';
+  if (tasks.some((task) => task.status === 'in_progress')) return 'in_progress';
+  if (tasks.every((task) => task.status === 'completed')) return 'completed';
+  return 'pending';
+}
+
+function taskReadinessDetails(tasks) {
+  const tasksById = new Map(tasks.map((task) => [task.id, task]));
+
+  return tasks.map((task) => {
+    const blockedBy = task.depends_on.filter((dependencyId) => {
+      return tasksById.get(dependencyId)?.status !== 'completed';
+    });
+
+    if (task.status === 'completed') {
+      return { id: task.id, readiness: 'completed', blockedBy: [] };
+    }
+    if (task.status === 'blocked') {
+      return { id: task.id, readiness: 'blocked', blockedBy };
+    }
+    if (blockedBy.length > 0) {
+      return { id: task.id, readiness: 'waiting', blockedBy };
+    }
+    return { id: task.id, readiness: 'ready', blockedBy: [] };
+  });
+}
+
+function taskReadinessSummaryLine(tasks) {
+  if (tasks.length === 0) return 'not recorded';
+  const counts = new Map([
+    ['ready', 0],
+    ['waiting', 0],
+    ['blocked', 0],
+    ['completed', 0],
+  ]);
+  for (const detail of taskReadinessDetails(tasks)) {
+    counts.set(detail.readiness, (counts.get(detail.readiness) || 0) + 1);
+  }
+  return [...counts.entries()].map(([status, count]) => `${status}=${count}`).join(', ');
+}
+
+function taskReadinessMap(tasks) {
+  return new Map(taskReadinessDetails(tasks).map((detail) => [detail.id, detail]));
+}
+
+function reviewSummaryStatus(tasks) {
+  if (tasks.length === 0) return 'not recorded';
+  if (tasks.some((task) => task.review_status === 'needs_fix')) return 'needs_fix';
+  if (tasks.some((task) => task.review_status === 'requested')) return 'requested';
+  if (tasks.some((task) => task.review_status === 'waived')) return 'waived';
+  if (tasks.every((task) => task.review_status === 'clean')) return 'clean';
+  return 'not_started';
+}
+
+function reviewSummaryLine(tasks) {
+  if (tasks.length === 0) return 'not recorded';
+  const counts = new Map();
+  for (const task of tasks) {
+    counts.set(task.review_status, (counts.get(task.review_status) || 0) + 1);
+  }
+  return [...allowedReviewStatuses]
+    .filter((status) => counts.has(status))
+    .map((status) => `${status}=${counts.get(status)}`)
+    .join(', ');
+}
+
+function normalizeJsonHandoff(handoff) {
+  const nested = handoff && typeof handoff.handoff === 'object' && handoff.handoff !== null ? handoff.handoff : {};
+
+  const state = {
+    current_skill: String(handoff?.current_skill || '').trim(),
+    next_skill: String(handoff?.next_skill || '').trim(),
+    reason: String(handoff?.reason || '').trim(),
+    status: 'handoff-recorded',
+    goal: String(nested.goal || '').trim(),
+    key_decisions: asList(nested.key_decisions),
+    scope: asList(nested.scope),
+    risks: asList(nested.risks),
+    acceptance: asList(nested.acceptance),
+    files: asList(nested.files),
+    evidence: asList(nested.evidence),
+    tasks: normalizeTasks(nested.tasks || handoff?.tasks || []),
+    stop_condition: String(handoff?.stop_condition || '').trim(),
+    updated_at: new Date().toISOString(),
+  };
+
+  validateState(state);
+  return state;
+}
+
+function parseJsonCandidate(candidate) {
+  const parsed = JSON.parse(candidate);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('JSON handoff must be an object');
+  }
+
+  return normalizeJsonHandoff(parsed);
+}
+
+function parseJsonHandoff(text) {
+  const trimmed = text.trim();
+  if (trimmed.startsWith('{')) {
+    return parseJsonCandidate(trimmed);
+  }
+
+  const fencedJson = text.match(/```json\s*\r?\n([\s\S]*?)\r?\n```/i);
+  if (!fencedJson) return null;
+
+  return parseJsonCandidate(fencedJson[1]);
+}
+
+function parseLegacyHandoff(text) {
+  const state = {
+    current_skill: scalarValue(text, 'current_skill'),
+    next_skill: scalarValue(text, 'next_skill'),
+    reason: scalarValue(text, 'reason'),
+    status: 'handoff-recorded',
+    goal: scalarValue(text, 'goal'),
+    key_decisions: collectList(text, 'key_decisions'),
+    scope: collectList(text, 'scope'),
+    risks: collectList(text, 'risks'),
+    acceptance: collectList(text, 'acceptance'),
+    files: collectList(text, 'files'),
+    evidence: collectList(text, 'evidence'),
+    tasks: [],
+    stop_condition: scalarValue(text, 'stop_condition'),
+    updated_at: new Date().toISOString(),
+  };
+
+  validateState(state);
+  return state;
+}
+
+function parseHandoffFile(file) {
+  if (!fs.existsSync(file)) throw new Error(`Handoff file not found: ${file}`);
+  const text = fs.readFileSync(file, 'utf8');
+
+  return parseJsonHandoff(text) || parseLegacyHandoff(text);
+}
+
+function printWorkflow(state) {
+  console.log('Vibecoding Runtime State');
+
+  if (!state) {
+    console.log('Status: idle');
+    console.log('State: none');
+    console.log('Manual action: record a Workflow Handoff explicitly to create local workflow state.');
+    return;
+  }
+
+  console.log(`Status: ${state.status || 'unknown'}`);
+  console.log(`Current skill: ${state.current_skill || 'none'}`);
+  console.log(`Next skill: ${state.next_skill || 'none'}`);
+  if (state.reason) console.log(`Reason: ${state.reason}`);
+  console.log(`Stop condition: ${state.stop_condition || 'none'}`);
+  if (state.updated_at) console.log(`Updated at: ${state.updated_at}`);
+  printList('Scope', asList(state.scope));
+  printList('Risks', asList(state.risks));
+  printList('Acceptance', asList(state.acceptance));
+  printList('Files', asList(state.files));
+  printList('Evidence', asList(state.evidence));
+  const tasks = tasksFromState(state);
+  if (tasks.length > 0) {
+    console.log(`Tasks: ${tasks.length} (${taskSummaryStatus(tasks)})`);
+    console.log(`Task readiness: ${taskReadinessSummaryLine(tasks)}`);
+    console.log(`Review: ${reviewSummaryLine(tasks)}`);
+    const readinessByTask = taskReadinessMap(tasks);
+    for (const task of tasks) {
+      const detail = readinessByTask.get(task.id);
+      const blockedBy = detail.blockedBy.length > 0 ? `; blocked_by=${detail.blockedBy.join(', ')}` : '';
+      console.log(`- ${task.id}: ${task.title} [${task.status}; readiness=${detail.readiness}${blockedBy}; review=${task.review_status}]`);
+    }
+  }
+  console.log('Action: status is read-only. No workflow state was changed.');
+}
+
+function runStatus(options) {
+  const state = readWorkflow(options.root);
+  if (options.json) {
+    const tasks = tasksFromState(state);
+    writeJsonEnvelope('status', {
+      mode: 'read-only',
+      ok: true,
+      state_present: Boolean(state),
+      summary: workflowSummary(state),
+      tasks: jsonTaskSummaries(tasks),
+      quality: [],
+      action: 'status is read-only. No workflow state was changed.',
+    });
+    return;
+  }
+  printWorkflow(state);
+}
+
+function handoffQuality(state) {
+  const checks = [
+    ['scope', 'scope is empty; record the active scope before continuing.'],
+    ['risks', 'risks is empty; record known risks or use none intentionally.'],
+    ['acceptance', 'acceptance is empty; define completion checks before implementation.'],
+    ['files', 'files is empty; add relevant files when available.'],
+    ['evidence', 'evidence is empty; add verification evidence when available.'],
+  ];
+  const items = checks.map(([key, warning]) => {
+    return asList(state[key]).length > 0
+      ? { status: 'ok', message: `${key} present` }
+      : { status: 'warn', message: warning };
+  });
+
+  const stopCondition = String(state.stop_condition || '').trim();
+  const hasStopCondition = stopCondition !== '' && stopCondition.toLowerCase() !== 'none';
+  const nextSkill = String(state.next_skill || '').trim();
+
+  if (hasStopCondition) {
+    items.push({ status: 'warn', message: 'stop_condition is set; resolve it before continuing.' });
+  }
+
+  if ((!nextSkill || nextSkill.toLowerCase() === 'none') && !hasStopCondition) {
+    items.push({ status: 'warn', message: 'next_skill is none but stop_condition is empty; record why the workflow stops.' });
+  }
+
+  return items;
+}
+
+function printHandoffQuality(items) {
+  console.log('Handoff quality:');
+  for (const item of items) {
+    console.log(`[${item.status}] ${item.message}`);
+  }
+}
+
+function runValidateHandoff(options) {
+  if (!options.fromFile) throw new Error('validate-handoff requires --from-file <path>');
+  ensureRoot(options.root);
+  const state = parseHandoffFile(options.fromFile);
+  const tasks = tasksFromState(state);
+  const quality = handoffQuality(state);
+
+  if (options.json) {
+    writeJsonEnvelope('validate-handoff', {
+      mode: 'dry-run',
+      ok: true,
+      state_present: false,
+      summary: workflowSummary(state),
+      tasks: jsonTaskSummaries(tasks),
+      quality,
+      action: 'handoff was validated. No workflow state was changed.',
+    });
+    return;
+  }
+
+  console.log('Vibecoding Runtime Handoff Validation');
+  console.log('Mode: dry-run');
+  console.log('Status: valid');
+  console.log(`Current skill: ${state.current_skill || 'none'}`);
+  console.log(`Next skill: ${state.next_skill || 'none'}`);
+  if (state.reason) console.log(`Reason: ${state.reason}`);
+  if (tasks.length > 0) {
+    console.log(`Tasks: ${tasks.length} (${taskSummaryStatus(tasks)})`);
+    console.log(`Task readiness: ${taskReadinessSummaryLine(tasks)}`);
+    console.log(`Review: ${reviewSummaryLine(tasks)}`);
+  }
+  printHandoffQuality(quality);
+  console.log('Action: handoff was validated. No workflow state was changed.');
+}
+
+function runRecordHandoff(options) {
+  if (options.json) throw new Error('record-handoff does not support --json in this stage');
+  if (!options.fromFile) throw new Error('record-handoff requires --from-file <path>');
+  ensureRoot(options.root);
+  const state = parseHandoffFile(options.fromFile);
+  writeWorkflow(options.root, state);
+  console.log(`Recorded handoff: ${path.relative(process.cwd(), workflowPath(options.root))}`);
+  console.log(`Current skill: ${state.current_skill || 'none'}`);
+  console.log(`Next skill: ${state.next_skill || 'none'}`);
+  printHandoffQuality(handoffQuality(state));
+  console.log('Action: handoff was recorded. No next skill was executed.');
+}
+
+function nextAdvice(state) {
+  if (!state) {
+    return {
+      status: 'idle',
+      currentSkill: 'none',
+      nextSkill: 'none',
+      manualAction: 'record a Workflow Handoff explicitly before asking for next.',
+    };
+  }
+
+  const stopCondition = String(state.stop_condition || '').trim();
+  const nextSkill = String(state.next_skill || '').trim();
+  const hasStopCondition = stopCondition !== '' && stopCondition.toLowerCase() !== 'none';
+  const tasks = tasksFromState(state);
+  const reviewStatus = reviewSummaryStatus(tasks);
+
+  if (hasStopCondition) {
+    return {
+      status: 'blocked',
+      currentSkill: state.current_skill || 'none',
+      nextSkill: nextSkill || 'none',
+      reason: state.reason,
+      stopCondition,
+      risks: asList(state.risks),
+      acceptance: asList(state.acceptance),
+      taskStatus: taskSummaryStatus(tasks),
+      taskReadiness: taskReadinessSummaryLine(tasks),
+      reviewStatus,
+      manualAction: 'resolve stop_condition before continuing.',
+    };
+  }
+
+  if (!nextSkill || nextSkill.toLowerCase() === 'none') {
+    return {
+      status: 'stopped',
+      currentSkill: state.current_skill || 'none',
+      nextSkill: 'none',
+      reason: state.reason,
+      risks: asList(state.risks),
+      acceptance: asList(state.acceptance),
+      taskStatus: taskSummaryStatus(tasks),
+      taskReadiness: taskReadinessSummaryLine(tasks),
+      reviewStatus,
+      manualAction: 'no next skill is suggested.',
+    };
+  }
+
+  return {
+    status: 'ready',
+    currentSkill: state.current_skill || 'none',
+    nextSkill,
+    reason: state.reason,
+    risks: asList(state.risks),
+    acceptance: asList(state.acceptance),
+    taskStatus: taskSummaryStatus(tasks),
+    taskReadiness: taskReadinessSummaryLine(tasks),
+    reviewStatus,
+    manualAction: reviewStatus === 'needs_fix'
+      ? 'resolve review feedback explicitly before finishing.'
+      : `invoke ${nextSkill} explicitly.`,
+  };
+}
+
+function printList(title, items) {
+  if (!items || items.length === 0) return;
+  console.log(`${title}:`);
+  for (const item of items) {
+    console.log(`- ${item}`);
+  }
+}
+
+  return {
+    asList,
+    validateState,
+    normalizeTasks,
+    workflowSummary,
+    tasksFromState,
+    jsonTaskSummaries,
+    scalarValue,
+    collectList,
+    readinessCounts,
+    taskSummaryStatus,
+    taskReadinessDetails,
+    taskReadinessSummaryLine,
+    taskReadinessMap,
+    reviewSummaryStatus,
+    reviewSummaryLine,
+    normalizeJsonHandoff,
+    parseJsonCandidate,
+    parseJsonHandoff,
+    parseLegacyHandoff,
+    parseHandoffFile,
+    runStatus,
+    runValidateHandoff,
+    runRecordHandoff,
+    printWorkflow,
+    handoffQuality,
+    printHandoffQuality,
+    nextAdvice,
+    markdownList,
+    generateArtifacts,
+    generateTaskArtifacts,
+    filterTaskArtifacts,
+  };
+}

package/tools/vibe-runtime/runtime-workflow-state-summary.mjs

@@ -0,0 +1,65 @@
+export function createWorkflowStateSummaryHelpers(deps) {
+  const { stateDirectoryName, taskArtifactsDirectoryName, taskArtifactFileNames, allowedReviewStatuses, validateTaskId, asList, tasksFromState, taskSummaryStatus, taskReadinessSummaryLine, taskReadinessMap, reviewSummaryStatus } = deps;
+
+  function taskArtifactRelativePath(taskId, fileName) {
+    validateTaskId(taskId);
+    return `${stateDirectoryName}/${taskArtifactsDirectoryName}/${taskId}/${fileName}`;
+  }
+
+  function readinessCounts(tasks) {
+    const counts = { ready: 0, waiting: 0, blocked: 0, completed: 0 };
+    for (const detail of taskReadinessMap(tasks).values()) counts[detail.readiness] = (counts[detail.readiness] || 0) + 1;
+    return counts;
+  }
+
+  function reviewCounts(tasks) {
+    const counts = {};
+    for (const status of allowedReviewStatuses) counts[status] = 0;
+    for (const task of tasks) counts[task.review_status] = (counts[task.review_status] || 0) + 1;
+    return counts;
+  }
+
+  function workflowSummary(state) {
+    if (!state) return null;
+    const tasks = tasksFromState(state);
+    return {
+      status: state.status || 'unknown',
+      current_skill: state.current_skill || 'none',
+      next_skill: state.next_skill || 'none',
+      reason: state.reason || '',
+      stop_condition: state.stop_condition || 'none',
+      goal: state.goal || '',
+      key_decisions: asList(state.key_decisions),
+      scope: asList(state.scope),
+      risks: asList(state.risks),
+      acceptance: asList(state.acceptance),
+      files: asList(state.files),
+      evidence: asList(state.evidence),
+      updated_at: state.updated_at || '',
+      task_status: taskSummaryStatus(tasks),
+      task_readiness: taskReadinessSummaryLine(tasks),
+      task_readiness_counts: readinessCounts(tasks),
+      review_status: reviewSummaryStatus(tasks),
+      review_counts: reviewCounts(tasks),
+    };
+  }
+
+  function jsonTaskSummaries(tasks, readinessSourceTasks = tasks) {
+    const readinessByTask = taskReadinessMap(readinessSourceTasks);
+    return tasks.map((task) => {
+      const detail = readinessByTask.get(task.id);
+      return {
+        id: task.id,
+        title: task.title,
+        status: task.status,
+        readiness: detail.readiness,
+        blocked_by: detail.blockedBy,
+        depends_on: task.depends_on,
+        review_status: task.review_status,
+        artifact_paths: Object.fromEntries(Object.values(taskArtifactFileNames).map((fileName) => [fileName, taskArtifactRelativePath(task.id, fileName)])),
+      };
+    });
+  }
+
+  return { readinessCounts, workflowSummary, jsonTaskSummaries };
+}

package/tools/vibe-runtime/runtime-workflow-state-validation.mjs

@@ -0,0 +1,104 @@
+export function createWorkflowStateValidationHelpers(deps) {
+  const { allowedStatuses, allowedTaskStatuses, allowedReviewStatuses, taskIdRequirement, validateTaskId } = deps;
+
+  function asList(value) {
+    if (Array.isArray(value)) return value.map((item) => String(item));
+    if (value === undefined || value === null || value === '') return [];
+    return [String(value)];
+  }
+
+  function scalarValue(text, key) {
+    const match = text.match(new RegExp(`^(?:\\uFEFF)?${key}:\\s*(.*)$`, 'm'));
+    return match ? match[1].trim() : '';
+  }
+
+  function collectList(text, key) {
+    const result = [];
+    let collecting = false;
+    let baseIndent = 0;
+    for (const line of text.split(/\r?\n/)) {
+      const keyMatch = line.match(new RegExp(`^(\\s*)${key}:\\s*$`));
+      if (keyMatch) {
+        collecting = true;
+        baseIndent = keyMatch[1].length;
+        continue;
+      }
+      if (!collecting) continue;
+      const indent = line.match(/^\s*/)?.[0].length ?? 0;
+      const itemMatch = line.match(/^\s*-\s+(.*)$/);
+      if (itemMatch && indent > baseIndent) {
+        result.push(itemMatch[1].trim());
+        continue;
+      }
+      if (line.trim() === '') continue;
+      if (indent <= baseIndent && /^\S/.test(line)) break;
+    }
+    return result;
+  }
+
+  function validateState(state) {
+    const missing = ['current_skill', 'next_skill', 'status'].filter((key) => !state[key]);
+    if (missing.length > 0) throw new Error(`Handoff missing required field(s): ${missing.join(', ')}`);
+    if (!allowedStatuses.has(state.status)) throw new Error(`Invalid handoff status: ${state.status}`);
+    for (const key of ['scope', 'risks', 'acceptance', 'files', 'evidence']) {
+      if (!Array.isArray(state[key])) throw new Error(`Handoff field must be a list: ${key}`);
+    }
+    if (state.key_decisions !== undefined && !Array.isArray(state.key_decisions)) throw new Error('Handoff field must be a list: key_decisions');
+    if (state.tasks !== undefined) state.tasks = normalizeTasks(state.tasks);
+  }
+
+  function normalizeTask(rawTask, index) {
+    const fallbackId = `task-${index + 1}`;
+    const hasExplicitId = Object.hasOwn(rawTask || {}, 'id');
+    const explicitId = hasExplicitId ? String(rawTask?.id) : '';
+    if (hasExplicitId && explicitId.length === 0) throw new Error(`Invalid task id: empty. ${taskIdRequirement}`);
+    const id = explicitId || fallbackId;
+    const task = { id, title: String(rawTask?.title || rawTask?.name || id).trim() || id, status: String(rawTask?.status || 'pending').trim() || 'pending', review_status: String(rawTask?.review_status || 'not_started').trim() || 'not_started', files: asList(rawTask?.files), depends_on: asList(rawTask?.depends_on), acceptance: asList(rawTask?.acceptance), evidence: asList(rawTask?.evidence), risks: asList(rawTask?.risks), notes: asList(rawTask?.notes), review_notes: asList(rawTask?.review_notes), review_evidence: asList(rawTask?.review_evidence), review_risks: asList(rawTask?.review_risks), review_waiver: String(rawTask?.review_waiver || '').trim(), stop_condition: String(rawTask?.stop_condition || '').trim() };
+    validateTask(task);
+    return task;
+  }
+
+  function normalizeTasks(tasks) {
+    const normalized = (Array.isArray(tasks) ? tasks : asList(tasks)).map((task, index) => typeof task === 'object' && task !== null ? normalizeTask(task, index) : normalizeTask({ title: task }, index));
+    const seenIds = new Set();
+    for (const task of normalized) {
+      if (seenIds.has(task.id)) throw new Error(`Duplicate task id: ${task.id}. Task ids must be unique within a workflow handoff.`);
+      seenIds.add(task.id);
+    }
+    validateTaskDependencies(normalized);
+    return normalized;
+  }
+
+  function validateTaskDependencies(tasks) {
+    const taskIds = new Set(tasks.map((task) => task.id));
+    const graph = new Map(tasks.map((task) => [task.id, task.depends_on]));
+    const visited = new Set();
+    const visiting = new Set();
+    for (const task of tasks) for (const dependencyId of task.depends_on) {
+      validateTaskId(dependencyId);
+      if (!taskIds.has(dependencyId)) throw new Error(`Unknown task dependency for ${task.id}: ${dependencyId}`);
+      if (dependencyId === task.id) throw new Error(`Self task dependency is not allowed for ${task.id}`);
+    }
+    function visit(taskId, pathStack) {
+      if (visiting.has(taskId)) throw new Error(`Cyclic task dependency detected: ${pathStack.slice(pathStack.indexOf(taskId)).join(' -> ')}`);
+      if (visited.has(taskId)) return;
+      visiting.add(taskId);
+      for (const dependencyId of graph.get(taskId) || []) visit(dependencyId, [...pathStack, dependencyId]);
+      visiting.delete(taskId);
+      visited.add(taskId);
+    }
+    for (const task of tasks) visit(task.id, [task.id]);
+  }
+
+  function validateTask(task) {
+    const missing = ['id', 'title', 'status'].filter((key) => !task[key]);
+    if (missing.length > 0) throw new Error(`Task missing required field(s): ${missing.join(', ')}`);
+    validateTaskId(task.id);
+    if (!allowedTaskStatuses.has(task.status)) throw new Error(`Invalid task status for ${task.id}: ${task.status}`);
+    if (!allowedReviewStatuses.has(task.review_status)) throw new Error(`Invalid task review_status for ${task.id}: ${task.review_status}`);
+    if (task.review_status === 'waived' && !task.review_waiver) throw new Error(`Task review waiver required for ${task.id} when review_status is waived`);
+    for (const key of ['files', 'depends_on', 'acceptance', 'evidence', 'risks', 'notes', 'review_notes', 'review_evidence', 'review_risks']) if (!Array.isArray(task[key])) throw new Error(`Task field must be a list: ${key}`);
+  }
+
+  return { asList, scalarValue, collectList, validateState, normalizeTasks, tasksFromState: (state) => normalizeTasks(state?.tasks || []) };
+}