codeharness 0.19.5 → 0.21.0

package/patches/AGENTS.md

@@ -17,7 +17,25 @@ patches/
   retro/enforcement.md      — Retrospective quality metrics
 ```
 
-Subdirectories map to BMAD workflow roles.
+Subdirectories map to BMAD workflow roles (or analysis categories like `observability/`).
+
+## Observability Module (`observability/`)
+
+Semgrep YAML rules for static analysis of observability gaps. Each `.yaml` file is a standalone Semgrep config — no build step required. Deleting a rule file removes that check.
+
+**Rules:**
+- `catch-without-logging.yaml` — Detects catch blocks without error/warn logging (WARNING)
+- `function-no-debug-log.yaml` — Detects functions without debug/info logging (INFO)
+- `error-path-no-log.yaml` — Detects error paths (throw/return err) without preceding log (WARNING)
+
+**Test fixtures** (`.ts` files alongside rules, annotated with `// ruleid:` / `// ok:` comments):
+- `catch-without-logging.ts` — Test cases for catch-without-logging rule
+- `function-no-debug-log.ts` — Test cases for function-no-debug-log rule
+- `error-path-no-log.ts` — Test cases for error-path-no-log rule
+
+**Testing:** `semgrep --test patches/observability/` runs annotated test fixtures.
+
+**Customization:** Edit YAML rules to add custom logger patterns (e.g., `logger.error(...)` for winston). Rules use `pattern-not` / `pattern-not-inside` to detect absence of logging.
 
 ## How Patches Work
 

package/patches/observability/AGENTS.md

@@ -0,0 +1,27 @@
+# patches/observability/ — Semgrep Rules for Observability Gap Detection
+
+Standalone Semgrep YAML rules for static analysis of observability gaps. Each `.yaml` file is a complete Semgrep config — no build step, no TypeScript. Deleting a rule file removes that check.
+
+## Rules
+
+| File | Purpose | Severity |
+|------|---------|----------|
+| catch-without-logging.yaml | Detects catch blocks without error/warn logging | WARNING |
+| function-no-debug-log.yaml | Detects functions without debug/info logging | INFO |
+| error-path-no-log.yaml | Detects error paths (throw/return err) without preceding log | WARNING |
+
+## Test Fixtures
+
+| File | Purpose |
+|------|---------|
+| catch-without-logging.ts | Test cases for catch-without-logging rule (annotated with `// ruleid:` / `// ok:`) |
+| function-no-debug-log.ts | Test cases for function-no-debug-log rule |
+| error-path-no-log.ts | Test cases for error-path-no-log rule |
+
+## Testing
+
+Run `semgrep --test patches/observability/` to execute all test fixtures against their rules.
+
+## Customization
+
+Edit YAML rules to add custom logger patterns (e.g., `logger.error(...)` for winston). Rules use `pattern-not` / `pattern-not-inside` to detect absence of logging.

package/patches/observability/__tests__/catch-without-logging.ts

@@ -0,0 +1,36 @@
+// Test cases for catch-without-logging Semgrep rule
+
+// ruleid: catch-without-logging
+try { doSomething(); } catch (e) { /* no logging at all */ }
+
+// ruleid: catch-without-logging
+try {
+  riskyOperation();
+} catch (err) {
+  cleanup();
+}
+
+// ok: catch-without-logging
+try { doSomething(); } catch (e) { console.error('failed', e); }
+
+// ok: catch-without-logging
+try {
+  riskyOperation();
+} catch (err) {
+  console.warn('operation failed', err);
+  cleanup();
+}
+
+// ok: catch-without-logging
+try {
+  riskyOperation();
+} catch (err) {
+  logger.error('operation failed', err);
+}
+
+// ok: catch-without-logging
+try {
+  riskyOperation();
+} catch (err) {
+  logger.warn('operation failed', err);
+}

package/patches/observability/__tests__/error-path-no-log.ts

