@danmoisan/drm-copilot-mcp 1.1.9 → 1.1.11

package/resources/claude-customizations/.claude/lib/project-file-merge/Resolve-MergeableConflict.ps1

@@ -0,0 +1,229 @@
+<#
+.SYNOPSIS
+    Resolve mechanically-mergeable project-file conflicts in a worktree.
+
+.DESCRIPTION
+    Entry point for the parent-side project-file merge step of issue #643. It
+    lists the conflicted paths of a worktree left by an in-progress merge,
+    refuses the whole set unless every path belongs to the mergeable class, and
+    otherwise rewrites each conflicted file as the keyed union of the two sides.
+
+    The script stages nothing and creates no revision: the caller owns those
+    steps, so a resolution this script produces is always inspectable before it
+    becomes history. It writes one compressed JSON object to stdout and exits 0
+    for both verdicts; the verdict is that object's result field. A non-zero exit
+    means an unexpected error, whose message is on stderr.
+
+.PARAMETER Worktree
+    Absolute or relative path to the worktree holding the conflicted merge.
+
+.PARAMETER ConfigPath
+    Truth table to read mergeable_paths from. Defaults to the worktree's own
+    config/blast-radius.json.
+#>
+param(
+    [string] $Worktree,
+    [string] $ConfigPath
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# The merge module is imported before the grammar module it nests. Reversing the
+# two would leave the grammar unavailable here: the nested -Force import inside
+# ProjectFileMerge.psm1 removes an already-loaded grammar module and re-imports it
+# into that module's own scope, taking its commands out of this scope.
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'ProjectFileMerge.psm1') -Force -ErrorAction Stop
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'ProjectFileMergeGrammar.psm1') -Force -ErrorAction Stop
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath '../blast-radius/BlastRadiusConflict.psm1') -Force -ErrorAction Stop
+
+# The three bytes a UTF-8 byte-order mark occupies, kept as a constant so the
+# reader and the writer agree on one prefix.
+$script:ByteOrderMark = [byte[]] @(0xEF, 0xBB, 0xBF)
+
+# Splits a text into lines that each retain their own terminator, which is what
+# lets a CRLF file survive a merge unchanged.
+$script:LinePattern = '[^\r\n]*(?:\r\n|\n|\r)'
+
+function Invoke-GitExe {
+    <#
+    .SYNOPSIS
+        The single executable seam of this script.
+    .DESCRIPTION
+        Every git invocation goes through here, so a test mocks one function
+        rather than an executable. A non-zero exit throws with the output.
+    #>
+    [CmdletBinding()]
+    # The unary comma wraps the result so the pipeline does not unroll a
+    # one-element collection, which makes the emitted object an Object[]
+    # carrying strings rather than a bare string[]. Both are declared.
+    [OutputType([string[]], [System.Object[]])]
+    param([Parameter(Mandatory = $true)][AllowEmptyCollection()][string[]] $GitArgs)
+
+    $output = & git @GitArgs 2>&1
+    # A failed git call is never a resolvable state, so it stops the run.
+    if ($LASTEXITCODE -ne 0) {
+        throw ('git {0} exited {1}: {2}' -f ($GitArgs -join ' '), $LASTEXITCODE, ($output -join ' '))
+    }
+    return , @($output | ForEach-Object { [string] $_ })
+}
+
+function Read-ConflictedFile {
+    <#
+    .SYNOPSIS
+        Read a conflicted file as bytes, a mark flag, and terminator-bearing lines.
+    .DESCRIPTION
+        Decoding is strict UTF-8. A file that does not decode returns $null, which
+        the caller turns into an escalation rather than a lossy rewrite.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param([Parameter(Mandatory = $true)][string] $Path)
+
+    $bytes = [System.IO.File]::ReadAllBytes($Path)
+    $hasBom = $bytes.Length -ge 3 -and $bytes[0] -eq $script:ByteOrderMark[0] -and $bytes[1] -eq $script:ByteOrderMark[1] -and $bytes[2] -eq $script:ByteOrderMark[2]
+    try {
+        $text = [System.Text.UTF8Encoding]::new($false, $true).GetString($bytes)
+    } catch [System.Text.DecoderFallbackException] {
+        return $null
+    }
+    # The decoded mark is metadata, not content; the writer restores it.
+    if ($hasBom) { $text = $text.Substring(1) }
+
+    $line = [System.Collections.Generic.List[string]]::new()
+    foreach ($match in [regex]::Matches($text, $script:LinePattern)) { $line.Add($match.Value) }
+    # A final line with no terminator is not matched above and is added here.
+    $consumed = ($line -join '').Length
+    if ($consumed -lt $text.Length) { $line.Add($text.Substring($consumed)) }
+
+    return [pscustomobject]@{ Bytes = $bytes; HasBom = $hasBom; Line = $line.ToArray() }
+}
+
+function Write-MergedFile {
+    <#
+    .SYNOPSIS
+        Write merged lines back over the conflicted file.
+    .DESCRIPTION
+        The byte array is assembled before the ShouldProcess guard, so -WhatIf
+        exercises the whole assembly and suppresses only the write itself.
+    #>
+    [CmdletBinding(SupportsShouldProcess = $true)]
+    [OutputType([void])]
+    param(
+        [Parameter(Mandatory = $true)][string] $Path,
+        [Parameter(Mandatory = $true)][AllowEmptyCollection()][AllowEmptyString()][string[]] $Line,
+        [Parameter(Mandatory = $true)][bool] $HasBom
+    )
+
+    $body = [System.Text.UTF8Encoding]::new($false).GetBytes($Line -join '')
+    $payload = [System.Collections.Generic.List[byte]]::new()
+    # A file that carried a mark keeps it, because dropping it is a byte change
+    # no reviewer asked for.
+    if ($HasBom) { $payload.AddRange($script:ByteOrderMark) }
+    $payload.AddRange($body)
+    if ($PSCmdlet.ShouldProcess($Path, 'Write the merged project file')) {
+        [System.IO.File]::WriteAllBytes($Path, $payload.ToArray())
+    }
+}
+
+function ConvertTo-ResolutionResult {
+    <#
+    .SYNOPSIS
+        Build the single result record this script emits.
+    .DESCRIPTION
+        The three keys are the whole published contract, so they are written in
+        one place rather than at each return site.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory = $true)][string] $ResultName,
+        [AllowEmptyCollection()][object[]] $Resolved = @(),
+        [AllowEmptyCollection()][AllowEmptyString()][string[]] $EscalatePath = @()
+    )
+
+    return [ordered]@{ result = $ResultName; resolved = $Resolved; escalate_paths = $EscalatePath }
+}
+
+function Invoke-MergeableConflictResolution {
+    <#
+    .SYNOPSIS
+        Resolve every conflicted path of a worktree, or escalate the whole set.
+    .DESCRIPTION
+        The set is all-or-nothing. One non-mergeable path escalates before any
+        file is read, and one unresolvable file escalates before any file is
+        written, so a partially merged worktree is not a reachable state.
+    .PARAMETER Worktree
+        The worktree holding the conflicted merge.
+    .PARAMETER ConfigPath
+        Truth table carrying mergeable_paths; the worktree default is used when
+        this is blank.
+    .OUTPUTS
+        An ordered record carrying result, resolved, and escalate_paths.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory = $true)][string] $Worktree,
+        [AllowNull()][AllowEmptyString()][string] $ConfigPath
+    )
+
+    if ([string]::IsNullOrWhiteSpace($ConfigPath)) { $ConfigPath = Join-Path -Path $Worktree -ChildPath 'config/blast-radius.json' }
+    $config = Get-Content -LiteralPath $ConfigPath -Raw | ConvertFrom-Json
+    $mergeable = @(Get-ConfigMergeablePath -Config $config)
+
+    # The listing is bound before it is filtered: Invoke-GitExe returns one array
+    # object, so piping it directly would hand the whole array to the filter.
+    $listed = Invoke-GitExe -GitArgs @('-C', $Worktree, 'diff', '--name-only', '--diff-filter=U')
+    $conflicted = @($listed | Where-Object { -not [string]::IsNullOrWhiteSpace($_) })
+    $outside = @($conflicted | Where-Object { -not (Test-MergeablePath -Entry $_ -MergeablePath $mergeable) })
+    # Classification happens first so a non-mergeable set costs no file read.
+    if ($outside.Count -gt 0) { return (ConvertTo-ResolutionResult -ResultName 'escalate' -EscalatePath $outside) }
+
+    $pending = [System.Collections.Generic.List[object]]::new()
+    foreach ($path in $conflicted) {
+        $kind = Get-ProjectFileKind -Path $path
+        if ($null -eq $kind) { return (ConvertTo-ResolutionResult -ResultName 'escalate' -EscalatePath @($path)) }
+        $file = Read-ConflictedFile -Path (Join-Path -Path $Worktree -ChildPath $path)
+        if ($null -eq $file) { return (ConvertTo-ResolutionResult -ResultName 'escalate' -EscalatePath @($path)) }
+
+        $outcome = Merge-ConflictedText -Line $file.Line -Kind $kind
+        if ($outcome.Escalate) { return (ConvertTo-ResolutionResult -ResultName 'escalate' -EscalatePath @($path)) }
+
+        # The three stages are the only authority on what the merge must keep.
+        # Each is bound directly, because Invoke-GitExe already returns one array
+        # and an array subexpression around it would nest that array inside another.
+        $ours = Invoke-GitExe -GitArgs @('-C', $Worktree, 'show', ":2:$path")
+        $theirs = Invoke-GitExe -GitArgs @('-C', $Worktree, 'show', ":3:$path")
+        $base = Invoke-GitExe -GitArgs @('-C', $Worktree, 'show', ":1:$path")
+        $isKept = Test-NeverDropPostCondition -MergedLine $outcome.Lines -OursLine $ours -TheirsLine $theirs -BaseLine $base -Kind $kind
+        if (-not $isKept) { return (ConvertTo-ResolutionResult -ResultName 'escalate' -EscalatePath @($path)) }
+
+        $pending.Add([pscustomobject]@{
+                Path   = $path
+                HasBom = $file.HasBom
+                Line   = $outcome.Lines
+                Record = [ordered]@{
+                    path                      = $path
+                    entries_added_from_ours   = @($outcome.EntriesAddedFromOurs)
+                    entries_added_from_theirs = @($outcome.EntriesAddedFromTheirs)
+                    version_resolutions       = @($outcome.VersionResolutions)
+                }
+            })
+    }
+
+    # Every path resolved, so the worktree can be rewritten in one pass.
+    foreach ($item in $pending) {
+        Write-MergedFile -Path (Join-Path -Path $Worktree -ChildPath $item.Path) -Line $item.Line -HasBom $item.HasBom
+    }
+    return (ConvertTo-ResolutionResult -ResultName 'resolved' -Resolved @($pending | ForEach-Object { $_.Record }))
+}
+
+# Dot-sourcing loads the functions for a test host; any other invocation runs the
+# step. The guard is the precedent set by Invoke-ReleaseReconciliation.ps1.
+if ($MyInvocation.InvocationName -ne '.') {
+    if ([string]::IsNullOrWhiteSpace($Worktree)) { throw 'Worktree is required.' }
+    $result = Invoke-MergeableConflictResolution -Worktree $Worktree -ConfigPath $ConfigPath
+    Write-Output (ConvertTo-Json -InputObject $result -Depth 6 -Compress)
+    exit 0
+}

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

