@massa-ai/cursor-plugin 1.22.0 → 1.24.0

package/.cursor-plugin/plugin.json

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

package/package.json

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

package/skills/massa-ai/SKILL.md

@@ -60,6 +60,14 @@ Before reading any massa-ai file:
 - Persist only durable, useful knowledge. Do not fabricate memories to satisfy
   process. Use `memory_update` to correct stale memories and `memory_delete`
   to remove obsolete ones.
+- Expand every word abbreviation on first use in user-facing output — e.g.
+  "PR (Pull Request)", "AC (Acceptance Criteria)", "KMP (Kotlin Multiplatform)"
+  — including workflow-specific shorthands and finding-ID families.
+- Use one uniform vocabulary for separating batches of work in every workflow:
+  a **Task** is the atomic unit; a **Phase** is an ordered group of Tasks.
+  Report a phase's size as `1 Phase = X Tasks` and a plan's total as
+  `Y Phases = Z Tasks`. Do not substitute synonyms such as batch, wave, stage,
+  or chunk for these units in agent prose.
 - Emit concise user-facing status updates at meaningful workflow boundaries
   when the Conversation Feedback Policy is active.
 - Verify, don't assume: every factual claim that drives a decision is
@@ -275,6 +283,7 @@ Load only when a selected workflow asks for them:
 - `references/debug-diagnosis-loop.md`
 - `references/mobile-context.md`
 - `references/mobile-diagnosis.md`
+- `references/figma-pre-analysis.md`
 - `references/mobile-figma-matcher/`
 - `references/lessons.md`
 - `references/naming-standards.md`

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

@@ -19,6 +19,32 @@ The main agent is the orchestrator. It owns:
 
 Subagents do bounded work only. Do not delegate everything.
 
+## Orchestrator Working Memory
+
+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.
+
+- **Never poll a running subagent for status, and never ingest a subagent's raw
+  transcript, JSONL, or intermediate reasoning — running or completed.** The
+  orchestrator consumes only the subagent's returned output contract (its completion
+  result). When lifecycle visibility helps the user, report the dispatch itself via
+  conversation-feedback labels, not by fetching agent state.
+- **Wave cap: dispatch at most 4 concurrent subagents.** Before planning 5 or more,
+  run and record a consolidation check — can any two planned agents be merged? — then
+  dispatch in waves of at most 4. Fixed protocols smaller than the cap (e.g. a
+  3-judge panel) are unaffected.
+- **Cognitive locality:** overlapping file/module ownership or a shared knowledge
+  domain between planned subagents — read-only agents included — is a consolidation signal:
+  consolidate into one agent before spawning. Two agents independently reconstructing
+  the same mental model is waste; one agent holding it once is the cheaper and more
+  coherent shape.
+- **Git safety for concurrent work:** no repository-wide git operations (`git stash`,
+  `git checkout`/`git switch` of shared state, `git reset`, `git clean`) inside any
+  concurrently-dispatched subagent's scope. Concurrent writers require disjoint git
+  worktrees. The Verifier's scratch-worktree discrimination sensor keeps its own
+  stricter isolation rules.
+
 ## Delegation Gates
 
 Delegate only when all base requirements are true and at least one dispatch trigger is true.
@@ -107,19 +133,27 @@ only, never a dispatch target.
 
 ## Capability Packet
 
+**This section is the sole canonical Capability Packet definition.** `references/subagent-design.md` and the root `skills/AGENTS.md` registry defer to or mirror this list; `scripts/__tests__/capability-packet-parity.test.ts` fails when the `skills/AGENTS.md` mirror diverges. Bespoke packets (judge panel, FURPS analyst, phase-batch worker) are declared specializations that map onto these fields in their own workflow files.
+
+**A subagent inherits nothing from the parent session** — no skills, no personas, no loaded references, no conversation history. Everything the subagent needs is named explicitly in the packet, including the exact reference file paths it must read itself.
+
 When dispatching a subagent, send a compact capability packet rather than a loose instruction. Include:
 
-- role and purpose for this workflow
-- trigger: why delegation is justified now
-- exact scope: files, modules, diff, report finding, task IDs, or artifact
-- permissions: read-only or write with disjoint ownership
-- inputs: recalled facts, source pointers, constraints, and exclusions
-- sensors: expected commands or concrete checks
-- output: the exact output contract
-- firewall: raw logs, diffs, snapshots, reports, or research that must be summarized
-- memory boundary: whether the subagent may suggest memories and who persists them
+- `role`: the role name from the Agent Table of `skills/AGENTS.md`
+- `purpose`: one sentence tied to this workflow
+- `trigger`: why delegation is justified now
+- `scope`: exact files, modules, diff, report finding, task IDs, or artifact
+- `permissions`: read-only or write with disjoint ownership
+- `inputs`: recalled facts, source pointers, constraints, and exclusions
+- `sensors`: expected commands or concrete checks
+- `output`: the exact output contract
+- `firewall`: raw logs, diffs, snapshots, reports, or research that must be summarized
+- `memory`: whether the subagent may suggest memories and who persists them
 - `persona`: optional. The cataloged persona id in effect for the parent conversation, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions. Pass the id alone, never the persona prompt.
