@cleocode/core 2026.3.57 → 2026.3.59

package/dist/tasks/complete.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"complete.d.ts","sourceRoot":"","sources":["../../src/tasks/complete.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAoB,MAAM,qBAAqB,CAAC;AAK3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAG9D,qCAAqC;AACrC,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mCAAmC;AACnC,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,IAAI,CAAC;IACX,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC;CACvD;AAkFD;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,EAC5B,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,kBAAkB,CAAC,CA8M7B"}
+{"version":3,"file":"complete.d.ts","sourceRoot":"","sources":["../../src/tasks/complete.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAoB,MAAM,qBAAqB,CAAC;AAM3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAI9D,qCAAqC;AACrC,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mCAAmC;AACnC,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,IAAI,CAAC;IACX,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC;CACvD;AA+FD;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,EAC5B,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,kBAAkB,CAAC,CA2M7B"}

package/dist/tasks/enforcement.d.ts

@@ -0,0 +1,22 @@
+import { ExitCode, type Task } from '@cleocode/contracts';
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+    fix?: string;
+    exitCode?: ExitCode;
+}
+export interface AddTaskEnforcementOptions {
+    acceptance?: string[];
+    priority?: string;
+}
+export interface UpdateTaskEnforcementOptions {
+    acceptance?: string[];
+}
+export interface AcceptanceEnforcement {
+    validateCreation(options: AddTaskEnforcementOptions): ValidationResult;
+    validateUpdate(task: Task, updates: UpdateTaskEnforcementOptions): ValidationResult;
+    validateCompletion(task: Task): ValidationResult;
+    checkMinimumCriteria(criteria: string[], minCriteria: number): boolean;
+}
+export declare function createAcceptanceEnforcement(cwd?: string): Promise<AcceptanceEnforcement>;
+//# sourceMappingURL=enforcement.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"enforcement.d.ts","sourceRoot":"","sources":["../../src/tasks/enforcement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAG1D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,4BAA4B;IAC3C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,CAAC,OAAO,EAAE,yBAAyB,GAAG,gBAAgB,CAAC;IACvE,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,4BAA4B,GAAG,gBAAgB,CAAC;IACpF,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,gBAAgB,CAAC;IACjD,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;CACxE;AAMD,wBAAsB,2BAA2B,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAgG9F"}

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

@@ -0,0 +1,199 @@
+/**
+ * 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';
+/** Minimum acceptance criteria count required for epic creation in strict mode. */
+export declare const EPIC_MIN_AC = 5;
+/** Minimum acceptance criteria count for regular tasks. */
+export declare const TASK_MIN_AC = 3;
+/** 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;
+}
+/**
+ * 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>;
+/**
+ * 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 declare function validateEpicCreation(options: {
+    acceptance?: string[];
+    description?: string;
+}, cwd?: string): Promise<EpicEnforcementResult>;
+/**
+ * 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 declare function validateChildStageCeiling(options: {
+    childStage: string;
+    epicId: string;
+}, accessor: DataAccessor, cwd?: string): Promise<EpicEnforcementResult>;
+/**
+ * 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 declare function findEpicAncestor(taskId: string, accessor: DataAccessor): Promise<Task | null>;
+/**
+ * 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 declare function validateEpicStageAdvancement(options: {
+    epicId: string;
+    currentStage: string;
+    newStage: string;
+}, accessor: DataAccessor, cwd?: string): Promise<EpicEnforcementResult>;
+//# sourceMappingURL=epic-enforcement.d.ts.map

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

@@ -0,0 +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;;;;;;;;;;;;;;;;;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/index.d.ts

@@ -3,7 +3,7 @@
  * @task T4460
  * @epic T4454
  */
-export { type AddTaskOptions, type AddTaskResult, addTask, findRecentDuplicate, getNextPosition, getTaskDepth, inferTaskType, logOperation, normalizePriority, VALID_PRIORITIES, validateDepends, validateLabels, validateParent, validatePhaseFormat, validatePriority, validateSize, validateStatus, validateTaskType, validateTitle, } from './add.js';
+export { type AddTaskOptions, type AddTaskResult, addTask, buildDefaultVerification, findRecentDuplicate, getNextPosition, getTaskDepth, inferTaskType, logOperation, normalizePriority, VALID_PRIORITIES, validateDepends, validateLabels, validateParent, validatePhaseFormat, validatePriority, validateSize, validateStatus, validateTaskType, validateTitle, } from './add.js';
 export { type ArchiveTasksOptions, type ArchiveTasksResult, archiveTasks } from './archive.js';
 export { type CompleteTaskOptions, type CompleteTaskResult, completeTask } from './complete.js';
 export { type DeleteTaskOptions, type DeleteTaskResult, deleteTask } from './delete.js';

package/dist/tasks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tasks/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,OAAO,EACP,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,aAAa,GACd,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC/F,OAAO,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAChG,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EACL,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,SAAS,EACT,UAAU,GACX,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACnF,OAAO,EAAE,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tasks/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,OAAO,EACP,wBAAwB,EACxB,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,aAAa,GACd,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC/F,OAAO,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAChG,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EACL,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,SAAS,EACT,UAAU,GACX,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACnF,OAAO,EAAE,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

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

@@ -0,0 +1,181 @@
+/**
+ * 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';
+/**
+ * Minimal parent task shape needed for pipeline stage resolution.
+ * @task T060
+ */
+export interface ResolvedParent {
+    pipelineStage?: string | null;
+    type?: TaskType | null;
+}
+/**
+ * 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 declare const TASK_PIPELINE_STAGES: readonly ["research", "consensus", "architecture_decision", "specification", "decomposition", "implementation", "validation", "testing", "release", "contribution"];
+/** Union type of all valid pipeline stage names. */
+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;
+/**
+ * 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 declare function resolveDefaultPipelineStage(options: {
+    explicitStage?: string | null;
+    taskType?: TaskType | null;
+    parentTask?: ResolvedParent | null;
+}): TaskPipelineStage;
+/**
+ * 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 declare function getPipelineStageOrder(stage: string): number;
+/**
+ * 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 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;
+//# sourceMappingURL=pipeline-stage.d.ts.map

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

@@ -0,0 +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;;;;;;;;;;;;;;;;;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/dist/tasks/update.d.ts

@@ -27,6 +27,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. */
 export interface UpdateTaskResult {

package/dist/tasks/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/tasks/update.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAK9F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAsC9D,mCAAmC;AACnC,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,iCAAiC;AACjC,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,iBAAiB,EAC1B,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAoO3B"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/tasks/update.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAM9F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AA8C9D,mCAAmC;AACnC,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,0FAA0F;IAC1F,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,iCAAiC;AACjC,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,iBAAiB,EAC1B,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAuR3B"}

package/migrations/drizzle-brain/20260321000001_t033-brain-indexes/migration.sql

@@ -0,0 +1,12 @@
+-- T033: Connection Health Remediation — brain.db indexes (from T031 analysis)
+-- INDEX 8: content_hash + created_at (dedup hot path in observeBrain)
+-- Drop single-column content_hash index first; composite covers the prefix case.
+DROP INDEX IF EXISTS `idx_brain_observations_content_hash`;
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS `idx_brain_observations_content_hash_created_at`
+  ON `brain_observations` (`content_hash`, `created_at`);
+--> statement-breakpoint
+
+-- INDEX 9: type + project (findObservations compound filter)
+CREATE INDEX IF NOT EXISTS `idx_brain_observations_type_project`
+  ON `brain_observations` (`type`, `project`);