@massa-ai/cursor-plugin 1.26.0 → 1.29.0

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.

package/skills/massa-ai/references/audit-scope.md

@@ -1,6 +1,6 @@
 # Audit Scope
 
-Use this reference from audit workflows, implementation audit, bug finder, mobile Figma, and execution workflows before inspecting changed code or selecting an audit report.
+Use from audit workflows, implementation audit, bug finder, mobile Figma, and execution workflows before inspecting changed code or selecting an audit report.
 
 ## Scope Packets
 
@@ -64,6 +64,27 @@ Use the smallest scope type that matches the user's target:
 - Feature/flow: map entry points through main transformations and side effects; ask for a narrower flow when the feature spans too many unrelated surfaces.
 - Implementation parent scope: accept the exact packet supplied by `workflows/implementation/implementation-audit.md`, including PR diff when that is the selected scope type; child lenses must not broaden it without parent approval.
 
+## Lens Audit Scope Resolution Procedure
+
+Use this procedure in `bugs-audit`, `architecture-audit`, `code-quality-audit`, `requirements-audit`, `security-audit`, and `tests-audit` once each workflow's own step 4 has selected one of the 5 resolution branches below from its trigger list (modified files, commit range, codebase area, explicit-files/globs/branch-comparison/symbol/feature/whole-repo, or implementation-parent scope). This is the single home for the mechanical resolution steps; each lens workflow keeps only its branch-name trigger list and a pointer here.
+
+- **Modified files**: include staged and unstaged tracked files from the working tree, plus untracked non-generated source/test/fixture/schema/config/docs files only when they can affect the lens's evidence (see Per-Lens Scope Deltas for the exact affect-scope and deleted-file-breakage wording per lens). Exclude generated, dependency, build, log, cache, temporary, and secret paths per repo rules. Inspect diffs first, then only the surrounding evidence the lens needs.
+- **Commit range**: use the user-supplied explicit commits/range when given. For "commits made by me", resolve author identity from `git config user.email`, falling back to `git config user.name` when empty, and review only branch-unique commits by that identity. For branch-relative commit scopes, resolve the base with `Branch, Commit, And PR Diff Resolution` below. Ask the user for any missing range/identity/base before proceeding. Inspect the changed files and diffs from those commits, then the lens-specific evidence named in Per-Lens Scope Deltas.
+- **Codebase area**: require a concrete path, module, package, feature area, or glob; ask when missing. Follow `references/codebase-investigation.md`'s retrieval order to find the lens-specific targets in Per-Lens Scope Deltas. Map only top-level modules first and recommend a narrower pass when scope is broad.
+- **Explicit files/globs, branch comparison, symbol/class/function, feature/flow, or explicitly requested whole-repo scope**: resolve the target here and record the resolution method, base/head when relevant, resolved files, exclusions, requirements source when applicable, and freshness timestamp. For symbol/class/function targets, inspect definitions, references, callers, tests, and config plus the lens's extra targets, only as needed to verify a candidate finding. For feature/flow targets, map entry points through the lens-specific transformations named in Per-Lens Scope Deltas. For whole-repo scope, map the lens's first-pass surface (Per-Lens Scope Deltas) and report skipped-depth checks rather than implying exhaustive coverage.
+- **Implementation parent scope**: accept the exact scope packet from `implementation-audit`; do not broaden beyond resolved files, surrounding code, and the lens-specific evidence in Per-Lens Scope Deltas needed to verify the lens's claim. Return compact lens findings to the parent implementation audit; do not write broad project memories unless explicitly assigned.
+
+### Per-Lens Scope Deltas
+
+| Lens (workflow) | Commit-range trigger phrase | Modified-files affect-scope + deleted-file breakage extras | Codebase-area retrieval targets | Symbol/class/function extra targets | Feature/flow mapping focus | Whole-repo first pass | Implementation-parent extra evidence |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Architecture (`architecture-audit`) | architecture issues introduced by branch commits | architecture contracts or module boundaries; deletion also breaks architecture contracts | target modules, entry points, exported surfaces, references, semantic hotspots, tests, adjacent config | exported surfaces, references, dependency direction, callers, tests, ADRs | entry points through main transformations, contracts, side effects | top-level modules | exported surfaces, references, config, tests, ADRs |
+| Bugs (`bugs-audit`) | bugs introduced by branch commits | runtime or validation behavior; deletion breaks imports, exports, routing, migrations, config, tests, or packaging | entry points, public API, tests, adjacent config | callers, callees, tests, contracts, config | input -> transformation -> output through the named flow | high-risk entry points | callers, callees, tests, config, migrations, schemas, public contracts |
+| Code Quality (`code-quality-audit`) | quality issues introduced by branch commits | maintainability, validation behavior, or public contracts; deletion breaks imports, exports, routing, migrations, config, tests, or packaging | target modules, semantic hotspots, public API, tests, adjacent config | references, call sites, tests, current usage evidence | main code path only as far as needed for maintainability/overengineering | sampled/top-level coverage | public API, tests, config, project patterns |
+| Requirements (`requirements-audit`) | requirement drift introduced by branch commits | required behavior; deletion also breaks required behavior or documentation contracts | entry points, public API, tests, config, docs, acceptance criteria | call paths, public contracts, tests, config, docs, requirement links | expected behavior from the requirements source to implementation, tests, docs, contracts | top-level requirement areas | public contracts, tests, config, docs, requirements |
+| Security (`security-audit`) | security issues introduced by branch commits | runtime or validation behavior; deletion also breaks secrets handling or policy enforcement | entry points, trust boundaries, policy checks, validators, tests, adjacent config | call paths, trust boundaries, validators, policies, tests, config, schemas | untrusted input, identity, authorization, validation, persistence, side effects, logs | major trust boundaries | called auth/validation helpers, config, schemas, tests |
+| Tests (`tests-audit`) | test gaps introduced by branch commits | runtime, validation, or test behavior; deletion also breaks test coverage | production entry points, tests, fixtures, mocks, test commands, coverage-sensitive config | call paths, behavior contracts, tests, fixtures, mocks, test commands | changed or targeted behavior mapped to existing tests and deterministic harnesses | major test surfaces | nearby tests, fixtures, config, callers |
+
 ## Branch, Commit, And PR Diff Resolution
 
 Use this order:

