@mmerterden/multi-agent-pipeline 17.3.0 → 17.5.0

package/pipeline/agents/code-reviewer.md

@@ -25,13 +25,15 @@ Return ONLY a JSON object:
 {
   "findings": [{"severity": "blocking|important|suggestion", "file": "...", "line": N, "issue": "...", "fix": "...", "ruleId": "SEC-01", "criteriaSource": "ios-coding-standard"}],
   "conformance": [{"ruleId": "SEC-01", "verdict": "conformant|violated|not-applicable", "file": "Sources/X.swift", "line": 42, "reason": "..."}],
+  "fileCoverage": [{"path": "Sources/X.swift", "verdict": "reviewed|skipped", "reason": "..."}],
   "approved": true|false
 }
 ```
 
 `ruleId` + `criteriaSource` are required on a finding that comes from a cited
 rule and omitted otherwise. `conformance` is required whenever a `${CRITERIA}`
-block was supplied  -  see below.
+block was supplied, and `fileCoverage` whenever a `${REVIEW_FILES}` block was  -
+see below.
 
 ## Severity Classification
 
@@ -90,6 +92,38 @@ obvious breach; `judgement` rules are yours, and each needs the measurement its
 When no `${CRITERIA}` block is supplied, omit `conformance` entirely and review
 on the focus areas above.
 
+## Review file set (required when supplied)
+
+The orchestrator may pass a `${REVIEW_FILES}` block: the changed files you are
+accountable for, computed before you were dispatched. Generated output,
+lockfiles, recorded snapshots, vendored source and binaries are already removed,
+so what is left is human-authored code and the list is not negotiable.
+
+```
+${REVIEW_FILES}
+reviewed:
+  <repo-relative path>
+  ...
+excluded (not yours, listed so you can see the decision):
+  <repo-relative path>  -  <reason>
+```
+
+Return one `fileCoverage` row **per path under `reviewed`**, and no rows for
+paths outside it. Rules:
+
+- `reviewed` means you read the file's diff in full. There is no `partial`: what
+  you read but did not understand belongs in a `findings` entry, not in a
+  hedged verdict.
+- `skipped` requires a `reason` naming why you could not read it  -  the diff was
+  truncated, the content was unreadable. "Not relevant" is not a skip reason; a
+  file you read and found nothing in is `reviewed`.
+- A path that is neither read nor explicitly skipped fails the stage, for the
+  same reason an unanswered rule ID does: a reviewer that opened one file of ten
+  and one that read all ten return identical empty `findings` arrays, and this
+  list is what tells them apart.
+
+When no `${REVIEW_FILES}` block is supplied, omit `fileCoverage` entirely.
+
 ## Priority Files (advisory)
 
 When the orchestrator passes a `${PRIORITY_FILES}` block, treat it as a heuristic

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

@@ -169,10 +169,10 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 
 In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints.
 
-**TaskCreate ordering (strict)**: All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**TaskCreate ordering (strict)**: All TaskCreate calls in a registration batch fire in strict phase-number order BEFORE any TaskUpdate in that batch, and a later batch only ever appends phases numbered above everything already registered. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ```text
-# Phase 0 startup  -  register one tile per phase (0..N), capture the taskId, persist it:
+# Register one tile per phase, capture the taskId, persist it:
 for each phase in 0:Init, 1:Analysis, 2:Planning, 4:Review, 6:Commit, 7:Report:
   TaskCreate({ subject: "Phase <N>: <Name>", activeForm: "<doing-form>" })
     -> returns taskId
@@ -194,7 +194,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update <N> completed
 
 #### TaskCreate ordering (strict)
 
-**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `analysis` that means: Phase 0 → Phase 1 → Phase 2 → Phase 4 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**All TaskCreate calls in a batch fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `analysis` that means: Phase 0 → Phase 1 → Phase 2 → Phase 4 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ### Visual channel  -  Copilot CLI / plain shell
 

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

@@ -83,10 +83,10 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 
 In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints.
 