-- exact next step: what the main agent should do with the result
+- `next_use`: what the main agent will do with the result
+- `lens`: conditional — `audit-specialist` dispatches only. One of `bugs | architecture | security | requirements | code-quality | performance`.
+
+The named dispatch block that workflows embed (the quoted block whose header carries the prefixed agent name and role) is the block projection of this packet: `role` and `purpose` live in the block's header line, and `next_use` defaults to "the main agent synthesizes and continues the workflow" when absent. The remaining eight fields — `trigger, scope, permissions, inputs, sensors, output, firewall, memory` — appear as the block's body lines. The optional `persona` field appears there too.
 
 ## Prompt Contract
 
@@ -154,6 +188,11 @@ Subagents must summarize verbose research, logs, snapshots, diffs, search output
 and transcripts. The main agent should receive only evidence, findings, risk,
 skipped checks, memory suggestions when allowed, and the next step, not raw dumps.
 
+**Default return bound: at most 40 lines of returned chat text.** A dispatch block's
+`output:` field may override the bound with a stated reason. When a dispatch writes a
+persisted report file, the chat return is the compact verdict only — never the file
+body (dual-channel rule).
+
 ## Conversation Feedback
 
 Use `references/conversation-feedback.md` when subagent lifecycle visibility would help the user understand what is running. Keep status updates to 1-2 human-readable lines.
@@ -222,6 +261,8 @@ For delegated tasks that expect repeated searches:
 
 ## Guardrails
 
+- No polling, no transcripts: never poll a running subagent and never ingest its
+  transcript or intermediate reasoning — see Orchestrator Working Memory.
 - No self-evaluation: claims need deterministic sensors or concrete source evidence.
 - No hidden scope expansion: subagents must not improve adjacent code.
 - No context dragging: send only task-specific source pointers and constraints, and receive compact summaries only.

package/skills/massa-ai/references/context-firewall.md

@@ -29,6 +29,7 @@ Apply the firewall before bringing any of these raw artifacts into the main cont
 - Source, docs, logs, CSV, or reports over 200 lines or 20 KB.
 - Search, grep, MCP, or external research output over 50 hits.
 - Generated audit reports, screenshots, browser snapshots, crash/device logs, or raw NotebookLM/web research dumps.
+- Running or completed subagent transcripts, JSONL session files, and intermediate agent reasoning — these never enter the main context at all; consume only the returned output contract.
 - Any subagent output, tool transcript, or diff where only counts, paths, representative snippets, or failing cases are needed for the next decision.
 
 ## Tool Output Discipline
@@ -53,7 +54,7 @@ The main agent receives only:
 - risks and skipped checks
 - exact next step
 
-Subagents should not return raw dumps. The main agent still owns memory recall, persistence, synthesis, and the final Evidence Gate.
+Subagents should not return raw dumps. Never poll a running subagent for status and never read a subagent transcript — the returned output contract is the only channel back into the main context (canonical rules: `references/agent-orchestration.md`, Orchestrator Working Memory). The main agent still owns memory recall, persistence, synthesis, and the final Evidence Gate.
 
 ## Persistence Boundary
 

package/skills/massa-ai/references/figma-pre-analysis.md

