@massa-ai/codex-plugin 1.25.0 → 1.27.0

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.

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

@@ -1,6 +1,6 @@
 # Android Views Figma Contract
 
-Load this reference only for Target Surface Packet rows classified as Android Views XML.
+Load only for Target Surface Packet rows classified as Android Views XML.
 
 - Resolve `res/layout`, qualifiers, includes/merges, styles/themes, dimensions, colors/selectors, text appearances, drawables, fonts, strings, binding/adapters, and Material components affecting the surface.
 - Follow aliases to final values. Record the symbolic resource chain and resolved value.

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

@@ -1,6 +1,6 @@
 # Mobile Figma Core
 
-Use this shared reference after `repository-detection.md` identifies one or more target surfaces. It defines Figma evidence, requirements boundaries, asset handling, mapping and comparison semantics, runtime evidence, and parity-claim limits. Load only the platform references named by the Target Surface Packet.
+Use after `repository-detection.md` identifies one or more target surfaces. Defines Figma evidence, requirements boundaries, asset handling, mapping and comparison semantics, runtime evidence, and parity-claim limits. Load only the platform references named by the Target Surface Packet.
 
 ## Boundaries
 

package/skills/massa-ai/references/mobile-figma-matcher/ios-swiftui.md

@@ -1,6 +1,6 @@
 # iOS SwiftUI Figma Contract
 
-Load this reference only for Target Surface Packet rows classified as iOS SwiftUI.
+Load only for Target Surface Packet rows classified as iOS SwiftUI.
 
 - Resolve `View` composition, modifiers, layout containers, environment values, state selection, navigation entry, styles, asset catalogs, symbols, fonts, previews, accessibility modifiers, and UIKit hosting/interoperability affecting the surface.
 - Compare Figma coordinates with SwiftUI points, then account for display scale only for rendered-pixel evidence.

package/skills/massa-ai/references/mobile-figma-matcher/ios-uikit.md

@@ -1,6 +1,6 @@
 # iOS UIKit Figma Contract
 
-Load this reference only for Target Surface Packet rows classified as iOS UIKit.
+Load only for Target Surface Packet rows classified as iOS UIKit.
 
 - Resolve storyboards, XIBs, programmatic views, view controllers, reusable views/cells, Auto Layout constraints, appearance APIs, trait-dependent resources, asset catalogs, fonts, strings, and state configuration.
 - Compare Figma coordinates with UIKit points, then account for device display scale only when validating rendered pixels.

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

@@ -1,6 +1,6 @@
 # KMP Compose Multiplatform Figma Contract
 
-Load this reference only for shared Compose Multiplatform Target Surface Packet rows.
+Load only for shared Compose Multiplatform Target Surface Packet rows.
 
 - Resolve common composables, shared state, theme/design tokens, Compose resources, adaptive layout, accessibility semantics, platform adapters, and `expect`/`actual` declarations affecting presentation.
 - Keep business/domain behavior in established shared boundaries. Do not move platform-only UI behavior into common code merely to reduce duplication.

package/skills/massa-ai/references/mobile-figma-matcher/repository-detection.md

@@ -1,6 +1,6 @@
 # Mobile Figma Repository Detection
 
-Use this reference before loading any stack-specific matcher reference. Classify the concrete target module and files, not the repository root or repository name.
+Use before loading any stack-specific matcher reference. Classify the concrete target module and files, not the repository root or repository name.
 
 Monorepositories may contain several valid mobile stacks; classify only modules connected to the requested target.
 

package/skills/massa-ai/references/naming-standards.md

@@ -1,6 +1,6 @@
 # Naming Standards
 
-Use this reference when a workflow writes code, drafts implementation contracts, audits code quality, or executes findings that introduce, rename, or preserve identifiers.
+Use when a workflow writes code, drafts implementation contracts, audits code quality, or executes findings that introduce, rename, or preserve identifiers.
 
 ## Goal
 

package/skills/massa-ai/references/pr-task-fix.md

@@ -1,12 +1,12 @@
 # PR Task Fix
 
-Load this reference from `workflows/feature.md` and `workflows/refactor.md` before non-trivial implementation or refactor execution that can be decomposed into reviewable task groups.
+Load from `workflows/feature.md` and `workflows/refactor.md` before non-trivial implementation or refactor execution that can be decomposed into reviewable task groups.
 
 ## ADR/TDD Input Gate
 
 Before decomposition, inspect the first user prompt, current prompt context, explicitly attached or readable local files, and any already supplied Atlassian MCP source pointers.
 
