@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/core/harnesses/shared/hooks/policies/session-context.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# session-context.sh — Canonical Policy Library: SessionStart guard policy
+#
+# Fires when a harness starts a new session. Captures git state into a
+# session-scoped file so a harness's user-prompt-submit hook can inject it on
+# the first prompt.
+#
+# Cannot inject into the LLM context from this event — side effects only.
+# Must complete in <200ms. Must never exit non-zero or produce unexpected stderr.
+#
+# Canonical Policy Script Contract (design.md §4):
+#   env    DOFLOW_PROJECT_DIR, DOFLOW_AGENT (both optional here; DOFLOW_AGENT
+#          only affects the "last_agent" field recorded in meta.json)
+#   stdin  the harness's native SessionStart JSON payload — must expose at
+#          least ".session_id" and ".cwd"
+#   exit   this policy never denies — it always exits 0 (side-effect only)
+#
+# Depends on lib.sh (require_jq, json_field, ensure_session_dir,
+# ensure_project_dir, cwd_hash, run_with_timeout, $SESSIONS_LOG) being
+# discoverable next to this script when it runs — a front door invoking this
+# canonical script is responsible for making lib.sh resolvable via
+# "$(dirname "$0")/lib.sh", exactly as every harness's own SessionStart script
+# already required before this policy moved to a shared location.
+
+set -euo pipefail
+# shellcheck source=lib.sh
+source "$(dirname "$0")/lib.sh"
+require_jq
+
+INPUT=$(cat)
+SESSION_ID=$(json_field "$INPUT" ".session_id")
+CWD=$(json_field "$INPUT" ".cwd")
+
+# Guard: if we can't determine the session, nothing to do
+[[ -z "$SESSION_ID" ]] && exit 0
+
+SESSION_PATH=$(ensure_session_dir "$SESSION_ID")
+
+# Clean up stale injected flag from a prior crashed session
+rm -f "$SESSION_PATH/injected"
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# ── Git state capture ─────────────────────────────────────────────────────────
+
+IS_GIT_REPO=false
+BRANCH=""
+SHA=""
+COMMITS_JSON="[]"
+UNCOMMITTED=0
+STASH_COUNT=0
+UPSTREAM_BEHIND=0
+
+if [[ -n "$CWD" ]] && is_git_worktree "$CWD"; then
+  IS_GIT_REPO=true
+
+  BRANCH=$(git_branch_of "$CWD" || echo "")
+  SHA=$(git_short_sha_of "$CWD" || echo "")
+
+  # Last 5 commits as a JSON array of one-liner strings.
+  # Capture git's raw output first (never fatal under pipefail), then build
+  # the JSON array from that captured text in a single jq call whose failure
+  # replaces COMMITS_JSON via assignment rather than appending via echo —
+  # a trailing `|| echo "[]"` on the pipe would double-emit when git log
+  # fails (e.g. zero-commit repo) but jq still prints "[]" downstream.
+  COMMITS_RAW=$(run_with_timeout 1 -- git -C "$CWD" log --oneline -5 2>/dev/null || true)
+  COMMITS_JSON=$(printf '%s' "$COMMITS_RAW" | jq -Rs 'split("\n") | map(select(length > 0))' 2>/dev/null) || COMMITS_JSON="[]"
+
+  # Count uncommitted (staged + unstaged) files
+  UNCOMMITTED=$(git_uncommitted_count_of "$CWD" || echo "0")
+
+  # Count stash entries
+  STASH_COUNT=$(run_with_timeout 1 -- git -C "$CWD" stash list 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+
+  # How far behind upstream (0 if no upstream configured)
+  # shellcheck disable=SC1083  # @{u} is git upstream ref syntax, not a shell brace expression
+  UPSTREAM_BEHIND=$(run_with_timeout 1 -- git -C "$CWD" rev-list --count HEAD..@{u} 2>/dev/null || echo "0")
+fi
+
+# ── Write git-context.json ────────────────────────────────────────────────────
+
+# Use jq -n for full construction — avoids heredoc variable interpolation
+# which can produce invalid JSON if numeric fields contain unexpected output.
+jq -n \
+  --arg     branch       "$BRANCH" \
+  --arg     sha          "$SHA" \
+  --argjson commits      "$COMMITS_JSON" \
+  --argjson uncommitted  "$UNCOMMITTED" \
+  --argjson stash        "$STASH_COUNT" \
+  --argjson behind       "$UPSTREAM_BEHIND" \
+  --argjson is_git       "$IS_GIT_REPO" \
+  --arg     cwd          "$CWD" \
+  --arg     captured_at  "$TIMESTAMP" \
+  '{
+    branch:           $branch,
+    sha:              $sha,
+    commits:          $commits,
+    uncommitted_count: $uncommitted,
+    stash_count:      $stash,
+    upstream_behind:  $behind,
+    is_git_repo:      $is_git,
+    cwd:              $cwd,
+    captured_at:      $captured_at
+  }' > "$SESSION_PATH/git-context.json"
+
+# ── Write meta.json ───────────────────────────────────────────────────────────
+
+if [[ -n "$CWD" ]]; then
+  PROJECT_DIR=$(ensure_project_dir "$CWD")
+  # Preserve compacted_at from the prior session if present
+  PRIOR_COMPACTED_AT=""
+  if [[ -f "$PROJECT_DIR/meta.json" ]]; then
+    PRIOR_COMPACTED_AT=$(jq -r '.compacted_at // empty' "$PROJECT_DIR/meta.json" 2>/dev/null || echo "")
+  fi
+  META_TMP=$(mktemp "$PROJECT_DIR/.meta.XXXXXX")
+  trap 'rm -f "$META_TMP" 2>/dev/null || true' EXIT
+  jq -n \
+    --arg cwd          "$CWD" \
+    --arg cwd_hash     "$(cwd_hash "$CWD")" \
+    --arg last_agent   "$DOFLOW_AGENT" \
+    --arg last_active  "$TIMESTAMP" \
+    --arg compacted_at "${PRIOR_COMPACTED_AT:-}" \
+    --arg branch       "${BRANCH:-}" \
+    '{
+      cwd:          $cwd,
+      cwd_hash:     $cwd_hash,
+      last_agent:   $last_agent,
+      last_active:  $last_active,
+      compacted_at: (if $compacted_at == "" then null else $compacted_at end),
+      branch:       $branch
+    }' > "$META_TMP" && mv "$META_TMP" "$PROJECT_DIR/meta.json" \
+    || rm -f "$META_TMP" 2>/dev/null || true
+fi
+
+# ── Append to sessions.log ────────────────────────────────────────────────────
+
+mkdir -p "$(dirname "$SESSIONS_LOG")"
+echo "$TIMESTAMP START $SESSION_ID ${CWD:-unknown}" >> "$SESSIONS_LOG"
+
+storage_upkeep_async "$CWD"
+exit 0

