Skip to content

OthmanAdi/planning-with-files / .continue/skills/planning-with-files

planning-with-files

Verified

Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; agent instructions read selected project planning context when invoked. 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. This adapter registers no lifecycle or Stop hook, never requests continuation, and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.

FileKindSize
SKILL.mdskill md13.6 KB
examples.mdmarkdown4.4 KB
plan-inventory.mdmarkdown9.3 KB
reference.mdmarkdown8.3 KB
scripts/attest-plan.ps1script27.4 KB
scripts/attest-plan.shscript27.4 KB
scripts/check-complete.ps1script12.8 KB
scripts/check-complete.shexecutablescript13.6 KB
scripts/init-session.ps1script19.5 KB
scripts/init-session.shexecutablescript15.4 KB
scripts/plan-doctor.shscript9.0 KB
scripts/resolve-plan-dir.ps1script11.5 KB
scripts/resolve-plan-dir.shscript15.3 KB
scripts/session-catchup.pyexecutablescript36.4 KB
scripts/set-active-plan.ps1executablescript42.7 KB
scripts/set-active-plan.shexecutablescript38.6 KB

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()
}
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: 472kUpdated Claude CodeCodexUnverifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall