@danmoisan/drm-copilot-mcp 1.0.0 → 1.0.7

package/resources/claude-customizations/.claude/hooks/enforce-epic-wave-barrier.ps1

@@ -0,0 +1,304 @@
+<#
+.SYNOPSIS
+    Pre-tool-use hook that is the Layer 1 per-call deterrent for the epic wave barrier.
+
+.DESCRIPTION
+    Invoked by the Claude Code PreToolUse hook on the "Agent" matcher before any Agent
+    (Task) call runs. Activates only when CLAUDE_TOOL_INPUT.subagent_type == "orchestrator"
+    and the serialized prompt contains the epic-mode kickoff marker "Epic mode: true".
+
+    Resolution and decision procedure:
+      1. Resolve the target child feature_folder from the prompt text by scanning for a
+         docs/features/active/<token> path, mirroring
+         enforce-prd-feature-before-planner.ps1's Find-PrdFeatureFolderFromPrompt
+         technique (longest match wins; a .md-suffixed match uses its parent directory).
+      2. Read artifacts/orchestration/epic-orchestrator-state.json and locate the
+         features[] record whose feature_folder equals the resolved basename.
+      3. Look up that feature's depends_on list, and for every dependency, locate its own
+         features[] record.
+      4. Deny with reason EPIC_WAVE_BARRIER_BLOCKED unless every dependency's merge_status
+         is merged or worktree_removed. A missing/unreadable checkpoint, an unresolved
+         target feature_folder, or a missing dependency record also denies (fail-closed).
+
+    This is the per-call deterrent (Layer 1) of the two-layer wave-barrier design; the
+    retrospective backstop (Layer 2) is the wave-barrier ordering invariant inside
+    validate_epic_orchestrator_state_text, enforced separately at epic-orchestrator
+    SubagentStop time.
+
+.NOTES
+    Compatible with PowerShell 7+. No external module dependencies. Filesystem reads go
+    through an injectable wrapper function so tests can mock the boundary without writing
+    temporary files.
+#>
+[CmdletBinding()]
+param()
+
+$script:EpicCheckpointPath = 'artifacts/orchestration/epic-orchestrator-state.json'
+$script:AllowedMergeStatuses = @('merged', 'worktree_removed')
+$script:EpicModeMarker = 'Epic mode: true'
+
+function Get-EpicWaveBarrierCheckpointContent {
+    <#
+    .SYNOPSIS
+        Read the raw JSON text of the epic checkpoint. Tests mock this function
+        (read seam).
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    if (-not (Test-Path -LiteralPath $script:EpicCheckpointPath -PathType Leaf)) {
+        return $null
+    }
+    return (Get-Content -LiteralPath $script:EpicCheckpointPath -Raw)
+}
+
+function Find-EpicWaveBarrierFeatureFolderFromPrompt {
+    <#
+    .SYNOPSIS
+        Scans a prompt string for docs/features/active/<...> path tokens and returns the
+        longest unique match's basename. Returns $null when no match is found.
+    .DESCRIPTION
+        Mirrors enforce-prd-feature-before-planner.ps1's
+        Find-PrdFeatureFolderFromPrompt technique: forward- or backslash-separated path
+        tokens are accepted, the longest match wins, and a .md-suffixed match resolves to
+        its parent directory before the basename is extracted.
+    .PARAMETER Prompt
+        The delegation prompt text under evaluation.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string] $Prompt
+    )
+
+    if (-not $Prompt) {
+        return $null
+    }
+
+    $pattern = 'docs[\\/]+features[\\/]+active[\\/]+[^\s"''`]+'
+    $matchList = [regex]::Matches($Prompt, $pattern)
+    if ($matchList.Count -eq 0) {
+        return $null
+    }
+
+    $unique = @{}
+    foreach ($m in $matchList) {
+        $normalized = ($m.Value -replace '\\', '/').TrimEnd('/')
+        $unique[$normalized] = $true
+    }
+
+    $candidates = @(@($unique.Keys) | Sort-Object -Property Length -Descending)
+    $best = $candidates[0]
+
+    if ($best -match '\.md$') {
+        $best = $best -replace '/[^/]+\.md$', ''
+    }
+
+    return ($best -split '/')[-1]
+}
+
+function Find-EpicWaveBarrierFeatureRecord {
+    <#
+    .SYNOPSIS
+        Locate the features[] record whose feature_folder equals the target basename.
+    .PARAMETER Checkpoint
+        Parsed epic checkpoint, or $null when absent/unreadable.
+    .PARAMETER FeatureFolder
+        The target feature_folder basename.
+    .OUTPUTS
+        System.Object or $null
+    #>
+    [CmdletBinding()]
+    param(
+        [AllowNull()]
+        $Checkpoint,
+
+        [AllowNull()]
+        [string] $FeatureFolder
+    )
+
+    if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($FeatureFolder)) {
+        return $null
+    }
+    $checkpointProps = @($Checkpoint.PSObject.Properties.Name)
+    if ($checkpointProps -notcontains 'features') {
+        return $null
+    }
+
+    # Scan every recorded feature for a feature_folder that equals the target basename.
+    foreach ($feature in @($Checkpoint.features)) {
+        $featureProps = @($feature.PSObject.Properties.Name)
+        if ($featureProps -notcontains 'feature_folder') {
+            continue
+        }
+        if (([string]$feature.feature_folder) -eq $FeatureFolder) {
+            return $feature
+        }
+    }
+    return $null
+}
+
+function Test-EpicWaveBarrierDependenciesMerged {
+    <#
+    .SYNOPSIS
+        Decision logic: true only when every dependency's merge_status is merged or
+        worktree_removed.
+    .PARAMETER Checkpoint
+        Parsed epic checkpoint, or $null when absent/unreadable.
+    .PARAMETER FeatureRecord
+        The target feature's own features[] record, or $null when not found.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()]
+        $Checkpoint,
+
+        [AllowNull()]
+        $FeatureRecord
+    )
+
+    if ($null -eq $Checkpoint -or $null -eq $FeatureRecord) {
+        return $false
+    }
+    $featureProps = @($FeatureRecord.PSObject.Properties.Name)
+    if ($featureProps -notcontains 'depends_on') {
+        # No dependencies recorded: an empty/absent depends_on list has nothing to block on.
+        return $true
+    }
+
+    $dependsOn = @($FeatureRecord.depends_on)
+    if ($dependsOn.Count -eq 0) {
+        return $true
+    }
+
+    # Every dependency edge must be durably confirmed merged or worktree_removed before
+    # this wave's feature is allowed to start.
+    foreach ($dependencyFolder in $dependsOn) {
+        $dependencyRecord = Find-EpicWaveBarrierFeatureRecord -Checkpoint $Checkpoint -FeatureFolder ([string]$dependencyFolder)
+        if ($null -eq $dependencyRecord) {
+            return $false
+        }
+        $dependencyProps = @($dependencyRecord.PSObject.Properties.Name)
+        if ($dependencyProps -notcontains 'merge_status') {
+            return $false
+        }
+        if ($script:AllowedMergeStatuses -notcontains ([string]$dependencyRecord.merge_status)) {
+            return $false
+        }
+    }
+    return $true
+}
+
+function Get-EpicWaveBarrierAllowDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param()
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName      = 'PreToolUse'
+            permissionDecision = 'allow'
+        }
+    }
+}
+
+function Get-EpicWaveBarrierBlockDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Reason
+    )
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = $Reason
+        }
+    }
+}
+
+function Invoke-EpicWaveBarrierDecision {
+    <#
+    .SYNOPSIS
+        Parses CLAUDE_TOOL_INPUT and returns an allow-or-block decision.
+    .PARAMETER ToolInputRaw
+        The raw JSON tool payload supplied by Claude Code.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $ToolInputRaw
+    )
+
+    if (-not $ToolInputRaw) {
+        return Get-EpicWaveBarrierAllowDecision
+    }
+
+    try {
+        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        throw "enforce-epic-wave-barrier hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    }
+
+    $subagent = $toolInput.subagent_type
+    if (-not $subagent -or $subagent -ne 'orchestrator') {
+        return Get-EpicWaveBarrierAllowDecision
+    }
+
+    $prompt = [string]$toolInput.prompt
+    if (-not $prompt -or $prompt -notlike "*$script:EpicModeMarker*") {
+        return Get-EpicWaveBarrierAllowDecision
+    }
+
+    $featureFolder = Find-EpicWaveBarrierFeatureFolderFromPrompt -Prompt $prompt
+    if (-not $featureFolder) {
+        return Get-EpicWaveBarrierBlockDecision -Reason 'EPIC_WAVE_BARRIER_BLOCKED: an epic-mode orchestrator delegation must reference the target feature folder in the prompt so its dependency edges can be verified.'
+    }
+
+    $checkpointRaw = Get-EpicWaveBarrierCheckpointContent
+    $checkpoint = $null
+    if (-not [string]::IsNullOrWhiteSpace($checkpointRaw)) {
+        try {
+            $checkpoint = $checkpointRaw | ConvertFrom-Json -ErrorAction Stop
+        } catch {
+            $checkpoint = $null
+        }
+    }
+
+    $featureRecord = Find-EpicWaveBarrierFeatureRecord -Checkpoint $checkpoint -FeatureFolder $featureFolder
+    if (Test-EpicWaveBarrierDependenciesMerged -Checkpoint $checkpoint -FeatureRecord $featureRecord) {
+        return Get-EpicWaveBarrierAllowDecision
+    }
+
+    return Get-EpicWaveBarrierBlockDecision -Reason "EPIC_WAVE_BARRIER_BLOCKED: '$featureFolder' cannot start until every dependency in its depends_on list is durably confirmed merged or worktree_removed in the epic checkpoint. The checkpoint was unreadable, the feature record was not found, or a dependency is not yet safe."
+}
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+try {
+    $decision = Invoke-EpicWaveBarrierDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
+} catch {
+    Write-Error $_
+    exit 1
+}
+
+$decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
+
+exit 0

