@massa-ai/cursor-plugin 1.53.0 → 1.55.0

package/install.sh

@@ -11,15 +11,38 @@
 # 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.
+# LOCAL IS THE DEFAULT ROUTE. The Claude bridge is opt-in (--prefer-bridge).
+#
+# Cursor can bridge the Claude marketplace registry from ~/.claude — observed
+# live in Cursor 3.14's "Cursor Plugins" exthost log on 2026-08-05
+# ("loadClaudePlugin massa-ai@massa-ai"). This installer used to PREFER that
+# bridge at user scope: on detection it deleted its own plugin directory and
+# stripped its hook wiring, on the premise that the bridge loads the whole
+# plugin.
+#
+# Measured on Cursor 3.16.17 (2026-08-17), with massa-ai listed and
+# `enabledPlugins` true in ~/.claude, that premise is at best half true:
+#
+#   hooks    → fire in Cursor
+#   plugin   → absent from the Cursor UI
+#   commands → absent (all 46 workflow commands)
+#
+# So bridge-preference silently withheld a working local install, and the user
+# lost every workflow command with nothing replacing them. Detection reads
+# ~/.claude, which is a fact about CLAUDE's files — never proof that Cursor
+# loaded anything from them — and nothing here can observe the difference.
+#
+# The default therefore installs everything locally. --prefer-bridge (or
+# MASSA_AI_CURSOR_PREFER_BRIDGE=1) restores the old behaviour for anyone whose
+# bridge does deliver hooks.
+#
+# AD-017 TRADE-OFF, STATED PLAINLY: if the bridge IS delivering hooks and you
+# take the default, both sources are live and every hook fires TWICE. The
+# install warns when it detects that combination. Choose --prefer-bridge, or
+# disable massa-ai in ~/.claude/settings.json, to keep exactly one source.
+#
+# Project-scope installs never consult the bridge — ~/.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,
@@ -29,6 +52,13 @@
 #   apps/cursor-plugin/install.sh             # install at user scope (~/.cursor)
 #   apps/cursor-plugin/install.sh --user      #   (same)
 #   apps/cursor-plugin/install.sh --project  # install at project scope (./.cursor)
+#   apps/cursor-plugin/install.sh --prefer-bridge # leave hook wiring to the
+#                                             # Claude bridge instead of
+#                                             # installing it locally; use when
+#                                             # bridge-delivered hooks DO fire
+#                                             # in your Cursor, to avoid every
+#                                             # hook firing twice. Same as
+#                                             # MASSA_AI_CURSOR_PREFER_BRIDGE=1
 #   apps/cursor-plugin/install.sh --uninstall # remove owned entries + plugin dir
 #   apps/cursor-plugin/install.sh -h|--help   # show this help
 
@@ -41,11 +71,26 @@ CLAUDE_PLUGIN_BIN="$REPO_ROOT/apps/claude-plugin/hooks/massa-ai-hook.ts"
 SCOPE="user"
 UNINSTALL=0
 DRY_RUN=0
+# Local is the DEFAULT route; the Claude bridge is opt-in.
+#
+# Bridge detection reads ~/.claude — a fact about CLAUDE's files — and infers
+# from it that Cursor is loading massa-ai. That inference cannot be verified
+# from here, and it was measured wrong on Cursor 3.16.17: the plugin and its
+# 46 workflow commands were absent from the Cursor UI while ~/.claude said the
+# plugin was installed and enabled. Preferring the bridge by default therefore
+# meant silently withholding a working local install on the strength of a
+# claim about a different product.
+#
+# So the default installs everything locally, and --prefer-bridge (or
+# MASSA_AI_CURSOR_PREFER_BRIDGE=1) opts into leaving hook wiring to the
+# bridge. See the AD-017 double-fire note where PREFER_BRIDGE is consumed.
+PREFER_BRIDGE="${MASSA_AI_CURSOR_PREFER_BRIDGE:-0}"
 
 for arg in "$@"; do
   case "$arg" in
     --user) SCOPE="user" ;;
     --project) SCOPE="project" ;;
+    --prefer-bridge) PREFER_BRIDGE=1 ;;
     --uninstall) UNINSTALL=1 ;;
     --quiet) MASSA_AI_VERBOSE=0 ;;
     --verbose) MASSA_AI_VERBOSE=1 ;;
