@danmoisan/drm-copilot-mcp 1.1.17 → 1.1.18

package/resources/claude-customizations/.claude/lib/orchestrator-state/OrchestratorStateRemediationAccounting.psm1

@@ -0,0 +1,337 @@
+<#
+.SYNOPSIS
+    Portable remediation-loop review-outcome and accounting checks (R5-R11).
+
+.DESCRIPTION
+    Destination-runtime PowerShell port of the issue #484 invariants the
+    authoritative Python validator applies to a checkpoint's remediation_loop:
+    the review-outcome rules R8a, R8b, R9a-R9d, and R10, and the accounting
+    rules R5, R6, R7a, R7b, and R11, matching the error-string templates in
+    `scripts/dev_tools/_orchestrator_state_remediation_loop.py` and the rules
+    document `.claude/rules/orchestrator-state.md`.
+
+    The receipts module calls the exported entry point after its unchanged
+    per-cycle checks, passing the cycle list or $null when cycles is absent or
+    not a list, so the new checks also run for a loop with review outcomes and
+    no cycles.
+
+    Every comparison against the verdict and class vocabulary is case-sensitive
+    (-ccontains, -cnotcontains, -ceq). An integer is a JSON number deserialized
+    as [int] or [long]; a boolean is never an integer. Values interpolated into
+    a message ({v}) render through ConvertTo-PythonDisplayText so the text
+    matches Python's str().
+
+    Every function is pure: it reads no file, starts no process, and never
+    mutates its input. Each check returns a string array, empty when valid.
+    CONVENTION: this module fails fast at module scope and imports its siblings with -ErrorAction Stop.
+#>
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# Import the shared checkpoint-value primitives, resolved relative to this
+# module's directory so the import travels with the pushed-down pack.
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'OrchestratorStateCheckpointValue.psm1') -Force -ErrorAction Stop
+
+# Loop and cycle keys read by the accounting rules.
+$script:REVIEW_OUTCOMES_KEY = 'review_outcomes'
+$script:COMPLETED_ATTEMPTS_KEY = 'completed_attempts'
+$script:CANDIDATE_APPLIED_KEY = 'candidate_applied'
+$script:OPENED_BY_REVIEW_KEY = 'opened_by_review'
+$script:COMPLETED_EXECUTION_STATUS = 'complete'
+
+# Review verdicts and remediability classes in spec table order, and the two
+# derived class partitions. Pinned to the Python constants of the same names.
+$script:REVIEW_VERDICTS = @('PASS', 'REMEDIATION_REQUIRED', 'HALT_NON_REMEDIABLE', 'AWAITING_CI')
+$script:REMEDIABILITY_CLASSES = @('autonomous', 'external_dependency', 'policy_hold', 'awaiting_ci', 'human_decision_required')
+$script:NON_REMEDIABLE_CLASSES = @('external_dependency', 'policy_hold', 'awaiting_ci', 'human_decision_required')
+$script:HALT_CLASSES = @('external_dependency', 'policy_hold', 'human_decision_required')
+$script:REMEDIABLE_CLASS = 'autonomous'
+$script:REMEDIATION_REQUIRED_VERDICT = 'REMEDIATION_REQUIRED'
+
+
+function Test-RemediationStrictInteger {
+    <#
+    .SYNOPSIS
+        Report whether a deserialized JSON value is an integer and not a boolean.
+    .DESCRIPTION
+        Private predicate mirroring Python's isinstance(value, int) and not
+        isinstance(value, bool). ConvertFrom-Json materializes a JSON integer as
+        [int] or [long] and a JSON boolean as [bool].
+    .PARAMETER Value
+        The deserialized JSON value to classify. May be $null.
+    .OUTPUTS
+        System.Boolean - $true only for an [int] or [long] value.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [object] $Value
+    )
+
+    return (($Value -is [int]) -or ($Value -is [long])) -and -not ($Value -is [bool])
+}
+
+function Get-RemediationReviewVerdict {
+    <#
+    .SYNOPSIS
+        Derive a review verdict from its findings' remediability classes.
+    .DESCRIPTION
+        Private helper mirroring derive_review_verdict. Evaluates, in order: no
+        classes yields PASS; any autonomous class yields REMEDIATION_REQUIRED;
+        any member of HALT_CLASSES yields HALT_NON_REMEDIABLE; otherwise
+        AWAITING_CI. A member outside REMEDIABILITY_CLASSES (compared
+        case-sensitively) raises a terminating error whose message begins
+        'invalid remediability: '.
+    .PARAMETER Remediability
+        The remediability class of every blocking finding; may be empty and may
+        repeat a class.
+    .OUTPUTS
+        System.String - one of the four review verdicts.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [string[]] $Remediability
+    )
+
+    foreach ($value in $Remediability) {
+        if ($script:REMEDIABILITY_CLASSES -cnotcontains $value) {
+            throw "invalid remediability: $value"
+        }
+    }
+
+    if ($Remediability.Count -eq 0) { return 'PASS' }
+    if ($Remediability -ccontains $script:REMEDIABLE_CLASS) { return 'REMEDIATION_REQUIRED' }
+    foreach ($value in $Remediability) {
+        if ($script:HALT_CLASSES -ccontains $value) { return 'HALT_NON_REMEDIABLE' }
+    }
+    return 'AWAITING_CI'
+}
+
+function Get-RemediationReviewOutcomeError {
+    <#
+    .SYNOPSIS
+        Return one review outcome's errors (R9a-R9d, then R10).
+    .DESCRIPTION
+        Private helper mirroring _validate_review_outcome. Checks the verdict
+        (string check before membership), the findings list, and each finding's
+        remediability (string check before membership); R10 runs only when none
+        of those checks produced an error for the outcome.
+    .PARAMETER Index
+        The outcome's zero-based position, used for error context.
+    .PARAMETER Outcome
+        The deserialized outcome object.
+    .OUTPUTS
+        System.String[] - zero or more error strings.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [int] $Index,
+
+        [Parameter(Mandatory = $true)]
+        [psobject] $Outcome
+    )
+
+    $errors = [System.Collections.Generic.List[string]]::new()
+    $prefix = "Checkpoint remediation review outcome #$Index"
+
+    $verdict = (Get-CheckpointObjectMember -Owner $Outcome -Name 'verdict').Value
+    if (-not ($verdict -is [string]) -or ($script:REVIEW_VERDICTS -cnotcontains [string]$verdict)) {
+        $rendered = ConvertTo-PythonDisplayText -Value $verdict
+        $errors.Add("$prefix verdict must be one of PASS, REMEDIATION_REQUIRED, HALT_NON_REMEDIABLE, AWAITING_CI; got: $rendered")
+    }
+
+    $classes = [System.Collections.Generic.List[string]]::new()
+    $findings = (Get-CheckpointObjectMember -Owner $Outcome -Name 'findings').Value
+    if (-not (Test-CheckpointListValue -Value $findings)) {
+        $errors.Add("$prefix findings must be a list.")
+    } else {
+        $findingIndex = 0
+        foreach ($finding in @($findings)) {
+            if (-not (Test-CheckpointObjectValue -Value $finding)) {
+                $errors.Add("$prefix finding #$findingIndex must be an object.")
+            } else {
+                $remediability = (Get-CheckpointObjectMember -Owner $finding -Name 'remediability').Value
+                if (-not ($remediability -is [string]) -or ($script:REMEDIABILITY_CLASSES -cnotcontains [string]$remediability)) {
+                    $rendered = ConvertTo-PythonDisplayText -Value $remediability
+                    $errors.Add("$prefix finding #$findingIndex remediability must be one of autonomous, external_dependency, policy_hold, awaiting_ci, human_decision_required; got: $rendered")
+                } else {
+                    $classes.Add([string]$remediability)
+                }
+            }
+            $findingIndex++
+        }
+    }
+
+    # R10 compares only a well-formed outcome; any shape error above suppresses it.
+    if ($errors.Count -eq 0) {
+        $expected = Get-RemediationReviewVerdict -Remediability $classes.ToArray()
+        if (-not ([string]$verdict -ceq $expected)) {
+            $errors.Add("$prefix verdict $verdict does not match its findings (expected $expected).")
+        }
+    }
+
+    return $errors.ToArray()
+}
+
+function Get-RemediationReviewOutcomeListError {
+    <#
+    .SYNOPSIS
+        Return the review-outcome errors (R8a, R8b, then each outcome).
+    .DESCRIPTION
+        Private helper mirroring _validate_review_outcomes. An absent
+        review_outcomes key yields no errors; a present non-list value yields R8a
+        alone; otherwise each non-object outcome yields R8b and is skipped.
+    .PARAMETER RemediationLoop
+        The deserialized remediation_loop object.
+    .OUTPUTS
+        System.String[] - zero or more error strings.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [psobject] $RemediationLoop
+    )
+
+    $errors = [System.Collections.Generic.List[string]]::new()
+    $member = Get-CheckpointObjectMember -Owner $RemediationLoop -Name $script:REVIEW_OUTCOMES_KEY
+    if (-not $member.Present) { return $errors.ToArray() }
+    if (-not (Test-CheckpointListValue -Value $member.Value)) {
+        $errors.Add('Checkpoint remediation_loop review_outcomes must be a list.')
+        return $errors.ToArray()
+    }
+
+    $index = 0
+    foreach ($outcome in @($member.Value)) {
+        if (-not (Test-CheckpointObjectValue -Value $outcome)) {
+            $errors.Add("Checkpoint remediation review outcome #$index must be an object.")
+        } else {
+            $errors.AddRange([string[]]@(Get-RemediationReviewOutcomeError -Index $index -Outcome $outcome))
+        }
+        $index++
+    }
+
+    return $errors.ToArray()
+}
+
+function Test-RemediationOpenedByReview {
+    <#
+    .SYNOPSIS
+        Report whether an index names a REMEDIATION_REQUIRED outcome object.
+    .DESCRIPTION
+        Private predicate for R11: the value must be an integer (not a boolean)
+        from 0 to one less than the outcome count of a list review_outcomes, and
+        the indexed entry must be an object whose verdict is exactly
+        REMEDIATION_REQUIRED. A negative index is out of range.
+    .PARAMETER OpenedByReview
+        The raw opened_by_review value. May be $null.
+    .PARAMETER Outcomes
+        The raw review_outcomes value. May be $null.
+    .OUTPUTS
+        System.Boolean - $true only when the reference is valid.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [object] $OpenedByReview,
+
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [object] $Outcomes
+    )
+
+    if (-not (Test-RemediationStrictInteger -Value $OpenedByReview)) { return $false }
+    if (-not (Test-CheckpointListValue -Value $Outcomes)) { return $false }
+    $outcomeList = @($Outcomes)
+    if ($OpenedByReview -lt 0 -or $OpenedByReview -ge $outcomeList.Count) { return $false }
+    $target = $outcomeList[[int]$OpenedByReview]
+    if (-not (Test-CheckpointObjectValue -Value $target)) { return $false }
+    $verdict = (Get-CheckpointObjectMember -Owner $target -Name 'verdict').Value
+    return ($verdict -is [string]) -and ([string]$verdict -ceq $script:REMEDIATION_REQUIRED_VERDICT)
+}
+
+function Get-OrchestratorStateRemediationAccountingError {
+    <#
+    .SYNOPSIS
+        Return the remediation_loop review-outcome and accounting errors (R5-R11).
+    .DESCRIPTION
+        Public entry mirroring the issue #484 tail of _validate_remediation_loop.
+        Returns, in order: the review-outcome errors (R8a; otherwise per outcome
+        R8b, R9a, R9b, R9c or R9d per finding, then R10); then, for each object
+        cycle in order, R5, R6, and R11; then R7a, otherwise R7b. With none of the
+        new keys present it returns nothing.
+    .PARAMETER RemediationLoop
+        The deserialized remediation_loop object.
+    .PARAMETER Cycle
+        The loop's cycles list, or $null when cycles is absent or not a list.
+    .OUTPUTS
+        System.String[] - zero or more error strings.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [psobject] $RemediationLoop,
+
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [AllowEmptyCollection()]
+        [object] $Cycle
+    )
+
+    $errors = [System.Collections.Generic.List[string]]::new()
+    $errors.AddRange([string[]]@(Get-RemediationReviewOutcomeListError -RemediationLoop $RemediationLoop))
+
+    $outcomes = (Get-CheckpointObjectMember -Owner $RemediationLoop -Name $script:REVIEW_OUTCOMES_KEY).Value
+    $appliedCount = 0
+    $cycleItems = @()
+    if ($null -ne $Cycle) { $cycleItems = @($Cycle) }
+    $index = 0
+    foreach ($item in $cycleItems) {
+        if (Test-CheckpointObjectValue -Value $item) {
+            $prefix = "Checkpoint remediation cycle #$index"
+            $applied = Get-CheckpointObjectMember -Owner $item -Name $script:CANDIDATE_APPLIED_KEY
+            if ($applied.Present) {
+                if (-not ($applied.Value -is [bool])) {
+                    $errors.Add("$prefix candidate_applied must be a boolean.")
+                } elseif ($applied.Value) {
+                    $appliedCount++
+                    $executionStatus = (Get-CheckpointObjectMember -Owner $item -Name 'execution_status').Value
+                    if (-not ($executionStatus -is [string]) -or -not ([string]$executionStatus -ceq $script:COMPLETED_EXECUTION_STATUS)) {
+                        $errors.Add("$prefix candidate_applied is true but execution_status is not 'complete'.")
+                    }
+                }
+            }
+            $opened = Get-CheckpointObjectMember -Owner $item -Name $script:OPENED_BY_REVIEW_KEY
+            if ($opened.Present -and -not (Test-RemediationOpenedByReview -OpenedByReview $opened.Value -Outcomes $outcomes)) {
+                $errors.Add("$prefix opened_by_review must reference a review outcome whose verdict is REMEDIATION_REQUIRED.")
+            }
+        }
+        $index++
+    }
+
+    $attempts = Get-CheckpointObjectMember -Owner $RemediationLoop -Name $script:COMPLETED_ATTEMPTS_KEY
+    if ($attempts.Present) {
+        if (-not (Test-RemediationStrictInteger -Value $attempts.Value) -or $attempts.Value -lt 0) {
+            $errors.Add('Checkpoint remediation_loop completed_attempts must be a non-negative integer.')
+        } elseif ($attempts.Value -ne $appliedCount) {
+            $errors.Add("Checkpoint remediation_loop completed_attempts is $($attempts.Value) but $appliedCount cycles have candidate_applied true.")
+        }
+    }
+
+    return $errors.ToArray()
+}
+
+# Only the entry point is exported; the verdict helper and the per-outcome and
+# per-reference checks stay private to this module.
+Export-ModuleMember -Function Get-OrchestratorStateRemediationAccountingError

