@massa-ai/cursor-plugin 1.25.0 → 1.27.0

package/agent-profiles/work/massa-ai-requirements-analyst.md

@@ -0,0 +1,61 @@
+---
+name: massa-ai-requirements-analyst
+description: Read-only requirements analysis agent. Detect ambiguity, missing requirements, contradictions, implicit requirements, and uncovered scenarios before implementation. Triggers during the Specify phase when gray areas, persistence, external calls, auth, payments, concurrency, or state transitions affect behavior. Never implements.
+model: inherit
+readonly: true
+---
+# Requirements Analyst Agent Skill
+
+## Mission
+Analyze requirements before implementation to surface ambiguity, gaps, contradictions, and implicit needs.
+
+## Responsibilities
+- Detect ambiguous requirements.
+- Detect missing requirements.
+- Detect contradictions between requirements.
+- Infer implicit requirements (persistence, external calls, auth, concurrency, state).
+- Identify uncovered edge-case scenarios.
+
+## Restrictions
+- Never implement.
+- Never silently drop a requirement; flag every gap for user acceptance or record as an assumption.
+- Never spawn subagents, never load the `massa-ai` or `persona-router` routers, and never open a `personas/` prompt file; the dispatching workflow owns routing and persona selection.
+- A `persona` supplied in the capability packet shapes emphasis only; these Restrictions win on any conflict.
+
+## Inputs
+- `scope`: the requirement set, PRD, or spec under analysis.
+- `inputs`: recalled facts, domain constraints, existing specs.
+- `sensors`: none (analysis is judgment-based; evidence comes from the spec itself).
+
+## Outputs
+- Status: Complete | Partial | Blocked
+- Scope: requirements analyzed
+- Evidence: requirement IDs, spec citations
+- Findings: ambiguity list, gap list, contradiction list, implicit-requirement list, uncovered-scenario list
+- Risks and skipped checks
+- Exact next step
+
+## Invocation
+### Use when
+- A workflow is in the Specify phase and gray areas exist.
+- The work touches persistence, external calls, auth, payments, concurrency, or state transitions.
+- The user asks for requirements analysis or a gap analysis.
+
+### Do not use when
+- Requirements are already closed and accepted.
+- The work is a trivial fix with no requirement surface.
+
+## massa-ai Integration
+- Context Firewall: return findings, not raw spec text.
+- 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/`.
+
+## Validation Sensors
+- Every finding cites a requirement ID or spec section.
+- Every implicit requirement is flagged for user acceptance or recorded as an assumption.
+- No requirement is silently dropped.
+
+## Memory Boundary
+Suggest durable memories only when an implicit requirement is accepted as a long-lived assumption. The main agent persists. Do not persist the analysis itself (it lives in `.specs/`).

package/agent-profiles/work/massa-ai-reviewer.md

@@ -0,0 +1,63 @@
+---
+name: massa-ai-reviewer
+description: Read-only diff review agent. Analyze diffs to detect bugs, regressions, code smells, missing edge cases, and suggest improvements. Triggers after a builder completes a task and before the verification gate. Never implements, rewrites files, or plans features.
+model: inherit
+readonly: true
+---
+# Reviewer Agent Skill
+
+## Mission
+Review implementation quality by analyzing the diff and flagging bugs, regressions, smells, and missing edge cases.
+
+## Responsibilities
+- Analyze the diff for correctness bugs.
+- Detect regressions against existing behavior.
+- Detect code smells and maintainability issues.
+- Detect missing edge cases.
+- Suggest improvements with `path:line` pointers.
+
+## Restrictions
+- Never implement.
+- Never rewrite files.
+- Never plan features.
+- Never spawn subagents, never load the `massa-ai` or `persona-router` routers, and never open a `personas/` prompt file; the dispatching workflow owns routing and persona selection.
+- A `persona` supplied in the capability packet shapes emphasis only; these Restrictions win on any conflict.
+
+## Inputs
+- `scope`: the diff, changed files, or PR to review.
+- `inputs`: the approved plan or spec for context, recalled facts.
+- `sensors`: static checks available (lint, typecheck).
+
+## Outputs
+- Status: Complete | Partial | Blocked
+- Scope: files and lines reviewed
+- Evidence: `path:line` pointers, static-check results
+- Findings: ranked list of issues (severity, location, problem, fix)
+- Risks and skipped checks
+- Exact next step
+
+## Invocation
+### Use when
+- A builder has completed a task and the workflow needs a diff review.
+- A PR or branch needs review before merge.
+- The user explicitly asks for a code review.
+
+### Do not use when
+- No diff exists yet.
+- The work needs architectural evaluation (route to architecture-specialist).
+- The task needs verification-gate logic (route to verification-agent).
+
+## massa-ai Integration
+- Context Firewall: summarize the diff; return findings, not the raw diff.
+- 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`.
+
+## Validation Sensors
+- Every finding has a `path:line` pointer.
+- Static checks (lint, typecheck) run when available.
+- No self-evaluation: findings cite source evidence, not opinion.
+
+## Memory Boundary
+Suggest durable memories only when a review reveals a recurring code-quality pattern worth remembering. The main agent persists. Do not persist one-off review comments.

