@danmoisan/drm-copilot-mcp 1.1.25 → 1.1.27

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

@@ -60,7 +60,7 @@ Enforced by `validate_parallel_orchestrator_state_text(text, *, require_complete
 
 9. **Blast-radius shape.** Each item's `blast_radius` must be an object carrying `paths`, `modules`, `shared_surfaces`, and `contracts` as lists of non-empty strings, a `source` in `{derived, declared, observed}`, and a non-empty `computed_at` string. `modules`, `shared_surfaces`, and `contracts` may be empty lists.
 
-10. **Prohibited dependency edges.** No object anywhere in the checkpoint may carry a `depends_on` key, and no top-level `depends_on` key may be present. Ordering is expressed only as blast-radius overlap. Presence is an explicit rejection, not mere absence.
+10. **Prohibited dependency edges.** No object anywhere in the checkpoint may carry a `depends_on` key, and no top-level `depends_on` key may be present. Ordering is expressed only as blast-radius overlap and as the operator precedence input declared in `## Prepared-Item Admission (issue #1047)`, which is a separating input and not a dependency key. Presence is an explicit rejection, not mere absence.
 
 11. **Prohibited integration-branch fields.** The checkpoint must not carry `integration_branch` or `epic_merge_pr` at any level. Each parallel item opens its own pull request against `main`, so there is no integration branch and no final integration pull request.
 
@@ -256,6 +256,22 @@ F3 deliberately excludes the kickoff-prompt contract module `scripts/dev_tools/p
 
 F3's `require_ready_for_execution` gate is STRUCTURAL ONLY. It enforces the kickoff-PATH invariant (P9: `kickoff_prompt_path` must equal `artifacts/orchestration/parallel-kickoff-<parallel_slug>.md`) and does not parse or cross-check kickoff CONTENT. The deeper readiness-integrity machinery of the epic surface — git-integrity checks, launch-evidence binding, and kickoff-contract cross-checks — is left to F4, which may layer repository-aware checks behind an additional keyword without changing the schema. F3 likewise does not recompute the cohort coloring (planner invariant P5).
 
+## Prepared-Item Admission (issue #1047)
+
+`/parallel-add` and `/parallel-plan` admit an item at the stage its pushed branch already reached. The decisions are made in code by the admission helper `.claude/lib/parallel-admission/Invoke-ParallelAdmission.ps1` (subcommands `guard-run`, `assess`, `order-cohorts`, `test-cohorts`, `record`, and `reuse-edges`). Every field below is tolerated and not validated: the Python validators and the TypeScript validator port accept it with zero errors, and no enum of `## Enum Ownership (F6/F7/F8 consume, never extend)` changes.
+
+**Tolerated item fields.** A parallel-orchestrator checkpoint item may carry `preparation_status` (`none|research|spec|plan|cleared`, as reported by `assess`), `plan_hash` (the git blob hash of the plan at the item branch head), `base_commit` (the commit the staleness check compares `origin/main` against), and `band_source` (`caller|planner_checkpoint|assessment`). A parallel-planner checkpoint item may carry `plan_hash` and `base_commit`. The planner keeps its ready value `preparation_status: prepared` (invariant P7), which corresponds to the admission stage `cleared`; no second ready value is introduced.
+
+**Precedence input.** Both checkpoints may carry a top-level `precedence[]` list of `{before, after, source, recorded_at}` entries, recorded from the operator's `--after` flags with `source` equal to `operator`. An entry states that the `after` item starts in a later cohort than the `before` item and only after the `before` item has merged. It is a separating input: each pair is passed to the cohort computation as an extra edge, and `order-cohorts` lifts an unstarted `after` item above its `before` item. It is not a `depends_on` key, and invariant 10, P3, and M7 are unchanged. Keys must resolve to items, an item is never paired with itself, and the entries must be acyclic. An entry is inactive once its `before` item has `merge_status` `merged` or `worktree_removed` or `state` `withdrawn`; a `blocked` predecessor still holds its dependent. A combined item inherits the union of its members' entries, and a pair inside one combination is dropped.
+
+**Preparation receipt.** The preparation child writes `<feature folder>/evidence/other/preparation-receipt.<yyyy-MM-ddTHH-mm>.json` before its commit, carrying `schema_version`, `stage`, `research_path`, `spec_path`, `plan_path`, `plan_hash`, `base_commit`, `preflight_status`, and `recorded_at`. The lexicographically greatest receipt name wins, a newer receipt supersedes an older one, and no receipt is deleted. A receipt whose `plan_hash` differs from the current blob hash is downgraded to `plan`.
+
+**Durable scheduling record.** `docs/features/parallel/<slug>/parallel-scheduling.json`, committed on `parallel/<slug>-plan`, carries `schema_version`, `parallel_slug`, `edges[]`, `tolerated_overlaps[]`, `precedence[]`, and `items[]` with `issue_num`, `branch_name`, `plan_path`, `plan_hash`, `base_commit`, `preparation_status`, and `complexity_band`. The planner writes it at seeding and `/parallel-add` rewrites it after each admission; the helper's `record` subcommand prints the content and performs no git write. A re-seed applies the reuse rule through the helper's `reuse-edges` subcommand, which reads the record by ref and reuses an item's recorded edges only when the recorded `plan_hash` equals the current blob hash. The run manifest stays read-only to the orchestrator.
+
+**Admission output signal.** A helper rule rejection exits 1 with one stderr line `PARALLEL_ADMISSION_REJECTED: <code>: <detail>`, where the code is one of `run_closed`, `precedence_cycle`, `precedence_unknown_item`, and `precedence_violated`. This signal is separate from the mutation rejection signal of `## Mutation Rejection Signal (issue #1012)`: a `run_closed` rejection is emitted after a checkpoint exists and emits no mutation rejection signal, and that section's closed code set is unchanged.
+
+**Known gap (Layer 2).** The Python orchestrator-state validator does not check precedence. Precedence is enforced by the helper's `test-cohorts` rejection and by Layer 1 of the cohort barrier hook (`Test-ParallelCohortBarrierClear` in `.claude/hooks/enforce-parallel-cohort-barrier-helpers.ps1`); the retrospective Layer 2 invariant reads `conflict_edges[]` only.
+
 ## Blast-Radius Contention Doctrine (issue #489)
 
 The conflict graph that seeds cohorts is only as good as the evidence that produces its edges. Two

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

