@danmoisan/drm-copilot-mcp 1.0.26 → 1.0.27

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

@@ -54,6 +54,7 @@ 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 'BlastRadiusNormalization.psm1') -Force
 Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusValidation.psm1') -Force
 
 # Feature-folder handling. Every radius contains its own feature folder, and a
@@ -66,6 +67,11 @@ $script:FeatureFolderPrefix = 'docs/features/'
 $script:SourceDerived = 'derived'
 $script:SourceObserved = 'observed'
 
+# A contract identifier names something callable or referenceable, so it must
+# carry at least one ASCII letter (issue #489). Get-NormalizedDeclaredRadius
+# re-applies that rule to identifiers a pre-#489 extractor already recorded.
+$script:ContractLetterPattern = [regex]::new('[A-Za-z]')
+
 # 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'
@@ -167,10 +173,20 @@ function Get-BlastRadius {
     $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 (
+
+    # Read-by-mandate citations are dropped before the feature folder is added: a
+    # plan cites the policy rules because its author was told to read them, not
+    # because the change will write them (issue #489). Test-BlastRadius applies
+    # the same filter, which is what keeps the derived radius passing V1 and V2
+    # against its own plan. The feature-folder glob is added afterwards so it can
+    # never be excluded.
+    $surviving = [System.Collections.Generic.List[string]]::new()
+    $surviving.AddRange([string[]]@(Get-NonMandateReadEntry -Entry $entry.ToArray() `
+                -MandateRead ([string[]]@(Get-ConfigMandateRead -Config $Config))))
+    $surviving.Add((Get-FeatureFolderGlob -FeatureFolder (
                 Get-RequiredText -Value $FeatureFolder -FieldName 'feature_folder')))
 
-    $paths = [string[]]@(Get-OrdinalSortedEntry -Entry $entry.ToArray())
+    $paths = [string[]]@(Get-OrdinalSortedEntry -Entry $surviving.ToArray())
     $concrete = [string[]]@(Get-ConcreteEntry -Entry $paths)
 
     return ConvertTo-NormalizedBlastRadius -Radius @{
@@ -183,6 +199,92 @@ function Get-BlastRadius {
     }
 }
 
+function Get-NormalizedDeclaredRadius {
+    <#
+    .SYNOPSIS
+        Re-apply the current extraction rules to an already-recorded radius.
+
+    .DESCRIPTION
+        Port of normalize_declared_radius. A radius recorded by an older
+        extractor can carry entries the current rules reject: directory-shaped
+        tokens, cross-corpus documentation globs, read-by-mandate citations, and
+        letterless contract tokens. Re-deriving from the plan text is not always
+        possible, so this function re-filters the recorded radius in place of a
+        fresh derivation and re-resolves the levels that depend on the surviving
+        paths (issue #489). source and computed_at are preserved and the input is
+        never mutated.
+
+    .PARAMETER Radius
+        A derived or declared radius hashtable to re-filter.
+
+    .PARAMETER Config
+        Parsed config/blast-radius.json. The root-surface set, the mandate-read
+        list, the module map, and the shared-surface list are all read from this
+        one value.
+
+    .OUTPUTS
+        System.Collections.Hashtable. A new radius carrying the surviving paths,
+        contracts re-filtered by the ASCII-letter rule, and modules and shared
+        surfaces re-resolved from the surviving paths. Throws when the radius
+        source is observed: an observed radius records a diff listing rather than
+        a plan-text harvest, so the plan-text acceptance rules do not apply to it
+        and re-filtering one would silently discard genuine evidence.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [object] $Radius,
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [object] $Config
+    )
+
+    $normalized = ConvertTo-NormalizedBlastRadius -Radius $Radius
+
+    # Fail fast, before any other work, so the prohibition is unambiguous and no
+    # partially-filtered value can escape.
+    if ($normalized['source'] -eq $script:SourceObserved) {
+        throw ("Get-NormalizedDeclaredRadius rejects a radius whose source is " +
+            "'$($script:SourceObserved)': an observed radius records a diff listing, " +
+            'not a plan-text harvest, so the plan-text acceptance rules must not ' +
+            'be applied to it.')
+    }
+
+    $rootSurface = [string[]]@(Get-ConfigRootSurface -Config $Config)
+
+    # Re-run the classifier over each recorded entry. An entry the current rules
+    # reject is dropped; the mandate-read filter then removes the citations that
+    # are evidence of a read rather than of a write.
+    $accepted = [System.Collections.Generic.List[string]]::new()
+    foreach ($entry in @($normalized['paths'])) {
+        if ($null -ne (Get-PathTokenKind -Token $entry -RootSurface $rootSurface)) {
+            $accepted.Add([string]$entry)
+        }
+    }
+
+    $paths = [string[]]@(Get-NonMandateReadEntry -Entry $accepted.ToArray() `
+            -MandateRead ([string[]]@(Get-ConfigMandateRead -Config $Config)))
+    $concrete = [string[]]@(Get-ConcreteEntry -Entry $paths)
+
+    $contract = [System.Collections.Generic.List[string]]::new()
+    foreach ($identifier in @($normalized['contracts'])) {
+        if ($script:ContractLetterPattern.IsMatch([string]$identifier)) {
+            $contract.Add([string]$identifier)
+        }
+    }
+
+    return ConvertTo-NormalizedBlastRadius -Radius @{
+        paths           = $paths
+        modules         = @(Resolve-BlastRadiusModule -PathEntry $paths -Config $Config)
+        shared_surfaces = @(Resolve-BlastRadiusSharedSurface -ConcretePath $concrete -Config $Config)
+        contracts       = @($contract.ToArray())
+        source          = $normalized['source']
+        computed_at     = $normalized['computed_at']
+    }
+}
+
 function Get-BlastRadiusFromObservedPaths {
     <#
     .SYNOPSIS
@@ -374,6 +476,7 @@ function Test-BlastRadiusConflict {
 Export-ModuleMember -Function `
     Get-PlanPaths, `
     Get-BlastRadius, `
+    Get-NormalizedDeclaredRadius, `
     Get-BlastRadiusFromObservedPaths, `
     Test-BlastRadius, `
     Test-BlastRadiusConflict

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

@@ -39,6 +39,7 @@ Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'BlastRadiusGlob.psm1')
 $script:ConfigSharedSurfaceKey = 'shared_surfaces'
 $script:ConfigSharedSurfaceGlobKey = 'shared_surface_globs'
 $script:ConfigModuleKey = 'modules'
+$script:ConfigMandateReadKey = 'mandate_reads'
 $script:ConfigOverBreadthKey = 'over_breadth_fraction'
 
 # Numeric types a JSON or literal truth table may carry for the V3 threshold.
@@ -279,6 +280,36 @@ function Get-ConfigRootSurface {
     return @($rootSurface.ToArray())
 }
 
+function Get-ConfigMandateRead {
+    <#
+    .SYNOPSIS
+        Read the read-by-mandate exclusion list from the truth table.
+
+    .DESCRIPTION
+        Port of config_mandate_reads. Mandate reads are the paths every agent is
+        instructed to read before doing any work, so a citation of one of them is
+        evidence that the author obeyed the reading order rather than evidence
+        that the change will write the file (issue #489).
+
+    .PARAMETER Config
+        Parsed config/blast-radius.json. Only the mandate_reads key is read.
+
+    .OUTPUTS
+        System.Object[]. Entries sorted and deduplicated by the underlying
+        reader. A config with no mandate_reads key yields an empty array, which
+        excludes nothing and reproduces pre-change behavior.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Object[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowNull()]
+        [object] $Config
+    )
+
+    return @(Get-ConfigStringList -Config $Config -Key $script:ConfigMandateReadKey)
+}
+
 function Get-ConfigModuleEntry {
     <#
     .SYNOPSIS
@@ -374,57 +405,6 @@ function Get-ConfigOverBreadthFraction {
     return $fraction
 }
 
-function Resolve-BlastRadiusModule {
-    <#
-    .SYNOPSIS
-        Resolve path entries to the module names of the truth-table map.
-
-    .DESCRIPTION
-        Port of resolve_modules. A module joins the radius as soon as one of its
-        globs covers one entry, so the search stops at the first hit per module.
-        A path matching no glob resolves to no module.
-
-    .PARAMETER PathEntry
-        Concrete paths and globs of a radius. An empty collection is accepted.
-
-    .PARAMETER Config
-        Parsed config/blast-radius.json.
-
-    .OUTPUTS
-        System.Object[]. Matched module names, deduplicated and ordinally sorted.
-    #>
-    [CmdletBinding()]
-    [OutputType([System.Object[]])]
-    param(
-        [Parameter(Mandatory = $true)]
-        [AllowEmptyCollection()]
-        [AllowEmptyString()]
-        [string[]] $PathEntry,
-        [Parameter(Mandatory = $true)]
-        [AllowNull()]
-        [object] $Config
-    )
-
-    $matched = [System.Collections.Generic.List[string]]::new()
-    foreach ($pair in @(Get-ConfigModuleEntry -Config $Config)) {
-        foreach ($pattern in $pair['globs']) {
-            $hit = $false
-            foreach ($entry in $PathEntry) {
-                if (Test-GlobMatch -Pattern $pattern -Candidate $entry) {
-                    $matched.Add([string]$pair['name'])
-                    $hit = $true
-                    break
-                }
-            }
-            if ($hit) {
-                break
-            }
-        }
-    }
-
-    return @(Get-OrdinalSortedEntry -Entry $matched.ToArray())
-}
-
 function Resolve-BlastRadiusSharedSurface {
     <#
     .SYNOPSIS
@@ -485,7 +465,7 @@ Export-ModuleMember -Function `
     Get-RequiredMapping, `
     Get-ConfigStringList, `
     Get-ConfigRootSurface, `
+    Get-ConfigMandateRead, `
     Get-ConfigModuleEntry, `
     Get-ConfigOverBreadthFraction, `
-    Resolve-BlastRadiusModule, `
     Resolve-BlastRadiusSharedSurface

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

@@ -6,8 +6,11 @@
     Destination-runtime PowerShell port of the text-scanning half of
     scripts/dev_tools/_blast_radius_extraction.py. Normalizes line endings,
     partitions atomic-plan lines, extracts backtick-delimited inline-code tokens,
-    classifies those tokens as concrete repository paths or globs, and extracts
-    contract identifiers from a feature spec's interface sections.
+    and classifies those tokens as concrete repository paths or globs.
+    Get-ContractIdentifier was relocated to BlastRadiusNormalization.psm1 so this
+    module stays inside the 500-line limit (issue #489); the three module-scoped
+    heading variables it read travelled with it, because $script: scope is per
+    module.
 
     The Python module remains the authoritative reference implementation. This
     module is one half of a two-language mirror; it never imports validator
@@ -53,17 +56,27 @@ $script:PlanTaskPattern = [regex]::new(
 # on its own line, from producing spurious spans.
 $script:InlineCodeSpanPattern = [regex]::new('`([^`]+)`')
 
-# Markdown ATX heading pattern used to locate spec interface sections.
-$script:HeadingPattern = [regex]::new('^(?<hashes>#{1,6}) (?<title>.+)$')
-
 # Top-level directories of this repository. A token starting with one of these is
-# accepted without needing a recognized extension, which admits directory-shaped
-# tokens and ** globs.
+# accepted without needing a recognized extension, which admits ** globs naming a
+# subtree. artifacts/ is deliberately absent (issue #489): the process-artifact
+# tree is read by mandate rather than written by a work item, so admitting
+# artifacts/** as a subtree claim made unrelated items contend.
 $script:KnownTopLevelSegment = @(
     'scripts/', 'tests/', 'docs/', 'config/', 'schemas/', 'packages/',
-    'extensions/', '.claude/', '.codex/', '.github/', '.agents/', 'artifacts/'
+    'extensions/', '.claude/', '.codex/', '.github/', '.agents/'
 )
 
+# A file citation may carry a trailing line reference such as :90. The suffix is
+# stripped before the extension test so a line-anchored citation keeps the
+# acceptance its unanchored form has; the token itself is recorded verbatim.
+$script:LineSuffixPattern = [regex]::new(':\d+$')
+
+# Documentation-corpus root and the index, counted after that prefix, of the
+# segment that names one feature folder. A glob whose wildcard reaches this
+# segment or any earlier one claims every feature folder in the corpus.
+$script:FeatureCorpusPrefix = 'docs/features/'
+$script:FeatureFolderSegmentIndex = 1
+
 # Fallback acceptance rule: a token shaped <segment>/.../<name>.<ext> counts as a
 # repository path when its final component carries one of these extensions.
 $script:RecognizedPathExtension = [System.Collections.Generic.HashSet[string]]::new(
@@ -74,19 +87,11 @@ $script:RecognizedPathExtension = [System.Collections.Generic.HashSet[string]]::
     ),
     [StringComparer]::Ordinal)
 
-# A spec section qualifies as an interface section when its heading, or the
-# heading of an ancestor section, contains one of these words.
-$script:ContractHeadingKeyword = @('API', 'Interface', 'Contract', 'Surface')
-
 # Classification vocabulary for accepted path tokens. Concrete entries take part
 # in exact-match checks; glob entries cannot and are matched by pattern.
 $script:PathKindConcrete = 'concrete'
 $script:PathKindGlob = 'glob'
 
-# Heading depth sentinel standing in for the Python `qualifying_depth is None`
-# state: markdown heading levels are 1..6, so 0 can never be a real level.
-$script:NoQualifyingHeadingDepth = 0
-
 
 function ConvertTo-NormalizedLine {
     <#
@@ -228,6 +233,60 @@ function Get-InlineCodeToken {
     return @($token.ToArray())
 }
 
+function Test-MultipleFeatureFolderSpan {
+    <#
+    .SYNOPSIS
+        Report whether a glob claims more than one documentation feature folder.
+
+    .DESCRIPTION
+        Port of spans_multiple_feature_folders. The documentation corpus is laid
+        out as docs/features/<bucket>/<feature-folder>/..., so a glob whose
+        wildcard occupies or truncates the feature-folder segment claims every
+        feature folder in the corpus. That made two unrelated work items contend
+        purely because both wrote documentation (issue #489). A glob carrying a
+        complete, wildcard-free feature-folder segment claims one folder and is
+        retained.
+
+    .PARAMETER Token
+        A wildcard-bearing token already accepted by the shape rules of
+        Get-PathTokenKind.
+
+    .OUTPUTS
+        System.Boolean. True when the token is rooted in the documentation corpus
+        and its wildcard reaches the feature-folder segment or any earlier one.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string] $Token
+    )
+
+    if (-not $Token.StartsWith($script:FeatureCorpusPrefix,
+            [System.StringComparison]::Ordinal)) {
+        return $false
+    }
+
+    $segment = @($Token.Substring($script:FeatureCorpusPrefix.Length) -split '/')
+
+    # A token that stops at or before the feature-folder segment has had that
+    # segment truncated away by the wildcard, so it spans the whole corpus.
+    if ($segment.Count -le $script:FeatureFolderSegmentIndex) {
+        return $true
+    }
+
+    # Every segment up to and including the feature-folder name must be a literal
+    # for the claim to resolve to exactly one folder.
+    for ($index = 0; $index -le $script:FeatureFolderSegmentIndex; $index++) {
+        if ($segment[$index].IndexOf('*') -ge 0) {
+            return $true
+        }
+    }
+
+    return $false
+}
+
 function Get-PathTokenKind {
     <#
     .SYNOPSIS
@@ -287,14 +346,30 @@ function Get-PathTokenKind {
     }
 
     # Read the final component's extension for the fallback acceptance rule; a
-    # component with no dot (a directory name or **) has no extension.
-    $finalComponent = $Token.Substring($Token.LastIndexOf('/') + 1)
+    # component with no dot (a directory name or **) has no extension. A trailing
+    # line reference is stripped first so file.md:90 reads as md rather than as
+    # the unrecognized extension md:90.
+    $finalComponent = $script:LineSuffixPattern.Replace(
+        $Token.Substring($Token.LastIndexOf('/') + 1), '')
     $extension = ''
     $dotIndex = $finalComponent.LastIndexOf('.')
     if ($dotIndex -ge 0) {
         $extension = $finalComponent.Substring($dotIndex + 1).ToLowerInvariant()
     }
 
+    $hasExtension = $script:RecognizedPathExtension.Contains($extension)
+
+    # A wildcard-free token must name a file, not a directory (issue #489). A
+    # directory-shaped token such as scripts/dev_tools is a location reference,
+    # not a write claim, and admitting it made every item touching anything under
+    # that directory contend at the path level.
+    if ($Token.IndexOf('*') -lt 0) {
+        if ($hasExtension) {
+            return $script:PathKindConcrete
+        }
+        return $null
+    }
+
     $hasKnownSegment = $false
     foreach ($segment in $script:KnownTopLevelSegment) {
         if ($Token.StartsWith($segment, [System.StringComparison]::Ordinal)) {
@@ -303,18 +378,23 @@ function Get-PathTokenKind {
         }
     }
 
-    # Failing both shape rules means the token is prose or a non-path expression
-    # that merely contains a separator, so it is dropped.
-    if (-not $hasKnownSegment -and -not $script:RecognizedPathExtension.Contains($extension)) {
+    # A wildcard-bearing token must still satisfy one of the two documented shape
+    # rules; failing both means the token is prose or a non-path expression that
+    # merely contains a separator, so it is dropped.
+    if (-not $hasKnownSegment -and -not $hasExtension) {
+        return $null
+    }
+
+    # A documentation glob spanning the whole feature corpus is a cross-corpus
+    # claim rather than a write claim, so it is dropped before it can become a
+    # radius entry.
+    if (Test-MultipleFeatureFolderSpan -Token $Token) {
         return $null
     }
 
     # An accepted token carrying a wildcard names a set of files, so it cannot
     # take part in concrete exact-match comparisons and is recorded as a glob.
-    if ($Token.IndexOf('*') -ge 0) {
-        return $script:PathKindGlob
-    }
-    return $script:PathKindConcrete
+    return $script:PathKindGlob
 }
 
 function Get-PathFromLine {
@@ -407,84 +487,12 @@ function Get-PlanPaths {
     return @(Get-PathFromLine -Line $allLine.ToArray() -RootSurface $RootSurface)
 }
 
-function Get-ContractIdentifier {
-    <#
-    .SYNOPSIS
-        Extract contract identifiers from a spec's interface sections.
-
-    .DESCRIPTION
-        Port of extract_contract_identifiers. Implements the contracts level of
-        the radius model: exported symbols, schema names, and CLI identifiers
-        named in inline code inside sections whose heading, or an ancestor
-        heading, contains API, Interface, Contract, or Surface. Markdown sections
-        nest, so a heading deeper than the innermost qualifying heading stays
-        inside that section and inherits its qualification; a heading at or above
-        that level ends the section and is judged on its own title.
-
-    .PARAMETER SpecText
-        Full feature spec.md document text; may be empty.
-
-    .OUTPUTS
-        System.Object[]. Identifiers, deduplicated and ordinally sorted. Tokens
-        containing a separator are excluded as path references.
-    #>
-    [CmdletBinding()]
-    [OutputType([System.Object[]])]
-    param(
-        [Parameter(Mandatory = $true)]
-        [AllowEmptyString()]
-        [string] $SpecText
-    )
-
-    $identifier = [System.Collections.Generic.List[string]]::new()
-    $qualifyingDepth = $script:NoQualifyingHeadingDepth
-
-    foreach ($line in @(ConvertTo-NormalizedLine -Text $SpecText)) {
-        $headingMatch = $script:HeadingPattern.Match($line)
-
-        # A heading changes the section context and contributes no identifiers of
-        # its own, so each heading is handled and the line is then skipped.
-        if ($headingMatch.Success) {
-            $headingLevel = $headingMatch.Groups['hashes'].Value.Length
-            if ($qualifyingDepth -ne $script:NoQualifyingHeadingDepth -and
-                $headingLevel -gt $qualifyingDepth) {
-                continue
-            }
-
-            $headingTitle = $headingMatch.Groups['title'].Value
-            $qualifyingDepth = $script:NoQualifyingHeadingDepth
-            foreach ($keyword in $script:ContractHeadingKeyword) {
-                if ($headingTitle.IndexOf($keyword, [System.StringComparison]::Ordinal) -ge 0) {
-                    $qualifyingDepth = $headingLevel
-                    break
-                }
-            }
-            continue
-        }
-
-        if ($qualifyingDepth -eq $script:NoQualifyingHeadingDepth) {
-            continue
-        }
-
-        # Inside a qualifying section an inline-code token without a separator is
-        # a contract identifier; a token with one is a path reference and is
-        # recorded at the paths level instead.
-        foreach ($token in @(Get-InlineCodeToken -Line $line)) {
-            if ($token.IndexOf('/') -lt 0) {
-                $identifier.Add($token)
-            }
-        }
-    }
-
-    return @(Get-OrdinalSortedEntry -Entry $identifier.ToArray())
-}
-
 Export-ModuleMember -Function `
     Get-OrdinalSortedEntry, `
     ConvertTo-NormalizedLine, `
     Get-PlanLineScan, `
     Get-InlineCodeToken, `
+    Test-MultipleFeatureFolderSpan, `
     Get-PathTokenKind, `
     Get-PathFromLine, `
-    Get-PlanPaths, `
-    Get-ContractIdentifier
+    Get-PlanPaths