@mmerterden/multi-agent-pipeline 20.21.0 → 20.23.0

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

@@ -134,9 +134,11 @@ Phase 0 Step 1b catalogued every typed external link from the task description i
 → context injection: total=<N>, fetched=<n>, pending=<n>, by-type={swagger:F/P, confluence:F/P, ...}
 ```
 
-#### Step 2  -  Stack Detection
+#### Step 1.6  -  Product context (advisory, read-only)
+
+`product-context.mjs refs` names the product's other repos (not the ones developed here); exit 2 = skip. Read them at their latest branch, pinned to a sha, via `repo_*`, and record each join key as `implemented`, `not-yet-implemented` or `diverges` in `state.productContext`. Never blocking. Steps: `$HOME/.claude/multi-agent-refs/features/product-context.md`.
 
-Two questions shared one answer here, and the shared answer was wrong on both.
+#### Step 2  -  Stack Detection
 
 **What the repo is BUILT WITH** - one owner, no marker list in this file:
 
@@ -146,22 +148,15 @@ bash $HOME/.claude/lib/stack-detect.sh --json "$PROJECT_ROOT"
 
 Persist `.stacks` as `state.stacks[]` (a subset of `ios android web backend`,
 always in that order) and `.why` as `state.stackWhy`. Empty is a real
-answer meaning no marker matched; `stackWhy` separates that from a directory that
-could not be read, and a caller that cannot tell those apart treats an unreadable
-repo as a language-free one. `state.stacks[]` routes toolkits, through
+answer (no marker matched); `stackWhy` separates it from an unreadable directory,
+which must never read as a language-free repo. `state.stacks[]` routes toolkits, through
 `pluginsForStacks()` in `$HOME/.claude/scripts/_stack-routing.mjs`. Do not derive
 plugin names here.
 
-`AndroidManifest.xml` sits at `<module>/src/main/`, depth 4 in a multi-module app,
-so the owner goes to depth 5 for that one file. It prunes submodules (a vendored
-checkout ships its own `Package.swift`) and checks the root first so traversal
-order cannot decide.
-
 **What the code is WRITTEN IN** - a different axis with its own field.
 `state.detectedStack[]` stays the language answer (`ios`, `python`, `node`, `go`,
 `docker`, `monorepo`): `graph-build.mjs --stack` takes `ios|android|node|python|go`
-and has no notion of `web` or `backend`. Folding the two together is what made a
-Gradle-built JVM service read as an Android app.
+and has no notion of `web` or `backend`, so the two never fold together.
 
 This informs:
 
@@ -173,9 +168,9 @@ This informs:
 
 Gated by `prefs.global.repoMap.enabled` (default: `false`). When enabled, runs `$HOME/.claude/scripts/repo-map.mjs` and injects the budgeted result into each Explore prompt as `${REPO_MAP}`. Aider-style: deterministic, no embeddings, sub-second, advisory only. Full wiring (helper invocation, properties, when-to-enable): `$HOME/.claude/multi-agent-refs/features/repo-map.md`.
 
-#### Step 2.6  -  Code Graph Injection (advisory, opt-in)
+#### Step 2.6  -  Code Graph Injection (advisory)
 
-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`.
+Gated by `prefs.global.codeGraph.enabled` (default: `true`). 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.
 

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

@@ -4,7 +4,7 @@
 
 ## Phase 2 Pre-flight (BLOCKING, v9.0.0)
 
-Per Locked decision 30, Phase 2 Dev consumes the analysis document as the sole design source. **Figma** MCP / REST / URL fetches are forbidden; the toolkit MCP is not, and Steps 3.4 and 3.55 call it.
+Per Locked decision 30, Phase 2 Dev consumes the analysis document as the sole design source. **Figma** MCP / REST / URL fetches are forbidden; the toolkit MCP is not (Steps 3.4, 3.55; `repo_read` checks `state.productContext` at its sha, copying nothing).
 
 Pre-flight steps (run in order, abort on failure).
 

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

@@ -55,9 +55,9 @@ Cost ledger: `phase-4.repo_map_emitted bytes=N budget=B cache_hit=true|false`  -
 
 #### Step 1.8  -  Platform parity cross-check (advisory, read-only)
 
-Runs when a counterpart app repo resolves AND the diff touches a screen,
-service, request model or localization file. Resolution is automatic and
-mirrored (ios ↔ android); the order and the learned pref live in the contract.
+Runs when a counterpart resolves AND the diff touches a screen, service,
+request model or localization file. Counterparts: `state.productContext`
+first, else mirrored (ios ↔ android); order and pref live in the contract.
 No counterpart, or an unattended run facing several, skips silently - no
 section, no placeholder, run unaffected.
 
