@massa-ai/cursor-plugin 1.29.0 → 1.31.0

package/.cursor-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "massa-ai",
-  "version": "1.29.0",
+  "version": "1.31.0",
   "description": "massa-ai — semantic code search, memory, and context compression for Cursor"
 }

package/README.md

@@ -62,7 +62,7 @@ If you are building a VS Code extension for Cursor, you can register the plugin
 vscode.cursor.plugins.registerPath("/abs/path/to/apps/cursor-plugin");
 ```
 
-Cursor auto-discovers `skills/`, `hooks/hooks.json`, and `agents/` inside the registered directory. MCP is not bundled — Cursor reads `~/.cursor/mcp.json`, which `scripts/install-agents.sh` owns. The `.cursor-plugin/plugin.json` manifest is optional — Cursor discovers the subdirectories without it, but including one aids marketplace submission later.
+Cursor 3.14 loads user-local plugins from `~/.cursor/plugins/local/<name>/` and also bridges Claude marketplace plugins from `~/.claude`, but subagents are discovered only from the flat `~/.cursor/agents/*.md` (or project `.cursor/agents/`) directory — never from a plugin's `agents/` subtree. `install.sh` therefore copies the specialists to `~/.cursor/agents/`; `hooks/hooks.json` entries are merged into `~/.cursor/hooks.json` pointing at the installed hook binary. Cursor reads no global rules file: the AGENTS.md bootstrap must be pasted into Cursor Settings → Rules or provided per project root. MCP is not bundled — Cursor reads `~/.cursor/mcp.json`, which `scripts/install-agents.sh` owns. The `.cursor-plugin/plugin.json` manifest is optional — Cursor discovers the subdirectories without it, but including one aids marketplace submission later.
 
 Use `unregisterPath` to remove:
 

package/install.sh

@@ -11,8 +11,19 @@
 # MCP registration is delegated to scripts/install-agents.sh, the single writer
 # of host MCP config. This installer no longer ships a plugin-local mcp.json.
 #
+# Cursor 3.14 also bridges the Claude marketplace registry from ~/.claude and
+# loads any plugin listed there IN ADDITION to a local install — a machine
+# with both would load massa-ai twice and fire every hook twice (AD-017). At
+# USER scope, this installer prefers the bridge: when ~/.claude lists massa-ai
+# as installed and enabled, it skips its own local plugin copy and hook
+# wiring (removing a pre-existing local copy so one run converges), while
+# still writing the flat subagents, harness skills, and MCP registration this
+# installer always owns. Project-scope installs are unaffected — ~/.claude is
+# a user surface, never a project one.
+#
 # Idempotent: re-running is a no-op when owned entries already present.
-# Uninstall removes only ownership-marked entries + the plugin directory.
+# Uninstall removes only ownership-marked entries + the plugin directory,
+# regardless of which route (bridge or local) installed them.
 #
 # Usage:
 #   apps/cursor-plugin/install.sh             # install at user scope (~/.cursor)
@@ -92,20 +103,80 @@ if [[ "$SCOPE" == "project" ]]; then
 else
   CURSOR_DIR="$HOME/.cursor"
 fi
-# Cursor discovers locally-installed plugins under plugins/local/<name>/, not
-# plugins/<name>/. Installing to the latter is why massa-ai never appeared in
-# Cursor's plugin list even though every file was written correctly.
-#
-# UNVERIFIED against a running Cursor.app — this path comes from Cursor's
-# plugin documentation, not from an observed load, because Cursor is not
-# installed on the machine this was developed on. Treat it as lower confidence
-# than the Claude/Codex routes, which were verified end-to-end.
+# Two verified Cursor 3.14 load surfaces (observed live in "Cursor Plugins"
+# exthost logs, 2026-08-05): user-local plugins ARE loaded from
+# plugins/local/<name>/ ("loadUserLocalPlugin massa-ai loaded"), and Cursor
+# additionally bridges Claude marketplace plugins from ~/.claude
+# ("loadClaudePlugin massa-ai@massa-ai") — so a machine with the Claude
+# plugin installed loads massa-ai twice. Subagents, however, are discovered
+# only from the flat .cursor/agents/*.md directory (cursor.com/docs/subagents
+# — no subdirectories), and there is no global rules file. So: PLUGIN_DIR
+# carries the manifest, hook binary, and command skills; everything else
+# Cursor must SEE goes to its dedicated read paths — $CURSOR_AGENTS_DIR
+# (subagents), $CURSOR_DIR/skills/ (harness skills), $CURSOR_DIR/hooks.json,
+# and $CURSOR_DIR/mcp.json (install-agents.sh).
 PLUGIN_DIR="$CURSOR_DIR/plugins/local/massa-ai"
+# The only directory Cursor discovers subagents from (project scope:
+# ./.cursor/agents/). Flat .md files, real copies, massa-ai- prefix owned.
+CURSOR_AGENTS_DIR="$CURSOR_DIR/agents"
 # Pre-fix installs wrote here; removed on install so the two cannot both be
 # discovered and register duplicate hooks.
 LEGACY_PLUGIN_DIR="$CURSOR_DIR/plugins/massa-ai"
 HOOKS_JSON="$CURSOR_DIR/hooks.json"
 
+# ── Claude-bridge detection (PAU-08/09/10) ──────────────────────────────────
+# Probe contract pinned against a read-only capture of this machine's live
+# ~/.claude registry files (2026-08-05) — never invented:
+#   - $CLAUDE_PLUGIN_REGISTRY must parse and list a non-empty
+#     plugins["massa-ai@massa-ai"] array
+#   - $CLAUDE_SETTINGS_JSON's enabledPlugins["massa-ai@massa-ai"] must not be
+#     literal false — an absent settings.json, or an absent key, is treated
+#     as enabled (matching Claude's own default)
+#   - any parse failure on either file → NOT detected (local fallback)
+# User-scope only: ~/.claude is a per-user surface, so a --project plugin
+# install always keeps the local branch regardless of what ~/.claude holds.
+CLAUDE_PLUGIN_REGISTRY="$HOME/.claude/plugins/installed_plugins.json"
+CLAUDE_SETTINGS_JSON="$HOME/.claude/settings.json"
+
+claude_bridge_detected() {
+  [[ "$SCOPE" == "project" ]] && return 1
+  [[ -f "$CLAUDE_PLUGIN_REGISTRY" ]] || return 1
+
+  local runner=""
+  if command -v node &>/dev/null; then runner="node"
+  elif command -v bun &>/dev/null; then runner="bun"
+  else return 1
+  fi
+
+  "$runner" - "$CLAUDE_PLUGIN_REGISTRY" "$CLAUDE_SETTINGS_JSON" <<'NODE'
+const fs = require("fs");
+const [, , registryFile, settingsFile] = process.argv;
+
+try {
+  const registry = JSON.parse(fs.readFileSync(registryFile, "utf8"));
+  const listed = registry && registry.plugins && registry.plugins["massa-ai@massa-ai"];
+  if (!Array.isArray(listed) || listed.length === 0) process.exit(1);
+} catch {
+  process.exit(1);
+}
+
+try {
+  const raw = fs.readFileSync(settingsFile, "utf8");
+  if (raw.trim()) {
+    const settings = JSON.parse(raw);
+    const enabled = settings && settings.enabledPlugins && settings.enabledPlugins["massa-ai@massa-ai"];
+    if (enabled === false) process.exit(1);
+  }
+} catch (e) {
+  // Absent settings.json is treated as enabled (Claude's own default); any
+  // other read/parse failure means the probe cannot trust this surface.
+  if (e.code !== "ENOENT") process.exit(1);
+}
+
+process.exit(0);
+NODE
+}
+
 # The 7 Cursor events → binary subcommands. The command path uses the
 # INSTALLED plugin dir (not the placeholder), so Cursor invokes the copy.
 # Cursor hooks.json shape: { "version": 1, "hooks": { "<event>": [...] } }
@@ -377,13 +448,15 @@ record_plugin_version() {
   local version installed_at route
   version="$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$SCRIPT_DIR/package.json" | head -n 1)"
   installed_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-  # installRoute (T9, design F1): installer-owned, engine-read-only. Cursor
-  # has one install shape (file copy) and no marketplace distinction, so this
-  # is unconditionally "file" — recorded for data-model consistency with the
-  # other three hosts even though the switch engine never reads it for Cursor
-  # (hosts.ts skips Cursor unconditionally: every tier resolves to inherit).
-  # Written on EVERY install path.
-  route="file"
+  # installRoute (T6, design Component 4): installer-owned, engine-read-only.
+  # "bridge" when ~/.claude's Claude marketplace plugin is what Cursor
+  # actually loads (this run skipped its own local copy); "local" otherwise.
+  # The switch engine still never reads it for Cursor (hosts.ts skips Cursor
+  # unconditionally: every tier resolves to inherit) — recorded for
+  # data-model consistency with the other three hosts, and now also read by
+  # the harness sentinel probe (T4/T5), which treats both routes alike (same
+  # flat-agents glob). Written on EVERY install path.
+  if [[ "$IS_BRIDGE" -eq 1 ]]; then route="bridge"; else route="local"; fi
 
   # Tolerant of a corrupt/missing state file (rewrites a minimal valid one —
   # AC-8). A record-write failure warns but never fails the install: the next
@@ -429,6 +502,19 @@ if [[ "$UNINSTALL" -eq 1 ]]; then
     merge_hooks_json "$HOOKS_JSON" "uninstall"
     echo "  - removed massa-ai hook entries from $HOOKS_JSON"
   fi
+  # Remove the massa-ai-owned subagents from Cursor's discovery directory.
+  # Prefix glob only: user-authored agents in the same flat dir survive.
+  if [[ -d "$CURSOR_AGENTS_DIR" ]]; then
+    removed_agents=0
+    for agent in "$CURSOR_AGENTS_DIR/"massa-ai-*.md; do
+      [[ -f "$agent" ]] || continue
+      rm -f "$agent"
+      removed_agents=$((removed_agents + 1))
+    done
+    if [[ "$removed_agents" -gt 0 ]]; then
+      echo "  - removed $removed_agents massa-ai subagents from $CURSOR_AGENTS_DIR"
+    fi
+  fi
   # Remove plugin directory
   if [[ -d "$LEGACY_PLUGIN_DIR" ]]; then
     rm -rf "$LEGACY_PLUGIN_DIR"
@@ -444,59 +530,101 @@ if [[ "$UNINSTALL" -eq 1 ]]; then
 fi
 
 # ── Install ──────────────────────────────────────────────────────────────────
-vecho "Installing massa-ai Cursor plugin to: $PLUGIN_DIR"
-# Migration: a pre-fix install left a copy at plugins/massa-ai. Leaving it in
-# place risks Cursor discovering both and firing every hook twice, so it goes
-# before the new location is written.
-if [[ -d "$LEGACY_PLUGIN_DIR" ]]; then
-  rm -rf "$LEGACY_PLUGIN_DIR"
-  echo -e "  - removed pre-fix plugin copy at $LEGACY_PLUGIN_DIR"
+# PAU-08/09: bridge-preferred, local-fallback. Computed once, used to decide
+# both which artifacts this run writes and what installRoute gets recorded.
+IS_BRIDGE=0
+if claude_bridge_detected; then
+  IS_BRIDGE=1
 fi
-mkdir -p "$PLUGIN_DIR/.cursor-plugin" "$PLUGIN_DIR/skills" "$PLUGIN_DIR/hooks" "$PLUGIN_DIR/agents"
-
-# Copy manifest
-cp "$SCRIPT_DIR/.cursor-plugin/plugin.json" "$PLUGIN_DIR/.cursor-plugin/plugin.json"
-vecho "  + .cursor-plugin/plugin.json"
 
-# Copy the 6 host-command skills (each in a subdirectory: skills/<name>/SKILL.md).
-# massa-ai/, persona-router/, and agents/ are the PDO-06 harness bundle, not a
-# Cursor command skill — they are installed separately, into the shared
-# harness skills directory (see "Skills bundling" below), not into this
-# plugin-cache skills/ tree.
 skill_count=0
-for src in "$SCRIPT_DIR/skills/"*/SKILL.md; do
-  name="$(basename "$(dirname "$src")")"
-  case "$name" in
-    massa-ai|persona-router|agents) continue ;;
-  esac
-  mkdir -p "$PLUGIN_DIR/skills/$name"
-  cp "$src" "$PLUGIN_DIR/skills/$name/SKILL.md"
-  vecho "  + skills/$name/SKILL.md"
-  skill_count=$((skill_count + 1))
-done
+specialist_count=0
 
