@massa-ai/claude-plugin 1.61.0 → 1.63.0

package/commands/{ticket.md → create-ticket.md}

@@ -1,13 +1,13 @@
 ---
-description: "Use this workflow to draft, review, create, or resume creation of Jira Epics, issues, or sub-tasks through Atlassian MCP, the only tracker and mutation path. — explicit massa-ai 'ticket' workflow"
+description: "Use this workflow to draft, review, create, or resume creation of Jira Epics, issues, or sub-tasks through Atlassian MCP, the only tracker and mutation path. — explicit massa-ai 'create-ticket' workflow"
 argument-hint: "[task description]"
 ---
 <!-- massa-ai:generated workflow-command -->
 
-Explicit massa-ai workflow invocation: `ticket`.
+Explicit massa-ai workflow invocation: `create-ticket`.
 
 Load the massa-ai router skill if not already loaded (dedupe guard), then
-route to workflow `ticket` under routing precedence 1 (explicit route) —
+route to workflow `create-ticket` under routing precedence 1 (explicit route) —
 do not reclassify. Pass the following as the task description; if empty,
 the workflow's own intake gathers it.
 

package/commands/{discovery.md → product-discovery.md}

@@ -1,13 +1,13 @@
 ---
-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. — explicit massa-ai 'discovery' workflow"
+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 create-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 (create-prd), or any implementation work. — explicit massa-ai 'product-discovery' workflow"
 argument-hint: "[task description]"
 ---
 <!-- massa-ai:generated workflow-command -->
 
-Explicit massa-ai workflow invocation: `discovery`.
+Explicit massa-ai workflow invocation: `product-discovery`.
 
 Load the massa-ai router skill if not already loaded (dedupe guard), then
-route to workflow `discovery` under routing precedence 1 (explicit route) —
+route to workflow `product-discovery` under routing precedence 1 (explicit route) —
 do not reclassify. Pass the following as the task description; if empty,
 the workflow's own intake gathers it.
 

package/hooks/massa-ai-hook.ts

