@cleocode/contracts 2026.4.96 → 2026.4.98

package/src/operations/release.ts

@@ -29,86 +29,156 @@ export interface ChangelogSection {
  */
 
 // release.prepare
+/**
+ * Parameters for `release.prepare`.
+ *
+ * @remarks
+ * Re-synced to match `prepareRelease(version, tasks?, notes?)` in
+ * `packages/core/src/release/release-manifest.ts`. The legacy `type` field
+ * was never accepted by the engine — the release manifest persists the
+ * version as-is after normalization. Task filtering happens via the
+ * optional `tasks` array (defaults to all tasks with `status=done`).
+ *
+ * @task T963 — contract↔impl drift reconciliation (T910 audit)
+ */
 export interface ReleasePrepareParams {
+  /** Version string (e.g. `YYYY.M.patch` or `X.Y.Z`). @task T963 */
   version: string;
-  type: ReleaseType;
-}
+  /**
+   * Specific task IDs to bundle into the release. When omitted, all
+   * completed tasks with `completedAt` are included.
+   * @task T963
+   */
+  tasks?: string[];
+  /** Free-form release notes persisted onto the manifest entry. @task T963 */
+  notes?: string;
+}
+/** Result of `release.prepare`. @task T963 */
 export interface ReleasePrepareResult {
+  /** Normalized version string. @task T963 */
   version: string;
-  type: ReleaseType;
-  currentVersion: string;
-  files: string[];
-  ready: boolean;
-  warnings: string[];
+  /** Manifest status — always `'prepared'` on success. @task T963 */
+  status: string;
+  /** Task IDs committed to the manifest. @task T963 */
+  tasks: string[];
+  /** Count of tasks in the release. @task T963 */
+  taskCount: number;
 }
 
 // release.changelog
+/** Parameters for `release.changelog`. @task T963 */
 export interface ReleaseChangelogParams {
+  /** Version to build the changelog for (must match an existing manifest). @task T963 */
   version: string;
+  /** Filter emitted sections. @task T963 */
   sections?: Array<'feat' | 'fix' | 'docs' | 'test' | 'refactor' | 'chore'>;
 }
+/** Result of `release.changelog`. @task T963 */
 export interface ReleaseChangelogResult {
+  /** Version. @task T963 */
   version: string;
+  /** Rendered changelog content (Markdown). @task T963 */
   content: string;
+  /** Grouped changelog sections. @task T963 */
   sections: ChangelogSection[];
+  /** Count of commits aggregated. @task T963 */
   commitCount: number;
 }
 
 // release.commit
+/** Parameters for `release.commit`. @task T963 */
 export interface ReleaseCommitParams {
+  /** Version tag being committed. @task T963 */
   version: string;
+  /** Files associated with the commit. @task T963 */
   files?: string[];
 }
+/** Result of `release.commit`. @task T963 */
 export interface ReleaseCommitResult {
+  /** Version. @task T963 */
   version: string;
+  /** Git commit hash. @task T963 */
   commitHash: string;
+  /** Commit message. @task T963 */
   message: string;
+  /** Files actually committed. @task T963 */
   filesCommitted: string[];
 }
 
 // release.tag
+/** Parameters for `release.tag`. @task T963 */
 export interface ReleaseTagParams {
+  /** Version being tagged. @task T963 */
   version: string;
+  /** Tag message (annotated tag). @task T963 */
   message?: string;
 }
+/** Result of `release.tag`. @task T963 */
 export interface ReleaseTagResult {
+  /** Version. @task T963 */
   version: string;
+  /** Tag name created. @task T963 */
   tagName: string;
+  /** ISO 8601 creation timestamp. @task T963 */
   created: string;
 }
 
 // release.push
+/** Parameters for `release.push`. @task T963 */
 export interface ReleasePushParams {
+  /** Version being pushed. @task T963 */
   version: string;
+  /** Git remote name. Defaults to `origin`. @task T963 */
   remote?: string;
 }
+/** Result of `release.push`. @task T963 */
 export interface ReleasePushResult {
+  /** Version. @task T963 */
   version: string;
+  /** Remote that received the push. @task T963 */
   remote: string;
+  /** ISO 8601 push timestamp. @task T963 */
   pushed: string;
+  /** Tags that were pushed alongside. @task T963 */
   tagsPushed: string[];
 }
 
 // release.gates.run
+/** Parameters for `release.gates.run`. @task T963 */
 export interface ReleaseGatesRunParams {
+  /** Specific gate names to run. Omit to run all. @task T963 */
   gates?: string[];
 }
