@danmoisan/drm-copilot-mcp 0.0.1 → 0.0.5

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

@@ -0,0 +1,273 @@
+<#
+.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'
+        }
+    }
+
+    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' }
+    }
+
+    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."
+    }
+}
+
+# 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-feature-folder-order.ps1

@@ -0,0 +1,148 @@
+<#
+.SYNOPSIS
+    Pre-tool-use hook that blocks writes to a feature folder's plan.md when issue.md,
+    spec.md, or user-story.md are not yet present in that same folder.
+
+.DESCRIPTION
+    Invoked by the Claude Code PreToolUse hook on Write or Edit operations. Reads
+    tool input JSON from the CLAUDE_TOOL_INPUT environment variable. When the
+    target file_path matches a feature-folder plan.md path under
+    docs/features/(active|archive)/<folder>/plan.md, the script verifies that
+    each of issue.md, spec.md, and user-story.md exists in the same folder.
+
+    If any of the three sibling files is missing, the script emits a JSON
+    response with decision='block' and exits 0 so Claude Code surfaces the
+    reason. All other paths pass through with decision='allow'.
+
+    Filesystem reads go through Get-FeatureFolderFileExistence so tests can
+    inject a fake without touching disk.
+
+.NOTES
+    Compatible with PowerShell 7+. Read-only validation gate; no state mutation.
+#>
+[CmdletBinding()]
+param()
+
+function Get-FeatureFolderFileExistence {
+    <#
+    .SYNOPSIS
+        Wrapper around Test-Path for sibling-file existence checks. Tests mock this.
+    .PARAMETER Path
+        Absolute or workspace-relative file path to check.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Path
+    )
+
+    return [bool](Test-Path -LiteralPath $Path -PathType Leaf)
+}
+
+function Get-FeatureFolderMissingFile {
+    <#
+    .SYNOPSIS
+        Returns the list of required sibling files missing alongside plan.md.
+    .PARAMETER PlanFilePath
+        Normalized (forward-slash) path to the plan.md target.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $PlanFilePath
+    )
+
+    $folder = $PlanFilePath -replace '/plan\.md$', ''
+    $required = @('issue.md', 'spec.md', 'user-story.md')
+    [System.Collections.Generic.List[string]] $missing = [System.Collections.Generic.List[string]]::new()
+
+    foreach ($name in $required) {
+        $siblingPath = "$folder/$name"
+        if (-not (Get-FeatureFolderFileExistence -Path $siblingPath)) {
+            $missing.Add($name)
+        }
+    }
+
+    return [string[]] $missing.ToArray()
+}
+
+function Test-IsFeaturePlanPath {
+    <#
+    .SYNOPSIS
+        Returns $true if the normalized path targets a feature-folder plan.md.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $NormalizedPath
+    )
+
+    return $NormalizedPath -match '(^|/)docs/features/(active|archive)/[^/]+/plan\.md$'
+}
+
+function Invoke-FeatureFolderOrderDecision {
+    <#
+    .SYNOPSIS
+        Parses CLAUDE_TOOL_INPUT and produces an allow-or-block decision.
+    .PARAMETER ToolInputRaw
+        Raw JSON string. Empty/null returns allow.
+    #>
+    [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-feature-folder-order 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-IsFeaturePlanPath -NormalizedPath $normalized)) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $missing = Get-FeatureFolderMissingFile -PlanFilePath $normalized
+    if ($missing.Count -eq 0) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $list = ($missing -join ', ')
+    return [ordered]@{
+        decision = 'block'
+        reason   = "FEATURE_FOLDER_ORDER_BLOCKED: cannot write plan.md before producing prerequisite documents. Missing in feature folder: $list. Invoke the prd-feature subagent to generate the missing file(s) before authoring plan.md."
+    }
+}
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+try {
+    $decision = Invoke-FeatureFolderOrderDecision -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-pr-author-skill.ps1

@@ -0,0 +1,190 @@
+<#
+.SYNOPSIS
+    Pre-tool-use hook that enforces the pr-author skill is used before gh pr create or gh pr edit.
+
+.DESCRIPTION
+    Invoked by the Claude Code PreToolUse hook before any Bash command runs. Reads
+    tool input JSON from the CLAUDE_TOOL_INPUT environment variable, inspects the
+    attempted command, and blocks gh pr create / gh pr edit commands that bypass the
+    pr-author skill workflow.
+
+    Required sequence:
+      1. mcp__drm-copilot__collect_pr_context writes artifacts/pr_context.summary.txt
+      2. pr-author skill reads that file and writes artifacts/pr_body_<N>.md
+      3. gh pr create --body-file artifacts/pr_body_<N>.md
+         (or gh pr edit --body-file ...)
+
+    Three block cases:
+      Case A - gh pr create with --body (inline, no --body-file): blocked.
+      Case B - gh pr create with neither --body nor --body-file: blocked.
+      Case C - gh pr create or gh pr edit with --body-file but context artifact absent: blocked.
+
+.NOTES
+    Compatible with PowerShell 7+. No external module dependencies.
+#>
+[CmdletBinding()]
+param()
+
+$script:PrContextArtifactPath = 'artifacts/pr_context.summary.txt'
+
+function Get-PrContextArtifactExistence {
+    <#
+    .SYNOPSIS
+        Wrapper around Test-Path for the PR context artifact. Tests mock this function.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param()
+
+    return [bool](Test-Path -LiteralPath $script:PrContextArtifactPath)
+}
+
+function Get-PrAuthorBypassReason {
+    <#
+    .SYNOPSIS
+        Inspect the command text and return a block reason string, or $null when the command is allowed.
+    .DESCRIPTION
+        Returns PR_AUTHOR_SKILL_BLOCKED when gh pr create is run with --body (inline) or with no body
+        flag at all. Returns PR_CONTEXT_MISSING when --body-file is present but the context artifact
+        does not exist on disk. Returns $null for all allowed patterns.
+    .PARAMETER CommandText
+        The Bash command text extracted from CLAUDE_TOOL_INPUT.
+    .PARAMETER ContextExists
+        Whether artifacts/pr_context.summary.txt currently exists on disk.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $CommandText,
+
+        [Parameter(Mandatory)]
+        [bool] $ContextExists
+    )
+
+    # Only act on gh pr create or gh pr edit subcommands.
+    $isPrCreate = $CommandText -match '(?i)\bgh\s+pr\s+create\b'
+    $isPrEdit = $CommandText -match '(?i)\bgh\s+pr\s+edit\b'
+
+    if (-not $isPrCreate -and -not $isPrEdit) {
+        return $null
+    }
+
+    $hasBodyFile = $CommandText -match '(?i)--body-file\b'
+    $hasInlineBody = $CommandText -match '(?i)--body(?!-file)\b'
+
+    if ($isPrCreate) {
+        # Case A: gh pr create with inline --body (not --body-file).
+        if ($hasInlineBody -and -not $hasBodyFile) {
+            return "PR_AUTHOR_SKILL_BLOCKED: ``gh pr create`` must use ``--body-file`` with a file produced by the pr-author skill from ``$script:PrContextArtifactPath``. Run ``mcp__drm-copilot__collect_pr_context`` to generate the context file, apply the pr-author skill to produce ``artifacts/pr_body_<N>.md``, then pass that file via ``--body-file``."
+        }
+
+        # Case B: gh pr create with no body flag at all.
+        if (-not $hasInlineBody -and -not $hasBodyFile) {
+            return "PR_AUTHOR_SKILL_BLOCKED: New PRs require ``--body-file``. Run ``mcp__drm-copilot__collect_pr_context`` to generate ``$script:PrContextArtifactPath``, apply the pr-author skill to produce ``artifacts/pr_body_<N>.md``, then pass that file via ``--body-file``."
+        }
+    }
+
+    if ($isPrEdit) {
+        # gh pr edit with no --body or --body-file (e.g., --title, --add-label, --reviewer) is allowed.
+        if (-not $hasInlineBody -and -not $hasBodyFile) {
+            return $null
+        }
+    }
+
+    # Case C: --body-file present but context artifact is absent.
+    if ($hasBodyFile -and -not $ContextExists) {
+        return "PR_CONTEXT_MISSING: ``$script:PrContextArtifactPath`` is absent. Run ``mcp__drm-copilot__collect_pr_context`` before creating or editing the PR body."
+    }
+
+    return $null
+}
+
+function Invoke-PrAuthorSkillDecision {
+    <#
+    .SYNOPSIS
+        Parse CLAUDE_TOOL_INPUT and return an allow-or-block decision.
+    .PARAMETER ToolInputRaw
+        The raw JSON tool payload supplied by Claude Code.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary
+    .NOTES
+        Missing tool input or missing command text is treated as allow.
+    #>
+    [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-pr-author-skill hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    }
+
+    $commandText = $toolInput.command
+    if (-not $commandText) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $contextExists = Get-PrContextArtifactExistence
+    $reason = Get-PrAuthorBypassReason -CommandText $commandText -ContextExists $contextExists
+
+    if ($reason) {
+        return [ordered]@{
+            decision = 'block'
+            reason   = $reason
+        }
+    }
+
+    return [ordered]@{ decision = 'allow' }
+}
+
+function Test-PrAuthorBypassRequired {
+    <#
+    .SYNOPSIS
+        Return $true when a Bash command requires the pr-author skill to run first.
+    .PARAMETER CommandText
+        The Bash command text extracted from CLAUDE_TOOL_INPUT.
+    .PARAMETER ContextExists
+        Whether artifacts/pr_context.summary.txt currently exists on disk.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $CommandText,
+
+        [Parameter(Mandatory)]
+        [bool] $ContextExists
+    )
+
+    return ($null -ne (Get-PrAuthorBypassReason -CommandText $CommandText -ContextExists $ContextExists))
+}
+
+# Allow dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+try {
+    $decision = Invoke-PrAuthorSkillDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
+} catch {
+    Write-Error $_
+    exit 1
+}
+
+$decision | ConvertTo-Json -Compress | Write-Output
+
+exit 0