@cleocode/contracts 2026.9.22 → 2026.9.23

package/src/__tests__/evidence-atom-schema.test.ts

@@ -684,7 +684,8 @@ describe('formatGateRequirement (T10337)', () => {
     expect(s).toContain('[decision AND note]');
     expect(s).toContain('[pr AND files]');
     // Joiner between combinations is ' OR '.
-    expect(s.split(' OR ').length).toBe(5);
+    // T12689: + [pr AND note] for a deletion-only PR.
+    expect(s.split(' OR ').length).toBe(6);
   });
 
   it('formats single-element combination without AND', () => {
@@ -759,7 +760,7 @@ describe('validateEvidenceForGate failure surface (T9949)', () => {
     if (!r.ok) {
       // Error includes the same artifact requirement as the validator.
       expect(r.message).toBe(
-        "Gate 'implemented' requires evidence: [commit AND files] OR [commit AND note] OR [decision AND files] OR [decision AND note] OR [pr AND files]",
+        "Gate 'implemented' requires evidence: [commit AND files] OR [commit AND note] OR [decision AND files] OR [decision AND note] OR [pr AND files] OR [pr AND note]",
       );
       // New rich hint includes the same content as formatGateRequirementHint.
       expect(r.hint).toBe(formatGateRequirementHint('implemented'));

package/src/acceptance-gate-schema.ts

@@ -536,7 +536,10 @@ export const acceptanceGateResultSchema = z
           message: 'Result cannot precede input capture',
         });
       const executable = ['test', 'command', 'lint'].includes(result.kind);
-      if (executable && !binding.invocation)
+      // T12718: a command the runner refused to split (shell syntax, open
+      // quote) never had an invocation. It is bound as an unmet `error` so the
+      // rest of its batch still records; any verdict needs the invocation.
+      if (executable && !binding.invocation && result.result !== 'error')
         context.addIssue({
           code: 'custom',
           path: ['binding', 'invocation'],

package/src/data-accessor.ts

@@ -255,6 +255,8 @@ export interface AcBindingRow {
 
 /** Query options for bounded reads from the append-only task audit log. @task T10594 */
 export interface TaskAuditLogQuery {
+  /** Exact audit row ids (T12693: revert one ranking change). */
+  ids?: readonly string[];
   taskIds?: readonly string[];
   actions?: readonly string[];
   since?: string;
@@ -271,6 +273,8 @@ export interface TaskAuditLogRow {
   detailsJson: string | null;
   beforeJson: string | null;
   afterJson: string | null;
+  /** Session the mutation ran in, when recorded (T12693). */
+  sessionId?: string | null;
 }
 
 /**

package/src/decide-sites.ts

@@ -0,0 +1,179 @@
+/**
+ * Decision-site registry contracts — the "decision ladder as code" (spec
+ * `system-one-integration` §3, owner decisions D11158 and D11159).
+ *
+ * Every place CLEO makes a judgement is a decision site: it has one primary
+ * rung, an ordered ladder of rungs it may escalate to, a fallback, an
+ * owner-escalation rule, a mode and (to act on a System One answer) go-live
+ * evidence. The registry rows live in `packages/core/src/decide/sites/`;
+ * these are their types.
+ *
+ * Types and const data only (arch gate 10).
+ *
+ * @task T12662
+ * @epic T12486
+ */
+
+/**
+ * The decision rungs, cheapest first. Escalation only moves up this list.
+ *
+ * - `rule` — the answer follows from data (ids, statuses, thresholds).
+ * - `system-one` — a typed judgement over text with a small fixed answer set.
+ * - `generative` — the output must be free text or code.
+ * - `agent` — multi-step work.
+ * - `owner` — authority only the owner can take (the ask tool).
+ */
+export const DECISION_RUNGS = ['rule', 'system-one', 'generative', 'agent', 'owner'] as const;
+
+/** One rung of the decision ladder. */
+export type DecisionRung = (typeof DECISION_RUNGS)[number];
+
+/** Site modes: `off` never asks, `shadow` asks and audits, `on` acts. */
+export const DECISION_SITE_MODES = ['off', 'shadow', 'on'] as const;
+
+/** How a site uses its System One rung. */
+export type DecisionSiteModeValue = (typeof DECISION_SITE_MODES)[number];
+
+/** The shape of the question a site answers. */
+export type DecisionSiteQuestionType =
+  | 'noul'
+  | 'choice'
+  | 'score'
+  | 'text'
+  | 'multi-step'
+  | 'owner-choice';
+
+/**
+ * When a site may put a question to the owner.
+ *
+ * - `never` — the site never asks the owner.
+ * - `escalate-only` — it may add an owner question, never clear one.
+ * - `below-floor` — it asks the owner when every lower rung is below its floor.
+ * - `always` — the owner always decides.
+ */
+export type DecisionSiteOwnerEscalation = 'never' | 'escalate-only' | 'below-floor' | 'always';
+
+/** Classes of text a site may send off the machine (spec §8). */
+export type DecisionSiteTextClass =
+  | 'task-text'
+  | 'memory-text'
+  | 'diff'
+  | 'skill-text'
+  | 'external-text';
+
+/** Measured evidence that lets a site act on its System One answer (`mode: on`). */
+export interface DecisionSiteGoLive {
+  /** Canonical doc slug holding the measurement. */
+  readonly evidenceDoc: string;
+  /** ISO date of the measurement. */
+  readonly measuredAt: string;
+  /** Number of labelled decisions measured. */
+  readonly n: number;
+  /** Metric name, e.g. `precision@acting-class`. */
+  readonly metric: string;
+  /** Measured value. */
+  readonly value: number;
+  /** Floor the value had to clear. */
+  readonly floor: number;
+}
+
+/** One registry row: everything CLEO knows about a decision site. */
+export interface DecisionSiteDefinition {
+  /** Site id; the string `decide()` and the audit log use, e.g. `tasks.duplicate-detection`. */
+  readonly id: string;
+  /** Human title. */
+  readonly title: string;
+  /** Repo-relative files where the site lives. */
+  readonly files: readonly string[];
+  /** The shape of the question. */
+  readonly questionType: DecisionSiteQuestionType;
+  /** The rung that answers first. */
+  readonly primaryRung: DecisionRung;
+  /** Rungs it may escalate to, in order, all above the primary. */
+  readonly ladder: readonly DecisionRung[];
+  /** What acts when the primary is unavailable. */
+  readonly fallback: DecisionRung | 'none';
+  /**
+   * Minimum confidence per question before `on` may act on a System One
+   * answer. The key `*` applies to every question of the site.
+   */
+  readonly floors?: Readonly<Record<string, number>>;
+  /** When the site may ask the owner. */
+  readonly ownerEscalation: DecisionSiteOwnerEscalation;
+  /** Config key holding the mode (the existing `decide.sites.*` keys, D11159). */
+  readonly modeKey?: string;
+  /** Config key opting the site into its generative rung (`decide.generativeFallback.*`). */
+  readonly generativeKey?: string;
+  /** Mode when the config key is unset. */
+  readonly defaultMode: DecisionSiteModeValue;
+  /** Generative rung: the role or system key it resolves its model with. */
+  readonly llmSystemKey?: string;
+  /** True for a site on a write path: 300 ms budget, never blocks the write. */
+  readonly writePath: boolean;
+  /** Text classes it sends to a provider. */
+  readonly sends: readonly DecisionSiteTextClass[];
+  /** Go-live evidence, required before a System One site runs `on`. */
+  readonly goLive?: DecisionSiteGoLive;
+  /** Owning task. */
+  readonly task: string;
+  /** Free-form note (constraints such as "interactive only"). */
+  readonly note?: string;
+}
+
+/** Audit counts for one site over the last seven days. */
+export interface DecisionSiteActivity {
+  /** Audit lines written for the site. */
+  readonly asked: number;
+  /** Answered by the provider. */
+  readonly provider: number;
+  /** Answered from the decision cache. */
+  readonly cache: number;
+  /** Answered by the fallback. */
+  readonly fallback: number;
+  /** Escalated to a higher rung (0 until the ladder executor lands, T12665). */
+  readonly escalated: number;
+  /** Share of compared shadow lines where decision and heuristic agreed, when any were compared. */
+  readonly agreement?: number;
+}
+
+/** One site as `cleo decide sites` reports it. */
+export interface DecisionSiteSummary {
+  /** Site id. */
+  readonly id: string;
+  /** Human title. */
+  readonly title: string;
+  /** Question shape. */
+  readonly questionType: DecisionSiteQuestionType;
+  /** Primary rung. */
+  readonly primaryRung: DecisionRung;
+  /** Escalation ladder. */
+  readonly ladder: readonly DecisionRung[];
+  /** Fallback. */
+  readonly fallback: DecisionRung | 'none';
+  /** Owner-escalation rule. */
+  readonly ownerEscalation: DecisionSiteOwnerEscalation;
+  /** Registry default mode. */
+  readonly mode: DecisionSiteModeValue;
+  /** Mode set in config, when the site has a mode key and it is set. */
+  readonly configuredMode?: DecisionSiteModeValue;
+  /** Mode in force: `off` for a System One site while no provider is configured. */
+  readonly effectiveMode: DecisionSiteModeValue;
+  /** Config key holding the mode, when the site has one. */
+  readonly modeKey?: string;
+  /** Go-live evidence, when recorded. */
+  readonly goLive?: DecisionSiteGoLive;
+  /** Owning task. */
+  readonly task: string;
+  /** Audit activity over the last seven days. */
+  readonly last7d: DecisionSiteActivity;
+}
+
+/** Result of `cleo decide sites`. */
+export interface DecisionSitesListResult {
+  /** Whether a System One provider is configured (else System One sites are `off`). */
+  readonly providerConfigured: boolean;
+  /** Registered sites total, before filters. */
+  readonly total: number;
+  /** Matching sites. */
+  readonly sites: readonly DecisionSiteSummary[];
+}

package/src/decide.ts

@@ -143,6 +143,17 @@ export interface DecisionRequest {
   readonly state: DecisionState;
   /** Question name → question (1–32 entries). Names key the answers in {@link DecisionOutcome}. */
   readonly questions: Readonly<Record<string, DecisionQuestion>>;
+  /**
+   * Language hint (e.g. `en`). Sent only to a provider whose capabilities
+   * include `langHint`; others never see it (T12664).
+   */
+  readonly lang?: string;
+  /**
+   * Provider-side answer cache. `false` asks a provider with `cacheControl`
+   * not to answer from its cache (real latency, sensitive text). Ignored by
+   * providers without the capability.
+   */
+  readonly cache?: boolean;
 }
 
 /** Answer to a {@link NoulDecisionQuestion}. */
@@ -196,14 +207,100 @@ export interface DecisionOutcome {
   readonly latencyMs: number;
   /** Provider-reported cost in US dollars, when known. */
   readonly costUsd?: number;
+  /** Provider-reported cost in integer micro-dollars, when known (T12664). */
+  readonly costMicros?: number;
+  /** Account balance in integer micro-dollars reported with this answer, when known. */
+  readonly balanceMicros?: number;
+  /** Provider model checkpoint that answered, when reported. */
+  readonly checkpoint?: string;
   /** Provider-reported input-token count, when known. */
   readonly inputTokens?: number;
 }
 
+// ─── Provider kinds (T12713) ─────────────────────────────────────────────────
+
+/**
+ * Every supported decision-provider kind, recommended first.
+ *
+ * - `layahost` — the hosted provider at {@link LAYAHOST_BASE_URL}; the user
+ *   supplies only an API key.
+ * - `jev`      — any other Jev-compatible endpoint; the user supplies the URL.
+ */
+export const DECISION_PROVIDER_KINDS = ['layahost', 'jev'] as const;
+
+/** A decision-provider kind. See {@link DECISION_PROVIDER_KINDS}. */
+export type DecisionProviderKind = (typeof DECISION_PROVIDER_KINDS)[number];
+
+/** Base URL of the layahost API (its OpenAPI `servers[0].url`). */
+export const LAYAHOST_BASE_URL = 'https://layahost.com';
+
+/** layahost's routing model, the default for a layahost connection. */
+export const LAYAHOST_DEFAULT_MODEL = 'laya-auto';
+
 /** Connection settings for a decision provider. */
 export interface DecisionProviderConfig {
   /** Absolute base URL of the provider's API (no trailing path to the endpoint). */
   readonly baseUrl: string;
+  /** Provider kind; absent means a custom Jev-compatible endpoint (`jev`). */
+  readonly provider?: DecisionProviderKind;
+}
+
+// ─── Provider capabilities (T12664) ──────────────────────────────────────────
+
+/**
+ * What a decision provider can do beyond the Jev minimum
+ * (`POST /v1/systemone`, 32 questions, 32,000-character state). A caller asks
+ * for a capability; the client degrades when it is absent (spec
+ * `system-one-integration` §2.2).
+ */
+export interface DecisionProviderCapabilities {
+  /** Wire protocol the provider speaks. */
+  readonly wire: string;
+  /** Most questions one request may carry. */
+  readonly maxQuestionsPerRequest: number;
+  /** Largest state, in characters. */
+  readonly maxStateChars: number;
+  /** Batch endpoint limits, when the provider has one. */
+  readonly batch?: { readonly maxRequests: number; readonly maxQuestions: number };
+  /** Built-in template names, when the provider has templates. */
+  readonly templates?: readonly string[];
+  /** Server-side flows are available. */
+  readonly flows?: boolean;
+  /** A usage/balance endpoint and cost headers are available. */
+  readonly usage?: boolean;
+  /** The request's `cache` field is honoured. */
+  readonly cacheControl?: boolean;
+  /** The request's `lang` field is honoured. */
+  readonly langHint?: boolean;
+  /** How the provider reports cost. */
+  readonly reportsCost?: 'micros' | 'usd' | false;
+}
+
+/** The Jev minimum every provider supports; the default when a provider reports nothing. */
+export const JEV_MINIMUM_CAPABILITIES: DecisionProviderCapabilities = {
+  wire: 'jev-systemone/1',
+  maxQuestionsPerRequest: 32,
+  maxStateChars: 32_000,
+  reportsCost: 'usd',
+};
+
+/** One item of a batch call: its outcome, or why it failed. */
+export type DecisionBatchItem =
+  | { readonly ok: true; readonly outcome: DecisionOutcome }
+  | { readonly ok: false; readonly status?: number; readonly errorKind: string };
+
+/** Account usage and balance as a provider reports it. */
+export interface DecisionProviderUsage {
+  /** Balance in integer micro-dollars. */
+  readonly balanceMicros?: number;
+  /** Decisions the balance still covers. */
+  readonly decisionsLeft?: number;
+  /** Plan name. */
+  readonly plan?: string;
+  /** End of the current plan period, ISO-8601. */
+  readonly periodEnd?: string;
+  /** Decisions and cost over the queried window. */
+  readonly totals?: { readonly decisions?: number; readonly costMicros?: number };
 }
 
 // ─── Zod schemas ──────────────────────────────────────────────────────────────
@@ -290,6 +387,11 @@ export const decisionQuestionSchema = z.discriminatedUnion('type', [
  */
 export const decisionRequestSchema = z.object({
   model: z.string().min(1).optional(),
+  lang: z
+    .string()
+    .regex(/^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$/)
+    .optional(),
+  cache: z.boolean().optional(),
   state: decisionStateSchema,
   questions: z.record(z.string().min(1), decisionQuestionSchema).refine(
     (questions) => {
@@ -346,10 +448,17 @@ export const decisionOutcomeSchema = z.object({
   requestId: z.string().min(1).optional(),
   latencyMs: z.number().nonnegative(),
   costUsd: z.number().nonnegative().optional(),
+  costMicros: z.number().int().nonnegative().optional(),
+  balanceMicros: z.number().int().optional(),
+  checkpoint: z.string().min(1).optional(),
   inputTokens: z.number().int().nonnegative().optional(),
 });
 
+/** Zod schema for {@link DecisionProviderKind}. */
+export const decisionProviderKindSchema = z.enum(DECISION_PROVIDER_KINDS);
+
 /** Zod schema for {@link DecisionProviderConfig}; `baseUrl` must be an absolute URL. */
 export const decisionProviderConfigSchema = z.object({
   baseUrl: z.url(),
+  provider: decisionProviderKindSchema.optional(),
 });

package/src/dispatch/operations-registry.ts

@@ -814,12 +814,22 @@ export const OPERATIONS: OperationDef[] = [
     gateway: 'query' as const,
     domain: 'tasks' as const,
     operation: 'history',
-    description: 'Show task work history (time tracked per task)',
+    description:
+      'Show task work history; with taskId, the task audit trail; with ranking, who changed its priority/severity/kind/depends and why (T12693)',
     tier: 1,
     idempotent: true,
     sessionRequired: false,
     requiredParams: [],
-    params: [],
+    params: [
+      { name: 'taskId', type: 'string', required: false, description: 'Task to show history for' },
+      { name: 'limit', type: 'number', required: false, description: 'Maximum entries' },
+      {
+        name: 'ranking',
+        type: 'boolean',
+        required: false,
+        description: 'Only ranking-input changes (actor, session, reason, before/after)',
+      },
+    ] satisfies ParamDef[],
   },
   {
     gateway: 'query',
@@ -3364,6 +3374,33 @@ export const OPERATIONS: OperationDef[] = [
     ] satisfies ParamDef[],
     outputSchema: OUTPUT_CONTRACTS['tasks.assignee'],
   },
+  {
+    gateway: 'mutate',
+    domain: 'tasks',
+    operation: 'ranking.revert',
+    description:
+      'tasks.ranking.revert (mutate) — undo one recorded ranking change (priority/severity/kind/depends) as a new audited change (T12693, D11161)',
+    tier: 1,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['entryId'],
+    params: [
+      {
+        name: 'entryId',
+        type: 'string',
+        required: true,
+        description: 'ranking_changed audit row id (cleo history ranking <taskId>)',
+        cli: { positional: true },
+      },
+      { name: 'reason', type: 'string', required: false, description: 'Why it is reverted' },
+      {
+        name: 'force',
+        type: 'boolean',
+        required: false,
+        description: 'Revert even though a field changed again since',
+      },
+    ] satisfies ParamDef[],
+  },
   {
     gateway: 'mutate',
     domain: 'tasks',

package/src/evidence-atom-schema.ts

@@ -500,6 +500,9 @@ export const GATE_EVIDENCE_REQUIREMENTS: Readonly<
       ['decision', 'files'],
       ['decision', 'note'],
       ['pr', 'files'],
+      // T12689: a deletion-only PR (no bytes to hash). Contextual validation
+      // accepts this only when every change the PR made is a deletion.
+      ['pr', 'note'],
     ],
   },
   testsPassed: { oneOf: [['test-run'], ['tool'], ['ci']] },

package/src/index.ts

@@ -2703,6 +2703,7 @@ export type {
   ScoreFactor,
   ScoreTaskContext,
   ScoreTaskInput,
+  ScoreTaskKey,
   ScoreTaskResult,
 } from './tools/score-task-priority.js';
 // === Transport (low-level wire protocol) ===
@@ -2890,11 +2891,15 @@ export type {
   ChoiceDecisionAnswer,
   ChoiceDecisionQuestion,
   DecisionAnswer,
+  DecisionBatchItem,
   DecisionInstructions,
   DecisionJsonValue,
   DecisionOutcome,
   DecisionOutcomeSource,
+  DecisionProviderCapabilities,
   DecisionProviderConfig,
+  DecisionProviderKind,
+  DecisionProviderUsage,
   DecisionQuestion,
   DecisionQuestionType,
   DecisionRequest,
@@ -2908,6 +2913,7 @@ export {
   choiceDecisionAnswerSchema,
   choiceDecisionQuestionSchema,
   DECISION_OUTCOME_SOURCES,
+  DECISION_PROVIDER_KINDS,
   DECISION_QUESTION_TYPES,
   DECISION_REQUEST_LIMITS,
   decisionAnswerSchema,
@@ -2915,14 +2921,32 @@ export {
   decisionOutcomeSchema,
   decisionOutcomeSourceSchema,
   decisionProviderConfigSchema,
+  decisionProviderKindSchema,
   decisionQuestionSchema,
   decisionQuestionTypeSchema,
   decisionRequestSchema,
   decisionStateSchema,
+  JEV_MINIMUM_CAPABILITIES,
+  LAYAHOST_BASE_URL,
+  LAYAHOST_DEFAULT_MODEL,
   noulDecisionAnswerSchema,
   noulDecisionQuestionSchema,
   scoreDecisionAnswerSchema,
   scoreDecisionQuestionSchema,
 } from './decide.js';
+// T12662: decision-site registry (the decision ladder as code).
+export type {
+  DecisionRung,
+  DecisionSiteActivity,
+  DecisionSiteDefinition,
+  DecisionSiteGoLive,
+  DecisionSiteModeValue,
+  DecisionSiteOwnerEscalation,
+  DecisionSiteQuestionType,
+  DecisionSiteSummary,
+  DecisionSitesListResult,
+  DecisionSiteTextClass,
+} from './decide-sites.js';
+export { DECISION_RUNGS, DECISION_SITE_MODES } from './decide-sites.js';
 
 export { isStorableTaskId, isTaskId, TASK_ID_REGEX, type TaskId } from './task-id.js';

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/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

@@ -187,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. */
@@ -390,6 +398,12 @@ export type EvidenceAtom =
        * (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[];
     }
   | {
       /**

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;
 }