@mmerterden/multi-agent-pipeline 16.25.0 → 16.27.0

package/pipeline/multi-agent-refs/phases/operations.md

@@ -150,7 +150,13 @@ This keeps orchestrator context lean and enables programmatic routing.
 
 **Proactive compaction + phase-boundary checkpoint**: the orchestrator follows ~2,500 lines of phase prose in one session; once context fills, it starts dropping steps  -  the single biggest cause of "it got stuck / skipped a step." Two defenses, both required on full-pipeline runs:
 
-- *Phase-boundary checkpoint.* At every phase transition, before loading the next phase doc, write the durable state (`agent-state.json` phase status + `files[]` + `retryCount`) and append a structured handoff block to `agent-log.md` (format below). The next phase reads state + log, not the back-conversation  -  so a transition is a clean re-entry point even if context is later compacted.
+- *Phase-boundary checkpoint.* At every phase transition, before loading the next phase doc, write the durable state (`agent-state.json` phase status + `files[]` + `retryCount`) and append a structured handoff block to `agent-log.md` (format below). The next phase reads state + log, not the back-conversation  -  so a transition is a clean re-entry point even if context is later compacted. Then flush what the run has learned so far:
+
+  ```bash
+  bash $HOME/.claude/scripts/capture-flush.sh --state "$STATE_FILE" --quiet
+  ```
+
+  The durable stores used to be written only in Phase 7, which is the phase a run is LEAST likely to reach: a run killed in Phase 3 threw away every finding it had established, and the next run on the same repo paid to rediscover it. The flush is idempotent (the second call through writes 0 rows), costs no API tokens, calls no model, and never fails the transition. Phase 7 is now the LAST flush rather than the only one. The trigger is deliberately mechanical - a phase transition, not a model noticing that a moment qualifies.
 - *Compaction trigger.* If conversation context exceeds ~50%, run `/compact` preserving "modified files, plan, open review findings, current phase + sub-step" before continuing. Don't wait for auto-compaction near the limit  -  it triggers exactly when context is worst and is lossy. After compaction, re-read `agent-state.json` AND the latest `## Handoff` block in `agent-log.md` to re-ground.
 
 **Handoff block (v10.8.0)**: the structured artifact the phase-boundary checkpoint appends to `agent-log.md`. Written by the orchestrator from state it already holds  -  no agent dispatch, no extra LLM call. Cap at ~15 lines; the latest block is authoritative (earlier ones are history). This is the fresh-context re-entry contract: a resume or post-compaction session rebuilds working context from the latest handoff + `agent-state.json` + git log, never from conversation memory.

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