-**TaskCreate ordering (strict)**: All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**TaskCreate ordering (strict)**: All TaskCreate calls in a registration batch fire in strict phase-number order BEFORE any TaskUpdate in that batch, and a later batch only ever appends phases numbered above everything already registered. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ```text
-# Phase 0 startup  -  register one tile per phase (0..N), capture the taskId, persist it:
+# Register one tile per phase, capture the taskId, persist it:
 for each phase in 0:Init, 1:Analysis, 2:Planning, 3:Dev, 4:Review, 6:Commit, 7:Report:
   TaskCreate({ subject: "Phase <N>: <Name>", activeForm: "<doing-form>" })
     -> returns taskId
@@ -108,7 +108,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update <N> completed
 
 #### TaskCreate ordering (strict)
 
-**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `autopilot` that means: Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**All TaskCreate calls in a batch fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `autopilot` that means: Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ### Visual channel  -  Copilot CLI / plain shell
 

package/pipeline/commands/multi-agent/autopilot-off/SKILL.md

@@ -45,9 +45,11 @@ pkill -f "$HOME/.claude/autopilot/bin/menubar" 2>/dev/null || true
 
 Without `--now` nothing here runs. With it, the child session is stopped and the
 run is marked `abandoned`, its worktree is removed **unless it holds uncommitted
-work**, in which case the work is stashed to `autopilot/abandoned/<task-id>` and
-the worktree is kept. Same contract as `gc-abandoned.sh`; losing a day of edits
-is worse than 750 MB.
+work**, in which case the work goes into a stash entry labelled
+`autopilot/abandoned/<task-id>` (find it with `git stash list`) and the worktree
+is kept. Same contract as `gc-abandoned.sh` and `autopilot-runner.mjs`; losing a
+day of edits is worse than 750 MB. No branch is created - one made after
+`stash push` would point at HEAD and contain none of the work.
 
 ### 5. Keep the selection
 

package/pipeline/commands/multi-agent/garbage-collect/SKILL.md

@@ -115,7 +115,7 @@ deletes nothing until you confirm.
    | Line | Meaning |
    |---|---|
    | `would remove` / `would remove worktree` | reapable: stopped past its age limit, or finished with its worktree left behind |
-   | `would stash` | uncommitted work found - it is stashed to `autopilot/abandoned/<task-id>` and the worktree is **kept** |
+   | `would stash` | uncommitted work found - it goes into a stash entry labelled `autopilot/abandoned/<task-id>` (`git stash list`) and the worktree is **kept** |
    | `would mark abandoned` | the state is stale but there is no worktree left to remove |
    | `unattributed` | a worktree with no run state. **Never removed, whatever the flags.** `.worktrees/` is not exclusively ours, and nothing distinguishes a hand-made worktree from a pipeline one whose log was pruned. Report the list and its size; the user decides |
 

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

@@ -67,10 +67,21 @@ Two channels run in parallel at every phase boundary:
 ```bash
 # Phase 0, very first shell call (every CLI):
 bash $HOME/.claude/scripts/phase-tracker.sh init "$TASK_ID"
-for p in "0:Init" "1:Analysis" "2:Planning" "3:Dev" "4:Review" "6:Commit" "7:Report"; do
+bash $HOME/.claude/scripts/phase-tracker.sh add 0 "Init"
+bash $HOME/.claude/scripts/phase-tracker.sh tiles
+bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
+
+# Phase 0 Step 7.5, immediately after the depth answer - the first moment this
+# mode knows its phase set. Full:
+for p in "1:Analysis" "2:Planning" "3:Dev" "4:Review" "6:Commit" "7:Report"; do
   bash $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
 done
-bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
+# Short (Analysis and Planning are not run, so they get no tile at all):
+for p in "3:Dev" "4:Review" "6:Commit" "7:Report"; do
+  bash $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
+done
+# Then the widget, narrowed to the phases that do not have a tile yet:
+bash $HOME/.claude/scripts/phase-tracker.sh tiles --new
 
 # Every phase boundary (every CLI):
 bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress|completed|failed|skipped
@@ -83,11 +94,11 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 
 In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints.
 