@@ -0,0 +1,69 @@
+# Figma Pre-Analysis And Sequential Retrieval
+
+Load this reference whenever a workflow receives one or more Figma links, node
+IDs, or a readable desktop selection as a design source — the Figma audit/fix
+family (`mobile-figma-audit`, `mobile-figma-fix`), `design`, and the
+design-source gates of implementation workflows (`feature`, `spec-driven`).
+This reference owns the orchestration protocol only; Figma Evidence Packet
+field contracts stay in `references/mobile-figma-matcher/core.md`.
+
+The protocol is the single normative copy. Workflows point here; they do not
+restate it.
+
+## Why Two Stages
+
+Full Figma extraction on unscoped links overloads one context with mixed
+screens, buries feature boundaries, and makes evidence non-attributable. A
+cheap pre-analysis pass first maps what the links contain, so each retrieval
+pass reads one coherent slice.
+
+## Stage 1 — Pre-Analysis (always first, exactly one subagent)
+
+Dispatch one read-only subagent (investigator-class; Figma MCP — Model Context
+Protocol — access, no repository mutation) over the user-provided Figma links.
+Its job is understanding, **not** extraction:
+
+- Summarize composition: pages, screens, frames, component sets, shared tokens.
+- Summarize product context: what the screens are for, the features they serve,
+  and the user flows connecting them.
+- It does not build Figma Evidence Packet fields, does not resolve variables or
+  exact geometry, and does not compare against source code.
+
+Its output is a compact packet:
+
+1. **Context summary** — screens/features/flows in prose, sized for the main
+   agent's context budget.
+2. **Partition proposal** — how many retrieval subagents should read which
+   links/nodes/screen groups, partitioned by:
+   - **Size:** each slice must fit one subagent's context comfortably.
+   - **Coupling:** screens sharing tokens, components, or a design system
+     section stay in one slice.
+   - **Feature flow:** one user flow per slice when possible, so evidence
+     stays attributable to a feature.
+   A single small screen legitimately yields a one-slice proposal.
+
+The main agent reviews the proposal, adjusts slice boundaries if project
+knowledge contradicts them, and records the final partition before Stage 2.
+
+## Stage 2 — Sequential Retrieval (N subagents, one at a time)
+
+The main agent orchestrates the retrieval subagents **strictly sequentially —
+never in parallel**. For each slice, in the recorded order:
+
+1. Dispatch one read-only retrieval subagent scoped to that slice's
+   links/nodes, carrying the Stage 1 context summary and the slice's purpose.
+2. Wait for completion; fold its output into the workflow's Figma Evidence
+   Packet (or Screenshot Context Packet rows) before dispatching the next.
+3. Let each completed slice inform the next dispatch prompt — resolved shared
+   tokens, discovered variants, and naming conventions carry forward.
+
+Sequential dispatch is a hard rule, not a tuning choice: it respects Figma MCP
+session/rate limits, and it is what lets slice N+1 reuse what slice N learned.
+Retrieval subagents never spawn further subagents.
+
+## Fallback
+
+If subagent spawning is unavailable (forbidden, plugin missing, unknown agent
+type), run both stages inline in the main agent in the same order — pre-analysis
+summary first, then per-slice retrieval — and record the skipped delegation
+with its reason. Do not skip Stage 1 because delegation is unavailable.

package/skills/massa-ai/references/implementation-delivery.md

@@ -90,6 +90,18 @@ title: `[SA-100] Phase 1: search facade split`. The per-task commit prefixes on
 the branch are owned by `workflows/commit.md`; this stage owns only the PR-level
 phase prefix. Non-phased work keeps the existing PR title behavior unchanged.
 
+### Stages 3–7 — the PR description stays current
+
+The PR description is a living artifact, not a creation-time snapshot. After
+**every push requested while the PR exists** — repair iterations, follow-up
+tasks, review-requested changes — update the PR description with
+`gh pr edit <number> --body <b>` so it reflects the branch's current commit
+set, scope, and evidence **before** returning to Watch. The description must be
+current before the merge decision is requested; a merge may never be proposed
+over a description that describes an older state of the branch. When generated
+or bundled files are regenerated alongside source edits, the description names
+that blast radius explicitly so reviewers do not undercount the diff.
+
 ### Stage 7 — merge is never automatic
 
 Do not run `gh pr merge` without explicit user approval given in the current
@@ -126,6 +138,8 @@ silently did not run is worse than one that loudly failed.
 - Merging because CI passed. CI passing is the precondition for asking, not the
   approval itself.
 - Reporting "done" while the branch is unpushed.
+- Proposing or performing a merge while the PR description still describes an
+  older commit set — update it after each requested push, before merging.
 
 ## Completion Evidence
 

package/skills/massa-ai/references/mobile-context.md

