@danmoisan/drm-copilot-mcp 1.1.11 → 1.1.12

package/resources/claude-customizations/.claude/lib/worktree-resolution/WorktreeTargetResolution.psm1

@@ -0,0 +1,347 @@
+<#
+.SYNOPSIS
+    Call-target derivation for target-worktree resolution (issue #669).
+
+.DESCRIPTION
+    Reads target signals from a tool-call payload (a feature-folder path, a file
+    path, and a branch name) and derives the worktree the call pertains to as one
+    of four states: SessionRoot, OtherWorktree, NoTarget, or Ambiguous.
+
+    The presence of a signal, not the success of resolving it, separates NoTarget
+    from Ambiguous. Signals that resolve to different worktree roots are
+    Ambiguous. The precedence order FeatureFolderPath, FilePath, Branch only
+    selects which agreeing signal is reported; no run state is ever read to break
+    a disagreement.
+
+.NOTES
+    Compatible with PowerShell 7+. Pure given its sibling WorktreeResolution.psm1,
+    which owns every filesystem read. No subprocess, no network, no clock read, and
+    no environment read. Mirrored byte-identically under
+    extensions/drm-copilot/resources/claude-customizations/.
+    CONVENTION: this module fails fast at module scope and imports its siblings with -ErrorAction Stop.
+#>
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+Import-Module (Join-Path $PSScriptRoot 'WorktreeResolution.psm1') -ErrorAction Stop
+
+# The four states of a derived target. The set is closed so a caller writes exactly
+# one branch per state; a fifth value would silently fall through every caller.
+$script:StatusSessionRoot = 'SessionRoot'
+$script:StatusOtherWorktree = 'OtherWorktree'
+$script:StatusNoTarget = 'NoTarget'
+$script:StatusAmbiguous = 'Ambiguous'
+
+# The signal kinds a result may report. SessionRoot names no payload signal; it is
+# reserved for a caller that resolves against the session root deliberately.
+$script:SignalFeatureFolderPath = 'FeatureFolderPath'
+$script:SignalFilePath = 'FilePath'
+$script:SignalBranch = 'Branch'
+$script:SignalSessionRoot = 'SessionRoot'
+
+# The prose label used for each payload signal in a Detail clause.
+$script:SignalLabel = @{
+    FeatureFolderPath = 'feature folder token'
+    FilePath          = 'file path'
+    Branch            = 'branch'
+}
+
+# A feature-folder token: an optional prefix ending in a separator, then
+# docs/features/active/<folder>. The prefix is kept rather than discarded, because
+# an absolute prefix is the only unambiguous placement of the token.
+$script:FeatureFolderPattern = '(?<![^\s"''`(])(?:[^\s"''`]*?[\\/])?docs[\\/]+features[\\/]+active[\\/]+[A-Za-z0-9][A-Za-z0-9._-]*'
+
+# An absolute file path with an extension. Only the absolute form is read from free
+# text, because a relative file path names a file present in every worktree.
+$script:FilePathPattern = '(?<![^\s"''`(])(?:[A-Za-z]:[\\/]|/)[^\s"''`]*[\\/][^\s"''`\\/]+\.[A-Za-z0-9]+'
+
+# A branch named by a --head or --branch option, or by a "branch:" label. Narrow on
+# purpose: a bare word is never read as a branch.
+$script:BranchPattern = '(?i)(?:(?<![\w-])--(?:head|branch)(?:=|\s+)|\bbranch:\s*)(?<name>[A-Za-z0-9][A-Za-z0-9._/-]*)'
+
+# A drive-rooted or slash-rooted normalised path.
+$script:AbsolutePathPattern = '^([A-Za-z]:(/|$)|/)'
+
+function New-WorktreeResolutionTargetResult {
+    <#
+    .SYNOPSIS
+        Build a target result object. The single constructor of that shape.
+    .DESCRIPTION
+        Enforces the field invariants: SessionRoot and Detail are always non-empty,
+        Candidates is always an array, WorktreeRoot is populated only for the two
+        resolved states, Signal and SignalValue are null for NoTarget, and
+        ReasonCode is the ambiguity code when Status is Ambiguous and the no-target
+        code when Status is NoTarget (issue #687); it is null for the two resolved
+        states.
+    .PARAMETER Status
+        One of SessionRoot, OtherWorktree, NoTarget, or Ambiguous.
+    .PARAMETER SessionRoot
+        The worktree root the invoking process runs in.
+    .PARAMETER WorktreeRoot
+        The resolved target root; required for the two resolved states.
+    .PARAMETER Signal
+        The signal kind that produced or failed to produce the target.
+    .PARAMETER SignalValue
+        The raw token the signal was read from.
+    .PARAMETER Candidate
+        The distinct candidate worktree roots considered.
+    .PARAMETER Detail
+        A prose clause safe to append to a gate's deny reason.
+    #>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '', Justification = 'Pure in-memory factory that changes no system state; the exported name is fixed by the issue #669 contract.')]
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('SessionRoot', 'OtherWorktree', 'NoTarget', 'Ambiguous')]
+        [string] $Status,
+        [Parameter(Mandatory = $true)]
+        [ValidatePattern('\S')]
+        [string] $SessionRoot,
+        [string] $WorktreeRoot,
+        [ValidateSet('', 'FeatureFolderPath', 'FilePath', 'Branch', 'SessionRoot')]
+        [string] $Signal,
+        [string] $SignalValue,
+        [AllowEmptyCollection()]
+        [string[]] $Candidate = @(),
+        [Parameter(Mandatory = $true)]
+        [ValidatePattern('\S')]
+        [string] $Detail
+    )
+
+    $isResolved = $Status -in @($script:StatusSessionRoot, $script:StatusOtherWorktree)
+    $root = ConvertTo-WorktreeResolutionNormalizedPath -Path $WorktreeRoot
+    if ($isResolved -and $null -eq $root) {
+        throw "A target result with Status '$Status' requires a WorktreeRoot."
+    }
+    $hasSignal = ($Status -ne $script:StatusNoTarget) -and -not [string]::IsNullOrEmpty($Signal)
+    $kept = if ($Status -eq $script:StatusNoTarget) { @() } else { $Candidate }
+    $candidates = [string[]] @($kept | Where-Object { -not [string]::IsNullOrWhiteSpace($_) })
+    return [pscustomobject]@{
+        Status       = $Status
+        WorktreeRoot = if ($isResolved) { $root } else { $null }
+        SessionRoot  = ConvertTo-WorktreeResolutionNormalizedPath -Path $SessionRoot
+        Signal       = if ($hasSignal) { $Signal } else { $null }
+        SignalValue  = if ($hasSignal) { $SignalValue } else { $null }
+        Candidates   = $candidates
+        ReasonCode   = switch ($Status) {
+            $script:StatusAmbiguous { Get-WorktreeResolutionAmbiguityReasonCode; break }
+            $script:StatusNoTarget { Get-WorktreeResolutionNoTargetReasonCode; break }
+            default { $null }
+        }
+        Detail       = $Detail
+    }
+}
+
+function Find-WorktreeResolutionFeatureFolderSignal {
+    <#
+    .SYNOPSIS
+        Return the first feature-folder token in a text, with any absolute prefix preserved, or $null.
+    .DESCRIPTION
+        The match does not start at the literal docs segment: a drive or worktree
+        prefix written before it stays part of the token, so the token can be
+        placed in exactly one worktree. The token ends at the feature-folder name.
+    .PARAMETER Text
+        The prompt or payload text to scan.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Text
+    )
+
+    $match = [regex]::Match([string] $Text, $script:FeatureFolderPattern)
+    if (-not $match.Success) {
+        return $null
+    }
+    return $match.Value.TrimEnd('.')
+}
+
+function Find-WorktreeResolutionBranchSignal {
+    <#
+    .SYNOPSIS
+        Return the first branch named by --head, --branch, or a "branch:" label, or $null.
+    .PARAMETER Text
+        The prompt or payload text to scan.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Text
+    )
+
+    $match = [regex]::Match([string] $Text, $script:BranchPattern)
+    if (-not $match.Success) {
+        return $null
+    }
+    return $match.Groups['name'].Value.TrimEnd('.', '/')
+}
+
+function Find-WorktreeResolutionFilePathSignal {
+    <#
+    .SYNOPSIS
+        Return the first absolute file path (with an extension) in a text, or $null.
+    .PARAMETER Text
+        The prompt or payload text to scan.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Text
+    )
+
+    $match = [regex]::Match([string] $Text, $script:FilePathPattern)
+    if (-not $match.Success) {
+        return $null
+    }
+    return $match.Value
+}
+
+function Get-WorktreeResolutionSignalCandidate {
+    # The distinct worktree roots one present signal resolves to. An absolute path
+    # is placed by the upward walk; a relative path is looked up in every worktree
+    # reachable from the session root; a branch is matched against each HEAD.
+    [OutputType([string[]])]
+    param([hashtable] $Signal, [string] $SessionRoot)
+
+    if ($Signal.Kind -eq $script:SignalBranch) {
+        $byBranch = Get-WorktreeResolutionWorktreeRoot -SessionRoot $SessionRoot -Branch $Signal.Value
+        return , [string[]] @($byBranch)
+    }
+    $normalized = ConvertTo-WorktreeResolutionNormalizedPath -Path $Signal.Value
+    if ($normalized -match $script:AbsolutePathPattern) {
+        $placed = ConvertTo-WorktreeResolutionRepoRelativePath -Path $normalized
+        if (-not $placed.IsNormalized) {
+            return , [string[]] @()
+        }
+        return , [string[]] @($placed.WorktreeRoot)
+    }
+    $byPath = Get-WorktreeResolutionWorktreeRoot -SessionRoot $SessionRoot -RepoRelativePath $normalized
+    return , [string[]] @($byPath)
+}
+
+function Resolve-WorktreeCallTarget {
+    <#
+    .SYNOPSIS
+        Derive the worktree a tool call pertains to, as one of four states.
+    .DESCRIPTION
+        Always returns a target result object. A call naming no signal is NoTarget.
+        A present signal that places in no worktree or in several, or two present
+        signals that place in different worktrees, is Ambiguous. Otherwise the one
+        agreed root is SessionRoot when it is the session root and OtherWorktree
+        when it is not. Signals are reported in the precedence FeatureFolderPath,
+        FilePath, Branch, which never suppresses a disagreement.
+    .PARAMETER Text
+        Optional prompt or payload text scanned for all three signal kinds.
+    .PARAMETER Branch
+        Optional explicit branch; takes the place of a branch read from Text.
+    .PARAMETER FilePath
+        Optional explicit file path, relative or absolute; takes the place of a
+        file path read from Text.
+    .PARAMETER SessionRoot
+        Optional. Defaults to the worktree containing the current location.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Text,
+        [string] $Branch,
+        [string] $FilePath,
+        [string] $SessionRoot
+    )
+
+    $session = ConvertTo-WorktreeResolutionNormalizedPath -Path $SessionRoot
+    if ($null -eq $session) {
+        $current = (Get-Location).ProviderPath
+        $session = Find-WorktreeResolutionRoot -Path $current
+        if ($null -eq $session) {
+            $session = ConvertTo-WorktreeResolutionNormalizedPath -Path $current
+        }
+    }
+
+    $filePathValue = if ([string]::IsNullOrWhiteSpace($FilePath)) { Find-WorktreeResolutionFilePathSignal -Text $Text } else { $FilePath.Trim() }
+    $branchValue = if ([string]::IsNullOrWhiteSpace($Branch)) { Find-WorktreeResolutionBranchSignal -Text $Text } else { $Branch.Trim() }
+    $present = @(
+        @{ Kind = $script:SignalFeatureFolderPath; Value = (Find-WorktreeResolutionFeatureFolderSignal -Text $Text) }
+        @{ Kind = $script:SignalFilePath; Value = $filePathValue }
+        @{ Kind = $script:SignalBranch; Value = $branchValue }
+    ) | Where-Object { -not [string]::IsNullOrWhiteSpace($_.Value) }
+    $present = @($present)
+    if ($present.Count -eq 0) {
+        return (New-WorktreeResolutionTargetResult -Status $script:StatusNoTarget -SessionRoot $session -Detail "the call names no feature folder, file path, or branch, so it has no target and the session root '$session' applies")
+    }
+
+    $agreed = [System.Collections.Generic.List[string]]::new()
+    foreach ($signal in $present) {
+        $label = $script:SignalLabel[$signal.Kind]
+        $candidates = Get-WorktreeResolutionSignalCandidate -Signal $signal -SessionRoot $session
+        if ($candidates.Count -ne 1) {
+            $detail = "$label '$($signal.Value)' matched $($candidates.Count) candidate worktrees; supply an absolute path inside exactly one worktree to disambiguate"
+            return (New-WorktreeResolutionTargetResult -Status $script:StatusAmbiguous -SessionRoot $session -Signal $signal.Kind -SignalValue $signal.Value -Candidate $candidates -Detail $detail)
+        }
+        if (-not ($agreed -contains $candidates[0])) {
+            $agreed.Add($candidates[0])
+        }
+    }
+
+    $reported = $present[0]
+    $reportedLabel = $script:SignalLabel[$reported.Kind]
+    if ($agreed.Count -gt 1) {
+        $detail = "the call's signals resolve to $($agreed.Count) different worktrees ($($agreed -join ', ')); precedence does not choose between disagreeing signals"
+        return (New-WorktreeResolutionTargetResult -Status $script:StatusAmbiguous -SessionRoot $session -Signal $reported.Kind -SignalValue $reported.Value -Candidate $agreed.ToArray() -Detail $detail)
+    }
+    $root = $agreed[0]
+    $status = if ($root -eq $session) { $script:StatusSessionRoot } else { $script:StatusOtherWorktree }
+    $detail = "$reportedLabel '$($reported.Value)' resolves to worktree '$root'"
+    return (New-WorktreeResolutionTargetResult -Status $status -SessionRoot $session -WorktreeRoot $root -Signal $reported.Kind -SignalValue $reported.Value -Candidate @($root) -Detail $detail)
+}
+
+function Join-WorktreeResolutionPath {
+    <#
+    .SYNOPSIS
+        Compose an absolute forward-slash path from a worktree root and a repo-relative path.
+    .PARAMETER WorktreeRoot
+        The absolute worktree root, in either separator style.
+    .PARAMETER RepoRelativePath
+        The path below the root, in either separator style.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $WorktreeRoot,
+        [Parameter(Mandatory = $true)]
+        [string] $RepoRelativePath
+    )
+
+    $root = ConvertTo-WorktreeResolutionNormalizedPath -Path $WorktreeRoot
+    if ($root -notmatch $script:AbsolutePathPattern) {
+        throw "WorktreeRoot must be an absolute path: '$WorktreeRoot'."
+    }
+    $relative = ConvertTo-WorktreeResolutionNormalizedPath -Path $RepoRelativePath
+    if ($null -eq $relative) {
+        return $root
+    }
+    $separator = if ($root.EndsWith('/')) { '' } else { '/' }
+    return $root + $separator + $relative.TrimStart('/')
+}
+
+Export-ModuleMember -Function `
+    New-WorktreeResolutionTargetResult, `
+    Find-WorktreeResolutionFeatureFolderSignal, `
+    Find-WorktreeResolutionBranchSignal, `
+    Find-WorktreeResolutionFilePathSignal, `
+    Resolve-WorktreeCallTarget, `
+    Join-WorktreeResolutionPath