@@ -145,7 +145,9 @@ Gated by `prefs.global.repoMap.enabled` (default: `false`). When enabled, runs `
 
 #### Step 2.6  -  Code Graph Injection (advisory, opt-in)
 
-Gated by `prefs.global.codeGraph.enabled` (default: `false`). With a rule file for `detectedStack`, Phase 1 refreshes the code graph, queries it, and hands Explore a ranked starting set instead of a full scan; `graph-affected` feeds `analysis.touchedAreas[]`. Zero API cost, read-only. Narrows an open-ended search; it does not replace a grep for a name the task already spells out. Commands, validator contract, measurements: `$HOME/.claude/multi-agent-refs/features/code-graph.md`.
+Gated by `prefs.global.codeGraph.enabled` (default: `false`). With a rule file for `detectedStack`, Phase 1 refreshes the graph and queries it; `graph-affected` feeds `analysis.touchedAreas[]`. Zero API cost, read-only. Commands and measurements: `$HOME/.claude/multi-agent-refs/features/code-graph.md`.
+
+**A valid result REPLACES the opening sweep** rather than sitting beside it: Explore starts from those files and walks outward, with no broad `Glob`/`Grep` pass first - running both pays twice, and the second re-derives what the graph said. No graph (missing rule, stale, or disabled) leaves the previous behaviour untouched; a task naming a symbol or path is still grepped directly.
 
 #### Step 3  -  Codebase Exploration
 

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

@@ -262,14 +262,7 @@ Visual-fidelity mismatches against the captured screenshot are BLOCKING findings
 
 - Canonical component usage: the Code Connect-mapped component is used verbatim  -  a sound-alike substitute, a forked copy, or ad-hoc inline UI where a mapping exists is blocking (Phase 3 "Design fidelity contract")
 - Inter-component spacing: gaps, paddings, and alignment BETWEEN components match the design's measured values mapped to spacing tokens  -  invented numeric values are blocking
-- Avatar icon (presence, glyph, shape, position)
-- Field grouping (one rounded box vs two; separator vs gap)
-- Character counter visibility
-- Header style (size, weight, alignment)
-- Inline error layout (icon presence, text colour, position relative to the input)
-- Button height
-- Indicator chip placement
-- Placeholder copy and position
+- Everything else: the 30-group catalog in `$HOME/.claude/multi-agent-refs/features/design-conformance.md`. Two of its rules carry into review: a height or inset is **measured**, never read from the token under test; an unrun check is a fail-to-verify, not a pass.
 
 When `state.figmaAccess.tier === 3` (user-attached screenshot, no Code Connect snippet), the reviewer additionally sets `findings[i].severity = "blocking"` and `findings[i].tag = "review_blocking_tier3"` on every UI atom that lacks a confirmed canonical-component mapping. The triage step preserves these findings unless the user has explicitly cleared the open question.
 

package/pipeline/multi-agent-refs/phases/phase-7-report.md

@@ -219,38 +219,28 @@ This is independent of the channels-side `reportContent.costSummary` (which gate
 
 **Missing-telemetry disclosure (required).** Name untracked phase ids as cost-unavailable in the report and closing summary. Mechanic: `payload-contracts.md`.
 
-**Triage memory ingest (mandatory):** after Phase 4 produces a final triage output, persist the accepted/deferred/rejected rows into the per-repo triage corpus so Phase 1 enrichment and Phase 4 prior-art lookup can recall them on future tasks. Idempotent  -  re-running on the same task writes 0 rows.
+**Final capture flush (mandatory):** persist the triage findings and the durable learnings this run established.
 
 ```bash
-# Salvaged copy first: Phase 6 removes the worktree once the PR is open, and this
-# reader is `[ -f ]`-guarded, so a wrong path degrades SILENTLY.
-TRIAGE_PATH="$(jq -r '.artifactsPath // empty' "$STATE_FILE" 2>/dev/null)/triage-output.json"
-[ -f "$TRIAGE_PATH" ] || TRIAGE_PATH="$WORKTREE/triage-output.json"
-if [ -f "$TRIAGE_PATH" ]; then
-  node $HOME/.claude/scripts/triage-memory.mjs ingest \
-    --triage "$TRIAGE_PATH" \
-    --task-id "$TASK_ID" \
-    --task-title "$TASK_TITLE" \
-    --stack "$DETECTED_STACK" >/dev/null 2>&1 || true
-fi
+bash $HOME/.claude/scripts/capture-flush.sh --state "$STATE_FILE"
 ```
 
-Best-effort. The corpus is JSONL at `~/.claude/memory/multi-agent/<repo-slug>/triage-corpus.jsonl` (per-repo isolation  -  never cross-leaks between projects). Disabled when `prefs.global.priorArtEnrichment.ingestOnComplete = false`.
+Every phase boundary already made this call (`operations.md`), so by Phase 7 it usually writes 0 rows - and that is the point. These writes used to live ONLY here, in the phase a run is least likely to reach: a run killed in Phase 3 lost every finding it had established. Phase 7 is now the last flush, not the only one.
 
-**Learnings ledger distill (on by default via `prefs.global.learningsLedger.enabled`):** distill this run's rejected findings into durable rejected-preference entries so future reviewers stop re-raising them, and record any durable architectural fact the analysis surfaced. Idempotent (dedup by kind + statement). Safety: `from-triage` skips blocking-severity rejections - a wrong rejection of a blocking issue must never permanently suppress that class; use `learnings-ledger.mjs forget` to clear a bad/stale entry.
+What it does, so this doc stays inspectable:
+
+- **Triage ingest** (`triage-memory.mjs ingest`). accepted/deferred/rejected rows into the per-repo corpus, so Phase 1 enrichment and Phase 4 prior-art recall them later. Idempotent. Reads the salvaged copy under `artifactsPath` FIRST: Phase 6 removes the worktree, and a worktree-first reader degrades silently for exactly the runs worth rescuing. JSONL at `~/.claude/memory/multi-agent/<repo-slug>/triage-corpus.jsonl`, per-repo, never cross-leaking. Off when `prefs.global.priorArtEnrichment.ingestOnComplete = false`.
+- **Ledger distill** (`learnings-ledger.mjs from-triage`). Rejected findings become durable `rejected-preference` entries so reviewers stop re-raising them. Idempotent. Safety: blocking-severity rejections are NOT distilled - a wrong rejection must never permanently suppress that class; `learnings-ledger.mjs forget` clears a stale one. JSONL beside the corpus; its brief replays into Phase 1 and Phase 4. On by default via `prefs.global.learningsLedger.enabled`.
+
+No model runs in the flush - it derives everything from `triage-output.json` plus `agent-state.json`, which is what lets a hook call it. The model-dependent parts of this phase (Step 3 knowledge capture, memory synthesis) stay here, because a hook cannot think.
+
+A durable architectural fact is a judgement call, so it stays here rather than in the flush:
 
 ```bash
