planning-with-files 3.9.0 → 3.10.0

package/scripts/ledger-summary.sh

@@ -0,0 +1,162 @@
+#!/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
+        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

package/scripts/phase-status.ps1

@@ -0,0 +1,175 @@
+#requires -Version 5.0
+<#
+.SYNOPSIS
+    Set the status of one phase in task_plan.md (PowerShell mirror, v3).
+
+.DESCRIPTION
+    The ONLY sanctioned concurrent-safe writer of task_plan.md status lines. The
+    orchestrator owns task_plan.md; workers NEVER edit it directly. The edit is
+    a read-modify-write under an exclusive lock on the <plan-dir>\.write_lock
+    sentinel, with an atomic temp-file + move swap so a torn write can never
+    leave a half-rewritten plan on disk (architecture C4).
+
+    Editing task_plan.md changes its SHA, so the orchestrator must re-attest at
+    phase boundaries (see attest-plan.ps1).
+
+    Plan-dir resolution matches resolve-plan-dir.ps1:
+      1. $env:PLAN_ID -> .\.planning\$PLAN_ID\
+      2. .\.planning\.active_plan
+      3. Newest .\.planning\<dir>\ by LastWriteTime
+      4. Legacy: project root .\task_plan.md
+
+    Exits 1 with a message if the phase does not exist or the status is invalid.
+
+.PARAMETER Phase
+    Phase number (positive integer).
+
+.PARAMETER Status
+    New status: pending, in_progress, or complete.
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true, Position = 0)]
+    [string] $Phase,
+
+    [Parameter(Mandatory = $true, Position = 1)]
+    [string] $Status
+)
+
+$ErrorActionPreference = "Stop"
+
+function Resolve-PlanFile {
+    $planRoot = Join-Path (Get-Location) ".planning"
+
+    if ($env:PLAN_ID) {
+        $candidate = Join-Path $planRoot $env:PLAN_ID
+        $planFile  = Join-Path $candidate "task_plan.md"
+        if (Test-Path -LiteralPath $planFile) { return (Resolve-Path -LiteralPath $planFile).Path }
+    }
+
+    $activePointer = Join-Path $planRoot ".active_plan"
+    if (Test-Path -LiteralPath $activePointer) {
+        $planId = (Get-Content -LiteralPath $activePointer -Raw).Trim()
+        if ($planId) {
+            $candidate = Join-Path $planRoot $planId
+            $planFile  = Join-Path $candidate "task_plan.md"
+            if (Test-Path -LiteralPath $planFile) { return (Resolve-Path -LiteralPath $planFile).Path }
+        }
+    }
+
+    if (Test-Path -LiteralPath $planRoot -PathType Container) {
+        $newest = Get-ChildItem -LiteralPath $planRoot -Directory -ErrorAction SilentlyContinue |
+            Where-Object { -not $_.Name.StartsWith(".") } |
+            Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") } |
+            Sort-Object LastWriteTime -Descending |
+            Select-Object -First 1
+        if ($newest) {
+            return (Resolve-Path -LiteralPath (Join-Path $newest.FullName "task_plan.md")).Path
+        }
+    }
+
+    $legacy = Join-Path (Get-Location) "task_plan.md"
+    if (Test-Path -LiteralPath $legacy) {
+        return (Resolve-Path -LiteralPath $legacy).Path
+    }
+
+    return $null
+}
+
+# Validate phase number is a positive integer.
+if ($Phase -notmatch '^[0-9]+$') {
+    Write-Error ("[phase-status] phase number must be a positive integer, got '" + $Phase + "'.")
+    exit 1
+}
+
+# Validate status value against the allowlist.
+$validStatus = @("pending", "in_progress", "complete")
+if ($validStatus -notcontains $Status) {
+    Write-Error ("[phase-status] invalid status '" + $Status + "' (allowed: pending, in_progress, complete).")
+    exit 1
+}
+
+$planFile = Resolve-PlanFile
+if (-not $planFile) {
+    Write-Error "[phase-status] No task_plan.md found. Create a plan first."
+    exit 1
+}
+
+$planDir  = Split-Path -Parent $planFile
+$lockFile = Join-Path $planDir ".write_lock"
+
+# Acquire an exclusive lock on the sentinel so concurrent writers serialize.
+$fs = $null
+$acquired = $false
+for ($i = 0; $i -lt 50 -and -not $acquired; $i++) {
+    try {
+        $fs = [System.IO.File]::Open($lockFile, [System.IO.FileMode]::OpenOrCreate, [System.IO.FileAccess]::ReadWrite, [System.IO.FileShare]::None)
+        $acquired = $true
+    } catch {
+        Start-Sleep -Milliseconds 100
+    }
+}
+
+$tmpFile = $planFile + ".tmp." + $PID
+$rc = 0
+try {
+    $lines = Get-Content -LiteralPath $planFile
+
+    # Confirm the phase heading exists.
+    $headingRe = '^### Phase ' + $Phase + '([^0-9]|$)'
+    if (-not ($lines | Where-Object { $_ -match $headingRe })) {
+        Write-Error ("[phase-status] Phase " + $Phase + " not found in " + $planFile + ".")
+        $rc = 1
+    } else {
+        $inBlock = $false
+        $done = $false
+        $out = New-Object System.Collections.Generic.List[string]
+        foreach ($line in $lines) {
+            $emit = $line
+            if ($line -match '^### Phase ') {
+                $rest = $line -replace '^### Phase ', ''
+                $num = $rest -replace '[^0-9].*$', ''
+                if (($num -eq $Phase) -and (-not $done)) {
+                    $inBlock = $true
+                } else {
+                    $inBlock = $false
+                }
+            } elseif ($inBlock -and (-not $done) -and ($line -match '\*\*Status:\*\*')) {
+                $prefix = $line -replace '\*\*Status:\*\*.*$', ''
+                $emit = $prefix + '**Status:** ' + $Status
+                $inBlock = $false
+                $done = $true
+            }
+            $out.Add($emit)
+        }
+
+        if (-not $done) {
+            Write-Error ("[phase-status] No **Status:** line found for Phase " + $Phase + ".")
+            $rc = 1
+        } else {
+            # Atomic-enough swap: write temp, then move over the target.
+            # Write BOM-less UTF-8 (platform-major): Set-Content -Encoding utf8 on
+            # Windows PowerShell 5.1 prepends a UTF-8 BOM (EF BB BF). The temp file
+            # then replaces task_plan.md, so every phase-status call from PS 5.1
+            # changes the file's leading bytes. If the plan was created on Linux or
+            # macOS (no BOM), the stored attestation SHA-256 no longer matches and
+            # inject-plan.sh blocks all further injection as [PLAN TAMPERED]. A
+            # UTF8Encoding constructed with $false emits no BOM on every PS version.
+            $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+            [System.IO.File]::WriteAllLines($tmpFile, $out, $utf8NoBom)
+            Move-Item -LiteralPath $tmpFile -Destination $planFile -Force
+        }
+    }
+} catch {
+    Write-Error ("[phase-status] " + $_.Exception.Message)
+    $rc = 1
+} finally {
+    if ($fs) { $fs.Close(); $fs.Dispose() }
+    if (Test-Path -LiteralPath $lockFile) { Remove-Item -LiteralPath $lockFile -Force -ErrorAction SilentlyContinue }
+    if (Test-Path -LiteralPath $tmpFile) { Remove-Item -LiteralPath $tmpFile -Force -ErrorAction SilentlyContinue }
+}
+
+if ($rc -ne 0) { exit 1 }
+
+Write-Output ("[phase-status] Phase " + $Phase + " -> " + $Status + " in " + $planFile)
+exit 0

