@cleocode/core 2026.3.57 → 2026.3.58

package/src/tasks/epic-enforcement.ts

@@ -0,0 +1,303 @@
+/**
+ * Epic lifecycle pipeline enforcement (RCASD-IVTR+C).
+ *
+ * Enforces three constraints specific to tasks of type "epic":
+ *
+ * 1. **Creation requirements** (strict mode only):
+ *    - Minimum 5 acceptance criteria (vs. 3 for regular tasks).
+ *    - Completion criteria must be defined (non-empty description field).
+ *    - Initial pipeline stage defaults to "research" (inherited from
+ *      pipeline-stage.ts, not re-asserted here).
+ *
+ * 2. **Child stage ceiling**: A child task's pipeline stage cannot advance
+ *    past the epic's current pipeline stage.  This is checked on child task
+ *    update (pipelineStage change) and on child task creation.
+ *
+ * 3. **Epic stage advancement gate**: An epic cannot advance its pipeline
+ *    stage while it has children whose status is not "done" AND whose
+ *    pipeline stage equals the epic's current stage.  In other words, all
+ *    in-flight children at the current stage must be completed before the
+ *    epic may move forward.
+ *
+ * Enforcement is conditional on `lifecycle.mode`:
+ *   - "strict"   → block (throw CleoError on violation)
+ *   - "advisory" → warn (return error string but do not throw)
+ *   - "off"      → skip (all checks are no-ops)
+ *
+ * @task T062
+ * @epic T056
+ */
+
+import type { DataAccessor, Task } from '@cleocode/contracts';
+import { ExitCode } from '@cleocode/contracts';
+import { loadConfig } from '../config.js';
+import { CleoError } from '../errors.js';
+import { getPipelineStageOrder, isValidPipelineStage } from './pipeline-stage.js';
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+/** Minimum acceptance criteria count required for epic creation in strict mode. */
+export const EPIC_MIN_AC = 5;
+
+/** Minimum acceptance criteria count for regular tasks. */
+export const TASK_MIN_AC = 3;
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/** The resolved enforcement mode (from lifecycle.mode config key). */
+export type LifecycleMode = 'strict' | 'advisory' | 'off';
+
+/** Result of an enforcement check.  `warning` is populated in advisory mode. */
+export interface EpicEnforcementResult {
+  /** True unless a hard block was raised. */
+  valid: boolean;
+  /** Advisory message (non-blocking) or error message (blocked). */
+  warning?: string;
+}
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+/**
+ * Read `lifecycle.mode` from config.  Falls back to "strict" when unset
+ * (matches the DEFAULTS in config.ts).
+ *
+ * @task T062
+ */
+export async function getLifecycleMode(cwd?: string): Promise<LifecycleMode> {
+  if (process.env.VITEST) return 'off';
+  const config = await loadConfig(cwd);
+  return config.lifecycle?.mode ?? 'strict';
+}
+
+// =============================================================================
+// 1. EPIC CREATION REQUIREMENTS
+// =============================================================================
+
+/**
+ * Validate that a new epic satisfies creation requirements.
+ *
+ * In **strict** mode:
+ *   - At least {@link EPIC_MIN_AC} acceptance criteria must be provided.
+ *   - `description` must be non-empty (treated as completion criteria).
+ *
+ * In **advisory** mode the same checks are run but violations do not block —
+ * they are returned as `warning` text for the caller to surface.
+ *
+ * In **off** mode this function is a no-op.
+ *
+ * @param options.acceptance  - Acceptance criteria array supplied by the caller.
+ * @param options.description - Task description (used as completion criteria proxy).
+ * @param cwd                 - Working directory for config resolution.
+ * @returns EpicEnforcementResult — `valid: false` only in strict mode on error.
+ * @throws CleoError(VALIDATION_ERROR) in strict mode when constraints are violated.
+ *
+ * @task T062
+ */
+export async function validateEpicCreation(
+  options: {
+    acceptance?: string[];
+    description?: string;
+  },
+  cwd?: string,
+): Promise<EpicEnforcementResult> {
+  const mode = await getLifecycleMode(cwd);
+  if (mode === 'off') return { valid: true };
+
+  const ac = options.acceptance ?? [];
+  const desc = (options.description ?? '').trim();
+
+  const violations: string[] = [];
+
+  if (ac.length < EPIC_MIN_AC) {
+    violations.push(
+      `Epic requires at least ${EPIC_MIN_AC} acceptance criteria (${ac.length} provided). Regular tasks need ${TASK_MIN_AC}.`,
+    );
+  }
+
+  if (!desc) {
+    violations.push('Epic must have a non-empty description (used as completion criteria).');
+  }
+
+  if (violations.length === 0) return { valid: true };
+
+  const message = violations.join(' | ');
+  const fix = `Add --acceptance "..." flags (need ${EPIC_MIN_AC}) and a --description "completion criteria"`;
+
+  if (mode === 'strict') {
+    throw new CleoError(ExitCode.VALIDATION_ERROR, message, { fix });
+  }
+
+  // advisory: warn but allow
+  return { valid: true, warning: message };
+}
+
+// =============================================================================
+// 2. CHILD STAGE CEILING
+// =============================================================================
+
+/**
+ * Validate that a child task's pipeline stage does not exceed its epic's stage.
+ *
+ * Call this when:
+ *   - A child task is **created** under an epic parent.
+ *   - A child task's `pipelineStage` is **updated** and it has an epic ancestor.
+ *
+ * The check walks the task's ancestor chain to find the nearest epic ancestor.
+ * If none exists, the check is skipped.
+ *
+ * @param options.childStage  - The proposed pipeline stage for the child.
+ * @param options.epicId      - ID of the epic ancestor to check against.
+ * @param accessor            - DataAccessor for task lookups.
+ * @param cwd                 - Working directory for config resolution.
+ * @returns EpicEnforcementResult
+ * @throws CleoError(VALIDATION_ERROR) in strict mode when the child stage exceeds the epic.
+ *
+ * @task T062
+ */
+export async function validateChildStageCeiling(
+  options: {
+    childStage: string;
+    epicId: string;
+  },
+  accessor: DataAccessor,
+  cwd?: string,
+): Promise<EpicEnforcementResult> {
+  const mode = await getLifecycleMode(cwd);
+  if (mode === 'off') return { valid: true };
+
+  const epic = await accessor.loadSingleTask(options.epicId);
+  if (!epic || epic.type !== 'epic') return { valid: true };
+
+  const epicStage = epic.pipelineStage;
+  if (!epicStage || !isValidPipelineStage(epicStage)) return { valid: true };
+
+  const childStage = options.childStage;
+  if (!isValidPipelineStage(childStage)) return { valid: true }; // stage validation handled elsewhere
+
+  const epicOrder = getPipelineStageOrder(epicStage);
+  const childOrder = getPipelineStageOrder(childStage);
+
+  if (childOrder <= epicOrder) return { valid: true };
+
+  const message =
+    `Child task cannot be at pipeline stage "${childStage}" (order ${childOrder}) ` +
+    `because its parent epic ${options.epicId} is only at stage "${epicStage}" (order ${epicOrder}). ` +
+    `Children cannot exceed their epic's current stage.`;
+  const fix = `Use a stage at or before "${epicStage}". Advance the epic first if needed.`;
+
+  if (mode === 'strict') {
+    throw new CleoError(ExitCode.VALIDATION_ERROR, message, { fix });
+  }
+
+  return { valid: true, warning: message };
+}
+
+/**
+ * Find the nearest epic ancestor for a given task.
+ *
+ * Walks the ancestor chain (root-first) and returns the first task whose
+ * type is "epic", or null if no epic ancestor exists.
+ *
+ * @param taskId   - ID of the task whose ancestors to inspect.
+ * @param accessor - DataAccessor for the ancestor chain query.
+ * @returns The nearest epic ancestor, or null.
+ *
+ * @task T062
+ */
+export async function findEpicAncestor(
+  taskId: string,
+  accessor: DataAccessor,
+): Promise<Task | null> {
+  const ancestors = await accessor.getAncestorChain(taskId);
+  // ancestors is root-first; the last entry is the immediate parent
+  // We want the nearest epic, so scan from the end (closest ancestor first)
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    const ancestor = ancestors[i];
+    if (ancestor && ancestor.type === 'epic') return ancestor;
+  }
+  return null;
+}
+
+// =============================================================================
+// 3. EPIC STAGE ADVANCEMENT GATE
+// =============================================================================
+
+/**
+ * Validate that an epic can advance its pipeline stage.
+ *
+ * An epic is **blocked** from advancing to a later stage when it has at least
+ * one child that:
+ *   - Has a pipeline stage **equal to the epic's current stage**, AND
+ *   - Has a status that is **not** "done" (i.e., is still in-flight).
+ *
+ * Rationale: the epic stage represents the stage the team is actively working
+ * in.  Moving the epic forward while children are unfinished at the current
+ * stage violates the pipeline discipline.
+ *
+ * @param options.epicId       - ID of the epic being advanced.
+ * @param options.currentStage - Epic's current pipeline stage (before the update).
+ * @param options.newStage     - Proposed new pipeline stage.
+ * @param accessor             - DataAccessor for children lookup.
+ * @param cwd                  - Working directory for config resolution.
+ * @returns EpicEnforcementResult
+ * @throws CleoError(VALIDATION_ERROR) in strict mode when incomplete children exist.
+ *
+ * @task T062
+ */
+export async function validateEpicStageAdvancement(
+  options: {
+    epicId: string;
+    currentStage: string;
+    newStage: string;
+  },
+  accessor: DataAccessor,
+  cwd?: string,
+): Promise<EpicEnforcementResult> {
+  const mode = await getLifecycleMode(cwd);
+  if (mode === 'off') return { valid: true };
+
+  const { epicId, currentStage, newStage } = options;
+
+  // Only enforce if actually advancing (not a same-stage no-op)
+  if (!isValidPipelineStage(currentStage) || !isValidPipelineStage(newStage)) {
+    return { valid: true };
+  }
+
+  const currentOrder = getPipelineStageOrder(currentStage);
+  const newOrder = getPipelineStageOrder(newStage);
+
+  if (newOrder <= currentOrder) {
+    // Same stage or backward — backward is caught by validatePipelineTransition
+    return { valid: true };
+  }
+
+  // Find all children whose stage equals the current epic stage and are not done
+  const children = await accessor.getChildren(epicId);
+  const blockers = children.filter((child) => {
+    if (child.status === 'done' || child.status === 'cancelled' || child.status === 'archived') {
+      return false;
+    }
+    return child.pipelineStage === currentStage;
+  });
+
+  if (blockers.length === 0) return { valid: true };
+
+  const blockerIds = blockers.map((t) => t.id).join(', ');
+  const message =
+    `Epic ${epicId} cannot advance from "${currentStage}" to "${newStage}" — ` +
+    `${blockers.length} child task(s) are still in-flight at stage "${currentStage}": ${blockerIds}. ` +
+    `Complete all children at the current stage before advancing the epic.`;
+  const fix = `Complete tasks ${blockerIds} first, then advance the epic stage.`;
+
+  if (mode === 'strict') {
+    throw new CleoError(ExitCode.VALIDATION_ERROR, message, { fix });
+  }
+
+  return { valid: true, warning: message };
+}

