@mmerterden/multi-agent-pipeline 20.23.1 → 20.24.0

package/pipeline/multi-agent-refs/picker-contract.md

@@ -156,7 +156,8 @@ longer exists. A remembered choice is evidence about this user and this repo; an
 order is a guess that happens to be sorted. Where the two agree nothing changes, and
 where they disagree the remembered one is the answer with a reason behind it.
 
-The run records which rule fired (`remembered` or `default`). An autopilot run cannot be
+The run records which rule fired (`remembered`, `default`, or `derived` when the answer follows from the task itself) and lists the choice in
+`state.decisions[]` (`features/autopilot-decisions.md`). An autopilot run cannot be
 asked anything, so the only thing that keeps it accountable is being readable afterwards.
 
 ## Background (unattended, not autopilot) contract
@@ -189,6 +190,6 @@ park it writes `agent-state.json` beside its tracker with `taskId`,
 
 ## Deterministic gates note
 
-Claude Code's `PreToolUse` exit-2 hooks are the HARD blocking gates. Three ship, none needing run-specific arguments so they are naturally hookable: (1) `pre-commit-check.sh` scans the staged diff on every `git commit` and blocks on a detected secret; (2) `agent-guard.sh` runs on `git commit` + `git push` and blocks AI/assistant attribution in a commit message and force-push to a protected branch (main/master/develop); (3) `check-read-size.sh` runs on `Read` and on the shell commands that read a file whole, and routes an oversized read to a cheap worker (`bulk-read.sh`) instead of the caller's own rung. The first two inspect what a run WRITES; the third inspects what it pays to READ, and it is inert until `bulkRead.mode` is set to `observe` or `enforce`, so merging the block changes nothing until the user opts in. Its `observe` mode blocks nothing and only logs, which is how the baseline is measured before anything is routed. All three are self-contained and never execute the inspected command. On an internal error they let the call through in an attended session; `agent-guard.sh` blocks instead under `MULTI_AGENT_UNATTENDED=1`, where nobody is watching to notice a gap. Three capture hooks ship in the same block and block nothing: `SessionEnd` runs `capture-flush.sh --if-stale` (writing a killed run's findings into the per-repo stores, so they do not depend on the run reaching Phase 5) plus `note-session.sh` (the mechanical shape of a non-pipeline session: tools used, commands that failed, calls the user refused - never an argument, never any output), `PreCompact` runs `capture-flush.sh` without `--if-stale` (a compaction summarizes a long phase mid-flight, so it is the moment unflushed findings are at risk; the staleness test exists only so a session exit does not re-flush a finished run, and both store writes are idempotent), and `SessionStart` runs `capture-resume.sh`, at most two lines about an unfinished run and a stale observation queue. None of them calls a model; all exit 0 on every path. The recommended hook block ships at `install/templates/claude-hooks.json`; `multi-agent:setup` offers to merge it into `~/.claude/settings.json`. The other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with per-run arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable.
+Claude Code's `PreToolUse` exit-2 hooks are the HARD blocking gates. Three ship, none needing run-specific arguments so they are naturally hookable: (1) `pre-commit-check.sh` scans the staged diff on every `git commit` and blocks on a detected secret; (2) `agent-guard.sh` runs on `git commit` + `git push` and blocks AI/assistant attribution in a commit message and force-push to a protected branch (main/master/develop); (3) `check-read-size.sh` runs on `Read` and on the shell commands that read a file whole, and routes an oversized read to a cheap worker (`bulk-read.sh`) instead of the caller's own rung. The first two inspect what a run WRITES; the third inspects what it pays to READ, and it is inert until `bulkRead.mode` is set to `observe` or `enforce`, so merging the block changes nothing until the user opts in. Its `observe` mode blocks nothing and only logs, which is how the baseline is measured before anything is routed. All three are self-contained and never execute the inspected command. On an internal error they let the call through in an attended session; `agent-guard.sh` blocks instead under `MULTI_AGENT_UNATTENDED=1`, where nobody is watching to notice a gap. Three capture hooks ship in the same block and block nothing: `SessionEnd` runs `capture-flush.sh --if-stale` (writing a killed run's findings into the per-repo stores, so they do not depend on the run reaching Phase 5) plus `note-session.sh` (the mechanical shape of a non-pipeline session: tools used, commands that failed, calls the user refused - never an argument, never any output), `PreCompact` runs `capture-flush.sh` without `--if-stale` (a compaction summarizes a long phase mid-flight, so it is the moment unflushed findings are at risk; the staleness test exists only so a session exit does not re-flush a finished run, and both store writes are idempotent), and `SessionStart` runs `capture-resume.sh`, at most two lines about an unfinished run and a stale observation queue. None of them calls a model; all exit 0 on every path. One `PostToolUse` hook ships in the same block and blocks nothing either: `edit-syntax-gate.sh` on `Edit|Write|MultiEdit` parses the file the edit just wrote (`swiftc -parse`, `node --check`, `py_compile` into a temp dir, `JSON.parse`, `bash -n`; Kotlin is skipped, no parser answers inside its 2 s deadline) and hands a syntax error to the model as `additionalContext`; it is silent when a parser is missing or slow, and inert until `editSyntaxGate.enabled` is true. Every registration here is Claude Code's: Codex has a `PostToolUse` event and Copilot CLI a `postToolUse` one, but the installer registers none of the pipeline's hooks on either host, so this gate is Claude Code only for now. The recommended hook block ships at `install/templates/claude-hooks.json`; `multi-agent:setup` offers to merge it into `~/.claude/settings.json`. The other deterministic gates (evidence, consensus, intent, learnings) are invoked by the pipeline phases with per-run arguments (a build-log path, the triage JSON, the free-text input), so they are phase-enforced by contract, not OS-hookable.
 
 Copilot CLI has no `PreToolUse` equivalent, so the secret scan there is workflow-enforced (run as a phase step, not OS-blocked) plus a CI smoke-gate step.

package/pipeline/multi-agent-refs/response-shape.md

@@ -0,0 +1,65 @@
+# Reply shape
+
+> Loaded on demand by `rules/response-shape.md`, which carries only the rules.
+> This file holds the reasons, the word lists and the examples.
+
+A reply is read by someone switching in from other work. The shape below lets
+them act after reading the first and the last line, and find the detail in
+between when they need it.
+
+## Where it applies
+
+| Output | Governed by |
+|---|---|
+| A reply in a conversation, inside or outside a run | this file |
+| Run progress lines | the progress contract (`progress-contract.md`) |
+| Phase 5 reports, PR bodies, Jira and Confluence text | their templates, then the humanizer skill |
+
+The language is `prefs.global.outputLanguage`; nothing here depends on it.
+
+## The rules, with their reasons
+
+1. **Lead with the answer or the next action.** The first line is the one that
+   is always read. Openers that only announce the reply ("Great question",
+   "Let me take a look", "Sure! Here is...", "Harika soru", "Hemen bakıyorum")
+   spend it on nothing.
+2. **Numbered steps, one action each.** A step that hides two actions is the
+   one that gets half done.
+3. **At most five items per group, the rest as a count** ("and 7 more, listed
+   in the report"). This is display only. A finding, a failed check or a
+   verification caveat is never cut to fit; when they do not fit, they go to a
+   file and the reply names it. The verification rule in `CLAUDE.md` wins over
+   this one every time.
+4. **Errors as cause, then fix.** "The build failed because X; fixed by Y" or
+   "...; needs Z from you". No apology paragraph.
+5. **Finished work in concrete terms.** What changed (file, commit, version)
+   and how it was checked (which tests, which counts). "Done" alone is not a
+   report.
+6. **Tangents at the end, one line.** Something noticed on the way is offered
+   ("Also noticed X; want it fixed?"), not woven into the answer.
+7. **Close with what happens next or what the user decides.** Not "Let me know
+   if you need anything else", "Hope this helps", "Başka bir şey olursa
+   söyle".
+
+## When the task wins
+
+- An explanation the user asked for runs as long as it needs, with headings.
+- A destructive or outward-facing step is confirmed before it runs, whatever
+  that does to the shape.
+- Real ambiguity gets one question, not a guess and not a questionnaire.
+- Inside a run, the phase files and their templates decide the format; this
+  file only shapes the conversation around them.
+
+## Example
+
+Too long to act on:
+
+> Great question! I looked into the failing build. It seems there might be an
+> issue with the signing configuration, which could be caused by several
+> things... Let me know if you want me to look further!
+
+Shaped:
+
+> The build fails on signing: the provisioning profile expired on 12.10.
+> Renew it in the developer portal, then rerun `xcodebuild archive`.
+> I can retry the archive once the new profile is installed.

package/pipeline/rules/response-shape.md

@@ -0,0 +1,18 @@
+## Reply shape
+
+For replies in a conversation. Reports, PR, Jira and Confluence bodies keep
+their own templates; the humanizer governs their wording.
+
+- First line: the answer or the next action. No preamble, no recap of the ask.
+- Steps: numbered, one action each. Items: at most five shown, the rest named
+  as a count. That limit shapes the display only; never drop a finding, a
+  failure or a verification note to fit it.
+- Errors: the cause, then the fix. Finished work: what changed, how it was
+  checked.
+- Tangents wait for the end, as one line.
+- Last line: what happens next, or what the user has to decide. No closing
+  pleasantries.
+- An explanation asked for runs as long as it needs; a destructive step is
+  confirmed first; real ambiguity gets one question.
+
+Detail and examples: `$HOME/.claude/multi-agent-refs/response-shape.md`.

package/pipeline/schemas/agent-state.schema.json

@@ -784,7 +784,7 @@
     },
     "plan": {
       "type": ["object", "null"],
-      "description": "The Phase 1 plan as a Todo list, written by plan-todos.sh when prefs.global.planTodos.enabled is true. Shape: plan-todos.schema.json, which plan-todos.sh validates on write; absent when the opt-in is off."
+      "description": "The Phase 1 plan as a Todo list, written by plan-todos.sh when prefs.global.planTodos.enabled is true. Shape: plan-todos.schema.json, which plan-todos.sh validates on write, including the optional todos[].type, the todos[].tdd evidence record, the drift record (the todo ended off-plan) and the needsReplan flag (a step it depends on drifted; it does not start until confirm-replan); absent when the opt-in is off."
     },
     "analysis": {
       "type": ["object", "null"],
@@ -1246,6 +1246,20 @@
             "type": "string",
             "enum": ["fix", "accept", "escalate"]
           },
+          "reworkEscalation": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["escalate", "fromTier", "toTier", "trigger", "reason"],
+            "description": "Written by rework-escalation.mjs --state before the rework dispatch this review sent back: the rung it ran on and why, a refusal included (multi-agent-refs/features/rework-escalation.md).",
+            "properties": {
+              "escalate": { "type": "boolean" },
+              "fromTier": { "type": "string" },
+              "toTier": { "type": "string" },
+              "trigger": { "enum": ["last-round", "still-present", null] },
+              "reason": { "type": "string" },
+              "at": { "type": "string", "format": "date-time" }
+            }
+          },
           "delta": {
             "type": "object",
             "additionalProperties": true,
@@ -2084,6 +2098,22 @@
         "sha": { "type": "string" }
       }
     },
+    "decisions": {
+      "type": "array",
+      "description": "Choices an autopilot run made where an attended run would have asked (multi-agent-refs/features/autopilot-decisions.md): parks (gate-ledger.mjs), blockers lowered to important (review-decision-gate.mjs), rework escalations (rework-escalation.mjs), pickers resolved without asking, split consensus taken on the triage verdict, a date-gate model fallback (decisions-log.mjs add). Written only while the quality gates are active. Rendered, redacted, in the Phase 5 report and appended to the autopilot PR body; an empty or absent list renders nothing.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["what", "why", "costIfWrong", "at", "phase"],
+        "properties": {
+          "what": { "type": "string", "minLength": 1, "maxLength": 200 },
+          "why": { "type": "string", "minLength": 1, "maxLength": 500 },
+          "costIfWrong": { "type": "string", "minLength": 1, "maxLength": 300 },
+          "at": { "type": "string", "format": "date-time" },
+          "phase": { "type": "integer", "minimum": 0, "maximum": 5 }
+        }
+      }
+    },
     "verificationFailed": {
       "type": "object",
       "additionalProperties": false,

package/pipeline/schemas/plan-todos.schema.json

@@ -58,10 +58,111 @@
             "enum": ["Reuse", "Add new", "Modify"],
             "description": "Carried from the analysis Section 14 row this step came from (Locked 16). Phase 2 reads it as an instruction: a Reuse step binds the existing file and must not write a new one. Phase 3 checks the diff against it. Absent when the step did not originate from a Files-to-Add row."
           },