@@ -249,14 +294,37 @@ if (typeof cfg.hooks !== "object" || cfg.hooks === null) cfg.hooks = {};
 
 const hooks = cfg.hooks;
 
+// Ownership test — marker first, command shape as the fallback. The marker is
+// precise but not the only way our entries reach this file: an entry written by
+// a release before the marker existed, or copied by hand from documentation,
+// carries none, and was invisible to BOTH directions here — never deduped on
+// install, never removed on uninstall. Claude's copy of this merge had exactly
+// that gap and it double-fired every lifecycle event (measured live
+// 2026-08-17). Referencing the massa-ai-hook binary is unambiguous; a user hook
+// that merely mentions massa-ai elsewhere does not match.
+const OWNED_COMMAND = /massa-ai-hook/;
+
+function entryIsOwned(e) {
+  if (!e || typeof e !== "object") return false;
+  if (e._massaAiOwned === true) return true;
+  return typeof e.command === "string" && OWNED_COMMAND.test(e.command);
+}
+
 function hasOwned(arr) {
-  return Array.isArray(arr) && arr.some((e) => e && e._massaAiOwned === true);
+  return Array.isArray(arr) && arr.some(entryIsOwned);
 }
 
 if (mode === "uninstall") {
-  for (const [evt] of EVENTS) {
+  // Back up before removing: this now deletes unmarked entries it did not
+  // necessarily write, so the install path's backup discipline applies here too.
+  if (existed) {
+    fs.copyFileSync(file, `${file}.massa-ai.bak-${ts}`);
+  }
+  // Every event, not just the ones this release writes — the predicate
+  // identifies our commands rather than a location.
+  for (const evt of Object.keys(hooks)) {
     if (Array.isArray(hooks[evt])) {
-      hooks[evt] = hooks[evt].filter((e) => !(e && e._massaAiOwned === true));
+      hooks[evt] = hooks[evt].filter((e) => !entryIsOwned(e));
       if (hooks[evt].length === 0) delete hooks[evt];
     }
   }
@@ -536,86 +604,110 @@ fi
 # ── Install ──────────────────────────────────────────────────────────────────
 # PAU-08/09: bridge-preferred, local-fallback. Computed once, used to decide
 # both which artifacts this run writes and what installRoute gets recorded.
+# Local by default. The probe still runs when the bridge is NOT opted into,
+# purely so the AD-017 double-fire warning below can be accurate — its result
+# no longer decides what gets installed.
 IS_BRIDGE=0
+BRIDGE_AVAILABLE=0
 if claude_bridge_detected; then
-  IS_BRIDGE=1
+  BRIDGE_AVAILABLE=1
+fi
+if [[ "$PREFER_BRIDGE" == "1" ]]; then
+  if [[ "$BRIDGE_AVAILABLE" == "1" ]]; then
+    IS_BRIDGE=1
+    vecho "--prefer-bridge: leaving hook wiring to the Claude bridge."
+  else
+    # Opting into a bridge that is not there would leave the user with no hooks
+    # at all, which is strictly worse than the default. Fall back loudly.
+    echo "  ⚠ --prefer-bridge requested, but ~/.claude does not list massa-ai as installed and enabled." >&2
+    echo "    Falling back to a local hook install so hooks are not silently absent." >&2
+  fi
 fi
 
 skill_count=0
 specialist_count=0
 
 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
+  vecho "Claude-bridge route: ~/.claude lists massa-ai as installed and enabled, so Cursor delivers its HOOKS via the bridge. The plugin bundle is still installed locally — see below."
+  # Hook wiring, and only hook wiring, is what the bridge actually delivers.
+  # Owned entries are stripped with the SAME filter merge_hooks_json's
+  # "uninstall" mode uses, so the bridge's copy is the only one that fires.
   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
+fi
 
-  # Copy manifest
-  cp "$SCRIPT_DIR/.cursor-plugin/plugin.json" "$PLUGIN_DIR/.cursor-plugin/plugin.json"
-  vecho "  + .cursor-plugin/plugin.json"
-
-  # Copy the host-command skills (each in a subdirectory: skills/<name>/SKILL.md),
-  # quick + generated workflow commands alike. massa-ai/, persona-router/,
-  # agents/, and profile/ 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. `profile` was missing from this exclusion pre-fix, which
-  # leaked it into the command-skill cache mislabeled as `/profile`.
-  for src in "$SCRIPT_DIR/skills/"*/SKILL.md; do
-    name="$(basename "$(dirname "$src")")"
-    case "$name" in
-      massa-ai|persona-router|agents|profile) 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
+# The plugin bundle (manifest + workflow-command skills) installs on BOTH
+# routes. It used to be skipped whenever the bridge was detected, on the
+# premise that the bridge loads the whole plugin.
+#
+# Measured against Cursor 3.16.17 on 2026-08-17, that premise is half true.
+# With the bridge active — massa-ai listed and `enabledPlugins` true in
+# ~/.claude — hooks DO fire in Cursor, while the plugin and its 46 workflow
+# commands are absent from the UI entirely. The old branch therefore deleted a
+# working local bundle and nothing replaced it: the user kept the hooks and
+# silently lost every workflow command. The header's "Cursor 3.14 also bridges
+# the Claude marketplace registry" was pinned against a 2026-08-05 capture and
+# was never re-verified against a later Cursor.
+#
+# So the two deliveries are gated independently: hooks by $IS_BRIDGE above,
+# the bundle never. Reinstating the bundle on the bridge route cannot
+# double-fire hooks — .cursor-plugin/plugin.json declares only
+# name/version/description, so the bundle carries no hook wiring of its own;
+# $HOOKS_JSON is the only surface that does, and on the bridge route it is
+# left stripped.
+vecho "Installing the massa-ai Cursor plugin bundle 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. Runs on both routes.
+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 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
+# Copy manifest
+cp "$SCRIPT_DIR/.cursor-plugin/plugin.json" "$PLUGIN_DIR/.cursor-plugin/plugin.json"
+vecho "  + .cursor-plugin/plugin.json"
+
+# Copy the host-command skills (each in a subdirectory: skills/<name>/SKILL.md),
+# quick + generated workflow commands alike. massa-ai/, persona-router/,
+# agents/, and profile/ 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. `profile` was missing from this exclusion pre-fix, which
+# leaked it into the command-skill cache mislabeled as `/profile`.
+for src in "$SCRIPT_DIR/skills/"*/SKILL.md; do
+  name="$(basename "$(dirname "$src")")"
+  case "$name" in
+    massa-ai|persona-router|agents|profile) 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
 
 # Flat agents and harness skills are written in BOTH branches (PAU-08/09):
@@ -708,9 +800,20 @@ fi
 # Summary line in quiet mode
 if [ "${MASSA_AI_VERBOSE:-0}" != "1" ]; then
   if [[ "$IS_BRIDGE" -eq 1 ]]; then
-    ok "cursor plugin: using the Claude bridge (${specialist_count} specialists) — hooks delivered by the bridge, not installed locally"
+    ok "cursor plugin installed (${skill_count} skills, ${specialist_count} specialists) — hooks left to the Claude bridge (--prefer-bridge)"
+    ok "  if massa-ai hooks do NOT fire in Cursor, the bridge is not delivering them: re-run without --prefer-bridge"
   else
     ok "cursor plugin installed (${skill_count} skills, ${specialist_count} specialists, 7 hooks)"
+    if [[ "$BRIDGE_AVAILABLE" -eq 1 ]]; then
+      # AD-017: both sources live. Not an error — the default is local by
+      # design — but the user must be told, because a doubled hook is silent
+      # and looks like the tool misbehaving rather than being installed twice.
+      echo "  ⚠ ~/.claude also lists massa-ai as installed and enabled." >&2
+      echo "    If Cursor's Claude bridge delivers those hooks, they now fire TWICE" >&2
+      echo "    (once from the bridge, once from ~/.cursor/hooks.json)." >&2
+      echo "    Keep one source: re-run with --prefer-bridge, or disable massa-ai" >&2
+      echo "    in ~/.claude/settings.json (enabledPlugins)." >&2
+    fi
   fi
 else
   vecho ""

package/package.json

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

package/skills/agents/architecture-specialist/SKILL.md

@@ -56,7 +56,7 @@ Provide architectural guidance by evaluating structure, suggesting boundaries, a
 - Verification Ladder: static (coupling, depth, boundary) checks; no behavioral changes.
 - Massa-ai Memory: suggest durable architecture-decision memories only when a boundary or abstraction is recommended; main agent persists.
 - Synapse: own ephemeral session when evaluation spans multiple modules with repeated searches.
-- References: `references/architecture-lenses.md`, `references/architecture-domain-lens.md`, `references/architecture-coupling-lens.md`, `references/architecture-deepening-lens.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/architecture-lenses.md`, `references/architecture-domain-lens.md`, `references/architecture-coupling-lens.md`, `references/architecture-deepening-lens.md`.
 
 ## Validation Sensors
 - Every finding has a `path:line` or metric pointer.

package/skills/agents/audit-specialist/SKILL.md

@@ -72,7 +72,7 @@ All lenses share `references/audit-scope.md` (scope rules) and `references/audit
 - Verification Ladder: static checks per lens; no behavioral changes (findings-only).
 - Massa-ai Memory: suggest durable audit-pattern memories only when a lens reveals a recurring issue class; main agent persists.
 - Synapse: own ephemeral session when the audit spans multiple modules with repeated searches.
-- References: `references/audit-scope.md`, `references/audit-report-io.md`, plus the per-lens references above.
+- References (paths relative to the `massa-ai` skill directory): `references/audit-scope.md`, `references/audit-report-io.md`, plus the per-lens references above.
 
 ## Validation Sensors
 - Every finding has a `path:line` pointer.

package/skills/agents/builder/SKILL.md

@@ -58,7 +58,7 @@ Implement an approved plan or task by modifying source code with a disjoint writ
 - Verification Ladder: run the task's sensors (static + behavioral) before claiming Complete.
 - Massa-ai Memory: suggest durable code-pattern memories only when the implementation establishes a reusable convention; main agent persists.
 - Synapse: none (implementation is not a repeated-search task).
-- References: `references/agent-orchestration.md`, `references/naming-standards.md`, `references/code-annotation.md`, `references/root-cause-scripts.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/agent-orchestration.md`, `references/naming-standards.md`, `references/code-annotation.md`, `references/root-cause-scripts.md`.
 
 ## Validation Sensors
 - Verification commands from the plan pass (tests, build, typecheck, lint).

package/skills/agents/context-curator/SKILL.md

@@ -58,7 +58,7 @@ Prepare the minimum high-quality Context Packet required for another agent to do
 - Verification Ladder: static checks only (file existence, reference existence).
 - Massa-ai Memory: retrieve via `recall`; do not persist unless the main agent assigns it.
 - Synapse: own ephemeral session per `references/synapse-policy.md`; pass `synapseSessionId` on every `search`.
-- References: `references/context-firewall.md`, `references/synapse-policy.md`, `references/mcp-tools.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/context-firewall.md`, `references/synapse-policy.md`, `references/mcp-tools.md`.
 
 ## Validation Sensors
 - Every file in the Context Packet exists (`test -f`).

package/skills/agents/designer/SKILL.md

@@ -59,7 +59,7 @@ Own the screen: verify an existing user-facing screen against its design source,
 - Verification Ladder: behavioral (the UI module builds and its tests pass) and file-integrity (no validation asset weakened).
 - Massa-ai Memory: suggest durable memories only when a reusable screen or design-token convention is established; the main agent persists.
 - Synapse: none by default; request an ephemeral session only when the scope needs two or more related searches across the UI layer.
-- References: `references/figma-pre-analysis.md`, `references/figma-wiring.md`, `references/design-implementation.md`, `references/naming-standards.md`, `references/verification-ladder.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/figma-pre-analysis.md`, `references/figma-wiring.md`, `references/design-implementation.md`, `references/naming-standards.md`, `references/verification-ladder.md`.
 
 ## Validation Sensors
 - Every design element in scope appears in the conformance table with a verdict, or the table states why the design source did not cover it.

package/skills/agents/documentation-agent/SKILL.md

@@ -56,7 +56,7 @@ Generate engineering documentation artifacts (README, ADR, RFC, changelog, KDoc,
 - Verification Ladder: static (doc-lint, stale-reference, link check); no behavioral sensors.
 - Massa-ai Memory: suggest durable doc-format memories only when a documentation convention is established; main agent persists.
 - Synapse: none (documentation is not a repeated-search task).
-- References: `references/adr-authoring.md`, `references/rfc/`.
+- References (paths relative to the `massa-ai` skill directory): `references/adr-authoring.md`, `references/rfc/`.
 
 ## Validation Sensors
 - Stale-reference scan passes (no dead links to removed files).

package/skills/agents/furps-analyst/SKILL.md

@@ -60,7 +60,7 @@ Analyze exactly one FURPS+ dimension of a PRD or ADR against its checklist secti
 - Verification Ladder: static evidence checks only — source-location proof per claim, absent-claim detection per `missing`.
 - Massa-ai Memory: suggest durable memories only when a reusable refinement pattern is discovered; the main agent persists.
 - Synapse: own ephemeral session when >= 2 searches are expected, per `references/synapse-policy.md`.
-- References: `references/furps/checklist.md`, `references/furps/report-contract.md`, `references/furps/intake.md`, `references/agent-orchestration.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/furps/checklist.md`, `references/furps/report-contract.md`, `references/furps/intake.md`, `references/agent-orchestration.md`.
 
 ## Validation Sensors
 - Source-location proof (quote plus section) for every `covered`/`partial` claim.

package/skills/agents/investigator/SKILL.md

@@ -59,7 +59,7 @@ Read and understand the codebase to answer engineering questions without modifyi
 - Verification Ladder: static checks (grep, search) and file-integrity; no behavioral changes.
 - Massa-ai Memory: suggest durable architecture/dependency memories only when useful; main agent persists.
 - Synapse: own ephemeral session per `references/synapse-policy.md`; pass `synapseSessionId` on every `search`.
-- References: `references/codebase-investigation.md`, `references/agent-orchestration.md`, `references/synapse-policy.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/codebase-investigation.md`, `references/agent-orchestration.md`, `references/synapse-policy.md`.
 
 ## Validation Sensors
 - Source-backed evidence for every claim (`path:line`).

package/skills/agents/judge/SKILL.md

@@ -80,7 +80,7 @@ next_step: <string>
 - Verification Ladder: every score cites a quotation; a score without a quote is a sensor failure.
 - Massa-ai Memory: suggest durable memories only for reusable evaluation failure patterns; the main agent persists.
 - Policy: the orchestrator owns dispatch, consensus arithmetic, and the final verdict; this agent owns its scores and its file only.
-- References: `references/agent-orchestration.md`, `references/audit-report-io.md` (Judge With Debate Report Contracts).
+- References (paths relative to the `massa-ai` skill directory): `references/agent-orchestration.md`, `references/audit-report-io.md` (Judge With Debate Report Contracts).
 
 ## Model Hint
 See `references/agent-orchestration.md` (Model Diversity Fallback): `metadata.model_tier`

package/skills/agents/meta-judge/SKILL.md

@@ -71,7 +71,7 @@ overall: weighted-mean
 - Verification Ladder: every criterion must be checkable by quoting the artifact — a criterion that cannot be evidenced is not a criterion.
 - Massa-ai Memory: suggest durable memories only for reusable rubric patterns; the main agent persists.
 - Policy: the main agent (judge-with-debate orchestrator) owns dispatch, YAML validation, retry, and consensus; this agent owns the specification only.
-- References: `references/agent-orchestration.md`, `references/audit-report-io.md` (Judge With Debate Report Contracts).
+- References (paths relative to the `massa-ai` skill directory): `references/agent-orchestration.md`, `references/audit-report-io.md` (Judge With Debate Report Contracts).
 
 ## Model Hint
 See `references/agent-orchestration.md` (Model Diversity Fallback): `metadata.model_tier`

package/skills/agents/mobile-specialist/SKILL.md

@@ -73,7 +73,7 @@ If none are present, refuse with: `Non-mobile target. Refusing mobile-specialist
 - Verification Ladder: platform-specific static checks when available; no behavioral changes.
 - Massa-ai Memory: suggest durable mobile-decision memories only when a platform constraint or lifecycle pattern is established; main agent persists.
 - Synapse: own ephemeral session when guidance spans multiple mobile modules with repeated searches.