@@ -0,0 +1,47 @@
+// Test cases for error-path-no-log Semgrep rule
+
+function badThrow() {
+  // ruleid: error-path-no-log
+  throw new Error('something went wrong');
+}
+
+function badReturn() {
+  // ruleid: error-path-no-log
+  return err('something went wrong');
+}
+
+function goodThrow() {
+  // ok: error-path-no-log
+  console.error('about to throw');
+  throw new Error('something went wrong');
+}
+
+function goodReturn() {
+  // ok: error-path-no-log
+  console.error('returning error');
+  return err('something went wrong');
+}
+
+function goodThrowWithLogger() {
+  // ok: error-path-no-log
+  logger.error('about to throw');
+  throw new Error('something went wrong');
+}
+
+function goodReturnWithLogger() {
+  // ok: error-path-no-log
+  logger.error('returning error');
+  return err('something went wrong');
+}
+
+function goodThrowWithWarn() {
+  // ok: error-path-no-log
+  console.warn('about to throw');
+  throw new Error('something went wrong');
+}
+
+function goodReturnWithLoggerWarn() {
+  // ok: error-path-no-log
+  logger.warn('returning error');
+  return err('something went wrong');
+}

package/patches/observability/__tests__/function-no-debug-log.ts

@@ -0,0 +1,54 @@
+// Test cases for function-no-debug-log Semgrep rule
+
+// ruleid: function-no-debug-log
+function processData(input: string) {
+  return input.trim();
+}
+
+// ruleid: function-no-debug-log
+function handleRequest(req: any) {
+  const result = compute(req);
+  return result;
+}
+
+// ruleid: function-no-debug-log
+const transformData = (input: string) => {
+  return input.toUpperCase();
+};
+
+// ok: function-no-debug-log
+function processDataWithLog(input: string) {
+  console.log('processing data', input);
+  return input.trim();
+}
+
+// ok: function-no-debug-log
+function handleRequestWithDebug(req: any) {
+  console.debug('handling request', req);
+  const result = compute(req);
+  return result;
+}
+
+// ok: function-no-debug-log
+function serviceCall(params: any) {
+  logger.debug('service call', params);
+  return fetch(params.url);
+}
+
+// ok: function-no-debug-log
+function anotherService(params: any) {
+  logger.info('another service call', params);
+  return fetch(params.url);
+}
+
+// ok: function-no-debug-log
+const transformWithLog = (input: string) => {
+  console.log('transforming', input);
+  return input.toUpperCase();
+};
+
+// ok: function-no-debug-log
+const arrowWithDebug = (input: string) => {
+  logger.debug('arrow function', input);
+  return input.toLowerCase();
+};

package/patches/observability/catch-without-logging.ts

@@ -0,0 +1,36 @@
+// Test cases for catch-without-logging Semgrep rule
+
+// ruleid: catch-without-logging
+try { doSomething(); } catch (e) { /* no logging at all */ }
+
+// ruleid: catch-without-logging
+try {
+  riskyOperation();
+} catch (err) {
+  cleanup();
+}
+
+// ok: catch-without-logging
+try { doSomething(); } catch (e) { console.error('failed', e); }
+
+// ok: catch-without-logging
+try {
+  riskyOperation();
+} catch (err) {
+  console.warn('operation failed', err);
+  cleanup();
+}
+
+// ok: catch-without-logging
+try {
+  riskyOperation();
+} catch (err) {
+  logger.error('operation failed', err);
+}
+
+// ok: catch-without-logging
+try {
+  riskyOperation();
+} catch (err) {
+  logger.warn('operation failed', err);
+}

package/patches/observability/catch-without-logging.yaml

@@ -0,0 +1,35 @@
+rules:
+  - id: catch-without-logging
+    patterns:
+      - pattern: |
+          try { ... } catch ($ERR) { ... }
+      - pattern-not: |
+          try { ... } catch ($ERR) {
+            ...
+            console.error(...)
+            ...
+          }
+      - pattern-not: |
+          try { ... } catch ($ERR) {
+            ...
+            console.warn(...)
+            ...
+          }
+      - pattern-not: |
+          try { ... } catch ($ERR) {
+            ...
+            logger.error(...)
+            ...
+          }
+      - pattern-not: |
+          try { ... } catch ($ERR) {
+            ...
+            logger.warn(...)
+            ...
+          }
+    message: "Catch block without error logging — observability gap"
+    languages: [typescript, javascript]
+    severity: WARNING
+    metadata:
+      category: observability
+      cwe: "CWE-778: Insufficient Logging"