package/resources/claude-customizations/.claude/lib/orchestrator-state/OrchestratorStateRoutingContract.psm1

@@ -5,7 +5,8 @@
 .DESCRIPTION
     Destination-runtime PowerShell port of `validate_routing_contract` in
     `scripts/dev_tools/_orchestrator_state_routing.py`, covering parity-inventory
-    rows C6.1 through C6.14:
+    rows C6.1 through C6.15. The C6.15 adoption waiver affects only receipt
+    presence (C6.9); the declared-list equality checks are unchanged:
 
       C6.1   routing matrix carries no routes object          (returns)
       C6.2   no route selected                                (returns)
@@ -21,6 +22,7 @@
       C6.12  lifecycle_operations must be a list when present
       C6.13  per non-object lifecycle operation
       C6.14  per lifecycle operation that did not use the MCP surface
+      C6.15  issue_adoption field and waiver rules (OrchestratorStateIssueAdoption.psm1)
 
     The routing matrix is read from `OrchestratorStateRoutingMatrix.psm1`, which
     implements deviation PD-1: the constants are pinned and no disk read occurs at
@@ -56,6 +58,7 @@ $ErrorActionPreference = 'Stop'
 # pushed-down pack regardless of the working directory.
 Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'OrchestratorStateCheckpointValue.psm1') -Force -ErrorAction Stop
 Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'OrchestratorStateRoutingMatrix.psm1') -Force -ErrorAction Stop
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'OrchestratorStateIssueAdoption.psm1') -Force -ErrorAction Stop
 
 # The promotion-entry MCP tools and the promotion type that triggers substitution.
 $script:FEATURE_PROMOTION_ENTRY_TOOL = 'new_potential_entry'