-if [ -f "$TRIAGE_PATH" ]; then
-  node $HOME/.claude/scripts/learnings-ledger.mjs from-triage \
-    --triage "$TRIAGE_PATH" --task "$TASK_ID" >/dev/null 2>&1 || true
-fi
-# Optionally capture a durable architectural fact the analysis established:
 # node $HOME/.claude/scripts/learnings-ledger.mjs add --kind fact \
 #   --statement "<one-line fact>" --scope "<path-glob>" --task "$TASK_ID" >/dev/null 2>&1 || true
 ```
 
-The ledger is JSONL at `~/.claude/memory/multi-agent/<repo-slug>/learnings-ledger.jsonl`, next to the triage corpus, per-repo isolated. Its brief is replayed into Phase 1 analysis and Phase 4 triage on future runs.
-
 Print the closing report to the terminal. Two blocks, in this order  -  what the pipeline spent, then what it changed:
 
 ```bash

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

@@ -81,6 +81,6 @@ In autopilot, `ask_choice` resolves to `default` (or the safe first option) with
 
 ## 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. 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, 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.
 
 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/refactor/observations.md

@@ -0,0 +1,81 @@
+# The observation backlog (refactor Step 0e / `backlog` mode)
+
+Loaded on demand by `/multi-agent:refactor`. The SKILL.md carries the band intro; this file is the flow.
+
+## 1. Why a queue exists at all
+
+`/multi-agent:refactor` derives its findings from scratch on every invocation. That is the right design for a sweep, and it has one consequence nobody chose: a friction noticed on Tuesday is gone by Wednesday unless it was fixed within the hour. Most are not, because they surface mid-task, when stopping to fix them is the wrong call.
+
+So the friction is written down the moment it is noticed, and this band decides what to do with it later. The two halves are deliberately separate: noticing is cheap and must never wait for a decision, deciding is expensive and must never happen mid-task.
+
+Store: `$HOME/.claude/memory/multi-agent/_pipeline/observations/NNNN-slug.md`, one file per observation, frontmatter per `schemas/skill-observation.schema.json`. The directory listing is the index - there is no index file, because an index is a second copy of the truth and the second copy is the one that goes stale.
+
+## 2. Reading the queue
+
+```bash
+node "$HOME/.claude/scripts/observations.mjs" scan --status open --json
+```
+
+`scan` reads frontmatter only and never opens a body, so a queue of several hundred costs almost nothing.
+
+**Exit 3 is `SCAN BROKEN` and it is not an empty queue.** It means files exist on disk and none parsed - the reader is broken. Halt the band and say so. An empty scan otherwise reports two different facts with one answer ("nothing to find" and "the question was never asked"), and only the first is a finding; the guard exists so those two can never be confused again.
+
+## 3. Splitting the queue
+
+Every open observation lands in exactly one of three buckets:
+
+| Bucket | Meaning | What happens |
+|---|---|---|
+| Actionable | a change worth making now | goes into the plan as a normal band item with its file and fix |
+| Sibling propagation | already fixed in one copy, not the others | goes into the plan as a propagation item, with the exact surfaces named |
+| To decline | not worth doing, or wrong | proposed for `declined` with a one-line reason |
+
+The second bucket is the one this tree specifically needs. A command is never one file: it is authored under `commands/`, mirrored into `skills/shared/core/`, and installed again into the Claude, Copilot and Codex trees. A fix applied to whichever copy was open drifts from the rest silently - nothing errors and every gate stays green. Resolve the surfaces mechanically, never from memory:
+
+```bash
+node "$HOME/.claude/scripts/skill-siblings.mjs" <path> --json
+node "$HOME/.claude/scripts/skill-siblings.mjs" --audit      # every command at once
+```
+
+## 4. Deciding, and the deferral that wears a disguise
+
+An observation leaves the queue with a status, never by being ignored:
+
+- `actioned` - a change shipped. Record the commit in `reference`.
+- `declined` - decided against. A decline with no `resolution` is indistinguishable from neglect, so the reason is written.
+- `superseded` - another observation covers it. Name which.
+- `parked` - decided, but blocked on something outside this repo.
+
+`parked` requires `parked_until` naming the concrete event that unblocks it: a version, a release, an upstream fix. "Let us gather more data" is not an event. If no observation could change the decision and no date is nameable, the honest status is `declined` - a park with no expiry leaves the queue and never comes back, which is a silent decline wearing a friendlier word.
+
+```bash
+node "$HOME/.claude/scripts/observations.mjs" resolve --id 0007 --status actioned \
+  --resolution "backlog mode added" --reference "<sha>"
+```
+
+## 5. Applying
+
+Changes go to a staged copy and are shown before anything is installed, exactly as the drift band does. The user installs; this band never edits an installed skill in place.
+
+When any observation is resolved, stamp the review:
+
+```bash
+date +%Y-%m-%d > "$HOME/.claude/memory/multi-agent/_pipeline/last-review-date.txt"
+```
+
+`capture-resume.sh` reads that stamp at session start and offers one line when it is seven days old and the queue is non-empty. One line, never a block - the user's own work does not wait on the pipeline's housekeeping.
+
+## 6. Writing an observation
+
+Any session may add one, in the same turn the friction appears, and then carry on:
+
+```bash
+node "$HOME/.claude/scripts/observations.mjs" add \
+  --title "<the friction, not the fix>" \
+  --target <repo-relative path> [--target ...] \
+  --area <phase|gates|docs|...> \
+  --session "<what the session was doing>" \
+  --body "<detail>"
+```
+
+State the friction, not the remedy: "refactor re-derives its findings every run" is an observation, "add a backlog mode" is a proposal, and proposals age badly while observations do not. `siblings_checked` is filled by `skill-siblings.mjs` automatically and cannot be empty - the whole point is that the answer is computed rather than recalled, because recollection is the faculty that produced the drift.

package/pipeline/multi-agent-refs/setup/firebase.md

@@ -0,0 +1,151 @@
+# Firebase / Crashlytics Onboarding (setup Step 3c)
+
+Loaded on demand by `/multi-agent:setup` Step 3c (optional, any platform). The SKILL.md carries the step intro; this file is the full flow.
+
+Runs inside Step 3 alongside the other missing credentials. A user who already
+holds a Firebase service-account JSON gets it mapped by Step 1 discovery like any
+other credential; this flow covers what discovery cannot see - whether that
+account may actually read Crashlytics, and what to do when it may not.
+
+## 1. Why there are three ways in
+
+Crashlytics has one API and three ways to authenticate against it. They fail
+differently, so the pipeline measures rather than assumes.
+
+| Tier | Path | Serves | Needs |
+|---|---|---|---|
+| 1 | Service account + `lib/fetch-crashlytics.sh` | headless: autopilot, cron, url-enrichment, review chains | a Crashlytics role on the service account |
+| 2 | Firebase MCP + an interactive `firebase login` | a person at the keyboard | a browser, a real terminal, a session that expires |
+| 3 | The user pastes the stack trace | last resort | nothing, and it produces degraded evidence |
+
+Order is not fixed - whichever tier is ready wins, exactly as in the Figma chain.
+But **tier 1 is preferred whenever both are ready**, and the reason is structural:
+url-enrichment expands a Crashlytics link found in a Jira ticket while nobody is
+watching, and autopilot runs with no terminal to log into. A tier that needs a
+browser cannot serve those. Tier 2 fills the gap while a role request is pending;
+it does not replace tier 1.
+
+`credential-inventory.sh --probe` reports which tier is live:
+`tier-1-ready` / `tier-2-ready` / `tier-1-no-grant` / `malformed` / `unreachable`.
+The vocabulary and what to tell the user for each: `refs/keychain.md`.
+
+## 2. Tier 1 - the service account
+
+One credential, `keychainMapping.firebase`, holding the JSON exactly as Firebase
+Console issued it. Firebase Console -> Project settings -> Service accounts ->
+Generate new private key. Store it through the normal Token Save Flow; it is
+multi-line and that is fine - the store round-trips it byte for byte.
+
+Do **not** base64 it. Encoding is the store's internal business, and a wrapper on
+the way in that nothing unwraps on the way out is how this path stayed broken.
+
+Several Firebase projects per team is the normal case (legacy plus redesign,
+staging plus prod). The single slot is the fallback; extra projects go in
+`prefs.global.firebase.accounts[]` as `{projectId, keychainKey, label}` and the
+URL's project id picks the key.
+
+**The role is the part discovery cannot see.** A freshly generated service account
+authenticates perfectly and reads nothing: `firebase-adminsdk-*` carries no
+Crashlytics permission by default. The probe surfaces this as `tier-1-no-grant`,
+and the fix is one line to whoever holds Owner on the project:
+
+> Please grant `roles/firebasecrashlytics.viewer` on project `<projectId>` to the
+> service account `<client_email>`. It is read-only: it allows reading crash
+> issues and their stack traces, and nothing else.
+
+`roles/firebase.viewer` also works and is broader. Ask for the narrower one first.
+
+Verify with `bash lib/fetch-crashlytics.sh --probe`. It asks IAM what the account
+may do rather than calling Crashlytics and reading the error, because a 403 from
+the data endpoint means "no permission" but so does a 403 from a disabled API,
+and those need different fixes.
+
+## 3. Tier 2 - interactive session plus MCP
+
+Two halves, both required. Either alone reaches nothing.
+
+**The session.** `firebase login` opens a browser and does not work from inside an
+agent harness - it needs a real terminal the user drives themselves. Ask them to
+run it and say when it is done; `firebase login:list` confirms.
+
+**The MCP server.** The Firebase CLI serves it itself - there is no package to
+install beyond the CLI the login already needed:
+
+```bash
+claude mcp add firebase -- firebase mcp --dir "$PWD"
+```
+
+`--dir` is not decoration: the server resolves the project from that directory's
+`.firebaserc` / `firebase.json`, so a server registered without it answers for
+whatever directory it happens to start in.
+
+Scope is a real choice with three answers, so ask rather than guess:
+
+| Scope | Where it lands | When |
+|---|---|---|
+| `local` (default) | this user's entry for this repo, in `~/.claude.json` | the normal answer - the grant stays scoped to the repo that needs it |
+| `user` | this user, every repo | only when the user works across several Firebase projects and says so; `--dir` then has to be re-pointed per repo |
+| `project` | `.mcp.json` **committed in the repo** | only on an explicit ask - this registers the server for everyone who clones it |
+
+Default to `local` and never reach for `project` on your own: the server can read
+that Firebase project's data, and committing it hands that reach to the whole
+team as a side effect of one person's setup.
+
+Verify the registration answers before calling tier 2 ready:
+
+```bash
+claude mcp list | grep -i firebase
+```
+
+A tier-2 session is a person's credential with a refresh token that expires. Never
+present it as the durable answer - it is the bridge while the role request moves.
+
+## 4. appId discovery
+
+Every Crashlytics call needs the opaque `appId` (`1:<number>:ios:<hex>`), and a
+console URL only ever carries the bundle id. The fetcher resolves it through the
+Firebase Management API on each run, which works but costs a round trip and needs
+the project resolved first.
+
+The repo already holds the answer. `GoogleService-Info*.plist` (iOS) and
+`google-services.json` (Android) carry `PROJECT_ID` and `GOOGLE_APP_ID` for every
+target:
+
+```bash
+bash "$HOME/.claude/scripts/firebase-app-discovery.sh" <repo-dir> --json
+```
+
+It prints entries shaped for `prefs.global.firebase.accounts[]`, each with an
+`apps[]` of `{bundleId, appId, platform}`. Merge them into the account that
+already carries the matching `projectId`, keeping its `keychainKey` - which
+credential covers a project is the user's mapping to make, so the script never
+guesses one.
+
+A repo with several targets has several plists and they do not all point at the
+same Firebase project, so the script reads every match rather than stopping at
+the first, and skips build outputs where a copied plist would count one app twice.
+
+Confirm the merge before writing: show the projectId and the app count, and write
+nothing on a decline. Finding nothing is a normal answer - the fetcher still
+resolves appIds live, one round trip per run.
+
+## 5. v1alpha, and what to do when it breaks
+
+Both tiers read `firebasecrashlytics.googleapis.com/v1alpha`. That surface is
+undocumented and unversioned in the usual sense: Google may change or withdraw it
+without notice, and when they do, both tiers fail at once.
+
+This is written down so the failure is diagnosable rather than mysterious. The
+symptom is a 404 or a changed response shape on a call that worked yesterday, with
+credentials that still pass `--probe`. When it happens, the fetcher exits 3 with
+`crashlytics-unreachable`, the orchestrator degrades to advisory, and the pipeline
+keeps moving - it does not halt a run over a crash report.
+
+## 6. Skipping
+
+All of it is optional. Skip and nothing is written; Crashlytics links in tickets
+are simply not enriched, and the run says so rather than pretending it looked.
+
+Never lead with "paste the stack trace yourself" - that is tier 3, and offering
+the last resort first trains the user to skip the durable fix (`refs/keychain.md`
+Rule 2).

package/pipeline/schemas/learnings-ledger.schema.json

@@ -38,6 +38,11 @@
       "type": ["string", "null"],
       "description": "Task id that produced this entry, or null when added manually."
     },
+    "source": {
+      "type": "string",
+      "enum": ["triage", "transcript-mining", "manual"],
+      "description": "v16.27+ - who found this. `triage` is the Phase 4 distill, `transcript-mining` is learn-from-transcripts.mjs correlating a failure with the retry that worked, `manual` is a human or a model writing it directly. Kept separate because the three have different error modes and learning-curve.mjs has to be able to say which kind of learning is actually accumulating: a machine-mined path correction and a model's architectural claim are not the same evidence, and a metric that pools them can rise while the useful half is flat. Absent means the row predates the field."
+    },
     "confidence": {
       "type": "string",
       "enum": ["low", "medium", "high"],

package/pipeline/schemas/prefs.schema.json

@@ -68,7 +68,7 @@
                   },
                   "firebase": {
                     "type": "string",
-                    "description": "Firebase JSON (base64-encoded). project_id is parsed from the decoded JSON - no separate firebase_project entry."
+                    "description": "Keychain key for the Firebase service-account JSON, stored as issued. project_id is read straight out of it - no separate firebase_project entry."
                   },
                   "fortify": {
                     "type": "string"
@@ -179,7 +179,7 @@
             },
             "firebase": {
               "type": ["string", "null"],
-              "description": "Firebase JSON (base64-encoded). project_id is parsed from the decoded JSON."
+              "description": "Keychain key for the Firebase service-account JSON, stored exactly as Google issued it - no base64 wrapper. project_id and client_email are read straight out of it; fetch-crashlytics.sh signs a JWT with private_key and exchanges it for an access token."
             },
             "firebase_sa": {
               "type": ["string", "null"],
@@ -594,6 +594,10 @@
               "type": "string",
               "description": "v15.15+ - Graylog TEST host without scheme. Optional; leaving it unset means fetch-graylog.sh only ever searches production. Test and production are separate instances, so a trx id minted by a tester does not exist in prod and searching prod alone answers 'no logs' for a complaint that is fully logged one host over. Resolves {GRAYLOG_TEST_HOST}."
             },
