@danmoisan/drm-copilot-mcp 1.1.12 → 1.1.15

package/resources/claude-customizations/.claude/lib/ci-gate/Invoke-CiGateParser.ps1

@@ -0,0 +1,330 @@
+<#
+.SYNOPSIS
+    Parses `gh pr checks` JSON into the orchestrator `ci_gate` object defined by
+    Step S9 (CI Green Gate) of .claude/skills/orchestrate/SKILL.md.
+
+.DESCRIPTION
+    Consumes the JSON array emitted by
+    `gh pr checks --required --json bucket,name,state,link,workflow` and produces
+    the `ci_gate` object the orchestrator writes to its checkpoint. The object
+    carries the five contract fields: head_sha, pr_pipeline_run_id,
+    pr_pipeline_run_url, conclusion, and verified_at.
+
+    This script is the single source of truth for `ci_gate.conclusion`
+    derivation. It does NOT invoke `gh`. The orchestrator runs `gh` and passes
+    the resulting JSON to this script via the -ChecksJson parameter or the
+    pipeline, keeping all network/executable I/O outside this derivation step so
+    the logic is deterministically testable.
+
+    Conclusion derivation (per the documented bucket mapping):
+      - Any required check with bucket 'fail' or 'cancel'  -> conclusion 'failure'
+      - Else any required check with bucket 'pending'       -> conclusion 'pending'
+      - Else (all checks 'pass' or 'skipping', or empty set) -> conclusion 'success'
+    An empty required-check set is treated as 'success' (vacuously satisfied: no
+    required check can fail or be in progress). An unrecognized bucket value is a
+    fail-fast error so the parser never silently passes an enum it does not
+    understand.
+
+    The verified_at timestamp is produced through an injectable clock delegate
+    (-NowProvider) so tests can assert an exact deterministic value without
+    reading the wall clock.
+
+.PARAMETER ChecksJson
+    The JSON array string emitted by `gh pr checks --required --json ...`. Each
+    element is expected to expose at least a `bucket` property. Accepts pipeline
+    / stdin input so the orchestrator can pipe the `gh` output directly.
+
+.PARAMETER HeadSha
+    The PR head SHA the required checks were observed against. Recorded verbatim
+    as ci_gate.head_sha.
+
+.PARAMETER PrPipelineRunId
+    Optional GitHub Actions run id for the PR Pipeline. Recorded verbatim as
+    ci_gate.pr_pipeline_run_id (may be empty when not supplied).
+
+.PARAMETER PrPipelineRunUrl
+    Optional URL of the PR Pipeline run. Recorded verbatim as
+    ci_gate.pr_pipeline_run_url (may be empty when not supplied).
+
+.PARAMETER NowProvider
+    Optional clock delegate (ScriptBlock) returning the value used for
+    ci_gate.verified_at. Defaults to a UTC Get-Date formatted as ISO-8601. Tests
+    inject a fixed delegate to make verified_at deterministic.
+
+.PARAMETER AsJson
+    When set, emits the ci_gate object as a JSON string instead of a PowerShell
+    object. The default (object) output is convenient for in-process callers; the
+    JSON output is convenient for checkpoint serialization.
+
+.EXAMPLE
+    gh pr checks --required --json bucket,name,state,link,workflow |
+        ./.claude/lib/ci-gate/Invoke-CiGateParser.ps1 -HeadSha $sha
+
+.OUTPUTS
+    A PSCustomObject (or JSON string when -AsJson is set) with properties
+    head_sha, pr_pipeline_run_id, pr_pipeline_run_url, conclusion, verified_at.
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+    [string]$ChecksJson,
+
+    [Parameter(Mandatory = $true)]
+    [ValidateNotNullOrEmpty()]
+    [string]$HeadSha,
+
+    [Parameter(Mandatory = $false)]
+    [string]$PrPipelineRunId = '',
+
+    [Parameter(Mandatory = $false)]
+    [string]$PrPipelineRunUrl = '',
+
+    [Parameter(Mandatory = $false)]
+    [ValidateNotNull()]
+    [ScriptBlock]$NowProvider = { (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ') },
+
+    [Parameter(Mandatory = $false)]
+    [switch]$AsJson
+)
+
+# Function definitions live in begin so the script is a single explicit
+# begin/process unit. This is required because the script-level -ChecksJson
+# parameter accepts pipeline input, which forces a named process block; once any
+# named block is used, all top-level statements must reside inside named blocks.
+begin {
+    function Get-CiGateConclusion {
+        <#
+    .SYNOPSIS
+        Pure derivation of ci_gate.conclusion from a parsed required-check set.
+
+    .DESCRIPTION
+        Implements the documented bucket precedence with no I/O and no external
+        calls, so it is deterministically unit-testable in isolation:
+          1. Any 'fail' or 'cancel' -> 'failure'.
+          2. Else any 'pending'      -> 'pending'.
+          3. Else                    -> 'success'.
+        'skipping' is non-blocking: it neither forces failure nor pending and
+        contributes to 'success'. An empty set yields 'success' (vacuous). Any
+        bucket value outside the known enum throws a fail-fast error naming the
+        unrecognized value, preventing a silent pass on an unknown state.
+
+    .PARAMETER Checks
+        The parsed required-check collection (each element exposing a `bucket`
+        property). May be $null or empty, which yields 'success'.
+
+    .OUTPUTS
+        One of the strings 'success', 'failure', or 'pending'.
+
+    .NOTES
+        Pure function: no filesystem, network, or `gh` access.
+    #>
+        [CmdletBinding()]
+        [OutputType([string])]
+        param(
+            [Parameter(Mandatory = $false)]
+            [AllowNull()]
+            [object[]]$Checks
+        )
+
+        # Empty or null required-check set is vacuously satisfied: there is no check
+        # that can fail or be in progress, so the gate concludes 'success'.
+        if ($null -eq $Checks -or $Checks.Count -eq 0) {
+            return 'success'
+        }
+
+        # Track whether any check is still in progress so we can defer the 'pending'
+        # decision until after confirming nothing failed (failure outranks pending).
+        $anyPending = $false
+
+        # Inspect each required check once, classifying by its bucket value. Failure
+        # short-circuits immediately because it is the highest-precedence outcome.
+        foreach ($check in $Checks) {
+            # A check element must expose a bucket; absence is an undefined state and
+            # is treated as a fail-fast error rather than silently ignored.
+            if ($null -eq $check -or -not ($check.PSObject.Properties.Name -contains 'bucket')) {
+                throw "Invoke-CiGateParser: required check is missing a 'bucket' property; cannot derive conclusion."
+            }
+
+            $bucket = [string]$check.bucket
+
+            # Routing table for the bucket enum. Ordering inside the switch does not
+            # change semantics because failure short-circuits via return; pending is
+            # only recorded (not returned) so a later failure can still take priority.
+            switch ($bucket) {
+                'fail' { return 'failure' }       # a failed required check is terminal-non-success
+                'cancel' { return 'failure' }       # a cancelled required check is treated conservatively as failure
+                'pending' { $anyPending = $true }     # in-progress; defer until failures are ruled out
+                'pass' { }                        # passing check contributes to success; no state change
+                'skipping' { }                        # skipped check is non-blocking; neither failure nor pending
+                default {
+                    # Unknown bucket: fail fast and name the value so the unsupported
+                    # enum is visible rather than silently mapped to a pass.
+                    throw "Invoke-CiGateParser: unrecognized check bucket '$bucket'; refusing to derive a conclusion for an unknown state."
+                }
+            }
+        }
+
+        # No failure or cancel was seen. If any check was pending the gate is still
+        # in progress; otherwise every check was pass/skipping and the gate succeeds.
+        if ($anyPending) {
+            return 'pending'
+        }
+
+        return 'success'
+    }
+
+    function ConvertTo-CiGateObject {
+        <#
+    .SYNOPSIS
+        Thin constructor for the ci_gate object from already-derived inputs.
+
+    .DESCRIPTION
+        Assembles the five contract fields into a PSCustomObject. Exists as a
+        small helper so the wrapper body stays readable and so the field set is
+        defined in exactly one place. Performs no derivation and no I/O.
+
+    .PARAMETER HeadSha
+        Recorded as head_sha.
+    .PARAMETER PrPipelineRunId
+        Recorded as pr_pipeline_run_id.
+    .PARAMETER PrPipelineRunUrl
+        Recorded as pr_pipeline_run_url.
+    .PARAMETER Conclusion
+        The already-derived conclusion ('success'/'failure'/'pending').
+    .PARAMETER VerifiedAt
+        The already-resolved ISO-8601 timestamp string.
+
+    .OUTPUTS
+        A PSCustomObject with the five ci_gate properties.
+    #>
+        [CmdletBinding()]
+        [OutputType([pscustomobject])]
+        param(
+            [Parameter(Mandatory = $true)][string]$HeadSha,
+            [Parameter(Mandatory = $true)][AllowEmptyString()][string]$PrPipelineRunId,
+            [Parameter(Mandatory = $true)][AllowEmptyString()][string]$PrPipelineRunUrl,
+            [Parameter(Mandatory = $true)][string]$Conclusion,
+            [Parameter(Mandatory = $true)][string]$VerifiedAt
+        )
+
+        return [pscustomobject]@{
+            head_sha            = $HeadSha
+            pr_pipeline_run_id  = $PrPipelineRunId
+            pr_pipeline_run_url = $PrPipelineRunUrl
+            conclusion          = $Conclusion
+            verified_at         = $VerifiedAt
+        }
+    }
+
+    function Invoke-CiGateParser {
+        <#
+    .SYNOPSIS
+        Wrapper that parses the checks JSON, derives the conclusion, and returns
+        the ci_gate object.
+
+    .DESCRIPTION
+        Thin orchestration over the pure helpers: it parses -ChecksJson (failing
+        fast on malformed JSON), normalizes the result into an array, delegates
+        conclusion derivation to Get-CiGateConclusion, resolves verified_at via
+        the injected clock delegate, and assembles the object via
+        ConvertTo-CiGateObject. The wrapper exists to separate the impure JSON-parsing
+        and clock concerns from the pure derivation logic.
+
+    .PARAMETER ChecksJson
+        See script-level parameter of the same name.
+    .PARAMETER HeadSha
+        See script-level parameter of the same name.
+    .PARAMETER PrPipelineRunId
+        See script-level parameter of the same name.
+    .PARAMETER PrPipelineRunUrl
+        See script-level parameter of the same name.
+    .PARAMETER NowProvider
+        See script-level parameter of the same name.
+    .PARAMETER AsJson
+        See script-level parameter of the same name.
+
+    .OUTPUTS
+        PSCustomObject, or JSON string when -AsJson is set.
+
+    .NOTES
+        Throws on malformed JSON and on unrecognized bucket values (fail-fast).
+    #>
+        [CmdletBinding()]
+        param(
+            [Parameter(Mandatory = $true)]
+            [string]$ChecksJson,
+
+            [Parameter(Mandatory = $true)]
+            [ValidateNotNullOrEmpty()]
+            [string]$HeadSha,
+
+            [Parameter(Mandatory = $false)]
+            [string]$PrPipelineRunId = '',
+
+            [Parameter(Mandatory = $false)]
+            [string]$PrPipelineRunUrl = '',
+
+            [Parameter(Mandatory = $false)]
+            [ValidateNotNull()]
+            [ScriptBlock]$NowProvider = { (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ') },
+
+            [Parameter(Mandatory = $false)]
+            [switch]$AsJson
+        )
+
+        # Parse the gh JSON. ConvertFrom-Json throws on malformed input; wrap it so
+        # the failure surfaces as an explicit, parser-attributed error rather than a
+        # raw deserialization message, satisfying fail-fast-and-explicitly policy.
+        try {
+            $parsed = $ChecksJson | ConvertFrom-Json -ErrorAction Stop
+        }
+        catch {
+            throw "Invoke-CiGateParser: malformed checks JSON could not be parsed: $($_.Exception.Message)"
+        }
+
+        # Normalize to an array. ConvertFrom-Json yields a single object for a
+        # one-element payload and $null for the literal 'null'; @() coercion makes the
+        # downstream Count/foreach logic uniform for the empty, single, and many cases.
+        $checks = @($parsed)
+
+        $conclusion = Get-CiGateConclusion -Checks $checks
+
+        # Resolve the timestamp through the injected delegate so tests can pin an
+        # exact value; the default delegate reads UTC wall-clock time.
+        $verifiedAt = [string](& $NowProvider)
+
+        $ciGate = ConvertTo-CiGateObject `
+            -HeadSha $HeadSha `
+            -PrPipelineRunId $PrPipelineRunId `
+            -PrPipelineRunUrl $PrPipelineRunUrl `
+            -Conclusion $conclusion `
+            -VerifiedAt $verifiedAt
+
+        # Emit either the object (default, for in-process callers) or its JSON
+        # serialization (for direct checkpoint writing) based on the caller's choice.
+        if ($AsJson) {
+            return ($ciGate | ConvertTo-Json -Depth 5)
+        }
+
+        return $ciGate
+    }
+}
+
+# Entry point. The script-level -ChecksJson parameter accepts pipeline input, so
+# the entry-point execution lives in a process block: each piped JSON payload is
+# handled as it arrives. The parser runs only when the file is executed directly;
+# when dot-sourced for testing, $MyInvocation.InvocationName is '.', so the guard
+# suppresses execution and lets tests invoke the functions with controlled inputs.
+process {
+    if ($MyInvocation.InvocationName -ne '.') {
+        Invoke-CiGateParser `
+            -ChecksJson $ChecksJson `
+            -HeadSha $HeadSha `
+            -PrPipelineRunId $PrPipelineRunId `
+            -PrPipelineRunUrl $PrPipelineRunUrl `
+            -NowProvider $NowProvider `
+            -AsJson:$AsJson
+    }
+}
+

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

@@ -209,6 +209,8 @@ All nine enums of the parallel surface are owned by the schema-and-validator fea
 
 The wave-4 features — F6 (mutation protocol), F7 (enforcement hooks), and F8 (drift detection) — CONSUME these member sets and NEVER extend them. A wave-4 feature that needs a new member must amend this rule file and the validators at spec review, not add the member at implementation time. This constraint exists because the wave-4 features are prepared concurrently and would otherwise add fields to the same files at the same time.
 
+Integration-cost scheduling (issue #722) adds no `conflict_edges[].reason` member; the four members above are unchanged. The scheduling data travels in tolerated-not-validated fields: an edge may carry the extra fields `hard`, `cost`, and `benefit`, and the planner and orchestrator checkpoints may carry a `tolerated_overlaps` list. No validator reads these fields, and the Python validators and the TypeScript validator port accept them with zero errors.
+
 ## F7 Seam
 
 The retrospective cohort-ordering invariant `PARALLEL_COHORT_BARRIER_VIOLATION` (design section 9, Layer 2) is F7's explicitly assigned addition to the orchestrator validator. It is NOT implemented here. The entry point of `scripts/dev_tools/validate_parallel_orchestrator_state.py` contains a clearly delimited, appendable helper-invocation block, marked with explicit begin and end comments that name F7 and the invariant token, so that F7's edit is one appended helper call with no reflow of existing code. The TypeScript core `extensions/drm-copilot/src/lib/validate/parallel-orchestrator-state-core.ts` carries the matching comment-delimited seam. Existing helper calls sit outside the block.
@@ -241,6 +243,11 @@ plan-side extraction so V1 and V2 stay self-consistent against a radius derived
 The key is optional and fail-closed: a truth table that omits it excludes nothing and reproduces
 pre-change behaviour exactly.
 
+The Copilot instructions file `.github/copilot-instructions.md` is a mandate read as well (issue
+#722): the policy reading order begins with it, so a plan that cites copilot-instructions.md is
+reporting that it read the tone and communication policy. Both committed copies of
+`config/blast-radius.json` list it in `mandate_reads`.
+
 Three constraints bound the mandate-read exclusion:
 
 1. **The planner remains obliged to enumerate a genuine write explicitly.** An exclusion describes
@@ -391,6 +398,144 @@ 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.
 
+### Integration-cost scheduling (issue #722)
+
+Detection and scheduling are separate steps. The detection relation (`conflicts` in Python,
+`Test-BlastRadiusConflict` in PowerShell) is unchanged and still answers one question: do two radii
+contend? Scheduling decides whether a detected contention must serialize the two items. The entry
+points are `schedule_conflict_edges` in `scripts/dev_tools/_blast_radius_scheduling.py` and
+Get-BlastRadiusConflictEdge in `.claude/lib/blast-radius/BlastRadiusScheduling.psm1`; both return
+the edges and the tolerated overlaps of a set of items. Planners call the entry point instead of
+applying the detection relation to every pair by hand.
+
+This is an operator-directed configured policy change (issue #722, 2026-09-27), not ad hoc
+narrowing. The only sanctioned mechanisms for relaxing contention are the configured
+`conflict_tolerance` key and configured write-intent extraction. Planners still never hand-narrow a
+radius: editing a declared radius to suppress an edge remains prohibited.
+
+**Configuration.** `config/blast-radius.json` carries an optional `conflict_tolerance` object with
+tolerance_percent (integer, at least 0), `weights` (same_file, possible_overlap, append_only, and
+module, each an integer of at least 1), `band_durations` (C1 through C4, each an integer of at least
+1), `default_band` (one of C1 through C4), and append_only_paths (a list of exact entries and `**`
+globs). The reader fails fast with an error naming the key for any other shape; booleans are
+rejected wherever an integer is required. An absent key means strict scheduling, identical to
+tolerance_percent 0.
+
+**Edge rule.** For each unordered pair of items:
+
+1. Run the unchanged detection relation. No conflict means no edge and no tolerated overlap.
+2. **Hard classes.** A reason list containing `shared_surface_overlap` or `contract_dependency`
+   makes the pair an edge at every tolerance.
+3. **Cost** (integer, computed only for a detected conflict). Re-enumerate the overlapping entry
+   pairs with the same mergeable-path exclusion and the same entry-overlap primitive the relation
+   uses, then sum the append_only weight for a concrete overlapping path that matches an
+   append_only_paths entry, the same_file weight for two equal concrete entries, the
+   possible_overlap weight for a glob or directory-prefix overlap, and the module weight times the
+   number of shared modules. The append_only_paths check runs before the same_file check (append-only
+   precedence), so an append-only file stays low cost even when both items name it. Mergeable paths
+   contribute 0 because they are excluded before enumeration.
+4. **Benefit** (integer, pairwise). The smaller of the two items' band durations; a missing band uses
+   `default_band`. Running the pair concurrently saves at most one cohort step of the shorter item.
+5. **Rule.** The pair is an edge if and only if it conflicts and either it is hard or
+   `cost * 100 > benefit * tolerance_percent`.
+6. **Recorded reason.** The first member of the relation's reason list in canonical kind order.
+
+**Strict-identity proof.** Every weight and every band duration is validated as an integer of at
+least 1. A detected conflict that is not hard therefore has a cost of at least 1, so at
+tolerance_percent 0 the inequality `cost * 100 > 0` always holds and the edge set equals the
+detected-conflict set exactly; cohort coloring of that set is identical to strict scheduling. At
+every tolerance an edge requires a conflict, so every edge implies a conflict and the edge set is
+always a subset of the detected-conflict set. Raising tolerance_percent never adds an edge, and the
+decision for (a, b) equals the decision for (b, a).
+
+**Soft-overlap handling.** A detected, non-hard pair within tolerance is a tolerated overlap, not an
+edge. The planner records it in a tolerated_overlaps list on the planner checkpoint (and the
+orchestrator carries it), each entry holding `a`, `b`, `reasons`, `cost`, and `benefit`. Tolerated
+pairs run in the same or adjacent cohorts without a barrier. The later-merging item of a tolerated
+pair merges `origin/main` under the existing per-item merge-conflict handling and re-passes CI before
+it merges.
+
+**Drift behaviour.** When an item's observed radius replaces its declared radius, drift detection
+evaluates each in-flight peer pair through the same edge rule, using the items' complexity bands from
+the checkpoint (`default_band` when absent), through the helper module
+`scripts/dev_tools/_parallel_drift_scheduling.py`. A pair is newly conflicting only when the rule
+yields an edge and the pair is not already a recorded edge. A tolerated pair whose observed overlap
+stays within tolerance halts neither item; one whose observed overlap exceeds tolerance, or becomes
+hard, is reported. An unevaluable peer radius still counts as an edge (fail closed). At
+tolerance_percent 0 the drift output equals strict drift output.
+
+### Write-intent extraction (issue #722)
+
+The extractor harvests every inline-code token of a plan and spec, so a path an item only reads,
+mentions as a glob, or quotes inside a command becomes a radius path and can create a false edge.
+Write-intent extraction keeps only tokens that state a write. It is the second sanctioned mechanism,
+beside `conflict_tolerance`, for relaxing contention; like it, it is an operator-directed configured
+policy change, and planners still never hand-narrow a radius.
+
+**Configuration.** `config/blast-radius.json` carries two optional keys. `write_intent_extraction`
+is a boolean; when it is true, rules W1 through W6 below apply. `path_roots` is a list of non-empty
+first path segments that enables rule W4. Both readers fail fast with an error naming the key for any
+other shape. An absent or false `write_intent_extraction` reproduces pre-change extraction exactly
+(fail closed), and an empty or absent `path_roots` disables W4. The self-hosted copy sets
+`path_roots` to this repository's tracked top-level directories. The implementations are
+`scripts/dev_tools/_blast_radius_write_intent.py` and
+`.claude/lib/blast-radius/BlastRadiusWriteIntent.psm1`.
+
+**Rules.** Each rule is a pure, statically decidable function of the text and the truth table.
+
+- **W1 glob mention.** Drop any harvested token containing a wildcard character. The feature-folder
+  glob is added after filtering and is never dropped.
+- **W2 command span.** Drop every token of an inline span whose whitespace split yields more than
+  one word.
+- **W3 read task.** Drop the tokens of a task attribution window (a task line plus the following
+  non-task lines up to the next ATX heading, as defined in `.claude/rules/plan-acceptance-gates.md`)
+  whose title's first word, after an optional bold label, is in the read-verb set (Read, Verify,
+  Confirm, Inspect, Review, Baseline) and whose title contains no member of the write-verb set (Fix,
+  Write, Update, Edit, Add, Create, Delete, Remove, Rename, Author, Append, Replace). A write verb
+  anywhere in the title overrides the read verb.
+- **W4 root anchoring.** Drop a concrete token whose first segment, after stripping a leading `./`,
+  is not in `path_roots` and is not a configured root surface.
+- **W5 spec paths.** The spec contributes contracts only, not paths. Contract harvesting from the
+  spec applies W1 and W2.
+- **W6 placeholder stem.** Drop a concrete token whose final-component stem is in the placeholder
+  set (the single ASCII letters, and foo, bar, baz, example, sample, placeholder), compared
+  case-insensitively.
+
+The read-verb, write-verb, and placeholder-stem sets are code constants pinned equal across Python
+and PowerShell by a parity test. Shared surfaces are still resolved from the surviving concrete
+paths, so a shared surface cited only in a read task, a command span, or the spec produces no hard
+edge, while a shared surface an item writes in a write task survives and stays hard.
+
+**One extractor for derivation and validation.** W1, W4, and W6 are token-level and also apply when
+`normalize_declared_radius` and Get-NormalizedDeclaredRadius re-filter a recorded radius; an entry
+that starts with `docs/features/`, ends with `/**`, and carries no other wildcard (the feature-folder
+glob) is always kept. W2, W3, and W5 need line context and apply only to derivation and to the
+plan-side extraction of validation. `derive_blast_radius` and `validate_blast_radius` (and their
+PowerShell ports) select the same extractor from the same flag, so a derived radius still passes V1
+and V2 against its own plan in both modes.
+
+#### Known false negatives
+
+Write-intent extraction can drop a genuine write in these cases:
+
+1. a genuine write stated only as a glob (W1);
+2. a genuine write stated only inside a command span (W2);
+3. a write named only in spec prose (W5);
+4. a read-verb task that also writes without a write verb in its title (W3);
+5. a new top-level directory not yet in `path_roots` (W4);
+6. a genuine file whose stem is in the placeholder set (W6).
+
+Three mitigations bound these cases:
+
+1. **The planner remains obliged to enumerate a genuine write explicitly.** When an item's plan will
+   write a path that one of the rules drops, the planner appends that exact path to the declared
+   radius after normalization, as for the mandate-read exclusion.
+2. **Execution-time escaped-path detection.** `detect_escaped_paths` compares the declared radius
+   against the paths a diff actually touched, so a dropped write is caught against observed evidence
+   rather than against prose.
+3. **The fail-closed absent key.** A truth table without `write_intent_extraction`, or with it set
+   to false, reproduces pre-change extraction exactly, so an operator can disable the rules at once.
+
 ### 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
@@ -430,8 +575,11 @@ 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`, `mandate_reads`, and `mergeable_paths`
-are byte-equal across the two copies.
+the self-hosted file. Only `version`, `over_breadth_fraction`, `mandate_reads`, `mergeable_paths`,
+`conflict_tolerance`, and `write_intent_extraction` are byte-equal across the two copies.
+`path_roots` is a Class 2 key: its self-hosted value is this repository's tracked top-level
+directory list, and its bundled value is an empty list, because the bundle cannot know a
+destination's top-level directories and an empty list disables root anchoring there.
 
 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

package/resources/claude-customizations/.claude/rules/plan-acceptance-gates.md

@@ -85,7 +85,7 @@ The window size is fixed at four adjacent non-blank lines. Blank lines are remov
 
 ### The shared measurement behind G7, G8, G8b, and G9
 
-The four severities below were fixed by one corpus measurement recorded in `docs/features/active/2026-08-23-plan-acceptance-gates-miss-unobservable-and-ambient-state-gates-519/evidence/qa-gates/corpus-measurement.2026-08-24T00-00.md`. The pre-declared decision rule was written and committed **before** the driver existed and before any count was taken, so the ordering is verifiable from git history rather than only asserted in prose. Its form matches the G5 precedent: the shipped severity is Blocking if and only if the total finding count for that rule is greater than zero **and** the recorded false-positive count for that rule is zero; otherwise Warning.
+The four severities below were fixed by one corpus measurement recorded in `docs/features/completed/2026-08-23-plan-acceptance-gates-miss-unobservable-and-ambient-state-gates-519/evidence/qa-gates/corpus-measurement.2026-08-24T00-00.md`. The pre-declared decision rule was written and committed **before** the driver existed and before any count was taken, so the ordering is verifiable from git history rather than only asserted in prose. Its form matches the G5 precedent: the shipped severity is Blocking if and only if the total finding count for that rule is greater than zero **and** the recorded false-positive count for that rule is zero; otherwise Warning.
 
 The false-positive definition the rule consumes is likewise pre-declared: a finding is a false positive when the acceptance condition it reports is in fact falsifiable — when the plan states an observation sufficient to distinguish a passing run from a failing one, by a mechanism the rule's predicate does not recognise. A finding is a true positive when the acceptance condition it reports genuinely cannot fail, or can only be satisfied vacuously.
 
@@ -108,7 +108,7 @@ G7's finding count of 466 satisfies the first conjunct, so the rule was not deci
 
 Both classes are addressable by a later feature — Class 1 by adding a check-flag exclusion to the `prettier-write` entry, Class 2 by admitting a tree-observation span as an alternative to a marker — but neither was changed here, because narrowing a predicate after reading its measurement would invalidate the measurement that decided its severity. A later feature that narrows either class must re-take the measurement the same way.
 
-Counts, and every one of the 22 false positives named by plan path, task identifier, and offending span: `docs/features/active/2026-08-23-plan-acceptance-gates-miss-unobservable-and-ambient-state-gates-519/evidence/qa-gates/corpus-measurement.2026-08-24T00-00.md`.
+Counts, and every one of the 22 false positives named by plan path, task identifier, and offending span: `docs/features/completed/2026-08-23-plan-acceptance-gates-miss-unobservable-and-ambient-state-gates-519/evidence/qa-gates/corpus-measurement.2026-08-24T00-00.md`.
 
 ### G8 — ships as a Warning because the measurement recorded 7 false positives
 
@@ -118,7 +118,7 @@ G8's finding count of 82 satisfies the first conjunct. It fails the second: 7 fi
 
 **Class 2, one finding — the unmerged-path filter.** `--diff-filter=U` selects conflicted paths during a merge or rebase. In that state the worktree-against-index comparison is the correct one and does not become vacuous on commit, because the conflict is precisely what is not yet committed.
 
-Counts, and every one of the 7 false positives named by plan path, task identifier, and offending span: `docs/features/active/2026-08-23-plan-acceptance-gates-miss-unobservable-and-ambient-state-gates-519/evidence/qa-gates/corpus-measurement.2026-08-24T00-00.md`.
+Counts, and every one of the 7 false positives named by plan path, task identifier, and offending span: `docs/features/completed/2026-08-23-plan-acceptance-gates-miss-unobservable-and-ambient-state-gates-519/evidence/qa-gates/corpus-measurement.2026-08-24T00-00.md`.
 
 ### G8b — ships as a Warning unconditionally, by the pre-declared rule
 
@@ -126,7 +126,7 @@ G8b is exempt from the two-conjunct rule and **cannot reach the Blocking channel
 
 The reason is that G8b carries the highest false-positive surface of the set, and a false-positive count taken over one corpus does not bound the false-positive surface of a predicate. Promoting a rule on the strength of a clean run over one corpus would convert an accident of that corpus into a gate. The 19 findings were nonetheless examined individually and all 19 were retained as true positives, across three sub-classes: a placeholder ref operand, which resolves to a real ref at run time and still cannot make the diff see an untracked path; an artifact-field label inside the span, which is cosmetic and leaves the underlying acceptance condition as the finding describes it; and a pathspec written without the `--` separator, where the predicate reads the pathspec as a ref operand. That last sub-class is a true positive for G8b and is simultaneously recorded in the measurement as a **G8 false negative**: the same span should also have been reported by G8, and was not.
 
-Counts, the zero false-positive record, and the three sub-classes with their plan paths and offending spans: `docs/features/active/2026-08-23-plan-acceptance-gates-miss-unobservable-and-ambient-state-gates-519/evidence/qa-gates/corpus-measurement.2026-08-24T00-00.md`.
+Counts, the zero false-positive record, and the three sub-classes with their plan paths and offending spans: `docs/features/completed/2026-08-23-plan-acceptance-gates-miss-unobservable-and-ambient-state-gates-519/evidence/qa-gates/corpus-measurement.2026-08-24T00-00.md`.
 
 ### G9 — ships as a Warning because the measurement recorded 4 false positives
 
@@ -134,7 +134,7 @@ G9's finding count of 8 satisfies the first conjunct. It fails the second: 4 of
 
 The remaining 4 findings are true positives, and each is the exact defect the rule was written for: the acceptance condition demands a numeric coverage percentage, the command supplies no terminal reporter, the project `addopts` supplies only an LCOV reporter, and the number the acceptance demands is therefore never printed.
 
-Counts, and every one of the 4 false positives named by plan path, task identifier, offending span, and the reason its acceptance condition is falsifiable: `docs/features/active/2026-08-23-plan-acceptance-gates-miss-unobservable-and-ambient-state-gates-519/evidence/qa-gates/corpus-measurement.2026-08-24T00-00.md`.
+Counts, and every one of the 4 false positives named by plan path, task identifier, offending span, and the reason its acceptance condition is falsifiable: `docs/features/completed/2026-08-23-plan-acceptance-gates-miss-unobservable-and-ambient-state-gates-519/evidence/qa-gates/corpus-measurement.2026-08-24T00-00.md`.
 
 ## The Write-Mode Register
 

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

@@ -45,10 +45,11 @@ single pass. Do not substitute the VS Code task wrappers for the native command
 
 ## Discovery Contract
 
-- Search roots: `tools/`, `scripts/`, and `.claude/lib/bash/`, relative to the current working
-  directory; a missing root is silently skipped. The `.claude/lib/bash/` root carries the
-  destination-portable bash library published by push-down, so those scripts are held to the
-  same format, lint, test, and coverage standards as `tools/` and `scripts/`.
+- Search roots: `tools/`, `scripts/`, `.claude/lib/bash/`, and `.claude/skills/`, relative to the
+  current working directory; a missing root is silently skipped. The `.claude/lib/bash/` root carries
+  the destination-portable bash library published by push-down, and the `.claude/skills/` root carries
+  scripts bundled inside a skill folder, so those scripts are held to the same format, lint, test, and
+  coverage standards as `tools/` and `scripts/`.
 - A file is a shell script when its suffix (lowercased) is `.sh` or its first line is a
   shebang whose resolved interpreter is `bash` or `sh` (including `env` and `env -S`/`-flag`
   forms; the shebang is lowercased before parsing, so `#!/usr/bin/env BASH` qualifies).
@@ -62,9 +63,9 @@ single pass. Do not substitute the VS Code task wrappers for the native command
 - Coverage is measured with kcov, which emits a single merged Cobertura report `cov.xml` under
   `artifacts/pester/kcov` (or `SHELL_QC_KCOV_OUT_DIR`). The run prints
   `Bash coverage (lines): NN.N%`.
-- The kcov include pattern covers all three discovery roots — `tools/`, `scripts/`, and
-  `.claude/lib/bash/` — so the Claude bash library is measured, not merely discovered. The
-  `tests/` tree remains excluded.
+- The kcov include pattern covers all four discovery roots — `tools/`, `scripts/`,
+  `.claude/lib/bash/`, and `.claude/skills/` — so the Claude bash library and skill-bundled scripts are
+  measured, not merely discovered. The `tests/` tree remains excluded.
 - kcov reports **line coverage only**. The uniform line-coverage threshold (>= 85% per
   `.claude/rules/quality-tiers.md`) applies. Branch coverage is not measurable by kcov for
   bash; there is no bash branch-coverage gate.

package/resources/claude-customizations/.claude/skills/cleanup-merged-worktrees/SKILL.md

@@ -6,7 +6,7 @@ allowed-tools:
   - Grep
   - Glob
   - Agent
-  - "Bash(bash scripts/bash/cleanup-worktrees.sh *)"
+  - "Bash(bash .claude/skills/cleanup-merged-worktrees/scripts/cleanup-worktrees.sh *)"
   - "Bash(git fetch *)"
   - "Bash(git merge-base *)"
   - "Bash(git push *)"
@@ -27,9 +27,9 @@ allowed-tools:
 
 Drive the end-to-end cleanup of stale git worktrees and branches after their work has
 merged into `main`. The deterministic classification, consolidation staging, and
-deletion mechanics live in `scripts/bash/cleanup-worktrees.sh` (wrapping
-`scripts/bash/cleanup_worktrees_lib.sh` and
-`scripts/bash/cleanup_worktrees_actions_lib.sh`). This skill owns the editorial and
+deletion mechanics live in `.claude/skills/cleanup-merged-worktrees/scripts/cleanup-worktrees.sh` (wrapping
+`.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_lib.sh` and
+`.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_actions_lib.sh`). This skill owns the editorial and
 orchestration layer: deciding whether flagged unique content is genuinely
 documentation/memory material, driving consolidation onto a single
 `documentationandmemories` branch, delegating PR creation to `Agent(pr-author)`, and
@@ -145,7 +145,7 @@ The script emits pipe-delimited, `LC_ALL=C`-ordered records, one per line:
 
 ## End-to-End Workflow
 
-1. **Detect and report (dry run).** Run `bash scripts/bash/cleanup-worktrees.sh`
+1. **Detect and report (dry run).** Run `bash .claude/skills/cleanup-merged-worktrees/scripts/cleanup-worktrees.sh`
    (report mode is the default and mutates nothing). It verifies local `main` against
    `origin/main` (emitting `WARN|main-divergence` on drift), enumerates branches and
    worktrees, and prints one `BRANCH|` line per branch plus `COMMIT|...|UNIQUE|...`
@@ -203,7 +203,7 @@ The script emits pipe-delimited, `LC_ALL=C`-ordered records, one per line:
    consolidated commit is now reachable from `main`; that is the only state that unlocks
    deletion of branches whose unique content was consolidated.
 
-6. **Run the apply-mode deletion.** Run `bash scripts/bash/cleanup-worktrees.sh --apply`.
+6. **Run the apply-mode deletion.** Run `bash .claude/skills/cleanup-merged-worktrees/scripts/cleanup-worktrees.sh --apply`.
    It re-verifies each candidate's ancestry/equivalence in-process, removes worktrees
    (without force; a dirty worktree is reported via `DIRTY|` lines and skipped), then
    deletes branches with `git branch -D`. The now-merged `documentationandmemories`
@@ -241,7 +241,7 @@ The script emits pipe-delimited, `LC_ALL=C`-ordered records, one per line:
 
 When report mode classifies every candidate as `MERGED_CLEAN` or `MERGED_EQUIVALENT`
 with an empty cherry-pick-candidate list, skip steps 3-5 entirely: proceed directly from
-the report to `bash scripts/bash/cleanup-worktrees.sh --apply`. Cleanup completes in a
+the report to `bash .claude/skills/cleanup-merged-worktrees/scripts/cleanup-worktrees.sh --apply`. Cleanup completes in a
 single session with no PR.
 
 ## Dirty Worktree Triage Procedure
@@ -464,7 +464,7 @@ These records serve the consolidation consumer and are never read by either gate
       "branch_state": "HAS_UNIQUE_RESIDUALS",
       "removal_disposition": "SAFE_TO_DELETE",
       "verdict": "ALREADY_SOLVED_ELSEWHERE",
-      "evidence": "Unique residual commit 3f9a1c2 records the cleanup-worktrees ancestry error; main already fixes it at scripts/bash/cleanup_worktrees_lib.sh:214-231 under issue #612."
+      "evidence": "Unique residual commit 3f9a1c2 records the cleanup-worktrees ancestry error; main already fixes it at .claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_lib.sh:214-231 under issue #612."
     }
   ],
   "preserved_files": [