package/skills/massa-ai/references/code-annotation.md

@@ -1,7 +1,7 @@
 # Code Annotation And Test Coverage
 
-Use this reference in every implementation workflow, before writing or editing
-source. It defines the three things every created or updated unit of code owes
+Use in every implementation workflow, before writing or editing
+source. Defines the three things every created or updated unit of code owes
 the next reader: an API doc block, a rationale comment, and a test.
 
 ## Principle
@@ -46,7 +46,7 @@ Rules:
 
 ## 2. Rationale Comment
 
-Doc blocks describe the contract. They do not explain why the code changed. Add
+Doc blocks describe the contract, not why the code changed. Add
 a rationale block once at the changed unit — the class, the method, or the
 enclosing block — not on every line.
 
@@ -108,8 +108,8 @@ Rules:
 
 Data models and anemic domain models carry state, not behavior. A unit test
 that constructs them and asserts their own getters, setters, fields, or
-constructor defaults mirrors the implementation and cannot detect that the
-model is wrong — it is the "test that mirrors the code" anti-pattern from the
+constructor defaults mirrors the implementation and cannot detect the
+model is wrong — the "test that mirrors the code" anti-pattern from the
 rule above. **Do not write unit tests for these kinds:**
 
 - **Data models** — persistence-layer entities: ORM-mapped classes, database

package/skills/massa-ai/references/codebase-investigation.md

@@ -1,6 +1,6 @@
 # Codebase Investigation
 
-Use this reference when understanding unfamiliar code before planning, fixing, reviewing, or refactoring.
+Use when understanding unfamiliar code before planning, fixing, reviewing, or refactoring.
 
 ## Golden Rules
 

package/skills/massa-ai/references/coding-guidelines.md

