@cleocode/contracts 2026.9.20 → 2026.9.22

package/src/index.ts

@@ -365,6 +365,7 @@ export type {
   TaskFieldUpdates,
   TaskPopulation,
   TaskQueryFilters,
+  TaskWriteGuard,
   TransactionAccessor,
 } from './data-accessor.js';
 // === Database Inventory (Saga T10281 / Epic T10282 / Task T10305 — SG-BRAIN-DB-RESILIENCE) ===
@@ -512,6 +513,28 @@ export type {
   WorktreeAnomaly,
   WorktreeAnomalyKind,
 } from './doctor.js';
+// === Done planner: read-only `cleo done --plan` evidence plan (T12623, T12624) ===
+export type {
+  ChangeSetDoc,
+  ChangeSetMergeState,
+  ChangeSetPrCandidate,
+  ChangeSetRootSource,
+  ChangeSetSource,
+  DoneBlockedDetails,
+  DoneNextStep,
+  DonePlan,
+  DonePlanAcBasis,
+  DonePlanAcMapping,
+  DonePlanBlocker,
+  DonePlanBlockerCode,
+  DonePlanGate,
+  DonePlanToolCacheState,
+  DonePlanToolRun,
+  DonePlanTypedGate,
+  DoneRecordResult,
+  DoneToolResult,
+  TaskChangeSet,
+} from './done-plan.js';
 export type {
   EngineErrorPayload,
   EngineFailure,
@@ -715,7 +738,11 @@ export type {
   ExtractedProvenance,
   GraphEdgeConfidenceLabel,
   GraphIndexAssessment,
+  GraphIndexAssessmentProjection,
+  GraphIndexFilePage,
   GraphIndexFileReport,
+  GraphIndexFileStatus,
+  GraphIndexFileStatusCounts,
   GraphIndexFreshness,
   GraphIndexReferenceReport,
   GraphIndexRunSummary,
@@ -1274,6 +1301,7 @@ export type {
   ApplyInsightsResult,
   DialecticInsights,
   DialecticTurn,
+  DialecticTurnOrigin,
   EvaluateDialecticParams,
   EvaluateDialecticResult,
 } from './operations/dialectic.js';
@@ -1457,6 +1485,7 @@ export type {
   NexusDepsEntry,
   NexusDepsParams,
   NexusDepsResult,
+  NexusDeviceRecord,
   NexusDiffHealth,
   NexusDiffParams,
   NexusDiffResult,
@@ -1468,6 +1497,7 @@ export type {
   NexusFlowsResult,
   NexusFullContextParams,
   NexusFullContextResult,
+  NexusGitProbeErrorCode,
   NexusGraphEdge,
   NexusGraphNode,
   NexusGraphParams,
@@ -1497,14 +1527,20 @@ export type {
   NexusPermissionLevel,
   NexusPermissionSetParams,
   NexusPermissionSetResult,
+  NexusProjectCandidate,
   NexusProjectCheckout,
+  NexusProjectGitState,
+  NexusProjectLocationState,
   NexusProjectRecord,
   NexusProjectStats,
+  NexusProjectsCleanIdMismatch,
   NexusProjectsCleanParams,
   NexusProjectsCleanReason,
   NexusProjectsCleanReceipt,
+  NexusProjectsCleanRelocated,
   NexusProjectsCleanRemoval,
   NexusProjectsCleanResult,
+  NexusProjectsCleanUnreadable,
   NexusProjectsListParams,
   NexusProjectsListResult,
   NexusProjectsRegisterParams,
@@ -1513,6 +1549,8 @@ export type {
   NexusProjectsRemoveResult,
   NexusProjectsScanParams,
   NexusProjectsScanResult,
+  NexusProjectsStatusParams,
+  NexusProjectsStatusResult,
   NexusQueryCteParams,
   NexusQueryCteResult,
   NexusReconcileParams,
@@ -1521,7 +1559,15 @@ export type {
   NexusRefreshBridgeResult,
   NexusRegisterParams,
   NexusRegisterResult,
+  NexusRegistryAmbiguousAlias,
   NexusRegistryClassification,
+  NexusRegistryFinding,
+  NexusRegistryFindingKind,
+  NexusRegistryIntegrityReport,
+  NexusRegistryRepairAction,
+  NexusRegistryRepairReceipt,
+  NexusRegistryRollbackResult,
+  NexusRegistrySplitPeer,
   NexusResolveParams,
   NexusResolveResult,
   NexusRouteMapParams,
@@ -1610,8 +1656,10 @@ export type {
   NexusProfileUpsertResult,
   NexusProfileViewParams,
   NexusProfileViewResult,
+  UserProfileScope,
   UserProfileTrait,
 } from './operations/nexus-user-profile.js';
+export { USER_PROFILE_SCOPES } from './operations/nexus-user-profile.js';
 // Commonly used ops types re-exported at top level for convenience
 export type {
   BrainState,
@@ -1932,6 +1980,10 @@ export type {
   WorktreeLifecycleAction,
   WorktreeLifecycleAuditEntry,
   WorktreeListEntry,
+  WorktreeLockAcquisition,
+  WorktreeLockAcquisitionStatus,
+  WorktreeLockHolder,
+  WorktreeLockRecord,
   WorktreeSource,
   WorktreeStatusCategory,
 } from './operations/worktree.js';
@@ -2011,6 +2063,8 @@ export type {
   SyncResult,
   SyncStatus,
 } from './postgres-data-accessor.js';
+// === Process-table probe constants (T12500 · T12506) ===
+export { PS_STABLE_ENV } from './process-probe.js';
 // === Project Context (ecosystem detection types) ===
 export type {
   EcosystemHint,
@@ -2020,6 +2074,16 @@ export type {
   ProjectType,
   TestFramework,
 } from './project-context.js';
+// === Project relocation (move / reroot — T12552 · T12558) ===
+export type {
+  MoveProjectResult,
+  ProjectMovedTombstone,
+  ProjectRelocationExclusion,
+  ProjectRelocationKind,
+  ProjectRelocationPlan,
+  ProjectRelocationRegistryAction,
+  RerootProjectResult,
+} from './project-lifecycle.js';
 // === ProjectTools Contracts (scaffold-project, doctor-project, scaffold-global — T10069 / T9835b) ===
 export type {
   DoctorProjectOptions,
@@ -2400,6 +2464,20 @@ export {
   SupervisorIpcResponseEnvelopeSchema,
   SupervisorIpcResponseSchema,
 } from './supervisor-ipc/index.js';
+// === Table Classification Types (T12332 — Gate A replication classes) ===
+export type {
+  ColumnClass,
+  ColumnOverride,
+  PendingTableClassification,
+  RowRouting,
+  TableClass,
+  TableClassification,
+  TableClassificationStatus,
+  TablePatternRule,
+  TableRegistryEntry,
+  TableScope,
+  TableScopeRegistry,
+} from './table-classification.js';
 // === Task Types ===
 export type {
   AcceptanceItem,
@@ -2807,4 +2885,44 @@ export {
   DEFAULT_IDENTITY_FIELD,
 } from './collection-keys.js';
 
+// === Typed-decision contracts (T12489 · epic T12486) ===
+export type {
+  ChoiceDecisionAnswer,
+  ChoiceDecisionQuestion,
+  DecisionAnswer,
+  DecisionInstructions,
+  DecisionJsonValue,
+  DecisionOutcome,
+  DecisionOutcomeSource,
+  DecisionProviderConfig,
+  DecisionQuestion,
+  DecisionQuestionType,
+  DecisionRequest,
+  DecisionState,
+  NoulDecisionAnswer,
+  NoulDecisionQuestion,
+  ScoreDecisionAnswer,
+  ScoreDecisionQuestion,
+} from './decide.js';
+export {
+  choiceDecisionAnswerSchema,
+  choiceDecisionQuestionSchema,
+  DECISION_OUTCOME_SOURCES,
+  DECISION_QUESTION_TYPES,
+  DECISION_REQUEST_LIMITS,
+  decisionAnswerSchema,
+  decisionInstructionsSchema,
+  decisionOutcomeSchema,
+  decisionOutcomeSourceSchema,
+  decisionProviderConfigSchema,
+  decisionQuestionSchema,
+  decisionQuestionTypeSchema,
+  decisionRequestSchema,
+  decisionStateSchema,
+  noulDecisionAnswerSchema,
+  noulDecisionQuestionSchema,
+  scoreDecisionAnswerSchema,
+  scoreDecisionQuestionSchema,
+} from './decide.js';
+
 export { isStorableTaskId, isTaskId, TASK_ID_REGEX, type TaskId } from './task-id.js';

package/src/memory/observe.ts

@@ -115,6 +115,13 @@ export interface ObserveBrainParams {
    * Null for directly-observed rows.
    */
   provenanceChain?: string[] | null;
+  /**
+   * T12494: opt in to a System One type choice when `type` is absent.
+   * Set ONLY by the interactive `memory.observe` operation (`cleo memory
+   * observe`). Background writers leave it unset, so they never send their
+   * content to a provider; their type comes from the keyword heuristic.
+   */
+  askTypeDecision?: boolean;
   /**
    * T992: Internal flag — when true, bypasses the verifyAndStore gate.
    * Set by storeVerifiedCandidate in extraction-gate.ts to avoid recursion,
@@ -148,6 +155,15 @@ export interface ObserveBrainResult {
   type: string;
   /** ISO 8601 creation timestamp. */
   createdAt: string;
+  /**
+   * T12494: where the stored type came from — `caller` (explicit `type`),
+   * `keyword` (whole-word keyword heuristic) or `system-one` (a confident
+   * System One `choice` in `on` mode). Absent when not determined on this path
+   * (e.g. the extraction gate merged or rejected the write).
+   */
+  typeSource?: 'caller' | 'keyword' | 'system-one';
+  /** T12494: confidence behind a `keyword` (flat 0.5) or `system-one` type. */
+  typeConfidence?: number;
 }
 
 // ── DocAttachmentObservationPayload ─────────────────────────────────

package/src/operations/__tests__/release-shared-surface.test.ts

@@ -0,0 +1,112 @@
+/**
+ * T10483 — release command/template shared-surface contract.
+ *
+ * These tests pin the taxonomy needed by T10468/T10476: shipped CLEO release
+ * commands, cleocode dogfood workflow templates, and the command↔template seams
+ * that are shared public surfaces. They also protect deterministic
+ * changesets-first release planning and the no-LLM blocking path invariant.
+ */
+
+import { existsSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import {
+  RELEASE_SHARED_COMMAND_SURFACES,
+  RELEASE_SHARED_SURFACE_CONTRACT,
+  RELEASE_SHARED_TEMPLATE_SURFACES,
+} from '../release.js';
+
+/** Repository root, resolved from this file (`packages/contracts/src/operations/__tests__`). */
+const REPO_ROOT = fileURLToPath(new URL('../../../../../', import.meta.url));
+/** The shipped workflow-template directory the contract claims to cover. */
+const WORKFLOW_TEMPLATE_DIR = fileURLToPath(
+  new URL('../../../../core/templates/workflows/', import.meta.url),
+);
+
+describe('release shared-surface contract (T10483)', () => {
+  it('classifies shipped release surfaces as consumer tooling or shared, never dogfood', () => {
+    const audiences = new Set<string>([
+      ...RELEASE_SHARED_COMMAND_SURFACES.map((surface) => surface.audience),
+      ...RELEASE_SHARED_TEMPLATE_SURFACES.map((surface) => surface.audience),
+    ]);
+
+    // Dogfood-only owner CI lives in the cleocode repo's .github/workflows and
+    // is never shipped, so no shipped command or template may carry it.
+    expect(audiences).toEqual(new Set(['shipped-consumer-tooling', 'shared-surface']));
+  });
+
+  it('pins every command to its registered dispatch gateway/operation', () => {
+    const byCommand = new Map(
+      RELEASE_SHARED_COMMAND_SURFACES.map((surface) => [
+        surface.command,
+        `${surface.gateway}:${surface.operation}`,
+      ]),
+    );
+
+    expect(byCommand).toEqual(
+      new Map([
+        ['cleo release plan', 'mutate:release.plan'],
+        ['cleo release open', 'mutate:release.open'],
+        ['cleo release reconcile', 'mutate:release.reconcile'],
+        ['cleo release rollback', 'mutate:pipeline.release.rollback'],
+      ]),
+    );
+  });
+
+  it('covers each shipped release workflow template on disk exactly once', () => {
+    // Compare against the real template directory, not a restated list, so a
+    // template added or removed without updating the contract fails here.
+    const onDisk = readdirSync(WORKFLOW_TEMPLATE_DIR)
+      .filter((name) => name.endsWith('.yml.tmpl'))
+      .map((name) => name.replace(/\.tmpl$/, ''))
+      .sort();
+    const rendered = RELEASE_SHARED_TEMPLATE_SURFACES.map((surface) => surface.renderedWorkflow);
+
+    expect(onDisk.length).toBeGreaterThan(0);
+    expect([...rendered].sort()).toEqual(onDisk);
+    for (const surface of RELEASE_SHARED_TEMPLATE_SURFACES) {
+      expect(existsSync(`${REPO_ROOT}${surface.template}`), surface.template).toBe(true);
+      expect(surface.template.endsWith(`/${surface.renderedWorkflow}.tmpl`)).toBe(true);
+    }
+  });
+
+  it('pins deterministic changesets-first planning as local and network-free', () => {
+    const plan = RELEASE_SHARED_COMMAND_SURFACES.find(
+      (surface) =>
+        surface.command === RELEASE_SHARED_SURFACE_CONTRACT.invariants.deterministicPlanningCommand,
+    );
+
+    expect(plan).toBeDefined();
+    expect(plan?.operation).toBe('release.plan');
+    expect(plan?.deterministic).toBe(true);
+    expect(plan?.mayCallNetwork).toBe(false);
+    expect(plan?.changesetRequired).toBe(true);
+  });
+
+  it('forbids LLM-first blocking paths on every release command and workflow template', () => {
+    expect(RELEASE_SHARED_SURFACE_CONTRACT.invariants.llmBlockingPathAllowed).toBe(false);
+
+    for (const surface of RELEASE_SHARED_COMMAND_SURFACES) {
+      expect(surface.llmBlockingPath).toBe(false);
+    }
+    for (const surface of RELEASE_SHARED_TEMPLATE_SURFACES) {
+      expect(surface.llmBlockingPath).toBe(false);
+    }
+  });
+
+  it('keeps public workflow templates attached to a shipped owner command', () => {
+    const commands = new Set(RELEASE_SHARED_COMMAND_SURFACES.map((surface) => surface.command));
+
+    for (const template of RELEASE_SHARED_TEMPLATE_SURFACES) {
+      expect(template.template).toMatch(
+        /^packages\/core\/templates\/workflows\/release-.+\.yml\.tmpl$/,
+      );
+      expect(template.renderSnapshotRequired).toBe(true);
+      if (template.stability === 'public-contract') {
+        expect(commands.has(template.owningCommand), template.owningCommand).toBe(true);
+        expect(template.audience).toBe('shared-surface');
+        expect(template.consumesReleasePlan).toBe(true);
+      }
+    }
+  });
+});

package/src/operations/dialectic.ts

@@ -55,8 +55,25 @@ export interface DialecticTurn {
   activePeerId: string;
   /** Session ID from the CLEO session store (e.g. `ses_20260422131135_5149eb`). */
   sessionId: string;
+  /**
+   * Structural origin of the turn (T12543). Omitted means `'conversation'`.
+   *
+   * `'operation-envelope'` marks a turn synthesised from a dispatched
+   * operation and its result envelope (the CQRS dispatcher hook). Such a turn
+   * carries no user utterance, so it can never yield a user trait: the
+   * evaluator drops every global trait for it and keeps only peer insights
+   * and the narrative delta.
+   */
+  origin?: DialecticTurnOrigin;
 }
 
+/**
+ * Structural origin of a {@link DialecticTurn}.
+ *
+ * @task T12543
+ */
+export type DialecticTurnOrigin = 'conversation' | 'operation-envelope';
+
 /**
  * Structured insights extracted from a single dialectic turn.
  *

package/src/operations/docs.ts

@@ -715,7 +715,9 @@ export type DocsLifecycleStatus = (typeof DOCS_LIFECYCLE_STATUSES)[number];
  * {@link DocsSupersedeParams}-style flows, NO supersession edge is created
  * (callers wanting an explicit lineage edge should use `cleo docs supersede`).
  *
- * Exactly one of `file` or `content` MUST be provided.
+ * At most one of `file` or `content` may be provided. With neither, `status`
+ * is required and the update changes only the lifecycle status, keeping the
+ * stored bytes (T12654).
  *
  * @task T10161 (Epic T10157 / Saga T9855 — E12.C4)
  */
@@ -738,7 +740,8 @@ export interface DocsUpdateParams {
   /**
    * Override the new lifecycle status. Defaults to `'draft'` on every update
    * so an explicit `accepted` doc gets back-pressured to draft on edit. Pass
-   * `--status accepted` (or any other valid status) to override.
+   * `--status accepted` (or any other valid status) to override. Passed alone
+   * (no `file`/`content`), it changes only the lifecycle status.
    */
   status?: DocsLifecycleStatus;
   /** Validate/preflight only; do not mutate attachment rows, blob storage, or audit logs. */

package/src/operations/memory.ts

@@ -1223,6 +1223,17 @@ export interface RetrievalObservation {
    * until the T1147 W7 sweep stamps them as clean.
    */
   provenanceClass?: string;
+  /**
+   * Stored quality score in [0, 1] (`quality_score` column), when the row
+   * carries one. Used to rank entries inside the spawn-prompt PSYCHE-MEMORY
+   * budget (T12519). Absent on legacy schemas.
+   */
+  qualityScore?: number;
+  /**
+   * Number of times this entry has been cited (`citation_count` column).
+   * Secondary ranking signal for the PSYCHE-MEMORY budget (T12519).
+   */
+  citationCount?: number;
 }
 
 /**
@@ -1241,6 +1252,17 @@ export interface RetrievalLearning {
    * until the T1147 W7 sweep stamps them as clean.
    */
   provenanceClass?: string;
+  /**
+   * Stored quality score in [0, 1] (`quality_score` column), when the row
+   * carries one. Used to rank entries inside the spawn-prompt PSYCHE-MEMORY
+   * budget (T12519). Absent on legacy schemas.
+   */
+  qualityScore?: number;
+  /**
+   * Number of times this entry has been cited (`citation_count` column).
+   * Secondary ranking signal for the PSYCHE-MEMORY budget (T12519).
+   */
+  citationCount?: number;
 }
 
 /**
@@ -1259,6 +1281,17 @@ export interface RetrievalPattern {
    * until the T1147 W7 sweep stamps them as clean.
    */
   provenanceClass?: string;
+  /**
+   * Stored quality score in [0, 1] (`quality_score` column), when the row
+   * carries one. Used to rank entries inside the spawn-prompt PSYCHE-MEMORY
+   * budget (T12519). Absent on legacy schemas.
+   */
+  qualityScore?: number;
+  /**
+   * Number of times this entry has been cited (`citation_count` column).
+   * Secondary ranking signal for the PSYCHE-MEMORY budget (T12519).
+   */
+  citationCount?: number;
 }
 
 /**
@@ -1277,6 +1310,21 @@ export interface RetrievalDecision {
    * until the T1147 W7 sweep stamps them as clean.
    */
   provenanceClass?: string;
+  /**
+   * Stored quality score in [0, 1] (`quality_score` column), when the row
+   * carries one. Used to rank entries inside the spawn-prompt PSYCHE-MEMORY
+   * budget (T12519). Absent on legacy schemas.
+   */
+  qualityScore?: number;
+  /**
+   * Number of times this entry has been cited (`citation_count` column).
+   * Secondary ranking signal for the PSYCHE-MEMORY budget (T12519).
+   */
+  citationCount?: number;
+  /** Task the decision was recorded against (`context_task_id`), if any (T12519). */
+  contextTaskId?: string | null;
+  /** Epic the decision was recorded against (`context_epic_id`), if any (T12519). */
+  contextEpicId?: string | null;
 }
 
 /**

package/src/operations/nexus-scope-map.ts

@@ -505,6 +505,15 @@ export const NEXUS_SCOPE_MAP = {
     stores: ['nexus-registry'],
     requiresProject: false,
   },
+  'projects.status': {
+    op: 'projects.status',
+    description:
+      'Probe git state (branch, head, dirty, upstream, ahead/behind) of every location on this device and record it.',
+    scope: 'global',
+    effect: 'write',
+    stores: ['nexus-registry', 'fs'],
+    requiresProject: false,
+  },
   'refresh-bridge': {
     op: 'refresh-bridge',
     description: 'Refresh the Nexus → BRAIN cross-store bridge.',

package/src/operations/nexus-user-profile.ts

@@ -24,6 +24,18 @@
 // Shared domain types
 // ============================================================================
 
+/**
+ * Legal visibility scopes for a user-profile trait (T12543).
+ *
+ * - `project` — visible only to agents working in the project whose portable
+ *   id is stamped on the trait (`projectId`). The default for every new row.
+ * - `user`    — explicitly marked user-global: visible in every project.
+ */
+export const USER_PROFILE_SCOPES = ['project', 'user'] as const;
+
+/** Visibility scope of a user-profile trait. See {@link USER_PROFILE_SCOPES}. */
+export type UserProfileScope = (typeof USER_PROFILE_SCOPES)[number];
+
 /**
  * A single user-profile trait record.
  *
@@ -61,6 +73,22 @@ export interface UserProfileTrait {
    * Set by `supersedeTrait` (T1139 supersession graph prep).
    */
   supersededBy: string | null;
+  /**
+   * Portable project id (`.cleo/project-id`, ADR-094) of the project the trait
+   * was derived in. `null` = unknown origin (rows written before T12543).
+   * Omitted on input means `null`.
+   *
+   * @task T12543
+   */
+  projectId?: string | null;
+  /**
+   * Visibility scope. Omitted on input means `'project'`. Spawn prompts include
+   * only `user` traits plus `project` traits whose `projectId` is the current
+   * project; unknown-origin rows are excluded.
+   *
+   * @task T12543
+   */
+  scope?: UserProfileScope;
 }
 
 // ============================================================================
@@ -180,7 +208,7 @@ export interface NexusProfileUpsertParams {
   /** Trait to create or update (required). */
   trait: Pick<
     UserProfileTrait,
-    'traitKey' | 'traitValue' | 'confidence' | 'source' | 'derivedFromMessageId'
+    'traitKey' | 'traitValue' | 'confidence' | 'source' | 'derivedFromMessageId' | 'scope'
   >;
 }