@@ -410,11 +413,16 @@ function Get-OrchestratorStateRoutingContractError {
     }
 
     $actualTools = @(Get-CheckpointAcknowledgedName -State $State -ArrayKey 'mcp_call_receipts' -NameKey 'tool' -FlagKey 'ok')
+    # C6.15: a valid issue_adoption record waives the receipt requirement for the
+    # tools it lists; any adoption error waives nothing.
+    $adoption = Get-OrchestratorStateIssueAdoptionResult -State $State -RouteId $routeId -RequiredMcpTool ([string[]]$requiredMcpTools) -SuccessfulTool ([string[]]$actualTools)
     foreach ($tool in $requiredMcpTools) {
+        if (@($adoption.WaivedTools) -ccontains $tool) { continue }
         if ($actualTools -cnotcontains $tool) {
             $errors.Add("Checkpoint missing successful MCP receipt: $tool.")
         }
     }
+    $errors.AddRange([string[]]@($adoption.Errors))
 
     # C6.10 to C6.14: the two empty-list fields and the lifecycle operations.
     foreach ($key in $script:COMPLETION_EMPTY_LIST_KEYS) {

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

@@ -24,7 +24,7 @@ description: Checkpoint invariants for the orchestration state artifact and the
 
 # Orchestrator-State Remediation-Cycle and Human-Interaction Invariants
 
-This rule governs remediation-cycle records and the optional `human_interaction` block in the orchestrator-state checkpoint at `artifacts/orchestration/orchestrator-state.json`. It documents three invariants that must hold for each remediation cycle, plus three invariants for the `human_interaction` block, so that resume and review workflows do not depend on a structurally invalid checkpoint.
+This rule governs remediation-cycle records and the optional `human_interaction` block in the orchestrator-state checkpoint at `artifacts/orchestration/orchestrator-state.json`. It documents the invariants that must hold for each remediation cycle and for the remediation-loop review outcomes and attempt count, plus three invariants for the `human_interaction` block, so that resume and review workflows do not depend on a structurally invalid checkpoint.
 
 ## Foreign Schema Warning (do not copy verbatim)
 
@@ -34,7 +34,7 @@ This prohibition is specific to the disqualified foreign schema identified by th
 
 ## Scope and Backward Compatibility
 
-These invariants apply only when the checkpoint contains a top-level `remediation_loop` with a `cycles` array. A checkpoint with no `remediation_loop` (the existing step-based checkpoint shape) is unaffected: it validates exactly as before and produces no new errors. The invariants are additive.
+These invariants apply only when the checkpoint contains a top-level `remediation_loop`; the per-cycle invariants apply when it has a `cycles` array, and the review-outcome and attempt-count invariants apply when their keys are present. A checkpoint with no `remediation_loop` (the existing step-based checkpoint shape) is unaffected: it validates exactly as before and produces no new errors. The invariants are additive.
 
 ## Invariants (per remediation cycle)
 
@@ -44,6 +44,45 @@ These invariants apply only when the checkpoint contains a top-level `remediatio
 
 3. **Exit gate requires zero blocking findings.** When a cycle's `exit_condition_met == true`, its `blocking_count` must be `0`. A non-zero `blocking_count` with `exit_condition_met == true` is a malformed cycle (the exit gate was marked satisfied while blocking findings remained).
 
+4. **`candidate_applied` is a boolean (R5).** When a cycle object carries `candidate_applied`, its value must be a JSON boolean, and any other value is a malformed cycle.
+
+5. **A completed attempt requires completed execution (R6).** A cycle whose `candidate_applied == true` must have `execution_status == "complete"`, and `candidate_applied == true` with any other execution status is a malformed cycle.
+
+6. **`opened_by_review` references a remediation review (R11).** When a cycle object carries `opened_by_review`, its value must be a non-negative integer (not a boolean) that indexes an object entry of the `remediation_loop.review_outcomes` list whose `verdict` is `REMEDIATION_REQUIRED`, and a value that is not such an integer, is out of range, or references an outcome with any other verdict is a malformed cycle.
+
+7. **`completed_attempts` counts completed attempts (R7).** When `remediation_loop.completed_attempts` is present, it must be a non-negative integer (not a boolean) equal to the number of object cycles whose `candidate_applied` is `true` (zero when `cycles` is absent or not a list), and any other value is a malformed loop.
+
+## Invariants (remediation_loop.review_outcomes)
+
+These invariants apply only when `remediation_loop` contains a `review_outcomes` key. The orchestrator appends one entry per review, including a `PASS` review, in the shape `{"verdict": <verdict>, "findings": [{"remediability": <class>}, ...]}`, where `findings` lists the review's blocking findings only. A halt or wait verdict records no remediation cycle.
+
+Review verdicts (exact, case-sensitive):
+
+| Verdict | Condition over the classes of the review's blocking findings |
+|---|---|
+| `PASS` | No blocking findings. |
+| `REMEDIATION_REQUIRED` | At least one `autonomous` finding. |
+| `HALT_NON_REMEDIABLE` | No `autonomous` finding, and at least one `external_dependency`, `policy_hold`, or `human_decision_required` finding. |
+| `AWAITING_CI` | At least one finding, and every finding is `awaiting_ci`. |
+
+Remediability classes (exact, case-sensitive) and the `blocked_reason` member (#523) that a halt or wait records for each class:
+
+| Class | Meaning | `blocked_reason` member |
+|---|---|---|
+| `autonomous` | Repository remediation can resolve the finding without a human decision. | none (remediation loop) |
+| `external_dependency` | A system, service, runtime, or published artifact outside the repository is unavailable or mismatched. | `external_dependency` |
+| `policy_hold` | Proceeding requires a policy decision, exception, or authorization that the orchestrator may not grant. | `policy_hold` |
+| `awaiting_ci` | The finding resolves when a CI result that has not completed becomes available. | `awaiting_ci` |
+| `human_decision_required` | A human must choose between alternatives or approve a direction. | `human_decision_required` |
+
+Derivation order. The verdict is a pure function of the findings' classes, evaluated in this order: no findings yields `PASS`; any `autonomous` finding yields `REMEDIATION_REQUIRED`; any `external_dependency`, `policy_hold`, or `human_decision_required` finding yields `HALT_NON_REMEDIABLE`; otherwise the verdict is `AWAITING_CI`.
+
+1. **`review_outcomes` is a list of objects (R8).** `review_outcomes` must be a list, and each entry must be an object. A non-list value or a non-object entry is malformed.
+
+2. **Verdict and class membership (R9).** Each outcome's `verdict` must be a string among the four verdicts, its `findings` must be a list (a missing key is not a list), and each finding must be an object whose `remediability` is a string among the five classes. Comparisons are case-sensitive, so a case variant such as `Pass` or `Autonomous` is malformed.
+
+3. **Verdict matches its findings (R10).** When an outcome passes the membership checks, its `verdict` must equal the verdict that the derivation order yields for its findings' classes. A mismatch is a malformed outcome.
+
 ## Human-Interaction Scope and Backward Compatibility
 
 These invariants apply only when the checkpoint contains a top-level `human_interaction` block. A checkpoint with no `human_interaction` key (the existing checkpoint shape) is unaffected: it validates exactly as before and produces no new errors. The invariants are additive and support the autonomous-execution mandate documented in `.claude/skills/orchestrate/SKILL.md`.
@@ -56,6 +95,41 @@ These invariants apply only when the checkpoint contains a top-level `human_inte
 
 3. **Exception requires `runbook_path`.** A requirement whose `response == "exception"` must carry a non-empty `runbook_path` string. A missing, non-string, or empty/whitespace-only `runbook_path` on an `exception` requirement is a malformed requirement.
 
+## Blocked-Reason Vocabulary
+
+The checkpoint key `blocked_reason` accepts exactly the twelve members below. The authoritative definition is `scripts/dev_tools/_orchestrator_state_blocked_reason.py`; the TypeScript module `extensions/drm-copilot/src/lib/validate/orchestrator-state-blocked-reason.ts` and the grouped arrays in `.claude/lib/orchestrator-state/OrchestratorState.psm1` mirror it.
+
+| Member | Partition | Definition |
+|---|---|---|
+| `none` | not blocked | The run is not blocked. JSON `null` is equivalent for classification. |
+| `spawn_agent_unavailable` | mechanical | Existing member; meaning unchanged. |
+| `delegation_launch_failed` | mechanical | Existing member; meaning unchanged. |
+| `delegate_no_receipt` | mechanical | Existing member; meaning unchanged. |
+| `delegate_contract_incomplete` | mechanical | Existing member; meaning unchanged. |
+| `validator_failed` | mechanical | Existing member; meaning unchanged. |
+| `user_requested_stop` | mechanical | Existing member; meaning unchanged. |
+| `premise_falsified` | non-mechanical | Every delegation and validator succeeded, but evidence gathered during execution falsified the premise on which the plan was built, so continuing would implement an invalid plan. |
+| `external_dependency` | non-mechanical | The run cannot proceed because a system, service, runtime, or artifact outside the repository's control is unavailable or mismatched, and no in-repository remediation can resolve it. |
+| `policy_hold` | non-mechanical | The run is stopped because proceeding requires a policy decision, exception, or authorization that the orchestrator is not permitted to grant autonomously. |
+| `awaiting_ci` | non-mechanical | The run is waiting for a CI result that has not yet completed, and no remediation is warranted until that result is available. |
+| `human_decision_required` | non-mechanical | The run requires a human to choose between alternatives or approve a direction before it can continue. |
+
+Partition definitions:
+
+- **Not blocked:** `none`, JSON `null`, or key absent at a gate. Plain validation still reports an absent key through the required-key check.
+- **Mechanical:** the orchestration process itself did not complete a step: a tool or delegation failed, a delegate returned no or an incomplete receipt, a validator failed, or the operator stopped execution. Membership is defined by the published constant, not by the wording.
+- **Non-mechanical:** every process step could proceed, but the work cannot continue for a reason that no retry or remediation cycle of the process resolves.
+
+The classification is recoverable from `blocked_reason` alone by looking the value up in the published partition (`classify_blocked_reason` in Python, `classifyBlockedReason` in TypeScript).
+
+Enforcement parity: the Python, PowerShell, and TypeScript validators enforce this vocabulary identically, with case-sensitive comparison. A value outside the vocabulary, including a case variant of any member, is rejected with `Checkpoint has invalid blocked_reason: <value>`. Every non-`none` member, including the five non-mechanical members, blocks completion and PR-creation readiness with the existing messages.
+
+Relationship to `human_interaction.requirements[].response == "halt"`: a human-decision halt may appear in both places. `blocked_reason: "human_decision_required"` classifies the run's halt, and a `human_interaction.requirements[]` entry with `response: "halt"` describes the specific requirement. There is no cross-field rule between them: either may appear without the other, and neither is validated against the other.
+
+Producer guidance for `premise_falsified`: set it when every delegation and validator succeeded but evidence gathered during execution falsified the plan's premise. The evidence path is still recorded in free-form checkpoint keys; `blocked_reason` carries the classification only.
+
+Extension point for #484: #484 consumes `external_dependency`, `policy_hold`, `awaiting_ci`, and `human_decision_required` without renaming, removing, or re-partitioning them; any further halt class is a separate contract change that appends the literal to the non-mechanical partition in all three runtimes, updates the partition oracle and corpus, and updates this section.
+
 ## Complexity-Assessment Scope and Backward Compatibility
 
 These invariants apply only when the checkpoint contains a top-level `complexity_assessments` array. A checkpoint with no `complexity_assessments` key (the existing checkpoint shape) is unaffected: it validates exactly as before and produces no new errors. The invariants are additive and support the two-axis model-selection mechanism documented in `.claude/skills/orchestrate/SKILL.md` (`## Model Selection`). Enforcement is the Python validator, not an imported schema.
@@ -92,7 +166,11 @@ The session `model_budget.fable_policy` switch is a three-way enum `disabled | a
 
 ## Require-Model-Routing Mode Scope and Backward Compatibility
 
-The complexity-assessment and model-routing-receipt invariants above are key-gated: they run only when their key is present, so a checkpoint that omits both arrays passes at every stage. The `require_model_routing` mode adds an existence gate that closes that gap without changing the default behavior. It is an opt-in keyword on `validate_orchestrator_state_text(..., require_model_routing=False)` (CLI flag `--require-model-routing`; MCP parameter `require_model_routing`), defaulting off. Plain, `require_complete`, and `require_pr_creation_ready` calls are unaffected and produce byte-identical results.
+The complexity-assessment and model-routing-receipt invariants above are key-gated: they run only when their key is present, so a checkpoint that omits both arrays passes at every stage. The `require_model_routing` mode adds an existence gate that closes that gap without changing the default behavior. It is an opt-in keyword on `validate_orchestrator_state_text(..., require_model_routing=False)` (CLI flag `--require-model-routing`, accepted by the dispatcher `orchestrator-state` subcommand and by the bare-module CLI; MCP parameter `require_model_routing`), defaulting off. Plain, `require_complete`, and `require_pr_creation_ready` calls are unaffected and produce byte-identical results.
+
+## Bare-Module CLI Contract
+
+The validator module runs directly as `python -m scripts.dev_tools.validate_orchestrator_state <path> [--require-complete] [--require-model-routing] [--require-pr-creation-ready] [--require-codex-model-routing] [--require-codex-topology]`. The dispatcher `python -m scripts.dev_tools.validate_orchestration_artifacts orchestrator-state` stays available and accepts the same flags. Exit code 0 means the checkpoint passed and the success line `orchestrator-state validation passed: <path>` is written to stdout. Exit code 1 means validation errors, written one per stderr line. Exit code 2 means the path is missing, unreadable, or not UTF-8, with one stderr diagnostic and no traceback; argparse usage errors also exit 2.
 
 ## Invariants (require_model_routing mode)
 
@@ -146,6 +224,43 @@ not a cryptographic or security control.
 
 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.
 
+## Issue-Adoption Scope and Backward Compatibility
+
+These invariants apply only when a checkpoint contains a top-level `issue_adoption` key. The key records that the orchestration adopted a GitHub issue that already existed before orchestration started (transferred, filed by hand, or created by epic decomposition), so the issue was never created through `potential_to_issue`. The key is presence-gated: a checkpoint without it validates byte-identically to before and produces no new errors. It is evaluated only by the routing-contract completion check (`validate_routing_contract` and its TypeScript and PowerShell ports). It is not a member of `REQUIRED_STATE_KEYS`, it is not read by plain (non-completion) validation, and it is not read by the PR-creation-readiness gate. No JSON Schema file is authored, imported, or read for it.
+
+Honest disclosure: the validators perform no network I/O. They cannot confirm that the issue exists, so `evidence` and `verified_via` are an auditable declaration of the read-only verification the orchestrator performed, not proof of it. This matches the `standalone_merge_authorizations` precedent above: the record is a policy-level declaration, not a security control.
+
+## Invariants (issue_adoption object)
+
+The object has the shape `{ issue_num, issue_url, origin, verified_via, verified_at, evidence, waived_tools, potential_record? }`.
+
+| Field | Rule |
+| --- | --- |
+| `issue_num` | A string of decimal digits without a leading zero; equal to the checkpoint `issue-num` when that is a string. |
+| `issue_url` | A string ending with `/issues/` followed by `issue_num`. |
+| `origin` | One of `transferred`, `filed_before_orchestration`, `epic_decomposition`. |
+| `verified_via` | One of `gh_issue_view`, `gh_api_get`, `github_mcp_issue_read`. |
+| `verified_at` | Present, not `null`, and not a blank string. |
+| `evidence` | A string with non-whitespace content. |
+| `waived_tools` | A non-empty list of non-blank tool names that includes `potential_to_issue`. |
+| `potential_record` | Required when waiving a promotion-entry tool: a path under `docs/features/potential/` ending in `.md`. |
+
+The rules run in this order, and their errors accumulate:
+
+1. A present value that is not an object (including `null`) yields `Checkpoint issue_adoption must be an object when present.` and evaluation stops.
+2. `issue_num` must be a string of decimal digits without a leading zero (a JSON number is invalid). Only when it is valid and the checkpoint `issue-num` is a different string, `issue_num` must equal the checkpoint issue-num.
+3. `issue_url` must end with `/issues/` followed by a valid `issue_num`.
+4. `origin` must be one of the three origin values.
+5. `verified_via` must be one of the three verification values.
+6. `verified_at` must be present: absent, `null`, and blank strings are rejected; any other value passes.
+7. `evidence` must be a non-empty string.
+8. `waived_tools` must be a non-empty list of non-blank strings; otherwise no further rule-8 or rule-9 check runs. Each entry, in list order, receives the first applicable error of: listed more than once; not in the closed waivable set; not required by the selected route after promotion-type resolution; already holding a successful MCP receipt. The list must include `potential_to_issue`.
+9. Only when the rule-8 shape check passed: each distinct waived promotion-entry tool (`new_potential_entry` or `new_potential_bug_entry`) requires a valid `potential_record`.
+
+The closed waivable set is `potential_to_issue`, `new_potential_entry`, and `new_potential_bug_entry`. `new_active_feature_folder`, `collect_pr_context`, `validate_orchestration_artifacts`, and every other tool can never be waived. All comparisons are ordinal and case-sensitive.
+
+Fail-closed behavior: any adoption error waives nothing, so each missing receipt is still reported as `Checkpoint missing successful MCP receipt: <tool>.`. Adoption errors are placed after the receipt-loop errors and before the `local_execution_overrides` errors. The waiver affects only receipt presence: the declared `required_mcp_tools` equality check with the routing matrix is unchanged, so a checkpoint must still declare every route tool it waives.
+
 ## 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.
@@ -157,3 +272,4 @@ Field checks 3 through 9 run in the fixed order `pr_url`, `issue_num`, `branch_n
 - 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.
+- The `issue_adoption` invariants are enforced at completion by the routing-contract check in all three runtimes: `scripts/dev_tools/_orchestrator_state_issue_adoption.py` (Python authority), `extensions/drm-copilot/src/lib/validate/orchestrator-state-issue-adoption.ts`, and `.claude/lib/orchestrator-state/OrchestratorStateIssueAdoption.psm1`, with byte-identical error strings pinned by the shared corpus under `tests/fixtures/orchestrator_state_issue_adoption/`.

package/resources/claude-customizations/.claude/rules/quality-tiers.md

@@ -6,7 +6,7 @@ description: Module rigor tier system and uniform coverage thresholds.
 
 # Module Rigor Tiers
 
-This rule defines the T1–T4 module rigor tier system used by all CI gates in this repository. The tier system source of truth is `docs/ci.research.md` section 1; the file `quality-tiers.yml` at the repository root maps every project to a tier. Adding a project without a tier classification fails CI.
+This rule defines the T1–T4 module rigor tier system used by all CI gates in this repository. The tier definitions and gate matrix in this document are the tier system's source of truth; the file `quality-tiers.yml` at the repository root maps every project to a tier. Adding a project without a tier classification fails CI.
 
 ## Tiers
 

package/resources/claude-customizations/.claude/skills/acceptance-criteria-tracking/SKILL.md

@@ -70,6 +70,14 @@ During plan execution, after completing a task whose work satisfies an acceptanc
 
 Timing: Check off AC items as soon as the corresponding plan task passes verification — do not defer all AC updates to the end of plan execution.
 
+### CI-Dependent Criteria
+
+A CI-dependent criterion is one whose verification requires the result of CI on the PR head. It cannot be verified before the pull request exists, so it stays unchecked and is listed as pending-CI in the AC verification artifact until CI has run.
+
+- Owner: the item's own orchestrator run owns the check-off and performs it at S9; this is the one case in which an orchestrator run checks off AC. A parent or coordinating session never commits the check-off from its own root.
+- Timing: after the CI green gate (S9) records `ci_gate.conclusion` as `success`, and before the run reports DONE.
+- Push and re-verify: the check-off is committed in the item's own worktree and pushed to the PR branch, and the CI green gate is re-run against the new head SHA so that `ci_gate.head_sha` equals the final PR head before DONE.
+
 ### When Reviewers Check Off AC
 
 During feature review (feature-audit phase):

package/resources/claude-customizations/.claude/skills/atomic-plan-contract/SKILL.md

@@ -212,6 +212,8 @@ Rules:
 - **Observe a command's success-case output before asserting over that output (mandatory).** Run the command, or read a recorded run of it, and confirm the value you intend to assert is actually printed on a *successful* run. Do not infer it from the tool's documentation, from the plan, or from what the tool prints on failure. This requirement exists because the class of defect it prevents is not detectable by reading: an assertion on a line the tool prints only when it changed something is unsatisfiable on a clean run; a demand for a zero-diagnostic count from a tool that returns only an ok flag names a value with no source; a demand for separate line and branch percentages from a coverage run that prints one combined column reads two numbers that are never printed. G7 and G9 cover two decidable slices of this class. The remainder is covered by this requirement and by nothing else, so a reviewer cannot rely on the gate to catch it.
 - **Fix the evidence in the plan; never leave the executor to select it.** An executor free to choose the evidence it is judged against cannot fail. Do not write an acceptance condition that asks the executor to identify "the known-genuine pair", to choose a survivor list, or to pick any suitable instance. Name the instances, or state the mechanical derivation that produces them, so a third party re-running it obtains the same set. This is authoring guidance and not a rule: a validator rule that scanned acceptance text for selection vocabulary was proposed and rejected, because that vocabulary is ordinary plan prose used in roles carrying no selection semantics and a keyword scan over prose is not statically decidable for the property it would claim to detect. The judgment is the author's, and it is not automated. `.claude/rules/plan-acceptance-gates.md` records the rejection and the reason for it.
 - **Check that the task-ordering does not make the condition unsatisfiable.** No rule covers this. A gate that runs a test path containing deliberately-failing cases added by an earlier task, before the later task that makes them pass, cannot exit 0. A baseline captured after a write-mode formatter has already repaired pre-existing drift becomes either a blanket waiver or makes a later gate unsatisfiable. Read each acceptance condition against the state the plan will actually be in when its task runs.
+- **Name the runner and job for a Pester acceptance criterion.** CI runs Pester in two jobs of `.github/workflows/_poshqc.yml`: `poshqc / PowerShell QC` runs every suite with coverage on `windows-latest`, and `poshqc / PowerShell hook suites (Linux)` runs only `tests/scripts/claude-hooks` and `tests/scripts/codex-hooks` on `ubuntu-latest`, with coverage disabled. A Pester acceptance criterion may cite `ubuntu-latest` only for suites under `tests/scripts/claude-hooks` or `tests/scripts/codex-hooks`, never for coverage, and must name the job it relies on (`poshqc / PowerShell QC` or `poshqc / PowerShell hook suites (Linux)`).
+- **Do not assert a fixed-string search literal that contains a backslash.** Git for Windows grep 3.0 reads a doubled backslash in a `grep -F` pattern as one backslash, so the same check returns a different count locally than on a CI runner and cannot pass in both places. Assert a backslash-free substring of the literal, a named test, or a hash or byte-identity check instead.
 
 ## Plan-Path Continuity Contract (Mandatory)
 

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

@@ -128,9 +128,17 @@ The script emits pipe-delimited, `LC_ALL=C`-ordered records, one per line:
   per-file outcome is reported by the companion `ACTION|preserve-stage|...` record.
 - `ORPHAN_DIR|<path>|<size>` — a directory under a worktree-tracking root that carries
   no `.git` pointer file and no `git worktree list` entry. `<size>` is best-effort and
-  may be the literal `unknown`. The record is advisory: it reports the directory, and
-  nothing in apply mode acts on it. For the disposition, see the Dirty Worktree Triage
-  Procedure's step 7, which governs how an orphaned directory is handled.
+  may be the literal `unknown`. The scanned roots are the default pair
+  `<main>/.claude/worktrees` and `<main>-wt`, or the `CLEANUP_WT_ORPHAN_ROOTS` entries
+  when that variable is set (the override replaces the default pair), plus the parent
+  directory of every non-main registered worktree, which is always added. A derived
+  parent is skipped when it is the main worktree or one of its ancestors, or is equal to
+  or inside a registered worktree. `CLEANUP_WT_ORPHAN_ROOTS` entries are separated by a
+  semicolon, a newline, or a colon; a colon that follows a single drive letter and
+  precedes `/` or `\` is part of the path, and empty or relative entries are dropped.
+  The record is advisory: it reports the directory, and nothing in apply mode acts on
+  it. For the disposition, see the Dirty Worktree Triage Procedure's step 7, which
+  governs how an orphaned directory is handled.
 - `STALE_REF|<refname>` — a `refs/remotes/<name>/*` ref whose `<name>` is not a
   configured remote, named in full ref form. Advisory only; no ref is ever pruned by
   this tool.

package/resources/claude-customizations/.claude/skills/cleanup-merged-worktrees/scripts/cleanup-worktrees.sh

@@ -139,8 +139,17 @@ Environment overrides:
                                nonexistent value is treated as missing (falls back to
                                the bundled cleanup_worktrees_scan_helper.sh). This is
                                the filesystem-scan test-stub seam.
-  CLEANUP_WT_ORPHAN_ROOTS      Colon-separated override for the worktree-tracking roots
-                               scanned for ORPHAN_DIR and WARN|registration-lost.
+  CLEANUP_WT_ORPHAN_ROOTS      Worktree-tracking roots scanned for ORPHAN_DIR and
+                               WARN|registration-lost. Entries are separated by a
+                               semicolon, a newline, or a colon; a colon that follows
+                               a single drive letter and precedes / or \ is part of
+                               the path (C:/x). Empty and relative entries are
+                               dropped. When set, it replaces the default pair
+                               <main>/.claude/worktrees and <main>-wt. The parent of
+                               every non-main registered worktree is always added,
+                               except a parent that is the main worktree or its
+                               ancestor, or is equal to or inside a registered
+                               worktree.
   CLEANUP_WT_STUB_SCENARIO     Scenario directory consumed by the checked-in git and
                                scan stubs (tests only).
   CLEANUP_WT_CONSOLIDATION_PATH Override the derived consolidation worktree path