@mmerterden/multi-agent-pipeline 16.12.0 → 16.14.0

package/CHANGELOG.md

@@ -16,6 +16,37 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [16.14.0] - 2026-08-28
+
+### Added
+
+- **Go joins the code graph, and `web` / `frontend` resolve to the node rules.** Phase 1 has detected Go since the stack table existed, while both rule layers rejected it: there was no `test-gap-rules/go.json` either, so `/multi-agent:test "test-gap"` was equally blind to a Go repo. Both files now exist. The alias is the other half of the same gap: the rule files are named after the toolchain (`node`) and the rest of the pipeline names the product surface (`web`), so a caller typing the word they were last shown got "unsupported". `backend` is deliberately NOT an alias - it could be node, python or go, and the error names all three rather than guessing one.
+- **Analysis ranks its repo-evidence candidates with the graph (opt-in).** The reuse-first scan (Locked 11) caps its candidate set at 200 files and warns when a generic feature name blows past it. `head -200` truncates in grep's walk order, so the cap was dropping an arbitrary file, not the least relevant one. With `prefs.global.codeGraph.enabled`, a graph query over the feature name sorts the set first. It is a sort key, never a filter: a file grep found and the graph did not rank is still scanned, because a regex extractor's silence is not evidence of absence. The 13 buckets, the cap and the no-graph behaviour are unchanged.
+
+### Fixed
+
+- **The code-graph ref did not say to build when no graph exists.** It said "build only when `baseCommit` no longer matches HEAD", which has no answer when there is nothing to compare. That is the case that matters: the knowledge base's prose files are written in Phase 7, the phase a run is least likely to reach, so a repo can carry a long task history and an empty knowledge directory. The graph must not inherit that dependency, and `--status` exiting 1 on a missing file now explicitly means build.
+
+## [16.13.0] - 2026-08-28
+
+### Added
+
+- **`/multi-agent:graph`  -  a deterministic code graph, built without an LLM.** Phase 1 re-scanned the repo with grep and read on every task and defaulted to the "very thorough" tier on feature work; Phase 7 wrote `architecture.md` from one task's window and let it age for 90 days. Both wanted the same answer: where does this live, and what depends on it. `graph-build.mjs` extracts symbols, imports and references by regex over comment-stripped source into `~/.claude/knowledge/<project>/code-graph.json`; `graph-query.mjs` runs a token-budgeted traversal, `graph-affected.mjs` walks it backwards for impact, `graph-report.mjs` renders `GRAPH_REPORT.md`, and `validate-code-graph.mjs` fails a build whose edges point at missing nodes. Zero runtime dependencies, zero API cost, read-only on the repo. Design reference: `Graphify-Labs/graphify`; the reasoning, the trade and the numbers are in `docs/adr/0010-own-code-graph.md`.
+- **Phase 1 Step 2.6 and Phase 7 graph refresh, behind `prefs.global.codeGraph.enabled` (default `false`).** When on, Phase 1 queries the graph and hands Explore a ranked starting set instead of a full scan, and Phase 7 rebuilds the graph after the branch changed code. Off, the pipeline behaves exactly as before. Measured on a 4,300-file Swift app at a fixed 30k retrieval budget: 80.4% coverage at 18,465 tokens against 66.0% at 24,555 for grep-and-read. The win is entirely in domain-word searches (63.3% vs 32.0% at under half the cost); when the task already names an exact type, `grep -lw` is still slightly better and slightly cheaper, and the command says so.
+- **`_path-match.mjs`.** The glob matcher `test-gap-scan.mjs` carried inline is now shared with the graph engine, so the two cannot drift apart on what a repo excludes.
+- **Code-graph rules for Android, Node and Python.** Four stacks now build: measured on a 4,229-file Kotlin app (25,234 nodes, 70,897 edges), this repo (126 sources) and a 43-file Python service, each validated and each hub list checked by hand rather than assumed correct. Two engine defects surfaced doing it, both of which iOS had been getting away with. Nesting was read from the pattern's match column, so `public final class Foo` counted as nested because the match starts at `class` seven columns in; it now reads the line's indentation. And the import pass read a fully stripped body, which blanks a JavaScript module specifier because the specifier IS a string literal - every import edge in that stack would have vanished with nothing to notice it. iOS was re-gated after both and scored identically (80.4% at 18,467 tokens).
+- **A nested declaration is a node but never a reference target.** Kotlin sealed cases and Python inner classes are named after the concept they model - `Icon`, `Color`, `Success`, `Disabled` - and each is declared exactly once, so the ambiguity rule never caught them. Every Kotlin file that merely mentioned Compose's `Color` gained an edge to one app's nested case: 4,072 false edges out of 74,969, and four of the top eight architectural hubs were wrong. They stay findable by name through their `defines` edge.
+- **`prefs.global.modelFallback.fableEnabled` (default `true`)  -  the fable rung as a switch, not only as a fallback.** Every other trigger in the fallback contract reacts to something going wrong; this one asserts up front that a rung is not in play, so there is no dispatch attempt and no error to recover from. `false` starts `ios/android/backend-architect`, `code-reviewer` and triage on `opus`. Claude Code only: Copilot CLI does not offer Fable 5, and on Codex CLI the `fable` rung means `gpt-5.6 @ xhigh`, a different vendor's model on a different account, which the switch deliberately leaves alone. Turning it off also collapses the Phase 4 Claude Code panel to two reviewers, because Reviewer 1 lands on the `opus` Reviewer 2 already holds and one model dispatched twice is not cross-model review; `consensus.reviewerCount` records `2`. Set `costBudget.priceAt` to `opus` alongside it, or the estimate keeps pricing at a rung nothing runs on and trips the ceiling early.
+
+### Fixed
+
+- **`derivedSkillSources` could not say which repo held the derived copies.** `localPath` reads as relative to the current repo, so both entries pointed at the UPSTREAM tree and stayed wrong through a plugin rename: the drift check was comparing a path that did not exist. Added `localRepo`, corrected both entries, and re-derived their skill lists from the tree instead of from memory.
+- **Two `excludePathGlobs` shapes were silently inert.** A pattern with a wildcard and no `**` fell through to a literal `endsWith` / `includes` test against the pattern text, which can never be true: nothing ends with the characters `*.d.ts`. So `*.d.ts` in the node rules and `*.egg-info/` in the python rules excluded nothing, and generated typings and build residue reached every consumer of those rules, `test-gap-scan.mjs` included. Both shapes now translate to an anchored regex, and eight glob cases are pinned by the smoke.
+- **`--all-data` left the knowledge base behind.** Full uninstall removed the log root and the per-repo memory root but never `~/.claude/knowledge/`, which holds `architecture.md`, `patterns.md`, `gotchas.md`, `decisions.md` and now `code-graph.json`. That is prose about a private codebase plus every symbol name in it, and it is the data a user most likely means by "remove everything". A default uninstall still keeps all of it, and memory written inside a repo (`$PROJECT_ROOT/.multi-agent/memory/`) is still never touched by either mode: it lives in the user's working tree and may be committed.
+- **`modelFallback.floorModel` could not be set.** The fallback contract has documented it since the two-step ladder landed, but it was absent from `prefs.schema.json`, whose `modelFallback` object forbids extra keys  -  so a prefs file that followed the documented example failed validation. Declared, defaulted to `haiku`, and added to the template.
+- **The consensus rule still claimed two reviewers on Claude Code.** v16.12.0 added the third reviewer and updated the matrix but not the `reviewerCount` line 300 lines below it. `smoke-cross-cli-behavior.sh` reads the matrix, so it never noticed. The line now says what it should have said all along: the count is the reviewers that actually dispatched, not the configured maximum.
+
+
 ## [16.12.0] - 2026-08-27
 
 ### Added

