@danmoisan/drm-copilot-mcp 1.1.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danmoisan/drm-copilot-mcp",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Stdio MCP server exposing drm-copilot repo-automation tools.",
   "license": "MIT",
   "type": "commonjs",

package/resources/claude-customizations/.claude/hooks/enforce-orchestration-preimplementation-gate-helpers.ps1

@@ -0,0 +1,349 @@
+<#
+.SYNOPSIS
+    Pathspec classifier for the orchestration-bookkeeping staging exemption (issue #539).
+.DESCRIPTION
+    Pure string logic only: no disk, process, network, or environment access. The single
+    entry predicate `Test-ExemptOrchestrationStagingCommand` answers one question - does
+    this command text parse, in its entirety, as recognized staging or integration
+    invocations whose every pathspec operand resolves inside an orchestration-bookkeeping
+    tree? Every parse ambiguity answers false, so the caller's pre-change deny is the
+    fallback for every unmodeled form.
+
+    The normative contract is the D4 fail-closed rule table in
+    docs/features/active/2026-08-24-preimplementation-gate-blocks-planner-integration-commits-539/spec.md.
+    Rule-table row numbers are cited inline against the code that realizes them.
+
+    This file is dot-sourced by the sibling gate hook, following the headroom-split
+    precedent set by enforce-pr-author-skill.ps1.
+#>
+
+# The five exempt orchestration-bookkeeping trees (D2). Directory prefixes, repo-relative,
+# forward-slash spelled. No glob, no absolute entry, no literal-file entry.
+$script:OrchestrationBookkeepingTrees = @(
+    'docs/features/epics/'
+    'docs/features/parallel/'
+    'docs/features/active/'
+    'docs/features/potential/'
+    'artifacts/orchestration/'
+)
+
+# Characters that make a command line statically unresolvable: shell interpolation and
+# redirection (D4 row 12). Tested across the whole line rather than per operand, because a
+# redirection anywhere in the line moves content the operand list cannot describe.
+$script:UnresolvableCommandCharacters = [char[]]@('$', '`', '>', '<')
+
+# Wildcards that make an operand a glob (D4 row 15). Only the literal prefix before the
+# first of these is prefix-tested.
+$script:PathspecWildcardCharacters = [char[]]@('*', '?', '[')
+
+function Split-OrchestrationCommandLine {
+    <#
+    .SYNOPSIS
+        Splits a command line into segments on chain operators outside quotes.
+    .DESCRIPTION
+        Realizes D4 row 13. Quote state is tracked while scanning so a chain operator
+        inside a quoted span does not split. The returned `Balanced` flag reports whether
+        the scan ended outside every quote; unbalanced text is not splittable and the
+        caller denies (D4 rows 11 and 13). Empty and whitespace-only segments are dropped.
+    .OUTPUTS
+        System.Collections.Hashtable with keys `Balanced` (bool) and `Segments` (string[]).
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param([Parameter(Mandatory)][AllowEmptyString()][string] $CommandText)
+
+    $segments = [System.Collections.Generic.List[string]]::new()
+    $current = [System.Text.StringBuilder]::new()
+    $openQuote = [char]0
+
+    foreach ($character in $CommandText.ToCharArray()) {
+        if ($openQuote -ne [char]0) {
+            if ($character -eq $openQuote) {
+                $openQuote = [char]0
+            }
+            [void]$current.Append($character)
+            continue
+        }
+
+        if ($character -eq '"' -or $character -eq "'") {
+            $openQuote = $character
+            [void]$current.Append($character)
+            continue
+        }
+
+        if ($character -eq ';' -or $character -eq '&' -or $character -eq '|' -or
+            $character -eq "`n" -or $character -eq "`r") {
+            $segments.Add($current.ToString())
+            [void]$current.Clear()
+            continue
+        }
+
+        [void]$current.Append($character)
+    }
+    $segments.Add($current.ToString())
+
+    return @{
+        Balanced = ($openQuote -eq [char]0)
+        Segments = @($segments | Where-Object { $_.Trim() })
+    }
+}
+
+function ConvertTo-OrchestrationCommandToken {
+    <#
+    .SYNOPSIS
+        Splits one segment into whitespace-delimited tokens with balanced quotes stripped.
+    .DESCRIPTION
+        Realizes the quote handling of D4 row 11. A quoted span contributes to the token it
+        sits in, so `-m "epic scaffold"` yields the two tokens `-m` and `epic scaffold`, and
+        a quoted operand arrives at the prefix test unquoted. The caller has already
+        rejected unbalanced text, so an unterminated quote simply ends the final token.
+    .OUTPUTS
+        System.String[]
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param([Parameter(Mandatory)][AllowEmptyString()][string] $Segment)
+
+    $tokens = [System.Collections.Generic.List[string]]::new()
+    $current = [System.Text.StringBuilder]::new()
+    $hasToken = $false
+    $openQuote = [char]0
+
+    foreach ($character in $Segment.ToCharArray()) {
+        if ($openQuote -ne [char]0) {
+            if ($character -eq $openQuote) {
+                $openQuote = [char]0
+            } else {
+                [void]$current.Append($character)
+            }
+            continue
+        }
+
+        if ($character -eq '"' -or $character -eq "'") {
+            $openQuote = $character
+            $hasToken = $true
+            continue
+        }
+
+        if ([char]::IsWhiteSpace($character)) {
+            if ($hasToken) {
+                $tokens.Add($current.ToString())
+                [void]$current.Clear()
+                $hasToken = $false
+            }
+            continue
+        }
+
+        $hasToken = $true
+        [void]$current.Append($character)
+    }
+
+    if ($hasToken) {
+        $tokens.Add($current.ToString())
+    }
+
+    return $tokens.ToArray()
+}
+
+function Test-ExemptOrchestrationOperand {
+    <#
+    .SYNOPSIS
+        Tests one pathspec operand against the five exempt orchestration trees.
+    .DESCRIPTION
+        Realizes D4 rows 3, 9, 15, 16, 17, and 18. Backslashes normalize to forward slashes
+        before the prefix test (row 18); pathspec magic, absolute spellings, parent-directory
+        segments, and globs whose literal prefix escapes the exempt set all deny.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][AllowEmptyString()][string] $Operand)
+
+    if (-not $Operand) {
+        return $false
+    }
+
+    # Row 3b and row 9: any leading colon is pathspec magic, which can escape or invert the
+    # tree scope, so no colon-led operand is ever resolvable by a prefix test.
+    if ($Operand.StartsWith(':')) {
+        return $false
+    }
+
+    # Row 18: separator normalization precedes every prefix comparison below.
+    $normalized = $Operand -replace '\\', '/'
+
+    # Row 16: rooted, drive-lettered, and UNC spellings all deny; the exempt prefixes stay
+    # repo-relative (this is the posture issue #516 later composes with).
+    if ($normalized.StartsWith('/')) {
+        return $false
+    }
+    if ($normalized -match '^[A-Za-z]:') {
+        return $false
+    }
+
+    # Rows 15c and 17: any parent-directory component escapes the prefix.
+    if (($normalized -split '/') -contains '..') {
+        return $false
+    }
+
+    # Row 15: only the literal prefix before the first wildcard is prefix-tested, so a glob
+    # whose wildcard occupies or truncates an ancestor segment cannot pass.
+    $literalPrefix = $normalized
+    $wildcardIndex = $normalized.IndexOfAny($script:PathspecWildcardCharacters)
+    if ($wildcardIndex -ge 0) {
+        $literalPrefix = $normalized.Substring(0, $wildcardIndex)
+    }
+
+    foreach ($tree in $script:OrchestrationBookkeepingTrees) {
+        if ($literalPrefix.StartsWith($tree)) {
+            return $true
+        }
+    }
+    return $false
+}
+
+function Test-ExemptOrchestrationSegmentToken {
+    <#
+    .SYNOPSIS
+        Tests one already-tokenized segment as a recognized all-exempt invocation.
+    .DESCRIPTION
+        Realizes D4 rows 1, 2, 4, 5, 6, 7, 8, 10, 14, and 19. The command name must lead the
+        segment and the subcommand must follow it immediately (row 14), the option table is
+        modelled positively so any unmodelled dash-leading token denies (rows 2, 5, 6, 8, 10),
+        tokens after the double-dash separator are pathspecs (row 7), at least one operand is
+        required (rows 1, 4, 7), and every operand must pass (row 19).
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][AllowEmptyCollection()][string[]] $Token)
+
+    if ($Token.Count -lt 2) {
+        return $false
+    }
+
+    # Row 14: the command name leads and the subcommand follows immediately. Anything in
+    # between - a relocating option or an env-style prefix - moves the pathspec base and is
+    # rejected here rather than modelled.
+    if ($Token[0] -cne 'git') {
+        return $false
+    }
+    $subcommand = $Token[1]
+    if ($subcommand -cne 'add' -and $subcommand -cne 'commit') {
+        return $false
+    }
+
+    $operands = [System.Collections.Generic.List[string]]::new()
+    $afterSeparator = $false
+    $index = 2
+
+    while ($index -lt $Token.Count) {
+        $candidate = $Token[$index]
+
+        if (-not $afterSeparator) {
+            if ($candidate -ceq '--') {
+                # Row 7: every remaining token is a pathspec, dash-leading or not.
+                $afterSeparator = $true
+                $index++
+                continue
+            }
+
+            if ($candidate.StartsWith('-')) {
+                # The message option is the only modelled option on either subcommand. Rows
+                # 2, 5, 6, 8, and 10 all land here and deny, including a dash-leading
+                # operand supplied without a preceding separator.
+                if ($subcommand -cne 'commit') {
+                    return $false
+                }
+                if ($candidate -ceq '-m' -or $candidate -ceq '--message') {
+                    # The message value is the following token and is not a pathspec.
+                    $index += 2
+                    if ($index -gt $Token.Count) {
+                        return $false
+                    }
+                    continue
+                }
+                if ($candidate.StartsWith('--message=') -or
+                    ($candidate.Length -gt 2 -and $candidate.StartsWith('-m'))) {
+                    $index++
+                    continue
+                }
+                return $false
+            }
+        }
+
+        $operands.Add($candidate)
+        $index++
+    }
+
+    # Rows 1, 4, and 7: an invocation with no pathspec operand claims no path, so there is
+    # nothing for the prefix test to scope and the exemption is not available.
+    if ($operands.Count -eq 0) {
+        return $false
+    }
+
+    # Row 19: all-operands-exempt is the invariant; one non-exempt operand denies the set.
+    foreach ($operand in $operands) {
+        if (-not (Test-ExemptOrchestrationOperand -Operand $operand)) {
+            return $false
+        }
+    }
+    return $true
+}
+
+function Test-ExemptOrchestrationStagingCommand {
+    <#
+    .SYNOPSIS
+        Reports whether a command line is an orchestration-bookkeeping staging invocation.
+    .DESCRIPTION
+        The entry predicate of the issue #539 exemption. Returns true only when the whole
+        command line splits cleanly into segments and EVERY segment parses as a complete,
+        recognized staging or integration invocation carrying at least one pathspec operand,
+        with every operand resolving inside one of the five exempt orchestration-bookkeeping
+        trees after balanced-quote stripping and separator normalization.
+
+        The all-segments reading is deliberate and fail-closed: a chained line denies unless
+        each of its segments is independently a recognized all-exempt invocation, so a
+        relocating spelling or a prose fragment anywhere in the line withholds the exemption
+        even when another segment on the same line would have qualified on its own.
+
+        Consumed allow-side only. A false result restores the caller's unchanged
+        classification; it never suppresses the trigger.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][AllowEmptyString()][string] $CommandText)
+
+    if (-not $CommandText) {
+        return $false
+    }
+
+    # Row 12: interpolation and redirection are not statically resolvable, so the operand
+    # list cannot be trusted to describe what the line actually touches.
+    if ($CommandText.IndexOfAny($script:UnresolvableCommandCharacters) -ge 0) {
+        return $false
+    }
+
+    $split = Split-OrchestrationCommandLine -CommandText $CommandText
+    if (-not $split.Balanced) {
+        # Rows 11 and 13: unbalanced quoting makes the segment boundaries ambiguous.
+        return $false
+    }
+
+    $segments = @($split.Segments)
+    if ($segments.Count -eq 0) {
+        return $false
+    }
+
+    foreach ($segment in $segments) {
+        $tokens = @(ConvertTo-OrchestrationCommandToken -Segment $segment)
+        if (-not (Test-ExemptOrchestrationSegmentToken -Token $tokens)) {
+            return $false
+        }
+    }
+    return $true
+}

