@cleocode/contracts 2026.9.21 → 2026.9.23

package/src/operations/admin.ts

@@ -1648,6 +1648,11 @@ export interface AdminBackupMutateParams {
   file?: string;
   /** Preview the restore without writing (restore.file only). */
   dryRun?: boolean;
+  /**
+   * Allow a restore run from inside a git worktree to overwrite the owning
+   * project's live store (T12680). Without it such a restore is refused.
+   */
+  confirmOwnerStore?: boolean;
 }
 
 /** Result of `admin.backup` mutate (create action). */

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/tasks.ts

@@ -921,6 +921,31 @@ export interface TasksComplexityEstimateResult {
 export interface TasksHistoryParams {
   taskId?: string;
   limit?: number;
+  /**
+   * With `taskId`: only ranking-input changes (priority, severity, kind,
+   * depends) — who, which session, why, before/after (T12693, D11161).
+   */
+  ranking?: boolean;
+}
+
+// tasks.ranking.revert
+/** Parameters for `tasks.ranking.revert` (T12693, D11161). */
+export interface TasksRankingRevertParams {
+  /** The `ranking_changed` audit row id to undo (from `cleo history ranking`). */
+  entryId: string;
+  /** Why it is reverted; recorded on the new audit row. */
+  reason?: string;
+  /** Revert even though a field changed again since. */
+  force?: boolean;
+}
+/** Result of `tasks.ranking.revert`. */
+export interface TasksRankingRevertResult {
+  /** Task whose ranking inputs were restored. */
+  taskId: string;
+  /** Fields set back. */
+  fields: string[];
+  /** The values they were set back to. */
+  revertedTo: Record<string, unknown>;
 }
 /**
  * Result of `tasks.history` — audit log entries for a task.
@@ -2277,6 +2302,7 @@ export type TasksOps = {
   readonly 'relates.add': readonly [TasksRelatesAddParams, TasksRelatesAddResult];
   readonly 'relates.add-batch': readonly [TasksRelatesAddBatchParams, TasksRelatesAddBatchResult];
   readonly 'relates.remove': readonly [TasksRelatesRemoveParams, TasksRelatesRemoveResult];
+  readonly 'ranking.revert': readonly [TasksRankingRevertParams, TasksRankingRevertResult];
   readonly start: readonly [TasksStartQueryParams, TasksStartQueryResult];
   readonly stop: readonly [TasksStopQueryParams, TasksStopQueryResult];
   readonly 'sync.reconcile': readonly [TasksSyncReconcileParams, TasksSyncReconcileResult];

package/src/task.ts

@@ -170,6 +170,12 @@ export interface EvidenceValidationContext {
   criteria: ReadonlyArray<Pick<AcRow, 'id' | 'text' | 'updatedAt'>>;
   /** Verified PR merge whose immutable artifact bytes must be inspected. */
   artifactCommitSha?: string;
+  /**
+   * Validate without persisting anything: `pr:`/`ci:` lookups write neither
+   * the PR-result cache nor the branch-protection cache (T12671 review — the
+   * `cleo done --plan` preview must leave `.cleo/` untouched).
+   */
+  readOnly?: boolean;
 }
 
 /** Explicit criterion link to inspected artifacts and validated results in one gate receipt. */
@@ -181,6 +187,14 @@ export interface CriterionEvidenceLink {
   artifactPaths: string[];
   /** Indices of actual validated result atoms in the containing gate's atoms array. */
   resultAtomIndices: number[];
+  /**
+   * How the `implemented` link is supported (T12689): `files` when a path the
+   * criterion names is among the inspected artifacts; `self-attested` when the
+   * criterion names no path in them, so the link rests on the agent's claim.
+   * Paths parsed from criterion text are advisory (T12118), so this flags
+   * rather than refuses. Absent on other gates and on older receipts.
+   */
+  basis?: 'files' | 'self-attested';
 }
 
 /** Verification failure log entry. */
@@ -371,10 +385,25 @@ export type EvidenceAtom =
       successCount: number;
       /** Total number of checks evaluated in the rollup. */
       totalChecks: number;