+          "type": {
+            "type": "string",
+            "enum": ["test", "code", "refactor", "docs", "chore"],
+            "description": "Carried from the planning-output task type. A docs or chore todo is exempt from the TDD evidence check (lib/tdd-evidence.mjs)."
+          },
+          "tdd": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "TDD evidence, written by plan-todos.sh tdd-red / tdd-green / complete through lib/tdd-evidence.mjs. complete reads it according to prefs.global.tddEvidence.mode.",
+            "properties": {
+              "red": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["at", "failed", "total"],
+                "description": "The run before the change: at least one failing test, or none when outcome is already-passing.",
+                "properties": {
+                  "at": { "type": "string", "format": "date-time" },
+                  "failed": { "type": "integer", "minimum": 0 },
+                  "total": { "type": "integer", "minimum": 1 },
+                  "tests": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "Failing test ids the todo named; every failing id when it named none; empty when the results carry no names."
+                  },
+                  "testsUnverifiable": {
+                    "type": "boolean",
+                    "description": "The todo named tests (--tests) but the results name no failing test, so the names went unchecked. Recorded in warn and off mode; enforce refuses the run instead."
+                  }
+                }
+              },
+              "green": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["at", "failed", "total"],
+                "description": "The run after the change, with no failures.",
+                "properties": {
+                  "at": { "type": "string", "format": "date-time" },
+                  "failed": { "const": 0 },
+                  "total": { "type": "integer", "minimum": 1 }
+                }
+              },
+              "outcome": {
+                "type": "string",
+                "enum": ["red", "verified", "already-passing", "exempt", "unverified"],
+                "description": "red: RED recorded. verified: RED then GREEN. already-passing: the behaviour existed and one passing run stands for both. exempt: no evidence needed. unverified: completed in warn mode without evidence; Phase 3 notes it."
+              },
+              "reason": {
+                "type": "string",
+                "description": "Why the outcome is already-passing, exempt or unverified."
+              },
+              "selfDeclared": {
+                "type": "boolean",
+                "description": "The exemption came from the todo itself (complete --no-tests), not from its type, the task type or the test policy. Phase 3 notes it."
+              }
+            }
+          },
           "estimatedMinutes": {
             "type": "integer",
             "minimum": 1,
             "description": "Optional Phase 1 estimate for the step. Phase 5 compares against actual duration."
+          },
+          "files": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "The planning-output task's files[], carried by plan-todos.sh set. The drift check compares the files a step changed against it."
+          },
+          "creates": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "The planning-output task's creates[], carried by plan-todos.sh set. The drift check counts these files as planned, like files[]."
+          },
+          "drift": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["outside", "notDone", "at"],
+            "description": "Set by plan-todos.sh drift when this step ended off-plan: the files it changed outside files[] and the number of planned items it did not do.",
+            "properties": {
+              "outside": { "type": "array", "items": { "type": "string" } },
+              "notDone": { "type": "integer", "minimum": 0 },
+              "at": { "type": "string", "format": "date-time" }
+            }
+          },
+          "needsReplan": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["because", "at"],
+            "description": "Set by plan-todos.sh drift on every pending step that depends, directly or transitively, on a step that drifted. Until confirmedAt is set, task-graph.mjs reports the step as waiting (reason needs-replan) and plan-todos.sh start refuses it; confirm-replan sets confirmedAt.",
+            "properties": {
+              "because": {
+                "type": "string",
+                "pattern": "^t[0-9]+$",
+                "description": "The step that drifted."
+              },
+              "at": { "type": "string", "format": "date-time" },
+              "reason": {
+                "type": "string",
+                "description": "What the drift was: files outside the plan, planned items not done, or a stated reason."
+              },
+              "confirmedAt": {
+                "type": "string",
+                "format": "date-time",
+                "description": "When someone confirmed the step's plan still holds."
+              },
+              "note": { "type": "string", "description": "What the confirmation decided." }
+            }
           }
         }
       }