package/core/harnesses/shared/hooks/policies/stop-check.sh

@@ -0,0 +1,264 @@
+#!/usr/bin/env bash
+# stop-check.sh — Canonical Policy Library: Stop hook
+#
+# Two responsibilities:
+#   1. Batch lint dispatch: reads the list of files edited this turn
+#      (written by a harness's own post-edit-lint hook), dispatches
+#      formatters async and linters sync with a 2s timeout, then clears the
+#      list. Only runs when the incoming payload carries a session_id — a
+#      harness with no edited-files queue of its own (e.g. Antigravity, which
+#      wires no PostToolUse editor hook yet) simply has nothing to drain here.
+#   2. Stub detection: takes the payload's last_assistant_message, or else the
+#      last assistant message in the JSONL transcript (Claude Code, Codex and
+#      flat {role,content} shapes), then checks for unfinished-work markers.
+#      Exits non-zero if stubs are found (blocks the session from stopping).
+#      Runs independently of (1) — it needs only the payload field or a
+#      transcript path, not a session_id, so it still fires for a harness that
+#      has no edited-files queue. A given message blocks once: harnesses without
+#      stop_hook_active (Antigravity, Kiro) have no other loop guard.
+#   3. Process-leak scan: DoFlow's own identifiers (FR-###, agent-docs/, chain
+#      artifact names) reaching files that ship. Warns, never blocks.
+#
+# Multi-session safe: reads/writes only from sessions/{session_id}/.
+# Async lint uses </dev/null >/dev/null to avoid holding stdin fd.
+#
+# Canonical Policy Script Contract (design.md §4):
+#   env    DOFLOW_PROJECT_DIR, DOFLOW_AGENT (both optional here)
+#   stdin  a Stop-shaped JSON payload. session_id and transcript path field
+#          names both vary by harness (transcript_path vs. Antigravity's
+#          camelCase transcriptPath) — this script reads the union of known
+#          field names rather than assuming one, since a native front door
+#          (Claude/Codex/Kiro) execs this script directly with no payload
+#          translation of its own.
+#   exit   0 = allow the stop, non-zero = deny (block the stop) with the
+#          reason on stderr.
+#
+# Depends on lib.sh (require_jq, json_field, ensure_session_dir,
+# run_with_timeout) being discoverable next to this script when it runs — see
+# session-context.sh's header note; the same front-door responsibility
+# applies here.
+#
+# Reconciliation note (022-normalize-hooks, Phase A): claude's own copy of
+# this policy additionally ran a process-leak scan (step 3) that
+# codex/kiro's copies did not have; that step is folded in here as the more
+# complete, already-proven behavior (D3) rather than dropped. Antigravity's
+# copy runs stub detection only (no lint dispatch, no leak scan — it has no
+# edited-files queue to drain), gated on session_id being absent being a
+# no-op rather than an early exit, so stub detection still fires for it.
+
+set -euo pipefail
+# shellcheck source=lib.sh
+source "$(dirname "$0")/lib.sh"
+require_jq
+
+INPUT=$(cat)
+SESSION_ID=$(json_field "$INPUT" ".session_id")
+
+TRANSCRIPT_PATH=$(json_field "$INPUT" ".transcript_path")
+[ -z "$TRANSCRIPT_PATH" ] && TRANSCRIPT_PATH=$(json_field "$INPUT" ".transcriptPath")
+
+# ── 1. Lint dispatch (only when we have a session-scoped edited-files queue) ──
+
+if [ -n "$SESSION_ID" ]; then
+  SESSION_PATH=$(ensure_session_dir "$SESSION_ID")
+  EDITED_FILES="$SESSION_PATH/edited-files.txt"
+  PROC_FILE="$SESSION_PATH/edited-files.txt.proc"
+
+  # Atomic read-and-clear: mv before reading so concurrent PostToolUse writes
+  # go to a fresh edited-files.txt, not the file we're about to process.
+  mv "$EDITED_FILES" "$PROC_FILE" 2>/dev/null || true
+
+  if [ -f "$PROC_FILE" ] && [ -s "$PROC_FILE" ]; then
+    # Partition paths by extension
+    py_files=()
+    js_files=()
+    go_files=()
+    leak_files=()
+    java_has_files=false
+
+    # The resolver for the leak-scan verb. Absent install -> the scan is
+    # skipped, like every other tool below: this hook has never required
+    # anything to be present.
+    DOFLOW_RUN=""
+    for candidate in \
+      "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/scripts/doflow/bin/doflow-run" \
+      "$HOME/.doflow/scripts/doflow/bin/doflow-run"
+    do
+      [ -x "$candidate" ] && { DOFLOW_RUN="$candidate"; break; }
+    done
+
+    while IFS= read -r path; do
+      [ -z "$path" ] && continue
+      case "$path" in
+        *.py)                   py_files+=("$path") ;;
+        *.ts|*.tsx|*.js|*.jsx)  js_files+=("$path") ;;
+        *.go)                   go_files+=("$path") ;;
+        *.java)                 java_has_files=true ;;
+      esac
+      # Every edited path is a leak-scan candidate regardless of language;
+      # the verb decides what it can read and reports the rest as unscanned.
+      case "$path" in
+        */agent-docs/*|agent-docs/*) ;;   # correct usage there; the verb excludes it too
+        *)                          leak_files+=("$path") ;;
+      esac
+    done < "$PROC_FILE"
+
+    # Python: async format, sync check (output goes to stderr: on Codex, text on stdout
+    # before the {} reply is invalid hook output)
+    if [ ${#py_files[@]} -gt 0 ]; then
+      if command -v ruff &>/dev/null; then
+        nohup ruff format "${py_files[@]}" </dev/null >/dev/null 2>&1 &
+        run_with_timeout 2 -- ruff check "${py_files[@]}" >&2 || true
+      fi
+    fi
+
+    # JS/TS: async fix only (eslint --fix rarely needs the caller's immediate attention)
+    if [ ${#js_files[@]} -gt 0 ]; then
+      if command -v eslint &>/dev/null; then
+        nohup eslint --fix "${js_files[@]}" </dev/null >/dev/null 2>&1 &
+      fi
+    fi
+
+    # Go: sync format (gofmt is fast, <100ms for typical files)
+    if [ ${#go_files[@]} -gt 0 ]; then
+      if command -v gofmt &>/dev/null; then
+        run_with_timeout 2 -- gofmt -w "${go_files[@]}" >&2 || true
+      fi
+    fi
+
+    # Java: async spotlessApply (slow — only if gradlew exists in cwd)
+    if [ "$java_has_files" = "true" ]; then
+      if [ -x "./gradlew" ]; then
+        nohup ./gradlew spotlessApply </dev/null >/dev/null 2>&1 &
+      fi
+    fi
+
+    # Process-leak scan: DoFlow's own identifiers (FR-###, agent-docs/, chain
+    # artifact names) reaching files that ship. Warns, never blocks — a
+    # legitimate occurrence exists in docs *about* DoFlow, and a false
+    # positive that failed a turn would cost more than the leak it prevented.
+    if [ ${#leak_files[@]} -gt 0 ]; then
+      leak_args=()
+      for p in "${leak_files[@]}"; do leak_args+=(--path "$p"); done
+      if [ -n "$DOFLOW_RUN" ]; then
+        leak_out="$(run_with_timeout 2 -- "$DOFLOW_RUN" leak-scan "${leak_args[@]}" 2>/dev/null || true)"
+        if [ -n "$leak_out" ] && printf '%s' "$leak_out" | grep -q ':[0-9]'; then
+          printf 'doflow: internal identifiers found in shipped files (warning, not a block):\n%s\n' \
+            "$leak_out" >&2
+        fi
+      fi
+    fi
+
+    rm -f "$PROC_FILE"
+  fi
+fi
+
+# ── 2. Stub detection ─────────────────────────────────────────────────────────
+
+# A stop that continues an earlier block has already been asked to finish once;
+# re-blocking it would loop, so only the lint queue above runs for it.
+[ "$(printf '%s' "$INPUT" | jq -r '.stop_hook_active // false' 2>/dev/null)" = "true" ] && exit 0
+
+# The payload's own last_assistant_message is the response being stopped on. A present key
+# (even null or empty) is authoritative: the transcript is only read when the key is absent.
+# jq filter for the transcript fallback: one JSON object per line, assistant text from three
+# shapes — Claude Code (.message with text blocks), Codex rollout (response_item .payload with
+# output_text blocks) and the flat {role,content} line. A partial or foreign line yields "".
+read -r -d '' LAST_ASSISTANT_JQ <<'JQ' || true
+def text: if type == "string" then .
+  elif type == "array" then [ .[]? | objects | select(.type == "text" or .type == "output_text") | .text | strings ] | join("\n")
+  else "" end;
+[ inputs | fromjson? | objects
+  | if ((.message | objects | .role) // null) == "assistant" then .message.content
+    elif .type == "response_item" and ((.payload | objects | .role) // null) == "assistant" then .payload.content
+    elif .role == "assistant" then .content
+    else empty end
+  | text | select(length > 0) ] | last // ""
+JQ
+
+if printf '%s' "$INPUT" | jq -e 'has("last_assistant_message")' >/dev/null 2>&1; then
+  LAST_ASSISTANT_CONTENT=$(printf '%s' "$INPUT" | jq -r '.last_assistant_message // ""' 2>/dev/null || true)
+else
+  # Only parse transcript if we have a path to it
+  [ -z "$TRANSCRIPT_PATH" ] && exit 0
+  [ -f "$TRANSCRIPT_PATH" ] || exit 0
+
+  # tail-scan is O(constant) regardless of transcript size — the last assistant
+  # entry is always near the end of the file. 200 lines covers any realistic
+  # single response without loading the entire (potentially multi-MB) transcript.
+  LAST_ASSISTANT_CONTENT=$(tail -n 200 "$TRANSCRIPT_PATH" | jq -Rnr "$LAST_ASSISTANT_JQ" 2>/dev/null || true)
+fi
+
+[ -z "$LAST_ASSISTANT_CONTENT" ] && exit 0
+
+# Text that only resembles a marker is cleaned before the match, outside ``` fences only, except
+# URLs: a markdown heading loses its leading hashes (## TODO list, # Todo) so a real marker later on
+# the same line still counts; "the // TODO comment" mentions (a marker, comment(s) or marker(s), then
+# the end of the sentence) are cut out; a URL, up to a space, quote, ) or //, is cut out
+# (http://todo-app.example.com). The text is lowercased, which the case-insensitive match ignores.
+# Every step is linear in the line length: a line with no "://" is not touched by the URL step,
+# and the URL step splits on "://" and trims each scheme (at most 32 characters) backwards.
+# Ceiling: an unfenced title-case `# Todo`/`# Fixme` at the start of a line reads as a heading, and an
+# unfenced `## TODO: x` as a heading, not a Python comment.
+STUB_TEXT=$(printf '%s\n' "$LAST_ASSISTANT_CONTENT" | awk '
+function strip_urls(s,   n, parts, k, cur, out, L, m, frag) {
+  if (index(s, "://") == 0) return s
+  n = split(s, parts, "://")
+  cur = parts[1]; out = ""
+  for (k = 2; k <= n; k++) {
+    L = length(cur); m = 0
+    while (m < 32 && m < L && substr(cur, L - m, 1) ~ /[A-Za-z0-9+.-]/) m++
+    while (m > 0 && substr(cur, L - m + 1, 1) !~ /[A-Za-z]/) m--
+    if (m > 0) {
+      out = out substr(cur, 1, L - m)
+      frag = parts[k]
+      cur = match(frag, urlend) ? substr(frag, RSTART) : ""
+    } else {
+      out = out cur "://"
+      cur = parts[k]
+    }
+  }
+  return out cur
+}
+BEGIN {
+  q = "\047"
+  urlend = "[[:space:]\"" q "`)]|//"
+  mention = "(#|//)[[:space:]]*(todo|fixme)s?[[:space:]]+(comments?|markers?)[[:space:]]*([.,;!?)]|$)"
+}
+/^[[:space:]]*(```|~~~)/ { fence = !fence }
+{
+  if (!fence) {
+    if ($0 ~ /^ ? ? ?###*[[:space:]]+/) sub(/^ ? ? ?#+[[:space:]]+/, "")
+    else if ($0 ~ /^ ? ? ?#[[:space:]]+(Todo|Fixme)([^[:alnum:]_]|$)/) sub(/^ ? ? ?#[[:space:]]+/, "")
+  }
+  line = tolower($0)
+  line = strip_urls(line)
+  if (!fence) gsub(mention, " ", line)
+  print line
+}') || STUB_TEXT=$LAST_ASSISTANT_CONTENT
+
+# Search extracted content for unfinished-work markers
+# Match stubs only inside code comment context to avoid false positives from
+# explanatory prose (e.g. "I removed the TODO comment" should not trigger).
+# POSIX ERE has no \b; require what follows TODO/FIXME/stub to be a
+# non-word character or end-of-string instead, so "TODOX" doesn't match.
+STUB_PATTERN='(#|//)[[:space:]]*(TODO|FIXME)([^[:alnum:]_]|$)|raise NotImplementedError|throw new Error\(.*[Nn]ot [Ii]mplemented|(#|//)[[:space:]]*stub([^[:alnum:]_]|$)'
+
+if grep -qiE -- "$STUB_PATTERN" <<<"$STUB_TEXT" 2>/dev/null; then
+  # Block a given message once: the continuation that follows is judged on new text, and a
+  # harness with no stop_hook_active would otherwise be blocked on this one forever. State is
+  # per session, or per transcript when the harness sends no session_id; any failure here
+  # leaves the block in force only for this call.
+  GUARD_KEY="$SESSION_ID"
+  [ -z "$GUARD_KEY" ] && GUARD_KEY="t$(printf '%s' "$TRANSCRIPT_PATH" | cksum | cut -d' ' -f1)"
+  GUARD_FILE="$(ensure_session_dir "$GUARD_KEY" 2>/dev/null)/stop-last-blocked" || GUARD_FILE=""
+  MESSAGE_SUM=$(printf '%s' "$LAST_ASSISTANT_CONTENT" | cksum 2>/dev/null) || MESSAGE_SUM=""
+  if [ -n "$MESSAGE_SUM" ] && [ -n "$GUARD_FILE" ] && [ "$(cat "$GUARD_FILE" 2>/dev/null)" = "$MESSAGE_SUM" ]; then
+    exit 0
+  fi
+  [ -n "$MESSAGE_SUM" ] && [ -n "$GUARD_FILE" ] && { printf '%s\n' "$MESSAGE_SUM" > "$GUARD_FILE"; } 2>/dev/null || true
+  echo "[stop-check] The last response contains an unfinished-work marker (TODO/FIXME/stub comment or a not-implemented raise/throw)." >&2
+  exit 2
+fi
+
+exit 0

package/core/harnesses/shared/hooks/policies/subagent-audit.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# subagent-audit.sh — Canonical Policy Library: SubagentStart + SubagentStop hook
+# (pure observability, no deny path)
+#
+# 022-hooks-remaining-duplication: claude and codex's copies were byte-identical — moved here as
+# the single canonical copy. Gemini has no SubagentStart/SubagentStop-equivalent event.
+#
+# Appends {timestamp, session_id, event, agent_type, agent_id} to a session-scoped audit log.
+# Today there is zero record of which of the installed agents/ specialists actually run, how often, or
+# whether one is invoked outside its intended use (e.g. everything routing through general-purpose
+# instead of do-code-review/security-engineer) — this hook is the evidence base a future policy
+# hook (e.g. an agent-aware pre-bash-guard extension) would need before writing rules on a guess.
+# Per agent-docs/research/hook-governance-agent-tool-mcp-skill.md §3.1: pure logging, no deny path,
+# safe to ship immediately, and the recommended first step before any tighter agent governance.
+#
+# Multi-session safe: writes only to sessions/{session_id}/subagent-audit.log.
+# Must never exit non-zero or block a subagent from starting/stopping.
+
+set -euo pipefail
+# shellcheck source=lib.sh
+source "$(dirname "$0")/lib.sh"
+require_jq
+
+INPUT=$(cat)
+SESSION_ID=$(json_field "$INPUT" ".session_id")
+
+# Guard: if we can't determine the session, nothing to do
+[[ -z "$SESSION_ID" ]] && exit 0
+
+EVENT=$(json_field "$INPUT" ".hook_event_name")
+AGENT_TYPE=$(json_field "$INPUT" ".agent_type")
+AGENT_ID=$(json_field "$INPUT" ".agent_id")
+TIMESTAMP=$(date -u +%FT%TZ)
+
+SESSION_PATH=$(ensure_session_dir "$SESSION_ID")
+
+jq -nc \
+  --arg ts "$TIMESTAMP" \
+  --arg session "$SESSION_ID" \
+  --arg event "$EVENT" \
+  --arg agent_type "$AGENT_TYPE" \
+  --arg agent_id "$AGENT_ID" \
+  '{timestamp: $ts, session_id: $session, event: $event, agent_type: $agent_type, agent_id: $agent_id}' \
+  >> "$SESSION_PATH/subagent-audit.log" 2>/dev/null || true
+
+exit 0