@@ -260,6 +260,61 @@ wildcard occupies or truncates the feature-folder segment, a contract token carr
 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.
 
+### Mechanically-mergeable path class (issue #643)
+
+Some contended paths are not a design collision. A `.csproj` item list, a `packages.config` package
+list, and an `app.config` binding-redirect list are additive registries: two items that each append a
+distinct entry produce a textual conflict that a deterministic union resolves without judgement.
+Serializing those items buys nothing.
+
+`config/blast-radius.json` carries an optional `mergeable_paths` list of exact entries and `**`
+globs. That list is the mechanically-mergeable path class. Its published default is the five-entry
+list `**/*.csproj`, `**/packages.config`, `**/app.config`, `**/*.vbproj`, `**/*.props`.
+
+A matching path **stays in the declared `paths`**. The exclusion is applied at exactly one place per
+runtime — inside `conflicts` (`scripts/dev_tools/_blast_radius_conflicts.py`) and inside
+`Test-BlastRadiusConflict` (`.claude/lib/blast-radius/BlastRadius.psm1`), on both radii's `paths`
+immediately before the smallest-path-overlap computation. Derivation, normalization,
+observed-radius construction, V1, V2, V3, and `detect_escaped_paths` are therefore unchanged: the
+class narrows one comparison and nothing else. The key is optional and fail-closed: a truth table
+that omits it excludes nothing and reproduces pre-change behaviour exactly.
+
+The matcher is local to this comparison and does not extend the glob engine. A declared path matches
+the class when, against some configured entry, any of the following holds: the two strings are
+ordinally equal; or the declared path is concrete (carries no wildcard) and the configured entry is
+a glob that contains it; or the declared path is concrete and, for a configured entry beginning with
+`**/`, the same two-step test succeeds against the entry with that prefix removed, which is what
+makes a root-level `Directory.Build.props` match `**/*.props`. A declared path that is itself a glob
+is mergeable only when it equals a configured entry verbatim, because a glob can expand over
+non-mergeable files. `_glob_to_regex_text` (`scripts/dev_tools/_blast_radius_glob.py`) and its
+PowerShell mirror `BlastRadiusGlob.psm1` are unchanged by this class; if either is ever changed, both
+it and this matcher must be re-examined together, since the containment step depends on the glob
+engine's semantics.
+
+Three constraints bound the mergeable-path class:
+
+1. **The planner remains obliged to enumerate a genuine write explicitly.** The class describes how a
+   contention is scored, not what an item may touch. An item that will write a `.csproj` still
+   declares that exact path in its radius.
+2. **The path stays in the declared radius, so the audits still see it.** Nothing is removed from any
+   stored record. Over-breadth, shared-surface, and manifest audits read the same `paths` they read
+   before; only the pairwise overlap set is narrowed.
+3. **`detect_escaped_paths` remains the backstop at execution time.** A mergeable classification is a
+   scheduling decision taken from declared text; `detect_escaped_paths` still compares the declared
+   radius against the paths a diff actually touched, so an item that wrote outside its radius is
+   caught against observed evidence regardless of this class.
+
+An item record of the parallel-orchestrator checkpoint MAY carry an optional
+`mergeable_conflicts_resolved` list recording the mergeable conflicts an item resolved mechanically.
+The field is additive and tolerated-not-validated: no validator in Python, TypeScript, or bash reads
+it, and it follows the `expected_conflict_components` diagnostic precedent — a record written for a
+human reader and for post-hoc audit, never a scheduling input. Each entry carries `path`,
+`resolved_at`, `merged_against`, `merge_commit_sha`, `entries_added_from_ours`,
+`entries_added_from_theirs`, and `version_resolutions`. Entry keys inside those three lists use
+`<ItemType>:<Include>` for MSBuild items, `package:<id>` for `packages.config` packages, and
+`bindingRedirect:<name>` for `app.config` binding redirects. Invariant 9 (the six `blast_radius`
+keys) and invariant 15 (the four edge reasons) are unchanged by this field.
+
 ### Placeholder-shape rejection (issue #502)
 
 The fourth shape is a token containing any member of the marker set
@@ -353,6 +408,15 @@ 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.
 
+**The .NET manifest family is a structure signal, not a module source (issue #643).** `.csproj`,
+`.fsproj`, `.vbproj`, `.sln`, and `.slnx` are classified in
+`extensions/drm-copilot/src/lib/push-down/claude-blast-radius-derive-manifests.ts` as
+structure-observing manifests: each one marks a project root and suppresses the
+top-level-directory fallback, and none of them contributes a module. A .NET solution layout
+therefore derives exactly `{ "config": ["config/**"] }` from `PAYLOAD_MODULES` alone. The reason is
+the granularity criterion: a per-assembly module would fire for the majority of work items in that
+solution, so it discriminates nothing and belongs in neither the module map nor the surface list.
+
 **`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
@@ -366,8 +430,8 @@ non-vacuous input.
 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 self-hosted file. Only `version`, `over_breadth_fraction`, `mandate_reads`, and `mergeable_paths`
+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