@mmerterden/multi-agent-pipeline 12.4.0 → 12.6.0

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

@@ -121,6 +121,96 @@
       "default": false,
       "description": "A Figma / skill instruction file is steering phases 3-6."
     },
+    "mode": {
+      "type": ["string", "null"],
+      "description": "Pipeline mode for this run (e.g. 'dev', 'local', 'design-check'). Absent = full pipeline."
+    },
+    "designCheck": {
+      "type": ["object", "null"],
+      "additionalProperties": true,
+      "description": "State for a /multi-agent:design-check run. Populated in Phase 0 (mock feasibility, scenario inventory, scope), Phase 2 (Figma variants) and Phase 3 (captures, skips, findings).",
+      "properties": {
+        "module": { "type": "string", "description": "Module / submodule path being audited." },
+        "platform": { "type": "string", "enum": ["ios", "android"] },
+        "mock": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "design_mock_detect result.",
+          "properties": {
+            "supported": { "description": "true | false | 'debug-only'" },
+            "mechanism": { "type": ["string", "null"] },
+            "activation": { "type": ["object", "null"] },
+            "variantsHint": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "inventory": {
+          "type": ["object", "null"],
+          "additionalProperties": true,
+          "description": "design_scenario_inventory result, persisted verbatim. THIS is the audit's target set  -  Phase 3 iterates it and Phase 4 gates on it. Never re-derive it by reading the repo.",
+          "properties": {
+            "targetCount": { "type": "integer" },
+            "targets": {
+              "type": "array",
+              "items": { "type": "object", "additionalProperties": true },
+              "description": "{ id, kind, label, screen, driver, evidence } per state driver (launch-arg / scenario-case / code-scenario / fixture / deep-link)."
+            },
+            "groups": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
+            "byKind": { "type": "object", "additionalProperties": true },
+            "truncated": { "type": "boolean" }
+          }
+        },
+        "scope": {
+          "type": ["object", "null"],
+          "additionalProperties": true,
+          "description": "Resolved run scope: the inventory targets this run must audit. The coverage gate applies to this set, not to the whole inventory  -  a scoped run is not penalised for out-of-scope targets.",
+          "properties": {
+            "argument": { "type": ["string", "null"], "description": "Raw $ARGUMENTS as given (empty = whole module, '--resume' = remainder of the last run)." },
+            "targetIds": { "type": "array", "items": { "type": "string" } },
+            "resumedFrom": { "type": ["string", "null"], "description": "Report dir of the run this scope resumes, when --resume was used." }
+          }
+        },
+        "figmaUrl": { "type": ["string", "null"] },
+        "variants": {
+          "type": "array",
+          "description": "Mapped variants with their Figma spec, capture, and findings.",
+          "items": { "type": "object", "additionalProperties": true }
+        },
+        "captured": {
+          "type": "array",
+          "description": "Every capture taken, appended and persisted as it happens so a dying run is resumable. One entry per screenshot, keyed to the target that produced it ('<targetId>', or '<targetId>#<sub-label>' for tap-reachable sub-states).",
+          "items": { "type": "object", "additionalProperties": true }
+        },
+        "skipped": {
+          "type": "array",
+          "description": "Targets that could not be audited, each with a CONCRETE reason. 'Requires a scenario / prefix / launch-arg' is not a reason  -  that is the work Phase 3 exists to do. A skip without a reason fails the coverage gate.",
+          "items": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["id", "reason"],
+            "properties": {
+              "id": { "type": "string" },
+              "group": { "type": ["string", "null"] },
+              "reason": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "coverage": {
+          "type": ["object", "null"],
+          "additionalProperties": true,
+          "description": "design_report coverage verdict for this run. gate='fail' means the run is INCOMPLETE and must be reported as such, with the unaccounted ids and the --resume command.",
+          "properties": {
+            "gate": { "type": "string", "enum": ["pass", "fail"] },
+            "audited": { "type": "integer" },
+            "target": { "type": "integer" },
+            "pct": { "type": "number" },
+            "skippedWithReason": { "type": "integer" },
+            "unaccounted": { "type": "integer" },
+            "unaccountedIds": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "reportDir": { "type": ["string", "null"], "description": "Output dir under ~/DesignChecks." }
+      }
+    },
     "identity": {
       "type": "object",
       "additionalProperties": false,

package/pipeline/schemas/design-check-config.schema.json

@@ -0,0 +1,162 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/design-check-config.schema.json",
+  "title": "Design Check Configuration",
+  "description": "Optional per-project config for /multi-agent:design-check. Stored at ~/.claude/projects/{slug}/design-check-config.json. Never committed. Everything here is optional: design_mock_detect auto-detects mock support and design_scenario_inventory auto-enumerates state drivers at run time; this file only overrides or augments that detection (extra mock switch keys, extra launch args / targets no source signal reveals, explicit variant->Figma-node mappings, status-bar crop, coverage floor, Confluence toggle). Keeps the engine generic — project specifics live here, never in shipped code.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion"],
+  "properties": {
+    "schemaVersion": { "type": "string", "const": "1.0.0" },
+    "platform": {
+      "type": "string",
+      "enum": ["ios", "android"],
+      "description": "Override auto platform detection."
+    },
+    "mock": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Mock-mode overrides. Omit to rely purely on auto-detection.",
+      "properties": {
+        "keys": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Extra UserDefaults / launch-arg switch keys to look for (passed as extra_keys to design_mock_detect)."
+        },
+        "launchArg": {
+          "type": "string",
+          "description": "Explicit iOS launch argument to force mock mode, e.g. '-debugMockMode YES'. Overrides the detected one."
+        },
+        "intentExtra": {
+          "type": "string",
+          "description": "Explicit Android intent extra, e.g. '--ez mockEnabled true'."
+        },
+        "buildConfig": {
+          "type": "string",
+          "description": "Build configuration that compiles the mocks (default 'Debug')."
+        }
+      }
+    },
+    "inventory": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Augments design_scenario_inventory, which decides the audit's target set. Only for states no source signal can reveal — everything detectable is detected.",
+      "properties": {
+        "extraLaunchArgs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Launch args (iOS) / boolean intent-extra keys (Android) that drive a distinct state but appear in no scanned literal."
+        },
+        "extraTargets": {
+          "type": "array",
+          "description": "Fully hand-declared targets, for states reachable only by a documented manual step.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id"],
+            "properties": {
+              "id": { "type": "string", "description": "Stable target id, e.g. 'config:seatmap-3d'." },
+              "kind": { "type": "string", "description": "Target kind label (default 'config')." },
+              "label": { "type": "string" },
+              "screen": { "type": "string", "description": "Screen this target belongs to (groups the coverage report)." },
+              "driver": {
+                "type": "object",
+                "additionalProperties": true,
+                "description": "How to reach it: { type: 'manual', note } or any driver shape the runner understands."
+              }
+            }
+          }
+        },
+        "ignoreTargets": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Target ids to drop from the inventory entirely (dead drivers, states retired in code but still referenced). Unlike a skip, these never enter the coverage gate — use sparingly and prefer a skip with a reason."
+        }
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Coverage gate tuning. The gate itself is not optional: a target is audited, or skipped with an explicit reason.",
+      "properties": {
+        "floor": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Additional hard floor on audited/target ratio (e.g. 0.9). Below it the gate fails even when every skip carries a reason."
+        },
+        "confirmAbove": {
+          "type": "integer",
+          "default": 25,
+          "description": "Relaunch count (inventory.relaunchCount for the scoped set, NOT the target count) above which Phase 0 asks for confirmation. Relaunches are the run's real cost: one relaunch serves every in-app target on that screen. Whole-module remains the intended default — this threshold estimates cost, it does not invite shrinking the audit."
+        }
+      }
+    },
+    "figma": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Figma frame + variant mapping overrides.",
+      "properties": {
+        "url": { "type": "string", "description": "Default Figma MCP URL for this module's frame/page." },
+        "frameSize": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": { "w": { "type": "number" }, "h": { "type": "number" } },
+          "description": "Figma frame size the spec coordinates are in (usually auto-read)."
+        }
+      }
+    },
+    "variants": {
+      "type": "array",
+      "description": "Explicit mock-variant -> Figma-node mappings. When present, the picker skips name-similarity guessing for these.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "figmaNodeId"],
+        "properties": {
+          "id": { "type": "string", "description": "Mock variant id (matches a variantsHint / fixture name)." },
+          "label": { "type": "string" },
+          "figmaNodeId": { "type": "string", "description": "Figma node id for this variant's frame." },
+          "activation": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "How to put the app into this variant (launch arg / UserDefaults values / navigation path)."
+          }
+        }
+      }
+    },
+    "capture": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Capture / comparison tuning.",
+      "properties": {
+        "cropTopLive": { "type": "number", "description": "Pixels to crop from the top of the live capture (status bar)." },
+        "tolerancePx": { "type": "number", "default": 2 },
+        "colorTolerance": { "type": "number", "default": 3 },
+        "maxDiffPct": { "type": "number", "default": 1.0 }
+      }
+    },
+    "report": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Report output + export.",
+      "properties": {
+        "outputRoot": { "type": "string", "description": "Report root dir (default ~/DesignChecks)." },
+        "formats": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["html", "pdf", "confluence"] },
+          "default": ["html", "pdf"]
+        },
+        "confluence": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": { "type": "boolean", "default": false },
+            "space": { "type": "string" },
+            "parentId": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -34,6 +34,10 @@
       "type": "string",
       "enum": ["low", "medium", "high"],
       "description": "How strongly to weight the entry when replaying it."
