@massa-ai/cursor-plugin 1.6.0

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

@@ -0,0 +1,52 @@
+### 🟡 Feature
+
+Use this workflow when the user wants to add a new capability, screen, command, integration, behavior, or user-facing improvement with clear intent or acceptance criteria. Do not use it for broken behavior; route that to `workflows/debug.md`. Do not use it for broad, ambiguous, migration-heavy, or cross-boundary work; route that to `workflows/spec-driven.md`.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+Before the first repository mutation, load `references/implementation-delivery.md` for worktree isolation, atomic commits, PR creation, CI watch, and the merge gate, and `references/code-annotation.md` for doc blocks, rationale comments, and test coverage on every created or updated unit. If two consecutive fix attempts fail on the same symptom, stop editing and load `references/root-cause-scripts.md`.
+
+1. Resolve/reuse `projectId` and `workflowSessionId` (`feature-[entity]`)
+2. `recall` → load prior decisions and patterns for this area
+   - Use the default recall budget: `limit <= 3`, `minImportance >= 0.7`, and `types=["critical","decision","pattern"]` unless the feature needs broader memory discovery.
+   - Recall is context only and must not load or reconstruct canonical artifact state.
+3. Load shared references as needed:
+   - `references/codebase-investigation.md` when the target area is unfamiliar
+   - `references/mobile-context.md` when the feature touches KMP, iOS, Android, native bridges, mobile lifecycle, offline sync, permissions, push/background behavior, local persistence, or backend-mobile contracts
+   - `references/verification-ladder.md` before Quick/Standard/Spec-driven sizing or edits
+   - `references/context-firewall.md` when source, logs, docs, or tool output meets its threshold table (a single source/log/doc block >200 lines, >20 KB, or >50 search hits)
+   - `references/naming-standards.md` before writing or renaming code identifiers, public contract fields, tests, fixtures, or implementation-facing design names
+   - `references/pr-task-fix.md` when the verification ladder trigger table applies
+   - `references/lessons.md` when `.specs/lessons.json` exists, to load confirmed project lessons before sizing
+4. For Android, iOS, KMP Compose Multiplatform UI, or work whose target matches the enumerated mobile-context trigger set (KMP, iOS, Android, native bridges, mobile lifecycle, offline/sync, permissions, push/background behavior, local persistence, or backend-mobile contracts), run the mobile UI design-source intake gate before implementation:
+   - 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.
+   - 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.
+5. Size the task before implementation:
+   - Use the exact Quick, Standard, and Spec-driven thresholds in `references/verification-ladder.md`.
+   - Low-risk feature plans use the Plan Challenge lite gate first; full The Fool is reserved for explicit challenge, high-risk domains, broad changes, or lite escalation.
+   - For Standard work or Quick work over 3 files/200 LOC, load `references/pr-task-fix.md`, run its ADR/TDD input gate, decompose work into Small-first independently buildable PR groups, and keep Medium groups only when splitting would break build, tests, UI, or review coherence.
+6. Follow the shared retrieval order from `references/codebase-investigation.md`
+   to find related code; pass only `synapseSessionId` to
+   `search.sessionId`. When the investigation involves multi-search, call `synapse_task_begin` with `id` (the `synapseSessionId`) and `taskContext` before the first search to open a task envelope; call `synapse_prefetch` with `id` and `filePath` after opening a file for deep investigation to warm the buffer; call `synapse_task_end` with `id` when the investigation completes. `synapse_task_begin`/`synapse_task_end` require an existing `synapse_session` id.
+7. Follow existing patterns discovered from recall
+8. Establish the verification recipe before Standard edits and before Quick edits that touch validation assets, including file-integrity checks for tests, specs, benchmarks, fixtures, and snapshots used as validation assets
+   - Include a focused naming review when the feature introduces or renames identifiers. New names should use domain or precise role vocabulary, and public/persisted names should not change without explicit compatibility handling.
+9. For mobile features, capture the mobile context packet, choose shared vs platform-specific boundaries, state platform parity expectations, and include the cheapest relevant mobile verification sensor from `references/mobile-context.md`
+10. Use `references/agent-orchestration.md` only for isolated implementation slices or independent verification
+11. Implement the feature by PR group when `references/pr-task-fix.md` applies:
+   - Order non-breaking groups by Data, Domain, then Presentation/Navigation, mapping those labels to repository boundaries when needed.
+   - Validate each group with the verification recipe before committing.
+   - Invoke `workflows/commit.md` for each verified group; do not duplicate commit staging, message, audit-exclusion, or Jira-prefix rules in this workflow.
+   - When every group has a confirmed Jira key, follow the reference's optional stacked branch flow: ask whether to create stacked task branches, ask for the base branch and a branch pattern containing `<jira-task-key>` if accepted, create each next branch from the previous task branch, never push, and report branches and commits in push order.
+12. Run the verification recipe and report skipped checks explicitly. If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
+     `python3 skills/massa-ai/scripts/lessons.py --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
+13. At completion, persist (run the scoring rubric from `references/decision-engine.md` for each):
+   - Design decisions made via `remember` as scored `decision` memories
+   - New patterns introduced via `remember` as scored `pattern` memories
+   - Trade-offs accepted via `remember` as scored `conversation` memories
+14. Complete the Evidence Gate from `references/evidence-gate.md`

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

@@ -0,0 +1,46 @@
+### General Coding Workflow
+
+Use this workflow for coding, planning-before-coding, review, or implementation work when no specialized massa-ai workflow is a better match. This is the final fallback, not a replacement for explicit or specialized workflows.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+Before the first repository mutation, load `references/implementation-delivery.md` for worktree isolation, atomic commits, PR creation, CI watch, and the merge gate, and `references/code-annotation.md` for doc blocks, rationale comments, and test coverage on every created or updated unit. If two consecutive fix attempts fail on the same symptom, stop editing and load `references/root-cause-scripts.md`.
+
+1. Resolve or reuse `projectId` and a stable `workflowSessionId`: `general-[entity]`.
+2. Run General fallback preflight before source work: name the specialized workflow considered, the exact rejected reason, and why fallback does not change verification, mutation behavior, or memory scope. Ask the user only when the rejected workflow would change those behaviors.
+3. Recall relevant durable context with `recall`. Treat recalled memory as a lead until current source confirms it. Confirm recalled memory against current source before relying on it only when the change touches the enumerated risk-domain set: public API, data loss, auth/PII, migrations, or cross-service contracts. Otherwise trust recalled memory and cite it with a one-line source note.
+4. Create a Synapse session when planned related `search` calls >=2, following `references/synapse-policy.md`.
+5. Load confirmed project lessons through `references/lessons.md` when `.specs/lessons.json` exists:
+   `python3 skills/massa-ai/scripts/lessons.py --root . list --status confirmed`
+   Retrieve only the context required for the goal:
+   - begin with focused local inspection or the shared summary-search sequence
+   - deepen into enriched search, symbols, or exact files only when needed
+   - prefer `read_file` over native Read when symbol metadata + imports are useful (retrieval order per `references/mcp-tools.md`); use `symbol_snippet` for raw code snippets by file + line range
+   - prefer current repository truth over stale or conflicting memories
+6. Execute the requested work using existing repository conventions. Tie verification depth to the Verification Ladder tier table in `references/verification-ladder.md`: Quick (<=3 files and <=200 changed LOC) runs static + file-integrity checks; Standard (<=10 files or <=500 changed LOC) adds a named verification recipe and behavioral checks; Spec-driven (>10 files, >500 changed LOC) escalates to `workflows/spec-driven.md`. Do not invent new thresholds; load specialized references only when the task needs their exact contracts.
+   - For analysis that benefits from running code (derived values, data inspection, bulk transforms), call `execute` with `language` and `code` or `batch_execute` with `commands`[] instead of loading raw data into context. Respect the local-dev-only trust model (no untrusted-client exposure).
+7. Use `compress` only when accumulated source or conversation context is reducing execution quality; preserve decisions, constraints, current state, and next steps rather than raw history.
+8. Before completion, if verification found a reusable signal, record it via `references/lessons.md`. Score potential memories using `references/decision-engine.md` when that guidance is not already loaded:
+   `python3 skills/massa-ai/scripts/lessons.py --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
+    - remember verified decisions, reusable discoveries, recurring blockers, accepted constraints, and completed outcomes that will save future work
+    - if a recalled memory is stale or needs correction, call `memory_update` with `id` and the new `content` (re-embeds automatically); if a memory is obsolete, call `memory_delete` with `id` (hard-delete, severs graph edges)
+    - for usage insights (search/cache patterns, recent activity), call `analytics` with `type` and `projectId`
+    - skip transient details, raw logs, copied source, unverified hypotheses, and facts already captured in current non-stale memory
+9. Complete the Evidence Gate from `references/evidence-gate.md` and report verification, changed artifacts, memory outcome, and residual risk.
+
+## Failure Handling
+
+- If massa-ai is unavailable, continue with focused shell and file inspection while retaining the project and workflow session concepts.
+- If recall is empty, proceed as a cold start without inventing memory.
+- If Synapse is unavailable, continue with stateless targeted search.
+- If a memory write fails, complete the task and report the durable insight that was not persisted.
+
+## Output Contract
+
+- Goal and selected fallback workflow
+- General fallback preflight: considered workflow, rejected reason, and fallback validity
+- Relevant recalled context or explicit cold-start status
+- Work completed and source evidence
+- Verification performed and skipped checks
+- Memory written or intentionally skipped, with reason
+- Residual risk