package/resources/claude-customizations/.claude/hooks/enforce-epic-worktree-removal-gate.ps1

@@ -0,0 +1,237 @@
+<#
+.SYNOPSIS
+    Pre-tool-use hook that gates git worktree remove behind epic checkpoint merge state.
+
+.DESCRIPTION
+    Invoked by the Claude Code PreToolUse hook on the "Bash" matcher before any Bash
+    command runs. Regex-matches git worktree remove against CLAUDE_TOOL_INPUT.command,
+    extracts the target worktree path argument, reads
+    artifacts/orchestration/epic-orchestrator-state.json, and finds the features[] record
+    whose worktree_path matches. Allows removal only when that record's merge_status is
+    merged or worktree_removed. Denies with reason EPIC_WORKTREE_REMOVAL_BLOCKED when the
+    checkpoint is unreadable, no matching record exists, or merge_status is anything else -
+    fail-closed, following the enforce-orchestration-preimplementation-gate.ps1 precedent of
+    treating an unreadable/no-match checkpoint as deny.
+
+.NOTES
+    Compatible with PowerShell 7+. No external module dependencies. Filesystem reads go
+    through an injectable wrapper function so tests can mock the boundary without writing
+    temporary files.
+#>
+[CmdletBinding()]
+param()
+
+$script:EpicCheckpointPath = 'artifacts/orchestration/epic-orchestrator-state.json'
+$script:AllowedMergeStatuses = @('merged', 'worktree_removed')
+
+function Get-EpicWorktreeGateCheckpointContent {
+    <#
+    .SYNOPSIS
+        Read the raw JSON text of the epic checkpoint. Tests mock this function
+        (read seam).
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    if (-not (Test-Path -LiteralPath $script:EpicCheckpointPath -PathType Leaf)) {
+        return $null
+    }
+    return (Get-Content -LiteralPath $script:EpicCheckpointPath -Raw)
+}
+
+function Get-EpicWorktreeRemovalCommandPath {
+    <#
+    .SYNOPSIS
+        Extract the target worktree path argument from a git worktree remove command.
+    .PARAMETER CommandText
+        The Bash command text under evaluation.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $CommandText
+    )
+
+    if ($CommandText -match '(?i)\bgit\s+worktree\s+remove\s+(?<path>\S+)') {
+        return $Matches['path'].Trim('"''')
+    }
+    return $null
+}
+
+function Find-EpicWorktreeFeatureRecord {
+    <#
+    .SYNOPSIS
+        Locate the features[] record whose worktree_path matches the target path.
+    .PARAMETER Checkpoint
+        Parsed epic checkpoint, or $null when absent/unreadable.
+    .PARAMETER WorktreePath
+        The target worktree path extracted from the command text.
+    .OUTPUTS
+        System.Object or $null
+    #>
+    [CmdletBinding()]
+    param(
+        [AllowNull()]
+        $Checkpoint,
+
+        [AllowNull()]
+        [string] $WorktreePath
+    )
+
+    if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($WorktreePath)) {
+        return $null
+    }
+    $checkpointProps = @($Checkpoint.PSObject.Properties.Name)
+    if ($checkpointProps -notcontains 'features') {
+        return $null
+    }
+
+    $normalizedTarget = ($WorktreePath -replace '\\', '/').TrimEnd('/')
+
+    # Scan every recorded feature for a worktree_path that matches the removal target;
+    # path separators are normalized so Windows- and POSIX-style paths compare equal.
+    foreach ($feature in @($Checkpoint.features)) {
+        $featureProps = @($feature.PSObject.Properties.Name)
+        if ($featureProps -notcontains 'worktree_path') {
+            continue
+        }
+        $normalizedFeaturePath = (([string]$feature.worktree_path) -replace '\\', '/').TrimEnd('/')
+        if ($normalizedFeaturePath -eq $normalizedTarget) {
+            return $feature
+        }
+    }
+    return $null
+}
+
+function Test-EpicWorktreeRemovalAllowed {
+    <#
+    .SYNOPSIS
+        Decision logic: allow only when the matching feature record's merge_status is
+        merged or worktree_removed.
+    .PARAMETER FeatureRecord
+        The matched features[] record, or $null when no match was found.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()]
+        $FeatureRecord
+    )
+
+    if ($null -eq $FeatureRecord) {
+        return $false
+    }
+    $props = @($FeatureRecord.PSObject.Properties.Name)
+    if ($props -notcontains 'merge_status') {
+        return $false
+    }
+    return $script:AllowedMergeStatuses -contains ([string]$FeatureRecord.merge_status)
+}
+
+function Get-EpicWorktreeGateAllowDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param()
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName      = 'PreToolUse'
+            permissionDecision = 'allow'
+        }
+    }
+}
+
+function Get-EpicWorktreeGateBlockDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Reason
+    )
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = $Reason
+        }
+    }
+}
+
+function Invoke-EpicWorktreeRemovalGateDecision {
+    <#
+    .SYNOPSIS
+        Parses CLAUDE_TOOL_INPUT and returns an allow-or-block decision.
+    .PARAMETER ToolInputRaw
+        The raw JSON tool payload supplied by Claude Code.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $ToolInputRaw
+    )
+
+    if (-not $ToolInputRaw) {
+        return Get-EpicWorktreeGateAllowDecision
+    }
+
+    try {
+        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        throw "enforce-epic-worktree-removal-gate hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    }
+
+    $commandText = $toolInput.command
+    if (-not $commandText) {
+        return Get-EpicWorktreeGateAllowDecision
+    }
+
+    if ($commandText -notmatch '(?i)\bgit\s+worktree\s+remove\b') {
+        return Get-EpicWorktreeGateAllowDecision
+    }
+
+    $worktreePath = Get-EpicWorktreeRemovalCommandPath -CommandText $commandText
+
+    $checkpointRaw = Get-EpicWorktreeGateCheckpointContent
+    $checkpoint = $null
+    if (-not [string]::IsNullOrWhiteSpace($checkpointRaw)) {
+        try {
+            $checkpoint = $checkpointRaw | ConvertFrom-Json -ErrorAction Stop
+        } catch {
+            $checkpoint = $null
+        }
+    }
+
+    $featureRecord = Find-EpicWorktreeFeatureRecord -Checkpoint $checkpoint -WorktreePath $worktreePath
+    if (Test-EpicWorktreeRemovalAllowed -FeatureRecord $featureRecord) {
+        return Get-EpicWorktreeGateAllowDecision
+    }
+
+    return Get-EpicWorktreeGateBlockDecision -Reason "EPIC_WORKTREE_REMOVAL_BLOCKED: git worktree remove for '$worktreePath' requires a matching epic checkpoint features[] record with merge_status in {merged, worktree_removed}. The checkpoint was unreadable, no matching record was found, or merge_status was not yet safe for removal."
+}
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+try {
+    $decision = Invoke-EpicWorktreeRemovalGateDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
+} catch {
+    Write-Error $_
+    exit 1
+}
+
+$decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
+
+exit 0