package/README.md

@@ -89,7 +89,7 @@ Depth, autopilot and `--local` are the only knobs on the run itself; everything
 
 ## Commands
 
-`/multi-agent` plus 53 sub-commands. `/multi-agent:help` renders the same catalog in your terminal, in your `outputLanguage`.
+`/multi-agent` plus 54 sub-commands. `/multi-agent:help` renders the same catalog in your terminal, in your `outputLanguage`.
 
 ### Pipeline entries
 
@@ -208,13 +208,13 @@ This enables the matching plugin (+ the shared `ai-common` plugin) in the repo's
 
 ## Tool support
 
-The pipeline runs natively on **Claude Code**, **Copilot CLI** and **Codex CLI** - all three install from the same `pipeline/` source and get the same 53 commands.
+The pipeline runs natively on **Claude Code**, **Copilot CLI** and **Codex CLI** - all three install from the same `pipeline/` source and get the same 54 commands.
 
 | Tool | Flag | What it installs |
 |---|---|---|
 | Claude Code | `--claude` (default) | slash commands + skills + agents + `PreToolUse` secret-scan hook |
-| Copilot CLI | `--copilot` | instructions + 53 sub-command skills + scripts |
-| Codex CLI | `--codex` | one router skill + 53 specs as refs + 8 agent TOML + `AGENTS.md` block + `codex mcp add` |
+| Copilot CLI | `--copilot` | instructions + 54 sub-command skills + scripts |
+| Codex CLI | `--codex` | one router skill + 54 specs as refs + 8 agent TOML + `AGENTS.md` block + `codex mcp add` |
 
 Filter skills by stack with `--platform=ios\|android\|all`.
 

package/README.tr.md

@@ -89,7 +89,7 @@ Koşunun kendisinde ayarlanabilen tek şey derinlik, autopilot ve `--local`; ger
 
 ## Komutlar
 
-`/multi-agent` ve 53 alt komut. `/multi-agent:help` aynı katalogu terminalde, `outputLanguage` ayarına göre gösterir.
+`/multi-agent` ve 54 alt komut. `/multi-agent:help` aynı katalogu terminalde, `outputLanguage` ayarına göre gösterir.
 
 ### Pipeline girişleri
 
@@ -208,13 +208,13 @@ Bu, ilgili plugin'i (+ ortak `ai-common` plugin'ini) repo'nun `.claude/settings.
 
 ## Araç desteği
 
-Pipeline **Claude Code**, **Copilot CLI** ve **Codex CLI** üzerinde native çalışır - üçü de aynı `pipeline/` kaynağından kurulur ve aynı 53 komutu alır.
+Pipeline **Claude Code**, **Copilot CLI** ve **Codex CLI** üzerinde native çalışır - üçü de aynı `pipeline/` kaynağından kurulur ve aynı 54 komutu alır.
 
 | Araç | Bayrak | Ne kurar |
 |---|---|---|
 | Claude Code | `--claude` (varsayılan) | slash komutları + skill'ler + agent'lar + `PreToolUse` secret-scan hook'u |
-| Copilot CLI | `--copilot` | talimatlar + 53 alt-komut skill'i + script'ler |
-| Codex CLI | `--codex` | bir router skill + ref olarak 53 spec + 8 agent TOML + `AGENTS.md` bloğu + `codex mcp add` |
+| Copilot CLI | `--copilot` | talimatlar + 54 alt-komut skill'i + script'ler |
+| Codex CLI | `--codex` | bir router skill + ref olarak 54 spec + 8 agent TOML + `AGENTS.md` bloğu + `codex mcp add` |
 
 Skill'leri stack'e göre filtrele: `--platform=ios\|android\|all`.
 

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