-      /** Complete PR changed-file inventory retained for task-scope checks and display. */
+      /**
+       * Changed-file inventory retained for task-scope checks and display. With
+       * `componentPrNumber`, the component PR's files that survive in this
+       * PR's merge commit — never the whole integration PR.
+       */
       changedPaths?: string[];
       /** Explicit task relationship established when this atom was accepted. */
       taskId?: string;
+      /**
+       * Component PR this (integration) PR landed on the default branch
+       * (T12671): the task is linked through it and its files are the change.
+       */
+      componentPrNumber?: number;
+      /**
+       * Paths the (component) PR deleted that stay deleted in the landing
+       * commit (T12689). A deletion has no bytes to hash, so a PR whose every
+       * change is a deletion implements with `pr:` + `note:` instead of `files:`.
+       */
+      deletedPaths?: string[];
     }
   | {
       /**
@@ -410,6 +439,8 @@ export type EvidenceAtom =
       testedTree?: string;
       /** Task the PR was verified to be linked to (T12634). */
       taskId?: string;
+      /** Component PR the task is linked through; its CI ran as this integration PR's (T12671). */
+      componentPrNumber?: number;
       /** Which configured checks attest each gate (`evidence.ciChecks`). */
       gateChecks?: { testsPassed?: string[]; qaPassed?: string[] };
       /** Where the required-check list came from (env, project context, branch protection). */

package/src/tools/index.ts

@@ -63,6 +63,7 @@ export type {
   ScoreFactor,
   ScoreTaskContext,
   ScoreTaskInput,
+  ScoreTaskKey,
   ScoreTaskResult,
 } from './score-task-priority.js';
 // === Web + browser agent tools (T1742 / T11456) ===

package/src/tools/score-task-priority.ts

@@ -6,7 +6,7 @@
  * @epic T9835
  */
 
-import type { TaskPriority } from '../task.js';
+import type { TaskKind, TaskPriority, TaskSeverity } from '../task.js';
 
 /** Minimal task shape required by scoreTask. */
 export interface ScoreTaskInput {
@@ -24,6 +24,10 @@ export interface ScoreTaskInput {
   createdAt?: string;
   /** Labels for pattern matching. */
   labels?: string[];
+  /** Severity axis (orthogonal to priority); unset for most tasks. */
+  severity?: TaskSeverity | null;
+  /** Kind axis; a `bug` with no severity is scored at the default bug severity (T12661). */
+  kind?: TaskKind | null;
 }
 
 /** Context provided to scoreTask to enable phase-aware and dependency-aware scoring. */
@@ -38,6 +42,8 @@ export interface ScoreTaskContext {
   successPatterns?: Array<{ pattern: string }>;
   /** Matched failure patterns from BRAIN (optional penalty scoring). */
   failurePatterns?: Array<{ pattern: string }>;
+  /** Open tasks that depend on each task id — its leverage (bounded bonus, T12661). */
+  leverage?: ReadonlyMap<string, number>;
 }
 
 /** A scoring factor contributing to the final score. */
@@ -48,12 +54,32 @@ export interface ScoreFactor {
   delta: number;
   /** Human-readable explanation. */
   detail: string;
+  /**
+   * Comparator tier the factor belongs to (T12691): 1 priority band, 2 severity,
+   * 3 bounded tiebreak; `null` for an informational factor outside the order.
+   */
+  tier?: 1 | 2 | 3 | null;
+}
+
+/** The lexicographic sort key of a scored task (T12691); higher sorts first. */
+export interface ScoreTaskKey {
+  /** Owner priority band: critical 4, high 3, medium 2, low 1. */
+  band: number;
+  /** Attested severity: P0 4, P1 3, P2 2, P3 1, unknown 0. */
+  severity: number;
+  /** Bounded computed tiebreak (deps, phase, leverage, age). */
+  tiebreak: number;
 }
 
 /** Result of scoreTask. */
 export interface ScoreTaskResult {
-  /** Final computed score. */
+  /**
+   * The key as one number that sorts identically (band × 10000 + severity ×
+   * 1000 + tiebreak), for display and single-number consumers.
+   */
   score: number;
-  /** Individual scoring factors. */
+  /** Individual scoring factors, each tagged with its comparator tier. */
   factors: ScoreFactor[];
+  /** The lexicographic sort key (T12691). */
+  key?: ScoreTaskKey;
 }