@mmerterden/multi-agent-pipeline 20.21.0 → 20.23.0

package/CHANGELOG.md

@@ -16,6 +16,68 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [20.23.0] - 2026-10-13
+
+### Added
+
+- **Operational reporting reaches teammates on work machines.** When no GitHub account on the machine can prove access, setup and update ask once for the person's GitHub username and `usage-register.mjs --login <name>` registers it as declared; the server issues the token only to a collaborator (the repository owner registers with a proof), under a machine label with a random suffix, and marks its records `claimed`. Later runs re-register a declared name without asking. A declared name is used only when the machine proves no account: it never replaces a proven registration, a later proof replaces it, it is compared case-insensitively, it is never used for `/multi-agent:feedback`, it is not written on a dry run or (outside feedback) an opted-out machine, a refused name is forgotten so setup asks again, and a claim that failed otherwise is not resent for a day.
+- The installer starts `usage-report.mjs --lifecycle` right after writing the version stamps, so every install and update reaches the panel when it happens (`MULTI_AGENT_SKIP_USAGE_REPORT=1` turns it off).
+- `graph-confirm.mjs` merges a `graph-affected` answer with `code_references` results: each direct dependent is `confirmed`, `name-only` or `unchecked`, and `lspOnly` names files the server found that the graph missed. Only a ready semantic index confirms or demotes.
+- **`inherits` edges in the code graph** (schema 1.2.0): subtype to superclass, protocol or interface, read from Swift and Kotlin `:` lists, Swift extensions, Python bases and TypeScript `extends` / `implements`. `graph-affected "<Protocol>" --kind inherits --depth 1` lists its conformers.
+
+### Changed
+
+- A Story's description puts each section in a coloured wiki panel, its heading first: the user story `#d4d39e`, the acceptance criteria `#d4a19e`, every other section `#9eb6d4`. `/multi-agent:create-jira` and the stories `/multi-agent:analysis-jira` plans both write it; Task and Bug keep plain sections.
+- The code graph is on by default (`prefs.global.codeGraph.enabled: true`): it costs seconds and no API calls, never fails a run, and without it the diff mapping, `dependents_reached` and `inherits` answers never run. Set it to `false` and no graph is built or refreshed.
+- `knowledge.md` lists the stores a run fills without a model, how each reaches Phase 1, and why the prose files carry no generated copy of them.
+
+### Fixed
+
+- The code graph never points production code at a type a test file declares; a test fake named after a framework type (`protocol View`) made every view in an app depend on it.
+- A root-level `Tests/` directory (the SwiftPM layout) counts as test code in the code graph and in `test-gap-scan`.
+- An attribute whose arguments run over several lines (`@available(iOS 16,` / `macOS 13, *)`, `@Test(arguments: [Item.init(a: 1),`) belongs to the declaration below it.
+- `symbol-existence-gate`, `test-strength`, `valven-port` and `valven-split` read git path lists NUL-separated, so files with non-ASCII names are checked under their real paths; valven pathspecs are literal.
+- `learnings-ledger from-triage` exits 2 when it distills nothing, so a repeat `capture-flush` reports `ok-nothing-new` for the ledger.
+- `product-context.mjs learn` and `decline` write the preferences file under the shared file lock, leave a file that does not parse untouched, and write through a symlink.
+- A diff header whose quoted path is followed by a tab maps to the right file in `graph-affected --diff` and in `symbol-existence-gate`.
+- `graph-affected --diff <base>..<head>` reads the diff on the side the graph was built at (its head or its base) whatever the working tree holds.
+- `graph-build` keeps git's stderr off the terminal.
+- `capture-flush.sh --json` keeps stdout to the JSON answer; its progress lines go to stderr.
+- A preferences file that is a dangling symlink, or a chain of them, is written through to its target instead of replacing the link.
+
+## [20.22.0] - 2026-10-13
+
+### Added
+
+- **Product context: planning reads the product's other repositories at their latest branch.** A run develops in its active stack's repositories; Phase 1 Step 1.6 now also reads every other repository of the product (the other platform's app, web, backend services, the shared resources repo), read-only, at `develop` or else the remote's default branch, pinned to a sha, through the multi-agent-toolkit's `repo_*` tools (≥ v3.22.1). It is symmetric: whichever stack is primary, the rest are references. Each join key (Figma node id, localization key, endpoint path, analytics event) lands as `implemented`, `not-yet-implemented` (this run is first; nothing is ported) or `diverges`, in `state.productContext` and in the plan. Never blocking. Contract: `multi-agent-refs/features/product-context.md`.
+- `prefs.global.products` and `prefs.projects[<key>].product`, the product map. GitHub and Bitbucket repositories mix in one product; a repository may name a read-token credential key and `basic` or `bearer` auth. The dev-context step offers to map an unmapped project once (attended only), suggesting repositories whose name core matches; declining is remembered.
+- `scripts/product-context.mjs` (`refs`, `suggest`, `needs-mapping`, `learn`, `decline`, `record`, `recall`). Each reference carries a tool-ready `spec`. Findings are appended to the related repository's own `knowledge/<repo>/product-context.jsonl`, keyed by the sha they were read at, so what an iOS run learns about Android serves the next Android run while that sha is current; the knowledge row keeps the tool's status and the planner's note, while a `diverges` verdict stays in the run's state. `learn` merges by remote, re-checks every credential the merge keeps, caps a product at 20 repositories (one `repo_find_keys` call), accepts `file://` only with the toolkit's file switch, and keeps the preferences file's mode.
+- **Change impact from the code graph.** `graph-affected --diff <base>` (also `<base>..<head>` and `--diff-file`) seeds the reverse walk from a diff: each hunk maps onto the innermost declaration it touches through indentation-derived spans (`endLine`, code-graph schema 1.1.0, attribute lines and multi-line headers included, `#if` lines skipped), read on the side of the diff the graph was built from (`side`), so a graph built on the base checkout maps a branch's diff correctly and a deleted file reaches its dependents; enclosing declarations are seeded too, and the JSON names `changedSymbols`, `notIndexed` and `fileLevel`. Contract: `multi-agent-refs/features/code-graph.md`; decision: `docs/adr/0017-change-impact-from-the-graph.md`.
+- **Graph freshness on every answer.** `graph-affected` reports `freshness`: files edited since the build (uncommitted work included), files removed, and whether HEAD moved. A stale answer says it is stale.
+- **`dependents_reached` risk signal.** `diff-risk-score --graph` adds the number of distinct non-test files that depend on the changed declarations, two rings out, capped at 20 so it never outweighs a security path. Phase 3 Step 1.75 passes the project's graph; without one, nothing changes.
+
+### Changed
+
+- Phase 3 platform parity and `/multi-agent:review` take their counterparts from the product first and compare at the pinned sha, without a local checkout; the mirrored ios ↔ android resolution remains the fallback. The sibling-directory source keeps only repositories whose name core matches the primary's, and lists the main checkout's parent, not a worktree's.
+- `/multi-agent:analysis` reads every repository other than the one it runs from at its latest integration branch through `repo_*`, records `evidence.repoShas[]`, and includes those shas in `evidence_digest`.
+- `/multi-agent:setup hosts` re-opens the host prompts and the repository read binding (Token Save Flow Step 3.7) for tokens already saved; a GitHub or Bitbucket token pass asks for the binding after its host.
+- `smoke-cross-cli-behavior.sh` installs Codex as well and checks that product context reaches Claude Code, Copilot CLI and Codex CLI.
+
+### Fixed
+
+- `graph-affected` reaches transitive dependents: the walk continues through what each dependent file declares, instead of stopping after one ring, and no longer lists the defining file as a dependent.
+- `graph-query` charges its token budget for the line it prints, so the reported count matches the output.
+- `capture-flush.sh` finds a run's triage when only Phase 3's own round files exist: after the salvaged and worktree copies it reads each worktree's newest `.pipeline/triage-round-<N>.json`, including worktrees a multi-repo run lists under `projects[]`, then the state directory. A run that died before its `triage-output.json` copy no longer leaves the triage corpus and learnings ledger empty.
+- `capture-flush.sh` files triage-corpus and ledger entries under the run's own repository (its worktree's main checkout, else the project in the state), not under the directory the hook fired in.
+- `capture-flush.sh` prefers the newer of a worktree's `triage-output.json` and its newest round, names a submodule's store after the submodule, and ignores a project name that is not a plain name.
+- Copilot's instructions map `$HOME/.claude/scripts/` and `lib/` in refs read from `~/.claude` or GitHub to the Copilot copies.
+- `diff-risk-score` reads `--numstat -z`, so renamed, braced and non-ASCII paths are the new path exactly.
+- `graph-build` lists files with `ls-files -z`, so files with non-ASCII names (`Ödeme Özeti.swift`) are indexed.
+
+### Security
+
+- A repository credential is accepted by `learn` only when `prefs.global.credentialHosts` already binds the key to that https host. The binding is written by `/multi-agent:setup` (Token Save Flow Step 3.7) with the person present; the product map never creates one. Requires multi-agent-toolkit ≥ v3.22.1, which reads bindings from the same place.
+
 ## [20.21.0] - 2026-10-12
 
 ### Added

