@mmerterden/multi-agent-pipeline 20.36.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);