@danmoisan/drm-copilot-mcp 1.1.9 → 1.1.11

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,25 @@ 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.
+   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 +206,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 +246,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 +302,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 +332,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 +369,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
@@ -249,6 +525,20 @@ specific files or commit SHAs, before step 9 acts on any finding.
   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 +552,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/orchestrate/SKILL.md

@@ -34,6 +34,48 @@ On every invocation, the main session must:
 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.
 
+## 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
 
 Because model selection is required once delegation occurs (see `## Model Selection`), a resuming orchestrator must repair a missing model choice deterministically before delegating at a delegating `next_step`. When the resumed `next_step` is a delegating step:

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

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

@@ -344,6 +344,29 @@ Remediation is child-owned and parent-initiated. The conflict is always between
 branch and `origin/main`; there is no integration branch and therefore no fan-in conflict path on
 this surface.
 
+Project-file conflicts are resolved by the parent first (issue #643); the numbered steps below are
+the escalation path.
+
+- (a) On a conflicted `gh pr merge --merge`, the parent runs the two commands
+  `git -C <worktree_path> fetch origin main` and
+  `git -C <worktree_path> merge --no-commit origin/main`.
+- (b) The parent then runs
+  `pwsh -NoProfile -File .claude/lib/project-file-merge/Resolve-MergeableConflict.ps1 -Worktree <worktree_path>`
+  and parses its single JSON object. A `result` of `escalate` makes the parent run
+  `git -C <worktree_path> merge --abort`
+  and continue with step 1 below, including `escalate_paths` in the Blocking finding.
+- (c) On `resolved` the parent stages and commits the resolved paths with a message body listing
+  every entry added from each side and every version choice, then runs the three commands
+  `dotnet tool restore --tool-manifest <worktree_path>/.config/dotnet-tools.json`,
+  `dotnet csharpier check <worktree_path>`, and
+  `dotnet build <worktree_path>/<solution>`, each with path arguments rather than `cd`.
+  A failing check reverts with
+  `git -C <worktree_path> reset --hard HEAD~1`
+  and escalates with the tool output as the finding.
+- (d) On success the parent pushes the item branch, records `mergeable_conflicts_resolved` on the
+  item, sets `merge_status: pr_open`, regenerates `parallel-status.md`, and re-enters
+  `## Per-Item Merge to Main (Merge-on-Green)` at the durable `gh pr checks` confirmation step.
+
 1. On a conflicted `gh pr merge --merge`, the parent detects the failure and re-delegates that item's
    child orchestration, passing the conflict signal and the instruction to resolve against
    `origin/main`. The conflict capture and the finding write both belong to the child's
@@ -427,6 +450,14 @@ whose rows appear only once F6 populates that array; section `## Drift Events` p
 `drift_events[]`, which only F8 populates. An empty array renders an empty section rather than an
 omitted one.
 
+The projection's `## Mergeable Conflicts Resolved` heading renders
+`items[].mergeable_conflicts_resolved`: for each entry the path, the `resolved_at` stamp, the
+`merged_against` ref, the `merge_commit_sha`, the entries added from each side, and the version
+resolutions. The same resolution is cited in three further places: the body of the resolution
+commit message, the pull-request body, and an evidence artifact at
+`docs/features/parallel/<slug>/evidence/other/mergeable-conflicts.<yyyy-MM-ddTHH-mm>.md` carrying
+`Timestamp`, `Command`, `EXIT_CODE`, and the script's JSON output verbatim.
+
 Regeneration boundaries — regenerate at each of the following, not only at final completion:
 
 - Run kickoff, seeding the initial projection from the manifest and the seeded cohorts.
@@ -435,6 +466,7 @@ Regeneration boundaries — regenerate at each of the following, not only at fin
 - Every `recolor_generation` increment.
 - Every append to `mutations[]`.
 - Every append to `drift_events[]`.
+- Every append to an item's `mergeable_conflicts_resolved`.
 - Run completion in `closed` mode, or run close in `open` mode.
 
 Defining the `mutations[]` and `drift_events[]` appends as regeneration boundaries here means F6 and
@@ -444,8 +476,10 @@ F8 need no amendment to these projection rules.
 
 This section is consumption documentation only. The checkpoint schema is owned by F3, defined once
 as prose invariants in `.claude/rules/parallel-orchestration.md`, and enforced by
-`scripts/dev_tools/validate_parallel_orchestrator_state.py`. Consume that schema; add no field to it
-and extend no enum in it.
+`scripts/dev_tools/validate_parallel_orchestrator_state.py`. Consume that schema;
+add no field to it that `.claude/rules/parallel-orchestration.md` does not declare,
+and extend no enum in it. `mergeable_conflicts_resolved` is the one declared optional item
+field.
 
 Fields `parallel-orchestrator` writes to `artifacts/orchestration/parallel-orchestrator-state.json`:
 `objective`, `route_id: "parallel"`, `parallel_slug`, `parallel_manifest_path`,

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

@@ -196,6 +196,10 @@ The facade re-exports the five functions this skill needs: `Get-PlanPaths` (port
 call to `Test-BlastRadius` in `@(...)`: it writes its findings to the pipeline, so a zero-element
 result writes nothing and a one-element result writes a single object.
 
+`Test-BlastRadiusConflict` reads the optional `mergeable_paths` list from that truth table and
+contributes no `path_overlap` edge for a path matching it, while the path itself stays in the
+declared radius and is still read by every audit.
+
 The truth table the port reads is `config/blast-radius.json`, which push-down publishes into the
 destination workspace alongside `.claude`.
 
@@ -312,6 +316,8 @@ The library returns the partition; the planner supplies the record fields.
    `Test-BlastRadiusConflict` to every unordered pair of `declared` radii, then pass the pairs as
    `--edges "<a>:<b> ..."` and the item keys as `--keys "<k1> <k2> ..."`.
    Read the verdict from the conflict key of the returned hashtable.
+   `Test-BlastRadiusConflict` contributes no `path_overlap` edge for a path matching the truth
+   table's optional `mergeable_paths` list, and the path stays in the declared radius.
    The hashtable itself is always truthy, so a bare boolean test on the result treats every pair as
    conflicting and serializes the whole run. This is the sibling hazard to the `@(...)` warning
    above for `Test-BlastRadius`: that function writes an `IList`-shaped pipeline result whose

package/resources/claude-customizations/.claude/skills/powershell-orchestration-state-machine/SKILL.md

@@ -42,6 +42,35 @@ For short-path runs, also persist:
 - `phase0_execution_summary`
 - `resume_after_manual_bootstrap` (next step token)
 
+## Portable Prepared-State Projection
+
+When the PowerShell delivery flow resumes from a provider-neutral prepared-state
+handoff, the active destination projection is
+`artifacts/orchestration/orchestrator-state.json`. Validate and retain:
+
+- the destination provider, checkpoint expression, selected projector,
+  `plan-path`, and exact recorded `next_step`;
+- the portable handoff ID, envelope and latest-history SHA-256 values, selected
+  adapter, source validator, identity, repository/workspace/branch binding,
+  exact plan proof, lifecycle, capabilities, and scheduler context;
+- the source checkpoint path/hash/archive facts and opaque historical receipt
+  references without converting them into Claude receipts; and
+- `destination_evidence: { status: "pending_first_delegation", receipts: [] }`
+  until the first new Claude delegation after materialization.
+
+Do not rediscover the plan or rerun any phase listed in
+`portable_handoff.lifecycle.completed_phases`. Resume only the recorded
+transition. Record Claude model, launch, worktree, and receipt evidence through
+Claude-native fields for new work; functional parity does not require copying
+Codex field names or launch representations.
+
+For a scheduled parallel or epic child, validate the run/item, parent
+checkpoint path/hash, scheduler and child owners, return contract, exact plan
+hash, child checkpoint hash, and result hash before returning a result. The
+ordinary child may update only its bounded status/result projection. Cohort or
+wave order, barriers, fan-in, integration, cleanup, worktree lifecycle, and
+parent completion remain owned by the parent scheduler.
+
 ## Update Protocol
 
 - Write checkpoint after every completed orchestration sub-step.
@@ -55,4 +84,3 @@ On invocation:
 2) If incomplete, resume from `next_step` without re-running `completed_steps`.
 3) If missing or completed, start at phase-0 intake.
 4) If user explicitly requests restart, reset checkpoint and start phase-0.
