@h-rig/contracts 0.0.6-alpha.18 → 0.0.6-alpha.181

package/dist/src/task-data.d.ts

@@ -0,0 +1,196 @@
+/**
+ * The TASK_DATA compatibility-facade seam.
+ *
+ * Floor-neutral vocab + a single `CapabilityId<TaskDataService>` for legacy
+ * task-data reads and task-command behaviours consumed by lifecycle, scheduler,
+ * isolation provisioning, repos, workspace, and CLI surfaces. Source adapters
+ * own real source IO through their dedicated seams; local task state, metadata,
+ * artifact IO, and tracker reads own their semantic capabilities in
+ * `@rig/task-state-plugin`.
+ *
+ * Ownership intent: `@rig/task-io-plugin` is the target owner for this legacy
+ * facade because it aggregates task/source IO for old consumers. The temporary
+ * provider shim remains in `@rig/task-state-plugin` only because capability
+ * provider factories run as `FeatureCapability.run(undefined)` with no
+ * `PluginHost`/resolver context; the narrower task-state/artifact/tracker
+ * capabilities are not boot-installed, and this facade still includes
+ * synchronous methods. Without a host-aware provider seam, task-io cannot compose
+ * `TASK_STATE_STORE`, `TASK_ARTIFACTS`, and `TASK_TRACKER_STATE` without a
+ * forbidden plugin-to-plugin implementation import.
+ *
+ * Consumers `resolve`/`require` task data off a built plugin host (or read the
+ * boot-installed singleton) WITHOUT importing the provider plugin. When provider
+ * execution becomes host-aware, move only the facade provider to task-io and keep
+ * the semantic state/artifact/tracker services in task-state.
+ *
+ * Pure: types + one branded legacy id, no behaviour.
+ */
+import type { CapabilityId } from "./capability-id";
+import type { TaskConfigEntry } from "./task-config";
+import type { TaskRecord, RegisteredTaskSource, TaskSourceUpdate } from "./task-source";
+import type { TaskRecordReader } from "./isolation";
+import type { CanonicalTaskLifecycleStatus, TaskStateMetadataEnvelope } from "./task-state-metadata";
+/** Result of a bounded artifact-file read (preview + truncation metadata). */
+export type TaskArtifactReadResult = {
+    path: string;
+    sizeBytes: number;
+    contents: string;
+    truncated: boolean;
+    maxBytes: number;
+};
+/** One validation category outcome inside a {@link TaskValidationSummary}. */
+export type TaskValidationCategoryResult = {
+    category: string;
+    status: "pass" | "fail";
+    exit_code?: number;
+    duration_seconds: number;
+};
+/**
+ * The aggregate task-validation outcome a task closeout reads/accepts (the
+ * category-rollup shape written to `validation-summary.json` by `taskValidate`).
+ * Distinct from the schema-typed run-level `ValidationSummary` in `./validation`.
+ */
+export type TaskValidationSummary = {
+    status: "pass" | "fail" | "skipped";
+    total: number;
+    passed: number;
+    failed: number;
+    categories: TaskValidationCategoryResult[];
+};
+/** A `bd-`/source-id lifecycle status projected from the synced tracker. */
+export type SyncedTrackerStatus = CanonicalTaskLifecycleStatus | "unknown";
+export type SyncedTrackerDependency = {
+    issueId: string | null;
+    dependsOnId: string | null;
+    id?: string | null;
+    type: string | null;
+};
+export type SyncedTrackerIssue = {
+    id: string;
+    title: string | null;
+    description: string | null;
+    acceptanceCriteria: string | null;
+    issueType: string | null;
+    status: SyncedTrackerStatus;
+    rawStatus: string | null;
+    priority: number | null;
+    dependencies: SyncedTrackerDependency[];
+};
+export type SyncedTrackerSnapshot = {
+    source: "remote" | "local";
+    baseOid: string | null;
+    issues: SyncedTrackerIssue[];
+    taskState: TaskStateMetadataEnvelope;
+};
+/** Optional fallback toggle for synced-tracker reads. */
+export type ReadSyncedTrackerOptions = {
+    allowLocalFallback?: boolean;
+};
+export type SourceAwareTaskConfigReadOptions = {
+    readonly configPath?: string;
+    readonly ghBinary?: string;
+};
+/** Result of resolving a single task through the configured task source. */
+export type TaskSourceTaskReadResult = {
+    configured: boolean;
+    sourceKind: string | null;
+    task: TaskRecord | null;
+};
+/** Summary of a `task reopen` operation. */
+export type TaskReopenSummary = {
+    mode: "all" | "single";
+    requestedTaskId: string | null;
+    dryRun: boolean;
+    closedFound: number;
+    reopened: string[];
+    failed: string[];
+    skipped: string[];
+};
+/** Identity fields used to resolve a task's source issue. */
+export type SourceTaskIdentity = {
+    id?: unknown;
+    sourceIssueId?: unknown;
+    source_issue_id?: unknown;
+};
+/** Result of pushing an explicit source writeback through the configured source. */
+export type TaskSourceWritebackResult = {
+    taskId: string;
+    updated: boolean;
+    source: "plugin" | "none";
+    sourceKind: string | null;
+    status: unknown;
+};
+/** Context for building a plugin-backed task-record reader. */
+export type PluginTaskRecordReaderContext = {
+    taskSourceRegistry: {
+        list(): readonly RegisteredTaskSource[];
+        resolveById(id: string): RegisteredTaskSource;
+        resolveByKind(kind: string): RegisteredTaskSource;
+    };
+};
+/** Options selecting a source for a plugin-backed task-record reader. */
+export type PluginTaskRecordReaderOptions = {
+    projectRoot: string;
+    sourceId?: string;
+    sourceKind?: string;
+};
+/**
+ * Legacy TASK_DATA compatibility facade.
+ *
+ * The shape intentionally remains broad while callers migrate to narrower
+ * semantic capabilities. Every method is keyed by `projectRoot` (the service is
+ * stateless), so the current provider can be installed as a boot singleton and
+ * read synchronously by substrate consumers.
+ */
+export interface TaskDataService {
+    currentTaskId(projectRoot: string): string;
+    readTaskConfig(projectRoot: string): Record<string, TaskConfigEntry>;
+    readSourceTaskConfig(projectRoot: string): Record<string, TaskConfigEntry>;
+    readValidationDescriptions(projectRoot: string): Record<string, string>;
+    lookupTask(projectRoot: string, input: string): string;
+    artifactDirForId(projectRoot: string, id: string): string;
+    /** @deprecated Third argument is ignored; runtime/provider instruction ownership lives outside TASK_DATA. */
+    taskInfo(projectRoot: string, taskId?: string, deprecatedRuntimeProviderOverride?: unknown): Promise<void>;
+    taskDeps(projectRoot: string, taskId?: string): Promise<void>;
+    taskStatus(projectRoot: string): void;
+    taskScope(projectRoot: string, expandFiles: boolean, taskId?: string): Promise<void>;
+    taskReady(projectRoot: string): Promise<void>;
+    taskLookup(projectRoot: string, id: string): string;
+    taskRecord(projectRoot: string, type: "decision" | "failure", text: string, taskId?: string): void;
+    taskReopen(projectRoot: string, options: {
+        all: boolean;
+        taskId?: string;
+        dryRun?: boolean;
+    }): TaskReopenSummary;
+    taskArtifacts(projectRoot: string, taskId?: string): void;
+    taskArtifactDir(projectRoot: string, taskId?: string): string;
+    taskArtifactWrite(projectRoot: string, filename: string, content: string, taskId?: string): void;
+    taskArtifactRead(projectRoot: string, filename: string, options?: {
+        taskId?: string;
+        maxBytes?: number;
+    }): TaskArtifactReadResult;
+    taskDependencyIds(projectRoot: string, taskId: string): string[];
+    changedFilesForTask(projectRoot: string, taskId: string, scoped: boolean): string[];
+    pendingFilesForTask(projectRoot: string, taskId: string, scoped: boolean): string[];
+    readSourceAwareTaskStatus(projectRoot: string, taskId: string, options?: SourceAwareTaskConfigReadOptions): Promise<unknown>;
+    readConfiguredTaskSourceTask(projectRoot: string, taskId: string): Promise<TaskSourceTaskReadResult>;
+    updateConfiguredTaskSourceTask(projectRoot: string, input: {
+        taskId: string;
+        sourceTask?: SourceTaskIdentity | null;
+        update: TaskSourceUpdate;
+    }): Promise<TaskSourceWritebackResult>;
+    createLegacyTaskConfigRecordReader(projectRoot: string, options?: {
+        configPath?: string;
+    }): TaskRecordReader;
+    createSourceAwareTaskConfigRecordReader(projectRoot: string, options?: SourceAwareTaskConfigReadOptions): TaskRecordReader;
+    createPluginTaskRecordReader(context: PluginTaskRecordReaderContext, options: PluginTaskRecordReaderOptions): TaskRecordReader;
+    readSyncedTrackerState(projectRoot: string, deps?: unknown, options?: ReadSyncedTrackerOptions): SyncedTrackerSnapshot;
+    normalizeTaskLifecycleStatus(status: unknown): CanonicalTaskLifecycleStatus | null;
+}
+/** Stable legacy id string for the TASK_DATA compatibility facade. */
+export declare const TASK_DATA_SERVICE_CAPABILITY_ID = "task-sources.task-data";
+/**
+ * The branded task-data capability id. `defineCapability(TASK_DATA_SERVICE_CAPABILITY)`
+ * (provider and consumers, independently) resolves to a `TaskDataService`.
+ */
+export declare const TASK_DATA_SERVICE_CAPABILITY: CapabilityId<TaskDataService>;

package/dist/src/task-data.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/task-data.ts
+var TASK_DATA_SERVICE_CAPABILITY_ID = "task-sources.task-data";
+var TASK_DATA_SERVICE_CAPABILITY = makeCapabilityId(TASK_DATA_SERVICE_CAPABILITY_ID);
+export {
+  TASK_DATA_SERVICE_CAPABILITY_ID,
+  TASK_DATA_SERVICE_CAPABILITY
+};

package/dist/src/task-graph-primitives.d.ts

@@ -0,0 +1,47 @@
+import type { TaskSummary } from "./graph";
+export type TaskDependencyProjection = Pick<TaskSummary, "id" | "status" | "priority" | "metadata"> & Partial<Pick<TaskSummary, "externalId" | "sourceIssueId" | "dependencies" | "parentChildDeps" | "createdAt" | "updatedAt" | "role" | "scope" | "validationKeys">> & {
+    readonly title?: string | null;
+};
+export type ClientTaskProjection = TaskDependencyProjection & {
+    readonly title?: string | null;
+    readonly assignees?: readonly string[] | null;
+    readonly assignedTo?: string | readonly string[] | null;
+    readonly labels?: readonly string[] | null;
+};
+export type TaskProjectionInput = {
+    readonly id: string;
+    readonly title?: string | null;
+    readonly status?: string | null;
+    readonly source?: string | null;
+    readonly url?: string | null;
+    readonly body?: string | null;
+    readonly priority?: number | string | null;
+    readonly assignedTo?: string | readonly string[] | null;
+    readonly assignees?: readonly string[] | null;
+    readonly dependencies?: readonly string[] | null;
+    readonly parentChildDeps?: readonly string[] | null;
+    readonly metadata?: Record<string, unknown> | null;
+    readonly [key: string]: unknown;
+};
+export type TaskDependencyBadgeKind = "blocked" | "ready" | "dependency";
+export interface TaskDependencyBadge {
+    readonly kind: TaskDependencyBadgeKind;
+    readonly label: string;
+    readonly description: string;
+    readonly count?: number;
+    readonly taskIds?: readonly string[];
+}
+export interface TaskDependencyBadgeSummary {
+    readonly taskId: string;
+    readonly blockingDepth: number;
+    readonly dependencyIds: readonly string[];
+    readonly unresolvedDependencyRefs: readonly string[];
+    readonly blockedBy: readonly string[];
+    readonly blocks: readonly string[];
+    readonly blocked: boolean;
+    readonly ready: boolean;
+    readonly dependencyCount: number;
+    readonly dependentCount: number;
+    readonly badges: readonly TaskDependencyBadge[];
+}
+export type TaskScopeInput = readonly string[] | TaskDependencyProjection;

package/dist/src/task-graph-primitives.js

@@ -0,0 +1 @@
+// @bun

package/dist/src/task-source.d.ts

@@ -0,0 +1,167 @@
+import type { CapabilityId } from "./capability-id";
+import type { TaskSourceRegistration } from "./plugin";
+import type { TaskConfigEntry } from "./task-config";
+export type { TaskConfigEntry } from "./task-config";
+/**
+ * A single task record returned by a task source adapter.
+ * Open-ended to allow adapters to include source-specific fields.
+ */
+export interface TaskRecord {
+    id: string;
+    deps: readonly string[];
+    status: "ready" | "in_progress" | "closed" | "blocked" | "open" | string;
+    [extra: string]: unknown;
+}
+/**
+ * The NORMALIZED, surface-facing task shape (the projection consumers read).
+ * The TYPE is floor-neutral vocab and lives here in contracts; the normalization
+ * implementation is provided by the task IO owner, not by the source-adapter
+ * plugin.
+ */
+export type RigTask = {
+    readonly id: string;
+    readonly title?: string | null;
+    readonly status?: string | null;
+    readonly source?: string | null;
+    readonly url?: string | null;
+    readonly body?: string | null;
+    readonly priority?: number | string | null;
+    readonly assignedTo?: string | readonly string[] | null;
+    readonly assignees?: readonly string[] | null;
+    readonly dependencies?: readonly string[] | null;
+    readonly parentChildDeps?: readonly string[] | null;
+    readonly metadata?: Record<string, unknown> | null;
+    readonly [key: string]: unknown;
+};
+/** Alias retained for call sites that accept any task-like projection. */
+export type TaskLike = RigTask;
+export type TaskSourceLabelUpdate = {
+    readonly add?: readonly string[];
+    readonly remove?: readonly string[];
+};
+/**
+ * Explicit provider-owned source update payload. Reflection code should
+ * project intent into these concrete source write values before calling adapters.
+ */
+export interface TaskSourceProjectedUpdate {
+    labels?: TaskSourceLabelUpdate;
+    sourceFields?: Record<string, string | null | undefined>;
+    close?: boolean;
+    assignToDefault?: boolean;
+}
+/** Generic provider-owned source update payload. */
+export interface TaskSourceUpdate extends TaskSourceProjectedUpdate {
+    title?: string;
+    body?: string;
+    comment?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface TaskSourceCreateInput {
+    title: string;
+    body: string;
+    deps?: readonly string[];
+    parents?: readonly string[];
+    metadata?: Record<string, unknown>;
+}
+export type TaskSourceCreateResult = TaskRecord;
+export type TaskSourceUpdateRequest = {
+    readonly projectRoot: string;
+    readonly taskId: string;
+    readonly sourceId?: string | null;
+    readonly sourceKind?: string | null;
+    readonly update: TaskSourceUpdate;
+};
+export type TaskSourceUpdateWriteResult = "applied" | "not-configured" | "unsupported";
+export type TaskSourceUpdateResult = {
+    readonly taskId: string;
+    readonly updated: boolean;
+    /** Authoritative source write outcome. `updated` is retained as a boolean compatibility projection. */
+    readonly writeResult: TaskSourceUpdateWriteResult;
+    readonly sourceId?: string | null;
+    readonly sourceKind?: string | null;
+    /** Best-effort status read back from the source after the write; absent/null when the adapter cannot read back. */
+    readonly sourceStatus?: unknown;
+};
+/**
+ * Generic source-adapter writeback port. The legacy id string is retained, but
+ * implementations should only dispatch to configured source adapters; local task
+ * state, normalized task IO, source reflection, and validation policy are
+ * owned by their respective plugins.
+ */
+export interface TaskSourceUpdateService {
+    updateTask(input: TaskSourceUpdateRequest): Promise<TaskSourceUpdateResult>;
+}
+/**
+ * Synchronous projection seam for task-source-owned task config materialization.
+ *
+ * The service owns source adapter/config-path semantics (for example files-backed
+ * task directories and source task-config locations) while legacy sync state-store
+ * callers keep the existing `TaskStateStoreService` surface.
+ */
+export interface TaskSourceConfigProjectionService {
+    /** Resolve the sync TaskStateStoreService readTaskConfig path, including source-owned fallback paths. */
+    resolveTaskConfigPath(projectRoot: string): string;
+    readSourceTaskConfig(projectRoot: string): Record<string, TaskConfigEntry>;
+    writeSourceTaskConfig(projectRoot: string, entries: Record<string, TaskConfigEntry>): void;
+    readSourceValidationDescriptions(projectRoot: string): Record<string, string>;
+}
+export declare const TASK_SOURCE_CONFIG_PROJECTION_CAPABILITY_ID = "task-sources.config-projection";
+export declare const TASK_SOURCE_CONFIG_PROJECTION: CapabilityId<TaskSourceConfigProjectionService>;
+export type TaskTerminalStateInput = {
+    readonly projectRoot: string;
+    readonly taskId: string;
+};
+/** Source-owned task terminal-state projection, including source config and Beads fallback. */
+export interface TaskSourceTerminalStateService {
+    isTaskTerminal(input: TaskTerminalStateInput): Promise<boolean>;
+}
+export declare const TASK_SOURCE_TERMINAL_STATE_CAPABILITY_ID = "task-sources.terminal-state";
+export declare const TASK_SOURCE_TERMINAL_STATE: CapabilityId<TaskSourceTerminalStateService>;
+export declare const TASK_SOURCE_UPDATE_CAPABILITY_ID = "task-sources.update";
+export declare const TASK_SOURCE_UPDATE: CapabilityId<TaskSourceUpdateService>;
+export interface RegisteredTaskSource extends TaskSourceRegistration {
+    list(): Promise<readonly TaskRecord[]>;
+    get?(id: string): Promise<TaskRecord | undefined>;
+    updateTask?(id: string, update: TaskSourceUpdate): Promise<void>;
+    create?(input: TaskSourceCreateInput): Promise<TaskSourceCreateResult>;
+}
+export type TaskIoCreateResult = {
+    readonly taskId: string | null;
+    readonly source: string;
+    readonly result: unknown;
+};
+export type TaskFactRecordInput = {
+    readonly type: "decision" | "failure";
+    readonly text: string;
+    readonly taskId?: string;
+};
+export type TaskFactRecordResult = {
+    readonly taskId: string;
+    readonly message: string;
+};
+export type TaskArtifactsPrepareResult = {
+    readonly taskId: string;
+    readonly artifactDir: string;
+    readonly message: string;
+};
+export type TaskIoStateFilter = "open" | "closed";
+export interface TaskIoListFilters {
+    readonly assignee?: string;
+    readonly state?: TaskIoStateFilter;
+    readonly limit?: number;
+    readonly search?: string;
+}
+/**
+ * Normalized task IO projection seam. The historical id string is retained for
+ * compatibility, but this capability is owned/provided by @rig/task-io-plugin;
+ * source-adapter plugins should contribute adapters and source writeback only.
+ */
+export interface TaskIoService {
+    listTasks(projectRoot: string, filters?: TaskIoListFilters): Promise<readonly RigTask[]>;
+    getTask(projectRoot: string, taskId: string): Promise<RigTask | null>;
+    createTask(projectRoot: string, task: Record<string, unknown>): Promise<TaskIoCreateResult>;
+    recordTaskFact(projectRoot: string, input: TaskFactRecordInput): Promise<TaskFactRecordResult>;
+    prepareTaskArtifacts(projectRoot: string, taskId?: string): Promise<TaskArtifactsPrepareResult>;
+}
+export declare const TASK_IO_SERVICE_CAPABILITY_ID = "rig.tasks.io";
+export declare const TASK_IO_SERVICE_CAPABILITY: CapabilityId<TaskIoService>;

package/dist/src/task-source.js

@@ -1 +1,25 @@
 // @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/task-source.ts
+var TASK_SOURCE_CONFIG_PROJECTION_CAPABILITY_ID = "task-sources.config-projection";
+var TASK_SOURCE_CONFIG_PROJECTION = makeCapabilityId(TASK_SOURCE_CONFIG_PROJECTION_CAPABILITY_ID);
+var TASK_SOURCE_TERMINAL_STATE_CAPABILITY_ID = "task-sources.terminal-state";
+var TASK_SOURCE_TERMINAL_STATE = makeCapabilityId(TASK_SOURCE_TERMINAL_STATE_CAPABILITY_ID);
+var TASK_SOURCE_UPDATE_CAPABILITY_ID = "task-sources.update";
+var TASK_SOURCE_UPDATE = makeCapabilityId(TASK_SOURCE_UPDATE_CAPABILITY_ID);
+var TASK_IO_SERVICE_CAPABILITY_ID = "rig.tasks.io";
+var TASK_IO_SERVICE_CAPABILITY = makeCapabilityId(TASK_IO_SERVICE_CAPABILITY_ID);
+export {
+  TASK_SOURCE_UPDATE_CAPABILITY_ID,
+  TASK_SOURCE_UPDATE,
+  TASK_SOURCE_TERMINAL_STATE_CAPABILITY_ID,
+  TASK_SOURCE_TERMINAL_STATE,
+  TASK_SOURCE_CONFIG_PROJECTION_CAPABILITY_ID,
+  TASK_SOURCE_CONFIG_PROJECTION,
+  TASK_IO_SERVICE_CAPABILITY_ID,
+  TASK_IO_SERVICE_CAPABILITY
+};

package/dist/src/task-state-metadata.d.ts

@@ -0,0 +1,21 @@
+export type CanonicalTaskLifecycleStatus = "draft" | "open" | "ready" | "queued" | "in_progress" | "under_review" | "blocked" | "completed" | "cancelled";
+export type TaskStateMetadata = {
+    claimId?: string;
+    status: CanonicalTaskLifecycleStatus;
+    ownerId?: string;
+    claimedAt?: string;
+    lastEvidenceAt?: string;
+    runId?: string;
+    branchName?: string;
+    prNumber?: number;
+    prUrl?: string;
+    reviewState?: string;
+    blockerReason?: string;
+    sourceCommit?: string;
+};
+export type TaskStateMetadataEnvelope = {
+    schemaVersion: number;
+    supported: boolean;
+    baseTrackerCommit: string | null;
+    tasks: Record<string, TaskStateMetadata>;
+};

package/dist/src/task-state-metadata.js

@@ -0,0 +1 @@
+// @bun

package/dist/src/task-state-paths.d.ts

@@ -0,0 +1,14 @@
+import type { CapabilityId } from "./capability-id";
+/** Task-state-owned local path layout for task config/session/artifacts/metadata files. */
+export interface TaskStatePaths {
+    readonly stateDir: string;
+    readonly artifactsDir: string;
+    readonly taskConfigPath: string;
+    readonly sessionPath: string;
+    readonly failedApproachesPath: string;
+}
+export interface TaskStatePathsService {
+    resolvePaths(projectRoot: string): TaskStatePaths;
+}
+export declare const TASK_STATE_PATHS_CAPABILITY_ID = "task-state.paths";
+export declare const TASK_STATE_PATHS: CapabilityId<TaskStatePathsService>;

package/dist/src/task-state-paths.js

@@ -0,0 +1,13 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/task-state-paths.ts
+var TASK_STATE_PATHS_CAPABILITY_ID = "task-state.paths";
+var TASK_STATE_PATHS = makeCapabilityId(TASK_STATE_PATHS_CAPABILITY_ID);
+export {
+  TASK_STATE_PATHS_CAPABILITY_ID,
+  TASK_STATE_PATHS
+};

package/dist/src/task-state-store.d.ts

@@ -0,0 +1,36 @@
+import type { CapabilityId } from "./capability-id";
+import type { TaskConfigEntry } from "./task-config";
+import type { TaskTerminalStateInput } from "./task-source";
+import type { TaskStateMetadataEnvelope } from "./task-state-metadata";
+export type TaskFailedApproachRecordInput = {
+    readonly projectRoot: string;
+    readonly taskId?: string;
+    readonly text: string;
+    readonly timestamp?: string;
+};
+export type TaskFailedApproachRecordResult = {
+    readonly taskId: string;
+    readonly attempts: number;
+    readonly path: string;
+    readonly message: string;
+};
+/** Local `.rig` task state/config/metadata only; no runtime/provider guidance. */
+export interface TaskStateStoreService {
+    readCurrentTaskId(projectRoot: string): string | null;
+    writeCurrentTaskId(projectRoot: string, taskId: string | null): void;
+    readTaskConfig(projectRoot: string): Record<string, TaskConfigEntry>;
+    writeTaskConfig(projectRoot: string, entries: Record<string, TaskConfigEntry>): void;
+    readSourceTaskConfig(projectRoot: string): Record<string, TaskConfigEntry>;
+    writeSourceTaskConfig(projectRoot: string, entries: Record<string, TaskConfigEntry>): void;
+    readTaskStateMetadata(projectRoot: string): TaskStateMetadataEnvelope | null;
+    writeTaskStateMetadata(projectRoot: string, envelope: TaskStateMetadataEnvelope): void;
+    recordFailedApproach(input: TaskFailedApproachRecordInput): TaskFailedApproachRecordResult;
+}
+export declare const TASK_STATE_STORE_CAPABILITY_ID = "task-state.store";
+export declare const TASK_STATE_STORE: CapabilityId<TaskStateStoreService>;
+/** Local task-state-owned terminal-state check over `.rig/task-config.json`. */
+export interface TaskStateTerminalStateService {
+    isTaskTerminal(input: TaskTerminalStateInput): Promise<boolean>;
+}
+export declare const TASK_STATE_TERMINAL_STATE_CAPABILITY_ID = "task-state.terminal-state";
+export declare const TASK_STATE_TERMINAL_STATE: CapabilityId<TaskStateTerminalStateService>;

package/dist/src/task-state-store.js

@@ -0,0 +1,17 @@
+// @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
+// packages/contracts/src/task-state-store.ts
+var TASK_STATE_STORE_CAPABILITY_ID = "task-state.store";
+var TASK_STATE_STORE = makeCapabilityId(TASK_STATE_STORE_CAPABILITY_ID);
+var TASK_STATE_TERMINAL_STATE_CAPABILITY_ID = "task-state.terminal-state";
+var TASK_STATE_TERMINAL_STATE = makeCapabilityId(TASK_STATE_TERMINAL_STATE_CAPABILITY_ID);
+export {
+  TASK_STATE_TERMINAL_STATE_CAPABILITY_ID,
+  TASK_STATE_TERMINAL_STATE,
+  TASK_STATE_STORE_CAPABILITY_ID,
+  TASK_STATE_STORE
+};

package/dist/src/task-tracker-state.d.ts

@@ -0,0 +1,101 @@
+import type { CapabilityId } from "./capability-id";
+import type { CanonicalTaskLifecycleStatus, TaskStateMetadata, TaskStateMetadataEnvelope } from "./task-state-metadata";
+import type { SyncedTrackerSnapshot, ReadSyncedTrackerOptions } from "./task-data";
+export declare const TASK_TRACKER_LIFECYCLE_STATUSES: readonly ["draft", "open", "ready", "queued", "in_progress", "under_review", "blocked", "completed", "cancelled"];
+export declare const TASK_TRACKER_STALE_CLAIM_MS: number;
+export type TaskTrackerPolicyDecision = {
+    readonly allowed: boolean;
+    readonly code?: "claim-conflict" | "status-conflict";
+    readonly reason?: string;
+    /** Owner-supplied compare-and-set precondition for tracker persistence. */
+    readonly expectedLifecycleStatus?: CanonicalTaskLifecycleStatus | readonly CanonicalTaskLifecycleStatus[];
+};
+export type TrackerPullRequestEvidence = {
+    readonly branchName?: string | null;
+    readonly prNumber?: number | null;
+    readonly prUrl?: string | null;
+    readonly isOpen?: boolean;
+    readonly isMerged?: boolean;
+    readonly reviewState?: string | null;
+};
+export type TrackerReconcileEvidence = {
+    readonly now?: string;
+    readonly closeoutPassed?: boolean;
+    readonly pr?: TrackerPullRequestEvidence | null;
+    readonly activeOwnerIds?: readonly string[];
+};
+export type TaskReconciliationProjection = {
+    readonly valid: boolean;
+    readonly reasons: readonly string[];
+    readonly isStale: boolean;
+    readonly wouldReconcileTo: CanonicalTaskLifecycleStatus | null;
+    readonly nextMetadata: TaskStateMetadata | null;
+};
+export type TaskTrackerReconciliationPolicyInput = {
+    readonly lifecycleStatus: CanonicalTaskLifecycleStatus;
+    readonly metadata: TaskStateMetadata | null;
+    readonly evidence?: TrackerReconcileEvidence;
+    /**
+     * Explicit clock input keeps the lifecycle-owned projection deterministic.
+     */
+    readonly nowIso: string;
+};
+export type TaskTrackerClaimTransitionPolicyInput = {
+    readonly taskId: string;
+    readonly lifecycleStatus: CanonicalTaskLifecycleStatus;
+    readonly expectedStatus?: CanonicalTaskLifecycleStatus;
+};
+export type TaskTrackerLifecycleTransitionPolicyInput = {
+    readonly taskId: string;
+    readonly lifecycleStatus: CanonicalTaskLifecycleStatus;
+    readonly allowedFrom?: readonly CanonicalTaskLifecycleStatus[];
+};
+export interface TaskTrackerReconciliationPolicyService {
+    projectReconciliation(input: TaskTrackerReconciliationPolicyInput): TaskReconciliationProjection;
+    canUpdateLifecycle(input: TaskTrackerLifecycleTransitionPolicyInput): TaskTrackerPolicyDecision;
+}
+export declare const TASK_TRACKER_RECONCILIATION_POLICY_CAPABILITY_ID = "lifecycle.task-tracker-reconciliation-policy";
+export declare const TASK_TRACKER_RECONCILIATION_POLICY: CapabilityId<TaskTrackerReconciliationPolicyService>;
+export interface TaskTrackerReadinessPolicyService {
+    listReadyTaskIds(snapshot: SyncedTrackerSnapshot): readonly string[];
+    canClaimTask(input: TaskTrackerClaimTransitionPolicyInput): TaskTrackerPolicyDecision;
+}
+export declare const TASK_TRACKER_READINESS_POLICY_CAPABILITY_ID = "scheduler.task-tracker-readiness-policy";
+export declare const TASK_TRACKER_READINESS_POLICY: CapabilityId<TaskTrackerReadinessPolicyService>;
+export type TaskTrackerStateUpdateInput = {
+    readonly projectRoot: string;
+    readonly taskId: string;
+    readonly lifecycleStatus: CanonicalTaskLifecycleStatus;
+    readonly metadata?: TaskStateMetadata | null;
+    /** Lifecycle-owner supplied transition precondition. Required by the legacy task-state wrapper. */
+    readonly allowedFrom?: readonly CanonicalTaskLifecycleStatus[];
+    readonly reason?: string;
+};
+export type TaskTrackerStateClaimInput = {
+    readonly projectRoot: string;
+    readonly taskId: string;
+    readonly ownerId: string;
+    readonly runId?: string | null;
+    readonly now?: string;
+};
+/**
+ * Tracker repository locator seam.
+ *
+ * Task-state owns tracker persistence and metadata storage only. Lifecycle and
+ * scheduler policy capabilities own reconciliation, stale-claim, readiness, and
+ * transition decisions; contracts provides the pure vocabulary/capability ids.
+ */
+export interface TaskTrackerRepoLocatorService {
+    resolveTrackerRepoPath(projectRoot: string): string;
+}
+export declare const TASK_TRACKER_REPO_LOCATOR_CAPABILITY_ID = "task-state.tracker-repo-locator";
+export declare const TASK_TRACKER_REPO_LOCATOR: CapabilityId<TaskTrackerRepoLocatorService>;
+/** Tracker snapshot/persistence API. Keep this shape stable for legacy callers. */
+export interface TaskTrackerStateService {
+    readSnapshot(projectRoot: string, options?: ReadSyncedTrackerOptions): SyncedTrackerSnapshot;
+    normalizeStatus(status: unknown): CanonicalTaskLifecycleStatus | null;
+    claimTask(input: TaskTrackerStateClaimInput): TaskStateMetadataEnvelope | Promise<TaskStateMetadataEnvelope>;
+    updateLifecycle(input: TaskTrackerStateUpdateInput): TaskStateMetadataEnvelope | Promise<TaskStateMetadataEnvelope>;
+}
+export declare const TASK_TRACKER_STATE_CAPABILITY_ID = "task-state.tracker-state";
+export declare const TASK_TRACKER_STATE: CapabilityId<TaskTrackerStateService>;