@@ -0,0 +1,67 @@
+# Coding Guidelines
+
+Source: Karpathy Guidelines (Useful-Agent-Skills)
+
+Behavioral guidelines to reduce common LLM coding mistakes. These principles bias toward caution over speed—for trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+
+- State assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them—don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+- Disagree honestly. If the user's approach seems wrong, say so—don't be sycophantic.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it—don't delete it.
+
+When your changes create orphans:
+
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+**The test:** Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

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

@@ -1,6 +1,6 @@
 # Context Firewall
 
-Use this reference before loading raw artifacts >200 lines, >20 KB, >50 search hits, generated reports, logs, screenshots, browser snapshots, CSVs, external research, or any source batch likely to exceed the next decision's needs.
+Use before loading raw artifacts >200 lines, >20 KB, >50 search hits, generated reports, logs, screenshots, browser snapshots, CSVs, external research, or any source batch likely to exceed the next decision's needs.
 
 ## Principle
 
@@ -56,6 +56,7 @@ The main agent receives only:
 
 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
 
 `massa-ai` remains the canonical memory layer for massa-ai workflows. Do not introduce `.notebook/`, SQLite, generated state files, or new persistence systems unless a separate workflow explicitly requires them.

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

@@ -1,6 +1,6 @@
 # Conversation Feedback
 
-Use this reference when a massa-ai workflow needs chat-visible status updates for routing, loading, memory, NotebookLM, subagents, divergences, errors, verification, or completion.
+Use when a massa-ai workflow needs chat-visible status updates for routing, loading, memory, NotebookLM, subagents, divergences, errors, verification, or completion.
 
 ## Principle
 

package/skills/massa-ai/references/debug-diagnosis-loop.md

@@ -1,6 +1,6 @@
 # Debug Diagnosis Loop
 
-Use this reference when `workflows/debug.md` asks for an evidence-first diagnosis loop.
+Use when `workflows/debug.md` asks for an evidence-first diagnosis loop.
 
 ## Principle
 

package/skills/massa-ai/references/decision-engine.md

@@ -1,6 +1,6 @@
 # Decision Engine Reference
 
-Load this when scoring memories, making a trade-off decision, or debugging with
+Load when scoring memories, making a trade-off decision, or debugging with
 prior attempts. Do not load for simple edits where no memory write or design
 decision is needed.
 

package/skills/massa-ai/references/evidence-gate.md

@@ -18,7 +18,7 @@ A completion report must include:
 
 Completion reports must also state that tests, specs, fixtures, snapshots,
 schemas, public contracts, and validator checks were not weakened unless the
-user explicitly requested a validation-asset change.
+user explicitly requested it.
 
 ## Acceptable Evidence
 

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

@@ -1,6 +1,6 @@
 # Figma Pre-Analysis And Sequential Retrieval
 