@@ -15,7 +15,7 @@ This rule file summarizes the PowerShell-specific policies for this repository.
 1. **Formatting — Invoke-Formatter**: Format all PowerShell files via PoshQC. MCP command: `mcp__drm-copilot__run_poshqc_format`
 2. **Linting — PSScriptAnalyzer**: Run PoshQC analyzer with repo settings. MCP command: `mcp__drm-copilot__run_poshqc_analyze`. Optional autofix: `mcp__drm-copilot__run_poshqc_analyze_autofix`
 3. **Type checking**: Not applicable for PowerShell; skip to testing.
-4. **Testing — Pester (v5.x)**: Run tests via MCP. MCP command: `mcp__drm-copilot__run_poshqc_test`. Use repo config at `scripts/powershell/PoshQC/settings/pester.runsettings.psd1`.
+4. **Testing — Pester (v6.x)**: Run tests via MCP. MCP command: `mcp__drm-copilot__run_poshqc_test`. Use repo config at `scripts/powershell/PoshQC/settings/pester.runsettings.psd1`.
 
 Run the toolchain in order: format → analyze → test. Restart from step 1 if any step fails or changes files. Use the MCP server functions; do not substitute VS Code task wrappers.
 
@@ -53,7 +53,7 @@ Introduce the smallest seam that enables reliable mocking. Apply these options i
 
 ## Testing Standards
 
-- Use **Pester** (v5.x) as the test framework.
+- Use **Pester** (v6.x) as the test framework.
 - Organize tests to mirror code structure (e.g., `tests/scripts/dev-tools/ScriptName.Tests.ps1`).
 - Name test files `*.Tests.ps1`.
 - Use `Describe`/`Context`/`It` blocks; one behavior per `It`.

package/resources/claude-customizations/.claude/settings.json

@@ -11,6 +11,7 @@
       "Bash(bash .claude/lib/bash/mutate-parallel-run.sh*)",
       "Bash(bash .claude/lib/bash/remove-parallel-item.sh*)",
       "Bash(bash .claude/lib/bash/validate-parallel-manifest.sh*)",
+      "Bash(pwsh -NoProfile -NonInteractive -File .claude/lib/parallel-admission/Invoke-ParallelAdmission.ps1*)",
       "Read",
       "Edit(docs/**)",
       "Edit(artifacts/**)",

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

@@ -32,7 +32,7 @@ Rules:
 - **Tool routes are not restated.** Tool routes, launchers, wrapper scripts, command-text restrictions, the batch budget, hook context, and CI shape are owned by the `execution-environment` skill. A plan references that skill instead of restating its content.
 - **Changed existing behavior names its asserting tests.** A task that changes the observable behavior of an existing function, script, fixture, or test stub (its signature, argv, output, exit status, or the files it writes) names every existing test that asserts that behavior and states each test's disposition: unchanged because it is unaffected, or updated, with the reason for the update. The tests are found by searching the test tree for the symbol, the file name, and the asserted output. A test that asserts the current behavior and is outside the task's file set fails once the change lands, and the plan's own acceptance condition then cannot be met. The planner's adversarial self-review includes this search for every task that changes existing behavior.
 - **Size guideline.** A plan stays within 40 canonical tasks and 400 physical lines. A plan that needs more carries a `## Size Justification` section with at least one line stating why the size is necessary (validator rule G13). Files produced by one generator run count as one generator task.