@@ -76,6 +76,25 @@ For design, mobile Figma audit, or mobile Figma fix, load `references/mobile-fig
 
 Never rely on model self-evaluation. If device access, signing, credentials, provisioning, or hardware is unavailable, state the missing dependency and use the strongest available artifact or static proof.
 
+## Compose Screen Previews
+
+In every implementation workflow, when the target surface is Android Jetpack
+Compose or KMP (Kotlin Multiplatform) Compose Multiplatform, every created or
+updated screen-level composable ships with `@Preview` composables in the same
+change:
+
+- Cover the representative states the change touches (default content, loading,
+  error, and empty where they exist), using preview parameter providers when
+  the project already uses them.
+- Follow the project's existing preview conventions (naming, placement,
+  multipreview annotations, theme wrappers) rather than inventing new ones.
+- Previews are validation assets: never delete or weaken an existing preview to
+  make a change compile, and treat a screen edit that leaves its previews stale
+  as incomplete work.
+- On KMP, place previews in the source set where the project renders them
+  (commonMain multiplatform previews or per-platform preview hosts), matching
+  established project layout.
+
 ## Tests Lens
 
 When auditing or executing test work, check mobile-specific coverage for:

package/skills/massa-ai/references/mobile-diagnosis.md

@@ -4,7 +4,7 @@ Use this reference when `workflows/debug.md` handles broken behavior involving K
 
 This extends `references/debug-diagnosis-loop.md`. Do not use it instead of the general debug loop.
 
-For non-debug mobile feature, refactor, tests, or security work, keep the intent-specific workflow and load `references/mobile-context.md` instead. Use `references/mobile-context.md` from Debug only when shared mobile vocabulary or non-bug parity/security/test framing is needed.
+For non-debug mobile feature, refactor, tests, or security work, keep the intent-specific workflow and load `references/mobile-context.md` instead. Use `references/mobile-context.md` from Debug only when shared mobile vocabulary or non-bug parity/security/test framing is needed — and always when a fix creates or updates a Compose screen, because its Compose Screen Previews rule (`@Preview` coverage) applies to debug-path edits too.
 
 ## Mobile Intake
 

package/skills/massa-ai/references/spec-driven/sub-agents.md

@@ -55,6 +55,16 @@ Batches run strictly sequentially: a batch never starts until the previous batch
 - `references/spec-driven/coding-principles.md`
 - Relevant `spec.md`, `context.md`, and `design.md` sections for the feature (not all specs)
 
+This worker payload is a specialization of the canonical Capability Packet in
+`references/agent-orchestration.md`: the task definitions and spec/design sections are
+its `scope` + `inputs`, the Gate Check Commands are its `sensors`, the structured
+return contract below is its `output`, and write permission is scoped to the batch's
+disjoint task files. Workers inherit nothing from the parent session — every needed
+reference is listed above by path. Inside a worker, repository-wide git operations
+(`git stash`, shared-state `git checkout`/`switch`, `git reset`, `git clean`) are
+prohibited; the only git surface a worker touches is the defined task cycle's atomic
+commits in the feature worktree.
+
 **What a batch worker does:**
 
 Executes ALL tasks in its assigned batch **in order** — finishing every task in one phase before starting the next phase in the batch — following the `references/spec-driven/execute.md` cycle for each task (implement → gate → atomic commit). It does NOT spawn further sub-agents. After completing all tasks in the batch, the worker reports a **compact summary** to the orchestrator using the structured return contract:
@@ -76,6 +86,12 @@ No raw logs, no full test output — only the above fields keep the main context
 
 **No nesting:** Batch workers execute their tasks themselves. They never spawn sub-sub-agents. Execution is strictly sequential within and across batches — there is no intra-phase or intra-batch parallelism.
 
+**Orchestrator context discipline:** the orchestrator consumes only the compact
+summary above. It must never read a worker's transcript, JSONL, or intermediate
+reasoning, and must never poll a running worker for status — the summary at batch
+completion is the only channel back (see `references/agent-orchestration.md`,
+Orchestrator Working Memory).
+
 ## Delegation Activity Table
 
 The batching trigger above governs **when** batch workers are offered. This table governs **what** may be delegated at all. Delegation is activity-scoped, not blanket.
@@ -118,6 +134,12 @@ Delegated work returns through the compact summary contract above. Planning, tas
 - The test files in scope
 - `references/spec-driven/validate.md` as its operating checklist
 
+This payload is a specialization of the canonical Capability Packet
+(`references/agent-orchestration.md`): spec + diff + tests are its `scope`/`inputs`,
+`validate.md` is its `sensors` source, the compact verdict + `validation.md` report
+below are its dual-channel `output`, and `permissions` are read-only outside the
+scratch sensor state.
+
 **What the Verifier does (full process in `validate.md`):**
 
 1. **Spec-anchored coverage check** — re-derives coverage evidence-or-zero: every AC traced to `file:line` + assertion expression. For each covered criterion, confirms the test's asserted value matches the **spec-defined expected outcome** (not just that an assertion exists). Where the spec does not define a precise outcome, flags a **spec-precision gap** rather than passing silently.

package/skills/massa-ai/references/subagent-design.md

@@ -91,19 +91,24 @@ Memory boundary:
 
 ## Capability Packet
 
-When a workflow dispatches a reusable role, send a capability packet rather than a loose instruction. The packet should include:
-
-- `role`: the role name from `agent-orchestration.md`
-- `purpose`: one sentence tied to this workflow
-- `trigger`: why delegation is justified now
-- `scope`: exact files, modules, diff, report finding, or task IDs
-- `permissions`: read-only or write with disjoint write set
-- `inputs`: recalled facts, source pointers, task/report IDs, constraints, and exclusions
-- `sensors`: commands or concrete checks expected
-- `output`: the exact output contract
-- `firewall`: raw logs, diffs, snapshots, or research that must be summarized
-- `memory`: whether the subagent may suggest memory and who persists it
-- `persona`: optional. The cataloged persona id in effect for the parent conversation, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions. Pass the id alone, never the persona prompt.
+**The packet field list lives in one place: `references/agent-orchestration.md`,
+§Capability Packet.** Do not restate it here — a second copy is what let the field
+sets drift into three diverging shapes before the canonical section existed. When a
+workflow dispatches a reusable role, send that canonical packet rather than a loose
+instruction.
+
+The one field this reference still names on its own is `persona`, because a
+persona-agent-boundary guard (`.specs/features/persona-agent-boundary/spec.md`)
+checks its clause byte-for-byte in every packet-defining file, this one included:
+
+`persona`: optional. The cataloged persona id in effect for the parent conversation, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions. Pass the id alone, never the persona prompt.
+
+Design-time additions this reference owns: a new role's charter must be expressible
+as that packet (if a role needs fields the canonical list cannot carry, the role is
+mis-scoped — split it or fix the charter, do not grow a bespoke packet silently), and
+any deliberate bespoke specialization (judge panel, FURPS analyst, phase-batch
+worker) must declare itself a specialization in its own workflow file and map its
+fields onto the canonical ones from `agent-orchestration.md`.
 
 ## Quality Checklist
 

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

@@ -9,7 +9,7 @@ Before the first repository mutation, load `references/implementation-delivery.m
 Do not use this workflow for Flutter, React Native, web UI, generic Figma exploration, variable-only queries, or MCP troubleshooting.
 
 1. Resolve/reuse `workflowSessionId`: `design-[entity]`.