+/** Result of `release.gates.run`. @task T963 */
 export interface ReleaseGatesRunResult {
+  /** Total gates evaluated. @task T963 */
   total: number;
+  /** Gates that passed. @task T963 */
   passed: number;
+  /** Gates that failed. @task T963 */
   failed: number;
+  /** Full per-gate report. @task T963 */
   gates: ReleaseGate[];
+  /** True when every gate passed. @task T963 */
   canRelease: boolean;
 }
 
 // release.rollback
+/** Parameters for `release.rollback`. @task T963 */
 export interface ReleaseRollbackParams {
+  /** Version to roll back. @task T963 */
   version: string;
+  /** Human-readable reason for the rollback. @task T963 */
   reason: string;
 }
+/** Result of `release.rollback`. @task T963 */
 export interface ReleaseRollbackResult {
+  /** Version that was rolled back. @task T963 */
   version: string;
+  /** ISO 8601 rollback timestamp. @task T963 */
   rolledBack: string;
+  /** Version that is now current. @task T963 */
   restoredVersion: string;
+  /** Rollback reason. @task T963 */
   reason: string;
 }

package/src/operations/session.ts

@@ -29,10 +29,33 @@ export interface SessionOp {
 
 // session.status
 export type SessionStatusParams = Record<string, never>;
+/**
+ * Result of `session.status`.
+ *
+ * @remarks
+ * Re-synced to match the envelope returned by `sessionStatus` in
+ * `packages/cleo/src/dispatch/engines/session-engine.ts`. The legacy
+ * contract's `{current, hasStartedTask, startedTask}` shape predated the
+ * current engine and never matched dispatch output — agents reading the
+ * contract would never find their data.
+ *
+ * @task T963 — contract↔impl drift reconciliation (T910 audit)
+ */
 export interface SessionStatusResult {
-  current: SessionOp | null;
-  hasStartedTask: boolean;
-  startedTask?: string;
+  /** True when a session is currently active. @task T963 */
+  hasActiveSession: boolean;
+  /**
+   * Active session record (full shape per `Session` contract) or `null`
+   * when none active.
+   * @task T963
+   */
+  session?: SessionOp | null;
+  /**
+   * Current task work state from `meta.focus_state` — tracks the
+   * task the orchestrator is focused on within the session.
+   * @task T963
+   */
+  taskWork?: import('../task.js').TaskWorkState | null;
 }
 
 // session.list

package/src/operations/tasks.ts

@@ -70,9 +70,39 @@ export interface TasksListResult {
 }
 
 // tasks.find
+/**
+ * Parameters for `tasks.find`.
+ *
+ * @remarks
+ * Re-synced to match `taskFind(projectRoot, query, limit, options)` in the
+ * dispatch layer. Legacy contract exposed only `{query, limit}` and hid
+ * the 7 additional filter options agents actually need.
+ *
+ * @task T963 — contract↔impl drift reconciliation (T910 audit)
+ */
 export interface TasksFindParams {
+  /** Free-text search query. @task T963 */
   query: string;
+  /** Max results. @task T963 */
   limit?: number;
+  /** Exact task ID lookup (bypasses search). @task T963 */
+  id?: string;
+  /** When true, require exact string match instead of fuzzy. @task T963 */
+  exact?: boolean;
+  /** Filter by status. @task T963 */
+  status?: TaskStatus;
+  /** When true, include archived tasks in the search. @task T963 */
+  includeArchive?: boolean;
+  /** Offset into the results (pagination). @task T963 */
+  offset?: number;
+  /**
+   * Comma-separated field projection (e.g. `'id,title,status'`) to shrink
+   * the wire payload.
+   * @task T963
+   */
+  fields?: string;
+  /** When true, emit verbose per-match diagnostic fields. @task T963 */
+  verbose?: boolean;
 }
 export type TasksFindResult = MinimalTask[];
 
@@ -157,33 +187,141 @@ export type TasksNextResult = SuggestedTask[];
  */
 
 // tasks.create
+/**
+ * Parameters for `tasks.create` / `tasks.add`.
+ *
+ * @remarks
+ * Re-synced to match `AddTaskOptions` in `packages/core/src/tasks/add.ts`
+ * and the dispatch handler in `packages/cleo/src/dispatch/domains/tasks.ts`.
+ * The legacy contract was missing 8 fields (`type`, `acceptance`, `phase`,
+ * `size`, `notes`, `files`, `dryRun`, `parentSearch`) — agents following
+ * the contract would omit them and fail CLEO's anti-hallucination + epic
+ * creation enforcement.
+ *
+ * @task T963 — contract↔impl drift reconciliation (T910 audit)
+ */
 export interface TasksCreateParams {
+  /** Task title (required, 1..200 chars). @task T963 */
   title: string;
+  /**
+   * Task description (required by anti-hallucination rule T5698 — must
+   * differ from `title`). The legacy contract marked this required; kept
+   * required here to preserve behavior.
+   * @task T963
+   */
   description: string;
+  /** Parent task id (`T###`). Omit for root-level tasks (epics only). @task T963 */
   parent?: string;
+  /** Task IDs this task depends on. @task T963 */
   depends?: string[];
+  /** Priority (`critical`|`high`|`medium`|`low`). Defaults to `medium`. @task T963 */
   priority?: TaskPriority;
+  /** Label tags (lowercase alphanumeric + hyphens/periods). @task T963 */
   labels?: string[];
+  /**
+   * Task type. When omitted, inferred from parent (epic-child → `task`,
+   * task-child → `subtask`, rootless → `task`). @task T963
+   */
+  type?: 'epic' | 'task' | 'subtask';
+  /**
+   * Acceptance criteria (pipe-separated strings). Minimum 3 required by
+   * enforcement layer; epics require minimum 5.
+   * @task T963
+   */
+  acceptance?: string[];
+  /** Phase slug (lowercase alphanumeric + hyphens). @task T963 */
+  phase?: string;
+  /** Task size (`small`|`medium`|`large`). Defaults to `medium`. @task T963 */
+  size?: 'small' | 'medium' | 'large';
+  /** Initial note text (timestamped at insertion). @task T963 */
+  notes?: string;
+  /** File paths associated with the task. @task T963 */
+  files?: string[];
+  /**
+   * When true, validate + preview the task without allocating a task id or
+   * writing to the DB. Preview returns an `id: 'T???'` placeholder.
+   * @task T963
+   */
+  dryRun?: boolean;
+  /**
+   * CLI helper for parent resolution via search term — when set, dispatch
+   * layer resolves the search to a parent id before calling core.
+   * @task T963
+   */
+  parentSearch?: string;
 }
 export type TasksCreateResult = TaskOp;
 
 // tasks.update
+/**
+ * Parameters for `tasks.update`.
+ *
+ * @remarks
+ * Re-synced to match `UpdateTaskOptions` in
+ * `packages/core/src/tasks/update.ts` and the dispatch handler in
+ * `packages/cleo/src/dispatch/domains/tasks.ts`. The legacy contract was
+ * missing `acceptance`, `pipelineStage` (T834 / ADR-051 Decision 4),
+ * `files`, `blockedBy`, `phase`, `noAutoComplete`, the narrow typing of
+ * `type`/`size`, and the `addDepends`/`removeDepends` array mutators.
+ *
+ * @task T963 — contract↔impl drift reconciliation (T910 audit)
+ */
 export interface TasksUpdateParams {
+  /** Task ID to update (required). @task T963 */
   taskId: string;
+  /** Replace title. @task T963 */
   title?: string;
+  /** Replace description. @task T963 */
   description?: string;
+  /** Target status — `done` transitions route through complete flow. @task T963 */
   status?: TaskStatus;
+  /** Replace priority. @task T963 */
   priority?: TaskPriority;
+  /** Append a timestamped note. @task T963 */
   notes?: string;
-  parent?: string | null; // Set parent ID, or null/"" to promote to root
+  /** Set parent ID, or null/"" to promote to root. @task T963 */
+  parent?: string | null;
+  /** Replace labels wholesale. @task T963 */
   labels?: string[];
+  /** Additive label insert. @task T963 */
   addLabels?: string[];
+  /** Label removal set. @task T963 */
   removeLabels?: string[];
+  /** Replace dependency list. @task T963 */
   depends?: string[];
+  /** Additive dependency insert. @task T963 */
   addDepends?: string[];
+  /** Dependency removal set. @task T963 */
   removeDepends?: string[];
-  type?: string;
-  size?: string;
+  /** Task type (`epic`|`task`|`subtask`). @task T963 */
+  type?: 'epic' | 'task' | 'subtask';
+  /** Task size (`small`|`medium`|`large`). @task T963 */
+  size?: 'small' | 'medium' | 'large';
+  /**
+   * Replace acceptance criteria. Subject to AC enforcement — min 3 for
+   * all tasks, min 5 for epics.
+   * @task T963
+   */
+  acceptance?: string[];
+  /** Replace files attached to the task. @task T963 */
+  files?: string[];
+  /** Phase slug (lowercase alphanumeric + hyphens). @task T963 */
+  phase?: string;
+  /** Blocking reason (set when status=`blocked`). @task T963 */
+  blockedBy?: string;
+  /**
+   * When true, skip auto-complete cascading when all children complete.
+   * @task T963
+   */
+  noAutoComplete?: boolean;
+  /**
+   * RCASD-IVTR+C pipeline stage transition target. Forward-only
+   * (validated by `validatePipelineTransition`); epic advancements are
+   * additionally gated by `validateEpicStageAdvancement`; non-epic tasks
+   * are gated by `validateChildStageCeiling` against their ancestor epic.
+   * @task T963 / T834 / ADR-051 Decision 4
+   */
+  pipelineStage?: string;
 }
 export type TasksUpdateResult = TaskOp;
 

package/src/sentient.ts

@@ -0,0 +1,100 @@
+/**
+ * Sentient Loop Tier-2 Contracts — Proposal types.
+ *
+ * Defines the shared interfaces for the Tier-2 proposal pipeline:
+ * ingester candidates, proposed-task metadata, and rate-limit results.
+ *
+ * These are LEAF types — zero runtime dependencies.
+ *
+ * @task T1008
+ * @see ADR-054 — Sentient Loop Tier-1 (Tier-2 extension)
+ */
+
+// ---------------------------------------------------------------------------
+// Proposal candidate (produced by ingesters)
+// ---------------------------------------------------------------------------
+
+/**
+ * Source system from which a proposal candidate was derived.
+ */
+export type ProposalSource = 'brain' | 'nexus' | 'test';
+
+/**
+ * A ranked proposal candidate produced by one of the three ingesters.
+ *
+ * Candidates are merged, deduplicated by fingerprint, scored, and written
+ * to tasks.db as rows with `status='proposed'` by the propose tick.
+ *
+ * Title format is ALWAYS a structured template — no freeform LLM text.
+ * This is a prompt-injection defence (T1008 §3.6).
+ */
+export interface ProposalCandidate {
+  /** Which ingester produced this candidate. */
+  source: ProposalSource;
+  /**
+   * Stable external identifier (brain entry id, nexus node id, file path).
+   * Used with `source` to compute the deduplication fingerprint.
+   */
+  sourceId: string;
+  /**
+   * Structured title — MUST match pattern `^\\[T2-(BRAIN|NEXUS|TEST)\\]`.
+   * No freeform LLM text is permitted here.
+   */
+  title: string;
+  /** Human-readable rationale (template-generated, not LLM-generated). */
+  rationale: string;
+  /**
+   * Relative priority weight in [0, 1].
+   * - BRAIN: `(citation_count / 10) * quality_score` capped at 1.0
+   * - NEXUS: fixed 0.3 base weight
+   * - TEST:  fixed 0.5 base weight
+   */
+  weight: number;
+}
+
+// ---------------------------------------------------------------------------
+// Proposed task meta (stored in tasks.metadataJson)
+// ---------------------------------------------------------------------------
+
+/**
+ * Metadata stored in `tasks.metadataJson` for rows created by the Tier-2
+ * proposer (`status='proposed'`).
+ *
+ * Parsed from JSON at read time; serialized to JSON at write time.
+ */
+export interface ProposedTaskMeta {
+  /**
+   * Identifier tag for the sentient proposer.
+   * Always `'sentient-tier2'` for Tier-2 proposals.
+   * Used in the transactional rate-limit count query.
+   */
+  proposedBy: 'sentient-tier2';
+  /** Source system that generated this proposal. */
+  source: ProposalSource;
+  /** External source ID (brain entry id, nexus node id, etc.). */
+  sourceId: string;
+  /** Computed weight at time of proposal. */
+  weight: number;
+  /** ISO-8601 timestamp when the proposal was generated. */
+  proposedAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Tier-2 stats
+// ---------------------------------------------------------------------------
+
+/**
+ * Rolling counters for Tier-2 proposal activity, persisted in sentient-state.json.
+ */
+export interface Tier2Stats {
+  /** Total proposals written to tasks.db as `status='proposed'`. */
+  proposalsGenerated: number;
+  /**
+   * Total proposals transitioned to `pending` by owner accept action.
+   */
+  proposalsAccepted: number;
+  /**
+   * Total proposals transitioned to `cancelled` by owner reject action.
+   */
+  proposalsRejected: number;
+}

package/src/status-registry.ts

@@ -19,6 +19,7 @@ export const TASK_STATUSES = [
   'done',
   'cancelled',
   'archived',
+  'proposed',
 ] as const;
 
 export const SESSION_STATUSES = ['active', 'ended', 'orphaned', 'suspended'] as const;
@@ -151,6 +152,7 @@ export const TASK_STATUS_SYMBOLS_UNICODE: Record<TaskStatus, string> = {
   done: '\u2713', // ✓  complete
   cancelled: '\u2717', // ✗  abandoned
   archived: '\u25a3', // ▣  stored, inactive
+  proposed: '\u25c7', // ◇  tier-2 proposal queue (T946)
 };
 
 /**
@@ -163,4 +165,5 @@ export const TASK_STATUS_SYMBOLS_ASCII: Record<TaskStatus, string> = {
   done: '+',
   cancelled: '~',
   archived: '#',
+  proposed: '?',
 };

package/src/task.ts

@@ -44,6 +44,39 @@ export type TaskPriority = 'critical' | 'high' | 'medium' | 'low';
 /** Task type in hierarchy. */
 export type TaskType = 'epic' | 'task' | 'subtask';
 
+/**
+ * Task role axis — orthogonal to {@link TaskType}, describes the intent of work.
+ * Defaults to `'work'` for backward compatibility.
+ *
+ * @task T944
+ */
+export type TaskRole = 'work' | 'research' | 'experiment' | 'bug' | 'spike' | 'release';
+
+/**
+ * Task scope axis — granularity of work. Orthogonal to {@link TaskType} and
+ * {@link TaskRole}. Defaults to `'feature'`.
+ *
+ * Legacy type → scope mapping on backfill:
+ * - `type='epic'`    → `scope='project'`
+ * - `type='task'`    → `scope='feature'`
+ * - `type='subtask'` → `scope='unit'`
+ *
+ * @task T944
+ */
+export type TaskScope = 'project' | 'feature' | 'unit';
+
+/**
+ * Bug severity axis. Only meaningful when `role='bug'`; enforced by a DB-level
+ * CHECK constraint (`severity IS NULL OR (severity IN (...) AND role='bug')`).
+ *
+ * OWNER-WRITE-ONLY: severity is intended to be set through owner-authenticated
+ * paths only. This prevents a prompt-injection exploit where a compromised
+ * Tier 3 agent could downgrade a P0 bug to P3 to force-ship.
+ *
+ * @task T944
+ */
+export type TaskSeverity = 'P0' | 'P1' | 'P2' | 'P3';
+
 /** Task size (scope, NOT time). */
 export type TaskSize = 'small' | 'medium' | 'large';
 
@@ -219,6 +252,27 @@ export interface Task {
   /** Task type in hierarchy. Inferred from parent context if not specified. @defaultValue undefined */
   type?: TaskType;
 
+  /**
+   * Task role axis — intent of work, orthogonal to {@link type}.
+   * Defaults to `'work'` at the DB level. @defaultValue 'work'
+   * @task T944
+   */
+  role?: TaskRole;
+
+  /**
+   * Task scope axis — granularity of work, orthogonal to {@link type} and
+   * {@link role}. Defaults to `'feature'` at the DB level. @defaultValue 'feature'
+   * @task T944
+   */
+  scope?: TaskScope;
+
+  /**
+   * Bug severity. Only valid when {@link role} is `'bug'`. OWNER-WRITE-ONLY.
+   * @defaultValue undefined
+   * @task T944
+   */
+  severity?: TaskSeverity | null;
+
   /** ID of the parent task. `null` for root-level tasks. @defaultValue undefined */
   parentId?: string | null;
 
@@ -356,6 +410,27 @@ export interface TaskCreate {
   /** Task type. Inferred from parent context if not specified. @defaultValue undefined */
   type?: TaskType;
 
+  /**
+   * Task role — intent of work. Defaults to `'work'` at the DB level.
+   * @defaultValue 'work'
+   * @task T944
+   */
+  role?: TaskRole;
+
+  /**
+   * Task scope — granularity of work. Defaults to `'feature'` at the DB level.
+   * @defaultValue 'feature'
+   * @task T944
+   */
+  scope?: TaskScope;
+
+  /**
+   * Bug severity (OWNER-WRITE-ONLY). Only valid with `role='bug'`.
+   * @defaultValue undefined
+   * @task T944
+   */
+  severity?: TaskSeverity | null;
+
   /** Parent task ID for hierarchy placement. @defaultValue undefined */
   parentId?: string | null;