Files
planning-with-files/scripts/ledger-summary.sh
T
OthmanAdi 3749f86ac3 fix: bind explicit plan selectors, floor slug modes on the project root, and classify doctor output on the data frame
Three defects reported by Raymond Manaloto (@sortakool), each reproduced on
Windows with Git Bash before any code changed. Two of them let a session work
on a plan nobody selected; the third made the diagnostic that should have
caught them report PASS.

closes #237: an explicit PLAN_ID was a hint, not a binding

resolve_from_env returned 1 both when no selector was set and when the selector
was rejected, so a PLAN_ID of valid slug shape naming no directory fell through
to .active_plan and then to newest-by-mtime. attest-plan.sh locked that other
plan at rc=0 and injection followed it. The guard in attest-plan.sh written for
exactly this case was unreachable, because the resolver never returned empty.
commands/plan-attest.md has promised the opposite since v3.9.0.

A non-empty PLAN_ID now resolves or stops, for every rejection reason: slug
shape (traversal included), naming no directory, or failing containment. An
empty value still means unset, which init-session.sh depends on. The rule went
into every resolver, because they disagreed otherwise: resolve-plan-dir.sh,
resolve-plan-dir.ps1, the inline resolver inside inject-plan.sh, and the
Hermes, OpenCode and Pi plugin resolvers. v3.14.0 had made the two plugin
resolvers fall through to match the shell; that parity was right and its target
was wrong.

Fixing the resolver alone would have moved the bug rather than removed it, so
every consumer was audited. check-complete.sh would have read the root plan's
completion state, which decides whether an autonomous run may stop.
ledger-summary.sh feeds phase counts into autonomous turns. phase-status.sh and
ledger-append.sh write into the directory they pick. The five Codex hooks call
the resolver directly and each fell through to the legacy root, stop.sh and
pre-compact.sh included. All of them now stop on a rejected selector, and the
once-per-turn routes print a notice, because a fail-closed path with no stated
cause would trade a wrong-plan bug for a silent one.

closes #238: a slug plan with no .mode bypassed the project's root .mode

A project makes attestation mandatory by committing a root .mode, a reviewed
project setting. inject-plan.sh read the slug's .mode and never the root's, and
init-session.sh writes no .mode unless --autonomous or --gated was passed, so
init-session.sh <name>, which /plan runs, produced a plan with no attestation
requirement and full injection. The policy was a flag the agent chose at plan
creation.

The root .mode is now a floor. Strictness-raising tokens count from either
file, so a slug may raise and never lower; the one strictness-lowering token,
plan-guard-off, needs the root's agreement. The same floor applies to the
completion gate in check-complete.sh and check-complete.ps1, which read .mode
the same way and had the same bypass, and to the Hermes and OpenCode plugins.
init-session.sh seeds a new slug from the root .mode so the effective policy is
visible in the plan directory, not only in the resolver. With no root .mode
present the effective token set is exactly the slug's, so existing projects are
unchanged.

closes #236: plan-doctor.sh reported PASS on a fully dark-hooks state

The injection check substring-matched five control strings against output that
carries the plan body verbatim inside the BEGIN-PWF-DATA fences. A plan whose
phase line read "fix the false PLAN TAMPERED warning in plan-doctor" reported a
hash mismatch while correctly attested. Worse, the PWF_PLAN_ROOT arm matched a
literal that is not a substring of what inject-plan.sh emits, so the arm was
dead code and execution fell to the success arm: PWF_PLAN_ROOT=/nonexistent
printed "PASS injection: emits plan context (123 bytes)" while nothing was
injected, counting the refusal notice's own bytes as plan context. The file's
own comment four lines above already warned against exactly that.

Classification now branches on the frame. Every refusal path exits before
frame_file runs, so a frame proves injection happened and unframed output is by
construction a notice. The default arm warns, so a reworded or translated
banner degrades noisily instead of silently. The stale literal is corrected
against the emitting echo.