package/skills/massa-ai/workflows/implementation/implementation-audit.md

@@ -0,0 +1,87 @@
+### Implementation Audit
+
+Use this workflow for a findings-only multi-lens audit of a concrete implementation target: modified files, explicit files/globs, commit ranges, branch comparisons or PR diffs, modules/packages, symbols/classes/functions, feature/runtime flows, or an explicitly requested whole-repository sample.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+Do not use this parent workflow when the user wants only one audit lens; route directly to that lens. Do not edit code. This workflow resolves one shared implementation scope packet, dispatches selected child lenses, and saves one durable report for `workflows/implementation/implementation-fix.md`.
+
+1. Resolve/reuse `workflowSessionId`: `implementation-audit-[entity]`.
+2. Load shared references:
+   - `references/audit-scope.md` for target resolution, implementation scope packets, exclusions, and freshness.
+   - `references/agent-orchestration.md` for modular read-only audit roles and capability packets.
+   - `references/audit-report-io.md` before producing the report.
+   - `references/context-firewall.md` before large diffs, logs, snapshots, generated reports, or broad searches.
+   - `references/synapse-policy.md` when repeated massa-ai searches are expected.
+3. `recall` -> load current architectural decisions, known regressions, security boundaries, requirements decisions, testing conventions, accepted exceptions, and project constraints. Apply the Memory Freshness Gate from `references/audit-scope.md`; memory is a lead, not proof.
+4. Establish one concrete implementation target before analysis:
+   - Accept modified files, explicit files/globs, commits/ranges, branch or PR comparisons, modules/packages, symbols/classes/functions, features/flows, or explicit whole-repository scope.
+   - If the target is absent or ambiguous, ask for it. Never default to the whole repository.
+   - Resolve the target using `references/audit-scope.md` and build one immutable implementation scope packet containing scope type, target focus, resolution method, base/head when relevant, resolved files, diff source when relevant, exclusions, requirements source, and freshness timestamp.
+   - Pass the exact packet to every child lens. Child lenses may inspect surrounding code only to prove a concrete claim and must not silently broaden the target.
+5. Resolve requirements source before lens dispatch:
+   - At workflow start, resolve whether Requirements lens is in scope: broad/full audit, explicitly named Requirements lens, or requirement-fidelity claim in the user request.
+   - If Requirements lens is in scope and no requirements source was provided or discovered from the prompt, PR description, task/spec file, issue text, or repository docs, ask the user for a requirements source before launching child lenses.
+   - Accepted requirements sources are Jira or Confluence link/key via Atlassian MCP when callable, pasted requirements text, or attached/local file path.
+   - If interactive input or Atlassian MCP is unavailable, mark Requirements `not evaluated: missing source` with skipped-check reason `needs-credentials`, `tool-missing`, or `not-applicable` as appropriate.
+   - Never report a Requirements all-clear without a requirements source.
+6. Select audit lenses:
+   - If the user names lenses, run only those lenses.
+   - For a broad/full audit, run Correctness, Architecture, Code Quality, Security, and Tests. Run Requirements only when a requirements source is available.
+   - Supported lenses: Correctness -> `workflows/bugs/bugs-audit.md`; Architecture -> `workflows/architecture/architecture-audit.md`; Code Quality -> `workflows/code-quality/code-quality-audit.md`; Security -> `workflows/security/security-audit.md`; Requirements -> `workflows/requirements/requirements-audit.md`; Tests -> `workflows/tests/tests-audit.md`.
+   - When a broad audit lacks requirements, ask for a source when interactive and not forbidden; otherwise mark Requirements `not evaluated: missing source`. Never report a requirements all-clear without a source.
+7. Establish child contracts and dispatch `audit-specialist` per lens through `references/agent-orchestration.md`:
+
+> **Dispatch: `massa-ai-audit-specialist`** (role: `audit-specialist`) — charter `skills/agents/audit-specialist/SKILL.md`
+> - trigger: broad/full audit requiring multiple lenses, or explicit multi-lens request
+> - scope: one lens per dispatch against the shared implementation scope packet (Correctness/Architecture/Code Quality/Security/Requirements/Tests)
+> - permissions: read-only
+> - inputs: exact `projectId`, parent `workflowSessionId`, child workflow, lens name, shared scope packet, resolved files/diff summary, relevant recalled facts, allowed surrounding-code depth, deterministic sensors, context-firewall limits, and output contract
+> - sensors: target-relevant deterministic commands (tests, builds, lint, type checks, static checks, import checks) per lens
+> - output: `Status`, `Scope checked`, `Evidence`, `Findings`, `Verification/Test Fidelity Checklist`, `Risks and skipped checks`, and `Exact next step`
+> - firewall: raw diffs/logs/search output summarized, not returned raw
+> - memory: suggest-only; children must not persist broad project memory unless assigned
+
+    - Repeated-search children receive isolated Synapse sessions. Durable child tags retain the parent session and workflow-specific session.
+8. Use deterministic sensors when target-relevant commands are expected to finish in <=5 minutes and need no network, destructive action, production credential, or unapproved external service: tests, builds, lint, type checks, static checks, import checks, or focused runtime commands. Record skipped commands with one reason enum: `too-expensive`, `needs-network`, `needs-credentials`, `destructive-risk`, `outside-scope`, `tool-missing`, or `not-applicable`. Model judgment alone is not completion evidence.
+9. Check whether SonarQube MCP is available and useful for the implementation scope:
+   - Detect callable SonarQube MCP tools at runtime, such as project discovery, issue search, file/snippet analysis, advanced code analysis, duplicated-file search, component measures, security hotspots, guidelines, or quality gate status.
+   - If SonarQube MCP is unavailable, no project key can be resolved, required credentials/configuration are missing, or the target files are outside the configured SonarQube project, record `SonarQube MCP: not evaluated` with the skipped-check reason and continue normal lens synthesis.
+   - If available, use `references/context-firewall.md` and pass only the immutable implementation scope packet, resolved files, branch/PR identifiers, project key, and minimal file contents or paths required by the selected SonarQube tools.
+   - Wait for SonarQube MCP execution to finish when a tool starts analysis, capture quality gate status when available, and summarize raw issues/measures/hotspots instead of copying raw tool output into the report.
+   - Normalize actionable SonarQube results into only these implementation audit areas: Architecture, Correctness/Bugs, Code Quality, Security, and Tests. Do not create a Requirements finding from SonarQube output.
+   - Preserve Sonar issue key, rule key, tool name, severity/impact, file/line, quality gate condition, and evidence summary inside the normalized finding.
+   - Use normal source-qualified implementation IDs after normalization, such as `Architecture/ARCH-1`, `Correctness/BUG-1`, `Code Quality/CQ-1`, `Security/SEC-1`, or `Tests/TST-1`; do not invent `SONAR-*` executable finding IDs.
+   - Keep unmapped, duplicate, low-context, or out-of-scope SonarQube results in Scope And Evidence or skipped checks, not in Findings or Execution Handoff.
+10. Synthesize one result:
+   - Start with a lens coverage matrix using `run`, `not evaluated`, `skipped`, or `failed`.
+   - Include SonarQube MCP as evidence in the coverage matrix or Scope And Evidence, with quality gate status when available.
+   - Preserve each child lens Verification/Test Fidelity Checklist from `references/audit-report-io.md` and summarize checklist proof in the parent lens coverage matrix, Scope And Evidence, and Execution Handoff.
+   - Tie every source-qualified finding or no-finding claim to deterministic sensors, commands/artifacts, results, validation assets, or skipped-check reasons. Model judgment alone cannot satisfy verification/testing all-clear.
+   - Deduplicate findings by root cause and order them `critical`, `high`, `medium`, then `low`.
+   - Preserve source lens, original ID, confidence, location, evidence, impact, smallest fix direction, and verification suggestion.
+   - Use source-qualified finding IDs of the form `Area/PREFIX-N` (e.g., `Correctness/BUG-1`, `Architecture/ARCH-1`, `Code Quality/CQ-1`, `Security/SEC-2`, `Requirements/REQ-1`, `Tests/TST-1`). The Area ties each finding to its source lens so traceability survives the broader non-PR-diff scope; the full discipline and area/prefix table live in `references/audit-report-io.md` (Source-Qualified Finding IDs).
+   - If no findings remain, state the exact scope and lenses checked, skipped checks, and any missing requirements coverage.
+11. Save or propose the canonical implementation audit report:
+   - Default mode: write `audits/implementation/<YYYY-MM-DD implementation-audit.md>` under the target project root. Create the directory when absent and never silently overwrite a different run.
+   - Plan Mode: return the proposed path and complete report without writing files.
+   - Required metadata: `Workflow: implementation-audit`, `ProjectId`, `WorkflowSessionId`, `Target`, `Target Focus`, `Scope`, `Git Base`, `Git Head`, `Source Evidence Timestamp`, and `Requirements Source` or `n/a`.
+   - Required sections: lens coverage matrix, findings, ruled-out candidates when relevant, scope and evidence, Verification/Test Fidelity Checklist, execution handoff, skipped checks, and residual risk.
+   - The execution handoff lists ordered source-qualified IDs, dependencies, likely affected files, validation assets, verification commands, and cautions for `implementation-fix`.
+   - Sonar-derived findings enter the execution handoff only after normalization to one of the supported source lens IDs and with enough evidence for `implementation-fix` to revalidate from the saved markdown report.
+12. Persist only durable repeated patterns, approved architecture/requirements interpretations, or accepted exceptions after Importance Calibration. Use `workflow:implementation-audit` and the required project/session/entity/memory tags. Do not persist one-off findings, raw SonarQube output, or raw child output.
+13. Complete `references/evidence-gate.md`.
+
+## Examples
+
+User asks: "Run a full implementation audit on my modified files."
+
+1. Resolve staged, unstaged, and relevant untracked files into one modified-files scope packet.
+2. Run all supported lenses except Requirements when no requirement source exists.
+3. Save one implementation report with source-qualified findings and an execution handoff.
+
+User asks: "Audit commits abc123..def456 for correctness and tests."
+
+1. Resolve the exact commit range and changed files.
+2. Run only Correctness and Tests against the shared packet.
+3. Save the report under `audits/implementation/`.

