@danmoisan/drm-copilot-mcp 1.0.26 → 1.1.0

package/resources/claude-customizations/.claude/hooks/enforce-pr-author-skill.ps1

@@ -4,9 +4,9 @@
 
 .DESCRIPTION
     Invoked by the Claude Code PreToolUse hook before any Bash command runs. Reads
-    tool input JSON from the CLAUDE_TOOL_INPUT environment variable, inspects the
-    attempted command, and blocks gh pr create / gh pr edit commands that bypass the
-    pr-author skill workflow.
+    the hook payload through the shared reader, extracts the attempted command from the
+    envelope's nested tool_input, and blocks gh pr create / gh pr edit commands that
+    bypass the pr-author skill workflow.
 
     Required sequence:
       1. mcp__drm-copilot__collect_pr_context writes artifacts/pr_context.summary.txt
@@ -43,6 +43,8 @@
 [CmdletBinding()]
 param()
 
+
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
 $script:PrContextArtifactPath = 'artifacts/pr_context.summary.txt'
 $script:OrchestratorStateCheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
 
@@ -141,235 +143,39 @@ function Get-PrContextSummaryLastWriteUtc {
 
 . (Join-Path $PSScriptRoot 'enforce-pr-author-skill.epic-base-branch.ps1')
 
-function Test-PrAuthorReceiptVerification {
-    <#
-    .SYNOPSIS
-        Verify the SHA-256 receipt and return a block-reason string, or $null when verified.
-    .DESCRIPTION
-        Runs the six ordered receipt checks on the --body-file-with-context path. Each check is its
-        own short-circuiting branch; the first failure returns its reason code:
-          1. PR_BODY_PATH_NONCANONICAL        - --body-file path does not match the canonical
-                                                 artifacts/pr_body_<N>.md pattern (case-sensitive).
-          2. PR_AUTHOR_RECEIPT_MISSING        - sibling artifacts/pr_body_<N>.receipt.json absent.
-          3. PR_AUTHOR_RECEIPT_NUMBER_MISMATCH- receipt.number (integer) != <N> from the path.
-          4. PR_AUTHOR_RECEIPT_HASH_MISMATCH  - inline SHA-256 (lowercase hex) of the body bytes
-                                                 != receipt.sha256.
-          5. PR_AUTHOR_RECEIPT_STALE          - receipt.created_at (UTC) not strictly newer than the
-                                                 context summary last-write time.
-          6. EPIC_BASE_BRANCH_MISMATCH        - under epic_mode, gh pr create does not carry a
-                                                 matching --base <epic_context.integration_branch>.
-        Returns $null when all six checks pass (allow). All disk access flows through the four
-        injectable seams (Get-PrBodyFileBytes, Get-PrAuthorReceiptContent,
-        Get-PrContextSummaryLastWriteUtc, Get-PrAuthorCheckpointContent); SHA-256 is computed
-        inline. This is a policy-level integrity check, not a cryptographic control: any actor
-        with Write access to artifacts/ can replace the body file and the receipt together.
-    .PARAMETER CommandText
-        The Bash command text containing the --body-file argument.
-    .OUTPUTS
-        System.String or $null
-    #>
-    [CmdletBinding()]
-    [OutputType([string])]
-    param(
-        [Parameter(Mandatory)]
-        [string] $CommandText
-    )
-
-    # Check 1: the --body-file argument must match the canonical artifacts/pr_body_<N>.md pattern.
-    # The match is case-sensitive (-cmatch) so a non-canonical path is rejected before any read.
-    if ($CommandText -cnotmatch '--body-file\s+artifacts/pr_body_(\d+)\.md\b') {
-        return "PR_BODY_PATH_NONCANONICAL: ``--body-file`` must reference a canonical ``artifacts/pr_body_<N>.md`` file produced by the pr-author skill. The path supplied does not match ``artifacts/pr_body_<N>.md``."
-    }
-
-    $bodyNumber = [int]$Matches[1]
-    $bodyFilePath = "artifacts/pr_body_$bodyNumber.md"
-    $receiptFilePath = "artifacts/pr_body_$bodyNumber.receipt.json"
-
-    # Check 2: the sibling receipt file must exist (read via the injectable seam).
-    $receiptRaw = Get-PrAuthorReceiptContent -ReceiptFilePath $receiptFilePath
-    if ([string]::IsNullOrWhiteSpace($receiptRaw)) {
-        return "PR_AUTHOR_RECEIPT_MISSING: ``$receiptFilePath`` is absent. The pr-author agent must write the SHA-256 receipt alongside ``$bodyFilePath`` before issuing ``gh pr create``/``gh pr edit --body-file``."
-    }
-
-    # A receipt that is present but not valid JSON cannot be verified; treat it as missing content.
-    try {
-        $receipt = $receiptRaw | ConvertFrom-Json -ErrorAction Stop
-    } catch {
-        return "PR_AUTHOR_RECEIPT_MISSING: ``$receiptFilePath`` is not valid JSON. The pr-author agent must write a well-formed receipt with ``number``, ``sha256``, and ``created_at``."
-    }
-
-    # Check 3: the receipt number must equal the <N> extracted from the canonical path.
-    $receiptNumber = $null
-    $parsedNumber = 0
-    if ([int]::TryParse([string]$receipt.number, [ref] $parsedNumber)) {
-        $receiptNumber = $parsedNumber
-    }
-    if ($receiptNumber -ne $bodyNumber) {
-        return "PR_AUTHOR_RECEIPT_NUMBER_MISMATCH: ``$receiptFilePath`` ``number`` ($($receipt.number)) does not equal the body-file number ($bodyNumber). The receipt must bind to ``$bodyFilePath``."
-    }
-
-    # Check 4: the inline SHA-256 (lowercase hex) of the body bytes must equal receipt.sha256.
-    $bodyBytes = Get-PrBodyFileBytes -BodyFilePath $bodyFilePath
-    if ($null -eq $bodyBytes) {
-        return "PR_AUTHOR_RECEIPT_HASH_MISMATCH: ``$bodyFilePath`` could not be read to verify its SHA-256 against ``$receiptFilePath``."
-    }
-
-    $sha256 = [System.Security.Cryptography.SHA256]::Create()
-    try {
-        $hashBytes = $sha256.ComputeHash($bodyBytes)
-    } finally {
-        $sha256.Dispose()
-    }
-    $computedHash = ([System.BitConverter]::ToString($hashBytes) -replace '-', '').ToLowerInvariant()
-
-    if ($computedHash -ne ([string]$receipt.sha256).ToLowerInvariant()) {
-        return "PR_AUTHOR_RECEIPT_HASH_MISMATCH: the SHA-256 of ``$bodyFilePath`` does not equal ``sha256`` in ``$receiptFilePath``. The body file was modified after the receipt was written."
-    }
-
-    # Check 5: receipt.created_at (UTC) must be strictly newer than the context summary last-write.
-    $createdAt = [DateTime]::MinValue
-    $createdParsed = [DateTime]::TryParse(
-        [string]$receipt.created_at,
-        [System.Globalization.CultureInfo]::InvariantCulture,
-        [System.Globalization.DateTimeStyles]::AdjustToUniversal -bor [System.Globalization.DateTimeStyles]::AssumeUniversal,
-        [ref] $createdAt)
-    if (-not $createdParsed) {
-        return "PR_AUTHOR_RECEIPT_STALE: ``$receiptFilePath`` has a missing or unparseable ``created_at``. The pr-author agent must record a UTC ISO-8601 ``created_at`` strictly newer than ``$script:PrContextArtifactPath``."
-    }
-
-    $contextLastWrite = Get-PrContextSummaryLastWriteUtc
-    if (($null -eq $contextLastWrite) -or ($createdAt -le $contextLastWrite)) {
-        return "PR_AUTHOR_RECEIPT_STALE: ``$receiptFilePath`` ``created_at`` is not strictly newer than the last-write time of ``$script:PrContextArtifactPath``. The pr-author agent must regenerate the body and receipt after refreshing the PR context."
-    }
-
-    # Check 6: under epic_mode, gh pr create must carry a matching --base override.
-    $epicBaseBranchReason = Test-EpicBaseBranchOverride -CommandText $CommandText
-    if ($epicBaseBranchReason) {
-        return $epicBaseBranchReason
-    }
-
-    return $null
-}
-
-function Get-PrAuthorBypassReason {
-    <#
-    .SYNOPSIS
-        Inspect the command text and return a block reason string, or $null when the command is allowed.
-    .DESCRIPTION
-        Returns PR_AUTHOR_SKILL_BLOCKED when gh pr create or gh pr edit is run with --body (inline,
-        no --body-file), or when gh pr create is run with no body flag at all. Returns
-        PR_CONTEXT_MISSING when --body-file is present but the context artifact does not exist on
-        disk. When --body-file is present and the context artifact exists, verifies the SHA-256
-        receipt via Test-PrAuthorReceiptVerification and returns its block reason
-        (PR_BODY_PATH_NONCANONICAL / PR_AUTHOR_RECEIPT_*) when verification fails. Returns $null for
-        all allowed patterns. Cases A, B, and C are evaluated first and unchanged; receipt
-        verification only extends the previously-allowed --body-file-with-context path.
-    .PARAMETER CommandText
-        The Bash command text extracted from CLAUDE_TOOL_INPUT.
-    .PARAMETER ContextExists
-        Whether artifacts/pr_context.summary.txt currently exists on disk.
-    .OUTPUTS
-        System.String or $null
-    #>
-    [CmdletBinding()]
-    [OutputType([string])]
-    param(
-        [Parameter(Mandatory)]
-        [string] $CommandText,
-
-        [Parameter(Mandatory)]
-        [bool] $ContextExists
-    )
-
-    # Only act on gh pr create or gh pr edit subcommands.
-    $isPrCreate = $CommandText -match '(?i)\bgh\s+pr\s+create\b'
-    $isPrEdit = $CommandText -match '(?i)\bgh\s+pr\s+edit\b'
-
-    if (-not $isPrCreate -and -not $isPrEdit) {
-        return $null
-    }
-
-    $hasBodyFile = $CommandText -match '(?i)--body-file\b'
-    $hasInlineBody = $CommandText -match '(?i)--body(?!-file)\b'
-
-    # Case A: gh pr create OR gh pr edit with inline --body (not --body-file). Evaluated before the
-    # gh pr edit no-body allow short-circuit so inline-body edits are blocked, not allowed.
-    if (($isPrCreate -or $isPrEdit) -and $hasInlineBody -and -not $hasBodyFile) {
-        return "PR_AUTHOR_SKILL_BLOCKED: ``gh pr create`` and ``gh pr edit`` must use ``--body-file`` with a file produced by the pr-author skill from ``$script:PrContextArtifactPath``. Run ``mcp__drm-copilot__collect_pr_context`` to generate the context file, apply the pr-author skill to produce ``artifacts/pr_body_<N>.md``, then pass that file via ``--body-file``."
-    }
-
-    if ($isPrCreate) {
-        # Case B: gh pr create with no body flag at all.
-        if (-not $hasInlineBody -and -not $hasBodyFile) {
-            return "PR_AUTHOR_SKILL_BLOCKED: New PRs require ``--body-file``. Run ``mcp__drm-copilot__collect_pr_context`` to generate ``$script:PrContextArtifactPath``, apply the pr-author skill to produce ``artifacts/pr_body_<N>.md``, then pass that file via ``--body-file``."
-        }
-    }
-
-    if ($isPrEdit) {
-        # gh pr edit with no --body or --body-file (e.g., --title, --add-label, --reviewer) is allowed.
-        if (-not $hasInlineBody -and -not $hasBodyFile) {
-            return $null
-        }
-    }
-
-    # Case C: --body-file present but context artifact is absent.
-    if ($hasBodyFile -and -not $ContextExists) {
-        return "PR_CONTEXT_MISSING: ``$script:PrContextArtifactPath`` is absent. Run ``mcp__drm-copilot__collect_pr_context`` before creating or editing the PR body."
-    }
-
-    # Orchestrator-state preflight: runs inside this same PreToolUse hook (so it cannot be
-    # bypassed by invoking gh pr create/edit directly) before receipt verification.
-    if ($hasBodyFile -and $ContextExists) {
-        $preflightResult = Invoke-OrchestratorStatePreflight -CheckpointPath $script:OrchestratorStateCheckpointPath
-        if ($preflightResult.HasErrors) {
-            $preflightSummary = if ([string]::IsNullOrWhiteSpace($preflightResult.ErrorText)) {
-                "checkpoint missing at $script:OrchestratorStateCheckpointPath"
-            } else {
-                $preflightResult.ErrorText
-            }
-            return "ORCHESTRATOR_STATE_PREFLIGHT_FAILED: $preflightSummary"
-        }
-    }
-
-    # Receipt verification: extends, and does not replace, the previously-allowed path.
-    if ($hasBodyFile -and $ContextExists) {
-        $receiptReason = Test-PrAuthorReceiptVerification -CommandText $CommandText
-        if ($receiptReason) {
-            return $receiptReason
-        }
-    }
-
-    return $null
-}
+# Dot-source the receipt-verification and bypass-reason helpers. Guarded so dot-sourcing this
+# hook in tests loads the helpers too (issue #501 headroom split).
+. (Join-Path $PSScriptRoot 'enforce-pr-author-skill-helpers.ps1')
 
 function Invoke-PrAuthorSkillDecision {
     <#
     .SYNOPSIS
-        Parse CLAUDE_TOOL_INPUT and return an allow-or-block decision.
+        Parse the PreToolUse envelope and return an allow-or-block decision.
+    .DESCRIPTION
+        Envelope-level anomalies fail closed as a deny; missing command text inside a
+        well-formed tool_input remains an allow, because that is this gate's scope filter.
     .PARAMETER ToolInputRaw
-        The raw JSON tool payload supplied by Claude Code.
+        The raw JSON hook payload acquired by Read-ClaudeHookRawPayload.
     .OUTPUTS
         System.Collections.Specialized.OrderedDictionary
-    .NOTES
-        Missing tool input or missing command text is treated as allow.
     #>
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
     param(
+        [AllowNull()]
+        [AllowEmptyString()]
         [string] $ToolInputRaw
     )
 
-    if (-not $ToolInputRaw) {
-        return Get-PrAuthorSkillAllowDecision
+    $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
+    if (-not $payload.IsValid) {
+        return Get-PrAuthorSkillBlockDecision -Reason (
+            'PR_AUTHOR_SKILL_BLOCKED: payload anomaly - ' +
+            (Get-ClaudeHookPayloadAnomalyReason -Anomaly $payload.Anomaly) +
+            '. The gate fails closed on an envelope it cannot read.')
     }
 
-    try {
-        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
-    } catch {
-        throw "enforce-pr-author-skill hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
-    }
-
-    $commandText = $toolInput.command
+    $commandText = Get-ClaudeHookToolInputString -ToolInput $payload.Value -Name 'command'
     if (-not $commandText) {
         return Get-PrAuthorSkillAllowDecision
     }
@@ -433,7 +239,7 @@ function Test-PrAuthorBypassRequired {
     .SYNOPSIS
         Return $true when a Bash command requires the pr-author skill to run first.
     .PARAMETER CommandText
-        The Bash command text extracted from CLAUDE_TOOL_INPUT.
+        The Bash command text extracted from the envelope's tool_input.
     .PARAMETER ContextExists
         Whether artifacts/pr_context.summary.txt currently exists on disk.
     .OUTPUTS
@@ -452,18 +258,55 @@ function Test-PrAuthorBypassRequired {
     return ($null -ne (Get-PrAuthorBypassReason -CommandText $CommandText -ContextExists $ContextExists))
 }
 
+function Invoke-PrAuthorSkillEntryPoint {
+    <#
+    .SYNOPSIS
+        Runs the hook decision and returns the process exit code.
+    .DESCRIPTION
+        Acquires the payload through the shared reader unless the caller supplies
+        one, emits the compact decision JSON, and returns 0. It never returns 1:
+        exit 1 is non-blocking for PreToolUse, so every anomaly is already a deny
+        decision by the time control reaches here. The function does not call exit;
+        the thin tail converts the returned code into a process exit.
+    .PARAMETER ToolInputRaw
+        Optional pre-acquired payload text. When omitted the ReadPayload seam runs.
+    .PARAMETER ReadPayload
+        Seam for payload acquisition, so tests can drive the empty-on-all-transports
+        case without touching a console.
+    .OUTPUTS
+        System.Int32
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $ToolInputRaw,
+
+        [scriptblock] $ReadPayload = { Read-ClaudeHookRawPayload }
+    )
+
+    if (-not $PSBoundParameters.ContainsKey('ToolInputRaw')) {
+        $ToolInputRaw = [string](& $ReadPayload)
+    }
+
+    $decision = Invoke-PrAuthorSkillDecision -ToolInputRaw $ToolInputRaw
+    $decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
+
+    return 0
+}
+
 # Allow dot-sourcing in tests without executing the entrypoint.
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
 
-try {
-    $decision = Invoke-PrAuthorSkillDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
-} catch {
-    Write-Error $_
-    exit 1
+# The entry point returns its [int] exit code as the last pipeline element and the
+# decision JSON before it. `exit (<call>)` would capture BOTH into the exit
+# expression and emit nothing, so the decision is written explicitly here first.
+$entryPointResult = @(Invoke-PrAuthorSkillEntryPoint)
+if ($entryPointResult.Count -gt 1) {
+    $entryPointResult[0..($entryPointResult.Count - 2)] | Write-Output
 }
 
-$decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
-
-exit 0
+exit ([int]$entryPointResult[-1])

package/resources/claude-customizations/.claude/hooks/enforce-prd-feature-before-planner.ps1

@@ -1,12 +1,15 @@
 <#
 .SYNOPSIS
     Pre-tool-use hook that blocks atomic-planner delegations when the target
-    feature folder does not yet contain spec.md and user-story.md.
+    feature folder does not yet contain the prd-feature outputs its persisted
+    work mode requires.
 
 .DESCRIPTION
     Invoked by the Claude Code PreToolUse hook on the Agent (Task) tool. Reads
-    tool input JSON from the CLAUDE_TOOL_INPUT environment variable. Activates
-    only when subagent_type is 'atomic-planner'.
+    the tool payload through the shared hook-payload reader (stdin first, with
+    environment-variable fallback) and takes the tool arguments from the
+    envelope's nested tool_input object. Activates only when subagent_type is
+    'atomic-planner'.
 
     Feature folder resolution order:
       1. Scan the prompt text for any path matching
@@ -18,11 +21,25 @@
       3. If neither yields a folder, block with a reason instructing the caller
          to reference a feature folder explicitly.
 
-    Once the folder is resolved, the hook verifies that both spec.md and
-    user-story.md exist in that folder. If either is missing, the script emits a
-    PreToolUse JSON response with hookSpecificOutput.permissionDecision='deny'
-    and a reason naming the missing file(s) and instructing the orchestrator to
-    invoke prd-feature first. Allowed delegations emit
+    Once the folder is resolved, the hook reads the persisted work-mode marker
+    (`- Work Mode: minor-audit|full-feature|full-bug|full`) from that folder's
+    issue.md, per the mode contract in
+    .claude/skills/feature-promotion-lifecycle/SKILL.md, and derives the
+    required prerequisite set:
+      - full-feature -> spec.md and user-story.md are both required.
+      - full-bug     -> spec.md only is required.
+      - minor-audit  -> neither is required; issue.md carries the acceptance
+                        criteria for this mode.
+      - marker absent, unreadable, or unrecognized -> fail closed to the
+        strictest set (spec.md and user-story.md), and the block reason states
+        that the work mode could not be determined so the operator can tell
+        this case apart from a genuine missing prerequisite. The legacy `full`
+        marker normalizes to full-feature's requirement set.
+
+    If any required file is missing, the script emits a PreToolUse JSON
+    response with hookSpecificOutput.permissionDecision='deny' and a reason
+    naming the missing file(s) and instructing the orchestrator to invoke
+    prd-feature first. Allowed delegations emit
     hookSpecificOutput.permissionDecision='allow'.
 
     Filesystem reads and orchestrator-state lookups go through wrapper functions
@@ -34,6 +51,8 @@
 [CmdletBinding()]
 param()
 
+
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
 function Get-PrdFeatureFileExistence {
     <#
     .SYNOPSIS
@@ -49,6 +68,96 @@ function Get-PrdFeatureFileExistence {
     return [bool](Test-Path -LiteralPath $Path -PathType Leaf)
 }
 
+function Get-PrdFeatureIssueContent {
+    <#
+    .SYNOPSIS
+        Wrapper around Get-Content for a feature folder's issue.md. Tests mock
+        this directly to inject work-mode marker content without touching disk.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $FeatureFolder
+    )
+
+    $issuePath = "$FeatureFolder/issue.md"
+    if (-not (Test-Path -LiteralPath $issuePath -PathType Leaf)) {
+        return $null
+    }
+
+    try {
+        return Get-Content -LiteralPath $issuePath -Raw -ErrorAction Stop
+    }
+    catch {
+        return $null
+    }
+}
+
+function Resolve-PrdFeatureWorkMode {
+    <#
+    .SYNOPSIS
+        Parses the persisted `- Work Mode: ...` marker out of issue.md content
+        and returns the canonical mode, or $null when the marker is absent,
+        unreadable, or unrecognized.
+    .DESCRIPTION
+        Recognizes minor-audit, full-feature, full-bug, and the legacy full
+        marker (normalized to full-feature), mirroring the regex convention
+        used by scripts/dev_tools/prompt_mode_contract.py so both runtimes
+        agree on what counts as a valid marker line.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowNull()]
+        [string] $IssueContent
+    )
+
+    if ([string]::IsNullOrWhiteSpace($IssueContent)) {
+        return $null
+    }
+
+    $match = [regex]::Match($IssueContent, '(?im)^-\s*Work Mode:\s*(minor-audit|full-feature|full-bug|full)\s*$')
+    if (-not $match.Success) {
+        return $null
+    }
+
+    $rawMode = $match.Groups[1].Value
+    if ($rawMode -eq 'full') {
+        return 'full-feature'
+    }
+    return $rawMode
+}
+
+function Get-PrdFeatureRequiredFile {
+    <#
+    .SYNOPSIS
+        Maps a resolved work mode to the set of prd-feature output files the
+        target folder must contain before an atomic-planner delegation is
+        allowed.
+    .DESCRIPTION
+        full-feature requires spec.md and user-story.md; full-bug requires
+        spec.md only; minor-audit requires neither. A $null or unrecognized
+        mode fails closed to the strictest set (spec.md and user-story.md) so
+        an undeterminable mode never becomes permissive.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [AllowNull()]
+        [string] $WorkMode
+    )
+
+    # Route on the canonical mode; anything outside the three known values
+    # (including $null) falls through to the fail-closed default case.
+    switch ($WorkMode) {
+        'full-feature' { return [string[]]@('spec.md', 'user-story.md') }
+        'full-bug' { return [string[]]@('spec.md') }
+        'minor-audit' { return [string[]]@() }
+        default { return [string[]]@('spec.md', 'user-story.md') }
+    }
+}
+
 function Get-PrdFeatureCheckpointFolder {
     <#
     .SYNOPSIS
@@ -126,19 +235,22 @@ function Find-PrdFeatureFolderFromPrompt {
 function Get-PrdFeatureMissingFile {
     <#
     .SYNOPSIS
-        Returns the list of required files (spec.md, user-story.md) missing in
-        the target folder.
+        Returns the subset of $RequiredFile that is missing from the target
+        folder.
     #>
     [CmdletBinding()]
     [OutputType([string[]])]
     param(
         [Parameter(Mandatory)]
-        [string] $FeatureFolder
+        [string] $FeatureFolder,
+
+        [Parameter(Mandatory)]
+        [AllowEmptyCollection()]
+        [string[]] $RequiredFile
     )
 
-    $required = @('spec.md', 'user-story.md')
     [System.Collections.Generic.List[string]] $missing = [System.Collections.Generic.List[string]]::new()
-    foreach ($name in $required) {
+    foreach ($name in $RequiredFile) {
         $candidate = "$FeatureFolder/$name"
         if (-not (Get-PrdFeatureFileExistence -Path $candidate)) {
             $missing.Add($name)
@@ -150,7 +262,7 @@ function Get-PrdFeatureMissingFile {
 function Invoke-PrdFeatureBeforePlannerDecision {
     <#
     .SYNOPSIS
-        Parses CLAUDE_TOOL_INPUT and returns an allow-or-block decision.
+        Parses the envelope's nested tool_input and returns an allow-or-block decision.
     #>
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
@@ -158,23 +270,25 @@ function Invoke-PrdFeatureBeforePlannerDecision {
         [string] $ToolInputRaw
     )
 
-    if (-not $ToolInputRaw) {
-        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
-    }
-
-    try {
-        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
-    }
-    catch {
-        throw "enforce-prd-feature-before-planner hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    $envelope = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
+    if (-not $envelope.IsValid) {
+        return [ordered]@{
+            hookSpecificOutput = [ordered]@{
+                hookEventName            = 'PreToolUse'
+                permissionDecision       = 'deny'
+                permissionDecisionReason = 'PRD_FEATURE_BLOCKED: payload anomaly - ' +
+                (Get-ClaudeHookPayloadAnomalyReason -Anomaly $envelope.Anomaly) +
+                '. The gate fails closed on an envelope it cannot read.'
+            }
+        }
     }
 
-    $subagent = $toolInput.subagent_type
+    $subagent = Get-ClaudeHookToolInputString -ToolInput $envelope.Value -Name 'subagent_type'
     if (-not $subagent -or $subagent -ne 'atomic-planner') {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
-    $prompt = [string]$toolInput.prompt
+    $prompt = Get-ClaudeHookToolInputString -ToolInput $envelope.Value -Name 'prompt'
     $folder = Find-PrdFeatureFolderFromPrompt -Prompt $prompt
     if (-not $folder) {
         $folder = Get-PrdFeatureCheckpointFolder
@@ -191,17 +305,36 @@ function Invoke-PrdFeatureBeforePlannerDecision {
     }
 
     $folderNormalized = ($folder -replace '\\', '/').TrimEnd('/')
-    $missing = Get-PrdFeatureMissingFile -FeatureFolder $folderNormalized
+
+    # Derive the prerequisite set from the persisted work-mode marker rather
+    # than a fixed spec.md/user-story.md pair. A marker that cannot be read or
+    # recognized must fail closed to the strictest set, not fail open.
+    $issueContent = Get-PrdFeatureIssueContent -FeatureFolder $folderNormalized
+    $workMode = Resolve-PrdFeatureWorkMode -IssueContent $issueContent
+    $modeDetermined = [bool]$workMode
+    # Force array wrapping: PowerShell unravels a zero-element array return down
+    # the pipeline to $null, which would otherwise fail the Mandatory
+    # -RequiredFile parameter on Get-PrdFeatureMissingFile for minor-audit mode.
+    $required = @(Get-PrdFeatureRequiredFile -WorkMode $workMode)
+
+    $missing = Get-PrdFeatureMissingFile -FeatureFolder $folderNormalized -RequiredFile $required
     if ($missing.Count -eq 0) {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
     $list = ($missing -join ', ')
+    if ($modeDetermined) {
+        $reason = "PRD_FEATURE_BLOCKED: cannot delegate to atomic-planner before prd-feature outputs are present in '$folderNormalized'. Missing: $list (work mode: $workMode). Invoke the prd-feature subagent first."
+    }
+    else {
+        $reason = "PRD_FEATURE_BLOCKED: cannot delegate to atomic-planner before prd-feature outputs are present in '$folderNormalized'. Missing: $list. Work mode could not be determined from '$folderNormalized/issue.md' (marker absent, unreadable, or unrecognized); failing closed to the strictest prerequisite set (spec.md, user-story.md). Invoke the prd-feature subagent first."
+    }
+
     return [ordered]@{
         hookSpecificOutput = [ordered]@{
             hookEventName            = 'PreToolUse'
             permissionDecision       = 'deny'
-            permissionDecisionReason = "PRD_FEATURE_BLOCKED: cannot delegate to atomic-planner before prd-feature outputs are present in '$folderNormalized'. Missing: $list. Invoke the prd-feature subagent first."
+            permissionDecisionReason = $reason
         }
     }
 }
@@ -211,13 +344,7 @@ if ($MyInvocation.InvocationName -eq '.') {
     return
 }
 
-try {
-    $decision = Invoke-PrdFeatureBeforePlannerDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
-}
-catch {
-    Write-Error $_
-    exit 1
-}
+$decision = Invoke-PrdFeatureBeforePlannerDecision -ToolInputRaw (Read-ClaudeHookRawPayload)
 
 $decision | ConvertTo-Json -Compress -Depth 5 | Write-Output