@@ -0,0 +1,129 @@
+# 10. Our own code graph, not a forked one
+
+**Status:** Accepted · 2026-08-28
+
+## Context
+
+Two parts of the pipeline were paying for the same missing capability.
+
+Phase 1 dispatches parallel Explore agents that re-scan the repository with
+grep and read on every task, and `phase-1-analysis.md` makes the "very
+thorough" tier the default for feature, refactor and component work. Phase 7
+writes `~/.claude/knowledge/<project>/architecture.md` with an LLM, from the
+narrow window of whatever task happened to run, and the file is treated as
+stale after 90 days.
+
+Both want the same thing: a cheap, current answer to "where does this live"
+and "what depends on this".
+
+`Graphify-Labs/graphify` is a public reference that solved this and, unlike
+most projects in the space, published numbers for it. Its `BENCHMARKS.md`
+measures a fixed coding agent on ERPNext (~1M lines) over a graded question
+set: key-fact coverage rises from 70.8% on a grep-and-read baseline to 82.0%
+with a graph tool, at ~140K tokens per query, n=6. The baseline it beats is
+our Phase 1.
+
+The obvious move was to adopt it. Two things ruled that out. Its extraction
+is built on tree-sitter, which is a native npm runtime dependency and
+therefore forbidden by ADR-0004. And depending on an external repository for
+a capability this central puts the pipeline's core behaviour outside our
+control.
+
+## Decision
+
+Build the capability inside the pipeline, taking graphify as a design
+reference and not as a code source.
+
+Adopted from it: extraction is deterministic and LLM-free; the artifact is a
+single `graph.json` of typed nodes and edges; hub ("god-node") ranking is the
+highest-signal line of the report; queries are token-budgeted traversals
+rather than neighbourhood dumps; reverse traversal answers impact; and the
+measurement methodology is a graded question set against a grep-and-read
+baseline with the same cost accounting on both arms.
+
+Not adopted: tree-sitter (ADR-0004), LLM-named communities (the pipeline
+already has model routing for that), an MCP server (we ship our own toolkit),
+and its multi-platform installers and hooks.
+
+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`.
+
+## What we deliberately gave up
+
+Regex over comment-stripped source is not a parser. Definitions and imports
+survive that trade; call graphs and type resolution do not. Two further limits
+follow from the same choice and are documented in the command rather than
+hidden:
+
+- A reference resolves only when a name maps to exactly one declaration. A
+  type declared in two files is dropped rather than fanned out to both, so
+  `affected` under-reports on duplicated names.
+- Only type-like symbols are reference targets. An early build let functions
+  be targets and the hub list filled with `with`, `localized`, `size` and
+  `name`: a bare lowercase name matched across files is almost never a call to
+  that exact declaration. The same measurement was repeated per stack rather
+  than assumed: on this repo, including JavaScript functions put `ok` at degree
+  52 and `f` at 38.
+- A nested declaration is a node but never a reference target. Sealed
+  hierarchies name their cases after the concept they model - `Icon`, `Color`,
+  `Success` - and each is declared exactly once, so the ambiguity rule does not
+  catch them. Before this rule, every Kotlin file that merely mentioned the
+  framework's `Color` gained an edge to one app's nested case: 4,072 false
+  edges out of 74,969.
+
+## Measurement
+
+Gated on a large private Swift app: 4,290 sources, 29,212 nodes, 54,626 edges,
+built in 3.2s, validator clean. Build time is dominated by reading the tree, so
+a repo whose files are not in the page cache costs more: the first build of the
+4,229-file Kotlin app took 18.2s and every later one 2.4-3.4s. Ten graded questions, both arms capped at a
+30,000-token retrieval budget, ground truth derived by grep and path match so
+that the impact family is stacked against the graph on purpose.
+
+| Arm | Coverage | Tokens/question |
+|---|---|---|
+| grep + read | 66.0% | 24,555 |
+| code graph | 80.4% | 18,465 |
+
+The aggregate passes the gate, but the split is the useful part. On questions
+naming an exact type, `grep -lw` is the oracle: it scored 100% and the graph
+was marginally worse and marginally more expensive. On questions phrased in
+domain words, the graph scored 63.3% against 32.0% at 10,937 tokens against
+24,983. The value is in narrowing an open-ended search, not in replacing a
+grep for a name you already know.
+
+That measurement covers the context each strategy assembles, not the quality
+of an answer written from it. graphify's numbers measure the latter. The two
+are not directly comparable and this ADR does not claim they are.
+
+## Consequences
+
+Positive:
+
+- No new runtime dependency; ADR-0004 holds.
+- Graph construction costs no API tokens, so Phase 7 can refresh it every run
+  instead of ageing an LLM-written file for 90 days.
+- Staleness becomes a commit comparison rather than a date heuristic.
+- Every stack after the first is one rules file. Bringing up Kotlin, Python
+  and JavaScript needed two engine changes, and both were engine defects that
+  iOS had been getting away with rather than stack requirements: nesting was
+  measured from the pattern's match column, so `public final class Foo` read as
+  nested, and the import pass read a fully stripped body, which blanks a
+  JavaScript module specifier because it is a string literal. iOS was re-gated
+  after both and scored identically.
+
+Negative:
+
+- Accuracy is bounded by regex extraction and will stay below what a parser
+  would give.
+- Each supported stack carries a hand-written rules file that has to keep up
+  with its language.
+- The symbol layer is thin on stacks whose exported unit is a function. On
+  Node the useful graph is the import graph between files, and the command
+  says so rather than implying a richness the stack does not have.
+- A 4,300-file repo produces a ~22MB JSON file. It is read whole on every
+  query; that is fine at this scale and is not proven at ten times it.

package/docs/adr/README.md

@@ -19,6 +19,7 @@ Format: lightly adapted from [Michael Nygard's ADR template](https://cognitect.c
 | [0007](./0007-multi-tool-adapter-framework.md) | Multi-tool adapter framework + token-preserving uninstall | Superseded by v10.7.0 (adapters removed; Claude Code + Copilot CLI only) |
 | [0008](./0008-installer-modularization-and-secret-leak-defense.md) | Installer modularization + secret-leak defense | Accepted (amended v10.7.0: adapter module removed) |
 | [0009](./0009-claude-stack-skills-plugin-only.md) | Claude Code stack skills are plugin-only; local copy retired | Accepted (supersedes ADR-0006 install-destination clause) |
+| [0010](./0010-own-code-graph.md) | Own code graph, referenced from graphify, not forked | Accepted |
 
 ## Writing a New ADR
 

package/docs/architecture.md

@@ -117,7 +117,7 @@ graph TB
     end
 
     subgraph "Pipeline Specs"
-        CMD[commands/<br/>53 command files]
+        CMD[commands/<br/>54 command files]
         AGT[agents/<br/>8 agent personas]
         RUL[rules/<br/>12 domain rules]
         PHS[multi-agent-refs/phases/<br/>phase specs + contracts]
@@ -170,7 +170,7 @@ revisions of this diagram - Codex CLI and the two independently-shipped repos
 graph TD
     CC["Claude Code<br/>(source of truth)"]
     COP["Copilot CLI<br/>(instructions + 51 skills)"]
-    COD["Codex CLI<br/>(1 router skill + 53 refs)"]
+    COD["Codex CLI<br/>(1 router skill + 54 refs)"]
     REPO["Pipeline Repo<br/>(npm package)"]
     WEB["Website"]
     PLUGREPO["multi-agent-plugins<br/>(5 stack plugins, own repo)"]

package/docs/ecosystem.md

@@ -5,7 +5,7 @@ separately, wired together at install time and at run time:
 
 | Repo | What it owns | Ships as |
 |---|---|---|
-| **`multi-agent-pipeline`** (this repo) | Orchestration: the 8-phase flow, the 53 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-pipeline`** (this repo) | Orchestration: the 8-phase flow, the 54 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, 5 independently-versioned plugins |
 | **`multi-agent-toolkit-mcp`** | The pipeline's hands on devices and browsers: 80 MCP tools across 6 categories (simulator/emulator control, accessibility audit, store compliance, web automation, Figma-vs-mock design audit, an agent-DSL batch runner) | npm package, registered as a standard stdio MCP server on every host |
 