package/skills/massa-ai/workflows/implementation/implementation-fix.md

@@ -0,0 +1,90 @@
+### Implementation Fix
+
+Use this workflow only to execute confirmed findings from a saved implementation audit markdown report.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+Before the first repository mutation, load `references/implementation-delivery.md` for worktree isolation, atomic commits, PR creation, CI watch, and the merge gate, and `references/code-annotation.md` for doc blocks, rationale comments, and test coverage on every created or updated unit. If two consecutive fix attempts fail on the same symptom, stop editing and load `references/root-cause-scripts.md`.
+
+Do not execute from chat summaries, inline review comments, remembered findings, or old PR audit reports. The saved `audits/implementation/<YYYY-MM-DD implementation-audit.md>` report is the source of truth. Route fresh findings work to `workflows/implementation/implementation-audit.md`.
+
+1. Resolve/reuse `workflowSessionId`: `implementation-fix-[entity]`.
+2. Load shared references:
+   - `references/audit-report-io.md` before any code or test change.
+   - `references/audit-scope.md` for target matching and freshness.
+   - `references/lessons.md` to load confirmed project lessons
+   - `references/codebase-investigation.md` before changing unfamiliar paths.
+   - `references/verification-ladder.md` before non-trivial edits.
+   - `references/naming-standards.md` before introducing, renaming, or preserving identifiers as part of a finding fix.
+   - `references/context-firewall.md` before large diffs, logs, snapshots, reports, or broad searches.
+   - `references/agent-orchestration.md` only for high-risk findings, disjoint implementation slices, or independent verification.
+3. `recall` -> load prior implementation audit decisions, known regressions, architecture/security boundaries, accepted exceptions, testing conventions, and reusable verification recipes for the target.
+4. Select the report with an explicit execution focus:
+   - Establish report selector, target focus, and optional source-qualified finding IDs before selecting a report.
+   - If the user provides a path, read that exact markdown file.
+   - If the user asks for `latest` or omits a path, require a concrete target focus first, then select the latest matching `audits/implementation/<YYYY-MM-DD implementation-audit.md>` using `references/audit-report-io.md`.
+   - Stop if no saved report exists. Tell the user to run `implementation-audit` or provide a report path.
+   - Reject reports missing `Workflow: implementation-audit`, `ProjectId`, `WorkflowSessionId`, `Target`, `Target Focus`, `Scope`, `Git Base`, `Git Head`, `Source Evidence Timestamp`, or `Requirements Source`/`n/a`.
+5. Validate freshness before editing:
+   - Verify project, target, target focus, scope, base/head, and resolved files match the current execution target.
+   - Re-resolve the current target and stop when material drift invalidates the report unless the user explicitly accepts the risk.
+   - Inspect every selected finding's current location and evidence. Stop or re-audit when files moved, cited code no longer exists, evidence no longer proves the claim, or newer code changed the contract.
+   - Treat unknown required fields, low-confidence suspects, skipped lenses, and `not evaluated` lenses as non-actionable unless explicitly included by the user.
+6. Extract actionable findings:
+   - Require source-qualified IDs of the form `Area/PREFIX-N` (e.g., `Correctness/BUG-1`, `Architecture/ARCH-1`, `Code Quality/CQ-1`, `Security/SEC-2`, `Requirements/REQ-1`, `Tests/TST-1`), plus severity, confidence, source lens, original ID, location, evidence, impact, smallest fix direction, and verification suggestion. The Area must match the source lens that produced the finding; the canonical area/prefix table and discipline live in `references/audit-report-io.md` (Source-Qualified Finding IDs).
+   - Ignore ruled-out candidates, skipped-check notes, no-finding summaries, and suspects unless explicitly selected.
+   - Treat SonarQube-derived items as actionable only when the saved implementation report already normalized them to a supported source-qualified ID with source lens, original ID, Sonar issue/rule evidence, location, impact, and verification suggestion. Never execute directly from raw SonarQube MCP output, quality gate summaries, chat summaries, or remembered Sonar findings.
+   - If finding IDs are supplied, execute only those IDs after validating target and report membership.
+   - Deduplicate findings sharing one root cause while preserving every original ID in the closure matrix.
+7. Build one remediation matrix before editing: finding -> source lens -> severity -> confidence -> root fix -> likely files -> validation assets -> naming/public-contract impact -> verification command -> dependency/order -> status. Prioritize critical/high findings, then dependency order, blast radius, and verification cost. Keep unrelated cleanup out of scope.
+8. Route each fix by source lens:
+   - Correctness/`BUG-`: apply `bugs-fix` methods and add regression coverage when feasible.
+   - Security/`SEC-`: apply `security-fix` methods, fail closed, and add negative validation when feasible.
+   - Tests/`TST-`: apply `tests-fix` methods and strengthen deterministic sensors without brittle fixtures.
+   - Requirements/`REQ-`: apply `requirements-fix` methods and preserve traceability, non-goals, and compatibility.
+   - Architecture/`ARCH-`: apply `architecture-fix` methods; route broad redesign to `spec-driven`.
+   - Code Quality/`CQ-`: apply `code-quality-fix` methods using small reversible simplification.
+9. Size each finding with `references/verification-ladder.md`. Quick findings may proceed locally; Standard findings require characterization and an explicit recipe; ambiguous, cross-boundary, migration-heavy, or broad redesign findings pause and route to `spec-driven`.
+10. Orchestrate conservatively. The main agent owns report parsing, scope/freshness, prioritization, questions, memory, and final evidence. Dispatch per `references/agent-orchestration.md`:
+
+> **Dispatch: `massa-ai-builder`** (role: `builder`) — charter `skills/agents/builder/SKILL.md`
+> - trigger: isolated finding with disjoint write set and concrete verification
+> - scope: one isolated implementation finding with a disjoint write set
+> - permissions: write (disjoint write set)
+> - inputs: the source-qualified finding ID (`Area/PREFIX-N`), target files, validation assets, and verification command
+> - sensors: report's verification suggestion or equivalent deterministic command per lens
+> - output: implementation summary, commands run, test counts, deviations
+> - firewall: raw diffs/logs summarized
+> - memory: suggest-only; main agent persists reusable patterns
+
+> **Dispatch: `massa-ai-verification-agent`** (role: `verification-agent`) — charter `skills/agents/verification-agent/SKILL.md`
+> - trigger: high-risk, security, public-contract, or multi-file fix
+> - scope: the fixed finding's behavior, contracts, tests, and report claim closure
+> - permissions: read-only
+> - inputs: the finding, the applied fix, the verification suggestion, and validation assets
+> - sensors: deterministic command per lens (tests, import checks, security checks) and report claim closure
+> - output: confirmed/disproven closure verdict with evidence
+> - firewall: raw test output/logs summarized
+> - memory: suggest-only; main agent persists reusable verification recipes
+
+    Never run parallel writers against shared files or contracts.
+11. Verify each completed finding with the Mandatory Verification Fix Gate from `references/verification-ladder.md`: run the report's Verification Suggestion or an equivalent deterministic command/artifact check, then run focused tests, build, lint, type, static, or runtime checks relevant to the source lens. Reinspect tests, fixtures, snapshots, types, specs, public contracts, and touched identifiers so validation assets were not weakened and names follow `references/naming-standards.md`. A finding cannot be marked `fixed` when a target-relevant command or artifact check exists but was not attempted; if verification cannot run, mark it `blocked`, `deferred`, or `skipped` with an allowed skipped-check reason.
+12. Produce a closure matrix with finding ID, source lens, status (`fixed`, `deferred`, `blocked`, `skipped`), changed files, command/artifact, result, skipped reason or `none`, highest Verification Ladder level reached, validation assets protected, residual risk, and exact next step for deferred or blocked findings.
+13. If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
+     `python3 skills/massa-ai/scripts/lessons.py --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
+14. Persist only reusable root-cause patterns, approved remediation exceptions, durable architecture/security/requirements decisions, or project-specific verification recipes after Importance Calibration. Use `workflow:implementation-fix` and required project/session/entity/memory tags.
+15. Complete `references/evidence-gate.md`.
+
+## Examples
+
+User asks: "Use implementation-fix to fix the latest audit findings for my modified files."
+
+1. Resolve modified files as target focus and select the latest matching implementation report.
+2. Validate report metadata, current files, and finding evidence.
+3. Fix confirmed findings by source lens and report the closure matrix.
+
+User asks: "Fix Security/SEC-2 from audits/implementation/2026-06-15 implementation-audit.md."
+
+1. Read the exact report and validate `Security/SEC-2` against current source.
+2. Apply security-fix methods only to that finding.
+3. Preserve all other findings for later execution.

package/skills/massa-ai/workflows/long-session.md

@@ -0,0 +1,44 @@
+### 🟠 Long Session (Context Growing Large)
+
+Use this workflow when the user asks for same-session handoff/continuation/safe stopping, work remains unfinished at session end, context budget falls below 40% remaining, context usage reaches 60% with more than one PR group/task still open, or verbose source/log/research context is reducing execution quality. Preserve the exact existing `projectId` and `workflowSessionId`; this workflow packages continuity rather than starting a new task. Do not persist an ephemeral `synapseSessionId` as continuation state.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+This workflow owns the Session Guide. Canonical resumable state still lives in `.specs/` files — `.specs/project/FEATURES.json`, `.specs/project/STATE.md`, `.specs/HANDOFF.md`, and `.specs/features/<slug>/` — and the Session Guide points at them rather than restating or replacing them.
+
+1. Continue with the same `workflowSessionId` and `projectId`; never generate a new durable workflow session for compaction
+2. If code context exceeds 200 lines, 20 KB, or 50 search hits in the active reasoning window, use `compress` with strategy `code_structure`
+3. If conversation history exceeds 60% context usage or contains stale/raw tool output that no longer drives decisions, use `compress` with strategy `conversation_summary`
+4. Before compaction fires, call `compact_snapshot` with `sessionId` (the lifecycle session id from hooks/sessions — NOT the `workflowSessionId`; see the two-session-id rule in `references/synapse-policy.md`) and `projectId` to build a bounded (<2KB) reference-based table-of-contents of the session's observations. This enables zero-loss recovery across `/compact`: raw events stay in the observation store; the snapshot is a navigable index. Record the snapshot as a reference pointer in the Session Guide. If `compact_snapshot` is unavailable, continue with `compress` + `remember` and record the skipped snapshot.
+5. Write a Session Guide before handoff, compaction, or stopping:
+   - Last request
+   - Current state
+   - Pending tasks
+   - Key decisions
+   - Files touched
+   - Unresolved errors
+   - Exact next step
+   - Exact `workflowSessionId` and `projectId`
+   - Instruction to open and optionally prime a fresh Synapse session after resume when repeated searches are expected
+   - Exact pointers to the canonical `.specs/` artifacts that hold the rest of the state
+6. Before compaction or stopping, call `create_checkpoint` with `checkpointType: "manual"`, `taskId` (or `workflowSessionId` as `taskId`), `description` summarizing the Session Guide, `currentStep`, `nextAction`, and `fileChanges` so the progress state is checkpoint-backed and resumable. If `create_checkpoint` is unavailable, continue with `.specs/` artifact state as the fallback.
+7. Persist the Session Guide via `remember` as `type=critical` for incomplete work or `type=conversation` for routine compaction, with `memory:working` and `handoff` tags
+   - If a memory from this session is now obsolete (e.g. a superseded hypothesis or a resolved blocker), call `memory_delete` with its `id` to hard-delete it and sever graph edges
+   - For usage insights before compaction, call `analytics` with `type` and `projectId` to capture search/cache patterns for the session guide
+8. Complete the Evidence Gate from `references/evidence-gate.md`
+
+## Example
+
+```md
+Session Guide
+workflowSessionId: spec-billing-workflow
+projectId: massa-ai
+Last request: continue the approved spec-driven billing implementation.
+Current state: requirements and design approved; T3 verification is pending.
+Pending tasks: run T3 Full gate, commit T3, update traceability, then start T4.
+Key decisions: feature artifacts own approved phase contracts; massa-ai owns durable cross-session memory.
+Files touched: .specs/features/billing/tasks.md, `src/billing/service.ts`, `tests/billing/service.test.ts`.
+Unresolved errors: none found.
+Exact next step: run the T3 validation command recorded in .specs/features/billing/tasks.md.
+```
+<!-- validator anchor: .specs/features/billing/tasks.md -->

package/skills/massa-ai/workflows/maestro/maestro-audit.md

@@ -0,0 +1,56 @@
+### Maestro Audit
+
+Use this workflow for findings-only audit of existing Maestro mobile E2E flows, fixtures, setup/teardown, reports, artifacts, CI invocation, selector stability, flake risk, and scenario coverage.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+Do not edit code or flows in this workflow. Do not use it for new flow implementation; route that to `workflows/maestro/maestro.md`. Do not fix findings directly; invoke `workflows/maestro/maestro-fix.md` as a bounded child workflow only after a saved audit report or audit handoff exists.
+
+1. Resolve/reuse `workflowSessionId`: `maestro-audit-[entity]`.
+2. Load shared references:
+   - `references/maestro.md` as the index before choosing focused Maestro references.
+   - `references/maestro/fact-ledger.md` before making any Maestro claim; tag facts as `official-doc`, `live-help`, `repo-convention`, or `excluded/unverified`.
+   - `references/maestro/cli-device.md` before CLI checks, device/platform readiness, local sharding, or executable runs.
+   - `references/maestro/workspace-execution.md` before discovering flows, tags, config, CI commands, execution order, or suite isolation.
+   - `references/maestro/artifacts-reports.md` before report/artifact/debug-output, screenshot, video, recording, or AI report claims.
+   - `references/maestro/selectors.md` before selector stability findings.
+   - `references/maestro/config-env-output.md` before env/config/report-output findings.
+   - `references/maestro/cloud.md` only when Cloud execution, Cloud devices, auth/plan, or Cloud artifact evidence is in scope.
+   - `references/maestro/mcp.md` only when Maestro MCP or Viewer evidence is in scope.
+   - `references/maestro/patterns.md` before flake, setup/teardown, coverage, and execution-handoff judgments.
+   - `references/audit-report-io.md` before producing the report.
+   - `references/mobile-context.md` for platform scope, parity, and device/emulator assumptions.
+   - `references/audit-scope.md` for scope packet, budgets, skipped depth checks, and freshness.
+   - `references/context-firewall.md` before large logs, screenshots, videos, JUnit XML, generated artifacts, or broad search output.
+   - `references/synapse-policy.md` when repeated massa-ai searches are expected.
+   - `references/agent-orchestration.md` only for large scopes, explicit parallel/subagent requests, or independent verification of high-impact findings.
+3. Run the mandatory Maestro CLI transcript gate from `references/maestro/cli-device.md` and `references/maestro/fact-ledger.md`: `command -v maestro`, `maestro --version` or `maestro --help`, and relevant subcommand help with command, exit code, stdout, and stderr. If missing or failing, block executable audit runs and produce only a blocked static-readiness report when source inspection is still useful.
+4. Establish the audit target:
+   - Explicit Maestro root, suite, flow file, tag, app/module, platform, branch comparison, commit range, modified files, or whole Maestro workspace.
+   - For omitted target, discover all developed Maestro flows and ask before whole-workspace audit if multiple roots exist.
+5. Resolve expected behavior sources in scenario input order: Jira/Confluence via Atlassian MCP, attached/local file, prompt text, then explored/inferred repository behavior. If no requirements source exists, run `workflows/exploration.md` before comparing behavior and label inferred expectations as inference.
+6. Discover all in-scope Maestro flows, subflows, fixtures, setup/teardown, config, tags, CI commands, report paths, and artifact paths.
+7. Run every existing in-scope Maestro flow when the CLI, app build, device/emulator, credentials, and backend dependencies are available. Use deterministic output:
+   - `maestro test --format junit --output <report.xml> --test-output-dir <artifact-dir> <flow-or-directory>`.
+   - Capture command, exit code, JUnit report, artifact directory, platform/device, app build/flavor, environment, and skipped-check reason.
+8. Compare current flows and run results against supplied or discovered expected behavior:
+   - Scenario coverage and acceptance criteria.
+   - Setup/teardown completeness, data isolation, feature flags, permissions, locale/timezone, cleanup, and app state reset.
+   - Selector/test-ID stability, synchronization, fixed sleeps, coordinates, screenshot/image coupling, brittle text, and flow ordering.
+   - CI report/artifact retention, runtime cost, device assumptions, retry/quarantine behavior, and flake diagnostics.
+9. Produce findings first, ordered by severity. IDs: `MST-<N>`.
+   - Each finding must include severity, confidence, flow/subflow/file location, scenario source, concrete evidence, impacted journey, flake or coverage risk, simplest sufficient fix, and Verification Suggestion.
+   - If no findings are found, say that clearly and list flows, scenarios, commands/artifacts, and skipped checks.
+   - Include the Verification/Test Fidelity Checklist from `references/audit-report-io.md`; tie every `MST-*` finding or no-finding claim to deterministic sensors, commands/artifacts, validation assets, skipped-check reasons, and runtime artifacts. Model judgment alone cannot satisfy verification/testing all-clear.
+10. Save or propose `audits/maestro/<YYYY-MM-DD maestro-audit.md>` using the report contract in `references/audit-report-io.md`. The enriched report must preserve flow inventory, run matrix, scenario coverage, JUnit report path, artifact directory, device/emulator readiness, validation assets, and execution handoff.
+11. Invoke `workflows/maestro/maestro-fix.md` only as a bounded child workflow for failed executable `MST-*` findings when requested or when the parent audit explicitly includes auto-fix handoff. The child may edit only Maestro flows, subflows, fixtures, setup/teardown, and test data.
+12. Persist only durable Maestro conventions, flake classes, selector/test-ID policy, device matrix constraints, or reusable verification recipes after Importance Calibration. Use `workflow:maestro-audit` and required memory tags.
+13. Complete the Evidence Gate from `references/evidence-gate.md`.
+
+## Examples
+
+User asks: "Run a Maestro audit for the checkout suite."
+
+1. Scope to the checkout Maestro root or tag, run CLI/device preflight, and discover expected behavior.
+2. Execute in-scope flows with JUnit report and artifact output when dependencies are available.
+3. Save `audits/maestro/<YYYY-MM-DD maestro-audit.md>` with `MST-*` findings and execution handoff.

package/skills/massa-ai/workflows/maestro/maestro-fix.md

@@ -0,0 +1,74 @@
+### Maestro Fix
+
+Use this child-only workflow to fix confirmed `MST-*` findings from a saved Maestro audit report or an explicit `maestro-audit` handoff.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+Before the first repository mutation, load `references/implementation-delivery.md` for worktree isolation, atomic commits, PR creation, CI watch, and the merge gate, and `references/code-annotation.md` for doc blocks, rationale comments, and test coverage on every created or updated unit. If two consecutive fix attempts fail on the same symptom, stop editing and load `references/root-cause-scripts.md`.
+
+Reject direct use without a saved `audits/maestro/<YYYY-MM-DD maestro-audit.md>` report or a parent audit handoff that includes the same required metadata. Do not execute from chat summaries, remembered findings, inline comments, or unsaved model analysis. The saved report or parent handoff is the source of truth.
+
+1. Resolve/reuse `workflowSessionId`: `maestro-fix-[entity]`.
+2. Load shared references:
+   - `references/maestro.md` as the index before choosing focused Maestro references.
+   - `references/maestro/fact-ledger.md` before making any Maestro claim; tag facts as `official-doc`, `live-help`, `repo-convention`, or `excluded/unverified`.
+   - `references/maestro/cli-device.md` before CLI checks, device/platform readiness, local sharding, or executable runs.
+   - `references/maestro/artifacts-reports.md` before report/artifact/debug-output, screenshot, video, recording, or AI report claims.
+   - `references/maestro/patterns.md` before applying flow, setup/teardown, fixture, validation asset, or skipped-check rules.
+   - `references/maestro/yaml-commands.md` before changing unfamiliar command syntax.
+   - `references/maestro/selectors.md` before changing selector strategy.
+   - `references/maestro/workspace-execution.md` before changing config, tags, execution order, sharding, or CI command shape.
+   - `references/maestro/config-env-output.md` before changing env, properties, report-output flags, or artifact directories.
+   - `references/maestro/js-scripting.md` before changing JavaScript helpers or logs.
+   - `references/maestro/cloud.md` only when saved finding scopes Cloud execution or Cloud artifact evidence.
+   - `references/maestro/mcp.md` only when saved finding scopes Maestro MCP or Viewer evidence.
+   - `references/audit-report-io.md` before report validation or source edits.
+   - `references/lessons.md` to load confirmed project lessons
+   - `references/mobile-context.md` for platform scope, parity, and device/emulator assumptions.
+   - `references/codebase-investigation.md` before changing unfamiliar flows, fixtures, setup/teardown, or CI wiring.
+   - `references/verification-ladder.md` before non-trivial edits.
+   - `references/context-firewall.md` before large reports, logs, screenshots, videos, JUnit XML, or generated artifacts.
+   - `references/naming-standards.md` before naming flows, tags, fixtures, selectors, or test data.
+3. Select and validate the report:
+   - Prefer an exact report path plus optional `MST-*` IDs.
+   - For `latest` or omitted path, require a concrete target focus, then select only from `audits/maestro/`.
+   - Validate metadata: `Workflow: maestro-audit`, `ProjectId`, `WorkflowSessionId`, `Target`, `Target Focus`, `Scope`, `Git Base`, `Git Head`, `Scenario Source`, flow inventory, Maestro run matrix, JUnit report/artifact evidence, Verification/Test Fidelity Checklist, and Execution Handoff.
+   - Stop on invalid, stale, target-drifted, or ambiguous reports.
+4. Extract actionable findings:
+   - Keep only selected `MST-*` findings with concrete location, scenario source, evidence, impacted journey, flake or coverage risk, simplest sufficient fix, and Verification Suggestion.
+   - Ignore no-finding claims, ruled-out candidates, skipped checks, and low-confidence ideas unless the user explicitly changes scope after revalidation.
+5. Revalidate current source and report drift:
+   - Reinspect current flow/subflow/fixture/setup files and current CI command shape.
+   - Confirm evidence still applies; stop or re-audit if files, flow paths, target, app behavior, or expected behavior have drifted.
+6. Fix only allowed artifacts:
+   - You may edit only Maestro flows, subflows, fixtures, setup/teardown, and test data unless the saved audit finding directly scopes Maestro CI/report wiring.
+   - Maestro flows.
+   - Subflows.
+   - Fixtures.
+   - Setup/teardown.
+   - Test data.
+   - Directly required Maestro CI/report wiring when the audit finding targets it.
+7. If evidence points to an app bug, product behavior gap, missing selector/test ID in production code, backend issue, or requirements ambiguity, stop and route to `workflows/debug.md`, `workflows/feature.md`, or `workflows/requirements/requirements-audit.md`. Do not modify production app behavior in this child workflow.
+8. Apply fixes using stable-flow design from `references/maestro/patterns.md`:
+   - Replace arbitrary sleeps with observable state waits when possible.
+   - Replace brittle selectors with stable selectors, accessibility labels, or test IDs already present.
+   - Keep setup/teardown explicit, idempotent, and isolated.
+   - Protect existing flows, subflows, fixtures, snapshots, baselines, report consumers, and CI commands unless the audit finding explicitly scopes them.
+9. Use strict harness sensors:
+   - If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
+     `python3 skills/massa-ai/scripts/lessons.py --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
+   - Apply the Mandatory Verification Fix Gate from `references/verification-ladder.md`: run the report's Verification Suggestion or an equivalent deterministic command/artifact check for each selected `MST-*` finding or coherent group.
+   - Prefer repository-specific Maestro commands; otherwise run `maestro test --format junit --output <report.xml> --test-output-dir <artifact-dir> <flow-or-directory>`.
+   - A finding cannot be marked `fixed` when a target-relevant command or artifact check exists but was not attempted.
+   - If verification cannot run, mark it `blocked`, `deferred`, or `skipped` with an allowed skipped-check reason.
+10. Produce a closure matrix with `MST-*` ID, status (`fixed`, `blocked`, `deferred`, or `skipped`), changed files, command/artifact, result, skipped reason or `none`, highest Verification Ladder level reached, validation assets protected, JUnit report path, artifact dir, device/platform, and residual risk.
+11. Persist only durable Maestro fix patterns, flake root causes, selector/test-ID policy, setup/teardown recipes, device matrix constraints, or reusable verification commands after Importance Calibration. Use `workflow:maestro-fix` and required memory tags.
+12. Complete the Evidence Gate from `references/evidence-gate.md`.
+
+## Examples
+
+User asks: "Fix MST-2 from audits/maestro/2026-06-29 maestro-audit.md."
+
+1. Read and validate the saved report.
+2. Reinspect current flow evidence and fix only the targeted Maestro flow/subflow/fixture surface.
+3. Run the report's Verification Suggestion or equivalent Maestro command and report the closure matrix.

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

