@mmerterden/multi-agent-pipeline 20.37.0 → 20.37.1

package/pipeline/scripts/user-test-handoff.sh

@@ -0,0 +1,203 @@
+#!/usr/bin/env bash
+#
+# user-test-handoff.sh  -  hand a task branch from its worktree to the main
+# repository for a manual test, and hand it back.
+#
+# A branch can be checked out in one place only, so testing in the main repo
+# means removing the worktree first. That removal is where work gets lost: an
+# uncommitted change, a submodule's local branches and stashes (its git dir
+# lives inside the worktree's admin dir), and every ignored file (the run
+# artefacts under `.pipeline/` and `.multi-agent/`, logs, `.env`, build
+# output) live only in the worktree. This script refuses what it cannot carry
+# and carries the rest.
+#
+# It never commits. The caller makes the WIP commit itself first, so the
+# commit passes through the same approval and secret-scan hooks as any other.
+#
+#   checkout  check that the worktree and its submodules hold no uncommitted
+#             or unpushed work, move every ignored entry and the main repo's
+#             current branch into a hold under the git common dir, remove the
+#             worktree, check the branch out in the main repo.
+#   restore   put the main repo back on the branch it was on, re-add the
+#             worktree on the task branch, move the held entries back. Safe to
+#             run again after an interrupted checkout or restore.
+#
+# The hold sits in the same repository as the worktree, so moving even a large
+# ignored tree is a rename. Success is judged by where the branch ends up, not
+# by git's exit code: a failing post-checkout hook (git LFS, core.hooksPath)
+# makes `git checkout` and `git worktree add` exit non-zero after they did
+# their work. The hold is deleted only once every entry is back.
+#
+# Usage:
+#   user-test-handoff.sh checkout|restore --task <id> --worktree <path>
+#                        --root <main repo> --branch <task branch>
+#
+# Prints one JSON line on success. Exit codes:
+#   0  done
+#   1  usage error, or the worktree is not on the task branch
+#   3  the main repo has uncommitted changes to tracked files; nothing moved
+#   5  the worktree or a submodule has uncommitted, unpushed or stashed work;
+#      nothing moved
+#   6  checkout: a handoff is already held (run restore), or git refused and
+#      everything was put back (restore then answers 7). restore: the main repo
+#      could not leave the branch, or the worktree could not be re-added; the
+#      hold is kept and the message names the cause
+#   7  restore found nothing held for this task
+set -uo pipefail
+
+usage() {
+  echo "usage: user-test-handoff.sh checkout|restore --task <id> --worktree <path> --root <repo> --branch <name>" >&2
+  exit 1
+}
+
+MODE="${1:-}"
+[ $# -gt 0 ] && shift
+TASK="" WT="" ROOT="" BRANCH=""
+while [ $# -gt 0 ]; do
+  [ $# -ge 2 ] || usage
+  case "$1" in
+    --task) TASK="$2" ;;
+    --worktree) WT="$2" ;;
+    --root) ROOT="$2" ;;
+    --branch) BRANCH="$2" ;;
+    *) echo "user-test-handoff: unknown argument $1" >&2; usage ;;
+  esac
+  shift 2
+done
+case "$MODE" in checkout | restore) ;; *) usage ;; esac
+[ -n "$TASK" ] && [ -n "$WT" ] && [ -n "$ROOT" ] && [ -n "$BRANCH" ] || usage
+case "$TASK" in */* | *..* | .* | *'"'* | *\\*) echo "user-test-handoff: task id must be a plain name" >&2; exit 1 ;; esac
+
+ROOT="$(cd "$ROOT" 2>/dev/null && pwd)" || { echo "user-test-handoff: --root is not a directory" >&2; exit 1; }
+case "$WT" in /*) ;; *) WT="$ROOT/$WT" ;; esac
+COMMON="$(git -C "$ROOT" rev-parse --path-format=absolute --git-common-dir 2>/dev/null)" ||
+  { echo "user-test-handoff: --root is not a git repository" >&2; exit 1; }
+HOLD="$COMMON/multi-agent-user-test/$TASK"
+
+esc() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; }
+json() { printf '{"status":"%s","task":"%s","branch":"%s","previous":"%s"}\n' "$1" "$(esc "$TASK")" "$(esc "$BRANCH")" "$(esc "$2")"; }
+
+on_branch() { [ "$(git -C "$1" branch --show-current 2>/dev/null)" = "$2" ]; }
+
+root_dirty() { [ -n "$(git -C "$ROOT" status --porcelain --untracked-files=no 2>/dev/null)" ]; }
+
+# Every ignored entry of the worktree, directories collapsed, NUL-separated.
+ignored_entries() { git -C "$WT" ls-files --others --ignored --exclude-standard --directory -z 2>/dev/null; }
+
+# Move the listed entries (NUL-separated file $3) from tree $1 to tree $2.
+move_entries() {
+  local from="$1" to="$2" list="$3" e rc=0
+  while IFS= read -r -d '' e; do
+    e="${e%/}"
+    [ -n "$e" ] && [ -e "$from/$e" ] || continue
+    mkdir -p "$to/$(dirname "$e")" && rm -rf "${to:?}/$e" && mv "$from/$e" "$to/$e" || rc=1
+  done <"$list"
+  return "$rc"
+}
+
+return_entries() {
+  [ -f "$HOLD/entries" ] || : >"$HOLD/entries"
+  if move_entries "$HOLD/tree" "$WT" "$HOLD/entries"; then
+    rm -rf "$HOLD"
+  else
+    echo "user-test-handoff: some held entries are still under $HOLD/tree" >&2
+  fi
+}
+
+submodule_problems() {
+  # shellcheck disable=SC2016  # submodule foreach expands $displaypath itself
+  git -C "$WT" submodule foreach --quiet --recursive '
+    if [ -n "$(git status --porcelain)" ]; then echo "$displaypath (uncommitted changes)"
+    elif ! git branch -r --contains HEAD 2>/dev/null | grep -q .; then echo "$displaypath (HEAD on no remote branch; push it, or add a remote if there is none)"
+    elif [ -n "$(git rev-list -n1 --branches --not --remotes 2>/dev/null)" ]; then echo "$displaypath (a local branch has unpushed commits)"
+    elif [ -n "$(git stash list 2>/dev/null)" ]; then echo "$displaypath (has stashes)"
+    fi' 2>/dev/null
+}
+
+checkout() {
+  on_branch "$WT" "$BRANCH" || { echo "user-test-handoff: $WT is not a worktree on $BRANCH" >&2; exit 1; }
+  if [ -e "$HOLD" ]; then
+    echo "user-test-handoff: a handoff for $TASK is already held; run restore first" >&2
+    exit 6
+  fi
+  if root_dirty; then
+    echo "user-test-handoff: the main repo has uncommitted changes; commit or stash them, then retry" >&2
+    git -C "$ROOT" status --short --untracked-files=no >&2
+    exit 3
+  fi
+  local problems
+  problems="$(submodule_problems)"
+  if [ -n "$problems" ]; then
+    printf 'user-test-handoff: these submodules hold work the removal would lose:\n%s\n' "$problems" >&2
+    exit 5
+  fi
+  if [ -n "$(git -C "$WT" status --porcelain)" ]; then
+    echo "user-test-handoff: the worktree has uncommitted changes; make the WIP commit first" >&2
+    git -C "$WT" status --short >&2
+    exit 5
+  fi
+  local previous
+  previous="$(git -C "$ROOT" symbolic-ref --short -q HEAD || git -C "$ROOT" rev-parse HEAD)"
+  mkdir -p "$HOLD/tree" || exit 6
+  printf '%s\n' "$previous" >"$HOLD/previous" || exit 6
+  ignored_entries >"$HOLD/entries" || exit 6
+  if ! move_entries "$WT" "$HOLD/tree" "$HOLD/entries"; then
+    return_entries
+    exit 6
+  fi
+  if ! git -C "$ROOT" worktree remove --force "$WT"; then
+    return_entries
+    exit 6
+  fi
+  git -C "$ROOT" checkout -q "$BRANCH" || true
+  if ! on_branch "$ROOT" "$BRANCH"; then
+    git -C "$ROOT" worktree add -q "$WT" "$BRANCH" || true
+    on_branch "$WT" "$BRANCH" && return_entries
+    echo "user-test-handoff: the main repo could not check out $BRANCH" >&2
+    exit 6
+  fi
+  json checked-out "$previous"
+}
+
+restore() {
+  [ -f "$HOLD/previous" ] || { echo "user-test-handoff: nothing is held for $TASK" >&2; exit 7; }
+  local previous
+  previous="$(cat "$HOLD/previous")"
+  if on_branch "$ROOT" "$BRANCH"; then
+    if root_dirty; then
+      echo "user-test-handoff: the main repo has uncommitted changes on $BRANCH; stash them (git stash), restore, then git stash pop in the worktree" >&2
+      git -C "$ROOT" status --short --untracked-files=no >&2
+      exit 3
+    fi
+    if [ -n "$previous" ] && [ "$previous" != "$BRANCH" ]; then
+      git -C "$ROOT" checkout -q "$previous" || true
+    else
+      git -C "$ROOT" checkout -q --detach || true
+    fi
+    if on_branch "$ROOT" "$BRANCH"; then
+      echo "user-test-handoff: the main repo could not leave $BRANCH for $previous (an untracked file in the way?); move it and run restore again" >&2
+      exit 6
+    fi
+  fi
+  if ! on_branch "$WT" "$BRANCH"; then
+    git -C "$ROOT" worktree unlock "$WT" 2>/dev/null || true
+    git -C "$ROOT" worktree prune
+    if [ -e "$WT" ]; then
+      if ! { mkdir -p "$HOLD/leftover" && mv "$WT" "$HOLD/leftover/$(date +%s)"; }; then
+        echo "user-test-handoff: $WT exists and is not a worktree; move it and run restore again" >&2
+        exit 6
+      fi
+    fi
+    git -C "$ROOT" worktree add -q "$WT" "$BRANCH" || true
+    on_branch "$WT" "$BRANCH" || { echo "user-test-handoff: the worktree could not be re-added on $BRANCH" >&2; exit 6; }
+  fi
+  if [ -d "$HOLD/leftover" ]; then
+    mkdir -p "$COMMON/multi-agent-user-test-leftover" &&
+      mv "$HOLD/leftover" "$COMMON/multi-agent-user-test-leftover/$TASK-$(date +%s)" &&
+      echo "user-test-handoff: files found at the worktree path were kept under $COMMON/multi-agent-user-test-leftover" >&2
+  fi
+  return_entries
+  json restored "$previous"
+}
+
+"$MODE"

package/pipeline/scripts/validate-planning.mjs

@@ -12,8 +12,10 @@
 //   cat plan.json | node validate-planning.mjs - [--spec <path>]
 //
 // --spec names the analysis document or task text the plan was written from.
-// A plan more than SPEC_RATIO times its length gets a warning: a plan should
-// record decisions, and one far longer than its spec is usually a transcript.
+// A named spec that cannot be read is an error, because the design checks
+// below would otherwise be skipped without a trace. A plan more than
+// SPEC_RATIO times its length gets a warning: a plan should record decisions,
+// and one far longer than its spec is usually a transcript.
 //
 // Exit codes:
 //   0  -  valid
@@ -326,7 +328,7 @@ async function main() {
       specText = readFileSync(spec, "utf-8");
       specChars = specText.length;
     } catch {
-      warnings.push(`spec not readable: ${spec}`);
+      errors.push(`spec not readable: ${spec}`);
     }
     // With a design behind the plan, values come from its tokens, never from a
     // number someone read off a screenshot.

package/pipeline/scripts/validate-triage.mjs

@@ -27,6 +27,7 @@
 //   0  -  valid, safe to act on
 //   1  -  invalid structure or required-field violation  -  caller MUST retry or fallback
 //   2  -  over-rejection guard tripped  -  caller MUST pause for human (or log+accept in autopilot)
+//        (takes precedence over 3; `corrected` is still set when a contradiction was fixed)
 //   3  -  contradiction auto-corrected  -  caller MAY proceed with corrected output
 //
 // Output: JSON result to stdout with shape:
@@ -427,7 +428,7 @@ function validate(raw) {
       warnings.push(
         `over-rejection guard: ${parsed.rejected.length}/${total} rejected (${(ratio * 100).toFixed(0)}%)  -  caller must pause for human confirm (triage=high-rejection-rate); autopilot may accept and log`,
       );
-      triageCode = Math.max(triageCode, 2);
+      triageCode = 2;
     }
   }
 

package/pipeline/scripts/write-state.mjs

@@ -390,7 +390,8 @@ export function completionRefusal(next, payload, replace, diskStatus) {
  *   background launches approve nothing by design, and in analysis mode
  *   Phase 1 is not a plan, so neither is asked.
  * - A `sessionId` already set is the run's identity for resume; a write that
- *   changes it detaches the run from the session that started it.
+ *   changes it detaches the run from the session that started it. A replace
+ *   document is the whole record, so leaving the field out also changes it.
  * - Phase 2 to a later phase in an attended run with a tracked issue (jiraId
  *   or githubIssue) needs `phases["2"].trackerStatus` verified, declined or
  *   not-tracked: the issue moves to In Progress before any code, and a failed
@@ -399,15 +400,16 @@ export function completionRefusal(next, payload, replace, diskStatus) {
  * @param {object} next     the document as it would be written
  * @param {unknown} payload the patch as sent
  * @param {object} current  the document on disk
+ * @param {{replace?: boolean}} [opts]
  * @returns {string|null}
  */
