517 lines
18 KiB
PowerShell
517 lines
18 KiB
PowerShell
# 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/<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 -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)"
|
|
}
|
|
}
|