package/pipeline/schemas/planning-output.schema.json

@@ -50,6 +50,52 @@
             "type": "array",
             "items": { "type": "string" },
             "description": "Analysis requirement ids this task implements or tests (BR-<slug>-NN, FG-NN). spec-consistency-gate.mjs reads them, with any id in the title or acceptance criteria, to check that every requirement has a task and a test and that every task traces to a requirement."
+          },
+          "creates": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "description": "Files this task brings into existence. validate-planning.mjs fails a plan in which two tasks create the same file, and warns when a task that edits a created file is not ordered after its creator."
+          },
+          "removes": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "description": "Files or symbols this task deletes, or renames away (the old name). A name with a '/' or a file extension is a file. validate-planning.mjs warns when another task edits, consumes or creates what this task removes."
+          },
+          "produces": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "description": "Interfaces or symbols this task introduces or changes the shape of. validate-planning.mjs warns when a task that consumes one is not ordered after its producer."
+          },
+          "consumes": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "description": "Interfaces or symbols this task calls or relies on without changing them. Paired against other tasks' produces and removes."
+          },
+          "complexity": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["score"],
+            "description": "Grounded size of the task, written by plan-complexity.mjs --write. A task with recommendSplit is split in Phase 1 before approval.",
+            "properties": {
+              "score": { "type": "integer", "minimum": 1, "maximum": 10 },
+              "recommendSplit": {
+                "type": "boolean",
+                "description": "score is above prefs.global.planComplexity.splitAbove."
+              },
+              "factors": {
+                "type": "object",
+                "additionalProperties": false,
+                "description": "The counts the score was built from. fanIn, crossModuleEdges and notIndexed are null when no code graph was available.",
+                "properties": {
+                  "files": { "type": "integer", "minimum": 0 },
+                  "fanIn": { "type": ["integer", "null"], "minimum": 0 },
+                  "modules": { "type": "integer", "minimum": 0 },
+                  "crossModuleEdges": { "type": ["integer", "null"], "minimum": 0 },
+                  "testSurface": { "type": "integer", "minimum": 0 },
+                  "notIndexed": { "type": ["integer", "null"], "minimum": 0 }
+                }
+              }
+            }
           }
         }
       }

