@danmoisan/drm-copilot-mcp 1.1.24 → 1.1.26

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

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

@@ -0,0 +1,234 @@
+#!/usr/bin/env bash
+# cleanup_worktrees_preserve_merge_lib.sh: sourceable staging-decision function group for
+# the preserve pass of the cleanup-worktrees tool. For each preserve record whose target
+# already exists as a regular file on the consolidation branch, it decides whether the
+# source may be copied, whether a three-way union merge may be staged instead, or whether
+# the record must be refused with ACTION|preserve-stage|<target-path>|REFUSED-WOULD-REGRESS.
+#
+# Sourcing contract: this library defines functions only and runs no work at source time.
+# It MUST be sourced before cleanup_worktrees_preserve_lib.sh, whose preserve_plan_one calls
+# preserve_merge_check_duplicate and preserve_merge_decide. Its own git calls go through
+# cleanup_wt_git, defined in cleanup_worktrees_enumerate_lib.sh.
+#
+# Phase-1 write exception. The preserve planning phase writes no index, ref, or working-tree
+# file. The one write it performs is the creation of unreferenced blob objects in the object
+# store: `git hash-object -w` hashes the two merge inputs and `git merge-file --object-id`
+# records the merged result. Nothing refers to those blobs unless the writing phase stages
+# the merged result, and an unreferenced blob is removed by the normal object pruning.
+#
+# Line-comparison rule. Every guard compares lines. Content is split with the
+# `while IFS= read -r line || [[ -n $line ]]` idiom, so an unterminated final line counts as
+# a line, and one trailing carriage return is stripped from each line before comparison, so
+# a CRLF working-tree file and its LF-normalized blob compare equal.
+#
+# No git call in this library passes -f or --force, and no process substitution is passed
+# to git as a file argument: native git on Windows cannot open an MSYS /dev/fd path.
+
+preserve_merge_split_lines() {
+	# Split one content string into the global array PRESERVE_MERGE_LINES under the
+	# line-comparison rule stated in the header. An empty string yields no line at all.
+	#
+	# Args: $1 = the content.
+	PRESERVE_MERGE_LINES=()
+	# The carriage return is held in a variable: ANSI-C quoting nested inside a
+	# double-quoted expansion is not interpreted consistently across bash versions.
+	local line cr=$'\r'
+	while IFS= read -r line || [[ -n $line ]]; do
+		PRESERVE_MERGE_LINES+=("${line%"$cr"}")
+	done < <(printf '%s' "${1-}")
+}
+
+preserve_merge_is_subsequence() {
+	# Return 0 when every line of the needle appears in the haystack in the same order, not
+	# necessarily adjacent, and 1 otherwise. An empty needle is a subsequence of anything.
+	#
+	# Args: $1 = needle content, $2 = haystack content.
+	local -a needle=() hay=()
+	preserve_merge_split_lines "${1-}"
+	needle=("${PRESERVE_MERGE_LINES[@]}")
+	preserve_merge_split_lines "${2-}"
+	hay=("${PRESERVE_MERGE_LINES[@]}")
+	local n=${#needle[@]} i=0 line
+	if ((n == 0)); then
+		return 0
+	fi
+	for line in "${hay[@]}"; do
+		if [[ $line == "${needle[$i]}" ]]; then
+			i=$((i + 1))
+			if ((i == n)); then
+				return 0
+			fi
+		fi
+	done
+	return 1
+}
+
+preserve_merge_extra_within() {
+	# Guard G3. Return 0 when multiset(merged) minus multiset(main) is contained in
+	# multiset(worktree) minus multiset(base), and 1 otherwise. A merged line that main does
+	# not carry is admitted only as one of the worktree's own additions, so a base line that
+	# main deleted and the merge re-emitted is refused. Counts are kept per line, so a line
+	# the worktree added once may appear at most once beyond main's own copies.
+	#
+	# Keys carry a fixed prefix because bash refuses an empty associative-array subscript,
+	# and a blank line is an ordinary line.
+	#
+	# Args: $1 = merged content, $2 = main content, $3 = worktree content, $4 = base content.
+	local -A extra=() added=()
+	local line key
+	preserve_merge_split_lines "${1-}"
+	for line in "${PRESERVE_MERGE_LINES[@]}"; do
+		key="k$line"
+		extra["$key"]=$((${extra["$key"]:-0} + 1))
+	done
+	preserve_merge_split_lines "${2-}"
+	for line in "${PRESERVE_MERGE_LINES[@]}"; do
+		key="k$line"
+		extra["$key"]=$((${extra["$key"]:-0} - 1))
+	done
+	preserve_merge_split_lines "${3-}"
+	for line in "${PRESERVE_MERGE_LINES[@]}"; do
+		key="k$line"
+		added["$key"]=$((${added["$key"]:-0} + 1))
+	done
+	preserve_merge_split_lines "${4-}"
+	for line in "${PRESERVE_MERGE_LINES[@]}"; do
+		key="k$line"
+		added["$key"]=$((${added["$key"]:-0} - 1))
+	done
+	for key in "${!extra[@]}"; do
+		if ((${extra["$key"]} > ${added["$key"]:-0} && ${extra["$key"]} > 0)); then
+			return 1
+		fi
+	done
+	return 0
+}
+
+preserve_merge_refuse() {
+	# Refuse one record: emit ACTION|preserve-stage|<target-path>|REFUSED-WOULD-REGRESS on
+	# stdout, a `cleanup-worktrees: refused` diagnostic naming the reason on stderr, set
+	# PRESERVE_EXIT to 1, and return 1. A refusal is not a hard stop: the remaining records
+	# are still planned and the pass exits 1.
+	#
+	# Args: $1 = target_path, $2 = the reason, which begins with the failed guard's token.
+	printf 'ACTION|preserve-stage|%s|REFUSED-WOULD-REGRESS\n' "${1-}"
+	printf 'cleanup-worktrees: refused %s: %s\n' "${1-}" "${2-}" >&2
+	# Read by preserve_plan and run_preserve across a source boundary shellcheck does not
+	# follow, so SC2034 reports it unused here; the suppression is line-scoped.
+	# shellcheck disable=SC2034
+	PRESERVE_EXIT=1
+	return 1
+}
+
+preserve_merge_check_duplicate() {
+	# Refuse a record whose target_path an earlier record of the same pass already named. A
+	# target counts as seen as soon as a record reaches this check, whatever that record's
+	# later outcome, so the first record keeps the target and every later one is refused.
+	# The seen set is the newline-delimited global PRESERVE_SEEN_TARGETS, which preserve_plan
+	# resets at the start of every pass.
+	#
+	# Args: $1 = target_path. Returns 0 when the target is new, 1 when it was refused.
+	local tgt=${1-}
+	local seen=${PRESERVE_SEEN_TARGETS:-$'\n'}
+	if [[ $seen == *$'\n'"$tgt"$'\n'* ]]; then
+		preserve_merge_refuse "$tgt" "duplicate-target: an earlier record in this pass names the same target_path"
+		return 1
+	fi
+	PRESERVE_SEEN_TARGETS="$seen$tgt"$'\n'
+	return 0
+}
+
+preserve_merge_resolve_base() {
+	# Echo the blob id of the source file at the merge base of the worktree HEAD and the
+	# consolidation HEAD, or return 1 when no base is available. The base is unavailable
+	# when source_path differs from target_path (no git call is made in that case), when
+	# the worktree HEAD does not resolve, when the two HEADs have no merge base, or when the
+	# file is absent at the merge base. An empty answer from git counts as unavailable.
+	#
+	# Args: $1 = worktree path, $2 = source_path, $3 = target_path, $4 = consolidation path.
+	local wt=${1-} src=${2-} tgt=${3-} cwt=${4-} head="" mb="" oid=""
+	if [[ $src != "$tgt" ]]; then
+		return 1
+	fi
+	head=$(cleanup_wt_git -C "$wt" rev-parse --verify --quiet HEAD) || return 1
+	[[ -n $head ]] || return 1
+	mb=$(cleanup_wt_git -C "$cwt" merge-base "$head" HEAD) || return 1
+	[[ -n $mb ]] || return 1
+	oid=$(cleanup_wt_git -C "$cwt" rev-parse --verify --quiet "$mb:$src") || return 1
+	[[ -n $oid ]] || return 1
+	printf '%s\n' "$oid"
+}
+
+preserve_merge_guard_b() {
+	# Guard (b), the fallback when no merge base is available: admit a whole-file copy only
+	# when main's version is a line-subsequence of the source, so no main line is lost.
+	#
+	# Args: $1 = target_path, $2 = main content, $3 = source content.
+	if preserve_merge_is_subsequence "${2-}" "${3-}"; then
+		PRESERVE_STAGE_MODE="copy"
+		return 0
+	fi
+	preserve_merge_refuse "${1-}" "guard-b: the target holds lines the source lacks"
+	return 1
+}
+
+# PRESERVE_STAGE_MODE and PRESERVE_STAGE_OID are read by preserve_plan_one across a source
+# boundary shellcheck does not follow, so SC2034 reports them unused; the suppression is
+# scoped to this one function.
+# shellcheck disable=SC2034
+preserve_merge_decide() {
+	# Decide how one record is staged. Sets PRESERVE_STAGE_MODE to `copy` or `merge` and
+	# PRESERVE_STAGE_OID to the merged blob id (empty for `copy`), or refuses the record.
+	#
+	#   - target not a regular file: `copy`, with no git call at all;
+	#   - `untracked` record, or `modified` record with no merge base: guard (b);
+	#   - `modified` record with a merge base: G1 (the worktree change is insertion-only),
+	#     then a `git merge-file --union --object-id` merge, then G2 (every main line
+	#     survives) and G3 (no line beyond the worktree's own additions); `merge` on success.
+	#
+	# The source and target are read with plain file I/O. The base and merged contents are
+	# read from the object store with `cat-file blob`.
+	#
+	# Args: $1 = change_class, $2 = worktree path, $3 = source_path, $4 = target_path,
+	# $5 = consolidation path. Returns 0 when the record may be staged, 1 when it was refused.
+	local cls=${1-} wt=${2-} src=${3-} tgt=${4-} cwt=${5-}
+	PRESERVE_STAGE_MODE="copy"
+	PRESERVE_STAGE_OID=""
+	if [[ ! -f "$cwt/$tgt" ]]; then
+		return 0
+	fi
+	local main_c wt_c base_oid base_c main_oid wt_oid merged_oid merged_c mrc=0
+	main_c=$(<"$cwt/$tgt")
+	wt_c=$(<"$wt/$src")
+	if [[ $cls == "untracked" ]] || ! base_oid=$(preserve_merge_resolve_base "$wt" "$src" "$tgt" "$cwt"); then
+		preserve_merge_guard_b "$tgt" "$main_c" "$wt_c"
+		return
+	fi
+	base_c=$(cleanup_wt_git -C "$cwt" cat-file blob "$base_oid") ||
+		{ preserve_merge_refuse "$tgt" "G1: the base blob could not be read" || return 1; }
+	if ! preserve_merge_is_subsequence "$base_c" "$wt_c"; then
+		preserve_merge_refuse "$tgt" "G1: the worktree removed or changed a base line"
+		return 1
+	fi
+	main_oid=$(cleanup_wt_git -C "$cwt" hash-object -w --path="$tgt" -- "$tgt") || main_oid=""
+	wt_oid=$(cleanup_wt_git -C "$wt" hash-object -w --path="$tgt" -- "$src") || wt_oid=""
+	merged_oid=$(cleanup_wt_git -C "$cwt" merge-file --union --object-id "$main_oid" "$base_oid" "$wt_oid") || mrc=$?
+	if ((mrc != 0)) || [[ -z $main_oid || -z $wt_oid || -z $merged_oid ]]; then
+		preserve_merge_refuse "$tgt" "merge-file rc=$mrc: no merged blob was produced"
+		return 1
+	fi
+	merged_c=$(cleanup_wt_git -C "$cwt" cat-file blob "$merged_oid") ||
+		{ preserve_merge_refuse "$tgt" "G2: the merged blob could not be read" || return 1; }
+	if ! preserve_merge_is_subsequence "$main_c" "$merged_c"; then
+		preserve_merge_refuse "$tgt" "G2: the merged result lost a main line"
+		return 1
+	fi
+	if ! preserve_merge_extra_within "$merged_c" "$main_c" "$wt_c" "$base_c"; then
+		preserve_merge_refuse "$tgt" "G3: the merged result carries a line the worktree did not add"
+		return 1
+	fi
+	PRESERVE_STAGE_MODE="merge"
+	PRESERVE_STAGE_OID=$merged_oid
+	printf 'cleanup-worktrees: merged %s\n' "$tgt" >&2
+	return 0
+}