1#!/usr/bin/env bash
2# Check if all phases in task_plan.md are complete
3# Default invocation: advisory echo, always exits 0 (Stop hook status report).
4# With --gate: deliberate completion gate, opt-in per plan via <plan-dir>/.mode.
5# Used by Stop hook to report task completion status.
6#
7# Plan-file resolution (v2.40+):
8#   1. $1 (explicit path) — first non-flag positional argument
9#   2. resolve-plan-dir.sh: $PLAN_ID env → .planning/.active_plan → newest mtime
10#   3. Legacy ./task_plan.md
11#
12# This restores slug-mode parity: the Stop hook and any caller invoking with
13# zero args now respects the active plan dir instead of silently defaulting to
14# the legacy root path.
15#
16# Gate mode (v3, --gate flag):
17#   The gate is OFF unless ALL of these hold (design "Gate decision table"):
18#     1. <plan-dir>/.mode exists and contains "gate" (explicit opt-in)
19#     2. an in_progress phase exists (not merely complete<total)
20#     3. the Stop hook input JSON on stdin does not set stop_hook_active=true
21#     4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
22#     5. the ledger advanced since the last block (stall → allow stop)
23#   When all hold, it emits a single-line block-decision JSON on stdout and
24#   exits 0. Otherwise it falls back to advisory output and exits 0.
25#   Without --gate, or in non-gated mode, behavior is byte-equivalent to v2.43.
26#
27# Stdin handling: the Claude Code Stop hook pipes a JSON payload on stdin. To
28# avoid hanging when nothing is piped, stdin is read ONLY when fd 0 is not a
29# TTY ([ -t 0 ]). Hook-piped input is EOF-terminated, so the read returns; an
30# interactive terminal (TTY) is skipped entirely. No data on stdin is treated
31# as stop_hook_active=false.
32 
33GATE=0
34PLAN_FILE=""
35for _arg in "$@"; do
36    case "$_arg" in
37        --gate) GATE=1 ;;
38        *)
39            if [ -z "$PLAN_FILE" ]; then
40                PLAN_FILE="$_arg"
41            fi
42            ;;
43    esac
44done
45 
46PLAN_DIR=""
47if [ -n "${PLAN_FILE}" ]; then
48    PLAN_DIR="$(dirname "${PLAN_FILE}")"
49else
50    SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd 2>/dev/null)" || SCRIPT_DIR="."
51    RESOLVER="${SCRIPT_DIR}/resolve-plan-dir.sh"
52    RESOLVED_DIR=""
53    if [ -f "${RESOLVER}" ]; then
54        RESOLVED_DIR="$(sh "${RESOLVER}" 2>/dev/null)"
55    fi
56    if [ -n "${RESOLVED_DIR}" ] && [ -f "${RESOLVED_DIR}/task_plan.md" ]; then
57        PLAN_FILE="${RESOLVED_DIR}/task_plan.md"
58        PLAN_DIR="${RESOLVED_DIR}"
59    else
60        PLAN_FILE="task_plan.md"
61        PLAN_DIR="."
62    fi
63fi
64 
65if [ ! -f "$PLAN_FILE" ]; then
66    echo "[planning-with-files] No task_plan.md found — no active planning session."
67    exit 0
68fi
69 
70# Count total phases
71TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
72 
73# Count both formats per field and keep the larger of the two. A plan may mix
74# '**Status:** pending' on one phase with '[in_progress]' on another; counting
75# only the primary format (and falling back to inline ONLY when all three
76# primaries are zero) lost the inline count and let an in_progress plan slip
77# past the gate. Per-field max preserves the legacy single-format result
78# (the other format contributes 0) while catching mixed plans.
79COMPLETE_PRIMARY=$(grep -cF "**Status:** complete" "$PLAN_FILE" || true)
80IN_PROGRESS_PRIMARY=$(grep -cF "**Status:** in_progress" "$PLAN_FILE" || true)
81PENDING_PRIMARY=$(grep -cF "**Status:** pending" "$PLAN_FILE" || true)
82 
83COMPLETE_INLINE=$(grep -c "\[complete\]" "$PLAN_FILE" || true)
84IN_PROGRESS_INLINE=$(grep -c "\[in_progress\]" "$PLAN_FILE" || true)
85PENDING_INLINE=$(grep -c "\[pending\]" "$PLAN_FILE" || true)
86 
87: "${COMPLETE_PRIMARY:=0}"; : "${IN_PROGRESS_PRIMARY:=0}"; : "${PENDING_PRIMARY:=0}"
88: "${COMPLETE_INLINE:=0}";  : "${IN_PROGRESS_INLINE:=0}";  : "${PENDING_INLINE:=0}"
89 
90if [ "$COMPLETE_INLINE" -gt "$COMPLETE_PRIMARY" ]; then COMPLETE="$COMPLETE_INLINE"; else COMPLETE="$COMPLETE_PRIMARY"; fi
91if [ "$IN_PROGRESS_INLINE" -gt "$IN_PROGRESS_PRIMARY" ]; then IN_PROGRESS="$IN_PROGRESS_INLINE"; else IN_PROGRESS="$IN_PROGRESS_PRIMARY"; fi
92if [ "$PENDING_INLINE" -gt "$PENDING_PRIMARY" ]; then PENDING="$PENDING_INLINE"; else PENDING="$PENDING_PRIMARY"; fi
93 
94# Default to 0 if empty
95: "${TOTAL:=0}"
96: "${COMPLETE:=0}"
97: "${IN_PROGRESS:=0}"
98: "${PENDING:=0}"
99 
100# advisory_report: the v2.43 status echo. Always exit 0 after calling.
101advisory_report() {
102    if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
103        echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL). If the user has additional work, add new phases to task_plan.md before starting."
104    else
105        echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete). Update progress.md before stopping."
106        if [ "$IN_PROGRESS" -gt 0 ]; then
107            echo "[planning-with-files] $IN_PROGRESS phase(s) still in progress."
108        fi
109        if [ "$PENDING" -gt 0 ]; then
110            echo "[planning-with-files] $PENDING phase(s) pending."
111        fi
112    fi
113}
114 
115# ---- Default (advisory) path: byte-equivalent to v2.43 ----
116if [ "$GATE" -ne 1 ]; then
117    advisory_report
118    exit 0
119fi
120 
121# ---- Gate path (--gate). Resolves to advisory unless every guard says block. ----
122 
123# Guard 1: gated mode. The .mode file must contain "gate". Absent or other
124# content means advisory mode (legacy behavior preserved).
125MODE_FILE="${PLAN_DIR}/.mode"
126if [ ! -f "${MODE_FILE}" ] || ! grep -q "gate" "${MODE_FILE}" 2>/dev/null; then
127    advisory_report
128    exit 0
129fi
130 
131# Guard 3: stop_hook_active. Read the Stop hook JSON from stdin only when fd 0
132# is not a TTY (see header). A true value means we are already inside a forced
133# continuation; allow the stop to avoid runaway recursion.
134STDIN_JSON=""
135if [ ! -t 0 ]; then
136    STDIN_JSON="$(cat 2>/dev/null)"
137fi
138# Anchor on the VALUE: "stop_hook_active" immediately followed (allowing
139# whitespace and the colon) by true. A bare glob like *stop_hook_active*true*
140# false-positives on '{"stop_hook_active": false, "other": true}', which would
141# silently disable the gate. Newlines are collapsed so the match works whether
142# the payload is pretty-printed or single-line.
143STOP_HOOK_ACTIVE="$(
144    printf '%s' "${STDIN_JSON}" \
145        | tr '\n' ' ' \
146        | sed -n 's/.*"stop_hook_active"[[:space:]]*:[[:space:]]*true.*/FOUND/p'
147)"
148if [ "${STOP_HOOK_ACTIVE}" = "FOUND" ]; then
149    advisory_report
150    exit 0
151fi
152 
153# Guard 2: an in_progress phase must exist. Merely complete<total is a normal
154# state and must NOT block (issue #178 lesson).
155if [ "$IN_PROGRESS" -le 0 ]; then
156    advisory_report
157    exit 0
158fi
159 
160# ledger_line_count: total lines across all <plan-dir>/ledger-*.jsonl files.
161# Echoes a single integer (0 when no ledger files exist).
162ledger_line_count() {
163    _total=0
164    for _lf in "${PLAN_DIR}"/ledger-*.jsonl; do
165        [ -f "${_lf}" ] || continue
166        _n="$(grep -c '' "${_lf}" 2>/dev/null || echo 0)"
167        _total=$((_total + _n))
168    done
169    printf "%s" "${_total}"
170}
171 
172CAP="${PWF_GATE_CAP:-20}"
173case "${CAP}" in
174    ''|*[!0-9]*) CAP=20 ;;
175esac
176 
177BLOCKS_FILE="${PLAN_DIR}/.stop_blocks"
178BLOCKS="$(cat "${BLOCKS_FILE}" 2>/dev/null || echo 0)"
179case "${BLOCKS}" in
180    ''|*[!0-9]*) BLOCKS=0 ;;
181esac
182 
183LEDGER_FILE="${PLAN_DIR}/.gate_last_ledger"
184LEDGER_PREV="$(cat "${LEDGER_FILE}" 2>/dev/null || echo 0)"
185case "${LEDGER_PREV}" in
186    ''|*[!0-9]*) LEDGER_PREV=0 ;;
187esac
188LEDGER_NOW="$(ledger_line_count)"
189 
190# Guard 4: block-count cap. At or over the cap, allow the stop.
191if [ "${BLOCKS}" -ge "${CAP}" ]; then
192    advisory_report
193    echo "[planning-with-files] gate cap reached ($BLOCKS/$CAP) — allowing stop."
194    exit 0
195fi
196 
197# Guard 5: stall detection. If we have blocked before (BLOCKS > 0) and the
198# ledger line count has not advanced since the last block, nothing progressed:
199# allow the stop instead of looping.
200if [ "${BLOCKS}" -gt 0 ] && [ "${LEDGER_NOW}" -eq "${LEDGER_PREV}" ]; then
201    advisory_report
202    echo "[planning-with-files] no progress since last gate block — allowing stop."
203    exit 0
204fi
205 
206# All guards passed: block the stop.
207# json_escape: escape a string for safe inclusion in a JSON string literal.
208# Escapes backslash and double-quote, then neutralizes every bare control
209# character JSON forbids (0x01-0x1F) by mapping it to a space. A phase heading
210# may carry a literal tab or other control byte; left raw it produces invalid
211# JSON ("Bad control character in string literal") that the Stop hook rejects.
212json_escape() {
213    printf "%s" "$1" \
214        | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' \
215        | tr '\001-\037' ' '
216}
217 
218# first_in_progress_phase: heading text of the first phase whose Status is
219# in_progress. Reads the plan top-to-bottom, remembers the most recent
220# "### " heading, and prints it (with the "### " prefix stripped) at the first
221# in_progress status line. Plain text only — no plan body beyond the heading.
222first_in_progress_phase() {
223    awk '
224        /^### / { heading = substr($0, 5); next }
225        /\*\*Status:\*\* in_progress/ { print heading; exit }
226        /\[in_progress\]/            { print heading; exit }
227    ' "$PLAN_FILE"
228}
229 
230PHASE_NAME="$(first_in_progress_phase)"
231if [ -z "${PHASE_NAME}" ]; then
232    PHASE_NAME="unknown phase"
233fi
234PHASE_ESCAPED="$(json_escape "${PHASE_NAME}")"
235 
236NEW_BLOCKS=$((BLOCKS + 1))
237printf "%s\n" "${NEW_BLOCKS}" > "${BLOCKS_FILE}" 2>/dev/null || true
238printf "%s\n" "${LEDGER_NOW}" > "${LEDGER_FILE}" 2>/dev/null || true
239 
240printf '{"decision":"block","reason":"[planning-with-files] Gated plan incomplete: phase '\''%s'\'' is in_progress (%s/%s complete, gate block %s/%s). Finish or update the plan, then stop."}\n' \
241    "${PHASE_ESCAPED}" "${COMPLETE}" "${TOTAL}" "${NEW_BLOCKS}" "${CAP}"
242exit 0
243