devflow-kit 1.8.3 → 2.0.1

package/src/assets/scripts/hooks/session-start-memory

@@ -0,0 +1,318 @@
+#!/bin/bash
+
+# SessionStart Hook
+# Injects working memory as additionalContext.
+# Memory: restores .devflow/memory/WORKING-MEMORY.md with git-reconciled header
+# and 3-state rendering (in-sync / drifted / refresh-failing).
+# State detection uses the <!-- memory-head: <sha> branch: <name> --> stamp on line 1.
+# No raw UNPROCESSED TURNS dump — the background-memory-update worker handles refresh.
+
+# Safe no-op fallback: must exist before set -e and before hook-bootstrap is sourced.
+dbg() { :; }
+
+set -e
+
+# Re-entrancy guard — before hook-bootstrap to minimize background session
+# overhead. The memory worker's own claude -p session fires SessionStart hooks
+# too (SessionStart fires on every session, including a detached worker's).
+if [ "${DEVFLOW_BG_UPDATER:-}" = "1" ]; then dbg "EXIT: bg_updater"; exit 0; fi
+
+# JSON parsing (jq with node fallback) — silently no-op if neither available
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+source "$SCRIPT_DIR/hook-bootstrap" "session-start-memory"
+
+source "$SCRIPT_DIR/json-parse" || { echo "session-start-memory: failed to source json-parse" >&2; exit 1; }
+if [ "$_JSON_AVAILABLE" = "false" ]; then exit 0; fi
+
+INPUT=$(cat)
+
+CWD=$(printf '%s' "$INPUT" | json_field "cwd" "")
+if [ -z "$CWD" ] || [ ! -d "$CWD" ]; then
+  dbg "EXIT: bad CWD"
+  exit 0
+fi
+
+devflow_debug_set_cwd "$CWD"
+dbg "CWD=$CWD"
+
+# Anchor .devflow/ to the project root (prevents a stray nested .devflow/ when this
+# hook runs with a CWD inside .devflow/...). Empty → fall back to CWD.
+source "$SCRIPT_DIR/resolve-project-root" 2>/dev/null || true
+PROJECT_ROOT="$(df_resolve_root "$CWD" 2>/dev/null || true)"
+[ -n "$PROJECT_ROOT" ] || PROJECT_ROOT="$CWD"
+
+DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
+MEMORY_DIR="$DEVFLOW_DIR/memory"
+
+# Normal logging
+source "$SCRIPT_DIR/hook-log-init" "session-start-memory"
+
+# Check feature config — single source of truth for memory enabled/disabled (ADR-001).
+FEATURE_CONFIG="$DEVFLOW_DIR/config.json"
+if [ -f "$FEATURE_CONFIG" ]; then
+  MEMORY_ENABLED=$(json_field_file "$FEATURE_CONFIG" "memory" "true")
+  if [ "$MEMORY_ENABLED" = "false" ]; then
+    dbg "EXIT: memory disabled in feature config"
+    exit 0
+  fi
+fi
+
+# --- D56c cold-path recovery: orphaned .pending-turns.processing ---
+# Self-contained (not sourced from a shared helper): applies a 300s stale-age
+# gate to .pending-turns.processing. background-memory-update is the PRIMARY
+# recovery owner: it re-merges a leftover .processing under its own lock on
+# every spawn. This is the COLD-PATH fallback for when the worker never
+# re-spawns (memory disabled mid-flight, host offline, etc.): a SessionStart
+# arriving >300s after the crash with no intervening Stop hook.
+# Non-clobber: only recovers when .pending-turns.jsonl does NOT already exist,
+# so a concurrent session's fresh queue is never overwritten.
+source "$SCRIPT_DIR/get-mtime" || { echo "session-start-memory: failed to source get-mtime" >&2; exit 1; }
+_SSM_PT_PROC="$MEMORY_DIR/.pending-turns.processing"
+_SSM_PT_JSONL="$MEMORY_DIR/.pending-turns.jsonl"
+if [ -f "$_SSM_PT_PROC" ]; then
+  _SSM_PT_MTIME=$(get_mtime "$_SSM_PT_PROC" 2>/dev/null || true)
+  _SSM_PT_MTIME="${_SSM_PT_MTIME:-0}"
+  _SSM_NOW_PT=$(date +%s)
+  _SSM_PT_AGE=$(( _SSM_NOW_PT - _SSM_PT_MTIME ))
+  if [ "$_SSM_PT_AGE" -gt 300 ]; then
+    if [ ! -f "$_SSM_PT_JSONL" ]; then
+      mv "$_SSM_PT_PROC" "$_SSM_PT_JSONL" 2>/dev/null || true
+      dbg "Recovered orphaned .pending-turns.processing (age ${_SSM_PT_AGE}s)"
+      log "Recovered orphaned .pending-turns.processing → .pending-turns.jsonl (cold path)"
+    else
+      dbg "Stale .pending-turns.processing skipped — .pending-turns.jsonl already exists"
+      log "Stale .pending-turns.processing skipped (cold path): .pending-turns.jsonl already exists"
+    fi
+  fi
+fi
+
+CONTEXT=""
+
+# --- Section 1: Working Memory with git-reconciled header ---
+
+MEMORY_FILE="$MEMORY_DIR/WORKING-MEMORY.md"
+
+# --- parse_and_validate_stamp: parse <!-- memory-head: <sha> branch: <name> --> from
+# line 1 and apply hex-validation security gate.  Sets STAMP_SHA, STAMP_BRANCH,
+# FIRST_LINE, and MEMORY_BODY in the caller's scope.
+# Treat WORKING-MEMORY.md as untrusted input (engineering rule: validate at boundaries;
+# assume input is malicious).  A value beginning with '-' or containing '..' could be a
+# git flag or unexpected revision range.  Reject anything that is not a hex object-id
+# (7–40 chars).  On mismatch fall through to the no-stamp path, preserving 3-state logic.
+parse_and_validate_stamp() {
+  local _content="$1"
+  FIRST_LINE=$(printf '%s' "$_content" | head -1 2>/dev/null || echo "")
+  STAMP_SHA=""
+  STAMP_BRANCH=""
+  case "$FIRST_LINE" in
+    "<!-- memory-head:"*)
+      # Extract sha and branch via sed (bash 3.2 compatible)
+      STAMP_SHA=$(echo "$FIRST_LINE" | sed -n 's/<!-- memory-head: \([^ ]*\) branch:.*/\1/p')
+      STAMP_BRANCH=$(echo "$FIRST_LINE" | sed -n 's/<!-- memory-head: [^ ]* branch: \([^ ]*\) -->/\1/p')
+      ;;
+  esac
+  # Hex-validation security gate — must stay before any git use of STAMP_SHA
+  if [ -n "$STAMP_SHA" ]; then
+    case "$STAMP_SHA" in
+      [0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]*)
+        # Looks like a hex string; verify length ≤ 40 and only hex chars via sed
+        local _SHA_CLEAN
+        _SHA_CLEAN=$(echo "$STAMP_SHA" | sed 's/[^0-9a-f]//g')
+        local _SHA_LEN=${#STAMP_SHA}
+        if [ "$_SHA_CLEAN" != "$STAMP_SHA" ] || [ "$_SHA_LEN" -gt 40 ]; then
+          dbg "STAMP_SHA rejected (non-hex chars or >40): $STAMP_SHA"
+          STAMP_SHA=""
+          STAMP_BRANCH=""
+        fi
+        ;;
+      *)
+        dbg "STAMP_SHA rejected (bad prefix): $STAMP_SHA"
+        STAMP_SHA=""
+        STAMP_BRANCH=""
+        ;;
+    esac
+  fi
+  dbg "STAMP_SHA=$STAMP_SHA STAMP_BRANCH=$STAMP_BRANCH"
+  # Strip stamp line from injected body
+  case "$FIRST_LINE" in
+    "<!-- memory-head:"*)
+      MEMORY_BODY=$(printf '%s' "$_content" | tail -n +2)
+      ;;
+    *)
+      MEMORY_BODY="$_content"
+      ;;
+  esac
+}
+
+# --- detect_refresh_failing: sets REFRESH_FAILING in caller's scope.
+# Condition: queue non-empty AND (.last-refresh-ok missing OR >600s old)
+detect_refresh_failing() {
+  local _now="$1"
+  local _memory_dir="$2"
+  local _log_dir="$3"
+  local _queue_file="$_memory_dir/.pending-turns.jsonl"
+  local _ok_file="$_memory_dir/.last-refresh-ok"
+  local _queue_depth=0
+  if [ -f "$_queue_file" ] && [ -s "$_queue_file" ]; then
+    _queue_depth=$(wc -l < "$_queue_file" | tr -d ' ')
+  fi
+  local _ok_age=9999999
+  if [ -f "$_ok_file" ]; then
+    local _ok_mtime
+    _ok_mtime=$(get_mtime "$_ok_file")
+    _ok_age=$(( _now - _ok_mtime ))
+  fi
+  REFRESH_FAILING=""
+  if [ "$_queue_depth" -gt 0 ] && { [ ! -f "$_ok_file" ] || [ "$_ok_age" -gt 600 ]; }; then
+    local _ok_min=$(( _ok_age / 60 ))
+    local _ok_min_str
+    if [ "$_ok_age" -ge 9999999 ]; then
+      _ok_min_str="never"
+    else
+      _ok_min_str="${_ok_min}m"
+    fi
+    REFRESH_FAILING="⚠ MEMORY REFRESH MAY BE FAILING — ${_queue_depth} turn(s) unprocessed, last refresh ${_ok_min_str} ago; check ${_log_dir}/.background-memory-update.log"
+    dbg "State C: refresh failing (QUEUE_DEPTH=$_queue_depth OK_AGE=${_ok_age}s)"
+  fi
+}
+
+if [ -f "$MEMORY_FILE" ]; then
+  dbg "MEMORY_FILE exists: $MEMORY_FILE"
+  MEMORY_CONTENT=$(head -c 65536 "$MEMORY_FILE")
+
+  source "$SCRIPT_DIR/get-mtime" || { echo "session-start-memory: failed to source get-mtime" >&2; exit 1; }
+  FILE_MTIME=$(get_mtime "$MEMORY_FILE")
+  NOW=$(date +%s)
+  AGE_SEC=$(( NOW - FILE_MTIME ))
+  AGE_MIN=$(( AGE_SEC / 60 ))
+  dbg "MEMORY_FILE AGE=${AGE_SEC}s"
+
+  # --- Parse stamp from line 1: <!-- memory-head: <sha> branch: <name> --> ---
+  parse_and_validate_stamp "$MEMORY_CONTENT"
+
+  # --- Gather current git state ---
+  BRANCH=""
+  HEAD=""
+  if cd "$CWD" 2>/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then
+    BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+    HEAD=$(git rev-parse HEAD 2>/dev/null || echo "")
+  fi
+  dbg "BRANCH=$BRANCH HEAD=$HEAD"
+
+  # --- Compute drift (only when stamp SHA is provably an ancestor of HEAD) ---
+  # Single rev-walk: capture full git log output once, then derive count + display lines
+  # from the same data — avoids walking the same commit range twice (perf fix).
+  COMMITS=0
+  _DRIFT_LOG=""
+  if [ -n "$STAMP_SHA" ] && [ -n "$HEAD" ] && [ "$STAMP_SHA" != "$HEAD" ]; then
+    # git merge-base --is-ancestor exits 0 when $STAMP_SHA is ancestor of HEAD
+    if cd "$CWD" 2>/dev/null && git merge-base --is-ancestor "$STAMP_SHA" "$HEAD" 2>/dev/null; then
+      _DRIFT_LOG_FULL=$(git log --oneline "${STAMP_SHA}..${HEAD}" 2>/dev/null || echo "")
+      # grep -c exits 1 on zero matches (POSIX); || true prevents set -e abort.
+      # ${COMMITS:-0} defends the transient-failure case where grep emits nothing.
+      # The old `|| echo "0"` produced "0\n0" (a two-line string) because grep -c
+      # already printed "0" before exiting 1, causing [ "$COMMITS" -le 0 ] to fail
+      # with "integer expression expected" and misroute State A into State B.
+      COMMITS=$(printf '%s\n' "$_DRIFT_LOG_FULL" | grep -c . 2>/dev/null || true)
+      COMMITS=${COMMITS:-0}
+      _DRIFT_LOG=$(printf '%s\n' "$_DRIFT_LOG_FULL" | head -10)
+    fi
+  fi
+  dbg "COMMITS=$COMMITS"
+
+  # --- Branch mismatch warning (shown for any state) ---
+  BRANCH_MISMATCH_NOTE=""
+  if [ -n "$STAMP_BRANCH" ] && [ -n "$BRANCH" ] && [ "$STAMP_BRANCH" != "$BRANCH" ]; then
+    BRANCH_MISMATCH_NOTE="⚠ Memory was written on branch ${STAMP_BRANCH}; you are now on ${BRANCH}.
+"
+  fi
+
+  # --- State C detection: refresh failing ---
+  detect_refresh_failing "$NOW" "$MEMORY_DIR" "$LOG_DIR"
+
+  # --- Build state-specific header ---
+  _STAMP_LABEL="${STAMP_SHA:-unknown}"
+  _BRANCH_LABEL="${BRANCH:-unknown}"
+
+  if [ -z "$STAMP_SHA" ]; then
+    # No stamp (legacy / killed mid-write) — render as A "synced @ unknown"
+    MEMORY_HEADER="--- WORKING MEMORY (synced @ unknown on ${_BRANCH_LABEL}, ${AGE_MIN}m ago) ---"
+    dbg "State A (no stamp)"
+  elif [ "$COMMITS" -le 0 ]; then
+    # State A: in-sync
+    MEMORY_HEADER="--- WORKING MEMORY (synced @ ${_STAMP_LABEL} on ${_BRANCH_LABEL}, ${AGE_MIN}m ago) ---"
+    dbg "State A: in-sync"
+  else
+    # State B: drifted — _DRIFT_LOG already populated from the single rev-walk above
+    MEMORY_HEADER="--- WORKING MEMORY (${COMMITS} commit(s) ago @ ${_STAMP_LABEL} on ${_BRANCH_LABEL}, ${AGE_MIN}m ago — ⚠ reconcile) ---
+Commits since memory was written:
+${_DRIFT_LOG}"
+    dbg "State B: drifted COMMITS=$COMMITS"
+  fi
+
+  # --- Assemble context ---
+  CONTEXT="${BRANCH_MISMATCH_NOTE}${MEMORY_HEADER}
+${MEMORY_BODY}"
+
+  # State C banner shown IN ADDITION to A/B
+  if [ -n "$REFRESH_FAILING" ]; then
+    CONTEXT="${CONTEXT}
+
+${REFRESH_FAILING}"
+    dbg "State C appended"
+  fi
+else
+  dbg "MEMORY_FILE not found: $MEMORY_FILE"
+fi
+
+# --- PRE-COMPACT snapshot recovery (orthogonal to memory refresh, still valuable) ---
+# Re-inject compaction snapshot when it's more recent than the memory file (compact overwrote
+# WORKING-MEMORY.md with a summary, but the pre-compact snapshot may have richer context).
+BACKUP_FILE="$MEMORY_DIR/backup.json"
+if [ -f "$BACKUP_FILE" ]; then
+  BACKUP_MEMORY=$(json_field_file "$BACKUP_FILE" "memory_snapshot" "")
+  if [ -n "$BACKUP_MEMORY" ]; then
+    BACKUP_TS=$(json_field_file "$BACKUP_FILE" "timestamp" "")
+    BACKUP_EPOCH=0
+    if [ -n "$BACKUP_TS" ]; then
+      BACKUP_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$BACKUP_TS" +%s 2>/dev/null \
+        || date -d "$BACKUP_TS" +%s 2>/dev/null \
+        || echo "0")
+    fi
+    FILE_MTIME_CK=0
+    if [ -f "$MEMORY_FILE" ]; then
+      FILE_MTIME_CK=$(get_mtime "$MEMORY_FILE" 2>/dev/null || echo "0")
+    fi
+    if [ "$BACKUP_EPOCH" -gt "$FILE_MTIME_CK" ]; then
+      dbg "Compact recovery available: BACKUP_TS=$BACKUP_TS"
+      COMPACT_NOTE="
+--- PRE-COMPACT SNAPSHOT ($BACKUP_TS) ---
+Context was compacted. This snapshot may contain decisions or progress not yet in working memory.
+
+$BACKUP_MEMORY
+"
+      if [ -n "$CONTEXT" ]; then
+        CONTEXT="${CONTEXT}
+${COMPACT_NOTE}"
+      else
+        CONTEXT="$COMPACT_NOTE"
+      fi
+    fi
+  fi
+fi
+
+# --- Output ---
+
+# Only output if we have something to inject
+if [ -z "$CONTEXT" ]; then
+  dbg "EXIT: no context to inject"
+  exit 0
+fi
+
+dbg "OUTPUT_LENGTH=${#CONTEXT}"
+log "Injecting memory context (${#CONTEXT} chars)"
+dbg "=== HOOK COMPLETE ==="
+
+# Output as additionalContext JSON envelope (Claude sees it as system context, not user-visible)
+json_session_output "$CONTEXT"

