@danmoisan/drm-copilot-mcp 1.1.16 → 1.1.18

package/resources/claude-customizations/.claude/rules/orchestrator-state.md

@@ -24,7 +24,7 @@ description: Checkpoint invariants for the orchestration state artifact and the
 
 # Orchestrator-State Remediation-Cycle and Human-Interaction Invariants
 
-This rule governs remediation-cycle records and the optional `human_interaction` block in the orchestrator-state checkpoint at `artifacts/orchestration/orchestrator-state.json`. It documents three invariants that must hold for each remediation cycle, plus three invariants for the `human_interaction` block, so that resume and review workflows do not depend on a structurally invalid checkpoint.
+This rule governs remediation-cycle records and the optional `human_interaction` block in the orchestrator-state checkpoint at `artifacts/orchestration/orchestrator-state.json`. It documents the invariants that must hold for each remediation cycle and for the remediation-loop review outcomes and attempt count, plus three invariants for the `human_interaction` block, so that resume and review workflows do not depend on a structurally invalid checkpoint.
 
 ## Foreign Schema Warning (do not copy verbatim)
 
@@ -34,7 +34,7 @@ This prohibition is specific to the disqualified foreign schema identified by th
 
 ## Scope and Backward Compatibility
 
-These invariants apply only when the checkpoint contains a top-level `remediation_loop` with a `cycles` array. A checkpoint with no `remediation_loop` (the existing step-based checkpoint shape) is unaffected: it validates exactly as before and produces no new errors. The invariants are additive.
+These invariants apply only when the checkpoint contains a top-level `remediation_loop`; the per-cycle invariants apply when it has a `cycles` array, and the review-outcome and attempt-count invariants apply when their keys are present. A checkpoint with no `remediation_loop` (the existing step-based checkpoint shape) is unaffected: it validates exactly as before and produces no new errors. The invariants are additive.
 
 ## Invariants (per remediation cycle)
 
@@ -44,6 +44,45 @@ These invariants apply only when the checkpoint contains a top-level `remediatio
 
 3. **Exit gate requires zero blocking findings.** When a cycle's `exit_condition_met == true`, its `blocking_count` must be `0`. A non-zero `blocking_count` with `exit_condition_met == true` is a malformed cycle (the exit gate was marked satisfied while blocking findings remained).
 
+4. **`candidate_applied` is a boolean (R5).** When a cycle object carries `candidate_applied`, its value must be a JSON boolean, and any other value is a malformed cycle.
+
+5. **A completed attempt requires completed execution (R6).** A cycle whose `candidate_applied == true` must have `execution_status == "complete"`, and `candidate_applied == true` with any other execution status is a malformed cycle.
+
+6. **`opened_by_review` references a remediation review (R11).** When a cycle object carries `opened_by_review`, its value must be a non-negative integer (not a boolean) that indexes an object entry of the `remediation_loop.review_outcomes` list whose `verdict` is `REMEDIATION_REQUIRED`, and a value that is not such an integer, is out of range, or references an outcome with any other verdict is a malformed cycle.
+
+7. **`completed_attempts` counts completed attempts (R7).** When `remediation_loop.completed_attempts` is present, it must be a non-negative integer (not a boolean) equal to the number of object cycles whose `candidate_applied` is `true` (zero when `cycles` is absent or not a list), and any other value is a malformed loop.
+
+## Invariants (remediation_loop.review_outcomes)
+
+These invariants apply only when `remediation_loop` contains a `review_outcomes` key. The orchestrator appends one entry per review, including a `PASS` review, in the shape `{"verdict": <verdict>, "findings": [{"remediability": <class>}, ...]}`, where `findings` lists the review's blocking findings only. A halt or wait verdict records no remediation cycle.
+
+Review verdicts (exact, case-sensitive):
+
+| Verdict | Condition over the classes of the review's blocking findings |
+|---|---|
+| `PASS` | No blocking findings. |
+| `REMEDIATION_REQUIRED` | At least one `autonomous` finding. |
+| `HALT_NON_REMEDIABLE` | No `autonomous` finding, and at least one `external_dependency`, `policy_hold`, or `human_decision_required` finding. |
+| `AWAITING_CI` | At least one finding, and every finding is `awaiting_ci`. |
+
+Remediability classes (exact, case-sensitive) and the `blocked_reason` member (#523) that a halt or wait records for each class:
+
+| Class | Meaning | `blocked_reason` member |
+|---|---|---|
+| `autonomous` | Repository remediation can resolve the finding without a human decision. | none (remediation loop) |
+| `external_dependency` | A system, service, runtime, or published artifact outside the repository is unavailable or mismatched. | `external_dependency` |
+| `policy_hold` | Proceeding requires a policy decision, exception, or authorization that the orchestrator may not grant. | `policy_hold` |
+| `awaiting_ci` | The finding resolves when a CI result that has not completed becomes available. | `awaiting_ci` |
+| `human_decision_required` | A human must choose between alternatives or approve a direction. | `human_decision_required` |
+
+Derivation order. The verdict is a pure function of the findings' classes, evaluated in this order: no findings yields `PASS`; any `autonomous` finding yields `REMEDIATION_REQUIRED`; any `external_dependency`, `policy_hold`, or `human_decision_required` finding yields `HALT_NON_REMEDIABLE`; otherwise the verdict is `AWAITING_CI`.
+
+1. **`review_outcomes` is a list of objects (R8).** `review_outcomes` must be a list, and each entry must be an object. A non-list value or a non-object entry is malformed.
+
+2. **Verdict and class membership (R9).** Each outcome's `verdict` must be a string among the four verdicts, its `findings` must be a list (a missing key is not a list), and each finding must be an object whose `remediability` is a string among the five classes. Comparisons are case-sensitive, so a case variant such as `Pass` or `Autonomous` is malformed.
+
+3. **Verdict matches its findings (R10).** When an outcome passes the membership checks, its `verdict` must equal the verdict that the derivation order yields for its findings' classes. A mismatch is a malformed outcome.
+
 ## Human-Interaction Scope and Backward Compatibility
 
 These invariants apply only when the checkpoint contains a top-level `human_interaction` block. A checkpoint with no `human_interaction` key (the existing checkpoint shape) is unaffected: it validates exactly as before and produces no new errors. The invariants are additive and support the autonomous-execution mandate documented in `.claude/skills/orchestrate/SKILL.md`.
@@ -56,6 +95,41 @@ These invariants apply only when the checkpoint contains a top-level `human_inte
 
 3. **Exception requires `runbook_path`.** A requirement whose `response == "exception"` must carry a non-empty `runbook_path` string. A missing, non-string, or empty/whitespace-only `runbook_path` on an `exception` requirement is a malformed requirement.
 
+## Blocked-Reason Vocabulary
+
+The checkpoint key `blocked_reason` accepts exactly the twelve members below. The authoritative definition is `scripts/dev_tools/_orchestrator_state_blocked_reason.py`; the TypeScript module `extensions/drm-copilot/src/lib/validate/orchestrator-state-blocked-reason.ts` and the grouped arrays in `.claude/lib/orchestrator-state/OrchestratorState.psm1` mirror it.
+
+| Member | Partition | Definition |
+|---|---|---|
+| `none` | not blocked | The run is not blocked. JSON `null` is equivalent for classification. |
+| `spawn_agent_unavailable` | mechanical | Existing member; meaning unchanged. |
+| `delegation_launch_failed` | mechanical | Existing member; meaning unchanged. |
+| `delegate_no_receipt` | mechanical | Existing member; meaning unchanged. |
+| `delegate_contract_incomplete` | mechanical | Existing member; meaning unchanged. |
+| `validator_failed` | mechanical | Existing member; meaning unchanged. |
+| `user_requested_stop` | mechanical | Existing member; meaning unchanged. |
+| `premise_falsified` | non-mechanical | Every delegation and validator succeeded, but evidence gathered during execution falsified the premise on which the plan was built, so continuing would implement an invalid plan. |
+| `external_dependency` | non-mechanical | The run cannot proceed because a system, service, runtime, or artifact outside the repository's control is unavailable or mismatched, and no in-repository remediation can resolve it. |
+| `policy_hold` | non-mechanical | The run is stopped because proceeding requires a policy decision, exception, or authorization that the orchestrator is not permitted to grant autonomously. |
+| `awaiting_ci` | non-mechanical | The run is waiting for a CI result that has not yet completed, and no remediation is warranted until that result is available. |
+| `human_decision_required` | non-mechanical | The run requires a human to choose between alternatives or approve a direction before it can continue. |
+
+Partition definitions:
+
+- **Not blocked:** `none`, JSON `null`, or key absent at a gate. Plain validation still reports an absent key through the required-key check.
+- **Mechanical:** the orchestration process itself did not complete a step: a tool or delegation failed, a delegate returned no or an incomplete receipt, a validator failed, or the operator stopped execution. Membership is defined by the published constant, not by the wording.
+- **Non-mechanical:** every process step could proceed, but the work cannot continue for a reason that no retry or remediation cycle of the process resolves.
+
+The classification is recoverable from `blocked_reason` alone by looking the value up in the published partition (`classify_blocked_reason` in Python, `classifyBlockedReason` in TypeScript).
+
+Enforcement parity: the Python, PowerShell, and TypeScript validators enforce this vocabulary identically, with case-sensitive comparison. A value outside the vocabulary, including a case variant of any member, is rejected with `Checkpoint has invalid blocked_reason: <value>`. Every non-`none` member, including the five non-mechanical members, blocks completion and PR-creation readiness with the existing messages.
+
+Relationship to `human_interaction.requirements[].response == "halt"`: a human-decision halt may appear in both places. `blocked_reason: "human_decision_required"` classifies the run's halt, and a `human_interaction.requirements[]` entry with `response: "halt"` describes the specific requirement. There is no cross-field rule between them: either may appear without the other, and neither is validated against the other.
+
+Producer guidance for `premise_falsified`: set it when every delegation and validator succeeded but evidence gathered during execution falsified the plan's premise. The evidence path is still recorded in free-form checkpoint keys; `blocked_reason` carries the classification only.
+
+Extension point for #484: #484 consumes `external_dependency`, `policy_hold`, `awaiting_ci`, and `human_decision_required` without renaming, removing, or re-partitioning them; any further halt class is a separate contract change that appends the literal to the non-mechanical partition in all three runtimes, updates the partition oracle and corpus, and updates this section.
+
 ## Complexity-Assessment Scope and Backward Compatibility
 
 These invariants apply only when the checkpoint contains a top-level `complexity_assessments` array. A checkpoint with no `complexity_assessments` key (the existing checkpoint shape) is unaffected: it validates exactly as before and produces no new errors. The invariants are additive and support the two-axis model-selection mechanism documented in `.claude/skills/orchestrate/SKILL.md` (`## Model Selection`). Enforcement is the Python validator, not an imported schema.