+            "jenkins": {
+              "type": "string",
+              "description": "Jenkins host without scheme. credential-inventory.sh reads it to probe the `jenkins` token; the key was undeclarable before v16.26, so the probe could only ever answer no-host-configured for a token that was fine. Optional - unset leaves the token reported as present but unprobed."
+            },
             "corpDomain": {
               "type": "string",
               "description": "Corporate email / cookie domain, e.g. example.com. Resolves {CORP_DOMAIN}."
@@ -619,11 +623,35 @@
                   },
                   "keychainKey": {
                     "type": "string",
-                    "description": "Keychain key holding this project's service-account JSON (base64 or raw)."
+                    "description": "Keychain key holding this project's service-account JSON, stored as issued."
                   },
                   "label": {
                     "type": "string",
                     "description": "Human label used in error output, e.g. \"redesign prod\". Defaults to the projectId."
+                  },
+                  "apps": {
+                    "type": "array",
+                    "description": "v16.26+ - bundle id -> opaque Firebase appId, discovered from the repo's GoogleService-Info*.plist / google-services.json by firebase-app-discovery.sh. Every Crashlytics call needs the appId while a console URL carries only the bundle id, so without this the fetcher spends a Management API round trip resolving it on every run. Optional: absent means the fetcher resolves it live, which still works.",
+                    "items": {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": ["bundleId", "appId", "platform"],
+                      "properties": {
+                        "bundleId": {
+                          "type": "string",
+                          "description": "iOS bundle identifier or Android application id, as it appears in a Crashlytics console URL after the platform prefix."
+                        },
+                        "appId": {
+                          "type": "string",
+                          "description": "Opaque Firebase app id, e.g. 1:123456789:ios:abcdef0123456789. GOOGLE_APP_ID in the plist, mobilesdk_app_id in google-services.json."
+                        },
+                        "platform": {
+                          "type": "string",
+                          "enum": ["ios", "android"],
+                          "description": "Which console path the appId belongs under."
+                        }
+                      }
+                    }
                   }
                 }
               }

