@danmoisan/drm-copilot-mcp 1.1.10 → 1.1.12

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

@@ -17,6 +17,7 @@ allowed-tools:
   - "Bash(git diff *)"
   - "Bash(git branch -r*)"
   - "Bash(git worktree list*)"
+  - "Bash(git worktree remove *)"
   - "Bash(gh issue view *)"
   - mcp__drm-copilot__new_potential_bug_entry
   - mcp__drm-copilot__potential_to_issue
@@ -64,11 +65,83 @@ The script emits pipe-delimited, `LC_ALL=C`-ordered records, one per line:
   in `EQUIVALENT | CONTENT_ON_MAIN | EMPTY | UNIQUE | CONFLICT`. A `UNIQUE` COMMIT record
   is a cherry-pick candidate for editorial triage.
 - `WORKTREE|<path>|<branch-or-DETACHED>|<flags>` — worktree registrations.
+- `WORKTREE|<path>|DETACHED|<state>|<flags>` — a detached-HEAD worktree registration,
+  classified on its own HEAD SHA. This five-field record replaces the four-field record
+  above for a detached registration; it is not emitted in addition to it. `state` is one
+  of `MERGED_CLEAN | MERGED_CONTENT_NEUTRAL | MERGED_EQUIVALENT | NOT_MERGED |
+  HAS_UNIQUE_RESIDUALS | PROTECTED_CURRENT | ANCESTRY_ERROR`, where `ANCESTRY_ERROR` is
+  the fail-closed verdict for a hard git failure at any rung of the classification. The
+  fifth field carries the porcelain flag set unchanged, so the `locked` and `prunable`
+  markers are preserved in the record.
 - `WARN|main-divergence|<local-sha>|<origin-sha>` — local `main` differs from
   `origin/main` (advisory; classification still runs).
 - `DIRTY|<worktree-path>|<status-porcelain-line>` — a dirty worktree that blocked
-  removal.
+  removal. This record is apply mode only, and its three-field shape is unchanged by the
+  dirt classifier: the classifier adds the two records below rather than altering or
+  replacing this one.
+- `DIRTFILE|<worktree-path>|<verdict>|<detail>|<xy>|<file-path>` — one record per
+  `git status --porcelain` entry in a dirty worktree, emitted by report mode in porcelain
+  order immediately after that worktree's `WORKTREE|` record. `verdict` is exactly one of
+  `DISPOSABLE_BUILD_ARTIFACT | DISPOSABLE_SESSION_ARTIFACT | CONTENT_ON_MAIN |
+  CONTENT_IN_HISTORY | STAGED_TREE_IS_COMMIT | UNIQUE`, and no other verdict token is ever
+  produced. `detail` carries the commit SHA that justifies the verdict for
+  `STAGED_TREE_IS_COMMIT` and `CONTENT_IN_HISTORY`, and is empty for the other four
+  verdicts. `xy` is the porcelain two-character status field, preserved verbatim including
+  its space. The file path is the last field, so a path containing a pipe character cannot
+  shift any later field. A classification read that fails maps its entry to `UNIQUE`: that
+  is the fail-closed direction, because an entry the tool could not classify is treated as
+  content that must be preserved. `CONTENT_ON_MAIN` is emitted for a tracked entry
+  only when `main` contains the path, so an entry whose content exists only as a staged
+  blob is reported `UNIQUE` rather than as content that is already on `main`. An entry
+  whose porcelain status shows content in both the index and the working tree is likewise
+  reported `UNIQUE`, because the rungs that could otherwise resolve it compare working-tree
+  content only and would leave the differing staged blob unaccounted for.
+  `DISPOSABLE_SESSION_ARTIFACT` matches three fixed
+  repository paths under `artifacts/`, is repository-agnostic, and cannot fire in a checkout
+  that gitignores `artifacts/` — which drm-copilot does at `.gitignore:6` — because the
+  status read never carries `--ignored`; the verdict is retained for consumer checkouts
+  where those paths are not ignored, and it must not be made reachable by adding
+  `--ignored`.
+- `DIRTSUM|<worktree-path>|<aggregate>|<detail>` — exactly one record per dirty worktree,
+  emitted by report mode immediately after that worktree's `DIRTFILE|` records.
+  `aggregate` is `ALL_DISPOSABLE` if and only if the worktree has at least one status
+  entry and none of them is `UNIQUE`, and `HAS_UNIQUE` otherwise. `detail` carries the
+  first non-empty per-entry detail. A worktree with zero status entries emits neither this
+  record nor any `DIRTFILE|` record. Both records are read-only: an `ALL_DISPOSABLE`
+  aggregate unlocks nothing on its own, and clearing happens only when the operator
+  supplies `--clear-disposable` in apply mode.
+
+  Report-mode exit status. When a candidate worktree's `git status --porcelain` read
+  fails, report mode emits no `DIRTFILE|` and no `DIRTSUM|` record for that worktree and
+  returns git's non-zero exit code. A checkout containing such a worktree therefore exits
+  non-zero from report mode where the same checkout previously exited 0 and produced a
+  complete report. This is deliberate. A worktree whose status read failed produces no dirt
+  records at all, so a report that also exited 0 would be indistinguishable from a report
+  about a clean worktree, and an operator would make a deletion decision on silently
+  incomplete data. The non-zero exit is the only channel that carries the incompleteness to
+  a wrapping script. See the analogous apply-mode note in the End-to-End Workflow, where a
+  blocked detached removal sets a non-zero exit status for the same reason.
 - `ACTION|<verb>|<target>|<result>` — apply-mode action results.