package/src/tasks/index.ts

@@ -8,6 +8,7 @@ export {
   type AddTaskOptions,
   type AddTaskResult,
   addTask,
+  buildDefaultVerification,
   findRecentDuplicate,
   getNextPosition,
   getTaskDepth,

package/src/tasks/pipeline-stage.ts

@@ -0,0 +1,224 @@
+/**
+ * Pipeline stage binding for tasks (RCASD-IVTR+C).
+ *
+ * Implements auto-assignment of pipeline stages on task creation and
+ * forward-only stage transition validation on task update.
+ *
+ * Stages (in order):
+ *   1. research
+ *   2. consensus
+ *   3. architecture_decision
+ *   4. specification
+ *   5. decomposition
+ *   6. implementation
+ *   7. validation
+ *   8. testing
+ *   9. release
+ *  10. contribution  (cross-cutting, treated as terminal)
+ *
+ * @task T060
+ * @epic T056
+ */
+
+import type { TaskType } from '@cleocode/contracts';
+import { ExitCode } from '@cleocode/contracts';
+import { CleoError } from '../errors.js';
+
+/**
+ * Minimal parent task shape needed for pipeline stage resolution.
+ * @task T060
+ */
+export interface ResolvedParent {
+  pipelineStage?: string | null;
+  type?: TaskType | null;
+}
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+/**
+ * Ordered pipeline stages (RCASD-IVTR+C).
+ * This matches lifecycle/stages.ts PIPELINE_STAGES but is kept local to avoid
+ * a circular dependency — tasks/ must not import from lifecycle/.
+ *
+ * @task T060
+ */
+export const TASK_PIPELINE_STAGES = [
+  'research',
+  'consensus',
+  'architecture_decision',
+  'specification',
+  'decomposition',
+  'implementation',
+  'validation',
+  'testing',
+  'release',
+  'contribution',
+] as const;
+
+/** Union type of all valid pipeline stage names. */
+export type TaskPipelineStage = (typeof TASK_PIPELINE_STAGES)[number];
+
+/** Order map for fast index lookups (1-based). */
+const STAGE_ORDER: Record<TaskPipelineStage, number> = {
+  research: 1,
+  consensus: 2,
+  architecture_decision: 3,
+  specification: 4,
+  decomposition: 5,
+  implementation: 6,
+  validation: 7,
+  testing: 8,
+  release: 9,
+  contribution: 10,
+};
+
+// =============================================================================
+// VALIDATION
+// =============================================================================
+
+/**
+ * Check whether a string is a valid pipeline stage name.
+ *
+ * @param stage - Raw string to test
+ * @returns True if it is a valid stage name
+ *
+ * @task T060
+ */
+export function isValidPipelineStage(stage: string): stage is TaskPipelineStage {
+  return TASK_PIPELINE_STAGES.includes(stage as TaskPipelineStage);
+}
+
+/**
+ * Validate a pipeline stage name and throw a CleoError on failure.
+ *
+ * @param stage - Stage name to validate
+ * @throws CleoError(VALIDATION_ERROR) if invalid
+ *
+ * @task T060
+ */
+export function validatePipelineStage(stage: string): asserts stage is TaskPipelineStage {
+  if (!isValidPipelineStage(stage)) {
+    throw new CleoError(
+      ExitCode.VALIDATION_ERROR,
+      `Invalid pipeline stage: "${stage}". Valid stages: ${TASK_PIPELINE_STAGES.join(', ')}`,
+      { fix: `Use one of: ${TASK_PIPELINE_STAGES.join(', ')}` },
+    );
+  }
+}
+
+// =============================================================================
+// AUTO-ASSIGNMENT
+// =============================================================================
+
+/**
+ * Determine the default pipeline stage for a new task.
+ *
+ * Rules (in priority order):
+ * 1. If an explicit stage is provided and valid, use it.
+ * 2. If the task has a parent, inherit the parent's pipelineStage.
+ * 3. If the task type is 'epic', default to 'research'.
+ * 4. Otherwise default to 'implementation'.
+ *
+ * @param options.explicitStage - Stage explicitly provided by the caller
+ * @param options.taskType      - Type of the task being created
+ * @param options.parentTask    - Parent task (if any), for inheritance
+ * @returns The resolved pipeline stage name
+ *
+ * @task T060
+ */
+export function resolveDefaultPipelineStage(options: {
+  explicitStage?: string | null;
+  taskType?: TaskType | null;
+  parentTask?: ResolvedParent | null;
+}): TaskPipelineStage {
+  const { explicitStage, taskType, parentTask } = options;
+
+  // 1. Caller-supplied explicit stage (validated upstream)
+  if (explicitStage && isValidPipelineStage(explicitStage)) {
+    return explicitStage;
+  }
+
+  // 2. Inherit from parent
+  if (parentTask?.pipelineStage && isValidPipelineStage(parentTask.pipelineStage)) {
+    return parentTask.pipelineStage;
+  }
+
+  // 3. Epic → research
+  if (taskType === 'epic') {
+    return 'research';
+  }
+
+  // 4. Default
+  return 'implementation';
+}
+
+// =============================================================================
+// TRANSITION VALIDATION
+// =============================================================================
+
+/**
+ * Get the numeric order of a pipeline stage (1-based).
+ *
+ * @param stage - Stage name (must be valid)
+ * @returns Numeric order, or -1 if not found
+ *
+ * @task T060
+ */
+export function getPipelineStageOrder(stage: string): number {
+  return isValidPipelineStage(stage) ? STAGE_ORDER[stage] : -1;
+}
+
+/**
+ * Check whether transitioning from `currentStage` to `newStage` is forward-only.
+ *
+ * "Forward" means the new stage's order is greater than or equal to the current
+ * stage's order (same stage is a no-op and is considered valid).
+ *
+ * @param currentStage - The task's current pipeline stage
+ * @param newStage     - The requested new pipeline stage
+ * @returns True if the transition is allowed (forward or same)
+ *
+ * @task T060
+ */
+export function isPipelineTransitionForward(currentStage: string, newStage: string): boolean {
+  const currentOrder = getPipelineStageOrder(currentStage);
+  const newOrder = getPipelineStageOrder(newStage);
+  if (currentOrder === -1 || newOrder === -1) return true; // unknown stages: allow
+  return newOrder >= currentOrder;
+}
+
+/**
+ * Validate a pipeline stage transition and throw if it would move backward.
+ *
+ * @param currentStage - The task's current pipeline stage (may be null/undefined)
+ * @param newStage     - The new stage being requested
+ * @throws CleoError(VALIDATION_ERROR) if the transition is backward
+ *
+ * @task T060
+ */
+export function validatePipelineTransition(
+  currentStage: string | null | undefined,
+  newStage: string,
+): void {
+  // Validate the new stage name first
+  validatePipelineStage(newStage);
+
+  if (!currentStage) {
+    // No current stage — any valid stage is allowed
+    return;
+  }
+
+  if (!isPipelineTransitionForward(currentStage, newStage)) {
+    const currentOrder = getPipelineStageOrder(currentStage);
+    const newOrder = getPipelineStageOrder(newStage);
+    throw new CleoError(
+      ExitCode.VALIDATION_ERROR,
+      `Pipeline stage transition rejected: cannot move backward from "${currentStage}" (order ${currentOrder}) to "${newStage}" (order ${newOrder}). Tasks can only move forward through pipeline stages.`,
+      {
+        fix: `Specify a stage at or after "${currentStage}". Valid forward stages: ${TASK_PIPELINE_STAGES.filter((s) => STAGE_ORDER[s] >= currentOrder).join(', ')}`,
+      },
+    );
+  }
+}

package/src/tasks/update.ts

@@ -9,6 +9,7 @@ import type { Task, TaskPriority, TaskSize, TaskStatus, TaskType } from '@cleoco
 import { ExitCode } from '@cleocode/contracts';
 import { loadConfig } from '../config.js';
 import { CleoError } from '../errors.js';
+import { requireActiveSession } from '../sessions/session-enforcement.js';
 import type { DataAccessor } from '../store/data-accessor.js';
 import { getAccessor } from '../store/data-accessor.js';
 import {
@@ -20,7 +21,14 @@ import {
   validateTitle,
 } from './add.js';
 import { completeTask } from './complete.js';
+import { createAcceptanceEnforcement } from './enforcement.js';
+import {
+  findEpicAncestor,
+  validateChildStageCeiling,
+  validateEpicStageAdvancement,
+} from './epic-enforcement.js';
 import { resolveHierarchyPolicy } from './hierarchy-policy.js';
+import { validatePipelineTransition } from './pipeline-stage.js';
 
 const NON_STATUS_DONE_FIELDS: Array<keyof Omit<UpdateTaskOptions, 'taskId' | 'status'>> = [
   'title',
@@ -41,6 +49,7 @@ const NON_STATUS_DONE_FIELDS: Array<keyof Omit<UpdateTaskOptions, 'taskId' | 'st
   'blockedBy',
   'parentId',
   'noAutoComplete',
+  'pipelineStage',
 ];
 
 function hasNonStatusDoneFields(options: UpdateTaskOptions): boolean {
@@ -69,6 +78,8 @@ export interface UpdateTaskOptions {
   blockedBy?: string;
   parentId?: string | null;
   noAutoComplete?: boolean;
+  /** RCASD-IVTR+C pipeline stage transition target. Must be >= current stage. @task T060 */
+  pipelineStage?: string;
 }
 
 /** Result of updating a task. */
@@ -93,6 +104,9 @@ export async function updateTask(
       fix: `Use 'cleo find "${options.taskId}"' to search`,
     });
   }
+
+  await requireActiveSession('tasks.update', cwd);
+
   const changes: string[] = [];
   const now = new Date().toISOString();
 
@@ -114,6 +128,17 @@ export async function updateTask(
     );
   }
 