-- **Pre-Mortem.** Every plan carries a `## Pre-Mortem` section with one bullet beginning with each of the seven labels `Review checklists`, `Coverage`, `Mirror parity`, `File size`, `Test isolation`, `CI-only behavior`, and `Evidence`. Each bullet states how the plan prevents that failure class, or states "not applicable" followed by the reason. The `Test isolation` bullet names the isolation runs the plan performs: a seeded shuffled Jest run with the seed recorded, a reversed-order run of the new or changed Python test modules, and a seeded shuffled file-order run of the touched Pester suites with at least three seeds, each seed recorded. The `Mirror parity` bullet also covers the execution-environment brief: a plan that alters a fact the brief states (for example, it adds or renames a CI job, changes a required status context, a tool route, or a batch-budget rule) includes a task that updates the brief in the same change, in all six byte-identical copies, and the bullet names that task. Without that task the brief states a superseded fact once the change lands, which breaks the brief's own maintenance rule. The planner SubagentStop hook blocks a plan without a complete section.
+- **Pre-Mortem.** Every plan carries a `## Pre-Mortem` section with one bullet beginning with each of the seven labels `Review checklists`, `Coverage`, `Mirror parity`, `File size`, `Test isolation`, `CI-only behavior`, and `Evidence`. Each bullet states how the plan prevents that failure class, or states "not applicable" followed by the reason. The `Test isolation` bullet names the parallel gates the plan uses: one `Invoke-PoshQCParallelTest` run, one `pytest -n auto` run, and Jest through its normal parallel workers, each re-run only after a fix. The `Mirror parity` bullet also covers the execution-environment brief: a plan that alters a fact the brief states (for example, it adds or renames a CI job, changes a required status context, a tool route, or a batch-budget rule) includes a task that updates the brief in the same change, in all six byte-identical copies, and the bullet names that task. Without that task the brief states a superseded fact once the change lands, which breaks the brief's own maintenance rule. The planner SubagentStop hook blocks a plan without a complete section.
 - **Final-phase self-review.** The final phase of every plan contains a self-review task that walks the policy-audit, code-review, and feature-audit templates under `docs/features/templates/policy_audit/` against the branch diff from the merge base and writes `<FEATURE>/evidence/qa-gates/self-review.<timestamp>.md` with one PASS, FAIL, or N/A row per checklist item. A FAIL row is fixed and the QA loop is re-run before the self-review is rewritten; the plan does not complete with a FAIL row.
 
 This section takes precedence over the literal-quoting rules of `## Wrap-Tolerant Assertion Authoring (Mandatory)`: those rules govern the asserted value of an acceptance condition, not context.
@@ -43,12 +43,11 @@ When orchestration selects short path, a minimal plan is still mandatory and mus
 
 1) Baseline capture block
 - policy reads in required order,
-- baseline toolchain/test state capture for each language that has explicit baseline command tasks in the plan.
+- static baseline capture (format, lint, type check, and analyzer findings) for each language that has explicit baseline command tasks in the plan; no test suite runs in this block.
 - required artifacts:
 	- a Phase 0 policy-read evidence artifact in the canonical evidence location defined by `evidence-and-timestamp-conventions`
 	- one baseline artifact per baseline command step (no aggregate-only baseline artifact)
 	- each baseline step artifact MUST include: `Timestamp:`, `Command:`, `EXIT_CODE:`, `Output Summary:`
-	- baseline test-step artifacts for languages with mandatory coverage policy MUST include numeric coverage headline values in `Output Summary:` (baseline percent and, when applicable, targeted module/new-code percent).
 
 2) Delegated implementation block
 - explicit handoff task to the small-path implementation engineer,
@@ -59,7 +58,7 @@ When orchestration selects short path, a minimal plan is still mandatory and mus
 - rerun behavior when any step changes files or fails.
 - one final-QC artifact per QC command step (no aggregate-only final-QC artifact)
 - each final-QC step artifact MUST include: `Timestamp:`, `Command:`, `EXIT_CODE:`, `Output Summary:`
-- final-QC test commands for languages with mandatory coverage policy MUST run in coverage mode and record numeric post-change coverage values in `Output Summary:`.
+- final-QC test commands for languages with mandatory coverage policy MUST run in coverage mode and record numeric coverage values from the single gate run in `Output Summary:`.
 - final-QC command tasks that are present in the approved plan MUST execute their stated commands; `SKIPPED` is invalid unless the task text itself explicitly authorizes a skip condition.
 
 4) Reduced audit block
@@ -96,7 +95,7 @@ Branching after Phase 0:
 
 Phase 0 must include tasks to read policy files in the order defined in `policy-compliance-order`.
 
-Phase 0 must also capture baseline toolchain results for the languages touched. Baseline artifact conventions (location + required fields) are defined in `evidence-and-timestamp-conventions`.
+Phase 0 must also capture static baselines (format, lint, type check, and analyzer findings) for the languages touched, and no test suite runs in it. Baseline artifact conventions (location + required fields) are defined in `evidence-and-timestamp-conventions`.
 
 For short-path/minimal-audit plans, Phase 0 evidence is incomplete unless both artifacts exist:
 - `phase0-instructions-read.md` with at least: `Timestamp:`, `Policy Order:`, and explicit list of files read.
@@ -128,12 +127,9 @@ Plans name evidence artifacts `<name>.<timestamp>.md` and never fix a plan-time
 
 For any language in scope where repository policy requires coverage validation:
 
-- The approved plan MUST include explicit baseline and final-QC coverage capture tasks.
-- Baseline and final-QC artifacts MUST record numeric coverage values (not placeholders such as `UNVERIFIED`).
-- Where policy requires no-regression and new-code thresholds, the plan MUST include a delta/threshold verification task that reports:
-	- baseline coverage,
-	- post-change coverage,
-	- new/changed-code coverage.
+- The approved plan MUST include an explicit final-QC coverage capture task.
+- The final-QC artifact MUST record numeric coverage values (not placeholders such as `UNVERIFIED`).
+- The plan MUST include a threshold task that reports each changed file from the single gate run against the coverage thresholds. New behavior is tested. No earlier figure is compared.
 - If required coverage values are unavailable, the plan outcome MUST be remediation-required and MUST NOT be reported as PASS.
 
 ## Final QA Loop (Required for Code/Test Changes)