-2. Load `references/mobile-figma-matcher/repository-detection.md`, `references/mobile-figma-matcher/core.md`, `references/mobile-context.md`, `references/codebase-investigation.md`, and `references/verification-ladder.md`. Load `references/context-firewall.md` before large design/runtime artifacts and `references/synapse-policy.md` when repeated massa-ai searches are expected.
+2. Load `references/mobile-figma-matcher/repository-detection.md`, `references/mobile-figma-matcher/core.md`, `references/mobile-context.md`, `references/codebase-investigation.md`, and `references/verification-ladder.md`. When Figma links or node IDs are provided, load `references/figma-pre-analysis.md` and run its two-stage sequential retrieval protocol before building the Figma Evidence Packet. Load `references/context-firewall.md` before large design/runtime artifacts and `references/synapse-policy.md` when repeated massa-ai searches are expected.
 3. `recall` -> load current component conventions, design-system rules, approved platform/accessibility deviations, prior Figma mappings, asset pipelines, and reusable render recipes. Memory is context, not proof.
 4. Require a concrete feature/module target plus at least one design source: readable Figma node/selection or supplied screenshots. Resolve required visual and interactive states plus a requirements source for behavior not represented in the design source. Ask only when target ownership, runtime platforms, platform-frame mappings, or screenshot authority remain ambiguous after source inspection.
 5. Build the immutable Target Surface Packet before loading stack guidance. Classify each selected surface and load only its contracts:

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

