@mmerterden/multi-agent-pipeline 16.13.0 → 16.14.0

package/CHANGELOG.md

@@ -16,6 +16,17 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "16.13.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/multi-agent-refs/analysis/evidence.md

@@ -75,6 +75,27 @@ grep -rilE "$slugs" $WHITELIST --include="*.swift" --include="*.kt" --include="*
 
 If `wc -l < $CANDIDATES` exceeds 200, record `fetchWarnings += "feature-name too generic; candidate cap hit"` in `repoEvidence[<repo>]`.
 
+**Ranking the candidates (opt-in, `prefs.global.codeGraph.enabled`).** `head -200`
+truncates in grep's walk order, so the cap drops an arbitrary file rather than the
+least relevant one - the failure the warning above names and cannot fix. When a
+graph exists for the repo, rank the set first:
+
+```bash
+GRAPH_PATH="$HOME/.claude/knowledge/$(basename "$REPO_ROOT")/code-graph.json"
+node $HOME/.claude/scripts/graph-report.mjs --graph "$GRAPH_PATH" --status \
+  || node $HOME/.claude/scripts/graph-build.mjs --root "$REPO_ROOT" --stack "$STACK" --json
+node $HOME/.claude/scripts/graph-query.mjs "$featureName" --graph "$GRAPH_PATH" --json
+```
+
+Ranked paths go to the front of `$CANDIDATES`, grep-only hits keep their order
+behind them, everything else is unchanged, and a repo with no graph, an
+unsupported stack or a failing validator gets exactly today's order. 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. Sorting
+rather than detecting is where each tool measured better - the graph beats grep on
+domain words, a feature name is domain words, and it loses on the exact symbols
+the bucket patterns use (`docs/adr/0010-own-code-graph.md`).
+
 **13 buckets** (each scanned in parallel with a 30 s timeout per bucket; timeout marks the bucket as `partial`, never blocks the others):
 
 | Bucket | Detection (iOS Swift sketch) | Cross-platform variant |

package/pipeline/multi-agent-refs/features/code-graph.md

@@ -29,7 +29,14 @@ report scripts default it from the CWD's basename, and a run happens in a
 worktree whose basename need not equal the repo's, so a defaulted path can point
 at a graph that was never built. Pass it.
 
-Build only when `baseCommit` no longer matches HEAD. A build is not usable until
+Build when there is no graph at all, and when `baseCommit` no longer matches
+HEAD. The missing case is the one that matters in practice: `architecture.md`
+and its siblings are written in Phase 7, which is the phase a run is least
+likely to reach, so a repo can have a long history of tasks and an empty
+knowledge directory. The graph must not inherit that. `--status` exits 1 on a
+missing file, and that exit means build, not skip.
+
+A build is not usable until
 `validate-code-graph.mjs` exits 0: a graph whose edges point at missing nodes
 truncates traversals silently, so a non-zero exit means skip the injection and
 run Explore as if no graph existed.

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