package/resources/claude-customizations/.claude/hooks/enforce-evidence-locations.ps1

@@ -27,10 +27,11 @@
     is written to the tracked roots docs/features/<feature>/research/
     (feature-associated) or docs/research/ (one-off).
 
-    If the file_path resolves to a forbidden prefix, the script writes a JSON response
-    to stdout with 'decision': 'block' and exits with code 0 so Claude Code surfaces
-    the reason. For allowed paths, 'decision': 'allow' is written to stdout and the
-    script exits 0. On hard failure (malformed JSON input), the script exits 1.
+    If the file_path resolves to a forbidden prefix, the script writes a PreToolUse JSON
+    response to stdout with hookSpecificOutput.permissionDecision = 'deny' and exits with
+    code 0 so Claude Code surfaces the reason. For allowed paths, a PreToolUse response
+    with permissionDecision = 'allow' is written to stdout and the script exits 0. On hard
+    failure (malformed JSON input), the script exits 1.
 
 .NOTES
     Compatible with PowerShell 7+.
@@ -83,9 +84,9 @@ function Test-EvidenceLocationForbidden {
 function Get-EvidenceLocationBlockDecision {
     <#
     .SYNOPSIS
-        Constructs a block-decision ordered dictionary for the supplied forbidden path.
+        Constructs a deny-decision ordered dictionary for the supplied forbidden path.
     .PARAMETER FilePath
-        The file path that triggered the block.
+        The file path that triggered the deny decision.
     #>
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
@@ -95,8 +96,11 @@ function Get-EvidenceLocationBlockDecision {
     )
 
     [ordered]@{
-        decision = 'block'
-        reason   = "EVIDENCE_LOCATION_BLOCKED: '$FilePath' is not a canonical evidence location. Use <FEATURE>/evidence/<kind>/ instead. See .claude/skills/evidence-and-timestamp-conventions/SKILL.md for the canonical scheme."
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = "EVIDENCE_LOCATION_BLOCKED: '$FilePath' is not a canonical evidence location. Use <FEATURE>/evidence/<kind>/ instead. See .claude/skills/evidence-and-timestamp-conventions/SKILL.md for the canonical scheme."
+        }
     }
 }
 