@@ -22,7 +22,7 @@ Before the first repository mutation, load `references/implementation-delivery.m
    - Ask for one or more Figma links, node IDs, a readable desktop selection, supplied screenshots, or explicit `none`.
    - Do not ask for clear backend, CLI, docs, infrastructure, or non-UI work.
    - Treat `none` as a first-class answer. Record `Figma Source: none by user choice` and do not re-ask unless the mobile UI scope changes.
-   - If Figma sources or screenshots are supplied for supported Android, iOS, or KMP Compose Multiplatform UI implementation/update work, keep this workflow as the parent and invoke `workflows/design.md` for the affected UI slice.
+   - If Figma sources or screenshots are supplied for supported Android, iOS, or KMP Compose Multiplatform UI implementation/update work, keep this workflow as the parent and invoke `workflows/design.md` for the affected UI slice. When Figma links or node IDs are supplied, load `references/figma-pre-analysis.md` and run its two-stage sequential retrieval protocol before consuming the design evidence.
    - Preserve mobile Figma routing by intent: compare/audit wording uses `workflows/mobile-figma/mobile-figma-audit.md`; saved `MFM-*` findings use `workflows/mobile-figma/mobile-figma-fix.md`.
    - If Figma sources are supplied for unsupported targets such as Flutter, React Native, web, desktop, or generic design exploration, do not run mobile Figma. Record that the Figma source is outside mobile Figma scope and continue the normal feature workflow.
    - Figma defines visible design intent and represented variants only. Screenshots are context-only unless paired with structured Figma evidence; do not claim exact Figma parity, tokens, variables, or dimensions from screenshots alone. Product behavior not represented by the design source still requires a separate requirements source.

package/skills/massa-ai/workflows/judge-with-debate.md

@@ -63,6 +63,21 @@ the capability, per-slot diversity activates automatically with no harness edit.
 Dispatch `massa-ai-meta-judge` (read-only) with the task description, artifact type, context,
 and artifact paths. Model request: `kimi-k3` (see Step 0.5).
 
+> **Dispatch: `massa-ai-meta-judge`** (role: `meta-judge`) — charter `skills/agents/meta-judge/SKILL.md`
+> - trigger: judge-with-debate Step 1; runs exactly once per evaluation
+> - scope: the artifact under evaluation (paths supplied), task description, artifact type
+> - permissions: read-only
+> - inputs: task description, artifact type, context, artifact paths, model request per Step 0.5; inherits nothing — every needed path is named here
+> - sensors: two-stage validation below (syntactic YAML, weights sum 1.0 ± 0.001, semantic shape)
+> - output: the evaluation-specification YAML, returned verbatim for all rounds; nothing else
+> - firewall: no artifact body quotes beyond what the rubric anchors need; no raw dumps
+> - memory: suggest-only; main agent persists
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
+This packet is a specialization of the canonical Capability Packet
+(`references/agent-orchestration.md`): the spec YAML is its `output` contract; the
+two-stage validation is its `sensors`.
+
 Validate the returned evaluation specification in two stages, in order; a retry names the
 **first failed check** and nothing else:
 
@@ -83,8 +98,24 @@ then `🤖 [Agent Done]` or `🤖 [Agent Blocked]` with the one-line reason.
 
 Dispatch three `massa-ai-judge` agents **in parallel** (round 0), one per judge number, each
 with: the verbatim specification YAML, task description, artifact paths, its own report path,
-`round: 0`, and its model request (Step 0.5). Each judge writes its own
-`audits/judge/<...> judge-N.md` per the report contract and returns the reply block:
+`round: 0`, and its model request (Step 0.5). The fixed panel of 3 sits inside the wave cap of
+4 concurrent subagents (`references/agent-orchestration.md`, Orchestrator Working Memory).
+Each judge writes its own `audits/judge/<...> judge-N.md` per the report contract and returns
+the reply block:
+
+> **Dispatch: `massa-ai-judge`** (role: `judge`) — charter `skills/agents/judge/SKILL.md` — 3 per panel, rounds 0..3
+> - trigger: judge-with-debate Steps 2 and 4; panel of exactly 3, never more
+> - scope: the artifact under evaluation, the verbatim specification YAML, own report path; debate rounds add all three report paths as peer paths and `round: R`
+> - permissions: read-only except appending to its own judge-N report file
+> - inputs: verbatim spec YAML, task description, artifact paths, own report path, round number, model request; debate rounds add peer report paths; inherits nothing — judges read peer reports from the filesystem paths supplied
+> - sensors: reply-block shape below (malformed or missing `scores` counts as `contest`; same judge malformed twice → Blocked)
+> - output: the YAML reply block below (strengths/weaknesses capped at ≤3 items); report file is the persisted channel — dual-channel rule, the chat return never carries the report body
+> - firewall: quoted evidence snippets only; no artifact or peer-report dumps in the reply
+> - memory: suggest-only; main agent persists
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
+This packet is a specialization of the canonical Capability Packet
+(`references/agent-orchestration.md`); the per-round additions are its `inputs` deltas.
 
 ```yaml
 status: Complete | Partial | Blocked

package/skills/massa-ai/workflows/mobile-figma/mobile-figma-audit.md

@@ -10,6 +10,7 @@ Do not edit code. Route direct design implementation to `design`. Do not use thi
 2. Load shared references:
    - `references/mobile-figma-matcher/repository-detection.md` before platform guidance.
    - `references/mobile-figma-matcher/core.md` for Figma, assets, mapping, comparison, Maestro, and claim contracts.
+   - `references/figma-pre-analysis.md` when Figma links or node IDs are provided — run its two-stage sequential retrieval protocol before Figma extraction.
    - `references/mobile-context.md` for mobile boundaries, parity, and verification context.
    - `references/audit-scope.md` for target resolution and freshness.
    - `references/audit-report-io.md` before producing the report.

package/skills/massa-ai/workflows/mobile-figma/mobile-figma-fix.md

@@ -12,6 +12,7 @@ Do not execute from chat summaries, screenshots alone, remembered findings, or a
 2. Load shared references:
    - `references/mobile-figma-matcher/repository-detection.md` before platform guidance.
    - `references/mobile-figma-matcher/core.md` for Figma, assets, mapping, Maestro, matrix, and claim contracts.
