codeharness 0.25.0 → 0.25.2

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

@@ -52,6 +52,8 @@ interface AnalyzerConfig {
     readonly tool?: string;
     /** Directory containing analysis rules, relative to project root. Default: 'patches/observability/' */
     readonly rulesDir?: string;
+    /** Additional rule directories to include in the scan, relative to project root. Default: ['patches/error-handling/'] */
+    readonly additionalRulesDirs?: readonly string[];
     /** Timeout for the analysis subprocess in milliseconds. Default: 60000 */
     readonly timeout?: number;
     /**

package/dist/modules/observability/index.js

@@ -15,6 +15,7 @@ function fail(error, context) {
 
 // src/modules/observability/analyzer.ts
 var DEFAULT_RULES_DIR = "patches/observability/";
+var ADDITIONAL_RULES_DIRS = ["patches/error-handling/"];
 var DEFAULT_TIMEOUT = 6e4;
 var FUNCTION_NO_LOG_RULE = "function-no-debug-log";
 var CATCH_WITHOUT_LOGGING_RULE = "catch-without-logging";
@@ -48,7 +49,8 @@ function analyze(projectDir, config) {
   const rulesDir = config?.rulesDir ?? DEFAULT_RULES_DIR;
   const timeout = config?.timeout ?? DEFAULT_TIMEOUT;
   const fullRulesDir = join(projectDir, rulesDir);
-  const rawResult = runSemgrep(projectDir, fullRulesDir, timeout);
+  const additionalDirs = (config?.additionalRulesDirs ?? ADDITIONAL_RULES_DIRS).map((d) => join(projectDir, d));
+  const rawResult = runSemgrep(projectDir, fullRulesDir, timeout, additionalDirs);
   if (!rawResult.success) {
     return fail(rawResult.error);
   }
@@ -73,11 +75,15 @@ function checkSemgrepInstalled() {
     return false;
   }
 }
-function runSemgrep(projectDir, rulesDir, timeout = DEFAULT_TIMEOUT) {
+function runSemgrep(projectDir, rulesDir, timeout = DEFAULT_TIMEOUT, additionalRulesDirs = []) {
   try {
+    const configArgs = ["--config", rulesDir];
+    for (const dir of additionalRulesDirs) {
+      configArgs.push("--config", dir);
+    }
     const stdout = execFileSync(
       "semgrep",
-      ["scan", "--config", rulesDir, "--json", projectDir],
+      ["scan", ...configArgs, "--json", projectDir],
       { encoding: "utf-8", timeout, stdio: ["pipe", "pipe", "pipe"] }
     );
     const parsed = JSON.parse(stdout);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeharness",
-  "version": "0.25.0",
+  "version": "0.25.2",
   "type": "module",
   "description": "CLI for codeharness — makes autonomous coding agents produce software that actually works",
   "bin": {
@@ -13,6 +13,11 @@
     "templates/Dockerfile.verify",
     "templates/Dockerfile.verify.rust",
     "templates/Dockerfile.verify.generic",
+    "templates/dockerfiles/",
+    "templates/compose/",
+    "templates/prompts/",
+    "templates/docs/",
+    "templates/otlp/",
     "ralph/**/*.sh",
     "ralph/AGENTS.md"
   ],
@@ -28,7 +33,9 @@
     "build": "tsup",
     "test": "bats tests/",
     "test:unit": "vitest run",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/",
+    "lint:sizes": "bash scripts/check-file-sizes.sh"
   },
   "dependencies": {
     "@inkjs/ui": "^2.0.0",
@@ -38,6 +45,7 @@
     "yaml": "^2.8.2"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@opentelemetry/auto-instrumentations-node": "^0.71.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.213.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.213.0",
@@ -45,9 +53,11 @@
     "@types/node": "^25.5.0",
     "@types/react": "^19.2.14",
     "@vitest/coverage-v8": "^4.1.0",
+    "eslint": "^10.1.0",
     "ink-testing-library": "^4.0.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
+    "typescript-eslint": "^8.57.2",
     "vitest": "^4.1.0"
   }
 }

package/patches/dev/enforcement.md

@@ -18,7 +18,7 @@ Before writing code, read the relevant `AGENTS.md` file for the module being cha
 
 ### Observability
 
-Run `semgrep scan --config patches/observability/` before committing and fix any gaps.
+Run `semgrep scan --config patches/observability/ --config patches/error-handling/` before committing and fix any gaps.
 
 After running tests, verify telemetry is flowing:
 - Query VictoriaLogs to confirm log events from test runs

package/patches/error-handling/AGENTS.md

@@ -0,0 +1,29 @@
+# patches/error-handling/ — Semgrep Rules for Error Handling Enforcement
+
+Standalone Semgrep YAML rules for detecting dangerous error-swallowing patterns. Each `.yaml` file is a complete Semgrep config — no build step, no TypeScript. Deleting a rule file removes that check.
+
+## Rules
+
+### Python
+
+| File | Purpose | Severity |
+|------|---------|----------|
+| no-bare-except.yaml | Detects `except Exception: pass` and `except Exception: ...` (bare error swallowing) | ERROR |
+
+## Test Fixtures
+
+### Python
+
+| File | Purpose |
+|------|---------|
+| __tests__/no-bare-except.py | Test cases for no-bare-except rules (annotated with `# ruleid:` / `# ok:`) |
+
+## Testing
+
+Run `semgrep --test patches/error-handling/` to execute all test fixtures against their rules.
+
+## Integration
+
+The review enforcement patch (`patches/review/enforcement.md`) and dev enforcement patch (`patches/dev/enforcement.md`) instruct agents to run Semgrep with `--config patches/error-handling/` in addition to `--config patches/observability/`.
+
+The `hooks/post-write-check.sh` hook provides fast grep-based detection of `except Exception: pass` in Python files for immediate feedback during development.

package/patches/error-handling/__tests__/no-bare-except.py

@@ -0,0 +1,38 @@
+# Test cases for no-bare-except-pass and no-bare-except-ellipsis Semgrep rules
+
+# ruleid: no-bare-except-pass
+try:
+    do_something()
+except Exception:
+    pass
+
+# ruleid: no-bare-except-ellipsis
+try:
+    do_something()
+except Exception:
+    ...
+
+# ok: no-bare-except-pass
+try:
+    do_something()
+except Exception as e:
+    logger.error("Failed: %s", e)
+
+# ok: no-bare-except-pass
+try:
+    do_something()
+except Exception as e:
+    print(f"Error: {e}")
+    raise
+
+# ok: no-bare-except-pass
+try:
+    do_something()
+except ValueError:
+    pass
+
+# ok: no-bare-except-ellipsis
+try:
+    do_something()
+except Exception as e:
+    logging.warning("Ignored: %s", e)

package/patches/error-handling/no-bare-except.yaml

@@ -0,0 +1,22 @@
+rules:
+  - id: no-bare-except-pass
+    pattern: |
+      try:
+        ...
+      except Exception:
+        pass
+    message: "Bare `except Exception: pass` swallows errors silently. Handle the error, log it, or add a # IGNORE: comment explaining why."
+    severity: ERROR
+    languages: [python]
+    metadata:
+      category: error-handling
+      confidence: HIGH
+
+  - id: no-bare-except-ellipsis
+    pattern-regex: 'except\s+Exception\s*:\s*\n\s+\.\.\.\s*$'
+    message: "Bare `except Exception: ...` swallows errors silently. Handle the error, log it, or add a # IGNORE: comment explaining why."
+    severity: ERROR
+    languages: [python]
+    metadata:
+      category: error-handling
+      confidence: HIGH

package/patches/review/enforcement.md

@@ -27,7 +27,7 @@ The proof must pass black-box enforcement:
 
 ### Observability
 
-Run `semgrep scan --config patches/observability/ --json` against changed files and report gaps.
+Run `semgrep scan --config patches/observability/ --config patches/error-handling/ --json` against changed files and report gaps.
 
 - For each gap found, list it as a review issue: file path, line number, and description (e.g., "src/lib/docker.ts:42 — catch block without logging")
 - Semgrep JSON output fields to extract: `check_id`, `path`, `start.line`, `extra.message`

package/ralph/ralph.sh

@@ -192,6 +192,10 @@ update_status() {
         flagged_json=$(jq -R -s 'split("\n") | map(select(length > 0))' < "$FLAGGED_STORIES_FILE")
     fi
 
+    # Get current story key for status tracking
+    local current_story
+    current_story=$(get_current_task)
+
     jq -n \
         --arg timestamp "$(get_iso_timestamp)" \
         --argjson loop_count "$loop_count" \
@@ -202,6 +206,7 @@ update_status() {
         --arg status "$status" \
         --arg exit_reason "$exit_reason" \
         --arg version "$VERSION" \
+        --arg story "${current_story:-}" \
         --argjson stories_total "$stories_total" \
         --argjson stories_completed "$stories_completed" \
         --argjson stories_remaining "$stories_remaining" \
@@ -216,6 +221,7 @@ update_status() {
             max_iterations: $max_iterations,
             last_action: $last_action,
             status: $status,
+            story: $story,
             exit_reason: $exit_reason,
             stories_total: $stories_total,
             stories_completed: $stories_completed,
@@ -228,8 +234,36 @@ update_status() {
 # codeharness: Task picking is handled by /harness-run skill inside each Claude session.
 # Ralph just spawns sessions and checks sprint-status.yaml for completion.
 get_current_task() {
-    # No-op — task picking is done by the /harness-run skill, not Ralph.
-    echo ""
+    # Read the first in-progress or ready-for-dev story from sprint-state.json.
+    # Task picking is done by /harness-run, but Ralph needs the story key
+    # for timeout reports and status tracking.
+    local state_file="sprint-state.json"
+    if [[ ! -f "$state_file" ]]; then
+        echo ""
+        return 0
+    fi
+
+    # First try to find an in-progress story
+    local story_key
+    story_key=$(jq -r '
+      .stories // {} | to_entries[]
+      | select(.value.status == "in-progress")
+      | .key
+    ' "$state_file" 2>/dev/null | head -1)
+
+    if [[ -n "$story_key" ]]; then
+        echo "$story_key"
+        return 0
+    fi
+
+    # Fall back to the first ready-for-dev story
+    story_key=$(jq -r '
+      .stories // {} | to_entries[]
+      | select(.value.status == "ready-for-dev")
+      | .key
+    ' "$state_file" 2>/dev/null | head -1)
+
+    echo "${story_key:-}"
     return 0
 }
 
@@ -243,6 +277,16 @@ check_sprint_complete() {
 
     local total=0
     local done_count=0
+    local flagged_count=0
+
+    # Load flagged stories for comparison
+    local -A flagged_map
+    if [[ -f "$FLAGGED_STORIES_FILE" ]]; then
+        while IFS= read -r flagged_key; do
+            flagged_key=$(echo "$flagged_key" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+            [[ -n "$flagged_key" ]] && flagged_map["$flagged_key"]=1
+        done < "$FLAGGED_STORIES_FILE"
+    fi
 
     while IFS=: read -r key value; do
         # Trim whitespace
@@ -257,6 +301,10 @@ check_sprint_complete() {
             total=$((total + 1))
             if [[ "$value" == "done" ]]; then
                 done_count=$((done_count + 1))
+            elif [[ -n "${flagged_map[$key]+x}" ]]; then
+                # Retry-exhausted/flagged stories count as "effectively done"
+                # — no autonomous work can be done on them
+                flagged_count=$((flagged_count + 1))
             fi
         fi
     done < "$SPRINT_STATUS_FILE"
@@ -265,7 +313,8 @@ check_sprint_complete() {
         return 1
     fi
 
-    [[ $done_count -eq $total ]]
+    # Sprint is complete if all stories are either done or flagged (no autonomous work left)
+    [[ $((done_count + flagged_count)) -eq $total ]]
 }
 
 # codeharness: Replaces all_tasks_complete() with sprint-status.yaml check.
@@ -781,6 +830,13 @@ execute_iteration() {
             fi
         fi
 
+        # If harness-run reported NO_WORK, don't count file changes as progress.
+        # Writing session-issues.md with "NO_WORK" creates git diffs but is NOT real progress.
+        if grep -qE 'Result: NO_WORK|no actionable stories remain' "$output_file" 2>/dev/null; then
+            files_changed=0
+            log_status "INFO" "NO_WORK detected — overriding files_changed to 0 for circuit breaker"
+        fi
+
         local has_errors="false"
         # Only check non-JSON lines for errors. Stream-json output is NDJSON
         # (one JSON object per line), so any line starting with '{' is Claude

package/templates/compose/collector-only.yml

@@ -0,0 +1,18 @@
+# Generated by codeharness — do not edit manually
+name: codeharness-collector
+
+services:
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:0.96.0
+    labels:
+      com.codeharness.stack: collector
+    ports:
+      - "4317:4317"
+      - "4318:4318"
+    volumes:
+      - ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml:ro
+    restart: unless-stopped
+
+networks:
+  default:
+    name: codeharness-collector-net

package/templates/compose/otel-collector-base.yaml

@@ -0,0 +1,55 @@
+# Generated by codeharness — do not edit manually
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  resource/default:
+    attributes:
+      - key: service.name
+        value: "unknown"
+        action: insert
+
+exporters:
+  otlphttp/logs:
+    endpoint: http://victoria-logs:9428/insert/opentelemetry
+    tls:
+      insecure: true
+
+  prometheusremotewrite:
+    endpoint: http://victoria-metrics:8428/api/v1/write
+    tls:
+      insecure: true
+
+  otlphttp/traces:
+    endpoint: http://victoria-traces:4318
+    tls:
+      insecure: true
+
+service:
+  pipelines:
+    logs:
+      receivers:
+        - otlp
+      processors:
+        - resource/default
+      exporters:
+        - otlphttp/logs
+    metrics:
+      receivers:
+        - otlp
+      processors:
+        - resource/default
+      exporters:
+        - prometheusremotewrite
+    traces:
+      receivers:
+        - otlp
+      processors:
+        - resource/default
+      exporters:
+        - otlphttp/traces

package/templates/compose/otel-collector-remote.yaml

@@ -0,0 +1,55 @@
+# Generated by codeharness — do not edit manually
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  resource/default:
+    attributes:
+      - key: service.name
+        value: "unknown"
+        action: insert
+
+exporters:
+  otlphttp/logs:
+    endpoint: {{LOGS_URL}}/insert/opentelemetry
+    tls:
+      insecure: true
+
+  prometheusremotewrite:
+    endpoint: {{METRICS_URL}}/api/v1/write
+    tls:
+      insecure: true
+
+  otlphttp/traces:
+    endpoint: {{TRACES_URL}}
+    tls:
+      insecure: true
+
+service:
+  pipelines:
+    logs:
+      receivers:
+        - otlp
+      processors:
+        - resource/default
+      exporters:
+        - otlphttp/logs
+    metrics:
+      receivers:
+        - otlp
+      processors:
+        - resource/default
+      exporters:
+        - prometheusremotewrite
+    traces:
+      receivers:
+        - otlp
+      processors:
+        - resource/default
+      exporters:
+        - otlphttp/traces

package/templates/compose/victoria.yml

@@ -0,0 +1,57 @@
+# Generated by codeharness — do not edit manually
+name: codeharness-shared
+
+services:
+  victoria-logs:
+    image: victoriametrics/victoria-logs:v1.15.0-victorialogs
+    labels:
+      com.codeharness.stack: shared
+    ports:
+      - "9428:9428"
+    volumes:
+      - victoria-logs-data:/vlogs
+    restart: unless-stopped
+
+  victoria-metrics:
+    image: victoriametrics/victoria-metrics:v1.106.1
+    labels:
+      com.codeharness.stack: shared
+    ports:
+      - "8428:8428"
+    volumes:
+      - victoria-metrics-data:/victoria-metrics-data
+    restart: unless-stopped
+
+  victoria-traces:
+    image: jaegertracing/all-in-one:1.56
+    labels:
+      com.codeharness.stack: shared
+    ports:
+      - "14268:14268"
+      - "16686:16686"
+    environment:
+      - COLLECTOR_OTLP_ENABLED=true
+    restart: unless-stopped
+
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:0.96.0
+    labels:
+      com.codeharness.stack: shared
+    ports:
+      - "4317:4317"
+      - "4318:4318"
+    volumes:
+      - ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml:ro
+    depends_on:
+      - victoria-logs
+      - victoria-metrics
+      - victoria-traces
+    restart: unless-stopped
+
+volumes:
+  victoria-logs-data:
+  victoria-metrics-data:
+
+networks:
+  default:
+    name: codeharness-shared-net

package/templates/dockerfiles/Dockerfile.generic

@@ -0,0 +1,13 @@
+# Base image — pinned version for reproducibility
+FROM node:22-slim
+
+# System utilities for verification
+RUN apt-get update && apt-get install -y --no-install-recommends bash curl jq git && rm -rf /var/lib/apt/lists/*
+
+# Install project binary (update this for your project)
+RUN npm install -g placeholder && npm cache clean --force
+
+# Run as non-root user
+USER node
+
+WORKDIR /workspace

package/templates/dockerfiles/Dockerfile.multi-stage.tmpl

@@ -0,0 +1,15 @@
+# NOTE: Customize COPY paths for your monorepo layout. Each build stage should only copy its own sources.
+{{BUILD_STAGES}}
+# === Runtime stage ===
+FROM debian:bookworm-slim
+
+# System utilities for verification
+RUN apt-get update && apt-get install -y --no-install-recommends curl jq && rm -rf /var/lib/apt/lists/*
+
+# Install artifacts from build stages
+{{COPY_DIRECTIVES}}
+
+# Run as non-root user
+USER nobody
+
+WORKDIR /workspace

package/templates/dockerfiles/Dockerfile.nodejs

@@ -0,0 +1,16 @@
+# Base image — pinned version for reproducibility
+FROM node:22-slim
+
+ARG TARBALL=package.tgz
+
+# System utilities for verification
+RUN apt-get update && apt-get install -y --no-install-recommends curl jq && rm -rf /var/lib/apt/lists/*
+
+# Install project from tarball (black-box: no source code)
+COPY ${TARBALL} /tmp/${TARBALL}
+RUN npm install -g /tmp/${TARBALL} && rm /tmp/${TARBALL}
+
+# Run as non-root user
+USER node
+
+WORKDIR /workspace

package/templates/dockerfiles/Dockerfile.python

@@ -0,0 +1,14 @@
+# Base image — pinned version for reproducibility
+FROM python:3.12-slim
+
+# System utilities for verification
+RUN apt-get update && apt-get install -y --no-install-recommends curl jq && rm -rf /var/lib/apt/lists/*
+
+# Install project from wheel or sdist
+COPY dist/ /tmp/dist/
+RUN pip install /tmp/dist/*.whl && rm -rf /tmp/dist/ && pip cache purge
+
+# Run as non-root user
+USER nobody
+
+WORKDIR /workspace

package/templates/dockerfiles/Dockerfile.rust

@@ -0,0 +1,24 @@
+# === Builder stage ===
+FROM rust:1.82-slim AS builder
+
+WORKDIR /build
+
+# Copy project files
+COPY . .
+
+# Build release binary
+RUN cargo build --release
+
+# === Runtime stage ===
+FROM debian:bookworm-slim
+
+# System utilities for verification
+RUN apt-get update && apt-get install -y --no-install-recommends curl jq && rm -rf /var/lib/apt/lists/*
+
+# Install compiled binary from builder (update 'myapp' to your binary name)
+COPY --from=builder /build/target/release/myapp /usr/local/bin/myapp
+
+# Run as non-root user
+USER nobody
+
+WORKDIR /workspace

package/templates/docs/readme.md.tmpl

@@ -0,0 +1,36 @@
+# {{PROJECT_NAME}}
+
+## Quick Start
+
+```bash
+# Install
+{{INSTALL_COMMAND}}
+
+# Initialize the project
+codeharness init
+
+# Check project status
+codeharness status
+```
+
+## Installation
+
+```bash
+{{INSTALL_COMMAND}}
+```
+
+## Usage
+
+After installation, initialize {{PROJECT_NAME}} in your project directory:
+
+```bash
+codeharness init
+```
+
+This sets up the harness with stack detection, observability, and documentation scaffolding.
+
+## CLI Reference
+
+```
+{{CLI_HELP_OUTPUT}}
+```