-If there is no ADR or TDD plain text, no attached/readable ADR or TDD file, and no already supplied Atlassian ADR/TDD source, ask whether the user wants to provide an ADR or TDD through Atlassian MCP. Do not ask again when the user has already supplied, declined, or made Atlassian unavailable for this run.
+If there is no ADR or TDD plain text, no attached/readable ADR or TDD file, and no already-supplied Atlassian ADR/TDD source, ask whether the user wants to provide an ADR or TDD through Atlassian MCP. Do not ask again once the user has already supplied, declined, or made Atlassian unavailable for this run.
 
 Use ADR/TDD input as implementation context, not as permission to bypass the active workflow's scope, source verification, or verification recipe. If the ADR/TDD conflicts with current source or project instructions, surface the conflict and resolve it before implementation.
 

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

@@ -1,6 +1,6 @@
 # Project Context Intake
 
-Use this reference at the start of every workflow, before the first substantive
+Use at the start of every workflow, before the first substantive
 read, edit, plan, or answer. It defines the minimum project-context sweep that
 makes agent behavior match this repository's actual conventions instead of
 generic defaults.
@@ -41,7 +41,7 @@ When two sources conflict, the higher tier wins:
 6. Current repository source code.
 7. Recalled memory — context only, never canonical.
 
-A conflict between a doc and current source is a finding: report it rather than
+A conflict between a doc and current source is a finding — report it rather than
 silently picking a side.
 
 ## Dedupe Guard

package/skills/massa-ai/references/repo-rules-discovery.md

@@ -1,7 +1,7 @@
 # Repo Rules Discovery
 
-Use this reference from `workflows/spec-driven.md` before the first repository
-mutation. It defines how to discover, load, and enforce the target repository's
+Use from `workflows/spec-driven.md` before the first repository
+mutation. Defines how to discover, load, and enforce the target repository's
 own AI-harness rules and implementation conventions, so spec-driven
 implementation conforms to the repo it runs in rather than only to the
 skill's defaults.
@@ -12,8 +12,8 @@ the target repo**: it loads what is present and never invents what is absent.
 ## Principle
 
 A repository's rules live in its own harness files and conventions. spec-driven
-must read them before implementing and enforce conformance, because a change
-that follows the skill's defaults but violates the repo's module layout, test
+must read them before implementing and enforce conformance — a change that
+follows the skill's defaults but violates the repo's module layout, test
 placement, or lint rules is not deliverable. Silence here reads as "the repo
 has no rules", which is almost never true — it means they were not looked up.
 

package/skills/massa-ai/references/rfc/discovery-and-sizing.md

@@ -1,6 +1,6 @@
 # RFC Discovery And Classification
 
-Load this reference before source investigation, RFC classification, impact selection, or clarification questions.
+Load before source investigation, RFC classification, impact selection, or clarification questions.
 
 ## Workflow Fit
 

package/skills/massa-ai/references/rfc/document-contract.md

@@ -1,6 +1,6 @@
 # RFC Document Contract
 
-Load this reference when drafting or revising an RFC. Preserve the full decision structure while tailoring detail to the RFC type and impact.
+Load when drafting or revising an RFC. Preserve the full decision structure while tailoring detail to the RFC type and impact.
 
 ## Section Contract
 

package/skills/massa-ai/references/rfc/quality-and-lifecycle.md

@@ -1,6 +1,6 @@
 # RFC Quality And Lifecycle
 
-Load this reference before challenging, finalizing, saving, updating, or closing an RFC.
+Load before challenging, finalizing, saving, updating, or closing an RFC.
 
 ## Quality Gate
 

package/skills/massa-ai/references/root-cause-scripts.md

@@ -1,6 +1,6 @@
 # Root-Cause Proof Scripts
 
-Use this reference the moment an implementation or fix stops converging. It is a
+Use the moment an implementation or fix stops converging. It is a
 circuit breaker, not a diagnosis method: it fires mid-implementation in any
 workflow — `feature`, `debug`, `refactor`, `spec-driven`, any `*-fix` — including
 the ones that never opened a reproduction loop.
@@ -11,7 +11,7 @@ This file is where any implementation *stops guessing*.
 ## Principle
 
 An agent that has failed twice on the same symptom does not have a code-reading
-problem. It has a data problem. Reading the same source a third time produces a
+problem — it has a data problem. Reading the same source a third time produces a
 third theory with the same evidence base as the first two. The only way out is
 to make the program tell you what it is actually doing.
 

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