@@ -12,7 +12,7 @@
     },
     "stack": {
       "type": "string",
-      "enum": ["ios", "android", "node", "python"]
+      "enum": ["ios", "android", "node", "python", "go"]
     },
     "root": {
       "type": "string",

package/pipeline/scripts/_code-graph.mjs

@@ -37,6 +37,27 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 
 export const GRAPH_SCHEMA_VERSION = "1.0.0";
 
+/**
+ * Stack words the pipeline uses elsewhere, mapped to the rule-file id.
+ *
+ * The rule files are named after the toolchain (`node`), but the rest of the
+ * pipeline names the product surface (`web`), and a caller reasonably types
+ * whichever one they were last shown. Aliasing is safe only where the mapping
+ * is one-to-one: `backend` is deliberately absent, because it could be node,
+ * python or go and picking one would be a guess dressed as support.
+ */
+export const STACK_ALIASES = { web: "node", frontend: "node" };
+
+/**
+ * Canonical rule-file id for a stack word.
+ *
+ * @param {string} stack
+ * @returns {string}
+ */
+export function resolveStack(stack) {
+  return STACK_ALIASES[stack] || stack;
+}
+
 /**
  * Load and merge the two rule files for a stack.
  *
@@ -48,9 +69,15 @@ export const GRAPH_SCHEMA_VERSION = "1.0.0";
  * @param {string} [baseDir] - directory holding the two rule dirs
  * @returns {object} merged rules
  */
-export function loadRules(stack, baseDir = __dirname) {
+export function loadRules(requested, baseDir = __dirname) {
+  const stack = resolveStack(requested);
   const gapPath = join(baseDir, "test-gap-rules", `${stack}.json`);
   const graphPath = join(baseDir, "code-graph-rules", `${stack}.json`);
+  if (requested === "backend") {
+    throw new Error(
+      "'backend' names a role, not a toolchain: pass node, python or go so the right rules load",
+    );
+  }
   if (!existsSync(gapPath)) throw new Error(`no test-gap rules for stack '${stack}': ${gapPath}`);
   if (!existsSync(graphPath))
     throw new Error(`no code-graph rules for stack '${stack}': ${graphPath}`);

package/pipeline/scripts/code-graph-rules/go.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "stack": "go",
+  "description": "Go code-graph rules. Adds what the graph needs on top of test-gap-rules/go.json, which already owns sourceExtensions, excludePathGlobs and the test-path predicates. Definition patterns here are deliberately broader than the test-gap publicApiPatterns: the graph wants unexported declarations too, because Phase 1 narrows scope on the whole package, not just its exported surface.",
+  "comments": {
+    "line": [
+      "//"
+    ],
+    "block": [
+      [
+        "/*",
+        "*/"
+      ]
+    ],
+    "string": [
+      "`",
+      "\"",
+      "'"
+    ]
+  },
+  "importSpecifiersAreStrings": true,
+  "definitionPatterns": [
+    {
+      "id": "struct",
+      "kind": "struct",
+      "regex": "\\btype\\s+([A-Za-z_][A-Za-z0-9_]*)\\s+struct\\b"
+    },
+    {
+      "id": "interface",
+      "kind": "interface",
+      "regex": "\\btype\\s+([A-Za-z_][A-Za-z0-9_]*)\\s+interface\\b"
+    },
+    {
+      "id": "type",
+      "kind": "type",
+      "regex": "\\btype\\s+([A-Za-z_][A-Za-z0-9_]*)\\s+(?!struct\\b|interface\\b)[A-Za-z_*\\[]"
+    },
+    {
+      "id": "func",
+      "kind": "func",
+      "regex": "^func\\s+(?:\\([^)]*\\)\\s+)?([A-Za-z_][A-Za-z0-9_]*)\\s*[(\\[]"
+    }
+  ],
+  "importPatterns": [
+    {
+      "id": "specifier",
+      "regex": "^[ \\t]*(?:import[ \\t]+)?(?:[A-Za-z_.][A-Za-z0-9_]*[ \\t]+)?\"(?:[^\"]*/)?([A-Za-z_][A-Za-z0-9_.-]*)\"[ \\t]*$"
+    }
+  ],
+  "referenceKinds": [
+    "struct",
+    "interface",
+    "type"
+  ],
+  "referenceKindsNote": "func is deliberately absent, for the reason the Swift, Kotlin, Node and Python rules all record: a bare name matched across files is almost never a call to that exact declaration, and Go's short-name convention (New, Run, Get, Close, Error) makes it worse than most. Functions still reach the graph through their defines edge, so they stay findable by name.",
+  "ignoredIdentifiers": [
+    "package",
+    "import",
+    "func",
+    "type",
+    "struct",
+    "interface",
+    "map",
+    "chan",
+    "var",
+    "const",
+    "return",
+    "if",
+    "else",
+    "for",
+    "range",
+    "switch",
+    "case",
+    "default",
+    "select",
+    "go",
+    "defer",
+    "break",
+    "continue",
+    "fallthrough",
+    "goto",
+    "nil",
+    "true",
+    "false",
+    "iota",
+    "make",
+    "new",
+    "len",
+    "cap",
+    "append",
+    "copy",
+    "delete",
+    "panic",
+    "recover",
+    "print",
+    "println",
+    "error",
+    "string",
+    "bool",
+    "byte",
+    "rune",
+    "int",
+    "int8",
+    "int16",
+    "int32",
+    "int64",
+    "uint",
+    "uint8",
+    "uint16",
+    "uint32",
+    "uint64",
+    "float32",
+    "float64",
+    "complex64",
+    "complex128",
+    "uintptr",
+    "any",
+    "comparable",
+    "err",
+    "ctx",
+    "ok"
+  ],
+  "note": "A Go import path is a string literal, so `importSpecifiersAreStrings` applies exactly as it does for JavaScript: the import pass reads a text with comments stripped and strings intact, and the pattern captures the last path segment, which is the package name in the overwhelmingly common case where the two agree. The pattern is anchored to a whole line holding nothing but an optional `import`, an optional alias and the quoted path, because Go has no import keyword on the lines inside a parenthesized block. Without that anchor it matched EVERY double-quoted string in the file and turned each one into a module node. A named import (`sql \"database/sql\"`) and the handful of packages whose name differs from their directory both resolve to the directory name, which is what the engine matches against a file basename anyway. The three type patterns are ordered so `struct` and `interface` claim their shapes before the general `type` alias pattern, which excludes them by lookahead rather than by order alone - order and lookahead together, because a rule file that relies on order silently changes meaning when someone sorts it. `func` is anchored to column 0, which is where every Go function and method declaration lives; the engine's nesting rule then never has to fire for this stack.\n\nUNMEASURED: unlike ios, android, node and python, these rules were never run against a real Go codebase. There was no Go repo and no toolchain on the machine that wrote them. The smoke exercises them on a synthetic fixture, which proves they parse and produce a schema-valid graph, not that they produce a USEFUL one. Treat the first real build as the measurement, and check the hub list before trusting it."
+}

package/pipeline/scripts/test-gap-rules/go.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "stack": "go",
+  "description": "Go test gap rules. Sources in *.go; tests are *_test.go beside the code they cover, which is why there is no test directory convention here.",
+  "sourceExtensions": [".go"],
+  "testPathSuffixes": ["_test.go"],
+  "testPathContains": [],
+  "excludePathGlobs": ["vendor/", "third_party/", "*.pb.go", "*_generated.go", "*_mock.go"],
+  "publicApiPatterns": [
+    {
+      "id": "exported_func",
+      "regex": "^func\\s+([A-Z][A-Za-z0-9_]*)\\s*\\("
+    },
+    {
+      "id": "exported_method",
+      "regex": "^func\\s+\\([^)]*\\)\\s+([A-Z][A-Za-z0-9_]*)\\s*\\("
+    },
+    {
+      "id": "exported_type",
+      "regex": "^type\\s+([A-Z][A-Za-z0-9_]*)\\s+(?:struct|interface|func|map|\\[|chan|\\*|[A-Za-z])"
+    }
+  ],
+  "hint": "Cover exported identifiers with a table-driven Test<Name> in the same package's <file>_test.go. An unexported identifier is covered through the exported one that calls it."
+}

package/pipeline/scripts/validate-code-graph.mjs

@@ -15,7 +15,7 @@
 
 import { readFileSync } from "node:fs";
 
-const ALLOWED_STACK = new Set(["ios", "android", "node", "python"]);
+const ALLOWED_STACK = new Set(["ios", "android", "node", "python", "go"]);
 const ALLOWED_NODE_KIND = new Set(["file", "symbol", "module"]);
 const ALLOWED_EDGE_KIND = new Set(["defines", "imports", "references"]);
 const MAX_REPORTED_DANGLING = 5;