@danmoisan/drm-copilot-mcp 1.0.27 → 1.1.1

package/resources/claude-customizations/.claude/hooks/enforce-promotion-mcp-only.ps1

@@ -4,8 +4,8 @@
 
 .DESCRIPTION
     This script is invoked by the Claude Code PreToolUse hook before any Bash
-    command runs. It reads the tool input from the CLAUDE_TOOL_INPUT environment
-    variable, inspects the attempted command text, and blocks direct promotion
+    command runs. It acquires the hook payload through the shared reader and reads
+    the command from the envelope's nested tool_input, then blocks direct promotion
     script execution that would bypass the repository's MCP-only promotion path.
 
     Forbidden command tokens (legacy promotion-script bypass):
@@ -29,6 +29,8 @@
 [CmdletBinding()]
 param()
 
+
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
 $script:PromotionMcpOnlyBlockedReason = 'PROMOTION_MCP_ONLY_BLOCKED: Direct Bash promotion-script execution is not allowed in agent sessions. Use the drm-copilot MCP promotion tools instead.'
 
 $script:PromotionMcpOnlyGhIssueBlockedReason = 'PROMOTION_MCP_ONLY_BLOCKED: Direct GitHub issue creation via `gh` bypasses the approved drm-copilot MCP promotion path (`mcp__drm-copilot__new_potential_entry` -> `mcp__drm-copilot__potential_to_issue` -> `mcp__drm-copilot__new_active_feature_folder`). Use those MCP tools instead.'
@@ -70,7 +72,7 @@ function Get-PromotionBypassReason {
         Returns the gh-CLI issue creation reason when a forbidden gh pattern is matched.
         Returns $null when the command is allowed.
     .PARAMETER CommandText
-        The Bash command text extracted from CLAUDE_TOOL_INPUT.
+        The Bash command text extracted from the envelope's tool_input.
     .OUTPUTS
         System.String or $null.
     #>
@@ -118,7 +120,7 @@ function Test-PromotionBypassToken {
     .SYNOPSIS
         Return $true when a Bash command contains a forbidden promotion bypass pattern.
     .PARAMETER CommandText
-        The Bash command text extracted from CLAUDE_TOOL_INPUT.
+        The Bash command text extracted from the envelope's tool_input.
     .OUTPUTS
         System.Boolean
     #>
@@ -183,7 +185,7 @@ function Get-PromotionMcpOnlyAllowDecision {
 function Invoke-PromotionMcpOnlyDecision {
     <#
     .SYNOPSIS
-        Parse CLAUDE_TOOL_INPUT and return an allow-or-block decision.
+        Parse the PreToolUse envelope and return an allow-or-block decision.
     .PARAMETER ToolInputRaw
         The raw JSON tool payload supplied by Claude Code.
     .OUTPUTS
@@ -198,17 +200,15 @@ function Invoke-PromotionMcpOnlyDecision {
         [string] $ToolInputRaw
     )
 
-    if (-not $ToolInputRaw) {
-        return Get-PromotionMcpOnlyAllowDecision
-    }
-
-    try {
-        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
-    } catch {
-        throw "enforce-promotion-mcp-only hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
+    if (-not $payload.IsValid) {
+        return Get-PromotionMcpOnlyBlockDecision -Reason (
+            'PROMOTION_MCP_ONLY_BLOCKED: payload anomaly - ' +
+            (Get-ClaudeHookPayloadAnomalyReason -Anomaly $payload.Anomaly) +
+            '. The gate fails closed on an envelope it cannot read.')
     }
 
-    $commandText = $toolInput.command
+    $commandText = Get-ClaudeHookToolInputString -ToolInput $payload.Value -Name 'command'
     if (-not $commandText) {
         return Get-PromotionMcpOnlyAllowDecision
     }
@@ -221,18 +221,55 @@ function Invoke-PromotionMcpOnlyDecision {
     return Get-PromotionMcpOnlyAllowDecision
 }
 
+function Invoke-PromotionMcpOnlyEntryPoint {
+    <#
+    .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-PromotionMcpOnlyDecision -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-PromotionMcpOnlyDecision -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-PromotionMcpOnlyEntryPoint)
+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-python-batch-budget.ps1

@@ -34,6 +34,8 @@
 [CmdletBinding()]
 param()
 
+
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
 function Get-PythonBatchBudgetState {
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
@@ -162,17 +164,15 @@ function Invoke-PythonBatchBudgetHook {
         }
     )
 
-    if (-not $ToolInputRaw) {
-        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
-    }
-
-    try {
-        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
-    } catch {
-        return Get-PythonBatchBudgetBlockDecision -Reason 'Python batch-budget hook received malformed JSON in CLAUDE_TOOL_INPUT.'
+    $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
+    if (-not $payload.IsValid) {
+        return Get-PythonBatchBudgetBlockDecision -Reason (
+            'Python batch-budget hook received an unreadable PreToolUse envelope: ' +
+            (Get-ClaudeHookPayloadAnomalyReason -Anomaly $payload.Anomaly) +
+            '. The gate fails closed on an envelope it cannot read.')
     }
 
-    $filePath = $toolInput.file_path
+    $filePath = Get-ClaudeHookToolInputString -ToolInput $payload.Value -Name 'file_path'
     if (-not $filePath) {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
@@ -211,28 +211,71 @@ function Invoke-PythonBatchBudgetHook {
     return $decision
 }
 
-if ($MyInvocation.InvocationName -eq '.') {
-    return
-}
+function Invoke-PythonBatchBudgetEntryPoint {
+    <#
+    .SYNOPSIS
+        Runs the Python batch-budget decision and returns the process exit code.
+    .DESCRIPTION
+        Wraps the dispatch logic that the hook entry point performs so it can be
+        exercised by unit tests. It acquires the payload through the shared reader
+        unless the caller supplies one, writes the compact JSON decision to the output
+        stream only when the decision is a deny (this hook is deny-only: an allow
+        decision emits nothing), and returns 0. This function does not call exit; the
+        thin entry-point wiring 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.
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $ToolInputRaw,
 
-$sessionId = $env:CLAUDE_SESSION_ID
-if (-not $sessionId) {
-    $sessionId = 'default'
-}
+        [scriptblock] $ReadPayload = { Read-ClaudeHookRawPayload }
+    )
 
-$prodCap = 3
-$testCap = 3
-if ($env:CLAUDE_PYTHON_BUDGET_PROD -match '^\d+$') {
-    $prodCap = [int]$env:CLAUDE_PYTHON_BUDGET_PROD
+    if (-not $PSBoundParameters.ContainsKey('ToolInputRaw')) {
+        $ToolInputRaw = [string](& $ReadPayload)
+    }
+
+    $sessionId = $env:CLAUDE_SESSION_ID
+    if (-not $sessionId) {
+        $sessionId = 'default'
+    }
+
+    $prodCap = 3
+    $testCap = 3
+    if ($env:CLAUDE_PYTHON_BUDGET_PROD -match '^\d+$') {
+        $prodCap = [int]$env:CLAUDE_PYTHON_BUDGET_PROD
+    }
+    if ($env:CLAUDE_PYTHON_BUDGET_TEST -match '^\d+$') {
+        $testCap = [int]$env:CLAUDE_PYTHON_BUDGET_TEST
+    }
+
+    $decision = Invoke-PythonBatchBudgetHook -ToolInputRaw $ToolInputRaw -SessionId $sessionId -ProdCap $prodCap -TestCap $testCap
+    if ($decision.hookSpecificOutput.permissionDecision -eq 'deny') {
+        $decision.Remove('state')
+        $decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
+    }
+
+    return 0
 }
-if ($env:CLAUDE_PYTHON_BUDGET_TEST -match '^\d+$') {
-    $testCap = [int]$env:CLAUDE_PYTHON_BUDGET_TEST
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
 }
 
-$decision = Invoke-PythonBatchBudgetHook -ToolInputRaw $env:CLAUDE_TOOL_INPUT -SessionId $sessionId -ProdCap $prodCap -TestCap $testCap
-if ($decision.hookSpecificOutput.permissionDecision -eq 'deny') {
-    $decision.Remove('state')
-    $decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
+# 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-PythonBatchBudgetEntryPoint)
+if ($entryPointResult.Count -gt 1) {
+    $entryPointResult[0..($entryPointResult.Count - 2)] | Write-Output
 }
 
-exit 0
+exit ([int]$entryPointResult[-1])

package/resources/claude-customizations/.claude/hooks/validate-bash.ps1

@@ -4,13 +4,14 @@
 
 .DESCRIPTION
     This script is invoked by the Claude Code PreToolUse hook before any Bash
-    command is executed. It reads the proposed command string from the
-    CLAUDE_TOOL_INPUT (or CLAUDE_HOOK_INPUT) environment variable (JSON with a
-    'command' field) or falls back to the first positional argument. If the
-    command matches any blocked pattern (destructive operations such as forced
-    deletions, forced pushes, or hard resets), the script writes a PreToolUse
-    deny decision to stdout and exits with code 0. The deny decision uses the
-    Claude Code PreToolUse schema:
+    command is executed. It acquires the hook payload through the shared reader
+    (.claude/lib/hook-payload/HookPayload.psm1: stdin first, then the two
+    environment-variable fallbacks) and reads the proposed command string from the
+    envelope's nested tool_input.command, or falls back to the first positional
+    argument. If the command matches any blocked pattern (destructive operations
+    such as forced deletions, forced pushes, or hard resets), the script writes a
+    PreToolUse deny decision to stdout and exits with code 0. The deny decision
+    uses the Claude Code PreToolUse schema:
 
         {"hookSpecificOutput":{"hookEventName":"PreToolUse",
          "permissionDecision":"deny","permissionDecisionReason":"<reason>"}}
@@ -20,6 +21,13 @@
     deny-path 'exit 1' are intentionally NOT used: PreToolUse fail-opens on both,
     so they would silently fail to block.
 
+    Deliberate exception to the fail-closed envelope policy (issue #501, AC-5): this
+    hook is a dangerous-command denylist, not a receipt gate, so an empty payload
+    remains an allow and unparseable raw text is still treated as the command text
+    for denylist matching. Both behaviours preserve the documented manual/CLI usage
+    'pwsh -NoProfile -File validate-bash.ps1 "<command>"'. Every other PreToolUse
+    hook denies on those two conditions.
+
 .NOTES
     Compatible with PowerShell 7+.
     This script must not modify any state; it is a read-only validation gate.
@@ -30,6 +38,8 @@ param(
     [string]$CommandInput
 )
 
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+
 function Get-BlockedBashPattern {
     [CmdletBinding()]
     [OutputType([string[]])]
@@ -119,14 +129,21 @@ function Get-BashCommandToCheck {
     )
 
     if ($ToolInputRaw) {
-        try {
-            $parsed = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
-            if ($parsed.command) {
-                return [string]$parsed.command
+        $parsed = ConvertFrom-ClaudeHookEnvelope -Raw $ToolInputRaw
+        if (-not $parsed.IsValid) {
+            # AC-5 exception: unparseable raw text is still treated as the command
+            # text, which is what the documented manual/CLI usage supplies.
+            if ($parsed.Anomaly -eq 'UnparseableJson') {
+                return [string]$ToolInputRaw
+            }
+        } else {
+            $extracted = Get-ClaudeHookToolInput -Envelope $parsed.Value
+            if ($extracted.IsValid) {
+                $command = Get-ClaudeHookToolInputString -ToolInput $extracted.Value -Name 'command'
+                if ($command) {
+                    return $command
+                }
             }
-        } catch {
-            # If JSON parsing fails, treat the raw input as the command.
-            return $ToolInputRaw
         }
     }
 
@@ -166,10 +183,7 @@ if ($MyInvocation.InvocationName -eq '.') {
     return
 }
 
-$toolInputRaw = $env:CLAUDE_TOOL_INPUT
-if (-not $toolInputRaw) {
-    $toolInputRaw = $env:CLAUDE_HOOK_INPUT
-}
+$toolInputRaw = Read-ClaudeHookRawPayload
 
 $decision = Invoke-ValidateBashDecision -ToolInputRaw $toolInputRaw -PositionalInput $CommandInput
 if ($null -ne $decision -and $decision.hookSpecificOutput.permissionDecision -eq 'deny') {

package/resources/claude-customizations/.claude/lib/blast-radius/BlastRadiusExtraction.psm1

@@ -44,6 +44,16 @@ Set-StrictMode -Version Latest
 # imports no sibling.
 Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusGlob.psm1') -Force
 
+# Test-MultipleFeatureFolderSpan moved to BlastRadiusTokenShape.psm1, joining the
+# new Test-PlaceholderMarker predicate that could not be added here: this module
+# had two lines of headroom against the 500-line limit (issue #502). Both
+# predicates are context-free shape tests, so they form one cohesive leaf. The
+# import keeps every pre-existing call site and test source-compatible and
+# introduces no cycle, because the TokenShape module imports no sibling. This
+# follows the same re-import-and-re-export pattern used above for the relocated
+# ordinal-sort helper.
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusTokenShape.psm1') -Force
+
 # Plan-structure patterns. The regex text mirrors the Python constants so radius
 # derivation and the plan validator can never disagree about which lines are
 # phase headings and which are tasks.
@@ -71,12 +81,6 @@ $script:KnownTopLevelSegment = @(
 # acceptance its unanchored form has; the token itself is recorded verbatim.
 $script:LineSuffixPattern = [regex]::new(':\d+$')
 
-# Documentation-corpus root and the index, counted after that prefix, of the
-# segment that names one feature folder. A glob whose wildcard reaches this
-# segment or any earlier one claims every feature folder in the corpus.
-$script:FeatureCorpusPrefix = 'docs/features/'
-$script:FeatureFolderSegmentIndex = 1
-
 # Fallback acceptance rule: a token shaped <segment>/.../<name>.<ext> counts as a
 # repository path when its final component carries one of these extensions.
 $script:RecognizedPathExtension = [System.Collections.Generic.HashSet[string]]::new(
@@ -233,60 +237,6 @@ function Get-InlineCodeToken {
     return @($token.ToArray())
 }
 
-function Test-MultipleFeatureFolderSpan {
-    <#
-    .SYNOPSIS
-        Report whether a glob claims more than one documentation feature folder.
-
-    .DESCRIPTION
-        Port of spans_multiple_feature_folders. The documentation corpus is laid
-        out as docs/features/<bucket>/<feature-folder>/..., so a glob whose
-        wildcard occupies or truncates the feature-folder segment claims every
-        feature folder in the corpus. That made two unrelated work items contend
-        purely because both wrote documentation (issue #489). A glob carrying a
-        complete, wildcard-free feature-folder segment claims one folder and is
-        retained.
-
-    .PARAMETER Token
-        A wildcard-bearing token already accepted by the shape rules of
-        Get-PathTokenKind.
-
-    .OUTPUTS
-        System.Boolean. True when the token is rooted in the documentation corpus
-        and its wildcard reaches the feature-folder segment or any earlier one.
-    #>
-    [CmdletBinding()]
-    [OutputType([bool])]
-    param(
-        [Parameter(Mandatory = $true)]
-        [AllowEmptyString()]
-        [string] $Token
-    )
-
-    if (-not $Token.StartsWith($script:FeatureCorpusPrefix,
-            [System.StringComparison]::Ordinal)) {
-        return $false
-    }
-
-    $segment = @($Token.Substring($script:FeatureCorpusPrefix.Length) -split '/')
-
-    # A token that stops at or before the feature-folder segment has had that
-    # segment truncated away by the wildcard, so it spans the whole corpus.
-    if ($segment.Count -le $script:FeatureFolderSegmentIndex) {
-        return $true
-    }
-
-    # Every segment up to and including the feature-folder name must be a literal
-    # for the claim to resolve to exactly one folder.
-    for ($index = 0; $index -le $script:FeatureFolderSegmentIndex; $index++) {
-        if ($segment[$index].IndexOf('*') -ge 0) {
-            return $true
-        }
-    }
-
-    return $false
-}
-
 function Get-PathTokenKind {
     <#
     .SYNOPSIS
@@ -300,6 +250,13 @@ function Get-PathTokenKind {
         drive. Acceptance then requires one of the two documented shape rules, a
         known top-level segment or a recognized final extension.
 
+        A token carrying any configured placeholder or interpolation marker is
+        rejected wherever the marker sits, because it documents a shape rather
+        than naming a file (issue #502). The rejection is silent and returns the
+        same null value the sibling rejections return: there is no diagnostic
+        channel and no finding rule, because a shape citation is not an error on
+        the author's part and reporting one would fire on almost every plan.
+
     .PARAMETER Token
         A single whitespace-free inline-code token.
 
@@ -337,6 +294,22 @@ function Get-PathTokenKind {
         }
     }
 
+    # A token carrying a placeholder or interpolation marker documents a shape
+    # rather than naming a file, so it is not a write claim (issue #502).
+    #
+    # Ordering, both directions. This runs AFTER the root-surface loop because
+    # that loop is exact ordinal equality against a configured surface name: a
+    # configured surface cannot contain a marker, so the two tests can never
+    # disagree, and putting the cheaper marker scan first would only add work to
+    # the common accepted case. It runs BEFORE the separator guard because a
+    # marker-bearing token frequently does carry a separator and would otherwise
+    # sail past that guard and reach the extension rule, which accepts it: the
+    # dominant corpus shape is an angle-bracketed leading segment followed by a
+    # real .md tail, and that is exactly the token this guard exists to reject.
+    if (Test-PlaceholderMarker -Token $Token) {
+        return $null
+    }
+
     $separatorIndex = $Token.IndexOf('/')
     if ($separatorIndex -lt 0 -or $separatorIndex -eq 0) {
         return $null
@@ -492,6 +465,7 @@ Export-ModuleMember -Function `
     ConvertTo-NormalizedLine, `
     Get-PlanLineScan, `
     Get-InlineCodeToken, `
+    Test-PlaceholderMarker, `
     Test-MultipleFeatureFolderSpan, `
     Get-PathTokenKind, `
     Get-PathFromLine, `

package/resources/claude-customizations/.claude/lib/blast-radius/BlastRadiusTokenShape.psm1

@@ -0,0 +1,187 @@
+<#
+.SYNOPSIS
+    Blast-radius token-shape predicates, ported from the Python reference.
+
+.DESCRIPTION
+    Destination-runtime PowerShell port of
+    scripts/dev_tools/_blast_radius_token_shapes.py. Holds the pure,
+    context-free shape tests that reject an inline-code token before
+    Get-PathTokenKind can record it as a repository path. A token can look like
+    a path and still name no file: a placeholder or interpolation marker makes it
+    a command or artifact shape, and a corpus-wide documentation glob makes it a
+    cross-corpus claim. Neither is evidence that a work item will write anything.
+
+    Test-PlaceholderMarker is new in issue #502.
+    Test-MultipleFeatureFolderSpan was relocated here from
+    BlastRadiusExtraction.psm1 in the same change, and the two module-scoped
+    documentation-corpus variables it reads travelled with it because $script:
+    scope is per module. The relocation exists because the extraction module had
+    two lines of headroom against the 500-line limit when the marker guard was
+    added, so an in-place guard was arithmetically impossible.
+
+    The Python module remains the authoritative reference implementation. This
+    module is a LEAF: it imports no sibling blast-radius module, so the
+    extraction module can import it with no possibility of a cycle. That
+    constraint is why the predicate does not live in BlastRadiusNormalization.psm1,
+    which already imports the extraction module.
+
+    Every function is pure: no filesystem, subprocess, network, or wall-clock
+    access, and no input is mutated.
+
+    Parity notes for maintainers:
+      - The marker array is character-identical to PLACEHOLDER_MARKERS in
+        scripts/dev_tools/_blast_radius_token_shapes.py and to the tuple of the
+        same name in scripts/dev_tools/plan_gate_coverage.py, whose origin is
+        the checkable-literal placeholder guard recorded in
+        .claude/rules/plan-acceptance-gates.md. The marker set is a module
+        constant, not a truth-table key: it describes what a path can never
+        contain rather than a policy a repository could tune.
+      - Every marker literal is single-quoted, and the two dollar forms are
+        built by character concatenation. A double-quoted PowerShell string
+        expands the subexpression form and the delimited-variable form, so a
+        double-quoted marker literal would silently define a DIFFERENT
+        vocabulary than the Python reference and the parity would fail on
+        exactly the two members that matter most.
+      - Substring search uses [System.StringComparison]::Ordinal so the result
+        is culture-independent and matches Python's byte-wise 'in' operator.
+      - Both predicates are total on every string, including the empty string, a
+        token consisting only of a marker, and a bare bracket pair. Neither
+        throws for any input, because the classifier that calls them runs over
+        every inline-code span in a document and a throw would abort an entire
+        derivation over one stray span.
+#>
+
+Set-StrictMode -Version Latest
+
+# Placeholder and interpolation markers. A token carrying any of these was
+# written to document a shape, not to name a file, so it can never be a write
+# claim.
+#
+# The angle brackets are the dominant corpus shape and are also the strongest
+# case: Windows forbids both characters in a filename outright, so an
+# angle-bracketed token cannot name a file on the platform this repository is
+# developed on. The two dollar forms are shell and PowerShell interpolation, and
+# the percent form is the Windows shell's environment-variable syntax; each
+# resolves at run time to text that is not in the token.
+#
+# The two dollar forms are assembled from single characters deliberately. Written
+# as one single-quoted literal they would be correct, but assembling them makes
+# the intent explicit at the definition site and removes any question of what a
+# future edit to the quoting style would do.
+$script:PlaceholderMarker = [string[]]@(
+    '<',
+    '>',
+    '$' + '{',
+    '$' + '(',
+    '%'
+)
+
+# Documentation-corpus root and the index, counted after that prefix, of the
+# segment that names one feature folder. A glob whose wildcard reaches this
+# segment or any earlier one claims every feature folder in the corpus.
+$script:FeatureCorpusPrefix = 'docs/features/'
+$script:FeatureFolderSegmentIndex = 1
+
+function Test-PlaceholderMarker {
+    <#
+    .SYNOPSIS
+        Report whether a token carries a placeholder or interpolation marker.
+
+    .DESCRIPTION
+        Port of contains_placeholder_marker. A marker-bearing token documents a
+        shape rather than naming a file. Two work items that cite the same
+        mandated artifact shape therefore acquired a path-level conflict edge on
+        a string that resolves to nothing, which made thematically unrelated
+        items contend and serialized runs that had no reason to serialize
+        (issue #502).
+
+        The test is a plain substring scan over a fixed vocabulary, deliberately
+        context-free: it needs no repository lookup, no configuration, and no
+        knowledge of which segment the marker sits in. A marker anywhere in the
+        token is disqualifying, including in the filename position, because an
+        interpolated filename is as unresolvable as an interpolated directory.
+
+    .PARAMETER Token
+        A single whitespace-free inline-code token. The empty string is accepted
+        and reports false.
+
+    .OUTPUTS
+        System.Boolean. True when any configured marker appears anywhere in the
+        token, otherwise false.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string] $Token
+    )
+
+    # Ordinal comparison keeps the result culture-independent and byte-wise, so
+    # it agrees with Python's 'in' operator on every input.
+    foreach ($marker in $script:PlaceholderMarker) {
+        if ($Token.IndexOf($marker, [System.StringComparison]::Ordinal) -ge 0) {
+            return $true
+        }
+    }
+
+    return $false
+}
+
+function Test-MultipleFeatureFolderSpan {
+    <#
+    .SYNOPSIS
+        Report whether a glob claims more than one documentation feature folder.
+
+    .DESCRIPTION
+        Port of spans_multiple_feature_folders. The documentation corpus is laid
+        out as docs/features/<bucket>/<feature-folder>/..., so a glob whose
+        wildcard occupies or truncates the feature-folder segment claims every
+        feature folder in the corpus. That made two unrelated work items contend
+        purely because both wrote documentation (issue #489). A glob carrying a
+        complete, wildcard-free feature-folder segment claims one folder and is
+        retained.
+
+    .PARAMETER Token
+        A wildcard-bearing token already accepted by the shape rules of
+        Get-PathTokenKind.
+
+    .OUTPUTS
+        System.Boolean. True when the token is rooted in the documentation corpus
+        and its wildcard reaches the feature-folder segment or any earlier one.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string] $Token
+    )
+
+    if (-not $Token.StartsWith($script:FeatureCorpusPrefix,
+            [System.StringComparison]::Ordinal)) {
+        return $false
+    }
+
+    $segment = @($Token.Substring($script:FeatureCorpusPrefix.Length) -split '/')
+
+    # A token that stops at or before the feature-folder segment has had that
+    # segment truncated away by the wildcard, so it spans the whole corpus.
+    if ($segment.Count -le $script:FeatureFolderSegmentIndex) {
+        return $true
+    }
+
+    # Every segment up to and including the feature-folder name must be a literal
+    # for the claim to resolve to exactly one folder.
+    for ($index = 0; $index -le $script:FeatureFolderSegmentIndex; $index++) {
+        if ($segment[$index].IndexOf('*') -ge 0) {
+            return $true
+        }
+    }
+
+    return $false
+}
+
+Export-ModuleMember -Function `
+    Test-PlaceholderMarker, `
+    Test-MultipleFeatureFolderSpan