@@ -0,0 +1,73 @@
+# SonarQube MCP Protocol
+
+Use from `workflows/implementation/implementation-audit.md` and
+`workflows/implementation/implementation-fix.md` when SonarQube MCP tools may
+be available for the current implementation scope.
+
+## Detection And Availability
+
+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.
+
+## Firewall And Invocation
+
+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 the selected SonarQube tools
+require.
+
+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.
+
+## Normalization Areas
+
+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.
+
+## Preserved Fields
+
+Preserve Sonar issue key, rule key, tool name, severity/impact, file/line,
+quality gate condition, and evidence summary inside the normalized finding.
+
+## ID Mapping
+
+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. The canonical area/prefix table and discipline live in
+`references/audit-report-io.md` (Source-Qualified Finding IDs).
+
+## Exclusion Rules
+
+Keep unmapped, duplicate, low-context, or out-of-scope SonarQube results in
+Scope And Evidence or skipped checks, not in Findings or Execution Handoff.
+
+## Reporting Integration
+
+- Include SonarQube MCP as evidence in the coverage matrix or Scope And
+  Evidence, with quality gate status when available.
+- Sonar-derived findings enter the execution handoff only after normalization
+  to one supported source lens ID, with enough evidence for
+  `implementation-fix` to revalidate from the saved markdown report.
+- Do not persist raw SonarQube output; persist only normalized, durable
+  patterns after Importance Calibration.
+
+## Fix-Time Consumption
+
+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.

package/skills/massa-ai/references/spec-driven/artifact-store.md

@@ -1,6 +1,6 @@
 # Spec-Driven Artifact Store
 
-Use this reference before any spec-driven workflow reads or writes feature registry, progress, handoff, phase artifacts, validation reports, or lessons. `.specs/` files are the canonical state layer for spec-driven logical artifacts.
+Use before any spec-driven workflow reads or writes feature registry, progress, handoff, phase artifacts, validation reports, or lessons. `.specs/` files are the canonical state layer for spec-driven logical artifacts.
 
 ## Source Of Truth
 

package/skills/massa-ai/references/spec-driven/brownfield-mapping.md

@@ -0,0 +1,16 @@
+# Brownfield Onboarding — 7-Doc Codebase Mapping
+
+Use from `workflows/spec-driven.md` when the target codebase
+has not yet been mapped (brownfield, new repo, or cold project). The map is
+the shared factual ground for requirements, design, and task derivation;
+each doc feeds a downstream phase.
+
+| Doc | Derives | Feeds |
+| --- | --- | --- |
+| `STACK.md` | languages, runtimes, frameworks, key libraries | Design constraints, verification commands |
+| `ARCHITECTURE.md` | layers, modules, boundaries, data flow | Design, risk surface |
+| `CONVENTIONS.md` | naming, file layout, commit/test conventions | Tasks, Execute |
+| `STRUCTURE.md` | directory map, where new code goes | Tasks, file placement |
+| `TESTING.md` | test runner, how to run gates, coverage tooling | Gate Check Commands, verification recipe |
+| `INTEGRATIONS.md` | external services, APIs, contracts, auth | Discuss, risk escalation |
+| `CONCERNS.md` | known risks, tech debt, migration landmines, security/privacy hotspots | Risk-domain escalation, validation focus |

package/skills/massa-ai/references/spec-driven/code-analysis.md

@@ -1,6 +1,6 @@
 # Spec-Driven Code Analysis
 
-Use this reference when Specify, Design, Tasks, Execute, or Validate needs source inspection or structural code search.
+Use when Specify, Design, Tasks, Execute, or Validate needs source inspection or structural code search.
 
 <!-- validator anchors: current repository source and approved .specs/ artifacts override stale memory -->
 

package/skills/massa-ai/references/spec-driven/coding-principles.md

@@ -1,6 +1,6 @@
 # Spec-Driven Coding Principles
 
-Use this reference before writing or changing implementation, tests, fixtures, validation assets, scripts, or docs during Execute.
+Use before writing or changing implementation, tests, fixtures, validation assets, scripts, or docs during Execute.
 
 Behavioral bias, not checklist. Read before every implementation.
 

package/skills/massa-ai/references/spec-driven/context-limits.md

@@ -1,6 +1,6 @@
 # Spec-Driven Context Limits
 
-Use this reference when planning context loading for a spec-driven feature or when `.specs/features/<slug>/` artifacts grow large enough to reduce implementation quality.
+Use when planning context loading for a spec-driven feature or when `.specs/features/<slug>/` artifacts grow large enough to reduce implementation quality.
 
 ## Targets