-Load this reference whenever a workflow receives one or more Figma links, node
+Load 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`).
@@ -14,14 +14,14 @@ restate it.
 
 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
+cheap pre-analysis pass maps what the links contain first, 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:
+Its job: understanding, **not** extraction:
 
 - Summarize composition: pages, screens, frames, component sets, shared tokens.
 - Summarize product context: what the screens are for, the features they serve,

package/skills/massa-ai/references/furps/analyst-role.md

@@ -2,7 +2,7 @@
 
 Reusable sub-agent role for `workflows/refinement/furps-refinement.md`. Charter follows `references/subagent-design.md`. Registered in `references/agent-orchestration.md`.
 
-Purpose: analyze exactly one FURPS+ dimension (F, U, R, P, S, or X) of a PRD/ADR against its checklist section and return structured refinement findings.
+Purpose: analyze exactly one FURPS+ dimension (F, U, R, P, S, or X) of a PRD/ADR against its checklist section, returning structured refinement findings.
 
 Trigger description:
 - Use when the `furps-refinement` workflow fans out per-dimension analysis and needs isolated context plus independent verification per dimension.

package/skills/massa-ai/references/furps/checklist.md

@@ -1,6 +1,6 @@
 # FURPS+ Refinement Checklist
 
-Use this reference from `workflows/refinement/furps-refinement.md` when analyzing a PRD and/or ADR against the FURPS+ quality model. One `furps-analyst` sub-agent loads only its assigned dimension section; the main agent loads the full file only when synthesizing or when no dimension split is used.
+Use from `workflows/refinement/furps-refinement.md` when analyzing a PRD and/or ADR against the FURPS+ quality model. One `furps-analyst` sub-agent loads only its assigned dimension section; the main agent loads the full file only when synthesizing or when no dimension split is used.
 
 ## Source
 

package/skills/massa-ai/references/furps/intake.md

@@ -1,6 +1,6 @@
 # FURPS+ Refinement Intake & Sub-agent Packet Contract
 
-Use this reference from `workflows/refinement/furps-refinement.md` during intake and before dispatching sub-agents. It defines source detection, DoR sourcing, the context-firewall, the bounded document packet, and the sub-agent packet contracts.
+Use from `workflows/refinement/furps-refinement.md` during intake and before dispatching sub-agents. Defines source detection, DoR sourcing, the context-firewall, the bounded document packet, and the sub-agent packet contracts.
 
 ## Source-type detection
 

package/skills/massa-ai/references/furps/report-contract.md

@@ -1,6 +1,6 @@
 # FURPS+ Refinement Report Contract
 
-Use this reference from `workflows/refinement/furps-refinement.md` before writing the final report. It extends the shared `references/audit-report-io.md` single-lens contract with FURPS-specific sections and the required refinement outputs (open questions, suggestions, insights, risks, DoR coverage gaps).
+Use from `workflows/refinement/furps-refinement.md` before writing the final report. Extends the shared `references/audit-report-io.md` single-lens contract with FURPS-specific sections and the required refinement outputs (open questions, suggestions, insights, risks, DoR coverage gaps).
 
 ## Report path
 

package/skills/massa-ai/references/graceful-degradation.md

@@ -0,0 +1,22 @@
+# Graceful Degradation
+
+Load when any massa-ai tool, index, or MCP capability named below is
+unavailable, empty, stale, or mismatched. Continue the workflow with the
+listed fallback instead of blocking.
+
+| 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. |

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

@@ -1,15 +1,15 @@
 # Hook Enforcement
 
-Maps the runtime hook layer (`scripts/hooks/`, `hooks/hooks.json`) to massa-ai
+Maps the runtime hook layer (`apps/claude-plugin/hooks/`, its `hooks.json`) to massa-ai
 workflows and references, and documents the massa-ai dual-write/tag contract.
-Hooks **enforce** existing references and the gate the router already selected;
+Hooks **enforce** existing references and the gate the router already selected —
 they never re-author policy and never re-route. One canonical location per rule.
 
 ## Platform Scoping
 
 The full hook graph installs for **Claude Code, Codex, and Cursor**. OpenCode has
 no hook model and keeps the `AGENTS.md` bootstrap only. The installer
-(`scripts/agent_integrations.py`) preserves unrelated user hooks on install and
+(each host plugin's `install.sh`) preserves unrelated user hooks on install and
 uninstall via managed-command tracking.
 
 Platform hook formats differ; the installer translates one canonical graph

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

@@ -1,7 +1,7 @@
 # Implementation Delivery Protocol
 
-Use this reference in every implementation workflow, before the first repository
-mutation. It defines how verified work leaves the agent's hands: isolated in a
+Use in every implementation workflow, before the first repository
+mutation. Defines how verified work leaves the agent's hands: isolated in a
 worktree, committed atomically, pushed, proposed as a pull request, watched
 through CI, repaired if red — and merged only after the user says so.
 
@@ -10,8 +10,8 @@ They do not mutate, so they have nothing to deliver.
 
 ## Principle
 
-Work that is not isolated, not pushed, and not tested by CI is not delivered —
-it is a local opinion. The protocol turns "I finished" into "CI agrees, and a
+Work that is not isolated, not pushed, and not tested by CI is not delivered — it
+is a local opinion. The protocol turns "I finished" into "CI agrees, and a
 human chose to merge it".
 
 ## The Chain

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

@@ -1,6 +1,6 @@
 # Massa-ai Installation And Diagnostics
 
-Load this only for installing, configuring, validating, or troubleshooting the
+Load only for installing, configuring, validating, or troubleshooting the
 massa-ai stack. Ordinary workflow routing should use MCP tools instead.
 
 ## Install And Upgrade

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

@@ -1,6 +1,6 @@
 # Lessons
 
-Use this reference when loading confirmed project lessons during startup, or recording grounded reusable failures after verification, across any workflow that produces verifiable outcomes.
+Use when loading confirmed project lessons during startup, or recording grounded reusable failures after verification, across any workflow that produces verifiable outcomes.
 
 ## Artifacts
 
@@ -73,7 +73,7 @@ If `lessons.ts` is unavailable or cannot run, record `Lessons: skipped - script
 ## Continuous-Learning Loop (hook-fed)
 
 The lessons layer is a closed loop, not manual-only. Two runtime hooks