package/pipeline/schemas/prefs.schema.json

@@ -577,6 +577,24 @@
             }
           }
         },
+        "reworkEscalation": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Rework model escalation (multi-agent-refs/features/rework-escalation.md). On the last rework round the cap allows, or when review-delta.mjs reports findings still present after a fix, scripts/rework-escalation.mjs moves that one dev dispatch one rung up the model-fallback ladder, as a fresh agent given the findings and the prior report as files. It never escalates against the cost budget (warn or exceeded), never re-upgrades a run that fell back, never reaches fable while modelFallback.fableEnabled is off, and never passes maxTier; a refusal is recorded with its reason.",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "Master switch. On by default: it fires only on the rounds where a failure costs most, moves one rung, and stops at maxTier. false keeps every rework round on the dev dispatch's rung."
+            },
+            "maxTier": {
+              "type": "string",
+              "enum": ["fable", "opus", "sonnet", "haiku"],
+              "default": "opus",
+              "description": "Highest rung an escalation may reach. fable also needs modelFallback.fableEnabled true."
+            }
+          }
+        },
         "modelRouting": {
           "type": "object",
           "description": "Policy-driven model selection. Ships DISABLED and changes no dispatch behaviour while enabled is false. Full contract and the reason `scope` has no host-session member: pipeline/schemas/route-config.schema.json. Written by /multi-agent:route-on, cleared of its on-state (not its rules) by /multi-agent:route-off, reported by /multi-agent:route-status.",
@@ -1151,6 +1169,19 @@
             }
           }
         },
