@cristochang/spec-execution 0.1.0

package/dist/runner/executor.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Executor Interface
+ *
+ * Generic executor interface for running AI agents.
+ * Ralph is just one implementation; other executors can be plugged in.
+ */
+import type { AssembledContext } from "../context.js";
+/**
+ * Result from an executor execution
+ *
+ * Plain data structure - no logic, just the raw result
+ */
+export interface ExecutorResult {
+    readonly success: boolean;
+    readonly output?: unknown;
+    readonly error?: unknown;
+    readonly tool?: string;
+    readonly filesModified?: string[];
+    readonly duration?: number;
+}
+/**
+ * Create a successful executor result
+ */
+export declare function createSuccessResult(output: unknown, tool?: string, filesModified?: string[]): ExecutorResult;
+/**
+ * Create a failed executor result
+ */
+export declare function createFailureResult(error: unknown, tool?: string): ExecutorResult;
+/**
+ * Generic executor interface
+ *
+ * Any AI agent can implement this to be used with spec-execution.
+ * The orchestrator doesn't care what's inside - only the result matters.
+ */
+export interface Executor {
+    /**
+     * Execute with the given context
+     *
+     * @param context - Assembled execution context
+     * @returns Raw execution result
+     */
+    execute(context: AssembledContext): Promise<ExecutorResult>;
+}
+/**
+ * Check if an executor is available
+ */
+export declare function isExecutorAvailable(executor: unknown): executor is Executor;
+//# sourceMappingURL=executor.d.ts.map

package/dist/runner/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/runner/executor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAMrD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,OAAO,EACf,IAAI,CAAC,EAAE,MAAM,EACb,aAAa,CAAC,EAAE,MAAM,EAAE,GACvB,cAAc,CAOhB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,IAAI,CAAC,EAAE,MAAM,GACZ,cAAc,CAMhB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;CAC5D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,IAAI,QAAQ,CAO3E"}

package/dist/runner/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Runner Module
+ *
+ * Generic executor interface + Ralph adapter + Execution session orchestrator
+ */
+export * from "./executor.js";
+export * from "./ralph.js";
+export * from "./session.js";
+export type { ExecutionSessionConfig, SessionState, SessionStatus, IterationResult, } from "./session.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/runner/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runner/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAG5B,YAAY,EACV,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,eAAe,GAChB,MAAM,cAAc,CAAA"}

package/dist/runner/ralph.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Ralph Adapter
+ *
+ * Thin adapter for Ralph Wiggum executor.
+ * No business logic - only call + translate.
+ */
+import type { Executor, ExecutorResult } from "./executor.js";
+import type { AssembledContext } from "../context.js";
+export interface RalphConfig {
+    readonly command?: string;
+    readonly args?: readonly string[];
+    readonly timeout?: number;
+    readonly cwd?: string;
+    readonly apiUrl?: string;
+}
+export declare const DEFAULT_RALPH_CONFIG: RalphConfig;
+export interface RalphInput {
+    readonly context: {
+        readonly prompt: string;
+        readonly tools: readonly string[];
+        readonly maxIterations: number;
+    };
+    readonly config: RalphConfig;
+}
+export interface RalphResult {
+    readonly success: boolean;
+    readonly output?: unknown;
+    readonly error?: unknown;
+    readonly lastTool?: string;
+    readonly filesModified?: string[];
+}
+export declare class RalphAdapter implements Executor {
+    private readonly _config;
+    constructor(config?: RalphConfig);
+    execute(context: AssembledContext): Promise<ExecutorResult>;
+    /**
+     * Call Ralph - IMPLEMENT THIS based on your Ralph setup
+     *
+     * Examples:
+     * - Spawn Ralph as child process
+     * - Call Ralph's HTTP API
+     * - Import Ralph module directly
+     */
+    private _callRalph;
+}
+export declare function createRalphAdapter(config?: RalphConfig): RalphAdapter;
+export type { Executor, ExecutorResult };
+//# sourceMappingURL=ralph.d.ts.map

package/dist/runner/ralph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ralph.d.ts","sourceRoot":"","sources":["../../src/runner/ralph.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAIrD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,eAAO,MAAM,oBAAoB,EAAE,WAIlC,CAAA;AAGD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAA;IAChH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CAClC;AAGD,qBAAa,YAAa,YAAW,QAAQ;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;gBAEzB,MAAM,GAAE,WAAkC;IAIhD,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC;IAuBjE;;;;;;;OAOG;YACW,UAAU;CAOzB;AAGD,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,YAAY,CAErE;AAGD,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAA"}

