@cleocode/contracts 2026.9.7 → 2026.9.9

package/src/operations/tasks.ts

@@ -18,6 +18,7 @@
  * @task T1703 — Fill Result=unknown stubs with canonical typed shapes
  */
 
+import type { TaskPopulation } from '../data-accessor.js';
 import type { ImpactReport } from '../facade.js';
 import type { TaskAnalysisResult, TaskRef } from '../results.js';
 /**
@@ -25,7 +26,7 @@ import type { TaskAnalysisResult, TaskRef } from '../results.js';
  */
 import type { TaskStatus } from '../status-registry.js';
 import type { TaskKind, TaskPriority, TaskSeverity, TaskType } from '../task.js';
-import type { TaskRecord } from '../task-record.js';
+import type { MinimalTaskRecord, TaskMatch, TaskRecord } from '../task-record.js';
 import type { ExternalTask, ExternalTaskLink, ReconcileResult } from '../task-sync.js';
 import type {
   CompletionEvaluateParams,
@@ -115,11 +116,14 @@ export interface TasksListParams {
   limit?: number;
   offset?: number;
   compact?: boolean;
+  /** Include archive rows under the same filters. */
+  includeArchive?: boolean;
 }
 export interface TasksListResult {
   tasks: TaskOp[];
   total: number;
   filtered: number;
+  population: TaskPopulation;
 }
 
 // tasks.find
@@ -142,6 +146,10 @@ export interface TasksFindParams {
   id?: string;
   /** When true, require exact string match instead of fuzzy. @task T963 */
   exact?: boolean;
+  /** Explicitly allow character-subsequence matching. Default is lexical. */
+  fuzzy?: boolean;
+  /** Restrict matching to this field; unsupported values reject. */
+  field?: string;
   /** Filter by status. @task T963 */
   status?: TaskStatus;
   /** When true, include archived tasks in the search. @task T963 */
@@ -201,7 +209,14 @@ export interface TasksFindParams {
    */
   parent?: string;
 }
-export type TasksFindResult = MinimalTask[];
+/** Canonical task-search wrapper, including retrieval basis and population scope. */
+export interface TasksFindResult {
+  results: (MinimalTaskRecord | TaskRecord)[];
+  total: number;
+  population: TaskPopulation;
+  query: string;
+  searchType: TaskMatch['kind'];
+}
 
 /**
  * Mutate Operations
@@ -1343,6 +1358,8 @@ export interface TasksAddBatchParams {
     scope?: string;
     severity?: string;
     forceDuplicate?: boolean;
+    /** Resolve design-point 3 in-line by decomposing a text-AC parent. @task T12298 */
+    autoDecompose?: boolean;
   }>;
   /** Optional default parent ID applied when a task spec omits `parent`. */
   defaultParent?: string;
@@ -1440,6 +1457,8 @@ export interface TasksAddParams {
    */
   parentSource?: 'explicit' | 'session-inference';
   depends?: string[];
+  /** Justification preserved in the creation audit for a critical-priority task. */
+  dependsWaiver?: string;
   priority?: string;
   labels?: string[];
   type?: TaskType; // SSoT-EXEMPT:kind≠type — 'type' is hierarchy(saga|epic|task|subtask), 'kind' is intent(work|bug|...) — separate axes T944 // ssot-exempt-ok: pre-existing exempt, narrowed string→TaskType (T10328)
@@ -1464,6 +1483,8 @@ export interface TasksAddParams {
    * @task T1633
    */
   forceDuplicate?: boolean;
+  /** Resolve design-point 3 in-line by decomposing a text-AC parent. @task T12298 */
+  autoDecompose?: boolean;
 }
 /**
  * Result of `tasks.add` — the newly created task.
@@ -1500,6 +1521,8 @@ export interface TasksUpdateQueryParams {
   description?: string;
   status?: string;
   priority?: string;
+  /** Project-defined task phase, persisted independently of pipelineStage. */
+  phase?: string;
   notes?: string;
   labels?: string[];
   addLabels?: string[];
@@ -1524,7 +1547,7 @@ export interface TasksUpdateQueryParams {
   scope?: string;
   /**
    * Severity level — valid for any kind (T9073). Orthogonal to priority.
-   * Appends a signed attestation to `.cleo/audit/severity-attestation.jsonl`.
+   * Persists a signed project-identity assertion in the task transaction audit.
    */
   severity?: string;
   /**
@@ -1536,6 +1559,8 @@ export interface TasksUpdateQueryParams {
   dependsWaiver?: string;
   /** Set the blockedBy free-text reason. @task T9241 (gh#1106) */
   blockedBy?: string;
+  /** Disable automatic parent completion when true; false restores automatic completion. */
+  noAutoComplete?: boolean;
   /** Clear the blockedBy free-text reason (set to undefined). @task T9241 */
   clearBlockedBy?: boolean;
   /** Set related tasks (replaces existing). @task T9327 */
@@ -1619,7 +1644,7 @@ export interface TasksCompleteQueryParams {
   /**
    * Reason for waiving the `E_CLEO_DEPENDENCY` gate when this task's own work
    * is done but its `depends` edges point at not-yet-terminal tasks (a stale or
-   * over-specified dependency). Recorded to `.cleo/audit/depends-waiver.jsonl`.
+   * over-specified dependency). Recorded with the task mutation in its transaction audit.
    *
    * @task T11954 (DHQ-071)
    */
@@ -1639,10 +1664,88 @@ export interface TasksCompleteQueryResult {
   unblockedTasks?: Array<Pick<TaskRef, 'id' | 'title'>>;
 }
 
+// tasks.reconcile-scope (dispatch-level params) — containment-aware overlap sweep
+/**
+ * Params for `tasks.reconcile-scope` — sweep a container for tasks whose scope
+ * overlaps and propose merge / absorb / split / link for each pair.
+ *
+ * @task T12299
+ */
+export interface TasksReconcileScopeParams {
+  /** Saga, epic or any container to sweep; its whole subtree is considered. */
+  rootId: string;
+  /** Write the proposed `relates` edges. Read-only when false or omitted. */
+  apply?: boolean;
+  /** Report pairs at or above this similarity score (0-1). */
+  threshold?: number;
+}
+
+/** One overlapping pair and the action proposed for it. @task T12299 */
+export interface TasksScopeOverlap {
+  keepId: string;
+  keepTitle: string;
+  otherId: string;
+  otherTitle: string;
+  action: 'merge' | 'absorb' | 'split' | 'link';
+  score: number;
+  relation: 'duplicates' | 'absorbs' | 'related';
+  rationale: string;
+  sameParent: boolean;
+}
+
+/** Result of `tasks.reconcile-scope`. @task T12299 */
+export interface TasksReconcileScopeResult {
+  rootId: string;
+  scanned: number;
+  pairs: number;
+  overlaps: TasksScopeOverlap[];
+  applied: number;
+  truncated?: { limit: number; liveNodes: number };
+}
+
+// tasks.decompose (dispatch-level params) — PM-Core V2 design-point 3
+/**
+ * Params for `tasks.decompose` — move a task's free-text acceptance criteria
+ * onto a new first child so the task becomes a pure container.
+ *
+ * @task T12281
+ */
+export interface TasksDecomposeParams {
+  /** Task whose text acceptance criteria move to a new child. */
+  taskId: string;
+  /** Title for the child that inherits the criteria. Defaults to the parent's. */
+  childTitle?: string;
+  /** Description for the child. Defaults to the parent's. */
+  childDescription?: string;
+  /** Preview the move without writing. */
+  dryRun?: boolean;
+}
+
+/**
+ * Result of `tasks.decompose` — the container/child pair and the criteria moved.
+ *
+ * @task T12281
+ */
+export interface TasksDecomposeResult {
+  /** The task that is now a pure container. */
+  parentId: string;
+  /** The created child, or `null` on a dry run. */
+  childId: string | null;
+  /** The criteria texts moved from parent to child, in ordinal order. */
+  movedAcceptance: string[];
+  /** True when nothing was written. */
+  dryRun: boolean;
+}
+
 // tasks.delete (dispatch-level params)
+/** Canonical task deletion controls shared by dispatch and core wrappers. */
 export interface TasksDeleteQueryParams {
+  /** Task to move into the archive. */
   taskId: string;
+  /** Allow dependents and orphan children unless cascade is explicitly enabled. */
   force?: boolean;
+  /** Archive the entire descendant subtree rather than orphaning children. */
+  cascade?: boolean;
 }
 /**
  * Result of `tasks.delete` — deletion confirmation with cascade details.
@@ -2154,6 +2257,8 @@ export type TasksOps = {
   readonly update: readonly [TasksUpdateQueryParams, TasksUpdateQueryResult];
   readonly complete: readonly [TasksCompleteQueryParams, TasksCompleteQueryResult];
   readonly cancel: readonly [TasksCancelParams, TasksCancelResult];
+  readonly decompose: readonly [TasksDecomposeParams, TasksDecomposeResult];
+  readonly 'reconcile-scope': readonly [TasksReconcileScopeParams, TasksReconcileScopeResult];
   readonly delete: readonly [TasksDeleteQueryParams, TasksDeleteQueryResult];
   readonly archive: readonly [TasksArchiveQueryParams, TasksArchiveQueryResult];
   readonly restore: readonly [TasksRestoreParams, TasksRestoreResult];
@@ -2252,6 +2357,8 @@ export interface TasksAddBatchEntry {
   severity?: string;
   /** Bypass BRAIN duplicate-task rejection (audited). */
   forceDuplicate?: boolean;
+  /** Resolve design-point 3 in-line by decomposing a text-AC parent. @task T12298 */
+  autoDecompose?: boolean;
 }
 
 /**
@@ -2273,6 +2380,7 @@ export const TASKS_ADD_INPUT_SCHEMA: JsonSchema = {
     description: { type: 'string' },
     parent: { type: 'string' },
     depends: { type: 'array', items: { type: 'string' } },
+    dependsWaiver: { type: 'string', minLength: 1 },
     priority: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
     labels: { type: 'array', items: { type: 'string' } },
     type: { type: 'string', enum: ['saga', 'epic', 'task', 'subtask'] },
@@ -2290,6 +2398,7 @@ export const TASKS_ADD_INPUT_SCHEMA: JsonSchema = {
     scope: { type: 'string', enum: ['project', 'feature', 'unit'] },
     severity: { type: 'string', enum: ['P0', 'P1', 'P2', 'P3'] },
     forceDuplicate: { type: 'boolean' },
+    autoDecompose: { type: 'boolean' },
   },
 };
 
@@ -2369,6 +2478,7 @@ export const TASKS_ADD_BATCH_INPUT_SCHEMA: JsonSchema = {
           scope: { type: 'string', enum: ['project', 'feature', 'unit'] },
           severity: { type: 'string', enum: ['P0', 'P1', 'P2', 'P3'] },
           forceDuplicate: { type: 'boolean' },
+          autoDecompose: { type: 'boolean' },
         },
       },
     },
@@ -2438,6 +2548,7 @@ export const TASKS_UPDATE_INPUT_SCHEMA: JsonSchema = {
       enum: ['pending', 'active', 'blocked', 'done', 'cancelled'],
     },
     priority: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
+    phase: { type: 'string' },
     notes: { type: 'string' },
     labels: { type: 'array', items: { type: 'string' } },
     addLabels: { type: 'array', items: { type: 'string' } },
@@ -2463,6 +2574,7 @@ export const TASKS_UPDATE_INPUT_SCHEMA: JsonSchema = {
     dependsWaiver: { type: 'string' },
     blockedBy: { type: 'string' },
     clearBlockedBy: { type: 'boolean' },
+    noAutoComplete: { type: 'boolean' },
     relates: {
       type: 'array',
       items: {

package/src/package-artifact.ts

@@ -0,0 +1,127 @@
+/**
+ * Shared contracts for semantic validation of a package inventory.
+ *
+ * Code placed in `packages/contracts/` per Package-Boundary Check — verified
+ * against AGENTS.md. Inventory validation does not certify runtime behavior.
+ */
+
+/** A file reported by the packer; hashes describe supplied evidence, not inferred bytes. */
+export interface PackageArtifactFile {
+  /** Canonical POSIX path relative to the package root. */
+  path: string;
+  /** Uncompressed file length in bytes. */
+  size: number;
+  /** SHA-256 computed by the inventory producer, when bytes were inspected. */
+  sha256?: string;
+}
+
+/** Identity and file evidence supplied by a pack operation or an explicit test fixture. */
+export interface PackageArtifactInventory {
+  /** Package name from the packed manifest. */
+  packageName: string;
+  /** Package version from the packed manifest. */
+  version: string;
+  /** Distinguishes a real packed artifact from a preview or synthetic fixture. */
+  source: 'npm-pack' | 'npm-pack-dry-run' | 'fixture';
+  /** Compressed artifact length reported by the packer. */
+  packedBytes: number;
+  /** SHA-256 of the retained tarball, absent for previews. */
+  tarballSha256?: string;
+  /** Actual selected file inventory, including files npm includes implicitly. */
+  files: readonly PackageArtifactFile[];
+}
+
+/** Classification of a manifest entry; classification does not reproduce npm's selection rules. */
+export interface PackageFilesEntry {
+  /** Original manifest string, preserved for diagnostics. */
+  entry: string;
+  /** Exclusions are patterns, never filesystem paths that must exist. */
+  kind: 'literal' | 'glob' | 'exclusion' | 'invalid';
+  /** Relative path or pattern without a leading exclusion marker. */
+  pattern: string;
+  /** Why an entry cannot be assessed, or null for a supported classification. */
+  reason: string | null;
+}
+
+/** One independently stated content requirement against a packer's inventory. */
+export interface PackageArtifactRequirement {
+  /** Stable semantic role, such as studio-server-entry. */
+  id: string;
+  /** Exact path or POSIX glob evaluated against already selected files. */
+  path: string;
+  /** Exact files and deliberately variable build filenames remain distinct. */
+  match: 'exact' | 'glob';
+}
+
+/** Upper installation-cost budgets; there is deliberately no mass-based presence floor. */
+export interface PackageArtifactBudgets {
+  /** Maximum compressed bytes. */
+  packedBytes: number;
+  /** Maximum sum of uncompressed file bytes. */
+  unpackedBytes: number;
+  /** Maximum number of selected files. */
+  fileCount: number;
+}
+
+/** Explicit content and comparison policy, independent of historical package size. */
+export interface PackageArtifactPolicy {
+  /** Required nonempty resources; an empty policy is rejected. */
+  requirements: readonly PackageArtifactRequirement[];
+  /** Existing upper budgets to enforce without increasing their values. */
+  budgets: PackageArtifactBudgets;
+  /** Manifest entries to classify only; the packer's inventory remains authoritative. */
+  filesEntries?: readonly string[];
+  /** Paths/globs that must be absent from the selected inventory. */
+  forbiddenPatterns?: readonly string[];
+  /** Independently captured expected files; supplied hashes must match actual hashes. */
+  expectedFiles?: readonly PackageArtifactFile[];
+}
+
+/** A concrete invalid inventory, policy, required resource, comparison, or budget finding. */
+export interface PackageArtifactIssue {
+  /** Machine-readable finding class. */
+  code:
+    | 'invalid-inventory'
+    | 'invalid-policy'
+    | 'missing'
+    | 'empty'
+    | 'mismatch'
+    | 'forbidden'
+    | 'budget';
+  /** File path, semantic role, or policy field identifying the affected evidence. */
+  subject: string;
+  /** Independently understandable failure explanation. */
+  message: string;
+}
+
+/** One semantic resource assessment, preserving its actual matched file identities. */
+export interface PackageArtifactRequirementResult {
+  /** Original requirement identity. */
+  id: string;
+  /** Actual paths selected from the supplied inventory. */
+  matchedPaths: readonly string[];
+  /** Whether at least one matching nonempty file exists and no match is empty. */
+  satisfied: boolean;
+}
+
+/** Result of validating supplied package evidence, with explicit limits on the claim. */
+export interface PackageArtifactValidation {
+  /** True only when the supplied inventory and policy have no findings. */
+  valid: boolean;
+  /** Original inventory identity and file/hash evidence, copied into the receipt. */
+  inventory: PackageArtifactInventory;
+  /** Computed byte total, or null if malformed/overflowing evidence prevents accounting. */
+  unpackedBytes: number | null;
+  /** Every detected failure; a failed diagnostic never becomes empty success. */
+  issues: readonly PackageArtifactIssue[];
+  /** Classified manifest entries without pretending to reproduce npm packlist. */
+  filesEntries: readonly PackageFilesEntry[];
+  /** Required resource assessments. */
+  requirements: readonly PackageArtifactRequirementResult[];
+  /** Hash comparisons establish equality with supplied expected evidence only. */
+  hashComparison: 'not-requested' | 'matched' | 'failed';
+  /** No runtime loading, install, dependency resolution, or dynamic-reference discovery occurs here. */
+  runtime: 'not-assessed';
+  /** Follow-up verification needed before claiming a usable installed artifact. */
+  limitations: readonly string[];
+}

package/src/release/evidence-atoms.ts

@@ -104,6 +104,12 @@ export const ghPrViewSchema = z
     state: z.enum(['OPEN', 'CLOSED', 'MERGED']),
     mergedAt: z.string().nullable(),
     headRefOid: z.string().optional(),
+    mergeCommit: z.object({ oid: z.string() }).nullable().optional(),
+    title: z.string().optional(),
+    body: z.string().optional(),
+    headRefName: z.string().optional(),
+    files: z.array(z.object({ path: z.string() })).optional(),
+    changedFiles: z.number().int().nonnegative().optional(),
     mergeable: z.string().optional(),
     statusCheckRollup: z
       .array(

package/src/resource-governor.ts

@@ -16,6 +16,8 @@
  * @adr resource-governor-never-oom-architecture §3.4
  */
 
+import type { OperationExecutionContext } from './jobs.js';
+
 /**
  * Governor arbitration mode. Mirrors the writer-lease mode shape
  * (`writer-lease.ts` {@link LeaseMode}).
@@ -121,3 +123,133 @@ export const DEFAULT_RESOURCE_RETRY_AFTER_MS = 2_000;
 export function isResourceGrant(r: AdmissionResult): r is ResourceGrant {
   return r.deferred === false;
 }
+
+/** Explicit local user-manager connection for resource-controlled process launch. */
+export interface SystemdControlContext {
+  /** Absolute existing runtime directory used only by the manager probe and launcher. */
+  runtimeDirectory: string;
+  /**
+   * Optional local Unix bus address.
+   * @defaultValue The bus socket in runtimeDirectory.
+   */
+  busAddress?: string;
+}
+
+/** Original execution deadline and optional cancellation observed at process-launch boundaries. */
+export type ProcessLaunchExecution = Pick<OperationExecutionContext, 'deadlineAt'> &
+  Partial<Pick<OperationExecutionContext, 'signal'>>;
+
+/**
+ * Captured inputs for a bounded process invocation; environment is copied before launch.
+ * @remarks The original absolute deadline covers launcher discovery and target execution;
+ * bounded cleanup may finish later. No caller environment is implicitly merged.
+ * @example
+ * ```typescript
+ * const options: ProcessCaptureOptions = { cwd: '/project', env: {}, execution: { deadlineAt: Date.now() + 2000 } };
+ * ```
+ */
+export interface ProcessCaptureOptions {
+  /** Explicit working directory for the requested executable. */
+  readonly cwd: string;
+  /** Explicit child environment; caller credentials are not added implicitly. */
+  readonly env: Readonly<Record<string, string | undefined>>;
+  /** Original shared deadline and cancellation, never reset between gates. */
+  readonly execution: ProcessLaunchExecution;
+  /** Aggregate stdout/stderr byte limit; exceeding it stops execution without a verdict. */
+  readonly maxOutputBytes?: number;
+  /** Requested hard native-memory ceiling in MiB; target admission requires observed cgroup enforcement. */
+  readonly memoryMaxMb?: number;
+  /** Requested kernel task ceiling (processes and threads); target admission requires observed cgroup enforcement. */
+  readonly tasksMax?: number;
+  /** Existing manager connection used only for launcher/control operations. */
+  readonly systemdControl?: SystemdControlContext;
+}
+
+/**
+ * Why capture stopped without a complete target verdict.
+ * @remarks Cancellation, deadline and malformed transport are not target test failures.
+ * @example
+ * ```typescript
+ * const stopped: ProcessCaptureStop = 'deadline';
+ * ```
+ */
+export type ProcessCaptureStop =
+  | 'deadline'
+  | 'cancelled'
+  | 'teardown'
+  | 'output-limit'
+  | 'resource-limit'
+  | 'transport-error';
+
+/**
+ * Kernel limits observed inside the owned cgroup before target admission.
+ * @remarks Values describe the capture scope, including its transport and descendants.
+ * They are observations at admission, not protection against later privileged reconfiguration.
+ * Null means the corresponding cgroup file contains an unlimited value.
+ * @example
+ * ```typescript
+ * const bounded = result.resourceLimits?.memoryMaxBytes === 4096 * 1024 * 1024;
+ * ```
+ */
+export interface ProcessCaptureResourceObservation {
+  /** Exact unified cgroup path containing the capture transport. */
+  readonly cgroup: string;
+  /** Observed memory.max bytes, or null when no finite ceiling was observed. */
+  readonly memoryMaxBytes: number | null;
+  /** Observed pids.max, counting kernel tasks including threads, or null. */
+  readonly tasksMax: number | null;
+}
+
+/**
+ * Observed target result, kept separate from wrapper and cleanup outcomes.
+ * @remarks A numeric exit alone is insufficient: started, stop/error and output completeness
+ * must also be checked. Cleanup scope does not cover descendants deliberately escaping it.
+ * @example
+ * ```typescript
+ * const completed = result.started && result.stopped === null && result.error === null;
+ * ```
+ */
+export interface ProcessCaptureResult {
+  /** True only after the transport observed the requested executable's spawn event. */
+  readonly started: boolean;
+  /** Requested executable PID when observed; distinct from the scope launcher. */
+  readonly targetPid: number | null;
+  /** Actual target close code, never synthesized from a wrapper or launch error. */
+  readonly exitCode: number | null;
+  /** Actual target terminating signal, if reported before transport termination. */
+  readonly signal: string | null;
+  /** Missing executable, permission or transport failure diagnostic. */
+  readonly error: string | null;
+  /** Original stop condition; stopped executions cannot establish a passing verdict. */
+  readonly stopped: ProcessCaptureStop | null;
+  /** Bounded UTF-8 standard output. */
+  readonly stdout: string;
+  /** Bounded UTF-8 standard error. */
+  readonly stderr: string;
+  /** Whether output exceeded the capture limit. */
+  readonly outputTruncated: boolean;
+  /** Total wall time including cleanup, which may exceed the execution deadline. */
+  readonly durationMs: number;
+  /** Actual selected launcher mode; does not establish observed memory containment. */
+  readonly mode: 'systemd' | 'pgid';
+  /** Exact scope name, where the launcher selected systemd. */
+  readonly unitName?: string;
+  /** Only a finite kernel ceiling observed inside the exact owned scope establishes this claim. */
+  readonly nativeMemory: 'unverified' | 'observed-cgroup';
+  /** Present only after validated pre-target observation of requested hard limits. */
+  readonly resourceLimits?: ProcessCaptureResourceObservation;
+  /** POSIX group cleanup covers members, not descendants that deliberately escape it. */
+  readonly cleanupScope: 'process-group' | 'direct-child';
+  /** Returned only after the owned transport emitted close; not a claim about escaped descendants. */
+  readonly transportClosed: true;
+  /** Whether the transport observed the requested target close before stopping. */
+  readonly targetCloseObserved: boolean;
+  /** Exact observed cleanup evidence, distinct from mere absence of an error. */
+  readonly cleanupObservation:
+    | 'scope-terminal'
+    | 'process-group-absent'
+    | 'process-group-signalled'
+    | 'unverified';
+  /** Cleanup failures remain visible; no successful cleanup claim is inferred from exit. */
+  readonly cleanupErrors: readonly string[];
+}

package/src/task-record.ts

@@ -8,7 +8,25 @@
  * @epic T4654
  */
 
-import type { TaskVerification } from './task.js';
+import type { AcceptanceItem, TaskVerification } from './task.js';
+
+/** Omitted source fields and their UTF-8 serialized sizes on partial records. */
+export interface RecordProjectionDisclosure {
+  /** Absence means this projection did not omit any source fields. */
+  _withheld?: Record<string, number>;
+}
+
+/** Per-result retrieval basis; never implies semantic or runtime-call completeness. */
+export interface TaskMatch {
+  /** Actual reason this row matched, including explicitly requested fuzzy fallback. */
+  kind: 'lexical' | 'fuzzy' | 'exact' | 'id' | 'filter';
+  /** Source fields that support this match. */
+  fields: Array<'title' | 'description' | 'notes' | 'id'>;
+  /** Query terms present literally in those fields (empty for fuzzy-only matches). */
+  terms: string[];
+  /** Human-readable ranking basis without exposing hidden source content. */
+  reason: string;
+}
 
 /** A single task relation entry (string-widened version). */
 export interface TaskRecordRelation {
@@ -40,7 +58,9 @@ export interface TaskRecordRelationCounts {
 }
 
 /** String-widened Task for JSON serialization in dispatch/LAFS layer. */
-export interface TaskRecord {
+export interface TaskRecord extends RecordProjectionDisclosure {
+  /** Search provenance when this full record is returned by task search. */
+  match?: TaskMatch;
   id: string;
   title: string;
   description: string;
@@ -58,7 +78,8 @@ export interface TaskRecord {
   depends?: string[];
   relates?: TaskRecordRelation[];
   files?: string[];
-  acceptance?: string[];
+  /** Canonical text criteria and typed gates, preserved in full record projections. */
+  acceptance?: AcceptanceItem[];
   notes?: string[];
   labels?: string[];
   size?: string | null;
@@ -107,7 +128,9 @@ export interface TaskRecord {
  * task readiness without N+1 show calls.
  * @task T091
  */
-export interface MinimalTaskRecord {
+export interface MinimalTaskRecord extends RecordProjectionDisclosure {
+  /** Search provenance when this record is a search result. */
+  match?: TaskMatch;
   id: string;
   title: string;
   status: string;