@danmoisan/drm-copilot-mcp 1.1.11 → 1.1.12

package/resources/claude-customizations/.claude/hooks/enforce-prd-feature-before-planner.ps1

@@ -12,7 +12,18 @@
     'atomic-planner'.
 
     Feature folder resolution order:
-      1. Scan the prompt text for any path matching
+      1. Resolve the worktree this call pertains to from the assembled prompt and
+         description text, by portable identity only: the canonical issue-number
+         line, and a branch signal. The resolution belongs to the
+         worktree-resolution library and is not re-implemented here. No path
+         signal selects a worktree, because a merged feature folder exists in
+         every checkout branched from main and so places a call in many at once.
+         When the call carries no identity, or an identity the library cannot
+         narrow to one live worktree, the gate denies at once with that library's
+         own reason code -- the no-target code or the ambiguity code -- before any
+         document probe runs. A probe at that point would validate the call
+         against whichever root happened to be current.
+      2. Scan the prompt text for any path matching
          docs/features/active/<token>, accepting both forward-slash and
          backslash separators. Truncate every match to two segments past the
          docs/features/active/ prefix -- that is, to exactly four path segments:
@@ -22,16 +33,30 @@
          the same folder. A match that truncates to fewer than four segments is
          rejected. Candidates are deduplicated preserving first-occurrence
          order.
-      2. Select among the distinct candidates: one candidate is used directly;
-         otherwise the candidate equal to the checkpoint's feature-folder field
-         is preferred, because the checkpoint is the orchestrator's own record of
-         which feature is in flight; otherwise the earliest-occurring candidate
-         in the prompt wins, because the orchestrator names the active feature
-         folder before citing artifacts inside it.
-      3. If no candidate was found in the prompt, read the feature-folder field
-         from artifacts/orchestration/orchestrator-state.json.
-      4. If neither yields a folder, block with a reason instructing the caller
-         to reference a feature folder explicitly.
+      3. Choose among the distinct candidates by asking which one the resolved
+         worktree's own orchestrator checkpoint names. That checkpoint is the only
+         disambiguator, and neither prompt position nor a foreign session's record
+         takes that role: position would make selection an accident of wording,
+         and another session's checkpoint records its own unrelated work.
+      4. When more than one folder was cited and that checkpoint names none of
+         them, the tie is unresolved and the gate denies with the ambiguity
+         reason code rather than selecting any one of the candidates.
+      5. When the prompt named no folder at all, the resolved worktree's
+         checkpoint supplies one. It is the item's own checkpoint by
+         construction, because identity selected the worktree it sits in, so the
+         conditional guard that used to protect this step is unnecessary and has
+         been removed.
+      6. If no folder is resolved by any of the steps above, block with a reason
+         instructing the caller to reference a feature folder explicitly.
+      7. Once a folder is resolved, anchor every document probe to the resolved
+         target root, and only when that root differs from the session root. When
+         the two coincide the bare repo-relative spelling is kept, because
+         prefixing unconditionally would break every call that legitimately
+         resolves where it runs. A folder that is absent under the resolved target
+         root therefore denies on the missing-document reason for that root. It
+         never denies on the marker-is-broken reason, which is reachable only when
+         the folder does exist under that root and its work-mode marker cannot be
+         read.
 
     Known limitation: resolution stops at the feature-folder segment, so it does
     not descend into a version folder (v1/, v2/). No versioned folder exists
@@ -76,6 +101,16 @@ param()
 
 
 Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+# Issue #669 owns worktree location and path normalisation; issue #673 owns the
+# portable-identity resolution this gate now selects a worktree with. Both imports are
+# unguarded on purpose: a resolution module that cannot be loaded is itself the
+# target-not-resolvable state, and the gate must fail closed on it rather than degrade to
+# a permissive path. Both are required rather than one: the absolute-path join the probe
+# step below calls is exported only by the first, because a module whose exports are pinned
+# by an explicit list does not re-export a sibling's functions to its own importer.
+Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeTargetResolution.psm1') -Force
+Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeItemResolution.psm1') -Force
+. (Join-Path $PSScriptRoot 'enforce-prd-feature-before-planner-helpers.ps1')
 function Get-PrdFeatureFileExistence {
     <#
     .SYNOPSIS
@@ -117,75 +152,6 @@ function Get-PrdFeatureIssueContent {
     }
 }
 