+   - `references/figma-pre-analysis.md` when the findings span multiple Figma links or nodes — run its two-stage sequential retrieval protocol for the re-read.
    - `references/lessons.md` to load confirmed project lessons
    - `references/mobile-context.md` for mobile boundary and verification guidance.
    - `references/audit-report-io.md` before any source or validation-asset edit.

package/skills/massa-ai/workflows/refinement/furps-refinement.md

@@ -33,7 +33,20 @@ This workflow is findings-only. Do not edit the PRD/ADR unless the user separate
    - Dispatch six `massa-ai-furps-analyst` sub-agents: F, U, R, P, S, X (X = FURPS+ Extensions).
    - Each receives its `checklist.md` section, the bounded document packet, the DoR, and the Fool summary.
    - Each returns per check-item status (`covered|partial|missing|unclear`), `FR-<letter>-<N>` findings, and contributions to Open Questions / Suggestions / Insights / Risks / DoR-gaps.
-   - Run in parallel; batch if a concurrency cap applies. Each gets its own ephemeral Synapse session only if it performs >=2 searches.
+   - Dispatch the six dimensions in waves of at most 4 concurrent analysts (e.g. 4 then 2), per the wave cap in `references/agent-orchestration.md` (Orchestrator Working Memory). Dimension analyses are order-independent, so wave order does not matter. Each gets its own ephemeral Synapse session only if it performs >=2 searches.
+
+> **Dispatch: `massa-ai-furps-analyst`** (role: `furps-analyst`) — charter `skills/agents/furps-analyst/SKILL.md` — 6 dispatches, one per dimension, waves of ≤4
+> - trigger: furps-refinement step 5; one analyst per FURPS+ dimension (F, U, R, P, S, X)
+> - scope: exactly one dimension's `checklist.md` section against the bounded document packet
+> - permissions: read-only
+> - inputs: the dimension's checklist section, bounded document packet, DoR, Fool summary; inherits nothing — the packet names every artifact
+> - sensors: per check-item status must be one of `covered|partial|missing|unclear`; findings carry `FR-<letter>-<N>` IDs
+> - output: per check-item statuses, findings, and Open Questions / Suggestions / Insights / Risks / DoR-gap contributions — compact structured return, no document quotes beyond evidence snippets
+> - firewall: document bodies summarized; no raw section dumps in the return
+> - memory: suggest-only; main agent persists
+> - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
+
+   This packet is a specialization of the canonical Capability Packet (`references/agent-orchestration.md`); the per-dimension checklist section is its `scope` delta.
 6. Synthesis (main):
    - Collect the six dimension analyses and the Fool summary.
    - Deduplicate, cross-check, and reconcile cross-dimension concerns (e.g., error flows span F3+R2+U1; components span F2+S2).
@@ -55,7 +68,7 @@ This workflow is findings-only. Do not edit the PRD/ADR unless the user separate
 | Sub-agent spawning unavailable | Run dimensions sequentially in the main agent; record the skipped-delegation reason |
 | DoR not supplied | Use the built-in fallback; mark DoR-gaps explicitly |
 | Document too large | context-firewall: section summaries plus pointers to sub-agents |
-| Concurrency cap on six FURPS agents | Batch dispatch; preserve order-independence |
+| Host concurrency cap tighter than the wave cap of 4 | Smaller waves; preserve order-independence |
 
 ## Examples
 

package/skills/massa-ai/workflows/spec-driven.md

@@ -40,7 +40,7 @@ Complexity determines depth, not a fixed pipeline. Assess scope first, apply onl
 | Large | >10 tasks OR multi-component feature | Full spec + requirement IDs | Architecture + components | Full breakdown + deps | Implement + verify per task |
 | Complex | Ambiguity or new domain (unfamiliar vocabulary, no prior pattern) | Full spec + discuss gray areas | Research + architecture | Breakdown + phase plan | Implement + interactive UAT |
 
-A "phase" is a group of tasks sharing a dependency boundary or a checkpoint commit — it is distinct from a single task or atomic step. The sub-agent offer fires when a formal `tasks.md` has more than 3 tasks — packing itself still uses ~7-task batches; a 4–8-task feature is offered as a single batch worker.
+A "Phase" is an ordered group of Tasks sharing a dependency boundary or a checkpoint commit — it is distinct from a single Task or atomic step. Report sizing in the uniform vocabulary: `1 Phase = X Tasks`; the whole plan is `Y Phases = Z Tasks`. The sub-agent offer fires when a formal `tasks.md` has more than 3 Tasks — packing itself still uses ~7-Task Phase groups; a 4–8-Task feature is offered as a single Phase-group worker.
 
 - Specify and Execute are always required.
 - Design is skipped when straightforward (no architectural decisions, no new patterns).
@@ -85,7 +85,7 @@ Quick artifacts live under `.specs/quick/NNN-slug/` with a `TASK.md` (one-line i
 3. Run `Specify` with `references/spec-driven/specify.md`.
    - Capture stable requirement IDs, testable acceptance criteria, edge cases, and explicit out-of-scope items.
    - Run `references/spec-driven/discuss.md` inside Specify when gray areas, implicit requirements, persistence/state, external calls, auth, payments, concurrency, or state transitions affect behavior.
-   - For Android, iOS, or KMP Compose Multiplatform UI work, load `references/mobile-context.md` and run the optional design-source gate: ask for one or more Figma links, node IDs, a readable desktop selection, supplied screenshots, or explicit `none`; record `Figma Source: none by user choice` when declined. Screenshots are context-only unless paired with structured Figma evidence. For unsupported targets, record the source as outside mobile Figma scope and do not run mobile Figma.
+   - For Android, iOS, or KMP Compose Multiplatform UI work, load `references/mobile-context.md` and run the optional design-source gate: ask for one or more Figma links, node IDs, a readable desktop selection, supplied screenshots, or explicit `none`; record `Figma Source: none by user choice` when declined. When Figma links or node IDs are supplied, load `references/figma-pre-analysis.md` and run its two-stage sequential retrieval protocol before consuming the design evidence. Screenshots are context-only unless paired with structured Figma evidence. For unsupported targets, record the source as outside mobile Figma scope and do not run mobile Figma.
    - Apply the Requirement Closure Gate: every open requirement question is resolved with the user or recorded as an accepted assumption before execution begins.
 4. Decide whether `Design` is required. If yes, run `references/spec-driven/design.md`; if no, record why the skip is valid. When Design is skipped and a design concern appears later, stop and create `design.md` before continuing.
 5. Decide whether `Tasks` is required. If yes, run `references/spec-driven/tasks.md`; if no, list the inline atomic execution steps before editing. If the inline list reveals more than 5 steps or complex dependencies, stop and create `tasks.md` — the Tasks phase was wrongly skipped (safety valve).
@@ -94,7 +94,7 @@ Quick artifacts live under `.specs/quick/NNN-slug/` with a `TASK.md` (one-line i
    - Run repo-rules discovery from `references/repo-rules-discovery.md` before the first repository mutation: record the harness sources loaded (or `repo-rules: none present`), and implement so every new or changed file conforms to the target repo's module layout, unit-test location, and testing-area conventions. A repo rule wins over a skill default for placement and gate commands; record any deviation with an explicit reason. Never fabricate rules or create `.claude/`/`.cursor/` directories the repo lacks.
    - Use the Test Coverage Matrix and Gate Check Commands from `tasks.md`, or state their inline equivalents when Tasks was skipped.
    - Ask the MCP and skill question in Tasks or inline Execute when tool choice can change correctness or verification.
-   - If a formal `tasks.md` has more than 3 tasks, present the sub-agent offer from `references/spec-driven/sub-agents.md` before starting Execute — even when packing yields a single batch (a 4–8-task feature is offered as one batch worker). Offer-then-confirm — never auto-spawn; the user must accept before any sub-agent is dispatched. One worker per batch (~7 tasks, whole phases): each batch worker executes all its tasks in order (implement → gate → atomic commit), then reports a compact summary (tasks done, commit hashes, test counts, deviations). Workers never spawn further sub-agents.
+   - If a formal `tasks.md` has more than 3 Tasks, present the sub-agent offer from `references/spec-driven/sub-agents.md` before starting Execute — even when packing yields a single Phase group (a 4–8-Task feature is offered as one Phase-group worker). Offer-then-confirm — never auto-spawn; the user must accept before any sub-agent is dispatched. One worker per Phase group (~7 Tasks, whole Phases): each worker executes all its Tasks in order (implement → gate → atomic commit), then reports a compact summary (Tasks done, commit hashes, test counts, deviations). Workers never spawn further sub-agents.
    - Implement one atomic step or approved task at a time.
    - For long-running task sequences, create a checkpoint via `create_checkpoint` at task boundaries with `taskId`, `description`, `progressPercent`, `currentStep`, `nextAction`, `fileChanges`, and `checkpointType: "manual"` so progress is resumable after interruption.
    - If resuming after interruption, call `list_checkpoints` with the `taskId` and `restore_checkpoint` to recover task state before continuing. If `create_checkpoint` is unavailable (e.g. `task_checkpoints` table missing), continue with `.specs/` artifact state as the fallback.