@danmoisan/drm-copilot-mcp 1.0.21 → 1.0.23

package/resources/claude-customizations/.claude/lib/bash/validate-parallel-manifest.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# validate-parallel-manifest.sh: destination-portable command-line entry point
+# for parallel-run manifest validation and the two default-resolving accessors.
+# It exists so a workspace that received the Claude customization payload can
+# validate a manifest with nothing but bash -- no Python, no Poetry, no yq, and
+# no repository checkout.
+#
+# Usage:
+#   bash .claude/lib/bash/validate-parallel-manifest.sh <manifest-path>
+#   bash .claude/lib/bash/validate-parallel-manifest.sh --print-mode <manifest-path>
+#   bash .claude/lib/bash/validate-parallel-manifest.sh --print-max-concurrency <manifest-path>
+#
+# Output contract:
+#   stdout  validation errors one per line (empty for a valid manifest), or the
+#           resolved accessor value under --print-mode / --print-max-concurrency
+#   exit 0  the manifest is valid, or the accessor resolved
+#   exit 1  the manifest is invalid
+#   exit 2  usage error, unreadable manifest, or a YAML construct outside the
+#           supported subset
+#
+# The accessors resolve the documented defaults -- `closed` and `4` -- when the
+# manifest omits the key or carries a malformed value, matching
+# manifest_mode and manifest_max_concurrency in the Python authority.
+set -euo pipefail
+
+# Resolve this script's own directory so the library sources regardless of cwd.
+VM_SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=.claude/lib/bash/parallel-manifest-validate.sh
+# shellcheck disable=SC1091
+source "$VM_SCRIPT_DIR/parallel-manifest-validate.sh"
+
+pc_enforce_c_locale
+
+vm_usage() {
+	# Print the entry point's usage text.
+	cat <<'EOF'
+Usage: validate-parallel-manifest.sh [--print-mode | --print-max-concurrency] <manifest-path>
+
+Validates a parallel-run manifest against invariants M1 through M7 and prints
+one error per line on stdout; a valid manifest prints nothing and exits 0.
+
+Options:
+  --print-mode              Print the resolved run mode (default: closed).
+  --print-max-concurrency   Print the resolved fan-out cap (default: 4).
+EOF
+}
+
+vm_require_readable() {
+	# Return 0 when the manifest path names a readable file.
+	#
+	# Args: $1 = manifest path. A missing manifest is an operator error rather
+	# than a validation verdict, so the caller exits 2 instead of reporting it
+	# as a manifest defect.
+	local path="$1"
+	if [[ ! -f $path || ! -r $path ]]; then
+		printf 'validate-parallel-manifest.sh: manifest not found or not readable: %s\n' "$path" >&2
+		return 1
+	fi
+	return 0
+}
+
+vm_report_subset_refusal() {
+	# Print the out-of-subset refusal and exit 2.
+	#
+	# Refusing to answer is deliberate: a guessed parse could disagree with the
+	# Python authority silently, whereas an explicit refusal is visible.
+	printf 'validate-parallel-manifest.sh: manifest uses a YAML construct outside the supported subset: %s\n' \
+		"$PM_SUBSET_DETAIL" >&2
+	exit 2
+}
+
+vm_main() {
+	# Dispatch on the optional accessor flag and run the requested operation.
+	local mode="validate" path="" status=0 text
+	# Routing table: the two accessor flags each consume the following path
+	# argument; anything else is treated as the manifest path itself.
+	case "${1-}" in
+	--print-mode)
+		mode="print-mode"
+		path="${2-}"
+		;;
+	--print-max-concurrency)
+		mode="print-max-concurrency"
+		path="${2-}"
+		;;
+	--help | -h)
+		vm_usage
+		return 0
+		;;
+	-*)
+		vm_usage >&2
+		return 2
+		;;
+	*)
+		path="${1-}"
+		;;
+	esac
+	[[ -n $path ]] || {
+		vm_usage >&2
+		return 2
+	}
+
+	vm_require_readable "$path" || return 2
+	text=$(cat -- "$path")
+	pm_validate_text "$text" || status=$?
+	if ((status == 2)); then
+		vm_report_subset_refusal
+	fi
+
+	# The accessors read the parsed node table, which pm_validate_text has
+	# already populated, so a malformed-but-parseable manifest still resolves.
+	if [[ $mode == "print-mode" ]]; then
+		pm_manifest_mode
+		printf '\n'
+		return 0
+	fi
+	if [[ $mode == "print-max-concurrency" ]]; then
+		pm_manifest_max_concurrency
+		printf '\n'
+		return 0
+	fi
+
+	pc_errors_print
+	(($(pc_errors_count) == 0)) || return 1
+	return 0
+}
+
+# Guard so the file can be sourced without executing main. main's return code
+# is captured and re-exited explicitly as the final statement.
+if [[ ${BASH_SOURCE[0]} == "${0}" ]]; then
+	vm_rc=0
+	vm_main "$@" || vm_rc=$?
+	exit "$vm_rc"
+fi

