planning-with-files 3.10.2 → 3.12.0

package/scripts/phase-status.sh

@@ -1,158 +1,202 @@
-#!/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
+#!/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 the portable
+# <plan-dir>/.pwf-locks/phase-status.lock directory lock, 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_ROOT="${PLAN_DIR}/.pwf-locks"
+LOCK_DIR="${LOCK_ROOT}/phase-status.lock"
+LOCK_TOKEN=""
+LOCK_ACQUIRED=0
+
+release_lock() {
+    if [ "${LOCK_ACQUIRED}" -ne 1 ] || [ -z "${LOCK_TOKEN}" ]; then
+        return 0
+    fi
+    owner_file="${LOCK_DIR}/.owner"
+    owner_value="$(cat "${owner_file}" 2>/dev/null || true)"
+    if [ "${owner_value}" = "${LOCK_TOKEN}" ]; then
+        rm -f "${owner_file}" 2>/dev/null || true
+        rmdir "${LOCK_DIR}" 2>/dev/null || true
+    fi
+    LOCK_ACQUIRED=0
+}
+
+acquire_lock() {
+    mkdir -p "${LOCK_ROOT}" 2>/dev/null || {
+        printf "[phase-status] Cannot create lock root %s.\n" "${LOCK_ROOT}" >&2
+        return 1
+    }
+    LOCK_TOKEN="phase-status-$$-$(date +%s 2>/dev/null || printf 0)"
+    started_at="$(date +%s 2>/dev/null || printf 0)"
+    attempts=0
+    while ! mkdir "${LOCK_DIR}" 2>/dev/null; do
+        attempts=$((attempts + 1))
+        now="$(date +%s 2>/dev/null || printf 0)"
+        if { [ "${started_at}" -gt 0 ] 2>/dev/null \
+                && [ $((now - started_at)) -ge 5 ]; } \
+            || [ "${attempts}" -ge 50 ]; then
+            printf "[phase-status] Timed out waiting for lock %s. No plan changes were made.\n" "${LOCK_DIR}" >&2
+            return 75
+        fi
+        sleep 0.1
+    done
+    if ! printf '%s\n' "${LOCK_TOKEN}" > "${LOCK_DIR}/.owner" 2>/dev/null; then
+        rmdir "${LOCK_DIR}" 2>/dev/null || true
+        printf "[phase-status] Cannot record lock ownership in %s.\n" "${LOCK_DIR}" >&2
+        return 1
+    fi
+    LOCK_ACQUIRED=1
+    return 0
+}
+
+trap 'release_lock' EXIT
+trap 'release_lock; exit 1' HUP INT TERM
+
+acquire_lock
+lock_rc=$?
+if [ "${lock_rc}" -ne 0 ]; then
+    exit "${lock_rc}"
+fi
+
+# Confirm the phase heading exists while holding the same lock as the rewrite.
+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
+do_write || rc=$?
+
+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

package/scripts/resolve-plan-dir.ps1