@@ -0,0 +1,68 @@
+### Maestro
+
+Use this workflow to implement new Maestro mobile E2E flows from Jira/Confluence, prompt text, attached or local scenario files, or inferred scenarios when no explicit source is supplied.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+Before the first repository mutation, load `references/implementation-delivery.md` for worktree isolation, atomic commits, PR creation, CI watch, and the merge gate, and `references/code-annotation.md` for doc blocks, rationale comments, and test coverage on every created or updated unit. If two consecutive fix attempts fail on the same symptom, stop editing and load `references/root-cause-scripts.md`.
+
+Do not use this workflow for findings-only review of existing flows; route that to `workflows/maestro/maestro-audit.md`. Do not use it to execute saved audit findings; route those to `workflows/maestro/maestro-fix.md`. Do not use it for app bug fixes or product behavior changes; route those to `workflows/debug.md`, `workflows/feature.md`, or `workflows/requirements/requirements-audit.md`.
+
+1. Resolve/reuse `workflowSessionId`: `maestro-[entity]`.
+2. Load shared references:
+   - `references/maestro.md` as the index before choosing focused Maestro references.
+   - `references/maestro/fact-ledger.md` before making any Maestro claim; tag facts as `official-doc`, `live-help`, `repo-convention`, or `excluded/unverified`.
+   - `references/maestro/cli-device.md` before CLI checks, device/platform readiness, or local execution planning.
+   - `references/maestro/yaml-commands.md` before writing unfamiliar YAML commands, flow headers, AI commands, or command examples.
+   - `references/maestro/selectors.md` before choosing or changing selectors.
+   - `references/maestro/workspace-execution.md` before flow discovery, tags, execution ordering, sharding, or workspace config changes.
+   - `references/maestro/config-env-output.md` before editing flow header env/properties or CLI output/report flags.
+   - `references/maestro/js-scripting.md` before adding `evalScript`, `runScript`, `output`, `faker`, or JavaScript logs.
+   - `references/maestro/artifacts-reports.md` before report, artifact, debug-output, screenshot, video, recording, or AI report claims.
+   - `references/maestro/cloud.md` only when Cloud execution, app binary upload/reuse, Cloud devices, or Cloud auth is in scope.
+   - `references/maestro/mcp.md` only when Maestro MCP or Maestro Viewer is in scope.
+   - `references/maestro/patterns.md` before designing flow segmentation, setup/teardown, validation assets, or closure output.
+   - `references/mobile-context.md` for platform scope, parity, device assumptions, and mobile verification sensors.
+   - `references/codebase-investigation.md` before unfamiliar app, test, fixture, or CI source inspection.
+   - `references/verification-ladder.md` before non-trivial edits.
+   - `references/context-firewall.md` before inspecting large logs, generated reports, screenshots, videos, or broad flow output.
+   - `references/naming-standards.md` before naming flows, subflows, fixtures, tags, selectors, or test data.
+3. Run the mandatory Maestro CLI transcript gate from `references/maestro/cli-device.md` and `references/maestro/fact-ledger.md`: `command -v maestro`, `maestro --version` or `maestro --help`, and relevant subcommand help with command, exit code, stdout, and stderr. If missing or failing, block mutation and report install guidance.
+4. Resolve scenario input order:
+   - Jira/Confluence via Atlassian MCP.
+   - Attached/local file.
+   - Prompt text.
+   - Inferred scenarios.
+   If inference is used, warn the user and run `workflows/exploration.md` to ground expected behavior before writing flows.
+5. Discover existing Maestro structure using `references/maestro/workspace-execution.md`; follow existing repo structure, naming, tags, setup, teardown, fixtures, and artifact paths. If no Maestro workspace exists, ask for the target test root before creating one.
+6. Build the mobile context packet:
+   - Platform scope, app/build context, device/emulator assumptions, runtime state, feature flags, account/test data, locale/timezone, and parity target.
+   - Required setup, teardown, data isolation, and cleanup.
+   - Expected behavior and the deterministic sensor that proves it.
+7. Design the flow set using `references/maestro/patterns.md`:
+   - Keep flows readable and segmented by suite intent.
+   - Reuse existing subflows for login, onboarding, permissions, navigation, setup, and teardown.
+   - Prefer stable selectors, accessibility labels, test IDs, and observable states over text that changes often, coordinates, images, or fixed delays.
+   - Use deep links, API/fixture setup, and app state reset to avoid long UI-only preparation.
+8. Edit only Maestro flows, subflows, fixtures, setup/teardown, test data, and directly required docs/CI wiring for the new flow. If implementation requires product hooks, selectors, app code, or backend behavior changes, stop and route that work through the appropriate parent workflow.
+9. Verify with the strongest available deterministic command:
+   - Prefer repository-specific Maestro test commands.
+   - Otherwise run `maestro test --format junit --output <report.xml> --test-output-dir <artifact-dir> <flow-or-directory>`.
+   - If device/app/backend access is unavailable, run static YAML, path, selector, or CI configuration checks and mark runtime verification blocked, deferred, or skipped with an allowed reason.
+10. Produce a closure summary with scenario source, changed flows/subflows/fixtures/setup/teardown, command, exit status, JUnit path, artifact dir, device/platform/app build, skipped reason, highest Verification Ladder level reached, validation assets protected, memory outcome, and residual risk.
+11. Persist only durable Maestro conventions, selector/test-ID policy, fixture/setup recipes, device matrix constraints, or reusable verification recipes after scoring with the Importance Calibration System. Use required tags: `project:<projectId>`, `session:<workflowSessionId>`, `workflow:maestro`, `entity:<entity>`, and one `memory:<tier>` tag.
+12. Complete the Evidence Gate from `references/evidence-gate.md`.
+
+## Examples
+
+User asks: "Add Maestro coverage for the Jira checkout coupon scenario."
+
+1. Resolve the Jira source through Atlassian MCP, run the Maestro CLI preflight, and discover the existing flow root.
+2. Create or update the smallest flow/subflow set that covers the coupon journey.
+3. Run the focused Maestro command with JUnit report and artifact output, or record the blocked runtime dependency.
+
+User asks: "Create a Maestro login smoke test from this YAML scenario file."
+
+1. Read the local scenario file, map setup/teardown and expected states, and reuse existing login fixtures/subflows.
+2. Add the flow under the existing smoke suite.
+3. Verify with the repository's Maestro smoke command.