@danmoisan/drm-copilot-mcp 1.0.27 → 1.1.1

package/resources/claude-customizations/.claude/lib/hook-payload/HookPayload.psm1

@@ -0,0 +1,494 @@
+<#
+.SYNOPSIS
+    Shared PreToolUse hook payload reader: transport, envelope parse, and strict
+    nested tool_input extraction (issue #501).
+
+.DESCRIPTION
+    Every PreToolUse hook under .claude/hooks/ acquires its payload through this
+    module instead of re-implementing the parse inline. The module owns three
+    concerns.
+
+    Transport. Claude Code delivers command-hook input on stdin as JSON.
+    Read-ClaudeHookRawPayload reads stdin first, then falls back to the
+    CLAUDE_HOOK_INPUT environment variable and then the CLAUDE_TOOL_INPUT
+    environment variable; the first non-whitespace source wins. Both stdin
+    operations sit behind injectable scriptblock seams so tests drive them without
+    touching a .NET static and without spawning a process.
+
+    Shape. Tool arguments are nested under the envelope's tool_input object.
+    Get-ClaudeHookToolInput extracts that object strictly: a parsed payload with no
+    tool_input key, or a tool_input that is null or not an object, is an envelope
+    anomaly. There is deliberately no flat-root fallback, because a permissive
+    dual-shape reader would keep every legacy-shaped fixture green and restore the
+    silent-allow failure mode on the next contract drift.
+
+    Anomaly classification. The parse and extract functions never return a silent
+    null for malformed input; they return a typed result whose Anomaly property
+    names the failure, and Get-ClaudeHookPayloadAnomalyReason maps that code to the
+    deny reason text a hook emits.
+
+    Fail-closed posture: an envelope-level anomaly is a deny, emitted as decision
+    JSON at process exit code 0. Exit code 1 is non-blocking for PreToolUse, so a
+    throwing hook is itself a fail-open. Property-level absence inside a well-formed
+    tool_input is NOT an anomaly: that is each hook's own scope filter and keeps its
+    existing allow early-return.
+
+.NOTES
+    Compatible with PowerShell 7+. No external module dependencies, no filesystem
+    access, no subprocess, no network, and no wall-clock read. Mirrored
+    byte-identically under extensions/drm-copilot/resources/claude-customizations/.
+#>
+
+Set-StrictMode -Version Latest
+
+# Anomaly codes. These are the only values Get-ClaudeHookPayloadAnomalyReason maps.
+$script:AnomalyEmptyPayload = 'EmptyPayload'
+$script:AnomalyUnparseableJson = 'UnparseableJson'
+$script:AnomalyMissingToolInput = 'MissingToolInput'
+$script:AnomalyNullToolInput = 'NullToolInput'
+$script:AnomalyNonObjectToolInput = 'NonObjectToolInput'
+
+# The nested key that carries the tool arguments in the documented envelope.
+$script:ToolInputKey = 'tool_input'
+
+# Deny reason text per anomaly code. Each string is distinct so an operator can
+# tell which leg of the contract drifted from the emitted decision alone.
+$script:AnomalyReasonText = @{
+    'EmptyPayload'       = 'the hook received an empty payload on stdin and on both environment-variable fallbacks'
+    'UnparseableJson'    = 'the hook received a payload that is not parseable JSON'
+    'MissingToolInput'   = 'the hook received a JSON payload with no tool_input key (the legacy flat root shape is an envelope anomaly, not a supported payload)'
+    'NullToolInput'      = 'the hook received a JSON payload whose tool_input is null'
+    'NonObjectToolInput' = 'the hook received a JSON payload whose tool_input is not an object'
+}
+
+function Get-ClaudeHookPayloadAnomalyCode {
+    <#
+    .SYNOPSIS
+        Return the anomaly codes this module can emit, so callers need not
+        hard-code the literals in a second place.
+    .OUTPUTS
+        System.String[]
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param()
+
+    return [string[]]@(
+        $script:AnomalyEmptyPayload,
+        $script:AnomalyUnparseableJson,
+        $script:AnomalyMissingToolInput,
+        $script:AnomalyNullToolInput,
+        $script:AnomalyNonObjectToolInput
+    )
+}
+
+function Get-ClaudeHookPayloadAnomalyReason {
+    <#
+    .SYNOPSIS
+        Map an anomaly code to the clause a hook puts in its deny reason.
+    .PARAMETER Anomaly
+        One of the codes returned by Get-ClaudeHookPayloadAnomalyCode.
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Anomaly
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Anomaly)) {
+        return 'the hook received an unclassified payload anomaly'
+    }
+    if ($script:AnomalyReasonText.ContainsKey($Anomaly)) {
+        return [string]$script:AnomalyReasonText[$Anomaly]
+    }
+    return ('the hook received an unrecognized payload anomaly ({0})' -f $Anomaly)
+}
+
+function ConvertTo-ClaudeHookPayloadResult {
+    <#
+    .SYNOPSIS
+        Build the typed result every parse/extract function returns: IsValid, Value
+        (the parsed envelope or extracted tool_input), and Anomaly (null when
+        valid). Always an object, so no caller tests for null first.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)]
+        [bool] $IsValid,
+
+        [AllowNull()]
+        [object] $Value,
+
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Anomaly
+    )
+
+    $normalizedAnomaly = $null
+    if (-not [string]::IsNullOrWhiteSpace($Anomaly)) {
+        $normalizedAnomaly = [string]$Anomaly
+    }
+
+    return [pscustomobject]@{
+        IsValid = $IsValid
+        Value   = $Value
+        Anomaly = $normalizedAnomaly
+    }
+}
+
+function Read-ClaudeHookRawPayload {
+    <#
+    .SYNOPSIS
+        Acquire the raw hook payload text, stdin first.
+
+    .DESCRIPTION
+        Ordering: stdin, then the CLAUDE_HOOK_INPUT environment variable, then the
+        CLAUDE_TOOL_INPUT environment variable. The first non-whitespace source
+        wins; when every source is empty or whitespace the function returns an empty
+        string, which callers classify as the EmptyPayload anomaly.
+
+        The stdin read is guarded by a redirect probe. An unguarded
+        [Console]::In.ReadToEnd() blocks indefinitely on a non-redirected console,
+        which would hang the documented manual/CLI invocation of validate-bash.ps1.
+        The guard lives in this function body rather than inside the read seam's
+        default so a test can drive both polarities by injection. A stdin read that
+        throws falls back rather than propagating (persist-session-id.ps1 precedent).
+
+    .PARAMETER ReadStandardInput
+        Seam for the stdin read. Default is the bare [Console]::In.ReadToEnd().
+    .PARAMETER TestStandardInputRedirected
+        Seam for the redirect probe. Default is [Console]::IsInputRedirected. When
+        it evaluates falsey, stdin is treated as empty and the env fallback runs.
+    .PARAMETER HookInputFallback
+        Seam for the first environment fallback.
+    .PARAMETER ToolInputFallback
+        Seam for the second environment fallback.
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [scriptblock] $ReadStandardInput = { [Console]::In.ReadToEnd() },
+
+        [scriptblock] $TestStandardInputRedirected = { [Console]::IsInputRedirected },
+
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $HookInputFallback = $env:CLAUDE_HOOK_INPUT,
+
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $ToolInputFallback = $env:CLAUDE_TOOL_INPUT
+    )
+
+    $raw = ''
+
+    $isRedirected = $false
+    try {
+        $isRedirected = [bool](& $TestStandardInputRedirected)
+    } catch {
+        $isRedirected = $false
+    }
+
+    if ($isRedirected) {
+        try {
+            $raw = [string](& $ReadStandardInput)
+        } catch {
+            $raw = ''
+        }
+    }
+
+    if (-not [string]::IsNullOrWhiteSpace($raw)) {
+        return $raw
+    }
+
+    if (-not [string]::IsNullOrWhiteSpace($HookInputFallback)) {
+        return [string]$HookInputFallback
+    }
+
+    if (-not [string]::IsNullOrWhiteSpace($ToolInputFallback)) {
+        return [string]$ToolInputFallback
+    }
+
+    return ''
+}
+
+function ConvertFrom-ClaudeHookEnvelope {
+    <#
+    .SYNOPSIS
+        Parse raw hook payload text into the envelope object.
+
+    .DESCRIPTION
+        Strips a UTF-8 byte-order mark and normalizes CRLF before parsing, because
+        stdin text arrives with either line ending and a BOM survives a piped read.
+        Never returns a silent null for malformed input: an empty or whitespace-only
+        payload yields the EmptyPayload anomaly and unparseable text yields the
+        UnparseableJson anomaly.
+
+    .PARAMETER Raw
+        The raw payload text from Read-ClaudeHookRawPayload.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject (typed result)
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Raw
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Raw)) {
+        return ConvertTo-ClaudeHookPayloadResult -IsValid $false -Value $null -Anomaly $script:AnomalyEmptyPayload
+    }
+
+    # A BOM decoded into the string appears as U+FEFF and makes ConvertFrom-Json fail.
+    $text = ([string]$Raw).TrimStart([char]0xFEFF)
+    $text = $text.Replace("`r`n", "`n")
+
+    if ([string]::IsNullOrWhiteSpace($text)) {
+        return ConvertTo-ClaudeHookPayloadResult -IsValid $false -Value $null -Anomaly $script:AnomalyEmptyPayload
+    }
+
+    try {
+        $envelope = $text | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        return ConvertTo-ClaudeHookPayloadResult -IsValid $false -Value $null -Anomaly $script:AnomalyUnparseableJson
+    }
+
+    if ($null -eq $envelope) {
+        return ConvertTo-ClaudeHookPayloadResult -IsValid $false -Value $null -Anomaly $script:AnomalyUnparseableJson
+    }
+
+    return ConvertTo-ClaudeHookPayloadResult -IsValid $true -Value $envelope -Anomaly $null
+}
+
+function Test-ClaudeHookEnvelopeHasKey {
+    <#
+    .SYNOPSIS
+        Report whether a parsed JSON object (PSCustomObject or dictionary) carries a
+        named key, without throwing under StrictMode.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()]
+        [object] $Envelope,
+
+        [Parameter(Mandatory)]
+        [string] $Name
+    )
+
+    if ($null -eq $Envelope) {
+        return $false
+    }
+    if ($Envelope -is [System.Collections.IDictionary]) {
+        return $Envelope.Contains($Name)
+    }
+    if ($Envelope -isnot [psobject]) {
+        return $false
+    }
+    return (@($Envelope.PSObject.Properties.Name) -contains $Name)
+}
+
+function Get-ClaudeHookEnvelopeValue {
+    <#
+    .SYNOPSIS
+        Read a named value off a parsed JSON object, returning null when the key is
+        absent rather than throwing under StrictMode.
+    .OUTPUTS
+        System.Object or null
+    #>
+    [CmdletBinding()]
+    param(
+        [AllowNull()]
+        [object] $Envelope,
+
+        [Parameter(Mandatory)]
+        [string] $Name
+    )
+
+    if (-not (Test-ClaudeHookEnvelopeHasKey -Envelope $Envelope -Name $Name)) {
+        return $null
+    }
+    if ($Envelope -is [System.Collections.IDictionary]) {
+        return $Envelope[$Name]
+    }
+    return $Envelope.PSObject.Properties[$Name].Value
+}
+
+function Test-ClaudeHookObjectValue {
+    <#
+    .SYNOPSIS
+        Report whether a parsed JSON value is an object rather than a scalar or an
+        array. ConvertFrom-Json produces a PSCustomObject for a JSON object, a
+        native scalar for a scalar, and an array for a JSON array; only the first is
+        a usable tool_input.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()]
+        [object] $Value
+    )
+
+    if ($null -eq $Value) {
+        return $false
+    }
+    if ($Value -is [System.Collections.IDictionary]) {
+        return $true
+    }
+    if ($Value -is [string] -or $Value -is [bool] -or $Value -is [ValueType]) {
+        return $false
+    }
+    if ($Value -is [System.Collections.IEnumerable]) {
+        return $false
+    }
+    return ($Value -is [psobject])
+}
+
+function Get-ClaudeHookToolInput {
+    <#
+    .SYNOPSIS
+        Extract the envelope's nested tool_input object. Strict: no flat-root
+        fallback.
+
+    .DESCRIPTION
+        A parsed payload with no tool_input key is the MissingToolInput anomaly,
+        which is exactly what the legacy flat root shape produces. A tool_input
+        present but null is NullToolInput; present but not an object is
+        NonObjectToolInput. Absence of a property inside a well-formed tool_input is
+        not handled here at all: that stays each hook's own scope filter.
+
+    .PARAMETER Envelope
+        The parsed envelope object from ConvertFrom-ClaudeHookEnvelope.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject (typed result)
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [AllowNull()]
+        [object] $Envelope
+    )
+
+    if ($null -eq $Envelope) {
+        return ConvertTo-ClaudeHookPayloadResult -IsValid $false -Value $null -Anomaly $script:AnomalyMissingToolInput
+    }
+
+    if (-not (Test-ClaudeHookEnvelopeHasKey -Envelope $Envelope -Name $script:ToolInputKey)) {
+        return ConvertTo-ClaudeHookPayloadResult -IsValid $false -Value $null -Anomaly $script:AnomalyMissingToolInput
+    }
+
+    $toolInput = Get-ClaudeHookEnvelopeValue -Envelope $Envelope -Name $script:ToolInputKey
+
+    if ($null -eq $toolInput) {
+        return ConvertTo-ClaudeHookPayloadResult -IsValid $false -Value $null -Anomaly $script:AnomalyNullToolInput
+    }
+
+    if (-not (Test-ClaudeHookObjectValue -Value $toolInput)) {
+        return ConvertTo-ClaudeHookPayloadResult -IsValid $false -Value $null -Anomaly $script:AnomalyNonObjectToolInput
+    }
+
+    return ConvertTo-ClaudeHookPayloadResult -IsValid $true -Value $toolInput -Anomaly $null
+}
+
+function Get-ClaudeHookToolInputString {
+    <#
+    .SYNOPSIS
+        Read a named string property off an already-extracted tool_input object.
+
+    .DESCRIPTION
+        Property-level tolerance lives here: an absent property returns an empty
+        string, which every hook already treats as "out of my scope, allow". This
+        helper exists only so the hooks do not each re-implement the StrictMode-safe
+        property probe.
+
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowNull()]
+        [object] $ToolInput,
+
+        [Parameter(Mandatory)]
+        [string] $Name
+    )
+
+    $value = Get-ClaudeHookEnvelopeValue -Envelope $ToolInput -Name $Name
+    if ($null -eq $value) {
+        return ''
+    }
+    return [string]$value
+}
+
+function Resolve-ClaudeHookToolInput {
+    <#
+    .SYNOPSIS
+        One-call convenience: raw text in, typed tool_input result out.
+
+    .DESCRIPTION
+        Composes ConvertFrom-ClaudeHookEnvelope and Get-ClaudeHookToolInput and
+        additionally surfaces the parsed envelope on the Envelope member, because
+        enforce-epic-invocation-origin.ps1 needs the envelope root (agent_type)
+        alongside the nested tool_input. Returns the envelope-parse anomaly unchanged
+        when the parse fails, so a hook maps a single Anomaly value to a single deny
+        reason.
+
+    .PARAMETER Raw
+        The raw payload text from Read-ClaudeHookRawPayload.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Raw
+    )
+
+    $parsed = ConvertFrom-ClaudeHookEnvelope -Raw $Raw
+    if (-not $parsed.IsValid) {
+        return [pscustomobject]@{
+            IsValid  = $false
+            Value    = $null
+            Envelope = $null
+            Anomaly  = $parsed.Anomaly
+        }
+    }
+
+    $extracted = Get-ClaudeHookToolInput -Envelope $parsed.Value
+    return [pscustomobject]@{
+        IsValid  = $extracted.IsValid
+        Value    = $extracted.Value
+        Envelope = $parsed.Value
+        Anomaly  = $extracted.Anomaly
+    }
+}
+
+Export-ModuleMember -Function `
+    Read-ClaudeHookRawPayload, `
+    ConvertFrom-ClaudeHookEnvelope, `
+    Get-ClaudeHookToolInput, `
+    Resolve-ClaudeHookToolInput, `
+    Get-ClaudeHookEnvelopeValue, `
+    Test-ClaudeHookEnvelopeHasKey, `
+    Test-ClaudeHookObjectValue, `
+    Get-ClaudeHookToolInputString, `
+    Get-ClaudeHookPayloadAnomalyCode, `
+    Get-ClaudeHookPayloadAnomalyReason

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

