@danmoisan/drm-copilot-mcp 0.0.5 → 0.0.6

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

@@ -0,0 +1,210 @@
+<#
+.SYNOPSIS
+    Blocks implementation operations before orchestration readiness exists.
+#>
+[CmdletBinding()]
+param()
+
+$script:CheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
+$script:Issue232FeatureFolder = 'docs/features/active/2026-06-24-harden-orchestrate-skill-232'
+
+function ConvertFrom-CheckpointJson {
+    [CmdletBinding()]
+    param([Parameter(Mandatory)][string] $Json)
+
+    return $Json | ConvertFrom-Json -ErrorAction Stop
+}
+
+function Get-StringProperty {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)][AllowNull()] $Value,
+        [Parameter(Mandatory)][string] $Name
+    )
+
+    if ($null -eq $Value -or -not ($Value.PSObject.Properties.Name -contains $Name)) {
+        return ''
+    }
+    return ([string]$Value.$Name).Trim()
+}
+
+function Test-FeatureDocumentationOrEvidencePath {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][string] $NormalizedPath)
+
+    return $NormalizedPath.StartsWith('docs/features/active/')
+}
+
+function Test-ImplementationPath {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][string] $NormalizedPath)
+
+    if (Test-FeatureDocumentationOrEvidencePath -NormalizedPath $NormalizedPath) {
+        return $false
+    }
+    if ($NormalizedPath -eq $script:CheckpointPath) {
+        return $false
+    }
+    return $NormalizedPath -match '\.(py|ps1|psm1|ts|tsx|js|jsx|cs|json|yml|yaml)$'
+}
+
+function Test-ImplementationCommand {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][string] $Command)
+
+    $normalizedCommand = $Command.Trim()
+    if (-not $normalizedCommand) {
+        return $false
+    }
+
+    $implementationCommandPatterns = @(
+        '(^|\s)git\s+(add|commit)\b',
+        '(^|\s)(poetry\s+run\s+)?(black|ruff|pyright|pytest)\b',
+        '(^|\s)npm\s+.*\s+(prettier|lint|typecheck|test:unit)\b',
+        '(^|\s)npx\s+(prettier|eslint|tsc|jest)\b',
+        '(^|\s)pwsh\s+.*(Invoke-Pester|tests/scripts/)'
+    )
+
+    foreach ($pattern in $implementationCommandPatterns) {
+        if ($normalizedCommand -match $pattern) {
+            return $true
+        }
+    }
+    return $false
+}
+
+function Test-ImplementationDelegation {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][AllowNull()] $ToolInput)
+
+    if ($null -eq $ToolInput) {
+        return $false
+    }
+
+    $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)'
+}
+
+function Test-OrchestrationReady {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][AllowNull()] $Payload)
+
+    if ($null -eq $Payload) {
+        return $false
+    }
+    $issueNum = Get-StringProperty -Value $Payload -Name 'issue-num'
+    $featureFolder = Get-StringProperty -Value $Payload -Name 'feature-folder'
+    $routeId = Get-StringProperty -Value $Payload -Name 'route_id'
+    if (-not $routeId) {
+        $routeId = Get-StringProperty -Value $Payload -Name 'path_selected'
+    }
+    $lifecycleReady = $false
+    if ($Payload.PSObject.Properties.Name -contains 'lifecycle_ready') {
+        $lifecycleReady = [bool]$Payload.lifecycle_ready
+    }
+
+    if (-not $issueNum -or -not $featureFolder -or -not $routeId -or -not $lifecycleReady) {
+        return $false
+    }
+
+    if ($issueNum -eq '232' -and $featureFolder -ne $script:Issue232FeatureFolder) {
+        return $false
+    }
+
+    return (
+        $featureFolder.StartsWith('docs/features/active/') -and
+        $routeId -and
+        $lifecycleReady
+    )
+}
+
+function Get-CheckpointContent {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    if (-not (Test-Path -LiteralPath $script:CheckpointPath)) {
+        return ''
+    }
+    return Get-Content -Raw -LiteralPath $script:CheckpointPath
+}
+
+function Invoke-OrchestrationPreimplementationGateDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $ToolInputRaw,
+        [string] $CheckpointRaw
+    )
+
+    if (-not $ToolInputRaw) {
+        return [ordered]@{ decision = 'allow' }
+    }
+    try {
+        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        throw "enforce-orchestration-preimplementation-gate hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    }
+
+    $requiresReadyCheckpoint = $false
+    $filePath = Get-StringProperty -Value $toolInput -Name 'file_path'
+    if ($filePath) {
+        $normalized = ([string]$filePath) -replace '\\', '/'
+        $requiresReadyCheckpoint = Test-ImplementationPath -NormalizedPath $normalized
+    } else {
+        $command = Get-StringProperty -Value $toolInput -Name 'command'
+        if ($command) {
+            $requiresReadyCheckpoint = Test-ImplementationCommand -Command $command
+        } else {
+            $requiresReadyCheckpoint = Test-ImplementationDelegation -ToolInput $toolInput
+        }
+    }
+
+    if (-not $requiresReadyCheckpoint) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    if (-not $CheckpointRaw) {
+        $CheckpointRaw = Get-CheckpointContent
+    }
+    try {
+        $checkpoint = ConvertFrom-CheckpointJson -Json $CheckpointRaw
+    } catch {
+        $checkpoint = $null
+    }
+
+    if (Test-OrchestrationReady -Payload $checkpoint) {
+        return [ordered]@{ decision = 'allow' }
+    }
+    $issueNum = Get-StringProperty -Value $checkpoint -Name 'issue-num'
+    if ($issueNum -eq '232') {
+        return [ordered]@{
+            decision = 'block'
+            reason   = 'PREIMPLEMENTATION_GATE_BLOCKED: Issue #232 implementation operations require artifacts/orchestration/orchestrator-state.json to contain route metadata, lifecycle readiness, and checkpoint state before implementation begins.'
+        }
+    }
+    return [ordered]@{
+        decision = 'block'
+        reason   = 'PREIMPLEMENTATION_GATE_BLOCKED: Implementation operations require artifacts/orchestration/orchestrator-state.json to contain issue number, feature folder, route metadata, lifecycle readiness, and checkpoint state before implementation begins.'
+    }
+}
+
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+try {
+    $decision = Invoke-OrchestrationPreimplementationGateDecision -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

@@ -14,18 +14,39 @@
       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.
+    Block cases:
+      Case A - gh pr create or gh pr edit 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.
+      Case D - --body-file present, context artifact present, but the authorization sentinel
+               artifacts/pr_author_authorization.json is absent or empty: blocked
+               (PR_AGENT_AUTHORIZATION_MISSING).
+      Malformed - sentinel present but not valid JSON, or issued_at missing/unparseable: blocked
+               (PR_AGENT_AUTHORIZATION_MALFORMED).
+      Case E - sentinel valid JSON but issued_by != "pr-author": blocked
+               (PR_AGENT_AUTHORIZATION_INVALID).
+      Case F - sentinel issued_by == "pr-author" but elapsed time since issued_at exceeds
+               ttl_seconds: blocked (PR_AGENT_AUTHORIZATION_EXPIRED).
+
+    Authorization sentinel decision order on the --body-file-with-context path:
+      missing -> malformed -> invalid issuer -> expired -> allow.
 
 .NOTES
     Compatible with PowerShell 7+. No external module dependencies.
+
+    Enforcement strength: the authorization sentinel is a policy guardrail, not a cryptographic
+    or security control. Any actor with Write access to artifacts/ 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 and requires a deliberate, documented act to circumvent. It MUST NOT be
+    described as tamper-proof or as a security boundary.
 #>
 [CmdletBinding()]
 param()
 
 $script:PrContextArtifactPath = 'artifacts/pr_context.summary.txt'
+$script:PrAuthorAuthorizationPath = 'artifacts/pr_author_authorization.json'
+$script:PrAuthorAuthorizationTtlSeconds = 120
 
 function Get-PrContextArtifactExistence {
     <#
@@ -41,14 +62,126 @@ function Get-PrContextArtifactExistence {
     return [bool](Test-Path -LiteralPath $script:PrContextArtifactPath)
 }
 
+function Get-PrAuthorAuthorizationContent {
+    <#
+    .SYNOPSIS
+        Read the raw text of the authorization sentinel. Tests mock this function (read seam).
+    .DESCRIPTION
+        Returns the raw text content of artifacts/pr_author_authorization.json, or $null when the
+        sentinel file is absent. This is the injectable boundary for sentinel content in tests; no
+        test writes the sentinel file to disk.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    if (-not (Test-Path -LiteralPath $script:PrAuthorAuthorizationPath)) {
+        return $null
+    }
+
+    return (Get-Content -LiteralPath $script:PrAuthorAuthorizationPath -Raw)
+}
+
+function Get-CurrentDateTimeUtc {
+    <#
+    .SYNOPSIS
+        Return the current UTC time. Tests mock this function (clock seam) for time-travel scenarios.
+    .OUTPUTS
+        System.DateTime
+    #>
+    [CmdletBinding()]
+    [OutputType([datetime])]
+    param()
+
+    return [DateTime]::UtcNow
+}
+
+function Test-PrAuthorAuthorization {
+    <#
+    .SYNOPSIS
+        Validate the authorization sentinel and return a block-reason string, or $null when authorized.
+    .DESCRIPTION
+        Reads the sentinel via Get-PrAuthorAuthorizationContent and computes elapsed time via
+        Get-CurrentDateTimeUtc. Applies the decision order missing -> malformed -> invalid issuer ->
+        expired -> allow (spec FR-2 step 3):
+          - $null/empty contents              -> PR_AGENT_AUTHORIZATION_MISSING
+          - not valid JSON, or issued_at
+            missing/unparseable               -> PR_AGENT_AUTHORIZATION_MALFORMED
+          - issued_by != "pr-author"          -> PR_AGENT_AUTHORIZATION_INVALID
+          - elapsed seconds > ttl_seconds     -> PR_AGENT_AUTHORIZATION_EXPIRED
+          - all checks pass                   -> $null (allow)
+        The ttl_seconds value defaults to the named constant when absent from the sentinel.
+        This is a policy guardrail, not a cryptographic control; the sentinel is forgeable by any
+        actor with Write access to artifacts/.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    $contents = Get-PrAuthorAuthorizationContent
+
+    if ([string]::IsNullOrWhiteSpace($contents)) {
+        return "PR_AGENT_AUTHORIZATION_MISSING: ``$script:PrAuthorAuthorizationPath`` is absent or empty. The pr-author agent must write the authorization sentinel immediately before issuing ``gh pr create``/``gh pr edit --body*``."
+    }
+
+    try {
+        $sentinel = $contents | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        return "PR_AGENT_AUTHORIZATION_MALFORMED: ``$script:PrAuthorAuthorizationPath`` is not valid JSON. The pr-author agent must write a well-formed sentinel with ``issued_by``, ``issued_at``, and ``ttl_seconds``."
+    }
+
+    $issuedAtRaw = $sentinel.issued_at
+    if ([string]::IsNullOrWhiteSpace([string]$issuedAtRaw)) {
+        return "PR_AGENT_AUTHORIZATION_MALFORMED: ``$script:PrAuthorAuthorizationPath`` is missing ``issued_at``. The pr-author agent must record a UTC ISO-8601 ``issued_at`` timestamp."
+    }
+
+    $issuedAt = [DateTime]::MinValue
+    $parsed = [DateTime]::TryParse(
+        [string]$issuedAtRaw,
+        [System.Globalization.CultureInfo]::InvariantCulture,
+        [System.Globalization.DateTimeStyles]::AdjustToUniversal -bor [System.Globalization.DateTimeStyles]::AssumeUniversal,
+        [ref] $issuedAt)
+    if (-not $parsed) {
+        return "PR_AGENT_AUTHORIZATION_MALFORMED: ``$script:PrAuthorAuthorizationPath`` has an unparseable ``issued_at``. The pr-author agent must record a UTC ISO-8601 ``issued_at`` timestamp."
+    }
+
+    if ($sentinel.issued_by -ne 'pr-author') {
+        return "PR_AGENT_AUTHORIZATION_INVALID: ``$script:PrAuthorAuthorizationPath`` ``issued_by`` is not ``pr-author``. Only the pr-author agent may authorize PR creation or body edits."
+    }
+
+    $ttlSeconds = $script:PrAuthorAuthorizationTtlSeconds
+    if ($null -ne $sentinel.ttl_seconds) {
+        $candidateTtl = 0
+        if ([int]::TryParse([string]$sentinel.ttl_seconds, [ref] $candidateTtl)) {
+            $ttlSeconds = $candidateTtl
+        }
+    }
+
+    $elapsedSeconds = ((Get-CurrentDateTimeUtc) - $issuedAt).TotalSeconds
+    if ($elapsedSeconds -gt $ttlSeconds) {
+        return "PR_AGENT_AUTHORIZATION_EXPIRED: ``$script:PrAuthorAuthorizationPath`` issued $([math]::Round($elapsedSeconds)) s ago, exceeding the ${ttlSeconds}s TTL. The pr-author agent must write a fresh sentinel immediately before the ``gh`` command."
+    }
+
+    return $null
+}
+
 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.
+        Returns PR_AUTHOR_SKILL_BLOCKED when gh pr create or gh pr edit is run with --body (inline,
+        no --body-file), or when gh pr create is run with no body flag at all. Returns
+        PR_CONTEXT_MISSING when --body-file is present but the context artifact
+        does not exist on disk. When --body-file is present and the context artifact exists, evaluates
+        the authorization sentinel via Test-PrAuthorAuthorization and returns its block reason
+        (PR_AGENT_AUTHORIZATION_*) when authorization fails. Returns $null for all allowed patterns.
+        Cases A, B, and C are evaluated first and unchanged; the sentinel check only extends the
+        previously-allowed --body-file-with-context path.
     .PARAMETER CommandText
         The Bash command text extracted from CLAUDE_TOOL_INPUT.
     .PARAMETER ContextExists
@@ -77,12 +210,13 @@ function Get-PrAuthorBypassReason {
     $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 A: gh pr create OR gh pr edit with inline --body (not --body-file). Evaluated before the
+    # gh pr edit no-body allow short-circuit so inline-body edits are blocked, not allowed.
+    if (($isPrCreate -or $isPrEdit) -and $hasInlineBody -and -not $hasBodyFile) {
+        return "PR_AUTHOR_SKILL_BLOCKED: ``gh pr create`` and ``gh pr edit`` 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``."
+    }
 
+    if ($isPrCreate) {
         # 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``."
@@ -101,6 +235,15 @@ function Get-PrAuthorBypassReason {
         return "PR_CONTEXT_MISSING: ``$script:PrContextArtifactPath`` is absent. Run ``mcp__drm-copilot__collect_pr_context`` before creating or editing the PR body."
     }
 
+    # Cases D/E/F and malformed: --body-file present and context artifact exists; verify the
+    # authorization sentinel. This extends, and does not replace, the previously-allowed path.
+    if ($hasBodyFile -and $ContextExists) {
+        $authorizationReason = Test-PrAuthorAuthorization
+        if ($authorizationReason) {
+            return $authorizationReason
+        }
+    }
+
     return $null
 }
 

package/resources/claude-customizations/.claude/hooks/validate-pr-author-output.ps1

@@ -0,0 +1,136 @@
+<#
+.SYNOPSIS
+    SubagentStop hook that verifies the pr-author agent reported a created or updated PR.
+
+.DESCRIPTION
+    Invoked by the Claude Code SubagentStop hook for the pr-author matcher. Reads the agent
+    transcript JSON from the CLAUDE_HOOK_INPUT environment variable, extracts the .output field,
+    and confirms the output reports that a pull request was created or updated. The hook allows
+    (exit 0) when the output contains:
+      - a GitHub PR URL (github.com/<owner>/<repo>/pull/<n>), or
+      - a PR reference of the form "PR #<n>", or
+      - a "gh pr create"/"gh pr edit" confirmation that includes a PR number.
+    The hook blocks (exit 1) when:
+      - CLAUDE_HOOK_INPUT is empty,
+      - the input is not valid JSON,
+      - the .output field is empty, or
+      - the output contains no PR URL or PR number.
+
+.NOTES
+    Compatible with PowerShell 7+. No external module dependencies.
+
+    Enforcement strength: this validator is a policy guardrail, not a cryptographic or security
+    control. It confirms that the pr-author agent's final output references a PR; it cannot verify
+    that the referenced PR actually exists on GitHub, and the output text is forgeable by any actor
+    that controls the agent transcript. It MUST NOT be described as tamper-proof or as a security
+    boundary.
+#>
+[CmdletBinding()]
+param()
+
+function Test-PrAuthorOutputReportsPr {
+    <#
+    .SYNOPSIS
+        Return $true when the supplied output text reports a created or updated PR.
+    .DESCRIPTION
+        Detection helper (injectable boundary for tests). Matches a GitHub PR URL, a "PR #<n>"
+        reference, or a "gh pr create"/"gh pr edit" confirmation that contains a PR number.
+    .PARAMETER OutputText
+        The pr-author agent's final output text extracted from CLAUDE_HOOK_INPUT.output.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [string] $OutputText
+    )
+
+    if ([string]::IsNullOrWhiteSpace($OutputText)) {
+        return $false
+    }
+
+    # GitHub PR URL, e.g. https://github.com/owner/repo/pull/123
+    if ($OutputText -match '(?i)github\.com/[^\s/]+/[^\s/]+/pull/\d+') {
+        return $true
+    }
+
+    # Explicit PR number reference, e.g. "PR #123".
+    if ($OutputText -match '(?i)\bPR\s*#\d+') {
+        return $true
+    }
+
+    # gh pr create / gh pr edit confirmation that includes a PR number anywhere in the output.
+    if (($OutputText -match '(?i)\bgh\s+pr\s+(create|edit)\b') -and ($OutputText -match '#\d+')) {
+        return $true
+    }
+
+    return $false
+}
+
+function Get-PrAuthorOutputDecision {
+    <#
+    .SYNOPSIS
+        Parse CLAUDE_HOOK_INPUT and return an allow-or-block decision with exit code semantics.
+    .DESCRIPTION
+        Returns an ordered dictionary with 'allowed' (bool) and 'reason' (string). Allowed is $true
+        only when the parsed .output reports a PR per Test-PrAuthorOutputReportsPr. Empty input,
+        malformed JSON, empty output, and PR-less output all yield allowed = $false.
+    .PARAMETER HookInputRaw
+        The raw JSON transcript payload supplied by Claude Code via CLAUDE_HOOK_INPUT.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $HookInputRaw
+    )
+
+    if ([string]::IsNullOrWhiteSpace($HookInputRaw)) {
+        return [ordered]@{
+            allowed = $false
+            reason  = 'PR_AUTHOR_OUTPUT_MISSING: CLAUDE_HOOK_INPUT is empty; the pr-author agent produced no transcript to validate.'
+        }
+    }
+
+    try {
+        $parsed = $HookInputRaw | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        return [ordered]@{
+            allowed = $false
+            reason  = 'PR_AUTHOR_OUTPUT_MALFORMED: CLAUDE_HOOK_INPUT is not valid JSON.'
+        }
+    }
+
+    $outputText = [string]$parsed.output
+    if ([string]::IsNullOrWhiteSpace($outputText)) {
+        return [ordered]@{
+            allowed = $false
+            reason  = 'PR_AUTHOR_OUTPUT_EMPTY: the pr-author agent output is empty; it must report the created or updated PR URL or number.'
+        }
+    }
+
+    if (Test-PrAuthorOutputReportsPr -OutputText $outputText) {
+        return [ordered]@{ allowed = $true }
+    }
+
+    return [ordered]@{
+        allowed = $false
+        reason  = 'PR_AUTHOR_OUTPUT_NO_PR: the pr-author agent output does not reference a PR URL or PR number; it must report the created or updated pull request.'
+    }
+}
+
+# Allow dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+$decision = Get-PrAuthorOutputDecision -HookInputRaw $env:CLAUDE_HOOK_INPUT
+
+if (-not $decision['allowed']) {
+    Write-Error $decision['reason']
+    exit 1
+}
+
+exit 0

package/resources/claude-customizations/.claude/hooks/validate-task-researcher-output.ps1

@@ -5,8 +5,10 @@
 .DESCRIPTION
     Blocks termination of the task-researcher subagent unless the agent's
     final output advertises a `research-path` token, the path is rooted
-    under artifacts/research/, matches the documented filename convention,
-    and the file exists on disk.
+    under one of the two tracked research roots
+    (docs/features/<feature>/research/ for feature-associated research, or
+    docs/research/ for one-off research), matches the documented filename
+    convention, and the file exists on disk.
 
 .NOTES
     Reads the hook payload from CLAUDE_HOOK_INPUT as JSON. Exits 0 to allow
@@ -64,7 +66,20 @@ function Test-IsUnderResearchRoot {
     )
 
     $normalized = $Path -replace '\\', '/'
-    return $normalized.StartsWith('artifacts/research/', [System.StringComparison]::OrdinalIgnoreCase)
+
+    # Accept either of the two tracked research roots:
+    #   - feature-associated research: docs/features/<...>/research/<file>
+    #     (a feature-folder path that contains a /research/ segment), or
+    #   - one-off research: docs/research/<file>.
+    # The /research/ segment requirement distinguishes feature research from
+    # other files under docs/features/ (for example spec.md or plan files).
+    $isFeatureResearch =
+    $normalized.StartsWith('docs/features/', [System.StringComparison]::OrdinalIgnoreCase) -and
+    $normalized.IndexOf('/research/', [System.StringComparison]::OrdinalIgnoreCase) -ge 0
+    $isOneOffResearch =
+    $normalized.StartsWith('docs/research/', [System.StringComparison]::OrdinalIgnoreCase)
+
+    return ($isFeatureResearch -or $isOneOffResearch)
 }
 
 function Test-IsValidResearchFileName {
@@ -174,15 +189,15 @@ function Invoke-TaskResearcherOutputValidation {
 
     $researchPath = Get-ResearchPathFromOutput -AgentOutput $agentOutput
     if ($null -eq $researchPath) {
-        return @{ Ok = $false; Message = 'task-researcher hook: agent output does not advertise a research-path. Researcher must report `research-path: <path>` pointing to artifacts/research/.' }
+        return @{ Ok = $false; Message = 'task-researcher hook: agent output does not advertise a research-path. Researcher must report `research-path: <path>` pointing to docs/features/<feature>/research/ (feature-associated) or docs/research/ (one-off).' }
     }
 
     if (-not (Test-IsUnderResearchRoot -Path $researchPath)) {
-        return @{ Ok = $false; Message = "task-researcher hook: research-path '$researchPath' is not under artifacts/research/. All research artifacts must be written to artifacts/research/." }
+        return @{ Ok = $false; Message = "task-researcher hook: research-path '$researchPath' is not under a tracked research root. All research artifacts must be written to docs/features/<feature>/research/ (feature-associated) or docs/research/ (one-off)." }
     }
 
     if (-not (Test-IsValidResearchFileName -Path $researchPath)) {
-        return @{ Ok = $false; Message = "task-researcher hook: research-path '$researchPath' does not match the required filename convention `artifacts/research/<timestamp>-<short-name>-research.md`." }
+        return @{ Ok = $false; Message = "task-researcher hook: research-path '$researchPath' does not match the required filename convention `<timestamp>-<short-name>-research.md` under docs/features/<feature>/research/ or docs/research/." }
     }
 
     if (-not (Test-ResearchFile -Path $researchPath)) {
@@ -208,3 +223,4 @@ if (-not $result.Ok) {
 }
 
 exit 0
+

package/resources/claude-customizations/.claude/settings.json

@@ -30,6 +30,7 @@
       "Agent(staged-review)",
       "Agent(epic-review)",
       "Agent(status-updater)",
+      "Agent(pr-author)",
       "Agent(python-typed-engineer)",
       "Agent(powershell-typed-engineer)",
       "Agent(csharp-typed-engineer)",
@@ -82,6 +83,10 @@
           {
             "type": "command",
             "command": "pwsh -NoProfile -File .claude/hooks/enforce-pr-author-skill.ps1"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File .claude/hooks/enforce-orchestration-preimplementation-gate.ps1"
           }
         ]
       },
@@ -108,6 +113,10 @@
             "type": "command",
             "command": "pwsh -NoProfile -File .claude/hooks/enforce-evidence-locations.ps1"
           },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File .claude/hooks/enforce-orchestration-preimplementation-gate.ps1"