-export function transitionRefusal(next, payload, current) {
+export function transitionRefusal(next, payload, current, { replace = false } = {}) {
   const patch = payload && typeof payload === "object" ? payload : {};
   const was = current && typeof current === "object" ? current : {};
   if (
     typeof was.sessionId === "string" &&
     was.sessionId &&
-    Object.hasOwn(patch, "sessionId") &&
+    (replace || Object.hasOwn(patch, "sessionId")) &&
     next.sessionId !== was.sessionId
   ) {
     return `write-state: refusing to change sessionId from "${was.sessionId}". It identifies the run for resume; nothing was written.`;
@@ -531,6 +533,13 @@ async function main() {
     let current = {};
     if (replace) {
       next = payload;
+      if (existsSync(path)) {
+        try {
+          current = JSON.parse(readFileSync(path, "utf-8"));
+        } catch {
+          current = {};
+        }
+      }
     } else {
       if (existsSync(path)) {
         try {
@@ -597,7 +606,7 @@ async function main() {
 
     const refusal =
       completionRefusal(next, payload, replace, diskStatus) ||
-      transitionRefusal(next, payload, current);
+      transitionRefusal(next, payload, current, { replace });
     if (refusal) {
       console.error(refusal);
       releaseLock(path);

package/pipeline/skills/.skill-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-10-31T15:40:00Z",
+  "generatedAt": "2026-10-31T20:07:26Z",
   "skillCount": 238,
   "entries": [
     {
@@ -121,7 +121,7 @@
     },
     {
       "path": "shared/core/multi-agent-manual-test/SKILL.md",
-      "sha256": "a4e78cde61e1b63b6a2643f08deeb577bfe7129428832e4238a4c5dcc129c725"
+      "sha256": "8ea107eebf8160ec30306a18c619f10b3a4cf9ddbd741d37c52f09a534e2c687"
     },
     {
       "path": "shared/core/multi-agent-model/SKILL.md",

package/pipeline/skills/shared/core/multi-agent-manual-test/SKILL.md

@@ -20,12 +20,13 @@ Lets you switch to the task branch for manual testing in Xcode before the PR is
 2. **Check the state**  -  the task must have completed Phase 2 (Dev) or later
    - Phase < 2 → "No code has been written yet, run `resume #N` first"
 
-3. **Remove the worktree and switch to the branch**:
+3. **Hand the branch over**. Make the WIP commit yourself (Standard path item 3 of Phase 4 Step 2 folds it back), then let the script hold the run artefacts and the project root's current branch, remove the worktree and check the branch out. `{worktree-path}` and `{jiraId}` come from the task's state (`worktreePath`, `jiraId`):
    ```bash
-   cd {project-root}
-   git worktree remove .worktrees/PROJ-{id} 2>/dev/null
-   git checkout {branch-name}
+   git -C "{worktree-path}" add -A
+   git -C "{worktree-path}" diff --cached --quiet || git -C "{worktree-path}" commit -m "WIP: {jiraId}  -  changes for user test"
+   bash $HOME/.claude/scripts/user-test-handoff.sh checkout --task "{jiraId}" --worktree "{worktree-path}" --root "{project-root}" --branch "{branch-name}"
    ```
+   A refused commit stops here with nothing moved. Script exits: 3 the project root has uncommitted changes; 5 the worktree or a submodule holds uncommitted, unpushed or stashed work (a submodule with no remote needs one added); both move nothing. 6 a handoff is already held, or git refused part way: run `restore` below (if it answers 7, nothing had moved). 1 the worktree is not on the branch.
 
 4. **Give test instructions**:
    ```
@@ -41,7 +42,11 @@ Lets you switch to the task branch for manual testing in Xcode before the PR is
      ❌ "fix: ..." → the worktree is recreated and the fix is applied
    ```
 
-5. **Wait for the user's response**
+5. **Wait for the user's response**, then hand the branch back before acting on it:
+   ```bash
+   bash $HOME/.claude/scripts/user-test-handoff.sh restore --task "{jiraId}" --worktree "{worktree-path}" --root "{project-root}" --branch "{branch-name}"
+   ```
+   Exit 3: the user edited files on the branch in the project root. Ask them to `git stash`, run `restore` again, then `git -C "{worktree-path}" stash pop`; a commit made there instead would stop Phase 4 from folding the checkpoints. Exit 6: the project root could not leave the branch (an untracked file in the way) or the worktree could not be re-added; the message names the cause, the hold is kept, and `restore` runs again once it is cleared. Exit 7: nothing was held, so the worktree was never removed.
 
 6. **Based on the result**:
    - **OK** → an "ok" is a claim, and the pass has to be substantiated before it is recorded. First write `$WORKTREE/.pipeline/manual-test.json`, one entry per acceptance criterion taken from the analysis doc test plan, the plan tasks, or the user's own words:
@@ -53,5 +58,5 @@ Lets you switch to the task branch for manual testing in Xcode before the PR is
      node $HOME/.claude/scripts/evidence-gate.mjs --claim manual --status passed \
        --evidence "$WORKTREE/.pipeline/manual-test.json"
      ```
-     Exit 1 means the "ok" is not accepted: name the criterion that lacks evidence and wait for the next reply. Exit 0 → recreate the worktree, proceed to Phase 4. Full contract: `$HOME/.claude/multi-agent-refs/phases/phase-3-review.md` step 5.
-   - **Fix needed** → recreate the worktree, apply the fix
+     Exit 1 means the "ok" is not accepted: name the criterion that lacks evidence and wait for the next reply. Exit 0 → proceed to Phase 4. Full contract: `$HOME/.claude/multi-agent-refs/phases/phase-3-review.md` step 5.
+   - **Fix needed** → apply the fix in the restored worktree