@@ -115,7 +119,7 @@ function Invoke-EvidenceLocationDecision {
     )
 
     if (-not $ToolInputRaw) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
     try {
@@ -127,14 +131,14 @@ function Invoke-EvidenceLocationDecision {
 
     $filePath = $toolInput.file_path
     if (-not $filePath) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
     if (Test-EvidenceLocationForbidden -FilePath $filePath) {
         return Get-EvidenceLocationBlockDecision -FilePath $filePath
     }
 
-    return [ordered]@{ decision = 'allow' }
+    return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
 }
 
 function Invoke-EvidenceLocationEntryPoint {
@@ -163,7 +167,7 @@ function Invoke-EvidenceLocationEntryPoint {
         return 1
     }
 
-    $decision | ConvertTo-Json -Compress | Write-Output
+    $decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
 
     return 0
 }

package/resources/claude-customizations/.claude/hooks/enforce-feature-folder-order.ps1

@@ -10,9 +10,10 @@
     docs/features/(active|archive)/<folder>/plan.md, the script verifies that
     each of issue.md, spec.md, and user-story.md exists in the same folder.
 
-    If any of the three sibling files is missing, the script emits a JSON
-    response with decision='block' and exits 0 so Claude Code surfaces the
-    reason. All other paths pass through with decision='allow'.
+    If any of the three sibling files is missing, the script emits a PreToolUse
+    JSON response with hookSpecificOutput.permissionDecision='deny' and exits 0 so
+    Claude Code surfaces the reason. All other paths pass through with
+    permissionDecision='allow'.
 
     Filesystem reads go through Get-FeatureFolderFileExistence so tests can
     inject a fake without touching disk.
@@ -97,7 +98,7 @@ function Invoke-FeatureFolderOrderDecision {
     )
 
     if (-not $ToolInputRaw) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
     try {
@@ -109,24 +110,27 @@ function Invoke-FeatureFolderOrderDecision {
 
     $filePath = $toolInput.file_path
     if (-not $filePath) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
     $normalized = $filePath -replace '\\', '/'
 
     if (-not (Test-IsFeaturePlanPath -NormalizedPath $normalized)) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
     $missing = Get-FeatureFolderMissingFile -PlanFilePath $normalized
     if ($missing.Count -eq 0) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
     $list = ($missing -join ', ')
     return [ordered]@{
-        decision = 'block'
-        reason   = "FEATURE_FOLDER_ORDER_BLOCKED: cannot write plan.md before producing prerequisite documents. Missing in feature folder: $list. Invoke the prd-feature subagent to generate the missing file(s) before authoring plan.md."
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = "FEATURE_FOLDER_ORDER_BLOCKED: cannot write plan.md before producing prerequisite documents. Missing in feature folder: $list. Invoke the prd-feature subagent to generate the missing file(s) before authoring plan.md."
+        }
     }
 }
 
@@ -143,6 +147,6 @@ catch {
     exit 1
 }
 
-$decision | ConvertTo-Json -Compress | Write-Output
+$decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
 
 exit 0