@mmerterden/multi-agent-pipeline 20.23.2 → 20.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "20.23.2",
+  "version": "20.25.0",
   "description": "6-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/agents/task-clarifier.md

@@ -116,7 +116,7 @@ pipeline/scripts/log-metric.sh "$TASK_ID" 0 clarify.call \
   tokens_in=$TI tokens_out=$TO
 ```
 
-Cost expectation on Haiku (input ~1.5k tokens issue body, output ~400 tokens JSON): **~$0.0025 per call**. Off by default; flip on for teams burned by ambiguity-driven rework.
+Cost expectation on Haiku (input ~1.5k tokens issue body, output ~400 tokens JSON): **~$0.0004 per call**. Off by default; flip on for teams burned by ambiguity-driven rework.
 
 ## Pattern citation
 

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

@@ -29,6 +29,7 @@ Contract, severities and reasoning:
 - An open `EKLENECEK`/`TBD` marker or an open Section 20 row stops planning with exit 4. Resolve them with `/multi-agent:analysis-resolve` first.
 - The epic must already exist: stories are linked to it, never an epic created. On Server/Data Center the Epic Link field is discovered from the site; when none is found the stories are created unlinked and the writer says so.
 - Channel clones (`issueTree.cloneByChannel`) carry their own labels and are searched like stories, so a re-run never doubles them or their links.
+- A requirement row with `Depends on: <ids>` links the stories, prerequisite first, as `issueTree.dependencyLinkType` (default Blocks). A cycle, or a prerequisite no story covers, makes the plan `incomplete`; fix the document, not the links.
 - Story bodies hold only document text. A body warning (no user story, fewer than 2 criteria, no negative criterion) is a gap in the document; fix the document, not the ticket.
 
 ## Phase 1 - Plan, offline
@@ -64,6 +65,7 @@ what makes a preview meaningful:
 - the coverage verdict **on its own line**, and the consistency verdict below it
 - every field beside the pref key it came from, so a wrong setting shows here
   rather than in Jira afterwards
+- the dependency edges between stories, prerequisite first
 - the write count
 - every story's full description, as it will be written, with its body
   warnings; `--brief` gives the one-line-per-node view
@@ -106,7 +108,7 @@ A run that could not be checked is allowed. One that looks checked when it was
 not is the defect, so the approval has to name it and a plain "Approve" must not
 be reachable.
 
-`incomplete` prints its uncovered and invented ids before the question. An
+`incomplete` prints its uncovered and invented ids, and any dependency cycle or uncovered prerequisite, before the question. An
 invented id means the plan cites something the document does not define - treat
 that as a defect in the plan, not a warning to click past.
 
@@ -156,7 +158,7 @@ missing-attachment warning.
 
 ## Phase 5 - Report
 
-Keys created, keys skipped, the epic linked (or none), the coverage verdict, and the ledger path. If the
+Keys created, keys skipped, the epic linked (or none), the dependency links written, the coverage verdict, and the ledger path. If the
 verdict was `unverifiable`, say that in the report too - not only at approval
 time, because the report is what gets pasted elsewhere.
 

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

@@ -0,0 +1,61 @@
+---
+description: "Bump one dependency, fix only what the bump broke, review, open a PR; rolls back past the fix round cap. SwiftPM, Gradle, npm, pip. Use when a library needs updating."
+description-tr: "Tek bağımlılığı yükseltir, yalnızca yükseltmenin kırdığını düzeltir, review edip PR açar; düzeltme turu sınırında geri alır. SwiftPM, Gradle, npm, pip. Bir kütüphaneyi güncellemek için kullanılır."
+argument-hint: "[package[@version]] [--major]  -  no package opens a picker over the outdated candidates; --major allows a breaking bump"
+parameters: [{"name":"package","kind":"text"},{"name":"--major","kind":"flag"}]
+gui: form
+destructive: false
+confirm: none
+---
+
+# multi-agent deps  -  bump one dependency and fix what it broke
+
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
+**Input**: $ARGUMENTS
+
+> **Language (read FIRST)**: read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` renders `question`, option `label`s and `description`s in `outputLanguage`; only `header` stays English (<=12-char chip). Commit messages and branch names stay English. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
+
+The normal pipeline with a fixed task. Read `$HOME/.claude/multi-agent-refs/features/dep-bump.md` first: it is the contract for every step below (run shape, scope rule, rollback). `dep-bump.mjs` does every deterministic step; never edit a version string or a lockfile by hand.
+
+## Steps
+
+1. **Repo and settings.** Resolve the repo as `/multi-agent` does for a free-text task (`_account-picker.md`, `_repo-picker.md`). Then:
+   ```bash
+   node "$HOME/.claude/scripts/dep-bump.mjs" config            # depBump.maxFixRounds, depBump.queryRegistry
+   node "$HOME/.claude/scripts/dep-bump.mjs" detect --dir "$REPO"
+   ```
+   No ecosystem detected: say so and stop.
+
+2. **Candidates.**
+   ```bash
+   node "$HOME/.claude/scripts/dep-bump.mjs" list --dir "$REPO" [--registry]   # --registry when queryRegistry is true
+   ```
+   Show `registry.note` and every per-package `note`: an offline listing is reported as offline, never as "nothing outdated".
+   - `package@version` given: use it. `package` alone: its `latestInMajor`, else `latest`. Not in the list: stop with the manifests that were read.
+   - No package: a single-select picker over the candidates with a newer version, non-breaking first, each option `name current -> target (risk)`. Two or more options per the picker contract; one candidate is confirmed with a yes/no, none means report "nothing newer found" with the registry note.
+
+3. **Major gate.** Risk `major` or `unknown`, or a prerelease target (`prerelease: true`), needs `--major` in the input or an explicit confirmation naming the versions (`Bump anyway` / `Take {latestInMajor} instead` when one exists / `Cancel`). An autopilot run without `--major` takes `latestInMajor` or stops.
+
+4. **Run the pipeline** with `state.mode = "deps"`, `state.taskType = "chore"`, the free-text task `chore(deps): bump {name} from {current} to {target}` and the branch `chore/deps-{name}-{target}` (kebab rules from Phase 0 Step 4). Phase 0 intake, worktree and tracker run as in `/multi-agent`. Then:
+   - **Phase 1**: the fixed plan from the feature doc, with the changelog excerpt as evidence:
+     ```bash
+     node "$HOME/.claude/scripts/dep-bump.mjs" notes --dir "$WORKTREE" --ecosystem E --name N --from A --to B
+     ```
+   - **Phase 2**: apply first, then the exit gate as written:
+     ```bash
+     node "$HOME/.claude/scripts/dep-bump.mjs" apply --dir "$WORKTREE" --ecosystem E --name N --to B [--allow-major]
+     ```
+     Exit 1: report `error` and `lock.output` (or `dirty`: the worktree had uncommitted changes), stop with nothing to commit. Persist the output to `state.depBump`. Green: no dev agent, on to Phase 3. Red: fix rounds, at most `depBump.maxFixRounds`, each dispatched with the failing log tail, `surface` output, the changelog excerpt and the scope rule (feature doc section 4); after each round:
+     ```bash
+     node "$HOME/.claude/scripts/dep-bump.mjs" scope --dir "$WORKTREE" --log "$GATE_LOG"   # the round's build/test log
+     ```
+     Only the surface recorded by `apply` is in scope. A file listed in `newImporters` with `cited: null` started importing the dependency without an error line behind it: revert it before the next round.
+   - **Cap reached and still red** (or still out of scope): `dep-bump.mjs rollback --dir "$WORKTREE"` (restores the manifest, lockfile and fix files; anything under `kept` is reported, not discarded), set `state.depBump.rolledBack = true`, and end with the report from feature doc section 5. No commit, no push, no PR.
+   - **Phase 3**: standard review. Each `outOfScope` file without a cited error line, and each `newImporters` entry with `cited: null`, is a blocking finding.
+   - **Phase 4**: commit with `commitMessage` from `apply` (plus ` [{jiraId}]` when present). PR body per the feature doc; `Ref:` or `Related:`, never `Closes`, `Fixes` or `Resolves`, and never close an issue.
+   - **Phase 5**: channels as in every mode.
+
+## Report
+
+In `outputLanguage`, at most 10 lines: the dependency, from and to, risk, lockfile command and result, rounds taken against the cap, files changed (in scope / justified), review verdict, and the PR URL or the rollback reason.

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