package/dist/runner/session.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Execution Session
+ *
+ * Orchestrates the execution loop:
+ * 1. Gate check
+ * 2. Context assembly
+ * 3. Executor execution
+ * 4. Result recording
+ * 5. Completion detection
+ * 6. Iteration
+ *
+ * The session owns all state; the executor is just a tool.
+ */
+import type { SpecInfo } from "../types.js";
+import { type GateResult } from "../gate.js";
+import { type ExecutionContract } from "../contract.js";
+import { ExecutionState, type CriteriaProgress } from "../state.js";
+import { FailureMemory, type FailureMemoryConfig } from "../failure.js";
+import { type AssembleOptions } from "../context.js";
+import type { CompletionRecommendation } from "../completion.js";
+import type { Executor, ExecutorResult } from "./executor.js";
+/**
+ * Execution session configuration
+ */
+export interface ExecutionSessionConfig {
+    readonly maxIterations: number;
+    readonly failureMemory: FailureMemoryConfig;
+    readonly contextAssembler?: AssembleOptions;
+    readonly executor: Executor;
+}
+/**
+ * Default session configuration
+ */
+export declare const DEFAULT_SESSION_CONFIG: ExecutionSessionConfig;
+/**
+ * Current state of an execution session
+ */
+export interface SessionState {
+    readonly iteration: number;
+    readonly status: SessionStatus;
+    readonly startedAt: number;
+    readonly lastUpdate: number;
+}
+/**
+ * Session status
+ */
+export type SessionStatus = "idle" | "running" | "paused" | "completed" | "blocked" | "failed" | "aborted";
+/**
+ * Execution Session
+ *
+ * Orchestrates the execution loop. Owns all state; coordinates:
+ * - Gate checks (before execution)
+ * - Context assembly (for executor)
+ * - Result recording (after execution)
+ * - Completion detection (for exit)
+ */
+export declare class ExecutionSession {
+    private readonly _config;
+    private readonly _spec;
+    private readonly _state;
+    private readonly _failures;
+    private readonly _contract;
+    private _sessionStatus;
+    private _iteration;
+    private _startedAt;
+    private _lastUpdate;
+    private _completionRecommendation;
+    constructor(spec: SpecInfo | null, config: ExecutionSessionConfig);
+    /**
+     * Get the current session state
+     */
+    getSessionState(): SessionState;
+    /**
+     * Get the completion recommendation (if any)
+     */
+    getCompletionRecommendation(): CompletionRecommendation | null;
+    /**
+     * Get the execution contract
+     */
+    getContract(): ExecutionContract | null;
+    /**
+     * Get the execution state
+     */
+    getExecutionState(): ExecutionState;
+    /**
+     * Get the failure memory
+     */
+    getFailureMemory(): FailureMemory;
+    /**
+     * Check if session is blocked by failures (for gate check)
+     */
+    isBlockedByFailures(): boolean;
+    /**
+     * Run one execution iteration
+     *
+     * This is the core loop method:
+     * 1. Gate check
+     * 2. Context assembly
+     * 3. Executor execution
+     * 4. Result recording
+     * 5. Completion detection
+     *
+     * @returns Result of the iteration
+     */
+    runIteration(): Promise<IterationResult>;
+    /**
+     * Run the full execution loop until completion
+     *
+     * @returns Final session state
+     */
+    run(): Promise<SessionState>;
+    /**
+     * Abort the session
+     */
+    abort(): void;
+    /**
+     * Step 1: Gate check
+     */
+    private _checkGate;
+    /**
+     * Step 2: Context assembly
+     */
+    private _assembleContext;
+    /**
+     * Step 3: Executor execution
+     */
+    private _execute;
+    /**
+     * Step 4: Record result
+     */
+    private _recordResult;
+    /**
+     * Step 5: Check completion
+     */
+    private _checkCompletion;
+    /**
+     * Build completion evidence from current state
+     */
+    private _buildEvidence;
+    /**
+     * Get criterion text by ID
+     */
+    private _getCriterionText;
+    /**
+     * Map gate reason to session status
+     */
+    private _mapGateReasonToStatus;
+}
+/**
+ * Result of a single iteration
+ */
+export interface IterationResult {
+    readonly continue: boolean;
+    readonly reason?: string;
+    readonly gateResult?: GateResult;
+    readonly executorResult?: ExecutorResult;
+    readonly progress?: CriteriaProgress;
+    readonly completion?: CompletionRecommendation;
+}
+/**
+ * Create an execution session
+ */
+export declare function createSession(spec: SpecInfo | null, config: ExecutionSessionConfig): ExecutionSession;
+//# sourceMappingURL=session.d.ts.map