-**TaskCreate ordering (strict)**: All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**TaskCreate ordering (strict)**: All TaskCreate calls in a registration batch fire in strict phase-number order BEFORE any TaskUpdate in that batch, and a later batch only ever appends phases numbered above everything already registered. This mode registers in two batches (Step -1, then Step 7.5), so `tiles --new` narrows the second one and the Phase 0 tile is never created twice. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ```text
-# Phase 0 startup  -  register one tile per phase (0..N), capture the taskId, persist it:
-for each phase in 0:Init, 1:Analysis, 2:Planning, 3:Dev, 4:Review, 6:Commit, 7:Report:
+# Register one tile per phase, capture the taskId, persist it:
+for each phase in 0:Init at Step -1, then 1:Analysis, 2:Planning, 3:Dev, 4:Review, 6:Commit, 7:Report (Full) or 3:Dev, 4:Review, 6:Commit, 7:Report (Short) at Step 7.5:
   TaskCreate({ subject: "Phase <N>: <Name>", activeForm: "<doing-form>" })
     -> returns taskId
   bash $HOME/.claude/scripts/phase-tracker.sh meta <N> tasklist_id "<taskId>"
@@ -108,7 +119,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update <N> completed
 
 #### TaskCreate ordering (strict)
 
-**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `--local` that means: Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**All TaskCreate calls in a batch fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `--local` that means: Phase 0 at Step -1, then the rest in ascending order at Step 7.5 (Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 6 → Phase 7 minus whatever the depth answer drops). The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ### Visual channel  -  Copilot CLI / plain shell
 

package/pipeline/commands/multi-agent/local-autopilot/SKILL.md

@@ -104,10 +104,10 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 
 In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints.
 
-**TaskCreate ordering (strict)**: All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**TaskCreate ordering (strict)**: All TaskCreate calls in a registration batch fire in strict phase-number order BEFORE any TaskUpdate in that batch, and a later batch only ever appends phases numbered above everything already registered. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ```text
-# Phase 0 startup  -  register one tile per phase (0..N), capture the taskId, persist it:
+# Register one tile per phase, capture the taskId, persist it:
 for each phase in 0:Init, 1:Analysis, 2:Planning, 3:Dev, 4:Review, 6:Commit, 7:Report:
   TaskCreate({ subject: "Phase <N>: <Name>", activeForm: "<doing-form>" })
     -> returns taskId
@@ -129,7 +129,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update <N> completed
 
 #### TaskCreate ordering (strict)
 
-**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `--local autopilot` that means: Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**All TaskCreate calls in a batch fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `--local autopilot` that means: Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ### Visual channel  -  Copilot CLI / plain shell
 

package/pipeline/lib/multi-repo-pipeline.sh