@@ -52,8 +52,8 @@ because it does not mean the same thing on all three:
 
 | Host | What `off` does | Why |
 |---|---|---|
-| Claude Code | every `preferredModel: fable` persona (architects, reviewer 1, triage) starts on `opus` | the only host where the rung is Fable 5 |
-| Copilot CLI | nothing | Fable 5 is not offered there; its personas never sat on this rung |
+| Claude Code | every `preferredModel: fable` persona (architects, reviewer 1, triage) starts on `opus` | the only host where the rung is Fable 5.1 |
+| Copilot CLI | nothing | Fable is not offered there; its personas never sat on this rung |
 | Codex CLI | nothing, deliberately | the `fable` rung there means `gpt-5.6 @ xhigh`, a different model on a different account - switching it from a knob named after an Anthropic model would surprise a Codex user |
 
 So on two of the three hosts this command is a **status report**, not a switch,

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

@@ -0,0 +1,90 @@
+---
+description: "Post-mortem of a run from its session transcripts: loops, stalls, root-cause hypotheses on file:line, fixes. Read-only, redacted. Use when a run went wrong or ran far too long."
+description-tr: "Bir koşunun oturum transkriptlerinden post-mortem'i: ne oldu, nerede döngüye girdi veya takıldı, file:line'a dayalı kök-neden hipotezleri, önerilen düzeltmeler. Salt-okunur; gösterilmeden önce redakte edilir."
+argument-hint: "[#id | transcript.jsonl] [--audit]  -  a run (task id or #N) or a session file; no argument means the most recent run. --audit re-checks the draft against the index"
+parameters: [{"name":"target","kind":"text"},{"name":"--audit","kind":"flag"}]
+gui: button
+destructive: false
+confirm: none
+---
+
+# multi-agent postmortem  -  Run Post-Mortem
+
+**Input**: $ARGUMENTS
+
+Explains what a run actually did, read from the session transcripts it ran in,
+not from what the run log says it decided. The evidence comes from a
+deterministic indexer; the model only interprets it.
+
+The indexer reads all three hosts and detects the format per file:
+
+| Host | Session files |
+|------|---------------|
+| Claude Code | `~/.claude/projects/<dir>/<session>.jsonl` plus its subagent files |
+| Copilot CLI | `~/.copilot/session-state/<session>/events.jsonl` (cited as `<first 8 of session>/events.jsonl`) |
+| Codex | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` (cited as `rollout-<first 8 of session>.jsonl`) |
+
+Copilot CLI reports tokens per session, so its turns carry output tokens only
+and the totals come from the session's shutdown record; Codex reports them per
+request.
+
+**Read-only.** Nothing is sent anywhere: no issue comment, no PR, no channel.
+The one write is the report itself, saved under the run's log directory.
+
+## Steps
+
+1. **Resolve the target.**
+   - A path ending in `.jsonl` (any of the three hosts): index that file
+     (Claude Code subagent files beside it are included). There is no run directory, so nothing is saved unless the user
+     names one.
+   - A task id or `#N`: locate the run and its transcripts:
+     ```bash
+     node "$HOME/.claude/scripts/transcript-index.mjs" --run "<id>" --locate
+     ```
+     `matchedBy: "session"` means the run recorded its session id and the match
+     is exact. `"time-window"` means it did not (attended runs record none), so
+     the files are the sessions, on any host, that ran in the run's worktree or
+     checkout while it was active; say that this match is a heuristic. Exit 3 with a `reason`:
+     report the reason, and offer to take a transcript path instead.
+   - No argument: take the most recent run from
+     `node "$HOME/.claude/scripts/runs-index.mjs" --json` (latest `startedAt`)
+     and continue as above.
+
+2. **Index.**
+   ```bash
+   node "$HOME/.claude/scripts/transcript-index.mjs" --run "<id>"         # or: <file.jsonl>
+   ```
+   The output lists turns, loops (identical tool calls repeated), stalls (gaps
+   while a tool or the model was working), compactions, subagents with their
+   results, errors and denials, skill and command invocations, the slowest tool
+   calls and a timeline. Every item carries `file:line`, the line of the JSONL
+   it came from. Exit 4 means the redaction guard found a credential left in the
+   output and printed nothing: report that and stop; never fall back to reading
+   the transcript directly.
+
+   Read only the index. Do not open the transcript files: the index is the
+   redacted view, the files are not.
+
+3. **Write the post-mortem** in `prefs.global.outputLanguage`, short:
+   - **What happened**: the run in five lines or fewer, from the turns and
+     timeline.
+   - **Where it looped or stalled**: each loop and stall that matters, with its
+     citations.
+   - **Root-cause hypotheses**: each one a hypothesis, not a verdict, and each
+     anchored to at least one `file:line` from the index. A hypothesis with no
+     citation is left out.
+   - **Suggested fixes**: concrete and tied to a hypothesis (a prompt rule, a
+     guard, a timeout, a tool to use instead).
+   - **Evidence limits**: the matching method (`session` / `time-window`),
+     malformed or truncated lines, and the redaction count the index reported.
+
+   Quote only excerpts the index already shows; they are redacted.
+
+4. **Audit pass** (`--audit`): re-read the draft against the index. Every cited
+   `file:line` must exist in the index and say what the draft claims; every
+   count must match the index's counts. Correct or drop what does not hold, and
+   add one line: `audit: N claims checked, M corrected`.
+
+5. **Save.** With a run directory, write the report to
+   `<runDir>/postmortem.md` (`runDir` from step 1, `~` expanded) and give the
+   path. That file is the only write this command makes.

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

@@ -247,14 +247,14 @@ off: Agent 1 is dropped, the panel is Agent 2 + Agent 3, triage runs on
 Never dispatch a Fable reviewer or a Fable triage on the model list below alone.
 
 **Claude Code (3 in parallel while the fable rung is on, 2 while it is off):**
-- Agent 1: `claude-fable-5` → security + architecture (only when `REVIEW_RUNG` is `fable`)
-- Agent 2: `claude-opus-5` → edge cases, alternate perspective
-- Agent 3: `claude-sonnet-5` → general quality
+- Agent 1: `claude-fable-5-1` → security + architecture (only when `REVIEW_RUNG` is `fable`)
+- Agent 2: `claude-opus-5-5` → edge cases, alternate perspective
+- Agent 3: `claude-sonnet-5-5` → general quality
 
 **Copilot CLI (3 in parallel):**
-- Agent 1: `claude-opus-5` → security + architecture (Fable 5 is not offered on Copilot CLI)
+- Agent 1: `claude-opus-4.7` → security + architecture (Fable is not offered on Copilot CLI)
 - Agent 2: `gpt-5.4` → edge cases, alternate perspective
-- Agent 3: `claude-sonnet-5` → general quality
+- Agent 3: `claude-sonnet-4.6` → general quality
 
 **Codex CLI (3 in parallel, single vendor):**
 - Agent 1: `gpt-5.6` @ `xhigh` → security + architecture

package/pipeline/commands/multi-agent/route-on/SKILL.md

@@ -30,7 +30,7 @@ honoured only at `bulk-read` and `delegate` and only while `--free` is on.
 
 **Rung names are the contract; model ids are not.** `opus` is a rung here and a
 model id in `cost-table.json`, and the second can change without anyone editing
-a rule. Writing `claude-opus-5` into a rule pins a decision to a string that will
+a rule. Writing `claude-opus-5-5` into a rule pins a decision to a string that will
 go stale.
 
 Set rules with:

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

@@ -429,14 +429,16 @@ To set up multi-agent on a new machine:
 
 All tokens are optional in the sense that every service can be answered with Skip  -  but the ASKING is not optional: the Step 3 sequential loop still walks every missing service one by one (token → author → host). Phase 0 re-asks at runtime only for tokens the user skipped here.
 
-### Step 8  -  Enforcement hooks (optional, Claude Code)
+### Step 8  -  Enforcement hooks (optional)
 
-Offer to merge `$HOME/.claude/templates/claude-hooks.json`: three `PreToolUse` gates that block on a non-zero exit (secret scan, agent-guard, read-size) plus three capture hooks that block nothing (`PreCompact`, `SessionEnd`, `SessionStart`). What each does: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
+On Claude Code, offer to merge `$HOME/.claude/templates/claude-hooks.json`: three blocking `PreToolUse` gates (secret scan, agent-guard, read-size) plus four non-blocking hooks (`PreCompact`, `SessionEnd`, `SessionStart`, `PostToolUse`). What each does: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
 
 - Ask (picker): "Install the pipeline's hooks into `~/.claude/settings.json`?" Default Yes.
-- On Yes, deep-merge EVERY event in the template's `hooks` object, not `PreToolUse` alone - merging one event silently drops the capture hooks, and a run killed before Phase 5 then loses its findings exactly as it did before they existed. Preserve existing hooks; never duplicate a matcher already calling the same script.
-- Say what the merge does NOT cover: only the three gates need no run-specific arguments, so only they are hookable; the rest are phase-enforced.
-- Say what it does not turn on: the read-size gate is inert until `prefs.global.bulkRead.mode` is set. Recommend `observe` first. Why, and the Phase 3 exemption: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
+- On Yes, deep-merge EVERY event in the template's `hooks` object (merging `PreToolUse` alone drops the capture hooks); keep existing hooks, never duplicate a matcher calling the same script.
+- Say only the three gates are hookable (no run-specific arguments); the rest are phase-enforced.
+- Say the read-size gate stays inert until `prefs.global.bulkRead.mode` is set; recommend `observe` first (why, and the Phase 3 exemption: `picker-contract.md`).
+
+Codex: offer only the syntax gate, then run `node "$HOME/.codex/scripts/host-hooks.mjs" install --host codex`. Copilot CLI: offer no hook (it discards `postToolUse` output as of 1.0.45).
 
 ### Step 9  -  Default stack plugin enablement
 

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

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

package/pipeline/commands/multi-agent/testflight-validation/SKILL.md

@@ -11,10 +11,9 @@ allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdat
 
 # /multi-agent:testflight-validation  -  iOS alias for store-ready
 
-This command is an alias. The implementation it used to carry was merged into
+This command is an alias. The implementation lives in
 `/multi-agent:store-ready`, which runs the same three gates on iOS and adds the
-Android side, so there is one flow to maintain instead of two that had already
-started to drift.
+Android side, so there is one flow to maintain instead of two that drift.
 
 The name is kept because it is the one people reach for when the target is
 TestFlight, and removing a command is a breaking change to the slash-command

package/pipeline/contract/fixtures/runs-failed.json

@@ -85,7 +85,7 @@
         "out": 1020,
         "cached": 2700
       },
-      "estUsd": 0.0449,
+      "estUsd": 0.0353,
       "unlockedWrites": 0,
       "runType": "development",
       "title": null,

package/pipeline/contract/fixtures/runs-old-schema.json

@@ -63,7 +63,7 @@
         "out": 680,
         "cached": 1800
       },
-      "estUsd": 0.0299,
+      "estUsd": 0.0236,
       "unlockedWrites": 0
     }
   ]

package/pipeline/contract/fixtures/runs-pr-opened-redacted.json

@@ -106,7 +106,7 @@
         "out": 2040,
         "cached": 5400
       },
-      "estUsd": 0.0897,
+      "estUsd": 0.0707,
       "unlockedWrites": 0,
       "runType": "development",
       "title": null,

package/pipeline/contract/fixtures/runs-pr-opened.json

@@ -111,7 +111,7 @@
         "out": 2040,
         "cached": 5400
       },
-      "estUsd": 0.0897,
+      "estUsd": 0.0707,
       "unlockedWrites": 0,
       "runType": "development",
       "title": null,

package/pipeline/contract/fixtures/runs-running.json