@@ -66,13 +66,14 @@ counterpart repo is **read only**, and parity findings are **never blocking**.
 
 #### Step 1.75  -  Diff Risk Scoring (advisory)
 
-Before dispatching reviewers, run the deterministic diff risk scorer and inject the top-N files into each reviewer's prompt as a priority hint. **Advisory only  -  never gates the pipeline.** Heuristic, zero LLM, runs in well under a second.
+Before dispatching reviewers, run the deterministic diff risk scorer and inject the top-N files into each reviewer's prompt as a priority hint. **Advisory only  -  never gates the pipeline.** Zero LLM, sub-second.
 
-Score the diff **once, in full** (no `--top`): Steps 1.76/1.77 need every scored file (a shrinking test file ranked 20th; whether ANY file is high-stakes). The top-N hint is derived from that report, not a second git walk.
+Score the diff **once, in full** (no `--top`); Steps 1.76/1.77 need every file, the top-N hint derives from it, and `--graph` adds `dependents_reached`.
 
 ```bash
+GRAPH_PATH="$HOME/.claude/knowledge/${PROJECT_ROOT##*/}/code-graph.json"
 RISK_FULL=$(node $HOME/.claude/scripts/diff-risk-score.mjs \
-  --base "$BASE_BRANCH" --head HEAD \
+  --base "$BASE_BRANCH" --head HEAD --graph "$GRAPH_PATH" \
   --task-id "$TASK_ID" 2>/dev/null)
 echo "$RISK_FULL" | node $HOME/.claude/scripts/validate-diff-risk.mjs - >/dev/null 2>&1 || RISK_FULL=""
 

package/pipeline/multi-agent-refs/platform-parity.md

@@ -14,13 +14,13 @@ description: "Internal  -  cross-platform parity cross-check for Phase 4 and /mu
 - [Severity](#severity)
 <!-- /toc -->
 
-A feature that exists on iOS and Android is written twice, and the two copies
-drift. The drift is invisible from inside one repo: the iOS diff is
+A feature that exists on several platforms is written more than once, and the
+copies drift. The drift is invisible from inside one repo: the iOS diff is
 self-consistent, the tests pass, and nobody notices that the Android screen
 calls a different endpoint, sends one parameter fewer, or reads a localization
 key that no longer exists on the other side.
 
-This step reads the counterpart repo and reports what differs. It is advisory:
+This step reads the counterpart repositories and reports what differs. It is advisory:
 it never blocks, never edits, and its silence is never evidence.
 
 ## When it runs
@@ -29,6 +29,17 @@ The counterpart is **resolved automatically**. Nothing is asked in the normal
 case, because the answer is the same on every run of the same project and a
 question asked every time is a question people learn to dismiss.
 
+**Source 0, when present, replaces the rest.** If Phase 1 recorded
+`state.productContext[]` (`features/product-context.md`), every entry without
+an `error` is a counterpart: the product's other app, web and backend
+repositories, read at the sha Phase 1 pinned, through `repo_grep` /
+`repo_read` / `repo_find_keys`. No local checkout is needed and none is read,
+so the comparison is against the latest integration branch rather than
+whatever a sibling directory has checked out. A `stale` entry is still
+compared, and the section header says it is stale. Resources entries are
+compared on axis 4 only.
+
+Without product context, the mirrored-platform resolution below applies.
 Resolution order, first hit wins. `<slug>` is the primary project's prefs key,
 and `MIRROR` is `android` when the run's stack is `ios`, `ios` when it is
 `android` - the check runs in both directions and neither platform is the
@@ -38,7 +49,7 @@ default one.
 |---|---|---|
 | 1 | `--with <path\|owner/repo>` (`/multi-agent:review` only) | An explicit override for a one-off. Remembered like any other resolution. |
 | 2 | `prefs.projects[<slug>].counterpartRoots[]` | What a previous run learned. Verified before use: the path must still exist and its markers must still resolve to `MIRROR`, otherwise the entry is dropped and detection continues at 3. A remembered answer that has gone stale is worse than none. |
-| 3 | Sibling checkouts of the primary repo | List the primary checkout's **parent directory**, depth 1, keep the git repos, resolve each one's stack from its marker files. This matches how the repos are actually laid out - a product's iOS and Android checkouts sit next to each other - and it is one directory listing, not a scan of `$HOME`. |
+| 3 | Sibling checkouts of the primary repo | List the primary checkout's **parent directory**, depth 1, keep the git repos, resolve each one's stack from its marker files, and keep only those whose name core matches the primary's (`product-context.mjs suggest`: platform and version words dropped, so `acme-shop-ios-new` keeps `acme-shop-android` and drops an unrelated repo that merely has Android markers). For a run inside a worktree, the parent is that of the primary repository's main checkout, not of the worktree. One directory listing, not a scan of `$HOME`. |
 | 4 | `state.siblings[]` | Anything the Phase 0 dev-context picker recorded, in case the counterpart is a submodule or a repo the user selected by hand. |
 
 Then:
@@ -64,9 +75,9 @@ The second condition is the diff: it has to touch something with a counterpart
 worth checking - a screen, a service/repository/use-case, a request model, or a
 localization file. Otherwise the step is skipped even when a counterpart exists.
 
-Nothing is ever cloned. A counterpart that is not checked out locally is
-skipped: cloning a repository in order to review a different one is a side
-effect nobody asked for.
+Nothing is cloned into a workspace. Product-context counterparts live in the
+`repo_*` tools' read-only cache, which has no working tree; a fallback
+counterpart that is not checked out locally is skipped.
 
 ## Read-only, without exception
 
@@ -80,8 +91,11 @@ for a human, not a task for the pipeline.
 
 ## Locating the counterpart, deterministically
 
-Do not grep the other repo by hand and do not read it broadly. Use the code
-graph, which is LLM-free and token-budgeted:
+Do not read the other repo broadly. For a product-context counterpart, look the
+diff's identifiers up with one `repo_find_keys` call at the recorded sha (paths,
+endpoint strings, request type names, localization keys), then `repo_read` the
+hit files. For a local fallback counterpart, use the code graph, which is
+LLM-free and token-budgeted:
 
 ```bash
 SIB_STACK=android                      # or ios, mirrored