+    },
+    "diagnosis": {
+      "type": "string",
+      "description": "Optional causal 'why' behind the lesson (Reflexion): the root-cause reasoning that turns a detected failure into a prevented one. Rendered in the brief as '(why: ...)'. Absent for plain facts/conventions."
     }
   }
 }

package/pipeline/schemas/migrations/state-2.0.0-to-2.1.0.mjs

@@ -12,22 +12,40 @@ export default function migrate(data) {
 
   out.schemaVersion = "2.1.0";
 
-  // If projects[] doesn't exist and scalar fields do, create projects[0] from scalars
-  if (!Array.isArray(out.projects) && out.project) {
-    out.projects = [{
-      name: out.project,
-      root: out.projectRoot || null,
-      worktreePath: out.worktreePath || null,
-      branch: out.branch || null,
-      baseBranch: out.baseBranch || null,
-      identity: out.identity || null,
-      platform: out.remoteType || null,
-      baseFetchStatus: "fresh",
+  // If projects[] doesn't exist and the scalar mirrors do, create projects[0]
+  // from them. The item schema sets additionalProperties:false and requires
+  // project/projectRoot/branch/baseBranch/identity, so only emit keys the
+  // schema declares and only build the entry when every required key is
+  // populated -  a partial entry would be schema-invalid, which is worse than
+  // no entry at all.
+  const canMirror =
+    !Array.isArray(out.projects) &&
+    typeof out.project === "string" &&
+    typeof out.projectRoot === "string" &&
+    typeof out.branch === "string" &&
+    typeof out.baseBranch === "string" &&
+    out.identity !== null &&
+    typeof out.identity === "object";
+
+  if (canMirror) {
+    const entry = {
+      project: out.project,
+      projectRoot: out.projectRoot,
+      branch: out.branch,
+      baseBranch: out.baseBranch,
+      identity: out.identity,
+      worktreePath: out.worktreePath ?? null,
       commit: null,
       pr: null,
       pushAttempts: 0,
       buildStatus: null,
-    }];
+    };
+    // `platform` and `remoteType` are non-nullable enums: omit rather than null.
+    if (typeof out.remoteType === "string") {
+      entry.remoteType = out.remoteType;
+      entry.platform = out.remoteType;
+    }
+    out.projects = [entry];
   }
 
   return out;

package/pipeline/schemas/prefs.schema.json

@@ -5,6 +5,11 @@
   "description": "User-level preferences. Written to $HOME/.claude/multi-agent-preferences.json. Never committed. Never synced to the open-source repo \u2014 may contain personal data.",
   "type": "object",
   "additionalProperties": false,
+  "patternProperties": {
+    "^_": {
+      "description": "Documentation-only blocks shipped in preferences-template.json (_figmaConfigTemplate, _derivedSkillSourcesTemplate, _devToolkitTemplate). Copy-paste examples, never read by the pipeline."
+    }
+  },
   "required": [
     "schemaVersion",
     "global",
@@ -101,7 +106,7 @@
         "keychainMapping": {
           "type": "object",
           "additionalProperties": false,
-          "description": "Maps logical token names to actual Keychain item names. Pipeline looks up tokens via `security find-generic-password -s <mapped-name>` (or `pipeline/lib/credential-store.sh get` cross-platform). 12 services covered: jira, bitbucket, bitbucket_token, bitbucket_user, github, confluence, figma, figma_mcp, fortify, firebase, jenkins, npm.",
+          "description": "Maps logical token names to actual Keychain item names. Pipeline looks up tokens via `security find-generic-password -s <mapped-name>` (or `pipeline/lib/credential-store.sh get` cross-platform). Covered keys: jira, bitbucket, bitbucket_token, bitbucket_user, github, confluence, figma, figma_pat, figma_user, figma_mcp, fortify, graylog, firebase, jenkins, npm, claude_oauth_token, claude_oauth_token_fallback.",
           "properties": {
             "jira": {
               "type": [
@@ -164,6 +169,34 @@
                 "null"
               ]
             },
+            "figma_pat": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "Figma Personal Access Token. Tier 2 of the Figma access chain (REST API) resolves this key."
+            },
+            "figma_user": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "Figma account identifier, when the REST flow needs it alongside figma_pat."
+            },
+            "claude_oauth_token": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "Claude Code OAuth token used by headless / scheduled runs."
+            },
+            "claude_oauth_token_fallback": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "Secondary OAuth token used when the primary is rate-limited or expired."
+            },
             "firebase": {
               "type": [
                 "string",
@@ -499,8 +532,39 @@
           }
         },
         "defaultJiraKey": {
-          "type": "string",
-          "description": "Default Jira project key used for placeholder replacement."
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Default Jira project key used for placeholder replacement. null until /multi-agent:setup onboards a Jira project."
+        },
+        "modelFallback": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Model-tier fallback policy. When the premium tier is unavailable (quota, dispatch error, or an expired premium window) the pipeline drops to fallbackModel instead of failing the phase.",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "Master switch for tier fallback."
+            },
+            "premiumTierUntil": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "ISO date after which the premium tier is assumed gone. null = no expiry known."
+            },
+            "fallbackModel": {
+              "type": "string",
+              "description": "Model id used when the premium tier is unavailable."
+            },
+            "onDispatchError": {
+              "type": "boolean",
+              "default": true,
+              "description": "Also fall back when a dispatch call errors, not only on quota."
+            }
+          }
         },
         "hosts": {
           "type": "object",
@@ -1130,6 +1194,94 @@
           "default": false,
           "description": "v7.0.0+ \u2014 Dynamic trigger-based skill loading. When enabled, the orchestrator reads `~/.claude/skills/.skills-index.json` after Phase 1 analysis and injects only the top-N matched skills into subagent prompts (via `match-skills.mjs`), instead of relying on eager-loaded SKILL.md bodies. Large token win on small tasks; no visible behavior change on big ones where many skills match. Requires either a full install (index is always shipped) or the `install.js --index-only` mode for users who want skill bodies fetched on demand. Off by default in v7.0 \u2014 flip to `true` to opt in; a future v7.x may flip the default once enough telemetry confirms no regression."
         },