-

package/resources/claude-customizations/config/blast-radius.json

@@ -22,6 +22,13 @@
     ".agents/skills/**",
     "scripts/vscode/**"
   ],
+  "mergeable_paths": [
+    "**/*.csproj",
+    "**/packages.config",
+    "**/app.config",
+    "**/*.vbproj",
+    "**/*.props"
+  ],
   "modules": {
     "config": ["config/**"]
   },

package/resources/claude-customizations/pack-manifests/core.json

@@ -46,6 +46,8 @@
     ".claude/hooks/enforce-pr-author-skill-helpers.ps1",
     ".claude/hooks/enforce-prd-feature-before-planner.ps1",
     ".claude/hooks/enforce-promotion-mcp-only.ps1",
+    ".claude/hooks/hook-command-invocation.ps1",
+    ".claude/hooks/hook-command-scanner.ps1",
     ".claude/hooks/persist-session-id.ps1",
     ".claude/hooks/validate-bash.ps1",
     ".claude/hooks/validate-discovery-artifact-gate.ps1",
@@ -134,6 +136,11 @@
     ".claude/lib/blast-radius/BlastRadius.psm1",
     ".claude/lib/blast-radius/BlastRadiusNormalization.psm1",
     ".claude/lib/blast-radius/BlastRadiusTokenShape.psm1",
+    ".claude/lib/cleanup-manifest/CleanupWorktreeManifest.psm1",
+    ".claude/lib/blast-radius/BlastRadiusConflict.psm1",
+    ".claude/lib/project-file-merge/ProjectFileMergeGrammar.psm1",
+    ".claude/lib/project-file-merge/ProjectFileMerge.psm1",
+    ".claude/lib/project-file-merge/Resolve-MergeableConflict.ps1",
     ".claude/rules/parallel-orchestration.md",
     ".claude/rules/shell.md",
     ".claude/lib/bash/compute-cohorts.sh",