-# Copy hooks.json (the placeholder version — installer replaces paths)
-cp "$SCRIPT_DIR/hooks/hooks.json" "$PLUGIN_DIR/hooks/hooks.json"
-vecho "  + hooks/hooks.json"
-
-# Older installs shipped a plugin-local mcp.json here. Cursor reads
-# ~/.cursor/mcp.json, not the plugin dir, and MCP is now owned by
-# scripts/install-agents.sh — drop the residue so upgraders converge.
-if [[ -f "$PLUGIN_DIR/mcp.json" ]]; then
-  rm -f "$PLUGIN_DIR/mcp.json"
-  # Not gated by --quiet: this deletes a file in the user's home, so it is a
-  # mutation notice rather than per-file chatter.
-  echo -e "  - removed stale mcp.json (MCP is now registered in ~/.cursor/mcp.json)"
+if [[ "$IS_BRIDGE" -eq 1 ]]; then
+  vecho "Installing massa-ai Cursor plugin (Claude-bridge route): ~/.claude already lists massa-ai as installed and enabled, so Cursor loads it via the bridge."
+  # Converge (PAU-08, spec edge case): a pre-existing local install (current
+  # or pre-fix legacy location) must not double-load alongside the bridge, so
+  # one run here ends with exactly one load path. Owned hook entries are
+  # stripped with the SAME filter merge_hooks_json's "uninstall" mode already
+  # uses — the bridge delivers hooks instead.
+  if [[ -d "$LEGACY_PLUGIN_DIR" ]]; then
+    rm -rf "$LEGACY_PLUGIN_DIR"
+    echo -e "  - removed pre-fix plugin copy at $LEGACY_PLUGIN_DIR"
+  fi
+  if [[ -d "$PLUGIN_DIR" ]]; then
+    rm -rf "$PLUGIN_DIR"
+    echo -e "  - removed local plugin copy at $PLUGIN_DIR (Claude bridge already loads massa-ai)"
+  fi
+  if [[ -f "$HOOKS_JSON" ]]; then
+    merge_hooks_json "$HOOKS_JSON" "uninstall"
+    echo -e "  - removed massa-ai hook entries from $HOOKS_JSON (the bridge delivers hooks instead)"
+  fi
+else
+  vecho "Installing massa-ai Cursor plugin to: $PLUGIN_DIR"
+  # Migration: a pre-fix install left a copy at plugins/massa-ai. Leaving it in
+  # place risks Cursor discovering both and firing every hook twice, so it goes
+  # before the new location is written.
+  if [[ -d "$LEGACY_PLUGIN_DIR" ]]; then
+    rm -rf "$LEGACY_PLUGIN_DIR"
+    echo -e "  - removed pre-fix plugin copy at $LEGACY_PLUGIN_DIR"
+  fi
+  mkdir -p "$PLUGIN_DIR/.cursor-plugin" "$PLUGIN_DIR/skills" "$PLUGIN_DIR/hooks"
+  # Migration: pre-fix installs bundled agents inside the plugin dir, which
+  # Cursor never reads. Drop that copy so upgraders converge on the one real
+  # discovery surface and a future Cursor plugin scan cannot double-register.
+  if [[ -d "$PLUGIN_DIR/agents" ]]; then
+    rm -rf "$PLUGIN_DIR/agents"
+    echo -e "  - removed pre-fix agents copy at $PLUGIN_DIR/agents (Cursor reads $CURSOR_AGENTS_DIR)"
+  fi
+
+  # Copy manifest
+  cp "$SCRIPT_DIR/.cursor-plugin/plugin.json" "$PLUGIN_DIR/.cursor-plugin/plugin.json"
+  vecho "  + .cursor-plugin/plugin.json"
+
+  # Copy the 6 host-command skills (each in a subdirectory: skills/<name>/SKILL.md).
+  # massa-ai/, persona-router/, and agents/ are the PDO-06 harness bundle, not a
+  # Cursor command skill — they are installed separately, into the shared
+  # harness skills directory (see "Skills bundling" below), not into this
+  # plugin-cache skills/ tree.
+  for src in "$SCRIPT_DIR/skills/"*/SKILL.md; do
+    name="$(basename "$(dirname "$src")")"
+    case "$name" in
+      massa-ai|persona-router|agents) continue ;;
+    esac
+    mkdir -p "$PLUGIN_DIR/skills/$name"
+    cp "$src" "$PLUGIN_DIR/skills/$name/SKILL.md"
+    vecho "  + skills/$name/SKILL.md"
+    skill_count=$((skill_count + 1))
+  done
+
+  # Copy hooks.json (the placeholder version — installer replaces paths)
+  cp "$SCRIPT_DIR/hooks/hooks.json" "$PLUGIN_DIR/hooks/hooks.json"
+  vecho "  + hooks/hooks.json"
+
+  # Older installs shipped a plugin-local mcp.json here. Cursor reads
+  # ~/.cursor/mcp.json, not the plugin dir, and MCP is now owned by
+  # scripts/install-agents.sh — drop the residue so upgraders converge.
+  if [[ -f "$PLUGIN_DIR/mcp.json" ]]; then
+    rm -f "$PLUGIN_DIR/mcp.json"
+    # Not gated by --quiet: this deletes a file in the user's home, so it is a
+    # mutation notice rather than per-file chatter.
+    echo -e "  - removed stale mcp.json (MCP is now registered in ~/.cursor/mcp.json)"
+  fi
 fi
 