-- References: `references/mobile-context.md`, `references/mobile-diagnosis.md`, `references/maestro.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/mobile-context.md`, `references/mobile-diagnosis.md`, `references/maestro.md`.
 
 ## Validation Sensors
 - At least one detection signal is confirmed present before guidance is given.

package/skills/agents/navigator/SKILL.md

@@ -66,7 +66,7 @@ The user's codebase is **already indexed** by massa-ai. The first move on any qu
 - Orphaned-dims recovery: if a vector `search` returns 0 results while other dim tables hold chunks for the project, report to the parent agent that `index` with `forceReindex=true` is required. Do not run it.
 - Context Firewall: summarize search output; return only `path:line` pointers and findings.
 - Massa-ai Memory: suggest durable navigation facts (entry points, ownership boundaries) only when reusable; the main agent persists.
-- References: `references/mcp-tools.md`, `references/codebase-investigation.md`, `references/synapse-policy.md`, `references/context-firewall.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/mcp-tools.md`, `references/codebase-investigation.md`, `references/synapse-policy.md`, `references/context-firewall.md`.
 
 ## Validation Sensors
 - Every claim carries a `path:line` or symbol pointer.

package/skills/agents/plan-critic/SKILL.md

@@ -79,7 +79,7 @@ Never receives full conversation context.
 - Verification Ladder: every challenge names the concrete sensor that would settle it.
 - Massa-ai Memory: suggest durable memories only for reusable failure modes or rejected approaches; the main agent persists.
 - Policy: the main agent owns mode selection, synthesis, plan revision, and the Evidence Gate; this agent owns the critique only.