+        "derivedSkillSources": {
+          "type": "array",
+          "description": "v11.3.0+. Skills/components in a project that were derived from an upstream marketplace plugin. `/multi-agent:refactor` Step 0b compares each entry's `derivedFromVersion` against the installed upstream version and reports drift (plan band D). Local-only: it may name private marketplaces, so it is never synced into the public repo. Empty array = the drift step is skipped.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "label",
+              "localPath",
+              "upstreamPlugin",
+              "derivedFromVersion"
+            ],
+            "properties": {
+              "label": {
+                "type": "string",
+                "description": "Human name for this derivation, shown in the drift table."
+              },
+              "localPath": {
+                "type": "string",
+                "description": "Repo-relative directory holding our derived copy."
+              },
+              "upstreamMarketplace": {
+                "type": "string",
+                "description": "Installed marketplace name, resolved under ~/.claude/plugins/cache/<marketplace>/."
+              },
+              "upstreamPlugin": {
+                "type": "string",
+                "description": "Upstream plugin name inside that marketplace."
+              },
+              "upstreamSkills": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "The upstream skill names we took."
+              },
+              "derivedFromVersion": {
+                "type": "string",
+                "description": "Upstream version we last synced from. Bumped after a drift port is applied."
+              },
+              "upstreamRepoUrl": {
+                "type": "string",
+                "description": "Used only when the marketplace is not installed locally (WebFetch fallback)."
+              }
+            }
+          }
+        },
+        "devToolkit": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "v12.6.0+. The companion MCP server that serves the pipeline's device and browser tools (dev-toolkit-mcp). Two commands read this: `/multi-agent:refactor` Step 0c researches current MCP practice and audits that repo against it (plan band E), and `/multi-agent:sync` Step 3d ships it when it moved (gates, commit, publish). When absent, both commands fall back to auto-detecting the repo from the `mcpServers` registration in ~/.claude.json / ~/.claude/settings.json, and skip silently when that fails. Never a hardcoded path.",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "Set false to skip both the refactor band-E research and the sync ship step."
+            },
+            "label": {
+              "type": "string",
+              "description": "Human name used in reports."
+            },
+            "localPath": {
+              "type": "string",
+              "description": "Working copy of the companion repo. `$HOME` and `~` are expanded. When omitted, resolved from the MCP registration (dirname of the stdio server's script)."
+            },
+            "mcpServerName": {
+              "type": "string",
+              "default": "dev-toolkit",
+              "description": "Registered MCP server name, used for the auto-detect fallback and for telling the user whether a restart or a reinstall is needed after a publish."
+            },
+            "packageName": {
+              "type": "string",
+              "description": "Published package name, e.g. @<scope>/<package>. Read from the repo's package.json when omitted."
+            },
+            "registry": {
+              "type": "string",
+              "enum": [
+                "github-packages",
+                "npmjs",
+                "none"
+              ],
+              "default": "github-packages",
+              "description": "Publish target for Step 3d. `none` means commit + push only, never publish. The concrete URL comes from the repo's publishConfig; the token comes from the `npm` logical Keychain key through a throwaway --userconfig."
+            },
+            "repoUrl": {
+              "type": "string",
+              "description": "https remote, used in reports and when the working copy has to be cloned by the user."
+            }
+          }
+        },
         "recentAccounts": {
           "type": "array",
           "description": "v7.3.0+. Last-used-first LRU of account ids (from account-resolver.sh). Used by autopilot to pick the most recent account when multiple are configured.",
@@ -1217,8 +1369,8 @@
               "items": {
                 "type": "string"
               },
-              "maxItems": 10,
-              "description": "Bitbucket/generic default reviewers (usernames)."
+              "maxItems": 40,
+              "description": "Bitbucket/generic default reviewers (usernames). Real corporate reviewer groups run well past ten members."
             },
             "githubDefaultReviewers": {
               "type": "array",
@@ -1290,6 +1442,10 @@
               "format": "date-time",
               "description": "Timestamp of last task start against this project."
             },
+            "componentDevWorkflow": {
+              "type": "boolean",
+              "description": "Project follows the component (Configuration / View / Modifiers) development workflow, so Phase 3 dispatches the component skills instead of the standard TDD flow."
+            },
             "figmaConfigPath": {
               "type": "string",
               "description": "Path to per-project figma-config.json (for Figma pipeline projects)."

package/pipeline/schemas/token-budget.json

@@ -12,6 +12,6 @@
     "phase-6-commit":    { "max_tokens": 6150, "warn_tokens": 5400 },
     "phase-7-report":    { "max_tokens": 5600, "warn_tokens": 4950 }
   },
-  "total_max_tokens": 50000,
-  "note": "Token estimate = ceil(chars / 4). Per-phase budget rule: warn = current+10% (rounded to nearest 50), max = current+25%. Gives ~6 edit cycles of headroom before warn trips  -  intentionally quiet under normal maintenance, loud when a phase grows unusually. Only the active phase is loaded (lazy). Recalibrated at v10.0.0 after the validator/consistency/simplifier/lesson gate contracts landed in phases 1-4. Recalibrated again at v10.9.0 after the verify-by-test (Phase 4 Step 3.7), update-check (Phase 0 Step 0.6), immutable-test (Phase 3 GREEN) and redTests re-entry contracts landed  -  Step 3.7 prose was compressed to a pointer into refs/features/verify-by-test.md before the recalibration."
+  "total_max_tokens": 51000,
+  "note": "Token estimate = ceil(chars / 4). Per-phase budget rule: warn = current+10% (rounded to nearest 50), max = current+25%. Gives ~6 edit cycles of headroom before warn trips  -  intentionally quiet under normal maintenance, loud when a phase grows unusually. Only the active phase is loaded (lazy). Recalibrated at v10.0.0 after the validator/consistency/simplifier/lesson gate contracts landed in phases 1-4. Recalibrated again at v10.9.0 after the verify-by-test (Phase 4 Step 3.7), update-check (Phase 0 Step 0.6), immutable-test (Phase 3 GREEN) and redTests re-entry contracts landed  -  Step 3.7 prose was compressed to a pointer into refs/features/verify-by-test.md before the recalibration. Total bumped 50000 -> 51000 at v12.5.0 after the worktree residue/traversal-prune contract (Phase 0 + Phase 5 heal) and the Reflexion causal-diagnosis contract (Phase 4 lesson memory) landed; the prose was compressed first (161 tokens reclaimed) and every per-phase max still passes  -  only the aggregate needed room."
 }

package/pipeline/schemas/triage-corpus.schema.json

@@ -26,6 +26,10 @@
     "issue": { "type": "string", "minLength": 1 },
     "fix":  { "type": ["string", "null"] },
     "reason": { "type": ["string", "null"] },
-    "reviewer": { "type": ["string", "null"] }
+    "reviewer": { "type": ["string", "null"] },
+    "file_sha": {
+      "type": ["string", "null"],
+      "description": "git blob SHA (git hash-object) of `file` at ingest time. On query, a differing current hash flags the hit stale (freshness gate). Null when not computable (file gone / not a git repo)."
+    }
   }
 }

package/pipeline/scripts/README.md

@@ -1,10 +1,10 @@
 # Pipeline Scripts  -  Category Index
 
-The `pipeline/scripts/` directory holds 59 shell scripts + 12 Node.js `.mjs` scripts in a flat layout. v6.0.0 evaluated moving them into `smoke/`, `hooks/`, `runtime/` subdirs and decided against it: each path change would need to propagate through `package.json` globs, `install.js` deploy logic, npm scripts, sibling script calls, and CI workflow references  -  a 40+ file touch radius with high regression risk for minor polish value.
+The `pipeline/scripts/` directory holds 148 shell scripts + 45 Node.js `.mjs` scripts in a flat layout. v6.0.0 evaluated moving them into `smoke/`, `hooks/`, `runtime/` subdirs and decided against it: each path change would need to propagate through `package.json` globs, `install.js` deploy logic, npm scripts, sibling script calls, and CI workflow references  -  a 40+ file touch radius with high regression risk for minor polish value.
 