package/scripts/phase-status.sh

@@ -0,0 +1,158 @@
+#!/bin/sh
+# planning-with-files: set the status of one phase in task_plan.md (v3).
+#
+# This is the ONLY sanctioned concurrent-safe writer of task_plan.md status
+# lines. The orchestrator owns task_plan.md; workers NEVER edit it directly.
+# All status edits go through this read-modify-write under an advisory flock on
+# the <plan-dir>/.write_lock sentinel, with an atomic temp-file + mv swap so a
+# torn write can never leave a half-rewritten plan on disk (architecture C4).
+#
+# Note: editing task_plan.md changes its SHA, so the orchestrator must
+# re-attest at phase boundaries (see attest-plan.sh).
+#
+# Plan-dir resolution (via resolve-plan-dir.sh):
+#   1. $PLAN_ID env var -> ./.planning/$PLAN_ID/
+#   2. ./.planning/.active_plan
+#   3. Newest ./.planning/<dir>/ by mtime
+#   4. Legacy: project root ./task_plan.md
+#
+# Usage:
+#   sh scripts/phase-status.sh <phase-number> <pending|in_progress|complete>
+#
+# Exits 1 with a message if the phase does not exist or the status is invalid.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+RESOLVER="${SCRIPT_DIR}/resolve-plan-dir.sh"
+
+usage() {
+    printf "Usage: %s <phase-number> <pending|in_progress|complete>\n" "$0" >&2
+}
+
+resolve_plan_file() {
+    plan_dir=""
+    if [ -f "${RESOLVER}" ]; then
+        plan_dir="$(sh "${RESOLVER}" 2>/dev/null)"
+    fi
+    if [ -n "${plan_dir}" ] && [ -f "${plan_dir}/task_plan.md" ]; then
+        printf "%s\n" "${plan_dir}/task_plan.md"
+        return 0
+    fi
+    if [ -f "./task_plan.md" ]; then
+        printf "%s\n" "./task_plan.md"
+        return 0
+    fi
+    return 1
+}
+
+PHASE_NUM="${1:-}"
+NEW_STATUS="${2:-}"
+
+if [ -z "${PHASE_NUM}" ] || [ -z "${NEW_STATUS}" ]; then
+    usage
+    exit 1
+fi
+
+# Validate phase number is a positive integer.
+case "${PHASE_NUM}" in
+    ''|*[!0-9]*)
+        printf "[phase-status] phase number must be a positive integer, got '%s'.\n" "${PHASE_NUM}" >&2
+        exit 1
+        ;;
+esac
+
+# Validate status value against the allowlist.
+case "${NEW_STATUS}" in
+    pending|in_progress|complete) : ;;
+    *)
+        printf "[phase-status] invalid status '%s' (allowed: pending, in_progress, complete).\n" "${NEW_STATUS}" >&2
+        exit 1
+        ;;
+esac
+
+PLAN_FILE="$(resolve_plan_file)" || {
+    printf "[phase-status] No task_plan.md found. Create a plan first.\n" >&2
+    exit 1
+}
+
+PLAN_DIR="$(dirname "${PLAN_FILE}")"
+LOCK_FILE="${PLAN_DIR}/.write_lock"
+
+# Confirm the phase heading exists before touching the file.
+if ! grep -q "### Phase ${PHASE_NUM}\b" "${PLAN_FILE}" 2>/dev/null; then
+    # Fall back to a looser match for headings like "### Phase 1:" where \b may
+    # not be honored by a minimal grep.
+    if ! grep -Eq "^### Phase ${PHASE_NUM}([^0-9]|$)" "${PLAN_FILE}" 2>/dev/null; then
+        printf "[phase-status] Phase %s not found in %s.\n" "${PHASE_NUM}" "${PLAN_FILE}" >&2
+        exit 1
+    fi
+fi
+
+# Rewrite only the FIRST "**Status:**" line that follows the "### Phase N"
+# heading. awk tracks whether we are inside the target phase block; once we
+# rewrite its status line we stop matching so later phases are untouched.
+rewrite() {
+    src="$1"
+    dst="$2"
+    awk -v target="${PHASE_NUM}" -v newstatus="${NEW_STATUS}" '
+        BEGIN { in_block = 0; done = 0 }
+        {
+            line = $0
+            if (line ~ /^### Phase /) {
+                # Extract the phase number right after "### Phase ".
+                rest = line
+                sub(/^### Phase /, "", rest)
+                num = rest
+                sub(/[^0-9].*$/, "", num)
+                if (num == target && done == 0) {
+                    in_block = 1
+                } else {
+                    in_block = 0
+                }
+            } else if (in_block == 1 && done == 0 && line ~ /\*\*Status:\*\*/) {
+                # Preserve leading whitespace/bullet before "**Status:**".
+                prefix = line
+                sub(/\*\*Status:\*\*.*$/, "", prefix)
+                line = prefix "**Status:** " newstatus
+                in_block = 0
+                done = 1
+            }
+            print line
+        }
+        END { if (done == 0) exit 3 }
+    ' "${src}" > "${dst}"
+}
+
+TMP_FILE="${PLAN_FILE}.tmp.$$"
+
+do_write() {
+    if ! rewrite "${PLAN_FILE}" "${TMP_FILE}"; then
+        rm -f "${TMP_FILE}" 2>/dev/null
+        printf "[phase-status] No **Status:** line found for Phase %s.\n" "${PHASE_NUM}" >&2
+        return 1
+    fi
+    mv -f "${TMP_FILE}" "${PLAN_FILE}"
+    return 0
+}
+
+rc=0
+if command -v flock >/dev/null 2>&1; then
+    (
+        flock -w 5 9 || true
+        do_write
+    ) 9>"${LOCK_FILE}" 2>/dev/null
+    rc=$?
+    rm -f "${LOCK_FILE}" 2>/dev/null || true
+else
+    do_write
+    rc=$?
+fi
+
+if [ "${rc}" -ne 0 ]; then
+    rm -f "${TMP_FILE}" 2>/dev/null
+    exit 1
+fi
+
+printf "[phase-status] Phase %s -> %s in %s\n" "${PHASE_NUM}" "${NEW_STATUS}" "${PLAN_FILE}"
+exit 0