-- References: `references/agent-orchestration.md`, `references/the-fool/`, `references/verification-ladder.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/agent-orchestration.md`, `references/the-fool/`, `references/verification-ladder.md`.
 
 ## Validation Sensors
 - Every challenge ties to a plan section plus a concrete evidence gap or falsifiable check.

package/skills/agents/planner/SKILL.md

@@ -56,7 +56,7 @@ Transform an engineering request into a structured implementation plan.
 - Verification Ladder: plan references expected sensors; does not run them.
 - Massa-ai Memory: suggest durable decision memories only when the plan locks a strategy; main agent persists.
 - Synapse: none (planning is not a repeated-search task).
-- References: `references/agent-orchestration.md`, `references/subagent-design.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/agent-orchestration.md`, `references/subagent-design.md`.
 
 ## Validation Sensors
 - Every step in the plan references a concrete file, module, or task.

package/skills/agents/requirements-analyst/SKILL.md

@@ -55,7 +55,7 @@ Analyze requirements before implementation to surface ambiguity, gaps, contradic
 - Verification Ladder: static (spec citation) only; no behavioral sensors.
 - Massa-ai Memory: suggest durable requirement-decision memories only when an implicit requirement is accepted as an assumption; main agent persists.
 - Synapse: none (analysis is not a repeated-search task).
-- References: `references/spec-driven/specify.md`, `references/furps/`.
+- References (paths relative to the `massa-ai` skill directory): `references/spec-driven/specify.md`, `references/furps/`.
 
 ## Validation Sensors
 - Every finding cites a requirement ID or spec section.

package/skills/agents/reviewer/SKILL.md

@@ -57,7 +57,7 @@ Review implementation quality by analyzing the diff and flagging bugs, regressio
 - Verification Ladder: static checks (lint, typecheck) as supporting evidence; behavioral checks belong to verification-agent.
 - Massa-ai Memory: suggest durable code-quality memories only when a review reveals a reusable pattern; main agent persists.
 - Synapse: none (review is not a repeated-search task).
-- References: `references/agent-orchestration.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/agent-orchestration.md`.
 
 ## Validation Sensors
 - Every finding has a `path:line` pointer.

package/skills/agents/test-engineer/SKILL.md

@@ -58,7 +58,7 @@ Generate a testing strategy that covers unit, integration, edge cases, negative
 - Verification Ladder: behavioral (tests) and file-integrity (no validation assets weakened).
 - Massa-ai Memory: suggest durable test-pattern memories only when a testing convention is established; main agent persists.
 - Synapse: none (test planning is not a repeated-search task).
-- References: `references/verification-ladder.md`, `references/code-annotation.md`, `references/root-cause-scripts.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/verification-ladder.md`, `references/code-annotation.md`, `references/root-cause-scripts.md`.
 
 ## Validation Sensors
 - Every acceptance criterion maps to at least one test case.

package/skills/agents/verification-agent/SKILL.md

@@ -55,7 +55,7 @@ Centralize Verification Ladder logic and validate that a task's output meets its
 - Verification Ladder: this agent IS the ladder; choose the cheapest sufficient evidence first.
 - Massa-ai Memory: suggest durable verification-recipe memories only when a sensor pattern is reusable; main agent persists.
 - Synapse: none (verification is not a repeated-search task).
