@danmoisan/drm-copilot-mcp 0.0.5 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danmoisan/drm-copilot-mcp",
-  "version": "0.0.5",
+  "version": "1.0.0",
   "description": "Stdio MCP server exposing drm-copilot repo-automation tools.",
   "license": "MIT",
   "type": "commonjs",
@@ -35,7 +35,7 @@
   "author": "Dan Moisan",
   "scripts": {
     "build": "node esbuild-mcp-server.cjs",
-    "prepack": "node -e \"const{cpSync}=require('fs');cpSync('../../extensions/drm-copilot/resources','./resources',{recursive:true,force:true})\""
+    "prepack": "node prepack.cjs"
   },
   "overrides": {
     "fast-uri": "^3.1.2",

package/resources/claude-customizations/.claude/agents/orchestrator.md

@@ -2,7 +2,7 @@
 name: orchestrator
 description: Deterministic repository orchestrator that estimates change budget, selects small or large workflow path, delegates to specialist subagents, persists checkpoint state, and enforces completion gates proactively.
 tools:
-  - "Agent(atomic-planner,atomic-executor,feature-review,task-researcher,prd-feature,staged-review,epic-review,status-updater,python-typed-engineer,powershell-typed-engineer,csharp-typed-engineer,typescript-engineer)"
+  - "Agent(atomic-planner,atomic-executor,feature-review,task-researcher,prd-feature,staged-review,epic-review,status-updater,pr-author,python-typed-engineer,powershell-typed-engineer,csharp-typed-engineer,typescript-engineer)"
   - Read
   - Grep
   - Glob
@@ -69,10 +69,14 @@ Delegate exclusively through configured subagents:
 - `atomic-planner` — generates phased implementation plans (planning only)
 - `atomic-executor` — executes approved plans task-by-task (execution only)
 - `feature-review` — produces policy, code, and feature audit artifacts
-- `task-researcher` — performs deep research and writes findings to `artifacts/research/`
+- `task-researcher` — performs deep research and writes findings to the research path the orchestrator resolves before delegating: `docs/features/<feature>/research/` when an active `feature-folder` is in scope in `orchestrator-state.json`, otherwise `docs/research/` for one-off research. The orchestrator passes the resolved path in the delegation prompt.
 
 For required delegated steps, delegation is mandatory. If a handoff cannot be started, resumed, or completed, stop execution and record blocked state. Do not perform the step locally.
 
+## PR Creation Delegation
+
+PR creation and PR body edits must be delegated to `Agent(pr-author)`. The orchestrator must not call `gh pr create` or `gh pr edit --body*` directly from the main thread; those commands are blocked by the `enforce-pr-author-skill.ps1` PreToolUse hook unless a valid authorization sentinel issued by the `pr-author` agent is present. The orchestrator first produces the PR-context artifact via `mcp__drm-copilot__collect_pr_context`, then delegates to `Agent(pr-author)`, which authors the PR body via the `pr-author` skill, writes and deletes the authorization sentinel around the `gh` command, and reports the resulting PR URL or PR number.
+
 ## Checkpoint Persistence
 
 Update `artifacts/orchestration/orchestrator-state.json` after every completed step with:

package/resources/claude-customizations/.claude/agents/pr-author.md

@@ -0,0 +1,78 @@
+---
+name: pr-author
+description: Project-scoped agent that runs the pr-author skill to produce a GitHub-ready PR body from the canonical PR-context bundle, then opens or updates the pull request. Sole authorized caller of gh pr create and gh pr edit --body*. Writes a short-lived authorization sentinel immediately before each gh command and deletes it afterward.
+model: sonnet
+skills:
+  - pr-author
+memory: project
+tools:
+  - Read
+  - "Bash(git log *)"
+  - "Bash(git rev-parse *)"
+  - "Bash(gh pr create *)"
+  - "Bash(gh pr edit *)"
+  - "Write(/artifacts/**)"
+hooks:
+  SubagentStop:
+    - matcher: "pr-author"
+      hooks:
+        - type: command
+          command: pwsh -NoProfile -File .claude/hooks/validate-pr-author-output.ps1
+---
+
+# PR Author Agent
+
+You are the dedicated pull-request authoring agent. Your sole responsibility is to consume the
+canonical PR-context bundle, produce the PR body using the `pr-author` skill, and open or update the
+pull request. You are the only agent authorized to run `gh pr create` and `gh pr edit --body*`. The
+orchestrator and all other agents are blocked from these commands by the
+`enforce-pr-author-skill.ps1` PreToolUse hook.
+
+## Skill
+
+Apply the `pr-author` skill (`.claude/skills/pr-author/SKILL.md`) as the canonical workflow for
+authoring the PR body. The skill produces the PR body text from the PR-context bundle
+(`artifacts/pr_context.summary.txt` and `artifacts/pr_context.appendix.txt`) and its enumerated
+additional context files. The skill itself only authors body text; opening and editing the pull
+request via `gh pr create` / `gh pr edit` is this agent's responsibility, not the skill's.
+
+## Authorization Sentinel Write/Delete Protocol
+
+Before any `gh pr create` or `gh pr edit --body*` command, you MUST perform these steps in order:
+
+1. Run `git rev-parse HEAD` to obtain the current `head_sha`.
+2. Write `artifacts/pr_author_authorization.json` with exactly these fields:
+   - `issued_by`: `"pr-author"`
+   - `issued_at`: the current time as a UTC ISO-8601 timestamp (for example `2026-06-24T16:00:00Z`)
+   - `head_sha`: the value from step 1
+   - `ttl_seconds`: `120`
+3. Issue the `gh pr create` or `gh pr edit --body-file ...` command immediately, within the 120-second
+   TTL. The PreToolUse hook verifies that the sentinel is present, that `issued_by` is exactly
+   `pr-author`, and that the sentinel has not expired before allowing the command.
+4. Delete `artifacts/pr_author_authorization.json` after the `gh` command completes, on both success
+   and failure. The TTL also expires abandoned sentinels, but explicit deletion is required.
+
+The sentinel filename is exactly `artifacts/pr_author_authorization.json`. The PR body must be passed
+via `--body-file`; inline `--body` is blocked by the hook (Case A).
+
+## Final Output Requirement
+
+After opening or updating the pull request, report the resulting PR URL
+(`https://github.com/<owner>/<repo>/pull/<n>`) or the PR number (`PR #<n>`) in your final output. The
+`validate-pr-author-output.ps1` SubagentStop hook blocks completion when the final output contains no
+PR URL or PR number.
+
+## Enforcement Strength (Honest Disclosure)
+
+The authorization sentinel is a **policy guardrail, not a cryptographic or security control.** Any
+actor with `Write(/artifacts/**)` access can forge `artifacts/pr_author_authorization.json`, because
+all agents share the same filesystem and the runtime exposes no native agent-identity signal at Bash
+PreToolUse time. The mechanism prevents accidental bypass (such as the PR #228 pattern where the
+orchestrator wrote the body file and called `gh pr create` directly) and requires a deliberate,
+documented act to circumvent. It is not tamper-proof and is not a security boundary.
+
+## Standing Rules
+
+Repository tone is defined in `CLAUDE.md` and `.claude/rules/tonality.md`. Reference only files
+listed under "Additional context files" in the PR-context bundle; do not cite or summarize files
+outside that enumeration. Do not invent issue or PR numbers.

package/resources/claude-customizations/.claude/agents/task-researcher.md

@@ -1,13 +1,14 @@
 ---
 name: task-researcher
-description: Research specialist that performs deep investigation and writes structured findings exclusively to artifacts/research/.
+description: Research specialist that performs deep investigation and writes structured findings to the orchestrator-supplied research path under docs/features/<feature>/research/ (feature-associated) or docs/research/ (one-off).
 model: sonnet
 tools:
   - Read
   - Grep
   - Glob
   - WebFetch
-  - "Write(/artifacts/research/**)"
+  - "Write(/docs/features/**/research/**)"
+  - "Write(/docs/research/**)"
   - evidence-and-timestamp-conventions
 memory: project
 hooks:
@@ -20,13 +21,16 @@ hooks:
 
 # Task Researcher Agent
 
-You are a research-only specialist. You perform deep analysis for task planning and write structured research notes. You do not make changes to source code, configurations, or project files outside `artifacts/research/`.
+You are a research-only specialist. You perform deep analysis for task planning and write structured research notes. You do not make changes to source code, configurations, or project files outside the research root the orchestrator supplies.
 
 ## Output Location
 
-Write all research artifacts to `artifacts/research/` using the filename convention:
+Write each research artifact to the research path the orchestrator supplies in the delegation prompt. There are two tracked research roots:
 
-- `artifacts/research/<timestamp>-<short-name>-research.md`
+- Feature-associated research: `docs/features/<feature>/research/<timestamp>-<short-name>-research.md` (for example `docs/features/active/<feature>/research/<timestamp>-<short-name>-research.md`).
+- One-off research not tied to a feature: `docs/research/<timestamp>-<short-name>-research.md`.
+
+The orchestrator resolves which root to use from whether an active feature folder is in scope and passes the exact path in the delegation prompt; do not infer the feature folder independently. The filename convention `<timestamp>-<short-name>-research.md` is unchanged.
 
 ## Core Principles
 
@@ -67,7 +71,7 @@ Write all research artifacts to `artifacts/research/` using the filename convent
 
 ## Constraints
 
-- Write only to `artifacts/research/`. Do not modify source code or configurations.
+- Write only to the orchestrator-supplied research path under `docs/features/<feature>/research/` (feature-associated) or `docs/research/` (one-off). Do not modify source code or configurations.
 - Ground all findings in verified evidence.
 - Keep discussion of non-selected approaches brief.
 - Do not claim nested worker delegation.

package/resources/claude-customizations/.claude/hooks/enforce-checkpoint-monotonic.ps1

@@ -134,6 +134,53 @@ function Get-OutOfOrderPair {
     return $null
 }
 
+function Test-StepHasPrefix {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $StepEntry,
+
+        [Parameter(Mandatory)]
+        [string] $Prefix
+    )
+
+    return $StepEntry -eq $Prefix -or $StepEntry.StartsWith("$Prefix" + '_') -or $StepEntry.StartsWith("$Prefix.") -or $StepEntry.StartsWith("$Prefix-")
+}
+
+function Get-MissingPrerequisiteForAdvancedStep {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyCollection()]
+        [string[]] $CompletedSteps
+    )
+
+    $hasPromotion = $false
+    $hasPlanning = $false
+    foreach ($step in $CompletedSteps) {
+        if (Test-StepHasPrefix -StepEntry $step -Prefix 'S3_promotion') {
+            $hasPromotion = $true
+        }
+        if (Test-StepHasPrefix -StepEntry $step -Prefix 'S4_atomic_planning') {
+            $hasPlanning = $true
+        }
+    }
+
+    foreach ($step in $CompletedSteps) {
+        $index = Get-CanonicalStepIndex -StepEntry $step
+        if ($index -ge 5 -and (-not $hasPromotion -or -not $hasPlanning)) {
+            return [pscustomobject]@{
+                Step             = $step
+                MissingPromotion = -not $hasPromotion
+                MissingPlanning  = -not $hasPlanning
+            }
+        }
+    }
+
+    return $null
+}
+
 function Test-IsCheckpointPath {
     [CmdletBinding()]
     [OutputType([bool])]
@@ -204,10 +251,6 @@ function Invoke-CheckpointMonotonicDecision {
         }
     }
 
-    if ($steps.Count -lt 2) {
-        return [ordered]@{ decision = 'allow' }
-    }
-
     $rollbackHistory = $null
     if ($payload.PSObject.Properties.Name -contains 'rollback_history') {
         $rollbackHistory = $payload.rollback_history
@@ -216,15 +259,30 @@ function Invoke-CheckpointMonotonicDecision {
         return [ordered]@{ decision = 'allow' }
     }
 
-    $pair = Get-OutOfOrderPair -CompletedSteps $steps
-    if ($null -eq $pair) {
-        return [ordered]@{ decision = 'allow' }
+    $pair = if ($steps.Count -ge 2) { Get-OutOfOrderPair -CompletedSteps $steps } else { $null }
+    if ($null -ne $pair) {
+        return [ordered]@{
+            decision = 'block'
+            reason   = "CHECKPOINT_ORDER_BLOCKED: completed_steps lists '$($pair.EarlierEntry)' at position $($pair.EarlierPos) before '$($pair.LaterEntry)' at position $($pair.LaterPos), but the canonical orchestrator workflow requires the later step to follow the earlier one. Reorder completed_steps or, if a rollback occurred, record it in rollback_history."
+        }
     }
 
-    return [ordered]@{
-        decision = 'block'
-        reason   = "CHECKPOINT_ORDER_BLOCKED: completed_steps lists '$($pair.EarlierEntry)' at position $($pair.EarlierPos) before '$($pair.LaterEntry)' at position $($pair.LaterPos), but the canonical orchestrator workflow requires the later step to follow the earlier one. Reorder completed_steps or, if a rollback occurred, record it in rollback_history."
+    $missingPrerequisite = Get-MissingPrerequisiteForAdvancedStep -CompletedSteps $steps
+    if ($null -ne $missingPrerequisite) {
+        $missing = @()
+        if ($missingPrerequisite.MissingPromotion) {
+            $missing += 'S3_promotion'
+        }
+        if ($missingPrerequisite.MissingPlanning) {
+            $missing += 'S4_atomic_planning'
+        }
+        return [ordered]@{
+            decision = 'block'
+            reason   = "CHECKPOINT_ORDER_BLOCKED: completed_steps lists '$($missingPrerequisite.Step)' before required prerequisite step(s): $($missing -join ', '). Record promotion and planning completion before implementation, review, PR, CI, or DONE steps."
+        }
     }
+
+    return [ordered]@{ decision = 'allow' }
 }
 
 # Guard allows dot-sourcing in tests without executing the entrypoint.

package/resources/claude-customizations/.claude/hooks/enforce-completion-consistency.ps1

@@ -39,6 +39,11 @@
 [CmdletBinding()]
 param()
 
+# Dot-source the shared validation helpers. Guarded so a missing file produces a
+# clear error and so dot-sourcing this hook in tests loads the helpers too.
+$script:CompletionHelpersPath = Join-Path $PSScriptRoot 'enforce-completion-helpers.ps1'
+. $script:CompletionHelpersPath
+
 function ConvertFrom-CheckpointJson {
     <#
     .SYNOPSIS
@@ -53,6 +58,29 @@ function ConvertFrom-CheckpointJson {
     return $Json | ConvertFrom-Json -ErrorAction Stop
 }
 
+function Get-CheckpointFileContent {
+    <#
+    .SYNOPSIS
+        Reads the on-disk checkpoint content for the read-then-validate Edit path.
+    .DESCRIPTION
+        Returns the full file text when the path resolves to a file on disk, or
+        $null when the file does not exist. Tests inject a CheckpointReader
+        scriptblock instead of mocking this function so no temporary files are
+        required.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Path
+    )
+
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+        return $null
+    }
+    return Get-Content -LiteralPath $Path -Raw -ErrorAction Stop
+}
+
 function Test-IsCheckpointPath {
     [CmdletBinding()]
     [OutputType([bool])]
@@ -149,7 +177,13 @@ function Get-MissingCompletionEvidence {
     param(
         [Parameter(Mandatory)]
         [AllowNull()]
-        $Payload
+        $Payload,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $FolderExistsCheck = { param($p) Test-Path -LiteralPath $p -PathType Container },
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $RoutingMatrixReader
     )
 
     $missing = @()
@@ -158,16 +192,17 @@ function Get-MissingCompletionEvidence {
     if (-not $issueNum -and $null -ne $Payload -and ($Payload.PSObject.Properties.Name -contains 'variables')) {
         $issueNum = Get-CheckpointStringValue -Payload $Payload.variables -Name 'issue-num'
     }
-    if (-not $issueNum) {
-        $missing += 'issue-num'
+    if (-not (Test-IsValidIssueNum -Value $issueNum)) {
+        # Name the offending value so sentinel/placeholder inputs are explicit.
+        $missing += "issue-num value '$issueNum' is not a valid issue number (must be digits-only)"
     }
 
     $featureFolder = Get-CheckpointStringValue -Payload $Payload -Name 'feature-folder'
     if (-not $featureFolder -and $null -ne $Payload -and ($Payload.PSObject.Properties.Name -contains 'variables')) {
         $featureFolder = Get-CheckpointStringValue -Payload $Payload.variables -Name 'feature-folder'
     }
-    if (-not $featureFolder) {
-        $missing += 'feature-folder'
+    if (-not (Test-IsValidFeatureFolder -Value $featureFolder -FolderExistsCheck $FolderExistsCheck)) {
+        $missing += "feature-folder value '$featureFolder' is not a valid feature folder (must be under docs/features/active/ and exist)"
     }
 
     $ciGate = $null
@@ -188,9 +223,92 @@ function Get-MissingCompletionEvidence {
         }
     }
 
+    # PR-gate evidence is required only when the checkpoint's selected route
+    # opts into it via requires_pr_gate in the routing matrix. This replaces the
+    # former issue-number special-casing with route-driven enforcement.
+    $prGateArgs = @{ Payload = $Payload }
+    if ($PSBoundParameters.ContainsKey('RoutingMatrixReader') -and $null -ne $RoutingMatrixReader) {
+        $prGateArgs['RoutingMatrixReader'] = $RoutingMatrixReader
+    }
+    if (Test-RouteRequiresPrGate @prGateArgs) {
+        $prGate = $null
+        if ($null -ne $Payload -and ($Payload.PSObject.Properties.Name -contains 'pr_gate')) {
+            $prGate = $Payload.pr_gate
+        }
+        if ($null -eq $prGate -or $prGate -isnot [System.Management.Automation.PSCustomObject]) {
+            $missing += 'pr_gate (object with pr_number, pr_url, head_branch, and head_sha)'
+        }
+        else {
+            foreach ($field in @('pr_number', 'pr_url', 'head_branch', 'head_sha')) {
+                if (-not (Get-CheckpointStringValue -Payload $prGate -Name $field)) {
+                    $missing += "pr_gate.$field"
+                }
+            }
+            $prHeadSha = Get-CheckpointStringValue -Payload $prGate -Name 'head_sha'
+            $ciHeadSha = Get-CheckpointStringValue -Payload $ciGate -Name 'head_sha'
+            if ($prHeadSha -and $ciHeadSha -and $prHeadSha -ne $ciHeadSha) {
+                $missing += 'ci_gate.head_sha matching pr_gate.head_sha'
+            }
+        }
+    }
+
     return [string[]]$missing
 }
 
+function Resolve-EditedCheckpointContent {
+    <#
+    .SYNOPSIS
+        Returns the patched checkpoint content for an Edit-tool call, or $null
+        when the patch cannot be applied against the on-disk checkpoint.
+    .DESCRIPTION
+        Implements the read-then-validate Edit path. When the tool input carries
+        an old_string (an Edit patch), the on-disk checkpoint is read through the
+        injectable CheckpointReader seam and the old_string -> new_string
+        replacement is applied in memory (no on-disk mutation). Returns $null
+        when there is no old_string, the on-disk file does not exist, or the
+        old_string is not present in the on-disk content, signalling the caller
+        to allow (defer).
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        $ToolInput,
+
+        [Parameter(Mandatory)]
+        [scriptblock] $CheckpointReader
+    )
+
+    $oldString = $null
+    if ($null -ne $ToolInput -and ($ToolInput.PSObject.Properties.Name -contains 'old_string')) {
+        $oldString = [string]$ToolInput.old_string
+    }
+    if ([string]::IsNullOrEmpty($oldString)) {
+        return $null
+    }
+
+    $newString = ''
+    if ($ToolInput.PSObject.Properties.Name -contains 'new_string') {
+        $newString = [string]$ToolInput.new_string
+    }
+
+    $onDisk = & $CheckpointReader 'artifacts/orchestration/orchestrator-state.json'
+    if ([string]::IsNullOrEmpty([string]$onDisk)) {
+        # The on-disk checkpoint does not exist (or is empty); cannot patch.
+        return $null
+    }
+
+    $onDiskText = [string]$onDisk
+    if (-not $onDiskText.Contains($oldString)) {
+        # The old_string is not present, so the patch does not apply here.
+        return $null
+    }
+
+    # Apply the patch in memory using a literal (non-regex) replacement.
+    return $onDiskText.Replace($oldString, $newString)
+}
+
 function Invoke-CompletionConsistencyDecision {
     <#
     .SYNOPSIS
@@ -200,7 +318,16 @@ function Invoke-CompletionConsistencyDecision {
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
     param(
-        [string] $ToolInputRaw
+        [string] $ToolInputRaw,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $FolderExistsCheck = { param($p) Test-Path -LiteralPath $p -PathType Container },
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $CheckpointReader = { param($Path) Get-CheckpointFileContent -Path $Path },
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $RoutingMatrixReader
     )
 
     if (-not $ToolInputRaw) {
@@ -224,11 +351,17 @@ function Invoke-CompletionConsistencyDecision {
         return [ordered]@{ decision = 'allow' }
     }
 
-    # Write tool: validate the content payload. Edit tool: partial new_string is
-    # not reliable without the full target file content, so allow.
+    # Write tool: validate the content payload directly. Edit tool: no content is
+    # supplied, so read the on-disk checkpoint through the injectable seam and
+    # apply the old_string -> new_string patch in memory (read-then-validate).
     $content = $toolInput.content
     if (-not $content) {
-        return [ordered]@{ decision = 'allow' }
+        $content = Resolve-EditedCheckpointContent -ToolInput $toolInput -CheckpointReader $CheckpointReader
+        if (-not $content) {
+            # No content, and the Edit could not be resolved against on-disk
+            # state (missing file or non-matching patch): defer and allow.
+            return [ordered]@{ decision = 'allow' }
+        }
     }
 
     try {
@@ -244,14 +377,18 @@ function Invoke-CompletionConsistencyDecision {
         return [ordered]@{ decision = 'allow' }
     }
 
-    $missing = Get-MissingCompletionEvidence -Payload $payload
+    $missingArgs = @{ Payload = $payload; FolderExistsCheck = $FolderExistsCheck }
+    if ($PSBoundParameters.ContainsKey('RoutingMatrixReader') -and $null -ne $RoutingMatrixReader) {
+        $missingArgs['RoutingMatrixReader'] = $RoutingMatrixReader
+    }
+    $missing = Get-MissingCompletionEvidence @missingArgs
     if ($missing.Count -eq 0) {
         return [ordered]@{ decision = 'allow' }
     }
 
     return [ordered]@{
         decision = 'block'
-        reason   = "COMPLETION_CONSISTENCY_BLOCKED: the checkpoint asserts completion but is missing required completion evidence: $($missing -join ', '). A completion-asserting checkpoint must include a non-empty issue-num, a non-empty feature-folder, and a ci_gate object with conclusion == 'success' and a non-empty head_sha. Supply the missing evidence or remove the completion assertion."
+        reason   = "COMPLETION_CONSISTENCY_BLOCKED: the checkpoint asserts completion but is missing required completion evidence: $($missing -join ', '). A completion-asserting checkpoint must include a non-empty issue-num, a non-empty feature-folder, and a ci_gate object with conclusion == 'success' and a non-empty head_sha; routes whose requires_pr_gate is true must also include pr_gate evidence with a matching head_sha. Supply the missing evidence or remove the completion assertion."
     }
 }
 

package/resources/claude-customizations/.claude/hooks/enforce-completion-helpers.ps1

@@ -0,0 +1,163 @@
+<#
+.SYNOPSIS
+    Dot-sourced helper functions for enforce-completion-consistency.ps1.
+
+.DESCRIPTION
+    Provides testable validation helpers used by the completion-consistency
+    PreToolUse hook:
+
+      - Test-IsValidIssueNum: rejects sentinel/placeholder and non-digit issue
+        numbers; accepts digits-only strings.
+      - Test-IsValidFeatureFolder: rejects sentinel/placeholder feature folders
+        and folders not anchored under docs/features/active/<segment>; optionally
+        verifies on-disk existence through an injectable scriptblock seam.
+
+    This script is dot-sourced by enforce-completion-consistency.ps1. It contains
+    no entrypoint logic, so dot-sourcing it in tests has no side effects.
+
+.NOTES
+    Compatible with PowerShell 7+.
+#>
+[CmdletBinding()]
+param()
+
+# Sentinel/placeholder values that must never satisfy a presence check.
+$script:CompletionEvidenceSentinels = @('n/a', 'none', 'tbd')
+
+function Test-IsValidIssueNum {
+    <#
+    .SYNOPSIS
+        Returns $true only for a digits-only issue number.
+    .DESCRIPTION
+        Returns $false when the value is empty, whitespace-only, a sentinel
+        (n/a, none, tbd; case-insensitive), or contains any non-digit character.
+        Returns $true only when the trimmed value matches ^\d+$.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Value
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Value)) {
+        return $false
+    }
+    $trimmed = $Value.Trim()
+    # Sentinel placeholders are explicitly rejected even though they are
+    # non-empty strings; the comparison is case-insensitive.
+    if ($script:CompletionEvidenceSentinels -contains $trimmed.ToLowerInvariant()) {
+        return $false
+    }
+    return $trimmed -match '^\d+$'
+}
+
+function Test-IsValidFeatureFolder {
+    <#
+    .SYNOPSIS
+        Returns $true only for a sentinel-free feature folder anchored under
+        docs/features/active/ with a non-empty trailing segment that exists.
+    .DESCRIPTION
+        Returns $false when the value is empty, whitespace-only, or a sentinel
+        (n/a, none, tbd; case-insensitive). Requires the value to start with
+        'docs/features/active/' and to carry at least one additional non-empty
+        path segment after that prefix. Invokes the injectable FolderExistsCheck
+        scriptblock (default Test-Path -PathType Container) and returns $false
+        when it reports the folder does not exist.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Value,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $FolderExistsCheck = { param($p) Test-Path -LiteralPath $p -PathType Container }
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Value)) {
+        return $false
+    }
+    $trimmed = $Value.Trim()
+    if ($script:CompletionEvidenceSentinels -contains $trimmed.ToLowerInvariant()) {
+        return $false
+    }
+
+    $prefix = 'docs/features/active/'
+    $normalized = $trimmed -replace '\\', '/'
+    if (-not $normalized.StartsWith($prefix)) {
+        return $false
+    }
+
+    # Require a non-empty segment after the active/ prefix so the bare prefix is
+    # not accepted as a valid folder.
+    $suffix = $normalized.Substring($prefix.Length).TrimEnd('/')
+    if ([string]::IsNullOrWhiteSpace($suffix)) {
+        return $false
+    }
+
+    return [bool](& $FolderExistsCheck $normalized)
+}
+
+function Test-RouteRequiresPrGate {
+    <#
+    .SYNOPSIS
+        Returns $true when the payload's selected route opts into the PR gate.
+    .DESCRIPTION
+        Resolves the route id from the payload (route_id, falling back to
+        path_selected), looks it up in the routing matrix returned by the
+        injectable RoutingMatrixReader seam, and returns $true only when that
+        route's requires_pr_gate value is the boolean $true. A missing route id,
+        an unknown route, a matrix without routes, or a missing/false
+        requires_pr_gate returns $false. This generalizes the former issue-232
+        special-casing into a route-driven check.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        $Payload,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $RoutingMatrixReader = {
+            $configPath = Join-Path $PSScriptRoot '../../config/orchestration-routing.json'
+            if (-not (Test-Path -LiteralPath $configPath)) { return $null }
+            Get-Content -LiteralPath $configPath -Raw | ConvertFrom-Json
+        }
+    )
+
+    if ($null -eq $Payload) {
+        return $false
+    }
+
+    # Resolve the selected route id, preferring route_id over path_selected.
+    $routeId = ''
+    if ($Payload.PSObject.Properties.Name -contains 'route_id') {
+        $routeId = ([string]$Payload.route_id).Trim()
+    }
+    if (-not $routeId -and ($Payload.PSObject.Properties.Name -contains 'path_selected')) {
+        $routeId = ([string]$Payload.path_selected).Trim()
+    }
+    if (-not $routeId) {
+        return $false
+    }
+
+    $matrix = & $RoutingMatrixReader
+    if ($null -eq $matrix -or -not ($matrix.PSObject.Properties.Name -contains 'routes')) {
+        return $false
+    }
+    $routes = $matrix.routes
+    if ($null -eq $routes -or -not ($routes.PSObject.Properties.Name -contains $routeId)) {
+        return $false
+    }
+    $route = $routes.$routeId
+    if ($null -eq $route -or -not ($route.PSObject.Properties.Name -contains 'requires_pr_gate')) {
+        return $false
+    }
+    return ([bool]$route.requires_pr_gate -eq $true)
+}