package/pipeline/multi-agent-refs/setup/token-save-flow.md

@@ -1,5 +1,11 @@
 ## Token Save Flow (reusable)
 
+<!-- toc -->
+- [Token Save Flow (reusable)](#token-save-flow-reusable)
+- [Step 3.5  -  Host Prompt (embedded in Token Save Flow)](#step-35---host-prompt-embedded-in-token-save-flow)
+- [Step 3.7  -  Repository read binding (embedded in Token Save Flow)](#step-37---repository-read-binding-embedded-in-token-save-flow)
+<!-- /toc -->
+
 This flow is used in TWO contexts:
 - **Setup Step 4**  -  for missing tokens during first-time onboarding
 - **Phase 0 token pre-check**  -  when a token is missing or expired (401/403) at runtime
@@ -199,3 +205,21 @@ Test host → `hosts.graylogTest` (`{GRAYLOG_TEST_HOST}`); skipped means product
 **Re-run / update**: `/multi-agent:setup hosts` re-opens the prompt to edit values without touching tokens.
 
 Team-sharing note: Hosts are the only corporate metadata the pipeline needs. Tokens live in macOS Keychain (encrypted, never on disk inside the repo). Preferences file lives in `~/.claude/`  -  fully outside the repo clone. A teammate cloning the repo runs `/multi-agent:setup` once; host + token prompts run naturally together.
+
+## Step 3.7  -  Repository read binding (embedded in Token Save Flow)
+
+Runs inline when the saved token can read git repositories over https (a
+GitHub PAT, a Bitbucket Data Center HTTP access token). The multi-agent-toolkit
+`repo_*` tools send a token only to a host bound to it here, and nothing else
+in the pipeline writes this binding: a product map or a planner's request
+naming a credential never creates one.
+
+```
+Repository hosts this token may be sent to for read-only clone and fetch
+(comma-separated, empty for none). Suggested: {github.com | prefs.global.hosts.bitbucket}
+  ___
+```
+
+Save the answer, lowercased, to `prefs.global.credentialHosts.{logical-key}`
+(an array of hostnames). Empty leaves the key unbound. `/multi-agent:setup hosts`
+re-opens it.

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

@@ -551,6 +551,37 @@
         }
       }
     },