@@ -227,7 +227,7 @@ function readModelLine(filePath: string): string | null {
 
 /**
  * The ≤2-line session-start drift report (agent-runtime-drift): version
- * drift (live bundle vs recorded state), agent drift (active investigator
+ * drift (live bundle vs recorded state), agent drift (active code-reviewer
  * model vs the recorded profile's variant), and the host env override that
  * nullifies every per-agent model at runtime. Null when every recording
  * agrees — silent when healthy. Read-only (INV5); every failure degrades to
@@ -253,13 +253,13 @@ export function buildSessionStartDoctorLine(
 
   const profile = claude?.modelProfile?.profile;
   if (typeof profile === "string" && profile) {
-    const activeModel = readModelLine(path.join(pluginRoot, "agents", "massa-ai-investigator.md"));
+    const activeModel = readModelLine(path.join(pluginRoot, "agents", "code-reviewer.md"));
     const variantModel = readModelLine(
-      path.join(pluginRoot, "agent-profiles", profile, "massa-ai-investigator.md"),
+      path.join(pluginRoot, "agent-profiles", profile, "code-reviewer.md"),
     );
     if (activeModel && variantModel && activeModel !== variantModel) {
       lines.push(
-        `[massa-ai] agent drift: investigator ${activeModel} vs ${profile} variant ${variantModel} — re-run the profile switch`,
+        `[massa-ai] agent drift: code-reviewer ${activeModel} vs ${profile} variant ${variantModel} — re-run the profile switch`,
       );
     }
   }

package/install.sh

@@ -350,7 +350,7 @@ 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
+# This plugin installs its bundled massa-ai/bootstrap 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
@@ -374,6 +374,44 @@ try {
 NODE
 }
 
+# C4: line 1 is the enumerated owner ("plugin" | "none" — never the raw
+# recorded value, so a hostile multi-line skillsOwner cannot smuggle a name
+# into the list); every further line is a harness skill this plugin recorded
+# as installed and no longer ships. The recorded list is the ownership proof,
+# so an unrecorded directory of the same name is never touched.
+plugin_skills_record() {
+  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];
+  const owned = !!rec && rec.skillsOwner === "plugin";
+  const current = ["massa-ai", "bootstrap"];
+  const retired = owned && Array.isArray(rec.skills)
+    ? rec.skills.filter((s) => typeof s === "string" && /^[a-z0-9][a-z0-9-]*$/.test(s) && !current.includes(s))
+    : [];
+  process.stdout.write([owned ? "plugin" : "none", ...retired].join("\n"));
+} catch {
+  process.stdout.write("none");
+}
+NODE
+}
+
+# Removes every retired name in a plugin_skills_record output. The subshell
+# body scopes `set -f` and a newline-only IFS, so no name is ever
+# glob-expanded or split on a space.
+remove_retired_skills() (
+  set -f
+  IFS=$'\n'
+  state_retired_skills="$(printf '%s\n' "$1" | sed 1d)"
+  for name in $state_retired_skills; do
+    rm -rf "$HARNESS_SKILLS_DIR/$name"
+    vecho "  - removed retired harness skill $HARNESS_SKILLS_DIR/$name"
+  done
+)
+
 install_bundled_skills() {
   local runner=""
   if command -v node &>/dev/null; then runner="node"
@@ -389,7 +427,7 @@ install_bundled_skills() {
   fi
 
   local installed=0 name src dest
-  for name in massa-ai persona-router profile bootstrap; do
+  for name in massa-ai bootstrap; do
     src="$SCRIPT_DIR/skills/$name"
     [[ -d "$src" ]] || continue
     dest="$HARNESS_SKILLS_DIR/$name"
@@ -404,6 +442,11 @@ install_bundled_skills() {
   done
   vecho "  + ${installed} harness skills installed to $HARNESS_SKILLS_DIR (plugin-owned)"
 
+  # C4: retired skills go BEFORE the record is rewritten — the recorded list
+  # is the only ownership proof, so a removal that fails (set -e aborts here)
+  # leaves it in place for the next run to retry.
+  remove_retired_skills "$(plugin_skills_record "$runner")"
+
   "$runner" - "$HARNESS_STATE_FILE" "$HARNESS_HOST" "$TARGET" <<'NODE'
 const fs = require("fs");
 const path = require("path");
@@ -418,7 +461,8 @@ if (typeof data.platforms !== "object" || data.platforms === null || Array.isArr
 }
 data.version = 2;
 const prev = data.platforms[host];
-data.platforms[host] = { root, skillsOwner: "plugin", skills: ["massa-ai", "persona-router", "profile", "bootstrap"] };
+const current = ["massa-ai", "bootstrap"];
+data.platforms[host] = { root, skillsOwner: "plugin", skills: current };
 // The whole-record replace must not drop fields a previous successful install
 // wrote (R2) — re-attach them. modelProfile (T10, MPS-03 round-trip
 // obligation) is engine-owned; installRoute is installer-owned but written by
@@ -448,26 +492,16 @@ uninstall_bundled_skills() {
   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" ]] && {
+  # Line 1 of the record is the enumerated owner; uninstall only ever acts on
+  # an exact "plugin" record.
+  local record
+  record="$(plugin_skills_record "$runner")"
+  [[ "${record%%$'\n'*}" == "plugin" ]] && {
     local name
-    for name in massa-ai persona-router profile bootstrap; do
+    for name in massa-ai bootstrap; do
       rm -rf "$HARNESS_SKILLS_DIR/$name"
     done
+    remove_retired_skills "$record"
     rmdir "$HARNESS_SKILLS_DIR" 2>/dev/null || true
     echo "  - removed plugin-owned harness skills from $HARNESS_SKILLS_DIR"
   }
@@ -678,16 +712,20 @@ apply_recorded_profile_after_update() {
     return 0
   fi
   mkdir -p "$install_path/agents"
-  for f in "$variant_dir/"massa-ai-*.md; do
+  for f in "$variant_dir/"*.md; do
     [[ -f "$f" ]] || continue
     name="$(basename "$f")"
+    if [[ -e "$install_path/agents/$name" || -L "$install_path/agents/$name" ]] && ! is_owned_agent "$install_path/agents/$name"; then
+      echo "  ⚠ $install_path/agents/$name exists and is not massa-ai-owned — skipped" >&2
+      continue
+    fi
     cp "$f" "$install_path/agents/$name"
     copied=$((copied + 1))
   done
   if [[ "$copied" -gt 0 ]]; then
     vecho "  ↷ re-applied recorded model profile '$profile' (${copied} files) to $install_path/agents"
   else
-    vecho "  ↷ recorded model profile '$profile' variant directory has no massa-ai-*.md files — nothing to re-apply"
+    vecho "  ↷ recorded model profile '$profile' variant directory has no agent files — nothing to re-apply"
   fi
 }
 
@@ -827,13 +865,49 @@ remove_file_route_artifacts() {
     done
   fi
   if [[ -d "$TARGET/agents" ]]; then
-    for src in "$TARGET/agents/"massa-ai-*.md; do
-      [[ -f "$src" ]] || continue
+    for src in "$TARGET/agents/"*.md; do
+      is_owned_agent "$src" || continue
       rm -f "$src"
     done
   fi
 }
 
+# >>> massa-ai agent ownership predicates >>>
+# Byte-identical in every plugin installer and scripts/lib/installer-shared.sh
+# (plugin tarballs cannot source repo-only libs); the TS twin is
+# packages/shared/src/profile-switch/ownership.ts, and
+# scripts/__tests__/agent-ownership-parity.test.ts holds all copies and both
+# languages to identical verdicts. Ownership is a content marker, never a
+# filename; the legacy rule lets an upgrade prune the pre-rename
+# massa-ai-<name> files — exact names only, never an open massa-ai-* glob.
+MASSA_AI_OWNED_MARKER_MD='<!-- massa-ai-owned: true -->'
+MASSA_AI_LEGACY_AGENT_NAMES=" architecture-specialist audit-specialist builder context-curator designer documentation-agent furps-analyst investigator judge meta-judge mobile-specialist navigator plan-critic planner requirements-analyst reviewer test-engineer verification-agent "
+is_legacy_agent() {
+  local b="${1##*/}"
+  b="${b%.*}"
+  [[ "$b" == massa-ai-* && "$MASSA_AI_LEGACY_AGENT_NAMES" == *" ${b#massa-ai-} "* ]]
+}
+has_owned_marker() {
+  awk -v m="$MASSA_AI_OWNED_MARKER_MD" 'NR==1{if($0!="---")exit;next} !c&&$0=="---"{c=1;next} c{ok=($0==m);exit} END{exit !ok}' "$1" 2>/dev/null
+}
+is_owned_agent() {
+  [[ -f "$1" && ! -L "$1" ]] || return 1
+  is_legacy_agent "$1" || has_owned_marker "$1"
+}
+is_owned_agent_toml() {
+  [[ -f "$1" && ! -L "$1" ]] || return 1
+  [[ "$(head -n1 "$1")" == "# massa-ai-owned" ]]
+}
+is_owned_agent_link() {
+  [[ -L "$1" ]] || return 1
+  is_legacy_agent "$1" && return 0
+  local b="${1##*/}" t
+  t="$(readlink "$1")"
+  [[ "$t" == */opencode-plugin/agents/"$b" || "$t" == */plugins/massa-ai/agent-profiles/*/"$b" ]] && return 0
+  [[ -f "$1" ]] && has_owned_marker "$1"
+}
+# <<< massa-ai agent ownership predicates <<<
+
 # ── Uninstall ───────────────────────────────────────────────────────────────
 if [[ "$UNINSTALL" -eq 1 ]]; then
   echo "Uninstalling massa-ai Claude Code plugin (scope: $SCOPE)..."
@@ -856,15 +930,15 @@ if [[ "$UNINSTALL" -eq 1 ]]; then
     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.
+  # Remove every massa-ai-owned subagent specialist: the body marker, or a
+  # legacy massa-ai-<name> file (is_owned_agent). A user's own agent, even
+  # one named like a massa-ai agent, is untouched.
   if [[ -d "$TARGET/agents" ]]; then
-    for src in "$TARGET/agents/"massa-ai-*.md; do
-      [[ -f "$src" ]] || continue
+    for src in "$TARGET/agents/"*.md; do
+      is_owned_agent "$src" || continue
       rm -f "$src"
     done
-    echo "  - removed massa-ai-* subagent specialists from $TARGET/agents/"
+    echo "  - removed massa-ai-owned subagent specialists from $TARGET/agents/"
   fi
   echo ""
   echo "Done. User hooks, keys, and non-massa-ai agents preserved."
@@ -892,7 +966,7 @@ if [[ "$PLUGIN_ROUTE" -eq 1 ]]; then
   for src in "$SCRIPT_DIR/commands/"*.md; do
     [[ -f "$src" ]] && command_count=$((command_count + 1))
   done
-  for src in "$SCRIPT_DIR/agents/"massa-ai-*.md; do
+  for src in "$SCRIPT_DIR/agents/"*.md; do
     [[ -f "$src" ]] && specialist_count=$((specialist_count + 1))
   done
   remove_file_route_artifacts
@@ -925,8 +999,8 @@ else
     vecho "  - removed retired command $(basename "$f")"
   done
 
-  # Subagent specialists (generated from skills/agents/*/SKILL.md, navigator
-  # included). The massa-ai- name prefix is the ownership marker used by uninstall.
+  # Subagent specialists (generated from skills/agents/*/SKILL.md). Each carries the body ownership marker used by prune and
+  # uninstall; a same-named file the user owns is skipped, never overwritten.
   #
   # Model-profile re-apply (T8, MPS-04): if a switch previously recorded a
   # profile for this host, and the bundle ships that profile's variant, the
@@ -951,9 +1025,13 @@ else
     fi
   fi
 
-  for src in "$ACTIVE_AGENTS_SRC/"massa-ai-*.md; do
+  for src in "$ACTIVE_AGENTS_SRC/"*.md; do
     [[ -f "$src" ]] || continue
     name="$(basename "$src")"
+    if [[ -e "$TARGET/agents/$name" || -L "$TARGET/agents/$name" ]] && ! is_owned_agent "$TARGET/agents/$name"; then
+      echo "  ⚠ $TARGET/agents/$name exists and is not massa-ai-owned — skipped" >&2
+      continue
+    fi
     cp "$src" "$TARGET/agents/$name"
     vecho "  + $name"
     specialist_count=$((specialist_count + 1))
@@ -966,10 +1044,10 @@ else
   # model-profile variant) no longer ships. Never prune-then-copy — an
   # interrupted run must never leave the user with fewer agents than before.
   # Removal population is the destination directory (D2); ownership test is
-  # the massa-ai- name prefix (install.sh:775-777).
-  for f in "$TARGET/agents/"massa-ai-*.md; do
-    [[ -f "$f" ]] || continue
+  # is_owned_agent — so legacy massa-ai-<name> files are pruned on upgrade.
+  for f in "$TARGET/agents/"*.md; do
     [[ -f "$ACTIVE_AGENTS_SRC/$(basename "$f")" ]] && continue
+    is_owned_agent "$f" || continue
     rm -f "$f"
     vecho "  - removed retired specialist $(basename "$f")"
   done
@@ -977,7 +1055,7 @@ else
   install_variant_tree
 fi
 
-# Skills bundling (PDO-08, 09): install massa-ai/persona-router into the
+# Skills bundling (PDO-08, 09): install massa-ai/bootstrap into the
 # shared harness skills directory, unless scripts/install-skills.sh already
 # owns it for this platform.
 vecho ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massa-ai/claude-plugin",
-  "version": "1.61.0",
+  "version": "1.63.0",
   "description": "massa-ai plugin for Claude Code — semantic code search, durable memory, symbol graph, and context compression",
   "files": [
     "agents",

package/skills/agents/code-explorer/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: code-explorer
+description: Read-only codebase exploration agent. Answer "where is X", "how does Y work", and "who calls Z" index-first through the massa-ai semantic index, and trace execution flow, map dependencies, and estimate change impact from source. Triggers when a workflow needs to understand existing code before planning or implementing. Never modifies code, never generates implementation, never performs reviews.
+license: MIT
+metadata:
+  author: Luiz Massa
+  version: "2.0.0"
+  permission: read-only
+---
+
+# Code Explorer Agent Skill
+
+## Mission
+Answer engineering questions about an existing codebase with source-backed evidence, reaching for the massa-ai index first and reading files only once the target is narrowed, without modifying anything.
+
+## Core Principle
+The user's codebase is usually **already indexed** by massa-ai. The first move on any question is to query the index, not to read files blindly: file reads are expensive in context, index queries are not. When the index is missing or stale, trace from source and say so.
+
+## Responsibilities
+- Resolve the current project from the packet's `projectId` matched against `list_projects` (running `pwd` to match the workspace basename only where the host allows shell access), and confirm index freshness before treating index output as evidence.
+- Locate implementations of symbols, features, or behaviors.
+- Trace execution flow across modules and boundaries.
+- Identify dependencies and their risk surface.
+- Estimate change impact for a proposed modification.
+- Read files only when one to three of them are already known to matter; never scan directories exhaustively.
+
+## Restrictions
+- Unknown `mode`: return `Blocked` naming `trace`; a missing `mode` defaults to `trace`.
+- Never modify code, docs, or configuration.
+- Never generate implementation and never perform reviews.
+- Never scan directories exhaustively or read whole trees to answer a narrow question.
+- Never paste long code; summarize and cite.
+- Never call `reset_project`, `index`, or `reindex`; report the needed reindex to the parent agent instead.
+- Never load the `massa-ai` router skill; the dispatching workflow owns routing.
+
+## Inputs
+- `mode`: `trace` (the sole mode, and the default when `mode` is omitted).
+- `question` / `scope`: the question to answer, or the files, modules, and symbols to investigate.
+- `inputs`: recalled facts, source pointers, constraints.
+- `sensors`: expected commands or concrete checks.
+- `identifiers`: exact `projectId`, parent `workflowSessionId`, workflow name.
+- `synapseSessionId`: own ephemeral Synapse session for repeated searches (per `references/synapse-policy.md`).
+
+## Modes
+
+### Mode: `trace`
+Index-first answer for a single orientation question, and source-first investigation for work that spans files or modules, or when the index is absent or stale.
+
+Pick the cheapest index tool for the question shape:
+- "what does this project do?" -> `project_map`
+- "where is X defined?" -> `go_to_definition` (exact) or `search_definitions` (substring)
+- "who uses or calls X?" -> `get_references`
+- "how does this feature work?" -> `search` with a semantic query, then `Read` only the top 2-3 files
+
+Output:
+- Status: Complete | Partial | Blocked
+- Scope: index tools called and files read, plus files and symbols inspected
+- Evidence: `path:line` pointers, command results, source locations
+- Findings: a compact, cited answer, self-contained because it is the sole result the parent sees; architecture summary, flow trace, dependency map, impact estimate
+- Risks and skipped checks: index staleness, zero-result searches, unresolved symbols
+- Exact next step
+
+## Invocation
+### Use when
+- A workflow needs to understand existing code before planning or implementing.
+- The question is "where is X", "how does Y work", "who calls Z", or any orientation question about an indexed codebase.
+- The scope touches >10 files, >500 LOC, or >2 modules, or the user asks for investigation or impact analysis.
+- Verbose investigation would exceed Context Firewall thresholds.
+
+### Do not use when
+- The answer is a one-liner already in context.
+- The task needs code changes, review, or planning.
+- The task needs unresolved user intent.
+- The work is tightly coupled without a clear owner.
+
+## massa-ai Integration
+- Retrieval order: `list_projects` freshness -> `project_map` -> `search(summary)` -> `search(enriched)` -> symbol tools -> `read_file` -> focused shell fallback.
+- Freshness gating: `project_map`, `get_architecture`, `trace_path`, and `impact_analysis` count as evidence only when the index is fresh for the current path and commit/worktree state; otherwise fall back to `search`/`get_references` and record reduced retrieval confidence.
+- 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, logs, and source reads; return only `path:line` pointers and findings.
+- Verification Ladder: static checks (grep, search) and file-integrity; no behavioral changes.
+- Massa-ai Memory: suggest durable navigation, architecture, or dependency facts only when reusable; the main agent persists.
+- Synapse: own ephemeral session per `references/synapse-policy.md`; pass `synapseSessionId` on every `search`.
+- 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`, `references/agent-orchestration.md`.
+
+## Validation Sensors
+- Every claim carries a `path:line` or symbol pointer.
+- Index-derived claims carry freshness evidence, or are labeled reduced-confidence.
+- Dependency references confirmed via `get_references` or equivalent.
+- No files modified (read-only enforced).
+
+## Memory Boundary
+Suggest durable memories only for reusable entry points, ownership boundaries, architectural facts, or dependency patterns. The main agent persists. Do not persist one-off lookups or investigation chatter.

package/skills/agents/code-reviewer/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: code-reviewer
+description: Read-only verification and audit agent. Independently verify a task against its acceptance criteria with the Verification Ladder and discrimination sensor; run findings-only audits through the bugs, architecture, security, code-quality, performance, or diff lens — diff review after a senior-engineer completes a task and before the verification gate. Mode and lens are selected by the capability packet. Never implements, rewrites files, or plans features.
+license: MIT
+metadata:
+  author: Luiz Massa
+  version: "2.0.0"
+  permission: read-only
+---
+
+# Code Reviewer Agent Skill
+
+## Mission
+Judge existing or changed code with source-backed evidence: verify that a task meets its acceptance criteria, or audit a target through one lens — including a diff review via the `diff` lens — without modifying code; the only write is the `verify` mode report carve-out in Restrictions.
+
+## Responsibilities
+- Run exactly one mode per dispatch, selected by the packet `mode` field: `verify` or `audit`.
+- Tie every finding to a `path:line` source location, a metric, or a command result.
+- Rank findings by severity.
+- Report every skipped check with its concrete reason.
+
+## Restrictions
+- Never implement, never rewrite files, never plan features.
+- Write only in `verify` mode, and only the feature's `.specs/features/<slug>/validation.md` report plus scratch mutation state outside the real working tree (a temporary worktree or temp copies, discarded before the verdict); `audit` mode writes nothing.
+- Missing or unknown `mode` (or, in `audit` mode, a missing or unknown `lens`): return `Blocked` naming the valid modes `verify`, `audit` (and lenses `bugs`, `architecture`, `security`, `code-quality`, `performance`, `diff`).
+- One mode per dispatch; in `audit` mode, one lens per dispatch — do not mix lenses in one run.
+- Never skip a verification level without recording a concrete reason.
+- Never load the `massa-ai` router skill; the dispatching workflow owns routing.
+
+## Inputs
+- `mode`: `verify` | `audit` (required).
+- `lens`: `audit` mode only — one of `bugs | architecture | security | code-quality | performance | diff` (required in that mode). The `requirements` lens belongs to `product-manager` and the `tests` lens to `test-engineer`.
+- `sub-mode`: `audit` mode with `lens: architecture` only — optional, one of `domain | coupling | deepening`, selecting `references/architecture-domain-lens.md`, `references/architecture-coupling-lens.md`, or `references/architecture-deepening-lens.md`; absent means all three.
+- `scope`: the diff, changed files, task and its acceptance criteria, target area, or module under evaluation.
+- `inputs`: the approved plan or spec, recalled facts, existing audit reports, source pointers, expected behavior.
+- `sensors`: static checks (lint, typecheck, security scanners), tests, build, artifact checks, coupling/depth metrics, platform linters.
+
+## Modes
+
+### Mode: `verify`
+Independent verification (author ≠ verifier): the mandatory final gate before a task or finding is claimed complete.
+
+- Validate outputs against the acceptance criteria.
+- Choose the verification level (static, file-integrity, behavioral, higher-order), cheapest sufficient evidence first.
+- Execute the verification checklist and detect incomplete work.
+- At the tiers the Independent Verification Mandate names, run the discrimination sensor from `references/discrimination-sensor.md`; a surviving mutant means the claim is not proven.
+- Confirm validation assets (tests, specs, fixtures) were not weakened.
+- A docs-only task with no behavioral sensors is verified at the file-integrity level only.
+
+Output:
+- Status: Complete | Partial | Blocked
+- Scope: files and criteria checked
+- Evidence: command results, artifact inspection, source locations
+- Findings: PASS/FAIL per criterion, gap list, and the highest ladder level reached
+- Risks and skipped checks (with reasons)
+- Exact next step
+
+### Mode: `audit`
+Findings-only audit through one lens.
+
+| 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` |
+| `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 |
+| `diff` | Correctness bugs, regressions against existing behavior, code smells, maintainability issues, missing edge cases introduced by a diff | No fixed reference |
+
+`bugs`, `architecture`, `security`, `code-quality`, and `performance` share `references/audit-scope.md` (scope rules) and `references/audit-report-io.md` (report format); their findings follow the project audit-report format. `diff` findings are ranked and marked blocking vs advisory, and are returned in chat with no saved report — the diff review after a senior-engineer completes a task and before the verification gate. No fix actions are taken in any lens.
+
+Output:
+- Status: Complete | Partial | Blocked
+- Scope: area audited + lens used (for `diff`, the files and lines reviewed)
+- Evidence: `path:line` pointers, static-check results, source locations
+- Findings: ranked list (severity, location, problem, suggestion) — project audit-report format for `bugs`/`architecture`/`security`/`code-quality`/`performance`; for `diff`, ranked list of issues (severity, location, problem, fix), marked blocking vs advisory, returned in chat with no saved report
+- Risks and skipped checks
+- Exact next step
+
+## Invocation
+### Use when
+- A senior-engineer has completed a task and the workflow needs a diff review, or a PR or branch needs review before merge (`audit`, `lens: diff`).
+- The mandatory verification gate must run, or the workflow needs author ≠ verifier verification (`verify`).
+- A workflow needs a findings-only audit through any lens, including architecture guidance, or a high/critical finding needs independent verification (`audit`).
+
+### Do not use when
+- No diff, implementation, or concrete target exists yet.
+- `lens: architecture` only: the work is a single-file fix with no architectural surface.
+- The task needs a fix (route to the matching `*-fix` workflow or `senior-engineer`).
+- The lens is ambiguous (ask the user to pick one), or it is the `requirements` or `tests` lens.
+
+## massa-ai Integration
+- Context Firewall: summarize diffs, command output, and source reads; return findings and PASS/FAIL evidence, not raw diffs or logs.
+- Verification Ladder: in `verify` mode this agent IS the ladder; in the other modes static checks are supporting evidence and behavioral checks belong to `verify`.
+- Massa-ai Memory: suggest durable memories only for a reusable code-quality pattern, recurring issue class, verification recipe, or accepted boundary; the main agent persists.
+- Synapse: own ephemeral session when an audit pass spans multiple modules with repeated searches.
+- References (paths relative to the `massa-ai` skill directory): `references/agent-orchestration.md`, `references/verification-ladder.md`, `references/evidence-gate.md`, `references/discrimination-sensor.md`, `references/audit-scope.md`, `references/audit-report-io.md`, plus the per-lens references above.
+
+## Validation Sensors
+- Every finding has a `path:line` or metric pointer.
+- `audit`: static checks (lint, typecheck) run when available; findings cite source evidence, not opinion; findings follow `references/audit-report-io.md` for `bugs`/`architecture`/`security`/`code-quality`/`performance`, severity follows the lens rubric, no fix actions taken; `diff` findings are ranked and marked blocking vs advisory.
+- `verify`: every acceptance criterion has a PASS/FAIL verdict with evidence; skipped checks have a concrete reason; the highest ladder level reached is reported.
+- No files modified outside the `verify` carve-out: `audit` writes nothing; `verify` writes only the feature's `validation.md` and scratch mutation state outside the real working tree.
+
+## Memory Boundary
+Suggest durable memories only when a review, audit, or verification reveals a recurring pattern, a reusable sensor recipe, or an accepted architectural or platform decision. The main agent persists. Do not persist one-off review comments, audit reports, or verification results (they live in `.specs/` and `validation.md`).