@@ -18,7 +18,7 @@ Either can be swapped or removed without touching the other two's source.
 graph LR
     subgraph PIPE ["multi-agent-pipeline (orchestrator)"]
         direction TB
-        PHASES["8 phases · 53 commands"]
+        PHASES["8 phases · 54 commands"]
         GATES["deterministic gates + review triage"]
     end
 
@@ -64,8 +64,8 @@ only those:
 graph TD
     CC["Claude Code<br/>~/.claude/commands/multi-agent/<br/>(source of truth)"]
 
-    CC -->|"Step 2: copy + reformat<br/>53 sub-command skills"| COP["Copilot CLI<br/>~/.copilot/skills/"]
-    CC -->|"Step 2b: transform<br/>(install.js --codex)"| COD["Codex CLI<br/>1 router skill + 53 refs<br/>+ 8 agent TOML"]
+    CC -->|"Step 2: copy + reformat<br/>54 sub-command skills"| COP["Copilot CLI<br/>~/.copilot/skills/"]
+    CC -->|"Step 2b: transform<br/>(install.js --codex)"| COD["Codex CLI<br/>1 router skill + 54 refs<br/>+ 8 agent TOML"]
     CC -->|"Step 3: genericize<br/>(strip personal data)"| REPO["multi-agent-pipeline repo<br/>pipeline/"]
     CC -->|"Step 4: version + feature sync"| WEB["Website<br/>projects.ts / i18n.tsx"]
 
@@ -153,7 +153,7 @@ measurements behind this table):
 
 | | Claude Code | Copilot CLI | Codex CLI |
 |---|---|---|---|
-| **Pipeline commands** | 53 slash-command skills, native | 53 skills, `multi-agent-{cmd}` naming, copied in | 1 router skill (`multi-agent`) + 53 command specs as reference files - Codex silently truncates its skills block past a few dozen entries, so sub-commands are not peer skills here |
+| **Pipeline commands** | 54 slash-command skills, native | 54 skills, `multi-agent-{cmd}` naming, copied in | 1 router skill (`multi-agent`) + 54 command specs as reference files - Codex silently truncates its skills block past a few dozen entries, so sub-commands are not peer skills here |
 | **Stack plugins** | Marketplace plugin, loaded natively, resolved by `.claude/settings.json` enabled-list | Enabled plugin's authored skills copied flat into `~/.copilot/skills/`; `knowledge/` **not** re-copied (already delivered via `shared/external`) | Copied as reference files under `~/.codex/multi-agent-refs/skills/`, plugin-prefixed on name clash (e.g. `architecture` → `ai-ios-toolkit-architecture`) |
 | **Component dispatch (Phase 3)** | Marketplace plugin's `create-component`/`create-screen` skill via the Skill tool | No plugin loader - the enabled stack plugin's authored skills (incl. `create-component`) are copied flat into `~/.copilot/skills/` at install time (the old frozen `figma-*` copies are pruned, they were never a fallback) | Not part of the enforced parity axis; classification + state-shape must match, skill *inventory* does not |
 | **multi-agent-toolkit-mcp** | `claude mcp add multi-agent-toolkit -- npx -y @mmerterden/multi-agent-toolkit-mcp` | `copilot mcp add multi-agent-toolkit -- npx -y @mmerterden/multi-agent-toolkit-mcp` | `codex mcp add multi-agent-toolkit -- npx -y @mmerterden/multi-agent-toolkit-mcp` (skipped with a warning if `codex` isn't on `PATH`) |

package/docs/features.md

@@ -40,6 +40,14 @@ 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)
+
+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 7 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.
+
+Measured on a 4,300-file Swift app against a grep-and-read baseline at the same 30,000-token retrieval budget: 80.4% key-fact coverage at 18,465 tokens against 66.0% at 24,555. The gain is entirely in searches phrased in domain words (63.3% against 32.0%, at under half the cost). When the task already names an exact type, `grep -lw` is still slightly better and slightly cheaper, and the command says so rather than overselling. Reasoning, trade and limits: `docs/adr/0010-own-code-graph.md`.
+
 ### Stack Auto-Detection
 
 | Platform       | Detection                                    | Guide Loaded             |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "16.12.0",
