@cristochang/spec-execution 0.1.0

package/dist/completion.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Completion Detector and Recommendation
+ *
+ * Evaluates whether a Spec is complete and generates recommendations.
+ * Does NOT directly modify Spec status - only suggests next actions.
+ */
+import type { CriterionStatus, SpecInfo } from "./types.js";
+import type { CriteriaProgress } from "./state.js";
+/**
+ * Test evidence for automated verification
+ */
+export interface TestEvidence {
+    readonly passed: boolean;
+    readonly total: number;
+    readonly passedCount: number;
+    readonly failed: number;
+    readonly summary?: string;
+}
+/**
+ * Completion evidence
+ */
+export interface CompletionEvidence {
+    readonly criteriaStatus: ReadonlyMap<string, CriterionStatus>;
+    readonly filesModified: readonly string[];
+    readonly testResults?: TestEvidence;
+    readonly verificationSummary?: string;
+    readonly timestamp: number;
+}
+/**
+ * Create completion evidence
+ */
+export declare function createEvidence(criteriaStatus: ReadonlyMap<string, CriterionStatus>, filesModified: readonly string[], testResults?: TestEvidence, verificationSummary?: string): CompletionEvidence;
+/**
+ * Suggested next step after completion evaluation
+ */
+export type NextStep = "mark_implemented" | "needs_verification" | "needs_user_review" | "continue" | "abort";
+/**
+ * Confidence level for recommendations
+ */
+export type Confidence = "low" | "medium" | "high";
+/**
+ * Completion recommendation
+ *
+ * Generated by spec-execution, consumed by user/orchestrator.
+ * The execution layer does NOT directly call spec_mark_implemented.
+ */
+export interface CompletionRecommendation {
+    readonly specID: string;
+    readonly ready: boolean;
+    readonly confidence: Confidence;
+    readonly evidence: CompletionEvidence;
+    readonly suggestedNextStep: NextStep;
+    readonly reason: string;
+    readonly requiresUserConfirmation: boolean;
+}
+/**
+ * Create a completion recommendation
+ */
+export declare function createRecommendation(specID: string, ready: boolean, confidence: Confidence, evidence: CompletionEvidence, suggestedNextStep: NextStep, reason: string, requiresUserConfirmation?: boolean): CompletionRecommendation;
+/**
+ * Completion proposal
+ *
+ * Sent to user/upper layer for action.
+ * Contains all information needed to make a decision.
+ */
+export interface CompletionProposal {
+    readonly specID: string;
+    readonly type: "completion" | "partial" | "failed";
+    readonly content: ProposalContent;
+    readonly nextStep: ProposalAction;
+}
+/**
+ * Content of the proposal
+ */
+export interface ProposalContent {
+    readonly evidence: CompletionEvidence;
+    readonly summary: string;
+    readonly confidence: Confidence;
+    readonly suggestedAction?: SuggestedAction;
+}
+/**
+ * Suggested action to take
+ */
+export interface SuggestedAction {
+    readonly tool: string;
+    readonly params: Record<string, unknown>;
+}
+/**
+ * Next step action
+ */
+export interface ProposalAction {
+    readonly action: NextStep;
+    readonly reason: string;
+    readonly requiresUserConfirmation: boolean;
+}
+/**
+ * Create a completion proposal from a recommendation
+ */
+export declare function createProposal(recommendation: CompletionRecommendation): CompletionProposal;
+/**
+ * Completion Detector
+ *
+ * Evaluates Spec completion and generates recommendations.
+ * Pure function - does not modify any state.
+ */
+export declare namespace CompletionDetector {
+    /**
+     * Evaluate completion status
+     *
+     * @param spec - The spec to evaluate
+     * @param progress - Current progress
+     * @param evidence - Completion evidence
+     * @param verificationMode - Verification mode from contract
+     * @returns Completion recommendation
+     */
+    function evaluate(spec: SpecInfo, progress: CriteriaProgress, evidence: CompletionEvidence, verificationMode: "none" | "manual" | "automated"): CompletionRecommendation;
+    /**
+     * Quick check: is the spec complete based on evidence only?
+     *
+     * Does not consider verification mode - just checks if all criteria are verified.
+     */
+    function isComplete(evidence: CompletionEvidence): boolean;
+    /**
+     * Quick check: can execution continue based on evidence?
+     */
+    function canContinue(evidence: CompletionEvidence): boolean;
+}
+//# sourceMappingURL=completion.d.ts.map

