sdd-agent-platform 0.1.0

package/dist/packages/core/src/index.d.ts

@@ -0,0 +1,1016 @@
+import { type AiProjectionResult, type AiToolSelection } from './ai-tools.js';
+export * from './ai-tools.js';
+export * from './instructions.js';
+export declare const RUNTIME_VERSION = "phase-1.2-runtime-skeleton";
+export declare const PROJECT_CONFIG_CONTRACT = "phase-1.2-project-contract";
+export declare const RUN_STATE_CONTRACT = "phase-1.2-run-state-contract";
+export declare const EVENT_LOG_CONTRACT = "phase-1.2-event-log-contract";
+export declare const ARTIFACT_PATH_CONTRACT = "phase-1.2-artifact-path-contract";
+export declare const LEGACY_LIFECYCLE_DECISION_CONTRACT = "phase-1.2-lifecycle-decision-contract";
+export declare const LIFECYCLE_DECISION_CONTRACT = "sdd-lifecycle-decision-v1";
+export declare const LIFECYCLE_DECISION_VERSION = "1.3.0";
+export declare const SDD_RESULT_CONTRACT = "sdd-result-v1";
+export declare const SDD_RESULT_VERSION = "1.3.0";
+export declare const DELEGATION_LIVENESS_CONTRACT = "sdd-delegation-liveness-v1";
+export declare const DELEGATION_LIVENESS_VERSION = "1.3.0";
+export declare const ARTIFACT_RESULT_INGESTION_CONTRACT_VERSION = "phase-3.6-artifact-result-ingestion-v1";
+export declare const TASK_GRAPH_PLANNER_CONTRACT_VERSION = "phase-3.9-task-graph-planner-v1";
+export declare const WAVE_PLANNER_CONTRACT_VERSION = "phase-3.10-wave-planner-v1";
+export declare const BACKGROUND_EXECUTOR_CONTRACT_VERSION = "phase-3.11-background-executor-v1";
+export declare const WAVE_EXECUTOR_CONTRACT_VERSION = "phase-3.12-wave-executor-v1";
+export declare const LOCAL_RUN_INDEX_CONTRACT_VERSION = "phase-3.13-local-run-index-v1";
+export declare const GOVERNANCE_POLICY_CONTRACT_VERSION = "phase-3.14-governance-policy-v1";
+export type DoctorLevel = 'PASS' | 'WARN' | 'FAIL';
+export type RunStatus = 'created' | 'running' | 'completed' | 'blocked' | 'failed' | 'archived';
+export type LifecycleProfile = 'direct' | 'compact' | 'full' | 'research';
+export type LifecycleConfidence = 'high' | 'medium' | 'low';
+export type SddResultStatus = 'PASS' | 'PASS_WITH_GAPS' | 'FAIL' | 'BLOCKED' | 'TIMED_OUT' | 'CANCELLED';
+export type DelegationRunMode = 'foreground' | 'background';
+export type DelegationStatus = 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'TIMED_OUT' | 'CANCELLED' | 'RECOVERABLE' | 'STALE';
+export type GoalVerifyStatus = 'PASS' | 'PASS_WITH_GAPS' | 'FAIL' | 'BLOCKED';
+export type ArtifactResultIngestionStatus = 'accepted' | 'rejected';
+export type DetectionConfidence = 'high' | 'medium' | 'low';
+export interface DetectionEvidence {
+    kind: string;
+    detail: string;
+    weight: number;
+}
+export interface ProjectDetectionCandidate {
+    id: string;
+    language: string;
+    framework: string;
+    score: number;
+    confidence: DetectionConfidence;
+    evidence: DetectionEvidence[];
+    validationDefault: string[];
+}
+export interface ProjectDetection {
+    primary: ProjectDetectionCandidate;
+    candidates: ProjectDetectionCandidate[];
+    mixed_stack: boolean;
+}
+export interface ProjectConfig {
+    contract: typeof PROJECT_CONFIG_CONTRACT;
+    project: {
+        name: string;
+        language: string;
+        framework: string;
+    };
+    detection?: {
+        confidence: DetectionConfidence;
+        mixed_stack: boolean;
+        primary: string;
+        candidates: Array<{
+            id: string;
+            confidence: DetectionConfidence;
+            score: number;
+        }>;
+    };
+    sdd: {
+        spec_dir: string;
+        docs_language: string;
+        compatible_with: string;
+    };
+    validation: {
+        default: string[];
+    };
+    editing: {
+        prefer_hashline: boolean;
+        native_edit_fallback: boolean;
+    };
+    runtime: {
+        background_write: boolean;
+        worktree_isolation: boolean;
+        sync_back_mode: 'proposal';
+    };
+    lifecycle: {
+        decision_required: boolean;
+        profiles: LifecycleProfile[];
+    };
+}
+export type ToolCapabilityCategory = 'runtime' | 'editing' | 'git' | 'validation' | 'browser' | 'artifact' | 'governance';
+export type ToolCapabilitySideEffect = 'read_only' | 'local_write' | 'command_execution' | 'external_interaction';
+export interface ToolCapability {
+    id: string;
+    title: string;
+    category: ToolCapabilityCategory;
+    summary: string;
+    sideEffect: ToolCapabilitySideEffect;
+    defaultAvailable: boolean;
+    allowedStages: string[];
+    requiredEvidence: string[];
+    forbiddenUses: string[];
+}
+export interface ToolCapabilityRegistry {
+    version: string;
+    capabilities: ToolCapability[];
+}
+export type ToolPluginEntryKind = 'cli' | 'adapter' | 'command' | 'manual';
+export type ToolPluginLoadMode = 'static_manifest' | 'readonly_asset';
+export interface ToolPluginContract {
+    id: string;
+    title: string;
+    version: string;
+    capabilityId: string;
+    entryKind: ToolPluginEntryKind;
+    assetPath: string;
+    loadMode: ToolPluginLoadMode;
+    checksum: string | null;
+    requiredEvidence: string[];
+    forbiddenUses: string[];
+}
+export interface ToolPluginContractRegistry {
+    version: string;
+    contracts: ToolPluginContract[];
+}
+export type DelegationQueueStatusSource = 'run_state_delegation';
+export interface DelegationQueueItem {
+    id: string;
+    runId: string;
+    delegationId: string;
+    taskId: string;
+    agent: string;
+    requestedCapabilityId: string;
+    dedupeKey: string;
+    status: DelegationStatus;
+    statusSource: DelegationQueueStatusSource;
+    runMode: DelegationRunMode;
+    expectedArtifact: string;
+    requiredEvidence: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface DelegationQueueSnapshot {
+    version: string;
+    items: DelegationQueueItem[];
+}
+export interface DelegationStateTransition {
+    from: DelegationStatus;
+    to: DelegationStatus;
+    event: string;
+    terminal: boolean;
+}
+export interface DelegationStateMachine {
+    version: string;
+    statuses: DelegationStatus[];
+    terminalStatuses: DelegationStatus[];
+    transitions: DelegationStateTransition[];
+}
+export interface DelegationStateTransitionValidation {
+    valid: boolean;
+    from: DelegationStatus;
+    to: DelegationStatus;
+    event: string | null;
+    issues: ContractValidationIssue[];
+}
+export type WorkerAdapterKind = 'claude_code_subagent' | 'sdd_cli_task' | 'manual_handoff';
+export type WorkerAdapterExitStatus = 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'blocked';
+export interface WorkerAdapterPayloadContract {
+    queueItemId: string;
+    runId: string;
+    taskId: string;
+    delegationId: string;
+    stateMachineVersion: string;
+}
+export interface WorkerAdapterOutputContract {
+    artifactReference: string;
+    terminalStatus: DelegationStatus[];
+    exitStatuses: WorkerAdapterExitStatus[];
+    requiredEvents: string[];
+}
+export interface WorkerAdapterContract {
+    id: string;
+    title: string;
+    version: string;
+    kind: WorkerAdapterKind;
+    capabilityId: string;
+    pluginContractId: string;
+    input: WorkerAdapterPayloadContract;
+    output: WorkerAdapterOutputContract;
+    sideEffect: ToolCapabilitySideEffect;
+    permissionPrompt: string;
+    requiredEvidence: string[];
+    forbiddenUses: string[];
+}
+export interface WorkerAdapterContractRegistry {
+    version: string;
+    adapters: WorkerAdapterContract[];
+}
+export type WorktreeIsolationMode = 'none' | 'required' | 'blocked' | 'manual';
+export interface WorktreeIsolationPeer {
+    taskId: string;
+    affectedFiles: string[];
+    risk: string[];
+}
+export interface WorktreeIsolationGate {
+    name: string;
+    passed: boolean;
+    message: string;
+}
+export interface WorktreeIsolationDecision {
+    version: string;
+    taskId: string;
+    mode: WorktreeIsolationMode;
+    safeConcurrency: boolean;
+    capabilityId: string;
+    capabilitySideEffect: ToolCapabilitySideEffect;
+    affectedFiles: string[];
+    risk: string[];
+    peers: WorktreeIsolationPeer[];
+    overlaps: Array<{
+        peerTaskId: string;
+        files: string[];
+    }>;
+    gates: WorktreeIsolationGate[];
+    reasons: string[];
+}
+export type WorktreeLifecycleStatus = 'created' | 'kept' | 'removed';
+export interface WorktreeLifecycleRecord {
+    contract: typeof WORKTREE_LIFECYCLE_CONTRACT_VERSION;
+    runId: string;
+    taskId: string;
+    worktreeId: string;
+    status: WorktreeLifecycleStatus;
+    branchName: string;
+    worktreePath: string;
+    baseRef: string;
+    createdAt: string;
+    updatedAt: string;
+    removedAt: string | null;
+    keepReason: string | null;
+    dirty: boolean;
+}
+export interface WorktreeLifecycleInspection {
+    runId: string;
+    contract: typeof WORKTREE_LIFECYCLE_CONTRACT_VERSION;
+    records: WorktreeLifecycleRecord[];
+    valid: boolean;
+    issues: ContractValidationIssue[];
+}
+export interface ArtifactResultIngestionRecord {
+    contract: typeof ARTIFACT_RESULT_INGESTION_CONTRACT_VERSION;
+    runId: string;
+    delegationId: string;
+    task: string;
+    agent: string;
+    artifactPath: string;
+    status: ArtifactResultIngestionStatus;
+    resultStatus: SddResultStatus | null;
+    delegationStatus: DelegationStatus | null;
+    ingestedAt: string;
+    issues: ContractValidationIssue[];
+    gaps: SddTaskGap[];
+}
+export interface ArtifactResultIngestionResult {
+    valid: boolean;
+    duplicate: boolean;
+    record: ArtifactResultIngestionRecord;
+    delegation: DelegationRecord | null;
+}
+export interface ArtifactResultIngestionInspection {
+    runId: string;
+    contract: typeof ARTIFACT_RESULT_INGESTION_CONTRACT_VERSION;
+    records: ArtifactResultIngestionRecord[];
+    valid: boolean;
+    issues: ContractValidationIssue[];
+}
+export interface LifecycleDecisionRecord {
+    contract: typeof LIFECYCLE_DECISION_CONTRACT | typeof LEGACY_LIFECYCLE_DECISION_CONTRACT;
+    version?: typeof LIFECYCLE_DECISION_VERSION;
+    model_version: string;
+    input_summary: Record<string, unknown>;
+    decision: {
+        profile: LifecycleProfile | null;
+        confidence: LifecycleConfidence | null;
+        hard_gate_hits: string[];
+        required_stages: string[];
+        skipped_stages: string[];
+        human_checkpoint_required: boolean;
+    };
+    reasons: string[];
+    escalation_triggers: string[];
+    downgrade_reason: string | null;
+    audit: {
+        decided_at: string | null;
+        decided_by: 'command' | 'runtime' | 'user_override' | null;
+        policy_version: string;
+        source_artifacts: string[];
+    };
+}
+export type SignalClarity = 'high' | 'medium' | 'low';
+export type EstimatedChangeSize = 'tiny' | 'small' | 'medium' | 'large';
+export type ImpactConfidence = 'high' | 'medium' | 'low';
+export type ValidationClarity = 'clear' | 'partial' | 'unclear';
+export type OrchestrationUncertainty = 'low' | 'medium' | 'high';
+export type Reversibility = 'reversible' | 'irreversible' | 'unknown';
+export interface LifecycleDecisionSignals {
+    intent_clarity: SignalClarity;
+    acceptance_clarity: SignalClarity;
+    estimated_change_size: EstimatedChangeSize;
+    task_count_estimate: number;
+    file_count_estimate: number;
+    affected_layers: string[];
+    affected_contracts: string[];
+    dependency_fanout: 'none' | 'local' | 'multi_component' | 'unknown';
+    impact_confidence: ImpactConfidence;
+    risk_tags: string[];
+    reversibility: Reversibility;
+    validation_clarity: ValidationClarity;
+    validation_available: boolean;
+    validation_cost: 'cheap' | 'moderate' | 'expensive' | 'unknown';
+    policy_hits: string[];
+    permission_required: string[];
+    requires_agents: boolean;
+    handoff_count: number;
+    artifact_dependency: boolean;
+    runtime_recovery_need: boolean;
+    orchestration_uncertainty: OrchestrationUncertainty;
+    human_checkpoint_required: boolean;
+    approval_reason: string[];
+    source_artifacts: string[];
+    can_scout_impact: boolean;
+    architecture_decision_required: boolean;
+    external_unknown: boolean;
+}
+export interface LifecycleDecisionGateResult {
+    record: LifecycleDecisionRecord;
+    checkpointRequired: boolean;
+    boundaries: string[];
+}
+export interface ArtifactIndexEntry {
+    path: string;
+    kind: string;
+    task: string | null;
+    agent: string | null;
+    createdAt: string;
+}
+export interface RunState {
+    contract: typeof RUN_STATE_CONTRACT;
+    runtimeVersion: typeof RUNTIME_VERSION;
+    runId: string;
+    status: RunStatus;
+    phase: string | null;
+    currentTask: string | null;
+    createdAt: string;
+    updatedAt: string;
+    projectRoot: string;
+    projectConfigPath: string;
+    eventLogPath: string;
+    artifactRoot: string;
+    lifecycleDecision: LifecycleDecisionRecord | null;
+    tasks: Record<string, unknown>;
+    agents: Record<string, unknown>;
+    delegations: Record<string, DelegationRecord>;
+    artifacts: ArtifactIndexEntry[];
+    artifactIngestions: Record<string, ArtifactResultIngestionRecord>;
+    worktrees: Record<string, WorktreeLifecycleRecord>;
+    validation: {
+        status: 'not_run' | 'pass' | 'pass_with_gaps' | 'fail' | 'blocked';
+        commands: string[];
+        evidence: string[];
+    };
+    syncBack: {
+        mode: 'proposal';
+        proposalPath: string | null;
+        status: 'not_created' | 'proposed' | 'applied';
+    };
+}
+export interface RuntimeEvent {
+    contract: typeof EVENT_LOG_CONTRACT;
+    time: string;
+    event: string;
+    runId: string;
+    summary?: string;
+    data?: Record<string, unknown>;
+}
+export interface DoctorCheck {
+    level: DoctorLevel;
+    check: string;
+    message: string;
+    action?: string;
+}
+export interface DoctorReport {
+    status: DoctorLevel;
+    checks: DoctorCheck[];
+}
+export type SddTaskStatus = 'pending' | 'in_progress' | 'completed' | 'blocked' | 'deferred' | 'unknown';
+export type SddGapSeverity = 'blocking' | 'warning';
+export type SddGapType = 'Document Gap' | 'Task Gap' | 'Dependency Gap';
+export interface SddTaskSourceLocation {
+    filePath: string;
+    heading: string | null;
+    lineStart: number;
+    lineEnd: number;
+}
+export interface SddTask {
+    id: string;
+    title: string | null;
+    status: SddTaskStatus;
+    wave: number | null;
+    dependsOn: string[];
+    affectedFiles: string[];
+    validation: string[];
+    risk: string[];
+    boundary: string | null;
+    acceptance: string[];
+    implementationNotes: string | null;
+    rawMetadata: Record<string, string | string[]>;
+    source: SddTaskSourceLocation;
+}
+export interface SddTaskGap {
+    type: SddGapType;
+    severity: SddGapSeverity;
+    taskId: string | null;
+    field: string;
+    message: string;
+    recommendation: string;
+}
+export interface SddTaskModel {
+    branch: string;
+    specPath: string;
+    planPath: string;
+    tasksPath: string;
+    documents: {
+        specExists: boolean;
+        planExists: boolean;
+        tasksExists: boolean;
+    };
+    tasks: SddTask[];
+    gaps: SddTaskGap[];
+}
+export type TaskGraphEdgeType = 'depends_on' | 'file_overlap';
+export interface TaskGraphNode {
+    taskId: string;
+    title: string | null;
+    status: SddTaskStatus;
+    wave: number | null;
+    dependsOn: string[];
+    affectedFiles: string[];
+    risk: string[];
+    validation: string[];
+    source: SddTaskSourceLocation;
+}
+export interface TaskGraphEdge {
+    from: string;
+    to: string;
+    type: TaskGraphEdgeType;
+    files: string[];
+}
+export interface TaskGraphDiagnostic {
+    severity: SddGapSeverity;
+    taskId: string | null;
+    field: string;
+    message: string;
+    recommendation: string;
+}
+export interface TaskGraphPlan {
+    version: typeof TASK_GRAPH_PLANNER_CONTRACT_VERSION;
+    branch: string;
+    valid: boolean;
+    nodes: TaskGraphNode[];
+    dependencyEdges: TaskGraphEdge[];
+    fileOverlapEdges: TaskGraphEdge[];
+    diagnostics: TaskGraphDiagnostic[];
+    summary: {
+        tasks: number;
+        dependencies: number;
+        fileOverlaps: number;
+        highRiskTasks: string[];
+        validationCommands: string[];
+    };
+}
+export interface WavePlanTask {
+    taskId: string;
+    isolationMode: WorktreeIsolationMode;
+    reasons: string[];
+}
+export interface WavePlanWave {
+    index: number;
+    tasks: WavePlanTask[];
+}
+export interface WavePlanGate {
+    taskId: string;
+    gate: 'manual' | 'blocked';
+    reasons: string[];
+}
+export interface WavePlan {
+    version: typeof WAVE_PLANNER_CONTRACT_VERSION;
+    branch: string;
+    valid: boolean;
+    waves: WavePlanWave[];
+    manualGates: WavePlanGate[];
+    blockedTasks: WavePlanGate[];
+    diagnostics: TaskGraphDiagnostic[];
+    summary: {
+        tasks: number;
+        waves: number;
+        plannedTasks: number;
+        manualTasks: number;
+        blockedTasks: number;
+    };
+}
+export type BackgroundExecutorStatus = 'claimed' | 'completed' | 'failed' | 'blocked';
+export interface BackgroundExecutorRunOptions {
+    branch?: string;
+    runId?: string;
+    taskId: string;
+    agent?: string;
+    workerAdapterId?: string;
+    artifactPath?: string;
+    delegationId?: string;
+    timeoutSeconds?: number;
+}
+export interface BackgroundExecutorResult {
+    version: typeof BACKGROUND_EXECUTOR_CONTRACT_VERSION;
+    runId: string;
+    taskId: string;
+    delegationId: string | null;
+    queueItemId: string | null;
+    workerAdapterId: string;
+    status: BackgroundExecutorStatus;
+    artifactPath: string | null;
+    ingestion: ArtifactResultIngestionRecord | null;
+    issues: ContractValidationIssue[];
+    message: string;
+}
+export interface BackgroundExecutorInspection {
+    version: typeof BACKGROUND_EXECUTOR_CONTRACT_VERSION;
+    runId: string;
+    delegations: DelegationQueueItem[];
+    artifactIngestions: ArtifactResultIngestionRecord[];
+    runningDelegations: number;
+    terminalDelegations: number;
+    valid: boolean;
+    issues: ContractValidationIssue[];
+}
+export type WaveExecutorStrategy = 'fast-stop' | 'safe-continue';
+export type WaveExecutorStatus = 'claimed' | 'completed' | 'failed' | 'blocked';
+export interface WaveExecutorRunOptions {
+    branch?: string;
+    runId?: string;
+    capabilityId?: string;
+    agent?: string;
+    workerAdapterId?: string;
+    strategy?: WaveExecutorStrategy;
+    artifactPaths?: Record<string, string>;
+}
+export interface WaveExecutorTaskResult {
+    waveIndex: number;
+    taskId: string;
+    result: BackgroundExecutorResult;
+}
+export interface WaveExecutorResult {
+    version: typeof WAVE_EXECUTOR_CONTRACT_VERSION;
+    runId: string;
+    branch: string;
+    strategy: WaveExecutorStrategy;
+    status: WaveExecutorStatus;
+    plannedWaves: number;
+    executedWaves: number;
+    taskResults: WaveExecutorTaskResult[];
+    manualGates: WavePlanGate[];
+    blockedTasks: WavePlanGate[];
+    issues: ContractValidationIssue[];
+    message: string;
+}
+export interface WaveExecutorInspection {
+    version: typeof WAVE_EXECUTOR_CONTRACT_VERSION;
+    runId: string;
+    background: BackgroundExecutorInspection;
+    waveEvents: RuntimeEvent[];
+    valid: boolean;
+    issues: ContractValidationIssue[];
+}
+export type GovernancePolicyOperation = 'background_executor' | 'wave_executor' | 'sync_back_apply' | 'destructive_git' | 'external_interaction' | 'cleanup';
+export type GovernancePolicyDecisionStatus = 'allow' | 'block' | 'confirm';
+export interface GovernancePolicy {
+    version: typeof GOVERNANCE_POLICY_CONTRACT_VERSION;
+    concurrency: {
+        maxBackgroundDelegations: number;
+        maxWaveExecutors: number;
+    };
+    manualConfirmation: {
+        operations: GovernancePolicyOperation[];
+        workerAdapters: string[];
+        riskTags: string[];
+    };
+    cleanup: {
+        archiveOnly: true;
+        deleteRunHistory: false;
+    };
+    retry: {
+        reopenTerminalDelegation: false;
+        maxAttemptsPerDelegation: number;
+    };
+    stopConditions: string[];
+    audit: {
+        requiredEvents: string[];
+        requiredEvidence: string[];
+    };
+}
+export interface GovernancePolicyDecisionInput {
+    operation: GovernancePolicyOperation;
+    runId?: string;
+    taskId?: string;
+    workerAdapterId?: string;
+    riskTags?: string[];
+    approved?: boolean;
+    excludeQueueItemId?: string;
+}
+export interface GovernancePolicyDecision {
+    version: typeof GOVERNANCE_POLICY_CONTRACT_VERSION;
+    operation: GovernancePolicyOperation;
+    status: GovernancePolicyDecisionStatus;
+    allowed: boolean;
+    reasons: string[];
+    issues: ContractValidationIssue[];
+    policy: GovernancePolicy;
+}
+export interface SddResult {
+    contract: typeof SDD_RESULT_CONTRACT;
+    version: typeof SDD_RESULT_VERSION;
+    agent: string;
+    task: string;
+    status: SddResultStatus;
+    artifacts: string[];
+    rawMetadata: Record<string, string | string[]>;
+}
+export interface ContractValidationIssue {
+    field: string;
+    message: string;
+    recommendation: string;
+}
+export interface SddResultValidationReport {
+    valid: boolean;
+    result: SddResult | null;
+    issues: ContractValidationIssue[];
+}
+export interface SddResultArtifactTemplateOptions {
+    branch?: string;
+    taskId: string;
+    agent: string;
+    artifactPath: string;
+    status?: SddResultStatus;
+}
+export interface DelegationRecord {
+    contract: typeof DELEGATION_LIVENESS_CONTRACT;
+    version: typeof DELEGATION_LIVENESS_VERSION;
+    delegationId: string;
+    task: string;
+    agent: string;
+    runMode: DelegationRunMode;
+    blocking: boolean;
+    requiredForPhaseExit: boolean;
+    status: DelegationStatus;
+    startedAt: string;
+    lastHeartbeatAt: string | null;
+    timeoutSeconds: number;
+    expectedArtifact: string;
+    terminalEventRequired: boolean;
+    terminalEventAt?: string | null;
+}
+export interface DelegationValidationReport {
+    valid: boolean;
+    delegation: DelegationRecord;
+    terminal: boolean;
+    stale: boolean;
+    issues: ContractValidationIssue[];
+}
+export type SingleTaskLoopStatus = 'completed' | 'blocked' | 'failed';
+export interface SingleTaskLoopOptions {
+    branch?: string;
+    taskId: string;
+    runId?: string;
+    implementArtifact?: string;
+    reviewArtifact?: string;
+    validationArtifact?: string;
+    debugArtifact?: string;
+}
+export interface SingleTaskLoopResult {
+    runId: string;
+    taskId: string;
+    status: SingleTaskLoopStatus;
+    task: SddTask | null;
+    gaps: SddTaskGap[];
+    requiredArtifacts: string[];
+    acceptedArtifacts: string[];
+    syncBackProposalPath: string;
+    message: string;
+}
+export interface GoalVerifyOptions {
+    branch?: string;
+    taskId: string;
+    runId: string;
+    reviewArtifact?: string;
+    validationArtifact?: string;
+}
+export interface AcceptanceCoverageItem {
+    acceptance: string;
+    status: GoalVerifyStatus | 'GAP';
+    evidence: string;
+}
+export interface GoalVerifyResult {
+    runId: string;
+    taskId: string;
+    status: GoalVerifyStatus;
+    task: SddTask | null;
+    reviewArtifact: string | null;
+    validationArtifact: string | null;
+    coverageArtifactPath: string;
+    syncBackProposalPath: string;
+    acceptanceCoverage: AcceptanceCoverageItem[];
+    gaps: SddTaskGap[];
+    commands: string[];
+    message: string;
+}
+export interface RunSummary {
+    runId: string;
+    status: RunStatus;
+    phase: string | null;
+    currentTask: string | null;
+    createdAt: string;
+    updatedAt: string;
+    validationStatus: RunState['validation']['status'];
+    syncBackStatus: RunState['syncBack']['status'];
+    taskIds: string[];
+    artifactCount: number;
+}
+export interface LocalRunIndexTaskEntry {
+    taskId: string;
+    status: string | null;
+    runId: string;
+    runStatus: RunStatus;
+    updatedAt: string;
+}
+export interface LocalRunIndexArtifactEntry {
+    path: string;
+    kind: string;
+    task: string | null;
+    agent: string | null;
+    runId: string;
+    createdAt: string;
+}
+export interface LocalRunIndexWaveSummary {
+    runId: string;
+    eventCount: number;
+    lastEvent: string | null;
+}
+export interface LocalRunIndexQuery {
+    runId?: string;
+    taskId?: string;
+    status?: RunStatus;
+    artifact?: string;
+}
+export interface LocalRunIndex {
+    contract: typeof LOCAL_RUN_INDEX_CONTRACT_VERSION;
+    generatedAt: string;
+    runs: RunSummary[];
+    tasks: LocalRunIndexTaskEntry[];
+    delegations: DelegationQueueItem[];
+    artifacts: LocalRunIndexArtifactEntry[];
+    waves: LocalRunIndexWaveSummary[];
+}
+export interface LocalRunIndexInspection {
+    valid: boolean;
+    exists: boolean;
+    indexPath: string;
+    index: LocalRunIndex | null;
+    issues: ContractValidationIssue[];
+}
+export interface RunInspection {
+    summary: RunSummary;
+    state: RunState;
+    events: RuntimeEvent[];
+    eventCount: number;
+    recentEvents: RuntimeEvent[];
+    artifacts: ArtifactIndexEntry[];
+    artifactIngestions: ArtifactResultIngestionRecord[];
+    worktrees: WorktreeLifecycleRecord[];
+    validation: RunState['validation'];
+    syncBack: RunState['syncBack'];
+    tasks: Record<string, unknown>;
+}
+export interface ProjectStatus {
+    branch: string;
+    documents: SddTaskModel['documents'];
+    tasks: {
+        total: number;
+        pending: number;
+        inProgress: number;
+        completed: number;
+        blocked: number;
+        deferred: number;
+        unknown: number;
+        gaps: number;
+    };
+    latestRun: RunSummary | null;
+    recommendedNextCommand: string;
+    gaps: SddTaskGap[];
+}
+export interface SyncBackApplyPolicy {
+    mode: 'direct' | 'confirm';
+    requiresApproval: boolean;
+    reasons: string[];
+}
+export interface SyncBackInspection {
+    runId: string;
+    branch: string;
+    taskId: string | null;
+    status: 'ready' | 'blocked' | 'applied';
+    reasons: string[];
+    proposalPath: string | null;
+    proposal: string | null;
+    runTaskStatus: string | null;
+    markdownTask: SddTask | null;
+    markdownStatus: SddTaskStatus | null;
+    targetTasksPath: string;
+    artifacts: string[];
+    gaps: SddTaskGap[];
+    applyPolicy: SyncBackApplyPolicy;
+}
+export interface SyncBackApplyResult {
+    runId: string;
+    taskId: string;
+    applied: boolean;
+    tasksPath: string;
+    inspection: SyncBackInspection;
+    message: string;
+}
+export declare function getWorktreesDir(projectRoot: string): string;
+export declare function getSddDir(projectRoot: string): string;
+export declare function getProjectConfigPath(projectRoot: string): string;
+export declare function getRunsDir(projectRoot: string): string;
+export declare function getLocalRunIndexPath(projectRoot: string): string;
+export declare function getRunDir(projectRoot: string, runId: string): string;
+export declare function getArtifactsDir(projectRoot: string, runId: string): string;
+export declare function getArtifactPath(projectRoot: string, runId: string, relativeArtifactPath: string): string;
+export declare function getRunRelativeArtifactPath(artifactRootRelativePath: string): string;
+export declare function toArtifactRootRelativePath(runRelativeArtifactPath: string): string;
+export declare function writeArtifact(projectRoot: string, runId: string, artifactRootRelativePath: string, content: string): Promise<{
+    absolutePath: string;
+    runRelativePath: string;
+}>;
+export declare function readArtifact(projectRoot: string, runId: string, artifactRootRelativePath: string): Promise<string>;
+export type InitDocumentStatus = 'created' | 'unchanged' | 'overwritten' | 'skipped';
+export interface InitDocumentReport {
+    branch: string;
+    relativePath: string;
+    status: InitDocumentStatus;
+    message: string;
+}
+export interface InitDocumentsResult {
+    branch: string;
+    root: string;
+    documents: InitDocumentReport[];
+}
+export interface InitProjectResult {
+    configPath: string;
+    created: boolean;
+    documents: InitDocumentsResult;
+    aiTools: AiProjectionResult[];
+}
+export declare function initProject(projectRoot: string, options?: {
+    force?: boolean;
+    aiTool?: AiToolSelection;
+    branch?: string;
+    scaffoldDocuments?: boolean;
+}): Promise<InitProjectResult>;
+export declare function readProjectConfig(projectRoot: string): Promise<ProjectConfig>;
+export declare function createRun(projectRoot: string, options?: {
+    runId?: string;
+    lifecycleDecision?: LifecycleDecisionRecord;
+}): Promise<RunState>;
+export declare function readRunState(projectRoot: string, runId: string): Promise<RunState>;
+export declare function writeRunState(projectRoot: string, state: RunState): Promise<void>;
+export declare function appendEvent(projectRoot: string, runId: string, event: Omit<RuntimeEvent, 'contract' | 'time'>): Promise<RuntimeEvent>;
+export declare function archiveRun(projectRoot: string, runId: string, options?: {
+    reason?: string;
+}): Promise<RunState>;
+export declare function listRuns(projectRoot: string): Promise<RunSummary[]>;
+export declare function rebuildLocalRunIndex(projectRoot: string): Promise<LocalRunIndex>;
+export declare function readLocalRunIndex(projectRoot: string): Promise<LocalRunIndex>;
+export declare function queryLocalRunIndex(projectRoot: string, query?: LocalRunIndexQuery): Promise<LocalRunIndex>;
+export declare function inspectLocalRunIndex(projectRoot: string): Promise<LocalRunIndexInspection>;
+export declare function inspectRun(projectRoot: string, runId: string): Promise<RunInspection>;
+export declare function getProjectStatus(projectRoot: string, options?: {
+    branch?: string;
+}): Promise<ProjectStatus>;
+export declare function inspectSyncBack(projectRoot: string, options: {
+    runId: string;
+    branch?: string;
+    taskId?: string;
+}): Promise<SyncBackInspection>;
+export declare function applySyncBack(projectRoot: string, options: {
+    runId: string;
+    branch?: string;
+    taskId?: string;
+    approved?: boolean;
+}): Promise<SyncBackApplyResult>;
+export declare function doctor(projectRoot: string, options?: {
+    allRuns?: boolean;
+    latestOnly?: boolean;
+}): Promise<DoctorReport>;
+export declare function parseSddBranch(projectRoot: string, branch?: string): Promise<SddTaskModel>;
+export declare function parseSddTasksMarkdown(raw: string, options?: {
+    branch?: string;
+    tasksPath?: string;
+    validateDependencies?: boolean;
+}): Pick<SddTaskModel, 'tasks' | 'gaps'>;
+export declare function renderSddResultArtifactTemplate(projectRoot: string, options: SddResultArtifactTemplateOptions): Promise<string>;
+export declare function validateSddResultArtifact(projectRoot: string, runId: string, runRelativeArtifactPath: string, options?: {
+    expectedTask?: string;
+    expectedAgent?: string;
+}): Promise<SddResultValidationReport>;
+export declare function parseSddResultMarkdown(raw: string): SddResultValidationReport;
+export declare function validateSddResult(result: SddResult, options?: {
+    expectedTask?: string;
+    expectedAgent?: string;
+    runRelativeArtifactPath?: string;
+}): ContractValidationIssue[];
+export declare function createDelegationRecord(input: {
+    delegationId: string;
+    task: string;
+    agent: string;
+    expectedArtifact: string;
+    runMode?: DelegationRunMode;
+    blocking?: boolean;
+    requiredForPhaseExit?: boolean;
+    startedAt?: string;
+    timeoutSeconds?: number;
+    status?: DelegationStatus;
+}): DelegationRecord;
+export declare function isDelegationTerminal(status: DelegationStatus): boolean;
+export declare function isDelegationStale(delegation: DelegationRecord, now?: Date): boolean;
+export declare function validateDelegationRecord(projectRoot: string, runId: string, delegation: DelegationRecord, now?: Date): Promise<DelegationValidationReport>;
+export declare function ingestArtifactResult(projectRoot: string, runId: string, input: {
+    delegationId: string;
+    artifactPath: string;
+}): Promise<ArtifactResultIngestionResult>;
+export declare function inspectArtifactResultIngestions(projectRoot: string, runId: string): Promise<ArtifactResultIngestionInspection>;
+export declare function evaluateLifecycleDecisionGate(input?: Partial<LifecycleDecisionSignals>, decidedAt?: Date): LifecycleDecisionGateResult;
+export declare function recordLifecycleDecision(projectRoot: string, runId: string, record: LifecycleDecisionRecord): Promise<RunState>;
+export declare function runSingleTaskLoop(projectRoot: string, options: SingleTaskLoopOptions): Promise<SingleTaskLoopResult>;
+export declare function runGoalVerify(projectRoot: string, options: GoalVerifyOptions): Promise<GoalVerifyResult>;
+export declare function renderGoalVerifyResult(result: GoalVerifyResult): string;
+export declare function renderSingleTaskLoopResult(result: SingleTaskLoopResult): string;
+export declare function renderLifecycleDecisionGate(result: LifecycleDecisionGateResult): string;
+export declare function inspectSddTask(model: SddTaskModel, taskId: string): {
+    task: SddTask | null;
+    gaps: SddTaskGap[];
+};
+export declare function renderTaskList(model: SddTaskModel): string;
+export declare function renderTaskInspect(task: SddTask | null, gaps?: SddTaskGap[]): string;
+export declare function renderTaskGapReport(model: SddTaskModel): string;
+export declare function inspectTaskGraph(projectRoot: string, options?: {
+    branch?: string;
+}): Promise<TaskGraphPlan>;
+export declare function inspectWavePlan(projectRoot: string, options?: {
+    branch?: string;
+    capabilityId?: string;
+}): Promise<WavePlan>;
+export declare function runBackgroundExecutor(projectRoot: string, options: BackgroundExecutorRunOptions): Promise<BackgroundExecutorResult>;
+export declare function inspectBackgroundExecutor(projectRoot: string, runId: string): Promise<BackgroundExecutorInspection>;
+export declare function runWaveExecutor(projectRoot: string, options?: WaveExecutorRunOptions): Promise<WaveExecutorResult>;
+export declare function inspectWaveExecutor(projectRoot: string, runId: string): Promise<WaveExecutorInspection>;
+export declare function renderDoctorReport(report: DoctorReport): string;
+export declare function defaultProjectConfig(projectName: string): ProjectConfig;
+export declare const TOOL_CAPABILITY_REGISTRY_VERSION = "phase-3.1-tool-capability-registry-v1";
+export declare const TOOL_PLUGIN_CONTRACT_REGISTRY_VERSION = "phase-3.2-tool-plugin-loading-contract-v1";
+export declare const DELEGATION_QUEUE_CONTRACT_VERSION = "phase-3.3-delegation-queue-contract-v1";
+export declare const DELEGATION_STATE_MACHINE_VERSION = "phase-3.4-delegation-state-machine-v1";
+export declare const WORKER_ADAPTER_CONTRACT_REGISTRY_VERSION = "phase-3.5-worker-adapter-contract-v1";
+export declare const ARTIFACT_RESULT_INGESTION_REGISTRY_VERSION = "phase-3.6-artifact-result-ingestion-v1";
+export declare const WORKTREE_ISOLATION_CONTRACT_VERSION = "phase-3.7-worktree-isolation-contract-v1";
+export declare const WORKTREE_LIFECYCLE_CONTRACT_VERSION = "phase-3.8-worktree-lifecycle-v1";
+export declare function listToolCapabilities(projectRoot: string): Promise<ToolCapabilityRegistry>;
+export declare function inspectToolCapability(projectRoot: string, capabilityId: string): Promise<ToolCapability | null>;
+export declare function inspectWorktreeIsolation(projectRoot: string, options: {
+    branch?: string;
+    taskId: string;
+    capabilityId?: string;
+    peerTaskIds?: string[];
+}): Promise<WorktreeIsolationDecision>;
+export declare function createWorktreeLifecycle(projectRoot: string, runId: string, options: {
+    taskId: string;
+    baseRef?: string;
+    worktreeId?: string;
+}): Promise<WorktreeLifecycleRecord>;
+export declare function inspectWorktreeLifecycle(projectRoot: string, runId: string): Promise<WorktreeLifecycleInspection>;
+export declare function keepWorktreeLifecycle(projectRoot: string, runId: string, worktreeId: string, options?: {
+    reason?: string;
+}): Promise<WorktreeLifecycleRecord>;
+export declare function removeWorktreeLifecycle(projectRoot: string, runId: string, worktreeId: string): Promise<WorktreeLifecycleRecord>;
+export declare function listToolPluginContracts(projectRoot: string): Promise<ToolPluginContractRegistry>;
+export declare function inspectToolPluginContract(projectRoot: string, pluginId: string): Promise<ToolPluginContract | null>;
+export declare function listWorkerAdapterContracts(projectRoot: string): Promise<WorkerAdapterContractRegistry>;
+export declare function inspectWorkerAdapterContract(projectRoot: string, adapterId: string): Promise<WorkerAdapterContract | null>;
+export declare function inspectGovernancePolicy(projectRoot: string): Promise<GovernancePolicy>;
+export declare function evaluateGovernancePolicy(projectRoot: string, input: GovernancePolicyDecisionInput): Promise<GovernancePolicyDecision>;
+export declare function listDelegationQueueItems(projectRoot: string, options?: {
+    runId?: string;
+}): Promise<DelegationQueueSnapshot>;
+export declare function inspectDelegationQueueItem(projectRoot: string, queueItemId: string): Promise<DelegationQueueItem | null>;
+export declare function getDelegationStateMachine(): DelegationStateMachine;
+export declare function validateDelegationStateTransition(from: DelegationStatus, to: DelegationStatus, event?: string | null): DelegationStateTransitionValidation;
+export declare function emptyLifecycleDecisionRecord(): LifecycleDecisionRecord;
+export declare function readRunEvents(projectRoot: string, runId: string): Promise<RuntimeEvent[]>;