+        "tddEvidence": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Whether completing a plan todo needs a recorded RED run and GREEN run (plan-todos.sh tdd-red / tdd-green). Applies where Phase 2 iterates plan todos (prefs.global.planTodos.enabled); without it Phase 2 walks tasks[] and nothing is recorded. Docs and chore todos, component tasks, test policy none and complete --no-tests are exempt and recorded with a reason.",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": ["off", "warn", "enforce"],
+              "default": "warn",
+              "description": "off: no check. warn: complete warns and records tdd.outcome unverified, which Phase 3 notes. enforce: complete refuses a todo without the evidence."
+            }
+          }
+        },
         "planTodos": {
           "type": "object",
           "additionalProperties": false,
@@ -1163,6 +1194,20 @@
             }
           }
         },
+        "planComplexity": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Grounded complexity score per Phase 1 plan task (pipeline/scripts/plan-complexity.mjs): counted from the files a task touches, their code-graph fan-in, the modules they span and their test surface, never from the planner's opinion. Phase 1 splits a task scoring above the threshold before the plan is approved.",
+          "properties": {
+            "splitAbove": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 10,
+              "default": 7,
+              "description": "A task whose score (1-10) is above this gets recommendSplit and is split before plan approval. Lower it to get smaller tasks; 10 never splits."
+            }
+          }
+        },
         "clarifyAmbiguous": {
           "type": "object",
           "additionalProperties": false,
@@ -1793,6 +1838,52 @@
             "tailLines": 20
           }
         },
