# 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 # # v3 modes (opt-in): -Autonomous / -Gated write a .mode marker next to the plan, # reset the .stop_blocks gate counter, clear any stale gate ledger, write a fresh # 16-hex nonce for delimiter framing, and auto-attest the plan. With NO v3 switch # and no .mode file, behavior is byte-equivalent to v2.43.0. param( [string]$ProjectName = "project", [string]$Template = "default", [switch]$PlanDir, [switch]$Autonomous, [switch]$Gated ) # Windows PowerShell 5.1 can silently relocate a -File invocation when the # inherited cwd contains wildcard characters such as [ or ]. Recover the # physical cwd for a direct invocation before any project-relative paths are # resolved. if ($PSVersionTable.PSVersion.Major -eq 5 -and [System.Management.Automation.WildcardPattern]::ContainsWildcardCharacters([Environment]::CurrentDirectory)) { $processArgs = [Environment]::GetCommandLineArgs() for ($index = 0; $index -lt ($processArgs.Length - 1); $index++) { if ($processArgs[$index] -ieq '-File') { $entryScript = $processArgs[$index + 1] if (-not [IO.Path]::IsPathRooted($entryScript)) { $entryScript = Join-Path ([Environment]::CurrentDirectory) $entryScript } if ([IO.Path]::GetFullPath($entryScript) -eq [IO.Path]::GetFullPath($PSCommandPath)) { Set-Location -LiteralPath ([Environment]::CurrentDirectory) } break } } } $DATE = Get-Date -Format "yyyy-MM-dd" # Resolve v3 opt-in mode. -Gated implies autonomous and is the stronger marker. $Mode = "" if ($Gated) { $Mode = "gated" } elseif ($Autonomous) { $Mode = "autonomous" } # Resolve template directory (skill root is one level up from scripts/) $ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path $SkillRoot = Split-Path -Parent $ScriptDir $TemplateDir = Join-Path $SkillRoot "templates" function Get-Nonce { # 16 hex chars for the plan-data delimiter framing (security strand rec 8). $bytes = New-Object 'System.Byte[]' 8 [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes) ($bytes | ForEach-Object { $_.ToString("x2") }) -join "" } 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 } function Format-AttestationFailureReason { param([object[]]$Output, [string]$Fallback) $Reason = @( $Output | ForEach-Object { if ($null -ne $_) { ($_.ToString()).Trim() } } | Where-Object { $_ } ) -join " " $Reason = ($Reason -replace '\s+', ' ').Trim() if ([string]::IsNullOrWhiteSpace($Reason)) { return $Fallback } if ($Reason.Length -gt 300) { return ($Reason.Substring(0, 297) + "...") } return $Reason } # Validate template if ($Template -ne "default" -and $Template -ne "analytics") { Write-Host "Unknown template: $Template (available: default, analytics). Using default." $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/-/ 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 -ErrorAction Stop | Out-Null $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" } try { # Create task_plan.md if it doesn't exist if (-not (Test-Path -LiteralPath $TaskPlanPath)) { $AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md" if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) { Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath -ErrorAction Stop } else { @" # Task Plan: [Brief Description] ## Goal [One sentence describing the end state] ## Next Step [The single next action. Update whenever phase status changes.] ## Current Phase Phase 1 ## Phases ### Phase 1: Requirements & Discovery - [ ] Understand user intent - [ ] Identify constraints - [ ] Document in findings.md - **Status:** in_progress ### Phase 2: Planning & Structure - [ ] Define approach - [ ] Create project structure - **Status:** pending ### Phase 3: Implementation - [ ] Execute the plan - [ ] Write to files before executing - **Status:** pending ### Phase 4: Testing & Verification - [ ] Verify requirements met - [ ] Document test results - **Status:** pending ### Phase 5: Delivery - [ ] Review outputs - [ ] Deliver to user - **Status:** pending ## Decisions Made | Decision | Rationale | |----------|-----------| ## Errors Encountered | Error | Resolution | |-------|------------| "@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8 -ErrorAction Stop } Write-Host "Created $TaskPlanDisplay" } else { Write-Host "$TaskPlanDisplay already exists, skipping" } # Create findings.md if it doesn't exist if (-not (Test-Path -LiteralPath $FindingsPath)) { $AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md" if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) { Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath -ErrorAction Stop } else { @" # Findings & Decisions ## Requirements - ## Research Findings - ## Technical Decisions | Decision | Rationale | |----------|-----------| ## Issues Encountered | Issue | Resolution | |-------|------------| ## Resources - "@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8 -ErrorAction Stop } Write-Host "Created $FindingsDisplay" } else { Write-Host "$FindingsDisplay already exists, skipping" } # Create progress.md if it doesn't exist if (-not (Test-Path -LiteralPath $ProgressPath)) { if ($Template -eq "analytics") { @" # Progress Log ## Session: $DATE ### Current Status - **Phase:** 1 - Data Discovery - **Started:** $DATE ### Actions Taken - ### Query Log | Query | Result Summary | Interpretation | |-------|---------------|----------------| ### Errors | Error | Resolution | |-------|------------| "@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop } else { @" # Progress Log ## Session: $DATE ### Current Status - **Phase:** 1 - Requirements & Discovery - **Started:** $DATE ### Actions Taken - ### Test Results | Test | Expected | Actual | Status | |------|----------|--------|--------| ### Errors | Error | Resolution | |-------|------------| "@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop } Write-Host "Created $ProgressDisplay" } else { Write-Host "$ProgressDisplay already exists, skipping" } } catch { Write-Error "Error: could not initialize planning files in '$TargetDir': $($_.Exception.Message)" exit 1 } if ($UsePlanDir) { # Activate the named plan only after all three planning files are ready. # This matches init-session.sh and prevents a failed initialization from # leaving .active_plan pointed at a partial plan directory. $pointerSet = $false for ($attempt = 1; $attempt -le 5; $attempt++) { $global:LASTEXITCODE = 0 try { $selectorResult = & $PlanSelector $PlanId 2>&1 } catch { $selectorResult = $_ $global:LASTEXITCODE = 1 } if ($LASTEXITCODE -eq 0) { $pointerSet = $true break } # Another writer can replace the pointer between the selector's # Get-Item and final-path check. Retry only that transient result. $transientPointerRace = $selectorResult -is [System.Management.Automation.ErrorRecord] -and $selectorResult.Exception.Message -ceq 'Error: could not set the active plan pointer: the active plan pointer became unsafe during replacement' if ($attempt -eq 5 -or -not $transientPointerRace) { break } Start-Sleep -Milliseconds 50 $global:LASTEXITCODE = 0 try { & $PlanSelector -VerifyRoot *> $null } catch { $global:LASTEXITCODE = 1 } if ($LASTEXITCODE -ne 0) { break } } if (-not $pointerSet) { Write-Error "Error: could not safely update the active plan pointer at $(Join-Path $PlanningRoot '.active_plan')." exit 1 } } Write-Host "" Write-Host "Planning files initialized!" 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. Dotfiles live beside the # selected plan; root mode therefore retains the legacy project-root behavior. if ($Mode -ne "") { $PlanDirPwf = $TargetDir # (a) reset gate block counter, drop stale gate ledger. Set-Content -LiteralPath (Join-Path $PlanDirPwf ".stop_blocks") -Value "0" -Encoding ascii $StaleLedger = Join-Path $PlanDirPwf ".gate_last_ledger" if (Test-Path -LiteralPath $StaleLedger) { Remove-Item -LiteralPath $StaleLedger -Force } # (b) fresh 16-hex nonce for delimiter framing. Set-Content -LiteralPath (Join-Path $PlanDirPwf ".nonce") -Value (Get-Nonce) -NoNewline -Encoding ascii # mode marker. gated implies autonomous, so it carries both tokens. if ($Mode -eq "gated") { $MarkerText = "autonomous gate" } else { $MarkerText = "autonomous" } Set-Content -LiteralPath (Join-Path $PlanDirPwf ".mode") -Value $MarkerText -Encoding ascii # (c) auto-attest (attestation default-on in v3 modes, security strand rec 1). # attest-plan.ps1 intentionally refuses non-Windows hosts because its secure # no-follow implementation uses Win32 handles. On Unix, use the POSIX # attester instead. Slug mode binds PWF_PLAN_ROOT and PLAN_ID to the plan # we just created so an inherited pin or slug cannot redirect attestation # to another project or plan (#261, #237). Root mode clears both instead: # the attester only falls back to the legacy ./task_plan.md when no # selector is set, and a bound pin would make it refuse the root plan. $AttestationSucceeded = $false $AttestationCommand = "attest-plan" $AttestationReason = "task_plan.md was not available for attestation" $PlanFilePwf = Join-Path $PlanDirPwf "task_plan.md" if (Test-Path -LiteralPath $PlanFilePwf -PathType Leaf) { $HadPlanId = Test-Path Env:PLAN_ID $PreviousPlanId = $env:PLAN_ID $HadPlanRoot = Test-Path Env:PWF_PLAN_ROOT $PreviousPlanRoot = $env:PWF_PLAN_ROOT try { if ($UsePlanDir) { $env:PWF_PLAN_ROOT = (Get-Location).Path $env:PLAN_ID = $PlanId } else { Remove-Item Env:PWF_PLAN_ROOT -ErrorAction SilentlyContinue Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue } # A called script can return without changing $LASTEXITCODE, so # clear the inherited value before every attempt. Both a non-zero # status and a terminating exception mean the plan is not attested. $global:LASTEXITCODE = 0 $AttestOutput = @() $IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT if ($IsWindowsHost) { $AttestationCommand = "attest-plan.ps1" $AttestPs1 = Join-Path $ScriptDir $AttestationCommand if (Test-Path -LiteralPath $AttestPs1 -PathType Leaf) { $AttestOutput = @(& $AttestPs1 2>&1) $AttestExitCode = $LASTEXITCODE if ($AttestExitCode -eq 0) { $AttestationSucceeded = $true $AttestationReason = "" } else { $AttestationReason = Format-AttestationFailureReason ` -Output $AttestOutput ` -Fallback "$AttestationCommand exited with code $AttestExitCode" } } else { $AttestationReason = "$AttestationCommand was not found beside init-session.ps1" } } else { $AttestationCommand = "attest-plan.sh" $AttestSh = Join-Path $ScriptDir $AttestationCommand $Sh = Get-Command sh -ErrorAction SilentlyContinue if ($Sh -and (Test-Path -LiteralPath $AttestSh -PathType Leaf)) { $AttestOutput = @(& $Sh.Path $AttestSh 2>&1) $AttestExitCode = $LASTEXITCODE if ($AttestExitCode -eq 0) { $AttestationSucceeded = $true $AttestationReason = "" } else { $AttestationReason = Format-AttestationFailureReason ` -Output $AttestOutput ` -Fallback "$AttestationCommand exited with code $AttestExitCode" } } elseif (-not $Sh) { $AttestationReason = "sh was not found; $AttestationCommand could not run" } else { $AttestationReason = "$AttestationCommand was not found beside init-session.ps1" } } } catch { $AttestationReason = Format-AttestationFailureReason ` -Output @($_) ` -Fallback "$AttestationCommand failed" } finally { if ($HadPlanId) { $env:PLAN_ID = $PreviousPlanId } else { Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue } if ($HadPlanRoot) { $env:PWF_PLAN_ROOT = $PreviousPlanRoot } else { Remove-Item Env:PWF_PLAN_ROOT -ErrorAction SilentlyContinue } } } if ($AttestationSucceeded) { Write-Host "Mode: $MarkerText (attested, gate counter reset)" } else { Write-Host "Mode: $MarkerText (NOT attested: $AttestationReason; run $AttestationCommand before the first hook fire)" } }