@@ -248,7 +244,7 @@ Rules:
 - **Observe a command's success-case output before asserting over that output (mandatory).** Run the command, or read a recorded run of it, and confirm the value you intend to assert is actually printed on a *successful* run. Do not infer it from the tool's documentation, from the plan, or from what the tool prints on failure. This requirement exists because the class of defect it prevents is not detectable by reading: an assertion on a line the tool prints only when it changed something is unsatisfiable on a clean run; a demand for a zero-diagnostic count from a tool that returns only an ok flag names a value with no source; a demand for separate line and branch percentages from a coverage run that prints one combined column reads two numbers that are never printed. G7 and G9 cover two decidable slices of this class. The remainder is covered by this requirement and by nothing else, so a reviewer cannot rely on the gate to catch it.
 - **Fix the evidence in the plan; never leave the executor to select it.** An executor free to choose the evidence it is judged against cannot fail. Do not write an acceptance condition that asks the executor to identify "the known-genuine pair", to choose a survivor list, or to pick any suitable instance. Name the instances, or state the mechanical derivation that produces them, so a third party re-running it obtains the same set. This is authoring guidance and not a rule: a validator rule that scanned acceptance text for selection vocabulary was proposed and rejected, because that vocabulary is ordinary plan prose used in roles carrying no selection semantics and a keyword scan over prose is not statically decidable for the property it would claim to detect. The judgment is the author's, and it is not automated. `.claude/rules/plan-acceptance-gates.md` records the rejection and the reason for it.
 - **Check that the task-ordering does not make the condition unsatisfiable.** No rule covers this. A gate that runs a test path containing deliberately-failing cases added by an earlier task, before the later task that makes them pass, cannot exit 0. A baseline captured after a write-mode formatter has already repaired pre-existing drift becomes either a blanket waiver or makes a later gate unsatisfiable. Read each acceptance condition against the state the plan will actually be in when its task runs.
-- **Name the runner and job for a Pester acceptance criterion.** In `.github/workflows/_poshqc.yml`, the Pester suites run with coverage on `windows-latest` in the shard jobs `poshqc / PowerShell QC shard 1`, `shard 2`, and `shard 3`; `poshqc / PowerShell QC` is the aggregating required check, which requires the static and shard jobs to succeed and merges shard coverage; and `poshqc / PowerShell hook suites (Linux)` runs only `tests/scripts/claude-hooks` and `tests/scripts/codex-hooks` on `ubuntu-latest`, with coverage disabled. The execution-environment brief's `## CI Shape and Required Checks` section is the authoritative description of this shape. A Pester acceptance criterion may cite `ubuntu-latest` only for suites under `tests/scripts/claude-hooks` or `tests/scripts/codex-hooks`, never for coverage, and must name the job it relies on (`poshqc / PowerShell QC` or `poshqc / PowerShell hook suites (Linux)`).
+- **Name the runner and job for a Pester acceptance criterion.** In `.github/workflows/_poshqc.yml`, the Pester suites run with coverage on `windows-latest` in the shard jobs `poshqc / PowerShell QC shard 1`, `shard 2`, and `shard 3`; `poshqc / PowerShell QC` is the aggregating check, whose result `CI Required Gate` requires, and it requires the static and shard jobs to succeed and merges shard coverage; and `poshqc / PowerShell hook suites (Linux)` runs only `tests/scripts/claude-hooks` and `tests/scripts/codex-hooks` on `ubuntu-latest`, with coverage disabled. The execution-environment brief's `## CI Shape and Required Checks` section is the authoritative description of this shape. A Pester acceptance criterion may cite `ubuntu-latest` only for suites under `tests/scripts/claude-hooks` or `tests/scripts/codex-hooks`, never for coverage, and must name the job it relies on (`poshqc / PowerShell QC` or `poshqc / PowerShell hook suites (Linux)`).
 - **Do not assert a fixed-string search literal that contains a backslash.** Git for Windows grep 3.0 reads a doubled backslash in a `grep -F` pattern as one backslash, so the same check returns a different count locally than on a CI runner and cannot pass in both places. Assert a backslash-free substring of the literal, a named test, or a hash or byte-identity check instead.
 
 ## Plan-Path Continuity Contract (Mandatory)
@@ -275,7 +271,7 @@ When a plan is generated or validated from a feature folder, resolve selected mo
 
 ## Mode-Specific Mandatory Plan Gates
 
-- `minor-audit` plans MUST include baseline evidence tasks, targeted verification evidence tasks, and end-state evidence tasks.
+- `minor-audit` plans MUST include static baseline evidence tasks, targeted verification evidence tasks read from the gate run, and end-state evidence tasks.
 - `minor-audit` plans MUST require `${feature-folder}/issue.md` to contain an explicit `## Acceptance Criteria` section; do not infer acceptance criteria from other `issue.md` sections.
 - `minor-audit` plans MUST NOT treat missing `spec.md` or `user-story.md` as automatic blockers.
 - `minor-audit` execution/validation/audit MUST fail closed when `spec.md` or `user-story.md` exists unexpectedly in the active folder, when the explicit `## Acceptance Criteria` section is missing from `issue.md`, when required Phase 0 artifacts are missing, or when checklist state contradicts evidence on disk.

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