-Instead, this README is the category index. Use it to navigate.
+Instead, this README is a curated category index of the key scripts, not an exhaustive listing. Use it to navigate.
 
-## Smoke scripts (42 files  -  `smoke-*.sh`)
+## Smoke scripts (118 files  -  `smoke-*.sh`)
 
 Validate contracts. Each emits `══ <name> smoke: N passed, M failed ══` on completion (the `smoke-personal-data.sh` + `smoke-token-budget.sh` suites use `PASS:` / `warnings:` variants). Run via `npm test` (chained) or individually.
 
@@ -57,6 +57,7 @@ Validate contracts. Each emits `══ <name> smoke: N passed, M failed ══`
 - `smoke-search.sh`  -  `/multi-agent:search` log search + smart ranking
 - `smoke-subagent-validators.sh`  -  Phase 1/2 validator schemas
 - `smoke-telemetry.sh`  -  opt-in telemetry contract
+- `smoke-learning-curve.sh`  -  `learning-curve.mjs` metrics-trend contract
 - `smoke-validator-contradiction.sh`  -  Phase 4 approved/blocking contradiction detection
 - `smoke-pre-commit.sh`  -  pre-commit hook integration
 
@@ -81,12 +82,13 @@ Shell scripts invoked during pipeline execution.
 - `github-ssh-setup.sh`  -  first-run SSH key setup helper
 - `sync-parity-check.sh`  -  manual parity verification helper
 