@@ -292,6 +292,12 @@ agent_state = {
     "worktreePath":  os.path.join(worktree_root, primary["name"]),
     "branch":        state["branch"],
     "baseBranch":    state.get("baseBranch", "develop"),
+    "baseBranchSource": state.get("baseBranchSource", "asked"),
+    # The multi-repo bridge always builds worktrees - that is what it is for -
+    # so the workspace was never in question here. It is recorded anyway,
+    # because phase0-exit-gate.mjs refuses to close Phase 0 on a state file
+    # that cannot say who decided.
+    "workspaceSource": state.get("workspaceSource", "command"),
     "remoteType":    primary.get("provider", "github"),
     "currentPhase":  0,
     "status":        "in_progress",
@@ -308,6 +314,26 @@ related = issue.get("relatedIssues") or []
 if isinstance(related, list) and related:
     agent_state["relatedIssues"] = related
 
+# Always written, `[]` included: the empty array is the record that the
+# dev-context step ran, and phase0-exit-gate.mjs refuses to close Phase 0
+# without it. Only repos this run will NOT modify belong here - the extras that
+# get a worktree are already in projects[].
+STACKS = {"ios", "android", "node", "python", "go"}
+worktreed = {r.get("name") for r in all_repos}
+siblings = []
+for r in (state.get("readonlySiblings") or []) + extras:
+    name = r.get("name")
+    if not name or name in worktreed:
+        continue
+    stack = r.get("stack", "unknown")
+    siblings.append({
+        "name":    name,
+        "root":    r.get("localPath") or None,
+        "stack":   stack if stack in STACKS else "unknown",
+        "canPush": bool(r.get("canPush", False)),
+    })
+agent_state["siblings"] = siblings
+
 logs_dir = os.path.expanduser(os.path.join("~/.claude/logs/multi-agent", primary["name"], state["taskId"]))
 os.makedirs(logs_dir, exist_ok=True)
 out_path = os.path.join(logs_dir, "agent-state.json")

package/pipeline/multi-agent-refs/analysis/locked.md

@@ -1,16 +1,16 @@
-# Locked decisions (36)
+# Locked decisions (37)
 
-> The 36 Locked decisions of the analysis flow. Loaded by `/multi-agent:analysis`, by `/multi-agent:analysis-resolve` (which inherits them) and by pipeline Phase 1 when it runs the analysis engine. Numbering is canonical: cite as `Locked <n> (<short label>)`.
+> The 37 Locked decisions of the analysis flow. Loaded by `/multi-agent:analysis`, by `/multi-agent:analysis-resolve` (which inherits them) and by pipeline Phase 1 when it runs the analysis engine. Numbering is canonical: cite as `Locked <n> (<short label>)`.
 
 ### Index by category (v9.1.0+)
 
-Browse-friendly grouping of the 36 Locked decisions. Numbering stays canonical (matches the list below); the index is read-only navigation.
+Browse-friendly grouping of the 37 Locked decisions. Numbering stays canonical (matches the list below); the index is read-only navigation.
 
 | Category | Decisions | Concern |
 |---|---|---|
 | **A. Governance** | 1, 5, 6, 7, 10, 26, 27, 32, 36 | Run-level process rules: one feature per run, default output, auto-commit ban, punctuation policy, output picker timing, Pass B preview, evidence digest cache, analysis profile, document reviewed before publish |
 | **B. Citation and Evidence** | 3, 4, 8, 11, 24, 30, 34 | Every fact in the doc traces back to a source: citation discipline, forward-looking spec, standards binding, repo-evidence reuse-first, Pass B footnote mandatory, analysis self-contained (pipeline-wide), references built from the evidence record |
-| **C. Output Format and Structure** | 2, 9, 13, 14, 16, 17, 20, 21, 25, 33, 35 | How the document is laid out: section omission rule, per-platform output split, Gherkin user stories, Goals + Non-Goals paired, Files-to-Add tag, API response variants exhaustive, localization mode (ownership-aware), References at the bottom, Lite mode, corporate backbone always renders, stack-optional render |
+| **C. Output Format and Structure** | 2, 9, 13, 14, 16, 17, 20, 21, 25, 33, 35, 37 | How the document is laid out: section omission rule, per-platform output split, Gherkin user stories, Goals + Non-Goals paired, Files-to-Add tag, API response variants exhaustive, localization mode (ownership-aware), References at the bottom, Lite mode, corporate backbone always renders, stack-optional render, redesign records v1 before planning v2 |
 | **D. Design Source and Pipeline Architecture** | 12, 22, 23 | Where design comes from and how the pipeline renders: Figma 3-tier access (BLOCKING), platform-agnostic template + Pass B render, convention extraction (Phase 1c) |
 | **E. UI, Variant, and Test Coverage** | 15, 18, 19, 28, 29, 31 | UI artefact rules: SVG default for new assets, screenshots embedded, all Figma variants drilled, SwiftUI Preview block (iOS), variant usage explicit, business-rule to acceptance-criterion to test traceability |
 

package/pipeline/multi-agent-refs/analysis/render.md

@@ -124,10 +124,11 @@ Result: `state.analysisSpec.outputs.requested[]`.
 for f in /tmp/analysis-<feature-slug>-<ts>/*.md; do
   node "$HOME/.claude/scripts/validate-analysis-doc.mjs" "$f" || GATE_FAILED=1
   node "$HOME/.claude/scripts/build-references.mjs" <state.json> --check "$f" || GATE_FAILED=1
+  node "$HOME/.claude/scripts/verify-citations.mjs" "$f" --repo "$REPO_ROOT" || GATE_FAILED=1
 done
 ```
 
-`validate-analysis-doc.mjs` enforces the mechanically-checkable Locked decisions on the emitted markdown itself (front-matter completeness, never-omitted sections per Locked 2, humanizer punctuation per Locked 7, Full-mode business-rule traceability per Locked 31, and in the corporate profile the backbone presence and `EKLENECEK`-to-Section-20 pairing per Locked 33). `build-references.mjs --check` runs the References coverage gate (Locked 34): a source the run consumed but did not list, or a listed row with no evidence behind it, blocks dispatch. Any ERROR blocks dispatch: fix the draft and re-validate. Warnings are advisory (run with `--strict` to treat them as blocking). This turns the "fails the dispatch gate" prose into a real, model-independent check.
+`validate-analysis-doc.mjs` enforces the mechanically-checkable Locked decisions on the emitted markdown itself (front-matter completeness, never-omitted sections per Locked 2, humanizer punctuation per Locked 7, Full-mode business-rule traceability per Locked 31, and in the corporate profile the backbone presence and `EKLENECEK`-to-Section-20 pairing per Locked 33). `build-references.mjs --check` runs the References coverage gate (Locked 34): a source the run consumed but did not list, or a listed row with no evidence behind it, blocks dispatch. `verify-citations.mjs` resolves each claimed `file:line` at HEAD with `git cat-file`, so `Foo.swift:9999` in a repo with no Foo.swift blocks dispatch (Locked 3, Locked 37). Any ERROR blocks dispatch: fix the draft and re-validate. Warnings are advisory (run with `--strict` to treat them as blocking). This turns the "fails the dispatch gate" prose into a real, model-independent check.
 
 Iterate `state.analysisSpec.outputs.requested`. For each target:
 

package/pipeline/multi-agent-refs/channels/pr.md

@@ -77,6 +77,32 @@ Across stacks the same shape produces, for example: `LoginView.swift  -  ...` (i
 <none, or which service, contract or channel>
 ```
 
+Part 3 is the one part of this body that is MEASURED rather than recalled. The
+code graph already answers it, so draw the answer instead of re-typing it:
+
+```bash
+node "$HOME/.claude/scripts/graph-mermaid.mjs" "<changed symbol[,symbol]>"
+```
+
+Append the fenced block it prints under part 3, above the prose. GitHub renders
+mermaid natively in pull requests, so this costs no renderer and no plugin. The
+prose stays: the diagram says which symbols the change reaches, the sentence says
+which screens and flows a tester must open, and neither answers the other.
+
+Exit 1 means the repo has no graph yet (`/multi-agent:graph` builds it) or the
+symbol is not in it. That is a gap with a reason, not a failure: write the prose
+alone and say the graph was unavailable. Never hand-draw the diagram - a drawn
+blast radius nobody measured is worse than none, because a diagram is read as
+fact.
+
+The commit line the script prints stays with it. A graph built before the change
+draws the radius of an older tree, and the reader has no other way to notice.
+
+This is a GitHub-only section. `channels/jira.md` has no mermaid handling at all:
+a fence there converts to a literal `{code:mermaid}` block, so the Jira impact
+section keeps its prose. Confluence renders it through the `ac:name="mermaid"`
+macro (`md2confluence-v3.py`) when the space has the plugin.
+
 When the change deliberately fixes part of a wider problem, a closing **Risk and remaining scope** paragraph names what is still open and why it was left - a reviewer who can see the rest of the pattern in the repo will ask otherwise, and the honest answer is cheaper written down than defended in a thread.
 
 **`test_scenarios`**  -  the same titled-scenario shape the Jira adapter uses, so the tester reads one list on both surfaces, with symbols allowed here:

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -214,6 +214,28 @@ on skill directories would demand exactly the layout that breaks it.
 
 Future changes that break an item in the "stay identical" list must update **both** files in the same commit. `smoke-cross-cli-behavior.sh` enforces the identity-preserving axis (input parsing, routing, output shape); structural differences are left to manual review because enforcing them would require forcing the files to the same shape, which we intentionally don't want.
 
+### Panel diversity per host
+
+Phase 4 runs three reviewers everywhere, but the diversity those three buy is not the
+same on every host. Copilot CLI gets cross-VENDOR disagreement for free: GPT-5.4 sits
+beside two Claude models. Claude Code and Codex each run a one-vendor panel - three
+Anthropic models on one, three OpenAI models on the other - so the same three-way
+agreement is weaker evidence there, and Phase 4 says so in the triage note on a
+borderline finding.
+
+Where the budget goes instead, when vendor diversity is unavailable:
+
+| Host | Reviewer 1 | Reviewer 2 | Reviewer 3 |
+|---|---|---|---|
+| Copilot CLI | Fable/Opus, security + architecture | GPT-5.4, edge cases (cross-vendor) | Sonnet, quality |
+| Claude Code | Fable, security + architecture | Opus, edge cases | Sonnet, quality |
+| Codex | `xhigh`, security + architecture | a different family member, edge cases | `medium`, quality |
+
+On Codex the axis is reasoning effort as much as model identity, because the family
+members available there are closer to each other than Fable and Sonnet are. That is a
+weaker axis, not an equivalent one, and treating it as equivalent is the error this
+section exists to prevent.
+
 ## 3. Frontmatter Transform Rules (Claude ↔ Copilot)
 
 Each file has a different frontmatter schema. The sync flow transforms between them:

package/pipeline/multi-agent-refs/features/base-branch-evidence.md

@@ -0,0 +1,222 @@
+# Feature: Base-Branch Evidence
+
+<!-- toc -->
+- [1. The fetch is a fact, not a formality](#1-the-fetch-is-a-fact-not-a-formality)
+- [2. Evidence sources](#2-evidence-sources)
+- [2b. A filter is not a ranking](#2b-a-filter-is-not-a-ranking)
+- [3. The convention is learned from the remote](#3-the-convention-is-learned-from-the-remote)
+- [4. The picker](#4-the-picker)
+- [5. Autopilot](#5-autopilot)
+- [6. State](#6-state)
+<!-- /toc -->
+
+**Pattern**: Phase 0 Step 3 used to ask one question with a list it could not
+vouch for. `git fetch origin` ran, its exit code was ignored, and `git branch -r`
+printed the remote-tracking cache either way - so on a restricted network a
+weeks-old local list was presented as the remote's answer, with nothing in the
+output saying so. And the answer was usually derivable: an issue that carries a
+target version, or that links a separate issue representing the release, already
+names the branch on a repo whose release branches encode the version. Nothing
+derived it.
+
+The shape here is **evidence collection, then a picker** - deliberately not a
+rule engine. Every candidate carries why it is a candidate; the ranking orders
+them; a human chooses. A rule engine would have to be right, and the inputs
+(field names, branch spellings, board conventions) differ per repo and change
+under it. An evidence list only has to be honest.
+
+Implemented by `$HOME/.claude/scripts/base-branch-candidates.mjs` (pure, no git,
+no network - it is handed ref lists and issue evidence). Gated by `prefs.global.baseBranchEvidence.enabled`
+(default `true`; off falls back to the rule-6 sort order, still through the picker). Asserted by `smoke-base-branch-evidence.sh`
+and `test/base-branch-candidates.test.mjs`.
+
+## 1. The fetch is a fact, not a formality
+
+```bash
+git -C "$PROJECT_ROOT" fetch origin; FETCH_RC=$?
+```
+
+`FETCH_RC` decides `refProvenance`, which is a required input to the collector
+and rides on every candidate as its own evidence row:
+
+| `FETCH_RC` | `refProvenance` | Ref list | What the user is told |
+|---|---|---|---|
+| 0 | `remote` | `git branch -r` | nothing extra; the list is current |
+| non-zero | `local` | `git branch -r` (cache) **and** `git branch` | the picker question itself says the fetch failed and these refs may be stale |
+
+A degraded list is still a list - falling back is correct, hiding it is not. The
+degraded picker gains a **Retry the fetch** row, and the fetch-fail picker
+already in Step 3 (Connect VPN / cached / local branch / abort) still owns the
+`baseFetchStatus` value. The two fit together: that picker records *what the run
+is working from*, this one records *what the candidate list is worth*.
+
+Local-only refs never silently become remote ones. `state.baseBranchEvidence.refProvenance`
+must be `local` whenever `baseFetchStatus` is `cached-stale` or `local-branch`,
+and `phase0-exit-gate.mjs` refuses to close Phase 0 otherwise. That assertion is
+the whole of problem 1: the run may degrade, it may not misreport.
+
+## 2. Evidence sources
+
+| Kind | Where it comes from | Weight |
+|---|---|---|
+| `issue-version` | a version-typed field on the issue whose value matches a branch on the ref list | 100 exact, 60 same major.minor, x0.6 for an affects-version field |
+| `linked-release` | a linked issue or parent whose own fix-version or summary names a version that matches a branch | 90 exact (110 when `baseBranchEvidence.preferLinkedRelease`) |
+| `version-convention` | the release-branch template inferred from the ref list | annotation only, no points |
+| `recent` | `prefs.global.recentBranches[{projectKey}]`, inside `settings.branchTtlDays` | 40 + up to 10 for recency |
+| `repo-default` | `origin/HEAD` | 20 |
+| `sort-order` | the develop / release / main families Step 3 always sorted by | 15 / 10 / 5 |
+| `ref-provenance` | the fetch outcome above | annotation only, on every candidate |
+
+### Field discovery, not a field table
+
+No field id is hardcoded, and none can be: a board's "target version" is a
+custom field whose id differs per Jira instance. What is stable is the *schema*.
+`GET /rest/api/2/field` returns `[{id, name, custom, schema: {type, items, custom}}]`,
+and any field whose schema resolves to `version` - directly, or as `array` with
+`items: "version"` - is read, whatever it is called. The two system fields
+(`fixVersions`, `versions`) are read unconditionally; an affects-version field
+is weighted lower than a fix-version one because it describes where the bug was
+seen, not where the fix lands.
+
+`GET /rest/api/2/issue/<key>?expand=names` returns the same display names inline
+and saves the second call when only labels are needed.
+
+### The linked release issue
+
+`fields.issuelinks[]` carries `{type: {inward, outward}, inwardIssue, outwardIssue}`
+and `fields.parent` carries the parent of a sub-task. On a board where opening a
+development sub-task requires selecting the related release issue, the link is
+the authoritative answer and the version field is the corroboration - so
+`prefs.global.baseBranchEvidence.preferLinkedRelease` (default `false`) raises the
+linked-release weight above the version-field one rather than adding a second rule. A linked issue counts as
+a release issue when a version can be read out of its own fix-version field or
+its summary; the issue *type name* is not consulted, because type names are
+per-board copy.
+
+GitHub's analogue is the milestone title, read the same way.
+
+## 2b. A filter is not a ranking
+
+Step 3's rule-5 list used to be narrowed with `grep -E '(develop|release|main|master)'`,
+which is the prefix table this whole feature exists not to have - and worse than a
+table, because it DISCARDS. A repo whose release branches read `stabilise-2.7`
+matched none of the four words, so none of its branches reached the picker, the
+convention-learner had nothing to learn from, and the version on the issue could
+never match anything. The feature would have been inert on exactly the repos it
+was written for.
+
+The rule is the distinction: **a word list that ranks is fine, a word list that
+filters is not.** Ranking only reorders rows the user can still see past; filtering
+removes answers with nothing saying so. So the four family words stay where they
+belong - rule 6's sort and this collector's 15/10/5 `sort-order` weights - and the
+filter gained a version alternative that admits any branch carrying a version
+token, whatever it is called.
+
+The excluded prefixes (`feature/`, `bugfix/`, `fix/`, `hotfix/`, `chore/`) are a
+different thing again: those are the task branches **this pipeline creates itself**,
+in Step 4. Excluding your own output is not a convention assumption.
+
+## 3. The convention is learned from the remote
+
+A table of branch prefixes would be wrong for most repos the day it was written.
+So the template is inferred from the refs that exist: every branch carrying a
+version token is reduced to its shape by replacing the token with `<version>`,
+and the most common shape is this repo's convention. A repo whose release
+branches read `<prefix>/develop_<version>` produces that template; a repo that
+spells them `release-<version>` produces that one; a repo with no versioned
+branches produces `null` and the whole source goes quiet.
+
+The inference is reported with its member count (`learned from 4 branch(es)`),
+because an inference from one branch and an inference from a dozen are different
+claims and the picker row should not flatten them.
+
+**A predicted branch is never offered.** When the learned template predicts a
+name that is not on the ref list, that is a note, not an option:
+
+```
+version 1.51.0 (field "Target Version") has no branch on the remote;
+the convention <prefix>/develop_<version> learned from 4 branch(es) would spell it
+<prefix>/develop_1.51.0
+```
+
+That sentence is more useful than a candidate would be - it tells the user the
+release branch has not been cut yet, which is a real answer to "which base?" -
+and an option the user picks has to be checkoutable. Offering a name that does
+not exist just moves the failure to Step 8, where it reads as a git error.
+
+## 4. The picker
+
+`toPickerOptions()` builds the rows, and the **evidence is the description**. A
+row reading `matches version 1.51.0 from the issue field "Target Version"` and a
+row reading `the repository's default branch` are different answers to the same
+question; a picker that hides which one it is cannot be chosen on its merits.
+
+The two-option floor is enforced inside that function rather than left to the
+caller: it never returns fewer than two rows, because `AskUserQuestion` refuses a
+question with fewer than two declared options *and discards every question
+batched with it*, and the host's injected Other row does not count toward the
+schema minimum. The escape row (`Show all branches`) is a genuine second choice,
+not an `OK` button - see picker-contract.md, "Two options or it is not a
+question".
+
+**Interactive runs always ask.** A derived candidate is a better-ordered list,
+never a skipped question. `baseBranchSource` stays `asked`, because a human
+answered; the derivation is recorded separately in `state.baseBranchEvidence` so
+it stays readable afterwards.
+
+## 5. Autopilot
+
+Autopilot cannot be asked anything, so it resolves in this order and records
+which rule fired in `baseBranchSource`:
+
+1. `remembered` - `recentBranches` inside the TTL and still on the ref list (memory outranks the default, per the picker contract).
+2. `derived` - the top candidate carries `issue-version` or `linked-release` evidence **and** no other candidate ties its score. Ambiguity is not resolved by coin-flip.
+3. `default` - the sort order.
+
+`derived` is an autopilot-only value, exactly like `remembered` and `default`;
+an interactive run recording it has skipped its picker, and the exit gate fails
+it. The gate additionally refuses `derived` unless `state.baseBranchEvidence`
+actually contains issue-derived evidence for the chosen branch - a `derived` that
+derived from nothing is `default` wearing a hat.
+
+### Asking on the issue (`prefs.global.baseBranchEvidence.autopilotAsksOnIssue`, default OFF)
+
+When the derivation is **ambiguous** and nothing is remembered, autopilot can
+post one comment on the Jira issue or GitHub issue asking which branch to
+develop from, then halt.
+
+This is an outward-facing write, so it is fenced:
+
+- **Off by default.** Nothing posts unless the user turned it on for this project.
+- **A question, never a state change.** No transition, no resolution, no assignee change, no label change, no close - ever. The standing rule that the pipeline never auto-closes an issue is not relaxed by this feature, and a comment is the only write it is allowed to make.
+- **Human-facing copy follows `outputLanguage`**, like every other comment the pipeline writes.
+- **`Ref:`, never `Closes:`/`Fixes:`/`Resolves:`** in the body, so no platform-side automation reads it as an instruction.
+- **It renders the same evidence the picker would have shown**, candidate by candidate, so the person answering sees what the run saw.
+- **Then the run halts.** Posting a question and continuing on a guess is worse than not asking: the guess lands in a branch while the question sits unanswered. So the comment trips the circuit breaker (trigger 6), which is the sanctioned autopilot pause - state recorded, one actionable line printed, waiting for an explicit `resume`. Phase 0 does not close and no worktree is created.
+
+The nearest-safe reading of "post a comment asking which branch" is therefore:
+ask once, change nothing, stop. An autopilot that posts a question and then
+answers it itself has not asked anything.
+
+## 6. State
+
+```jsonc
+"baseBranchSource": "asked" | "input" | "remembered" | "default" | "derived",
+"baseBranchEvidence": {
+  "refProvenance": "remote" | "local",   // required whenever this object exists
+  "chosen": "<branch>",
+  "ambiguous": false,
+  "convention": { "template": "<prefix>/develop_<version>", "members": 4 },
+  "candidates": [
+    { "branch": "<branch>", "score": 115,
+      "evidence": [{ "kind": "issue-version", "detail": "..." }] }
+  ],
+  "notes": ["..."],
+  "askedOnIssue": { "target": "PROJ-1234", "url": "...", "at": "..." }
+}
+```
+
+`baseBranchEvidence` is required when `baseBranchSource` is `derived`, and when
+`baseFetchStatus` is `cached-stale` or `local-branch`. Everywhere else it is
+optional: a run that took the base from the task reference has no evidence to
+record and should not be made to invent some.

package/pipeline/multi-agent-refs/features/code-graph.md

@@ -1,5 +1,11 @@
 ## Code Graph (Phase 1 Step 2.6 + Phase 7 Step 3)
 
+<!-- toc -->
+- [Phase 1 Step 2.6  -  query before dispatching Explore](#phase-1-step-26---query-before-dispatching-explore)
+- [Phase 7 Step 3  -  refresh after the branch changed code](#phase-7-step-3---refresh-after-the-branch-changed-code)
+- [The graph is drawable, and one place already asks for it](#the-graph-is-drawable-and-one-place-already-asks-for-it)
+<!-- /toc -->
+
 A deterministic, LLM-free map of what a repo declares and what refers to what,
 written to `~/.claude/knowledge/<project>/code-graph.json`. Gated by
 `prefs.global.codeGraph.enabled` (default `false`); with it off, Phase 1 and
@@ -67,3 +73,37 @@ The rebuild costs no API tokens, so it runs every task rather than on a stalenes
 heuristic. A non-zero validator exit keeps the previous graph and logs
 `knowledge.graph_invalid`; it never fails the run  -  a stale graph is a degraded
 Phase 1, not a broken deliverable.
+
+### The graph is drawable, and one place already asks for it
+
+The PR body's Impact Analysis, part 3, asks which symbols and files a change
+reaches. That is `graph-affected.mjs`'s question, and until now the answer was
+re-typed as prose by a model while the measurement sat on disk unread.
+
+```bash
+node $HOME/.claude/scripts/graph-mermaid.mjs "<symbol[,symbol]>" [--depth N] [--max-nodes N]
+```
+
+It emits a fenced `flowchart` and nothing else - no renderer, no plugin, no
+dependency, because mermaid is text and GitHub renders it natively in pull
+requests, issues and markdown files. Traversal is not reimplemented: `findByName`
+and `affected` are imported from `graph-affected.mjs`, so the diagram and the
+text report cannot disagree about what is affected.
+
+Three properties that are enforced rather than promised
+(`smoke-graph-mermaid.sh`):
+
+- Every drawn node and edge resolves back into `code-graph.json`, with the edge
+  kind it claims. A diagram is read as fact and checked less than prose, so an
+  invented edge is the expensive failure.
+- Over `--max-nodes` the leftover count is printed inside the diagram, not
+  dropped. A small picture of a large blast radius reads as reassurance.
+- The graph's `baseCommit` is printed beside it. A graph built before the change
+  draws an older tree, and nothing else in the PR would reveal that.
+
+Exit 1 with a reason on stderr means no graph or no such symbol. The caller
+records the gap and writes the prose alone; it never hand-draws a replacement.
+
+Jira is not a target: its renderer turns the fence into a literal
+`{code:mermaid}` block. Confluence renders it through the `ac:name="mermaid"`
+macro when the space carries the plugin (`channels/confluence.md`).