+- `PRESERVE|<worktree-path>|<source-path>|<verdict>` — a manifest `preserved_files[]`
+  finding staged onto the consolidation branch; `verdict` in `DEAD_ONE_OFF |
+  ALREADY_SOLVED_ELSEWHERE | STALE_OR_CONTRADICTED | GENUINELY_NEW | STILL_RELEVANT`. The
+  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.
+- `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.
+- `CHILD_OF|<branch>|<ancestor>` — `branch` is a git ancestor of `ancestor`, and both
+  resolved exactly `NOT_MERGED` through their own full ladders. It is emitted alongside,
+  never instead of, the branch's own `BRANCH|<branch>|NOT_MERGED` line, and names the
+  containment relationship so an operator can see that the branch's work is not lost
+  when the named ancestor is retained.
+- `WARN|registration-lost|<path>` — a worktree directory whose `.git` pointer file names
+  a gitdir target that no longer exists. Git commands run inside such a directory fail
+  in confusing ways. Advisory only.
 
 ## End-to-End Workflow
 
@@ -101,11 +174,31 @@ The script emits pipe-delimited, `LC_ALL=C`-ordered records, one per line:
    (`artifacts/orchestration/orchestrator-state.json`) with `--require-pr-creation-ready`
    and record the `pr_author_preflight` result; delegation is prohibited when that
    validation fails. Then delegate PR creation to `Agent(pr-author)` per
-   `.claude/skills/pr-author/SKILL.md`, using `<N> = 396` for the body-file and receipt
-   contract. This skill never authors or creates the PR itself.
-
-5. **Wait for merge and verify git-natively.** After the consolidation PR merges,
-   verify it with `git fetch` followed by
+   `.claude/skills/pr-author/SKILL.md`, which owns the body-file and receipt contract;
+   defer to that skill for it rather than restating any value from it here. For `<N>`,
+   use the GitHub issue number the run executes under when the run has one. When the run
+   has none, `<N>` is an arbitrary run-scoped identifier chosen by the pr-author agent.
+   The delegation prompt MUST carry a `branch: <name>` label naming the consolidation branch,
+   and the canonical issue number line when the run has an issue number.
+   `enforce-model-routing-receipt.ps1` identifies the item from those two lines and denies a
+   gated delegation it cannot identify. A cleanup run with no issue number is therefore
+   identified by the branch label alone, which is why the label is required and the issue line
+   is not.
+   It is not a pull-request number, and the only requirement on it is that the body-file
+   path, the receipt's `number` field, and the body bytes all agree. This skill never
+   authors or creates the PR itself.
+
+5. **Wait for merge and verify git-natively.** The consolidation PR's merge is
+   **human-performed**: the operator merges it outside the agent session; this skill
+   never issues the merge itself. This is why: `gh pr merge` is absent from this skill's
+   `allowed-tools`; the project permission allow-list (`permissions.allow` in
+   `.claude/settings.json`) carries no `gh` entry; and `.claude/hooks/enforce-epic-merge-gate.ps1`
+   would deny the command with `EPIC_MERGE_GATE_BLOCKED` if it were attempted. At this
+   boundary the agent reports the consolidation pull request's URL or number to the
+   operator and stops. The ruleset on `main` sets `strict_required_status_checks_policy`,
+   so the branch must be up to date with `main` before the merge becomes available to the
+   operator; the wait for the merge is unbounded within a session. After the consolidation
+   PR merges, verify it with `git fetch` followed by
    `git merge-base --is-ancestor documentationandmemories main`. Exit 0 confirms every
    consolidated commit is now reachable from `main`; that is the only state that unlocks
    deletion of branches whose unique content was consolidated.
@@ -119,6 +212,31 @@ The script emits pipe-delimited, `LC_ALL=C`-ordered records, one per line:
    branch classified `NOT_MERGED` or `HAS_UNIQUE_RESIDUALS` — is not abandoned; it moves
    to the Dirty Worktree Triage Procedure below.
 
+   A consolidation branch whose tip equals `main`, which is the state of
+   `documentationandmemories` between its creation off `main` and its first commit, is
+   reported `NOT_ANCESTOR` by a tip-equality pre-check that runs before any network fetch
+   and is therefore not delete-eligible; the post-merge cleanup described above is
+   unaffected, because a merged consolidation branch's tip differs from `main`, and an
+   empty or unresolvable tip on either side is reported `ANCESTRY_ERROR` rather than
+   treated as equality.
+
+   Detached-HEAD worktrees are handled on the same terms. Apply mode classifies each on
+   its own HEAD SHA, emits the five-field `WORKTREE|<path>|DETACHED|<state>|<flags>`
+   record from that verdict, and acts only on the delete-eligible states `MERGED_CLEAN`,
+   `MERGED_CONTENT_NEUTRAL`, and `MERGED_EQUIVALENT`. A delete-eligible detached worktree
+   is re-verified in the same process immediately before the destructive action and is
+   then removed without force. A locked one is skipped with the result token
+   `ACTION|worktree-remove|<path>|BLOCKED-LOCKED`; the locked test reads the porcelain
+   flags already in hand and precedes every git invocation, so no `git worktree remove`
+   command is issued for it. A prunable one is report-only: it produces its registration
+   record and no further line, with no removal and no prune. A dirty one reaches the same
+   non-forced removal path as a branch-backed worktree and is reported `BLOCKED-DIRTY`
+   with its accompanying `DIRTY|` lines.
+   In apply mode a blocked detached removal — `BLOCKED-DIRTY`, `BLOCKED-LOCKED`, or
+   `BLOCKED-REVERIFY` — sets a non-zero exit status, so a checkout holding dirty or locked
+   detached worktrees exits non-zero from `--apply` where the same checkout previously
+   exited 0.
+
 ## Nothing to Consolidate (Short Path)
 
 When report mode classifies every candidate as `MERGED_CLEAN` or `MERGED_EQUIVALENT`
@@ -134,7 +252,12 @@ accompanying `DIRTY|<path>|<status-porcelain-line>` records), or a branch classi
 script correctly refuses to discard. That refusal is correct and this procedure never
 overrides it — a dirty worktree is never force-removed. This procedure is the systematic
 follow-up: deciding, per worktree, whether that content is disposable or must be
-preserved before the worktree can ever be deleted.
+preserved before the worktree can ever be deleted. Report mode now precedes this
+procedure with a machine-readable first pass: one `DIRTFILE|` record per status entry
+giving that entry's verdict, and one `DIRTSUM|` record per worktree giving the aggregate
+`ALL_DISPOSABLE` or `HAS_UNIQUE`. Steps 1-9 below apply to the worktrees carrying at
+least one `UNIQUE` verdict, which are exactly the ones the classifier could not establish
+as disposable and which therefore still require human editorial judgement.
 
 Steps 1-7 are read-only investigation. Run them per worktree, or fan out one
 `Agent(general-purpose)` investigation per worktree (or small batch) concurrently per
@@ -185,7 +308,12 @@ specific files or commit SHAs, before step 9 acts on any finding.
    build artifacts (a modified `.csproj`/`packages.config`/`app.config` from a build run
    in that worktree) rather than documentation. Diff a representative sample against
    `main` (`git diff main -- <path>`) to characterize the change before deciding it is
-   disposable.
+   disposable. The classifier scopes this class narrowly: it labels a project file
+   `DISPOSABLE_BUILD_ARTIFACT` only when every changed line in that entry's diff is an
+   analyzer `HintPath` rewrite. A project file whose diff touches anything else — a
+   `Compile Include` registration, a package reference, a target or property change — is
+   reported `UNIQUE` and is not disposable, so this step's manual characterization is
+   still required for it.
 
 7. **Recognize orphaned non-worktree directories.** A path can still exist on disk
    under a worktree-tracking folder after `git worktree remove` partially ran or
@@ -210,13 +338,32 @@ specific files or commit SHAs, before step 9 acts on any finding.
    `mcp__drm-copilot__potential_to_issue` per
    `.claude/skills/feature-promotion-lifecycle/SKILL.md`. For a `SAFE_TO_DELETE`
    verdict, discard the content as a distinct, individually confirmed manual action —
-   clear the dirty working tree, or delete a disposable `NOT_MERGED`/
-   `HAS_UNIQUE_RESIDUALS` branch directly. This is never automated: the script's
-   classification ladder and apply-mode allowlist are never changed to accept these
-   states, so a `--apply` run never deletes them on its own, before or after triage. If
-   discarding the working-tree content changes the branch's classification (for example
-   to content-neutral against `main`), a follow-up report/apply pass then picks it up
-   through the normal deterministic path.
+   clear the dirty working tree, delete a disposable `NOT_MERGED`/`HAS_UNIQUE_RESIDUALS`
+   branch directly, or remove the worktree itself through a
+   manifest-authorized removal. A manifest-authorized removal is a single
+   `git worktree remove <path>` covering one worktree, issued as its own Bash tool call,
+   one call per worktree, and it is authorized only when the Sanctioned Removal Manifest
+   below carries a record for that exact path whose `removal_disposition` is
+   `SAFE_TO_DELETE` and whose `branch_state` is `NOT_MERGED` or `HAS_UNIQUE_RESIDUALS`.
+   Never pass a force flag to that command: a dirty worktree blocks deletion and is
+   reported for manual handling, and it is never force-removed. This is never automated:
+   the script's classification ladder and apply-mode allowlist are never changed to
+   accept these states, so a `--apply` run never deletes them on its own, before or
+   after triage. If discarding the working-tree content changes the branch's
+   classification (for example to content-neutral against `main`), a follow-up
+   report/apply pass then picks it up through the normal deterministic path.
+
+   Distinguish two different discards. The sentence above governs the editorial discard
+   of `UNIQUE` content — content a human judged safe to lose — and that discard stays
+   manual and individually confirmed. Separately, dirt the classifier established as
+   disposable, meaning a worktree whose `DIRTSUM|` aggregate is `ALL_DISPOSABLE`, can be
+   cleared by the tool itself under the opt-in `--clear-disposable` flag in apply mode.
+   That path never touches a `UNIQUE` verdict: one `UNIQUE` entry refuses the clear for
+   the whole worktree, and a classification read that errors produces a fail-closed
+   `UNIQUE` with the same effect. It is also not force-removal — it clears the working
+   tree and retries the same unforced `git worktree remove` after a fresh in-process
+   re-verification. The classification ladder and the apply-mode allowlist remain
+   unchanged by it.
 
 10. **After local branch deletion, check origin too.** This skill is local-only by
     design (see "When to Use This Skill"), which leaves stale branches on the remote for
@@ -228,13 +375,148 @@ specific files or commit SHAs, before step 9 acts on any finding.
     cleanup, and never rely on this skill's general `Bash(git push *)` allowance to
     perform it silently.
 
+## Sanctioned Removal Manifest
+
+**Write the manifest before step 9 of the Dirty Worktree Triage Procedure acts on any
+`SAFE_TO_DELETE` verdict.** The run records its triage verdicts in
+`artifacts/orchestration/cleanup-worktrees-manifest.json`. The two PreToolUse gates
+`.claude/hooks/enforce-epic-worktree-removal-gate.ps1` and
+`.claude/hooks/enforce-parallel-worktree-removal-gate.ps1` read that document and admit a
+`git worktree remove <path>` command only when a record in it covers that exact path. A removal
+issued with no covering record is denied with each gate's existing, unchanged reason code.
+
+The document is UTF-8 JSON with `snake_case` keys. It carries six top-level fields. Its `removals`
+and `preserved_files` entries are sibling arrays and are never nested: removal records are keyed by
+worktree path, preserve records by the pair of worktree path and file path, and the gates must
+never traverse preserve data.
+
+### Top-level fields
+
+- `tool` — string, required, exactly `cleanup-merged-worktrees`. The self-identifying
+  discriminator. Absent, non-string, or any other value and no record authorizes anything.
+- `schema_version` — integer, required, exactly `1`. Absent, non-integer, or any other value fails
+  closed; a forward version is not accepted by silence.
+- `generated_at` — string, required, an ISO-8601 UTC timestamp recording when the run wrote the
+  document. Absent, unparseable, in the future, or older than the 24-hour freshness bound fails
+  closed.
+- `run_id` — string, required, non-empty. An opaque per-run identifier for audit correlation.
+- `removals` — array, required, of removal records. It may be empty; absent, non-array, or empty
+  authorizes no removal.
+- `preserved_files` — array, required, of preserve records. It may be empty. Neither gate ever
+  reads it, and its absence or malformation must not affect any gate decision.
+
+### `removals[]` record fields
+
+- `worktree_path` — string, required, non-empty. The absolute path of the worktree to remove. A
+  record with it absent or empty is skipped.
+- `branch` — string or `null`, key required. The worktree's branch, or `null` for a detached
+  worktree. An absent key means the record does not authorize; `null` is a valid, meaningful value.
+- `branch_state` — string, required. The classification the report emitted for that branch: one of
+  `MERGED_CLEAN`, `MERGED_CONTENT_NEUTRAL`, `MERGED_EQUIVALENT`, `NOT_MERGED`,
+  `HAS_UNIQUE_RESIDUALS`, or `PROTECTED_CURRENT`. Only `NOT_MERGED` and `HAS_UNIQUE_RESIDUALS`
+  authorize a removal; every other member, and any value outside the vocabulary, does not.
+- `removal_disposition` — string, required. The triage disposition that authorizes removal. The
+  allowed set is exactly the single member `SAFE_TO_DELETE`. This key is deliberately distinct from
+  the `merge_status` key the orchestration checkpoints carry.
+- `verdict` — string, required. The step-5 content classification that produced the disposition:
+  one of `DEAD_ONE_OFF`, `ALREADY_SOLVED_ELSEWHERE`, `STALE_OR_CONTRADICTED`, `GENUINELY_NEW`, or
+  `STILL_RELEVANT`. Absent, out of vocabulary, or preserve-implying and the record does not
+  authorize.
+- `evidence` — string, required, non-empty. The justification step 9 requires, citing specific
+  files or commit SHAs. Absent, empty, or whitespace-only and the record does not authorize.
+
+### `preserved_files[]` record fields
+
+These records serve the consolidation consumer and are never read by either gate.
+
+- `worktree_path` — string, required, non-empty. The worktree holding the file, and where the
+  consumer reads that worktree's `MEMORY.md`.
+- `source_path` — string, required, repo-relative within that worktree. The file to preserve.
+- `change_class` — string, required, either `untracked` or `modified`, recording whether staging
+  adds a new file or carries a working-tree modification.
+- `disposition` — string, required, exactly `PRESERVE`.
+- `verdict` — string, required, a member of the step-5 verdict vocabulary listed above.
+- `target_path` — string, required, repo-relative on the consolidation branch. Required because the
+  same relative path may already exist on `main` with different content and a lesson file may be
+  re-namespaced; the consumer must not guess it.
+- `memory_index_line` — string or `null`, key required. The source worktree's `MEMORY.md` index
+  line, or `null` when the file is not a memory entry.
+- `line_ending` — string, required, one of `crlf`, `lf`, or `absent`. Advisory only: it records the
+  target file's existing convention, and the consumer re-derives and compares rather than trusting
+  it.
+- `host_token_scan` — object, required, carrying a `result` member and a `pattern_set_id` member.
+  It records the scan outcome and the identifier of the pattern set used, never the patterns
+  themselves.
+- `evidence` — string, required, non-empty.
+
+### Example
+
+```json
+{
+  "tool": "cleanup-merged-worktrees",
+  "schema_version": 1,
+  "generated_at": "2026-09-07T03:40:00Z",
+  "run_id": "cleanup-2026-09-07T03-40-00Z-a47a5e33",
+  "removals": [
+    {
+      "worktree_path": "C:/Users/DanMoisan/repos/drm-copilot/.claude/worktrees/agent-0f1c2d",
+      "branch": "drm-copilot-wt-2026-08-14T09-02",
+      "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."
+    }
+  ],
+  "preserved_files": [
+    {
+      "worktree_path": "C:/Users/DanMoisan/repos/drm-copilot/.claude/worktrees/agent-91ee43",
+      "source_path": ".claude/agent-memory/general-purpose/hook-payload-anomaly.md",
+      "change_class": "untracked",
+      "disposition": "PRESERVE",
+      "verdict": "GENUINELY_NEW",
+      "target_path": ".claude/agent-memory/general-purpose/hook-payload-anomaly-envelope.md",
+      "memory_index_line": "- [Hook payload anomaly envelope](hook-payload-anomaly-envelope.md) - the deny path a malformed envelope takes",
+      "line_ending": "crlf",
+      "host_token_scan": {
+        "result": "clean",
+        "pattern_set_id": "child-f-host-tokens-v1"
+      },
+      "evidence": "No equivalent file on main under .claude/agent-memory/**; grep for 'payload anomaly' returns only this worktree."
+    }
+  ]
+}
+```
+
+### Accepted residual
+
+Both gates read the command text of the `Bash` tool call they are given. A removal routed
+indirectly — for example by writing the command into a file and invoking that file with `bash
+<file>` — presents command text the gates do not match, so the manifest requirement does not reach
+it. This design does not close that indirection, and the requirement is recorded here as an
+accepted residual rather than left implicit.
+
+The manifest requirement is a policy-level integrity check, on the same terms
+`.claude/hooks/enforce-pr-author-skill.ps1` records for its own receipt mechanism: it prevents
+accidental bypass and requires a deliberate, documented act to circumvent. It is not a
+cryptographic or security boundary, and it must not be described as tamper-proof. Routing a
+removal through such an indirection in order to avoid the manifest requirement is a deliberate act
+and is prohibited by this skill, which is the term the residual rests on.
+
 ## Prohibited Shortcuts
 
 - Never invoke `gh pr create` or `gh pr edit --body*` from this skill or the scripts. PR
   authoring is `Agent(pr-author)`'s exclusive responsibility and is enforced by the
   `enforce-pr-author-skill.ps1` PreToolUse hook.
 - Never pass a force flag to `git worktree remove`. A dirty worktree blocks deletion and
-  is reported for manual handling; it is never force-removed.
+  is reported for manual handling; it is never force-removed. The `--clear-disposable`
+  flag is not an exception to this rule and is not force-removal: it clears the working
+  tree first and then retries the same unforced `git worktree remove`, so the removal it
+  retries is the identical unforced call that was blocked. It runs only when every
+  per-file verdict for that worktree is non-`UNIQUE`, only in apply mode, only when the
+  operator explicitly requests it, and only after a fresh in-process re-verification that
+  the branch is still delete-eligible. A single `UNIQUE` verdict refuses the clear for the
+  whole worktree, including the fail-closed `UNIQUE` assigned when a classification read
+  errors.
 - Never execute `git worktree prune`. Prunable registrations are report-only.
 - Never act on `NOT_MERGED`, `HAS_UNIQUE_RESIDUALS`, or `PROTECTED_CURRENT` candidates
   through the script or its apply-mode allowlist; `--apply` never mutates them, and the
@@ -243,12 +525,32 @@ specific files or commit SHAs, before step 9 acts on any finding.
   only a distinct, individually confirmed manual action outside that automated path for
   `NOT_MERGED`/`HAS_UNIQUE_RESIDUALS` — never a change to the classification ladder
   itself, and never for `PROTECTED_CURRENT`.
+- Never delete the base branch `main` and never remove a worktree checked out on it.
+  `compute_protected` protects `main` by name in every checkout topology, so it
+  classifies `PROTECTED_CURRENT` even when no protected worktree has it checked out, and
+  `delete_candidate` refuses a deletion request for it with
+  `ACTION|delete|main|BLOCKED-PROTECTED-BASE` before any re-verification, worktree
+  removal, or branch deletion runs.
 - Never use commit-message text matching as a classification input, and never
   auto-resolve cherry-pick conflicts.
 - Never delete an origin branch, or run plain filesystem removal on an orphaned
   worktree-tracking directory, without explicit per-item user confirmation — both are
   outside this skill's pre-approved tool surface regardless of how the triage verdict
   came out.
+- Never issue the consolidation merge command, and never write or edit an orchestration
+  checkpoint in order to satisfy `.claude/hooks/enforce-epic-merge-gate.ps1`. This
+  forecloses the specific evasion of writing an
+  `artifacts/orchestration/orchestrator-state.json` whose `epic_mode` and `step9_status`
+  fields the gate's child-feature accept shape would honour for any pull-request number.
+- Never widen the definition of disposable dirt. The session-artifact list is a fixed
+  in-script array of exactly three paths with no configuration override, no environment
+  variable, and no per-repository extension point; adding a path to it is a change to the
+  classifier, not a setting. The build-artifact rule requires both conditions together —
+  the `*.csproj` path pattern and the content confinement that every changed line in the
+  entry's diff is an analyzer `HintPath` rewrite — and a project file whose diff touches
+  anything else is `UNIQUE`. Ignored files are never cleared, because they are never
+  classified: `git status --porcelain` is read without `--ignored`, so an ignored file
+  never becomes an entry, and `git clean` is never given `-x`, `-X`, or `-ff`.
 
 ## Cross-References
 
@@ -262,3 +564,8 @@ specific files or commit SHAs, before step 9 acts on any finding.
 - `.claude/skills/feature-promotion-lifecycle/SKILL.md` — the potential-entry-to-issue
   promotion path used by the Dirty Worktree Triage Procedure's step 9 for `PRESERVE`
   findings that describe unresolved product scope.
+- `.claude/hooks/enforce-epic-merge-gate.ps1` — the PreToolUse gate on the consolidation
+  merge command, backed by orchestration checkpoints. A cleanup run satisfies none of its
+  three checkpoint shapes: it is neither a per-feature orchestration, nor an epic
+  integration, nor a parallel run, so it writes none of the three checkpoints the gate
+  reads.

package/resources/claude-customizations/.claude/skills/epic-orchestrate/SKILL.md

@@ -170,6 +170,13 @@ frontmatter default — `opus` for these workers — which suppresses a `fable`
 MUST NOT hard-code `model=opus` in a way that overrides the resolved routing model, mirroring
 step 5 of `## Model Selection` in `.claude/skills/orchestrate/SKILL.md`.
 