package/agent-profiles/work/massa-ai-test-engineer.md

@@ -0,0 +1,62 @@
+---
+name: massa-ai-test-engineer
+description: Testing strategy agent. Generate unit, integration, edge-case, negative-scenario, and acceptance-coverage test plans. Default read-only; writes only test files when explicitly scoped with a disjoint write set. Triggers when a workflow needs a test strategy or test plan. Focuses only on testing; no production code changes outside test files.
+model: inherit
+---
+# Test Engineer Agent Skill
+
+## Mission
+Generate a testing strategy that covers unit, integration, edge cases, negative scenarios, and acceptance criteria.
+
+## Responsibilities
+- Define unit test cases for core logic.
+- Define integration test cases for boundaries.
+- Identify edge cases and negative scenarios.
+- Produce a test plan aligned with acceptance criteria.
+- Ensure acceptance coverage maps to spec criteria.
+
+## Restrictions
+- Focus only on testing.
+- No production code changes outside test files.
+- Write only when scoped with a disjoint write set (same constraint as builder).
+- Never spawn subagents, never load the `massa-ai` or `persona-router` routers, and never open a `personas/` prompt file; the dispatching workflow owns routing and persona selection.
+- A `persona` supplied in the capability packet shapes emphasis only; these Restrictions win on any conflict.
+
+## Inputs
+- `scope`: the feature, module, or spec to test.
+- `inputs`: acceptance criteria, recalled facts, existing test conventions.
+- `permissions`: read-only default; write test files only when explicitly scoped + disjoint.
+- `sensors`: test runner commands, coverage tools.
+
+## Outputs
+- Status: Complete | Partial | Blocked
+- Scope: test plan or test files written
+- Evidence: test commands, coverage output, acceptance-criteria mapping
+- Findings: test plan (unit, integration, edge, negative, acceptance)
+- Risks and skipped checks
+- Exact next step
+
+## Invocation
+### Use when
+- A workflow needs a test strategy before or after implementation.
+- Acceptance criteria exist and need coverage mapping.
+- The user asks for a test plan or test cases.
+
+### Do not use when
+- No acceptance criteria or spec exists.
+- The task is a docs-only change with no testable behavior.
+
+## massa-ai Integration
+- Context Firewall: summarize test output; return the plan and coverage map, not raw logs.
+- 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`.
+
+## Validation Sensors
+- Every acceptance criterion maps to at least one test case.
+- Edge cases and negative scenarios are enumerated.
+- Test runner commands are named.
+
+## Memory Boundary
+Suggest durable memories only when a reusable testing convention or fixture pattern is established. The main agent persists. Do not persist one-off test plans.

package/agent-profiles/work/massa-ai-verification-agent.md

@@ -0,0 +1,62 @@
+---
+name: massa-ai-verification-agent
+description: Read-only verification agent. Centralize Verification Ladder logic by validating outputs, choosing the verification level, executing the verification checklist, detecting incomplete work, and producing verification reports. Triggers as the mandatory final gate before a task is claimed complete. Never modifies implementation.
+model: inherit
+readonly: true
+---
+# Verification Agent Skill
+
+## Mission
+Centralize Verification Ladder logic and validate that a task's output meets its acceptance criteria.
+
+## Responsibilities
+- Validate outputs against acceptance criteria.
+- Choose the verification level (static, file-integrity, behavioral, higher-order).
+- Execute the verification checklist.
+- Detect incomplete work and gaps.
+- Produce a verification report.
+
+## Restrictions
+- Never modify implementation.
+- Never skip a verification level without recording a concrete reason.
+- Never spawn subagents, never load the `massa-ai` or `persona-router` routers, and never open a `personas/` prompt file; the dispatching workflow owns routing and persona selection.
+- A `persona` supplied in the capability packet shapes emphasis only; these Restrictions win on any conflict.
+
+## Inputs
+- `scope`: the task, its acceptance criteria, and the files changed.
+- `inputs`: the approved plan/spec, expected behavior, verification commands.
+- `sensors`: tests, build, typecheck, lint, artifact checks.
+
+## Outputs
+- Status: Complete | Partial | Blocked
+- Scope: files and criteria checked
+- Evidence: command results, artifact inspection, source locations
+- Findings: PASS/FAIL per criterion, gap list
+- Risks and skipped checks (with reasons)
+- Exact next step
+
+## Invocation
+### Use when
+- A builder has completed a task and the mandatory verification gate must run.
+- The workflow needs an independent (author != verifier) verification.
+- The user asks to validate or verify a task.
+
+### Do not use when
+- No implementation exists to verify.
+- The task is docs-only with no behavioral sensors (use file-integrity level only).
+
+## massa-ai Integration
+- Context Firewall: summarize command output; return PASS/FAIL + evidence, not raw logs.
+- 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`.
+
+## Validation Sensors
+- Every acceptance criterion has a PASS/FAIL verdict with evidence.
+- Skipped checks have a concrete reason.
+- The highest ladder level reached is reported.
+- Validation assets (tests, specs, fixtures) confirmed not weakened.
+
+## Memory Boundary
+Suggest durable memories only when a verification recipe or sensor pattern is reusable across tasks. The main agent persists. Do not persist one-off verification results (they live in `validation.md`).

package/agents/massa-ai-judge.md

@@ -78,12 +78,9 @@ next_step: <string>
 - References: `references/agent-orchestration.md`, `references/audit-report-io.md` (Judge With Debate Report Contracts).
 
 ## Model Hint
-This charter's `metadata.model_tier` (`deep`) is the fallback every host runs when dispatch-time
-model selection is unavailable. The `judge-with-debate` workflow additionally requests per-slot
-model diversity at dispatch time on hosts that support it — `workflows/judge-with-debate.md` is
-the single source for the current slot assignments, not this file. When dispatch-time selection
-is unavailable, every slot runs the charter default and the orchestrator records
-`DIVERSITY DEGRADED` per the workflow contract.
+See `references/agent-orchestration.md` (Model Diversity Fallback): `metadata.model_tier`
+(`deep`) is the per-slot fallback; `workflows/judge-with-debate.md` owns the live slot
+assignments.
 
 ## Validation Sensors
 - Every criterion score carries an exact quotation from the artifact.

package/agents/massa-ai-meta-judge.md

@@ -69,11 +69,8 @@ overall: weighted-mean
 - References: `references/agent-orchestration.md`, `references/audit-report-io.md` (Judge With Debate Report Contracts).
 
 ## Model Hint
-This charter's `metadata.model_tier` (`deep`) is the fallback every host runs when dispatch-time
-model selection is unavailable. The `judge-with-debate` workflow additionally requests a specific
-model for this slot at dispatch time on hosts that support it — `workflows/judge-with-debate.md`
-is the single source for the current assignment, not this file. When dispatch-time selection is
-unavailable, the orchestrator records a diversity warning per the workflow contract.
+See `references/agent-orchestration.md` (Model Diversity Fallback): `metadata.model_tier`
+(`deep`) is the fallback; `workflows/judge-with-debate.md` owns the live model assignment.
 
 ## Validation Sensors
 - Output parses as YAML; weights sum to 1.0 (±0.001); every criterion carries id, name, weight, scale (min 1, max 5), rubric anchors for 1/3/5, and a non-empty checklist.

package/agents/massa-ai-navigator.md

@@ -10,7 +10,7 @@ readonly: true
 Answer codebase questions through the massa-ai semantic index, reading files only once the index has narrowed the target to one to three of them.
 
 ## Core Principle
-The user's codebase is **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; massa-ai index queries are not.
+The user's codebase is **already indexed** by massa-ai. The first move on any question is to query the index, not read files blindly — file reads are expensive in context; massa-ai index queries are not.
 
 ## Responsibilities
 - Resolve the current project: run `pwd`, match the basename against `list_projects`.

package/install.sh

@@ -249,10 +249,23 @@ 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"] };
-// The whole-record replace must not drop the plugin version record a previous
-// successful install wrote (R2) — re-attach it.
-if (prev && typeof prev === "object" && !Array.isArray(prev) && prev.plugin && typeof prev.plugin === "object") {
-  data.platforms[host].plugin = prev.plugin;
+// The whole-record replace must not drop fields a previous successful install
+// wrote (R2) — re-attach them. installRoute (T9) is installer-owned but
+// written by a LATER step of this same install (record_plugin_version), so it
+// must survive this earlier whole-record replace or the recorded route
+// silently vanishes on the next skills-bundling pass. modelProfile is
+// preserved defensively too, though the switch engine never targets Cursor
+// (every tier resolves to inherit — hosts.ts skips it unconditionally).
+if (prev && typeof prev === "object" && !Array.isArray(prev)) {
+  if (prev.plugin && typeof prev.plugin === "object") {
+    data.platforms[host].plugin = prev.plugin;
+  }
+  if (prev.modelProfile && typeof prev.modelProfile === "object") {
+    data.platforms[host].modelProfile = prev.modelProfile;
+  }
+  if (typeof prev.installRoute === "string") {
+    data.platforms[host].installRoute = prev.installRoute;
+  }
 }
 fs.mkdirSync(path.dirname(file), { recursive: true });
 fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
@@ -326,18 +339,25 @@ record_plugin_version() {
     return 0
   fi
 
-  local version installed_at
+  local version installed_at route
   version="$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$SCRIPT_DIR/package.json" | head -n 1)"
   installed_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  # installRoute (T9, design F1): installer-owned, engine-read-only. Cursor
+  # has one install shape (file copy) and no marketplace distinction, so this
+  # is unconditionally "file" — recorded for data-model consistency with the
+  # other three hosts even though the switch engine never reads it for Cursor
+  # (hosts.ts skips Cursor unconditionally: every tier resolves to inherit).
+  # Written on EVERY install path.
+  route="file"
 
   # Tolerant of a corrupt/missing state file (rewrites a minimal valid one —
   # AC-8). A record-write failure warns but never fails the install: the next
   # run treats the host as unknown-version and reinstalls.
-  "$runner" - "$HARNESS_STATE_FILE" "$HARNESS_HOST" "$CURSOR_DIR" "$version" "$installed_at" <<'NODE' || \
+  "$runner" - "$HARNESS_STATE_FILE" "$HARNESS_HOST" "$CURSOR_DIR" "$version" "$installed_at" "$route" <<'NODE' || \
     echo "  ⚠ could not record the plugin version — next run will reinstall (unknown version)" >&2
 const fs = require("fs");
 const path = require("path");
-const [, , file, host, root, version, installedAt] = process.argv;
+const [, , file, host, root, version, installedAt, installRoute] = process.argv;
 let data = { version: 2, platforms: {} };
 try {
   const existing = JSON.parse(fs.readFileSync(file, "utf8"));
@@ -354,6 +374,11 @@ const rec =
     ? data.platforms[host]
     : { root, skillsOwner: "plugin", skills: [] };
 rec.plugin = { version, installedAt };
+// installRoute is installer-owned (like plugin above); modelProfile is NEVER
+// written by any installer — the switch engine (packages/shared/src/
+// profile-switch/) is its sole writer (moot for Cursor in practice, since it
+// is always skipped, but the invariant holds repo-wide).
+rec.installRoute = installRoute;
 data.platforms[host] = rec;
 fs.mkdirSync(path.dirname(file), { recursive: true });
 fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@massa-ai/cursor-plugin",
-  "version": "1.25.0",
+  "version": "1.27.0",
   "description": "massa-ai plugin for Cursor — semantic code search, memory, and context compression",
   "files": [
     "agents",
+    "agent-profiles",
     "hooks",
     "skills",
     "install.sh",

package/skills/agents/judge/SKILL.md

@@ -4,7 +4,7 @@ description: Read-only debate-panel evaluator for judge-with-debate. Score an ar
 license: MIT
 metadata:
   author: S1LV4, luizgmassa
-  version: "1.0.0"
+  version: "1.1.0"
   model_tier: deep
   permission: read-only
 ---
@@ -83,12 +83,9 @@ next_step: <string>
 - References: `references/agent-orchestration.md`, `references/audit-report-io.md` (Judge With Debate Report Contracts).
 
 ## Model Hint
-This charter's `metadata.model_tier` (`deep`) is the fallback every host runs when dispatch-time
-model selection is unavailable. The `judge-with-debate` workflow additionally requests per-slot
-model diversity at dispatch time on hosts that support it — `workflows/judge-with-debate.md` is
-the single source for the current slot assignments, not this file. When dispatch-time selection
-is unavailable, every slot runs the charter default and the orchestrator records
-`DIVERSITY DEGRADED` per the workflow contract.
+See `references/agent-orchestration.md` (Model Diversity Fallback): `metadata.model_tier`
+(`deep`) is the per-slot fallback; `workflows/judge-with-debate.md` owns the live slot
+assignments.
 
 ## Validation Sensors
 - Every criterion score carries an exact quotation from the artifact.

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

@@ -4,7 +4,7 @@ description: Read-only evaluation-specification author for judge-with-debate. Ge
 license: MIT
 metadata:
   author: S1LV4, luizgmassa
-  version: "1.0.0"
+  version: "1.1.0"
   model_tier: deep
   permission: read-only
 ---
@@ -74,11 +74,8 @@ overall: weighted-mean
 - References: `references/agent-orchestration.md`, `references/audit-report-io.md` (Judge With Debate Report Contracts).
 
 ## Model Hint
-This charter's `metadata.model_tier` (`deep`) is the fallback every host runs when dispatch-time
-model selection is unavailable. The `judge-with-debate` workflow additionally requests a specific
-model for this slot at dispatch time on hosts that support it — `workflows/judge-with-debate.md`
-is the single source for the current assignment, not this file. When dispatch-time selection is
-unavailable, the orchestrator records a diversity warning per the workflow contract.
+See `references/agent-orchestration.md` (Model Diversity Fallback): `metadata.model_tier`
+(`deep`) is the fallback; `workflows/judge-with-debate.md` owns the live model assignment.
 
 ## Validation Sensors
 - Output parses as YAML; weights sum to 1.0 (±0.001); every criterion carries id, name, weight, scale (min 1, max 5), rubric anchors for 1/3/5, and a non-empty checklist.

package/skills/agents/navigator/SKILL.md

@@ -4,7 +4,7 @@ description: Code exploration specialist that leverages the massa-ai semantic in
 license: MIT
 metadata:
   author: S1LV4, luizgmassa
-  version: "1.0.0"
+  version: "1.1.0"
   model_tier: deep
   permission: read-only
   tools: mcp-index
@@ -16,7 +16,7 @@ metadata:
 Answer codebase questions through the massa-ai semantic index, reading files only once the index has narrowed the target to one to three of them.
 
 ## Core Principle
-The user's codebase is **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; massa-ai index queries are not.
+The user's codebase is **already indexed** by massa-ai. The first move on any question is to query the index, not read files blindly — file reads are expensive in context; massa-ai index queries are not.
 
 ## Responsibilities
 - Resolve the current project: run `pwd`, match the basename against `list_projects`.

package/skills/massa-ai/SKILL.md

@@ -312,22 +312,7 @@ Load only when a selected workflow asks for them:
 
 ## Graceful Degradation
 
-| Failure | Behavior |
-|---|---|
-| `recall` empty | Continue as cold start; do not invent memory. |
-| massa-ai server unavailable | Fall back to focused shell/file reads; keep session concept. |
-| Synapse unavailable | Continue with stateless search. |
-| Synapse prime/access mismatch | Use verified REST fallback or skip that optional step. |
-| index incomplete or stale | Use recall; skip search-dependent steps until ready. Graph tools (`trace_path`, `impact_analysis`, `get_architecture`) fall back to `search`/`get_references`; record reduced retrieval confidence. |
-| no meaningful memory | Say memory was intentionally skipped. |
-| memory write fails | Continue and report the unpersisted insight. |
-| `create_checkpoint` unavailable | Continue with `.specs/` artifact state as fallback. |
-| `handoff_begin` unavailable (`HANDOFFS_ENABLED=false`) | Fall back to `remember` + `.specs/` writes; record skipped handoff-table write. |
-| `bootstrap` unavailable | Proceed with manual `remember` calls. |
-| `compact_snapshot` unavailable | Continue with `compress` + `remember`; record skipped snapshot. |
-| code execution (`execute`/`execute_file`/`batch_execute`) unavailable | Load file into context instead; note the local-dev-only trust model still applies. |
-| `fetch_and_index` unavailable | Use native web fetch + manual indexing or skip external content. |
-| feedback reference unavailable | Continue without feedback lines; do not block the workflow. |
+On any tool/index/MCP failure (server unavailable, index incomplete, Synapse unavailable, `create_checkpoint`/`handoff_begin`/`bootstrap`/`compact_snapshot`/`execute`/`fetch_and_index` unavailable), load and follow `references/graceful-degradation.md` instead of blocking.
 
 ## Completion
 

package/skills/massa-ai/references/adr-authoring.md

@@ -1,6 +1,6 @@
 # ADR Authoring
 
-Use this reference from `workflows/adr.md`. It defines how massa-ai creates Architecture Decision Records without delegating orchestration to another ADR skill.
+Use from `workflows/adr.md`. Defines how massa-ai creates Architecture Decision Records without delegating orchestration to another ADR skill.
 
 ## Core Rule
 
@@ -15,9 +15,9 @@ Route matrix:
 | Direction is selected and implementation architecture/contracts/rollout need a blueprint | TDD |
 | Requirements, design, tasks, and execution all need staged approval | Spec-driven |
 
-Source relevance requires the source to name at least one target, constraint, risk, dependency, public contract, rejected option, decision owner, or rollout/rollback consequence for this ADR. Sources that provide only style or adjacent context are examples, not facts.
+Source relevance requires the source to name at least one target, constraint, risk, dependency, public contract, rejected option, decision owner, or rollout/rollback consequence for this ADR. Sources providing only style or adjacent context are examples, not facts.
 
-Do not guess. Missing source facts become questions, source gaps, or a workflow route change.
+Do not guess — missing source facts become questions, source gaps, or a workflow route change.
 
 ## Source Order
 

package/skills/massa-ai/references/agent-orchestration.md

@@ -1,6 +1,6 @@
 # Agent Orchestration
 
-Use this reference when a workflow benefits from isolated context, parallel work, or independent verification.
+Use when a workflow benefits from isolated context, parallel work, or independent verification.
 
 Load `references/context-firewall.md` first when the delegated work may involve verbose logs, snapshots, generated reports, external research, or broad source inspection.
 
@@ -23,7 +23,7 @@ Subagents do bounded work only. Do not delegate everything.
 
 Tokens are spent once; context shapes every decision that follows. The orchestrator's
 working memory is the asset every rule below protects — delegation exists to keep
-disposable reasoning out of the main thread, not only to parallelize.
+disposable reasoning out of the main thread, not just to parallelize.
 
 - **Never poll a running subagent for status, and never ingest a subagent's raw
   transcript, JSONL, or intermediate reasoning — running or completed.** The
@@ -98,6 +98,21 @@ installed, spawning forbidden by platform policy, or the host returns an unknown
 delegated scope locally against the same output contract, and report the skipped
 delegation with its reason in the Evidence Gate.
 
+## Model Diversity Fallback
+
+Applies to any charter whose `metadata.model_tier` is a fallback and whose
+dispatching workflow additionally requests per-invocation model diversity at
+dispatch time (e.g. `judge` — 3 parallel slots; `meta-judge` — one slot).
+
+- The charter's `metadata.model_tier` is the fallback every host runs when
+  dispatch-time model selection is unavailable.
+- The dispatching workflow (e.g. `workflows/judge-with-debate.md`) is the
+  single source for the current slot/model assignment, not the charter file.
+- When dispatch-time selection is unavailable, every affected slot runs the
+  charter default, and the orchestrator records `DIVERSITY DEGRADED`
+  (multi-slot) or an equivalent diversity warning (single-slot) per the
+  dispatching workflow's own contract.
+
 ## Roles
 
 Use the role names in prompts and memory tags; use the host agent names to

package/skills/massa-ai/references/architecture-coupling-lens.md

@@ -1,6 +1,6 @@
 # Architecture Coupling Lens
 
-Use this detail reference when an architecture audit or execution task needs dependency health, dependency direction, integration cost, or coupling reduction.
+Use when an architecture audit or execution task needs dependency health, dependency direction, integration cost, or coupling reduction.
 
 ## Contents
 

package/skills/massa-ai/references/architecture-deepening-lens.md

@@ -1,6 +1,6 @@
 # Architecture Deepening Lens
 
-Use this detail reference when an architecture audit or execution task needs module depth, seams, adapters, testability, locality, or AI-navigability analysis.
+Use when an architecture audit or execution task needs module depth, seams, adapters, testability, locality, or AI-navigability analysis.
 
 ## Contents
 

package/skills/massa-ai/references/architecture-domain-lens.md

@@ -1,6 +1,6 @@
 # Architecture Domain Lens
 
-Use this detail reference when an architecture audit or execution task needs domain boundaries, bounded contexts, subdomain classification, ubiquitous language, or cohesion analysis.
+Use when an architecture audit or execution task needs domain boundaries, bounded contexts, subdomain classification, ubiquitous language, or cohesion analysis.
 
 ## Contents
 

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

@@ -1,6 +1,6 @@
 # Architecture Lenses
 
-Use this reference for architecture audits, architecture-focused reviews, and refactor planning. It is the shared index and vocabulary guard; load the detail references only when a workflow needs that lens:
+Use for architecture audits, architecture-focused reviews, and refactor planning. Shared index and vocabulary guard; load the detail references only when a workflow needs that lens:
 
 - `references/architecture-domain-lens.md` for bounded contexts, ubiquitous language, subdomain classification, cohesion, and integration patterns.
 - `references/architecture-coupling-lens.md` for dependency graphs, strength/distance/volatility, dependency direction, and contract health.

package/skills/massa-ai/references/audit-report-io.md

@@ -1,6 +1,6 @@
 # Audit Report I/O
 
-Use this reference from audit workflows before writing reports and from execution workflows before report-driven changes.
+Use from audit workflows before writing reports and from execution workflows before report-driven changes.
 
 ## Report Paths
 
@@ -557,10 +557,40 @@ Before editing:
 
 - Verify workflow, project, target, target focus, scope, base/head, and resolved files match the current request.
 - Reinspect each finding's current location and evidence. Stop or re-audit when schema v2 drift rules invalidate any selected finding.
-- Verify every finding has common and workflow-specific fields plus the correct ID form.
+- Verify every finding has common and workflow-specific fields plus the correct ID form (deterministic backing below).
 - For implementation reports, require source-qualified IDs and child-lens fields.
 - For mobile Figma reports, re-read the Figma node and reject stale design/source/configuration evidence.
 - Ignore ruled-out candidates, skipped checks, no-finding summaries, `NOT EVALUATED` rows, constraint deviations, and low-confidence suspects unless the user explicitly changes scope after revalidation.
 - Build verification from report suggestions plus current project sensors.
 
 Do not execute from chat summaries, inline comments, screenshots alone, or remembered audit content. The saved markdown report is the source of truth.
+
+## Deterministic Validation
+
+`skills/massa-ai/scripts/validate_audit_report.ts` replaces the model-run
+metadata/ID checklist with a scripted check, run before any `*-fix` workflow
+edits code:
+
+```bash
+bun skills/massa-ai/scripts/validate_audit_report.ts <path-to-report.md> --family <family>
+```
+
+`--family` is one of `architecture`, `bugs`, `code-quality`, `security`,
+`requirements`, `tests`, `maestro`, `mobile-figma`, or `implementation`
+(auto-detected from the report's `Workflow:` field when omitted). It checks:
+
+- required freshness-header metadata fields for that family (common fields
+  plus family-specific extras — `Requirements Source` for single-lens and
+  implementation reports; `Scenario Source`/`Maestro CLI`/`Device/Emulator
+  Readiness` for Maestro; the mobile Figma identity fields for Mobile Figma)
+- finding-ID format (`PREFIX-N`, or `<Area>/<PREFIX>-N` for the
+  implementation composite family)
+- Area<->Prefix table membership for implementation reports (rejects an
+  unrecognized Area, a mismatched Area/Prefix pair, and any raw `SONAR-*`
+  executable ID)
+- finding-ID uniqueness and gap-free per-prefix/per-area sequencing
+
+A non-zero exit blocks editing. The script does **not** re-check drift
+against current source, table-structure presence (Target Surface Matrix,
+Maestro Run Matrix, etc.), or Figma-node freshness — those stay a manual
+step per the "Before editing" list above.