package/docs/adr/0010-own-code-graph.md

@@ -51,8 +51,9 @@ The engine is `pipeline/scripts/_code-graph.mjs`, with per-stack rules in
 `pipeline/scripts/code-graph-rules/<stack>.json`, five entry points
 (`graph-build`, `graph-query`, `graph-affected`, `graph-report`,
 `validate-code-graph`), a schema at `pipeline/schemas/code-graph.schema.json`,
-and the `/multi-agent:graph` command. It is off by default behind
-`prefs.global.codeGraph.enabled`.
+and the `/multi-agent:graph` command. It sits behind
+`prefs.global.codeGraph.enabled`, off when this was decided and on by default
+since ADR 0017's change-impact work made Phase 3 depend on it.
 
 ## What we deliberately gave up
 

package/docs/adr/0017-change-impact-from-the-graph.md

@@ -0,0 +1,69 @@
+# 17. Change impact from the graph: spans, a transitive walk, and freshness
+
+**Status:** Accepted · 2026-10-12 · extends [ADR-0010](./0010-own-code-graph.md)
+
+## Context
+
+ADR-0010 built the code graph to answer "where does this live" and "what
+depends on this". Four properties of the graph shape the second answer:
+
+- References point from files to symbols, and a file's only incoming edges are
+  imports. A reverse walk therefore needs a hop from each dependent file to the
+  declarations it makes before it can reach the next ring, and the file that
+  defines a seed is not one of its dependents.
+- A reviewer starts from a diff, not from a symbol name, so the walk needs a
+  way to turn changed lines into declarations.
+- The manifest written at build time records each file's size and mtime, which
+  is enough to tell whether an answer describes the current tree.
+- A query budget is only honest when it is charged for the text the caller
+  receives.
+
+Two public references solved parts of this. `DeusData/codebase-memory-mcp`
+(MIT) maps a diff onto the symbols that contain the changed lines and walks
+outward for blast radius, and reports whether the paths asked about are indexed
+and fresh. `Graphify-Labs/graphify` (Apache-2.0) seeds its affected walk from a
+declaration's members and counts the tokens of the answer it actually returns.
+Both are design references only: the first is a C daemon with tree-sitter
+grammars, a file watcher and a browser UI, the second a Python service with
+incremental reconciliation, and ADR-0004 forbids a native runtime dependency.
+
+## Decision
+
+Extend the graph in place:
+
+- **Spans.** Every definition gets an `endLine`: the line before the next
+  definition at the same or a lower indentation, or the end of the file. It is
+  derived from the indentation signal the engine already uses for nesting, so
+  it needs no parser and holds across the brace languages and Python. Schema
+  1.1.0; a 1.0.0 graph stays readable.
+- **Diff seeding.** `graph-affected --diff` maps each hunk onto the innermost
+  declaration it touches and seeds the walk with it and its enclosing
+  declarations. A file from a pre-1.1.0 graph is seeded whole and listed as
+  such; a changed file the graph does not contain is listed as not indexed.
+  The diff is read on the side the graph describes: the new side when the
+  graph matches the tree, otherwise the old side, where its spans hold.
+- **A transitive walk.** Dependents are files; the walk continues through what
+  each dependent file declares, never follows `defines`, and never reports a
+  seed's defining file.
+- **Freshness on every answer.** Size and mtime against the manifest, plus the
+  build commit against HEAD. A stale answer says it is stale.
+- **Risk.** `diff-risk-score --graph` adds `dependents_reached`, combined with
+  the existing security, public-API and missing-test signals and capped, so a
+  change is not ranked by graph distance alone.
+- **Honest budgets.** `graph-query` charges for the printed line.
+
+## Not adopted
+
+A daemon or watcher, incremental reconciliation (a full build takes seconds;
+graphify's history shows how many defects incremental state produces), Cypher,
+a UI, LLM-labelled edges and confidence scores. The single-candidate rule from
+ADR-0010 stays: an ambiguous reference gets no edge rather than a guessed one.
+
+## Consequences
+
+A reviewer and Phase 3 get the blast radius of the actual diff. A span is an
+upper bound, so a hunk in trailing blank lines or a closing brace counts toward
+the declaration above it; that errs toward more dependents, not fewer. Method
+level precision is still bounded by regex extraction; confirming candidates
+through the language server (`code_references`) is the next step and is not
+part of this decision.

package/docs/adr/README.md

@@ -26,6 +26,7 @@ Format: lightly adapted from [Michael Nygard's ADR template](https://cognitect.c
 | [0014](./0014-six-phase-consolidation.md)                          | Six phases, because two of the eight were doing the same work twice | Accepted (amended by 0015: the depth answer is removed)                  |
 | [0015](./0015-one-pipeline-no-depth-answer.md)                     | One pipeline: the depth question is removed                         | Accepted (extended by 0016: the workspace and resume names go too)       |
 | [0016](./0016-the-run-shape-is-asked-not-typed.md)                  | The shape of a run is asked, not typed into its name                | Accepted                                                                 |
+| [0017](./0017-change-impact-from-the-graph.md)                     | Change impact from the graph: spans, a transitive walk, freshness   | Accepted                                                                 |
 
 ## Writing a New ADR
 

package/docs/ecosystem.md

@@ -7,7 +7,7 @@ separately, wired together at install time and at run time:
 |---|---|---|
 | **`multi-agent-pipeline`** (this repo) | Orchestration: the 6-phase flow, the 64 slash commands, quality gates, review/triage, cross-CLI parity | npm package (`@mmerterden/multi-agent-pipeline`), installs itself onto Claude Code / Copilot CLI / Codex CLI |
 | **`multi-agent-plugins`** | Stack knowledge: per-platform component/lifecycle skills (iOS, Android, Frontend, Backend) + shared knowledge | Claude Code marketplace, 6 independently-versioned plugins |
-| **`multi-agent-toolkit-mcp`** | The pipeline's hands on devices and browsers: 191 MCP tools across 20 categories (simulator/emulator control, end-to-end locators and assertions, memory, crash diagnostics, accessibility audit, store compliance, web automation and scraping, Figma-vs-mock design audit, code intelligence, wallet passes, an agent-DSL batch runner, a full-text context index with text-to-image rendering, provider-backed research, verified hand-off of simple text tasks to free models, video key frames, offline security scoring, travel document fixtures, a voice channel, App Store Connect and Play Console APIs, virtual iPhones) | npm package, registered as a standard stdio MCP server on every host |
+| **`multi-agent-toolkit-mcp`** | The pipeline's hands on devices and browsers: 197 MCP tools across 21 categories (simulator/emulator control, end-to-end locators and assertions, memory, crash diagnostics, accessibility audit, store compliance, web automation and scraping, Figma-vs-mock design audit, code intelligence, wallet passes, an agent-DSL batch runner, a full-text context index with text-to-image rendering, provider-backed research, verified hand-off of simple text tasks to free models, video key frames, offline security scoring, read-only access to related repositories at their latest branch, travel document fixtures, a voice channel, App Store Connect and Play Console APIs, virtual iPhones) | npm package, registered as a standard stdio MCP server on every host |
 
 None of the three depends on the others at the code level. They compose through two
 narrow contracts: the **Skill tool** (pipeline → plugin, at Phase 2) and the **MCP
@@ -234,14 +234,14 @@ Detail: [`unattended-security.md`](../pipeline/multi-agent-refs/features/unatten
 
 ### multi-agent-toolkit-mcp's tools, by category
 
-191 tools in 20 categories, counted from the server's own `tools/list` response
-at toolkit 3.21.0 rather than from a README. Three families are defined in
+197 tools in 21 categories, counted from the server's own `tools/list` response
+at toolkit 3.22.1 rather than from a README. Three families are defined in
 modules the main file only spreads in, so a count taken from the source reads
 low; the response is the only place the whole surface appears at once.
 
 The families can be narrowed per host: `MCP_TOOLKIT_CAPS` serves only the named
-ones, and unset serves all 191. A frontend repo that sets `web,code,context`
-sees 47 tools instead of 191, which matters because every registered server's
+ones, and unset serves all 197. A frontend repo that sets `web,code,context`
+sees 47 tools instead of 197, which matters because every registered server's
 tool list is charged against the context window on every turn.
 
 | Category | Tools | Primary pipeline consumers |
@@ -262,6 +262,7 @@ tool list is charged against the context window on every turn.
 | Free Models | 2 (`llm_delegate`, `llm_providers`) | `route-on --free`: `bulk-read.sh` through the `multi-agent-toolkit-llm` CLI, the `delegate` call site in skills and analysis evidence gathering ([`free-models.md`](../pipeline/multi-agent-refs/features/free-models.md)). Allowed in unattended runs only while the free chain is on |
 | Media | 1 (`media_frames`) | Phase 2 visual evidence: turns a screen recording into frames a reviewer and a model can both look at |
 | Security | 2 (`security_cvss_score`, `security_dep_inventory`) | the Phase 3 Step 2.7 security audit (`security-auditor`) and `/multi-agent:security-review`; offline, no egress |
+| Related Repositories | 6 (`repo_resolve`, `repo_grep`, `repo_read`, `repo_ls`, `repo_log`, `repo_find_keys`) | Phase 1 Step 1.6 product context, Phase 3 platform parity, `/multi-agent:review`, `/multi-agent:analysis`; read-only, pinned to a sha |
 | Travel Document Fixtures | 2 (`document_mrz_build`, `document_generate`) | the `e2e-testing` skill's MRZ and document-scan recipes |
 | Voice | 6 | none in the pipeline; a local voice host outside it |
 | Store APIs | 30 | `/multi-agent:store-ready`, `/multi-agent:setup` credential onboarding |

package/docs/facts.json

@@ -1,7 +1,7 @@
 {
   "$comment": "Generated by pipeline/scripts/gen-facts.mjs. Do not hand-edit: the site reads this, and a number edited here instead of at its source is the drift this file removes.",
-  "generatedAt": "2026-10-12",
-  "version": "20.21.0",
+  "generatedAt": "2026-10-13",
+  "version": "20.23.0",
   "phaseSchema": 2,
   "phases": [
     {
@@ -40,7 +40,7 @@
   "skillCountAll": 228,
   "agentCount": 10,
   "hosts": ["Claude Code", "Codex CLI", "Copilot CLI"],
-  "toolCount": 191,
+  "toolCount": 197,
   "toolCategories": {
     "ios": 42,
     "web": 35,
@@ -49,6 +49,7 @@
     "vphone": 10,
     "code": 8,
     "design": 7,
+    "repo": 6,
     "voice": 6,
     "context": 4,
     "pass": 4,
@@ -61,5 +62,5 @@
     "ui": 1
   },
   "pluginSkillCount": 252,
-  "toolkitVersion": "3.21.1"
+  "toolkitVersion": "3.22.2"
 }

package/docs/features.md

@@ -58,11 +58,11 @@ The install is not only useful while `/multi-agent` is running. `rules/outside-t
 
 Uninstall preserves the whole layer - tokens, the reader that opens them, the mapping that names them, the MCP registration. It is 1.5 kB of always-loaded text; the detail lives in a ref that loads on demand, and a gate keeps both under a ceiling because every byte there is paid by every session.
 
-### Code Graph (`/multi-agent:graph`, opt-in)
+### Code Graph (`/multi-agent:graph`)
 
 A deterministic, LLM-free map of what a repo declares and what refers to what, extracted by regex over comment-stripped source into `~/.claude/knowledge/<project>/code-graph.json`. Four stacks build today (Swift, Kotlin/Java, TypeScript/JavaScript, Python); each is one rules file, and the engine is the same for all of them. Zero runtime dependencies, zero API cost, read-only on the repo.
 
-Phase 1 queries it to hand Explore a ranked starting file set instead of a full scan, and Phase 5 rebuilds it after the branch changed code - a rebuild is seconds, so staleness is a `baseCommit` comparison rather than a date heuristic. Off by default behind `prefs.global.codeGraph.enabled`; with it off the pipeline behaves exactly as before.
+Phase 1 queries it to hand Explore a ranked starting file set instead of a full scan, and Phase 5 rebuilds it after the branch changed code - a rebuild is seconds, so staleness is a `baseCommit` comparison rather than a date heuristic. On by default behind `prefs.global.codeGraph.enabled`; with it off no graph is built or refreshed.
 
 `GRAPH_REPORT.md` also ends with **Symbols nothing else references**: symbols no other file in the repo names, split from the ones referenced only by their own tests. Candidates, never verdicts - the extractor is regex, not a parser, so the four classes that could not carry a reference edge either way (a kind outside the stack's `referenceKinds`, a name declared twice, a nested declaration, a test file) are counted and excluded rather than listed, and nothing gates on the result.
 

package/install/_usage-lifecycle.mjs

@@ -0,0 +1,44 @@
+/**
+ * Report the version just installed, without waiting for it.
+ *
+ * `usage-report.mjs --lifecycle` compares the version stamps the installer just
+ * wrote with `usageLog.reportedVersion` and sends one install or update record
+ * when they differ. It does nothing unless operational reporting is on and a
+ * token resolves, and it never fails. Starting it from the installer puts an
+ * install or update on the panel when it happens, including a version that is
+ * replaced before the machine's next pipeline run.
+ *
+ * `MULTI_AGENT_SKIP_USAGE_REPORT=1` starts nothing.
+ *
+ * @module install/_usage-lifecycle
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const HOSTS = [".claude", ".copilot", ".codex"];
+
+/**
+ * @param {{home: string, packageRoot?: string, env?: NodeJS.ProcessEnv, spawnImpl?: typeof spawn}} opts
+ * @returns {string|null} the script started, or null
+ */
+export function startLifecycleReport({ home, packageRoot, env = process.env, spawnImpl = spawn }) {
+  if (env.MULTI_AGENT_SKIP_USAGE_REPORT === "1") return null;
+  const candidates = [
+    ...HOSTS.map((h) => join(home, h, "scripts", "usage-report.mjs")),
+    ...(packageRoot ? [join(packageRoot, "pipeline", "scripts", "usage-report.mjs")] : []),
+  ];
+  const script = candidates.find((p) => existsSync(p));
+  if (!script) return null;
+  try {
+    spawnImpl(process.execPath, [script, "--lifecycle"], {
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env, ...env, HOME: home },
+    }).unref();
+    return script;
+  } catch {
+    return null;
+  }
+}