package/resources/claude-customizations/.claude/rules/orchestrator-state.md

@@ -122,6 +122,30 @@ The rest of the completion gate is unchanged. An epic whose feature is not merge
 
 Enforcement is validator logic plus this prose, never an imported JSON Schema. The activation scope lives in `scripts/dev_tools/_epic_orchestrator_state_launch_binding.py`, and the TypeScript parity port at `extensions/drm-copilot/src/lib/validate/epic-orchestrator-state-launch-binding.ts` reproduces it with byte-identical error strings. No schema file is authored, imported, or read for it.
 
+## Standalone-Merge-Authorization Scope and Backward Compatibility
+
+These invariants apply only when a checkpoint contains a top-level `standalone_merge_authorizations` array. The key may appear in any of the three checkpoints the epic merge gate reads: `artifacts/orchestration/orchestrator-state.json`, `artifacts/orchestration/epic-orchestrator-state.json`, and `artifacts/orchestration/parallel-orchestrator-state.json`. A checkpoint with no such key (the existing checkpoint shape) is unaffected: it validates exactly as before and produces no new errors. The invariants are additive and key-gated. No JSON Schema file is authored, imported, or read for the block (see the Foreign Schema Warning above); the enforcing surface is the `PreToolUse` merge gate (issue #670).
+
+Each entry records one authorized standalone merge with the shape `{ pr_number, pr_url, issue_num, branch_name, authorized_by, authorized_at, session_id, basis, run_slug? }`. The gate consults the array only for a `gh pr merge --merge` command that names an explicit pull request number, and only after its per-feature, epic, and parallel allow conditions have all declined.
+
+Honest disclosure: the standalone-merge authorization record is a policy-level, auditable declaration and is
+not a cryptographic or security control.
+`authorized_by` is a declaration that the gate does not verify, because the runtime exposes no attested agent identity at Bash `PreToolUse` time. The record is not tamper-proof: any actor able to write `artifacts/orchestration/*.json` inside the authorizing session can write one. The `session_id` cross-check binds a record to the session that wrote it, so a stale record from a previous run or a record copied between runs authorizes nothing; it does not stop same-session forgery. This is a documented accepted trade, not an unexamined gap.
+
+## Invariants (standalone_merge_authorizations array)
+
+1. **PR-specific block.** The value of `standalone_merge_authorizations` must be a non-empty array whose every entry is an object with a `pr_number` that is a JSON integer greater than zero. Any other shape (a boolean or other blanket flag, a string, an object, an empty array, a non-object entry, or a `pr_number` that is absent, `null`, zero, negative, fractional, a string, or an array) is rejected with `STANDALONE_MERGE_AUTHORIZATION_NOT_PR_SPECIFIC`.
+2. **Binding by `pr_number`.** The gate selects the entry whose `pr_number` equals the pull request number extracted from the command. When records exist but none matches, the gate denies with `STANDALONE_MERGE_AUTHORIZATION_PR_MISMATCH`; when no checkpoint carries the key, it denies with `STANDALONE_MERGE_AUTHORIZATION_ABSENT`.
+3. **`pr_url`.** Non-empty, and it must end with `/pull/` followed by the entry's own `pr_number` and nothing else.
+4. **`issue_num`.** A JSON integer greater than zero.
+5. **`branch_name`.** A non-empty string. It is never compared against the live branch or the working directory.
+6. **`authorized_by`.** A non-empty string; presence only.
+7. **`authorized_at`.** A date-time string that parses with the invariant culture, assuming and adjusting to UTC. No clock is read.
+8. **`basis` and `run_slug`.** `basis` is at least 20 characters after trimming. `run_slug` is optional; when present it is a non-empty string.
+9. **`session_id`.** A non-empty string equal, by ordinal comparison, to the `session_id` of the live hook envelope. An envelope without a `session_id` fails closed.
+
+Field checks 3 through 9 run in the fixed order `pr_url`, `issue_num`, `branch_name`, `authorized_by`, `authorized_at`, `basis`, `run_slug`, `session_id`; the first failure wins and the gate denies with `STANDALONE_MERGE_AUTHORIZATION_MALFORMED` naming that field.
+
 ## Enforcement
 
 - `scripts/dev_tools/validate_orchestrator_state.py` appends one error per violated invariant when a `remediation_loop` is present, using the existing validator message style (literal, checkpoint-context prefixed). The validator returns a list of error strings and does not mutate its input.
@@ -130,3 +154,6 @@ Enforcement is validator logic plus this prose, never an imported JSON Schema. T
 - `scripts/dev_tools/validate_orchestrator_state.py` appends one error per violated `model_routing_receipts` invariant when a `model_routing_receipts` key is present, delegating to `scripts/dev_tools/_orchestrator_state_model_routing.py`, which recomputes the resolved model via `resolve_delegation_model`. The check does not import or read any schema file.
 - `scripts/dev_tools/validate_orchestrator_state.py` appends one error per violated `require_model_routing` invariant only when the caller passes `require_model_routing=True`, delegating to `scripts/dev_tools/_orchestrator_state_model_routing_gate.py`, which reuses the complexity and model-routing per-entry validators. When the flag is not passed the gate does not run, so existing calls are byte-identical.
 - The validator is consumed by the MCP tool `validate_orchestration_artifacts`; backward compatibility for existing step-based checkpoints is preserved.
+- The standalone-merge authorization invariants are enforced by the `PreToolUse` merge gate (`.claude/hooks/enforce-epic-merge-gate.ps1` with its dot-sourced helpers file, and `.codex/hooks/enforce-epic-merge-gate.ps1`) at merge time. The Python checkpoint validator
+  does not currently validate standalone_merge_authorizations
+  entries; adding that check is recorded as follow-up FU-3.

package/resources/claude-customizations/.claude/skills/cleanup-merged-worktrees/SKILL.md

@@ -178,6 +178,12 @@ The script emits pipe-delimited, `LC_ALL=C`-ordered records, one per line:
    defer to that skill for it rather than restating any value from it here. For `<N>`,
    use the GitHub issue number the run executes under when the run has one. When the run
    has none, `<N>` is an arbitrary run-scoped identifier chosen by the pr-author agent.
+   The delegation prompt MUST carry a `branch: <name>` label naming the consolidation branch,
+   and the canonical issue number line when the run has an issue number.
+   `enforce-model-routing-receipt.ps1` identifies the item from those two lines and denies a
+   gated delegation it cannot identify. A cleanup run with no issue number is therefore
+   identified by the branch label alone, which is why the label is required and the issue line
+   is not.
    It is not a pull-request number, and the only requirement on it is that the body-file
    path, the receipt's `number` field, and the body bytes all agree. This skill never
    authors or creates the PR itself.
@@ -519,6 +525,12 @@ and is prohibited by this skill, which is the term the residual rests on.
   only a distinct, individually confirmed manual action outside that automated path for
   `NOT_MERGED`/`HAS_UNIQUE_RESIDUALS` — never a change to the classification ladder
   itself, and never for `PROTECTED_CURRENT`.
+- Never delete the base branch `main` and never remove a worktree checked out on it.
+  `compute_protected` protects `main` by name in every checkout topology, so it
+  classifies `PROTECTED_CURRENT` even when no protected worktree has it checked out, and
+  `delete_candidate` refuses a deletion request for it with
+  `ACTION|delete|main|BLOCKED-PROTECTED-BASE` before any re-verification, worktree
+  removal, or branch deletion runs.
 - Never use commit-message text matching as a classification input, and never
   auto-resolve cherry-pick conflicts.
 - Never delete an origin branch, or run plain filesystem removal on an orphaned

package/resources/claude-customizations/.claude/skills/epic-orchestrate/SKILL.md

@@ -170,6 +170,13 @@ frontmatter default — `opus` for these workers — which suppresses a `fable`
 MUST NOT hard-code `model=opus` in a way that overrides the resolved routing model, mirroring
 step 5 of `## Model Selection` in `.claude/skills/orchestrate/SKILL.md`.
 
+Every such spawn of `Agent(pr-author)` also carries the canonical issue number line and a
+`branch: <name>` label naming the branch checked out in the worktree the pull request is opened
+from, per `## Issue Number Consistency` in `.claude/skills/orchestrate/SKILL.md`.
+`enforce-model-routing-receipt.ps1` identifies the item from those two lines and denies a gated
+delegation it cannot identify, so a spawn that omits both is refused rather than validated against
+whichever checkpoint occupies the calling session's root.
+
 `route` is never an input to model selection; `route` remains file-count driven and governs only
 agents, skills, and MCP tools. A skill whose frontmatter `context` field holds the value `fork`
 inherits the parent model and ignores a model override, so model selection applies to agent
@@ -281,7 +288,9 @@ checkpoint JSON remains the durable, machine-authoritative source.
 `epic_feature_folder`, `epic_manifest_path` (which points at
 `docs/features/epics/<epic-slug>/epic.md`), `epic_status_doc_path`, `integration_branch`,
 `completed_steps`, `next_step`, `last_updated`, `current_wave`, `waves[]`, `features[]`,
-`epic_merge_pr`, and the three receipt arrays (`delegation_receipts[]`, `skill_receipts[]`,
+`epic_merge_pr`, `epic_issue_num` (the epic-level issue `epic-planner` promoted),
+`model_routing_receipts[]` (the routing receipt for each delegation `epic-orchestrator` itself
+spawns), and the three receipt arrays (`delegation_receipts[]`, `skill_receipts[]`,
 `mcp_call_receipts[]`). The
 `merge_status` enum is: `not_started`, `worktree_created`, `pr_open`, `ci_green`,
 `merge_conflict`, `blocked_conflict_loop_limit`, `merged`, `worktree_removed`. The optional
@@ -298,6 +307,10 @@ Validate the checkpoint through the
 that same call at the completion gate. The validation is implemented in
 `scripts/dev_tools/validate_epic_orchestrator_state.py`.
 
+**Checkpoint hygiene (issue #673).** The coordinating session never holds a per-feature checkpoint at its own root. Before the first child delegation of a run it moves any `artifacts/orchestration/orchestrator-state.json` at its root to `artifacts/orchestration/handoff/orchestrator-state.issue-<issue-num>.<yyyy-MM-ddTHH-mm>.json`, and writes none there for the rest of the run, because each item's checkpoint lives in that item's worktree. A gated call the coordinator issues on an item's behalf is resolved by the item's issue number and branch, never by the coordinator root.
+
+**Integration-PR checkpoint shape (issue #663).** The integration-to-`main` pull request and its `Agent(pr-author)` delegation are gated against `artifacts/orchestration/epic-orchestrator-state.json`, and no per-feature checkpoint is written for them. Before `epic-orchestrator` opens that pull request, the epic checkpoint carries `route_id: "epic"`, `integration_branch`, `epic_issue_num`, and a `features[]` array in which every entry's `merge_status` is `merged` or `worktree_removed`. Before the `Agent(pr-author)` delegation, `epic-orchestrator` records the `pr-author` routing receipt in that file's `model_routing_receipts[]`. The pr-author gate, the epic base-branch check, the model-routing gate, and the preimplementation gate treat a call as epic scope when its branch signal (or, for a staging command or file edit, the worktree HEAD) equals `integration_branch`; the pull request base must then be `main`.
+
 ## Completion Requirements
 
 `epic-orchestrator` must not report completion until:

package/resources/claude-customizations/.claude/skills/epic-plan/SKILL.md

@@ -66,6 +66,10 @@ At manifest-authoring time child issues do not exist yet, so `issue_num` values
 placeholders and back-filled from each child's promotion receipt as preparation completes. The
 manifest is committed in final, resolved form before the kickoff artifact is written.
 
+## Epic-Level Issue Promotion
+
+Issue #663. Before the first preparation-mode child delegation, `epic-planner` promotes one epic-level GitHub issue for the epic itself. It authors a potential entry under `docs/features/potential/` describing the epic and promotes it through `mcp__drm-copilot__potential_to_issue` with `promotion_type: epic`; `gh issue create` is not used. It records the resulting number as `epic_issue_num` in the epic planning checkpoint (`artifacts/orchestration/epic-planner-state.json`) and in the kickoff prompt artifact, and `epic-orchestrator` copies it into the epic checkpoint `artifacts/orchestration/epic-orchestrator-state.json` at its first checkpoint write. The integration-to-`main` pull request uses `epic_issue_num` as its canonical issue number.
+
 ## Complexity Assessment
 
 Assess each child feature's complexity band (`C1`-`C4`) using the `model_policy` scale and

package/resources/claude-customizations/.claude/skills/orchestrate/SKILL.md

@@ -33,6 +33,7 @@ On every invocation, the main session must:
 1. Read `artifacts/orchestration/orchestrator-state.json` to check for existing state.
 2. If a valid checkpoint exists with a matching objective, resume from the recorded `next_step`.
 3. If no checkpoint exists or the objective is new, begin the orchestration lifecycle from the start.
+4. **Checkpoint hygiene (issue #673).** When the checkpoint at `artifacts/orchestration/orchestrator-state.json` records an `issue-num` other than the item this invocation is about, move it to `artifacts/orchestration/handoff/orchestrator-state.issue-<issue-num>.<yyyy-MM-ddTHH-mm>.json` before writing a new checkpoint, rather than overwriting it or leaving it in place. Apply the same move when this session hands an item whose checkpoint it holds to another session or worktree. A checkpoint left at a session root is read by gates that resolve against that root, so a foreign one there is state a gate can answer from.
 
 ## Prepared-State Portable Handoff Intake
 
@@ -255,10 +256,12 @@ A bounded loop consisting of five steps. The loop variable `remediation_pass` st
 
 The canonical issue number is derived once from the active feature folder name: extract the trailing integer from the folder base name (e.g., `2026-04-26-push-down-claude-customizations-162` yields `162`). Record as `issue_num` in the checkpoint.
 
-Every delegation prompt to `atomic-planner`, `atomic-executor`, and `feature-review` must include the line:
+Every delegation prompt to a receipt-gated subagent type — `atomic-planner`, `atomic-executor`, `feature-review`, `task-researcher`, `prd-feature`, and `pr-author` — must include the line:
 
 > `Canonical issue number for this feature is <issue_num>. All artifact content, file paths, and cross-references must use this number.`
 
+Each such prompt also carries a `branch: <name>` label naming the branch checked out in the item's worktree, written as the first `branch:` occurrence in the prompt. Before promotion assigns an issue number, the branch label alone is required. Two gates, `enforce-model-routing-receipt.ps1` and `enforce-prd-feature-before-planner.ps1`, identify the item from these two lines: they deny a gated delegation they cannot identify rather than checking it against whichever checkpoint occupies the calling session's root, and they never use a feature-folder path to choose the worktree, because a merged feature folder exists in every checkout branched from main.
+
 If a subagent artifact references a different issue number, the orchestrator rejects it, requests correction, and records the discrepancy under `artifact_errors` in the checkpoint.
 
 ## Step S9 — CI Green Gate

package/resources/claude-customizations/.claude/skills/parallel-orchestrate/SKILL.md

@@ -234,6 +234,8 @@ There is no final integration pull request and no fan-in path: the epic surface'
 integration-branch lifecycle has no counterpart on this surface, and its absence is structural
 rather than an omission.
 
+**Checkpoint hygiene (issue #673).** The coordinating session never holds a per-feature checkpoint at its own root. Before the first item delegation of a run it moves any `artifacts/orchestration/orchestrator-state.json` at its root to `artifacts/orchestration/handoff/orchestrator-state.issue-<issue-num>.<yyyy-MM-ddTHH-mm>.json`, and writes none there for the rest of the run, because each item's checkpoint lives in that item's worktree. A gated call the coordinator issues on an item's behalf is resolved by the item's issue number and branch, never by the coordinator root.
+
 ## Parallel-Mode Kickoff Parameter
 
 When `parallel-orchestrator` delegates an item to `Agent(orchestrator)`, the delegation prompt
@@ -326,12 +328,43 @@ Procedure, per item:
 
 **Merge-gate authorization.** `.claude/hooks/enforce-epic-merge-gate.ps1` is a project-wide
 `PreToolUse` Bash-matcher hook that denies any `gh pr merge --merge` unless a checkpoint satisfies
-one of its allow conditions; its block reason is `EPIC_MERGE_GATE_BLOCKED`. The gate now authorizes
-a parallel per-item merge when the parallel-orchestrator checkpoint has `route_id == "parallel"`,
-the target item's `merge_status == "ci_green"`, and, when a PR number is named, it matches the
-item's `pr_number`. Step 3 above is therefore permitted for a legitimate parallel merge; a missing,
-unreadable, or invalid parallel checkpoint, a target item whose `merge_status` is not `ci_green`, or
-a PR number that matches no item still fails closed with `EPIC_MERGE_GATE_BLOCKED`.
+one of its allow conditions; its block reason is `EPIC_MERGE_GATE_BLOCKED`. The gate has
+four allow conditions
+which it evaluates in this order: a per-feature checkpoint with `epic_mode == true` and
+`step9_status == "passed"`; an epic checkpoint whose `epic_merge_pr.ci_gate.conclusion` is
+`success` with a matching `pr_number`; the parallel condition described next; and a standalone
+merge authorization record, described after it. The parallel condition authorizes a per-item merge
+when the parallel-orchestrator checkpoint has `route_id == "parallel"`, the target item's
+`merge_status == "ci_green"`, and, when a PR number is named, it matches the item's `pr_number`.
+Step 3 above is therefore permitted for a legitimate parallel merge; a missing, unreadable, or
+invalid parallel checkpoint, a target item whose `merge_status` is not `ci_green`, or a PR number
+that matches no item still fails closed with `EPIC_MERGE_GATE_BLOCKED`.
+
+The standalone condition (issue #670) is the only route for merging a pull request that is not a
+parallel item, such as a standalone fix that unblocks the run. It is evaluated last and never
+overrides the other three. Writer procedure for the coordinating session:
+
+1. Write the record into a top-level `standalone_merge_authorizations` array in the
+   parallel-orchestrator checkpoint (`artifacts/orchestration/parallel-orchestrator-state.json`);
+   the gate also reads the key from the per-feature and epic checkpoints.
+2. Write one entry per authorized pull request, with these fields: `pr_number` (JSON integer),
+   `pr_url` (ending in `/pull/<pr_number>`), `issue_num` (JSON integer), `branch_name`,
+   `authorized_by`, `authorized_at` (ISO 8601 date-time), `session_id`, `basis` (at least 20
+   characters), and optionally `run_slug`.
+3. Set `session_id` to the session id of the coordinating session that will run the merge
+   command. The gate compares it with the live hook envelope and denies on any difference, so a
+   record written by another session or a previous run authorizes nothing.
+4. Name the pull request explicitly in the merge command (`gh pr merge <PR> --merge`); a bare
+   command never satisfies the standalone condition.
+
+A blanket flag is actively rejected: a `standalone_merge_authorizations` value that names no
+specific pull request (for example `true`) denies with
+`STANDALONE_MERGE_AUTHORIZATION_NOT_PR_SPECIFIC`. Other denials carry
+`STANDALONE_MERGE_AUTHORIZATION_ABSENT`, `STANDALONE_MERGE_AUTHORIZATION_PR_MISMATCH`, or
+`STANDALONE_MERGE_AUTHORIZATION_MALFORMED` (naming the failing field) after the
+`EPIC_MERGE_GATE_BLOCKED` token. The record is a policy-level, auditable declaration, not a
+security control; see the Standalone-Merge-Authorization section of
+`.claude/rules/orchestrator-state.md` for the full field rules and the disclosure.
 
 Branch protection on `main` affects only the pacing of step 3, not its ownership: if `main`
 requires branches to be up to date, an automated `gh pr update-branch` plus re-green cycle is

package/resources/claude-customizations/.claude/skills/pr-author/SKILL.md

@@ -76,3 +76,18 @@ writes and the `gh pr create` / `gh pr edit --body-file` handoff.
 - Do not treat PR numbers as issues.
 - Auto-close bullets must use exactly `- Closes #NNN` format, sourced only from "Issues to autoclose" or "Author-asserted autoclose issues."
 - If GitHub validation is unavailable/unverified, do not emit `Closes`; use the fallback `None` bullet.
+
+## Required `--head` on `gh pr create` (issue #687)
+
+Every `gh pr create` command this agent issues MUST carry an explicit
+`--head <branch>` naming the branch the pull request is opened from.
+
+This is what makes the call's target derivable. `enforce-pr-author-skill.ps1` resolves the
+worktree the call pertains to from the command text, and validates the orchestrator checkpoint
+belonging to that worktree. Without `--head`, `gh pr create` infers its head branch from the
+current checkout and the command carries no signal at all, so the gate denies with
+`TARGET_WORKTREE_NOT_DERIVABLE` rather than validating against whichever checkpoint occupies the
+session root, which in a parallel or epic topology belongs to a different item.
+
+Pass `--head` even when the branch is the current one: the gate resolves it to the session root
+and behaves exactly as before, and the command stays correct if it is ever replayed elsewhere.