package/patches/observability/error-path-no-log.ts

@@ -0,0 +1,47 @@
+// Test cases for error-path-no-log Semgrep rule
+
+function badThrow() {
+  // ruleid: error-path-no-log
+  throw new Error('something went wrong');
+}
+
+function badReturn() {
+  // ruleid: error-path-no-log
+  return err('something went wrong');
+}
+
+function goodThrow() {
+  // ok: error-path-no-log
+  console.error('about to throw');
+  throw new Error('something went wrong');
+}
+
+function goodReturn() {
+  // ok: error-path-no-log
+  console.error('returning error');
+  return err('something went wrong');
+}
+
+function goodThrowWithLogger() {
+  // ok: error-path-no-log
+  logger.error('about to throw');
+  throw new Error('something went wrong');
+}
+
+function goodReturnWithLogger() {
+  // ok: error-path-no-log
+  logger.error('returning error');
+  return err('something went wrong');
+}
+
+function goodThrowWithWarn() {
+  // ok: error-path-no-log
+  console.warn('about to throw');
+  throw new Error('something went wrong');
+}
+
+function goodReturnWithLoggerWarn() {
+  // ok: error-path-no-log
+  logger.warn('returning error');
+  return err('something went wrong');
+}

package/patches/observability/error-path-no-log.yaml

@@ -0,0 +1,68 @@
+rules:
+  - id: error-path-no-log
+    patterns:
+      - pattern-either:
+          - pattern: throw $ERR;
+          - pattern: return err(...);
+      - pattern-not-inside: |
+          {
+            ...
+            console.error(...)
+            ...
+            throw $ERR;
+          }
+      - pattern-not-inside: |
+          {
+            ...
+            console.warn(...)
+            ...
+            throw $ERR;
+          }
+      - pattern-not-inside: |
+          {
+            ...
+            logger.error(...)
+            ...
+            throw $ERR;
+          }
+      - pattern-not-inside: |
+          {
+            ...
+            logger.warn(...)
+            ...
+            throw $ERR;
+          }
+      - pattern-not-inside: |
+          {
+            ...
+            console.error(...)
+            ...
+            return err(...);
+          }
+      - pattern-not-inside: |
+          {
+            ...
+            console.warn(...)
+            ...
+            return err(...);
+          }
+      - pattern-not-inside: |
+          {
+            ...
+            logger.error(...)
+            ...
+            return err(...);
+          }
+      - pattern-not-inside: |
+          {
+            ...
+            logger.warn(...)
+            ...
+            return err(...);
+          }
+    message: "Error path without logging — observability gap"
+    languages: [typescript, javascript]
+    severity: WARNING
+    metadata:
+      category: observability
+      cwe: "CWE-778: Insufficient Logging"

package/patches/observability/function-no-debug-log.ts

@@ -0,0 +1,54 @@
+// Test cases for function-no-debug-log Semgrep rule
+
+// ruleid: function-no-debug-log
+function processData(input: string) {
+  return input.trim();
+}
+
+// ruleid: function-no-debug-log
+function handleRequest(req: any) {
+  const result = compute(req);
+  return result;
+}
+
+// ruleid: function-no-debug-log
+const transformData = (input: string) => {
+  return input.toUpperCase();
+};
+
+// ok: function-no-debug-log
+function processDataWithLog(input: string) {
+  console.log('processing data', input);
+  return input.trim();
+}
+
+// ok: function-no-debug-log
+function handleRequestWithDebug(req: any) {
+  console.debug('handling request', req);
+  const result = compute(req);
+  return result;
+}
+
+// ok: function-no-debug-log
+function serviceCall(params: any) {
+  logger.debug('service call', params);
+  return fetch(params.url);
+}
+
+// ok: function-no-debug-log
+function anotherService(params: any) {
+  logger.info('another service call', params);
+  return fetch(params.url);
+}
+
+// ok: function-no-debug-log
+const transformWithLog = (input: string) => {
+  console.log('transforming', input);
+  return input.toUpperCase();
+};
+
+// ok: function-no-debug-log
+const arrowWithDebug = (input: string) => {
+  logger.debug('arrow function', input);
+  return input.toLowerCase();
+};

package/patches/observability/function-no-debug-log.yaml

