@cleocode/core 2026.3.57 → 2026.3.59

package/src/tasks/epic-enforcement.ts

@@ -0,0 +1,364 @@
+/**
+ * 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).
+ *
+ * @remarks
+ * In VITEST environments, returns "off" to avoid blocking tests.
+ *
+ * @param cwd - Working directory for config resolution
+ * @returns The resolved lifecycle mode
+ *
+ * @example
+ * ```ts
+ * const mode = await getLifecycleMode();
+ * // => 'strict' | 'advisory' | 'off'
+ * ```
+ *
+ * @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.
+ *
+ * @remarks
+ * The description field serves as a proxy for completion criteria — epics
+ * without a description have no definition of "done" and should be blocked.
+ *
+ * @param options - Epic creation parameters
+ * @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.
+ *
+ * @example
+ * ```ts
+ * await validateEpicCreation({ acceptance: ['AC1','AC2','AC3','AC4','AC5'] });
+ * // => { valid: true }
+ * ```
+ *
+ * @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.
+ *
+ * @remarks
+ * Skips the check if the epic has no pipeline stage set, or if the child
+ * stage is not a recognised value (those are handled by separate validation).
+ *
+ * @param options - Ceiling check parameters
+ * @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.
+ *
+ * @example
+ * ```ts
+ * await validateChildStageCeiling(
+ *   { childStage: 'testing', epicId: 'T001' },
+ *   accessor,
+ * );
+ * ```
+ *
+ * @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.
+ *
+ * @remarks
+ * Scans from closest ancestor to root so the *nearest* epic is returned,
+ * not the highest-level one.
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * const epic = await findEpicAncestor('T042', accessor);
+ * if (epic) console.log(epic.id); // e.g. 'T029'
+ * ```
+ *
+ * @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.
+ *
+ * @remarks
+ * Only fires on genuine forward advancement — same-stage updates and
+ * backward moves are handled by {@link validatePipelineTransition}.
+ * Children with status "done", "cancelled", or "archived" are excluded
+ * from the blocker check.
+ *
+ * @param options - Advancement check parameters
+ * @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.
+ *
+ * @example
+ * ```ts
+ * await validateEpicStageAdvancement(
+ *   { epicId: 'T029', currentStage: 'research', newStage: 'consensus' },
+ *   accessor,
+ * );
+ * ```
+ *
+ * @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,293 @@
+/**
+ * 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.
+ *
+ * @remarks
+ * Uses a type-narrowing signature so callers can safely use the value
+ * as {@link TaskPipelineStage} after a truthy check.
+ *
+ * @param stage - Raw string to test
+ * @returns True if it is a valid stage name
+ *
+ * @example
+ * ```ts
+ * isValidPipelineStage('research');       // => true
+ * isValidPipelineStage('not_a_stage');    // => false
+ * ```
+ *
+ * @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.
+ *
+ * @remarks
+ * Uses an assertion signature — after a successful call the compiler
+ * narrows `stage` to {@link TaskPipelineStage}.
+ *
+ * @param stage - Stage name to validate
+ * @returns void (assertion function — narrows type on success)
+ * @throws CleoError(VALIDATION_ERROR) if invalid
+ *
+ * @example
+ * ```ts
+ * validatePipelineStage('implementation'); // passes
+ * validatePipelineStage('invalid');        // throws CleoError
+ * ```
+ *
+ * @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'.
+ *
+ * @remarks
+ * Priority order ensures explicit caller intent wins, then parent
+ * inheritance, then type-based defaults. This avoids surprising
+ * overrides when parent stages differ from the default.
+ *
+ * @param options - Resolution inputs
+ * @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
+ *
+ * @example
+ * ```ts
+ * resolveDefaultPipelineStage({ taskType: 'epic' });
+ * // => 'research'
+ *
+ * resolveDefaultPipelineStage({ taskType: 'task' });
+ * // => 'implementation'
+ * ```
+ *
+ * @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).
+ *
+ * @remarks
+ * Returns -1 for unrecognised stage names so callers can distinguish
+ * "unknown" from a valid low-order stage.
+ *
+ * @param stage - Stage name (must be valid)
+ * @returns Numeric order (1–10), or -1 if not found
+ *
+ * @example
+ * ```ts
+ * getPipelineStageOrder('research');       // => 1
+ * getPipelineStageOrder('implementation'); // => 6
+ * getPipelineStageOrder('unknown');        // => -1
+ * ```
+ *
+ * @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).
+ *
+ * @remarks
+ * Unknown stages are treated as valid to avoid blocking tasks with
+ * legacy or custom stage names that predate the standard set.
+ *
+ * @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)
+ *
+ * @example
+ * ```ts
+ * isPipelineTransitionForward('research', 'implementation'); // => true
+ * isPipelineTransitionForward('testing', 'research');        // => false
+ * ```
+ *
+ * @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.
+ *
+ * @remarks
+ * Validates the new stage name first via {@link validatePipelineStage},
+ * then checks directionality. A null/undefined current stage accepts any
+ * valid new stage (first assignment).
+ *
+ * @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
+ *
+ * @example
+ * ```ts
+ * validatePipelineTransition(null, 'research');              // passes (first assignment)
+ * validatePipelineTransition('research', 'implementation');   // passes (forward)
+ * validatePipelineTransition('testing', 'research');          // throws (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(', ')}`,
+      },
+    );
+  }
+}