+  "version": "16.14.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/commands/multi-agent/graph/SKILL.md

@@ -0,0 +1,105 @@
+---
+description: "Build and query this repo's code graph: a deterministic, LLM-free map of symbols, imports and references used to narrow Phase 1's Explore scope and to keep the knowledge base current. Read-only on code, costs no API tokens. Use when a task needs to know where something lives or what depends on it before reading files."
+description-tr: "Bu repo'nun kod grafiğini kurar ve sorgular: sembolleri, import'ları ve referansları LLM'siz, deterministik biçimde haritalar. Faz 1'in Explore kapsamını daraltmak ve bilgi tabanını güncel tutmak için kullanılır. Kodda salt-okunur, API maliyeti yok."
+argument-hint: "[build | refresh | ask \"<question>\" | affected \"<symbol>\" | report | status]"
+---
+
+# multi-agent graph  -  code graph build and query
+
+**Input**: $ARGUMENTS
+
+A code graph is a map of what this repo declares and what refers to what, built by
+regex over comment-stripped source. It exists so Phase 1 can narrow its Explore
+fan-out and Phase 7 can refresh `~/.claude/knowledge/<project>/` without an LLM
+pass. It answers "where does this live" and "what depends on this". It does not
+answer "what calls this at runtime": call graphs and type resolution need a real
+parser, which would be an npm runtime dependency, and ADR-0004 forbids one.
+
+No worktree, no branch, no commit, no pipeline chaining.
+
+## Sub-commands
+
+| Input | Runs | Notes |
+|---|---|---|
+| `build` | `graph-build.mjs --root <repo> --stack <stack>` | Writes `~/.claude/knowledge/<project>/code-graph.json` |
+| `refresh` | same as `build` | A full rebuild takes seconds, so there is no separate incremental path |
+| `ask "<question>"` | `graph-query.mjs "<question>" --budget N` | Token-budgeted traversal; default budget 2000 |
+| `affected "<symbol>"` | `graph-affected.mjs "<symbol>" --depth N` | Reverse traversal: the blast radius of a change |
+| `report` | `graph-report.mjs` | Writes `GRAPH_REPORT.md` beside the graph |
+| `status` | `graph-report.mjs --status` | One line: stack, scale, build time and whether `baseCommit` still matches HEAD. Never read the graph file yourself - it is 22MB on a large repo |
+
+With no argument, run `status`, then offer `build` when no graph exists and
+`refresh` when `baseCommit` differs from the current HEAD.
+
+## Steps
+
+1. **Resolve the repo.** `PROJECT_ROOT` is the current repo root unless the user
+   named another. Derive the graph path once and pass it to every call below:
+
+   ```bash
+   GRAPH_PATH="$HOME/.claude/knowledge/$(basename "$PROJECT_ROOT")/code-graph.json"
+   ```
+
+   The query, affected and report scripts default that path from the CWD's
+   basename, which is not the same thing when the shell sits in a worktree or a
+   sub-package, so a defaulted path can point at a graph that was never built.
+
+2. **Resolve the stack.** Read `state.detectedStack` when a run is in flight;
+   otherwise detect from project markers the way Phase 1 Step 2 does. Only stacks
+   with a file in `$HOME/.claude/scripts/code-graph-rules/` can be built. A stack with
+   no rule file is reported as unsupported, never guessed at.
+
+3. **Run the sub-command.** Every script is read-only on the repo and writes only
+   under `~/.claude/knowledge/`:
+
+   ```bash
+   node $HOME/.claude/scripts/graph-build.mjs --root "$PROJECT_ROOT" --stack "$STACK" --out "$GRAPH_PATH"
+   node $HOME/.claude/scripts/graph-query.mjs "<question>" --graph "$GRAPH_PATH" --budget 2000
+   node $HOME/.claude/scripts/graph-affected.mjs "<symbol>" --graph "$GRAPH_PATH" --depth 2
+   node $HOME/.claude/scripts/graph-report.mjs --graph "$GRAPH_PATH"
+   node $HOME/.claude/scripts/graph-report.mjs --graph "$GRAPH_PATH" --status
+   ```
+
+4. **Validate after a build.** A graph that parses but whose edges point at
+   missing nodes yields silently truncated traversals, so the build is not
+   reported as successful until the validator agrees:
+
+   ```bash
+   node $HOME/.claude/scripts/validate-code-graph.mjs "$GRAPH_PATH"
+   ```
+
+   A non-zero exit fails CLOSED: report the validator's `errors[]` verbatim and
+   do not record the graph as usable.
+
+5. **Report.** One line for a build (`files / nodes / edges / elapsed`), the
+   traversal output as-is for `ask` and `affected`, the report path for `report`.
+
+## What the output is for
+
+`ask` returns ranked nodes plus their neighbourhood within a token budget. Feed
+it to an Explore agent as the starting file set rather than pasting it into a
+final answer: it is a search result, not an explanation.
+
+`affected` returns dependents, which is what `analysis.touchedAreas[]` wants.
+
+## Limits worth stating when reporting
+
+- References resolve only when a name maps to exactly one declaration. A type
+  declared in two files is ambiguous and is deliberately dropped, so `affected`
+  under-reports for duplicated names rather than fanning out to every candidate.
+- Only type-like symbols are reference targets. Functions appear in the graph
+  through their declaring file, not as targets, because a bare lowercase name
+  matched across files is almost never a call to that exact declaration.
+- Comments and string literals are stripped before extraction, so a name that
+  appears only in prose or in a string produces no edge.
+- A nested declaration is a node but never a reference target. A Kotlin sealed
+  case or a Python inner class named `Icon` or `Color` is declared exactly once,
+  so the ambiguity rule above does not catch it, and every file that merely
+  mentions the framework type of that name would otherwise gain an edge to it.
+- On stacks whose exported unit is a function (Node most of all) the symbol
+  layer is thin by design and the import graph between files carries the value.
+  Ask `affected "<file>.mjs"` there, not `affected "<functionName>"`.
+- `affected` at `--depth 1` returns direct symbol references only. An import
+  whose module name matches a declaring file's basename reaches the symbol
+  through that file, so its importers appear at depth 2. Keep the default
+  depth of 2 unless direct references are what you actually want.