-## Node.js helpers (12 `.mjs` files)
+## Node.js helpers (45 `.mjs` files)
 
 - `aggregate-metrics.mjs`  -  collects telemetry aggregates
+- `learning-curve.mjs`  -  time-bucketed trend over `metrics.jsonl` (first-pass clean rate, review cycles, rework/task, tokens/task, cache ratio); `--bucket`, `--since`, `--json`, `--markdown`
 - `eval-triage.mjs`  -  runs the 10 triage eval fixtures
 - `gen-skills-index.mjs`  -  regenerates `pipeline/skills/shared/README.md` skill catalog
-- `migrate-prefs.mjs`  -  preference migration driver (v2.0.0 → v2.1.0 → v2.2.0)
+- `migrate-prefs.mjs`  -  preference migration driver (v2.0.0 through v2.4.0)
 - `migrate-state.mjs`  -  generic migration runner (reads `schemas/migrations/`)
 - `token-budget-report.mjs`  -  per-phase token usage report
 - `validate-analysis.mjs`, `validate-planning.mjs`, `validate-reviewer.mjs`, `validate-triage.mjs`  -  per-phase output validators

package/pipeline/scripts/classify-plan-safety.mjs

@@ -34,8 +34,10 @@
 //   - infrastructure        20    -  touches Dockerfile, CI yaml, Gradle wrapper,
 //                                    package.json resolutions / engines, install.js
 //
-// recommendPause = true when score >= 50 (tuned: any two medium signals or
-// any one heavy signal flips it).
+// recommendPause = true when any one heavy signal (weight >= 30) fires, OR two
+// or more medium-and-above signals (weight >= 20) fire, OR the accumulated
+// score reaches 50. A score threshold alone cannot express the first two
+// clauses: the heaviest single rule is 35 and two medium signals can total 45.
 //
 // Exit codes: 0 = verdict produced, 1 = malformed input, 2 = usage error.
 
@@ -168,7 +170,10 @@ if (infraHits.length > 0) {
 
 // --- aggregate ---
 const score = reasons.reduce((s, r) => s + r.weight, 0);
-const recommendPause = score >= 50;
+const heavyHits = reasons.filter((r) => r.weight >= 30);
+const mediumOrAboveHits = reasons.filter((r) => r.weight >= 20);
+const recommendPause =
+  heavyHits.length >= 1 || mediumOrAboveHits.length >= 2 || score >= 50;
 
 let summary;
 if (recommendPause) {