@mmerterden/multi-agent-pipeline 20.23.1 → 20.24.0

package/pipeline/commands/multi-agent/setup/SKILL.md

@@ -431,7 +431,7 @@ All tokens are optional in the sense that every service can be answered with Ski
 
 ### Step 8  -  Enforcement hooks (optional, Claude Code)
 
-Offer to merge `$HOME/.claude/templates/claude-hooks.json`: three `PreToolUse` gates that block on a non-zero exit (secret scan, agent-guard, read-size) plus three capture hooks that block nothing (`PreCompact`, `SessionEnd`, `SessionStart`). What each does: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
+Offer to merge `$HOME/.claude/templates/claude-hooks.json`: three `PreToolUse` gates that block on a non-zero exit (secret scan, agent-guard, read-size) plus four hooks that block nothing (`PreCompact`, `SessionEnd`, `SessionStart`, `PostToolUse`). What each does: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
 
 - Ask (picker): "Install the pipeline's hooks into `~/.claude/settings.json`?" Default Yes.
 - On Yes, deep-merge EVERY event in the template's `hooks` object, not `PreToolUse` alone - merging one event silently drops the capture hooks, and a run killed before Phase 5 then loses its findings exactly as it did before they existed. Preserve existing hooks; never duplicate a matcher already calling the same script.

package/pipeline/commands/multi-agent/sync/SKILL.md