package/pipeline/commands/multi-agent/help/SKILL.md

@@ -9,14 +9,14 @@ Called with no args or `help`, show the usage guide in the user's preferred lang
 
 ## Language resolution
 
-Help is the assistant's own explanation to the user  -  render it in `prefs.global.outputLanguage`. Fall back to `prefs.global.promptLanguage` for legacy prefs files where `outputLanguage` did not exist yet. Two valid values: `"en"` (default) and `"tr"`. If both fields are missing / malformed → treat as `"en"`.
+Help is the assistant's own explanation to the user  -  render it in `prefs.global.outputLanguage`, falling back to `prefs.global.promptLanguage` on prefs files written before it existed. Two valid values: `"en"` (default) and `"tr"`; missing or malformed → `"en"`.
 
 ```bash
 PREFS="$HOME/.claude/multi-agent-preferences.json"
 LANG=$(jq -r '.global.outputLanguage // .global.promptLanguage // "en"' "$PREFS" 2>/dev/null || echo "en")
 ```
 
-Render **exactly one** of the two blocks below  -  the one matching `LANG`. Do not print both; the user asked for a display, not a bilingual dump.
+Render **exactly one** of the two blocks below  -  the one matching `LANG`. Never print both.
 
 ---
 
@@ -127,12 +127,12 @@ Post-Hoc & Side-Channel:
   /multi-agent:build-optimize iOS-only Xcode build perf wrapper → benchmark + analyze + recommend-first .build-benchmark/optimization-plan.md
   /multi-agent:create-jira ["desc"] [figma-url] [swagger-url]  Create a Jira Task/Bug/Story matching team conventions (asks type + mining + active sprint + auto-sizing sections + preview & approval)
   /multi-agent:diff-explain   Map a Phase 4 triage finding back to specific diff lines
+  /multi-agent:graph         Build and query the repo code graph (symbols, imports, references), LLM-free
   /multi-agent:search         Cross-task log search with smart ranking; --semantic queries triage corpus
   /multi-agent:scan           Skill security scan against tiered pattern catalog
   /multi-agent:refactor       Best practices + bug hunt + upstream drift + toolkit MCP research -> one plan, approval, dev + sync
   /multi-agent:store-ready [repo] [--archive=|--ipa=|--aab=|--apk=] [--skip-sweep]  Pre-submission store readiness, iOS + Android, local-only: three symmetric gates per platform plus the running-app sweep. A skipped gate is never a pass. Validates only, never uploads.
-  /multi-agent:testflight-validation [repo] [--ipa=|--archive=]  iOS-pinned alias of :store-ready, kept because it is
-                              the name you reach for when the target is TestFlight. Same three gates, one implementation.
+  /multi-agent:testflight-validation [repo] [--ipa=|--archive=]  iOS-pinned alias of :store-ready. Same three gates, one implementation.
   /multi-agent:ios-coding-standard [module]  Audit an iOS module against the 99-rule coding-standard registry -> remediation
                               plan + one-page onboarding summary -> hand off to /multi-agent or :local. Read-only, never edits source.
 
@@ -143,7 +143,7 @@ Setup & Maintenance:
   /multi-agent:stack [ids...]  Enable stack plugin(s); multi-select: ids together (ios backend) or no arg -> native picker (common always on)
   /multi-agent:sync           Sync ecosystem (Claude Code + Copilot CLI + pipeline + website + toolkit MCP)
   /multi-agent:update         Pull latest pipeline + reinstall + run migrations
-  /multi-agent:uninstall      Uninstall pipeline from every CLI (--all-data also clears settings + logs; Keychain tokens always intact, double confirm)
+  /multi-agent:uninstall      Uninstall pipeline from every CLI (--all-data also clears settings, logs, memory + knowledge; tokens always intact)
 
 ------------------------------------------------------------
 
@@ -401,12 +401,12 @@ Post-Hoc & Side-Channel:
   /multi-agent:build-optimize iOS-only Xcode build performance wrapper → benchmark + analiz + recommend-first .build-benchmark/optimization-plan.md
   /multi-agent:create-jira ["açıklama"] [figma-url] [swagger-url]  Takım standartlarına uygun Jira Task/Bug/Story oluştur (tip sorar + convention mining + aktif sprint + auto-sizing bölümler + önizleme & onay)
   /multi-agent:diff-explain   Phase 4 triage bulgusunu diff satırlarına eşle