@@ -18,6 +18,64 @@ param(
 
 $projectRoot = (Get-Location).Path
 
+# Resolve-Path is lexical for Windows junctions: it can return the junction's
+# spelling rather than the directory opened by the filesystem. Use a directory
+# handle and GetFinalPathNameByHandleW on Windows so containment is decided from
+# the object the kernel actually opened.
+$script:IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
+if ($script:IsWindowsHost -and -not ("PwfResolverNative" -as [type])) {
+    Add-Type -TypeDefinition @'
+using System;
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+using System.Text;
+using Microsoft.Win32.SafeHandles;
+
+public static class PwfResolverNative {
+    private const uint FILE_SHARE_READ = 0x00000001;
+    private const uint FILE_SHARE_WRITE = 0x00000002;
+    private const uint FILE_SHARE_DELETE = 0x00000004;
+    private const uint OPEN_EXISTING = 3;
+    private const uint FILE_FLAG_BACKUP_SEMANTICS = 0x02000000;
+
+    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    private static extern SafeFileHandle CreateFileW(
+        string name, uint access, uint share, IntPtr security,
+        uint creation, uint flags, IntPtr template);
+
+    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    private static extern uint GetFinalPathNameByHandleW(
+        SafeFileHandle handle, StringBuilder path, uint length, uint flags);
+
+    public static string FinalDirectoryPath(string path) {
+        using (SafeFileHandle handle = CreateFileW(
+            path, 0, FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
+            IntPtr.Zero, OPEN_EXISTING, FILE_FLAG_BACKUP_SEMANTICS, IntPtr.Zero)) {
+            if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
+            StringBuilder buffer = new StringBuilder(32768);
+            uint length = GetFinalPathNameByHandleW(handle, buffer, (uint)buffer.Capacity, 0);
+            if (length == 0 || length >= buffer.Capacity)
+                throw new Win32Exception(Marshal.GetLastWin32Error());
+            string result = buffer.ToString();
+            if (result.StartsWith(@"\\?\UNC\", StringComparison.OrdinalIgnoreCase))
+                return @"\\" + result.Substring(8);
+            if (result.StartsWith(@"\\?\", StringComparison.OrdinalIgnoreCase))
+                return result.Substring(4);
+            return result;
+        }
+    }
+}
+'@
+}
+
+function Get-FinalDirectoryPath {
+    param([string]$Path)
+    if ($script:IsWindowsHost) {
+        return [PwfResolverNative]::FinalDirectoryPath($Path)
+    }
+    return (Resolve-Path -LiteralPath $Path -ErrorAction Stop).Path
+}
+
 # PWF_PLAN_ROOT: absolute plan-root binding (issue #212), mirroring
 # resolve-plan-dir.sh. A thread whose cwd is a shared PARENT of the real
 # project resolves the parent's plan and never sees the nested one;
@@ -30,9 +88,12 @@ $projectRoot = (Get-Location).Path
 # user-facing notice; stdout here is the data channel). Containment is then
 # checked against the pinned root. Unset keeps legacy behavior unchanged.
 if ($env:PWF_PLAN_ROOT) {
-    if (Test-Path -LiteralPath $env:PWF_PLAN_ROOT -PathType Container) {
-        $projectRoot = $env:PWF_PLAN_ROOT
-        $PlanRoot = Join-Path $env:PWF_PLAN_ROOT ".planning"
+    $pin = $env:PWF_PLAN_ROOT
+    $isUnc = $pin.StartsWith('\\') -or $pin.StartsWith('//')
+    $isAbsolute = [System.IO.Path]::IsPathFullyQualified($pin)
+    if ($isAbsolute -and -not $isUnc -and (Test-Path -LiteralPath $pin -PathType Container)) {
+        $projectRoot = $pin
+        $PlanRoot = Join-Path $pin ".planning"
     } else {
         exit 0
     }
@@ -55,8 +116,8 @@ function Test-ValidSlug {
 function Test-WithinRoot {
     param([string]$Candidate)
     try {
-        $rootReal = (Resolve-Path -LiteralPath $projectRoot -ErrorAction Stop).Path
-        $candReal = (Resolve-Path -LiteralPath $Candidate -ErrorAction Stop).Path
+        $rootReal = Get-FinalDirectoryPath $projectRoot
+        $candReal = Get-FinalDirectoryPath $Candidate
     } catch {
         return $false
     }
@@ -79,8 +140,17 @@ if ($env:PLAN_ID) {
     }
 }
 
-if (Test-Path $activeFile) {
-    $planId = (Get-Content $activeFile -Raw).Trim()
+# Get-Item observes the link object even when its target is missing, unlike
+# Test-Path which follows the target. An active pointer that is a directory or
+# reparse point is an unsafe/ambiguous selector and must terminate resolution;
+# falling through would silently select and expose the newest unrelated plan.
+$activeItem = Get-Item -LiteralPath $activeFile -Force -ErrorAction SilentlyContinue
+if ($activeItem) {
+    if ($activeItem.PSIsContainer -or
+        (($activeItem.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0)) {
+        exit 0
+    }
+    $planId = (Get-Content -LiteralPath $activeFile -Raw).Trim()
     if ($planId -and (Test-ValidSlug $planId)) {
         $candidate = Join-Path $PlanRoot $planId
         if ((Test-Path $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {

package/scripts/resolve-plan-dir.sh

@@ -31,7 +31,12 @@ PLAN_ROOT="${1:-${PWD}/.planning}"
 # With the variable unset, behavior is byte-identical to the legacy shape.
 PWF_ROOT_PIN=""
 if [ -n "${PWF_PLAN_ROOT:-}" ]; then
-    if [ -d "${PWF_PLAN_ROOT}" ]; then
+    case "${PWF_PLAN_ROOT}" in
+        \\\\*|//*|[A-Za-z]:[!\\/]*) _pwf_pin_absolute=0 ;;
+        /*|[A-Za-z]:[\\/]*) _pwf_pin_absolute=1 ;;
+        *) _pwf_pin_absolute=0 ;;
+    esac
+    if [ "$_pwf_pin_absolute" = "1" ] && [ -d "${PWF_PLAN_ROOT}" ]; then
         PWF_ROOT_PIN="${PWF_PLAN_ROOT}"
         PLAN_ROOT="${PWF_PLAN_ROOT}/.planning"
     else