OthmanAdi/planning-with-files / .factory/skills/planning-with-files
planning-with-files
VerifiedPersistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.
scripts/attest-plan.ps1
View on GitHub#requires -Version 5.0
<#
.SYNOPSIS
Lock the current task_plan.md content with a SHA-256 attestation.
.DESCRIPTION
Use after you finalise (or intentionally edit) a plan. The hooks then refuse
to inject plan content into the model context if the file diverges from the
attested hash, surfacing a "[PLAN TAMPERED]" warning instead.
Plan resolution:
1. -Target root or <plan-id> -> root or named plan
2. $env:PLAN_ID -> ./.planning/$PLAN_ID/
3. ./.planning/.active_plan
4. Newest ./.planning/<dir>/ by LastWriteTime
5. Legacy ./task_plan.md at project root
.PARAMETER Show
Print the stored hash for the active plan.
.PARAMETER Clear
Remove the attestation (re-open the plan).
.PARAMETER Target
Attest the root plan or one named plan without changing the active pointer.
#>
[CmdletBinding(DefaultParameterSetName = "Attest")]
param(
[Parameter(ParameterSetName = "Show")]
[switch] $Show,
[Parameter(ParameterSetName = "Clear")]
[switch] $Clear,
[Parameter(ParameterSetName = "Target", Mandatory = $true)]
[ValidateNotNullOrEmpty()]
[string] $Target
)
$ErrorActionPreference = "Stop"
# Refusals are one plain line. Write-Error would add the script path and the
# source snippet and repeat the marker. [Console]::Error bypasses the 2>&1
# capture of a script calling this one in-process (init-session.ps1 reports
# the reason), so a nested call uses the error stream, which 2>&1 captures and
# which still reaches the console when the caller captures only its output.
$script:CalledFromScript = [bool]$MyInvocation.PSCommandPath
function Write-AttestationRefusal {
param([string] $Message)
if ($script:CalledFromScript) { Write-Error -Message $Message -ErrorAction Continue }
else { [Console]::Error.WriteLine($Message) }
}
# An echoed selector must not forge output: a newline or an escape sequence
# in PLAN_ID could otherwise print a fake status line.
function Format-Selector {
param([string] $Value)
return ($Value -replace '[\x00-\x1F\x7F-\x9F]', '?')
}
function Write-PinRefusal {
Write-AttestationRefusal "[plan-attest] PWF_PLAN_ROOT=$(Format-Selector $env:PWF_PLAN_ROOT) did not resolve to a project root holding a plan. An explicit pin is a binding: nothing was attested and no other plan was substituted."
}
$script:IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
if (-not $script:IsWindowsHost) {
throw "Safe no-follow descriptor operations are unavailable in this PowerShell script on Unix. Use scripts/attest-plan.sh instead."
}
if ($script:IsWindowsHost -and -not ("PwfAttestationNative" -as [type])) {
Add-Type -TypeDefinition @'
using System;
using System.ComponentModel;
using System.IO;
using System.Runtime.InteropServices;
using System.Text;
using Microsoft.Win32.SafeHandles;
public static class PwfAttestationNative {
private const uint GENERIC_READ = 0x80000000;
private const uint GENERIC_WRITE = 0x40000000;
private const uint DELETE = 0x00010000;
private const uint FILE_READ_ATTRIBUTES = 0x00000080;
private const uint FILE_SHARE_READ = 0x00000001;
private const uint FILE_SHARE_WRITE = 0x00000002;
private const uint FILE_SHARE_DELETE = 0x00000004;
private const uint CREATE_NEW = 1;
private const uint OPEN_EXISTING = 3;
private const uint FILE_FLAG_BACKUP_SEMANTICS = 0x02000000;
private const uint FILE_FLAG_OPEN_REPARSE_POINT = 0x00200000;
private const uint FILE_ATTRIBUTE_REPARSE_POINT = 0x00000400;
private const int FileAttributeTagInfo = 9;
private const int FileDispositionInfo = 4;
private const int ERROR_FILE_EXISTS = 80;
private const int ERROR_ALREADY_EXISTS = 183;
[StructLayout(LayoutKind.Sequential)]
private struct FILE_ATTRIBUTE_TAG_INFO {
public uint FileAttributes;
public uint ReparseTag;
}
[StructLayout(LayoutKind.Sequential)]
private struct BY_HANDLE_FILE_INFORMATION {
public uint FileAttributes;
public System.Runtime.InteropServices.ComTypes.FILETIME CreationTime;
public System.Runtime.InteropServices.ComTypes.FILETIME LastAccessTime;
public System.Runtime.InteropServices.ComTypes.FILETIME LastWriteTime;
public uint VolumeSerialNumber;
public uint FileSizeHigh;
public uint FileSizeLow;
public uint NumberOfLinks;
public uint FileIndexHigh;
public uint FileIndexLow;
}
[StructLayout(LayoutKind.Sequential)]
private struct FILE_DISPOSITION_INFO {
[MarshalAs(UnmanagedType.Bool)] public bool DeleteFile;
}
[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", SetLastError = true)]
private static extern bool GetFileInformationByHandleEx(
SafeFileHandle handle, int infoClass,
out FILE_ATTRIBUTE_TAG_INFO info, uint size);
[DllImport("kernel32.dll", SetLastError = true)]
private static extern bool GetFileInformationByHandle(
SafeFileHandle handle, out BY_HANDLE_FILE_INFORMATION info);
[DllImport("kernel32.dll", SetLastError = true)]
private static extern bool SetFileInformationByHandle(
SafeFileHandle handle, int infoClass,
ref FILE_DISPOSITION_INFO info, uint size);
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern uint GetFinalPathNameByHandleW(
SafeFileHandle handle, StringBuilder path, uint length, uint flags);
private static void ValidateRegular(SafeFileHandle handle, bool singleLink) {
FILE_ATTRIBUTE_TAG_INFO tag;
if (!GetFileInformationByHandleEx(
handle, FileAttributeTagInfo, out tag,
(uint)Marshal.SizeOf(typeof(FILE_ATTRIBUTE_TAG_INFO))))
throw new Win32Exception(Marshal.GetLastWin32Error());
// Refuse only name-surrogate reparse points (symlinks, junctions, and any
// unknown tag with bit 29 set): those are what path parsing follows. A
// OneDrive Files On-Demand placeholder (tag 0x9000601A) is a regular file
// that every other route reads; refusing it broke attestation, --show
// and --clear in every project under OneDrive (#275).
if ((tag.FileAttributes & FILE_ATTRIBUTE_REPARSE_POINT) != 0 &&
(tag.ReparseTag & 0x20000000) != 0)
throw new IOException("Refusing a reparse-point file.");
if ((tag.FileAttributes & (uint)FileAttributes.Directory) != 0)
throw new IOException("Refusing a directory where a regular file is required.");
if (singleLink) {
BY_HANDLE_FILE_INFORMATION info;
if (!GetFileInformationByHandle(handle, out info))
throw new Win32Exception(Marshal.GetLastWin32Error());
if (info.NumberOfLinks != 1)
throw new IOException("Refusing a multiply-linked attestation file.");
}
}
public static SafeFileHandle OpenRead(string path, bool singleLink) {
SafeFileHandle handle = CreateFileW(
path, GENERIC_READ | FILE_READ_ATTRIBUTES,
FILE_SHARE_READ, IntPtr.Zero, OPEN_EXISTING,
FILE_FLAG_OPEN_REPARSE_POINT, IntPtr.Zero);
if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
try { ValidateRegular(handle, singleLink); return handle; }
catch { handle.Dispose(); throw; }
}
public static SafeFileHandle ClaimWriter(string path) {
SafeFileHandle handle = CreateFileW(
path, DELETE | FILE_READ_ATTRIBUTES, 0, IntPtr.Zero, CREATE_NEW,
FILE_FLAG_OPEN_REPARSE_POINT, IntPtr.Zero);
if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
return handle;
}
public static SafeFileHandle OpenAttestationWrite(string path) {
uint access = GENERIC_READ | GENERIC_WRITE | DELETE | FILE_READ_ATTRIBUTES;
SafeFileHandle handle = CreateFileW(
path, access, 0, IntPtr.Zero, CREATE_NEW,
FILE_FLAG_OPEN_REPARSE_POINT, IntPtr.Zero);
if (handle.IsInvalid) {
int error = Marshal.GetLastWin32Error();
if (error != ERROR_FILE_EXISTS && error != ERROR_ALREADY_EXISTS)
throw new Win32Exception(error);
handle = CreateFileW(
path, access, 0, IntPtr.Zero, OPEN_EXISTING,
FILE_FLAG_OPEN_REPARSE_POINT, IntPtr.Zero);
if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
}
try { ValidateRegular(handle, true); return handle; }
catch { handle.Dispose(); throw; }
}
public static SafeFileHandle OpenDelete(string path) {
SafeFileHandle handle = CreateFileW(
path, DELETE | FILE_READ_ATTRIBUTES, 0, IntPtr.Zero, OPEN_EXISTING,
FILE_FLAG_OPEN_REPARSE_POINT, IntPtr.Zero);
if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
try { ValidateRegular(handle, true); return handle; }
catch { handle.Dispose(); throw; }
}
public static void DeleteOpened(SafeFileHandle handle) {
FILE_DISPOSITION_INFO info = new FILE_DISPOSITION_INFO { DeleteFile = true };
if (!SetFileInformationByHandle(
handle, FileDispositionInfo, ref info,
(uint)Marshal.SizeOf(typeof(FILE_DISPOSITION_INFO))))
throw new Win32Exception(Marshal.GetLastWin32Error());
}
public static string FinalPath(SafeFileHandle handle) {
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;
}
public static string FileIdentity(SafeFileHandle handle) {
BY_HANDLE_FILE_INFORMATION info;
if (!GetFileInformationByHandle(handle, out info))
throw new Win32Exception(Marshal.GetLastWin32Error());
return info.VolumeSerialNumber.ToString("X8") + ":" +
info.FileIndexHigh.ToString("X8") + info.FileIndexLow.ToString("X8");
}
public static string FinalDirectoryPath(string path) {
using (SafeFileHandle handle = OpenDirectory(path)) {
return FinalPath(handle);
}
}
public static SafeFileHandle OpenDirectory(string path) {
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());
return handle;
}
}
'@
}
$script:SecurityRootHandle = $null
$script:SecurityRootFinalPath = $null
if ($script:IsWindowsHost) {
$securityRootPath = (Get-Location).Path
if ($env:PWF_PLAN_ROOT) {
$pin = $env:PWF_PLAN_ROOT
# Windows PowerShell 5.1 has no IsPathFullyQualified; a drive-qualified
# local path is the only accepted shape, as in resolve-plan-dir.ps1.
$isUnc = $pin.StartsWith('\\') -or $pin.StartsWith('//')
if ($isUnc -or ($pin -notmatch '^[A-Za-z]:[\\/]')) {
Write-AttestationRefusal "[plan-attest] PWF_PLAN_ROOT=$(Format-Selector $env:PWF_PLAN_ROOT) must be an absolute local path. An explicit pin is a binding: nothing was attested and no other plan was substituted."
exit 1
}
$securityRootPath = $pin
}
if (Test-Path -LiteralPath $securityRootPath -PathType Container) {
$script:SecurityRootHandle = [PwfAttestationNative]::OpenDirectory($securityRootPath)
$script:SecurityRootFinalPath = [PwfAttestationNative]::FinalPath($script:SecurityRootHandle).TrimEnd('\', '/')
}
}
function Test-FinalPathWithinSecurityRoot {
param([string] $FinalPath)
if (-not $script:SecurityRootFinalPath) { return $false }
$candidate = $FinalPath.TrimEnd('\', '/')
if ([string]::Equals($candidate, $script:SecurityRootFinalPath, [StringComparison]::OrdinalIgnoreCase)) {
return $true
}
return $candidate.StartsWith(
$script:SecurityRootFinalPath + [IO.Path]::DirectorySeparatorChar,
[StringComparison]::OrdinalIgnoreCase
)
}
function Open-TrustedDirectory {
param([string] $ExpectedDirectory)
$handle = [PwfAttestationNative]::OpenDirectory($ExpectedDirectory)
try {
$finalPath = [PwfAttestationNative]::FinalPath($handle).TrimEnd('\', '/')
if (-not (Test-FinalPathWithinSecurityRoot $finalPath)) {
throw "Refusing a plan directory outside the frozen project root."
}
return [PSCustomObject]@{
Handle = $handle
FinalPath = $finalPath
Identity = [PwfAttestationNative]::FileIdentity($handle)
}
} catch {
$handle.Dispose()
throw
}
}
function Assert-HandleParent {
param(
[Microsoft.Win32.SafeHandles.SafeFileHandle] $Handle,
[string] $ExpectedDirectoryFinal,
[string] $ExpectedDirectoryIdentity
)
if (-not $script:IsWindowsHost) { return }
$openedPath = [PwfAttestationNative]::FinalPath($Handle)
$openedParent = (Split-Path -Parent $openedPath).TrimEnd('\', '/')
if (-not [string]::Equals($openedParent, $ExpectedDirectoryFinal, [StringComparison]::OrdinalIgnoreCase)) {
throw "Refusing file outside the expected plan directory."
}
$parentHandle = [PwfAttestationNative]::OpenDirectory($openedParent)
try {
$openedIdentity = [PwfAttestationNative]::FileIdentity($parentHandle)
if (-not [string]::Equals($openedIdentity, $ExpectedDirectoryIdentity, [StringComparison]::Ordinal)) {
throw "Refusing a file whose parent directory identity changed."
}
} finally {
$parentHandle.Dispose()
}
}
function Open-SafeReadStream {
param([string] $Path, [string] $ExpectedDirectory, [switch] $SingleLink)
if (-not $script:IsWindowsHost) {
throw "[plan-attest] Safe no-follow descriptor operations are unavailable in this PowerShell script on Unix. Use scripts/attest-plan.sh instead."
}
$directory = Open-TrustedDirectory -ExpectedDirectory $ExpectedDirectory
try {
$handle = [PwfAttestationNative]::OpenRead($Path, [bool]$SingleLink)
try {
Assert-HandleParent -Handle $handle -ExpectedDirectoryFinal $directory.FinalPath -ExpectedDirectoryIdentity $directory.Identity
return New-Object System.IO.FileStream($handle, [IO.FileAccess]::Read)
} catch {
$handle.Dispose()
throw
}
} finally {
$directory.Handle.Dispose()
}
}
function Read-SafeText {
param([string] $Path, [string] $ExpectedDirectory, [int64] $MaxBytes)
$stream = Open-SafeReadStream -Path $Path -ExpectedDirectory $ExpectedDirectory -SingleLink
try {
if ($stream.Length -gt $MaxBytes) { throw "Refusing oversized metadata file."
}
$buffer = New-Object byte[] ([int]$stream.Length)
$offset = 0
while ($offset -lt $buffer.Length) {
$read = $stream.Read($buffer, $offset, $buffer.Length - $offset)
if ($read -le 0) { break }
$offset += $read
}
return [Text.Encoding]::UTF8.GetString($buffer, 0, $offset)
} finally {
$stream.Dispose()
}
}
function Write-SafeAscii {
param([string] $Path, [string] $ExpectedDirectory, [string] $Value)
$bytes = [Text.Encoding]::ASCII.GetBytes($Value)
if (-not $script:IsWindowsHost) {
throw "[plan-attest] Safe no-follow descriptor operations are unavailable in this PowerShell script on Unix. Use scripts/attest-plan.sh instead."
}
$directory = Open-TrustedDirectory -ExpectedDirectory $ExpectedDirectory
try {
$handle = [PwfAttestationNative]::OpenAttestationWrite($Path)
try {
Assert-HandleParent -Handle $handle -ExpectedDirectoryFinal $directory.FinalPath -ExpectedDirectoryIdentity $directory.Identity
$stream = New-Object System.IO.FileStream($handle, [IO.FileAccess]::ReadWrite)
$handle = $null
try {
$stream.SetLength(0)
$stream.Write($bytes, 0, $bytes.Length)
$stream.Flush($true)
$stream.Position = 0
$verify = New-Object byte[] $bytes.Length
$read = $stream.Read($verify, 0, $verify.Length)
return [Text.Encoding]::ASCII.GetString($verify, 0, $read)
} finally {
$stream.Dispose()
}
} finally {
if ($handle) { $handle.Dispose() }
}
} finally {
$directory.Handle.Dispose()
}
}
function Remove-SafeFile {
param([string] $Path, [string] $ExpectedDirectory)
if (-not $script:IsWindowsHost) {
throw "[plan-attest] Safe no-follow descriptor operations are unavailable in this PowerShell script on Unix. Use scripts/attest-plan.sh instead."
}
$directory = Open-TrustedDirectory -ExpectedDirectory $ExpectedDirectory
try {
$handle = [PwfAttestationNative]::OpenDelete($Path)
try {
Assert-HandleParent -Handle $handle -ExpectedDirectoryFinal $directory.FinalPath -ExpectedDirectoryIdentity $directory.Identity
[PwfAttestationNative]::DeleteOpened($handle)
} finally {
$handle.Dispose()
}
} finally {
$directory.Handle.Dispose()
}
}
function Resolve-ContainedPlanFile {
param(
[string] $Candidate,
[string] $ExpectedDirectory
)
if (-not (Test-Path -LiteralPath $Candidate -PathType Leaf)) { return $null }
try {
$stream = Open-SafeReadStream -Path $Candidate -ExpectedDirectory $ExpectedDirectory
$stream.Dispose()
return (Get-Item -LiteralPath $Candidate -Force -ErrorAction Stop).FullName
} catch { return $null }
}
function Test-SlugPlanDirectory {
param([string] $Directory)
try {
$finalDirectory = [PwfAttestationNative]::FinalDirectoryPath($Directory)
} catch {
return $false
}
$planningDirectory = Split-Path -Parent $finalDirectory
$planId = Split-Path -Leaf $finalDirectory
return (
(Split-Path -Leaf $planningDirectory) -eq ".planning" -and
$planId -match '^[A-Za-z0-9_][A-Za-z0-9._-]*$'
)
}
function Resolve-PlanFile {
$resolver = Join-Path $PSScriptRoot "resolve-plan-dir.ps1"
if (-not (Test-Path -LiteralPath $resolver -PathType Leaf)) { return $null }
if ($Target) {
if ($Target -ceq "root") {
# A missing pin has no frozen root to read a plan from.
if (-not $script:SecurityRootFinalPath) {
$script:PlanResolutionFailure = "Target"
return $null
}
$rootPlan = Join-Path $securityRootPath "task_plan.md"
$resolvedRoot = Resolve-ContainedPlanFile -Candidate $rootPlan -ExpectedDirectory $securityRootPath
if (-not $resolvedRoot) { $script:PlanResolutionFailure = "Target" }
return $resolvedRoot
}
# \z, because $ also matches before a final newline. Win32 drops a
# trailing dot, so alpha. would be another spelling of alpha.
if ($Target -notmatch '^[A-Za-z0-9_][A-Za-z0-9._-]*\z' -or $Target.EndsWith('.')) {
$script:PlanResolutionFailure = "Target"
return $null
}
$hadPlanId = Test-Path Env:PLAN_ID
$previousPlanId = $env:PLAN_ID
try {
$env:PLAN_ID = $Target
$targetDir = @(& $resolver | Where-Object { $_ }) | Select-Object -First 1
} finally {
if ($hadPlanId) { $env:PLAN_ID = $previousPlanId }
else { Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue }
}
if ($targetDir) {
$targetPlan = Join-Path $targetDir "task_plan.md"
$resolvedTarget = Resolve-ContainedPlanFile -Candidate $targetPlan -ExpectedDirectory $targetDir
if ($resolvedTarget) { return $resolvedTarget }
}
$script:PlanResolutionFailure = "Target"
return $null
}
$resolvedDir = @(& $resolver | Where-Object { $_ }) | Select-Object -First 1
if (-not $resolvedDir -and ((& $resolver -CheckAmbiguity) -eq "PWF_PLAN_AMBIGUOUS_V1")) {
$script:PlanResolutionFailure = "Ambiguous"
return $null
}
if ($resolvedDir) {
$planFile = Join-Path $resolvedDir "task_plan.md"
$resolvedPlan = Resolve-ContainedPlanFile -Candidate $planFile -ExpectedDirectory $resolvedDir
if ($resolvedPlan) { return $resolvedPlan }
if (Test-Path -LiteralPath $planFile) {
$script:PlanResolutionFailure = "ResolvedPlan"
} elseif ($env:PLAN_ID) {
$script:PlanResolutionFailure = "PLAN_ID"
} elseif ($env:PWF_PLAN_ROOT) {
$script:PlanResolutionFailure = "PWF_PLAN_ROOT"
}
return $null
}
# An explicit pin or a scoped selector that failed validation must never
# fall through and attest an unrelated legacy-root plan.
if ($env:PWF_PLAN_ROOT -and -not $script:SecurityRootFinalPath) {
$script:PlanResolutionFailure = "PWF_PLAN_ROOT"
return $null
}
if ($env:PLAN_ID) {
$script:PlanResolutionFailure = "PLAN_ID"
return $null
}
if ($env:PWF_PLAN_ROOT) {
$script:PlanResolutionFailure = "PWF_PLAN_ROOT"
return $null
}
$activePointer = Join-Path (Join-Path (Get-Location) ".planning") ".active_plan"
$activePointerItem = Get-Item -LiteralPath $activePointer -Force -ErrorAction SilentlyContinue
if ($activePointerItem) { return $null }
$currentDirectory = (Get-Location).Path
if (Test-SlugPlanDirectory $currentDirectory) {
$slugPlan = Join-Path $currentDirectory "task_plan.md"
return (Resolve-ContainedPlanFile -Candidate $slugPlan -ExpectedDirectory $currentDirectory)
}
$legacy = Join-Path $currentDirectory "task_plan.md"
return (Resolve-ContainedPlanFile -Candidate $legacy -ExpectedDirectory $currentDirectory)
}
function Get-AttestationPath {
param([string] $PlanFile)
$planDir = Split-Path -Parent $PlanFile
$cwd = (Get-Location).Path
if ($Target -ceq "root") {
return (Join-Path $planDir ".plan-attestation")
}
if ($planDir -eq $cwd) {
if (Test-SlugPlanDirectory $cwd) {
return (Join-Path $cwd ".attestation")
}
return (Join-Path $cwd ".plan-attestation")
}
return (Join-Path $planDir ".attestation")
}
$script:PlanResolutionFailure = $null
$planFile = Resolve-PlanFile
if (-not $planFile) {
if ($script:PlanResolutionFailure -eq "Ambiguous") {
Write-AttestationRefusal "[plan-attest] Multiple plans are available. Set PLAN_ID=<slug>; nothing was attested."
} elseif ($script:PlanResolutionFailure -eq "Target") {
Write-AttestationRefusal "[plan-attest] -Target $(Format-Selector $Target) did not resolve to a plan. An explicit target is a binding: nothing was attested and no other plan was substituted."
} elseif ($script:PlanResolutionFailure -eq "PLAN_ID") {
Write-AttestationRefusal "[plan-attest] PLAN_ID=$(Format-Selector $env:PLAN_ID) names no plan directory under .planning. An explicit selector is a binding: nothing was attested and no other plan was substituted."
} elseif ($script:PlanResolutionFailure -eq "PWF_PLAN_ROOT") {
Write-PinRefusal
} elseif ($script:PlanResolutionFailure -eq "ResolvedPlan") {
Write-AttestationRefusal "[plan-attest] The selected plan could not be read safely; nothing was attested."
} else {
Write-AttestationRefusal "[plan-attest] No task_plan.md found. Create a plan first."
}
exit 1
}
$attestationFile = Get-AttestationPath -PlanFile $planFile
$attestationDir = Split-Path -Parent $attestationFile
if ($Show) {
if (Get-Item -LiteralPath $attestationFile -Force -ErrorAction SilentlyContinue) {
Write-Output "Plan: $planFile"
Write-Output "Attestation: $attestationFile"
Write-Output ("SHA-256: " + (Read-SafeText -Path $attestationFile -ExpectedDirectory $attestationDir -MaxBytes 4096).Trim())
# Nonce (security A1.4): surface the per-plan nonce if init-session
# generated one next to the attestation. Informational only here; the
# hooks consume it to build collision-proof BEGIN/END delimiters.
$nonceFile = Join-Path (Split-Path -Parent $attestationFile) ".nonce"
if (Get-Item -LiteralPath $nonceFile -Force -ErrorAction SilentlyContinue) {
$nonceVal = (Read-SafeText -Path $nonceFile -ExpectedDirectory $attestationDir -MaxBytes 4096).Trim()
if ($nonceVal) { Write-Output "Nonce: $nonceVal" }
}
} else {
Write-Output "[plan-attest] No attestation set for $planFile."
exit 1
}
exit 0
}
$writerDirectory = Open-TrustedDirectory -ExpectedDirectory $attestationDir
try {
$claim = [PwfAttestationNative]::ClaimWriter($attestationFile + ".writer-lock")
try {
Assert-HandleParent -Handle $claim -ExpectedDirectoryFinal $writerDirectory.FinalPath -ExpectedDirectoryIdentity $writerDirectory.Identity
if ($Clear) {
if (Get-Item -LiteralPath $attestationFile -Force -ErrorAction SilentlyContinue) {
Remove-SafeFile -Path $attestationFile -ExpectedDirectory $attestationDir
Write-Output "[plan-attest] Cleared attestation for $planFile."
} else {
Write-Output "[plan-attest] No attestation to clear."
}
exit 0
}
$planStream = Open-SafeReadStream -Path $planFile -ExpectedDirectory (Split-Path -Parent $planFile)
try {
$sha256 = [Security.Cryptography.SHA256]::Create()
try {
$hashBytes = $sha256.ComputeHash($planStream)
} finally {
$sha256.Dispose()
}
} finally {
$planStream.Dispose()
}
$hashVal = ([BitConverter]::ToString($hashBytes)).Replace("-", "").ToLowerInvariant()
$storedHash = Write-SafeAscii -Path $attestationFile -ExpectedDirectory $attestationDir -Value $hashVal
# Integrity verification (security A2.1): confirm the on-disk attestation
# matches the intended hash before reporting success. A silent write failure
# (permissions, full disk) must not leave a stale attestation and exit clean.
if ($null -ne $storedHash) { $storedHash = $storedHash.Trim() }
if ($storedHash -ne $hashVal) {
Write-AttestationRefusal "[plan-attest] Attestation write verification FAILED for $attestationFile. Expected $hashVal, found $storedHash. The plan is NOT attested."
exit 1
}
$short = $hashVal.Substring(0, 12)
Write-Output "[plan-attest] Locked $planFile"
Write-Output "[plan-attest] SHA-256: $short... (stored in $attestationFile)"
Write-Output "[plan-attest] Hooks will block injection if the file is modified without re-running this command."
exit 0
} finally {
try { [PwfAttestationNative]::DeleteOpened($claim) } finally { $claim.Dispose() }
}
} finally {
$writerDirectory.Handle.Dispose()
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |