@danmoisan/drm-copilot-mcp 0.0.1 → 0.0.6

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

@@ -0,0 +1,303 @@
+<#
+.SYNOPSIS
+    Pre-tool-use hook that blocks Write operations on the orchestrator checkpoint
+    file when completed_steps appear out of declared canonical order.
+
+.DESCRIPTION
+    Invoked by the Claude Code PreToolUse hook on Write or Edit operations. The
+    hook activates only when the target file_path is
+    artifacts/orchestration/orchestrator-state.json.
+
+    For Write tool calls, the content field is parsed as JSON and its
+    completed_steps array is validated against the canonical orchestrator
+    workflow step prefixes:
+
+      S0_startup_checks
+      S1_change_budget_estimation
+      S2_research
+      S3_promotion
+      S4_atomic_planning
+      S5_atomic_execution
+      S6_pre_review_commit
+      S7_feature_review
+      S8_create_pr
+      S9_remediation_loop
+      S10_post_pr
+      S12_complete
+
+    Entries that do not match any canonical prefix are treated as informational
+    and ignored. If any pair (i, j) with i < j has a higher canonical index at
+    position i than at position j, the script blocks with a reason listing the
+    offending pair. A non-empty rollback_history array suppresses this check
+    because rollbacks legitimately reorder steps.
+
+    Edit tool calls supply only old_string/new_string (a partial patch) and
+    cannot be reliably validated without the full target file content, so they
+    are allowed by this hook. The next Write call will catch a regression.
+
+.NOTES
+    Compatible with PowerShell 7+. Read-only validation gate.
+#>
+[CmdletBinding()]
+param()
+
+$script:CanonicalStepPrefixes = @(
+    'S0_startup_checks',
+    'S1_change_budget_estimation',
+    'S2_research',
+    'S3_promotion',
+    'S4_atomic_planning',
+    'S5_atomic_execution',
+    'S6_pre_review_commit',
+    'S7_feature_review',
+    'S8_create_pr',
+    'S9_remediation_loop',
+    'S10_post_pr',
+    'S12_complete'
+)
+
+function ConvertFrom-CheckpointJson {
+    <#
+    .SYNOPSIS
+        Wrapper around ConvertFrom-Json for the checkpoint content. Mockable.
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Json
+    )
+
+    return $Json | ConvertFrom-Json -ErrorAction Stop
+}
+
+function Get-CanonicalStepIndex {
+    <#
+    .SYNOPSIS
+        Returns the canonical index for a completed_steps entry, or -1 when the
+        entry does not match any canonical prefix.
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string] $StepEntry
+    )
+
+    for ($i = 0; $i -lt $script:CanonicalStepPrefixes.Count; $i++) {
+        $prefix = $script:CanonicalStepPrefixes[$i]
+        if ($StepEntry -eq $prefix -or $StepEntry.StartsWith("$prefix" + '_') -or $StepEntry.StartsWith("$prefix.") -or $StepEntry.StartsWith("$prefix-")) {
+            return $i
+        }
+        # The S3_promotion family of variants (S3_promotion_potential, S3_promotion_issue,
+        # S3_promotion_folder, etc.) is matched by the StartsWith branches above.
+    }
+
+    return -1
+}
+
+function Get-OutOfOrderPair {
+    <#
+    .SYNOPSIS
+        Returns the first pair (entry-at-i, entry-at-j, indices) where i<j but the
+        canonical index at i is greater than the canonical index at j. Non-canonical
+        entries (index -1) are skipped. Returns $null when in order.
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyCollection()]
+        [string[]] $CompletedSteps
+    )
+
+    $indexed = @()
+    for ($i = 0; $i -lt $CompletedSteps.Count; $i++) {
+        $idx = Get-CanonicalStepIndex -StepEntry $CompletedSteps[$i]
+        if ($idx -ge 0) {
+            $indexed += [pscustomobject]@{ Position = $i; CanonicalIndex = $idx; Entry = $CompletedSteps[$i] }
+        }
+    }
+
+    for ($a = 0; $a -lt $indexed.Count; $a++) {
+        for ($b = $a + 1; $b -lt $indexed.Count; $b++) {
+            if ($indexed[$a].CanonicalIndex -gt $indexed[$b].CanonicalIndex) {
+                return [pscustomobject]@{
+                    EarlierEntry = $indexed[$a].Entry
+                    EarlierPos   = $indexed[$a].Position
+                    LaterEntry   = $indexed[$b].Entry
+                    LaterPos     = $indexed[$b].Position
+                }
+            }
+        }
+    }
+
+    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])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $NormalizedPath
+    )
+
+    return $NormalizedPath -match '(^|/)artifacts/orchestration/orchestrator-state\.json$'
+}
+
+function Invoke-CheckpointMonotonicDecision {
+    <#
+    .SYNOPSIS
+        Parses CLAUDE_TOOL_INPUT and returns an allow-or-block decision.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $ToolInputRaw
+    )
+
+    if (-not $ToolInputRaw) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    try {
+        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
+    }
+    catch {
+        throw "enforce-checkpoint-monotonic hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    }
+
+    $filePath = $toolInput.file_path
+    if (-not $filePath) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $normalized = $filePath -replace '\\', '/'
+    if (-not (Test-IsCheckpointPath -NormalizedPath $normalized)) {
+        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.
+    $content = $toolInput.content
+    if (-not $content) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    try {
+        $payload = ConvertFrom-CheckpointJson -Json $content
+    }
+    catch {
+        # The content itself is not valid JSON. Let downstream tools surface the
+        # error rather than blocking with a misleading reason here.
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    if (-not $payload.PSObject.Properties.Name -contains 'completed_steps') {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $steps = @()
+    if ($payload.completed_steps) {
+        foreach ($s in $payload.completed_steps) {
+            $steps += [string]$s
+        }
+    }
+
+    $rollbackHistory = $null
+    if ($payload.PSObject.Properties.Name -contains 'rollback_history') {
+        $rollbackHistory = $payload.rollback_history
+    }
+    if ($rollbackHistory -and @($rollbackHistory).Count -gt 0) {
+        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."
+        }
+    }
+
+    $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.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+try {
+    $decision = Invoke-CheckpointMonotonicDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
+}
+catch {
+    Write-Error $_
+    exit 1
+}
+
+$decision | ConvertTo-Json -Compress | Write-Output
+
+exit 0

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

@@ -0,0 +1,300 @@
+<#
+.SYNOPSIS
+    Pre-tool-use hook that blocks Write operations on the orchestrator checkpoint
+    file when the checkpoint asserts completion without verifiable completion
+    evidence.
+
+.DESCRIPTION
+    Invoked by the Claude Code PreToolUse hook on Write or Edit operations. The
+    hook activates only when the target file_path normalizes to
+    artifacts/orchestration/orchestrator-state.json.
+
+    A written checkpoint asserts completion when any of the following hold:
+
+      next_step == "complete"
+      completed_steps contains "S12_complete"
+      step8_status, step9_status, or step10_status == "completed"
+
+    When completion is asserted, the write is blocked unless ALL of the following
+    completion evidence is present:
+
+      - a non-empty issue-num (top-level, falling back to variables.issue-num);
+      - a non-empty feature-folder (top-level, falling back to
+        variables.feature-folder);
+      - a ci_gate object with conclusion == "success" and a non-empty head_sha.
+
+    The block reason names the specific missing evidence so the caller can
+    remediate. When completion is not asserted, the write is allowed
+    (backward compatibility).
+
+    Edit tool calls supply only old_string/new_string (a partial patch) and
+    cannot be reliably validated without the full target file content, so they
+    are allowed by this hook, matching enforce-checkpoint-monotonic.ps1. For
+    Write calls whose content is not valid JSON, the hook allows the operation
+    and defers to downstream tools to surface the error.
+
+.NOTES
+    Compatible with PowerShell 7+. Read-only validation gate.
+#>
+[CmdletBinding()]
+param()
+
+function ConvertFrom-CheckpointJson {
+    <#
+    .SYNOPSIS
+        Wrapper around ConvertFrom-Json for the checkpoint content. Mockable.
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Json
+    )
+
+    return $Json | ConvertFrom-Json -ErrorAction Stop
+}
+
+function Test-IsCheckpointPath {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $NormalizedPath
+    )
+
+    return $NormalizedPath -match '(^|/)artifacts/orchestration/orchestrator-state\.json$'
+}
+
+function Get-CheckpointStringValue {
+    <#
+    .SYNOPSIS
+        Returns a trimmed string for a payload property, or an empty string when
+        the property is absent or its value is not a non-empty string.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        $Payload,
+
+        [Parameter(Mandatory)]
+        [string] $Name
+    )
+
+    if ($null -eq $Payload) {
+        return ''
+    }
+    if (-not ($Payload.PSObject.Properties.Name -contains $Name)) {
+        return ''
+    }
+
+    $value = $Payload.$Name
+    if ($null -eq $value) {
+        return ''
+    }
+
+    return ([string]$value).Trim()
+}
+
+function Test-CompletionAsserted {
+    <#
+    .SYNOPSIS
+        Returns $true when the checkpoint payload asserts completion via
+        next_step, completed_steps, or step8/9/10 status fields.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        $Payload
+    )
+
+    if ($null -eq $Payload) {
+        return $false
+    }
+
+    $nextStep = Get-CheckpointStringValue -Payload $Payload -Name 'next_step'
+    if ($nextStep -eq 'complete') {
+        return $true
+    }
+
+    if ($Payload.PSObject.Properties.Name -contains 'completed_steps' -and $Payload.completed_steps) {
+        foreach ($step in $Payload.completed_steps) {
+            if (([string]$step) -eq 'S12_complete') {
+                return $true
+            }
+        }
+    }
+
+    foreach ($statusField in @('step8_status', 'step9_status', 'step10_status')) {
+        $status = Get-CheckpointStringValue -Payload $Payload -Name $statusField
+        if ($status -eq 'completed') {
+            return $true
+        }
+    }
+
+    return $false
+}
+
+function Get-MissingCompletionEvidence {
+    <#
+    .SYNOPSIS
+        Returns the list of missing completion-evidence descriptions for a
+        completion-asserting checkpoint. An empty list means all evidence is
+        present.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        $Payload
+    )
+
+    $missing = @()
+
+    $issueNum = Get-CheckpointStringValue -Payload $Payload -Name 'issue-num'
+    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'
+    }
+
+    $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'
+    }
+
+    $ciGate = $null
+    if ($null -ne $Payload -and ($Payload.PSObject.Properties.Name -contains 'ci_gate')) {
+        $ciGate = $Payload.ci_gate
+    }
+    if ($null -eq $ciGate -or $ciGate -isnot [System.Management.Automation.PSCustomObject]) {
+        $missing += 'ci_gate (object with conclusion == "success" and non-empty head_sha)'
+    }
+    else {
+        $conclusion = Get-CheckpointStringValue -Payload $ciGate -Name 'conclusion'
+        if ($conclusion -ne 'success') {
+            $missing += 'ci_gate.conclusion == "success"'
+        }
+        $headSha = Get-CheckpointStringValue -Payload $ciGate -Name 'head_sha'
+        if (-not $headSha) {
+            $missing += 'ci_gate.head_sha'
+        }
+    }
+
+    if ($issueNum -eq '232') {
+        $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 Invoke-CompletionConsistencyDecision {
+    <#
+    .SYNOPSIS
+        Parses CLAUDE_TOOL_INPUT and returns an allow-or-block decision based on
+        completion-evidence consistency.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $ToolInputRaw
+    )
+
+    if (-not $ToolInputRaw) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    try {
+        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
+    }
+    catch {
+        throw "enforce-completion-consistency hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    }
+
+    $filePath = $toolInput.file_path
+    if (-not $filePath) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $normalized = $filePath -replace '\\', '/'
+    if (-not (Test-IsCheckpointPath -NormalizedPath $normalized)) {
+        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.
+    $content = $toolInput.content
+    if (-not $content) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    try {
+        $payload = ConvertFrom-CheckpointJson -Json $content
+    }
+    catch {
+        # The content itself is not valid JSON. Let downstream tools surface the
+        # error rather than blocking with a misleading reason here.
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    if (-not (Test-CompletionAsserted -Payload $payload)) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $missing = Get-MissingCompletionEvidence -Payload $payload
+    if ($missing.Count -eq 0) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $issueContext = ''
+    if ((Get-CheckpointStringValue -Payload $payload -Name 'issue-num') -eq '232') {
+        $issueContext = ' Issue #232 requires pr_gate evidence and current-head ci_gate evidence.'
+    }
+
+    return [ordered]@{
+        decision = 'block'
+        reason   = "COMPLETION_CONSISTENCY_BLOCKED: the checkpoint asserts completion but is missing required completion evidence: $($missing -join ', ').$issueContext 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."
+    }
+}
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+try {
+    $decision = Invoke-CompletionConsistencyDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
+}
+catch {
+    Write-Error $_
+    exit 1
+}
+
+$decision | ConvertTo-Json -Compress | Write-Output
+
+exit 0

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

@@ -17,12 +17,15 @@
       - artifacts/evidence/
       - artifacts/regression-testing/
       - artifacts/post-change/
+      - artifacts/research/
 
     All other paths pass through, including canonical evidence paths of the form
     <FEATURE>/evidence/<kind>/ and permitted artifacts/ sub-paths such as
-    artifacts/orchestration/, artifacts/research/, artifacts/pr_context,
-    artifacts/reviews/, artifacts/status/, artifacts/python/, artifacts/pester/,
-    and artifacts/csharp/.
+    artifacts/orchestration/, artifacts/pr_context, artifacts/reviews/,
+    artifacts/status/, artifacts/python/, artifacts/pester/, and
+    artifacts/csharp/. Research output is no longer an artifacts/ sub-path; it
+    is written to the tracked roots docs/features/<feature>/research/
+    (feature-associated) or docs/research/ (one-off).
 
     If the file_path resolves to a forbidden prefix, the script writes a JSON response
     to stdout with 'decision': 'block' and exits with code 0 so Claude Code surfaces
@@ -61,7 +64,8 @@ function Test-EvidenceLocationForbidden {
         'artifacts/coverage/',
         'artifacts/evidence/',
         'artifacts/regression-testing/',
-        'artifacts/post-change/'
+        'artifacts/post-change/',
+        'artifacts/research/'
     )
 
     # Match the prefix either at the start of the string or after any directory separator,
@@ -133,18 +137,40 @@ function Invoke-EvidenceLocationDecision {
     return [ordered]@{ decision = 'allow' }
 }
 
+function Invoke-EvidenceLocationEntryPoint {
+    <#
+    .SYNOPSIS
+        Runs the evidence-location 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. On success it writes the compact JSON decision to
+        the output stream and returns 0. On a hard failure (malformed JSON) it
+        writes the error record and returns 1. This function does not call exit;
+        the thin entry-point wiring converts the returned code into a process exit.
+    .PARAMETER ToolInputRaw
+        The raw JSON string from $env:CLAUDE_TOOL_INPUT.
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param(
+        [string] $ToolInputRaw = $env:CLAUDE_TOOL_INPUT
+    )
+
+    try {
+        $decision = Invoke-EvidenceLocationDecision -ToolInputRaw $ToolInputRaw
+    } catch {
+        Write-Error $_
+        return 1
+    }
+
+    $decision | ConvertTo-Json -Compress | Write-Output
+
+    return 0
+}
+
 # Guard allows dot-sourcing in tests without executing the entrypoint.
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
 
-try {
-    $decision = Invoke-EvidenceLocationDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
-} catch {
-    Write-Error $_
-    exit 1
-}
-
-$decision | ConvertTo-Json -Compress | Write-Output
-
-exit 0
+exit (Invoke-EvidenceLocationEntryPoint)