@@ -73,7 +73,7 @@ Run every step automatically:
 ```
 Step 0: DOCTOR      doctor.mjs  -  exit 2 or 4 stops the sync
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 64 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 65 sub-command skills)
 Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + sub-command specs as refs + agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
@@ -241,14 +241,14 @@ same specs as reference files rather than as peer skills, via Step 2b -  see
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**64 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**65 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off, autopilot-on,
 autopilot-status, bug-bash, build-optimize, channels, complaint-analysis, create-jira,
 design-check, diff-explain, doctor, estimate, feedback, forget, garbage-collect, graph, help,
 ios-coding-standard, issue, jira, kill, language, log,
-manual-test, model, prune-logs, prune-prompts, purge, refactor, research, resume, review, review-analysis, review-issue, review-jira, route-off, route-on, route-status,
+manual-test, model, postmortem, prune-logs, prune-prompts, purge, refactor, research, resume, review, review-analysis, review-issue, review-jira, route-off, route-on, route-status,
 routines, save, scaffold, scan, scenario-audit, search, security-review, serve, setup, stack, status, steer, store-ready, sync, test,
 test-accessibility, test-dark-mode, test-dynamic-type, test-screenshots,
 testflight-validation, uninstall, update

package/pipeline/lib/analysis-jira-write.sh

@@ -34,8 +34,16 @@
 # Jira has no backup path for fields other than description. Rewriting a body an
 # engineer has since edited would lose that edit with no way back.
 #
+# A STORY DEPENDENCY IS A LINK, WRITTEN LAST
+#
+# A plan node's `dependsOn` names the stories it waits for. Once every story has
+# a key, each edge becomes an issue link of `prefsUsed.dependencyLinkType`
+# (default Blocks) from the prerequisite to the dependent, checked before it is
+# sent so a re-run adds none.
+#
 # Usage:
 #   analysis-jira-write.sh --plan plan.json --project KEY [--dry-run] [--ledger FILE] [--epic KEY]
+#   analysis-jira-write.sh --subtask-types --project KEY   the site's sub-task type names, one per line
 #
 # Exit: 0 written (or previewed), 3 the plan does not parse, 4 auth, 5 a Jira
 #       call failed, 64 usage.
@@ -46,7 +54,7 @@ SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 . "$SELF_DIR/_jira-auth.sh"
 
-PLAN=""; PROJECT=""; DRY=0; LEDGER=""; EPIC=""
+PLAN=""; PROJECT=""; DRY=0; LEDGER=""; EPIC=""; LIST_TYPES=0
 while [ $# -gt 0 ]; do
   case "$1" in
     --plan) PLAN="${2:-}"; shift 2 ;;
@@ -54,13 +62,44 @@ while [ $# -gt 0 ]; do
     --ledger) LEDGER="${2:-}"; shift 2 ;;
     --dry-run) DRY=1; shift ;;
     --epic) EPIC="${2:-}"; shift 2 ;;
-    *) echo "usage: analysis-jira-write.sh --plan FILE --project KEY [--dry-run] [--ledger FILE] [--epic KEY]" >&2; exit 64 ;;
+    --subtask-types) LIST_TYPES=1; shift ;;
+    *) echo "usage: analysis-jira-write.sh --plan FILE --project KEY [--dry-run] [--ledger FILE] [--epic KEY] | --subtask-types --project KEY" >&2; exit 64 ;;
   esac
 done
-[ -n "$PLAN" ] && [ -f "$PLAN" ] || { echo "ERR: --plan FILE is required and must exist" >&2; exit 64; }
 [ -n "$PROJECT" ] || { echo "ERR: --project KEY is required" >&2; exit 64; }
+if [ "$LIST_TYPES" -eq 0 ] && { [ -z "$PLAN" ] || [ ! -f "$PLAN" ]; }; then
+  echo "ERR: --plan FILE is required and must exist" >&2; exit 64
+fi
 
 command -v jq >/dev/null 2>&1 || { echo "ERR: jq is required" >&2; exit 3; }
+
+# Discover rather than assume: the types this site marks subtask:true, under
+# whatever names it gave them. Jira Data Center 9 answers only the per-project
+# createmeta; older sites answer only the classic one. Read once per run.
+SITE_SUBTASK_TYPES=""
+SITE_SUBTASK_READ=0
+site_subtask_types() {
+  SITE_SUBTASK_READ=1
+  SITE_SUBTASK_TYPES="$(jira_api GET "/rest/api/2/issue/createmeta/${PROJECT}/issuetypes?maxResults=100" 2>/dev/null \
+    | jq -r '.values[]? | select(.subtask == true) | .name' 2>/dev/null || echo "")"
+  [ -n "$SITE_SUBTASK_TYPES" ] || SITE_SUBTASK_TYPES="$(jira_api GET \
+    "/rest/api/2/issue/createmeta?projectKeys=${PROJECT}&expand=projects.issuetypes" 2>/dev/null \
+    | jq -r '.projects[]?.issuetypes[]? | select(.subtask == true) | .name' 2>/dev/null || echo "")"
+  local n
+  n="$(printf '%s' "$SITE_SUBTASK_TYPES" | grep -c . || true)"
+  if [ "${n:-0}" -gt 1 ]; then
+    echo "  note      ${PROJECT} has ${n} sub-task types ($(printf '%s' "$SITE_SUBTASK_TYPES" | paste -sd, - | sed 's/,/, /g')); using the first. Set issueTree.subtaskIssueType to a name, or to a {role: type} map, to choose." >&2
+  fi
+}
+
+if [ "$LIST_TYPES" -eq 1 ]; then
+  jira_auth_resolve || exit 4
+  site_subtask_types 2>/dev/null
+  [ -n "$SITE_SUBTASK_TYPES" ] || { echo "ERR: ${PROJECT} answered no sub-task types" >&2; exit 5; }
+  printf '%s\n' "$SITE_SUBTASK_TYPES"
+  exit 0
+fi
+
 jq -e . "$PLAN" >/dev/null 2>&1 || { echo "ERR: the plan does not parse as JSON: $PLAN" >&2; exit 3; }
 
 DOC_ID="$(jq -r '.document.id // "unidentified"' "$PLAN")"
@@ -170,6 +209,40 @@ link_issues() {  # link_issues <type> <fromKey> <toKey> <cloneLabel>
   echo "  linked  $from <-> $to"
 }
 
+# A dependency link: the prerequisite is the link's source (the POST's
+# inwardIssue), so the site reads "<prerequisite> blocks <dependent>" for the
+# default Blocks type, and lists the link on the prerequisite under outwardIssue.
+# Only a link of this type in this direction counts as already there: a Relates
+# link a person added between the same two stories is not the dependency.
+link_dependency() {  # link_dependency <type> <prerequisiteKey> <dependentKey> <dependentLabel>
+  local ltype="$1" pre="$2" dep="$3" label="$4" linked
+  linked="$(jira_api GET "/rest/api/2/issue/${pre}?fields=issuelinks" 2>/dev/null \
+    | jq -r --arg t "$ltype" --arg d "$dep" \
+      '[.fields.issuelinks[]? | select(.type.name == $t and .outwardIssue.key == $d)] | length > 0' \
+      2>/dev/null || echo false)"
+  if [ "$linked" = "true" ]; then
+    echo "  linked  $pre -> $dep  ($ltype)"
+    return 0
+  fi
+  if ! printf '%s' "$(jq -cn --arg t "$ltype" --arg a "$pre" --arg b "$dep" \
+      '{type: {name: $t}, inwardIssue: {key: $a}, outwardIssue: {key: $b}}')" \
+      | jira_api POST "/rest/api/2/issueLink" --data @- >/dev/null; then
+    echo "ERR: could not link $pre to $dep" >&2
+    return 5
+  fi
+  ledger dependency "$label" "$pre"
+  echo "  linked  $pre -> $dep  ($ltype)"
+}
+
+declare -a STORY_KEYS=()
+story_key() {  # story_key <label> -> prints the key this run created or found, or empty
+  local i
+  for i in "${STORY_KEYS[@]:-}"; do
+    case "$i" in "$1="*) printf '%s' "${i#*=}"; return 0 ;; esac
+  done
+  printf ''
+}
+
 CREATED_KEY=""
 create_issue() {  # create_issue <label> <summary> <issuetype> <parentKey|""> <description> [extraFieldsJson]
   local label="$1" summary="$2" itype="$3" parent="$4" desc="$5" extra="${6:-}" body key existing
@@ -239,25 +312,6 @@ if [ -n "${EPIC:-}" ]; then
   fi
 fi
 
-# Discover rather than assume: the types this site marks subtask:true, under
-# whatever names it gave them. Jira Data Center 9 answers only the per-project
-# createmeta; older sites answer only the classic one. Read once per run.
-SITE_SUBTASK_TYPES=""
-SITE_SUBTASK_READ=0
-site_subtask_types() {
-  SITE_SUBTASK_READ=1
-  SITE_SUBTASK_TYPES="$(jira_api GET "/rest/api/2/issue/createmeta/${PROJECT}/issuetypes?maxResults=100" 2>/dev/null \
-    | jq -r '.values[]? | select(.subtask == true) | .name' 2>/dev/null || echo "")"
-  [ -n "$SITE_SUBTASK_TYPES" ] || SITE_SUBTASK_TYPES="$(jira_api GET \
-    "/rest/api/2/issue/createmeta?projectKeys=${PROJECT}&expand=projects.issuetypes" 2>/dev/null \
-    | jq -r '.projects[]?.issuetypes[]? | select(.subtask == true) | .name' 2>/dev/null || echo "")"
-  local n
-  n="$(printf '%s' "$SITE_SUBTASK_TYPES" | grep -c . || true)"
-  if [ "${n:-0}" -gt 1 ]; then
-    echo "  note      ${PROJECT} has ${n} sub-task types ($(printf '%s' "$SITE_SUBTASK_TYPES" | paste -sd, - | sed 's/,/, /g')); using the first. Set issueTree.subtaskIssueType to a name, or to a {role: type} map, to choose." >&2
-  fi
-}
-
 RC=0
 NODES="$(jq -c '.nodes[]' "$PLAN")"
 while IFS= read -r node; do
@@ -277,6 +331,7 @@ while IFS= read -r node; do
     continue
   fi
   skey="$CREATED_KEY"
+  [ -n "$skey" ] && STORY_KEYS+=("$s_label=$skey")
   LINK_TYPE="$(jq -r '.prefsUsed.cloneLinkType // "Relates"' "$PLAN")"
   while IFS= read -r clone; do
     [ -n "$clone" ] || continue
@@ -306,4 +361,32 @@ while IFS= read -r node; do
   done < <(printf '%s' "$node" | jq -c '.subtasks[]?')
 done <<< "$NODES"
 
+# Dependencies, once every story has a key. An edge inside a strongly connected
+# component (`onCycle`, set by the planner from task-graph.mjs) is not linked:
+# a cycle has no order to record, and the plan already reported it.
+DEP_TYPE="$(jq -r '.prefsUsed.dependencyLinkType // "Blocks"' "$PLAN")"
+EDGES="$(jq -r '(.nodes | map({(.label): .title}) | add // {}) as $t
+  | .dependencies.edges[]? | .prerequisite as $p | .dependent as $d
+  | [$p, $d, $t[$p], $t[$d], (if .onCycle == true then "cycle" else "" end)]
+  | map(. // "" | tostring | gsub("[\n\r\u001f]"; " "))
+  | join("\u001f")' "$PLAN")"
+# \x1f, unlike a tab, is not IFS whitespace, so an empty field stays a field.
+while IFS=$'\x1f' read -r p_label d_label p_title d_title on_cycle; do
+  [ -n "$p_label" ] || continue
+  if [ "$on_cycle" = "cycle" ]; then
+    echo "  skipped   link $p_label ($p_title) -> $d_label ($d_title): the two stories are on a dependency cycle"
+    continue
+  fi
+  if [ "$DRY" -eq 1 ]; then
+    echo "  link    $DEP_TYPE  $p_label ($p_title) -> $d_label ($d_title)  (prerequisite -> dependent)"
+    continue
+  fi
+  p_key="$(story_key "$p_label")"; d_key="$(story_key "$d_label")"
+  if [ -z "$p_key" ] || [ -z "$d_key" ]; then
+    echo "  skipped   link $p_label ($p_title) -> $d_label ($d_title): one of the stories was not created" >&2
+    continue
+  fi
+  link_dependency "$DEP_TYPE" "$p_key" "$d_key" "$d_label" || RC=5
+done <<< "$EDGES"
+
 exit "$RC"

package/pipeline/lib/decisions.mjs

@@ -0,0 +1,130 @@
+/**
+ * decisions.mjs  -  the record of what an autopilot run decided in place of a
+ * person, and its rendering.
+ *
+ * An attended run asks: a picker, a park, a waived finding, a model change are
+ * each a question with an answer someone gave. An autopilot run answers them
+ * itself. `state.decisions[]` holds one entry per such answer, so the person
+ * who reads the PR or the Phase 5 report sees every place the run chose for
+ * them, why, and what it costs if the choice was wrong:
+ *
+ *   { what, why, costIfWrong, at, phase }
+ *
+ * The entries are written from text the run composed (gate reasons, finding
+ * locations, picker labels), so every field is passed through redact.mjs
+ * before it is capped, and the rendered section again before it reaches any
+ * outward text. The caller still runs the
+ * outbound gate over the whole body it publishes; redaction here only keeps a
+ * decision's wording from being the reason a publish is refused.
+ *
+ * Pure functions; the writers that hold the state lock are gate-ledger.mjs
+ * (park) and scripts/decisions-log.mjs (everything else).
+ *
+ * @module pipeline/lib/decisions
+ */
+
+import { redact } from "./redact.mjs";
+
+export const DECISIONS_HEADING = "## Decisions made on your behalf";
+
+const FIELD_MAX = { what: 200, why: 500, costIfWrong: 300 };
+const MIN_PHASE = 0;
+const MAX_PHASE = 5;
+// Room for the heading's blank line and one "... N more" line.
+const MIN_ROOM = 48;
+
+/**
+ * `value` on one line, redacted, then capped at `max`. Redaction comes first:
+ * a token cut at the boundary is too short for its rule to recognise, and its
+ * prefix would survive.
+ */
+function oneLine(value, max) {
+  const text = redact(
+    String(value ?? "")
+      .replace(/\s+/g, " ")
+      .trim(),
+  );
+  return text.length > max ? `${text.slice(0, max - 3)}...` : text;
+}
+
+/**
+ * A validated entry. Throws when a field is missing: an entry that cannot say
+ * what was decided, why, or what being wrong costs is not worth showing.
+ *
+ * @param {{what: string, why: string, costIfWrong: string, phase: number, at?: string}} input
+ * @returns {{what: string, why: string, costIfWrong: string, at: string, phase: number}}
+ */
+export function decisionEntry({ what, why, costIfWrong, phase, at } = {}) {
+  const out = {
+    what: oneLine(what, FIELD_MAX.what),
+    why: oneLine(why, FIELD_MAX.why),
+    costIfWrong: oneLine(costIfWrong, FIELD_MAX.costIfWrong),
+  };
+  for (const [k, v] of Object.entries(out)) {
+    if (!v) throw new Error(`a decision needs a non-empty ${k}`);
+  }
+  const n = Number(phase);
+  if (!Number.isInteger(n) || n < MIN_PHASE || n > MAX_PHASE) {
+    throw new Error(`a decision needs a phase between ${MIN_PHASE} and ${MAX_PHASE}`);
+  }
+  const stamp = typeof at === "string" && !Number.isNaN(Date.parse(at)) ? at : null;
+  return { ...out, at: stamp || new Date().toISOString(), phase: n };
+}
+
+/** The state with `entry` appended to `decisions[]`; `state` is not changed. */
+export function withDecision(state, entry) {
+  const list = Array.isArray(state?.decisions) ? state.decisions : [];
+  return { ...state, decisions: [...list, entry] };
+}
+
+function line(d) {
+  const phase = Number.isInteger(d?.phase) ? `Phase ${d.phase}` : "Phase ?";
+  return redact(
+    `- **${phase}** - ${oneLine(d?.what, FIELD_MAX.what)}. Why: ${oneLine(d?.why, FIELD_MAX.why)}. If wrong: ${oneLine(d?.costIfWrong, FIELD_MAX.costIfWrong)}.`,
+  );
+}
+
+/**
+ * The markdown section, or "" for an empty list: a run that decided nothing
+ * for anyone adds nothing to the report.
+ *
+ * @param {object[]|undefined} decisions
+ * @param {{maxChars?: number}} [opts]  trim to this many characters, oldest first kept
+ */
+export function renderDecisions(decisions, { maxChars = Infinity } = {}) {
+  const list = Array.isArray(decisions) ? decisions.filter((d) => d && typeof d === "object") : [];
+  if (!list.length) return "";
+  const head = `${DECISIONS_HEADING}\n\n`;
+  const lines = [];
+  let size = head.length;
+  for (let i = 0; i < list.length; i++) {
+    const l = `${line(list[i])}\n`;
+    const rest = list.length - i - 1;
+    const tail = rest ? `- ... ${rest + 1} more in the run report\n`.length : 0;
+    if (size + l.length + tail > maxChars) {
+      lines.push(`- ... ${list.length - i} more in the run report\n`);
+      break;
+    }
+    lines.push(l);
+    size += l.length;
+  }
+  return head + lines.join("");
+}
+
+/**
+ * `body` with the decisions section appended, once. A body that already holds
+ * the heading is returned unchanged; `maxChars` bounds the whole result.
+ *
+ * @param {string} body
+ * @param {object[]|undefined} decisions
+ * @param {{maxChars?: number}} [opts]
+ */
+export function appendDecisionsSection(body, decisions, { maxChars = Infinity } = {}) {
+  const text = typeof body === "string" ? body : "";
+  if (text.includes(DECISIONS_HEADING)) return text;
+  const sep = text.endsWith("\n") ? "\n" : "\n\n";
+  const room = maxChars - text.length - sep.length;
+  const section = renderDecisions(decisions, { maxChars: room });
+  if (!section || room < DECISIONS_HEADING.length + MIN_ROOM) return text;
+  return `${text}${sep}${section}`;
+}

package/pipeline/lib/plan-todos.sh

@@ -14,10 +14,23 @@
 #   init      <task-id> [title]            Initialize with empty todos[] (Phase 2 usually pipes the JSON instead)
 #   set       <task-id> <plan-json>        Replace the whole plan from a JSON blob on stdin or arg
 #   start     <task-id> <todo-id>          Mark in_progress, set startedAt; refuses if deps unsatisfied
-#   complete  <task-id> <todo-id> [notes]  Mark completed, set completedAt
+#                                          or the todo awaits re-plan confirmation
+#   complete  <task-id> <todo-id> [notes] [--no-tests <reason>]
+#                                          Mark completed, set completedAt; refuses what start refuses
+#                                          (unsatisfied deps on a pending todo, re-plan unconfirmed); checks TDD evidence per
+#                                          prefs.global.tddEvidence.mode (off | warn | enforce, default warn)
+#   tdd-red   <task-id> <todo-id> <results> [--tests a,b] [--already-passing <reason>]
+#                                          Record the RED run (a named test fails) from JUnit XML / xcresult / log
+#                                          (under enforce, --tests needs results that name failing tests)
+#   tdd-green <task-id> <todo-id> <results> Record the GREEN run (no failures, RED's tests among them)
 #   fail      <task-id> <todo-id> <reason> Mark failed
 #   skip      <task-id> <todo-id> <reason> Mark skipped (counts as satisfied for dependents)
-#   next      <task-id>                    Print next pending todo (deps-respecting); empty if none
+#   next      <task-id>                    Print the next ready todo (deps-respecting, ranked by what it unblocks); empty if none, blocked todos named on stderr
+#   drift     <task-id> <todo-id> [--files <path|->] [--not-done N] [--reason <text>]
+#                                          The todo ended off-plan (files outside its files[],
+#                                          planned items not done, or a stated reason): flag its
+#                                          pending transitive dependents needsReplan; prints JSON
+#   confirm-replan <task-id> <todo-id> [note]  Confirm a flagged todo's plan still holds, so it can start
 #   list      <task-id>                    Render Markdown checklist
 #   status    <task-id>                    Print one-line summary: "2/5 done, 1 in progress"
 #   show      <task-id>                    Print the full plan JSON
@@ -59,7 +72,7 @@ CMD="${1:-}"
 shift || true
 
 usage() {
-  sed -n '2,30p' "$0" >&2
+  sed -n '2,37p' "$0" >&2
   exit 64
 }
 
@@ -115,12 +128,8 @@ do_set() {
   if [ -z "$plan_blob" ] || [ "$plan_blob" = "-" ]; then
     plan_blob=$(cat)
   fi
-  # A planning-output document is accepted directly and converted here.
-  #
-  # The conversion used to live as a jq blob inside phase-1-plan.md, which
-  # made the mapping from `tasks[]` to `todos[]` a thing two files defined - and
-  # the phase doc was the copy nothing tested. Accepting both shapes costs four
-  # lines and removes the second definition.
+  # A planning-output document is accepted directly and converted here, so the
+  # mapping from `tasks[]` to `todos[]` has one tested definition.
   if jq -e '.tasks and (.todos | not)' <<<"$plan_blob" >/dev/null 2>&1; then
     plan_blob=$(jq '{
       title: (.summary // .title // "plan"),
@@ -129,7 +138,9 @@ do_set() {
         task: (.title // .subject // ""),
         status: "pending",
         deps: (.dependsOn // .blockedBy // [])
-      } ]
+      } + (if (.files | type) == "array" then {files: .files} else {} end)
+        + (if (.creates | type) == "array" then {creates: .creates} else {} end)
+        + (if .type then {type: .type} else {} end) ]
     }' <<<"$plan_blob")
   fi
 
@@ -169,6 +180,22 @@ deps_satisfied() {
   ' <<<"$state" >/dev/null 2>&1
 }
 
+refuse_unconfirmed_replan() {
+  # $1 state JSON, $2 task_id, $3 todo_id. A todo planned on top of one that
+  # drifted waits for a person to confirm its plan: exits 2 until confirm-replan.
+  local replan
+  replan=$(jq -r --arg id "$3" '
+    (.plan.todos // []) | map(select(.id == $id))[0].needsReplan
+    | select(. != null and (.confirmedAt // "") == "")
+    | "\(.because)\t\(.reason // "")"
+  ' <<<"$1")
+  if [ -n "$replan" ]; then
+    printf "plan-todos: '%s' awaits re-plan confirmation: %s drifted (%s). Check its plan, then: plan-todos.sh confirm-replan %s %s\n" \
+      "$3" "${replan%%$'\t'*}" "${replan#*$'\t'}" "$2" "$3" >&2
+    exit 2
+  fi
+}
+
 do_start() {
   local task_id="${1:-}"; local todo_id="${2:-}"
   [ -z "$task_id" ] || [ -z "$todo_id" ] && { echo "usage: start <task-id> <todo-id>" >&2; exit 64; }
@@ -184,6 +211,7 @@ do_start() {
     echo "plan-todos: deps for '$todo_id' not satisfied (still pending/in_progress/failed)" >&2
     exit 2
   fi
+  refuse_unconfirmed_replan "$state" "$task_id" "$todo_id"
   local now; now=$(iso_now)
   local new
   new=$(jq --arg id "$todo_id" --arg t "$now" '
@@ -202,18 +230,85 @@ require_todo() {
   fi
 }
 
+TDD_EVIDENCE="$_MA_RP_HERE/tdd-evidence.mjs"
+
+tdd_mode() {
+  local prefs="${MULTI_AGENT_PREFS:-$HOME/.claude/multi-agent-preferences.json}" mode
+  mode=$(jq -r '.global.tddEvidence.mode // "warn"' "$prefs" 2>/dev/null) || mode=warn
+  case "$mode" in off|warn|enforce) printf '%s' "$mode" ;; *) printf 'warn' ;; esac
+}
+
+write_tdd() {
+  # $1 state path, $2 todo_id, $3 tdd record JSON
+  local new
+  new=$(jq --arg id "$2" --argjson r "$3" '
+    .plan.todos |= map(if .id == $id then .tdd = $r else . end)
+  ' "$1")
+  write_state "$1" "$new"
+}
+
+do_tdd_run() {
+  # $1 red|green, then <task-id> <todo-id> <results> [flags passed to tdd-evidence.mjs]
+  local kind="$1"; shift
+  local task_id="${1:-}"; local todo_id="${2:-}"; local results="${3:-}"
+  [ -z "$task_id" ] || [ -z "$todo_id" ] || [ -z "$results" ] && { echo "usage: tdd-$kind <task-id> <todo-id> <results-file> [flags]" >&2; exit 64; }
+  shift 3
+  # Only the caller-owned flags pass through; --state, --todo, --results and
+  # --mode come from the pipeline, so a trailing copy cannot override them.
+  local extra=()
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --tests|--already-passing)
+        [ $# -ge 2 ] || { echo "tdd-$kind: $1 needs a value" >&2; exit 64; }
+        extra+=("$1" "$2"); shift 2 ;;
+      *) echo "tdd-$kind: unsupported flag '$1' (only --tests and --already-passing)" >&2; exit 64 ;;
+    esac
+  done
+  local state_path; state_path=$(resolve_state "$task_id")
+  require_todo "$state_path" "$todo_id"
+  local record mode_flag=()
+  [ "$kind" = "red" ] && mode_flag=(--mode "$(tdd_mode)")
+  record=$(node "$TDD_EVIDENCE" "$kind" --state "$state_path" --todo "$todo_id" --results "$results" ${mode_flag[@]+"${mode_flag[@]}"} ${extra[@]+"${extra[@]}"}) || exit 2
+  write_tdd "$state_path" "$todo_id" "$record"
+}
+
 do_complete() {
-  local task_id="${1:-}"; local todo_id="${2:-}"; local notes="${3:-}"
-  [ -z "$task_id" ] || [ -z "$todo_id" ] && { echo "usage: complete <task-id> <todo-id> [notes]" >&2; exit 64; }
+  local task_id="${1:-}"; local todo_id="${2:-}"; local notes="" no_tests=""
+  [ -z "$task_id" ] || [ -z "$todo_id" ] && { echo "usage: complete <task-id> <todo-id> [notes] [--no-tests <reason>]" >&2; exit 64; }
+  shift 2
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --no-tests) no_tests="${2:-}"; [ -z "$no_tests" ] && { echo "complete: --no-tests needs a reason" >&2; exit 64; }; shift 2 ;;
+      *) notes="$1"; shift ;;
+    esac
+  done
   local state_path; state_path=$(resolve_state "$task_id")
   require_todo "$state_path" "$todo_id"
+  local state; state=$(cat "$state_path")
+  refuse_unconfirmed_replan "$state" "$task_id" "$todo_id"
+  # A todo that never started skipped the deps check start makes.
+  if [ "$(jq -r --arg id "$todo_id" '(.plan.todos // []) | map(select(.id == $id))[0].status // "pending"' <<<"$state")" = "pending" ] \
+     && ! deps_satisfied "$state" "$todo_id"; then
+    echo "plan-todos: deps for '$todo_id' not satisfied (still pending/in_progress/failed); it cannot complete before they do" >&2
+    exit 2
+  fi
+  local verdict action
+  verdict=$(node "$TDD_EVIDENCE" check --state "$state_path" --todo "$todo_id" --mode "$(tdd_mode)" \
+    ${no_tests:+--no-tests "$no_tests"}) || exit 2
+  action=$(jq -r '.action' <<<"$verdict")
+  if [ "$action" = "refuse" ]; then
+    echo "plan-todos: $(jq -r '.message' <<<"$verdict") - tddEvidence.mode is enforce" >&2
+    exit 2
+  fi
+  [ "$action" = "warn" ] && echo "plan-todos: warning: $(jq -r '.message' <<<"$verdict"); recorded as unverified" >&2
   local now; now=$(iso_now)
   local new
-  new=$(jq --arg id "$todo_id" --arg t "$now" --arg n "$notes" '
+  new=$(jq --arg id "$todo_id" --arg t "$now" --arg n "$notes" --argjson v "$verdict" '
     .plan.todos |= map(
       if .id == $id then
         .status = "completed" | .completedAt = $t
         | if ($n != "") then .notes = $n else . end
+        | if ($v.tdd != null) then .tdd = $v.tdd else . end
       else . end
     )
   ' "$state_path")
@@ -254,25 +349,47 @@ do_next() {
   local task_id="${1:-}"
   [ -z "$task_id" ] && { echo "usage: next <task-id>" >&2; exit 64; }
   local state_path; state_path=$(resolve_state "$task_id")
-  # Pick the first pending todo whose deps are all completed|skipped.
-  jq -r '
-    (.plan.todos // []) as $all
-    | $all
-    | map(select(.status == "pending"))
-    | map(
-        . as $t
-        | select(
-            (.deps // [])
-            | all(
-                . as $d
-                | $all | map(select(.id == $d))[0] // null
-                | . != null and (.status == "completed" or .status == "skipped")
-              )
-          )
-      )
-    | (.[0] // empty)
-    | if . == null or . == "" then "" else (.id // "") + "\t" + (.task // "") end
-  ' "$state_path"
+  # Ready set ranked by the work each todo unblocks; blocked todos are named on stderr.
+  node "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/task-graph.mjs" next "$state_path" --task-id "$task_id"
+}
+
+do_drift() {
+  local task_id="${1:-}"; local todo_id="${2:-}"
+  [ -z "$task_id" ] || [ -z "$todo_id" ] && { echo "usage: drift <task-id> <todo-id> [--files <path|->] [--not-done N] [--reason <text>]" >&2; exit 64; }
+  shift 2
+  local state_path; state_path=$(resolve_state "$task_id")
+  require_todo "$state_path" "$todo_id"
+  local result rc=0
+  result=$(node "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/task-graph.mjs" drift "$state_path" "$todo_id" "$@") || rc=$?
+  [ "$rc" -eq 0 ] || exit "$rc"
+  if [ "$(jq -r '.drifted' <<<"$result")" = "true" ]; then
+    local new
+    new=$(jq --argjson r "$result" '.plan.todos = $r.todos' "$state_path")
+    write_state "$state_path" "$new"
+  fi
+  jq -c 'del(.todos)' <<<"$result"
+}
+
+do_confirm_replan() {
+  local task_id="${1:-}"; local todo_id="${2:-}"; local note="${3:-}"
+  [ -z "$task_id" ] || [ -z "$todo_id" ] && { echo "usage: confirm-replan <task-id> <todo-id> [note]" >&2; exit 64; }
+  local state_path; state_path=$(resolve_state "$task_id")
+  require_todo "$state_path" "$todo_id"
+  if ! jq -e --arg id "$todo_id" '(.plan.todos // []) | map(select(.id == $id))[0].needsReplan | type == "object"' "$state_path" >/dev/null 2>&1; then
+    echo "plan-todos: '$todo_id' has no re-plan flag to confirm" >&2
+    exit 2
+  fi
+  local now; now=$(iso_now)
+  local new
+  new=$(jq --arg id "$todo_id" --arg t "$now" --arg n "$note" '
+    .plan.todos |= map(
+      if .id == $id then
+        .needsReplan.confirmedAt = $t
+        | if ($n != "") then .needsReplan.note = $n else . end
+      else . end
+    )
+  ' "$state_path")
+  write_state "$state_path" "$new"
 }
 
 do_list() {
@@ -294,7 +411,9 @@ do_list() {
         | ($marks[.status] // "- [ ]") + " **" + (.id // "") + "** " + (.task // "")
           + (if (.notes // "") != "" then "  _(" + .notes + ")_" else "" end)
           + (if (.failureReason // "") != "" then "  _**failed:** " + .failureReason + "_" else "" end)
-          + (if (.skipReason    // "") != "" then "  _**skipped:** "    + .skipReason    + "_" else "" end))
+          + (if (.skipReason    // "") != "" then "  _**skipped:** "    + .skipReason    + "_" else "" end)
+          + (if (.needsReplan // null) != null and (.needsReplan.confirmedAt // "") == ""
+             then "  _**needs re-plan:** " + (.needsReplan.because // "?") + " drifted_" else "" end))
       )
     | .[]
   ' "$state_path"
@@ -332,9 +451,13 @@ case "$CMD" in
   set)      do_set      "$@" ;;
   start)    do_start    "$@" ;;
   complete) do_complete "$@" ;;
+  tdd-red)   do_tdd_run red   "$@" ;;
+  tdd-green) do_tdd_run green "$@" ;;
   fail)     do_fail     "$@" ;;
   skip)     do_skip     "$@" ;;
   next)     do_next     "$@" ;;
+  drift)    do_drift    "$@" ;;
+  confirm-replan) do_confirm_replan "$@" ;;
   list)     do_list     "$@" ;;
   status)   do_status   "$@" ;;
   show)     do_show     "$@" ;;