@massa-ai/claude-plugin 1.6.0

package/install.sh

@@ -0,0 +1,435 @@
+#!/usr/bin/env bash
+#
+# massa-ai Claude Code plugin installer
+#
+# Copies slash commands and the generated massa-ai subagents into the user's
+# Claude Code config directory AND auto-writes the 5 massa-ai hook events
+# into ~/.claude/settings.json (or ./.claude/settings.json) using an
+# array-append merge that preserves existing user hooks. The hooks block uses
+# Claude Code's nested matcher-group + hooks[] form, each owned entry marked
+# with _massaAiOwned: true.
+#
+# MCP registration is delegated to scripts/install-agents.sh, the single writer
+# of host MCP config; it merges the massa-ai entry alongside the hooks block.
+#
+# Idempotent: re-running is a no-op when owned hooks already present.
+# Uninstall removes only ownership-marked hook entries + commands/agents,
+# preserving user keys and user hooks.
+#
+# Usage:
+#   apps/claude-plugin/install.sh             # install at user scope (~/.claude)
+#   apps/claude-plugin/install.sh --user      #   (same)
+#   apps/claude-plugin/install.sh --project   # install at project scope (./.claude)
+#   apps/claude-plugin/install.sh --uninstall # remove owned hooks + commands/agents
+#   apps/claude-plugin/install.sh -h|--help   # show this help
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+SCOPE="user"
+UNINSTALL=0
+DRY_RUN=0
+
+for arg in "$@"; do
+  case "$arg" in
+    --user) SCOPE="user" ;;
+    --project) SCOPE="project" ;;
+    --uninstall) UNINSTALL=1 ;;
+    --quiet) MASSA_AI_VERBOSE=0 ;;
+    --verbose) MASSA_AI_VERBOSE=1 ;;
+    --dry-run) DRY_RUN=1; MASSA_AI_VERBOSE=1 ;;
+    -h|--help)
+      sed -n '2,/^$/p' "$0" | sed 's/^# \{0,1\}//'
+      exit 0
+      ;;
+    *) echo "Unknown flag: $arg" >&2; exit 2 ;;
+  esac
+done
+
+# Banner
+source "$SCRIPT_DIR/../../scripts/banner.sh"
+massa_ai_banner
+
+if [[ "$SCOPE" == "project" ]]; then
+  TARGET="$(pwd)/.claude"
+else
+  TARGET="$HOME/.claude"
+fi
+SETTINGS_JSON="$TARGET/settings.json"
+# The shared binary lives in the repo (not copied) — settings.json references
+# its absolute path so Claude Code can invoke `bun run <path> <subcommand>`.
+HOOK_BIN="$SCRIPT_DIR/hooks/massa-ai-hook.ts"
+# Double-fire guard input. The plugin now ships hooks/hooks.json, so a user who
+# installed massa-ai through /plugin AND ran this script would ingest every
+# lifecycle event twice. Claude Code records plugin installs at USER scope even
+# for --project, so this resolves from $HOME, never from $SCOPE.
+PLUGIN_REGISTRY="$HOME/.claude/plugins/installed_plugins.json"
+
+# The 5 Claude Code events → binary subcommands. The matcher-group entry shape:
+#   { "hooks": [{ "type": "command", "command": "bun run \"<HOOK_BIN>\" <sub>" }],
+#     "_massaAiOwned": true }
+# The merge appends one owned matcher-group entry per event array, preserving
+# any pre-existing user matcher-group entries (F5 mitigation).
+merge_settings_hooks() {
+  local file="$1"
+  local mode="$2" # "install" or "uninstall"
+  local ts
+  ts="$(date +%Y%m%d%H%M%S)"
+
+  local runner=""
+  if command -v node &>/dev/null; then
+    runner="node"
+  elif command -v bun &>/dev/null; then
+    runner="bun"
+  else
+    echo "Error: node or bun required to merge settings.json (JSON manipulation)" >&2
+    exit 3
+  fi
+
+  "$runner" - "$file" "$mode" "$ts" "$HOOK_BIN" "$PLUGIN_REGISTRY" <<'NODE'
+const fs = require("fs");
+const path = require("path");
+
+const file = process.argv[2];
+const mode = process.argv[3];
+const ts = process.argv[4];
+const hookBin = process.argv[5];
+const pluginRegistry = process.argv[6];
+
+const EVENTS = [
+  ["SessionStart", "session-start"],
+  ["UserPromptSubmit", "user-prompt-submit"],
+  ["PostToolUse", "post-tool-use"],
+  ["PreCompact", "pre-compact"],
+  ["Stop", "stop"],
+];
+
+let cfg = {};
+let existed = false;
+try {
+  const raw = fs.readFileSync(file, "utf8");
+  if (raw.trim()) {
+    cfg = JSON.parse(raw);
+    existed = true;
+  }
+} catch (e) {
+  if (e.code === "ENOENT") {
+    // no file — start empty
+  } else {
+    throw e;
+  }
+}
+
+function hasOwned(arr) {
+  return Array.isArray(arr) && arr.some((e) => e && e._massaAiOwned === true);
+}
+
+// Double-fire guard: true when massa-ai is already installed as a Claude Code
+// plugin, in which case the plugin's own hooks/hooks.json is already wired and
+// appending owned entries here would ingest every event twice.
+//
+// Fails OPEN in every uncertain case — a missing registry is the normal fresh
+// install, and a malformed one must not block installation. That is deliberately
+// unlike the read at the top of this script, which only tolerates ENOENT.
+function pluginAlreadyInstalled() {
+  let raw;
+  try {
+    raw = fs.readFileSync(pluginRegistry, "utf8");
+  } catch (e) {
+    if (e.code !== "ENOENT") {
+      console.error(
+        `  ⚠ could not read ${pluginRegistry} (${e.code}) — wiring hooks anyway`,
+      );
+    }
+    return false;
+  }
+  try {
+    const plugins = JSON.parse(raw).plugins;
+    if (!plugins || typeof plugins !== "object") return false;
+    return Object.keys(plugins).some((k) => /^massa-ai@/.test(k));
+  } catch {
+    console.error(
+      `  ⚠ ${pluginRegistry} is not valid JSON — wiring hooks anyway`,
+    );
+    return false;
+  }
+}
+
+if (mode === "uninstall") {
+  const hooks = cfg.hooks;
+  if (hooks && typeof hooks === "object" && !Array.isArray(hooks)) {
+    for (const [evt] of EVENTS) {
+      if (Array.isArray(hooks[evt])) {
+        hooks[evt] = hooks[evt].filter((e) => !(e && e._massaAiOwned === true));
+        if (hooks[evt].length === 0) delete hooks[evt];
+      }
+    }
+    if (Object.keys(hooks).length === 0) delete cfg.hooks;
+  }
+} else if (pluginAlreadyInstalled()) {
+  console.error(
+    "  ↷ massa-ai is installed as a Claude Code plugin — skipping settings.json" +
+      " hooks (the plugin already provides them; wiring both would double-fire)",
+  );
+  process.exit(0);
+} else {
+  // install: backup before first write if file existed
+  if (existed) {
+    const bak = `${file}.massa-ai.bak-${ts}`;
+    fs.copyFileSync(file, bak);
+  }
+  if (!cfg.hooks || typeof cfg.hooks !== "object" || Array.isArray(cfg.hooks)) {
+    cfg.hooks = {};
+  }
+  for (const [evt, sub] of EVENTS) {
+    if (!Array.isArray(cfg.hooks[evt])) cfg.hooks[evt] = [];
+    if (!hasOwned(cfg.hooks[evt])) {
+      cfg.hooks[evt].push({
+        hooks: [
+          {
+            type: "command",
+            command: `bun run "${hookBin}" ${sub}`,
+          },
+        ],
+        _massaAiOwned: true,
+      });
+    }
+  }
+}
+
+fs.mkdirSync(path.dirname(file), { recursive: true });
+fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + "\n");
+NODE
+}
+
+# ── Skills bundling (PDO-08, 09 / D3 two-writer ownership) ──────────────────
+# scripts/install-skills.sh remains the single writer once it has already
+# claimed this platform (skillsOwner: "repo" in the shared install-state.json).
+# This plugin installs its bundled massa-ai/persona-router skills into the
+# SAME harness skills directory (~/.claude/skills, not this plugin's cache)
+# only when that has not happened, mirroring the MCP single-writer precedent
+# (test-mcp-single-writer.sh). A repo checkout's own --apply always takes
+# precedence over a prior plugin install — see install-skills.sh.
+HARNESS_STATE_FILE="$HOME/.config/massa-ai/install-state.json"
+HARNESS_SKILLS_DIR="$TARGET/skills"
+HARNESS_HOST="claude"
+
+harness_skills_owner() {
+  local runner="$1"
+  "$runner" - "$HARNESS_STATE_FILE" "$HARNESS_HOST" <<'NODE'
+const fs = require("fs");
+const [, , file, host] = process.argv;
+try {
+  const data = JSON.parse(fs.readFileSync(file, "utf8"));
+  const rec = data && data.platforms && data.platforms[host];
+  process.stdout.write(rec && rec.skillsOwner === "repo" ? "repo" : "none");
+} catch {
+  process.stdout.write("none");
+}
+NODE
+}
+
+install_bundled_skills() {
+  local runner=""
+  if command -v node &>/dev/null; then runner="node"
+  elif command -v bun &>/dev/null; then runner="bun"
+  else
+    echo "  ⚠ node or bun required to install bundled skills — skipping" >&2
+    return 0
+  fi
+
+  if [[ "$(harness_skills_owner "$runner")" == "repo" ]]; then
+    vecho "  ↷ skills already installed by scripts/install-skills.sh (repo-owned) — skipping bundled copy"
+    return 0
+  fi
+
+  local installed=0 name src dest
+  for name in massa-ai persona-router; do
+    src="$SCRIPT_DIR/skills/$name"
+    [[ -d "$src" ]] || continue
+    dest="$HARNESS_SKILLS_DIR/$name"
+    if [[ -e "$dest" && ! -d "$dest" ]]; then
+      echo "  ⚠ $dest exists and is not a directory — skipping" >&2
+      continue
+    fi
+    mkdir -p "$HARNESS_SKILLS_DIR"
+    rm -rf "$dest"
+    cp -R "$src" "$dest"
+    installed=$((installed + 1))
+  done
+  vecho "  + ${installed} harness skills installed to $HARNESS_SKILLS_DIR (plugin-owned)"
+
+  "$runner" - "$HARNESS_STATE_FILE" "$HARNESS_HOST" "$TARGET" <<'NODE'
+const fs = require("fs");
+const path = require("path");
+const [, , file, host, root] = process.argv;
+let data = { version: 2, platforms: {} };
+try {
+  const existing = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (existing && typeof existing === "object" && !Array.isArray(existing)) data = existing;
+} catch { /* fresh */ }
+if (typeof data.platforms !== "object" || data.platforms === null || Array.isArray(data.platforms)) {
+  data.platforms = {};
+}
+data.version = 2;
+data.platforms[host] = { root, skillsOwner: "plugin", skills: ["massa-ai", "persona-router"] };
+fs.mkdirSync(path.dirname(file), { recursive: true });
+fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+NODE
+}
+
+uninstall_bundled_skills() {
+  local runner=""
+  if command -v node &>/dev/null; then runner="node"
+  elif command -v bun &>/dev/null; then runner="bun"
+  else return 0
+  fi
+
+  # harness_skills_owner collapses to "repo" | "none"; uninstall only ever
+  # acts on an exact "plugin" record, so query the raw value directly.
+  local raw_owner
+  raw_owner="$("$runner" - "$HARNESS_STATE_FILE" "$HARNESS_HOST" <<'NODE'
+const fs = require("fs");
+const [, , file, host] = process.argv;
+try {
+  const data = JSON.parse(fs.readFileSync(file, "utf8"));
+  const rec = data && data.platforms && data.platforms[host];
+  process.stdout.write(rec ? String(rec.skillsOwner) : "none");
+} catch {
+  process.stdout.write("none");
+}
+NODE
+  )"
+  [[ "$raw_owner" == "plugin" ]] || return 0
+
+  local name
+  for name in massa-ai persona-router; do
+    rm -rf "$HARNESS_SKILLS_DIR/$name"
+  done
+  rmdir "$HARNESS_SKILLS_DIR" 2>/dev/null || true
+  echo "  - removed plugin-owned harness skills from $HARNESS_SKILLS_DIR"
+
+  "$runner" - "$HARNESS_STATE_FILE" "$HARNESS_HOST" <<'NODE'
+const fs = require("fs");
+const [, , file, host] = process.argv;
+try {
+  const data = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (data && data.platforms && data.platforms[host] && data.platforms[host].skillsOwner === "plugin") {
+    delete data.platforms[host];
+    fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+  }
+} catch { /* nothing to clean up */ }
+NODE
+}
+
+# ── Uninstall ───────────────────────────────────────────────────────────────
+if [[ "$UNINSTALL" -eq 1 ]]; then
+  echo "Uninstalling massa-ai Claude Code plugin (scope: $SCOPE)..."
+  uninstall_bundled_skills
+  # Remove owned hook entries (preserves user hooks + user keys)
+  if [[ -f "$SETTINGS_JSON" ]]; then
+    merge_settings_hooks "$SETTINGS_JSON" "uninstall"
+    echo "  - removed massa-ai hook entries from $SETTINGS_JSON"
+  fi
+  # Remove owned command files
+  if [[ -d "$TARGET/commands" ]]; then
+    for src in "$SCRIPT_DIR/commands/"*.md; do
+      name="$(basename "$src" .md)"
+      rm -f "$TARGET/commands/massa-ai-${name}.md"
+    done
+    echo "  - removed massa-ai-* commands from $TARGET/commands/"
+  fi
+  # Remove every massa-ai-owned subagent specialist. All of them are generated
+  # from skills/agents/*/SKILL.md, so the massa-ai- name prefix is the ownership
+  # marker; user agents without that prefix are untouched.
+  if [[ -d "$TARGET/agents" ]]; then
+    for src in "$TARGET/agents/"massa-ai-*.md; do
+      [[ -f "$src" ]] || continue
+      rm -f "$src"
+    done
+    echo "  - removed massa-ai-* subagent specialists from $TARGET/agents/"
+  fi
+  echo ""
+  echo "Done. User hooks, keys, and non-massa-ai agents preserved."
+  exit 0
+fi
+
+# ── Install ──────────────────────────────────────────────────────────────────
+vecho "Installing massa-ai Claude Code plugin to: $TARGET"
+mkdir -p "$TARGET/commands" "$TARGET/agents"
+
+# Count for summary
+command_count=0
+# Slash commands — prefix with 'massa-ai-' to avoid collisions with user commands
+for src in "$SCRIPT_DIR/commands/"*.md; do
+  name="$(basename "$src" .md)"
+  dest="$TARGET/commands/massa-ai-${name}.md"
+  cp "$src" "$dest"
+  vecho "  + /massa-ai-${name}"
+  command_count=$((command_count + 1))
+done
+
+# Subagent specialists (generated from skills/agents/*/SKILL.md, navigator
+# included). The massa-ai- name prefix is the ownership marker used by uninstall.
+specialist_count=0
+for src in "$SCRIPT_DIR/agents/"massa-ai-*.md; do
+  [[ -f "$src" ]] || continue
+  name="$(basename "$src")"
+  cp "$src" "$TARGET/agents/$name"
+  vecho "  + $name"
+  specialist_count=$((specialist_count + 1))
+done
+vecho "  + ${specialist_count} subagent specialists (generated from skills/agents/*/SKILL.md)"
+
+# 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.
+vecho ""
+install_bundled_skills
+
+# Merge hooks into settings.json (array-append, backup, idempotent)
+vecho ""
+vecho "Merging hooks into $SETTINGS_JSON..."
+if [[ ! -f "$HOOK_BIN" ]]; then
+  echo "  ⚠ Warning: hook binary not found at $HOOK_BIN" >&2
+  echo "    Hooks will not fire until the binary is available." >&2
+fi
+merge_settings_hooks "$SETTINGS_JSON" "install"
+vecho "  + 5 massa-ai hook events wired (array-append, user hooks preserved)"
+
+# ── MCP registration (delegated) ─────────────────────────────────────────────
+# scripts/install-agents.sh is the single writer of host MCP config. It merges
+# the massa-ai entry into ~/.claude/settings.json alongside the hooks block
+# written above, at USER scope — a --project plugin install still registers MCP
+# for the whole user.
+vecho ""
+vecho "Registering MCP server (user scope) via scripts/install-agents.sh..."
+if [[ -f "$REPO_ROOT/scripts/install-agents.sh" ]]; then
+  # On success the delegated output is detail (usually "up to date"), so it is
+  # gated. On failure it is never gated: a silently-failed MCP registration is
+  # exactly the bug this change set exists to fix.
+  if agents_out="$(MASSA_AI_SUPPRESS_SPECIALIST_HINT=1 bash "$REPO_ROOT/scripts/install-agents.sh" --agent claude-code --yes 2>&1)"; then
+    vecho "$agents_out"
+  else
+    echo "$agents_out" >&2
+    echo "  ⚠ MCP wiring failed — run: bash scripts/install-agents.sh --agent claude-code --yes" >&2
+  fi
+else
+  echo "  ⚠ scripts/install-agents.sh not found — register MCP with: bash scripts/install-agents.sh --agent claude-code --yes" >&2
+fi
+
+# Summary line in quiet mode
+if [ "${MASSA_AI_VERBOSE:-0}" != "1" ]; then
+  ok "claude plugin installed (${command_count} commands, ${specialist_count} specialists, 5 hooks)"
+else
+  vecho ""
+  vecho "Done. Restart Claude Code to pick up the new commands and hooks."
+  vecho ""
+fi
+vecho "Next steps:"
+vecho "  1. Try: /massa-ai-status"
+vecho "  2. Try: /massa-ai-map (on an indexed project)"
+# ~/.claude.json, not ~/.claude/settings.json — Claude Code reads MCP
+# definitions from the former; settings.json only holds approval controls.
+vecho "💡 Hooks are wired by this plugin; MCP is registered in ~/.claude.json by scripts/install-agents.sh (single writer)."

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@massa-ai/claude-plugin",
+  "version": "1.6.0",
+  "description": "massa-ai plugin for Claude Code — semantic code search, durable memory, symbol graph, and context compression",
+  "files": [
+    "agents",
+    "commands",
+    "hooks",
+    "!hooks/__tests__",
+    "skills",
+    "install.sh",
+    "README.md",
+    ".claude-plugin/plugin.json"
+  ],
+  "author": "luizgmassa",
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "massa-ai",
+    "semantic-search",
+    "code-search",
+    "memory",
+    "context-compression",
+    "ai",
+    "llm"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/luizgmassa/massa-ai"
+  }
+}

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

@@ -0,0 +1,69 @@
+---
+name: architecture-specialist
+description: Read-only architecture guidance agent. Evaluate architecture, suggest boundaries, recommend abstractions, evaluate trade-offs, and suggest modularization. Folds the existing domain-mapper, coupling-auditor, and deepening-architect roles into one specialist. Triggers when a workflow needs architectural guidance before or during design. Never implements or rewrites code.
+license: MIT
+metadata:
+  author: S1LV4, luizgmassa
+  version: "1.0.0"
+  model_hint: MiniMax M3
+  permission: read-only
+---
+
+# Architecture Specialist Agent Skill
+
+## Mission
+Provide architectural guidance by evaluating structure, suggesting boundaries, and weighing trade-offs.
+
+## Responsibilities
+- Evaluate architecture (layering, boundaries, coupling, depth).
+- Suggest module boundaries and seams.
+- Recommend abstractions where duplication or volatility warrants them.
+- Evaluate trade-offs between approaches.
+- Suggest modularization for shallow or over-coupled modules.
+
+## Restrictions
+- Never implement.
+- Never rewrite code.
+- Never spawn subagents and never load the `massa-ai` router; the dispatching workflow owns routing.
+
+## Inputs
+- `scope`: the module, service, or area under evaluation.
+- `inputs`: recalled facts, source pointers, existing architecture docs.
+- `sensors`: static coupling/depth metrics when available.
+
+## Outputs
+- Status: Complete | Partial | Blocked
+- Scope: modules and boundaries evaluated
+- Evidence: `path:line` pointers, coupling/depth metrics, source locations
+- Findings: boundary suggestions, abstraction recommendations, trade-off analysis, modularization plan
+- Risks and skipped checks
+- Exact next step
+
+## Invocation
+### Use when
+- A workflow needs architectural guidance before or during design.
+- The work crosses module or service boundaries.
+- The user asks for architecture evaluation, coupling analysis, or modularization.
+
+### Do not use when
+- The work is a single-file fix with no architectural surface.
+- The task needs a concrete implementation (route to builder).
+- An audit-specific lens is needed (route to audit-specialist with `lens: architecture`).
+
+## massa-ai Integration
+- Context Firewall: summarize source reads; return findings and metrics, not raw code.
+- 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`.
+
+## Model Hint
+MiniMax M3 (advisory). Fallback to the workflow's configured default model if unavailable.
+
+## Validation Sensors
+- Every finding has a `path:line` or metric pointer.
+- Trade-offs name at least two alternatives.
+- Boundary suggestions reference concrete modules.
+
+## Memory Boundary
+Suggest durable memories only when an architectural boundary or abstraction is recommended and accepted. The main agent persists. Do not persist one-off evaluation chatter.

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

@@ -0,0 +1,85 @@
+---
+name: audit-specialist
+description: Configurable read-only audit agent. Execute specialized audits through six lenses — bugs, architecture, security, requirements, code-quality, performance — selected via the lens field in the capability packet. Triggers when a workflow needs a findings-only audit. Never modifies implementation.
+license: MIT
+metadata:
+  author: S1LV4, luizgmassa
+  version: "1.0.0"
+  model_hint: GLM-5.2
+  permission: read-only
+---
+
+# Audit Specialist Agent Skill
+
+## Mission
+Execute a specialized audit through one configurable lens and return findings-only output.
+
+## Responsibilities
+- Execute the audit checklist for the selected lens.
+- Tie every finding to a `path:line` source location.
+- Rank findings by severity.
+- Produce a findings report following the project audit-report format.
+
+## Restrictions
+- Never modify implementation.
+- One lens per dispatch; do not mix lenses in one run.
+- Never spawn subagents and never load the `massa-ai` router; the dispatching workflow owns routing.
+
+## Lenses
+
+The `lens` field in the capability packet selects the audit behavior:
+
+| Lens | Focus | Per-lens references |
+|---|---|---|
+| `bugs` | Bug discovery: null paths, error handling, race conditions, logic errors | `workflows/bugs/bugs-audit.md` |
+| `architecture` | DDD, boundaries, coupling, module depth, seams | `references/architecture-lenses.md`, `references/architecture-domain-lens.md`, `references/architecture-coupling-lens.md`, `references/architecture-deepening-lens.md` |
+| `security` | Security, privacy, auth, validation, secret handling | `workflows/security/security-audit.md` |
+| `requirements` | Requirements, spec, acceptance, scope alignment | `workflows/requirements/requirements-audit.md` |
+| `code-quality` | SOLID, Clean Code, KISS, YAGNI, DRY, maintainability | `workflows/code-quality/code-quality-audit.md` |
+| `performance` | Performance hotspots, allocation, latency, throughput | Domain-specific; no fixed reference |
+
+All lenses share `references/audit-scope.md` (scope rules) and `references/audit-report-io.md` (report format).
+
+## Inputs
+- `scope`: the target area, diff, or module to audit.
+- `lens`: one of `bugs | architecture | security | requirements | code-quality | performance` (required).
+- `inputs`: recalled facts, existing audit reports, source pointers.
+- `sensors`: static checks available for the lens (lint, typecheck, security scanners).
+
+## Outputs
+- Status: Complete | Partial | Blocked
+- Scope: area audited + lens used
+- Evidence: `path:line` pointers, static-check results, source locations
+- Findings: ranked list (severity, location, problem, suggestion) in the project audit-report format
+- Risks and skipped checks
+- Exact next step
+
+## Invocation
+### Use when
+- A workflow needs a findings-only audit of an implementation target.
+- The user asks for a bug, architecture, security, requirements, code-quality, or performance audit.
+- A high/critical finding needs independent verification.
+
+### Do not use when
+- The task needs a fix (route to the matching `*-fix` workflow or builder).
+- No concrete target exists to audit.
+- The lens is ambiguous (ask the user to pick one).
+
+## massa-ai Integration
+- Context Firewall: summarize the audit scope; return findings, not raw source dumps.
+- 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.
+
+## Model Hint
+GLM-5.2 (advisory). Fallback to the workflow's configured default model if unavailable.
+
+## Validation Sensors
+- Every finding has a `path:line` pointer.
+- Findings follow the project audit-report format (`references/audit-report-io.md`).
+- Severity is assigned per the lens rubric.
+- No fix actions taken (findings-only).
+
+## Memory Boundary
+Suggest durable memories only when a lens reveals a recurring issue class worth remembering. The main agent persists. Do not persist the audit report itself (it lives in `.specs/`).