@danmoisan/drm-copilot-mcp 1.1.14 → 1.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danmoisan/drm-copilot-mcp",
-  "version": "1.1.14",
+  "version": "1.1.15",
   "description": "Stdio MCP server exposing drm-copilot repo-automation tools.",
   "license": "MIT",
   "type": "commonjs",

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/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": [

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

@@ -0,0 +1,234 @@
+#!/usr/bin/env bash
+# cleanup-worktrees.sh: thin CLI wrapper for the cleanup-merged-worktrees tool. It
+# classifies local branches/worktrees against main and, in apply mode only, deletes
+# delete-eligible candidates and drives consolidation. All logic lives in the two
+# sourceable libraries so the functions are unit-testable from bats by sourcing them
+# directly; this wrapper only resolves paths, prints usage, and dispatches.
+set -euo pipefail
+
+# Resolve this script's own directory so the libraries source regardless of cwd.
+SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+# The library paths are resolved at runtime from SCRIPT_DIR, so shellcheck cannot load
+# them as static inputs without -x; SC1091 is the expected, benign result. The
+# enumeration/protection library is sourced first because cleanup_worktrees_lib.sh's
+# classification functions call cleanup_wt_git, parse_worktree_list, compute_protected,
+# and normalize_wt_path defined there.
+# shellcheck source=.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_enumerate_lib.sh
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/cleanup_worktrees_enumerate_lib.sh"
+# The report-record library depends on the enumeration library above and is called BY
+# run_report/run_apply in the two libraries sourced below, so it is sourced between them.
+# shellcheck source=.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_report_records_lib.sh
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/cleanup_worktrees_report_records_lib.sh"
+# shellcheck source=.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_lib.sh
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/cleanup_worktrees_lib.sh"
+# shellcheck source=.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_actions_lib.sh
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/cleanup_worktrees_actions_lib.sh"
+# shellcheck source=.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_detached_lib.sh
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/cleanup_worktrees_detached_lib.sh"
+# Neither of the three libraries below requires being sourced last, and neither claims to
+# be. Each library's source-time work is limited to function definitions plus constant and
+# environment-default variable assignments; none of them calls a function while being
+# sourced, and no function name is defined by more than one library, so no later source can
+# shadow an earlier definition. Bash resolves a function name when the call runs, not when
+# the caller is defined, so the cross-library calls resolve whatever the order: the
+# disposable-dirt classifier is called BY run_report and BY delete_candidate in the
+# libraries above, and the preserve library calls cleanup_wt_git from the enumeration
+# library and consolidation_worktree_path from the actions library. The order here is
+# therefore grouping for readability only.
+# shellcheck source=.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_dirt_lib.sh
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/cleanup_worktrees_dirt_lib.sh"
+# The line-ending and index group is placed immediately before the preserve library, whose
+# read-only planning phase calls the functions it defines.
+# shellcheck source=.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_preserve_eol_lib.sh
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/cleanup_worktrees_preserve_eol_lib.sh"
+# shellcheck source=.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_preserve_lib.sh
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/cleanup_worktrees_preserve_lib.sh"
+
+usage() {
+	# Print the wrapper usage/help text.
+	cat <<'EOF'
+Usage: cleanup-worktrees.sh [command]
+
+Commands:
+  (no args) | report   Dry-run report (default). Classifies every local branch and
+                       worktree against main and prints a deterministic, machine-
+                       parseable report. Performs NO mutation of any kind.
+  --apply | apply      Apply mode. Deletes delete-eligible candidates (MERGED_CLEAN,
+                       MERGED_CONTENT_NEUTRAL, MERGED_EQUIVALENT) after same-process
+                       re-verification, removing worktrees without force and deleting
+                       branches with -D. Never acts on NOT_MERGED,
+                       HAS_UNIQUE_RESIDUALS, or PROTECTED_CURRENT candidates.
+  preserve | --preserve
+                       Stage the manifest's preserved_files[] findings onto the
+                       consolidation branch. Takes no operand; the manifest path comes
+                       from CLEANUP_WT_MANIFEST_PATH. Copies each named source file
+                       verbatim, carries its MEMORY.md index line across using the
+                       destination file's own re-derived line-ending convention, and
+                       refuses the whole pass when the incoming bytes carry a
+                       host-identifying token. Exit 0 clean, 1 something was skipped or
+                       an index was created, 3 host-token hard stop, 127 a required tool
+                       could not be resolved.
+  --help | -h | help   Print this help and exit 0.
+
+Flags:
+  --clear-disposable   Apply mode only, opt-in, and destructive. When a worktree removal
+                       is blocked because the worktree is dirty, and every per-file
+                       verdict for that worktree is disposable, the working tree is
+                       cleared with reset --hard and clean -fd and the SAME unforced
+                       removal is retried once after a fresh in-process re-verification.
+                       Refuses the clear for the whole worktree when any per-file verdict
+                       is UNIQUE, including the fail-closed UNIQUE assigned when a
+                       classification read errors. Ignored files are never cleared. This
+                       flag may be given before or after the apply argument; supplying it
+                       without apply mode is a usage error and exits 2.
+
+Report lines (pipe-delimited, LC_ALL=C ordered): BRANCH|<name>|<state>;
+COMMIT|<branch>|<sha>|<state>|<paths>|<author>|<date>;
+WORKTREE|<path>|<branch>|<flags> for a branch-backed worktree registration;
+WORKTREE|<path>|DETACHED|<state>|<flags> for a detached-HEAD worktree registration,
+which is classified on its own HEAD SHA and whose fifth field preserves the porcelain
+locked and prunable markers; WARN|main-divergence|<local>|<origin>;
+DIRTY|<path>|<status>; ACTION|<verb>|<target>|<result> (apply mode);
+DIRTFILE|<worktree>|<verdict>|<detail>|<xy>|<path>, one per dirty entry in porcelain order;
+DIRTSUM|<worktree>|<aggregate>|<detail>, exactly one per dirty worktree. The verdicts are
+DISPOSABLE_BUILD_ARTIFACT, DISPOSABLE_SESSION_ARTIFACT, CONTENT_ON_MAIN, CONTENT_IN_HISTORY,
+STAGED_TREE_IS_COMMIT, and UNIQUE; the aggregate is ALL_DISPOSABLE or HAS_UNIQUE. Both are
+read-only records and neither unlocks a destructive action on its own.
+
+PRESERVE|<worktree-path>|<source-path>|<verdict> (preserve mode), a manifest
+preserved_files[] finding staged onto the consolidation branch, whose per-file outcome is
+reported by the companion ACTION|preserve-stage|... record.
+
+Advisory, read-only records (report and apply mode; none unlocks a destructive action):
+ORPHAN_DIR|<path>|<size> for a scanned directory with no .git pointer file and no
+worktree registration, where <size> is best-effort and may be the literal unknown;
+STALE_REF|<refname> for a refs/remotes/<name>/* ref whose <name> is not a configured
+remote, in full ref form; CHILD_OF|<branch>|<ancestor> emitted alongside a branch's own
+BRANCH| line when it is a git ancestor of a branch that resolved exactly NOT_MERGED;
+WARN|registration-lost|<path> for a worktree whose .git gitdir pointer no longer
+resolves. Deleting any of these is a manual, individually confirmed action.
+
+Branch and detached-worktree states: MERGED_CLEAN, MERGED_CONTENT_NEUTRAL,
+MERGED_EQUIVALENT, NOT_MERGED, HAS_UNIQUE_RESIDUALS, PROTECTED_CURRENT, and
+ANCESTRY_ERROR. The first three are the delete-eligible allowlist; ANCESTRY_ERROR is a
+hard git failure and never unlocks a destructive action.
+
+PROTECTED_CURRENT also covers the base branch main, which is protected by name in every
+checkout topology: main is never deleted and a worktree checked out on main is never
+removed. As a second guard, apply mode refuses a deletion request for main with the
+action result BLOCKED-PROTECTED-BASE.
+
+In apply mode a blocked detached removal sets a non-zero exit status. The blocked results
+are BLOCKED-DIRTY, BLOCKED-LOCKED, and BLOCKED-REVERIFY. A checkout holding dirty or
+locked detached worktrees therefore exits non-zero from --apply where it previously
+exited 0.
+
+Environment overrides:
+  CLEANUP_WT_GIT_BIN            Path to the git binary; an empty or nonexistent value
+                               is treated as missing (falls back to PATH git). This is
+                               the test-stub seam.
+  CLEANUP_WT_SCAN_BIN          Path to the filesystem-scan helper; an empty or
+                               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_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
+                               (<main-worktree-path>-wt/documentationandmemories).
+  CLEANUP_WT_MANIFEST_PATH     Path to the cleanup-worktrees manifest read by preserve
+                               mode. Defaults to
+                               artifacts/orchestration/cleanup-worktrees-manifest.json.
+  CLEANUP_WT_JQ_BIN            Path to the jq binary used to read that manifest; an empty
+                               or nonexistent value is treated as missing (falls back to
+                               PATH jq). No default. This is the jq test-stub seam.
+EOF
+}
+
+main() {
+	# Dispatch on the first argument. No args or `report` runs the dry-run report;
+	# `--apply`/`apply` runs apply mode; `preserve`/`--preserve` stages the manifest's
+	# preserved_files[] findings onto the consolidation branch and takes no operand,
+	# reading its manifest path from CLEANUP_WT_MANIFEST_PATH; `--help`/`-h`/`help`
+	# prints usage and exits 0;
+	# anything else prints usage to stderr and exits 2 (usage-error parity with
+	# shell-qc.sh). Subcommand return codes are captured so an intermediate failure is
+	# never masked before the final exit.
+	local exit_code=0
+	# --clear-disposable pre-pass, run before the dispatch below so the flag may be given
+	# on either side of the mode argument. The flag is stripped from the argument list and
+	# the remaining first argument must select apply mode: the flag is opt-in and
+	# destructive, so pairing it with report mode (or with no mode at all) is a usage error
+	# rather than a silently ignored flag. Every case arm below is unchanged.
+	local -a args=()
+	local clear_flag=0 arg
+	for arg in "$@"; do
+		if [[ $arg == "--clear-disposable" ]]; then
+			clear_flag=1
+			continue
+		fi
+		args+=("$arg")
+	done
+	if ((clear_flag == 1)); then
+		case "${args[0]:-}" in
+		--apply | apply) ;;
+		*)
+			usage >&2
+			return 2
+			;;
+		esac
+		# Read across a source boundary shellcheck does not follow:
+		# cleanup_worktrees_dirt_lib.sh gates clear_disposable_dirt on this variable and
+		# cleanup_worktrees_actions_lib.sh gates delete_candidate's clear-and-retry block
+		# on it, so SC2034 reports it unused here. The suppression below is line-scoped,
+		# not file-scoped, so SC2034 stays live for every other variable in this file.
+		# The assignment's effect is pinned end to end by the wrapper-driven test pair at
+		# the foot of tests/shell/test_cleanup_worktrees_dirt_clear.bats.
+		# shellcheck disable=SC2034
+		CLEANUP_WT_CLEAR_DISPOSABLE=1
+	fi
+	if ((${#args[@]} > 0)); then
+		set -- "${args[@]}"
+	else
+		set --
+	fi
+	local command=${1:-}
+	case "$command" in
+	"" | report)
+		run_report || exit_code=$?
+		;;
+	--apply | apply)
+		run_apply || exit_code=$?
+		;;
+	preserve | --preserve)
+		run_preserve || exit_code=$?
+		;;
+	--help | -h | help)
+		usage
+		return 0
+		;;
+	*)
+		usage >&2
+		return 2
+		;;
+	esac
+	return "$exit_code"
+}
+
+# Guard so the file can be sourced without executing main. main's return code is
+# captured and re-exited explicitly as the final statement, so intermediate
+# `|| rc=$?` captures inside the libraries cannot mask a real failure.
+if [[ ${BASH_SOURCE[0]} == "${0}" ]]; then
+	rc=0
+	main "$@" || rc=$?
+	exit "$rc"
+fi