package/src/assets/scripts/hooks/session-start-orchestrator

@@ -0,0 +1,54 @@
+#!/bin/bash
+
+# SessionStart Hook: Orchestrator Charter Injection
+# Presence-gated: registered/removed by `devflow ambient --enable/--disable`.
+# Git repos only: silent outside a git repo (df_has_git_marker bounded walk).
+# Charter includes the plan-handoff fallback bullet — SessionStart provably fires
+# (SessionStart:clear) in plan-handoff sessions even if UserPromptSubmit does not.
+# NOTE: the literal prefix `Implement the following plan:` is duplicated in
+# src/assets/scripts/hooks/preamble — update both if Claude Code changes the handoff format.
+
+# Safe no-op fallback: must exist before hook-bootstrap is sourced.
+dbg() { :; }
+
+# set -e intentionally omitted: a failure in this section must not crash the hook.
+
+# Re-entrancy guard — before hook-bootstrap to minimize background session overhead.
+# The memory worker's own claude -p session fires SessionStart hooks; without this
+# guard the nested session would re-inject the charter (and receive a plan-handoff
+# directive it must never act on).
+if [ "${DEVFLOW_BG_UPDATER:-}" = "1" ]; then dbg "EXIT: bg_updater"; exit 0; fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+source "$SCRIPT_DIR/hook-bootstrap" "session-start-orchestrator"
+
+source "$SCRIPT_DIR/json-parse" || { echo "session-start-orchestrator: failed to source json-parse" >&2; exit 1; }
+if [ "$_JSON_AVAILABLE" = "false" ]; then exit 0; fi
+
+INPUT=$(cat)
+
+CWD=$(printf '%s' "$INPUT" | json_field "cwd" "")
+if [ -z "$CWD" ] || [ ! -d "$CWD" ]; then
+  dbg "EXIT: bad CWD"
+  exit 0
+fi
+
+devflow_debug_set_cwd "$CWD"
+dbg "CWD=$CWD"
+
+source "$SCRIPT_DIR/hook-log-init" "session-start-orchestrator"
+
+source "$SCRIPT_DIR/git-marker" || true
+if ! df_has_git_marker "$CWD" 2>/dev/null; then dbg "EXIT: not a git repo"; exit 0; fi
+
+CHARTER_FILE="$SCRIPT_DIR/assets/orchestrator-charter.md"
+if [ ! -f "$CHARTER_FILE" ]; then dbg "EXIT: charter missing"; exit 0; fi
+CHARTER=$(cat "$CHARTER_FILE")
+if [ -z "$CHARTER" ]; then dbg "EXIT: charter empty"; exit 0; fi
+if [ "${#CHARTER}" -gt 4096 ]; then dbg "EXIT: charter exceeds cap (${#CHARTER})"; exit 0; fi
+
+dbg "OUTPUT_LENGTH=${#CHARTER}"
+log "Injecting charter (${#CHARTER} chars)"
+json_session_output "$CHARTER"
+dbg "=== HOOK COMPLETE ==="

package/src/assets/scripts/hud.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Devflow HUD — configurable TypeScript status line
+# Receives JSON via stdin from Claude Code, outputs ANSI-formatted HUD
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec node "${SCRIPT_DIR}/hud/index.js"