package/resources/claude-customizations/.claude/lib/blast-radius/BlastRadius.psm1

@@ -0,0 +1,379 @@
+<#
+.SYNOPSIS
+    Blast-radius derivation and the fail-closed contention relation.
+
+.DESCRIPTION
+    Destination-runtime PowerShell facade for the blast-radius library, porting
+    scripts/dev_tools/compute_blast_radius.py (derive_blast_radius,
+    radius_from_observed_paths, _feature_folder_glob) and
+    scripts/dev_tools/_blast_radius_conflicts.py (conflicts,
+    _smallest_path_overlap, _smallest_common). It imports the extraction, glob,
+    truth-table, and validation modules that sit beside it and re-exports the
+    five functions the spec PowerShell surface fixes:
+
+      - Get-PlanPaths                     port of extract_plan_paths
+      - Get-BlastRadius                   port of derive_blast_radius
+      - Get-BlastRadiusFromObservedPaths  port of radius_from_observed_paths
+      - Test-BlastRadius                  port of validate_blast_radius
+      - Test-BlastRadiusConflict          port of conflicts
+
+    The Python modules remain the authoritative reference implementation. This
+    module is one half of a two-language mirror; it never imports validator
+    logic. Every function is pure: no filesystem, subprocess, network, or
+    wall-clock access, and no input is mutated. computed_at is caller supplied,
+    so the library never reads the clock.
+
+    Parity notes for maintainers:
+      - A radius is a hashtable whose key set is exactly paths, modules,
+        shared_surfaces, contracts, source, and computed_at. Hashtable key order
+        is not significant; the key set and the values are the contract.
+      - Every function in this library that mirrors a Python tuple return writes
+        its elements to the pipeline, following the repository's
+        Get-PoshQCFileList convention. Callers must wrap such a call in @(...) to
+        obtain an array, because a zero-element result writes nothing and a
+        one-element result writes a single object. Test-BlastRadius is the one
+        collection-returning function on this facade; Get-BlastRadius,
+        Get-BlastRadiusFromObservedPaths, and Test-BlastRadiusConflict each
+        return a single hashtable.
+      - source is restricted to derived, declared, and observed; anything else,
+        and any malformed input, throws.
+      - The contention relation fails closed: a glob pair that cannot be proven
+        disjoint counts as overlapping, because radius under-reporting is the
+        dominant risk of the parallel design.
+      - Reasons are reported in the fixed kind order path_overlap,
+        module_overlap, shared_surface_overlap, contract_dependency, and each
+        detail is order-normalized so the relation is observably symmetric in its
+        two arguments.
+      - Two empty radii, and an empty radius against a non-empty one, do not
+        conflict. Under-reporting via emptiness is V1's problem at plan time, not
+        the relation's.
+#>
+
+Set-StrictMode -Version Latest
+
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusExtraction.psm1') -Force
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusGlob.psm1') -Force
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusConfig.psm1') -Force
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusValidation.psm1') -Force
+
+# Feature-folder handling. Every radius contains its own feature folder, and a
+# caller may pass either a bare folder name or an already-qualified path.
+$script:FeatureFolderRoot = 'docs/features/active'
+$script:FeatureFolderPrefix = 'docs/features/'
+
+# The default confidence source for derivation, and the source a diff-derived
+# radius always records.
+$script:SourceDerived = 'derived'
+$script:SourceObserved = 'observed'
+
+# Contention reason kinds, in the fixed order every result reports them. These
+# strings are contract literals consumed by the downstream parallel schema.
+$script:ConflictPathOverlap = 'path_overlap'
+$script:ConflictModuleOverlap = 'module_overlap'
+$script:ConflictSharedSurfaceOverlap = 'shared_surface_overlap'
+$script:ConflictContractDependency = 'contract_dependency'
+
+# Separator used in an overlapping-pair detail string. The pair is ordered
+# ordinally before formatting so the detail is identical in both argument orders.
+$script:PairDetailSeparator = ' ~ '
+
+
+# Port of _feature_folder_glob. Accepting an already-qualified path avoids
+# producing a doubled docs/features/active/docs/features/active/... entry when a
+# caller passes the folder path it already holds.
+function Get-FeatureFolderGlob {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $FeatureFolder
+    )
+
+    $trimmed = $FeatureFolder.Trim().Trim('/')
+    if ($trimmed.StartsWith($script:FeatureFolderPrefix, [System.StringComparison]::Ordinal)) {
+        return "$trimmed/**"
+    }
+
+    return "$script:FeatureFolderRoot/$trimmed/**"
+}
+
+function Get-BlastRadius {
+    <#
+    .SYNOPSIS
+        Derive a blast radius from an approved plan and its feature spec.
+
+    .DESCRIPTION
+        Port of derive_blast_radius. Plan task bodies are the primary signal, the
+        spec contributes the paths it cites in inline code, and the feature
+        folder is always present because every work item writes its own documents
+        and evidence. A plan and spec with no extractable paths still yield a
+        radius containing the feature-folder glob.
+
+    .PARAMETER PlanText
+        Approved atomic-plan document text; may be empty.
+
+    .PARAMETER SpecText
+        Feature spec.md document text; may be empty.
+
+    .PARAMETER FeatureFolder
+        Bare feature folder name, or a path that already starts with
+        docs/features/.
+
+    .PARAMETER Config
+        Parsed config/blast-radius.json.
+
+    .PARAMETER Source
+        Confidence source to record; derived by default and declared when a
+        planner adopts the result as authoritative.
+
+    .PARAMETER ComputedAt
+        Caller-supplied ISO-8601 timestamp. The library never reads the clock.
+
+    .OUTPUTS
+        System.Collections.Hashtable. The derived radius, carrying exactly the
+        keys paths, modules, shared_surfaces, contracts, source, and computed_at.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string] $PlanText,
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string] $SpecText,
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string] $FeatureFolder,
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [object] $Config,
+        [string] $Source = $script:SourceDerived,
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string] $ComputedAt
+    )
+
+    [void](Get-RequiredText -Value $PlanText -FieldName 'plan_text' -AllowEmpty)
+    [void](Get-RequiredText -Value $SpecText -FieldName 'spec_text' -AllowEmpty)
+
+    # Both extraction calls read the separator-free root-surface set from the
+    # same -Config value that resolves modules and shared surfaces below. Sharing
+    # one reader with Test-BlastRadius is what preserves the invariant that a
+    # derived radius always passes V1 and V2 against its own plan (issue #452).
+    $rootSurface = [string[]]@(Get-ConfigRootSurface -Config $Config)
+
+    $specLine = [string[]]@(ConvertTo-NormalizedLine -Text $SpecText)
+    $entry = [System.Collections.Generic.List[string]]::new()
+    $entry.AddRange([string[]]@(Get-PlanPaths -PlanText $PlanText -RootSurface $rootSurface))
+    $entry.AddRange([string[]]@(Get-PathFromLine -Line $specLine -RootSurface $rootSurface))
+    $entry.Add((Get-FeatureFolderGlob -FeatureFolder (
+                Get-RequiredText -Value $FeatureFolder -FieldName 'feature_folder')))
+
+    $paths = [string[]]@(Get-OrdinalSortedEntry -Entry $entry.ToArray())
+    $concrete = [string[]]@(Get-ConcreteEntry -Entry $paths)
+
+    return ConvertTo-NormalizedBlastRadius -Radius @{
+        paths           = $paths
+        modules         = @(Resolve-BlastRadiusModule -PathEntry $paths -Config $Config)
+        shared_surfaces = @(Resolve-BlastRadiusSharedSurface -ConcretePath $concrete -Config $Config)
+        contracts       = @(Get-ContractIdentifier -SpecText $SpecText)
+        source          = $Source
+        computed_at     = $ComputedAt
+    }
+}
+
+function Get-BlastRadiusFromObservedPaths {
+    <#
+    .SYNOPSIS
+        Build an observed-source radius from an already-collected path list.
+
+    .DESCRIPTION
+        Port of radius_from_observed_paths. Drift detection supplies the output
+        of a diff listing; the library performs no subprocess call of its own, so
+        the paths arrive as plain strings and are taken verbatim rather than
+        re-classified by the plan-text heuristic. contracts is empty because a
+        diff carries no interface-section text.
+
+    .PARAMETER ObservedPaths
+        Repository-relative paths from a diff, as a collection. A bare string is
+        rejected, matching the Python reference guard.
+
+    .PARAMETER Config
+        Parsed config/blast-radius.json.
+
+    .PARAMETER ComputedAt
+        Caller-supplied ISO-8601 timestamp. The library never reads the clock.
+
+    .OUTPUTS
+        System.Collections.Hashtable. A radius whose source is observed and whose
+        modules and shared surfaces are resolved by the derivation rules.
+    #>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingularNouns', '', Justification = 'The exported name is fixed by the spec PowerShell surface contract for issue #447 and mirrors radius_from_observed_paths.')]
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [object] $ObservedPaths,
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [object] $Config,
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string] $ComputedAt
+    )
+
+    $paths = [string[]]@(Get-RequiredStringList -Value $ObservedPaths -FieldName 'observed_paths')
+    $concrete = [string[]]@(Get-ConcreteEntry -Entry $paths)
+
+    return ConvertTo-NormalizedBlastRadius -Radius @{
+        paths           = $paths
+        modules         = @(Resolve-BlastRadiusModule -PathEntry $paths -Config $Config)
+        shared_surfaces = @(Resolve-BlastRadiusSharedSurface -ConcretePath $concrete -Config $Config)
+        contracts       = @()
+        source          = $script:SourceObserved
+        computed_at     = $ComputedAt
+    }
+}
+
+# Port of _smallest_path_overlap. Each overlapping pair is ordered before it is
+# recorded, so the minimum is taken over a set that does not depend on argument
+# order; that is what makes the reported detail symmetric.
+function Get-SmallestPathOverlap {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $PathA,
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $PathB
+    )
+
+    $detail = [System.Collections.Generic.List[string]]::new()
+    foreach ($entryA in $PathA) {
+        foreach ($entryB in $PathB) {
+            if (-not (Test-EntryOverlap -EntryA $entryA -EntryB $entryB)) {
+                continue
+            }
+            $ordered = if ([string]::CompareOrdinal($entryA, $entryB) -le 0) {
+                @($entryA, $entryB)
+            } else {
+                @($entryB, $entryA)
+            }
+            $detail.Add($ordered -join $script:PairDetailSeparator)
+        }
+    }
+
+    return (Get-OrdinalSmallestEntry -Entry $detail.ToArray())
+}
+
+# Port of _smallest_common. Two empty collections share nothing, so the result is
+# $null and the level contributes no reason.
+function Get-SmallestCommonEntry {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $Left,
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $Right
+    )
+
+    $rightSet = [System.Collections.Generic.HashSet[string]]::new($Right, [StringComparer]::Ordinal)
+    $common = [System.Collections.Generic.List[string]]::new()
+    foreach ($entry in $Left) {
+        if ($rightSet.Contains($entry)) {
+            $common.Add($entry)
+        }
+    }
+
+    return (Get-OrdinalSmallestEntry -Entry $common.ToArray())
+}
+
+function Test-BlastRadiusConflict {
+    <#
+    .SYNOPSIS
+        Decide whether two radii contend, and report every triggered disjunct.
+
+    .DESCRIPTION
+        Port of conflicts. Evaluates the four disjuncts and returns the verdict
+        plus one reason per triggered level in the fixed kind order path_overlap,
+        module_overlap, shared_surface_overlap, contract_dependency. The three
+        set-intersection levels differ only in which collection they read, so one
+        pass over the level table keeps them in the required order without
+        repeating the intersection logic.
+
+    .PARAMETER RadiusA
+        First radius record.
+
+    .PARAMETER RadiusB
+        Second radius record.
+
+    .PARAMETER Config
+        Parsed config/blast-radius.json. The relation reads no key from it today;
+        it is validated and kept in the signature because the contract is frozen
+        for downstream consumers.
+
+    .OUTPUTS
+        System.Collections.Hashtable. Keys conflict (a boolean) and reasons (an
+        array of hashtables with keys kind and detail).
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [object] $RadiusA,
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [object] $RadiusB,
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [object] $Config
+    )
+
+    [void](Get-RequiredMapping -Value $Config -FieldName 'config')
+    $left = ConvertTo-NormalizedBlastRadius -Radius $RadiusA
+    $right = ConvertTo-NormalizedBlastRadius -Radius $RadiusB
+
+    $reason = [System.Collections.Generic.List[hashtable]]::new()
+    $pathDetail = Get-SmallestPathOverlap -PathA ([string[]]@($left['paths'])) `
+        -PathB ([string[]]@($right['paths']))
+    if ($null -ne $pathDetail) {
+        $reason.Add(@{ kind = $script:ConflictPathOverlap; detail = $pathDetail })
+    }
+
+    $level = @(
+        @{ kind = $script:ConflictModuleOverlap; key = 'modules' },
+        @{ kind = $script:ConflictSharedSurfaceOverlap; key = 'shared_surfaces' },
+        @{ kind = $script:ConflictContractDependency; key = 'contracts' }
+    )
+    foreach ($entry in $level) {
+        $shared = Get-SmallestCommonEntry -Left ([string[]]@($left[$entry['key']])) `
+            -Right ([string[]]@($right[$entry['key']]))
+        if ($null -ne $shared) {
+            $reason.Add(@{ kind = $entry['kind']; detail = $shared })
+        }
+    }
+
+    return @{
+        conflict = ($reason.Count -gt 0)
+        reasons  = @($reason.ToArray())
+    }
+}
+
+Export-ModuleMember -Function `
+    Get-PlanPaths, `
+    Get-BlastRadius, `
+    Get-BlastRadiusFromObservedPaths, `
+    Test-BlastRadius, `
+    Test-BlastRadiusConflict