+    "productContext": {
+      "type": "array",
+      "maxItems": 20,
+      "description": "What Phase 1 read from the other repositories of the product (every product repo except the ones this run develops), each at its pinned sha through the toolkit's repo_* tools. Written by scripts/product-context.mjs record; read by Phase 1 planning, Phase 2 dev and Phase 3 platform parity. See multi-agent-refs/features/product-context.md.",
+      "items": {
+        "type": "object",
+        "required": ["remote", "slug"],
+        "properties": {
+          "remote": { "type": "string" },
+          "slug": { "type": "string" },
+          "stack": { "type": "string" },
+          "branch": { "type": "string" },
+          "sha": { "type": "string" },
+          "stale": { "type": "boolean" },
+          "error": { "type": "string" },
+          "keys": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["key", "status"],
+              "properties": {
+                "key": { "type": "string" },
+                "status": { "enum": ["implemented", "not-yet-implemented", "diverges", "error"] },
+                "hits": { "type": "array" },
+                "note": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
     "siblings": {
       "type": "array",
       "maxItems": 10,

package/pipeline/schemas/analysis-spec.schema.json

@@ -610,6 +610,20 @@
             }
           }
         },
+        "repoShas": {
+          "type": "array",
+          "description": "Every repo read through the toolkit's repo_* tools at its latest integration branch, with the sha it was read at. Sorted shas are an evidence_digest input, so a new commit invalidates the cache.",
+          "items": {
+            "type": "object",
+            "required": ["remote", "branch", "sha"],
+            "properties": {
+              "remote": { "type": "string" },
+              "branch": { "type": "string" },
+              "sha": { "type": "string" },
+              "stale": { "type": "boolean" }
+            }
+          }
+        },
         "repoEvidence": {
           "type": "object",
           "description": "Phase 1b deep-scan result keyed by repo name. Each value holds the 13-bucket catalogue.",

package/pipeline/schemas/code-graph.schema.json

@@ -8,7 +8,8 @@
   "additionalProperties": false,
   "properties": {
     "schemaVersion": {
-      "const": "1.0.0"
+      "enum": ["1.0.0", "1.1.0", "1.2.0"],
+      "description": "1.1.0 adds endLine on symbol nodes; 1.2.0 adds inherits edges (subtype to supertype). Older graphs stay readable; diff mapping falls back to file level for a 1.0.0 graph."
     },
     "stack": {
       "type": "string",
@@ -51,6 +52,16 @@
           "name": { "type": "string" },
           "path": { "type": ["string", "null"] },
           "line": { "type": "integer", "minimum": 1 },
+          "startLine": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "First line of the declaration when attribute or decorator lines sit directly above it; absent when it equals line."
+          },
+          "endLine": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Last line indented deeper than the declaration, plus a closing bracket at its own indentation when one follows. Absent in graphs built before schema 1.1.0."
+          },
           "symbolKind": { "type": "string" },
           "nested": {
             "type": "boolean",
@@ -70,7 +81,7 @@
         "properties": {
           "from": { "type": "string" },
           "to": { "type": "string" },
-          "kind": { "type": "string", "enum": ["defines", "imports", "references"] }
+          "kind": { "type": "string", "enum": ["defines", "imports", "references", "inherits"] }
         }
       }
     },

package/pipeline/schemas/diff-risk.schema.json

@@ -64,7 +64,8 @@
                     "complexity_delta",
                     "ui_critical",
                     "migration",
-                    "test_lines_removed"
+                    "test_lines_removed",
+                    "dependents_reached"
                   ]
                 },
                 "weight": { "type": "number" },

package/pipeline/schemas/prefs.schema.json

@@ -1273,9 +1273,14 @@
               "type": "string",
               "description": "Shared ingest token the receiving endpoint validates. May be left empty here and supplied via env MULTI_AGENT_USAGE_TOKEN instead. Local prefs only, never synced."
             },
+            "declaredLogin": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,38}$",
+              "description": "The GitHub username the person typed at setup or update (usage-register.mjs --login). Registered as declared when this machine cannot prove that account; the server issues a token only when it is a collaborator (the repository owner registers with a proof). Forgotten when the server refuses it. Local prefs only, never synced."
+            },
             "reportAs": {
               "type": "string",
-              "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."
+              "description": "Preferred GitHub login when more than one account is logged in to gh. usage-register.mjs --login sets it to the declared name, and removes it with that name when the server refuses the name. 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",
@@ -1320,6 +1325,23 @@
               "type": "string",
               "description": "ISO time of the registration that issued the stored token."
             },
+            "claimNonce": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{8,32}$",
+              "description": "Random suffix of the machine label a declared registration is sent with, so nobody else can name the label and replace this machine's token. Written once by usage-register.mjs."
+            },
+            "claimFailedAt": {
+              "type": "string",
+              "description": "ISO time a declared registration last failed for a reason other than a refusal of the name (rate limit, cap, endpoint down). The claim is not sent again for a day unless the name is typed again."
+            },
+            "reportAsBefore": {
+              "type": "string",
+              "description": "The reportAs a declared name replaced, put back when that name is refused."
+            },
+            "registeredClaim": {
+              "type": "boolean",
+              "description": "true when the stored token was issued for a declared login rather than a proven one. A proof found later, for any login with access, replaces it; a declared name never replaces a proven registration."
+            },
             "registeredFallback": {
               "type": "boolean",
               "description": "Deprecated (20.17.0). true marked a registration made with an account that cannot read accessRepo; it is not treated as pinned and is replaced once an account with access is found."
@@ -1463,15 +1485,69 @@
             }
           }
         },