@@ -96,7 +96,7 @@
         "out": 680,
         "cached": 1800
       },
-      "estUsd": 0.0299,
+      "estUsd": 0.0236,
       "unlockedWrites": 0,
       "runType": "autopilot",
       "title": "Fix the crash on the login screen",

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

@@ -34,6 +34,13 @@
 # Jira has no backup path for fields other than description. Rewriting a body an
 # engineer has since edited would lose that edit with no way back.
 #
+# A STORY DEPENDENCY IS A LINK, WRITTEN LAST
+#
+# A plan node's `dependsOn` names the stories it waits for. Once every story has
+# a key, each edge becomes an issue link of `prefsUsed.dependencyLinkType`
+# (default Blocks) from the prerequisite to the dependent, checked before it is
+# sent so a re-run adds none.
+#
 # Usage:
 #   analysis-jira-write.sh --plan plan.json --project KEY [--dry-run] [--ledger FILE] [--epic KEY]
 #   analysis-jira-write.sh --subtask-types --project KEY   the site's sub-task type names, one per line
@@ -202,6 +209,40 @@ link_issues() {  # link_issues <type> <fromKey> <toKey> <cloneLabel>
   echo "  linked  $from <-> $to"
 }
 
+# A dependency link: the prerequisite is the link's source (the POST's
+# inwardIssue), so the site reads "<prerequisite> blocks <dependent>" for the
+# default Blocks type, and lists the link on the prerequisite under outwardIssue.
+# Only a link of this type in this direction counts as already there: a Relates
+# link a person added between the same two stories is not the dependency.
+link_dependency() {  # link_dependency <type> <prerequisiteKey> <dependentKey> <dependentLabel>
+  local ltype="$1" pre="$2" dep="$3" label="$4" linked
+  linked="$(jira_api GET "/rest/api/2/issue/${pre}?fields=issuelinks" 2>/dev/null \
+    | jq -r --arg t "$ltype" --arg d "$dep" \
+      '[.fields.issuelinks[]? | select(.type.name == $t and .outwardIssue.key == $d)] | length > 0' \
+      2>/dev/null || echo false)"
+  if [ "$linked" = "true" ]; then
+    echo "  linked  $pre -> $dep  ($ltype)"
+    return 0
+  fi
+  if ! printf '%s' "$(jq -cn --arg t "$ltype" --arg a "$pre" --arg b "$dep" \
+      '{type: {name: $t}, inwardIssue: {key: $a}, outwardIssue: {key: $b}}')" \
+      | jira_api POST "/rest/api/2/issueLink" --data @- >/dev/null; then
+    echo "ERR: could not link $pre to $dep" >&2
+    return 5
+  fi
+  ledger dependency "$label" "$pre"
+  echo "  linked  $pre -> $dep  ($ltype)"
+}
+
+declare -a STORY_KEYS=()
+story_key() {  # story_key <label> -> prints the key this run created or found, or empty
+  local i
+  for i in "${STORY_KEYS[@]:-}"; do
+    case "$i" in "$1="*) printf '%s' "${i#*=}"; return 0 ;; esac
+  done
+  printf ''
+}
+
 CREATED_KEY=""
 create_issue() {  # create_issue <label> <summary> <issuetype> <parentKey|""> <description> [extraFieldsJson]
   local label="$1" summary="$2" itype="$3" parent="$4" desc="$5" extra="${6:-}" body key existing
@@ -290,6 +331,7 @@ while IFS= read -r node; do
     continue
   fi
   skey="$CREATED_KEY"
+  [ -n "$skey" ] && STORY_KEYS+=("$s_label=$skey")
   LINK_TYPE="$(jq -r '.prefsUsed.cloneLinkType // "Relates"' "$PLAN")"
   while IFS= read -r clone; do
     [ -n "$clone" ] || continue
@@ -319,4 +361,32 @@ while IFS= read -r node; do
   done < <(printf '%s' "$node" | jq -c '.subtasks[]?')
 done <<< "$NODES"
 
+# Dependencies, once every story has a key. An edge inside a strongly connected
+# component (`onCycle`, set by the planner from task-graph.mjs) is not linked:
+# a cycle has no order to record, and the plan already reported it.
+DEP_TYPE="$(jq -r '.prefsUsed.dependencyLinkType // "Blocks"' "$PLAN")"
+EDGES="$(jq -r '(.nodes | map({(.label): .title}) | add // {}) as $t
+  | .dependencies.edges[]? | .prerequisite as $p | .dependent as $d
+  | [$p, $d, $t[$p], $t[$d], (if .onCycle == true then "cycle" else "" end)]
+  | map(. // "" | tostring | gsub("[\n\r\u001f]"; " "))
+  | join("\u001f")' "$PLAN")"
+# \x1f, unlike a tab, is not IFS whitespace, so an empty field stays a field.
+while IFS=$'\x1f' read -r p_label d_label p_title d_title on_cycle; do
+  [ -n "$p_label" ] || continue
+  if [ "$on_cycle" = "cycle" ]; then
+    echo "  skipped   link $p_label ($p_title) -> $d_label ($d_title): the two stories are on a dependency cycle"
+    continue
+  fi
+  if [ "$DRY" -eq 1 ]; then
+    echo "  link    $DEP_TYPE  $p_label ($p_title) -> $d_label ($d_title)  (prerequisite -> dependent)"
+    continue
+  fi
+  p_key="$(story_key "$p_label")"; d_key="$(story_key "$d_label")"
+  if [ -z "$p_key" ] || [ -z "$d_key" ]; then
+    echo "  skipped   link $p_label ($p_title) -> $d_label ($d_title): one of the stories was not created" >&2
+    continue
+  fi
+  link_dependency "$DEP_TYPE" "$p_key" "$d_key" "$d_label" || RC=5
+done <<< "$EDGES"
+
 exit "$RC"

package/pipeline/lib/credential-inventory.sh

@@ -3,11 +3,11 @@
 #
 # WHY THIS EXISTS
 #
-# A run asked the user to paste a Crashlytics stack trace by hand while a Firebase
-# service-account JSON sat in the Keychain, mapped as `firebase`, fully valid. Nothing
-# was broken - the pipeline simply never asked itself "do I already hold a credential
-# that answers this?" before asking the user. From the user's side that is worse than a
-# failure: they had supplied the key precisely so this would not happen.
+# A run that asks the user to paste a Crashlytics stack trace by hand while a valid
+# Firebase service-account JSON sits in the Keychain, mapped as `firebase`, has failed
+# even though nothing is broken. From the user's side that is worse than a failure: they
+# supplied the key precisely so this would not happen. So the pipeline asks itself "do I
+# already hold a credential that answers this?" before it asks the user.
 #
 # One command, so there is no excuse for asking blind. Run it before any question that
 # requests data an external system holds, and let the answer shape the question:

package/pipeline/lib/decisions.mjs

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

package/pipeline/lib/fetch-crashlytics.sh

@@ -214,15 +214,13 @@ if [ -z "$SA_JSON_RAW" ]; then
 fi
 
 # The credential store returns the JSON as stored - encoding is its internal
-# business, not this script's. The base64 attempt that used to live here was
-# guesswork that never fired: what actually broke the fetcher was the store
-# returning bare hex for any multi-line value, which is neither base64-of-JSON
-# nor JSON, so both branches failed and the failure surfaced three layers later
-# as a token-exchange error.
+# business, not this script's, so nothing here guesses at a decoding. A guess
+# that misfires (bare hex read as base64, say) fails three layers later as a
+# token-exchange error instead of here.
 #
-# With no decode step there is nothing to stage on disk, so the temp file and its
-# cleanup traps went with it: the service-account JSON now only ever exists in a
-# shell variable, which is one fewer place a GCP private key can be left behind.
+# With no decode step there is nothing to stage on disk, so there is no temp file
+# and no cleanup trap: the service-account JSON only ever exists in a shell
+# variable, which is one fewer place a GCP private key can be left behind.
 SA_JSON="$SA_JSON_RAW"
 
 # Verify project_id from SA JSON matches the URL  -  protects against pasting a