+        "editSyntaxGate": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Parse the file an Edit / Write / MultiEdit just wrote and tell the model when it no longer parses: swiftc -parse, node --check, python3 py_compile (bytecode to a temp dir), JSON.parse, bash -n, chosen by extension, each under a 2 s deadline. Kotlin and every other extension are skipped. The hook is pipeline/scripts/edit-syntax-gate.sh (PostToolUse, Claude Code, installed from install/templates/claude-hooks.json). It never blocks: the message arrives as PostToolUse context and the hook exits 0. A parser that is not installed or runs past the deadline means no message.",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": false,
+              "description": "false = the hook is a no-op. true = every edited file with a supported extension is parsed after the edit."
+            }
+          },
+          "default": {
+            "enabled": false
+          }
+        },
+        "mutationProbe": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Phase 3 optional review signal: pipeline/scripts/mutation-probe.mjs makes small textual mutants (a flipped comparison, a negated boolean literal, a swapped + / -, a changed returned constant) on lines the diff added or changed, runs the test command against each in a disposable worktree, and reports every mutant the tests did not catch as a finding. The caller's checkout is never written.",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": false,
+              "description": "false = Phase 3 skips the probe. true = Phase 3 runs it when a test command is known and merges each survivor as an important finding (the tests do not catch that change)."
+            },
+            "maxMutants": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 50,
+              "default": 5,
+              "description": "Upper bound on mutants per run. Each one costs a full test-command run, so the bound is the cost bound."
+            },
+            "timeoutSec": {
+              "type": "integer",
+              "minimum": 5,
+              "maximum": 3600,
+              "default": 120,
+              "description": "Deadline for one test-command run. A mutant whose run times out is reported as timed out, not as a survivor."
+            }
+          },
+          "default": {
+            "enabled": false,
+            "maxMutants": 5,
+            "timeoutSec": 120
+          }
+        },
         "bulkRead": {
           "type": "object",
           "additionalProperties": false,
@@ -2205,7 +2296,27 @@
               "type": ["string", "null", "object"],
               "additionalProperties": { "type": "string" },
               "default": null,
-              "description": "The sub-task type name, or a map from a subtaskRoles entry to this site's type name (\"*\" for any other role), e.g. {\"develop\": \"Development Task\", \"test\": \"Test Task\"}. Null means discover from createmeta (the per-project endpoint, else the classic one) rather than assume a name; when the site has several sub-task types the first is used and the run says so."
+              "description": "The sub-task type name, or a map from a subtaskRoles entry to this site's type name (\"*\" for any other role), e.g. {\"develop\": \"Build Sub-task\", \"test\": \"QA Sub-task\"}. Null means discover from createmeta (the per-project endpoint, else the classic one) rather than assume a name; when the site has several sub-task types the first is used and the run says so."
+            },
+            "subtaskRolesDeclined": {
+              "type": "boolean",
+              "default": false,
+              "description": "true once the person answered the sub-task question with no sub-tasks, so /multi-agent:analysis-jira does not ask again. Written by analysis-story-tree.mjs --save-subtasks none."
+            },
+            "storyPanels": {
+              "oneOf": [
+                { "const": false },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "properties": {
+                    "story": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+                    "criteria": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+                    "other": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }
+                  }
+                }
+              ],
+              "description": "Border colours of a Story's wiki panels, as written by /multi-agent:create-jira and /multi-agent:analysis-jira: story (the user story), criteria (the acceptance criteria), other (every other section). Unset means #d4d39e, #d4a19e and #9eb6d4; a colour left out keeps its default; false writes plain h3. sections."
             },
             "subtaskRoles": {
               "type": "array",
@@ -2256,6 +2367,11 @@
               "type": "string",
               "default": "Relates",
               "description": "The link type between a story and its channel clones, by this site's name."
+            },
+            "dependencyLinkType": {
+              "type": "string",
+              "default": "Blocks",
+              "description": "The link type written from a prerequisite story to the story that depends on it (a `Depends on:` clause in the analysis document), by this site's name. The prerequisite is the link's source."
             }
           }
         },

package/pipeline/scripts/_jsonl.mjs