-(`scripts/hooks/`, installed for Claude Code by the installer) feed it:
+(`apps/claude-plugin/hooks/`, installed for Claude Code by the plugin installer) feed it:
 
 1. **observe** — `observe_runner.py` (PostToolUse) captures raw tool-use
    observations into the gitignored `.specs/observations.json` buffer. Grounding

package/skills/massa-ai/references/maestro/artifacts-reports.md

@@ -1,6 +1,6 @@
 # Maestro Artifacts And Reports Reference
 
-Use this when running, auditing, or fixing flows that need report paths, artifact directories, screenshots, videos, debug output, or recording.
+Use when running, auditing, or fixing flows that need report paths, artifact directories, screenshots, videos, debug output, or recording.
 
 ## Reports
 

package/skills/massa-ai/references/maestro/cli-device.md

@@ -1,6 +1,6 @@
 # Maestro CLI And Device Reference
 
-Use this for CLI preflight, local command syntax, device/platform readiness, and local execution constraints.
+Use for CLI preflight, local command syntax, device/platform readiness, and local execution constraints.
 
 ## Mandatory Preflight
 

package/skills/massa-ai/references/maestro/cloud.md

@@ -1,6 +1,6 @@
 # Maestro Cloud Reference
 
-Use this only when a Maestro task touches Cloud execution, CI upload, Cloud devices, Cloud-auth-backed AI, or app binary reuse.
+Use only when a Maestro task touches Cloud execution, CI upload, Cloud devices, Cloud-auth-backed AI, or app binary reuse.
 
 ## Cloud Command
 

package/skills/massa-ai/references/maestro/config-env-output.md

@@ -1,6 +1,6 @@
 # Maestro Config, Env, And Output Boundaries
 
-Use this when deciding whether a fact belongs in a Flow header, `config.yaml`, CLI invocation, report metadata, or artifact output.
+Use when deciding whether a fact belongs in a Flow header, `config.yaml`, CLI invocation, report metadata, or artifact output.
 
 ## Boundary Matrix
 

package/skills/massa-ai/references/maestro/fact-ledger.md

@@ -1,6 +1,6 @@
 # Maestro Fact Ledger
 
-Use this before making Maestro claims. It defines source authority, fact tags, local transcript requirements, and quarantine rules for unsupported checklist items.
+Use before making Maestro claims. Defines source authority, fact tags, local transcript requirements, and quarantine rules for unsupported checklist items.
 
 ## Authority Order
 

package/skills/massa-ai/references/maestro/js-scripting.md

@@ -1,6 +1,6 @@
 # Maestro JavaScript Reference
 
-Use this for `evalScript`, `runScript`, inline expressions, generated data, shared state, and JavaScript logging.
+Use for `evalScript`, `runScript`, inline expressions, generated data, shared state, and JavaScript logging.
 
 ## Execution Methods
 

package/skills/massa-ai/references/maestro/mcp.md

@@ -1,6 +1,6 @@
 # Maestro MCP Reference
 
-Use this only when the task mentions Maestro MCP, agent/device automation through MCP tools, Maestro Viewer, or Cloud MCP tooling.
+Use only when the task mentions Maestro MCP, agent/device automation through MCP tools, Maestro Viewer, or Cloud MCP tooling.
 
 ## MCP Surface
 

package/skills/massa-ai/references/maestro/patterns.md

@@ -1,6 +1,6 @@
 # Maestro Workflow Patterns
 