-# Copy agents — every generated subagent specialist (auto-discovered by Cursor
-# from the plugin's agents/ dir). All of them, navigator included, are generated
-# from skills/agents/*/SKILL.md and owned by the massa-ai- name prefix (CRS-04).
-specialist_count=0
+# Flat agents and harness skills are written in BOTH branches (PAU-08/09):
+# Cursor discovers subagents only from the flat directory regardless of which
+# plugin-load path is active, and MCP/harness-skills ownership is independent
+# of it too. Prune-then-copy so a specialist deleted from the bundle cannot
+# linger installed. All of them, navigator included, are generated from
+# skills/agents/*/SKILL.md and owned by the massa-ai- name prefix (CRS-04) —
+# user-authored agents are untouched.
+mkdir -p "$CURSOR_AGENTS_DIR"
+rm -f "$CURSOR_AGENTS_DIR/"massa-ai-*.md
 for src in "$SCRIPT_DIR/agents/"massa-ai-*.md; do
   [[ -f "$src" ]] || continue
   name="$(basename "$src")"
-  cp "$src" "$PLUGIN_DIR/agents/$name"
+  cp "$src" "$CURSOR_AGENTS_DIR/$name"
   vecho "  + $name"
   specialist_count=$((specialist_count + 1))
 done
@@ -504,31 +632,33 @@ vecho "  + ${specialist_count} subagent specialists (generated from skills/agent
 
 # Skills bundling (PDO-08, 09): install massa-ai/persona-router into the
 # shared harness skills directory, unless scripts/install-skills.sh already
-# owns it for this platform.
+# owns it for this platform. Runs in both branches (same reasoning as above).
 vecho ""
 install_bundled_skills
 
-# Copy the real hooks/massa-ai-hook this plugin already ships (T14/PDO-14: a
-# generated real file, no longer a symlink into apps/claude-plugin/ — that
-# path does not exist in a registry tarball install, where $REPO_ROOT is not
-# this monorepo. $CLAUDE_PLUGIN_BIN is kept only as a repo-checkout fallback.
-if [[ -f "$SCRIPT_DIR/hooks/massa-ai-hook" ]]; then
-  cp "$SCRIPT_DIR/hooks/massa-ai-hook" "$PLUGIN_DIR/hooks/massa-ai-hook"
-  chmod +x "$PLUGIN_DIR/hooks/massa-ai-hook"
-  vecho "  + hooks/massa-ai-hook"
-elif [[ -f "$CLAUDE_PLUGIN_BIN" ]]; then
-  ln -sfn "$CLAUDE_PLUGIN_BIN" "$PLUGIN_DIR/hooks/massa-ai-hook"
-  vecho "  + hooks/massa-ai-hook → $CLAUDE_PLUGIN_BIN"
-else
-  echo "  ⚠ Warning: no massa-ai-hook binary found" >&2
-  echo "    Hooks will not fire until the binary is available." >&2
-fi
+if [[ "$IS_BRIDGE" -ne 1 ]]; then
+  # Copy the real hooks/massa-ai-hook this plugin already ships (T14/PDO-14: a
+  # generated real file, no longer a symlink into apps/claude-plugin/ — that
+  # path does not exist in a registry tarball install, where $REPO_ROOT is not
+  # this monorepo. $CLAUDE_PLUGIN_BIN is kept only as a repo-checkout fallback.
+  if [[ -f "$SCRIPT_DIR/hooks/massa-ai-hook" ]]; then
+    cp "$SCRIPT_DIR/hooks/massa-ai-hook" "$PLUGIN_DIR/hooks/massa-ai-hook"
+    chmod +x "$PLUGIN_DIR/hooks/massa-ai-hook"
+    vecho "  + hooks/massa-ai-hook"
+  elif [[ -f "$CLAUDE_PLUGIN_BIN" ]]; then
+    ln -sfn "$CLAUDE_PLUGIN_BIN" "$PLUGIN_DIR/hooks/massa-ai-hook"
+    vecho "  + hooks/massa-ai-hook → $CLAUDE_PLUGIN_BIN"
+  else
+    echo "  ⚠ Warning: no massa-ai-hook binary found" >&2
+    echo "    Hooks will not fire until the binary is available." >&2
+  fi
 
-# Merge hooks.json (array-append, backup, idempotent)
-vecho ""
-vecho "Merging hooks into $HOOKS_JSON..."
-merge_hooks_json "$HOOKS_JSON" "install"
-vecho "  + 7 massa-ai hook events wired (array-append, user hooks preserved)"
+  # Merge hooks.json (array-append, backup, idempotent)
+  vecho ""
+  vecho "Merging hooks into $HOOKS_JSON..."
+  merge_hooks_json "$HOOKS_JSON" "install"
+  vecho "  + 7 massa-ai hook events wired (array-append, user hooks preserved)"
+fi
 
 # ── MCP registration (delegated) ─────────────────────────────────────────────
 # scripts/install-agents.sh is the single writer of host MCP config. It writes