@@ -233,11 +233,69 @@ Three constraints bound the mandate-read exclusion:
    detection compares the declared radius against the paths a diff actually touched, so an item that
    wrote an excluded path is caught against observed evidence rather than against prose.
 
-The extractor additionally rejects three token shapes that were never write claims: a wildcard-free
+The extractor additionally rejects four token shapes that were never write claims: a wildcard-free
 token whose final component names a directory rather than a file, a `docs/features/` glob whose
-wildcard occupies or truncates the feature-folder segment, and a contract token carrying no ASCII
-letter. `artifacts/` is not a known top-level segment, so a bare `artifacts/**` subtree claim no
-longer satisfies the shape rules.
+wildcard occupies or truncates the feature-folder segment, a contract token carrying no ASCII
+letter, and a token containing a placeholder or interpolation marker. `artifacts/` is not a known
+top-level segment, so a bare `artifacts/**` subtree claim no longer satisfies the shape rules.
+
+### Placeholder-shape rejection (issue #502)
+
+The fourth shape is a token containing any member of the marker set
+
+```text
+<    >    ${    $(    %
+```
+
+The set is not a configuration key and is not read from `config/blast-radius.json`. It originates in
+the checkable-literal placeholder guard defined in `.claude/rules/plan-acceptance-gates.md`, which
+uses the identical five markers to decide that a plan operand documents a command *shape* rather
+than stating a real assertion. Both subsystems answer the same question about the same text, so the
+two vocabularies are pinned equal by test rather than left to convention.
+
+**A marker-bearing token never matches a tracked path.** A placeholder or interpolation form
+resolves at run time to text that is not in the token, so the token as written names nothing. For
+the two angle brackets the claim is stronger than a heuristic: Windows forbids both characters in a
+filename outright, so an angle-bracketed token cannot name a file on the platform this repository is
+developed on. Admitting such a token recorded a `paths` entry that no diff could ever touch, and two
+items citing the identical shape then acquired a `path_overlap` edge on a string that resolves to
+nothing.
+
+**The dominant token is a mandated artifact shape, which is why the exposure was corpus-wide rather
+than incidental.** Every agent in this repository is instructed to write its evidence to the
+canonical scheme defined in `.claude/skills/evidence-and-timestamp-conventions/SKILL.md`, and that
+scheme is non-overridable, so a well-formed plan quotes the same feature-relative artifact shape
+that every other well-formed plan quotes. The shape is therefore the most widely shared token in the
+corpus, and admitting it made compliance with the evidence-path scheme a source of contention. The
+same reasoning applies to the feature-document shapes and to the session-keyed state-file shape.
+
+**The planner remains obliged to enumerate a genuine write explicitly.** This rejection describes a
+plan that documents a shape, not a permanent ban on the paths a shape resembles. When an item's plan
+will actually write a path it expressed as a shape, the planner appends that exact concrete path to
+the declared radius after normalization. This is the same obligation constraint 1 of the
+mandate-read exclusion imposes, and `detect_escaped_paths` is the same backstop: drift detection
+compares the declared radius against the paths a diff actually touched, so an item that wrote a path
+it expressed only as a shape is caught against observed evidence rather than against prose.
+
+**Accepted fail-open trade.** The rejection runs inside the classifier, upstream of shared-surface
+resolution, so a marker-bearing token whose shape matches a configured `shared_surface_globs`
+pattern is dropped before it can be reported as a touched shared surface. The trade is inherent to
+that placement: a guard downstream of surface resolution would leave the token in `paths` and
+reintroduce the path-level false edge it exists to remove. Corpus exposure was measured empty — no
+plan in the 58-plan corpus examined for issue #502 cited a marker-bearing token whose shape matched a
+configured shared-surface glob — and the planner obligation above is what keeps a genuine write
+visible. A later change that widens the marker set must re-take that measurement.
+
+**Known residual: the whitespace split.** Extraction harvests whitespace-free inline-code tokens, so
+a placeholder form written with internal whitespace is split into fragments before the marker test
+ever runs. Each fragment is then judged on its own shape and is normally rejected for an unrelated
+reason, most often for carrying no separator. The residual is therefore benign in the accepting
+direction but is recorded here because it means the rejection is not a complete guard against every
+way a shape can be written; it is a guard against the whitespace-free forms the extractor actually
+admits.
+
+Enforcement of this rejection is prose plus validator logic, exactly as for the three shapes above.
+No JSON Schema is authored, imported, or read for it, and `config/blast-radius.json` gains no key.
 
 ### Module-map granularity criterion
 