-Use this for stable suite design, setup/teardown strategy, validation assets, and workflow output contracts.
+Use for stable suite design, setup/teardown strategy, validation assets, and workflow output contracts.
 
 ## Stable Flow Design
 

package/skills/massa-ai/references/maestro/selectors.md

@@ -1,6 +1,6 @@
 # Maestro Selectors Reference
 
-Use this when choosing or auditing selectors. Official selector index: https://docs.maestro.dev/reference/selectors.md.
+Use when choosing or auditing selectors. Official selector index: https://docs.maestro.dev/reference/selectors.md.
 
 ## Source Basis
 

package/skills/massa-ai/references/maestro/workspace-execution.md

@@ -1,6 +1,6 @@
 # Maestro Workspace And Execution Reference
 
-Use this when discovering Maestro roots, config files, tags, execution order, suite isolation, and CI invocation.
+Use when discovering Maestro roots, config files, tags, execution order, suite isolation, and CI invocation.
 
 ## Discovery
 

package/skills/massa-ai/references/maestro/yaml-commands.md

@@ -1,6 +1,6 @@
 # Maestro YAML Commands Reference
 
-Use this when authoring or auditing Maestro flow commands. Official command inventory lives at https://docs.maestro.dev/reference/commands-available.md.
+Use when authoring or auditing Maestro flow commands. Official command inventory lives at https://docs.maestro.dev/reference/commands-available.md.
 
 ## Flow Header
 

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

@@ -1,6 +1,6 @@
 # Maestro Reference Index
 
-Use this small index from `workflows/maestro/maestro.md`, `workflows/maestro/maestro-audit.md`, and `workflows/maestro/maestro-fix.md` to select the minimum focused Maestro reference for the current step. Do not treat this index as the full Maestro source of truth.
+Use this small index from `workflows/maestro/maestro.md`, `workflows/maestro/maestro-audit.md`, and `workflows/maestro/maestro-fix.md` to select the minimum focused Maestro reference for the current step. Not the full Maestro source of truth.
 
 ## Source Policy
 

package/skills/massa-ai/references/mcp-tools.md

@@ -1,6 +1,6 @@
 # massa-ai Tool Contracts (52 Tools)
 
-Load this reference when exact MCP schemas, REST fallbacks, response modes, or
+Load when exact MCP schemas, REST fallbacks, response modes, or
 polling rules are needed. Prefer the active tool declaration over copied
 examples. The canonical tool list and order is defined in
 `apps/mcp-client/src/tool-definitions.ts` CANONICAL_ORDER.
@@ -278,7 +278,7 @@ required operation is absent or its adapter is proven broken.
 
 ## Polling Discipline
 