@@ -0,0 +1,114 @@
+rules:
+  - id: function-no-debug-log
+    patterns:
+      - pattern-either:
+          - pattern: |
+              function $FUNC(...) { ... }
+          - pattern: |
+              const $FUNC = (...) => { ... }
+          - pattern: |
+              let $FUNC = (...) => { ... }
+          - pattern: |
+              $FUNC(...) { ... }
+      - pattern-not: |
+          function $FUNC(...) {
+            ...
+            console.log(...)
+            ...
+          }
+      - pattern-not: |
+          function $FUNC(...) {
+            ...
+            console.debug(...)
+            ...
+          }
+      - pattern-not: |
+          function $FUNC(...) {
+            ...
+            logger.debug(...)
+            ...
+          }
+      - pattern-not: |
+          function $FUNC(...) {
+            ...
+            logger.info(...)
+            ...
+          }
+      - pattern-not: |
+          const $FUNC = (...) => {
+            ...
+            console.log(...)
+            ...
+          }
+      - pattern-not: |
+          const $FUNC = (...) => {
+            ...
+            console.debug(...)
+            ...
+          }
+      - pattern-not: |
+          const $FUNC = (...) => {
+            ...
+            logger.debug(...)
+            ...
+          }
+      - pattern-not: |
+          const $FUNC = (...) => {
+            ...
+            logger.info(...)
+            ...
+          }
+      - pattern-not: |
+          let $FUNC = (...) => {
+            ...
+            console.log(...)
+            ...
+          }
+      - pattern-not: |
+          let $FUNC = (...) => {
+            ...
+            console.debug(...)
+            ...
+          }
+      - pattern-not: |
+          let $FUNC = (...) => {
+            ...
+            logger.debug(...)
+            ...
+          }
+      - pattern-not: |
+          let $FUNC = (...) => {
+            ...
+            logger.info(...)
+            ...
+          }
+      - pattern-not: |
+          $FUNC(...) {
+            ...
+            console.log(...)
+            ...
+          }
+      - pattern-not: |
+          $FUNC(...) {
+            ...
+            console.debug(...)
+            ...
+          }
+      - pattern-not: |
+          $FUNC(...) {
+            ...
+            logger.debug(...)
+            ...
+          }
+      - pattern-not: |
+          $FUNC(...) {
+            ...
+            logger.info(...)
+            ...
+          }
+    message: "Function without debug/info logging — observability gap"
+    languages: [typescript, javascript]
+    severity: INFO
+    metadata:
+      category: observability
+      cwe: "CWE-778: Insufficient Logging"

package/ralph/drivers/claude-code.sh

@@ -79,10 +79,8 @@ driver_build_command() {
         CLAUDE_CMD_ARGS+=("--plugin-dir" "$plugin_dir")
     fi
 
-    # Output format
-    if [[ "$CLAUDE_OUTPUT_FORMAT" == "json" ]]; then
-        CLAUDE_CMD_ARGS+=("--output-format" "json")
-    fi
+    # Output format — always stream-json for real-time NDJSON output
+    CLAUDE_CMD_ARGS+=("--output-format" "stream-json" "--verbose" "--include-partial-messages")
 
     # Allowed tools
     if [[ -n "$CLAUDE_ALLOWED_TOOLS" ]]; then
@@ -123,30 +121,6 @@ driver_supports_live_output() {
     return 0
 }
 
-# Prepare command arguments for live stream-json output
-driver_prepare_live_command() {
-    LIVE_CMD_ARGS=()
-    local skip_next=false
-
-    for arg in "${CLAUDE_CMD_ARGS[@]}"; do
-        if [[ "$skip_next" == "true" ]]; then
-            LIVE_CMD_ARGS+=("stream-json")
-            skip_next=false
-        elif [[ "$arg" == "--output-format" ]]; then
-            LIVE_CMD_ARGS+=("$arg")
-            skip_next=true
-        else
-            LIVE_CMD_ARGS+=("$arg")
-        fi
-    done
-
-    if [[ "$skip_next" == "true" ]]; then
-        return 1
-    fi
-
-    LIVE_CMD_ARGS+=("--verbose" "--include-partial-messages")
-}
-
 # Stream filter for raw Claude stream-json events
 driver_stream_filter() {
     echo '