@cleocode/contracts 2026.5.77 → 2026.5.79

package/src/exit-codes.ts

@@ -226,6 +226,60 @@ export enum ExitCode {
   LEAD_BYPASS_DETECTED = 107,
 }
 
+// ---------------------------------------------------------------------------
+// Release pipeline v2 error code names (SPEC-T9345 §4.7)
+//
+// String-valued error codes emitted by the new release verbs (plan, open,
+// reconcile, rollback). These are the `code` field of EngineErrorPayload;
+// the numeric exit code is the bucket the verb resolves to (per SPEC §4.7).
+//
+// @task T9525
+// @epic T9492
+// @spec .cleo/rcasd/T9345/research/SPEC-T9345-release-pipeline-v2.md §4.7
+// ---------------------------------------------------------------------------
+
+/** Dirty version files block `cleo release plan` (R-020). Exit code 13. */
+export const E_DIRTY_TREE = 'E_DIRTY_TREE' as const;
+/** Epic referenced by `--epic` has zero children (R-021). Exit code 4. */
+export const E_EPIC_EMPTY = 'E_EPIC_EMPTY' as const;
+/** Epic referenced by `--epic` does not exist (R-021). Exit code 10. */
+export const E_EPIC_NOT_FOUND = 'E_EPIC_NOT_FOUND' as const;
+/** Channel + version scheme are incompatible (R-022). Exit code 6. */
+export const E_CHANNEL_MISMATCH = 'E_CHANNEL_MISMATCH' as const;
+/**
+ * One or more tasks in the plan are missing required ADR-051 evidence atoms
+ * (R-301 / R-310). Exit code 83. `error.details.tasks[]` lists offenders.
+ */
+export const E_EVIDENCE_INSUFFICIENT = 'E_EVIDENCE_INSUFFICIENT' as const;
+/** Plan file at `.cleo/release/<version>.plan.json` is absent. Exit code 4. */
+export const E_PLAN_NOT_FOUND = 'E_PLAN_NOT_FOUND' as const;
+/** Generic release-plan validation failure (e.g. schema). Exit code 6. */
+export const E_RELEASE_PLAN_INVALID = 'E_RELEASE_PLAN_INVALID' as const;
+/**
+ * Release row exists but is not in the status FSM state required by the
+ * caller (R-051 — `cleo release open` requires status='planned'). Exit code 6.
+ * `error.details.currentStatus` MUST report the actual status; `error.details.expectedStatus`
+ * SHOULD list the accepted state(s).
+ *
+ * @task T9530
+ */
+export const E_INVALID_STATE = 'E_INVALID_STATE' as const;
+/**
+ * `gh auth status` exited non-zero (R-052). The GitHub CLI is either not
+ * installed or not authenticated for the active hostname. Exit code 5.
+ *
+ * @task T9530
+ */
+export const E_GH_NOT_AUTHENTICATED = 'E_GH_NOT_AUTHENTICATED' as const;
+/**
+ * The expected GitHub Actions workflow file is missing under `.github/workflows/`
+ * (R-053). Without it, `gh workflow run` would fail with a non-recoverable error.
+ * Exit code 4.
+ *
+ * @task T9530
+ */
+export const E_WORKFLOW_NOT_FOUND = 'E_WORKFLOW_NOT_FOUND' as const;
+
 /** Check if an exit code represents an error (1-99). */
 export function isErrorCode(code: ExitCode): boolean {
   return code >= 1 && code < 100;

package/src/index.ts

@@ -332,6 +332,18 @@ export {
 } from './evidence-record-schema.js';
 // === Exit Codes ===
 export {
+  // SPEC-T9345 release pipeline v2 error code names (T9525)
+  E_CHANNEL_MISMATCH,
+  E_DIRTY_TREE,
+  E_EPIC_EMPTY,
+  E_EPIC_NOT_FOUND,
+  E_EVIDENCE_INSUFFICIENT,
+  // SPEC-T9345 release pipeline v2 error code names (T9530)
+  E_GH_NOT_AUTHENTICATED,
+  E_INVALID_STATE,
+  E_PLAN_NOT_FOUND,
+  E_RELEASE_PLAN_INVALID,
+  E_WORKFLOW_NOT_FOUND,
   ExitCode,
   getExitCodeName,
   isErrorCode,
@@ -1144,13 +1156,24 @@ export type {
   CreateWorktreeResult,
   DestroyWorktreeOptions,
   DestroyWorktreeResult,
+  ForceUnlockWorktreeOpts,
+  ForceUnlockWorktreeResult,
   ListWorktreesOptions,
+  ListWorktreesOpts,
+  ListWorktreesResult,
+  PrunedWorktreeOutcome,
+  PruneOrphanedWorktreesOpts,
+  PruneOrphanedWorktreesResult,
   PruneWorktreesOptions,
   PruneWorktreesResult,
   WorktreeHook,
   WorktreeHookResult,
   WorktreeIncludePattern,
+  WorktreeInfo,
+  WorktreeLifecycleAction,
+  WorktreeLifecycleAuditEntry,
   WorktreeListEntry,
+  WorktreeStatusCategory,
 } from './operations/worktree.js';
 // === Orchestration Roll-up Types (T9082, ADR-070) ===
 export type {
@@ -1235,6 +1258,62 @@ export type {
   ReleaseVersionScheme,
   VerifyResult,
 } from './release/pipeline.js';
+// === Release Plan Envelope (T9527 / SPEC-T9345 §6) ===
+export type {
+  GateName as ReleaseGateName,
+  GateStatus as ReleaseGateExecutionStatus,
+  Impact as ReleasePlanImpact,
+  PlatformTuple,
+  Publisher,
+  ReleaseChannel as ReleasePlanChannel,
+  ReleaseGate,
+  ReleaseKind,
+  ReleasePlan,
+  ReleasePlanChangelog,
+  ReleasePlanMeta,
+  ReleasePlanTask,
+  ReleasePlatformMatrixEntry,
+  ReleasePreflightSummary,
+  ReleaseScheme,
+  ReleaseStatus as ReleasePlanStatus,
+  ResolvedSource,
+  TaskKind as ReleaseTaskKind,
+} from './release/plan.js';
+export {
+  GATE_NAME,
+  GATE_STATUS,
+  GateNameSchema,
+  GateStatusSchema,
+  IMPACT,
+  ImpactSchema,
+  PLATFORM_TUPLE,
+  PlatformTupleSchema,
+  PUBLISHER,
+  PublisherSchema,
+  parseReleasePlan,
+  RELEASE_CHANNEL,
+  RELEASE_KIND,
+  RELEASE_PLAN_SCHEMA_URL,
+  RELEASE_PLAN_SCHEMA_VERSION,
+  RELEASE_SCHEME,
+  RELEASE_STATUS,
+  RESOLVED_SOURCE,
+  ReleaseChannelSchema,
+  ReleaseGateSchema,
+  ReleaseKindSchema,
+  ReleasePlanChangelogSchema,
+  ReleasePlanMetaSchema,
+  ReleasePlanSchema,
+  ReleasePlanTaskSchema,
+  ReleasePlatformMatrixEntrySchema,
+  ReleasePreflightSummarySchema,
+  ReleaseSchemeSchema,
+  ReleaseStatusSchema,
+  ResolvedSourceSchema,
+  safeParseReleasePlan,
+  TASK_KIND,
+  TaskKindSchema,
+} from './release/plan.js';
 // === Release Version Bump ===
 export type {
   BumpResult,

package/src/operations/worktree.ts

@@ -349,3 +349,277 @@ export interface PruneWorktreesResult {
   /** Whether `git worktree prune` was run. */
   gitPruneRan: boolean;
 }
+
+// ---------------------------------------------------------------------------
+// Structured listing (T9546 — worktree-lifecycle 2/5)
+// ---------------------------------------------------------------------------
+
+/**
+ * Mutually-exclusive worktree status category assigned by orphan-detection
+ * heuristics in {@link WorktreeInfo}.
+ *
+ * Resolution precedence (first match wins):
+ *  1. `locked` — git porcelain reports the worktree is locked.
+ *  2. `orphan` — owning task is cancelled OR the branch has been deleted.
+ *  3. `merged` — the branch is reachable from `main` (already integrated).
+ *  4. `stale`  — no commits in N days AND (task=done OR no live owner).
+ *  5. `active` — everything else (default).
+ *
+ * @task T9546
+ */
+export type WorktreeStatusCategory = 'active' | 'stale' | 'merged' | 'orphan' | 'locked';
+
+/**
+ * A single structured worktree entry with full status classification.
+ *
+ * Returned by `cleo worktree list` and the `worktree.list` dispatch operation.
+ * Each entry combines filesystem state, git state, and owning-task state into
+ * a single JSON envelope payload that downstream consumers (prune, dashboard,
+ * sentient daemon) can act on without re-querying git.
+ *
+ * @task T9546
+ */
+export interface WorktreeInfo {
+  /** Absolute path to the worktree directory. */
+  path: string;
+  /** Branch checked out in this worktree. */
+  branch: string;
+  /** Task ID derived from the branch name (`task/T####`), or null. */
+  taskId: string | null;
+  /** Agent identifier that owns this worktree (from audit log / metadata), or null. */
+  owningAgent: string | null;
+  /** ISO-8601 timestamp of last activity (newest commit OR mtime of working tree). */
+  lastActivity: string;
+  /** Whether `git worktree list --porcelain` reports the worktree as locked. */
+  isLocked: boolean;
+  /** Whether the worktree is stale: no activity > N days AND (task done/cancelled OR branch merged). */
+  isStale: boolean;
+  /** Whether the branch is reachable from `main` (already integrated). */
+  isMerged: boolean;
+  /** Status of the owning task (if {@link taskId} is present and resolvable), or null. */
+  owningTaskStatus: string | null;
+  /** Mutually-exclusive status category — see {@link WorktreeStatusCategory}. */
+  statusCategory: WorktreeStatusCategory;
+}
+
+/**
+ * Options for the structured worktree listing operation.
+ *
+ * @task T9546
+ */
+export interface ListWorktreesOpts {
+  /**
+   * Absolute path to the project root (used to compute the project hash
+   * and resolve the canonical worktrees directory).
+   */
+  projectRoot?: string;
+  /**
+   * Filter results to entries with one of these status categories.
+   * When omitted, all entries are returned.
+   */
+  statusFilter?: WorktreeStatusCategory[];
+  /**
+   * Staleness threshold in days. An entry is marked stale when its last
+   * activity is older than this AND either the owning task is done/cancelled
+   * or no owning task can be resolved while the branch is merged.
+   *
+   * @default 7
+   */
+  staleDays?: number;
+}
+
+/**
+ * Result of the structured worktree listing operation.
+ *
+ * @task T9546
+ */
+export interface ListWorktreesResult {
+  /** All matched worktree entries (post-filter). */
+  worktrees: WorktreeInfo[];
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle prune + force-unlock (T9547 — worktree-lifecycle 3/5)
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical action recorded in `.cleo/audit/worktree-lifecycle.jsonl`.
+ *
+ * - `prune` — orphaned/merged worktree was removed.
+ * - `prune-skip` — orphan was detected but skipped (user said N, or had uncommitted changes).
+ * - `force-unlock` — git index.lock removed + `git worktree unlock` ran.
+ * - `complete` — worktree was merged (`--no-ff`) into the default branch and pruned (T9548).
+ * - `complete-skip` — idempotent no-op (worktree already integrated or branch absent) (T9548).
+ * - `complete-manual` — operator marked the worktree as manually-handled via
+ *                       `--resolve manual`; no automatic merge attempted (T9548).
+ * - `complete-conflict` — auto-merge attempted but failed (e.g. rebase/merge conflict);
+ *                          worktree was preserved for manual resolution (T9548).
+ *
+ * @task T9547
+ * @task T9548
+ */
+export type WorktreeLifecycleAction =
+  | 'prune'
+  | 'prune-skip'
+  | 'force-unlock'
+  | 'complete'
+  | 'complete-skip'
+  | 'complete-manual'
+  | 'complete-conflict';
+
+/**
+ * One append-only entry written to `.cleo/audit/worktree-lifecycle.jsonl` by
+ * the prune + force-unlock commands.
+ *
+ * The shape intentionally mirrors the existing audit-jsonl pattern used by
+ * `worktree-prune.jsonl` (single-task path) so downstream log shippers can
+ * unify both streams. Optional fields are omitted (not null) when absent,
+ * keeping the JSONL surface compact and grep-friendly.
+ *
+ * @task T9547
+ */
+export interface WorktreeLifecycleAuditEntry {
+  /** ISO-8601 timestamp when the action was attempted. */
+  timestamp: string;
+  /** Agent / actor that initiated the action (env `CLEO_AGENT_ID` ?? `'cleo'`). */
+  actor: string;
+  /** The action performed — see {@link WorktreeLifecycleAction}. */
+  action: WorktreeLifecycleAction;
+  /** Absolute path to the worktree directory the action targeted. */
+  target: string;
+  /** Branch name (e.g. `task/T9547`) when known. */
+  branch?: string;
+  /** Task ID parsed from the branch name when known. */
+  taskId?: string;
+  /** Free-form reason — e.g. `orphaned-merged`, `dirty-skip`, `index-lock`. */
+  reason?: string;
+  /** Whether the action completed without error. */
+  success: boolean;
+  /** Error message when {@link success} is false. */
+  error?: string;
+}
+
+/**
+ * Options for {@link pruneOrphanedWorktreesByStatus} — the SDK primitive behind
+ * `cleo worktree prune --orphaned`.
+ *
+ * Per-orphan Y/N confirmation is the responsibility of the CLI layer; the SDK
+ * primitive itself is non-interactive and acts on the input set wholesale.
+ *
+ * @task T9547
+ */
+export interface PruneOrphanedWorktreesOpts {
+  /** Absolute path to the project root used for git invocations + audit log. */
+  projectRoot: string;
+  /**
+   * When true, do not actually remove worktrees — return the set that WOULD
+   * be pruned with `success: true` and the appropriate `reason`. The audit
+   * log is NOT written under `--dry-run`.
+   *
+   * @default false
+   */
+  dryRun?: boolean;
+  /**
+   * Staleness threshold in days passed through to {@link listWorktrees} when
+   * the caller wants a non-default `isStale` window.
+   *
+   * @default 7
+   */
+  staleDays?: number;
+  /**
+   * Optional subset of paths to prune. When supplied, only worktrees whose
+   * absolute `path` matches one of these strings are removed. The CLI passes
+   * this set after the user has confirmed per-orphan; in pure SDK use, omit
+   * the field to prune every orphan/merged entry the listing surfaces.
+   */
+  paths?: readonly string[];
+  /**
+   * Override actor name written to the audit log. Defaults to
+   * `process.env.CLEO_AGENT_ID ?? 'cleo'`.
+   */
+  actor?: string;
+  /**
+   * Optional override for the audit-log file path (testing). When omitted,
+   * writes to `<projectRoot>/.cleo/audit/worktree-lifecycle.jsonl`.
+   */
+  auditLogPath?: string;
+}
+
+/**
+ * Per-worktree outcome from a prune attempt.
+ *
+ * @task T9547
+ */
+export interface PrunedWorktreeOutcome {
+  /** Absolute path of the worktree. */
+  path: string;
+  /** Branch name (when known) — used by callers to render audit summaries. */
+  branch: string;
+  /** Task ID derived from the branch (when known). */
+  taskId: string | null;
+  /** Why this worktree was selected — e.g. `orphaned-merged`, `orphan-cancelled`. */
+  reason: string;
+  /** Whether the worktree was actually removed (false under --dry-run or on error). */
+  pruned: boolean;
+  /** Whether the task branch was deleted (only true when it was safe to do so). */
+  branchDeleted: boolean;
+  /** Error message when prune failed (set only on `pruned=false` + error path). */
+  error?: string;
+}
+
+/**
+ * Result of {@link pruneOrphanedWorktreesByStatus}.
+ *
+ * @task T9547
+ */
+export interface PruneOrphanedWorktreesResult {
+  /** Number of worktrees successfully pruned. */
+  prunedCount: number;
+  /** Number of orphans detected but NOT pruned (filtered by `paths`, dry-run, or errored). */
+  skippedCount: number;
+  /** Per-worktree outcomes, one entry per orphan that was considered. */
+  outcomes: PrunedWorktreeOutcome[];
+  /** Per-worktree errors raised during prune (subset of {@link outcomes} where `error` is set). */
+  errors: Array<{ path: string; error: string }>;
+  /** Whether {@link PruneOrphanedWorktreesOpts.dryRun} was set. */
+  dryRun: boolean;
+}
+
+/**
+ * Options for {@link forceUnlockWorktree} — the SDK primitive behind
+ * `cleo worktree force-unlock <taskId>`.
+ *
+ * @task T9547
+ */
+export interface ForceUnlockWorktreeOpts {
+  /** Absolute path to the project root used for git invocations. */
+  projectRoot: string;
+  /** Task ID whose worktree should be force-unlocked. */
+  taskId: string;
+  /** Override actor name written to the audit log. */
+  actor?: string;
+  /** Optional override for the audit-log file path (testing). */
+  auditLogPath?: string;
+}
+
+/**
+ * Result of {@link forceUnlockWorktree}.
+ *
+ * @task T9547
+ */
+export interface ForceUnlockWorktreeResult {
+  /** Task ID whose worktree was located. */
+  taskId: string;
+  /** Absolute path to the worktree (when located). */
+  path: string | null;
+  /** Whether `.git/index.lock` was present and removed. */
+  indexLockRemoved: boolean;
+  /** Whether `git worktree unlock` was executed (because porcelain reported `locked`). */
+  worktreeUnlocked: boolean;
+  /** Whether the worktree had uncommitted changes at the time of unlock (warn-only). */
+  hadUncommittedChanges: boolean;
+  /** Aggregate success — true when at least one unlock action ran without error. */
+  success: boolean;
+  /** Error message when no worktree could be located or all actions failed. */
+  error?: string;
+}