-Never call `index_status` in a tight turn-by-turn loop. Poll after a real
+Never call `index_status` in a tight turn-by-turn loop — poll after a real
 delay. Preferred shell pattern:
 
 ```bash

package/skills/massa-ai/references/memory-policy.md

@@ -1,6 +1,6 @@
 # Memory Policy
 
-Read this when writing, updating, pruning, promoting, or resolving conflicting massa-ai memories.
+Read when writing, updating, pruning, promoting, or resolving conflicting massa-ai memories.
 
 ## Tiers
 
@@ -15,7 +15,7 @@ Supported massa-ai types are only `critical`, `conversation`, `code`, `decision`
 
 ## Observational Memory
 
-Observational Memory is not a new storage layer. It is the discipline for deciding which execution observations become massa-ai memories.
+Observational Memory is not a new storage layer — it is the discipline for deciding which execution observations become massa-ai memories.
 
 - Observer mode: capture only high-signal events, decisions, failed attempts, ruled-out hypotheses, and verification recipes.
 - Reflector mode: when the same lesson appears in 3+ independent sessions, promote it to semantic or procedural memory.

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

@@ -1,6 +1,6 @@
 # Mobile Context
 
-Use this reference when a non-debug workflow touches KMP, iOS, Android, native bridges, mobile app lifecycle, offline sync, permissions, push/background work, local persistence, or backend-mobile contracts.
+Use when a non-debug workflow touches KMP, iOS, Android, native bridges, mobile app lifecycle, offline sync, permissions, push/background work, local persistence, or backend-mobile contracts.
 
 Mobile is a context modifier, not a primary workflow. Keep the selected workflow based on user intent:
 
@@ -19,13 +19,17 @@ Mobile is a context modifier, not a primary workflow. Keep the selected workflow
 - Fix findings from a security audit report -> `workflows/security/security-fix.md`
 - Broad, cross-boundary, unclear, or multi-platform implementation -> `workflows/spec-driven.md`
 
-For `feature`, `spec-driven`, `rfc`, `adr`, and `tdd`, supported mobile UI work can use the optional design-source gate. Ask for one or more Figma links, node IDs, a readable desktop selection, supplied screenshots, or explicit `none` only when the request is Android, iOS, KMP Compose Multiplatform UI, or plausibly mobile UI. Clear backend, CLI, docs, infrastructure, and non-UI requests skip the prompt.
-
 Maestro is a first-class mobile E2E workflow family when the primary target is flow implementation, existing-flow audit, or saved `MST-*` remediation. Generic test coverage, assertion quality, or regression-risk review still belongs to `workflows/tests/tests-audit.md` or `workflows/tests/tests-fix.md` when the target is not Maestro-specific.
 
-When Figma sources or screenshots are supplied for supported Android, iOS, or KMP Compose Multiplatform UI implementation, keep the parent workflow as the lifecycle owner and invoke `workflows/design.md` only for the affected UI slice or visual feasibility context. Use `workflows/mobile-figma/mobile-figma-audit.md` for compare/audit intent and `workflows/mobile-figma/mobile-figma-fix.md` for saved `MFM-*` findings.
+## Design-Source Intake Gate
+
+Use this gate for `feature`, `spec-driven`, `rfc`, `adr`, and `tdd` workflows when the target is Android, iOS, KMP Compose Multiplatform UI, or plausibly mobile UI. Clear backend, CLI, docs, infrastructure, or non-UI work skips the gate entirely.
 
-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. For unsupported targets such as Flutter, React Native, web, desktop, or generic design exploration, record supplied design sources as outside mobile Figma scope, do not run mobile Figma, and continue the parent workflow. Screenshots are context-only unless paired with structured Figma evidence; do not claim exact Figma parity, tokens, variables, or dimensions from screenshots alone.
+- Ask once for one or more Figma links, node IDs, a readable desktop selection, supplied screenshots, or explicit `none`. 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.
+- When Figma sources or screenshots are supplied for supported Android, iOS, or KMP Compose Multiplatform UI implementation/update work, keep the parent workflow as the lifecycle owner and invoke `workflows/design.md` only for the affected UI slice or visual feasibility context. 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`.
+- 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.
+- For unsupported targets such as Flutter, React Native, web, desktop, or generic design exploration, record supplied design sources as outside mobile Figma scope, do not run mobile Figma, and continue the parent 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.
 
 ## Mobile Context Packet
 

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

@@ -1,8 +1,8 @@
 # Mobile Diagnosis
 
-Use this reference when `workflows/debug.md` handles broken behavior involving KMP, iOS, Android, native bridges, real devices, simulators, emulators, mobile app lifecycle, or device-specific failures.
+Use when `workflows/debug.md` handles broken behavior involving KMP, iOS, Android, native bridges, real devices, simulators, emulators, mobile app lifecycle, or device-specific failures.
 
-This extends `references/debug-diagnosis-loop.md`. Do not use it instead of the general debug loop.
+This extends `references/debug-diagnosis-loop.md`. Not a substitute for 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 — 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.
 

package/skills/massa-ai/references/mobile-figma-matcher/android-compose.md

@@ -1,6 +1,6 @@
 # Android Jetpack Compose Figma Contract
 
-Load this reference only for Target Surface Packet rows classified as Android Jetpack Compose.
+Load only for Target Surface Packet rows classified as Android Jetpack Compose.
 
 - Resolve composables, modifiers, layout primitives, Material/theme tokens, typography, shapes, painters/assets, state holders, previews/providers, navigation entry, semantics, and test tags affecting the surface.
 - Distinguish Android-only Compose from Compose Multiplatform using module and source-set evidence.