@cristochang/spec-execution 0.1.0

package/dist/index.js

@@ -0,0 +1,1282 @@
+// src/types.ts
+var EMPTY_BOUNDARIES = {
+  objective: "",
+  inclusions: [],
+  exclusions: [],
+  constraints: [],
+  maxIterations: 0
+};
+var EMPTY_COMPLETION = {
+  criteria: [],
+  verification: { mode: "none" }
+};
+var EMPTY_SNAPSHOT = {
+  id: "",
+  status: "",
+  created: ""
+};
+
+// src/contract.ts
+var ContractFactory;
+((ContractFactory2) => {
+  function create(spec) {
+    if (!spec) {
+      return {
+        gate: { allowed: false, reason: "spec_not_found" },
+        boundaries: EMPTY_BOUNDARIES,
+        completion: EMPTY_COMPLETION,
+        specSnapshot: EMPTY_SNAPSHOT
+      };
+    }
+    const gate = evaluateGate(spec.status);
+    const boundaries = buildBoundaries(spec);
+    const completion = buildCompletion(spec);
+    const specSnapshot = buildSnapshot(spec);
+    return {
+      gate,
+      boundaries,
+      completion,
+      specSnapshot
+    };
+  }
+  ContractFactory2.create = create;
+  function evaluateGate(status) {
+    switch (status) {
+      case "pending":
+        return { allowed: false, reason: "spec_not_approved" };
+      case "approved":
+        return { allowed: true };
+      case "implemented":
+        return { allowed: false, reason: "spec_already_implemented" };
+      case "cancelled":
+        return { allowed: false, reason: "spec_cancelled" };
+      default:
+        return { allowed: false, reason: "spec_not_approved" };
+    }
+  }
+  function buildBoundaries(spec) {
+    return {
+      objective: spec.objective,
+      inclusions: spec.scope.inclusions,
+      exclusions: spec.scope.exclusions,
+      constraints: spec.constraints ?? [],
+      maxIterations: 50
+      // Default, can be overridden by config
+    };
+  }
+  function buildCompletion(spec) {
+    const criteria = buildCriteria(spec);
+    const verification = inferVerificationMode(spec);
+    return {
+      criteria,
+      verification
+    };
+  }
+  function buildCriteria(spec) {
+    return spec.successCriteria.map((description, index) => ({
+      id: `criterion_${index}`,
+      description,
+      status: "pending"
+    }));
+  }
+  function inferVerificationMode(spec) {
+    const constraintsLower = spec.constraints?.map((c) => c.toLowerCase()) ?? [];
+    const inclusionsLower = spec.scope.inclusions.map((i) => i.toLowerCase());
+    const requiresTest = constraintsLower.some(
+      (c) => c.includes("test") || c.includes("ci") || c.includes("coverage")
+    );
+    if (requiresTest) {
+      return { mode: "automated" };
+    }
+    const isUI = inclusionsLower.some(
+      (s) => s.includes("ui") || s.includes("component") || s.includes("page") || s.includes("screen") || s.includes("view")
+    );
+    if (isUI) {
+      return { mode: "manual" };
+    }
+    return { mode: "none" };
+  }
+  function buildSnapshot(spec) {
+    return {
+      id: spec.id,
+      status: spec.status,
+      created: spec.created
+    };
+  }
+})(ContractFactory || (ContractFactory = {}));
+
+// src/gate.ts
+var ExecutionGate;
+((ExecutionGate2) => {
+  function check(spec, session) {
+    if (!spec) {
+      return { allowed: false, reason: "spec_not_found" };
+    }
+    if (spec.status === "cancelled") {
+      return { allowed: false, reason: "spec_cancelled" };
+    }
+    if (spec.status === "implemented") {
+      return { allowed: false, reason: "spec_already_implemented" };
+    }
+    if (spec.status !== "approved") {
+      return { allowed: false, reason: "spec_not_approved" };
+    }
+    if (session.iteration >= session.config.maxIterations) {
+      return { allowed: false, reason: "max_iterations_exceeded" };
+    }
+    if (session.isBlockedByFailures()) {
+      return { allowed: false, reason: "blocked_by_failures" };
+    }
+    const contract = ContractFactory.create(spec);
+    return {
+      allowed: true,
+      contract
+    };
+  }
+  ExecutionGate2.check = check;
+  function checkSpecOnly(spec) {
+    if (!spec) {
+      return { allowed: false, reason: "spec_not_found" };
+    }
+    if (spec.status === "cancelled") {
+      return { allowed: false, reason: "spec_cancelled" };
+    }
+    if (spec.status === "implemented") {
+      return { allowed: false, reason: "spec_already_implemented" };
+    }
+    if (spec.status !== "approved") {
+      return { allowed: false, reason: "spec_not_approved" };
+    }
+    return { allowed: true };
+  }
+  ExecutionGate2.checkSpecOnly = checkSpecOnly;
+  function isRetryableReason(reason) {
+    const retryable = /* @__PURE__ */ new Set([
+      "spec_not_approved",
+      "max_iterations_exceeded",
+      "blocked_by_failures"
+    ]);
+    return retryable.has(reason);
+  }
+  ExecutionGate2.isRetryableReason = isRetryableReason;
+  function isTerminalReason(reason) {
+    const terminal = /* @__PURE__ */ new Set([
+      "spec_not_found",
+      "spec_cancelled",
+      "spec_already_implemented"
+    ]);
+    return terminal.has(reason);
+  }
+  ExecutionGate2.isTerminalReason = isTerminalReason;
+})(ExecutionGate || (ExecutionGate = {}));
+
+// src/state.ts
+function computeProgress(counts, total) {
+  return {
+    total,
+    pending: counts.pending ?? 0,
+    inProgress: counts.in_progress ?? 0,
+    satisfied: counts.satisfied ?? 0,
+    verified: counts.verified ?? 0,
+    blocked: counts.blocked ?? 0,
+    failed: counts.failed ?? 0,
+    percentage: total > 0 ? (counts.verified ?? 0) / total * 100 : 0
+  };
+}
+function createToolCallSummary(tool, success, files, error) {
+  return {
+    tool,
+    success,
+    timestamp: Date.now(),
+    files: files ?? [],
+    error
+  };
+}
+var ExecutionState = class {
+  _filesTouched = /* @__PURE__ */ new Set();
+  _criteriaStatus = /* @__PURE__ */ new Map();
+  _criteriaVerifiedAt = /* @__PURE__ */ new Map();
+  _criteriaVerificationMethod = /* @__PURE__ */ new Map();
+  _lastToolCall;
+  _startedAt;
+  _lastUpdated;
+  constructor() {
+    this._startedAt = Date.now();
+    this._lastUpdated = this._startedAt;
+  }
+  /**
+   * Initialize criteria from a list of criterion IDs
+   */
+  initializeCriteria(criterionIds) {
+    for (const id of criterionIds) {
+      if (!this._criteriaStatus.has(id)) {
+        this._criteriaStatus.set(id, "pending");
+      }
+    }
+    this._touch();
+  }
+  /**
+   * Get the status of a criterion
+   */
+  getCriterionStatus(criterionId) {
+    return this._criteriaStatus.get(criterionId);
+  }
+  /**
+   * Set the status of a criterion
+   */
+  setCriterionStatus(criterionId, status, verifiedAt, verificationMethod) {
+    this._criteriaStatus.set(criterionId, status);
+    if (verifiedAt) {
+      this._criteriaVerifiedAt.set(criterionId, verifiedAt);
+    }
+    if (verificationMethod) {
+      this._criteriaVerificationMethod.set(criterionId, verificationMethod);
+    }
+    this._touch();
+  }
+  /**
+   * Get all criteria statuses
+   */
+  getAllCriteriaStatus() {
+    return this._criteriaStatus;
+  }
+  /**
+   * Mark a file as touched
+   */
+  touchFile(file) {
+    this._filesTouched.add(file);
+    this._touch();
+  }
+  /**
+   * Mark multiple files as touched
+   */
+  touchFiles(files) {
+    for (const file of files) {
+      this._filesTouched.add(file);
+    }
+    this._touch();
+  }
+  /**
+   * Check if a file has been touched
+   */
+  hasTouchedFile(file) {
+    return this._filesTouched.has(file);
+  }
+  /**
+   * Get all touched files
+   */
+  getTouchedFiles() {
+    return Array.from(this._filesTouched);
+  }
+  /**
+   * Get count of touched files
+   */
+  getTouchedFileCount() {
+    return this._filesTouched.size;
+  }
+  /**
+   * Record a tool call
+   */
+  recordToolCall(summary) {
+    this._lastToolCall = summary;
+    this._touch();
+  }
+  /**
+   * Get the last tool call summary
+   */
+  getLastToolCall() {
+    return this._lastToolCall;
+  }
+  /**
+   * Get progress summary for all criteria
+   */
+  getProgress() {
+    const counts = {
+      pending: 0,
+      in_progress: 0,
+      satisfied: 0,
+      verified: 0,
+      blocked: 0,
+      failed: 0
+    };
+    for (const status of this._criteriaStatus.values()) {
+      counts[status] = (counts[status] ?? 0) + 1;
+    }
+    return computeProgress(counts, this._criteriaStatus.size);
+  }
+  /**
+   * Check if all criteria are verified
+   */
+  isAllVerified() {
+    if (this._criteriaStatus.size === 0) return false;
+    for (const status of this._criteriaStatus.values()) {
+      if (status !== "verified") return false;
+    }
+    return true;
+  }
+  /**
+   * Get criteria with a specific status
+   */
+  getCriteriaByStatus(status) {
+    const result = [];
+    for (const [id, s] of this._criteriaStatus) {
+      if (s === status) {
+        result.push(id);
+      }
+    }
+    return result;
+  }
+  /**
+   * Get the next pending criterion
+   */
+  getNextPendingCriterion() {
+    for (const [id, status] of this._criteriaStatus) {
+      if (status === "pending") {
+        return id;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Get session duration in milliseconds
+   */
+  getDuration() {
+    return this._lastUpdated - this._startedAt;
+  }
+  /**
+   * Create a snapshot of the current state
+   */
+  snapshot() {
+    return {
+      filesTouched: Array.from(this._filesTouched),
+      criteriaStatus: Object.fromEntries(this._criteriaStatus),
+      lastToolCall: this._lastToolCall,
+      startedAt: this._startedAt,
+      lastUpdated: this._lastUpdated,
+      duration: this.getDuration()
+    };
+  }
+  /**
+   * Update internal timestamp
+   */
+  _touch() {
+    this._lastUpdated = Date.now();
+  }
+};
+function restoreFromSnapshot(snapshot) {
+  const state = new ExecutionState();
+  const accessor = state;
+  accessor._startedAt = snapshot.startedAt;
+  accessor._lastUpdated = snapshot.lastUpdated;
+  for (const file of snapshot.filesTouched) {
+    state.touchFile(file);
+  }
+  for (const [id, status] of Object.entries(snapshot.criteriaStatus)) {
+    state.setCriterionStatus(id, status);
+  }
+  if (snapshot.lastToolCall) {
+    state.recordToolCall(snapshot.lastToolCall);
+  }
+  return state;
+}
+
+// src/failure.ts
+var DEFAULT_FAILURE_CONFIG = {
+  capacity: 10,
+  retryThreshold: 3
+};
+var PatternExtractor;
+((PatternExtractor2) => {
+  function fromToolOutput(tool, output) {
+    const normalizedTool = normalizeToolName(tool);
+    const recognizedTools = ["typescript", "tsc", "test", "jest", "bun", "bash", "write", "edit"];
+    if (!recognizedTools.includes(normalizedTool)) {
+      return null;
+    }
+    if (output == null) {
+      return null;
+    }
+    if (typeof output === "string") {
+      return extractFromString(normalizedTool, output);
+    }
+    if (typeof output === "object") {
+      return extractFromObject(normalizedTool, output);
+    }
+    return null;
+  }
+  PatternExtractor2.fromToolOutput = fromToolOutput;
+  function normalizeToolName(tool) {
+    const aliases = {
+      "type_error": "typescript",
+      "test_failure": "test",
+      "runtime_error": "bash"
+    };
+    return aliases[tool] ?? tool;
+  }
+  function shouldRecord(pattern) {
+    return pattern !== null;
+  }
+  PatternExtractor2.shouldRecord = shouldRecord;
+  function extractHint(output) {
+    if (typeof output === "string" && output.length > 0) {
+      return output.slice(0, 100);
+    }
+    if (typeof output === "object" && output !== null) {
+      if ("message" in output && typeof output.message === "string") {
+        return output.message.slice(0, 100);
+      }
+      if ("error" in output && typeof output.error === "string") {
+        return output.error.slice(0, 100);
+      }
+    }
+    return void 0;
+  }
+  PatternExtractor2.extractHint = extractHint;
+  function extractFromString(tool, output) {
+    const lower = output.toLowerCase();
+    if (lower.includes("type error") || lower.includes("ts(") || lower.includes("cannot find type") || lower.includes("not assignable") || lower.includes("type '") && lower.includes("' is not assignable")) {
+      return "type_error";
+    }
+    if (lower.includes("cannot find module") || lower.includes("module not found") || lower.includes("missing import")) {
+      return "missing_import";
+    }
+    if (lower.includes("syntax error") || lower.includes("unexpected token")) {
+      return "syntax_error";
+    }
+    if (lower.includes("enoent") || lower.includes("no such file")) {
+      return "file_not_found";
+    }
+    if (tool === "test" || tool === "jest" || tool === "bun") {
+      if (lower.includes("fail") || lower.includes("error") || lower.includes("assertion")) {
+        return "test_failure";
+      }
+    }
+    return null;
+  }
+  function extractFromObject(tool, output) {
+    const o = output;
+    if ("code" in o && typeof o.code === "string") {
+      const code = o.code.toLowerCase();
+      if (code === "enoent") return "file_not_found";
+      if (code === "eacces" || code === "eperm") return "permission_denied";
+    }
+    if ("message" in o && typeof o.message === "string") {
+      return extractFromString(tool, o.message);
+    }
+    if ("error" in o) {
+      if (typeof o.error === "string") {
+        return extractFromString(tool, o.error);
+      }
+      if (typeof o.error === "object" && o.error !== null) {
+        return extractFromObject(tool, o.error);
+      }
+    }
+    if ("failed" in o && typeof o.failed === "number" && o.failed > 0) {
+      return "test_failure";
+    }
+    return null;
+  }
+})(PatternExtractor || (PatternExtractor = {}));
+var FailureMemory = class {
+  _config;
+  _entries;
+  constructor(config = DEFAULT_FAILURE_CONFIG) {
+    this._config = config;
+    this._entries = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Record a failure
+   *
+   * If the same failure (same criterion + pattern) already exists,
+   * increments the count. Otherwise, adds a new entry.
+   */
+  record(input) {
+    if (!PatternExtractor.shouldRecord(input.pattern)) {
+      return;
+    }
+    const key = this._makeKey(input);
+    const existing = this._entries.get(key);
+    if (existing) {
+      const updated = {
+        ...existing,
+        count: existing.count + 1,
+        lastSeen: Date.now()
+      };
+      this._entries.set(key, updated);
+    } else {
+      if (this._entries.size >= this._config.capacity) {
+        const lruKey = this._findLRU();
+        if (lruKey) {
+          this._entries.delete(lruKey);
+        }
+      }
+      const entry = {
+        id: `failure_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`,
+        criterionId: input.criterionId,
+        pattern: input.pattern,
+        hint: input.hint,
+        count: 1,
+        firstSeen: Date.now(),
+        lastSeen: Date.now()
+      };
+      this._entries.set(key, entry);
+    }
+  }
+  /**
+   * Check if a criterion should be skipped due to repeated failures
+   *
+   * Returns true if the same failure has occurred >= retryThreshold times.
+   */
+  shouldSkip(criterionId, pattern) {
+    const key = this._makeKey({ criterionId, pattern });
+    const entry = this._entries.get(key);
+    return entry ? entry.count >= this._config.retryThreshold : false;
+  }
+  /**
+   * Get failure count for a specific criterion + pattern
+   */
+  getFailureCount(criterionId, pattern) {
+    const key = this._makeKey({ criterionId, pattern });
+    return this._entries.get(key)?.count ?? 0;
+  }
+  /**
+   * Get all failures for a criterion
+   */
+  getFailuresForCriterion(criterionId) {
+    const result = [];
+    for (const [key, entry] of this._entries) {
+      if (key.startsWith(`${criterionId}:`)) {
+        result.push(entry);
+      }
+    }
+    return result.sort((a, b) => b.lastSeen - a.lastSeen);
+  }
+  /**
+   * Get compressed failure summary
+   */
+  summarize() {
+    const entries = Array.from(this._entries.values());
+    const patterns = [...new Set(entries.map((e) => e.pattern))];
+    return {
+      total: this._entries.size,
+      patterns,
+      recent: entries.sort((a, b) => b.lastSeen - a.lastSeen).slice(0, 3)
+    };
+  }
+  /**
+   * Clear all entries
+   */
+  clear() {
+    this._entries.clear();
+  }
+  /**
+   * Get total entry count
+   */
+  get size() {
+    return this._entries.size;
+  }
+  /**
+   * Create key for storing entries
+   */
+  _makeKey(input) {
+    return `${input.criterionId}:${input.pattern}`;
+  }
+  /**
+   * Find least recently used entry
+   */
+  _findLRU() {
+    let lruKey = null;
+    let oldestTime = Infinity;
+    for (const [key, entry] of this._entries) {
+      if (entry.lastSeen < oldestTime) {
+        oldestTime = entry.lastSeen;
+        lruKey = key;
+      }
+    }
+    return lruKey;
+  }
+};
+
+// src/context.ts
+var DEFAULT_ASSEMBLE_OPTIONS = {
+  maxFiles: 5,
+  maxFailures: 3,
+  includeCodeSnippet: false,
+  maxCodeLines: 100
+};
+function createWorkingFocus(criterionId, criterionText, targetFile, contextSnippet) {
+  return {
+    targetCriterionId: criterionId,
+    targetCriterionText: criterionText,
+    targetFile,
+    contextSnippet
+  };
+}
+var ContextAssembler;
+((ContextAssembler2) => {
+  function assemble(input, options = DEFAULT_ASSEMBLE_OPTIONS) {
+    const opts = { ...DEFAULT_ASSEMBLE_OPTIONS, ...options };
+    return {
+      immutable: assembleImmutable(input),
+      state: assembleState(input, opts),
+      failures: assembleFailures(input, opts),
+      working: assembleWorking(input)
+    };
+  }
+  ContextAssembler2.assemble = assemble;
+  function assembleImmutable(input) {
+    const { boundaries, completion } = input.contract;
+    return {
+      spec: {
+        objective: boundaries.objective,
+        scope: {
+          in: boundaries.inclusions,
+          out: boundaries.exclusions
+        },
+        criteria: completion.criteria.map((c) => ({
+          id: c.id,
+          text: c.description
+        })),
+        constraints: boundaries.constraints
+      }
+    };
+  }
+  function assembleState(input, options) {
+    const { iteration, progress, touchedFiles, criteriaStatus } = input;
+    const maxFiles = options.maxFiles ?? 5;
+    const fileList = touchedFiles.slice(0, maxFiles);
+    const moreCount = Math.max(0, touchedFiles.length - maxFiles);
+    const displayList = moreCount > 0 ? [...fileList, `... and ${moreCount} more`] : fileList;
+    const criteriaEntries = Array.from(criteriaStatus.entries()).map(([id, status]) => ({ id, status }));
+    return {
+      iteration,
+      progress: {
+        current: progress.verified,
+        total: progress.total,
+        percentage: Math.round(progress.percentage)
+      },
+      files: {
+        count: touchedFiles.length,
+        list: displayList
+      },
+      criteria: criteriaEntries
+    };
+  }
+  function assembleFailures(input, options) {
+    const { failureSummary } = input;
+    const maxFailures = options.maxFailures ?? 3;
+    const recent = failureSummary.recent.slice(0, maxFailures).map((entry) => ({
+      criterion: entry.criterionId,
+      error: entry.pattern,
+      hint: entry.hint
+    }));
+    return {
+      count: failureSummary.total,
+      patterns: failureSummary.patterns,
+      recent
+    };
+  }
+  function assembleWorking(input) {
+    const { currentFocus, lastToolCall } = input;
+    if (!currentFocus) {
+      return {
+        task: "Continue working on the next criterion",
+        criterion: "No specific criterion selected",
+        lastResult: lastToolCall?.success ? `Last tool (${lastToolCall.tool}) succeeded` : lastToolCall?.error ? `Last tool (${lastToolCall.tool}) failed: ${lastToolCall.error}` : void 0
+      };
+    }
+    return {
+      task: `Work on criterion: ${currentFocus.targetCriterionText}`,
+      criterion: currentFocus.targetCriterionText,
+      file: currentFocus.targetFile,
+      lastResult: lastToolCall?.success ? `Last tool (${lastToolCall.tool}) succeeded` : lastToolCall?.error ? `Last tool (${lastToolCall.tool}) failed: ${lastToolCall.error}` : void 0
+    };
+  }
+  function estimateTokens(context) {
+    const json = JSON.stringify(context);
+    return Math.ceil(json.length / 4);
+  }
+  ContextAssembler2.estimateTokens = estimateTokens;
+  function formatAsText(context) {
+    const lines = [];
+    lines.push("=== Immutable Truth ===");
+    lines.push(`Objective: ${context.immutable.spec.objective}`);
+    lines.push(`In scope: ${context.immutable.spec.scope.in.join(", ")}`);
+    lines.push(`Out of scope: ${context.immutable.spec.scope.out.join(", ") || "none"}`);
+    lines.push(`Criteria (${context.immutable.spec.criteria.length}):`);
+    for (const c of context.immutable.spec.criteria) {
+      lines.push(`  - ${c.id}: ${c.text}`);
+    }
+    lines.push("\n=== Execution State ===");
+    lines.push(`Iteration: ${context.state.iteration}`);
+    lines.push(`Progress: ${context.state.progress.current}/${context.state.progress.total} (${context.state.progress.percentage}%)`);
+    lines.push(`Files touched: ${context.state.files.count}`);
+    if (context.state.files.list.length > 0) {
+      lines.push(`  ${context.state.files.list.join(", ")}`);
+    }
+    if (context.failures.count > 0) {
+      lines.push("\n=== Failure Memory ===");
+      lines.push(`Total failures: ${context.failures.count}`);
+      lines.push(`Patterns: ${context.failures.patterns.join(", ")}`);
+      for (const f of context.failures.recent) {
+        lines.push(`  - ${f.criterion}: ${f.error}`);
+      }
+    }
+    lines.push("\n=== Working Context ===");
+    lines.push(`Task: ${context.working.task}`);
+    if (context.working.file) {
+      lines.push(`File: ${context.working.file}`);
+    }
+    if (context.working.lastResult) {
+      lines.push(`Last result: ${context.working.lastResult}`);
+    }
+    return lines.join("\n");
+  }
+  ContextAssembler2.formatAsText = formatAsText;
+})(ContextAssembler || (ContextAssembler = {}));
+
+// src/completion.ts
+function createEvidence(criteriaStatus, filesModified, testResults, verificationSummary) {
+  return {
+    criteriaStatus,
+    filesModified,
+    testResults,
+    verificationSummary,
+    timestamp: Date.now()
+  };
+}
+function createRecommendation(specID, ready, confidence, evidence, suggestedNextStep, reason, requiresUserConfirmation = false) {
+  return {
+    specID,
+    ready,
+    confidence,
+    evidence,
+    suggestedNextStep,
+    reason,
+    requiresUserConfirmation
+  };
+}
+function createProposal(recommendation) {
+  const type = recommendation.ready ? "completion" : recommendation.confidence === "low" ? "failed" : "partial";
+  return {
+    specID: recommendation.specID,
+    type,
+    content: {
+      evidence: recommendation.evidence,
+      summary: generateSummary(recommendation),
+      confidence: recommendation.confidence,
+      suggestedAction: recommendation.ready ? {
+        tool: "spec_update",
+        params: {
+          specID: recommendation.specID,
+          changes: recommendation.evidence.filesModified,
+          verification: recommendation.evidence.verificationSummary
+        }
+      } : void 0
+    },
+    nextStep: {
+      action: recommendation.suggestedNextStep,
+      reason: recommendation.reason,
+      requiresUserConfirmation: recommendation.requiresUserConfirmation
+    }
+  };
+}
+function generateSummary(rec) {
+  const verifiedCount = Array.from(rec.evidence.criteriaStatus.values()).filter((s) => s === "verified").length;
+  const totalCount = rec.evidence.criteriaStatus.size;
+  if (rec.ready) {
+    return `All ${totalCount} criteria verified. Ready to mark as implemented.`;
+  }
+  return `${verifiedCount}/${totalCount} criteria verified. ${rec.suggestedNextStep === "continue" ? "Continuing execution..." : rec.reason}`;
+}
+var CompletionDetector;
+((CompletionDetector2) => {
+  function evaluate(spec, progress, evidence, verificationMode) {
+    const allSatisfied = checkAllCriteriaSatisfied(progress);
+    if (!allSatisfied) {
+      return createRecommendation(
+        spec.id,
+        false,
+        "low",
+        evidence,
+        "continue",
+        `${progress.verified}/${progress.total} criteria verified. Continue execution.`,
+        false
+      );
+    }
+    switch (verificationMode) {
+      case "none":
+        return createRecommendation(
+          spec.id,
+          true,
+          "high",
+          evidence,
+          "mark_implemented",
+          "All criteria satisfied. No verification required.",
+          false
+        );
+      case "automated":
+        if (evidence.testResults?.passed) {
+          return createRecommendation(
+            spec.id,
+            true,
+            "high",
+            evidence,
+            "mark_implemented",
+            `All criteria satisfied and tests passing (${evidence.testResults.passedCount}/${evidence.testResults.total}).`,
+            false
+          );
+        } else if (evidence.testResults) {
+          return createRecommendation(
+            spec.id,
+            false,
+            "medium",
+            evidence,
+            "needs_verification",
+            `All criteria satisfied but tests failed (${evidence.testResults.failed} failures).`,
+            false
+          );
+        } else {
+          return createRecommendation(
+            spec.id,
+            false,
+            "medium",
+            evidence,
+            "needs_verification",
+            "All criteria satisfied but no test results yet.",
+            false
+          );
+        }
+      case "manual":
+        return createRecommendation(
+          spec.id,
+          true,
+          "medium",
+          evidence,
+          "needs_user_review",
+          "All criteria satisfied. Manual review required before marking as implemented.",
+          true
+          // Requires user confirmation
+        );
+      default:
+        return createRecommendation(
+          spec.id,
+          false,
+          "low",
+          evidence,
+          "continue",
+          "Unknown verification mode. Continue execution.",
+          false
+        );
+    }
+  }
+  CompletionDetector2.evaluate = evaluate;
+  function checkAllCriteriaSatisfied(progress) {
+    const completedCount = progress.satisfied + progress.verified;
+    return completedCount === progress.total && progress.failed === 0;
+  }
+  function isComplete(evidence) {
+    if (evidence.criteriaStatus.size === 0) return false;
+    for (const status of evidence.criteriaStatus.values()) {
+      if (status !== "verified") return false;
+    }
+    return true;
+  }
+  CompletionDetector2.isComplete = isComplete;
+  function canContinue(evidence) {
+    return !isComplete(evidence);
+  }
+  CompletionDetector2.canContinue = canContinue;
+})(CompletionDetector || (CompletionDetector = {}));
+
+// src/runner/executor.ts
+function createSuccessResult(output, tool, filesModified) {
+  return {
+    success: true,
+    output,
+    tool,
+    filesModified
+  };
+}
+function createFailureResult(error, tool) {
+  return {
+    success: false,
+    error,
+    tool
+  };
+}
+function isExecutorAvailable(executor) {
+  return typeof executor === "object" && executor !== null && "execute" in executor && typeof executor.execute === "function";
+}
+
+// src/runner/ralph.ts
+var DEFAULT_RALPH_CONFIG = {
+  command: "ralph",
+  args: [],
+  timeout: 12e4
+};
+var RalphAdapter = class {
+  _config;
+  constructor(config = DEFAULT_RALPH_CONFIG) {
+    this._config = { ...DEFAULT_RALPH_CONFIG, ...config };
+  }
+  async execute(context) {
+    const startTime = Date.now();
+    try {
+      const prompt = ContextAssembler.formatAsText(context);
+      void this._config;
+      const ralphResult = await this._callRalph({ prompt, tools: ["edit", "write", "bash", "test"], maxIterations: 50 });
+      const duration = Date.now() - startTime;
+      return {
+        success: ralphResult.success,
+        output: ralphResult.output,
+        error: ralphResult.error,
+        tool: ralphResult.lastTool,
+        filesModified: ralphResult.filesModified,
+        duration
+      };
+    } catch (error) {
+      return { success: false, error, duration: Date.now() - startTime };
+    }
+  }
+  /**
+   * Call Ralph - IMPLEMENT THIS based on your Ralph setup
+   *
+   * Examples:
+   * - Spawn Ralph as child process
+   * - Call Ralph's HTTP API
+   * - Import Ralph module directly
+   */
+  async _callRalph(_input) {
+    throw new Error(
+      "Ralph adapter not connected. Implement _callRalph() based on your Ralph setup.\nExamples: fetch(this._config.apiUrl, {...}), spawn(this._config.command, {...}), etc."
+    );
+  }
+};
+function createRalphAdapter(config) {
+  return new RalphAdapter(config);
+}
+
+// src/runner/session.ts
+var ExecutionSession = class {
+  _config;
+  _spec;
+  _state;
+  _failures;
+  _contract;
+  _sessionStatus = "idle";
+  _iteration = 0;
+  _startedAt = 0;
+  _lastUpdate = 0;
+  _completionRecommendation = null;
+  constructor(spec, config) {
+    this._spec = spec;
+    this._config = config;
+    this._state = new ExecutionState();
+    this._failures = new FailureMemory(config.failureMemory);
+    this._contract = spec ? ContractFactory.create(spec) : null;
+    if (this._contract?.completion.criteria) {
+      const criteriaIds = this._contract.completion.criteria.map((c) => c.id);
+      this._state.initializeCriteria(criteriaIds);
+    }
+  }
+  // ========================================================================
+  // Public API
+  // ========================================================================
+  /**
+   * Get the current session state
+   */
+  getSessionState() {
+    return {
+      iteration: this._iteration,
+      status: this._sessionStatus,
+      startedAt: this._startedAt,
+      lastUpdate: this._lastUpdate
+    };
+  }
+  /**
+   * Get the completion recommendation (if any)
+   */
+  getCompletionRecommendation() {
+    return this._completionRecommendation;
+  }
+  /**
+   * Get the execution contract
+   */
+  getContract() {
+    return this._contract;
+  }
+  /**
+   * Get the execution state
+   */
+  getExecutionState() {
+    return this._state;
+  }
+  /**
+   * Get the failure memory
+   */
+  getFailureMemory() {
+    return this._failures;
+  }
+  /**
+   * Check if session is blocked by failures (for gate check)
+   */
+  isBlockedByFailures() {
+    const criteria = this._state.getAllCriteriaStatus();
+    for (const [criterionId] of criteria.entries()) {
+      const criterionFailures = this._failures.getFailuresForCriterion(criterionId);
+      for (const failure of criterionFailures) {
+        if (failure.count >= this._config.failureMemory.retryThreshold) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+  /**
+   * 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
+   */
+  async runIteration() {
+    this._lastUpdate = Date.now();
+    if (this._iteration === 0) {
+      this._startedAt = this._lastUpdate;
+    }
+    const gateResult = this._checkGate();
+    if (!gateResult.allowed) {
+      this._sessionStatus = this._mapGateReasonToStatus(gateResult.reason);
+      return {
+        continue: false,
+        reason: gateResult.reason ?? "unknown",
+        gateResult
+      };
+    }
+    this._sessionStatus = "running";
+    const context = this._assembleContext();
+    const executorResult = await this._execute(context);
+    this._recordResult(executorResult);
+    const completion = this._checkCompletion();
+    this._iteration++;
+    if (completion.ready) {
+      this._sessionStatus = "completed";
+      this._completionRecommendation = completion;
+      return {
+        continue: false,
+        reason: "complete",
+        completion
+      };
+    }
+    return {
+      continue: true,
+      executorResult,
+      progress: this._state.getProgress()
+    };
+  }
+  /**
+   * Run the full execution loop until completion
+   *
+   * @returns Final session state
+   */
+  async run() {
+    while (true) {
+      const result = await this.runIteration();
+      if (!result.continue) {
+        break;
+      }
+      if (this._iteration >= this._config.maxIterations) {
+        this._sessionStatus = "blocked";
+        break;
+      }
+    }
+    return this.getSessionState();
+  }
+  /**
+   * Abort the session
+   */
+  abort() {
+    this._sessionStatus = "aborted";
+    this._lastUpdate = Date.now();
+  }
+  // ========================================================================
+  // Private Methods
+  // ========================================================================
+  /**
+   * Step 1: Gate check
+   */
+  _checkGate() {
+    if (!this._spec) {
+      return { allowed: false, reason: "spec_not_found" };
+    }
+    return ExecutionGate.check(this._spec, {
+      iteration: this._iteration,
+      config: { maxIterations: this._config.maxIterations },
+      isBlockedByFailures: () => this.isBlockedByFailures()
+    });
+  }
+  /**
+   * Step 2: Context assembly
+   */
+  _assembleContext() {
+    if (!this._contract) {
+      throw new Error("Cannot assemble context without contract");
+    }
+    const nextPending = this._state.getNextPendingCriterion();
+    if (nextPending) {
+      this._state.setCriterionStatus(nextPending, "in_progress");
+    }
+    const focus = nextPending ? createWorkingFocus(
+      nextPending,
+      this._getCriterionText(nextPending),
+      this._state.getLastToolCall()?.files?.[0]
+    ) : void 0;
+    return ContextAssembler.assemble(
+      {
+        contract: this._contract,
+        iteration: this._iteration,
+        progress: this._state.getProgress(),
+        touchedFiles: this._state.getTouchedFiles(),
+        criteriaStatus: this._state.getAllCriteriaStatus(),
+        failureSummary: this._failures.summarize(),
+        currentFocus: focus,
+        lastToolCall: this._state.getLastToolCall()
+      },
+      this._config.contextAssembler
+    );
+  }
+  /**
+   * Step 3: Executor execution
+   */
+  async _execute(context) {
+    return await this._config.executor.execute(context);
+  }
+  /**
+   * Step 4: Record result
+   */
+  _recordResult(result) {
+    const summary = createToolCallSummary(
+      result.tool ?? "unknown",
+      result.success,
+      result.filesModified,
+      result.error ? String(result.error) : void 0
+    );
+    this._state.recordToolCall(summary);
+    if (result.filesModified) {
+      this._state.touchFiles(result.filesModified);
+    }
+    if (!result.success) {
+      const pattern = result.tool ? PatternExtractor.fromToolOutput(result.tool, result.error) : null;
+      if (pattern && result.tool) {
+        const currentCriterion = this._state.getCriteriaByStatus("in_progress")[0] ?? this._state.getCriteriaByStatus("failed")[0] ?? "unknown";
+        this._failures.record({
+          criterionId: currentCriterion,
+          pattern,
+          hint: PatternExtractor.extractHint(result.error)
+        });
+        if (currentCriterion !== "unknown") {
+          const inProgress = this._state.getCriteriaByStatus("in_progress")[0];
+          if (inProgress) {
+            this._state.setCriterionStatus(inProgress, "pending");
+          }
+        }
+      }
+    } else {
+      const currentCriterion = this._state.getCriteriaByStatus("in_progress")[0];
+      if (currentCriterion) {
+        const verificationMode = this._contract?.completion.verification.mode ?? "none";
+        const finalStatus = verificationMode === "none" ? "verified" : "satisfied";
+        this._state.setCriterionStatus(currentCriterion, finalStatus);
+      }
+    }
+  }
+  /**
+   * Step 5: Check completion
+   */
+  _checkCompletion() {
+    if (!this._spec) {
+      return createRecommendation(
+        "",
+        false,
+        "low",
+        createEvidence(/* @__PURE__ */ new Map(), []),
+        "abort",
+        "No spec provided",
+        false
+      );
+    }
+    const evidence = this._buildEvidence();
+    const progress = this._state.getProgress();
+    const verificationMode = this._contract?.completion.verification.mode ?? "none";
+    return CompletionDetector.evaluate(this._spec, progress, evidence, verificationMode);
+  }
+  /**
+   * Build completion evidence from current state
+   */
+  _buildEvidence() {
+    return createEvidence(
+      this._state.getAllCriteriaStatus(),
+      this._state.getTouchedFiles()
+    );
+  }
+  /**
+   * Get criterion text by ID
+   */
+  _getCriterionText(criterionId) {
+    const criterion = this._contract?.completion.criteria.find((c) => c.id === criterionId);
+    return criterion?.description ?? criterionId;
+  }
+  /**
+   * Map gate reason to session status
+   */
+  _mapGateReasonToStatus(reason) {
+    switch (reason) {
+      case "spec_not_found":
+      case "spec_cancelled":
+      case "spec_already_implemented":
+        return "blocked";
+      case "max_iterations_exceeded":
+      case "blocked_by_failures":
+        return "failed";
+      default:
+        return "blocked";
+    }
+  }
+};
+function createSession(spec, config) {
+  return new ExecutionSession(spec, config);
+}
+export {
+  CompletionDetector,
+  ContextAssembler,
+  ContractFactory,
+  DEFAULT_ASSEMBLE_OPTIONS,
+  DEFAULT_FAILURE_CONFIG,
+  EMPTY_BOUNDARIES,
+  EMPTY_COMPLETION,
+  EMPTY_SNAPSHOT,
+  ExecutionGate,
+  ExecutionSession,
+  ExecutionState,
+  FailureMemory,
+  PatternExtractor,
+  RalphAdapter,
+  computeProgress,
+  createEvidence,
+  createFailureResult,
+  createProposal,
+  createRalphAdapter,
+  createRecommendation,
+  createSession,
+  createSuccessResult,
+  createToolCallSummary,
+  createWorkingFocus,
+  isExecutorAvailable,
+  restoreFromSnapshot
+};