@@ -257,6 +315,69 @@ weakens the relation below the path level: two items editing the same file still
 A candidate module belongs in the map when it names a subsystem an item could plausibly not touch.
 A candidate that matches the majority of work items belongs nowhere.
 
+### The published truth table is not a copy of this one (issue #500)
+
+The push-down publishes a second truth table into a destination workspace at
+`extensions/drm-copilot/resources/claude-customizations/config/blast-radius.json`. That copy stood
+stale after issue #489 corrected only the self-hosted one, and correcting it fixed contention in
+both directions at once. Three points fix the relation between the two copies so a later maintainer
+does not re-synchronise them by hand.
+
+**A destination's module map is DERIVED, so the bundled `modules` key is not consumed.**
+`assembleModules` in `extensions/drm-copilot/src/lib/push-down/claude-blast-radius-derive-core.ts`
+computes a destination's module map from the destination's OWN layout — the manifest-bearing
+directories its scan observes — unioned with `PAYLOAD_MODULES`. It never reads the source document's
+`modules` key. The bundled `modules` key is retained rather than deleted only so that a maintainer
+reading the file is not told something false, and because
+`tests/scripts/dev_tools/test_blast_radius_config.py` calls `load_module_globs` on it and that
+helper raises on an absent key. Nothing schedules on it.
+
+**`PAYLOAD_MODULES` carries `config` only.** `claude-runtime` was removed from it by the same
+granularity criterion that removed it from this repository's own map. The criterion transfers
+without modification: every agent in the runtime is instructed to read the policy rules and process
+skills before doing any work, so a `.claude/**` umbrella matches nearly every radius in a
+destination exactly as it did here. The no-signal floor is preserved because `config/**` in a
+destination holds only the two published files, which makes `config` a subsystem an item can
+plausibly not touch and keeps the assembled map non-empty so the forbidden-glob guard has a
+non-vacuous input.
+
+**The bundled `shared_surfaces` and `shared_surface_globs` sets are the destination-portable
+subset, not a copy of the self-hosted sets.** They were authored narrow when the bundled copy was
+created and were never a copy that fell behind, so the correct gate is portable-set equality against
+a declared constant plus a subset relation against the self-hosted list — never byte-equality with
+the self-hosted file. Only `version`, `over_breadth_fraction`, and `mandate_reads` are byte-equal
+across the two copies.
+
+The reason the two key groups take different relations is an asymmetry between surfaces and modules.
+An over-matching MODULE glob costs concurrency on every pair of items it touches, because a module
+that fires for both radii forces contention whether or not the items are related. A SURFACE or
+mandate-read entry naming a path the destination lacks is inert: it matches nothing, so it costs
+nothing. Erring wide is therefore free on the surface side and expensive on the module side, which
+is why the portable surface set carries ecosystem-standard root filenames a given destination may
+not have. A separator-free shared surface carries additional weight: it is the sole gate on whether
+the path-token extractor accepts a separator-free token at all, so a published table with no
+separator-free surface entry cannot detect two items rewriting the same root build file, whatever
+that file is named.
+
+**A directional invariant closes the residual Class 2 gap (issue #500 remediation).** Portable-set
+equality against the declared portable-surface constant and the `bundled <= self_hosted` subset
+relation together do not observe the self-hosted copy gaining a portable separator-free surface
+that never reaches the bundle: both checks are satisfied by a bundled set that stays fixed while
+the self-hosted set grows around it. `test_every_separator_free_self_hosted_shared_surface_reaches_the_bundle`
+in `tests/scripts/dev_tools/test_blast_radius_config_parity.py`, mirrored in
+`tests/scripts/claude-lib/blast-radius/BlastRadius.KeyPartition.Tests.ps1`, closes that gap
+structurally by asserting the reverse containment for separator-free entries: every separator-free
+self-hosted `shared_surfaces` entry must also appear in the bundled separator-free set.
+
+**The key-partition gate now asserts exhaustiveness (issue #500 remediation, R8).** The three
+declared classes each assert a property of the keys they name, but none of them asserted that
+the two committed copies' top-level key sets are identical, or that every top-level key
+belongs to one of the three declared classes. `test_every_top_level_key_is_classified_and_shared_by_both_copies`
+in `tests/scripts/dev_tools/test_blast_radius_config_parity.py`, mirrored in
+`tests/scripts/claude-lib/blast-radius/BlastRadius.KeyPartition.Tests.ps1`, closes that gap: the
+union of both copies' top-level keys is exhaustively covered by the three declared classes, and
+an unclassified key or a key present in only one copy fails loudly and names itself.
+
 ## Enforcement
 
 - `scripts/dev_tools/validate_parallel_orchestrator_state.py`, with the helper modules `scripts/dev_tools/_parallel_state_common.py`, `scripts/dev_tools/_parallel_state_structures.py`, and `scripts/dev_tools/_parallel_state_records.py`, appends one error per violated orchestrator invariant. The completion-gate invariants 20 and 21 run only when the caller passes `require_complete=True`.

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

@@ -173,6 +173,33 @@ integration-to-main PR.
 The `## Invocation Prompt` section is the exact text the user replays (from the main session,
 never from an `orchestrator` agent) to launch execution.
 
+### Integration Commit Form (issue #539)
+
+The epic planner's own version-control operations — committing the epic manifest, the fanned-in
+child feature folders and approved plans, and the durable kickoff copy — are orchestration
+bookkeeping, not implementation. The preimplementation gate
+(`.claude/hooks/enforce-orchestration-preimplementation-gate.ps1`) exempts them only when the
+invocation is **pathspec-bearing**: every staging or integration invocation must name at least one
+explicit path operand, and every operand must resolve inside one of the five exempt
+orchestration-bookkeeping trees:
+
+- `docs/features/epics/`
+- `docs/features/parallel/`
+- `docs/features/active/`
+- `docs/features/potential/`
+- `artifacts/orchestration/`
+
+Use one of the two pathspec-bearing spellings:
+
+- the message option followed by a double-dash separator and then the exempt path operands, or
+- the exempt path operands named directly before the message option.
+
+A pathless integration invocation — a message option with no path operand — is denied (D4 row 4),
+as are whole-tree operands, tree-wide flags, pathspec-from-file options, history-rewriting or
+content-widening options, and any operand that resolves outside the five exempt trees. Mixing one
+exempt operand with one production operand denies the whole invocation. Name each exempt path
+explicitly; the exemption is allow-side only and every parse ambiguity denies.
+
 ## Checkpoint Handling
 
 Persist `artifacts/orchestration/epic-planner-state.json` after every completed step with the