@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/pipeline/schemas/prefs.schema.json

@@ -15,7 +15,7 @@
     "schemaVersion": {
       "type": "string",
       "enum": ["2.0.0", "2.1.0", "2.2.0", "2.3.0", "2.4.0", "2.5.0", "2.6.0", "2.7.0", "2.8.0"],
-      "description": "v2.0.0: pre-v3.7. v2.1.0: v3.7+ adds identities[].servicePatMap, platformIdentityRouting, recentGroups, recentBranches, serviceStatus, settings, expanded keychainMapping. v2.2.0: v6.0.0 formalizes v5.7 / v5.8 additions (reportChannels, reportContent with technicalAnalysis, wikiScope, autopilotReportTimeoutSeconds) that had been running as 2.1.0 sub-migrations without a proper version bump. v2.5.0: v14.0.0 adds global.skillConformance (Phase 4 criteria resolution) and declares global.ship.autoFix, which the tail command's spec had referenced as global.finish.autoFix without ever declaring it. v2.6.0: v15.0.0 renames global.ship to global.resumeLocal (/multi-agent:ship -> :resume-local). v2.7.0: v19.0.0 drops the analysis Lite mode (global.analysisPhase.mode keeps a single value 'full') and adds global.modelRouting, which ships disabled. v2.8.0: v20.0.0 folds :resume-local into :resume and renames global.resumeLocal to global.resume."
+      "description": "v2.0.0: pre-v3.7. v2.1.0: v3.7+ adds identities[].servicePatMap, platformIdentityRouting, recentGroups, recentBranches, serviceStatus, settings, expanded keychainMapping. v2.2.0: v6.0.0 formalizes v5.7 / v5.8 additions (reportChannels, reportContent with technicalAnalysis, wikiScope, autopilotReportTimeoutSeconds). v2.5.0: v14.0.0 adds global.skillConformance (Phase 4 criteria resolution) and declares global.ship.autoFix. v2.6.0: v15.0.0 renames global.ship to global.resumeLocal (/multi-agent:ship -> :resume-local). v2.7.0: v19.0.0 drops the analysis Lite mode (global.analysisPhase.mode keeps a single value 'full') and adds global.modelRouting, which ships disabled. v2.8.0: v20.0.0 folds :resume-local into :resume and renames global.resumeLocal to global.resume."
     },
     "global": {
       "type": "object",
@@ -888,7 +888,7 @@
         "testBaseline": {
           "type": "object",
           "additionalProperties": false,
-          "description": "Phase 0 test baseline. When enabled, Phase 0 runs the SAME test command Phase 3 Gate 3 uses and records which tests were already failing before this run touched anything, so Phase 3 stops attributing an inherited red suite to the current work. Three outcomes are stored, never two: green, red (with the failing set when it can be parsed, otherwise the log path alone), or unknown when the command is absent or the time cap was hit. Off by default because on iOS the run costs a full xcodebuild test before any work starts. Pattern source: obra/superpowers using-git-worktrees Step 3 'Verify Clean Baseline', extended from ask-the-user to a stored set Phase 3 can subtract.",
+          "description": "Phase 0 test baseline. When enabled, Phase 0 runs the SAME test command the Phase 2 exit gate's Gate 3 uses and records which tests were already failing before this run touched anything, so the gate stops attributing an inherited red suite to the current work. Three outcomes are stored, never two: green, red (with the failing set when it can be parsed, otherwise the log path alone), or unknown when the command is absent or the time cap was hit. Off by default because on iOS the run costs a full xcodebuild test before any work starts. Pattern source: obra/superpowers using-git-worktrees Step 3 'Verify Clean Baseline', extended from ask-the-user to a stored set Phase 3 can subtract.",
           "properties": {
             "enabled": {
               "type": "boolean",
@@ -1258,7 +1258,51 @@
             },
             "reportAs": {
               "type": "string",
-              "description": "Pins the reporting user (a SCM login) for a machine with more than one identity, where identities[0] or the active gh account may be a work account the usage panel should not attribute the run to. Reporting resolves this first, then identities[0].username, then gh api user, then the OS user. Local prefs only, never synced."
+              "description": "Preferred GitHub login when more than one account is logged in to gh. It is checked first, and used only if that account can read accessRepo; otherwise the next logged-in account with access is used. Local prefs only, never synced."
+            },
+            "accessRepo": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$",
+              "default": "mmerterden/multi-agent-pipeline",
+              "description": "owner/repo whose read access decides the reporting identity (usage-identity.mjs). Reporting uses the first logged-in gh account that can read it, and sends nothing when none can."
+            },
+            "login": {
+              "type": ["string", "null"],
+              "description": "Cached result of the identity check: the logged-in GitHub account that can read accessRepo, or null when none could. Written by usage-identity.mjs; refresh with `node ~/.claude/scripts/usage-identity.mjs --refresh`."
+            },
+            "loginRepo": {
+              "type": "string",
+              "description": "The accessRepo the cached login was checked against. A different accessRepo invalidates the cache."
+            },
+            "loginCheckedAt": {
+              "type": "string",
+              "description": "ISO time of the last identity check. Re-checked after 7 days, or after 1 day when no account had access."
+            },
+            "loginReason": {
+              "type": ["string", "null"],
+              "description": "Why no account qualified at the last check. Null when login is set."
+            },
+            "registeredAs": {
+              "type": "string",
+              "description": "The login the stored ingest token was issued for. usage-register.mjs replaces the token when the verified login differs, because the server pins each token to one login."
+            },
+            "includeTitle": {
+              "type": "boolean",
+              "default": false,
+              "description": "Send a one-line task title (at most 80 characters, code spans, markup and absolute paths removed) with each run record. Off by default: a title is the tracker's text, not pipeline metadata."
+            },
+            "includePrUrl": {
+              "type": "boolean",
+              "default": false,
+              "description": "Send the PR URL with a run that opened one. Off by default because the URL names the repository; without it the record carries only whether a PR was opened."
+            },
+            "trustedHosts": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              },
+              "description": "Extra https hosts that may receive the GitHub login proof at registration, besides the default reporting host. Only for a self-hosted endpoint you trust with the account's gh token."
             }
           }
         },