package/dist/completion.d.ts.map

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

package/dist/context.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Context Assembler
+ *
+ * Generates minimal, controlled, reproducible context for each execution round.
+ *
+ * Layers:
+ * 1. Immutable Truth - never changes between rounds
+ * 2. Execution State - monotonically grows
+ * 3. Failure Memory - capacity-limited
+ * 4. Working Context - replaced each round
+ */
+import type { CriterionStatus } from "./types.js";
+import type { CriteriaProgress, ToolCallSummary } from "./state.js";
+import type { FailureSummary } from "./failure.js";
+/**
+ * Immutable context - Layer 1
+ * Never changes between rounds
+ */
+export interface ImmutableContext {
+    readonly spec: {
+        readonly objective: string;
+        readonly scope: {
+            readonly in: readonly string[];
+            readonly out: readonly string[];
+        };
+        readonly criteria: readonly CriterionDescriptor[];
+        readonly constraints: readonly string[];
+    };
+}
+/**
+ * Criterion descriptor for immutable context
+ */
+export interface CriterionDescriptor {
+    readonly id: string;
+    readonly text: string;
+}
+/**
+ * State context - Layer 2
+ * Monotonically grows, compressed
+ */
+export interface StateContext {
+    readonly iteration: number;
+    readonly progress: {
+        readonly current: number;
+        readonly total: number;
+        readonly percentage: number;
+    };
+    readonly files: {
+        readonly count: number;
+        readonly list: readonly string[];
+    };
+    readonly criteria: readonly CriterionStatusEntry[];
+}
+/**
+ * Criterion status entry
+ */
+export interface CriterionStatusEntry {
+    readonly id: string;
+    readonly status: CriterionStatus;
+}
+/**
+ * Failure context - Layer 3
+ * Capacity-limited, compressed
+ */
+export interface FailureContext {
+    readonly count: number;
+    readonly patterns: readonly string[];
+    readonly recent: readonly FailureHint[];
+}
+/**
+ * Failure hint for context
+ */
+export interface FailureHint {
+    readonly criterion: string;
+    readonly error: string;
+    readonly hint?: string;
+}
+/**
+ * Working context - Layer 4
+ * Replaced each round
+ */
+export interface WorkingContext {
+    readonly task: string;
+    readonly criterion: string;
+    readonly file?: string;
+    readonly lastResult?: string;
+}
+/**
+ * Assembled context for Ralph
+ */
+export interface AssembledContext {
+    readonly immutable: ImmutableContext;
+    readonly state: StateContext;
+    readonly failures: FailureContext;
+    readonly working: WorkingContext;
+}
+/**
+ * Metadata about the assembled context
+ */
+export interface ContextMetadata {
+    readonly tokenEstimate: number;
+    readonly compressionRatio: number;
+    readonly layers: readonly string[];
+}
+/**
+ * Options for context assembly
+ */
+export interface AssembleOptions {
+    readonly maxFiles?: number;
+    readonly maxFailures?: number;
+    readonly includeCodeSnippet?: boolean;
+    readonly maxCodeLines?: number;
+}
+/**
+ * Default options
+ */
+export declare const DEFAULT_ASSEMBLE_OPTIONS: AssembleOptions;
+/**
+ * Current focus for execution
+ */
+export interface WorkingFocus {
+    readonly targetCriterionId: string;
+    readonly targetCriterionText: string;
+    readonly targetFile?: string;
+    readonly contextSnippet?: string;
+}
+/**
+ * Create a working focus
+ */
+export declare function createWorkingFocus(criterionId: string, criterionText: string, targetFile?: string, contextSnippet?: string): WorkingFocus;
+/**
+ * Context Assembler input
+ *
+ * Combines all necessary information for context generation
+ */
+export interface ContextInput {
+    readonly contract: {
+        readonly boundaries: {
+            readonly objective: string;
+            readonly inclusions: readonly string[];
+            readonly exclusions: readonly string[];
+            readonly constraints: readonly string[];
+        };
+        readonly completion: {
+            readonly criteria: readonly {
+                id: string;
+                description: string;
+                status: CriterionStatus;
+            }[];
+        };
+    };
+    readonly iteration: number;
+    readonly progress: CriteriaProgress;
+    readonly touchedFiles: readonly string[];
+    readonly criteriaStatus: ReadonlyMap<string, CriterionStatus>;
+    readonly failureSummary: FailureSummary;
+    readonly currentFocus?: WorkingFocus;
+    readonly lastToolCall?: ToolCallSummary;
+}
+/**
+ * Context Assembler
+ *
+ * Pure function: ContextInput → AssembledContext
+ */
+export declare namespace ContextAssembler {
+    /**
+     * Assemble context for the next execution round
+     *
+     * @param input - Context input data
+     * @param options - Assembly options
+     * @returns Assembled context for Ralph
+     */
+    function assemble(input: ContextInput, options?: AssembleOptions): AssembledContext;
+    /**
+     * Estimate token count for assembled context
+     */
+    function estimateTokens(context: AssembledContext): number;
+    /**
+     * Format context as human-readable text
+     */
+    function formatAsText(context: AssembledContext): string;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

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

package/dist/contract.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Execution Contract Factory
+ *
+ * Creates ExecutionContract from SpecInfo.
+ * All rules come from spec-core, no additional logic introduced.
+ */
+import type { ExecutionContract, Gate, Boundaries, CompletionConfig, VerificationConfig, SuccessCriterion, SpecSnapshot, SpecInfo, CriterionStatus, GateDeniedReason } from "./types.js";
+/**
+ * Contract Factory
+ *
+ * Pure function: SpecInfo → ExecutionContract
+ */
+export declare namespace ContractFactory {
+    /**
+     * Create an ExecutionContract from a Spec
+     *
+     * @param spec - The spec to create contract from, or null if spec not found
+     * @returns ExecutionContract with gate check and execution boundaries
+     */
+    function create(spec: SpecInfo | null): ExecutionContract;
+}
+export type { ExecutionContract, Gate, Boundaries, CompletionConfig, VerificationConfig, SuccessCriterion, SpecSnapshot, SpecInfo, CriterionStatus, GateDeniedReason, };
+export { EMPTY_BOUNDARIES, EMPTY_COMPLETION, EMPTY_SNAPSHOT } from "./types.js";
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,IAAI,EACJ,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACZ,QAAQ,EACR,eAAe,EACf,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAOnB;;;;GAIG;AACH,yBAAiB,eAAe,CAAC;IAC/B;;;;;OAKG;IACH,SAAgB,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,iBAAiB,CAsB/D;CA8GF;AAGD,YAAY,EACV,iBAAiB,EACjB,IAAI,EACJ,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACZ,QAAQ,EACR,eAAe,EACf,gBAAgB,GACjB,CAAA;AAGD,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACf,MAAM,YAAY,CAAA"}

package/dist/failure.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Failure Memory
+ *
+ * Records and tracks failed execution patterns.
+ * Prevents repeated mistakes by recognizing failure patterns.
+ */
+/**
+ * Structured failure patterns
+ *
+ * These are machine-classifiable error types.
+ * "other" is intentionally excluded - unknown failures should not be recorded.
+ */
+export type FailurePattern = "type_error" | "missing_import" | "dependency_missing" | "test_failure" | "runtime_error" | "permission_denied" | "file_not_found" | "syntax_error";
+/**
+ * Failure memory configuration
+ */
+export interface FailureMemoryConfig {
+    readonly capacity: number;
+    readonly retryThreshold: number;
+}
+/**
+ * Default configuration
+ */
+export declare const DEFAULT_FAILURE_CONFIG: FailureMemoryConfig;
+/**
+ * A single failure record
+ */
+export interface FailureEntry {
+    readonly id: string;
+    readonly criterionId: string;
+    readonly pattern: FailurePattern;
+    readonly hint?: string;
+    readonly count: number;
+    readonly firstSeen: number;
+    readonly lastSeen: number;
+}
+/**
+ * Input for recording a failure
+ */
+export interface FailureInput {
+    readonly criterionId: string;
+    readonly pattern: FailurePattern;
+    readonly hint?: string;
+}
+/**
+ * Failure summary for context
+ */
+export interface FailureSummary {
+    readonly total: number;
+    readonly patterns: readonly string[];
+    readonly recent: readonly FailureEntry[];
+}
+/**
+ * Pattern Extractor
+ *
+ * Extracts structured failure patterns from tool outputs.
+ *
+ * IMPORTANT: Returns null for unclassifiable failures.
+ * Null results should NOT be recorded in FailureMemory
+ * to prevent noise pollution.
+ */
+export declare namespace PatternExtractor {
+    /**
+     * Extract failure pattern from tool output
+     *
+     * @param tool - Tool name that was executed
+     * @param output - Tool output (any type)
+     * @returns FailurePattern if recognized, null otherwise
+     */
+    function fromToolOutput(tool: string, output: unknown): FailurePattern | null;
+    /**
+     * Check if a pattern should be recorded
+     *
+     * Null patterns should not be recorded.
+     */
+    function shouldRecord(pattern: FailurePattern | null): boolean;
+    /**
+     * Extract hint from output for debugging
+     */
+    function extractHint(output: unknown): string | undefined;
+}
+/**
+ * Failure Memory class
+ *
+ * Records failures with LRU eviction when capacity is reached.
+ * Checks retry threshold to prevent repeated mistakes.
+ */
+export declare class FailureMemory {
+    private readonly _config;
+    private readonly _entries;
+    constructor(config?: FailureMemoryConfig);
+    /**
+     * Record a failure
+     *
+     * If the same failure (same criterion + pattern) already exists,
+     * increments the count. Otherwise, adds a new entry.
+     */
+    record(input: FailureInput): void;
+    /**
+     * Check if a criterion should be skipped due to repeated failures
+     *
+     * Returns true if the same failure has occurred >= retryThreshold times.
+     */
+    shouldSkip(criterionId: string, pattern: FailurePattern): boolean;
+    /**
+     * Get failure count for a specific criterion + pattern
+     */
+    getFailureCount(criterionId: string, pattern: FailurePattern): number;
+    /**
+     * Get all failures for a criterion
+     */
+    getFailuresForCriterion(criterionId: string): FailureEntry[];
+    /**
+     * Get compressed failure summary
+     */
+    summarize(): FailureSummary;
+    /**
+     * Clear all entries
+     */
+    clear(): void;
+    /**
+     * Get total entry count
+     */
+    get size(): number;
+    /**
+     * Create key for storing entries
+     */
+    private _makeKey;
+    /**
+     * Find least recently used entry
+     */
+    private _findLRU;
+}
+//# sourceMappingURL=failure.d.ts.map

package/dist/failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure.d.ts","sourceRoot":"","sources":["../src/failure.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GACtB,YAAY,GACZ,gBAAgB,GAChB,oBAAoB,GACpB,cAAc,GACd,eAAe,GACf,mBAAmB,GACnB,gBAAgB,GAChB,cAAc,CAAA;AAElB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAChC;AAED;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,mBAGpC,CAAA;AAMD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;CACzC;AAMD;;;;;;;;GAQG;AACH,yBAAiB,gBAAgB,CAAC;IAChC;;;;;;OAMG;IACH,SAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CA0BnF;IAkBD;;;;OAIG;IACH,SAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,OAAO,CAEpE;IAED;;OAEG;IACH,SAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAc/D;CA+EF;AAMD;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;gBAExC,MAAM,GAAE,mBAA4C;IAKhE;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAwCjC;;;;OAIG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO;IAMjE;;OAEG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM;IAKrE;;OAEG;IACH,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,EAAE;IAU5D;;OAEG;IACH,SAAS,IAAI,cAAc;IAa3B;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,OAAO,CAAC,QAAQ;IAIhB;;OAEG;IACH,OAAO,CAAC,QAAQ;CAajB"}

package/dist/gate.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Execution Gate
+ *
+ * Determines if execution is allowed based on:
+ * 1. Spec existence
+ * 2. Spec status (cancelled, implemented, approved)
+ * 3. Iteration limits
+ * 4. Failure blocking
+ *
+ * Check order is critical for correct behavior.
+ */
+import type { SpecInfo } from "./types.js";
+/**
+ * Gate check result
+ *
+ * If allowed is true, contract contains the execution contract.
+ * If allowed is false, reason contains the denial reason.
+ */
+export interface GateResult {
+    readonly allowed: boolean;
+    readonly reason?: GateDeniedReason;
+    readonly contract?: import("./contract.js").ExecutionContract;
+}
+/**
+ * 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";
+/**
+ * Execution session state interface (partial)
+ * Used for gate checks without requiring full import
+ */
+export interface ExecutionSessionState {
+    readonly iteration: number;
+    readonly config: {
+        readonly maxIterations: number;
+    };
+    /**
+     * Check if session is blocked by failures
+     */
+    isBlockedByFailures(): boolean;
+}
+/**
+ * Execution Gate
+ *
+ * Performs pre-execution checks in the correct order:
+ * 1. Spec not found
+ * 2. Spec cancelled
+ * 3. Spec already implemented
+ * 4. Spec not approved
+ * 5. Max iterations exceeded
+ * 6. Blocked by failures
+ */
+export declare namespace ExecutionGate {
+    /**
+     * Check if execution is allowed
+     *
+     * @param spec - The spec to check, or null if not found
+     * @param session - Current execution session state
+     * @returns Gate check result
+     */
+    function check(spec: SpecInfo | null, session: ExecutionSessionState): GateResult;
+    /**
+     * Quick check without session state
+     *
+     * Only checks spec-related conditions (1-4),
+     * not iteration or failure blocking.
+     *
+     * @param spec - The spec to check, or null if not found
+     * @returns Gate check result
+     */
+    function checkSpecOnly(spec: SpecInfo | null): Omit<GateResult, "contract">;
+    /**
+     * Check if a specific reason allows retry
+     *
+     * Some denial reasons are permanent (cancelled, implemented),
+     * others are temporary (not_approved, iterations_exceeded).
+     */
+    function isRetryableReason(reason: GateDeniedReason): boolean;
+    /**
+     * Check if a specific reason is permanent (terminal)
+     */
+    function isTerminalReason(reason: GateDeniedReason): boolean;
+}
+//# sourceMappingURL=gate.d.ts.map

package/dist/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAG1C;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAA;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,eAAe,EAAE,iBAAiB,CAAA;CAC9D;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,gBAAgB,GAChB,gBAAgB,GAChB,0BAA0B,GAC1B,mBAAmB,GACnB,yBAAyB,GACzB,qBAAqB,CAAA;AAEzB;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;KAC/B,CAAA;IACD;;OAEG;IACH,mBAAmB,IAAI,OAAO,CAAA;CAC/B;AAED;;;;;;;;;;GAUG;AACH,yBAAiB,aAAa,CAAC;IAC7B;;;;;;OAMG;IACH,SAAgB,KAAK,CACnB,IAAI,EAAE,QAAQ,GAAG,IAAI,EACrB,OAAO,EAAE,qBAAqB,GAC7B,UAAU,CAqCZ;IAED;;;;;;;;OAQG;IACH,SAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAuBjF;IAED;;;;;OAKG;IACH,SAAgB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAOnE;IAED;;OAEG;IACH,SAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAOlE;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @cristochang/spec-execution
+ *
+ * Spec execution orchestration layer for OpenCode
+ *
+ * This package provides the execution and orchestration layer for Spec workflows.
+ * It bridges the gap between Spec governance (spec-core) and execution runners (Ralph).
+ *
+ * @packageDocumentation
+ */
+export type { SpecInfo, ExecutionContract, Gate, Boundaries, CompletionConfig, VerificationConfig, SuccessCriterion, SpecSnapshot, CriterionStatus, GateDeniedReason, } from "./types.js";
+export { EMPTY_BOUNDARIES, EMPTY_COMPLETION, EMPTY_SNAPSHOT, } from "./contract.js";
+export { ContractFactory } from "./contract.js";
+export { ExecutionGate } from "./gate.js";
+export type { GateResult, ExecutionSessionState, } from "./gate.js";
+export { ExecutionState, computeProgress, createToolCallSummary, restoreFromSnapshot, } from "./state.js";
+export type { CriteriaProgress, ToolCallSummary, ExecutionStateSnapshot, } from "./state.js";
+export { FailureMemory, PatternExtractor, DEFAULT_FAILURE_CONFIG, } from "./failure.js";
+export type { FailurePattern, FailureMemoryConfig, FailureEntry, FailureInput, FailureSummary, } from "./failure.js";
+export { ContextAssembler, DEFAULT_ASSEMBLE_OPTIONS, createWorkingFocus, } from "./context.js";
+export type { ImmutableContext, StateContext, FailureContext, WorkingContext, AssembledContext, ContextMetadata, AssembleOptions, WorkingFocus, CriterionDescriptor, CriterionStatusEntry, FailureHint, } from "./context.js";
+export { CompletionDetector, createEvidence, createRecommendation, createProposal, } from "./completion.js";
+export type { TestEvidence, CompletionEvidence, NextStep, Confidence, CompletionRecommendation, CompletionProposal, ProposalContent, SuggestedAction, ProposalAction, } from "./completion.js";
+export { createSuccessResult, createFailureResult, isExecutorAvailable, createRalphAdapter, createSession, RalphAdapter, ExecutionSession, } from "./runner/index.js";
+export type { Executor, ExecutorResult, RalphConfig, RalphInput, RalphResult, ExecutionSessionConfig, SessionState, SessionStatus, IterationResult, } from "./runner/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,YAAY,EACV,QAAQ,EACR,iBAAiB,EACjB,IAAI,EACJ,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,gBAAgB,GACjB,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,GACf,MAAM,eAAe,CAAA;AAGtB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAG/C,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,YAAY,EACV,UAAU,EACV,qBAAqB,GACtB,MAAM,WAAW,CAAA;AAGlB,OAAO,EACL,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,sBAAsB,GACvB,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,cAAc,GACf,MAAM,cAAc,CAAA;AAGrB,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,GACZ,MAAM,cAAc,CAAA;AAGrB,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,cAAc,GACf,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACV,YAAY,EACZ,kBAAkB,EAClB,QAAQ,EACR,UAAU,EACV,wBAAwB,EACxB,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,iBAAiB,CAAA;AAGxB,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,gBAAgB,GACjB,MAAM,mBAAmB,CAAA;AAC1B,YAAY,EACV,QAAQ,EACR,cAAc,EACd,WAAW,EACX,UAAU,EACV,WAAW,EACX,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,eAAe,GAChB,MAAM,mBAAmB,CAAA"}