+          },
           {
             "type": "command",
             "command": "pwsh -NoProfile -File .claude/hooks/enforce-feature-folder-order.ps1"
@@ -128,6 +137,10 @@
           {
             "type": "command",
             "command": "pwsh -NoProfile -File .claude/hooks/enforce-prd-feature-before-planner.ps1"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File .claude/hooks/enforce-orchestration-preimplementation-gate.ps1"
           }
         ]
       }
@@ -159,6 +172,15 @@
             "command": "pwsh -NoProfile -File .claude/hooks/validate-planner-output.ps1"
           }
         ]
+      },
+      {
+        "matcher": "pr-author",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File .claude/hooks/validate-pr-author-output.ps1"
+          }
+        ]
       }
     ]
   },

package/resources/claude-customizations/.claude/skills/evidence-and-timestamp-conventions/SKILL.md

@@ -31,7 +31,6 @@ The following sub-paths under `artifacts/` are FORBIDDEN for evidence output:
 
 Allowed `artifacts/` sub-paths (non-evidence orchestration use only):
 - `artifacts/orchestration/`
-- `artifacts/research/`
 
 No delegation prompt, plan task, or upstream agent instruction may override this scheme. If a caller supplies a non-canonical path, the receiving agent MUST reject it, substitute the canonical path, and record `EVIDENCE_LOCATION_OVERRIDE_REJECTED: <supplied path> replaced with <canonical path>`.