@@ -1271,7 +1315,7 @@
               "type": "string",
               "enum": ["full"],
               "default": "full",
-              "description": "Retained with a single value so a preferences file that sets it stays valid. Section depth is no longer a mode: Lite was removed in v19.0.0 because it chose sections from a fixed list while Locked 2 chooses them from evidence, and the two disagreed in both directions. Sections render when they have evidence and are dropped when they do not. The `auto` and `lite` values are rewritten to `full` by the 2.6.0-to-2.7.0 migration."
+              "description": "Retained with a single value so a preferences file that sets it stays valid. Section depth is not a mode: Locked 2 chooses sections from evidence, so a section renders when it has evidence and is dropped when it does not (ADR-0015). The `auto` and `lite` values are rewritten to `full` by the 2.6.0-to-2.7.0 migration."
             },
             "forceFull": {
               "type": "boolean",
@@ -1547,7 +1591,7 @@
         "memoryRecall": {
           "type": "object",
           "additionalProperties": false,
-          "description": "v15.10+  -  How the per-repo memory stores decide WHICH entries to inject. Ranking is BM25 over the stored text (identifier-aware, IDF-weighted) fused with recency by Reciprocal Rank Fusion, shared by triage-memory.mjs and learnings-ledger.mjs via pipeline/scripts/_retrieval.mjs. Zero dependencies: no embedding service, no vector store, no extra model call. Before this, the triage corpus scored a raw token overlap and the ledger brief replayed the newest N entries, both of which stop discriminating once a repo has a few hundred rows.",
+          "description": "v15.10+  -  How the per-repo memory stores decide WHICH entries to inject. Ranking is BM25 over the stored text (identifier-aware, IDF-weighted) fused with recency by Reciprocal Rank Fusion, shared by triage-memory.mjs and learnings-ledger.mjs via pipeline/scripts/_retrieval.mjs. Zero dependencies: no embedding service, no vector store, no extra model call. Raw token overlap and newest-N replay both stop discriminating once a repo has a few hundred rows, which is why ranking fuses the two signals.",
           "properties": {
             "strategy": {
               "type": "string",
@@ -1716,7 +1760,7 @@
         "dynamicSkillLoading": {
           "type": "boolean",
           "default": false,
-          "description": "v7.0.0+ - 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. The index ships with every install - full and `--index-only` alike - so this is safe to flip on any installed tree. It was not always: until v13.6 only `--index-only` copied the index, and `match-skills.mjs` resolved its default index path relative to a repo checkout, so enabling this on a normal install produced `cannot read index` and a silent fall back to eager loading. Off by default - flip to `true` to opt in; a future release may flip the default once enough telemetry confirms no regression."
+          "description": "v7.0.0+ - 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. The index ships with every install - full and `--index-only` alike - so this is safe to flip on any installed tree. Off by default - flip to `true` to opt in; a future release may flip the default once enough telemetry confirms no regression."
         },
         "derivedSkillSources": {
           "type": "array",
@@ -1758,9 +1802,21 @@
                 "description": "Upstream version we last synced from, read from the manifest named by `upstreamVersionSource`. Bumped after a drift port is applied."
               },
               "upstreamVersionSource": {
-                "enum": ["marketplace.json", "plugin.json"],
+                "enum": ["marketplace.json", "plugin.json", "git-paths"],
                 "default": "marketplace.json",
-                "description": "Which upstream manifest carries the authoritative version. Defaults to marketplace.json because that is what a marketplace consumer resolves; some upstreams keep plugin.json deliberately unused, so reading it silently records a version nobody ships. Recording from the wrong manifest is how an entry here sat at 0.7.0 while the marketplace said 0.6.0."
+                "description": "git-paths: the upstream ships no manifest, so derivedFromVersion is the commit the port was taken from and drift is any later commit on upstreamRef touching upstreamPaths, read from upstreamLocalClone only. Otherwise, which upstream manifest carries the authoritative version. Defaults to marketplace.json because that is what a marketplace consumer resolves; some upstreams keep plugin.json deliberately unused, so reading it silently records a version nobody ships. Recording from the wrong manifest is how an entry here sat at 0.7.0 while the marketplace said 0.6.0."
+              },
+              "upstreamPaths": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "git-paths only. Repo-relative paths whose commits count as upstream changes."
+              },
+              "upstreamRef": {
+                "type": "string",
+                "default": "origin/main",
+                "description": "git-paths only. The ref compared against derivedFromVersion."
               },
               "upstreamLocalClone": {
                 "type": "string",
@@ -2209,6 +2265,21 @@
               },
               "maxItems": 4,
               "description": "Absolute local paths of this project's counterpart app repo - the same product on the other mobile platform. Read by Phase 3's platform-parity cross-check. Learned, not configured: the first run that resolves a counterpart writes it here and every later run reuses it without asking. An entry whose path is gone, or whose marker files no longer resolve to the mirrored stack, is dropped and re-detected rather than trusted. Same shape as webRoots."
+            },
+            "research": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "Optional read-only evidence providers a research pass (/multi-agent:research, refs/research/engine.md) may query for this project on top of its core sources: tracker comments and links, similar closed items, the repository and its history, and the documents the item links. Absent means core sources only.",
+              "properties": {
+                "providers": {
+                  "type": "array",
+                  "uniqueItems": true,
+                  "items": {
+                    "enum": ["graylog", "crashlytics", "counterpart"]
+                  },
+                  "description": "graylog: lib/fetch-graylog.sh log search; crashlytics: lib/fetch-crashlytics.sh crash groups; counterpart: this project's counterpartRoots, read only. Each uses credentials or paths already onboarded; one that cannot run is skipped and named in research.md, never asked for."
+                }
+              }
             }
           }
         }

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

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/research-output.schema.json",
+  "title": "Multi-Agent Pipeline  -  research output",
+  "description": "What a research pass (/multi-agent:research, engine multi-agent-refs/research/engine.md) writes to <run state dir>/research/research.json. research-gate.mjs reads it and decides which gaps closed; nothing here is taken on the writer's word. The gaps themselves come from the run state (maturity blockers and warnings, or analysis.openQuestions), so a finding can only address a gap the run actually has. Every source carries a label: evidence (tracker or fetched document, cited by URL or id and quoted), repo (file:line or a commit, quoted) or inference (reasoning, never enough on its own to close a gap).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "findings"],
+  "properties": {
+    "version": { "type": "integer", "const": 1 },
+    "kind": {
+      "enum": ["maturity", "open-questions"],
+      "description": "Which gap list the pass worked on. The gate takes the run state's own answer when the two disagree."
+    },
+    "item": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "kind": { "enum": ["jira", "github", "freetext"] },
+        "key": { "type": ["string", "null"] },
+        "url": { "type": ["string", "null"] }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["gap", "answer", "sources"],
+        "properties": {
+          "gap": {
+            "type": "string",
+            "minLength": 1,
+            "description": "A maturity gap code (description_empty, no_repro_steps, ...) or an open question id (Q1, or the row's own id)."
+          },
+          "category": {
+            "enum": [
+              "description",
+              "reproduction",
+              "acceptance-criteria",
+              "business-rule",
+              "status",
+              "scope",
+              "technical",
+              "other"
+            ],
+            "description": "The writer's view. The gate can only make it stricter: a gap that reads as acceptance criteria or a business rule is treated as one whatever this says."
+          },
+          "answer": { "type": "string", "minLength": 1 },
+          "sources": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "$ref": "#/$defs/source" }
+          }
+        }
+      }
+    },
+    "notes": { "type": "string" }
+  },
+  "$defs": {
+    "source": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["label", "ref", "quote"],
+          "properties": {
+            "label": { "const": "evidence" },
+            "ref": {
+              "type": "string",
+              "minLength": 1,
+              "description": "A URL or id present in research/context.json: the item, one of its comments, links or related issues, or a fetched document."
+            },
+            "quote": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Text found in that source, whitespace-insensitive."
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["label", "file", "line", "quote"],
+          "properties": {
+            "label": { "const": "repo" },
+            "file": { "type": "string", "minLength": 1 },
+            "line": { "type": "integer", "minimum": 1 },
+            "quote": { "type": "string", "minLength": 1 }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["label", "commit", "quote"],
+          "properties": {
+            "label": { "const": "repo" },
+            "commit": { "type": "string", "pattern": "^[0-9a-f]{7,40}$" },
+            "quote": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Text in the commit's message or diff."
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["label", "rationale"],
+          "properties": {
+            "label": { "const": "inference" },
+            "rationale": { "type": "string", "minLength": 1 }
+          }
+        }
+      ]
+    }
+  }
+}