package/dist/runner/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/runner/session.ts"],"names":[],"mappings":"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"}

package/dist/state.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Execution State
+ *
+ * Tracks the progress of an execution session:
+ * - Files touched
+ * - Criteria status (partial completion tracking)
+ * - Tool call history
+ */
+import type { CriterionStatus } from "./types.js";
+/**
+ * Progress summary for all criteria
+ */
+export interface CriteriaProgress {
+    readonly total: number;
+    readonly pending: number;
+    readonly inProgress: number;
+    readonly satisfied: number;
+    readonly verified: number;
+    readonly blocked: number;
+    readonly failed: number;
+    readonly percentage: number;
+}
+/**
+ * Compute progress from criteria status counts
+ */
+export declare function computeProgress(counts: Record<CriterionStatus, number>, total: number): CriteriaProgress;
+/**
+ * Summary of a tool call for tracking
+ */
+export interface ToolCallSummary {
+    readonly tool: string;
+    readonly success: boolean;
+    readonly timestamp: number;
+    readonly files?: readonly string[];
+    readonly error?: string;
+}
+/**
+ * Create a tool call summary
+ */
+export declare function createToolCallSummary(tool: string, success: boolean, files?: string[], error?: string): ToolCallSummary;
+/**
+ * Execution state tracks progress during a session
+ */
+export declare class ExecutionState {
+    private readonly _filesTouched;
+    private readonly _criteriaStatus;
+    private readonly _criteriaVerifiedAt;
+    private readonly _criteriaVerificationMethod;
+    private _lastToolCall?;
+    private _startedAt;
+    private _lastUpdated;
+    constructor();
+    /**
+     * Initialize criteria from a list of criterion IDs
+     */
+    initializeCriteria(criterionIds: readonly string[]): void;
+    /**
+     * Get the status of a criterion
+     */
+    getCriterionStatus(criterionId: string): CriterionStatus | undefined;
+    /**
+     * Set the status of a criterion
+     */
+    setCriterionStatus(criterionId: string, status: CriterionStatus, verifiedAt?: string, verificationMethod?: string): void;
+    /**
+     * Get all criteria statuses
+     */
+    getAllCriteriaStatus(): ReadonlyMap<string, CriterionStatus>;
+    /**
+     * Mark a file as touched
+     */
+    touchFile(file: string): void;
+    /**
+     * Mark multiple files as touched
+     */
+    touchFiles(files: readonly string[]): void;
+    /**
+     * Check if a file has been touched
+     */
+    hasTouchedFile(file: string): boolean;
+    /**
+     * Get all touched files
+     */
+    getTouchedFiles(): readonly string[];
+    /**
+     * Get count of touched files
+     */
+    getTouchedFileCount(): number;
+    /**
+     * Record a tool call
+     */
+    recordToolCall(summary: ToolCallSummary): void;
+    /**
+     * Get the last tool call summary
+     */
+    getLastToolCall(): ToolCallSummary | undefined;
+    /**
+     * Get progress summary for all criteria
+     */
+    getProgress(): CriteriaProgress;
+    /**
+     * Check if all criteria are verified
+     */
+    isAllVerified(): boolean;
+    /**
+     * Get criteria with a specific status
+     */
+    getCriteriaByStatus(status: CriterionStatus): string[];
+    /**
+     * Get the next pending criterion
+     */
+    getNextPendingCriterion(): string | undefined;
+    /**
+     * Get session duration in milliseconds
+     */
+    getDuration(): number;
+    /**
+     * Create a snapshot of the current state
+     */
+    snapshot(): ExecutionStateSnapshot;
+    /**
+     * Update internal timestamp
+     */
+    private _touch;
+}
+/**
+ * Immutable snapshot of execution state
+ */
+export interface ExecutionStateSnapshot {
+    readonly filesTouched: readonly string[];
+    readonly criteriaStatus: Record<string, CriterionStatus>;
+    readonly lastToolCall?: ToolCallSummary;
+    readonly startedAt: number;
+    readonly lastUpdated: number;
+    readonly duration: number;
+}
+/**
+ * Restore execution state from a snapshot
+ */
+export declare function restoreFromSnapshot(snapshot: ExecutionStateSnapshot): ExecutionState;
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @cristochang/spec-execution
+ *
+ * Core type definitions for the execution orchestration layer
+ */
+/**
+ * The status of a single success criterion during execution
+ */
+export type CriterionStatus = "pending" | "in_progress" | "satisfied" | "verified" | "blocked" | "failed";
+/**
+ * A single success criterion with execution status
+ */
+export interface SuccessCriterion {
+    id: string;
+    description: string;
+    status: CriterionStatus;
+    verifiedAt?: string;
+    verificationMethod?: string;
+}
+/**
+ * Verification mode determines how completion is verified
+ */
+export type VerificationMode = "none" | "manual" | "automated";
+/**
+ * Verification configuration
+ */
+export interface VerificationConfig {
+    mode: VerificationMode;
+}
+/**
+ * Reasons why execution is denied
+ */
+export type GateDeniedReason = "spec_not_found" | "spec_cancelled" | "spec_already_implemented" | "spec_not_approved" | "max_iterations_exceeded" | "blocked_by_failures";
+/**
+ * Gate check result
+ */
+export interface Gate {
+    readonly allowed: boolean;
+    readonly reason?: GateDeniedReason;
+}
+/**
+ * Boundary constraints for execution
+ */
+export interface Boundaries {
+    readonly objective: string;
+    readonly inclusions: readonly string[];
+    readonly exclusions: readonly string[];
+    readonly constraints: readonly string[];
+    readonly maxIterations: number;
+}
+/**
+ * Completion configuration from the contract
+ */
+export interface CompletionConfig {
+    readonly criteria: readonly SuccessCriterion[];
+    readonly verification: VerificationConfig;
+}
+/**
+ * Immutable snapshot of Spec state at contract creation
+ */
+export interface SpecSnapshot {
+    readonly id: string;
+    readonly status: string;
+    readonly created: string;
+}
+/**
+ * Empty boundaries constant
+ */
+export declare const EMPTY_BOUNDARIES: Boundaries;
+/**
+ * Empty completion config constant
+ */
+export declare const EMPTY_COMPLETION: CompletionConfig;
+/**
+ * Empty spec snapshot constant
+ */
+export declare const EMPTY_SNAPSHOT: SpecSnapshot;
+/**
+ * Execution Contract
+ *
+ * Read-only adjudication structure derived from SpecInfo.
+ * Describes "what is allowed" and "how to judge completion".
+ * Does NOT contain execution commands.
+ */
+export interface ExecutionContract {
+    /**
+     * Gate check - determines if execution is allowed
+     */
+    readonly gate: Gate;
+    /**
+     * Boundary constraints
+     */
+    readonly boundaries: Boundaries;
+    /**
+     * Completion conditions
+     */
+    readonly completion: CompletionConfig;
+    /**
+     * Spec state snapshot at contract creation
+     */
+    readonly specSnapshot: SpecSnapshot;
+}
+/**
+ * Import SpecInfo from spec-core for type references
+ * This is a re-export type to avoid requiring the full dependency
+ */
+export type SpecInfo = {
+    readonly id: string;
+    readonly created: string;
+    readonly status: string;
+    readonly objective: string;
+    readonly scope: {
+        readonly inclusions: readonly string[];
+        readonly exclusions: readonly string[];
+    };
+    readonly successCriteria: readonly string[];
+    readonly constraints?: readonly string[];
+    readonly implementationNotes?: string;
+    readonly changes?: readonly string[];
+    readonly verification?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@cristochang/spec-execution",
+  "version": "0.1.0",
+  "description": "Spec execution orchestration layer for OpenCode",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun run build:js && bun run build:dts",
+    "build:js": "bunx esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --external:@cristochang/spec-core",
+    "build:dts": "bunx tsc --emitDeclarationOnly",
+    "test": "bun test"
+  },
+  "keywords": [
+    "opencode",
+    "spec",
+    "execution",
+    "orchestration",
+    "workflow"
+  ],
+  "author": "OpenCode",
+  "license": "MIT",
+  "dependencies": {
+    "@cristochang/spec-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.13.9",
+    "esbuild": "0.27.2",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}