package/resources/claude-customizations/.claude/hooks/enforce-orchestration-preimplementation-gate.ps1

@@ -7,8 +7,38 @@ param()
 
 
 Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+
+# Pure pathspec classifier for the issue #539 orchestration-bookkeeping staging exemption.
+# Extracted to a dot-sourced sibling so this file stays inside the 500-line cap, following
+# the enforce-pr-author-skill.ps1 headroom-split precedent.
+. (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-helpers.ps1')
+
+# The readiness checkpoint this gate reads and names in its block message.
 $script:CheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
 
+# Every orchestration checkpoint a planner or orchestrator surface writes. Writing one
+# of these is orchestration bookkeeping, not implementation, so the gate must not
+# require a ready checkpoint before the checkpoint itself can be created. The set is a
+# list of repo-relative literals behind a single membership check: no directory prefix,
+# no glob, and no absolute-path entry.
+$script:CheckpointPaths = @(
+    'artifacts/orchestration/orchestrator-state.json'
+    'artifacts/orchestration/parallel-planner-state.json'
+    'artifacts/orchestration/parallel-orchestrator-state.json'
+    'artifacts/orchestration/epic-planner-state.json'
+    'artifacts/orchestration/epic-orchestrator-state.json'
+    'artifacts/orchestration/powershell-orchestrator-state.json'
+    'artifacts/orchestration/csharp-orchestrator-state.json'
+)
+
+# Both markers must appear in the field-scoped prompt for a delegation to qualify as a
+# preparation-mode kickoff. The literals are reused verbatim from
+# .claude/skills/parallel-plan/SKILL.md and .claude/skills/epic-plan/SKILL.md.
+$script:PreparationModeMarkers = @(
+    'Preparation mode: true.'
+    'route_id: preparation.'
+)
+
 function ConvertFrom-CheckpointJson {
     [CmdletBinding()]
     param([Parameter(Mandatory)][string] $Json)
@@ -35,7 +65,13 @@ function Test-FeatureDocumentationOrEvidencePath {
     [OutputType([bool])]
     param([Parameter(Mandatory)][string] $NormalizedPath)
 
-    return $NormalizedPath.StartsWith('docs/features/active/')
+    # The segment anchor (^|/) admits both the repo-relative spelling and an
+    # absolute spelling of the same feature document, which the Write tool
+    # supplies by contract. -cmatch is deliberate and must not be normalized into
+    # -match: String.StartsWith is case-sensitive, so the case-sensitive operator
+    # is what preserves the previous semantics exactly. PowerShell -match is
+    # case-insensitive and would widen this predicate.
+    return $NormalizedPath -cmatch '(^|/)docs/features/active/'
 }
 
 function Test-ImplementationPath {
@@ -46,8 +82,29 @@ function Test-ImplementationPath {
     if (Test-FeatureDocumentationOrEvidencePath -NormalizedPath $NormalizedPath) {
         return $false
     }
-    if ($NormalizedPath -eq $script:CheckpointPath) {
-        return $false
+    # Segment-anchored and end-anchored, so an absolute spelling of a checkpoint is
+    # exempt exactly as its repo-relative spelling already was. -match is
+    # deliberate here and must not be narrowed into -cmatch: -contains was
+    # case-insensitive, so the case-insensitive operator is what preserves the
+    # previous semantics exactly.
+    #
+    # Accepted widening: this also exempts a path OUTSIDE the workspace whose tail
+    # is an artifacts/orchestration/ segment followed by one of the seven names.
+    # Measured exposure in this repository is one matching file, the real
+    # checkpoint; there is no nested or vendored second copy. The same widening is
+    # already accepted for the identical literal in four other hooks. Resolving a
+    # workspace root instead would reintroduce every root-resolution failure mode
+    # (8.3 short names, drive-letter case, symlinks, linked worktrees), and a strip
+    # that failed to match would leave the path absolute and deny, reinstating the
+    # reported defect in a subtler form.
+    #
+    # Known deliberate miss: a path reaching a checkpoint name only through a '..'
+    # hop stays denied. The Write tool does not emit '..' segments, and a
+    # canonicalizer would reintroduce filesystem dependence for no measured gain.
+    foreach ($checkpoint in $script:CheckpointPaths) {
+        if ($NormalizedPath -match ('(^|/)' + [regex]::Escape($checkpoint) + '$')) {
+            return $false
+        }
     }
     return $NormalizedPath -match '\.(py|ps1|psm1|ts|tsx|js|jsx|cs|json|yml|yaml)$'
 }
@@ -70,14 +127,58 @@ function Test-ImplementationCommand {
         '(^|\s)pwsh\s+.*(Invoke-Pester|tests/scripts/)'
     )
 
-    foreach ($pattern in $implementationCommandPatterns) {
-        if ($normalizedCommand -match $pattern) {
-            return $true
+    for ($index = 0; $index -lt $implementationCommandPatterns.Count; $index++) {
+        if ($normalizedCommand -notmatch $implementationCommandPatterns[$index]) {
+            continue
+        }
+        # Allow-side only (issue #539). Index 0 is the git staging trigger, whose pattern
+        # text is unchanged. It is the sole leg the orchestration-bookkeeping exemption may
+        # clear, and only when no other implementation pattern matches the same line: the
+        # loop continues rather than returning, so a chained line carrying any non-git
+        # implementation segment still classifies as implementation.
+        if ($index -eq 0 -and (Test-ExemptOrchestrationStagingCommand -CommandText $normalizedCommand)) {
+            continue
         }
+        return $true
     }
     return $false
 }
 
+function Test-PreparationModeDelegation {
+    <#
+    .SYNOPSIS
+        Identifies an orchestrator delegation that is a preparation-mode kickoff.
+    .DESCRIPTION
+        Returns true only when all three conjuncts hold: the payload is present, the
+        delegated agent is exactly 'orchestrator', and the field-scoped prompt carries
+        both preparation markers. The prompt is read as a named field rather than from
+        the serialized payload so that marker text planted in an unrelated field cannot
+        exempt an implementation delegation.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][AllowNull()] $ToolInput)
+
+    if ($null -eq $ToolInput) {
+        return $false
+    }
+
+    $subagentType = Get-ClaudeHookToolInputString -ToolInput $ToolInput -Name 'subagent_type'
+    if ($subagentType -ne 'orchestrator') {
+        return $false
+    }
+
+    $prompt = Get-ClaudeHookToolInputString -ToolInput $ToolInput -Name 'prompt'
+    foreach ($marker in $script:PreparationModeMarkers) {
+        if (-not $prompt.Contains($marker)) {
+            return $false
+        }
+    }
+    return $true
+}
+
 function Test-ImplementationDelegation {
     [CmdletBinding()]
     [OutputType([bool])]
@@ -87,6 +188,17 @@ function Test-ImplementationDelegation {
         return $false
     }
 
+    try {
+        if (Test-PreparationModeDelegation -ToolInput $ToolInput) {
+            return $false
+        }
+    } catch {
+        # An envelope the field reader cannot probe falls through to the unchanged
+        # whole-payload regex below. An extraction failure must never become an
+        # exemption, so the gate stays closed on the stricter classifier.
+        Write-Debug "Preparation-mode probe failed: $($_.Exception.Message)"
+    }
+
     $payloadText = ($ToolInput | ConvertTo-Json -Depth 20 -Compress)
     return $payloadText -match '(python-typed-engineer|powershell-typed-engineer|typescript-engineer|csharp-typed-engineer|atomic-executor|implementation|execute)'
 }

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, `