@@ -0,0 +1,151 @@
+/**
+ * @file _jsonl.mjs  -  read a JSON-lines file one record at a time, by line number.
+ *
+ * Session transcripts are append-only logs that can run to hundreds of
+ * megabytes, are sometimes cut mid-line by a crash, and occasionally carry a
+ * record far larger than the rest (a whole file pasted into a tool result).
+ * So the reader streams, stops at a byte cap, refuses a single line over a
+ * per-line cap without parsing it, and reports every line it could not use
+ * instead of throwing. Line numbers are physical lines of the file, blank ones
+ * included, so `file:line` points at what an editor shows.
+ *
+ * Each yielded row is `{ line, record }` for a parsed object, or
+ * `{ line, reason }` for a line that was not used: `parse` (not JSON),
+ * `not-object` (JSON, but not an object), `oversized` (over the per-line cap)
+ * or `truncated` (the line the byte cap cut through). `stats` is filled in as
+ * the file is read.
+ *
+ * @module pipeline/scripts/_jsonl
+ */
+
+import { createReadStream, statSync } from "node:fs";
+
+export const DEFAULT_MAX_BYTES = 256 * 1024 * 1024;
+export const DEFAULT_MAX_LINE_BYTES = 8 * 1024 * 1024;
+
+/**
+ * @param {string} path
+ * @param {{maxBytes?:number, maxLineBytes?:number, stats?:object}} [opts]
+ */
+export async function* readJsonl(path, opts = {}) {
+  const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+  const maxLineBytes = opts.maxLineBytes ?? DEFAULT_MAX_LINE_BYTES;
+  const stats = opts.stats ?? {};
+  Object.assign(stats, {
+    lines: 0,
+    malformed: 0,
+    oversized: 0,
+    truncated: false,
+    unreadable: false,
+    bytes: 0,
+  });
+
+  let size;
+  try {
+    const st = statSync(path);
+    if (!st.isFile()) throw new Error("not a regular file");
+    size = st.size;
+  } catch {
+    stats.unreadable = true;
+    return;
+  }
+  const capped = size > maxBytes;
+  stats.bytes = Math.min(size, maxBytes);
+  if (stats.bytes === 0) return;
+
+  const classify = (n, text) => {
+    let value;
+    try {
+      value = JSON.parse(text);
+    } catch {
+      stats.malformed++;
+      return { line: n, reason: "parse" };
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      stats.malformed++;
+      return { line: n, reason: "not-object" };
+    }
+    return { line: n, record: value };
+  };
+
+  // A line becomes {n, text} or {n, oversized}. Bytes of the current line are
+  // kept only while it is within the cap; past it they are dropped as they
+  // arrive, so a single huge line costs one chunk of memory, not its length.
+  // One line is held back so the last one is known before it is classified:
+  // when the byte cap cut the file, that line is incomplete.
+  const NL = 0x0a;
+  let parts = [];
+  let partBytes = 0;
+  let over = false;
+  let n = 0;
+  let held = null;
+  const finish = () => {
+    n++;
+    let line;
+    if (over) line = { n, oversized: true };
+    else {
+      let text = Buffer.concat(parts, partBytes).toString("utf8");
+      if (text.endsWith("\r")) text = text.slice(0, -1);
+      line = Buffer.byteLength(text) > maxLineBytes ? { n, oversized: true } : { n, text };
+    }
+    parts = [];
+    partBytes = 0;
+    over = false;
+    return line;
+  };
+  const emit = (line) => {
+    if (line.oversized) {
+      stats.oversized++;
+      return { line: line.n, reason: "oversized" };
+    }
+    return line.text.trim() ? classify(line.n, line.text) : null;
+  };
+  const append = (buf) => {
+    if (over || buf.length === 0) return;
+    if (partBytes + buf.length > maxLineBytes + 1) {
+      over = true;
+      parts = [];
+      partBytes = 0;
+      return;
+    }
+    parts.push(buf);
+    partBytes += buf.length;
+  };
+
+  const input = createReadStream(path, { start: 0, end: stats.bytes - 1 });
+  try {
+    for await (const chunk of input) {
+      let from = 0;
+      for (let at = chunk.indexOf(NL); at !== -1; at = chunk.indexOf(NL, from)) {
+        append(chunk.subarray(from, at));
+        from = at + 1;
+        const line = finish();
+        if (held) {
+          const row = emit(held);
+          if (row) yield row;
+        }
+        held = line;
+      }
+      append(chunk.subarray(from));
+    }
+  } catch {
+    stats.unreadable = true;
+  }
+  if (partBytes > 0 || over) {
+    const line = finish();
+    if (held) {
+      const row = emit(held);
+      if (row) yield row;
+    }
+    held = line;
+  }
+  stats.lines = n;
+  if (!held || (!held.oversized && !held.text.trim())) return;
+  if (capped) {
+    stats.truncated = true;
+    yield { line: held.n, reason: "truncated" };
+    return;
+  }
+  const row = emit(held);
+  if (row) yield row;
+}