+  /multi-agent:graph         Repo kod grafiğini kur ve sorgula (semboller, import'lar, referanslar), LLM'siz
   /multi-agent:search         Task log'larında akıllı arama; --semantic triage corpus'unu sorgular
   /multi-agent:scan           Skill güvenlik taraması (tiered pattern catalog)
   /multi-agent:refactor       Uyarlanmış best-practice + bug avı + upstream-drift + multi-agent-toolkit MCP araştırması -> tek plan, onay, dev + sync
   /multi-agent:store-ready [repo] [--archive=|--ipa=|--aab=|--apk=] [--skip-sweep]  Yükleme öncesi store hazırlığı, iOS + Android, yalnızca lokal: platform başına 3 simetrik kapı artı çalışan-app sweep'i. Atlanan kapı asla pass sayılmaz. Sadece doğrular, asla yüklemez.
-  /multi-agent:testflight-validation [repo] [--ipa=|--archive=]  :store-ready'nin iOS'a sabitlenmiş alias'ı; hedef
-                              TestFlight olduğunda akla gelen isim olduğu için korunuyor. Aynı 3 kapı, tek implementasyon.
+  /multi-agent:testflight-validation [repo] [--ipa=|--archive=]  :store-ready'nin iOS alias'ı. Aynı 3 kapı, tek implementasyon.
   /multi-agent:ios-coding-standard [modül]  Bir iOS modülünü 99 kurallık kodlama-standardı registry'sine göre denetler -> düzeltme
                               planı + tek sayfalık onboarding özeti -> /multi-agent veya :local'e devreder. Read-only, kaynağı hiç düzenlemez.
 
@@ -417,7 +417,7 @@ Setup & Maintenance:
   /multi-agent:stack [ids...]     Stack plugin'lerini etkinleştir; çoklu seçim: id'ler yan yana (ios backend) ya da argümansız -> native picker (common hep açık)
   /multi-agent:sync               Ekosistemi senkronize et (Claude Code + Copilot CLI + pipeline + website + multi-agent-toolkit MCP)
   /multi-agent:update             En son pipeline'ı çek + reinstall + migration çalıştır
-  /multi-agent:uninstall          Pipeline'ı tüm CLI'lerden kaldır (--all-data ayar + logları da siler; Keychain token her zaman dokunulmaz, çift onay)
+  /multi-agent:uninstall          Pipeline'ı tüm CLI'lerden kaldır (--all-data ayar, log, hafıza + bilgi tabanını da siler; token'a dokunulmaz)
 
 ------------------------------------------------------------
 

package/pipeline/commands/multi-agent/sync/SKILL.md

@@ -16,7 +16,7 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 | Arg | Meaning |
 |---|---|
 | (none) | Full ecosystem sync: Claude Code, Copilot CLI, pipeline repo, website, multi-agent-toolkit MCP server. |
-| `release` | Full sync + version bump + tag + npm publish + website deploy (includes the multi-agent-toolkit ship path) |
+| `release` | Full sync + version bump + tag + npm publish + website deploy (plus the multi-agent-toolkit ship path) |
 | `multi-agent-toolkit` | Run Step 3d only: gate, commit and publish the companion MCP server |
 | `--platform=<macos\|linux\|windows>` | Override automatic platform detection. For CI / cross-platform smoke. |
 | `"change description"` | Apply the description to every target at once |
@@ -59,7 +59,7 @@ Run every step automatically:
 ```
 Step 1: PLATFORM    Detect macOS / Linux / Windows (Git Bash / WSL); export PLATFORM env
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 53 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 54 sub-command skills)
 Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 51 specs as refs + 8 agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
@@ -166,7 +166,7 @@ If nothing is stale → report "All targets up to date" and stop.
 Unlike the Copilot step, this one does **not** hand-copy files. The Codex tree is a
 *transform* of the Claude tree, not a mirror of it, and the transform is real work:
 
-- the 53 sub-command specs become reference files, because Codex silently truncates
+- the 54 sub-command specs become reference files, because Codex silently truncates
   its skills block (see `cross-cli-contract.md` 2.6 for the measurement)
 - every `$HOME/.claude/...` reference to a CLI-owned tree is retargeted, with
   `agents/<persona>.md` becoming `.toml` and the dispatcher becoming the router skill
@@ -467,7 +467,7 @@ When invoked with the `release` argument:
 3. LINT + TEST   ESLint + smoke tests
 4. VERSION       package.json version bump (patch/minor/major)
 5. Commit + TAG  git commit + git tag v{VERSION}
-6. PUSH          git push --tags -> release.yml auto-publish
+6. PUSH          git push --tags; publish is local (release.yml off)
 7. DEV-TOOLKIT   Ship the companion MCP server if it moved (Step 3d gates, then publish)
 8. WEBSITE       Version + features -> {website-host} (maintainer identity, build verified Ready)
 9. COPILOT       Copilot CLI instructions + skills sync
@@ -489,18 +489,18 @@ same 51 specs as reference files rather than as peer skills, via Step 2b -  see
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**53 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**54 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels,
 complaint-analysis, create-jira, design-check, dev, dev-autopilot, dev-local,
-dev-local-autopilot, diff-explain, feedback, forget, garbage-collect, help,
-ios-coding-standard, issue, jira, kill, language, local, local-autopilot,
-log, manual-test, prune-logs, prune-prompts, purge, refactor, resume,
-resume-local, review, review-analysis, review-issue, review-jira, routines,
-save, scan, search, setup, stack, status, store-ready, sync, test,
-test-accessibility, test-dark-mode, test-dynamic-type, test-screenshots,
-testflight-validation, uninstall, update
+dev-local-autopilot, diff-explain, feedback, forget, garbage-collect,
+graph, help, ios-coding-standard, issue, jira, kill, language, local,
+local-autopilot, log, manual-test, prune-logs, prune-prompts, purge,
+refactor, resume, resume-local, review, review-analysis, review-issue,
+review-jira, routines, save, scan, search, setup, stack, status,
+store-ready, sync, test, test-accessibility, test-dark-mode,
+test-dynamic-type, test-screenshots, testflight-validation, uninstall, update
 ```
 
 **NOT synced**: `$HOME/.claude/multi-agent-refs/*`  -  lazy-load references, Claude Code specific

package/pipeline/commands/multi-agent/uninstall/SKILL.md

@@ -1,7 +1,7 @@
 ---
-description: "Uninstall the pipeline from Claude Code + Copilot CLI. Keychain access tokens are always left untouched; --all-data also clears pipeline settings and logs. Asks for double confirmation. Use when the pipeline should be removed from Claude Code and Copilot CLI."
+description: "Uninstall the pipeline from Claude Code + Copilot CLI. Keychain access tokens are always left untouched; --all-data also clears pipeline settings, logs, per-repo memory and the knowledge base. Asks for double confirmation. Use when the pipeline should be removed from Claude Code and Copilot CLI."
 disable-model-invocation: true
-description-tr: "Pipeline'ı Claude Code + Copilot CLI'dan kaldırır. Keychain erişim token'larına asla dokunulmaz; --all-data ayrıca pipeline ayarlarını ve loglarını da siler. Çift onay ister."
+description-tr: "Pipeline'ı Claude Code + Copilot CLI'dan kaldırır. Keychain erişim token'larına asla dokunulmaz; --all-data ayrıca pipeline ayarlarını, loglarını, repo bazlı hafızayı ve bilgi tabanını da siler. Çift onay ister."
 argument-hint: "[--dry-run] [--all-data] [--claude] [--copilot] [--target=<path>]"
 ---
 
@@ -19,7 +19,7 @@ Uninstalls the pipeline itself from the system. **This is different from `:purge
 | Mode | Flag | Removes | Keeps |
 |---|---|---|---|
 | **Standard** (default) | (none) | distributed files: commands, skills, agents, scripts, refs, schemas, lib (except the credential reader) | tokens + `lib/credential-store.sh` + the `multi-agent-toolkit` MCP registration, `CLAUDE.md`, `rules/`, `multi-agent-preferences.json`, all logs |
-| **Full cleanup** | `--all-data` | standard PLUS `~/.claude/logs/multi-agent/` (task logs, state, metrics, audit) and everything in `multi-agent-preferences.json` **except `global.keychainMapping`** | tokens + the credential reader + the mapping that names them + the MCP registration, `CLAUDE.md`, `rules/` (user-owned) |
+| **Full cleanup** | `--all-data` | standard PLUS `~/.claude/logs/multi-agent/` (task logs, state, metrics, audit), `~/.claude/memory/multi-agent/` (learnings ledger + triage corpus), `~/.claude/knowledge/` (per-repo knowledge base + code graph) and everything in `multi-agent-preferences.json` **except `global.keychainMapping`** | tokens + the credential reader + the mapping that names them + the MCP registration, `CLAUDE.md`, `rules/` (user-owned) |
 
 Tokens in the OS credential store are NEVER removed by either mode.
 
@@ -35,22 +35,24 @@ Tokens in the OS credential store are NEVER removed by either mode.
 - Local-only alias wrappers (`local-only: true` frontmatter) under `commands/multi-agent/` (user-authored, exist nowhere else)
 - User-authored skill dirs and agent files (only pipeline-shipped names are removed)
 
-Settings (`multi-agent-preferences.json`) and the log root (`~/.claude/logs/multi-agent/`) are kept by default and removed only when the user picks full cleanup (`--all-data`).
+Settings (`multi-agent-preferences.json`), the log root (`~/.claude/logs/multi-agent/`), the memory root (`~/.claude/memory/multi-agent/`) and the knowledge root (`~/.claude/knowledge/`) are kept by default and removed only when the user picks full cleanup (`--all-data`). The last two are the ones a user usually means by "remove everything": they hold prose about a private codebase and, in `code-graph.json`, every symbol name in it.
+
+Per-repo memory written INSIDE a repo (`$PROJECT_ROOT/.multi-agent/memory/`) is never touched by either mode. It lives in the user's working tree, may be committed, and uninstalling a tool is not a licence to edit their repos.
 
 ## Steps
 
 1. **Determine scope**  -  parse `$ARGUMENTS`:
    - No target flag: every installed target (default)
    - `--claude / --copilot`: selective
-   - `--all-data`: full cleanup (also removes settings + logs)
+   - `--all-data`: full cleanup (also removes settings, logs, per-repo memory and the knowledge base)
    - `--target=<path>`: adapter target (default: cwd)
    - `--dry-run`: report only, delete nothing
 
 2. **Ask the cleanup depth** (skip if the user already passed `--all-data` or `--dry-run`)  -  native `AskUserQuestion` picker in `outputLanguage`:
    - `question`: "How much should uninstall remove? Tokens are preserved either way."
    - `header`: "Scope" · `options`:
-     `{ label: "Standard", description: "Remove pipeline files; keep settings + logs" }`,
-     `{ label: "Full cleanup", description: "Also remove settings + all task logs/state/metrics" }`
+     `{ label: "Standard", description: "Remove pipeline files; keep settings, logs, memory, knowledge" }`,
+     `{ label: "Full cleanup", description: "Also remove settings, logs, per-repo memory and the knowledge base" }`
    - **Full cleanup** adds `--all-data` to the flag set below.
 
 3. **Show a preview** (run the script with `--dry-run`, carrying the chosen flags):