planning-with-files 3.17.1 → 3.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planning-with-files",
-  "version": "3.17.1",
+  "version": "3.19.0",
   "description": "Persistent project planning with selected context injection. Automatic recovery uses project files only; explicit catchup modes read same-project local session records for aggregate counts or bounded replay. The host-aware gate never runs Markdown-declared commands. No network upload path. Ships the skill plus a Pi Coding Agent extension.",
   "keywords": [
     "pi-package",

package/scripts/check-complete.ps1

@@ -10,7 +10,8 @@
 #   4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
 #   5. the ledger advanced since the last block (stall -> allow stop)
 # When all hold, emits a single-line block-decision JSON on stdout and exits 0.
-# Otherwise advisory output and exit 0. Without -Gate, byte-equivalent to v2.43.
+# Otherwise reports incomplete plans and exits 0; completed plans stay silent
+# with -Gate, including legacy plans without .mode. Explicit reports are unchanged.
 #
 # Stdin: read only when input is redirected ([Console]::IsInputRedirected), so an
 # interactive console never blocks. Hook-piped JSON is EOF-terminated.
@@ -85,9 +86,10 @@ if ($TOTAL -eq 0) {
     exit 0
 }
 
-# advisory_report: the v2.43 status echo.
+# Keep explicit reports, but omit routine success from automatic gate checks.
 function Write-AdvisoryReport {
     if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
+        if ($Gate) { return }
         Write-Host ('[planning-with-files] ALL PHASES COMPLETE (' + $COMPLETE + '/' + $TOTAL + '). If the user has additional work, add new phases to task_plan.md before starting.')
     } else {
         Write-Host ('[planning-with-files] Task in progress (' + $COMPLETE + '/' + $TOTAL + ' phases complete). Update progress.md before stopping.')

package/scripts/check-complete.sh

@@ -21,8 +21,9 @@
 #     4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
 #     5. the ledger advanced since the last block (stall → allow stop)
 #   When all hold, it emits a single-line block-decision JSON on stdout and
-#   exits 0. Otherwise it falls back to advisory output and exits 0.
-#   Without --gate, or in non-gated mode, behavior is byte-equivalent to v2.43.
+#   exits 0. Otherwise it reports incomplete plans and exits 0; completed
+#   plans stay silent in --gate mode, including legacy plans without .mode.
+#   Without --gate, the explicit advisory report is unchanged.
 #
 # Stdin handling: the Claude Code Stop hook pipes a JSON payload on stdin. To
 # avoid hanging when nothing is piped, stdin is read ONLY when fd 0 is not a
@@ -119,9 +120,11 @@ if [ "$TOTAL" -eq 0 ]; then
     exit 0
 fi
 
-# advisory_report: the v2.43 status echo. Always exit 0 after calling.
+# Explicit status reports retain completion text. Automatic gate checks have
+# nothing to report on success; keep evaluating all gate guards before here.
 advisory_report() {
     if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
+        [ "$GATE" -eq 1 ] && return 0
         echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL). If the user has additional work, add new phases to task_plan.md before starting."
     else
         echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete). Update progress.md before stopping."

package/scripts/init-session.ps1

@@ -1,5 +1,6 @@
 # Initialize planning files for a new session
 # Usage: .\init-session.ps1 [-Template TYPE] [project-name]
+#        .\init-session.ps1 -PlanDir             # isolated plan with generated slug
 #        .\init-session.ps1 -Autonomous        # v3 autonomous mode (opt-in)
 #        .\init-session.ps1 -Gated             # v3 gated mode (opt-in, implies autonomous)
 # Templates: default, analytics
@@ -12,6 +13,7 @@
 param(
     [string]$ProjectName = "project",
     [string]$Template = "default",
+    [switch]$PlanDir,
     [switch]$Autonomous,
     [switch]$Gated
 )
@@ -38,7 +40,45 @@ function Get-Nonce {
     ($bytes | ForEach-Object { $_.ToString("x2") }) -join ""
 }
 
-Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
+function Get-PlanSlug([string]$Name) {
+    # -creplace: the case-insensitive -replace lets letters that .NET folds to
+    # ASCII (a dotted capital I, the Kelvin sign) survive into the plan id.
+    $slug = $Name.ToLowerInvariant() -creplace '[^a-z0-9]', '-'
+    $slug = $slug -creplace '-{2,}', '-'
+    $slug = $slug.Trim('-')
+    if ($slug.Length -gt 40) {
+        $slug = $slug.Substring(0, 40).TrimEnd('-')
+    }
+    # The resolvers and the selector only accept ASCII plan ids.
+    if ($slug -cnotmatch '^[a-z0-9-]*$') {
+        return ""
+    }
+    return $slug
+}
+
+function Get-ShortId {
+    return ([Guid]::NewGuid().ToString('N')).Substring(0, 8)
+}
+
+function Get-InheritedMode([string]$CurrentMode) {
+    $RootModePath = Join-Path (Get-Location).Path ".mode"
+    if (-not (Test-Path -LiteralPath $RootModePath)) {
+        return $CurrentMode
+    }
+    if ($CurrentMode -eq "gated") {
+        return $CurrentMode
+    }
+
+    $RootMode = Get-Content -LiteralPath $RootModePath -Raw -ErrorAction SilentlyContinue
+    # Case-sensitive like inherit_root_mode in init-session.sh and the injector.
+    if ($RootMode -cmatch 'gate') {
+        return "gated"
+    }
+    if ($RootMode -cmatch 'autonomous') {
+        return "autonomous"
+    }
+    return $CurrentMode
+}
 
 # Validate template
 if ($Template -ne "default" -and $Template -ne "analytics") {
@@ -46,11 +86,98 @@ if ($Template -ne "default" -and $Template -ne "analytics") {
     $Template = "default"
 }
 
+# Match init-session.sh: zero args (or an empty name) preserve legacy root
+# mode. A positional project name or -PlanDir creates an isolated
+# .planning/<date>-<slug>/ plan.
+$NamedPlan = $PSBoundParameters.ContainsKey("ProjectName") -and -not [string]::IsNullOrEmpty($ProjectName)
+$UsePlanDir = $PlanDir -or $NamedPlan
+if ($UsePlanDir) {
+    $PlanningRoot = Join-Path (Get-Location).Path ".planning"
+    # Match init-session.sh: set-active-plan.ps1 owns every write to the
+    # shared pointer, so a named plan cannot be created without it.
+    $PlanSelector = Join-Path $ScriptDir "set-active-plan.ps1"
+    if (-not (Test-Path -LiteralPath $PlanSelector -PathType Leaf)) {
+        Write-Error "Error: set-active-plan.ps1 is required to create a named plan safely."
+        exit 1
+    }
+    New-Item -ItemType Directory -Path $PlanningRoot -Force | Out-Null
+    # Verify the physical planning root and the existing pointer before
+    # creating anything below it. A symlink or junction that escapes the
+    # project must not redirect init writes, and a linked or non-regular
+    # pointer must be refused before a plan directory exists on disk. A
+    # script that returns without exit leaves $LASTEXITCODE alone, so reset
+    # it first and treat a thrown error as a failure too.
+    $global:LASTEXITCODE = 0
+    try {
+        & $PlanSelector -VerifyRoot *> $null
+    } catch {
+        $global:LASTEXITCODE = 1
+    }
+    if ($LASTEXITCODE -ne 0) {
+        Write-Error "Error: the planning directory or the active plan pointer is outside the project or cannot be verified."
+        exit 1
+    }
+
+    if ($NamedPlan) {
+        $Slug = Get-PlanSlug $ProjectName
+    } else {
+        $Slug = ""
+        $ProjectName = "untitled"
+    }
+    if ([string]::IsNullOrEmpty($Slug)) {
+        $Slug = "untitled-$(Get-ShortId)"
+    }
+
+    $BaseId = "$DATE-$Slug"
+    $PlanId = $BaseId
+    $Counter = 2
+    while (Test-Path -LiteralPath (Join-Path $PlanningRoot $PlanId)) {
+        $PlanId = "$BaseId-$Counter"
+        $Counter++
+    }
+    $TargetDir = Join-Path $PlanningRoot $PlanId
+    New-Item -ItemType Directory -Path $TargetDir -Force | Out-Null
+    # Reuse the selector's contained, atomic pointer replacement. Set-Content
+    # would follow a reparse point and truncate a hardlinked pointer in place,
+    # overwriting whichever file shares that inode.
+    $global:LASTEXITCODE = 0
+    try {
+        & $PlanSelector $PlanId *> $null
+    } catch {
+        $global:LASTEXITCODE = 1
+    }
+    if ($LASTEXITCODE -ne 0) {
+        Write-Error "Error: could not safely update the active plan pointer at $(Join-Path $PlanningRoot '.active_plan')."
+        exit 1
+    }
+    $Mode = Get-InheritedMode $Mode
+} else {
+    $TargetDir = (Get-Location).Path
+}
+
+$TaskPlanPath = Join-Path $TargetDir "task_plan.md"
+$FindingsPath = Join-Path $TargetDir "findings.md"
+$ProgressPath = Join-Path $TargetDir "progress.md"
+if ($UsePlanDir) {
+    $TaskPlanDisplay = $TaskPlanPath
+    $FindingsDisplay = $FindingsPath
+    $ProgressDisplay = $ProgressPath
+} else {
+    $TaskPlanDisplay = "task_plan.md"
+    $FindingsDisplay = "findings.md"
+    $ProgressDisplay = "progress.md"
+}
+
+Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
+if ($UsePlanDir) {
+    Write-Host "PLAN_ID=$PlanId"
+}
+
 # Create task_plan.md if it doesn't exist
-if (-not (Test-Path "task_plan.md")) {
+if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
     $AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
     if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
-        Copy-Item $AnalyticsPlan "task_plan.md"
+        Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath
     } else {
         @"
 # Task Plan: [Brief Description]
@@ -99,18 +226,18 @@ Phase 1
 ## Errors Encountered
 | Error | Resolution |
 |-------|------------|
-"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
+"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8
     }
-    Write-Host "Created task_plan.md"
+    Write-Host "Created $TaskPlanDisplay"
 } else {
-    Write-Host "task_plan.md already exists, skipping"
+    Write-Host "$TaskPlanDisplay already exists, skipping"
 }
 
 # Create findings.md if it doesn't exist
-if (-not (Test-Path "findings.md")) {
+if (-not (Test-Path -LiteralPath $FindingsPath)) {
     $AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
     if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
-        Copy-Item $AnalyticsFindings "findings.md"
+        Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath
     } else {
         @"
 # Findings & Decisions
@@ -131,15 +258,15 @@ if (-not (Test-Path "findings.md")) {
 
 ## Resources
 -
-"@ | Out-File -FilePath "findings.md" -Encoding UTF8
+"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8
     }
-    Write-Host "Created findings.md"
+    Write-Host "Created $FindingsDisplay"
 } else {
-    Write-Host "findings.md already exists, skipping"
+    Write-Host "$FindingsDisplay already exists, skipping"
 }
 
 # Create progress.md if it doesn't exist
-if (-not (Test-Path "progress.md")) {
+if (-not (Test-Path -LiteralPath $ProgressPath)) {
     if ($Template -eq "analytics") {
         @"
 # Progress Log
@@ -160,7 +287,7 @@ if (-not (Test-Path "progress.md")) {
 ### Errors
 | Error | Resolution |
 |-------|------------|
-"@ | Out-File -FilePath "progress.md" -Encoding UTF8
+"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
     } else {
         @"
 # Progress Log
@@ -181,23 +308,28 @@ if (-not (Test-Path "progress.md")) {
 ### Errors
 | Error | Resolution |
 |-------|------------|
-"@ | Out-File -FilePath "progress.md" -Encoding UTF8
+"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
     }
-    Write-Host "Created progress.md"
+    Write-Host "Created $ProgressDisplay"
 } else {
-    Write-Host "progress.md already exists, skipping"
+    Write-Host "$ProgressDisplay already exists, skipping"
 }
 
 Write-Host ""
 Write-Host "Planning files initialized!"
-Write-Host "Files: task_plan.md, findings.md, progress.md"
+if ($UsePlanDir) {
+    Write-Host "Active plan recorded: $(Join-Path $PlanningRoot '.active_plan')"
+    Write-Host "Pin this terminal to the plan for parallel sessions:"
+    Write-Host "  `$env:PLAN_ID='$PlanId'"
+} else {
+    Write-Host "Files: task_plan.md, findings.md, progress.md"
+}
 
 # v3 opt-in mode side effects. No-op when -Autonomous/-Gated were not passed, so
-# the default path stays byte-equivalent to v2.43.0. PS1 init writes in CWD, so
-# dotfiles live in CWD and attest-plan.ps1 falls back to the legacy
-# .plan-attestation at the project root.
+# the default path stays byte-equivalent to v2.43.0. Dotfiles live beside the
+# selected plan; root mode therefore retains the legacy project-root behavior.
 if ($Mode -ne "") {
-    $PlanDirPwf = (Get-Location).Path
+    $PlanDirPwf = $TargetDir
 
     # (a) reset gate block counter, drop stale gate ledger.
     Set-Content -LiteralPath (Join-Path $PlanDirPwf ".stop_blocks") -Value "0" -Encoding ascii
@@ -216,13 +348,42 @@ if ($Mode -ne "") {
     Set-Content -LiteralPath (Join-Path $PlanDirPwf ".mode") -Value $MarkerText -Encoding ascii
 
     # (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
-    $AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
+    # attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
+    # no-follow implementation uses Win32 handles. On Unix, use the POSIX
+    # attester instead. Bind slug mode to the plan we just created so an
+    # inherited PLAN_ID cannot redirect attestation to another plan.
     $PlanFilePwf = Join-Path $PlanDirPwf "task_plan.md"
-    if ((Test-Path -LiteralPath $AttestPs1) -and (Test-Path -LiteralPath $PlanFilePwf)) {
+    if (Test-Path -LiteralPath $PlanFilePwf) {
+        $HadPlanId = Test-Path Env:PLAN_ID
+        $PreviousPlanId = $env:PLAN_ID
         try {
-            & $AttestPs1 *> $null
+            if ($UsePlanDir) {
+                $env:PLAN_ID = $PlanId
+            } else {
+                Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
+            }
+
+            $IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
+            if ($IsWindowsHost) {
+                $AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
+                if (Test-Path -LiteralPath $AttestPs1) {
+                    & $AttestPs1 *> $null
+                }
+            } else {
+                $AttestSh = Join-Path $ScriptDir "attest-plan.sh"
+                $Sh = Get-Command sh -ErrorAction SilentlyContinue
+                if ($Sh -and (Test-Path -LiteralPath $AttestSh)) {
+                    & $Sh.Path $AttestSh *> $null
+                }
+            }
         } catch {
             # attestation failure must not abort init; the mode marker still stands.
+        } finally {
+            if ($HadPlanId) {
+                $env:PLAN_ID = $PreviousPlanId
+            } else {
+                Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
+            }
         }
     }
 

package/scripts/init-session.sh

@@ -83,7 +83,8 @@ done
 
 DATE=$(date +%Y-%m-%d)
 
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# CDPATH must not redirect the cd that locates the sibling scripts.
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
 SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
 TEMPLATE_DIR="$SKILL_ROOT/templates"
 
@@ -382,6 +383,20 @@ if [ "$SLUG_MODE" -eq 1 ]; then
     BASE_ID="${DATE}-${SLUG}"
     PLAN_ID="$BASE_ID"
     PLAN_ROOT="${PWD}/.planning"
+    PLAN_SELECTOR="${SCRIPT_DIR}/set-active-plan.sh"
+    if [ ! -f "${PLAN_SELECTOR}" ]; then
+        echo "Error: set-active-plan.sh is required to create a named plan safely." >&2
+        exit 1
+    fi
+    mkdir -p "${PLAN_ROOT}"
+    # Verify the physical planning root and the existing pointer before
+    # creating anything below it. A symlink or junction that escapes the
+    # project must not redirect init writes, and a linked or non-regular
+    # pointer must be refused before a plan directory exists on disk. The
+    # selector's check is constant time; --list would parse every plan.
+    if ! sh "${PLAN_SELECTOR}" --verify-root; then
+        exit 1
+    fi
     counter=2
     while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
         PLAN_ID="${BASE_ID}-${counter}"
@@ -393,7 +408,13 @@ if [ "$SLUG_MODE" -eq 1 ]; then
     echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
     echo "PLAN_ID=$PLAN_ID"
     create_files_in "$PLAN_DIR"
-    printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
+    # Reuse the selector's contained, atomic pointer replacement. Direct shell
+    # redirection would truncate a pre-existing hardlink and could overwrite a
+    # different file that shares the same inode.
+    if ! sh "${PLAN_SELECTOR}" "${PLAN_ID}" >/dev/null; then
+        echo "Error: could not safely update ${PLAN_ROOT}/.active_plan." >&2
+        exit 1
+    fi
     inherit_root_mode
     apply_v3_mode "$PLAN_DIR" "${PLAN_DIR}/task_plan.md"
     echo ""

package/scripts/session-catchup.py

@@ -407,9 +407,6 @@ def get_session_candidates(
     return 'claude', []
 
 
-PLANNING_LIKE_SQL = ('%task_plan.md', '%findings.md', '%progress.md')
-
-
 def get_opencode_db_path() -> Optional[Path]:
     """Resolve OpenCode SQLite path. Same on all OS per xdg-basedir."""
     xdg = os.environ.get('XDG_DATA_HOME')
@@ -576,28 +573,42 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
     update_time = None
     update_idx = -1
     for idx, (sid, _) in enumerate(previous_sessions):
-        params = (sid,) + PLANNING_LIKE_SQL
         cur.execute(
             """
-            SELECT time_created FROM part
+            SELECT time_created, data FROM part
             WHERE session_id = ?
               AND json_extract(data, '$.type') = 'tool'
               AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
               AND (
-                json_extract(data, '$.state.input.filePath') LIKE ?
-                OR json_extract(data, '$.state.input.filePath') LIKE ?
-                OR json_extract(data, '$.state.input.filePath') LIKE ?
+                  replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
+                      IN ('task_plan.md', 'findings.md', 'progress.md')
+                  OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
+                      GLOB '*/task_plan.md'
+                  OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
+                      GLOB '*/findings.md'
+                  OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
+                      GLOB '*/progress.md'
               )
-            ORDER BY time_created DESC
-            LIMIT 1
+            ORDER BY time_created DESC, id DESC
             """,
-            params,
+            (sid,),
         )
-        row = cur.fetchone()
-        if row:
-            update_sid = sid
-            update_time = row[0]
-            update_idx = idx
+        # Iterate lazily: write parts carry whole file bodies, and fetchall
+        # would materialize every planning write of the session before the
+        # first validated row ends the loop.
+        for candidate_time, data_str in cur:
+            data = json_loads(data_str)
+            if not isinstance(data, dict):
+                continue
+            state = data.get('state')
+            input_ = state.get('input') if isinstance(state, dict) else None
+            file_path = input_.get('filePath') if isinstance(input_, dict) else None
+            if planning_file_from_path(file_path):
+                update_sid = sid
+                update_time = candidate_time
+                update_idx = idx
+                break
+        if update_sid:
             break
 
     if not update_sid:
@@ -685,12 +696,17 @@ def parse_session_messages(session_file: Path) -> List[Dict[str, Any]]:
 
 
 def planning_file_from_path(path_value: Any) -> Optional[str]:
+    """Return a planning filename only when it is the path's exact basename.
+
+    A suffix check treats lookalikes such as ``draft_task_plan.md`` as real
+    planning updates and can anchor catchup at unrelated transcript content.
+    Normalize separators so the same boundary rule works for Unix and Windows
+    session records.
+    """
     if not isinstance(path_value, str):
         return None
-    for pf in PLANNING_FILES:
-        if path_value.endswith(pf):
-            return pf
-    return None
+    basename = path_value.replace(chr(92), '/').rsplit('/', 1)[-1]
+    return basename if basename in PLANNING_FILES else None
 
 
 def planning_file_from_paths(paths: Iterable[Any]) -> Optional[str]: