@cleocode/core 2026.3.58 → 2026.3.59

package/dist/tasks/epic-enforcement.d.ts

@@ -45,6 +45,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 declare function getLifecycleMode(cwd?: string): Promise<LifecycleMode>;
@@ -60,12 +72,23 @@ export declare 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 declare function validateEpicCreation(options: {
@@ -82,6 +105,11 @@ export declare function validateEpicCreation(options: {
  * 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.
@@ -89,6 +117,14 @@ export declare function validateEpicCreation(options: {
  * @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 declare function validateChildStageCeiling(options: {
@@ -101,10 +137,20 @@ export declare function validateChildStageCeiling(options: {
  * 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 declare function findEpicAncestor(taskId: string, accessor: DataAccessor): Promise<Task | null>;
@@ -120,6 +166,13 @@ export declare function findEpicAncestor(taskId: string, accessor: DataAccessor)
  * 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.
@@ -128,6 +181,14 @@ export declare function findEpicAncestor(taskId: string, accessor: DataAccessor)
  * @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 declare function validateEpicStageAdvancement(options: {

package/dist/tasks/epic-enforcement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"epic-enforcement.d.ts","sourceRoot":"","sources":["../../src/tasks/epic-enforcement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAU9D,mFAAmF;AACnF,eAAO,MAAM,WAAW,IAAI,CAAC;AAE7B,2DAA2D;AAC3D,eAAO,MAAM,WAAW,IAAI,CAAC;AAM7B,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,KAAK,CAAC;AAE1D,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACpC,2CAA2C;IAC3C,KAAK,EAAE,OAAO,CAAC;IACf,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAI3E;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE;IACP,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,EACD,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,qBAAqB,CAAC,CA8BhC;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE;IACP,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB,EACD,QAAQ,EAAE,YAAY,EACtB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,qBAAqB,CAAC,CA6BhC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,YAAY,GACrB,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAStB;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE;IACP,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB,EACD,QAAQ,EAAE,YAAY,EACtB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,qBAAqB,CAAC,CA0ChC"}
+{"version":3,"file":"epic-enforcement.d.ts","sourceRoot":"","sources":["../../src/tasks/epic-enforcement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAU9D,mFAAmF;AACnF,eAAO,MAAM,WAAW,IAAI,CAAC;AAE7B,2DAA2D;AAC3D,eAAO,MAAM,WAAW,IAAI,CAAC;AAM7B,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,KAAK,CAAC;AAE1D,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACpC,2CAA2C;IAC3C,KAAK,EAAE,OAAO,CAAC;IACf,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAI3E;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE;IACP,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,EACD,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,qBAAqB,CAAC,CA8BhC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE;IACP,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB,EACD,QAAQ,EAAE,YAAY,EACtB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,qBAAqB,CAAC,CA6BhC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,YAAY,GACrB,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAStB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE;IACP,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB,EACD,QAAQ,EAAE,YAAY,EACtB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,qBAAqB,CAAC,CA0ChC"}

package/dist/tasks/pipeline-stage.d.ts

@@ -41,18 +41,39 @@ export type TaskPipelineStage = (typeof TASK_PIPELINE_STAGES)[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 declare 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 declare function validatePipelineStage(stage: string): asserts stage is TaskPipelineStage;
@@ -65,11 +86,26 @@ export declare function validatePipelineStage(stage: string): asserts stage is T
  * 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 declare function resolveDefaultPipelineStage(options: {
@@ -80,8 +116,19 @@ export declare 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
  */
@@ -92,20 +139,42 @@ export declare 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 declare function isPipelineTransitionForward(currentStage: string, newStage: string): boolean;
 /**
  * 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 declare function validatePipelineTransition(currentStage: string | null | undefined, newStage: string): void;

package/dist/tasks/pipeline-stage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline-stage.d.ts","sourceRoot":"","sources":["../../src/tasks/pipeline-stage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAIpD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;CACxB;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,qKAWvB,CAAC;AAEX,oDAAoD;AACpD,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAoBtE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,iBAAiB,CAE9E;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,iBAAiB,CAQvF;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IACnD,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;CACpC,GAAG,iBAAiB,CAoBpB;AAMD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAK3F;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACvC,QAAQ,EAAE,MAAM,GACf,IAAI,CAoBN"}
+{"version":3,"file":"pipeline-stage.d.ts","sourceRoot":"","sources":["../../src/tasks/pipeline-stage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAIpD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;CACxB;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,qKAWvB,CAAC;AAEX,oDAAoD;AACpD,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAoBtE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,iBAAiB,CAE9E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,iBAAiB,CAQvF;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IACnD,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;CACpC,GAAG,iBAAiB,CAoBpB;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAK3F;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACvC,QAAQ,EAAE,MAAM,GACf,IAAI,CAoBN"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/core",
-  "version": "2026.3.58",
+  "version": "2026.3.59",
   "description": "CLEO core business logic kernel — tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,10 +36,10 @@
     "write-file-atomic": "^6.0.0",
     "yaml": "^2.8.2",
     "zod": "^3.25.76",
-    "@cleocode/adapters": "2026.3.58",
-    "@cleocode/agents": "2026.3.58",
-    "@cleocode/contracts": "2026.3.58",
-    "@cleocode/skills": "2026.3.58"
+    "@cleocode/adapters": "2026.3.59",
+    "@cleocode/agents": "2026.3.59",
+    "@cleocode/skills": "2026.3.59",
+    "@cleocode/contracts": "2026.3.59"
   },
   "engines": {
     "node": ">=24.0.0"