Skip to content

OthmanAdi/planning-with-files / skills/i18n/planning-with-files-ar

planning-with-files-ar

Verified

تخطيط مستمر قائم على الملفات لعمل وكلاء الذكاء الاصطناعي متعدد الخطوات. يحتفظ بملفات task_plan.md و findings.md و progress.md على القرص، وتحقن خطافات دورة الحياة سياق التخطيط المحدد للمشروع. تقرأ الاستعادة التلقائية ملفات تخطيط المشروع فقط. يمكن للأمر الصريح session-catchup.py --metadata فحص بيانات وصفية لجلسات الوكيل المحلية التابعة للمشروع نفسه، بينما قد يصدر --replay مقتطفات محدودة مؤطرة بقيمة nonce. يمكن للوضع المحكوم الاختياري طلب المتابعة فقط عندما يدعمه المضيف، ولا ينفذ أبدًا أوامر معلنة في Markdown. لا تتضمن المهارة مسارًا لرفع البيانات عبر الشبكة. تُستخدم للبحث أو العمل الذي يحتاج إلى 5 استدعاءات أدوات أو أكثر.

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()
}
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall