@cleocode/contracts 2026.5.61 → 2026.5.63

package/src/operations/nexus-scope.ts

@@ -0,0 +1,217 @@
+/**
+ * Nexus operation scope contracts — discriminated unions and descriptor
+ * interface used by the NEXUS_SCOPE_MAP SSoT.
+ *
+ * @task T9145
+ * @module operations/nexus-scope
+ */
+
+// ---------------------------------------------------------------------------
+// NexusScope — five-state discriminated union
+// ---------------------------------------------------------------------------
+
+/**
+ * Five-state scope classification for Nexus operations.
+ *
+ * - `project`      — Operates on a single registered project graph.
+ * - `living-brain` — Reads/writes the BRAIN (memory) store.
+ * - `cross`        — Spans multiple project graphs or compares them.
+ * - `hybrid`       — Touches both the project graph AND BRAIN.
+ * - `global`       — Operates on the global Nexus registry (all projects).
+ */
+export type NexusScope = 'project' | 'living-brain' | 'cross' | 'hybrid' | 'global';
+
+// ---------------------------------------------------------------------------
+// NexusEffect — read / write / admin axis
+// ---------------------------------------------------------------------------
+
+/**
+ * Side-effect classification for a Nexus operation.
+ *
+ * - `read`  — Pure query; no persistent state change.
+ * - `write` — Mutates the target store(s).
+ * - `admin` — Administrative operation (register/unregister/permission).
+ */
+export type NexusEffect = 'read' | 'write' | 'admin';
+
+// ---------------------------------------------------------------------------
+// NexusStore — target data stores
+// ---------------------------------------------------------------------------
+
+/**
+ * The persistent stores a Nexus operation may touch.
+ *
+ * - `nexus-graph`    — The graph DB (nodes + relations for a project).
+ * - `nexus-registry` — The global project registry.
+ * - `brain`          — The BRAIN memory / observation store.
+ * - `tasks`          — The task store (nexus → task bridge operations).
+ * - `fs`             — The local filesystem (scan / walk / snapshot).
+ */
+export type NexusStore = 'nexus-graph' | 'nexus-registry' | 'brain' | 'tasks' | 'fs';
+
+// ---------------------------------------------------------------------------
+// ScopeBinding — links an operation key to scope + effect metadata
+// ---------------------------------------------------------------------------
+
+/**
+ * A single scope binding, attaching NexusScope and NexusEffect metadata to
+ * a named Nexus operation.
+ */
+export interface ScopeBinding {
+  /** The operation key as declared in {@link NexusOps}. */
+  readonly op: string;
+  /** Scope classification of this operation. */
+  readonly scope: NexusScope;
+  /** Side-effect classification. */
+  readonly effect: NexusEffect;
+  /** Stores this operation reads or writes. */
+  readonly stores: ReadonlyArray<NexusStore>;
+}
+
+// ---------------------------------------------------------------------------
+// NexusOperationDescriptor — full operation metadata
+// ---------------------------------------------------------------------------
+
+/**
+ * Rich metadata descriptor for a single Nexus operation.
+ *
+ * Used by the NEXUS_SCOPE_MAP SSoT to provide compile-time exhaustiveness
+ * checking and runtime helpers (`getNexusDescriptor`, `listOpsByScope`).
+ */
+export interface NexusOperationDescriptor {
+  /** The operation key as declared in {@link NexusOps}. */
+  readonly op: string;
+  /** Human-readable summary of the operation. */
+  readonly description: string;
+  /** Scope classification. */
+  readonly scope: NexusScope;
+  /** Side-effect classification. */
+  readonly effect: NexusEffect;
+  /** Stores this operation reads or writes. */
+  readonly stores: ReadonlyArray<NexusStore>;
+  /**
+   * Whether this operation requires a `projectId` parameter.
+   * Operations with `scope === 'global'` typically do NOT require one.
+   * @defaultValue `true`
+   */
+  readonly requiresProject: boolean;
+  /**
+   * When `true`, the decorator stamps `meta._nexus.indexFreshness` on the
+   * response envelope (top-level CLI invocations only; sub-calls inherit via
+   * `meta.requestId` lineage to avoid per-call git-status shell-outs).
+   *
+   * @defaultValue `false`
+   * @task T9146
+   */
+  readonly indexSensitive?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// W2: NexusScopeMeta — namespaced _nexus block stamped on every response
+// ---------------------------------------------------------------------------
+
+/**
+ * Source of the `projectId` binding for a nexus operation.
+ *
+ * - `arg-project-id` — caller supplied `--project-id` explicitly.
+ * - `arg-path`       — resolved from `--path` argument.
+ * - `cwd`            — derived from current working directory.
+ * - `registry`       — looked up via the global project registry.
+ * - `none`           — operation does not require a project binding.
+ *
+ * @task T9146
+ */
+export type NexusBindingSource = 'arg-project-id' | 'arg-path' | 'cwd' | 'registry' | 'none';
+
+/**
+ * A structured suggestion for the next action an agent should take after a
+ * Nexus operation completes.
+ *
+ * Machine-readable — display strings are derived from these fields.
+ *
+ * @task T9146
+ */
+export interface SuggestedNextOp {
+  /** Nexus operation key (must exist in NEXUS_SCOPE_MAP). */
+  readonly op: string;
+  /** Arguments to pass to the operation. */
+  readonly args: Readonly<Record<string, unknown>>;
+  /** Scope of the suggested operation. */
+  readonly scope: NexusScope;
+  /** Side-effect classification of the suggested operation. */
+  readonly effect: NexusEffect;
+  /** Whether the agent should confirm with the user before executing. */
+  readonly requiresConfirmation: boolean;
+  /** Human-readable rationale for why this next step is suggested. */
+  readonly reason: string;
+}
+
+/**
+ * Namespaced `_nexus` block attached to every nexus-domain dispatch response
+ * under `meta._nexus`.
+ *
+ * Consumed by agents, renderers, and downstream middleware for scope-aware
+ * routing and display.
+ *
+ * @task T9146
+ */
+export interface NexusScopeMeta {
+  /** Scope classification of the operation that produced this envelope. */
+  readonly scope: NexusScope;
+  /** Side-effect classification of the operation. */
+  readonly effect: NexusEffect;
+  /**
+   * Resolved project identifier (undefined for `global` / `living-brain`
+   * scope operations that do not require a project).
+   */
+  readonly projectId?: string;
+  /** Human-readable project name from the registry (if available). */
+  readonly projectName?: string;
+  /** Absolute filesystem path to the project root. */
+  readonly projectPath?: string;
+  /** Absolute path to the nexus DB or registry file. */
+  readonly registryPath?: string;
+  /** How the `projectId` was resolved for this request. */
+  readonly bindingSource: NexusBindingSource;
+  /**
+   * For `hybrid`-scope operations: the ID of the secondary project
+   * (the one whose data is being compared or merged with the primary).
+   */
+  readonly counterpartProjectId?: string;
+  /**
+   * Whether the nexus index was considered fresh at the time of this call.
+   * Only present when `descriptor.indexSensitive === true` AND this was a
+   * top-level CLI invocation (sub-calls inherit via `meta.requestId` lineage).
+   */
+  readonly indexFreshness?: 'fresh' | 'stale' | 'unknown';
+  /**
+   * The canonical CLI command string for this operation (e.g. `"cleo nexus context"`).
+   */
+  readonly canonicalCommand: string;
+  /**
+   * If this operation is a legacy alias, the canonical op key it maps to.
+   * Absent when the operation is already canonical.
+   */
+  readonly legacyAliasFor?: string;
+  /** Non-fatal warnings surfaced from descriptor or runtime resolution. */
+  readonly warnings?: ReadonlyArray<string>;
+  /**
+   * Structured suggestions for what the agent should do next.
+   * Every entry's `.op` MUST resolve to a known NEXUS_SCOPE_MAP entry
+   * (enforced at build time by the typed-registry gate in nexus-decorator.ts).
+   */
+  readonly suggestedNext?: ReadonlyArray<SuggestedNextOp>;
+}
+
+/**
+ * Utility type that intersects {@link NexusScopeMeta} into `meta._nexus` for
+ * nexus-domain dispatch responses.
+ *
+ * Use this to narrow the `meta` field when processing nexus responses.
+ *
+ * @task T9146
+ */
+export interface MetaWithNexusScope {
+  _nexus: NexusScopeMeta;
+  [key: string]: unknown;
+}

package/src/operations/session.ts

@@ -200,6 +200,91 @@ export interface SessionHandoffShowResult {
   handoff: unknown;
 }
 
+// ---------------------------------------------------------------------------
+// BriefingFieldContract — per-field staleness + dedup rules (T1905 / BBTT-W1-3)
+// ---------------------------------------------------------------------------
+
+/**
+ * Provenance category for briefing observation exclusion.
+ *
+ * @task T1905
+ */
+export type BriefingExcludeProvenance = 'test-fixture' | 'synthetic' | 'imported';
+
+/**
+ * Per-field contract rule for a single briefing field.
+ *
+ * Defines staleness and deduplication constraints for one named section
+ * of the `SessionBriefingShowResult`. `assertBriefingContract` evaluates
+ * these rules and emits a `ContractViolation` for each breach.
+ *
+ * @task T1905
+ */
+export interface BriefingFieldRule {
+  /**
+   * Maximum acceptable age (in days) for any observation surfaced in this field.
+   * A violation is emitted when `now - capturedAt > maxAgeDays * 86_400_000`.
+   */
+  maxAgeDays?: number;
+  /**
+   * Deduplication key — field path within each list item used to detect
+   * duplicate entries (e.g. `'id'` deduplicates by task ID).
+   * When set, the contract checker warns if two items share the same key value.
+   */
+  dedupBy?: string;
+  /**
+   * Provenance tags whose observations must be excluded from this field.
+   * Violations are emitted when an item carries one of these provenance values.
+   */
+  excludeProvenance?: BriefingExcludeProvenance[];
+}
+
+/**
+ * Full briefing field contract — maps each named briefing section to its rule.
+ *
+ * Pass to `assertBriefingContract` together with the computed briefing to
+ * obtain `ContractViolation[]`.
+ *
+ * @example
+ * ```ts
+ * const contract: BriefingFieldContract = {
+ *   recentObservations: { maxAgeDays: 7, excludeProvenance: ['test-fixture'] },
+ *   nextTasks:           { dedupBy: 'id' },
+ * };
+ * ```
+ *
+ * @task T1905
+ */
+export interface BriefingFieldContract {
+  recentObservations?: BriefingFieldRule;
+  nextTasks?: BriefingFieldRule;
+  openBugs?: BriefingFieldRule;
+  blockedTasks?: BriefingFieldRule;
+  activeEpics?: BriefingFieldRule;
+  [field: string]: BriefingFieldRule | undefined;
+}
+
+/**
+ * A single contract violation emitted by `assertBriefingContract`.
+ *
+ * @task T1905
+ */
+export interface ContractViolation {
+  /** Name of the briefing field that violated its rule. */
+  field: string;
+  /** Human-readable description of the violation. */
+  message: string;
+  /**
+   * Violation kind for programmatic handling.
+   * - `stale` — field data exceeds `maxAgeDays`.
+   * - `duplicate` — two items share the same `dedupBy` key value.
+   * - `excluded-provenance` — item carries a banned provenance tag.
+   */
+  kind: 'stale' | 'duplicate' | 'excluded-provenance';
+  /** Severity — P0 violations block `cleo briefing --strict`. */
+  severity: 'P0' | 'P1';
+}
+
 // session.briefing.show
 /** Parameters for `session.briefing.show`. */
 export interface SessionBriefingShowParams {
@@ -208,6 +293,8 @@ export interface SessionBriefingShowParams {
   maxBlocked?: number;
   maxEpics?: number;
   scope?: string;
+  /** When true, exit non-zero if any contract violation is detected (T1905). */
+  strict?: boolean;
 }
 
 /** Compact task entry in a session briefing's next-tasks list. */

package/src/operations/tasks.ts

@@ -630,6 +630,29 @@ export interface TasksRelatesAddResult {
   added: boolean;
 }
 
+// tasks.relates.remove
+export interface TasksRelatesRemoveParams {
+  /** Source task ID. */
+  taskId: string;
+  /** Target task ID to remove the relation to. */
+  relatedId: string;
+  /** Optional relation type to narrow the deletion (omit to remove any type). */
+  type?: string;
+}
+/**
+ * Result of `tasks.relates.remove` — relation deletion confirmation.
+ *
+ * @task T9240
+ */
+export interface TasksRelatesRemoveResult {
+  /** Source task ID. */
+  from: string;
+  /** Target (related) task ID. */
+  to: string;
+  /** Whether a relation was actually deleted. */
+  removed: boolean;
+}
+
 // tasks.add (dispatch-level params — extends TasksCreateParams)
 export interface TasksAddParams {
   title: string;
@@ -708,6 +731,10 @@ export interface TasksUpdateQueryParams {
   type?: string; // SSoT-EXEMPT:kind≠type — 'type' is hierarchy(epic|task|subtask), 'kind' is intent(work|bug|...) — separate axes T944
   size?: string;
   files?: string[];
+  /** Add files incrementally (mirrors --add-labels pattern). @task T9242 */
+  addFiles?: string[];
+  /** Remove files incrementally (mirrors --remove-labels pattern). @task T9242 */
+  removeFiles?: string[];
   pipelineStage?: string;
   /** Canonical wire field for task kind axis (T9072: renamed from role). */
   kind?: string;
@@ -725,6 +752,8 @@ export interface TasksUpdateQueryParams {
   reason?: string;
   /** Dependency declaration waiver for critical-priority tasks (T1856). */
   dependsWaiver?: string;
+  /** Clear the blockedBy free-text reason (set to undefined). @task T9241 */
+  clearBlockedBy?: boolean;
 }
 /**
  * Result of `tasks.update` — the updated task record with change list.
@@ -917,6 +946,7 @@ export type TasksOps = {
   readonly reparent: readonly [TasksReparentQueryParams, TasksReparentDispatchResult];
   readonly reorder: readonly [TasksReorderQueryParams, TasksReorderDispatchResult];
   readonly 'relates.add': readonly [TasksRelatesAddParams, TasksRelatesAddResult];
+  readonly 'relates.remove': readonly [TasksRelatesRemoveParams, TasksRelatesRemoveResult];
   readonly start: readonly [TasksStartQueryParams, TasksStartQueryResult];
   readonly stop: readonly [TasksStopQueryParams, TasksStopQueryResult];
   readonly 'sync.reconcile': readonly [TasksSyncReconcileParams, TasksSyncReconcileResult];

package/src/operations/worktree.ts

@@ -135,6 +135,39 @@ export interface CreateWorktreeOptions {
    * @default true
    */
   lockWorktree?: boolean;
+  /**
+   * Glob patterns to exclude from the worktree via sparse-checkout after
+   * creation (T9226 spawn-clone-exclude filter).
+   *
+   * When set, `createWorktree` enables sparse-checkout on the new worktree
+   * and hides all files matching any pattern. Callers should also supply
+   * `spawnCloneExcludeExempt` to preserve the task-scoped file.
+   *
+   * @task T9226
+   */
+  spawnCloneExclude?: readonly string[];
+  /**
+   * Specific file paths to re-include after the exclude filter is applied.
+   *
+   * Used to preserve the task's own verifier (`scripts/verify-<taskId>.mjs`)
+   * after the broad `scripts/verify-*.mjs` exclusion.
+   *
+   * @task T9226
+   */
+  spawnCloneExcludeExempt?: readonly string[];
+  /**
+   * When `true`, forcibly reset an existing `task/<taskId>` branch that has
+   * orphan commits (commits not reachable from `baseRef`).
+   *
+   * Without this flag, `createWorktree` throws `E_DIRTY_BRANCH` when an orphan
+   * branch is detected so the caller can investigate before losing history.
+   * Set to `true` only when you are certain the prior branch state is stale and
+   * safe to discard (e.g. CI retry or integration-test re-runs).
+   *
+   * @default false
+   * @task T1927
+   */
+  forceReset?: boolean;
 }
 
 /**

package/src/task.ts

@@ -87,8 +87,12 @@ export type TaskSize = 'small' | 'medium' | 'large';
 /** Epic lifecycle states. */
 export type EpicLifecycle = 'backlog' | 'planning' | 'active' | 'review' | 'released' | 'archived';
 
-/** Task origin (provenance). */
+/** Task origin (provenance). T1899: added production/test-fixture/imported/migrated. */
 export type TaskOrigin =
+  | 'production'
+  | 'test-fixture'
+  | 'imported'
+  | 'migrated'
   | 'internal'
   | 'bug-report'
   | 'feature-request'
@@ -97,6 +101,19 @@ export type TaskOrigin =
   | 'dependency'
   | 'regression';
 
+/** Canonical origin values for the T1899 CHECK constraint. */
+export const TASK_ORIGIN_CANONICAL = [
+  'production',
+  'test-fixture',
+  'imported',
+  'migrated',
+] as const satisfies readonly TaskOrigin[];
+
+/** Whether an origin value is a test-fixture (should be excluded from live briefing). */
+export function isTestFixtureOrigin(origin: string | null | undefined): boolean {
+  return origin === 'test-fixture';
+}
+
 /** Verification agent types. */
 export type VerificationAgent =
   | 'planner'
@@ -463,6 +480,18 @@ export interface Task {
 
   /** Agent ID that has claimed/is assigned to this task. Null when unclaimed. @defaultValue undefined */
   assignee?: string | null;
+
+  /**
+   * Abort reason when a worker was stopped due to runaway detection (T1658).
+   *
+   * Set by the sentient monitor when a worker exceeds its size-based budget
+   * (`small` ≥ 30 min, `medium` ≥ 2 h, `large` ≥ 4 h). The field is
+   * informational — callers may surface it in `cleo sentient monitor` output.
+   *
+   * @task T1658
+   * @defaultValue undefined
+   */
+  abortReason?: string | null;
 }
 
 // ---------------------------------------------------------------------------

package/src/tasks.ts

@@ -24,8 +24,6 @@ import type { TaskPriority, TaskStatus } from './task.js';
 /**
  * RCASD-IVTR+C pipeline stage values valid for `TaskView.pipelineStage`.
  *
- * Mirrors `TaskViewPipelineStage` from `packages/core/src/tasks/compute-task-view.ts`.
- *
  * @task T1703
  */
 export type TaskViewPipelineStage =