@@ -552,10 +682,17 @@ fi
 
 # Summary line in quiet mode
 if [ "${MASSA_AI_VERBOSE:-0}" != "1" ]; then
-  ok "cursor plugin installed (${skill_count} skills, ${specialist_count} specialists, 7 hooks)"
+  if [[ "$IS_BRIDGE" -eq 1 ]]; then
+    ok "cursor plugin: using the Claude bridge (${specialist_count} specialists) — hooks delivered by the bridge, not installed locally"
+  else
+    ok "cursor plugin installed (${skill_count} skills, ${specialist_count} specialists, 7 hooks)"
+  fi
 else
   vecho ""
   vecho "Done. Restart Cursor to pick up the plugin."
+  if [[ "$IS_BRIDGE" -eq 1 ]]; then
+    vecho "💡 massa-ai loads via the Claude bridge (~/.claude) — local plugin/hook install skipped."
+  fi
   vecho "💡 MCP is registered in ~/.cursor/mcp.json by scripts/install-agents.sh (single writer)."
 fi
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massa-ai/cursor-plugin",
-  "version": "1.29.0",
+  "version": "1.31.0",
   "description": "massa-ai plugin for Cursor — semantic code search, memory, and context compression",
   "files": [
     "agents",

package/skills/massa-ai/SKILL.md

@@ -46,7 +46,7 @@ Before reading any massa-ai file:
   Never pass `workflowSessionId` in that field. Use `synapse_task_begin`/`synapse_task_end`
   for task envelopes and `synapse_prefetch` to warm the buffer on file open.
 - Prefer the shared v2 retrieval order; fall back gracefully if the massa-ai
-  server or Synapse is unavailable. The full tool surface includes 52 tools
+  server or Synapse is unavailable. The full tool surface includes 54 tools
   (see `references/mcp-tools.md`): indexing, search, symbol graph
   (`trace_path`, `impact_analysis`, `get_architecture`), memory CRUD
   (`remember`, `recall`, `memory_update`, `memory_delete`), checkpoints
@@ -166,6 +166,8 @@ current context already contains it.
 | `commit` | draft or create safe Conventional Commits with Jira branch prefixes and audit report exclusions | `workflows/commit.md` |
 | `the-fool` | direct challenge, red-team, pre-mortem, evidence audit | `workflows/the-fool.md` |
 | `judge-with-debate` | standalone multi-judge debate evaluation of user-supplied artifacts | `workflows/judge-with-debate.md` |
+| `pr-review` | review a hosted GitHub PR / GitLab MR and post findings via `gh`/`glab` | `workflows/pr-review.md` |
+| `discovery` | product brainstorming / problem-space thinking partner | `workflows/discovery.md` |
 | `to-prd` | turn the current conversation into a PRD without a new interview | `workflows/to-prd.md` |
 | `skill-architect` | design and build a new skill through structured conversation | `workflows/skill-architect.md` |
 | `furps-refinement` | FURPS+ refinement of a PRD and/or ADR before implementation, with The Fool pre-validation and DoR coverage | `workflows/refinement/furps-refinement.md` |
@@ -181,8 +183,8 @@ Deterministic routing precedence, first match wins:
 
 1. **Explicit route:** user names a massa-ai workflow, report family, saved finding type, or asks for a direct challenge.
 2. **Requested artifact:** ADR, RFC, TDD, Jira ticket, commit, session guide, audit report, implementation audit report, mobile Figma report, FURPS refinement report, PRD synthesized from the current conversation -> `to-prd` (explicit request only; refining an existing PRD stays `furps-refinement`), or new SKILL.md / skill design -> `skill-architect`.
-3. **Target type:** broken behavior/error -> `debug`; saved audit finding -> matching `*-fix`; implementation scope review -> `implementation-audit`; Maestro E2E/device automation target -> `maestro`, `maestro-audit`, or child-only `maestro-fix` before generic tests workflows; security/privacy/auth finding -> security workflow; tests/flakes/coverage finding -> tests workflow; supplied Figma/screenshot mobile UI design -> `design`; mobile Figma compare/audit -> `mobile-figma-audit`; saved `MFM-*` findings -> `mobile-figma-fix`.
-4. **Primary verb:** create/add/implement -> `feature` unless the concrete target is new Maestro flow work, which routes to `maestro`; restructure without behavior change -> `refactor`; inspect/understand only -> `exploration`; record selected decision -> `adr`; compare open options -> `rfc`; design settled implementation -> `tdd`; refine/quality-check an existing PRD or ADR document (not implementation auditing) -> `furps-refinement`.
+3. **Target type:** broken behavior/error -> `debug`; hosted PR/MR reference (number or URL) to review with posted findings -> `pr-review` (local working diff stays with audit routes); saved audit finding -> matching `*-fix`; implementation scope review -> `implementation-audit`; Maestro E2E/device automation target -> `maestro`, `maestro-audit`, or child-only `maestro-fix` before generic tests workflows; security/privacy/auth finding -> security workflow; tests/flakes/coverage finding -> tests workflow; supplied Figma/screenshot mobile UI design -> `design`; mobile Figma compare/audit -> `mobile-figma-audit`; saved `MFM-*` findings -> `mobile-figma-fix`.
+4. **Primary verb:** create/add/implement -> `feature` unless the concrete target is new Maestro flow work, which routes to `maestro`; restructure without behavior change -> `refactor`; inspect/understand only -> `exploration`; brainstorm/explore a product problem, idea, or direction with no concrete code target -> `discovery`; record selected decision -> `adr`; compare open options -> `rfc`; design settled implementation -> `tdd`; refine/quality-check an existing PRD or ADR document (not implementation auditing) -> `furps-refinement`.
 5. **Risk domain escalation:** migrations, irreversible operations, auth/privacy, cross-service contracts, public compatibility, or work over 10 files routes to `spec-driven` unless the user explicitly requests a narrower workflow and accepts the containment.
 6. **General fallback:** use `general` only after a one-line General fallback preflight names the specialized workflow considered, rejected reason, and why fallback does not change verification or mutation behavior.
 

package/skills/massa-ai/references/installation.md

@@ -100,9 +100,9 @@ behavior through MCP declarations and non-destructive runtime probes.
 - Preferred: `bash scripts/install-agents.sh --agent <host>` — the single writer
   of host MCP config (Claude Code, Claude Desktop, Codex, Cursor, OpenCode).
   Plugin installers call it; nothing else writes an MCP entry.
-- OpenCode: local MCP package via `bunx @massa-ai/mcp-client`, or
-  `@massa-ai/opencode-plugin` (which registers tools in-process, so
-  `install-agents.sh` skips the MCP entry when that plugin is present).
+- OpenCode: `@massa-ai/opencode-plugin` is hooks-only (AD-017) and delegates
+  MCP registration to `install-agents.sh --agent opencode` on every install,
+  same as every other host — no separate MCP step needed.
 - VS Code/Antigravity: `.vscode/mcp.json` or `./scripts/setup-vscode.sh`.
 - Docker: run the `mcp` service through `docker compose run --rm -i mcp`.
 

package/skills/massa-ai/references/mcp-tools.md

@@ -1,4 +1,4 @@
-# massa-ai Tool Contracts (52 Tools)
+# massa-ai Tool Contracts (54 Tools)
 
 Load when exact MCP schemas, REST fallbacks, response modes, or
 polling rules are needed. Prefer the active tool declaration over copied
@@ -138,6 +138,8 @@ depends on exact content.
 |---|---|---|
 | `rename_project` | Rename a project identity transactionally | Req: `sourceProjectId`, `targetProjectId`. Default `dryRun=true`; apply with `dryRun=false` + `operationId` + `expectedPlanHash`. Administrative, not workflow-recurring. |
 | `merge_projects` | Merge one project identity into another | Req: `sourceProjectId`, `targetProjectId`. Same dryRun/planHash contract as `rename_project`. Administrative, not workflow-recurring. |
+| `profile_list` | List shipped model profiles and each detected host's current profile + bundle version | No required args; optional `host` to scope to one. Offline — reads on-disk variant directories only, never the registry. |
+| `profile_set` | Switch the installed massa-ai agents to a registry model profile | Req: `profile`. Optional `host` (default: every detected, supported host), `dryRun` (default `false`) to preview without writing. Local trust model — mutates installed agent files on the machine the MCP server runs on; a host session restart is required to take effect. |
 
 ## Retrieval Order
 

package/skills/massa-ai/workflows/discovery.md

@@ -0,0 +1,236 @@
+---
+name: discovery
+description: "Product discovery and brainstorming workflow — act as a sharp product thinking partner to explore problem spaces, generate and stress-test ideas, and spar on strategy before anything is spec-ready, ending with a mandatory offer to synthesize the conversation into a PRD via the to-prd workflow. Use when the user wants to brainstorm a product problem, idea, opportunity, or direction with no concrete code target. Do NOT use for codebase understanding (exploration), converting a finished discussion into a PRD (to-prd), or any implementation work."
+license: Apache-2.0
+metadata:
+  version: "1.0.0"
+---
+
+### Discovery (Product Brainstorming)
+
+Attribution: adapted from the `product-brainstorming` skill in
+`anthropics/knowledge-work-plugins` (Apache-2.0). massa-ai session/memory
+binding, router integration, and the to-prd handoff are additions.
+
+Act as a sharp product thinking partner — the experienced PM (Product
+Manager) or design lead who challenges assumptions, asks hard questions, and
+pushes ideas further before anyone converges too early. The job is not to
+generate deliverables; it is to think alongside the user: be opinionated,
+push back, bring unexpected angles, and help them reach ideas they would not
+have reached alone.
+
+This is a read-only conversation workflow: it never mutates the repository
+and writes no `.specs/` artifacts. Its only outputs are the conversation
+itself, durable memories at Capture, and — on explicit acceptance — a routed
+handoff to `to-prd`.
+
+Load `references/project-context.md` (intake sweep) before the first
+substantive read when the conversation touches an existing product or
+codebase; product context grounds the brainstorm in what exists today.
+
+## Session And Memory
+
+- `workflowSessionId`: `discovery-<entity>` (e.g., `discovery-onboarding-dropoff`),
+  stable for the whole conversation.
+- Start with a budgeted `recall` (limit ≤ 3, minImportance ≥ 0.7, types
+  `critical`/`decision`/`pattern`): prior product decisions, rejected
+  directions, and known constraints for this problem area. Rejected
+  directions are recalled so they are not re-litigated — but a rejected idea
+  may be re-opened deliberately when the user brings new evidence.
+- If the massa-ai server is unavailable, continue without recall and say so
+  once; discovery degrades gracefully — the conversation is the primary
+  medium, not the memory store.
+
+## Brainstorming Modes
+
+Identify which mode fits the conversation and adapt; shift modes as the
+conversation evolves.
+
+### Problem Exploration
+
+Use when the user has a problem area but has not defined what to solve.
+Understand the problem space before any solutions: ask who has this problem
+and what they do about it today; map who is involved, what triggers it, and
+the consequences of not solving it; distinguish symptoms from root causes —
+keep asking "why" until something structural appears; surface adjacent
+problems; ask how the problem varies across user segments. Strong questions:
+"What happens if we do nothing — who suffers and how?", "Who has solved a
+version of this in a different context?", "Is this a problem of awareness,
+ability, or motivation?"
+
+### Solution Ideation
+
+Use when the problem is well-defined and the goal is divergent thinking —
+quantity over quality. Generate at least 5–7 distinct approaches before
+evaluating any; vary them along scope (tweak vs big bet), approach (product
+vs process vs policy), and timing (quick win vs long-term); include one
+"do the opposite" option and one that removes something instead of adding.
+Techniques: constraint removal (no technical/budget/political constraints,
+then work back to feasible), analogies from other industries, inversion,
+decomposition into subproblems, and user hat-switching (power user, brand
+new user, admin, someone who hates the product).
+
+### Assumption Testing
+
+Use when an idea exists and needs stress-testing before investment. List
+every assumption the idea depends on — stated and unstated — across user,
+problem, solution, business, feasibility, and adoption categories. For each:
+how confident are we, on what evidence, and what would disprove it? Identify
+the riskiest assumption — the one that kills the idea if wrong — and the
+cheapest way to test it before building anything. Argue the strongest
+possible case against the idea.
+
+### Strategy Exploration
+
+Use for direction, positioning, or big bets rather than a specific feature.
+Map the possible strategic moves, not just the obvious one; think in bets
+(what are we betting on, the odds, the payoff); consider second-order
+effects ("if we do X, what does that enable or foreclose?"); bring in
+competitive response; think in timeframes (3 months vs 12 months vs 3
+years).
+
+## Frameworks As Tools
+
+Pull a framework in when it moves the conversation forward — never dump
+frameworks or force the conversation through them as a checklist.
+
+- **How Might We (HMW)**: "How might we [outcome] for [user] without
+  [constraint]?" Aim between too broad ("improve onboarding") and too narrow
+  (a disguised solution); generate 5–10 reframings — each opens a different
+  solution space.
+- **Jobs-to-be-Done (JTBD)**: "When [situation], I want to [motivation] so I
+  can [outcome]." The job is stable while solutions change; emotional and
+  social jobs often outweigh functional ones. Ask "what did they fire to
+  hire this?" — it reveals the real competitive set.
+- **Opportunity Solution Tree**: outcome → opportunities (evidence-backed
+  user needs) → multiple solutions per opportunity → cheapest experiment per
+  solution. One solution per opportunity means exploration stopped too
+  early; the tree is a living artifact.
+- **First Principles Decomposition**: state the assumption, break it into
+  fundamental components, ask of each "law of physics or convention?", then
+  rebuild from only the fundamentals. Use when the team is stuck in
+  incremental thinking.
+- **SCAMPER**: seven lenses on an existing product — Substitute, Combine,
+  Adapt, Modify (10x bigger/smaller/faster), Put to other use, Eliminate
+  ("would anyone notice?"), Reverse (flip the sequence or the default).
+- **OODA Loop** (Observe–Orient–Decide–Act): a decision-tempo framework —
+  gather raw signals wide, make sense of them while challenging your own
+  orientation, choose a proportional reversible bet, act, and cycle. Use
+  when the conversation over-deliberates or keeps circling: orient with what
+  exists, decide, and let the next observation correct course.
+- **Reverse Brainstorming**: invert the problem ("how could we make this
+  worse?"), generate freely — people find flaws more easily than fixes —
+  then reverse each worsening idea into the seed of a solution.
+
+## Session Rhythm
+
+A good session opens up before it narrows down. Move through five stages;
+name the stage transition when it helps the user follow.
+
+1. **Frame** — Set boundaries before generating ideas: what are we
+   exploring, why now, what is already known (research, data, feedback),
+   what are the constraints, and what would a great outcome from this
+   session look like? A poorly framed brainstorm produces ideas that connect
+   to nothing.
+2. **Diverge** — Generate many ideas without judgment; build on ideas rather
+   than shooting them down; follow tangents; push past the first 3–5 obvious
+   ideas; use the frameworks above to open new angles. Do not evaluate
+   feasibility here — that kills divergent thinking.
+3. **Provoke** — The sparring-partner stage: "What is the strongest argument
+   against this?", "Who would hate this and why?", "What are we not
+   seeing?", "What if the opposite were true?", "What is the 10x more
+   ambitious version?"
+4. **Converge** — Group ideas into themes; evaluate against user impact,
+   feasibility, strategic alignment, and evidence strength; identify the top
+   2–3 directions; for each, name the biggest unknown and the cheapest way
+   to resolve it. If one idea excites the user, explore it even if risky —
+   the brainstorm is not the decision.
+5. **Capture** — Mandatory; a brainstorm with no capture never happened.
+   Record in conversation: the key ideas and why they are interesting, the
+   assumptions to test, the questions to research, the suggested next steps,
+   and what was explicitly set aside (interesting, but not now).
+
+At Capture, persist the durable subset via `remember`: chosen directions
+with their why and rejected directions with reasons as `decision`, reusable
+framings or cross-session insights as `pattern` — tagged
+`project:<projectId>`, `session:discovery-<entity>`, `workflow:discovery`,
+`entity:<name>`, and a memory-tier tag. Persist only what transcends the
+session; never fabricate memories to satisfy process. If the server is
+unavailable, the capture summary in conversation is the record.
+
+## PRD Handoff (to-prd)
+
+End every Capture with an explicit offer — this step is mandatory, the PRD
+is not:
+
+> "Want me to turn this into a PRD (Product Requirements Document)? I'd
+> synthesize this conversation through the `to-prd` workflow — no new
+> interview."
+
+- **Accepted** → route to `workflows/to-prd.md`. The user's acceptance is
+  the explicit request `to-prd`'s routing requires. Carry the current
+  conversation context — Capture's output (chosen directions, assumptions,
+  set-asides) feeds the PRD's problem statement, decisions, and out-of-scope
+  sections directly; `to-prd` does not re-interview.
+- **Declined** → the capture summary stays in conversation and the durable
+  memories from Capture remain the only persistence. Offer nothing else.
+
+If discovery converged on nothing PRD-shaped (pure problem exploration, or
+the session identified research as the next step), say so instead of
+offering an empty PRD — name what research or evidence would make the next
+discovery session converge.
+
+## Thinking-Partner Conduct
+
+Do:
+
+- **Be opinionated.** "I think approach B is stronger because…" beats a
+  pro/con list.
+- **Challenge constructively.** "That assumes X — are we confident?", not
+  "that will not work."
+- **Bring unexpected angles** — cross-industry analogies, counterexamples,
+  edge cases the user has not considered.
+- **Match energy.** When the user is excited about an idea, explore it with
+  them before poking holes.
+- **Ask the next question.** When the user finishes a thought, push
+  further: "and then what happens?"
+- **Name the pattern.** When a common PM trap appears (solutioning too
+  early, scope creep, feature-parity thinking), name it directly.
+
+Do not:
+
+- Dump frameworks or work through them as a checklist.
+- Generate a list and hand it over — brainstorming is a conversation, not a
+  deliverable.
+- Agree with everything — a thinking partner who only validates is not one.
+- Evaluate feasibility during divergence.
+- Anchor on the first idea — when the user leads with a solution,
+  acknowledge it, then ask what else could solve the problem.
+- Confuse brainstorming with decision-making — the brainstorm generates
+  options; the decision comes later with more data.
+
+## Anti-Patterns To Catch
+
+- **Solutioning before framing**: "we should build X" before the problem is
+  defined — slow down, ask what user problem X solves and how we know.
+- **The feature-parity trap**: "competitor has X, so we need X" is copying,
+  not brainstorming — ask what user need X serves and whether there is a
+  better way to serve it.
+- **Anchoring on constraints**: "we can't because of Y" during divergence —
+  set constraints aside, explore freely, then price feasibility.
+- **The one-idea brainstorm**: a solution presented as a brainstorm —
+  acknowledge it, then push for three alternatives.
+- **Analysis paralysis**: long divergence with no convergence — prompt "if
+  you had to pick one direction right now, which and why?"
+- **Brainstorming when you should be researching**: when the session circles
+  because nobody knows the answer, stop and name the research needed — some
+  questions need data, not ideation.
+
+## Completion
+
+Discovery completes at Capture plus the PRD offer. Before claiming the
+session complete, apply `references/evidence-gate.md`: the evidence here is
+the capture summary (ideas, assumptions, next steps, set-asides), the memory
+outcome (what was persisted or why persistence was skipped), and the
+recorded PRD-offer disposition (accepted → to-prd, declined, or
+not-PRD-shaped with the named research gap).

package/skills/massa-ai/workflows/pr-review.md

@@ -0,0 +1,246 @@
+---
+name: pr-review
+description: "Explicit-route workflow to review a hosted GitHub Pull Request or GitLab Merge Request across six dimensions — security, requirements, test coverage, architecture, regression, performance — using massa-ai roster subagents, then post inline comments plus one consolidated summary through the host CLI (gh or glab). Use when the user says review PR 128, review this MR, or code review this pull request. Do NOT use for local working-diff review (audit workflows), creating PRs, replying to review comments, or fixing CI."
+license: CC-BY-4.0
+metadata:
+  version: "1.0.0"
+---
+
+Attribution: adapted from the `pr-review` skill by github.com/augusto-dmh
+(TLC skills catalog), licensed CC-BY-4.0. Host abstraction (GitLab support),
+massa-ai roster dispatches, memory/index/`.specs/` integration, and channel
+discipline are this repository's additions; repository contracts win on any
+conflict with the base.
+
+### PR Review
+
+Use when the user explicitly asks to review a hosted PR (Pull Request, GitHub) or
+MR (Merge Request, GitLab) — "review PR 128", "review this MR", "check pull request
+42". Explicit route only: never auto-trigger during coding. Local working-tree diff
+review stays with the audit workflows and `massa-ai-reviewer`; this workflow exists
+to **post findings back to the host**.
+
+Load `references/project-context.md` (intake sweep) before the first substantive
+read. Resolve `projectId` and `workflowSessionId` = `pr-review-<number>` per the
+Core Contract, and run a budgeted `recall` (limit ≤ 3, minImportance ≥ 0.7) for
+prior review conventions and known regression patterns.
+
+## Execution Contract (non-negotiable)
+
+1. **Orchestration-only.** The main agent never authors a review finding. It
+   gathers context, dispatches the review subagents, dedupes their returned
+   findings, and posts. Doing the review inline — even for a small diff — is a
+   failure of this workflow.
+2. **Comment-only, never destructive.** Forbidden in every circumstance:
+   `gh pr review --approve`, `gh pr review --request-changes`, `gh pr merge`,
+   `glab mr approve`, `glab mr revoke`, `glab mr merge`, and the raw
+   `POST …/approve` / `POST …/unapprove` endpoints. Posting notes or discussions
+   never approves — keep it that way. Never modify repository files.
+3. **Subagents never touch the host.** Review subagents are read-only and
+   host-agnostic: they receive the diff and context in their packet and return
+   findings in their reply block. Only the orchestrator executes `gh`/`glab`.
+4. **File-body posting.** Every multiline body is written to a temp file and
+   posted with the host's file-body mechanism (`--body-file` / `-F body=@file`).
+   Inlining a multiline `--body` string is the protocol's most common failure.
+5. **Ask, never guess.** No PR/MR reference in the request → ask for it. Host CLI
+   cannot resolve the reference → stop and surface the CLI error output.
+
+## Step 1 — Initialize
+
+### 1a. Resolve the host
+
+Order: explicit user statement > CLI probe > git remote host. Probe with
+`gh repo view` / `glab repo view` **exit status** (glab's no-remote error text is
+not a documented stable string — never match on the message). Both probes fail →
+stop and report which CLI is missing or unauthenticated (`gh auth status` /
+`glab auth status`). Both succeed (mirrored repo) → ask the user which host to
+review on; a posted comment is outward-facing. Record `HOST ∈ {github, gitlab}`.
+
+### 1b. PR/MR context (via the command map below)
+
+Resolve repository identity, then fetch: title + body/description + source
+branch, the head anchor (`{SHA}` on GitHub; the full `diff_refs`
+`{base_sha, head_sha, start_sha}` triple on GitLab), the full diff, and the
+changed-file list. Then load the existing inline-comment inventory as
+`{id, path, line, body}` records — **page to completion** (GitLab discussions
+default to 20 per page; pin `per_page=100` and loop) — used for dedupe,
+`[RESOLVED]` replies, and threading.
+
+### 1c. Project discovery (the adaptive spine)
+
+Probe the repository once and record a DISCOVERY MAP passed verbatim to every
+subagent. Prefer evidence the project states over guesses; mark absences `none`.
+
+```
+TEST:          <command CI actually runs> | globs: <...> | unit vs e2e: <split | none>
+REQS:          tracker=<GH #42 | Jira KEY-123 | GitLab #42 | none> ; specs=<paths | none>
+CONVENTIONS:   <doc/skill paths that state rules | none-found>
+REVIEW_SKILLS: <project-local review skill paths | none>
+INDEX:         <massa-ai retrieval state: fresh | stale | unavailable — CLI fallback>
+```
+
+- **TEST**: the CI workflow config is authoritative; manifests are fallback.
+- **REQS Track A (tracker)**: ticket key from branch name or PR/MR body —
+  `gh issue view {N} --json title,body` / `glab issue view {N} --output json`;
+  Jira only through an already-configured Atlassian MCP (never invent a host).
+- **REQS Track B (in-repo)**: `.specs/project/FEATURES.json` and
+  `.specs/features/<slug>/{spec,tasks}.md` acceptance criteria matched by branch,
+  ticket, or feature stem; then `docs/`, ADR/RFC directories, `*-spec.md`.
+- **CONVENTIONS/REVIEW_SKILLS**: `CONTRIBUTING*`, `ARCHITECTURE*`, `AGENTS.md`,
+  `CLAUDE.md`, `docs/**` convention files, `.claude/skills/`, `.cursor/skills/`.
+- **INDEX**: `list_projects` freshness first; when fresh, `project_map` or
+  `get_architecture` for orientation and `impact_analysis` over the PR/MR diff
+  for centrality-ranked hotspots; `search` under `references/synapse-policy.md`
+  when two or more related searches are planned. Index results are leads until
+  confirmed against the diff — never evidence on their own. Server or index
+  unavailable → record it and continue per `references/graceful-degradation.md`.
+
+## Host Command Map
+
+The orchestrator reads every host operation from this table. `{REPO}`/`{PR}` are
+GitHub coordinates; `{MR}` is the GitLab IID; `:id` is glab's project placeholder
+(resolved from the current repo's remote — 8 placeholders are documented:
+`:branch :fullpath :group :id :namespace :repo :user :username`).
+
+| Operation | GitHub (`gh`) | GitLab (`glab`) |
+| --- | --- | --- |
+| Identity | `gh repo view --json nameWithOwner -q .nameWithOwner` → `{REPO}` | `glab repo view --output json --jq .path_with_namespace` (project id: `--jq .id`) |
+| Metadata | `gh pr view {PR} --json title,body,headRefName,headRefOid` → `{SHA}` | `glab mr view {MR} --output json` → `title`, `description`, `source_branch`, `sha`, `diff_refs.{base_sha,head_sha,start_sha}` |
+| Full diff | `gh pr diff {PR}` | `glab mr diff {MR} --raw` |
+| Changed files | `gh pr diff {PR} --name-only` | `glab api "projects/:id/merge_requests/{MR}/diffs?per_page=100&page={N}"` → `new_path`/`old_path`, page to completion |
+| Existing comments | `gh api repos/{REPO}/pulls/{PR}/comments` | `glab api "projects/:id/merge_requests/{MR}/discussions?per_page=100&page={N}"` → note `id`, `position.new_path`, `position.new_line`, `body` |
+| Inline comment | `gh api repos/{REPO}/pulls/{PR}/comments -F body=@body.md -f commit_id={SHA} -f path={path} -F line={N} -f side=RIGHT` | `glab api --method POST "projects/:id/merge_requests/{MR}/discussions" -F body=@body.md -f "position[position_type]=text" -f "position[base_sha]={base}" -f "position[head_sha]={head}" -f "position[start_sha]={start}" -f "position[new_path]={path}" -f "position[old_path]={old}" -F "position[new_line]={N}"` |
+| Thread reply | `gh api repos/{REPO}/pulls/{PR}/comments/{COMMENT_ID}/replies -F body=@body.md` | `glab api --method POST "projects/:id/merge_requests/{MR}/discussions/{DISCUSSION_ID}/notes" -F body=@body.md` |
+| Summary | `gh pr review {PR} --comment --body-file summary.md` | `glab api --method POST "projects/:id/merge_requests/{MR}/notes" -F body=@summary.md` |
+
+Anchoring and flag semantics (load-bearing, verified against official docs):
+
+- **GitHub `line={N}`** is the 1-based line number in the **head file** on side
+  `RIGHT` — count from the hunk header across added and context lines. A
+  diff-relative offset returns 422 or lands on the wrong line.
+- **GitLab added line** ⇒ send `position[new_line]` and **omit** `old_line`
+  (removed line: the reverse; context line: both). `new_path` **and** `old_path`
+  are both required for `position_type=text` — take `old_path` from the `/diffs`
+  inventory, never assume it equals `new_path` (renames break that).
+- **`-F`/`--field` expands `@file` and infers types on both CLIs; `-f`/
+  `--raw-field` does neither** — `-f body=@body.md` posts the literal string
+  `@body.md`. Use `-F` for bodies and line numbers, `-f` for plain strings.
+  glab's `-F` also switches the default method to POST.
+- `glab mr note create` has experimental inline flags (`--file`, `--line`,
+  `--reply`) — GitLab marks them "might be unstable or removed at any time"; the
+  stable `glab api` paths above are the contract. A plain summary may also use
+  `glab mr note create {MR} < summary.md` (body from stdin).
+
+## Step 2 — Dispatch the review (two waves)
+
+Six dimensions run as read-only roster dispatches under
+`references/agent-orchestration.md` (wave cap 4 → wave 1 = rows 1–4, wave 2 =
+rows 5–6). Each packet carries: the dimension row below, the DISCOVERY MAP, the
+PR/MR intent (title/body/branch), the existing-comment inventory, the diff
+trimmed to hunks relevant to the dimension per `references/context-firewall.md`,
+the severity labels, and the reply contract.
+
+| # | Dimension | Agent | Packet delta (lens / scope) | Marker `{type}` |
+| --- | --- | --- | --- | --- |
+| 1 | Security | `massa-ai-audit-specialist` | `lens: security` — secrets, authn/authz on new endpoints, injection, unsafe deserialization, PII in logs, permissive CORS, leaking payload fields | `security` |
+| 2 | Requirements & DoD (Definition of Done) | `massa-ai-audit-specialist` | `lens: requirements` — score merged Track A + Track B criteria against the diff, evidence-or-zero: ✅ implemented (`path:line`) / 🟡 partial / ❌ missing; no source ⇒ report "requirements verification skipped" | `requirements` |
+| 3 | Architecture & conventions | `massa-ai-audit-specialist` | `lens: architecture` — extract every explicit rule from the profile's CONVENTIONS/REVIEW_SKILLS docs into a numbered matrix, grade each changed file PASS/VIOLATION/N/A; no docs ⇒ minimal generic boundary sweep, stated | `architecture` |
+| 4 | Performance | `massa-ai-audit-specialist` | `lens: performance` — only issues clearly visible in the diff: N+1 queries, unbounded fetches, per-row lazy I/O, sequential awaits of independent calls, loop-invariant recomputation, unbatched writes | `performance` |
+| 5 | Test coverage | `massa-ai-audit-specialist` | `lens: performance`, scope: test coverage (the charter's lens set has no `tests` lens; `tests-audit.md` precedent) — new/changed behavior with no test, wrong level (unit vs integration), placement/naming vs profile TEST row, missing negative case, assertions that exercise but never assert | `tests` |
+| 6 | Regression & hallucination | `massa-ai-reviewer` | diff review — unrelated deletions, references to symbols absent from the repo, wrong signature/arity, duplicated existing logic, weakened error handling or assertions, leftover TODO/stub, dead code | `regression` |
+
+Consolidation check (≥ 5 subagents): recorded in the feature design — rows 4 and 5
+share only the lens label, not a knowledge domain; they stay separate dispatches.
+
+> **Dispatch: `massa-ai-audit-specialist`** (role: `audit-specialist`) — charter `skills/agents/audit-specialist/SKILL.md`
+> - trigger: pr-review Step 2, dimension rows 1–5 (one dispatch per row)
+> - scope: the PR/MR diff and surrounding context for one dimension row; never the whole repository
+> - permissions: read-only; no host CLI calls, no posting
+> - inputs: exact `projectId`, parent `workflowSessionId`, dimension row (lens + scope), DISCOVERY MAP, PR/MR intent, trimmed diff, existing-comment inventory, severity labels, reply contract
+> - sensors: second-pass sweep — re-read the full trimmed diff, list every file/hunk not commented on, and state per file why it is clean for this dimension before returning
+> - output: structured reply block — findings rows `{path, head-line, severity, marker type, title, body ≤ 6 lines, recommendation}` + exactly one positive highlight + files-swept-clean list; when uncertain a finding is real, withhold it (the source protocol's high-confidence bar, applied qualitatively)
+> - firewall: raw diff/log/search output summarized, never returned raw
+> - memory: suggest-only; the main agent persists durable outcomes
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
+> **Dispatch: `massa-ai-reviewer`** (role: `reviewer`) — charter `skills/agents/reviewer/SKILL.md`
+> - trigger: pr-review Step 2, dimension row 6 (regression & hallucination)
+> - scope: the full PR/MR diff against the repository's real symbol surface
+> - permissions: read-only; no host CLI calls, no posting
+> - inputs: exact `projectId`, parent `workflowSessionId`, dimension row 6, DISCOVERY MAP, PR/MR intent, full diff, existing-comment inventory, severity labels, reply contract
+> - sensors: verify referenced symbols exist (`search_definitions`/`get_references` when INDEX is fresh, else grep); second-pass sweep as above
+> - output: structured reply block — findings rows tagged `{unrelated-deletion | phantom-reference | wrong-signature | duplicate | weakened-check | dead-code}` + one positive highlight + files-swept-clean list; withhold uncertain findings
+> - firewall: raw diff/log/search output summarized, never returned raw
+> - memory: suggest-only; the main agent persists durable outcomes
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
+Severity labels (all dimensions): 🚨 Critical (bugs/logic errors that will fail) ·
+🔒 Security · ⚡ Performance · ⚠️ Warning (smells/maintainability) ·
+💡 Suggestion. A failed or unavailable dispatch is reported in the summary as a
+skipped dimension with its reason — never silently dropped.
+
+## Step 3 — Post inline findings (orchestrator only)
+
+For every returned finding, in order:
+
+1. **Dedupe**: drop it when an existing comment sits within ±3 lines of the same
+   path/line (inventory from 1b) or another dimension already produced the same
+   `{path, line}` finding (keep the higher severity; note both markers).
+2. **Resolve check**: when an existing comment's issue is fixed by this diff,
+   reply `[RESOLVED] This appears resolved by the recent changes.` on that thread
+   via the reply command (GitHub: the comment's `id`; GitLab: its
+   `discussion_id`).
+3. **Anchor**: only added (`+`) diff lines on the head revision, per the
+   anchoring semantics above. A finding with no `+` line to stand on goes to the
+   summary instead.
+4. **Body**: temp file, starting with the invisible marker
+   `<!-- pr-review:{type} -->`, then `[severity emoji] — [short title]`, the
+   evidence-grounded body, and a `**Recommendation:**` line. No AI/assistant/
+   tool attribution anywhere — write as a reviewer. Specific, actionable,
+   collegial; always explain why.
+5. **Post** with the inline-comment command for `HOST`.
+
+## Step 4 — Consolidated summary
+
+Assemble from the reply blocks (no extra subagent) and post one summary via the
+summary command:
+
+```markdown
+## 📋 PR Review Summary
+
+| | |
+|---|---|
+| **Host / target** | {github PR #N | gitlab MR !N} @ {head sha} |
+| **Dimensions** | 6 (Security · Requirements & DoD · Tests · Architecture · Regression · Performance) |
+| **Detected runner** | {TEST row | none found} |
+| **Requirements source** | {tracker / spec paths / none} |
+| **Project refs loaded** | {CONVENTIONS + REVIEW_SKILLS rows} |
+| **Findings** | {N} across {M} files |
+
+### 🔒 Security ({N}) / 🚨 Critical ({N}) / ⚡ Performance ({N}) / ⚠️ Warnings ({N}) / 💡 Suggestions ({N})
+- [`path/file:L42`] Finding title — one line each, grouped by severity
+
+### 📋 Requirements
+{✅/🟡/❌ rows from dimension 2, with `path:line` evidence}
+
+### 🔍 Files with no findings
+- `path` — swept clean by {dimensions} (omit section when every logic file got a comment; config/lock/declaration files excluded)
+
+### ✅ Highlights
+- one per dimension
+
+> See inline comments for details. {Skipped dimensions/sensors with reasons, if any.}
+```
+
+Zero findings overall → post "✅ No issues found across all review dimensions."
+with the metadata table intact.
+
+## Completion
+
+- Emit Conversation Feedback status updates at wave boundaries when that policy
+  is active; expand every abbreviation on first use in user-facing output.
+- Persist durable outcomes only (recurring review pattern, confirmed project
+  convention) with the required memory tags; do not fabricate memories.
+- Close with `references/evidence-gate.md`: counts posted vs deduped vs withheld,
+  skipped dimensions/sensors with reasons, and the summary URL/reference.
+<!-- validator anchors: comment-only | added (+) diff lines | page to completion | two waves -->