+  // Enforce Acceptance Criteria on Update
+  const enforcement = await createAcceptanceEnforcement(cwd);
+  const updateValidation = enforcement.validateUpdate(task, { acceptance: options.acceptance });
+  if (!updateValidation.valid) {
+    throw new CleoError(
+      updateValidation.exitCode ?? ExitCode.VALIDATION_ERROR,
+      updateValidation.error!,
+      { fix: updateValidation.fix },
+    );
+  }
+
   // Update fields
   if (options.title !== undefined) {
     validateTitle(options.title);
@@ -230,6 +255,43 @@ export async function updateTask(
     changes.push('noAutoComplete');
   }
 
+  // Pipeline stage transition — forward-only (T060)
+  if (options.pipelineStage !== undefined) {
+    validatePipelineTransition(task.pipelineStage, options.pipelineStage);
+
+    // Epic stage advancement gate (T062): block advancement if children are in-flight
+    // at the current stage.
+    if (task.type === 'epic' && task.pipelineStage) {
+      await validateEpicStageAdvancement(
+        {
+          epicId: task.id,
+          currentStage: task.pipelineStage,
+          newStage: options.pipelineStage,
+        },
+        acc,
+        cwd,
+      );
+    }
+
+    // Child stage ceiling (T062): non-epic tasks cannot advance past their epic ancestor.
+    if (task.type !== 'epic') {
+      const epicAncestor = task.parentId ? await findEpicAncestor(task.parentId, acc) : null;
+      // Also check if the direct parent is an epic
+      const directParent = task.parentId ? await acc.loadSingleTask(task.parentId) : null;
+      const epicToCheck = directParent?.type === 'epic' ? directParent : epicAncestor;
+      if (epicToCheck) {
+        await validateChildStageCeiling(
+          { childStage: options.pipelineStage, epicId: epicToCheck.id },
+          acc,
+          cwd,
+        );
+      }
+    }
+
+    task.pipelineStage = options.pipelineStage;
+    changes.push('pipelineStage');
+  }
+
   // Handle parentId change (reparent) using targeted queries
   // Supports: parentId="T001" to set parent, parentId=null or parentId="" to promote to root
   if (options.parentId !== undefined) {

package/templates/config.template.json

@@ -23,6 +23,40 @@
     "logSessionEvents": true
   },
 
+  "enforcement": {
+    "acceptance": {
+      "mode": "block",
+      "requiredForPriorities": ["critical", "high", "medium", "low"],
+      "minimumCriteria": 3
+    },
+    "session": {
+      "requiredForMutate": true
+    },
+    "pipeline": {
+      "bindTasksToStage": true
+    }
+  },
+
+  "verification": {
+    "enabled": true,
+    "requiredForTypes": ["epic", "task", "subtask"],
+    "autoInitialize": true,
+    "maxRounds": 5,
+    "requiredGates": ["implemented", "testsPassed", "qaPassed"],
+    "autoSetImplementedOnComplete": true,
+    "requireForParentAutoComplete": true,
+    "allowManualOverride": true
+  },
+
+  "lifecycle": {
+    "mode": "strict"
+  },
+
+  "hierarchy": {
+    "maxDepth": 3,
+    "maxSiblings": 0
+  },
+
   "validation": {
     "strictMode": false,
     "checksumEnabled": true,