codeharness 0.21.0 → 0.22.0

package/dist/index.js

@@ -1941,7 +1941,7 @@ async function scaffoldDocs(opts) {
 }
 
 // src/modules/infra/init-project.ts
-var HARNESS_VERSION = true ? "0.21.0" : "0.0.0-dev";
+var HARNESS_VERSION = true ? "0.22.0" : "0.0.0-dev";
 function failResult(opts, error) {
   return {
     status: "fail",
@@ -5178,11 +5178,134 @@ import { join as join16 } from "path";
 // src/modules/observability/coverage.ts
 import { readFileSync as readFileSync18, writeFileSync as writeFileSync12, renameSync as renameSync2, existsSync as existsSync21 } from "fs";
 import { join as join17 } from "path";
+var STATE_FILE2 = "sprint-state.json";
+var DEFAULT_STATIC_TARGET = 80;
+function defaultCoverageState() {
+  return {
+    static: {
+      coveragePercent: 0,
+      lastScanTimestamp: "",
+      history: []
+    },
+    targets: {
+      staticTarget: DEFAULT_STATIC_TARGET
+    }
+  };
+}
+function readStateFile(projectDir) {
+  const fp = join17(projectDir, STATE_FILE2);
+  if (!existsSync21(fp)) {
+    return ok2({});
+  }
+  try {
+    const raw = readFileSync18(fp, "utf-8");
+    const parsed = JSON.parse(raw);
+    return ok2(parsed);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return fail2(`Failed to read ${STATE_FILE2}: ${msg}`);
+  }
+}
+function readCoverageState(projectDir) {
+  if (!projectDir || typeof projectDir !== "string") {
+    return fail2("projectDir is required and must be a non-empty string");
+  }
+  const stateResult = readStateFile(projectDir);
+  if (!stateResult.success) {
+    return fail2(stateResult.error);
+  }
+  return ok2(extractCoverageState(stateResult.data));
+}
+function extractCoverageState(state) {
+  const obs = state.observability;
+  if (!obs) {
+    return defaultCoverageState();
+  }
+  const staticSection = obs.static;
+  const targets = obs.targets;
+  const runtimeSection = obs.runtime;
+  const runtime = runtimeSection && typeof runtimeSection.coveragePercent === "number" ? {
+    coveragePercent: runtimeSection.coveragePercent,
+    lastValidationTimestamp: typeof runtimeSection.lastValidationTimestamp === "string" ? runtimeSection.lastValidationTimestamp : "",
+    modulesWithTelemetry: typeof runtimeSection.modulesWithTelemetry === "number" ? runtimeSection.modulesWithTelemetry : 0,
+    totalModules: typeof runtimeSection.totalModules === "number" ? runtimeSection.totalModules : 0,
+    telemetryDetected: typeof runtimeSection.telemetryDetected === "boolean" ? runtimeSection.telemetryDetected : false
+  } : void 0;
+  const parsedGaps = parseGapArray(staticSection?.gaps);
+  const result = {
+    static: {
+      coveragePercent: typeof staticSection?.coveragePercent === "number" ? staticSection.coveragePercent : 0,
+      lastScanTimestamp: typeof staticSection?.lastScanTimestamp === "string" ? staticSection.lastScanTimestamp : "",
+      history: Array.isArray(staticSection?.history) ? staticSection.history.filter(
+        (entry) => typeof entry === "object" && entry !== null && typeof entry.coveragePercent === "number" && typeof entry.timestamp === "string"
+      ) : [],
+      ...parsedGaps.length > 0 ? { gaps: parsedGaps } : {}
+    },
+    targets: {
+      staticTarget: typeof targets?.staticTarget === "number" ? targets.staticTarget : DEFAULT_STATIC_TARGET,
+      ...typeof targets?.runtimeTarget === "number" ? { runtimeTarget: targets.runtimeTarget } : {}
+    },
+    ...runtime ? { runtime } : {}
+  };
+  return result;
+}
+function parseGapArray(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((g) => {
+    if (typeof g !== "object" || g === null) return false;
+    const r = g;
+    return typeof r.file === "string" && typeof r.line === "number" && typeof r.type === "string" && typeof r.description === "string";
+  }).map((g) => ({
+    file: g.file,
+    line: g.line,
+    type: g.type,
+    description: g.description,
+    severity: g.severity === "error" || g.severity === "warning" ? g.severity : "info"
+  }));
+}
 
 // src/modules/observability/runtime-coverage.ts
 import { readFileSync as readFileSync19, writeFileSync as writeFileSync13, renameSync as renameSync3, existsSync as existsSync22 } from "fs";
 import { join as join18 } from "path";
 
+// src/modules/observability/coverage-gate.ts
+var DEFAULT_STATIC_TARGET2 = 80;
+var DEFAULT_RUNTIME_TARGET = 60;
+function checkObservabilityCoverageGate(projectDir, overrides) {
+  if (!projectDir || typeof projectDir !== "string") {
+    return fail2("projectDir is required and must be a non-empty string");
+  }
+  const stateResult = readCoverageState(projectDir);
+  if (!stateResult.success) {
+    return fail2(stateResult.error);
+  }
+  const state = stateResult.data;
+  const staticTarget = overrides?.staticTarget ?? state.targets.staticTarget ?? DEFAULT_STATIC_TARGET2;
+  const runtimeTarget = overrides?.runtimeTarget ?? state.targets.runtimeTarget ?? DEFAULT_RUNTIME_TARGET;
+  const staticCurrent = state.static.coveragePercent;
+  const staticMet = staticCurrent >= staticTarget;
+  const staticResult = {
+    met: staticMet,
+    current: staticCurrent,
+    target: staticTarget,
+    gap: staticMet ? 0 : staticTarget - staticCurrent
+  };
+  let runtimeResult = null;
+  if (state.runtime) {
+    const runtimeCurrent = state.runtime.coveragePercent;
+    const runtimeMet = runtimeCurrent >= runtimeTarget;
+    runtimeResult = {
+      met: runtimeMet,
+      current: runtimeCurrent,
+      target: runtimeTarget,
+      gap: runtimeMet ? 0 : runtimeTarget - runtimeCurrent
+    };
+  }
+  const passed = staticResult.met && (runtimeResult === null || runtimeResult.met);
+  const gapSummary = state.static.gaps ? [...state.static.gaps] : [];
+  return ok2({ passed, staticResult, runtimeResult, gapSummary });
+}
+
 // src/modules/verify/browser.ts
 import { execFileSync as execFileSync9 } from "child_process";
 import { existsSync as existsSync23, readFileSync as readFileSync20 } from "fs";
@@ -10693,8 +10816,106 @@ function registerProgressCommand(program) {
   });
 }
 