@@ -162,7 +162,9 @@ The script emits pipe-delimited, `LC_ALL=C`-ordered records, one per line:
 2. **Editorial triage of the cherry-pick candidates.** Review each
    `COMMIT|...|UNIQUE|...` record — this is the LLM-judgment boundary. Confirm
    editorially that the unique commits are genuinely documentation/agent-memory
-   content (for example paths under `docs/**`, `.claude/agent-memory/**`, or `**/*.md`).
+   content: paths under the repository-relative prefixes `docs/` and `.claude/agent-memory/`,
+   compared case-sensitively. A Markdown file outside those two prefixes (for example
+   `CLAUDE.md` or `.claude/rules/*.md`) is not consolidation content.
    The script only reports the deterministic facts (SHA, paths, author, date); deciding
    what counts as documentation is this skill's responsibility.
 
@@ -174,21 +176,42 @@ The script emits pipe-delimited, `LC_ALL=C`-ordered records, one per line:
    reuse it silently. Conflicts are aborted and surfaced as `CONFLICT` for editorial
    resolution, never auto-resolved.
 
+   **Cleanup context.** A cleanup run writes no orchestration checkpoint, so the enforcement
+   hooks recognize its operations by the cleanup context instead: the sanctioned-removal
+   manifest at the session root (`artifacts/orchestration/cleanup-worktrees-manifest.json` in
+   the main checkout where this skill runs, written whole with Write; see Sanctioned Removal
+   Manifest) and the consolidation worktree, identified by its branch
+   `documentationandmemories`. Any staging in that worktree beyond what the script performs
+   uses `git -C <consolidation root> add -- <path>` with paths under `docs/` or
+   `.claude/agent-memory/` only, and the commit uses
+   `git -C <consolidation root> commit -F <message file>` with no pathspec. The preimplementation
+   gate admits that commit only when every staged path is under those two prefixes.
+
 4. **Push and hand off PR creation to `Agent(pr-author)`.** Push the consolidation
-   branch (`git push`). Refresh the PR-context bundle with
-   `mcp__drm-copilot__collect_pr_context` using base branch `main` (producing
-   `artifacts/pr_context.summary.txt` and `artifacts/pr_context.appendix.txt`).
-   Validate the orchestrator-state checkpoint
-   (`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`, which owns the body-file and receipt contract;
-   defer to that skill for it rather than restating any value from it here. For `<N>`,
+   branch (`git -C <consolidation root> push -u origin documentationandmemories`).
+   The push precedes `gh pr create`: the PR-author gate requires
+   `refs/remotes/origin/documentationandmemories` to resolve to the same commit as the
+   consolidation worktree `HEAD`, so push again after any later commit in that worktree. Refresh the
+   PR-context bundle with `mcp__drm-copilot__collect_pr_context` using base branch `main` and
+   `workspace_root` set to the consolidation worktree, so that
+   `artifacts/pr_context.summary.txt` and `artifacts/pr_context.appendix.txt` exist beneath the
+   consolidation worktree. A consolidation pull request has no orchestrator-state checkpoint and
+   is not validated against one; the hooks perform the cleanup readiness check instead.
+   `enforce-model-routing-receipt.ps1` admits the `Agent(pr-author)` delegation, and
+   `enforce-pr-author-skill.ps1` admits `gh pr create`, only while a fresh, valid manifest exists
+   at the session root; the PR-author gate also requires an explicit
+   `--head documentationandmemories --base main` and a branch diff limited to `docs/` and
+   `.claude/agent-memory/`, and its receipt checks still apply. Then delegate PR creation to
+   `Agent(pr-author)` per `.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.
+   The delegation is non-isolated and passes the absolute body path beneath the consolidation
+   worktree, as that skill's coordinator-session topology requires. 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
+   The delegation prompt MUST carry exactly one `branch: documentationandmemories` label, on
+   its own line, and no `--head` or `--branch` text, plus the canonical issue number line when
+   the run has an issue number.
+   `enforce-model-routing-receipt.ps1` identifies the item from those 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.
@@ -397,6 +420,15 @@ specific files or commit SHAs, before step 9 acts on any finding.
 `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 manifest lives at the session root: the main checkout where this skill runs. Both removal
+gates, the PR-author gate, and the model-routing gate read the relative path
+`artifacts/orchestration/cleanup-worktrees-manifest.json` against the hook process location,
+which is the session root, so a manifest written in any other worktree is never read. Write the
+whole document with Write; the preimplementation gate admits that Write without a checkpoint
+only at the session-root spelling and only when the content carries the expected `tool` and
+`schema_version`. An Edit of the manifest is not supported without a checkpoint, and neither is a
+Codex `apply_patch` Update, Delete, or Move of it; rewrite the document with Write instead.
+
 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
@@ -445,7 +477,8 @@ These records serve the consolidation consumer and are never read by either gate
   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.
+  adds a new file or carries a working-tree modification. How each class is staged is described
+  under `### Preserve staging outcomes`.
 - `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
@@ -499,6 +532,52 @@ These records serve the consolidation consumer and are never read by either gate
 }
 ```
 
+### Preserve staging outcomes
+
+`cleanup-worktrees.sh --preserve` reports each record's outcome as
+`ACTION|preserve-stage|<target_path>|<result>`. The result vocabulary is:
+
+- `OK` — the record was written and staged.
+- `FAILED` — a write or staging operation failed; the remaining records continue.
+- `SKIPPED-INVALID` — a record field failed validation.
+- `MISSING-SOURCE` — the source file does not exist in the named worktree.
+- `HOST-TOKEN-BLOCKED` — the incoming bytes carry a host-identifying token; the whole pass stops
+  with exit 3 and nothing is staged.
+- `IGNORED-TARGET` — the target path is ignored on the consolidation branch and is not forced.
+- `MISSING-WORKTREE` — the consolidation worktree does not exist.
+- `REFUSED-WOULD-REGRESS` — staging the record would lose a line that the consolidation branch
+  already carries, or the record repeats an earlier record's `target_path`.
+
+Staging depends on whether `<consolidation-worktree>/<target_path>` is an existing regular file:
+
+- Absent target, either `change_class`: the source is copied byte for byte.
+- Existing target, `untracked` record: the source is copied only when every line of the target is
+  present in the source in the same order; otherwise the record is refused.
+- Existing target, `modified` record with a merge base (the source path equals the target path, and
+  the file exists at the merge base of the worktree `HEAD` and the consolidation `HEAD`): the
+  worktree change must only add lines to the base (G1); a `git merge-file --union --object-id`
+  merge of the target, the base, and the source then runs; the merged result must keep every target
+  line (G2) and must add no line beyond the worktree's own additions (G3). The merged blob is
+  staged.
+- Existing target, `modified` record without a merge base: treated as an existing `untracked`
+  target.
+- A record whose `target_path` repeats an earlier record's in the same pass is refused; the first
+  record keeps the target.
+
+A refused record still emits its `PRESERVE|` record, writes a `cleanup-worktrees: refused` line to
+stderr naming the failed guard, appends no `MEMORY.md` index line, and makes the pass exit 1.
+
+Residuals:
+
+- A resurrected line textually identical to a line the worktree added cannot be distinguished by G3.
+- The merge path requires Git 2.43 or later for `merge-file --object-id`; an older Git fails the
+  merge and the record is refused.
+- The order in which `--union` places two insertions at the same position is not specified by Git;
+  G2 and G3 bound the result whatever the order.
+- The planning phase writes unreferenced blob objects (`hash-object -w`, `merge-file --object-id`)
+  to the object store; it writes no index, ref, or working-tree file.
+- A refused record is not consolidated; the operator consolidates it manually.
+
 ### Accepted residual
 
 Both gates read the command text of the `Bash` tool call they are given. A removal routed

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

@@ -30,19 +30,24 @@ 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
+# None of the four libraries below requires being sourced last, and none 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.
+# library, consolidation_worktree_path from the actions library, and the staging decision
+# from the merge 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 merge library holds the preserve staging decision. It is sourced before the
+# line-ending library so that library stays immediately before the preserve library.
+# shellcheck source=.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_preserve_merge_lib.sh
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/cleanup_worktrees_preserve_merge_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
@@ -69,12 +74,20 @@ Commands:
   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
+                       from CLEANUP_WT_MANIFEST_PATH. Staging depends on the target and
+                       change_class: a target absent from the consolidation branch is
+                       copied byte for byte; an existing target is copied only when
+                       none of its lines would be lost (untracked, or modified with no
+                       merge base), or receives a three-way union merge of the
+                       worktree's added lines (modified with a merge base). A record
+                       that would lose a line, fails a merge guard, or repeats an
+                       earlier target_path is refused with
+                       ACTION|preserve-stage|<target>|REFUSED-WOULD-REGRESS. The
+                       MEMORY.md index line is carried across using the destination
+                       file's own re-derived line-ending convention, and the whole pass
+                       is refused when the incoming bytes carry a host-identifying
+                       token. Exit 0 clean, 1 something was skipped or refused 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.
 

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

@@ -12,12 +12,13 @@
 # cleanup_worktrees_actions_lib.sh, because it calls cleanup_wt_git (defined in the
 # enumeration library) and consolidation_worktree_path (defined in the actions library).
 #
-# Two-phase design. preserve_plan performs NO writes: it reads and validates the manifest
-# and every record, verifies each source file exists, runs the host-token pre-pass,
-# decides each index outcome, and emits the PRESERVE| and ACTION| records plus an internal
-# plan stream. preserve_commit_plan is the only function that writes and is entered only
-# when the pre-pass reported no match, which is what keeps the writing phase thin enough
-# to leave in the coverage denominator rather than exclude from measurement.
+# Two-phase design. preserve_plan writes no index, ref, or working-tree file: it validates
+# the manifest and every record, verifies each source exists, runs the host-token
+# pre-pass, takes each staging and index decision, and emits the PRESERVE| and ACTION|
+# records plus an internal plan stream. Its one write is the exception stated in
+# cleanup_worktrees_preserve_merge_lib.sh: unreferenced blob objects created by
+# `hash-object -w` and `merge-file --object-id`. preserve_commit_plan is the only writer of
+# files and is entered only when the pre-pass reported no match.
 #
 # Seams. All git commands go through cleanup_wt_git (CLEANUP_WT_GIT_BIN); jq resolves
 # through preserve_resolve_jq (CLEANUP_WT_JQ_BIN); the manifest path comes from
@@ -174,9 +175,8 @@ preserve_validate_record() {
 	# ACTION|preserve-stage|<target-path>|SKIPPED-INVALID; the first violation in the chain
 	# below wins, because one bad field skips the record whatever the others say.
 	#
-	# change_class is validated for vocabulary but does NOT change the staging action: an
-	# untracked and a modified record are both copied to target_path and staged, stated
-	# here so no later change invents a divergent path for one of them.
+	# change_class is validated here for vocabulary only; its effect on staging belongs to
+	# preserve_merge_decide (absent target copied, existing target guarded or merged).
 	#
 	# host_token_scan is refused when it is absent, is not a JSON object, is missing either
 	# member, or carries a result outside clean/tokens_present: a record whose scan metadata
@@ -236,16 +236,18 @@ preserve_validate_record() {
 }
 
 preserve_plan_one() {
-	# Plan one manifest record. Performs no write of any kind.
+	# Plan one manifest record. Writes no index, ref, or working-tree file; the staging
+	# decision may write unreferenced blob objects (`hash-object -w`, `merge-file
+	# --object-id`), the exception cleanup_worktrees_preserve_merge_lib.sh states.
 	#
-	# The PRESERVE| report record is emitted for every record that survives validation,
-	# before any per-record outcome is known, because that record identifies the finding at
-	# its origin exactly as DIRTY|<worktree-path>|<status-line> does. The destination
-	# outcome travels separately on the ACTION| result channel.
+	# The PRESERVE| record is emitted for every record that survives validation, before any
+	# per-record outcome is known, as DIRTY|<worktree-path>|<status-line> is; the outcome
+	# travels separately on the ACTION| result channel. The source file is read by plain
+	# file I/O at <worktree_path>/<source_path>, never through git (see the header).
 	#
-	# The source file is located by plain file I/O at <worktree_path>/<source_path> and is
-	# never read through git: the repository-root .claude/agent-memory tree is gitignored,
-	# so a git-mediated read would be refused or would need a force flag.
+	# The plan entry carries ten columns: target_path, source file, destination file, index
+	# action, index path, index line, terminator token, leading-terminator flag, staging
+	# mode (`copy` or `merge`), and the merged blob id (empty for `copy`).
 	#
 	# Args: $1 = the tab-separated record. Returns 0 when the record was planned and 1 when
 	# it was skipped, refused, or reported.
@@ -294,6 +296,11 @@ preserve_plan_one() {
 		printf 'cleanup-worktrees: destination is ignored, refusing to force: %s\n' "$tgt" >&2
 		return 1
 	fi
+	# The staging decision (merge library): a repeated target_path is refused, and a target
+	# that already exists is guarded or merged rather than overwritten. A refusal returns
+	# before the index decision, so a refused record produces no index record either.
+	preserve_merge_check_duplicate "$tgt" || return 1
+	preserve_merge_decide "${PRESERVE_FIELDS[2]}" "$wt" "$src" "$tgt" "$PRESERVE_CWT" || return 1
 	# The index decision, including the line-ending re-derivation it rests on, lives in
 	# the line-ending library. A memory_index_line of JSON null means the file is not a
 	# memory entry: it is copied and staged, and no index is read, created, or appended to.
@@ -307,16 +314,19 @@ preserve_plan_one() {
 		ipre=$PRESERVE_INDEX_PRE
 	fi
 	local entry
-	printf -v entry '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s' \
-		"$tgt" "$srcfile" "$PRESERVE_CWT/$tgt" "$iaction" "$ipath" "$iline" "$iterm" "$ipre"
+	printf -v entry '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s' \
+		"$tgt" "$srcfile" "$PRESERVE_CWT/$tgt" "$iaction" "$ipath" "$iline" "$iterm" "$ipre" \
+		"$PRESERVE_STAGE_MODE" "$PRESERVE_STAGE_OID"
 	PRESERVE_PLAN_STREAM+=("$entry")
 	return 0
 }
 
 preserve_plan() {
-	# Phase 1 of the two-phase driver: read, validate, decide, and report. It performs no
-	# write of any kind, so a failure anywhere in it leaves the consolidation worktree
-	# byte-unchanged and there is nothing to undo.
+	# Phase 1 of the two-phase driver: read, validate, decide, and report. It writes no
+	# index, ref, or working-tree file, so a failure anywhere in it leaves the consolidation
+	# worktree byte-unchanged and there is nothing to undo. The one exception is the staging
+	# decision's unreferenced blob objects (`hash-object -w`, `merge-file --object-id`),
+	# which nothing references unless phase 2 stages the merged result.
 	#
 	# Records are processed in LC_ALL=C order of the pair (worktree_path, source_path)
 	# rather than in manifest array order, because the report stream's ordering is
@@ -324,10 +334,8 @@ preserve_plan() {
 	# a contract. The sort is field-aware rather than whole-line, so a worktree_path that
 	# is a prefix of another cannot reorder the pair.
 	#
-	# The decisions are accumulated on two globals rather than returned, because a record's
-	# outcome has to survive the loop: PRESERVE_PLAN_STREAM carries one tab-separated entry
-	# per record that reached the writing phase, and PRESERVE_EXIT accumulates the
-	# per-record skip signal that becomes the pass's exit code.
+	# Outcomes survive the loop on globals: PRESERVE_PLAN_STREAM (one entry per planned
+	# record), PRESERVE_EXIT (the per-record skip signal), and PRESERVE_SEEN_TARGETS.
 	#
 	# Returns 0 when the pass may proceed to the writing phase, 1 when the manifest itself
 	# was rejected, 3 on the host-token hard stop, and 127 when a required tool could not
@@ -337,6 +345,9 @@ preserve_plan() {
 	PRESERVE_EXIT=0
 	PRESERVE_BLOCKED=0
 	PRESERVE_CWT=""
+	# Read by preserve_merge_check_duplicate in the merge library (SC2034 cannot see it).
+	# shellcheck disable=SC2034
+	PRESERVE_SEEN_TARGETS=""
 	local manifest records sorted line rc=0
 	manifest=${CLEANUP_WT_MANIFEST_PATH:-artifacts/orchestration/cleanup-worktrees-manifest.json}
 	PRESERVE_CWT=$(consolidation_worktree_path) || return $?
@@ -353,31 +364,26 @@ preserve_plan() {
 		[[ -n $line ]] || continue
 		preserve_plan_one "$line" || PRESERVE_EXIT=1
 	done <<<"$sorted"
-	# The hard stop is evaluated only after every record has been examined, so the pass
-	# reports every match rather than only the first, and the writing phase is not entered
-	# for any record. Nothing has been written at this point, so there is nothing to undo.
+	# The hard stop is evaluated after every record is examined, so every match is reported
+	# and the writing phase is entered for no record; no file has been written to undo.
 	((PRESERVE_BLOCKED == 0)) || return 3
 	return 0
 }
 
 preserve_commit_plan() {
-	# Phase 2: the only function in this library that writes anything.
+	# Phase 2: the only function in this library that writes files. It executes each plan
+	# entry's decisions with exactly four kinds of operation: mkdir -p of the destination
+	# directory, the content write, the index append or creation, and the staging call. It
+	# takes no staging decision of its own, which keeps it thin enough to stay measured.
 	#
-	# It consumes the plan stream phase 1 built and performs exactly four kinds of
-	# operation: mkdir -p of the destination directory, a verbatim byte copy of the source,
-	# the destination index append or creation, and the staging call. Every decision was
-	# already taken in phase 1, so this function contains no policy and is thin enough to
-	# leave in the coverage denominator rather than exclude from measurement.
+	# The content write follows column 9. `merge` writes the merged blob phase 1 recorded
+	# (`cat-file blob <oid>`); `copy` or empty copies the source byte for byte. Neither
+	# applies a line-ending transformation to the preserved content; the line-ending
+	# obligation is scoped to the index append, and staging re-normalizes tracked text.
 	#
-	# The copy is verbatim. No line-ending transformation is applied to the preserved
-	# file's own content: transforming it would alter content the editorial pass judged
-	# worth keeping, and the staging call re-normalizes tracked text anyway. The
-	# line-ending obligation is scoped to the index append, where the defect occurred.
-	#
-	# A non-zero result from any of the three operations emits
-	# ACTION|preserve-stage|<target-path>|FAILED and contributes to exit 1; it never aborts
-	# the remaining records, because each record's write is independent of the others.
-	local entry tgt srcfile dstfile iaction ipath iline iterm ipre fail
+	# A failed operation emits ACTION|preserve-stage|<target-path>|FAILED and contributes to
+	# exit 1; it never aborts the remaining records, whose writes are independent.
+	local entry tgt srcfile dstfile iaction ipath iline iterm ipre mode oid fail
 	((${#PRESERVE_PLAN_STREAM[@]} > 0)) || return 0
 	for entry in "${PRESERVE_PLAN_STREAM[@]}"; do
 		preserve_split_tsv "$entry"
@@ -389,10 +395,12 @@ preserve_commit_plan() {
 		iline=${PRESERVE_FIELDS[5]}
 		iterm=${PRESERVE_FIELDS[6]}
 		ipre=${PRESERVE_FIELDS[7]}
-		fail=""
+		mode=${PRESERVE_FIELDS[8]-} oid=${PRESERVE_FIELDS[9]-} fail=""
 		if ! mkdir -p -- "${dstfile%/*}" 2>/dev/null; then
 			fail="cannot create the destination directory"
-		elif ! cat -- "$srcfile" >"$dstfile" 2>/dev/null; then
+		elif [[ $mode == "merge" ]] && ! cleanup_wt_git -C "$PRESERVE_CWT" cat-file blob "$oid" >"$dstfile"; then
+			fail="reading the merged blob failed"
+		elif [[ $mode != "merge" ]] && ! cat -- "$srcfile" >"$dstfile" 2>/dev/null; then
 			fail="the verbatim byte copy failed"
 		elif [[ $iaction != "none" ]] &&
 			! preserve_render_index_append "$ipath" "$iline" "$iterm" "$ipre"; then