+Every such spawn of `Agent(pr-author)` also carries the canonical issue number line and a
+`branch: <name>` label naming the branch checked out in the worktree the pull request is opened
+from, per `## Issue Number Consistency` in `.claude/skills/orchestrate/SKILL.md`.
+`enforce-model-routing-receipt.ps1` identifies the item from those two lines and denies a gated
+delegation it cannot identify, so a spawn that omits both is refused rather than validated against
+whichever checkpoint occupies the calling session's root.
+
 `route` is never an input to model selection; `route` remains file-count driven and governs only
 agents, skills, and MCP tools. A skill whose frontmatter `context` field holds the value `fork`
 inherits the parent model and ignores a model override, so model selection applies to agent
@@ -281,7 +288,9 @@ checkpoint JSON remains the durable, machine-authoritative source.
 `epic_feature_folder`, `epic_manifest_path` (which points at
 `docs/features/epics/<epic-slug>/epic.md`), `epic_status_doc_path`, `integration_branch`,
 `completed_steps`, `next_step`, `last_updated`, `current_wave`, `waves[]`, `features[]`,
-`epic_merge_pr`, and the three receipt arrays (`delegation_receipts[]`, `skill_receipts[]`,
+`epic_merge_pr`, `epic_issue_num` (the epic-level issue `epic-planner` promoted),
+`model_routing_receipts[]` (the routing receipt for each delegation `epic-orchestrator` itself
+spawns), and the three receipt arrays (`delegation_receipts[]`, `skill_receipts[]`,
 `mcp_call_receipts[]`). The
 `merge_status` enum is: `not_started`, `worktree_created`, `pr_open`, `ci_green`,
 `merge_conflict`, `blocked_conflict_loop_limit`, `merged`, `worktree_removed`. The optional
@@ -298,6 +307,10 @@ Validate the checkpoint through the
 that same call at the completion gate. The validation is implemented in
 `scripts/dev_tools/validate_epic_orchestrator_state.py`.
 
+**Checkpoint hygiene (issue #673).** The coordinating session never holds a per-feature checkpoint at its own root. Before the first child delegation of a run it moves any `artifacts/orchestration/orchestrator-state.json` at its root to `artifacts/orchestration/handoff/orchestrator-state.issue-<issue-num>.<yyyy-MM-ddTHH-mm>.json`, and writes none there for the rest of the run, because each item's checkpoint lives in that item's worktree. A gated call the coordinator issues on an item's behalf is resolved by the item's issue number and branch, never by the coordinator root.
+
+**Integration-PR checkpoint shape (issue #663).** The integration-to-`main` pull request and its `Agent(pr-author)` delegation are gated against `artifacts/orchestration/epic-orchestrator-state.json`, and no per-feature checkpoint is written for them. Before `epic-orchestrator` opens that pull request, the epic checkpoint carries `route_id: "epic"`, `integration_branch`, `epic_issue_num`, and a `features[]` array in which every entry's `merge_status` is `merged` or `worktree_removed`. Before the `Agent(pr-author)` delegation, `epic-orchestrator` records the `pr-author` routing receipt in that file's `model_routing_receipts[]`. The pr-author gate, the epic base-branch check, the model-routing gate, and the preimplementation gate treat a call as epic scope when its branch signal (or, for a staging command or file edit, the worktree HEAD) equals `integration_branch`; the pull request base must then be `main`.
+
 ## Completion Requirements
 
 `epic-orchestrator` must not report completion until:

package/resources/claude-customizations/.claude/skills/epic-plan/SKILL.md

@@ -66,6 +66,10 @@ At manifest-authoring time child issues do not exist yet, so `issue_num` values
 placeholders and back-filled from each child's promotion receipt as preparation completes. The
 manifest is committed in final, resolved form before the kickoff artifact is written.
 
+## Epic-Level Issue Promotion
+
+Issue #663. Before the first preparation-mode child delegation, `epic-planner` promotes one epic-level GitHub issue for the epic itself. It authors a potential entry under `docs/features/potential/` describing the epic and promotes it through `mcp__drm-copilot__potential_to_issue` with `promotion_type: epic`; `gh issue create` is not used. It records the resulting number as `epic_issue_num` in the epic planning checkpoint (`artifacts/orchestration/epic-planner-state.json`) and in the kickoff prompt artifact, and `epic-orchestrator` copies it into the epic checkpoint `artifacts/orchestration/epic-orchestrator-state.json` at its first checkpoint write. The integration-to-`main` pull request uses `epic_issue_num` as its canonical issue number.
+
 ## Complexity Assessment
 
 Assess each child feature's complexity band (`C1`-`C4`) using the `model_policy` scale and

package/resources/claude-customizations/.claude/skills/orchestrate/SKILL.md

@@ -33,6 +33,49 @@ On every invocation, the main session must:
 1. Read `artifacts/orchestration/orchestrator-state.json` to check for existing state.
 2. If a valid checkpoint exists with a matching objective, resume from the recorded `next_step`.
 3. If no checkpoint exists or the objective is new, begin the orchestration lifecycle from the start.
+4. **Checkpoint hygiene (issue #673).** When the checkpoint at `artifacts/orchestration/orchestrator-state.json` records an `issue-num` other than the item this invocation is about, move it to `artifacts/orchestration/handoff/orchestrator-state.issue-<issue-num>.<yyyy-MM-ddTHH-mm>.json` before writing a new checkpoint, rather than overwriting it or leaving it in place. Apply the same move when this session hands an item whose checkpoint it holds to another session or worktree. A checkpoint left at a session root is read by gates that resolve against that root, so a foreign one there is state a gate can answer from.
+
+## Prepared-State Portable Handoff Intake
+
+Treat a portable prepared-state checkpoint as a request to resume the recorded
+lifecycle, not as a new orchestration intake. Before any destination launch:
+
+1. Validate the envelope through the published, workspace-explicit handoff
+   authority. Require exact repository, workspace, branch lineage, issue,
+   feature folder, work mode, scheduler, capability, and transition bindings.
+   Supply the complete caller-controlled independent expected context on every
+   call to `resolve_orchestration_topology`, `resolve_provider_routing`, and
+   `transition_prepared_orchestration`: `expected_repository_id`,
+   `expected_workspace_root`, `expected_branch`, `expected_source_head_sha`,
+   `allowed_head_relationship`, `expected_issue_number`,
+   `expected_feature_folder`, `expected_work_mode`, `expected_plan_path`, and
+   `expected_plan_sha256`. Derive each value from the destination checkout and
+   the caller's own record. A call that omits a value, or that copies one from
+   the envelope under validation, is rejected before any service invocation.
+2. Prove the plan using only the independently expected repository-relative
+   path and raw-byte SHA-256 the caller supplied in `expected_plan_path` and
+   `expected_plan_sha256`. Do not rediscover, rename, or substitute a plan, and
+   do not read the plan identity from the envelope.
+3. Use `transition_prepared_orchestration` as the only authority that may
+   materialize a provider-native destination checkpoint. Dry run validates and
+   projects state without source archival or canonical-checkpoint replacement.
+4. Preserve the envelope's completed phases and reject replay before mutation.
+   Promotion, research, feature-document authoring, atomic planning, and
+   preflight remain complete when the source recorded them as complete.
+5. Keep source-provider model, reasoning, profile, topology, launch, worktree,
+   and receipt evidence opaque. Create destination routing evidence only for
+   the first new delegation after materialization.
+
+When Claude is the destination, resolve its model through the existing Claude
+model-routing procedure and launch with the existing `Agent(...)` and Claude
+worktree mechanisms. Do not translate Codex deployment receipts into Claude
+launch evidence. When Claude is the source, preserve Claude launch and
+worktree evidence in the portable source expression and allow the Codex
+destination to resolve its own topology and model. An ordinary handoff whose
+recorded transition is `atomic_execution` resumes the exact approved plan at
+that transition without invoking a parent scheduler. Any validation,
+authority, plan, replay, or materialization failure returns the deterministic
+blocked result before launch.
 
 ### Model-choice reconciliation on resume
 
@@ -213,10 +256,12 @@ A bounded loop consisting of five steps. The loop variable `remediation_pass` st
 
 The canonical issue number is derived once from the active feature folder name: extract the trailing integer from the folder base name (e.g., `2026-04-26-push-down-claude-customizations-162` yields `162`). Record as `issue_num` in the checkpoint.
 
-Every delegation prompt to `atomic-planner`, `atomic-executor`, and `feature-review` must include the line:
+Every delegation prompt to a receipt-gated subagent type — `atomic-planner`, `atomic-executor`, `feature-review`, `task-researcher`, `prd-feature`, and `pr-author` — must include the line:
 
 > `Canonical issue number for this feature is <issue_num>. All artifact content, file paths, and cross-references must use this number.`
 
+Each such prompt also carries a `branch: <name>` label naming the branch checked out in the item's worktree, written as the first `branch:` occurrence in the prompt. Before promotion assigns an issue number, the branch label alone is required. Two gates, `enforce-model-routing-receipt.ps1` and `enforce-prd-feature-before-planner.ps1`, identify the item from these two lines: they deny a gated delegation they cannot identify rather than checking it against whichever checkpoint occupies the calling session's root, and they never use a feature-folder path to choose the worktree, because a merged feature folder exists in every checkout branched from main.
+
 If a subagent artifact references a different issue number, the orchestrator rejects it, requests correction, and records the discrepancy under `artifact_errors` in the checkpoint.
 
 ## Step S9 — CI Green Gate

package/resources/claude-customizations/.claude/skills/parallel-add/SKILL.md

@@ -66,7 +66,9 @@ re-derivation is mandatory and is not an optimization to skip when the checkpoin
    (Join-Path $repoRoot '.claude/lib/blast-radius/BlastRadius.psm1') -Force -ErrorAction Stop`).
    Its two radius arguments are the two items' radius hashtables, not strings, and the third
    argument is the required parsed `config/blast-radius.json` mapping, which push-down publishes
-   into the destination workspace. `conflicts(a, b, config)` in
+   into the destination workspace. That mapping's optional `mergeable_paths` list is read by
+   `Test-BlastRadiusConflict`, which contributes no `path_overlap` edge for a path matching it
+   while the path stays in the declared radius. `conflicts(a, b, config)` in
    `scripts/dev_tools/compute_blast_radius.py` (defined in
    `scripts/dev_tools/_blast_radius_conflicts.py`) remains the repository authority and the parity
    reference. Read the verdict from `$result['conflict']`; do not test the returned hashtable