+// src/commands/observability-gate.ts
+function registerObservabilityGateCommand(program) {
+  program.command("observability-gate").description("Check observability coverage against targets (commit gate)").option("--json", "Machine-readable JSON output").option("--min-static <percent>", "Override static coverage target").option("--min-runtime <percent>", "Override runtime coverage target").action((opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const isJson = opts.json === true || globalOpts.json === true;
+    const root = process.cwd();
+    const overrides = {};
+    if (opts.minStatic !== void 0) {
+      const parsed = parseInt(opts.minStatic, 10);
+      if (isNaN(parsed) || parsed < 0 || parsed > 100) {
+        if (isJson) {
+          jsonOutput({ status: "error", message: "--min-static must be a number between 0 and 100" });
+        } else {
+          fail("--min-static must be a number between 0 and 100");
+        }
+        process.exitCode = 1;
+        return;
+      }
+      overrides.staticTarget = parsed;
+    }
+    if (opts.minRuntime !== void 0) {
+      const parsed = parseInt(opts.minRuntime, 10);
+      if (isNaN(parsed) || parsed < 0 || parsed > 100) {
+        if (isJson) {
+          jsonOutput({ status: "error", message: "--min-runtime must be a number between 0 and 100" });
+        } else {
+          fail("--min-runtime must be a number between 0 and 100");
+        }
+        process.exitCode = 1;
+        return;
+      }
+      overrides.runtimeTarget = parsed;
+    }
+    const result = checkObservabilityCoverageGate(root, overrides);
+    if (!result.success) {
+      if (isJson) {
+        jsonOutput({ status: "error", message: result.error });
+      } else {
+        fail(`Observability gate error: ${result.error}`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    const gate = result.data;
+    if (isJson) {
+      jsonOutput({
+        status: gate.passed ? "pass" : "fail",
+        passed: gate.passed,
+        static: {
+          current: gate.staticResult.current,
+          target: gate.staticResult.target,
+          met: gate.staticResult.met,
+          gap: gate.staticResult.gap
+        },
+        runtime: gate.runtimeResult ? {
+          current: gate.runtimeResult.current,
+          target: gate.runtimeResult.target,
+          met: gate.runtimeResult.met,
+          gap: gate.runtimeResult.gap
+        } : null,
+        gaps: gate.gapSummary.map((g) => ({
+          file: g.file,
+          line: g.line,
+          type: g.type,
+          description: g.description
+        }))
+      });
+    } else {
+      const staticLine = `Static: ${gate.staticResult.current}% / ${gate.staticResult.target}% target`;
+      if (gate.passed) {
+        ok(`Observability gate passed. ${staticLine}`);
+        if (gate.runtimeResult) {
+          ok(`Runtime: ${gate.runtimeResult.current}% / ${gate.runtimeResult.target}% target`);
+        }
+      } else {
+        fail(`Observability gate failed. ${staticLine}`);
+        if (gate.runtimeResult && !gate.runtimeResult.met) {
+          fail(`Runtime: ${gate.runtimeResult.current}% / ${gate.runtimeResult.target}% target`);
+        }
+        if (gate.gapSummary.length > 0) {
+          fail("Gaps:");
+          const shown = gate.gapSummary.slice(0, 5);
+          for (const g of shown) {
+            fail(`  ${g.file}:${g.line} \u2014 ${g.description}`);
+          }
+          if (gate.gapSummary.length > 5) {
+            fail(`  ... and ${gate.gapSummary.length - 5} more.`);
+          }
+        }
+        fail("Add logging to flagged functions. Run: codeharness observability-gate for details.");
+      }
+    }
+    if (!gate.passed) {
+      process.exitCode = 1;
+    }
+  });
+}
+
 // src/index.ts
-var VERSION = true ? "0.21.0" : "0.0.0-dev";
+var VERSION = true ? "0.22.0" : "0.0.0-dev";
 function createProgram() {
   const program = new Command();
   program.name("codeharness").description("Makes autonomous coding agents produce software that actually works").version(VERSION).option("--json", "Output in machine-readable JSON format");
@@ -10719,6 +10940,7 @@ function createProgram() {
   registerValidateStateCommand(program);
   registerValidateCommand(program);
   registerProgressCommand(program);
+  registerObservabilityGateCommand(program);
   return program;
 }
 if (!process.env["VITEST"]) {

package/dist/modules/observability/index.d.ts

@@ -96,6 +96,8 @@ interface StaticCoverageState {
     readonly lastScanTimestamp: string;
     /** Historical coverage entries */
     readonly history: readonly CoverageHistoryEntry[];
+    /** Cached observability gaps from last analysis run (persisted by saveCoverageResult) */
+    readonly gaps?: readonly ObservabilityGap[];
 }
 /** Coverage targets configuration */
 interface CoverageTargets {
@@ -153,6 +155,17 @@ interface RuntimeCoverageState {
     /** Whether telemetry was detected at all */
     readonly telemetryDetected: boolean;
 }
+/** Result of the observability coverage gate check */
+interface ObservabilityCoverageGateResult {
+    /** Whether the gate passed (all required checks met their targets) */
+    readonly passed: boolean;
+    /** Static coverage check result */
+    readonly staticResult: CoverageTargetResult;
+    /** Runtime coverage check result, or null if no runtime data exists */
+    readonly runtimeResult: CoverageTargetResult | null;
+    /** List of observability gaps for actionable feedback */
+    readonly gapSummary: ObservabilityGap[];
+}
 /** Trend comparison between latest and previous coverage entries */
 interface CoverageTrend {
     /** Latest coverage percentage */
@@ -214,38 +227,15 @@ type Result<T> = Ok<T> | Fail;
  */
 declare function analyze(projectDir: string, config?: AnalyzerConfig): Result<AnalyzerResult>;
 
-/**
- * Coverage state persistence — tracks observability coverage in sprint-state.json.
- *
- * Implements Story 1.3: read/write/trend/target comparison for static analysis coverage.
- * Only the `static` section is managed here; `runtime` is deferred to Epic 2.
- */
+/** Coverage state persistence — tracks observability coverage in sprint-state.json. */
 
-/**
- * Save coverage result from an analysis run into sprint-state.json.
- *
- * Updates `observability.static.coveragePercent`, `observability.static.lastScanTimestamp`,
- * and appends to `observability.static.history`. Preserves all other state fields.
- */
+/** Save coverage result from an analysis run into sprint-state.json. */
 declare function saveCoverageResult(projectDir: string, result: AnalyzerResult): Result<void>;
-/**
- * Read the observability coverage state from sprint-state.json.
- *
- * Returns the typed `ObservabilityCoverageState` from the `observability` key.
- * If no observability section exists, returns default state.
- */
+/** Read the observability coverage state from sprint-state.json. */
 declare function readCoverageState(projectDir: string): Result<ObservabilityCoverageState>;
-/**
- * Get coverage trend by comparing latest vs previous history entries.
- */
+/** Get coverage trend by comparing latest vs previous history entries. */
 declare function getCoverageTrend(projectDir: string): Result<CoverageTrend>;
-/**
- * Check current coverage against a target threshold.
- *
- * @param projectDir - Project root directory
- * @param target - Target percentage (default 80%)
- * @returns Structured result indicating whether coverage meets the target
- */
+/** Check current coverage against a target threshold. */
 declare function checkCoverageTarget(projectDir: string, target?: number): Result<CoverageTargetResult>;
 
 /** Per-AC observability gap presence */
@@ -292,4 +282,28 @@ declare function computeRuntimeCoverage(gapResults: ObservabilityGapResult): Run
  */
 declare function saveRuntimeCoverage(projectDir: string, result: RuntimeCoverageResult): Result<void>;
 
-export { type AnalyzerConfig, type AnalyzerResult, type AnalyzerSummary, type CoverageHistoryEntry, type CoverageTargetResult, type CoverageTargets, type CoverageTrend, type GapSeverity, type ObservabilityCoverageState, type ObservabilityGap, type RuntimeCoverageEntry, type RuntimeCoverageResult, type RuntimeCoverageState, type StaticCoverageState, analyze, checkCoverageTarget, computeRuntimeCoverage, getCoverageTrend, readCoverageState, saveCoverageResult, saveRuntimeCoverage };
+/**
+ * Observability coverage gate — checks if coverage meets targets for commit gating.
+ *
+ * Implements Story 2.2: reads cached coverage from sprint-state.json and compares
+ * against targets. Does NOT re-run Semgrep — uses cached results for performance.
+ * Static coverage is always required; runtime is only checked when data exists.
+ */
+
+/**
+ * Check observability coverage against targets for commit gating.
+ *
+ * Reads static and runtime coverage from sprint-state.json. Static coverage
+ * is always checked. Runtime coverage is only checked when runtime data exists
+ * in the state file (i.e., after at least one verification run).
+ *
+ * @param projectDir - Project root directory
+ * @param overrides - Optional target overrides
+ * @returns Gate result with pass/fail, per-dimension results, and gap summary
+ */
+declare function checkObservabilityCoverageGate(projectDir: string, overrides?: {
+    staticTarget?: number;
+    runtimeTarget?: number;
+}): Result<ObservabilityCoverageGateResult>;
+
+export { type AnalyzerConfig, type AnalyzerResult, type AnalyzerSummary, type CoverageHistoryEntry, type CoverageTargetResult, type CoverageTargets, type CoverageTrend, type GapSeverity, type ObservabilityCoverageGateResult, type ObservabilityCoverageState, type ObservabilityGap, type RuntimeCoverageEntry, type RuntimeCoverageResult, type RuntimeCoverageState, type StaticCoverageState, analyze, checkCoverageTarget, checkObservabilityCoverageGate, computeRuntimeCoverage, getCoverageTrend, readCoverageState, saveCoverageResult, saveRuntimeCoverage };

package/dist/modules/observability/index.js

@@ -195,11 +195,13 @@ function saveCoverageResult(projectDir, result) {
   const updatedStatic = {
     coveragePercent: result.summary.coveragePercent,
     lastScanTimestamp: timestamp,
-    history: trimmedHistory
+    history: trimmedHistory,
+    gaps: result.gaps.map(({ file, line, type, description, severity }) => ({ file, line, type, description, severity }))
   };
   const updatedObservability = {
     static: updatedStatic,
-    targets: existing.targets
+    targets: existing.targets,
+    ...existing.runtime ? { runtime: existing.runtime } : {}
   };
   const updatedState = {
     ...state,
@@ -275,18 +277,45 @@ function extractCoverageState(state) {
   }
   const staticSection = obs.static;
   const targets = obs.targets;
-  return {
+  const runtimeSection = obs.runtime;
+  const runtime = runtimeSection && typeof runtimeSection.coveragePercent === "number" ? {
+    coveragePercent: runtimeSection.coveragePercent,
+    lastValidationTimestamp: typeof runtimeSection.lastValidationTimestamp === "string" ? runtimeSection.lastValidationTimestamp : "",
+    modulesWithTelemetry: typeof runtimeSection.modulesWithTelemetry === "number" ? runtimeSection.modulesWithTelemetry : 0,
+    totalModules: typeof runtimeSection.totalModules === "number" ? runtimeSection.totalModules : 0,
+    telemetryDetected: typeof runtimeSection.telemetryDetected === "boolean" ? runtimeSection.telemetryDetected : false
+  } : void 0;
+  const parsedGaps = parseGapArray(staticSection?.gaps);
+  const result = {
     static: {
       coveragePercent: typeof staticSection?.coveragePercent === "number" ? staticSection.coveragePercent : 0,
       lastScanTimestamp: typeof staticSection?.lastScanTimestamp === "string" ? staticSection.lastScanTimestamp : "",
       history: Array.isArray(staticSection?.history) ? staticSection.history.filter(
         (entry) => typeof entry === "object" && entry !== null && typeof entry.coveragePercent === "number" && typeof entry.timestamp === "string"
-      ) : []
+      ) : [],
+      ...parsedGaps.length > 0 ? { gaps: parsedGaps } : {}
     },
     targets: {
-      staticTarget: typeof targets?.staticTarget === "number" ? targets.staticTarget : DEFAULT_STATIC_TARGET
-    }
+      staticTarget: typeof targets?.staticTarget === "number" ? targets.staticTarget : DEFAULT_STATIC_TARGET,
+      ...typeof targets?.runtimeTarget === "number" ? { runtimeTarget: targets.runtimeTarget } : {}
+    },
+    ...runtime ? { runtime } : {}
   };
+  return result;
+}
+function parseGapArray(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((g) => {
+    if (typeof g !== "object" || g === null) return false;
+    const r = g;
+    return typeof r.file === "string" && typeof r.line === "number" && typeof r.type === "string" && typeof r.description === "string";
+  }).map((g) => ({
+    file: g.file,
+    line: g.line,
+    type: g.type,
+    description: g.description,
+    severity: g.severity === "error" || g.severity === "warning" ? g.severity : "info"
+  }));
 }
 
 // src/modules/observability/runtime-coverage.ts
@@ -355,9 +384,48 @@ function saveRuntimeCoverage(projectDir, result) {
     return fail(`Failed to write ${STATE_FILE2}: ${msg}`);
   }
 }
+
+// src/modules/observability/coverage-gate.ts
+var DEFAULT_STATIC_TARGET2 = 80;
+var DEFAULT_RUNTIME_TARGET = 60;
+function checkObservabilityCoverageGate(projectDir, overrides) {
+  if (!projectDir || typeof projectDir !== "string") {
+    return fail("projectDir is required and must be a non-empty string");
+  }
+  const stateResult = readCoverageState(projectDir);
+  if (!stateResult.success) {
+    return fail(stateResult.error);
+  }
+  const state = stateResult.data;
+  const staticTarget = overrides?.staticTarget ?? state.targets.staticTarget ?? DEFAULT_STATIC_TARGET2;
+  const runtimeTarget = overrides?.runtimeTarget ?? state.targets.runtimeTarget ?? DEFAULT_RUNTIME_TARGET;
+  const staticCurrent = state.static.coveragePercent;
+  const staticMet = staticCurrent >= staticTarget;
+  const staticResult = {
+    met: staticMet,
+    current: staticCurrent,
+    target: staticTarget,
+    gap: staticMet ? 0 : staticTarget - staticCurrent
+  };
+  let runtimeResult = null;
+  if (state.runtime) {
+    const runtimeCurrent = state.runtime.coveragePercent;
+    const runtimeMet = runtimeCurrent >= runtimeTarget;
+    runtimeResult = {
+      met: runtimeMet,
+      current: runtimeCurrent,
+      target: runtimeTarget,
+      gap: runtimeMet ? 0 : runtimeTarget - runtimeCurrent
+    };
+  }
+  const passed = staticResult.met && (runtimeResult === null || runtimeResult.met);
+  const gapSummary = state.static.gaps ? [...state.static.gaps] : [];
+  return ok({ passed, staticResult, runtimeResult, gapSummary });
+}
 export {
   analyze,
   checkCoverageTarget,
+  checkObservabilityCoverageGate,
   computeRuntimeCoverage,
   getCoverageTrend,
   readCoverageState,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeharness",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "type": "module",
   "description": "CLI for codeharness — makes autonomous coding agents produce software that actually works",
   "bin": {

package/ralph/bridge.sh

@@ -99,9 +99,9 @@ fi
 
 # ─── Sprint Status Parsing ────────────────────────────────────────────────
 
-# Parse sprint status YAML into an associative array
+# Parse sprint status YAML into a newline-delimited key=value store
 # Maps story slug (e.g., "1-1-login-page") to status
-declare -A SPRINT_STATUSES
+SPRINT_STATUSES=""
 
 parse_sprint_status() {
     local file="$1"
@@ -133,7 +133,8 @@ parse_sprint_status() {
                 # Extract story number from slug: "1-1-login-page" -> "1.1"
                 if [[ "$key" =~ ^([0-9]+)-([0-9]+) ]]; then
                     local story_id="${BASH_REMATCH[1]}.${BASH_REMATCH[2]}"
-                    SPRINT_STATUSES["$story_id"]="$value"
+                    SPRINT_STATUSES="${SPRINT_STATUSES}${story_id}=${value}
+"
                 fi
             fi
         fi
@@ -181,8 +182,10 @@ parse_epics() {
 
         # Determine status from sprint status or default to pending
         local status="pending"
-        if [[ -n "${SPRINT_STATUSES[$current_story_id]:-}" ]]; then
-            status=$(map_status "${SPRINT_STATUSES[$current_story_id]}")
+        local _sprint_val
+        _sprint_val=$(echo "$SPRINT_STATUSES" | grep "^${current_story_id}=" | head -1 | cut -d= -f2-)
+        if [[ -n "$_sprint_val" ]]; then
+            status=$(map_status "$_sprint_val")
         fi
 
         # Clean up description

package/ralph/lib/circuit_breaker.sh

@@ -27,7 +27,7 @@ NC='\033[0m'
 
 init_circuit_breaker() {
     if [[ -f "$CB_STATE_FILE" ]]; then
-        if ! jq '.' "$CB_STATE_FILE" > /dev/null 2>&1; then
+        if ! jq -e type "$CB_STATE_FILE" > /dev/null 2>&1; then
             rm -f "$CB_STATE_FILE"
         fi
     fi