+        "credentialHosts": {
+          "type": "object",
+          "description": "Hosts each credential-store key may be sent to by the multi-agent-toolkit repo_* tools for read-only clone and fetch over https. Written by /multi-agent:setup (Token Save Flow Step 3.7) with the person present; product-context.mjs learn refuses a repository credential whose host is not listed here, and the toolkit refuses to send a token anywhere else.",
+          "additionalProperties": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^[a-z0-9.-]+$" },
+            "maxItems": 20
+          }
+        },
+        "products": {
+          "type": "object",
+          "description": "Products and the repositories each is made of, for the planning step that reads every repository of the product except the ones a run develops (scripts/product-context.mjs, toolkit repo_* tools). Keyed by product name; a project joins one through projects[<key>].product, or implicitly when one of its developed remotes is listed here. Written by product-context.mjs learn after the user confirms; read-only to everything else.",
+          "propertyNames": { "pattern": "^[A-Za-z0-9._-]{1,64}$" },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["repos"],
+            "properties": {
+              "repos": {
+                "type": "array",
+                "minItems": 1,
+                "maxItems": 20,
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["stack", "remote"],
+                  "properties": {
+                    "stack": { "enum": ["ios", "android", "web", "backend", "resources"] },
+                    "remote": {
+                      "type": "string",
+                      "description": "https://, ssh:// or user@host:path remote, without credentials."
+                    },
+                    "branch": {
+                      "type": "string",
+                      "description": "Override for the branch rule (develop when the remote has it, else its default branch)."
+                    },
+                    "credential": {
+                      "type": "string",
+                      "description": "Logical credential-store key of a read token for this host, accepted only when global.credentialHosts already binds the key to this https host. Omit to use git's own credential helper or SSH agent."
+                    },
+                    "authScheme": {
+                      "enum": ["basic", "bearer"],
+                      "description": "basic for GitHub, bearer for Bitbucket Data Center HTTP access tokens."
+                    },
+                    "username": {
+                      "type": "string",
+                      "description": "Username for basic auth. Default x-access-token."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
         "codeGraph": {
           "type": "object",
           "additionalProperties": false,
-          "description": "v16.1+  -  deterministic, LLM-free code graph (symbols, imports, references) built by pipeline/scripts/graph-build.mjs into ~/.claude/knowledge/<project>/code-graph.json. Phase 1 Step 2.6 queries it to narrow the Explore starting set; Phase 5 Step 3 refreshes it after the branch changed code. Zero API cost, zero runtime dependencies (ADR-0004), read-only on the repo. Off by default: with it off the pipeline behaves exactly as it did before. Measured on a 4,300-file Swift app at a fixed 30k retrieval budget, it roughly doubled coverage at under half the token cost on domain-word searches, and was marginally worse than plain grep when the task already names an exact symbol.",
+          "description": "v16.1+  -  deterministic, LLM-free code graph (symbols, imports, references) built by pipeline/scripts/graph-build.mjs into ~/.claude/knowledge/<project>/code-graph.json. Phase 1 Step 2.6 queries it to narrow the Explore starting set; Phase 5 Step 3 refreshes it after the branch changed code. Zero API cost, zero runtime dependencies (ADR-0004), read-only on the repo. On by default; with it off no graph is built or refreshed. Measured on a 4,300-file Swift app at a fixed 30k retrieval budget, it roughly doubled coverage at under half the token cost on domain-word searches, and was marginally worse than plain grep when the task already names an exact symbol.",
           "properties": {
             "enabled": {
               "type": "boolean",
-              "default": false,
-              "description": "Master switch. When false, Phase 1 Step 2.6 and the Phase 5 refresh are skipped entirely and no graph file is written."
+              "default": true,
+              "description": "Master switch, on by default. When false, Phase 1 Step 2.6 and the Phase 5 refresh are skipped and no graph is built or refreshed; a graph file already on disk is still read by Phase 3 and the analysis ranking."
             },
             "autoRefresh": {
               "type": "boolean",
@@ -2338,6 +2414,10 @@
                 }
               }
             },
+            "product": {
+              "type": "string",
+              "description": "Name of the global.products entry this project belongs to. Planning reads every repository of that product except the ones the run develops. Written by product-context.mjs learn."
+            },
             "counterpartRoots": {
               "type": "array",
               "items": {