Tests: Python suite 653 to 696, OpenCode Vitest 28 to 34. New files
test_plan_selector_binding.py, test_root_mode_floor.py and
test_plan_doctor_classification.py; new arms in test_resolver_parity.py,
test_resolve_plan_dir.py, test_resolver_plan_root_pin.py and
test_hermes_first_class.py. Five existing tests asserted the fall-through and
were rewritten to assert the refusal, keeping their original security
assertion. Each suite carries a control arm: two first drafts passed on
fixtures that could not have failed, a gate assertion over a plan with every
phase complete and a parallel-write-guard assertion over a plan with nothing
checked to lose.
2026-09-03 00:23:03 +02:00

172 lines
6.5 KiB
Bash
Executable File

#!/bin/sh
# planning-with-files: emit a fixed-shape, cache-stable run-ledger summary (v3).
#
# This replaces raw `tail -20 progress.md` injection in autonomous mode. The
# output is synthesized from the machine ledger and task_plan.md status counts
# only: NO free text from disk reaches the model context, and there are NO
# timestamps, so the injected block is KV-cache stable by construction
# (architecture C3 injection rule).
#
# Plan-dir resolution:
# 0. Explicit plan-dir argument (issue #212, see below)
# 1. $PLAN_ID env var -> ./.planning/$PLAN_ID/ (via resolve-plan-dir.sh)
# 2. ./.planning/.active_plan (via resolve-plan-dir.sh)
# 3. Newest ./.planning/<dir>/ by mtime (via resolve-plan-dir.sh)
# 4. Legacy: project root
#
# Usage:
# sh scripts/ledger-summary.sh [plan-dir]
#
# The optional argument is the caller's already-resolved plan directory and
# wins over self-resolution: inject-plan.sh passes the dir it resolved,
# because a cwd-based re-resolution here would pair a PWF_PLAN_ROOT-pinned
# plan's body with the PARENT project's phase counts and agent events — a
# false termination signal for an autonomous loop. No argument keeps the
# self-resolution above unchanged.
#
# Output block (stable shape):
# === RUN LEDGER ===
# entries: <N>
# phases: <complete>/<total> complete
# in_progress: <phase heading or none>
# agent <name>: <last event type>
# ...
# ==================
#
# When no plan directory is determinable at all (argument names a missing dir,
# or no argument AND resolve-plan-dir.sh is not next to this script), the block
# is replaced by a clearly marked unavailable state instead of a confident
# "phases: 0/0 complete" — see emit_unavailable below.
set -u
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
RESOLVER="${SCRIPT_DIR}/resolve-plan-dir.sh"
ARG_DIR="${1:-}"
# Loud degradation: when the counts below are NOT computable — the caller
# named a plan dir that is gone, or no dir was passed and the resolver is
# missing next to this script — emit a clearly marked unavailable block
# instead of a confident "phases: 0/0 complete" + "in_progress: none", which
# an autonomous loop would read as its termination signal. Fixed strings
# only, so the block stays byte-stable (no timestamps, no free text from
# disk). Exit 0: this feeds hook output and must never error the agent loop.
emit_unavailable() {
printf '=== RUN LEDGER ===\n'
printf 'ledger: unavailable (%s)\n' "$1"
printf '==================\n'
exit 0
}
PLAN_DIR=""
if [ -n "${ARG_DIR}" ]; then
# The caller already resolved the plan dir; never second-guess it with a
# cwd-based re-resolution (that is exactly the parent/child mismatch this
# argument exists to prevent). If the named dir is gone, say so.
[ -d "${ARG_DIR}" ] || emit_unavailable "plan dir argument does not exist"
PLAN_DIR="${ARG_DIR}"
elif [ -f "${RESOLVER}" ]; then
PLAN_DIR="$(sh "${RESOLVER}" 2>/dev/null)"
if [ -z "${PLAN_DIR}" ] || [ ! -d "${PLAN_DIR}" ]; then
# Explicit selectors are bindings, not hints (issue #237). A rejected
# PLAN_ID or PWF_PLAN_ROOT must not fall back to the cwd: this summary
# is injected into autonomous turns, so reporting the ROOT plan's
# phase counts under a mistyped pin feeds the loop another plan's
# termination signal. Degrade loudly, the same way a missing resolver
# already does.
if [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
emit_unavailable "explicit PLAN_ID or PWF_PLAN_ROOT did not resolve"
fi
PLAN_DIR="."
fi
else
emit_unavailable "resolve-plan-dir.sh missing and no plan dir argument"
fi
if [ "${PLAN_DIR}" = "." ]; then
PLAN_FILE="./task_plan.md"
else
PLAN_FILE="${PLAN_DIR}/task_plan.md"
fi
# --- Phase counts: identical grep patterns to check-complete.sh ---
TOTAL=0
COMPLETE=0
IN_PROGRESS=0
IN_PROGRESS_HEADING="none"
if [ -f "${PLAN_FILE}" ]; then
TOTAL=$(grep -c "### Phase" "${PLAN_FILE}" 2>/dev/null || true)
COMPLETE=$(grep -cF "**Status:** complete" "${PLAN_FILE}" 2>/dev/null || true)
IN_PROGRESS=$(grep -cF "**Status:** in_progress" "${PLAN_FILE}" 2>/dev/null || true)
# Fallback to inline [status] format when **Status:** is absent.
if [ "${COMPLETE}" -eq 0 ] && [ "${IN_PROGRESS}" -eq 0 ]; then
c2=$(grep -c "\[complete\]" "${PLAN_FILE}" 2>/dev/null || true)
i2=$(grep -c "\[in_progress\]" "${PLAN_FILE}" 2>/dev/null || true)
: "${c2:=0}"
: "${i2:=0}"
if [ "${c2}" -gt 0 ] || [ "${i2}" -gt 0 ]; then
COMPLETE="${c2}"
IN_PROGRESS="${i2}"
fi
fi
# Heading of the FIRST phase whose status block is in_progress. We walk
# phase headings and look ahead for the status line so the summary names
# the active phase without leaking any plan body text beyond the heading.
heading=""
state=""
# shellcheck disable=SC2162
while IFS= read -r line; do
case "${line}" in
"### Phase"*)
heading="${line}"
;;
*"**Status:** in_progress"*)
if [ -n "${heading}" ]; then
IN_PROGRESS_HEADING="${heading}"
break
fi
;;
*"[in_progress]"*)
if [ -n "${heading}" ] && [ "${IN_PROGRESS_HEADING}" = "none" ]; then
IN_PROGRESS_HEADING="${heading}"
fi
;;
esac
done < "${PLAN_FILE}"
fi
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
# --- Ledger stats: total entries + last event type per agent ---
TOTAL_ENTRIES=0
for f in "${PLAN_DIR}"/ledger-*.jsonl; do
[ -f "${f}" ] || continue
n=$(grep -c '"tick"' "${f}" 2>/dev/null || true)
: "${n:=0}"
TOTAL_ENTRIES=$((TOTAL_ENTRIES + n))
done
printf '=== RUN LEDGER ===\n'
printf 'entries: %s\n' "${TOTAL_ENTRIES}"
printf 'phases: %s/%s complete\n' "${COMPLETE}" "${TOTAL}"
printf 'in_progress: %s\n' "${IN_PROGRESS_HEADING}"
# Per-agent last event type. Agent name comes from the filename
# (ledger-<agent>.jsonl); the last event is parsed from the final line.
for f in "${PLAN_DIR}"/ledger-*.jsonl; do
[ -f "${f}" ] || continue
base="$(basename "${f}")"
agent="${base#ledger-}"
agent="${agent%.jsonl}"
last_line="$(tail -n 1 "${f}" 2>/dev/null)"
last_event="$(printf '%s' "${last_line}" | sed -n 's/.*"event"[[:space:]]*:[[:space:]]*"\([A-Za-z_]*\)".*/\1/p')"
[ -z "${last_event}" ] && last_event="none"
printf 'agent %s: %s\n' "${agent}" "${last_event}"
done
printf '==================\n'
exit 0