@@ -92,7 +166,11 @@ The session `model_budget.fable_policy` switch is a three-way enum `disabled | a
 
 ## Require-Model-Routing Mode Scope and Backward Compatibility
 
-The complexity-assessment and model-routing-receipt invariants above are key-gated: they run only when their key is present, so a checkpoint that omits both arrays passes at every stage. The `require_model_routing` mode adds an existence gate that closes that gap without changing the default behavior. It is an opt-in keyword on `validate_orchestrator_state_text(..., require_model_routing=False)` (CLI flag `--require-model-routing`; MCP parameter `require_model_routing`), defaulting off. Plain, `require_complete`, and `require_pr_creation_ready` calls are unaffected and produce byte-identical results.
+The complexity-assessment and model-routing-receipt invariants above are key-gated: they run only when their key is present, so a checkpoint that omits both arrays passes at every stage. The `require_model_routing` mode adds an existence gate that closes that gap without changing the default behavior. It is an opt-in keyword on `validate_orchestrator_state_text(..., require_model_routing=False)` (CLI flag `--require-model-routing`, accepted by the dispatcher `orchestrator-state` subcommand and by the bare-module CLI; MCP parameter `require_model_routing`), defaulting off. Plain, `require_complete`, and `require_pr_creation_ready` calls are unaffected and produce byte-identical results.
+
+## Bare-Module CLI Contract
+
+The validator module runs directly as `python -m scripts.dev_tools.validate_orchestrator_state <path> [--require-complete] [--require-model-routing] [--require-pr-creation-ready] [--require-codex-model-routing] [--require-codex-topology]`. The dispatcher `python -m scripts.dev_tools.validate_orchestration_artifacts orchestrator-state` stays available and accepts the same flags. Exit code 0 means the checkpoint passed and the success line `orchestrator-state validation passed: <path>` is written to stdout. Exit code 1 means validation errors, written one per stderr line. Exit code 2 means the path is missing, unreadable, or not UTF-8, with one stderr diagnostic and no traceback; argparse usage errors also exit 2.
 
 ## Invariants (require_model_routing mode)
 
@@ -146,6 +224,43 @@ not a cryptographic or security control.
 
 Field checks 3 through 9 run in the fixed order `pr_url`, `issue_num`, `branch_name`, `authorized_by`, `authorized_at`, `basis`, `run_slug`, `session_id`; the first failure wins and the gate denies with `STANDALONE_MERGE_AUTHORIZATION_MALFORMED` naming that field.
 
+## Issue-Adoption Scope and Backward Compatibility
+
+These invariants apply only when a checkpoint contains a top-level `issue_adoption` key. The key records that the orchestration adopted a GitHub issue that already existed before orchestration started (transferred, filed by hand, or created by epic decomposition), so the issue was never created through `potential_to_issue`. The key is presence-gated: a checkpoint without it validates byte-identically to before and produces no new errors. It is evaluated only by the routing-contract completion check (`validate_routing_contract` and its TypeScript and PowerShell ports). It is not a member of `REQUIRED_STATE_KEYS`, it is not read by plain (non-completion) validation, and it is not read by the PR-creation-readiness gate. No JSON Schema file is authored, imported, or read for it.
+
+Honest disclosure: the validators perform no network I/O. They cannot confirm that the issue exists, so `evidence` and `verified_via` are an auditable declaration of the read-only verification the orchestrator performed, not proof of it. This matches the `standalone_merge_authorizations` precedent above: the record is a policy-level declaration, not a security control.
+
+## Invariants (issue_adoption object)
+
+The object has the shape `{ issue_num, issue_url, origin, verified_via, verified_at, evidence, waived_tools, potential_record? }`.
+
+| Field | Rule |
+| --- | --- |
+| `issue_num` | A string of decimal digits without a leading zero; equal to the checkpoint `issue-num` when that is a string. |
+| `issue_url` | A string ending with `/issues/` followed by `issue_num`. |
+| `origin` | One of `transferred`, `filed_before_orchestration`, `epic_decomposition`. |
+| `verified_via` | One of `gh_issue_view`, `gh_api_get`, `github_mcp_issue_read`. |
+| `verified_at` | Present, not `null`, and not a blank string. |
+| `evidence` | A string with non-whitespace content. |
+| `waived_tools` | A non-empty list of non-blank tool names that includes `potential_to_issue`. |
+| `potential_record` | Required when waiving a promotion-entry tool: a path under `docs/features/potential/` ending in `.md`. |
+
+The rules run in this order, and their errors accumulate:
+
+1. A present value that is not an object (including `null`) yields `Checkpoint issue_adoption must be an object when present.` and evaluation stops.
+2. `issue_num` must be a string of decimal digits without a leading zero (a JSON number is invalid). Only when it is valid and the checkpoint `issue-num` is a different string, `issue_num` must equal the checkpoint issue-num.
+3. `issue_url` must end with `/issues/` followed by a valid `issue_num`.
+4. `origin` must be one of the three origin values.
+5. `verified_via` must be one of the three verification values.
+6. `verified_at` must be present: absent, `null`, and blank strings are rejected; any other value passes.
+7. `evidence` must be a non-empty string.
+8. `waived_tools` must be a non-empty list of non-blank strings; otherwise no further rule-8 or rule-9 check runs. Each entry, in list order, receives the first applicable error of: listed more than once; not in the closed waivable set; not required by the selected route after promotion-type resolution; already holding a successful MCP receipt. The list must include `potential_to_issue`.
+9. Only when the rule-8 shape check passed: each distinct waived promotion-entry tool (`new_potential_entry` or `new_potential_bug_entry`) requires a valid `potential_record`.
+
+The closed waivable set is `potential_to_issue`, `new_potential_entry`, and `new_potential_bug_entry`. `new_active_feature_folder`, `collect_pr_context`, `validate_orchestration_artifacts`, and every other tool can never be waived. All comparisons are ordinal and case-sensitive.
+
+Fail-closed behavior: any adoption error waives nothing, so each missing receipt is still reported as `Checkpoint missing successful MCP receipt: <tool>.`. Adoption errors are placed after the receipt-loop errors and before the `local_execution_overrides` errors. The waiver affects only receipt presence: the declared `required_mcp_tools` equality check with the routing matrix is unchanged, so a checkpoint must still declare every route tool it waives.
+
 ## Enforcement
 
 - `scripts/dev_tools/validate_orchestrator_state.py` appends one error per violated invariant when a `remediation_loop` is present, using the existing validator message style (literal, checkpoint-context prefixed). The validator returns a list of error strings and does not mutate its input.
@@ -157,3 +272,4 @@ Field checks 3 through 9 run in the fixed order `pr_url`, `issue_num`, `branch_n
 - The standalone-merge authorization invariants are enforced by the `PreToolUse` merge gate (`.claude/hooks/enforce-epic-merge-gate.ps1` with its dot-sourced helpers file, and `.codex/hooks/enforce-epic-merge-gate.ps1`) at merge time. The Python checkpoint validator
   does not currently validate standalone_merge_authorizations
   entries; adding that check is recorded as follow-up FU-3.
