@mmerterden/multi-agent-pipeline 16.27.0 → 16.29.0

package/pipeline/multi-agent-refs/features/doctor.md

@@ -0,0 +1,197 @@
+# doctor - the check registry
+
+Every check `/multi-agent:doctor` can report has a `### <id>` heading here, and
+`doctor.mjs --list-checks` prints exactly the same set. The equality is checked
+in both directions by `smoke-doctor.sh`: a check that ships without an entry
+cannot be released, and an entry whose check was deleted cannot linger as orphan
+prose. That is the mechanism that keeps this file from rotting into a list of
+things the tool used to do.
+
+## What the exit code means
+
+| Code | Meaning |
+|---|---|
+| 0 | healthy - nothing above INFO |
+| 1 | degraded - at least one WARN, no BLOCK |
+| 2 | blocked - at least one BLOCK |
+| 3 | usage error |
+| 4 | indeterminate - the installed layout could not be resolved, so nothing was checked |
+
+4 exists so that "I could not look" never borrows the exit code of "I looked and
+it is fine". A consumer that treats 0 as healthy would otherwise read a broken
+resolver as a clean bill.
+
+## What BLOCK means, exactly
+
+**A state in which a run will fail or leak. Not a state in which it will merely
+be worse.** Without a closed definition "blocked" grows until nobody respects
+exit 2, so only five checks can produce it: `install-present`, `script-surface`,
+`state-writable`, `prefs-valid` and `embedded-credentials`. Every other check
+tops out at WARN however bad it looks.
+
+## Who calls it, and what they do with the code
+
+| Caller | When | On exit 2 |
+|---|---|---|
+| `/multi-agent:setup` | before the first question, and again at the end | the closing run is the evidence for or against "setup complete" |
+| `/multi-agent:update` | after the install | report that the update left a state a run will fail from, rather than "updated" |
+| `/multi-agent:sync` | step 0 | **stop.** Syncing a blocked install copies one fault onto five surfaces, and the copies are what people then debug |
+
+`/multi-agent:sync` stops on exit 4 as well: the layout did not resolve, so
+nothing was checked, and syncing from an unknown state is worse than not syncing
+at all. Exit 1 never stops anything - a degraded install still syncs correctly,
+and a gate that blocked on every warning would be routed around within a week.
+
+## The four severities
+
+| Severity | Meaning |
+|---|---|
+| BLOCK | a run will fail or leak |
+| WARN | a run will work and be worse: a degraded capability, a stale copy, a rejected credential |
+| INFO | a capability the user chose not to enable; nothing to fix |
+| SKIP | not checked, and why |
+
+`SKIP` is printed in the same list, in the same position, and the summary always
+carries its count (`... 2 not checked, 15 checks`). Absence is a finding: a run
+without `--probe` exits 0 **and** prints `SKIP credential-liveness`, so "healthy"
+and "not looked at" are never the same output.
+
+The INFO / WARN boundary is already decided in `lib/credential-inventory.sh` and
+this tool only renders it: an unmapped key is INFO because it is a capability the
+user chose not to enable, while `auth-rejected`, `malformed` and
+`tier-1-no-grant` are WARN because the configuration made a claim the service
+refused. **A missing optional capability is information; a mapped credential the
+service rejected is a warning. The difference is whether the configuration
+asserted anything.**
+
+## The line shape
+
+```
+<SEV> <id>  -  <what is wrong>  -  <single imperative step>
+```
+
+The third field is one step, and its first word comes from a closed list:
+`run`, `set`, `map`, `revoke`, `install`, `remove`, `free`, `export`, `merge`,
+`record`, `re-run`. `consider`, `may want` and `should probably` are refused by
+the gate. One problem, one step: a reader with five suggestions does nothing.
+
+## It recommends, it never fixes
+
+Nothing here rewrites a remote URL, edits `settings.json` or touches a token.
+A remote whose URL carries a token may be the only credential that repo has, the
+remote may be a mirror a script depends on verbatim, and doctor can run inside a
+checkout the user does not own. Silent repair breaks all three.
+
+For an embedded credential the honest single step is **not** "hide it". A token
+that reached `.git/config` is already burned: it is in the shell history and
+readable by anything that can read the working tree. The step is to revoke it at
+its host; everything after that is behind `--explain`.
+
+---
+
+## Checks
+
+### install-present
+
+The installed tree exists and carries the subtrees a run reads: `commands/`,
+`multi-agent-refs/`, `scripts/`, `lib/`, `schemas/`. BLOCK when any is missing -
+a run cannot start without them.
+
+### install-version
+
+The installed `.pipeline-version` matches the package version resolved from the
+checkout or the published package. WARN on a mismatch: the run works, it just
+is not the version the user thinks they have.
+
+### script-surface
+
+Every script a shipped command names by path exists in the installed tree. BLOCK:
+the failure lands mid-run, at the call, with the phase already half done.
+
+### skill-siblings
+
+Every command has its copies in the host trees this machine installs. WARN, never
+BLOCK: an unsynced host is a fact about the machine, and `skill-siblings.mjs`
+itself reports the installed layout as "authored side not checked" rather than
+claiming a repo verdict it cannot reach.
+
+### state-writable
+
+`$HOME/.claude/logs/multi-agent` exists or can be created, and a file can be
+written there. BLOCK: a run that cannot record its state cannot be resumed,
+reported or priced, and it discovers this at Phase 0 after the pickers.
+
+### prefs-valid
+
+`multi-agent-preferences.json` parses and satisfies `schemas/prefs.schema.json`.
+BLOCK: Phase 0 reads it before anything else, and a malformed file fails the run
+after the user has already answered the pickers.
+
+### identity
+
+A git identity resolves for the account the run would commit as. WARN: the run
+reaches Phase 6 and stops there.
+
+### hook-coverage
+
+The blocking `PreToolUse` gates from `templates/claude-hooks.json` are present in
+`settings.json`. WARN. SKIP when the template is not installed - which was the
+permanent state until the installer began copying `templates/`, and is exactly
+the case this severity exists to make visible.
+
+### credential-mapping
+
+Which logical keys are mapped, and whether each mapped value is well formed.
+Unmapped is INFO. Malformed is WARN.
+
+### credential-liveness
+
+One cheap authenticated request per mapped credential. WARN on `auth-rejected`,
+`tier-1-no-grant` or `unreachable` - but with **different steps**, because a
+refused credential and a host that never answered need different actions.
+`credential-inventory.sh` already draws that line ("unreachable - no response at
+all - on a corporate host, almost always the VPN"), and telling someone to
+re-onboard a token that was never the problem is the exact failure the keychain
+rules warn about one layer up. **SKIP unless `--probe` is passed**, and the
+skip is printed, because a network check is the user's decision to spend.
+
+### embedded-credentials
+
+A token in a git remote URL or a tracked config file. BLOCK: this one leaks
+rather than fails.
+
+The report carries the repo path, the config key, the **host**, a shape label and
+a length bucket. Never the value, and not the prefix either: `ghp_` plus a length
+is already a fingerprint, and this line is printed to a terminal that is often
+shared, which is the whole reason the check exists. The URL is parsed inside a
+`python3` heredoc reading stdin, so no shell variable ever holds it.
+
+### task-tools
+
+Whether this session's model carries `TaskCreate` / `TaskUpdate`. Claude Code
+provides them by default only on Claude 3.x, Opus 4 through 4.7, Sonnet 4 through
+4.6 and Haiku 4.5; on any newer model they are absent unless the user opts in.
+INFO, with the opt-in as the step.
+
+A script cannot answer this - only the agent knows its own tool list - so the
+caller passes `--task-tools=yes|no` and the default is SKIP. Reporting "absent"
+from a script that never looked would be the same defect this check is about.
+
+### mcp-registration
+
+Whether `multi-agent-toolkit` is registered as an MCP server. INFO when it is
+not: the tools it provides are optional and a run without them is smaller, not
+wrong.
+
+**Registered is not the same as working.** With `--probe` the server is started
+and its tools counted; serving none is WARN. Without `--probe` this reports what
+is configured, and says so. The distinction is not theoretical: a half-extracted
+package in the npx cache left the server dying on `Cannot find module` at
+startup, which the client surfaces only as `CONNECTION_CLOSED`, and a check that
+read the registration and stopped would have called that healthy.
+
+### disk-space
+
+Free space on the volume holding `$HOME`. WARN under 2 GB: a worktree plus a
+build is the largest thing a run writes, and ENOSPC mid-run corrupts the state
+file it was writing at the time.

package/pipeline/multi-agent-refs/features/jira-context.md

@@ -0,0 +1,101 @@
+# Related-issue context at intake
+
+A development sub-task is often filed with no description of its own. The
+requirement sits on the parent, and the rest of the picture  -  the analysis, the
+test scope  -  sits on the sibling sub-tasks beside it. The fetcher already read
+the parent; it did not read the siblings, so a board that keeps its analysis in a
+separate sub-task handed the pipeline an empty task.
+
+`issue-fetcher.sh` now reads those siblings and exposes them as
+`descriptor.relatedIssues[]`.
+
+## What it costs
+
+One search request, and only when the issue has a parent:
+
+```
+GET /rest/api/2/search?jql=parent="<PARENT>"&fields=summary,issuetype,status,description&maxResults=20
+```
+
+An issue with no parent has no siblings, so the lookup is skipped entirely and
+that run pays nothing. The count does not grow with the number of siblings: the
+issue's own `subtasks` field lists ITS children rather than its siblings, and the
+parent's lists siblings without their descriptions, so either of those shapes
+would cost one GET per sibling. `smoke-jira-context.sh` counts the requests, so
+this stays a measurement rather than a claim.
+
+The request lands before the maturity verdict reaches the user, which is one
+extra round trip on the intake path. `jiraContext.enabled: false` is the way out
+when latency matters more than the context.
+
+## Shape
+
+```json
+"relatedIssues": [
+  {
+    "key": "PROJ-1002",
+    "relation": "sibling",
+    "type": "Sub-task",
+    "status": "Done",
+    "summary": "...",
+    "description": "...",
+    "truncated": false
+  }
+]
+```
+
+`type` is carried through verbatim from Jira and is never matched against in
+code. Boards name their sub-task types differently and the query does not need
+to know: `parent = <key>` returns all of them.
+
+Siblings that carry a description are ordered first, so `maxItems` drops the
+empty ones rather than the useful ones. An empty sibling is still listed  -  its
+key, type and status are information  -  with an empty `description`.
+
+## Settings
+
+`prefs.global.jiraContext`:
+
+| Key | Default | Effect |
+|---|---|---|
+| `enabled` | `true` | `false` skips the search entirely |
+| `maxItems` | `6` | Hard cap; `0` behaves like `enabled: false` |
+| `maxCharsPerItem` | `1200` | Per-sibling truncation, marked `truncated: true` |
+
+Worst case payload is `maxItems x maxCharsPerItem`, next to the 4000-character
+cap on the issue's own description.
+
+## Maturity
+
+One new code, `description_empty_sibling_available`, and it fires narrowly: the
+issue's own description is empty, the parent's is empty or unreachable, AND a
+sibling carries content. Today that combination produces the hard
+`description_empty` blocker; it becomes a warning instead, the same downgrade
+`description_empty_parent_available` already makes one level up.
+
+The narrowness is deliberate. `score` is `100 - 40*blockers - 10*warnings`, and
+the picker continues silently only at `score >= 90`, so a warning that fired
+whenever an issue merely HAD siblings would cost ten points on every parented
+issue and turn a silent intake into a question across the board.
+
+## Where it goes
+
+The descriptor is carried verbatim into the picker state as `issueRef`, and the
+bridge copies `relatedIssues` onto `agent-state.json` when it is non-empty.
+
+Persisting it is the point: `/multi-agent:resume` rebuilds context from durable
+artefacts and never from the conversation, so an intake-only enrichment would be
+gone by the first resume. The task's own `description` and `maturity` are still
+not persisted, which is a known asymmetry rather than an oversight  -  this
+change did not widen the bridge beyond the one field it needed.
+
+Sibling text is added as its own labelled block. It never replaces the working
+description the way an accepted `parentDescription` does: substituting it would
+erase the provenance that Phase 2's parent-story scope-drift check reads.
+
+## Not included
+
+Following the parent's `issuelinks` in a second search. A linked bug can be the
+whole requirement while a linked test-execution record is noise, and the fetcher
+cannot tell them apart, so the scope stops at sub-tasks. There is no setting for
+it: a switch that does nothing is worse than an absent one.

package/pipeline/multi-agent-refs/features/model-fallback.md

@@ -83,7 +83,7 @@ predate this field still get the second downgrade step):
   "premiumTierUntil": null,
   "fallbackModel": "sonnet",
   "floorModel": "haiku",