package/pipeline/schemas/review-file-exclusions.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/review-file-exclusions.schema.json",
+  "title": "Review file exclusions",
+  "description": "review-file-exclusions.json: globs of files review skips, each with the reason.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "patterns"],
+  "properties": {
+    "$comment": { "type": "string" },
+    "version": { "type": "integer", "minimum": 1 },
+    "patterns": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["glob", "reason"],
+        "properties": {
+          "glob": { "type": "string", "minLength": 1 },
+          "reason": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

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

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/reviewer-output.schema.json",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "title": "Multi-Agent Pipeline  -  Phase 3 reviewer output",
-  "description": "Contract for a single code-reviewer subagent's JSON output in Phase 4 Step 2. Every host dispatches 3 parallel reviewers; the middle slot is CLI-aware: Claude Code (Fable, Opus, Sonnet); Copilot CLI (Opus, GPT-5.4, Sonnet); Codex CLI dispatches 3 (gpt-5.6 at xhigh, gpt-5.4, gpt-5.6 at medium). Every reviewer must return an object matching this shape before Opus triage merges them. v1.1.0 adds the rule-ID conformance checklist: when the orchestrator supplies a ${CRITERIA} block (Phase 3 Step 1.78), the reviewer must return one conformance row per selected rule ID. Findings alone cannot answer 'was this applied completely' - a reviewer that opened nothing returns the same empty findings array as one that checked everything. v1.2.0 adds the optional per-finding fingerprint (Phase 3 Step 2.1): the stable id a finding keeps across review rounds. v1.4.0 adds the optional per-finding `security` envelope (OWASP + CWE + CVSS + evidence + remediation): the security-auditor emits reviewer-output objects whose findings carry it, so a blocking security finding merges at Step 3.0 and blocks Phase 4 like any reviewer blocker. General reviewers omit it. Its shape mirrors security-finding.schema.json, kept in step by smoke-security-schema-parity.sh.",
+  "description": "Contract for a single code-reviewer subagent's JSON output in Phase 4 Step 2. Every host dispatches 3 parallel reviewers; the middle slot is CLI-aware: Claude Code (Fable, Opus, Sonnet); Copilot CLI (Opus, GPT-5.4, Sonnet); Codex CLI dispatches 3 (gpt-5.6 at xhigh, gpt-5.4, gpt-5.6 at medium). Every reviewer must return an object matching this shape before Opus triage merges them. v1.1.0 adds the rule-ID conformance checklist: when the orchestrator supplies a ${CRITERIA} block (Phase 3 Step 1.78), the reviewer must return one conformance row per selected rule ID. Findings alone cannot answer 'was this applied completely' - a reviewer that opened nothing returns the same empty findings array as one that checked everything. v1.2.0 adds the optional per-finding fingerprint (Phase 3 Step 2.1): the stable id a finding keeps across review rounds. v1.4.0 adds the optional per-finding `security` envelope (OWASP + CWE + CVSS + evidence + remediation): the security-auditor emits reviewer-output objects whose findings carry it, so a blocking security finding merges at Step 3.0 and blocks Phase 4 like any reviewer blocker. General reviewers omit it. Its shape mirrors security-finding.schema.json, kept in step by smoke-security-schema-parity.sh. v1.5.0 adds the optional per-finding `quote`, `preExisting` and `baselineEvidence` (see triage-output.schema.json).",
   "type": "object",
   "additionalProperties": false,
   "required": ["findings", "approved"],
@@ -207,8 +207,12 @@
               "required": ["before", "after"],
               "description": "The fix as a before/after pair.",
               "properties": {
-                "before": { "type": "string" },
-                "after": { "type": "string" }
+                "before": {
+                  "type": "string"
+                },
+                "after": {
+                  "type": "string"
+                }
               }
             },
             "endpoint": {
@@ -225,6 +229,38 @@
               "description": "How to confirm the fix worked - the test to add or check to run."
             }
           }
+        },
+        "quote": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Verbatim text of the cited line (or of the lines starting there). verify-citations.mjs requires it to match after whitespace is collapsed; a line number alone only says the line exists."
+        },
+        "preExisting": {
+          "type": "boolean",
+          "description": "The finding is claimed to exist on the base commit already. In an unattended run the claim needs baselineEvidence."
+        },
+        "baselineEvidence": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["sha"],
+          "description": "What backs a pre-existing claim, checked in unattended runs by verify-citations.mjs (_pre-existing.mjs). sha must be the run's base commit or an ancestor of it; for a code finding the cited line must be present in that file there; for a failing test, testId must be in state.baseline.tests.failing or logPath must be a non-empty log of the check run at the base.",
+          "properties": {
+            "sha": {
+              "type": "string",
+              "minLength": 7,
+              "description": "The base commit the claim is about."
+            },
+            "testId": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The failing test the claim names, as it appears in state.baseline.tests.failing."
+            },
+            "logPath": {
+              "type": "string",
+              "minLength": 1,
+              "description": "A log of the check run at sha."
+            }
+          }
         }
       }
     }