-function Resolve-PrdFeatureWorkMode {
-    <#
-    .SYNOPSIS
-        Parses the persisted `- Work Mode: ...` marker out of issue.md content
-        and returns the canonical mode, or $null when the marker is absent,
-        unreadable, or unrecognized.
-    .DESCRIPTION
-        Recognizes minor-audit, full-feature, full-bug, and the legacy full
-        marker (normalized to full-feature), mirroring the regex convention
-        used by scripts/dev_tools/prompt_mode_contract.py so both runtimes
-        agree on what counts as a valid marker line.
-    #>
-    [CmdletBinding()]
-    [OutputType([string])]
-    param(
-        [AllowNull()]
-        [string] $IssueContent
-    )
-
-    if ([string]::IsNullOrWhiteSpace($IssueContent)) {
-        return $null
-    }
-
-    $match = [regex]::Match($IssueContent, '(?im)^-\s*Work Mode:\s*(minor-audit|full-feature|full-bug|full)\s*$')
-    if (-not $match.Success) {
-        return $null
-    }
-
-    $rawMode = $match.Groups[1].Value
-    if ($rawMode -eq 'full') {
-        return 'full-feature'
-    }
-    return $rawMode
-}
-
-function Get-PrdFeatureRequiredFile {
-    <#
-    .SYNOPSIS
-        Maps a resolved work mode to the set of prd-feature output files the
-        target folder must contain before an atomic-planner delegation is
-        allowed.
-    .DESCRIPTION
-        full-feature requires spec.md and user-story.md; full-bug requires
-        spec.md only; minor-audit requires neither.
-
-        The default arm returns spec.md alone. It is not reached from the
-        decision path for an undeterminable mode, which denies on its own branch
-        without probing at all; the arm exists so a direct caller passing a $null
-        or unrecognized mode never receives a permissive empty set, and it must
-        not name user-story.md, because that document is required to be ABSENT
-        for full-bug and minor-audit work.
-    #>
-    [CmdletBinding()]
-    [OutputType([string[]])]
-    param(
-        [AllowNull()]
-        [string] $WorkMode
-    )
-
-    # Route on the canonical mode; anything outside the three known values
-    # (including $null) falls through to the fail-closed default case.
-    switch ($WorkMode) {
-        'full-feature' { return [string[]]@('spec.md', 'user-story.md') }
-        'full-bug' { return [string[]]@('spec.md') }
-        'minor-audit' { return [string[]]@() }
-        default { return [string[]]@('spec.md') }
-    }
-}
-
 function Get-PrdFeatureCheckpointFolder {
     <#
     .SYNOPSIS
@@ -195,7 +161,8 @@ function Get-PrdFeatureCheckpointFolder {
     [CmdletBinding()]
     [OutputType([string])]
     param(
-        [string] $CheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
+        [Parameter(Mandatory)]
+        [string] $CheckpointPath
     )
 
     if (-not (Test-Path -LiteralPath $CheckpointPath -PathType Leaf)) {
@@ -216,133 +183,138 @@ function Get-PrdFeatureCheckpointFolder {
     return $null
 }
 
-function Find-PrdFeatureFolderFromPrompt {
+function Get-PrdFeatureTargetDecision {
     <#
     .SYNOPSIS
-        Scans a prompt string for docs/features/active/<...> path tokens,
-        truncates each to exactly four path segments, and returns the selected
-        feature folder. Returns $null when no token truncates to four segments.
+        Builds a target-resolution deny, carrying the caller's reason code.
     .DESCRIPTION
-        Truncation to four segments -- docs, features, active, and the
-        feature-folder name -- is two segments past the docs/features/active/
-        prefix, so the depth at which an artifact is cited cannot change which
-        folder is resolved. Candidates are deduplicated preserving
-        first-occurrence order; selection among two or more distinct candidates
-        prefers the checkpoint's feature-folder field and otherwise takes the
-        earliest occurrence in the prompt.
-
-        The return value is a repo-relative path normalized to forward slashes,
-        or $null. The function reads no file except through the existing
-        checkpoint seam, and it is deterministic for a given prompt and
-        checkpoint value.
+        The code is supplied by the caller rather than chosen here, because two are
+        now reachable: the no-target code when the call carries no identity or an
+        identity that places in no live worktree, and the ambiguity code when
+        several live worktrees match or two identities disagree. Both are read from
+        the resolution library's accessors, so the gate and the library can never
+        disagree about either spelling.
+
+        Every reason built here is distinct from the missing-document and marker
+        reasons, which name a resolved folder rather than a resolution failure.
+
+        The remedy sentence names the two identity lines rather than an absolute
+        path. Citing a path is no longer an action that selects anything, so the
+        previous remedy would have instructed the caller to do something inert.
+    .PARAMETER ReasonCode
+        The resolution reason code to carry, from one of the library's accessors.
+    .PARAMETER Detail
+        The library's own detail text for the unresolved state.
     #>
     [CmdletBinding()]
-    [OutputType([string])]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
     param(
         [Parameter(Mandatory)]
         [AllowEmptyString()]
-        [string] $Prompt
-    )
+        [string] $ReasonCode,
 
-    if (-not $Prompt) {
-        return $null
-    }
-
-    # Allow forward or backslash separators inside the matched path token.
-    $pattern = 'docs[\\/]+features[\\/]+active[\\/]+[^\s"''`]+'
-    $matchList = [regex]::Matches($Prompt, $pattern)
-    if ($matchList.Count -eq 0) {
-        return $null
-    }
-
-    # Deduplicate preserving FIRST-OCCURRENCE order. A [hashtable] must not be
-    # used here: PowerShell hashtable key enumeration order is unspecified, so a
-    # first-occurrence selection rule fed by a hashtable is not deterministic.
-    [System.Collections.Generic.List[string]] $candidates = [System.Collections.Generic.List[string]]::new()
-    foreach ($m in $matchList) {
-        $normalized = ($m.Value -replace '\\', '/').TrimEnd('/')
-
-        # Truncate to exactly two segments past the docs/features/active/ prefix,
-        # that is, to the four segments docs, features, active, and the feature
-        # folder name. Truncation is depth-insensitive, so a folder path, a
-        # spec.md path, a research/ artifact path, and an evidence/ artifact path
-        # all reduce to the same value. A '.' component is a path no-op and is
-        # discarded first, so a degenerate token such as docs/features/active/.
-        # yields three segments and is rejected rather than resolved.
-        $segments = @($normalized -split '/' | Where-Object { $_ -ne '' -and $_ -ne '.' })
-        if ($segments.Count -lt 4) {
-            continue
-        }
-
-        $truncated = ($segments[0..3] -join '/')
-        if (-not $candidates.Contains($truncated)) {
-            $candidates.Add($truncated)
-        }
-    }
-
-    if ($candidates.Count -eq 0) {
-        return $null
-    }
-
-    # One distinct candidate is used directly, so the common case never consults
-    # the checkpoint.
-    if ($candidates.Count -eq 1) {
-        return $candidates[0]
-    }
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string] $Detail
+    )
 
-    # More than one distinct feature folder was cited. Prefer the folder the
-    # orchestrator itself records as in flight: the checkpoint is the
-    # authoritative disambiguator, and it reuses a seam this hook already owns.
-    $checkpointFolder = Get-PrdFeatureCheckpointFolder
-    if ($checkpointFolder) {
-        $checkpointNormalized = ($checkpointFolder -replace '\\', '/').TrimEnd('/')
-        if ($candidates.Contains($checkpointNormalized)) {
-            return $checkpointNormalized
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = "PRD_FEATURE_BLOCKED: $ReasonCode - $Detail. " +
+            "Put the line 'Canonical issue number for this feature is <N>.' and a " +
+            "'branch: <item branch>' label in the delegation prompt so the gate can identify the item."
         }
     }
-
-    # Tiebreak of last resort: the orchestrator supplies the active feature folder
-    # among its delegation inputs and names it before citing artifacts inside it,
-    # so a cross-reference to another feature appears later in the prompt.
-    return $candidates[0]
 }
 
-function Get-PrdFeatureMissingFile {
+function Resolve-PrdFeatureWorktreeTarget {
     <#
     .SYNOPSIS
-        Returns the subset of $RequiredFile that is missing from the target
-        folder.
+        Resolve the delegation's target worktree. Tests mock this function (seam).
+    .DESCRIPTION
+        A seam rather than a direct call because the resolver reads real git state: the
+        worktree list, each registration's branch, and the filesystem. A test that drove
+        it directly would depend on whichever worktrees exist on the machine running it.
+    .PARAMETER Text
+        The assembled prompt and description text to read identity from.
+    .OUTPUTS
+        The target result object from Resolve-WorktreeItemTarget.
     #>
     [CmdletBinding()]
-    [OutputType([string[]])]
+    [OutputType([pscustomobject])]
     param(
         [Parameter(Mandatory)]
-        [string] $FeatureFolder,
+        [AllowEmptyString()]
+        [string] $Text
+    )
 
-        [Parameter(Mandatory)]
-        [AllowEmptyCollection()]
-        [string[]] $RequiredFile
+    return (Resolve-WorktreeItemTarget -Text $Text -SessionRoot (Get-Location).Path)
+}
+
+function Get-PrdFeatureCallTarget {
+    <#
+    .SYNOPSIS
+        Resolves the worktree this tool call pertains to, or $null when the call
+        supplies no text to resolve from.
+    .DESCRIPTION
+        The resolution itself belongs to the worktree-resolution library and is not
+        re-implemented here: this function only assembles the text it reads, from the
+        envelope root and the nested tool_input, and supplies the session root from
+        the envelope's own cwd field when the runtime sets one.
+
+        The assembled text is handed to the derivation unconditionally. Which
+        citations are eligible to be placed is the derivation's decision and not
+        this hook's: it answers NoTarget for a call it cannot place at all, and
+        Ambiguous for a placed signal that resolves to no worktree or to several.
+        A repo-relative citation therefore has a real placement channel, because
+        the derivation keeps only the worktrees under which that repo-relative
+        path exists. The outcome the caller sees is fail-closed:
+        a call that places in no worktree, or in several, denies before any probe
+        runs, rather than being validated against whichever root happened to be
+        current.
+    #>
+    [CmdletBinding()]
+    [OutputType([object])]
+    param(
+        [AllowNull()]
+        [object] $ToolInput
     )
 
-    [System.Collections.Generic.List[string]] $missing = [System.Collections.Generic.List[string]]::new()
-    foreach ($name in $RequiredFile) {
-        $candidate = "$FeatureFolder/$name"
-        if (-not (Get-PrdFeatureFileExistence -Path $candidate)) {
-            $missing.Add($name)
-        }
+    $prompt = Get-ClaudeHookToolInputString -ToolInput $ToolInput -Name 'prompt'
+    $description = Get-ClaudeHookToolInputString -ToolInput $ToolInput -Name 'description'
+    $text = (@($prompt, $description) | Where-Object { $_ }) -join ' '
+
+    # An empty call resolves nothing and, importantly, performs no enumeration and no
+    # file read. The caller treats the null as the no-target state.
+    if (-not $text) {
+        return $null
     }
-    return [string[]] $missing.ToArray()
+
+    return (Resolve-PrdFeatureWorktreeTarget -Text $text)
 }
 
 function Invoke-PrdFeatureBeforePlannerDecision {
     <#
     .SYNOPSIS
         Parses the envelope's nested tool_input and returns an allow-or-block decision.
+    .PARAMETER ToolInputRaw
+        The raw PreToolUse payload.
+    .PARAMETER ResolvedTarget
+        Test-only injection seam for the derived call target, following the
+        -CheckpointRaw precedent in enforce-orchestration-preimplementation-gate.ps1.
+        Binding is decided with $PSBoundParameters.ContainsKey rather than a
+        truthiness test, so an explicitly supplied empty value suppresses the
+        derivation seam instead of falling through to it.
     #>
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
     param(
-        [string] $ToolInputRaw
+        [string] $ToolInputRaw,
+
+        [AllowNull()]
+        [object] $ResolvedTarget
     )
 
     $envelope = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
@@ -364,9 +336,47 @@ function Invoke-PrdFeatureBeforePlannerDecision {
     }
 
     $prompt = Get-ClaudeHookToolInputString -ToolInput $envelope.Value -Name 'prompt'
-    $folder = Find-PrdFeatureFolderFromPrompt -Prompt $prompt
+
+    $target = if ($PSBoundParameters.ContainsKey('ResolvedTarget')) {
+        $ResolvedTarget
+    }
+    else {
+        Get-PrdFeatureCallTarget -ToolInput $envelope.Value
+    }
+
+    # Unresolved identity denies before any document probe runs; a probe here would
+    # validate the call against whichever root happened to be current. A null target has
+    # two origins that mean the same thing -- the injection seam bound to null, and a call
+    # carrying no text at all -- so both take the no-target code.
+    if ($null -eq $target -or $target.Status -eq 'NoTarget' -or $target.Status -eq 'Ambiguous') {
+        $code = if ($null -eq $target) { Get-WorktreeResolutionNoTargetReasonCode } else { $target.ReasonCode }
+        $detail = if ($null -eq $target) { 'the call target was not resolved' } else { $target.Detail }
+        return (Get-PrdFeatureTargetDecision -ReasonCode $code -Detail $detail)
+    }
+
+    $candidates = @(Find-PrdFeatureFolderCandidate -Prompt $prompt)
+
+    # The checkpoint is read only when it is needed. Exactly one cited candidate is used
+    # directly, so the common case performs no checkpoint read at all; zero or several
+    # candidates need the resolved worktree's own checkpoint, which is read once here.
+    $checkpointFolder = $null
+    if ($candidates.Count -ne 1) {
+        $checkpointFolder = Get-PrdFeatureCheckpointFolder -CheckpointPath (Get-WorktreeItemCheckpointPath -WorktreeRoot $target.WorktreeRoot)
+    }
+
+    $folder = Find-PrdFeatureFolderFromPrompt -Prompt $prompt -CheckpointFolder $checkpointFolder
+
+    # More than one folder was cited and the resolved worktree's checkpoint names none of
+    # them. The tie is unresolved, which is a resolution failure rather than a document one.
+    if (-not $folder -and $candidates.Count -gt 1) {
+        return (Get-PrdFeatureTargetDecision -ReasonCode (Get-WorktreeResolutionAmbiguityReasonCode) -Detail ("the call cites $($candidates.Count) feature folders ($($candidates -join ', ')) and the resolved worktree's checkpoint chooses between none of them"))
+    }
+
+    # The prompt named no folder, so the resolved worktree's checkpoint supplies one. It is
+    # the item's own checkpoint by construction, because identity selected the worktree it
+    # sits in, so no conditional guard is needed before trusting it.
     if (-not $folder) {
-        $folder = Get-PrdFeatureCheckpointFolder
+        $folder = $checkpointFolder
     }
 
     if (-not $folder) {
@@ -374,18 +384,37 @@ function Invoke-PrdFeatureBeforePlannerDecision {
             hookSpecificOutput = [ordered]@{
                 hookEventName            = 'PreToolUse'
                 permissionDecision       = 'deny'
-                permissionDecisionReason = "PRD_FEATURE_BLOCKED: atomic-planner delegation must reference a feature folder (either in the prompt or via orchestrator-state.json) so spec.md and user-story.md prerequisites can be verified."
+                permissionDecisionReason = "PRD_FEATURE_BLOCKED: atomic-planner delegation must reference a feature folder, either in the prompt or in the orchestrator checkpoint of the worktree the call resolves to, so spec.md and user-story.md prerequisites can be verified."
             }
         }
     }
 
     $folderNormalized = ($folder -replace '\\', '/').TrimEnd('/')
 
+    # Anchor every probe to the resolved target root, and only when that root differs
+    # from the session root. When the two coincide the bare repo-relative spelling is
+    # kept: prefixing unconditionally would break every call that legitimately resolves
+    # where it runs.
+    $probeFolder = $folderNormalized
+    if ($null -ne $target -and $target.Status -eq 'OtherWorktree' -and $target.WorktreeRoot) {
+        $probeFolder = Join-WorktreeResolutionPath -WorktreeRoot $target.WorktreeRoot -RepoRelativePath $folderNormalized
+    }
+
     # Derive the prerequisite set from the persisted work-mode marker rather
     # than a fixed spec.md/user-story.md pair. A marker that cannot be read or
     # recognized must fail closed, not fail open: it denies on its own branch
     # below, naming no prerequisite set and probing for no required file.
-    $issueContent = Get-PrdFeatureIssueContent -FeatureFolder $folderNormalized
+    $issueContent = Get-PrdFeatureIssueContent -FeatureFolder $probeFolder
+
+    # A folder that is absent from the resolved target root is a resolution failure,
+    # not a broken marker. Reporting it as a broken marker would describe a folder the
+    # gate probed at a root the call never named. The conjunct on the guard above is
+    # load-bearing: without it, an unreadable issue.md would take this branch on every
+    # session-root call instead of falling through to the work-mode branch.
+    if ($null -eq $issueContent -and $probeFolder -ne $folderNormalized) {
+        return (Get-PrdFeatureTargetDecision -ReasonCode (Get-WorktreeResolutionAmbiguityReasonCode) -Detail ("the resolved feature folder '$probeFolder' does not exist under the resolved target worktree, so the call's target cannot be confirmed"))
+    }
+
     $workMode = Resolve-PrdFeatureWorkMode -IssueContent $issueContent
 
     # An indeterminate mode is its own decision path, and it deliberately does NOT
@@ -400,8 +429,8 @@ function Invoke-PrdFeatureBeforePlannerDecision {
             hookSpecificOutput = [ordered]@{
                 hookEventName            = 'PreToolUse'
                 permissionDecision       = 'deny'
-                permissionDecisionReason = "PRD_FEATURE_BLOCKED: resolved feature folder '$folderNormalized', " +
-                "but its work mode could not be determined from '$folderNormalized/issue.md' " +
+                permissionDecisionReason = "PRD_FEATURE_BLOCKED: resolved feature folder '$probeFolder', " +
+                "but its work mode could not be determined from '$probeFolder/issue.md' " +
                 '(the ''- Work Mode:'' marker is absent, unreadable, or unrecognized). ' +
                 'Confirm that is the intended feature folder, then add or correct the ' +
                 '''- Work Mode:'' marker in that file so the prerequisite set can be derived.'
@@ -414,7 +443,7 @@ function Invoke-PrdFeatureBeforePlannerDecision {
     # -RequiredFile parameter on Get-PrdFeatureMissingFile for minor-audit mode.
     $required = @(Get-PrdFeatureRequiredFile -WorkMode $workMode)
 
-    $missing = Get-PrdFeatureMissingFile -FeatureFolder $folderNormalized -RequiredFile $required
+    $missing = Get-PrdFeatureMissingFile -FeatureFolder $probeFolder -RequiredFile $required
     if ($missing.Count -eq 0) {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
@@ -423,7 +452,7 @@ function Invoke-PrdFeatureBeforePlannerDecision {
     # folder they did not intend diagnoses a path problem immediately instead of
     # re-running a step that has already completed correctly.
     $list = ($missing -join ', ')
-    $reason = "PRD_FEATURE_BLOCKED: resolved feature folder '$folderNormalized' is missing: " +
+    $reason = "PRD_FEATURE_BLOCKED: resolved feature folder '$probeFolder' is missing: " +
     "$list (work mode: $workMode). Confirm that is the intended feature folder, then " +
     'invoke the prd-feature subagent to produce the missing output(s).'
 

package/resources/claude-customizations/.claude/lib/codex-routing/CodexDeployment.psm1

@@ -71,6 +71,7 @@ $script:GENERATED_AGENT_FAMILIES = @(
     'task-researcher',
     'prd-feature',
     'pr-author',
+    'commit-steward',
     'python-typed-engineer',
     'powershell-typed-engineer',
     'csharp-typed-engineer',