package/pipeline/schemas/skill-observation.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "skill-observation.schema.json",
+  "title": "Skill observation",
+  "description": "One noticed piece of friction in the pipeline's own skills, written the moment it is noticed. The store is a directory of markdown files whose frontmatter conforms to this schema; the directory listing IS the index, so there is no index file to keep in sync and no scan that reads a body. This schema describes that frontmatter. The learnings ledger holds what a run learned about a REPO; this holds what a run learned about the PIPELINE, which nothing captured before: /multi-agent:refactor derived its findings from scratch on every invocation, so a friction noticed on Tuesday was gone by Wednesday unless it was fixed the same hour.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "title", "status", "target", "siblings_checked", "area", "date"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[0-9]{4}$",
+      "description": "Zero-padded sequence number, matching the file's NNNN- prefix."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 8,
+      "description": "One line, stating the friction rather than the fix. 'refactor re-derives findings every run' is an observation; 'add a backlog mode' is a proposal, and belongs in the body."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["open", "actioned", "declined", "superseded", "parked"],
+      "description": "open = in the queue. actioned = a change shipped. declined = decided against, with the reason in resolution. superseded = another observation covers it. parked = decided, but blocked on something outside this repo; it leaves the queue without being archived, and parked_until is then required. Five values rather than open/closed because 'declined' and 'parked' are the two that get silently dropped when the vocabulary is too small - a parked item with no expiry is a deferral wearing a disguise."
+    },
+    "parked_until": {
+      "type": "string",
+      "description": "Required when status is parked: the concrete event that unblocks it (a version, a release, an upstream fix). 'more data' is not an event - if no observation could change the decision and no date is nameable, the honest status is declined."
+    },
+    "target": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" },
+      "description": "Repo-relative paths the observation is about. Always a list, even for one path: a scalar here means every consumer needs two code paths, and the one that handles the scalar is the one that gets forgotten.",
+      "uniqueItems": true
+    },
+    "proposes_skill": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Skills or commands that do not exist yet but should, if this observation implies one."
+    },
+    "siblings_checked": {
+      "type": "string",
+      "minLength": 3,
+      "description": "What was found when the sibling surfaces were checked. This tree mirrors every command into skills/shared/core and again into the Copilot and Codex trees, so a fix applied to one copy drifts silently from the rest. 'checked, does not apply to the shared skill' is a valid answer; empty is not, which is why the field is required and why skill-siblings.mjs fills it mechanically rather than from memory."
+    },
+    "area": {
+      "type": "string",
+      "description": "Rough grouping for the weekly review: a phase name, a subsystem, 'gates', 'docs'."
+    },
+    "date": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+      "description": "ISO date the observation was written, absolute so it survives being read a year later."
+    },
+    "session_context": {
+      "type": "string",
+      "description": "What the session was doing when the friction appeared. Free text, kept short; it is what makes an old observation legible."
+    },
+    "resolved": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+      "description": "ISO date the status left 'open'."
+    },
+    "resolution": {
+      "type": "string",
+      "description": "One line saying what happened. Required in practice for declined and superseded - a decline with no reason is indistinguishable from neglect."
+    },
+    "reference": {
+      "type": "string",
+      "description": "A commit, PR, or issue that carried the change."
+    }
+  }
+}