@danmoisan/drm-copilot-mcp 1.0.23 → 1.0.26

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

@@ -0,0 +1,377 @@
+<#
+.SYNOPSIS
+    Pinned routing-matrix constants and route accessors for the portable checks.
+
+.DESCRIPTION
+    Implements deliberate deviation PD-1 exactly as the feature spec records it.
+    The subset of `config/orchestration-routing.json` that the completion checks
+    consume - each route's `requires_pr_gate`, `requires_ci_gate`,
+    `required_agents`, `required_skills`, and `required_mcp_tools` - is embedded
+    here as pinned constants, following the established `ModelRouting.psm1:33-39`
+    pattern.
+
+    NO DISK READ AT VALIDATION TIME. This module never opens
+    `config/orchestration-routing.json`. That file is deliberately not shipped to
+    consumer repositories, and the Python reference crashes with an uncaught
+    FileNotFoundError in a repository that lacks it - even on a plain validator
+    call. A missing-config crash, or a blanket block, is precisely the portability
+    failure this feature exists to remove, so fail-closed-on-missing-config was
+    rejected in favour of pinned constants. The config is read only by the static
+    config-parity Pester test, which runs in drm-copilot where the file exists and
+    is the oracle that keeps these constants honest.
+
+    Route-value resolution is exported too, because two different Python rules
+    exist and both must be reproduced: the routing-contract and preparation
+    checks read the raw `route_id` value (falling back to `path_selected` only
+    when the `route_id` KEY is absent), while the gate helpers additionally
+    require that value to be a non-blank string.
+
+    Every accessor takes an optional -RoutingMatrix override so a caller can
+    supply an alternative matrix, mirroring the Python `routing_matrix` keyword.
+    The override exists for testability and for the malformed-matrix check; it is
+    never used to read from disk.
+
+    Every function is pure: it reads no file, starts no process, and never mutates
+    its input.
+#>
+
+Set-StrictMode -Version Latest
+
+# 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
+
+# The pinned routing-matrix subset. Each route records the two gate flags and the
+# three required-name lists the completion checks consume. A gate flag of $null
+# means the key is ABSENT from the config, which is semantically distinct from
+# $false: an absent requires_ci_gate keeps the CI gate required, while an absent
+# requires_pr_gate leaves the PR gate not required.
+$script:PINNED_ROUTES = @{
+    small       = @{
+        requires_pr_gate   = $null
+        requires_ci_gate   = $null
+        required_agents    = @('atomic-planner', 'atomic-executor', 'feature-review')
+        required_skills    = @('orchestrate', 'feature-promotion-lifecycle', 'atomic-plan-contract', 'acceptance-criteria-tracking', 'pr-context-artifacts', 'pr-base-branch-merge-base')
+        required_mcp_tools = @('new_potential_entry', 'potential_to_issue', 'new_active_feature_folder', 'collect_pr_context', 'validate_orchestration_artifacts')
+    }
+    large       = @{
+        requires_pr_gate   = $true
+        requires_ci_gate   = $null
+        required_agents    = @('task-researcher', 'prd-feature', 'atomic-planner', 'atomic-executor', 'feature-review', 'pr-author')
+        required_skills    = @('orchestrate', 'feature-promotion-lifecycle', 'atomic-plan-contract', 'acceptance-criteria-tracking', 'pr-context-artifacts', 'pr-base-branch-merge-base')
+        required_mcp_tools = @('new_potential_entry', 'potential_to_issue', 'new_active_feature_folder', 'collect_pr_context', 'validate_orchestration_artifacts')
+    }
+    remediation = @{
+        requires_pr_gate   = $null
+        requires_ci_gate   = $null
+        required_agents    = @('atomic-planner', 'atomic-executor', 'feature-review')
+        required_skills    = @('orchestrate', 'atomic-plan-contract', 'acceptance-criteria-tracking', 'pr-context-artifacts')
+        required_mcp_tools = @('collect_pr_context', 'validate_orchestration_artifacts')
+    }
+    preparation = @{
+        requires_pr_gate   = $null
+        requires_ci_gate   = $false
+        required_agents    = @('task-researcher', 'prd-feature', 'atomic-planner', 'atomic-executor')
+        required_skills    = @('orchestrate', 'feature-promotion-lifecycle', 'atomic-plan-contract')
+        required_mcp_tools = @('new_potential_entry', 'potential_to_issue', 'new_active_feature_folder', 'validate_orchestration_artifacts')
+    }
+    parallel    = @{
+        requires_pr_gate   = $false
+        requires_ci_gate   = $null
+        required_agents    = @('orchestrator', 'pr-author')
+        required_skills    = @('parallel-orchestrate', 'orchestrate', 'feature-promotion-lifecycle', 'atomic-plan-contract', 'acceptance-criteria-tracking', 'evidence-and-timestamp-conventions', 'pr-context-artifacts', 'pr-base-branch-merge-base')
+        required_mcp_tools = @('collect_pr_context', 'validate_orchestration_artifacts')
+    }
+    epic        = @{
+        requires_pr_gate   = $true
+        requires_ci_gate   = $null
+        required_agents    = @('orchestrator', 'pr-author')
+        required_skills    = @('epic-orchestrate', 'orchestrate', 'feature-promotion-lifecycle', 'atomic-plan-contract', 'acceptance-criteria-tracking', 'evidence-and-timestamp-conventions', 'pr-context-artifacts', 'pr-base-branch-merge-base')
+        required_mcp_tools = @('collect_pr_context', 'validate_orchestration_artifacts')
+    }
+}
+
+# The three per-route list names the completion and routing-contract checks read.
+$script:ROUTE_LIST_NAMES = @('required_agents', 'required_skills', 'required_mcp_tools')
+
+
+function Get-OrchestratorStateRoutingMatrix {
+    <#
+    .SYNOPSIS
+        Return the pinned routing matrix in the shape the Python matrix has.
+    .DESCRIPTION
+        Returns a hashtable with a single `routes` member, mirroring the top-level
+        shape of config/orchestration-routing.json so the accessors and the
+        malformed-matrix check operate on the same structure whether the matrix is
+        the pinned default or a caller-supplied override. No file is read.
+    .OUTPUTS
+        System.Collections.Hashtable with a `routes` member.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param()
+
+    return @{ routes = $script:PINNED_ROUTES }
+}
+
+function Get-OrchestratorStateRoutingMatrixRouteMap {
+    <#
+    .SYNOPSIS
+        Return a matrix's routes mapping, or $null when the matrix is malformed.
+    .DESCRIPTION
+        Private-shape accessor mirroring the Python `matrix.get("routes")` guard.
+        A matrix whose `routes` member is absent or is not a mapping yields $null,
+        which the routing-contract check reports as a malformed matrix.
+    .PARAMETER RoutingMatrix
+        The matrix to inspect. When omitted, the pinned matrix is used.
+    .OUTPUTS
+        System.Collections.Hashtable, or $null when the matrix carries no routes
+        mapping.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $false)]
+        [AllowNull()]
+        [hashtable] $RoutingMatrix = $null
+    )
+
+    $matrix = if ($null -ne $RoutingMatrix) { $RoutingMatrix } else { Get-OrchestratorStateRoutingMatrix }
+    if (-not $matrix.ContainsKey('routes')) { return $null }
+    $routes = $matrix['routes']
+    if ($routes -isnot [hashtable]) { return $null }
+    return $routes
+}
+
+function Get-OrchestratorStateRoute {
+    <#
+    .SYNOPSIS
+        Return one route's pinned entry, or $null when the route is unknown.
+    .DESCRIPTION
+        Accessor mirroring the Python `routes.get(route_id)` lookup plus its
+        `isinstance(raw_route, dict)` guard. A null or unknown route id, or a
+        malformed matrix, yields $null.
+    .PARAMETER RouteId
+        The route identifier. May be $null.
+    .PARAMETER RoutingMatrix
+        Optional matrix override. When omitted, the pinned matrix is used.
+    .OUTPUTS
+        System.Collections.Hashtable, or $null when the route is unknown.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $RouteId,
+
+        [Parameter(Mandatory = $false)]
+        [AllowNull()]
+        [hashtable] $RoutingMatrix = $null
+    )
+
+    if ([string]::IsNullOrEmpty($RouteId)) { return $null }
+    $routes = Get-OrchestratorStateRoutingMatrixRouteMap -RoutingMatrix $RoutingMatrix
+    if ($null -eq $routes -or -not $routes.ContainsKey($RouteId)) { return $null }
+    $route = $routes[$RouteId]
+    if ($route -isnot [hashtable]) { return $null }
+    return $route
+}
+
+function Get-OrchestratorStateRawRouteValue {
+    <#
+    .SYNOPSIS
+        Return the checkpoint's raw route value without a string requirement.
+    .DESCRIPTION
+        Reproduces the Python expression `state.get("route_id",
+        state.get("path_selected"))`. The distinction matters: when the `route_id`
+        KEY is present its value is used even if that value is null, and only an
+        ABSENT `route_id` key falls back to `path_selected`. The preparation
+        terminal check compares this raw value directly.
+    .PARAMETER State
+        The parsed checkpoint object.
+    .OUTPUTS
+        System.Object - the raw route value, which may be $null or a non-string.
+    #>
+    [CmdletBinding()]
+    [OutputType([object])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [psobject] $State
+    )
+
+    $routeIdField = Get-CheckpointObjectMember -Owner $State -Name 'route_id'
+    if ($routeIdField.Present) { return $routeIdField.Value }
+    return (Get-CheckpointObjectMember -Owner $State -Name 'path_selected').Value
+}
+
+function Get-OrchestratorStateSelectedRouteId {
+    <#
+    .SYNOPSIS
+        Return the checkpoint's selected route id, or $null when unusable.
+    .DESCRIPTION
+        Reproduces the Python `_selected_route_id` helper: the raw route value is
+        usable only when it is a non-blank string. Every gate accessor and the
+        phase-completeness check resolve the route through this rule.
+    .PARAMETER State
+        The parsed checkpoint object.
+    .OUTPUTS
+        System.String - the route id, or $null when absent, non-string, or blank.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [psobject] $State
+    )
+
+    $value = Get-OrchestratorStateRawRouteValue -State $State
+    if (-not ($value -is [string]) -or [string]::IsNullOrWhiteSpace([string]$value)) { return $null }
+    return [string]$value
+}
+
+function Test-OrchestratorStateRouteRequiresPrGate {
+    <#
+    .SYNOPSIS
+        Report whether a route requires the completion PR gate.
+    .DESCRIPTION
+        Mirrors `route_requires_pr_gate`. The gate applies only when the route
+        exists and its `requires_pr_gate` value is exactly the boolean true, so a
+        missing route id, an unknown route, and an absent flag all report false.
+    .PARAMETER RouteId
+        The route identifier. May be $null.
+    .PARAMETER RoutingMatrix
+        Optional matrix override. When omitted, the pinned matrix is used.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $RouteId,
+
+        [Parameter(Mandatory = $false)]
+        [AllowNull()]
+        [hashtable] $RoutingMatrix = $null
+    )
+
+    $route = Get-OrchestratorStateRoute -RouteId $RouteId -RoutingMatrix $RoutingMatrix
+    if ($null -eq $route -or -not $route.ContainsKey('requires_pr_gate')) { return $false }
+    return (($route['requires_pr_gate'] -is [bool]) -and [bool]$route['requires_pr_gate'])
+}
+
+function Test-OrchestratorStateRouteRequiresCiGate {
+    <#
+    .SYNOPSIS
+        Report whether a route requires the completion CI gate.
+    .DESCRIPTION
+        Mirrors `route_requires_ci_gate`. Only an explicit boolean false opts a
+        route out, so a missing route id, an unknown route, and an absent flag all
+        keep the CI gate required. The asymmetry with the PR gate is deliberate
+        and is the historical behaviour the Python reference preserves.
+    .PARAMETER RouteId
+        The route identifier. May be $null.
+    .PARAMETER RoutingMatrix
+        Optional matrix override. When omitted, the pinned matrix is used.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $RouteId,
+
+        [Parameter(Mandatory = $false)]
+        [AllowNull()]
+        [hashtable] $RoutingMatrix = $null
+    )
+
+    $route = Get-OrchestratorStateRoute -RouteId $RouteId -RoutingMatrix $RoutingMatrix
+    if ($null -eq $route -or -not $route.ContainsKey('requires_ci_gate')) { return $true }
+    return -not (($route['requires_ci_gate'] -is [bool]) -and -not [bool]$route['requires_ci_gate'])
+}
+
+function Get-OrchestratorStateRouteRequiredList {
+    <#
+    .SYNOPSIS
+        Return one of a route's three required-name lists.
+    .DESCRIPTION
+        Mirrors the Python `_route_list` helper: a route that does not carry the
+        named list, or carries a value that is not a list of non-blank strings,
+        contributes an empty list rather than an error.
+    .PARAMETER RouteId
+        The route identifier. May be $null.
+    .PARAMETER ListName
+        One of required_agents, required_skills, required_mcp_tools.
+    .PARAMETER RoutingMatrix
+        Optional matrix override. When omitted, the pinned matrix is used.
+    .OUTPUTS
+        System.String[] - the required names in matrix order, possibly empty.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $RouteId,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('required_agents', 'required_skills', 'required_mcp_tools')]
+        [string] $ListName,
+
+        [Parameter(Mandatory = $false)]
+        [AllowNull()]
+        [hashtable] $RoutingMatrix = $null
+    )
+
+    $route = Get-OrchestratorStateRoute -RouteId $RouteId -RoutingMatrix $RoutingMatrix
+    if ($null -eq $route -or -not $route.ContainsKey($ListName)) { return [string[]]@() }
+
+    # A malformed list contributes nothing, matching the Python helper's
+    # None-to-empty-list conversion rather than raising.
+    $value = $route[$ListName]
+    if ($value -isnot [System.Array]) { return [string[]]@() }
+    foreach ($item in $value) {
+        if (-not ($item -is [string]) -or [string]::IsNullOrWhiteSpace([string]$item)) { return [string[]]@() }
+    }
+    return [string[]]@($value)
+}
+
+function Get-OrchestratorStateRouteListName {
+    <#
+    .SYNOPSIS
+        Return the three per-route required-name list names.
+    .DESCRIPTION
+        Read-only accessor so the routing-contract check and the config-parity
+        test iterate one declared set of list names instead of restating it.
+    .OUTPUTS
+        System.String[] - the three list names.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param()
+
+    return [string[]]@($script:ROUTE_LIST_NAMES)
+}
+
+# The matrix, the route lookup, both gate predicates, the required-list accessor,
+# and both route-value resolvers are exported for the completion-checks and
+# routing-contract modules and for the static config-parity test.
+Export-ModuleMember -Function `
+    Get-OrchestratorStateRoutingMatrix, `
+    Get-OrchestratorStateRoutingMatrixRouteMap, `
+    Get-OrchestratorStateRoute, `
+    Get-OrchestratorStateRawRouteValue, `
+    Get-OrchestratorStateSelectedRouteId, `
+    Test-OrchestratorStateRouteRequiresPrGate, `
+    Test-OrchestratorStateRouteRequiresCiGate, `
+    Get-OrchestratorStateRouteRequiredList, `
+    Get-OrchestratorStateRouteListName

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

@@ -0,0 +1,166 @@
+<#
+.SYNOPSIS
+    Single entry point for the orchestrator-state unconditional check block.
+
+.DESCRIPTION
+    Composes the whole U family of the issue #475 parity inventory into one
+    portable call, mirroring the unconditional block of
+    `validate_orchestrator_state_text` in
+    `scripts/dev_tools/validate_orchestrator_state.py`:
+
+      U2-U4  required keys, step-status validity, blocked_reason validity, from
+             the existing `Get-OrchestratorStateBasePresenceError` in
+             `OrchestratorState.psm1`
+      U5     delegation_receipts shape, from `OrchestratorStateReceipts.psm1`
+      U6.R   remediation_loop cycles, same module
+      U6.H   human_interaction shape, same module
+      U6.C   complexity_assessments per-entry, from `OrchestratorStateModelReceipts.psm1`
+      U6.M   model_routing_receipts per-entry, same module
+      U6.X   codex_model_routing_receipts, from `OrchestratorStateCodexModelReceipts.psm1`
+      U6.T   codex_topology_receipts, from `OrchestratorStateCodexTopologyReceipts.psm1`
+
+    U1 (parse failure and non-object root) is the LOADER's contract, produced by
+    `Get-OrchestratorStateCheckpoint` in `OrchestratorState.psm1`. Every caller
+    runs the loader first and fails closed on its error before reaching this
+    function, so the loader and this function together are the complete U family.
+    The loader's path-prefixed message text is the one documented parity
+    divergence from the Python strings, recorded in the feature spec.
+
+    KEY-GATED SEMANTICS ARE PRESERVED. Each optional-key family runs only when
+    its key is PRESENT on the checkpoint, exactly as the Python
+    `optional_key_validators` loop does. An absent key contributes zero errors and
+    never produces a "must be a list when present" message. The distinction
+    matters: a present key holding null is validated, an absent key is not.
+
+    Families run in the Python reference's order so accumulated error output is
+    ordered identically.
+
+    The function is pure: it reads no file, starts no process, and never mutates
+    its input.
+#>
+
+Set-StrictMode -Version Latest
+
+# Import the four leaf check modules eagerly. None of them imports this module,
+# so this import graph has no cycle. OrchestratorState.psm1 is deliberately NOT
+# imported here; it is loaded lazily inside the function, because the preflight
+# path in that module imports this one and an eager import in both directions
+# would couple their load order.
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'OrchestratorStateReceipts.psm1') -Force
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'OrchestratorStateModelReceipts.psm1') -Force
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'OrchestratorStateCodexModelReceipts.psm1') -Force
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'OrchestratorStateCodexTopologyReceipts.psm1') -Force
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'OrchestratorStateCheckpointValue.psm1') -Force
+
+# The checkpoint key whose value carries the delegation receipts. It is read with
+# the Python `is not None` guard rather than a presence guard, matching the
+# reference.
+$script:DELEGATION_RECEIPTS_KEY = 'delegation_receipts'
+
+# The optional-key families, in the Python reference's evaluation order. The
+# dispatch below routes each present key to its validator by name; the list is
+# declared here so the order is stated once and is visible at a glance.
+$script:OPTIONAL_KEYS = @(
+    'remediation_loop',
+    'human_interaction',
+    'complexity_assessments',
+    'model_routing_receipts',
+    'codex_model_routing_receipts',
+    'codex_topology_receipts'
+)
+
+
+function Import-OrchestratorStateBaseModule {
+    <#
+    .SYNOPSIS
+        Ensure the shared base-presence command is available, importing it lazily.
+    .DESCRIPTION
+        Private helper following the guarded lazy-import pattern used by
+        .claude/hooks/validate-orchestrator-output.ps1. The base module is
+        imported only when its command is not already resolvable, so this module
+        can be loaded from inside that module's own call path without an
+        eager two-way import.
+    .OUTPUTS
+        None.
+    #>
+    [CmdletBinding()]
+    [OutputType([void])]
+    param()
+
+    if (Get-Command -Name 'Get-OrchestratorStateBasePresenceError' -ErrorAction SilentlyContinue) { return }
+    Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'OrchestratorState.psm1')
+}
+
+function Get-OrchestratorStateUnconditionalError {
+    <#
+    .SYNOPSIS
+        Return every unconditional-block error for a parsed checkpoint.
+    .DESCRIPTION
+        The single U-family entry point. Runs the base-presence checks (U2-U4),
+        the delegation-receipt shape checks (U5), and each optional-key family
+        (U6.R, U6.H, U6.C, U6.M, U6.X, U6.T) in the Python reference's order.
+        Every optional family is key-gated: it runs only when its key is present
+        on the checkpoint, so an absent key contributes zero errors.
+
+        U1 is not produced here. Parse failure and a non-object root are the
+        loader's contract; callers run Get-OrchestratorStateCheckpoint first and
+        fail closed on its error before reaching this function.
+    .PARAMETER State
+        The parsed checkpoint object, as returned by the loader.
+    .OUTPUTS
+        System.String[] - zero or more error strings, in Python reference order.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [psobject] $State
+    )
+
+    Import-OrchestratorStateBaseModule
+
+    $errors = [System.Collections.Generic.List[string]]::new()
+
+    # U2-U4: required keys, step-status validity, blocked_reason validity.
+    $errors.AddRange([string[]]@(Get-OrchestratorStateBasePresenceError -State $State))
+
+    # U5: the delegation-receipt shape, guarded on a non-null value rather than
+    # key presence, matching the Python `receipts is not None` test.
+    $receipts = (Get-CheckpointObjectMember -Owner $State -Name $script:DELEGATION_RECEIPTS_KEY).Value
+    $errors.AddRange([string[]]@(Get-OrchestratorStateDelegationReceiptError -Value $receipts))
+
+    # U6: each optional-key family, in reference order, key-gated so an absent key
+    # never produces a "must be a list when present" message. The dispatch names
+    # every validator explicitly rather than invoking a command stored in a
+    # variable, so the enforcement-hook AST guard sees only constant command
+    # names and no dynamic invocation.
+    foreach ($key in $script:OPTIONAL_KEYS) {
+        $field = Get-CheckpointObjectMember -Owner $State -Name $key
+        if (-not $field.Present) { continue }
+        switch ($key) {
+            'remediation_loop' {
+                $errors.AddRange([string[]]@(Get-OrchestratorStateRemediationLoopError -Value $field.Value))
+            }
+            'human_interaction' {
+                $errors.AddRange([string[]]@(Get-OrchestratorStateHumanInteractionError -Value $field.Value))
+            }
+            'complexity_assessments' {
+                $errors.AddRange([string[]]@(Get-OrchestratorStateComplexityAssessmentError -Value $field.Value))
+            }
+            'model_routing_receipts' {
+                $errors.AddRange([string[]]@(Get-OrchestratorStateModelRoutingReceiptError -Value $field.Value))
+            }
+            'codex_model_routing_receipts' {
+                $errors.AddRange([string[]]@(Get-OrchestratorStateCodexModelRoutingReceiptError -Value $field.Value))
+            }
+            'codex_topology_receipts' {
+                $errors.AddRange([string[]]@(Get-OrchestratorStateCodexTopologyReceiptError -Value $field.Value))
+            }
+        }
+    }
+
+    return $errors.ToArray()
+}
+
+# Only the aggregate entry point is exported; the lazy-import helper is private.
+Export-ModuleMember -Function Get-OrchestratorStateUnconditionalError

package/resources/claude-customizations/.claude/rules/general-unit-test.md

@@ -21,7 +21,7 @@ Every unit test must satisfy all five of these properties:
 ## Coverage Requirements
 
 - **Line coverage must remain >= 85% across all tiers (T1–T4).**
-- **Branch coverage must remain >= 75% across all tiers (T1–T4).**
+- **Branch coverage must remain >= 75% across all tiers (T1–T4) for languages whose coverage tooling measures branch coverage.** PowerShell (Pester) and bash (kcov) are the exceptions: neither tool measures branch coverage in any output format, so only the line threshold applies to them and there is no branch-coverage gate. This is a threshold exemption only; PowerShell and bash production files remain in the coverage denominator under the Coverage Exclusion Policy below.
 - Code changes or refactors must not reduce coverage for the lines that were changed.
 - Tier-specific lower coverage thresholds are not used in this repository. See `.claude/rules/quality-tiers.md` for the full tier system.
 - Coverage is a supporting metric, not the sole quality gate. Untested critical behavior is not acceptable even if the overall percentage looks good.

package/resources/claude-customizations/.claude/rules/parallel-orchestration.md

@@ -26,7 +26,7 @@ Enforced by `validate_parallel_orchestrator_state_text(text, *, require_complete
 
 3. **Mode enum.** `mode` must be `closed` or `open`.
 
-4. **Bounded concurrency.** `max_concurrency` must be an integer from 1 through 8, and must not be a boolean.
+4. **Bounded concurrency.** `max_concurrency` must be an integer from 1 through 32, and must not be a boolean.
 
 5. **Item uniqueness and shape.** Each `items[]` entry must be an object whose `issue_num` is a positive integer unique across items and whose `feature_folder` is a non-empty string.
 
@@ -98,7 +98,7 @@ Enforced by `validate_parallel_manifest_text(text)` in `scripts/dev_tools/parall
 
 - **M3 — Mode default.** `mode`, when present, must be `closed` or `open`. When absent it defaults to `closed`: the accessor `manifest_mode(mapping)` returns the default and the validator emits no error for absence.
 
-- **M4 — Concurrency default.** `max_concurrency`, when present, must be an integer from 1 through 8. When absent it defaults to `4`: the accessor `manifest_max_concurrency(mapping)` returns the default and the validator emits no error for absence.
+- **M4 — Concurrency default.** `max_concurrency`, when present, must be an integer from 1 through 32. When absent it defaults to `4`: the accessor `manifest_max_concurrency(mapping)` returns the default and the validator emits no error for absence.
 
 - **M5 — Created-at.** `created_at` must be a non-empty string.
 
@@ -106,6 +106,22 @@ Enforced by `validate_parallel_manifest_text(text)` in `scripts/dev_tools/parall
 
 - **M7 — Prohibited keys.** No `depends_on` key may appear at any level, and no `integration_branch` key may appear at top level. Presence is an explicit rejection.
 
+- **M8 — Expected conflict components (optional assertion).** `expected_conflict_components`, when present, must be a list. Each entry must be an object carrying a required `members` list that is non-empty and holds positive integers, each of which resolves to an `items[].issue_num`, with no `issue_num` appearing in more than one component; and an optional `name` that, when present, must be a non-empty string. When the key is ABSENT the invariant contributes zero errors and the manifest's error list is byte-identical to what it was before M8 existed.
+
+  The value must be authored as a YAML BLOCK sequence. The destination-runtime bash YAML subset parser (`.claude/lib/bash/parallel-yaml-scan.sh`) rejects a non-empty flow collection, so a flow-style value such as `members: [101, 102]` is outside the supported subset and is not accepted on the bash path.
+
+  `expected_conflict_components` is an ASSERTION, not a declaration. It NEVER overrides a derived conflict edge, NEVER feeds `compute_cohorts`, and NEVER influences scheduling. It is consumed by a planner diagnostic (`scripts/dev_tools/parallel_lane_assertion.py`), invoked advisory-only, whose findings never block. Its name deliberately references the DERIVED conflict graph: the field asserts what the operator expects blast-radius derivation to produce, and a mismatch is a signal to re-examine the radii, never a licence to edit the graph. The prohibition on narrowing a radius to suppress an edge is unaffected, as is the `depends_on` prohibition of invariant 10, P3, and M7 — this key is not a dependency edge and does not express ordering.
+
+  Example, in the mandatory block-sequence form:
+
+  ```yaml
+  expected_conflict_components:
+    - name: hooks-lane          # optional, diagnostic label only
+      members:                  # required, non-empty, positive ints
+        - 101
+        - 102
+  ```
+
 ## Cache Doctrine — the checkpoint is not the source of truth
 
 The parallel-orchestrator checkpoint is a CACHE of durable state, not the source of truth. Every field it records is re-derivable from the repository and from GitHub:
@@ -135,10 +151,19 @@ Per-item `merge_commit_sha` is retained; only the run-level merge-pull-request b
 
 ## Concurrency Bound (A7)
 
-`max_concurrency` is bounded at 1 through 8 inclusive and defaults to `4` when absent from the manifest. The design document sets only the default of 4; the upper bound of 8 is adopted here for symmetry with the epic surface, whose `max_parallel_features` is validated as `1..8`. The bound is recorded in this rule file so that downstream features do not re-litigate it. Booleans are rejected even though `True` and `False` are integers in Python.
+`max_concurrency` is bounded at 1 through 32 inclusive and defaults to `4` when absent from the manifest. The design document sets only the default of 4. Booleans are rejected even though `True` and `False` are integers in Python.
+
+The upper bound is derived from a constraint analysis of this surface alone. No other surface's bound is a reason for it. The findings recorded here so that downstream features do not re-litigate them:
+
+- **No constraint binds hard below O(100) concurrent worktrees.** Git worktrees, per-item feature branches, checkpoint size, and the cohort-coloring computation all scale well past a hundred concurrent items; none of them fails, or degrades sharply, anywhere near 32.
+- **The first-binding constraint is GitHub Actions job concurrency**, which begins to bite at roughly 10 to 20 concurrent items on a typical plan. It binds by QUEUING, not by failing: excess jobs wait for a runner and the run completes more slowly. A `max_concurrency` above that point is therefore not an error, merely a setting whose marginal throughput is absorbed by the queue.
+- **The ceiling of 32 is a SANITY limit, not a capacity limit.** Its purpose is to reject an order-of-magnitude operator typo (`320` for `32`), not to express a supported maximum. Do not read a value at or below 32 as an assurance that the runner pool can serve it.
+- **Under the per-edge cohort barrier `max_concurrency` is a pure throughput throttle.** Mutual exclusion inside a conflict component is automatic: a conflicting neighbour in a strictly prior current-generation cohort must be `merged` or `worktree_removed` before an item starts, so raising the cap can never co-schedule two conflicting items. Raising it changes only how many independent lanes advance at once.
 
 The bound is enforced in three places with the same semantics: orchestrator invariant 4, planner invariant P2, and manifest invariant M4.
 
+The epic surface is unaffected. `max_parallel_features` remains bounded at `1..8`; it is a different field on a different surface and is not changed by this bound.
+
 ## Drift-Event Recording Rule (A8)
 
 `drift_events[].action` is the two-member enum `{raised_blocking_finding, halted_later_started_item}`. The recording rule is: one event per drift occurrence, carrying the STRONGEST action taken. `halted_later_started_item` subsumes `raised_blocking_finding`, so an occurrence that halted a later-started item records exactly one event with `action == 'halted_later_started_item'` and does not additionally record a `raised_blocking_finding` event for the same occurrence.

package/resources/claude-customizations/.claude/rules/powershell.md

@@ -61,7 +61,7 @@ Introduce the smallest seam that enables reliable mocking. Apply these options i
 - Mock sparingly; prefer real code paths.
 - No external dependencies in unit tests.
 - Line coverage must remain >= 85% across all tiers (T1–T4) per `.claude/rules/quality-tiers.md`.
-- Branch coverage must remain >= 75% across all tiers (T1–T4).
+- Pester reports **command (instruction) coverage and line coverage only**. The uniform line-coverage threshold (>= 85% per `.claude/rules/quality-tiers.md`) applies. Branch coverage is not measurable by Pester for PowerShell; there is no PowerShell branch-coverage gate. This removes an unevaluable threshold, not a measurement obligation: PowerShell production files remain in the coverage denominator per the Coverage Exclusion Policy in `.claude/rules/general-unit-test.md`, and command coverage is reported for information only, with no threshold attached.
 - Coverage regression on changed lines is a blocking finding.
 
 ### Deterministic Test Requirements

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

@@ -22,7 +22,7 @@ This rule defines the T1–T4 module rigor tier system used by all CI gates in t
 
 ## Uniform-vs-Tier-Dependent Gate Matrix
 
-Per Authoritative Decision #2, line and branch coverage thresholds are uniform across all tiers. Other gates remain tier-dependent.
+Per Authoritative Decision #2, line and branch coverage thresholds are uniform across all tiers. The line threshold applies to every coverage language; the branch threshold applies to languages whose coverage tooling measures branch coverage. Other gates remain tier-dependent.
 
 ### Uniform across all tiers (T1–T4)
 
@@ -31,7 +31,7 @@ Per Authoritative Decision #2, line and branch coverage thresholds are uniform a
 - Type errors: 0.
 - Architecture violations: 0.
 - Line coverage: >= 85%.
-- Branch coverage: >= 75%.
+- Branch coverage: >= 75% for languages whose coverage tooling measures branch coverage. PowerShell (Pester) and bash (kcov) are exempt from this threshold because neither tool measures branch coverage; no branch-coverage gate applies to them.
 - No regression on changed lines.
 
 ### Tier-dependent
@@ -48,4 +48,4 @@ Per Authoritative Decision #2, line and branch coverage thresholds are uniform a
 
 ## Rationale (uniform coverage thresholds)
 
-High test coverage is a fundamental quality-control design choice that enables autonomous agentic development and trust in the work product. For that reason, line coverage >= 85% and branch coverage >= 75% apply uniformly across T1–T4; tier-specific lower coverage floors are not used in this repository.
+High test coverage is a fundamental quality-control design choice that enables autonomous agentic development and trust in the work product. For that reason, line coverage >= 85% applies uniformly across T1–T4 to every coverage language, and branch coverage >= 75% applies uniformly across T1–T4 to every language whose coverage tooling measures branch coverage; tier-specific lower coverage floors are not used in this repository. The branch threshold is not applied to PowerShell or bash because Pester and kcov do not measure branch coverage. That exemption is a capability limit on an unevaluable threshold, not a licence to exclude files from measurement: PowerShell and bash production files remain in the coverage denominator under the Coverage Exclusion Policy in `.claude/rules/general-unit-test.md`.