+- The `issue_adoption` invariants are enforced at completion by the routing-contract check in all three runtimes: `scripts/dev_tools/_orchestrator_state_issue_adoption.py` (Python authority), `extensions/drm-copilot/src/lib/validate/orchestrator-state-issue-adoption.ts`, and `.claude/lib/orchestrator-state/OrchestratorStateIssueAdoption.psm1`, with byte-identical error strings pinned by the shared corpus under `tests/fixtures/orchestrator_state_issue_adoption/`.

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

@@ -611,6 +611,27 @@ in `tests/scripts/dev_tools/test_blast_radius_config_parity.py`, mirrored in
 union of both copies' top-level keys is exhaustively covered by the three declared classes, and
 an unclassified key or a key present in only one copy fails loudly and names itself.
 
+**A destination records its own entries in `config/blast-radius.local.json` (issue #508).** The
+push-down regenerates a destination's `config/blast-radius.json` on every push, so an entry
+hand-added to that file does not survive the next push. The supported extension point is the
+destination-owned overlay `config/blast-radius.local.json`. No payload contains it, and the
+push-down never writes or publishes it: both implementations list it in `EXCLUDED_RELATIVE_PATHS`.
+At push time the overlay is composed onto the freshly generated base document (the derived document
+in TypeScript, the published document in Python), and the composed result is written to
+`config/blast-radius.json`, so consumers continue to read one file. Per-key semantics: the
+string-list keys `shared_surfaces`, `shared_surface_globs`, `mandate_reads`, `mergeable_paths`, and
+`path_roots` take an ordered union (base entries first, then overlay-only entries, duplicates
+removed); an overlay module absent from the base is added and an overlay module with the same name
+replaces that module's glob list, with module names emitted in ordinal order; `conflict_tolerance`
+merges recursively (nested lists by union, nested objects per member, nested scalars overlay-wins);
+the scalars `over_breadth_fraction` and `write_intent_extraction` take the overlay value; overlay-only
+keys are appended after the base keys. An overlay `version` must equal the base `version`, and the
+forbidden-glob guard (`**`, `docs/**`, `tests/**`) applies to the composed module map, including
+overlay-authored modules. A malformed overlay, a `version` mismatch, or a forbidden glob raises an
+error before any write, so `config/blast-radius.json` keeps its prior bytes. With no overlay
+present, the written file is byte-identical to the base document. The overlay cannot remove a
+shipped surface or a derived module.
+
 ## Enforcement
 
 - `scripts/dev_tools/validate_parallel_orchestrator_state.py`, with the helper modules `scripts/dev_tools/_parallel_state_common.py`, `scripts/dev_tools/_parallel_state_structures.py`, and `scripts/dev_tools/_parallel_state_records.py`, appends one error per violated orchestrator invariant. The completion-gate invariants 20 and 21 run only when the caller passes `require_complete=True`.

package/resources/claude-customizations/.claude/rules/quality-tiers.md

@@ -6,7 +6,7 @@ description: Module rigor tier system and uniform coverage thresholds.
 
 # Module Rigor Tiers
 
-This rule defines the T1–T4 module rigor tier system used by all CI gates in this repository. The tier system source of truth is `docs/ci.research.md` section 1; the file `quality-tiers.yml` at the repository root maps every project to a tier. Adding a project without a tier classification fails CI.
+This rule defines the T1–T4 module rigor tier system used by all CI gates in this repository. The tier definitions and gate matrix in this document are the tier system's source of truth; the file `quality-tiers.yml` at the repository root maps every project to a tier. Adding a project without a tier classification fails CI.
 
 ## Tiers
 

package/resources/claude-customizations/.claude/skills/acceptance-criteria-tracking/SKILL.md

@@ -70,6 +70,14 @@ During plan execution, after completing a task whose work satisfies an acceptanc
 
 Timing: Check off AC items as soon as the corresponding plan task passes verification — do not defer all AC updates to the end of plan execution.
 
+### CI-Dependent Criteria
+
+A CI-dependent criterion is one whose verification requires the result of CI on the PR head. It cannot be verified before the pull request exists, so it stays unchecked and is listed as pending-CI in the AC verification artifact until CI has run.
+
+- Owner: the item's own orchestrator run owns the check-off and performs it at S9; this is the one case in which an orchestrator run checks off AC. A parent or coordinating session never commits the check-off from its own root.
+- Timing: after the CI green gate (S9) records `ci_gate.conclusion` as `success`, and before the run reports DONE.
+- Push and re-verify: the check-off is committed in the item's own worktree and pushed to the PR branch, and the CI green gate is re-run against the new head SHA so that `ci_gate.head_sha` equals the final PR head before DONE.
+
 ### When Reviewers Check Off AC
 
 During feature review (feature-audit phase):

package/resources/claude-customizations/.claude/skills/atomic-plan-contract/SKILL.md

@@ -212,6 +212,8 @@ Rules:
 - **Observe a command's success-case output before asserting over that output (mandatory).** Run the command, or read a recorded run of it, and confirm the value you intend to assert is actually printed on a *successful* run. Do not infer it from the tool's documentation, from the plan, or from what the tool prints on failure. This requirement exists because the class of defect it prevents is not detectable by reading: an assertion on a line the tool prints only when it changed something is unsatisfiable on a clean run; a demand for a zero-diagnostic count from a tool that returns only an ok flag names a value with no source; a demand for separate line and branch percentages from a coverage run that prints one combined column reads two numbers that are never printed. G7 and G9 cover two decidable slices of this class. The remainder is covered by this requirement and by nothing else, so a reviewer cannot rely on the gate to catch it.
 - **Fix the evidence in the plan; never leave the executor to select it.** An executor free to choose the evidence it is judged against cannot fail. Do not write an acceptance condition that asks the executor to identify "the known-genuine pair", to choose a survivor list, or to pick any suitable instance. Name the instances, or state the mechanical derivation that produces them, so a third party re-running it obtains the same set. This is authoring guidance and not a rule: a validator rule that scanned acceptance text for selection vocabulary was proposed and rejected, because that vocabulary is ordinary plan prose used in roles carrying no selection semantics and a keyword scan over prose is not statically decidable for the property it would claim to detect. The judgment is the author's, and it is not automated. `.claude/rules/plan-acceptance-gates.md` records the rejection and the reason for it.
 - **Check that the task-ordering does not make the condition unsatisfiable.** No rule covers this. A gate that runs a test path containing deliberately-failing cases added by an earlier task, before the later task that makes them pass, cannot exit 0. A baseline captured after a write-mode formatter has already repaired pre-existing drift becomes either a blanket waiver or makes a later gate unsatisfiable. Read each acceptance condition against the state the plan will actually be in when its task runs.
+- **Name the runner and job for a Pester acceptance criterion.** CI runs Pester in two jobs of `.github/workflows/_poshqc.yml`: `poshqc / PowerShell QC` runs every suite with coverage on `windows-latest`, and `poshqc / PowerShell hook suites (Linux)` runs only `tests/scripts/claude-hooks` and `tests/scripts/codex-hooks` on `ubuntu-latest`, with coverage disabled. A Pester acceptance criterion may cite `ubuntu-latest` only for suites under `tests/scripts/claude-hooks` or `tests/scripts/codex-hooks`, never for coverage, and must name the job it relies on (`poshqc / PowerShell QC` or `poshqc / PowerShell hook suites (Linux)`).
+- **Do not assert a fixed-string search literal that contains a backslash.** Git for Windows grep 3.0 reads a doubled backslash in a `grep -F` pattern as one backslash, so the same check returns a different count locally than on a CI runner and cannot pass in both places. Assert a backslash-free substring of the literal, a named test, or a hash or byte-identity check instead.
 
 ## Plan-Path Continuity Contract (Mandatory)
 

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

@@ -128,9 +128,17 @@ The script emits pipe-delimited, `LC_ALL=C`-ordered records, one per line:
   per-file outcome is reported by the companion `ACTION|preserve-stage|...` record.
 - `ORPHAN_DIR|<path>|<size>` — a directory under a worktree-tracking root that carries
   no `.git` pointer file and no `git worktree list` entry. `<size>` is best-effort and
-  may be the literal `unknown`. The record is advisory: it reports the directory, and
-  nothing in apply mode acts on it. For the disposition, see the Dirty Worktree Triage
-  Procedure's step 7, which governs how an orphaned directory is handled.
+  may be the literal `unknown`. The scanned roots are the default pair
+  `<main>/.claude/worktrees` and `<main>-wt`, or the `CLEANUP_WT_ORPHAN_ROOTS` entries
+  when that variable is set (the override replaces the default pair), plus the parent
+  directory of every non-main registered worktree, which is always added. A derived
+  parent is skipped when it is the main worktree or one of its ancestors, or is equal to
+  or inside a registered worktree. `CLEANUP_WT_ORPHAN_ROOTS` entries are separated by a
+  semicolon, a newline, or a colon; a colon that follows a single drive letter and
+  precedes `/` or `\` is part of the path, and empty or relative entries are dropped.
+  The record is advisory: it reports the directory, and nothing in apply mode acts on
+  it. For the disposition, see the Dirty Worktree Triage Procedure's step 7, which
+  governs how an orphaned directory is handled.
 - `STALE_REF|<refname>` — a `refs/remotes/<name>/*` ref whose `<name>` is not a
   configured remote, named in full ref form. Advisory only; no ref is ever pruned by
   this tool.

package/resources/claude-customizations/.claude/skills/cleanup-merged-worktrees/scripts/cleanup-worktrees.sh

@@ -139,8 +139,17 @@ Environment overrides:
                                nonexistent value is treated as missing (falls back to
                                the bundled cleanup_worktrees_scan_helper.sh). This is
                                the filesystem-scan test-stub seam.
-  CLEANUP_WT_ORPHAN_ROOTS      Colon-separated override for the worktree-tracking roots
-                               scanned for ORPHAN_DIR and WARN|registration-lost.
+  CLEANUP_WT_ORPHAN_ROOTS      Worktree-tracking roots scanned for ORPHAN_DIR and
+                               WARN|registration-lost. Entries are separated by a
+                               semicolon, a newline, or a colon; a colon that follows
+                               a single drive letter and precedes / or \ is part of
+                               the path (C:/x). Empty and relative entries are
+                               dropped. When set, it replaces the default pair
+                               <main>/.claude/worktrees and <main>-wt. The parent of
+                               every non-main registered worktree is always added,
+                               except a parent that is the main worktree or its
+                               ancestor, or is equal to or inside a registered
+                               worktree.
   CLEANUP_WT_STUB_SCENARIO     Scenario directory consumed by the checked-in git and
                                scan stubs (tests only).
   CLEANUP_WT_CONSOLIDATION_PATH Override the derived consolidation worktree path

package/resources/claude-customizations/.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_enumerate_lib.sh

@@ -4,16 +4,19 @@
 # every file within the 500-line cap. Provides the git-binary test seam
 # (cleanup_wt_git), branch/worktree enumeration (enumerate_branches,
 # parse_worktree_list), path normalization (normalize_wt_path), the
-# current-worktree/branch and base-branch protection set (compute_protected), and
-# the main-freshness warning (check_main_freshness). The classification ladder,
-# consolidation, deletion, and the CLI live in sibling files (cleanup_worktrees_lib.sh,
-# cleanup_worktrees_actions_lib.sh, cleanup-worktrees.sh).
+# current-worktree/branch and base-branch protection set (compute_protected), the
+# main-freshness warning (check_main_freshness), the shared absolute-path predicate
+# (cleanup_wt_is_absolute_path), and the worktree-tracking scan roots
+# (cleanup_wt_split_roots, cleanup_wt_derive_scan_roots, cleanup_wt_scan_roots). The
+# classification ladder, consolidation, deletion, and the CLI live in sibling files
+# (cleanup_worktrees_lib.sh, cleanup_worktrees_actions_lib.sh, cleanup-worktrees.sh).
 #
 # Sourcing contract: defines functions and the single constant CLEANUP_WT_BASE_BRANCH
 # and runs no other work at source time, so wrapper and bats suites source it safely.
 # It MUST be sourced before cleanup_worktrees_lib.sh, whose classification functions
 # call cleanup_wt_git, parse_worktree_list, compute_protected, and normalize_wt_path
-# defined here.
+# defined here. The filesystem-scan helper cleanup_worktrees_scan_helper.sh runs as a
+# separate process and sources this library directly for cleanup_wt_is_absolute_path.
 #
 # All git commands go through cleanup_wt_git so tests can stub the git binary via
 # CLEANUP_WT_GIT_BIN. Git exit-code capture rule: the `git worktree list --porcelain`
@@ -250,3 +253,164 @@ check_main_freshness() {
 	fi
 	return 0
 }
+
+cleanup_wt_is_absolute_path() {
+	# Return 0 when <path> is absolute, else 1. Pure: no filesystem access.
+	#
+	# Absolute forms are a leading `/` (POSIX paths, MSYS `/c/...` paths, and `//server`
+	# UNC paths) and a drive letter followed by `/` or `\` (`C:/...`, `c:/...`,
+	# `C:\...`), which is the form Git for Windows writes into a worktree's `.git`
+	# pointer file (issue #706). A drive letter with no separator (`C:rel`) is
+	# drive-relative and is not absolute; an empty path is not absolute. This is the one
+	# absolute-path predicate of the skill: the preserve library and the filesystem-scan
+	# helper both call it.
+	#
+	# Args: $1 = path. Returns 0 (absolute) or 1 (not absolute).
+	local path=${1:-}
+	[[ $path == /* || $path == [A-Za-z]:[/\\]* ]]
+}
+
+cleanup_wt_split_roots() {
+	# Split a CLEANUP_WT_ORPHAN_ROOTS value into absolute roots, one per line.
+	#
+	# Entries are separated by `;`, by a newline, or by `:`. A `:` is part of the path
+	# instead when the text before it in the current entry is exactly one ASCII letter
+	# and the character after it is `/` or `\` (a drive letter, as in `C:/x`). Empty
+	# entries are dropped. An entry that is not absolute (cleanup_wt_is_absolute_path) is
+	# dropped with a one-line stderr diagnostic naming it, because a relative root would
+	# be resolved against the process's current working directory.
+	#
+	# The value is walked one character at a time with parameter expansion and never
+	# word-split, so no pathname expansion occurs and a `*` is emitted literally.
+	#
+	# Args: $1 = the override value. Always returns 0.
+	local value=${1:-}
+	local -a entries=()
+	local entry="" ch next i
+	for ((i = 0; i < ${#value}; i++)); do
+		ch=${value:i:1}
+		if [[ $ch == ';' || $ch == $'\n' ]]; then
+			entries+=("$entry")
+			entry=""
+		elif [[ $ch == ':' ]]; then
+			next=${value:i+1:1}
+			if [[ ${#entry} -eq 1 && $entry == [A-Za-z] && $next == [/\\] ]]; then
+				entry+=$ch
+			else
+				entries+=("$entry")
+				entry=""
+			fi
+		else
+			entry+=$ch
+		fi
+	done
+	entries+=("$entry")
+	for entry in "${entries[@]}"; do
+		[[ -z $entry ]] && continue
+		if ! cleanup_wt_is_absolute_path "$entry"; then
+			printf 'cleanup-worktrees: CLEANUP_WT_ORPHAN_ROOTS entry is not absolute, dropped: %s\n' "$entry" >&2
+			continue
+		fi
+		printf '%s\n' "$entry"
+	done
+	return 0
+}
+
+cleanup_wt_derive_scan_roots() {
+	# Echo the registration-derived scan roots, one per line.
+	#
+	# Input is parse_worktree_list output; its first record is the main worktree. The
+	# candidate for every later record is the parent directory of its path (backslashes
+	# converted to `/`). A candidate is kept only when its normalize_wt_path value N:
+	#   - is not the main worktree's normalized path and is not one of its ancestors
+	#     (scanning an ancestor would list the main worktree's siblings), and
+	#   - is not equal to, and not inside, any registered worktree, main included
+	#     (its subdirectories are that worktree's own content, not worktrees).
+	# Kept candidates are emitted in LC_ALL=C order of N, once per N, using the first
+	# spelling seen in record order.
+	#
+	# Args: $1 = parse_worktree_list output. Always returns 0.
+	local records=${1:-}
+	local -a paths=() norms=()
+	local record path
+	while IFS= read -r record; do
+		[[ -z $record ]] && continue
+		path=${record%%|*}
+		paths+=("$path")
+		norms+=("$(normalize_wt_path "$path")")
+	done <<<"$records"
+	((${#paths[@]} < 2)) && return 0
+	local main_norm=${norms[0]}
+	local -A seen=()
+	local -a kept=()
+	local i p parent n w inside
+	for ((i = 1; i < ${#paths[@]}; i++)); do
+		p=${paths[i]//\\//}
+		parent=${p%/*}
+		[[ -z $parent || $parent == "$p" ]] && continue
+		n=$(normalize_wt_path "$parent")
+		[[ -z $n || -n ${seen[$n]:-} ]] && continue
+		[[ $n == "$main_norm" || $main_norm == "$n"/* ]] && continue
+		inside=0
+		for w in "${norms[@]}"; do
+			[[ -z $w ]] && continue
+			if [[ $n == "$w" || $n == "$w"/* ]]; then
+				inside=1
+				break
+			fi
+		done
+		((inside == 1)) && continue
+		seen[$n]=1
+		kept+=("$n|$parent")
+	done
+	((${#kept[@]} == 0)) && return 0
+	local line
+	while IFS= read -r line; do
+		printf '%s\n' "${line#*|}"
+	done < <(printf '%s\n' "${kept[@]}" | LC_ALL=C sort -t '|' -k1,1)
+	return 0
+}
+
+cleanup_wt_scan_roots() {
+	# Echo the worktree-tracking roots to scan, one per line.
+	#
+	# Configured roots come first: the CLEANUP_WT_ORPHAN_ROOTS entries
+	# (cleanup_wt_split_roots) when that variable is set, otherwise the default pair
+	# derived from the main worktree path (the first `git worktree list --porcelain`
+	# stanza, the same derivation consolidation_worktree_path uses in
+	# cleanup_worktrees_actions_lib.sh): `<main>/.claude/worktrees` then `<main>-wt`.
+	# Registration-derived roots (cleanup_wt_derive_scan_roots) are always appended.
+	# The combined list is deduplicated by normalize_wt_path, keeping the first spelling.
+	#
+	# The listing is read once (`out=$(...) || rc=$?`). On a parse_worktree_list hard
+	# failure nothing is derived from it: with no override no root is emitted at all,
+	# rather than a bare relative path resolved against the current working directory,
+	# and with an override exactly the override roots are emitted.
+	# cleanup_wt_scan_records returns 0 with no record for an empty root list, so the
+	# advisory records degrade to silence rather than to a misleading scan.
+	# Always returns 0.
+	local out rc=0 first_record main_wt="" configured="" derived=""
+	out=$(parse_worktree_list) || rc=$?
+	if ((rc == 0)); then
+		first_record=${out%%$'\n'*}
+		main_wt=${first_record%%|*}
+		derived=$(cleanup_wt_derive_scan_roots "$out")
+	fi
+	if [[ -n ${CLEANUP_WT_ORPHAN_ROOTS:-} ]]; then
+		configured=$(cleanup_wt_split_roots "$CLEANUP_WT_ORPHAN_ROOTS")
+	elif [[ -n $main_wt ]]; then
+		configured="${main_wt}/.claude/worktrees"$'\n'"${main_wt}-wt"
+	fi
+	local -A seen=()
+	local root n
+	while IFS= read -r root; do
+		[[ -z $root ]] && continue
+		n=$(normalize_wt_path "$root")
+		# A root of `/` normalizes to empty, which is not a valid array key.
+		[[ -z $n ]] && n=/
+		[[ -n ${seen[$n]:-} ]] && continue
+		seen[$n]=1
+		printf '%s\n' "$root"
+	done <<<"${configured}"$'\n'"${derived}"
+	return 0
+}

package/resources/claude-customizations/.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_preserve_lib.sh

@@ -158,7 +158,7 @@ preserve_relative_path_reason() {
 	local name=${1-} val=${2-}
 	if [[ -z $val ]]; then
 		printf '%s is empty' "$name"
-	elif [[ $val == /* || $val == [A-Za-z]:[\\/]* ]]; then
+	elif cleanup_wt_is_absolute_path "$val"; then
 		printf '%s is absolute: %s' "$name" "$val"
 	elif [[ $val == ".." || $val == "../"* || $val == *"/../"* || $val == *"/.." ]]; then
 		printf '%s contains a .. segment: %s' "$name" "$val"

package/resources/claude-customizations/.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_report_records_lib.sh

@@ -6,10 +6,10 @@
 # whose gitdir pointer no longer resolves, and the ancestor relationship between two
 # branches that both resolve NOT_MERGED. The enumeration/protection seam
 # (cleanup_wt_git, enumerate_branches, parse_worktree_list, normalize_wt_path,
-# compute_protected, check_main_freshness) lives in cleanup_worktrees_enumerate_lib.sh
-# and the classification ladder (classify_branch) lives in cleanup_worktrees_lib.sh;
-# both MUST be sourced before this file. Keeping these records in a sibling file keeps
-# every file within the 500-line cap.
+# compute_protected, check_main_freshness, cleanup_wt_scan_roots) lives in
+# cleanup_worktrees_enumerate_lib.sh and the classification ladder (classify_branch)
+# lives in cleanup_worktrees_lib.sh; both MUST be sourced before this file. Keeping
+# these records in a sibling file keeps every file within the 500-line cap.
 #
 # Sourcing contract: this library defines functions only; it never runs work at source
 # time, so the wrapper and the bats suites can source it without side effects.
@@ -111,47 +111,10 @@ scan_stale_refs() {
 	return 0
 }
 
-cleanup_wt_scan_roots() {
-	# Echo the worktree-tracking roots to scan, one per line.
-	#
-	# CLEANUP_WT_ORPHAN_ROOTS overrides the derivation with a colon-separated list.
-	# Otherwise BOTH roots derive from the main worktree path — the first
-	# `git worktree list --porcelain` stanza, the same derivation
-	# consolidation_worktree_path uses in cleanup_worktrees_actions_lib.sh. They are
-	# `<main-worktree-path>` joined with `.claude/worktrees` (the agent worktree folder)
-	# and `<main-worktree-path>-wt` (the sibling worktree folder), in that order.
-	#
-	# Deriving both from one read means a parse_worktree_list hard failure emits no root
-	# at all, rather than a bare relative path that would be resolved against whatever
-	# the process's current working directory happened to be. cleanup_wt_scan_records
-	# returns 0 with no record for an empty root list, so the advisory records degrade to
-	# silence rather than to a misleading scan. Always returns 0.
-	local override=${CLEANUP_WT_ORPHAN_ROOTS:-}
-	if [[ -n $override ]]; then
-		local IFS=:
-		local part
-		for part in $override; do
-			[[ -n $part ]] && printf '%s\n' "$part"
-		done
-		return 0
-	fi
-	local out rc=0 first_record main_wt=""
-	out=$(parse_worktree_list) || rc=$?
-	if ((rc != 0)); then
-		return 0
-	fi
-	first_record=${out%%$'\n'*}
-	main_wt=${first_record%%|*}
-	if [[ -n $main_wt ]]; then
-		printf '%s\n' "${main_wt}/.claude/worktrees"
-		printf '%s\n' "${main_wt}-wt"
-	fi
-	return 0
-}
-
 cleanup_wt_scan_records() {
 	# Echo the raw `<path>|<has_gitfile>|<gitdir_target_exists>|<size>` records for every
-	# candidate directory under the resolved scan roots, one per line.
+	# candidate directory under the resolved scan roots, one per line. The roots come
+	# from cleanup_wt_scan_roots in cleanup_worktrees_enumerate_lib.sh.
 	#
 	# Every filesystem read goes through the CLEANUP_WT_SCAN_BIN seam, so the bats suites
 	# replay canned records instead of touching the real filesystem. The scan output is

package/resources/claude-customizations/.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_scan_helper.sh

@@ -40,6 +40,9 @@
 # the SHELL_QC_<TOOL>_BIN seams substitute a checked-in stand-in for a real dependency.
 # An empty value is treated as missing and falls back to `.git`.
 set -euo pipefail
+# shellcheck source=.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_enumerate_lib.sh
+# shellcheck disable=SC1091
+source "$(dirname -- "${BASH_SOURCE[0]}")/cleanup_worktrees_enumerate_lib.sh"
 
 scan_helper_dir_size() {
 	# Echo the best-effort human-readable size of a directory, or `unknown`.
@@ -70,20 +73,6 @@ scan_helper_gitfile_name() {
 	printf '%s\n' ".git"
 }
 
-scan_helper_is_absolute_path() {
-	# Return 0 when <path> is absolute, else 1. Pure: no filesystem access.
-	#
-	# Absolute forms are a leading `/` (POSIX paths, MSYS `/c/...` paths, and `//server`
-	# UNC paths) and a drive letter followed by `/` or `\` (`C:/...`, `c:/...`,
-	# `C:\...`), which is the form Git for Windows writes into a worktree's `.git`
-	# pointer file (issue #706). A drive letter with no separator (`C:rel`) is
-	# drive-relative and is not absolute; an empty path is not absolute.
-	#
-	# Args: $1 = path. Returns 0 (absolute) or 1 (not absolute).
-	local path=${1:-}
-	[[ $path == /* || $path == [A-Za-z]:[/\\]* ]]
-}
-
 scan_helper_target_present() {
 	# Return 0 when <path> exists, else non-zero. This is the helper's single
 	# filesystem existence check, kept in its own function as a test seam: bats tests
@@ -113,7 +102,7 @@ scan_helper_gitdir_target_exists() {
 		printf '0\n'
 		return 0
 	fi
-	if ! scan_helper_is_absolute_path "$target"; then
+	if ! cleanup_wt_is_absolute_path "$target"; then
 		target="$dir/$target"
 	fi
 	if scan_helper_target_present "$target"; then