-  "fableEnabled": true,
+  "fableEnabled": false,
   "onDispatchError": true
 }
 ```
@@ -91,7 +91,7 @@ predate this field still get the second downgrade step):
 | Field | Meaning |
 |---|---|
 | `enabled` | Master switch. `false` = always dispatch the persona's `preferredModel`, fail loudly on error. |
-| `modelFallback.fableEnabled` | Whether the `fable` rung exists at all on Claude Code. `false` starts every `preferredModel: fable` persona on `opus`. See "Turning the fable rung off" below. |
+| `modelFallback.fableEnabled` | Whether the `fable` rung exists at all on Claude Code. **Ships `false`.** `false` starts every `preferredModel: fable` persona on `opus`; set it to `true` to opt the top rung back in. A cost control that defaults to on is not a control. See "Turning the fable rung off" below. |
 | `premiumTierUntil` | ISO date (`YYYY-MM-DD`) or `null`. When set and today is **after** this date, every `preferredModel` dispatch is downgraded to `fallbackModel` unless the user re-confirms (see Date gate). Use when the top tier is included in a plan only until a known date. |
 | `fallbackModel` | Target of the first downgrade step. Default `sonnet` (the next tier below opus). |
 | `modelFallback.floorModel` | Last-resort tier when `fallbackModel` also fails to dispatch. Default `haiku`. Set to the same value as `fallbackModel` (or `null`) to disable the second step and halt after one downgrade. |

package/pipeline/multi-agent-refs/phases/phase-0-init.md

@@ -275,11 +275,8 @@ Scan `$HOME` (maxdepth 2) for project markers (`.xcodeproj`, `Package.swift`, `b
      | grep -v -E '(feature/|bugfix/|fix/|hotfix/|chore/)'
    ```
 6. Sort: `develop*` first, then `release/*`, then `main`/`master`. Surface through the
-   **native picker** per `picker-contract.md` (`AskUserQuestion` on Claude Code,
-   `ask-choice.sh` on Copilot CLI) - `question` + `description` in `outputLanguage`,
-   `label` = the branch name verbatim (a proper noun, never translated) with the recent
-   branch first and marked `(Recommended)`. The ASCII sketch
-   below is what the options carry, not a menu to print:
+   **native picker** per `picker-contract.md`, recent branch first and marked
+   `(Recommended)`:
 
    ```
    header: "Base branch"
@@ -298,9 +295,14 @@ nothing surfaced it. `phase0-exit-gate.mjs` now refuses to close Phase 0 unless
 `agent-state.json` carries `baseBranch` and `baseFetchStatus`, so a skipped picker is a
 gate failure rather than a silent default.
 
+One row is a normal outcome of the rule-5 filter and is **still asked** - see
+`picker-contract.md` "A single candidate is still a question".
+
 This holds in every mode. A Short run skips the *LLM* phases (Analysis, Planning); it
-does not skip Phase 0's pickers. Autopilot resolves them to their defaults without prompting,
-which still writes the fields - it does not leave them unset.
+does not skip Phase 0's pickers. Autopilot resolves them without prompting, which still
+writes the fields. For the base branch it reads `recentBranches[{projectKey}]` (most
+recent inside the TTL, still on the remote) before the rule-6 order, recording which
+fired in `state.baseBranchSource`.
 
 **TTL filter for recent branches**:
 

package/pipeline/multi-agent-refs/phases/phase-1-analysis.md

@@ -109,7 +109,7 @@ back. "Copy X and rename it" is the reuse answer, not a hint  -  name X's files.
 
 #### Step 1.5  -  External Context Injection (`state.contextLinks[]`)
 
-Phase 0 Step 1b catalogued every typed external link from the task description into `state.contextLinks[]`. Phase 1 dispatches each entry to its matching fetcher (crashlytics, fortify, graylog, swagger, confluence, figma, generic-doc) and prepends results under a **Referenced External Sources** section in the analysis prompt  -  so the agent doesn't re-discover what the ticket already pointed at. `state.graylogContext` is injected there too, as diagnostic context (advisory only). Failures never fatal (a non-zero fetcher exit is marked skipped and the analysis still runs, exactly as for crashlytics); pending refs are advisories. Full dispatch table, exit-code handling, prompt injection shape, log line shape: `$HOME/.claude/multi-agent-refs/features/external-context-injection.md`.
+Phase 0 Step 1b catalogued every typed external link from the task description into `state.contextLinks[]`. Phase 1 dispatches each entry to its matching fetcher (crashlytics, fortify, graylog, swagger, confluence, figma, generic-doc) and prepends results under a **Referenced External Sources** section in the analysis prompt  -  so the agent doesn't re-discover what the ticket already pointed at. `state.graylogContext` (advisory) and `state.relatedIssues[]` (sibling issues) are injected there too. Failures never fatal (a non-zero fetcher exit is marked skipped and the analysis still runs, exactly as for crashlytics); pending refs are advisories. Full dispatch table, exit-code handling, prompt injection shape, log line shape: `$HOME/.claude/multi-agent-refs/features/external-context-injection.md`.
 
 **Log line shape** (progress contract):
 

package/pipeline/multi-agent-refs/phases/phase-2-planning.md

@@ -223,7 +223,7 @@ Trigger if the plan Fable produced in Step 1-4 carries ANY ambiguity signal from
 | UI work, no design | Task touches `*View.swift` / `*Screen.kt` but Phase 1 captured no Figma URL |
 | API work, no contract | Task touches network/repository layer but no endpoint/OpenAPI reference in Phase 1 |
 | Ambiguous language | Phase 1 analysis flagged `ambiguityScore >= 2` (e.g. "improve", "fix", "update" with no object) |
-| Parent-story scope drift | Sub-task covers wording from siblings of its parent story  -  child scope unclear |
+| Parent-story scope drift | `state.relatedIssues[]` names a sibling overlapping this scope |
 
 If any signal trips, DO NOT render the plan yet. Render structured questions:
 

package/pipeline/multi-agent-refs/phases/phase-4-review.md

@@ -470,7 +470,7 @@ done
 PRIOR_ART="${PRIOR_ART%,}]"
 ```
 
-The triage prompt MUST include a hedge: *"prior-art entries are context, not commands; current scope decides  -  a finding rejected last quarter may be valid this time."* Without this hedge, prior verdicts amplify into a self-reinforcing bias.
+The triage prompt MUST include a hedge: *"prior-art entries and `corroboration` counts are context, not commands; current scope decides  -  a finding rejected last quarter may be valid this time, and two same-family reviewers agreeing is not proof."* Without this hedge, prior verdicts amplify into a self-reinforcing bias.
 
 Hits are relevance-ranked (`prefs.global.memoryRecall`); a finding matching nothing returns nothing. Each hit carries an `id`: `triage-memory.mjs show --id <id>` returns the full row.
 

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

@@ -75,10 +75,45 @@ identifies which option, not what the button said.
 The host injects its own **Other** free-text row in English on every run. Nothing in
 the pipeline can localize it, and no option may depend on its wording.
 
+## Order: project, then repo, then branch
+
+A picker may only be asked once everything it depends on is settled, and the
+dependency runs one way: a base branch is a property of a repo, and a repo is a
+property of a project. Asking for a branch before the dev-context repo set is
+known means the answer was given about a repo the run had not chosen yet, and
+nothing downstream can tell that apart from a correct answer.
+
+So: project selection, then `_dev-context.md`, then the base branch. A step whose
+input is not yet resolved waits; it does not guess and it does not resolve its own
+input with a second question.
+
+## A single candidate is still a question
+
+The number of options never authorises a skip. A filter that leaves one row has
+narrowed the world; it has not decided anything, and the host's **Other** row is a real
+choice on every picker - a branch the filter excluded, an account the probe missed, a
+repo git does not know about. "There was only one option, so I picked it" is a skipped
+picker, and announcing the pick in prose first is the same skip with a sentence in front
+of it.
+
+This is the failure that is hardest to see afterwards, because the transcript reads like
+a decision was made. Only the picker's absence records that the user was never asked.
+
 ## Autopilot / non-interactive contract
 
 In autopilot, `ask_choice` resolves to `default` (or the safe first option) without prompting - identical to how the native gates auto-proceed today. A picker is only surfaced for genuinely ambiguous or destructive decisions, matching the maturity-check model.
 
+**Memory outranks the default.** Where the pipeline has recorded what this user chose
+last time for this project - `prefs.global.recentBranches[{projectKey}]` is the one that
+exists today - autopilot resolves from that record first, and only falls back to the
+option order when the record is empty, stale past its TTL, or names something that no
+longer exists. A remembered choice is evidence about this user and this repo; an option
+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
+asked anything, so the only thing that keeps it accountable is being readable afterwards.
+
 ## 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, fail-open on internal error, and never execute the inspected command. Two 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, since every durable write used to live in Phase 7 - the phase a run is least likely to reach) 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), and `SessionStart` runs `capture-resume.sh`, at most two lines about an unfinished run and a stale observation queue. Neither calls a model; both 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.

package/pipeline/multi-agent-refs/readiness-review.md

@@ -12,7 +12,7 @@ Instruction prose here is English. The verdict shown in chat and the comment bod
 - With no argument: offer the picker - review-jira reuses the `jira` command's issue list (`jira/SKILL.md` JQL, assignee=currentUser, open); review-issue reuses the `issue` command's list (`gh issue list`). Single-select (one item reviewed per run; re-run for more).
 
 ## Step 2 - fetch + base maturity
-Run `$HOME/.claude/lib/issue-fetcher.sh` (the same fetcher Phase 0 uses). It returns a descriptor with `title`, `type`, `status`, `description`, and `maturity = { score (0..100), blockers[], warnings[], summary }`. Reuse that maturity verbatim as the baseline; never re-fetch through MCP.
+Run `$HOME/.claude/lib/issue-fetcher.sh` (the same fetcher Phase 0 uses). It returns a descriptor with `title`, `type`, `status`, `description`, `relatedIssues[]` (the parent's other sub-tasks), and `maturity = { score (0..100), blockers[], warnings[], summary }`. Reuse that maturity verbatim as the baseline; never re-fetch through MCP.
 
 ## Step 3 - readiness rubric (extends maturity)
 Maturity is generic; add these pipeline-readiness dimensions by reading the fetched `title` + `description` (no invention - only judge what is written). Each is `pass` / `gap`:

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

@@ -32,7 +32,7 @@ Visual mechanism per CLI:
 
 | CLI | What the agent calls at every phase boundary |
 |---|---|
-| **claude-code** | `TaskCreate({subject, activeForm})` then `TaskUpdate({status, activeForm})`. Native sticky widget; ⏺ tiles, spinner header. |
+| **claude-code** | `TaskCreate({subject, activeForm})` then `TaskUpdate({status, activeForm})`. Native sticky widget; ⏺ tiles, spinner header. **Not in every session** - see below. |
 | **copilot** | Inline call: `bash phase-tracker.sh render`. The bordered ANSI card lands as the last tool result in the chat. |
 | **codex** | The native `update_plan` tool: one plan step per phase, `status: pending \| in_progress \| completed`. Rewrite the whole step list on each boundary  -  the tool takes the full plan, not a delta. |
 | **generic** (plain shell, Git Bash, WSL, tmux) | Same bash render  -  the bordered ANSI card prints to terminal stdout in place. |
@@ -41,6 +41,10 @@ Visual mechanism per CLI:
 
 **Claude Code only**: in addition, `TaskCreate` / `TaskUpdate` native tool calls → the sticky widget pins the phase stack in the user's view.
 
+**The task tools depend on the MODEL, not the CLI version.** Claude Code provides `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList` and `TodoWrite` by default only on Claude 3.x, Opus 4 through 4.7, Sonnet 4 through 4.6 and Haiku 4.5; on any newer model it leaves them out unless the user opts in. That default arrived in Claude Code v2.1.268, and this contract was written when the tools were universal, so nothing noticed the change: a run wrote its tracker state correctly, advanced every phase, and drew nothing for the whole run.
+
+So the branch is taken by the agent, which knows its own tool list, and never by the shell, which cannot see it. Without the tools the bordered card IS the widget and has to be reprinted inside the reply at every boundary, exactly as on Copilot CLI. Say once, in `outputLanguage`, that the native widget returns with `CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude` (or `claude --allowedTools TaskCreate`); a user staring at a missing widget needs the command, not the diagnosis. A subagent inherits the session's tool set even when it runs a different model, so this is a session-level fact and not a per-phase one.
+
 ### Codex specifics
 
 Two constraints on `update_plan`, both of which fail quietly if ignored:

package/pipeline/preferences-template.json

@@ -63,7 +63,7 @@
       "premiumTierUntil": null,
       "fallbackModel": "sonnet",
       "floorModel": "haiku",
-      "fableEnabled": true,
+      "fableEnabled": false,
       "onDispatchError": true
     },
     "costBudget": {

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

@@ -76,6 +76,11 @@
       "type": "string",
       "description": "PR target branch (e.g. develop, main)."
     },
+    "baseBranchSource": {
+      "type": "string",
+      "enum": ["asked", "input", "remembered", "default"],
+      "description": "How baseBranch was decided. asked = the user answered the Step 3 picker; input = it arrived with the task reference; remembered = autopilot took the most recent entry in prefs.global.recentBranches still inside the TTL and still on the remote; default = autopilot fell back to the develop/release/main sort order. An autopilot run cannot be asked anything, so recording which rule fired is what keeps it readable afterwards."
+    },
     "remoteType": {
       "type": "string",
       "enum": ["github", "bitbucket"],
@@ -104,6 +109,25 @@
       "type": ["string", "null"],
       "description": "Set when a phase halts on a hard error (validator failed twice, no subagent returned, dispatch error past fallback, lock irrecoverable). Format '<phase>:<cause>'. Surfaced to the user and cleared on successful resume. See operations.md 'Halt visibility'."
     },
+    "relatedIssues": {
+      "type": "array",
+      "maxItems": 20,
+      "description": "Jira issues fetched alongside the task at intake: the other sub-tasks under this issue's parent, where a board keeps the analysis and the test scope. NOT the same field as siblings[] below, which is read-only sibling REPOS. Written by the picker bridge from descriptor.relatedIssues; read by Phase 1 as ground truth and by Phase 2's parent-story scope-drift check. Durable on purpose: /multi-agent:resume rebuilds context from artefacts, never from the conversation, so intake-only enrichment would vanish on the first resume. The task's own description and maturity are still NOT persisted here, which is a known asymmetry, not an oversight.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["key", "relation"],
+        "properties": {
+          "key": { "type": "string" },
+          "relation": { "type": "string", "enum": ["sibling"] },
+          "type": { "type": "string" },
+          "status": { "type": "string" },
+          "summary": { "type": "string" },
+          "description": { "type": "string" },
+          "truncated": { "type": "boolean", "default": false }
+        }
+      }
+    },
     "siblings": {
       "type": "array",
       "maxItems": 10,