oh-my-customcode 0.77.0 → 0.78.1

package/README.md

@@ -235,7 +235,7 @@ Key rules: R010 (orchestrator never writes files), R009 (parallel execution mand
 
 ---
 
-### Guides (31)
+### Guides (32)
 
 Reference documentation covering best practices, architecture decisions, and integration patterns. Located in `guides/` at project root, covering topics from agent design to CI/CD to observability.
 
@@ -292,7 +292,7 @@ your-project/
 │   ├── specs/                  # Extracted canonical specs
 │   ├── contexts/               # 4 shared context files
 │   └── ontology/               # Knowledge graph for RAG
-└── guides/                     # 31 reference documents
+└── guides/                     # 32 reference documents
 ```
 
 ---

package/dist/cli/index.js

@@ -9325,7 +9325,7 @@ var init_package = __esm(() => {
     workspaces: [
       "packages/*"
     ],
-    version: "0.77.0",
+    version: "0.78.1",
     description: "Batteries-included agent harness for Claude Code",
     type: "module",
     bin: {

package/dist/index.js

@@ -1820,7 +1820,7 @@ var package_default = {
   workspaces: [
     "packages/*"
   ],
-  version: "0.77.0",
+  version: "0.78.1",
   description: "Batteries-included agent harness for Claude Code",
   type: "module",
   bin: {

package/package.json

@@ -3,7 +3,7 @@
   "workspaces": [
     "packages/*"
   ],
-  "version": "0.77.0",
+  "version": "0.78.1",
   "description": "Batteries-included agent harness for Claude Code",
   "type": "module",
   "bin": {

package/templates/.claude/hooks/hooks.json

@@ -166,9 +166,13 @@
           {
             "type": "command",
             "command": "#!/bin/bash\ninput=$(cat)\nagent_type=$(echo \"$input\" | jq -r '.agent_type // \"unknown\"')\nmodel=$(echo \"$input\" | jq -r '.model // \"inherit\"')\ndesc=$(echo \"$input\" | jq -r '.description // \"\"' | head -c 40)\necho \"─── [SubagentStart] ${agent_type}:${model} | ${desc} ───\" >&2\necho \"$input\""
+          },
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/scripts/agent-start-recorder.sh"
           }
         ],
-        "description": "HUD display when a subagent starts (complements PreToolUse Agent matcher)"
+        "description": "HUD display + agent start time recording for stall detection (R009)"
       }
     ],
     "SubagentStop": [
@@ -181,7 +185,11 @@
           },
           {
             "type": "command",
-            "command": "count_file=\"/tmp/.claude-loop-count-$PPID\"; if [ -f \"$count_file\" ]; then last_mod=$(stat -c%Y \"$count_file\" 2>/dev/null || stat -f%m \"$count_file\" 2>/dev/null || echo 0); now=$(date +%s); if [ $((now - last_mod)) -gt 60 ]; then echo 0 > \"$count_file\"; fi; fi; count=$(cat \"$count_file\" 2>/dev/null || echo 0); count=$((count + 1)); echo \"$count\" > \"$count_file\"; if [ \"$count\" -ge 4 ]; then echo '[AutoContinue] SAFETY: auto-continue limit (3) reached. Pausing.' >&2; fi; cat"
+            "command": "bash .claude/hooks/scripts/stall-detection-advisor.sh"
+          },
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/scripts/auto-continue-guard.sh"
           },
           {
             "type": "prompt",

package/templates/.claude/hooks/scripts/agent-start-recorder.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+set -euo pipefail
+
+# Agent Start Recorder
+# Trigger: SubagentStart
+# Purpose: Record agent spawn time for stall detection duration calculations
+# Protocol: stdin JSON -> record start time -> stdout pass-through, exit 0 always (R021 advisory)
+
+command -v jq >/dev/null 2>&1 || { cat; exit 0; }
+
+input=$(cat)
+
+agent_type=$(echo "$input" | jq -r '.agent_type // "unknown"')
+model=$(echo "$input" | jq -r '.model // "inherit"')
+description=$(echo "$input" | jq -r '.description // ""' | head -c 80)
+
+AGENT_START_FILE="/tmp/.claude-agent-starts-${PPID}"
+
+timestamp=$(date +%s)
+
+entry=$(jq -cn \
+  --arg ts "$timestamp" \
+  --arg agent "$agent_type" \
+  --arg model "$model" \
+  --arg desc "$description" \
+  '{start_epoch: $ts, agent_type: $agent, model: $model, description: $desc}')
+
+echo "$entry" >> "$AGENT_START_FILE"
+
+# Ring buffer: 50 max
+if [ -f "$AGENT_START_FILE" ]; then
+  line_count=$(wc -l < "$AGENT_START_FILE" | tr -d ' ')
+  if [ "$line_count" -gt 50 ]; then
+    tail -50 "$AGENT_START_FILE" > "${AGENT_START_FILE}.tmp"
+    mv "${AGENT_START_FILE}.tmp" "$AGENT_START_FILE"
+  fi
+fi
+
+echo "$input"
+exit 0

package/templates/.claude/hooks/scripts/auto-continue-guard.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+set -euo pipefail
+
+# Auto-Continue Guard
+# Trigger: SubagentStop
+# Purpose: Count consecutive subagent completions and warn when auto-continue limit reached
+# Protocol: stdin JSON -> count check -> stdout pass-through, exit 0 always (R021)
+
+input=$(cat)
+
+count_file="/tmp/.claude-loop-count-${PPID}"
+
+# Reset counter if stale (>60s since last update)
+if [ -f "$count_file" ]; then
+  last_mod=$(stat -c%Y "$count_file" 2>/dev/null || stat -f%m "$count_file" 2>/dev/null || echo 0)
+  now=$(date +%s)
+  if [ $((now - last_mod)) -gt 60 ]; then
+    echo 0 > "$count_file"
+  fi
+fi
+
+# Increment counter
+count=$(cat "$count_file" 2>/dev/null || echo 0)
+count=$((count + 1))
+echo "$count" > "$count_file"
+
+# Warn if limit reached
+if [ "$count" -ge 4 ]; then
+  echo '[AutoContinue] SAFETY: auto-continue limit (3) reached. Pausing.' >&2
+fi
+
+echo "$input"
+exit 0

package/templates/.claude/hooks/scripts/stall-detection-advisor.sh

@@ -0,0 +1,112 @@
+#!/bin/bash
+set -euo pipefail
+
+# Stall Detection Advisor
+# Trigger: SubagentStop
+# Purpose: Detect stalled parallel agents and advise adaptive splitting (R009)
+# Protocol: stdin JSON -> analyze durations -> stderr advisory, stdout pass-through, exit 0 always (R021)
+
+# ORDERING: This hook MUST run AFTER task-outcome-recorder.sh in hooks.json SubagentStop array.
+# Reason: This script removes consumed entries from AGENT_START_FILE; task-outcome-recorder reads them first.
+
+command -v jq >/dev/null 2>&1 || { cat; exit 0; }
+
+input=$(cat)
+
+AGENT_START_FILE="/tmp/.claude-agent-starts-${PPID}"
+DURATION_FILE="/tmp/.claude-agent-durations-${PPID}"
+
+# Skip if no start records exist
+[ -f "$AGENT_START_FILE" ] || { echo "$input"; exit 0; }
+
+# --- 1. Extract completed agent info ---
+agent_type=$(echo "$input" | jq -r '.agent_type // "unknown"')
+model=$(echo "$input" | jq -r '.model // "inherit"')
+description=$(echo "$input" | jq -r '.description // ""' | head -c 80)
+
+# --- 2. Calculate duration from start record ---
+start_epoch=$(grep -F "\"agent_type\":\"${agent_type}\"" "$AGENT_START_FILE" 2>/dev/null | tail -1 | jq -r '.start_epoch // "0"' 2>/dev/null || echo "0")
+
+if [ "$start_epoch" = "0" ] || [ "$start_epoch" = "null" ]; then
+  echo "$input"
+  exit 0
+fi
+
+now_epoch=$(date +%s)
+duration_seconds=$((now_epoch - start_epoch))
+
+# Guard against negative duration (NTP adjustment, clock skew)
+if [ "$duration_seconds" -lt 0 ]; then duration_seconds=0; fi
+
+# --- 3. Stall detection (BEFORE recording this agent's duration, so self is excluded from average) ---
+# Need at least 1 completed peer to calculate average
+if [ -f "$DURATION_FILE" ]; then
+  completed_count=$(wc -l < "$DURATION_FILE" | tr -d ' ')
+else
+  completed_count=0
+fi
+
+if [ "$completed_count" -ge 1 ]; then
+  # Calculate average duration of completed agents (null-safe)
+  avg_duration=$(jq -s '[.[].duration_seconds | numbers] | if length == 0 then 0 else add / length | floor end' "$DURATION_FILE" 2>/dev/null || echo "0")
+
+  if [ "$avg_duration" -gt 0 ]; then
+    stall_threshold=$((avg_duration * 2))
+
+    # Check for still-running agents (in start file but not in duration file)
+    if [ -f "$AGENT_START_FILE" ] && [ -s "$AGENT_START_FILE" ]; then
+      while IFS= read -r line; do
+        running_agent=$(echo "$line" | jq -r '.agent_type // ""' 2>/dev/null || true)
+        running_start=$(echo "$line" | jq -r '.start_epoch // "0"' 2>/dev/null || echo "0")
+        running_desc=$(echo "$line" | jq -r '.description // ""' 2>/dev/null || true)
+        running_model=$(echo "$line" | jq -r '.model // "inherit"' 2>/dev/null || true)
+
+        if [ "$running_start" = "0" ] || [ "$running_start" = "null" ]; then continue; fi
+
+        elapsed=$((now_epoch - running_start))
+
+        if [ "$elapsed" -gt "$stall_threshold" ]; then
+          # --- Emit advisory (stderr) ---
+          echo "" >&2
+          echo "─── [Stall Detection Advisory] ───────────────────────────" >&2
+          echo "  Stalled: ${running_agent}:${running_model} (${elapsed}s elapsed, 2x avg ${avg_duration}s)" >&2
+          echo "  Description: ${running_desc}" >&2
+          echo "  ⚡ Consider spawning independent pending tasks immediately" >&2
+          echo "  R009 Adaptive Parallel Splitting applies" >&2
+          echo "──────────────────────────────────────────────────────────" >&2
+          echo "" >&2
+        fi
+      done < "$AGENT_START_FILE"
+    fi
+  fi
+fi
+
+# --- 4. Record duration (AFTER stall detection so self is excluded from average) ---
+duration_entry=$(jq -cn \
+  --arg agent "$agent_type" \
+  --arg model "$model" \
+  --arg desc "$description" \
+  --arg dur "$duration_seconds" \
+  --arg ts "$now_epoch" \
+  '{agent_type: $agent, model: $model, description: $desc, duration_seconds: ($dur | tonumber), timestamp: $ts}')
+
+echo "$duration_entry" >> "$DURATION_FILE"
+
+# Remove only first consumed start entry (preserve siblings for parallel same-type agents)
+if [ -f "$AGENT_START_FILE" ]; then
+  awk -v pat="\"agent_type\":\"${agent_type}\"" 'found || $0 !~ pat { print; next } { found=1 }' "$AGENT_START_FILE" > "${AGENT_START_FILE}.tmp" 2>/dev/null || true
+  mv "${AGENT_START_FILE}.tmp" "$AGENT_START_FILE" 2>/dev/null || true
+fi
+
+# Ring buffer: 50 max
+if [ -f "$DURATION_FILE" ]; then
+  line_count=$(wc -l < "$DURATION_FILE" | tr -d ' ')
+  if [ "$line_count" -gt 50 ]; then
+    tail -50 "$DURATION_FILE" > "${DURATION_FILE}.tmp"
+    mv "${DURATION_FILE}.tmp" "$DURATION_FILE"
+  fi
+fi
+
+# Pass through
+echo "$input"
+exit 0

package/templates/.claude/hooks/scripts/task-outcome-recorder.sh

@@ -67,6 +67,19 @@ else
   fi
 fi
 
+# Duration calculation from start recorder
+# ORDERING: This script MUST run BEFORE stall-detection-advisor.sh in hooks.json SubagentStop array.
+# Reason: stall-detection-advisor removes consumed entries from AGENT_START_FILE after reading.
+AGENT_START_FILE="/tmp/.claude-agent-starts-${PPID}"
+duration_seconds=0
+if [ -f "$AGENT_START_FILE" ]; then
+  start_epoch=$(grep -F "\"agent_type\":\"${agent_type}\"" "$AGENT_START_FILE" 2>/dev/null | tail -1 | jq -r '.start_epoch // "0"' 2>/dev/null || echo "0")
+  if [ "$start_epoch" != "0" ] && [ "$start_epoch" != "null" ]; then
+    now_epoch=$(date +%s)
+    duration_seconds=$((now_epoch - start_epoch))
+  fi
+fi
+
 # Append JSON line entry
 timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 entry=$(jq -n \
@@ -78,7 +91,8 @@ entry=$(jq -n \
   --arg skill "$skill_name" \
   --arg desc "$description" \
   --arg err "$error_summary" \
-  '{timestamp: $ts, agent_type: $agent, model: $model, outcome: $outcome, pattern_used: $pattern, skill: $skill, description: $desc, error_summary: $err}')
+  --arg dur "$duration_seconds" \
+  '{timestamp: $ts, agent_type: $agent, model: $model, outcome: $outcome, pattern_used: $pattern, skill: $skill, description: $desc, error_summary: $err, duration_seconds: ($dur | tonumber)}')
 
 echo "$entry" >> "$OUTCOME_FILE"
 

package/templates/CLAUDE.md

@@ -156,7 +156,7 @@ project/
 |   +-- rules/                   # 전역 규칙 (R000-R021)
 |   +-- hooks/                   # 훅 스크립트 (보안, 검증, HUD)
 |   +-- contexts/                # 컨텍스트 파일 (ecomode)
-+-- guides/                      # 레퍼런스 문서 (31 토픽)
++-- guides/                      # 레퍼런스 문서 (32 토픽)
 ```
 
 ## 오케스트레이션

package/templates/guides/hook-data-flow/README.md

@@ -0,0 +1,135 @@
+# Hook Data Flow: Stall Detection Pipeline
+
+Added in v0.78.0. Documents the three-script pipeline that detects stalled parallel agents and emits R009 Adaptive Parallel Splitting advisories.
+
+Related rule: `.claude/rules/MUST-parallel-execution.md` (R009 Adaptive Parallel Splitting section)
+
+---
+
+## Overview
+
+When multiple agents run in parallel, one agent may take significantly longer than its peers. The stall detection pipeline identifies this condition at the moment any agent completes and advises the orchestrator to spawn independent pending tasks immediately — without cancelling the stalled agent.
+
+The pipeline spans two hook events and three scripts:
+
+| Event | Script | Role |
+|-------|--------|------|
+| SubagentStart | `agent-start-recorder.sh` | Record spawn timestamp |
+| SubagentStop (1st) | `task-outcome-recorder.sh` | Read start time, record outcome with duration |
+| SubagentStop (2nd) | `stall-detection-advisor.sh` | Read start times, compare durations, emit advisory, consume start entry |
+
+---
+
+## Data Flow
+
+```
+SubagentStart event
+  └─ agent-start-recorder.sh
+       reads:  stdin JSON (agent_type, model, description)
+       writes: /tmp/.claude-agent-starts-$PPID  (appends 1 JSON line)
+
+SubagentStop event  [hooks execute in array order — ordering is critical]
+  │
+  ├─ [1] task-outcome-recorder.sh
+  │       reads:  stdin JSON (agent_type, model, outcome)
+  │       reads:  /tmp/.claude-agent-starts-$PPID  (duration calc — entry still present)
+  │       writes: /tmp/.claude-task-outcomes-$PPID  (appends 1 JSON line with duration_seconds)
+  │       writes: stderr  (on failure only)
+  │
+  └─ [2] stall-detection-advisor.sh
+          reads:  stdin JSON (agent_type, model, description)
+          reads:  /tmp/.claude-agent-starts-$PPID  (finds matching start entry for duration)
+          reads:  /tmp/.claude-agent-durations-$PPID  (peer durations for average calculation)
+          writes: /tmp/.claude-agent-durations-$PPID  (appends completed agent's duration)
+          writes: /tmp/.claude-agent-starts-$PPID  (removes consumed start entry)
+          writes: stderr  (advisory block if stall detected — R021 advisory-only)
+```
+
+### Stall Detection Logic
+
+At SubagentStop, after at least one peer has already completed:
+
+1. Calculate `avg_duration` from all entries in `.claude-agent-durations-$PPID`
+2. Set `stall_threshold = avg_duration * 2`
+3. Scan `.claude-agent-starts-$PPID` for agents not yet in the duration file (still running)
+4. For each still-running agent where `elapsed > stall_threshold`, emit advisory to stderr
+
+The current agent's duration is recorded *after* stall detection so it does not inflate the average for its own check.
+
+### Advisory Output Format
+
+```
+─── [Stall Detection Advisory] ───────────────────────────
+  Stalled: {agent_type}:{model} ({elapsed}s elapsed, 2x avg {avg_duration}s)
+  Description: {description}
+  ⚡ Consider spawning independent pending tasks immediately
+  R009 Adaptive Parallel Splitting applies
+──────────────────────────────────────────────────────────
+```
+
+---
+
+## Shared Files
+
+| File | Writer | Readers | Lifecycle |
+|------|--------|---------|-----------|
+| `/tmp/.claude-agent-starts-$PPID` | `agent-start-recorder.sh` (append) | `task-outcome-recorder.sh` (read), `stall-detection-advisor.sh` (read + remove entry) | Session-scoped via PPID; ring buffer 50 entries; entry removed after `stall-detection-advisor` consumes it |
+| `/tmp/.claude-task-outcomes-$PPID` | `task-outcome-recorder.sh` (append) | `feedback-collector.sh`, `eval-core-batch-save.sh` (at Stop) | Session-scoped via PPID; ring buffer 50 entries |
+| `/tmp/.claude-agent-durations-$PPID` | `stall-detection-advisor.sh` (append) | `stall-detection-advisor.sh` (read for average calculation) | Session-scoped via PPID; ring buffer 50 entries |
+
+---
+
+## Execution Order Requirements
+
+The SubagentStop hook array in `hooks.json` defines a strict ordering:
+
+```json
+"SubagentStop": [
+  { "command": "bash .claude/hooks/scripts/task-outcome-recorder.sh" },
+  { "command": "bash .claude/hooks/scripts/stall-detection-advisor.sh" },
+  ...
+]
+```
+
+**task-outcome-recorder MUST run before stall-detection-advisor.**
+
+Reason: `stall-detection-advisor.sh` removes the matching start entry from `.claude-agent-starts-$PPID` after reading it (to prevent re-matching on the next SubagentStop). If the order were reversed, `task-outcome-recorder.sh` would find no start entry for the agent and would always record `duration_seconds=0`.
+
+If the order is swapped:
+- `task-outcome-recorder` records `duration_seconds=0` for all agents
+- Model escalation decisions based on duration become unreliable
+- No other visible error — silent data corruption
+
+---
+
+## Temp File Lifecycle
+
+```
+Session start (PPID assigned)
+  │
+  ├─ First SubagentStart  →  .claude-agent-starts-$PPID  created
+  │
+  ├─ First SubagentStop   →  .claude-task-outcomes-$PPID  created
+  │                          .claude-agent-durations-$PPID  created
+  │
+  ├─ Each SubagentStop    →  start entry consumed (removed by stall-detection-advisor)
+  │                          duration entry appended
+  │                          outcome entry appended
+  │
+  └─ Session end (PPID released)
+       Files remain in /tmp — OS cleans up on reboot
+       Ring buffers cap each file at 50 lines to bound growth
+```
+
+PPID (parent process ID) is used rather than PID (`$$`) to scope files to the Claude Code session rather than to individual script invocations. All three scripts use `${PPID}` consistently.
+
+---
+
+## Design Principles
+
+- **Advisory-only (R021):** All three scripts exit 0 unconditionally. A missing `jq` binary causes silent pass-through, not a blocked hook.
+- **PPID scoping:** Isolates temp files per Claude Code session. Multiple concurrent sessions do not interfere.
+- **Ring buffers:** Each temp file is capped at 50 lines via `tail -50` after each append. Prevents unbounded growth in long sessions with many agents.
+- **grep -F for pattern matching:** Fixed-string matching in `agent-start-recorder` and `task-outcome-recorder` avoids regex injection from agent type names.
+- **Self-exclusion from average:** `stall-detection-advisor` reads the duration file *before* appending its own entry, so the completing agent is never compared against itself.
+- **Sibling preservation:** When removing a start entry, `awk` removes only the first matching line — preserving sibling entries when multiple agents of the same type run in parallel.

package/templates/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.77.0",
+  "version": "0.78.1",
   "lastUpdated": "2026-03-24T00:00:00.000Z",
   "components": [
     {
@@ -24,7 +24,7 @@
       "name": "guides",
       "path": "guides",
       "description": "Reference documentation",
-      "files": 31
+      "files": 32
     },
     {
       "name": "hooks",