-- References: `references/verification-ladder.md`, `references/evidence-gate.md`.
+- References (paths relative to the `massa-ai` skill directory): `references/verification-ladder.md`, `references/evidence-gate.md`.
 
 ## Validation Sensors
 - Every acceptance criterion has a PASS/FAIL verdict with evidence.

package/skills/massa-ai/references/architecture-lenses.md

@@ -39,28 +39,7 @@ Analyze dependency cost with strength, distance, and volatility.
 
 Load `references/architecture-coupling-lens.md` when the audit target includes dependencies, imports, service calls, shared schemas/models, direct persistence access, co-change, or contract leakage.
 
-Strength levels:
-
-- Intrusive: downstream depends on internals not designed for integration.
-- Functional: sequential, transactional, or duplicated symmetric business rules.
-- Model: upstream exposes internal domain model to downstream.
-- Contract: integration-specific DTO/protocol hides internals.
-
-Distance levels:
-
-- same function or class
-- same package
-- same module/library
-- different service
-- external system or team
-
-Volatility signals:
-
-- core business logic
-- frequent git changes or co-change
-- TODO/FIXME clusters
-- evolving API versions
-- fragile tests or recurring regressions
+Strength, distance, and volatility level definitions: full detail in `references/architecture-coupling-lens.md`.
 
 Flag highest risk when high strength, high distance, and high volatility combine.
 
@@ -88,10 +67,7 @@ Check:
 - test-only extraction that loses locality
 - concepts split across many files without leverage
 
-Use the deletion test:
-
-- If deleting a module removes complexity, it was probably shallow.
-- If deleting it spreads complexity across callers, it was probably earning its keep.
+Deletion test: full detail in `references/architecture-deepening-lens.md`.
 
 Only recommend a new seam when variation, dependency direction, external I/O, or test substitution is real.
 

package/skills/massa-ai/references/conversation-feedback.md

@@ -17,19 +17,7 @@ repeated micro-events.
 
 ## Line Shape
 
-Each status update must be 1-2 lines. Use an emoji, a capitalized label in square brackets, and one or two plain sentences.
-
-Do:
-
-```md
-🔵 [Start] Planning visual feedback for massa-ai. Workflow: Spec Driven. Session: Visual Feedback.
-🔄 [Loading] Reading AGENTS.md and massa-ai router guidance before planning.
-🧠 [Context] Found 8 relevant massa-ai memories and queried the requested NotebookLM source.
-🤖 [Agent Running] Plan Critic is checking failure modes for the proposed design.
-⚠️ [Divergence] Expected the legacy router path, but this checkout uses skills/massa-ai/SKILL.md.
-✅ [Verified] Stale-reference checks and skill validation passed.
-🏁 [Finished] Plan complete. Changed files: none. Remaining risk: none found.
-```
+Each status update must be 1-2 lines. Use an emoji, a capitalized label in square brackets, and one or two plain sentences. The worked example is not repeated here — it lives in the canonical policy block named under Policy Source above, which is always in context.
 
 Avoid terse machine-shaped status lines, lowercase labels, equals-sign syntax, and tiny abbreviations.
 

package/skills/massa-ai/references/hook-enforcement.md

@@ -131,7 +131,7 @@ recall stays owned by the router.
 
 | Failure | Behavior |
 |---|---|
-| massa-ai REST unavailable | lesson still lands in `lessons.json`; skipped memory write logged to `scripts/hooks-state/skip.log` |
-| `.specs/STATE.md` absent / workflow unset | stop gate falls back to flat matrix |
+| massa-ai REST unavailable | lesson still lands in `lessons.json`; the memory write is fire-and-forget and is dropped silently (a timeout emits a `deadline-on-fire` JSON breadcrumb on **stderr**, nothing is written to disk) |
+| `.specs/project/STATE.md` absent / workflow unset | stop gate falls back to flat matrix |
 | bad / malformed stdin | hook exits 0, never blocks |
-| hook non-critical error | exit 0, approve, log skip |
+| hook non-critical error | exit 0, approve, degrade silently — there is no skip log file |

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

@@ -166,5 +166,5 @@ best-effort. An ungrounded lesson is refused by both `add` and the massa-ai writ
 ### Self-Check
 
 After verification: if a reusable signal was found but no lesson was recorded,
-state the skipped reason. The hook loop logs every skip to
-`scripts/hooks-state/skip.log`.
+state the skipped reason. Nothing else records it — the hook loop keeps no skip
+log on disk, so your stated reason is the only record.