@cleocode/core 2026.3.58 → 2026.3.60

package/src/tasks/epic-enforcement.ts

@@ -67,6 +67,18 @@ export interface EpicEnforcementResult {
  * 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> {
@@ -91,12 +103,23 @@ export async function getLifecycleMode(cwd?: string): Promise<LifecycleMode> {
  *
  * 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(
@@ -151,6 +174,11 @@ export async function validateEpicCreation(
  * 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.
@@ -158,6 +186,14 @@ export async function validateEpicCreation(
  * @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(
@@ -204,10 +240,20 @@ export async function validateChildStageCeiling(
  * 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(
@@ -240,6 +286,13 @@ export async function findEpicAncestor(
  * 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.
@@ -248,6 +301,14 @@ export async function findEpicAncestor(
  * @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(

package/src/tasks/pipeline-stage.ts

@@ -81,9 +81,19 @@ const STAGE_ORDER: Record<TaskPipelineStage, number> = {
 /**
  * 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 {
@@ -93,9 +103,20 @@ export function isValidPipelineStage(stage: string): stage is 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 {
@@ -121,11 +142,26 @@ export function validatePipelineStage(stage: string): asserts stage is TaskPipel
  * 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: {
@@ -161,8 +197,19 @@ export function resolveDefaultPipelineStage(options: {
 /**
  * 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, or -1 if not found
+ * @returns Numeric order (1–10), or -1 if not found
+ *
+ * @example
+ * ```ts
+ * getPipelineStageOrder('research');       // => 1
+ * getPipelineStageOrder('implementation'); // => 6
+ * getPipelineStageOrder('unknown');        // => -1
+ * ```
  *
  * @task T060
  */
@@ -176,10 +223,20 @@ export function getPipelineStageOrder(stage: string): number {
  * "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 {
@@ -192,10 +249,22 @@ export function isPipelineTransitionForward(currentStage: string, newStage: stri
 /**
  * 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(

package/templates/config.template.json

@@ -16,13 +16,6 @@
     "autoArchiveOnComplete": false
   },
 
-  "logging": {
-    "enabled": true,
-    "retentionDays": 30,
-    "level": "standard",
-    "logSessionEvents": true
-  },
-
   "enforcement": {
     "acceptance": {
       "mode": "block",
@@ -57,41 +50,12 @@
     "maxSiblings": 0
   },
 
-  "validation": {
-    "strictMode": false,
-    "checksumEnabled": true,
-    "enforceAcceptance": true,
-    "requireDescription": false,
-    "maxActiveTasks": 1,
-    "validateDependencies": true,
-    "detectCircularDeps": true
-  },
-
   "defaults": {
-    "priority": "medium",
-    "phase": "core",
-    "labels": []
+    "priority": "medium"
   },
 
   "session": {
-    "requireSession": true,
-    "requireSessionNote": true,
-    "requireNotesOnComplete": true,
-    "warnOnNoFocus": true,
-    "allowNestedSessions": true,
-    "allowParallelAgents": true,
-    "autoStartSession": true,
-    "autoDiscoveryOnStart": true,
-    "sessionTimeoutHours": 72
-  },
-
-  "multiSession": {
-    "enabled": true,
-    "maxConcurrentSessions": 5,
-    "maxActiveTasksPerScope": 1,
-    "scopeValidation": "strict",
-    "allowNestedScopes": true,
-    "allowScopeOverlap": false
+    "enforcement": "strict"
   },
 
   "release": {
@@ -104,43 +68,12 @@
     }
   },
 
-  "display": {
-    "showArchiveCount": true,
-    "showLogSummary": true,
-    "warnStaleDays": 30
-  },
-
   "output": {
     "defaultFormat": "text",
     "showColor": true,
     "showUnicode": true,
     "showProgressBars": true,
-    "csvDelimiter": ",",
-    "dateFormat": "iso8601",
-    "showCompactTitles": false,
-    "maxTitleLength": 80
-  },
-
-  "cli": {
-    "aliases": {
-      "ls": "list",
-      "done": "complete",
-      "new": "add",
-      "edit": "update",
-      "rm": "archive",
-      "check": "validate"
-    },
-    "plugins": {
-      "enabled": true,
-      "directories": ["~/.cleo/plugins", "./.cleo/plugins"],
-      "autoDiscover": true
-    },
-    "debug": {
-      "enabled": true,
-      "validateMappings": true,
-      "checksumVerify": true,
-      "showTimings": false
-    }
+    "dateFormat": "iso8601"
   },
 
   "backup": {
@@ -153,17 +86,8 @@
     "safetyRetentionDays": 7
   },
 
-  "cancellation": {
-    "cascadeConfirmThreshold": 10,
-    "requireReason": true,
-    "daysUntilArchive": 3,
-    "allowCascade": true,
-    "defaultChildStrategy": "block"
-  },
-
   "contextAlerts": {
     "enabled": true,
-    "minThreshold": "warning",
     "triggerCommands": ["complete", "start", "stop", "add", "session"],
     "suppressDuration": 0
   },
@@ -172,50 +96,15 @@
     "contextThresholds": {
       "warning": 70,
       "critical": 80
-    },
-    "autoStopOnCritical": true,
-    "hitlSummaryOnPause": true
+    }
   },
 
   "agentOutputs": {
     "directory": ".cleo/agent-outputs",
-    "manifestFile": "MANIFEST.jsonl",
-    "archiveDir": "archive",
-    "archiveDays": 30
+    "manifestFile": "MANIFEST.jsonl"
   },
 
   "retention": {
-    "maxArchivedSessions": 100,
-    "autoArchiveEndedAfterDays": 30,
-    "autoDeleteArchivedAfterDays": 90,
-    "contextStateRetentionDays": 7,
-    "cleanupOnSessionEnd": true,
-    "dryRunByDefault": true,
-    "maxSessionsInMemory": 100,
     "autoEndActiveAfterDays": 7
-  },
-
-  "project": {
-    "status": {
-      "health": "unknown",
-      "lastCheck": null,
-      "schemaVersions": {
-        "todo": "{{SCHEMA_VERSION_TODO}}",
-        "config": "{{SCHEMA_VERSION_CONFIG}}",
-        "archive": "{{SCHEMA_VERSION_ARCHIVE}}",
-        "log": "{{SCHEMA_VERSION_LOG}}"
-      },
-      "validation": {
-        "lastValidated": null,
-        "passed": false,
-        "errors": [],
-        "warnings": []
-      },
-      "injection": {
-        "CLAUDE.md": "not_found",
-        "AGENTS.md": "not_found",
-        "GEMINI.md": "not_found"
-      }
-    }
   }
 }

package/templates/global-config.template.json

@@ -6,40 +6,7 @@
     "showColor": true,
     "showUnicode": true,
     "showProgressBars": true,
-    "dateFormat": "iso8601",
-    "showCompactTitles": false,
-    "maxTitleLength": 80
-  },
-  "display": {
-    "showArchiveCount": true,
-    "showLogSummary": true,
-    "warnStaleDays": 30
-  },
-  "cli": {
-    "aliases": {
-      "ls": "list",
-      "done": "complete",
-      "new": "add",
-      "edit": "update",
-      "rm": "archive",
-      "check": "validate",
-      "tags": "labels",
-      "overview": "dash"
-    },
-    "plugins": {
-      "enabled": true,
-      "directories": [
-        "~/.cleo/plugins",
-        "./.cleo/plugins"
-      ],
-      "autoDiscover": true
-    },
-    "debug": {
-      "enabled": false,
-      "validateMappings": true,
-      "checksumVerify": true,
-      "showTimings": false
-    }
+    "dateFormat": "iso8601"
   },
   "enforcement": {
     "acceptance": {
@@ -68,15 +35,6 @@
     "mode": "strict"
   },
   "defaults": {
-    "priority": "medium",
-    "labels": []
-  },
-  "multiSession": {
-    "enabled": true,
-    "maxConcurrentSessions": 5,
-    "maxActiveTasksPerScope": 1,
-    "scopeValidation": "strict",
-    "allowNestedScopes": true,
-    "allowScopeOverlap": false
+    "priority": "medium"
   }
 }