@massa-ai/cursor-plugin 1.26.0 → 1.29.0

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

@@ -1,17 +1,25 @@
+---
+name: design
+description: "Implements or updates a concrete mobile UI from structured Figma evidence or screenshots when no saved audit report exists; route comparisons to mobile-figma-audit."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Design
 
-Use this workflow to implement or update a concrete Android, iOS, or KMP Compose Multiplatform UI from structured Figma evidence or supplied screenshot context when no saved mobile Figma audit report is the source of truth. Route findings-only comparison to `mobile-figma-audit` and saved `MFM-*` remediation to `mobile-figma-fix`.
+Implement or update a concrete Android, iOS, or KMP Compose Multiplatform UI from structured Figma evidence or supplied screenshot context when no saved mobile Figma audit report is the source of truth. Route findings-only comparison to `mobile-figma-audit` and saved `MFM-*` remediation to `mobile-figma-fix`.
 
-Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-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`.
+Before the first repository mutation, load `references/implementation-delivery.md` (delivery chain: worktree, atomic commits, PR, CI watch, merge gate) and `references/code-annotation.md` (doc blocks, rationale, test coverage). After two consecutive failed fixes on one symptom, stop editing and load `references/root-cause-scripts.md`.
 
-Do not use this workflow for Flutter, React Native, web UI, generic Figma exploration, variable-only queries, or MCP troubleshooting.
+Not for Flutter, React Native, web UI, generic Figma exploration, variable-only queries, or MCP troubleshooting.
 
 1. Resolve/reuse `workflowSessionId`: `design-[entity]`.
 2. Load `references/mobile-figma-matcher/repository-detection.md`, `references/mobile-figma-matcher/core.md`, `references/mobile-context.md`, `references/codebase-investigation.md`, and `references/verification-ladder.md`. When Figma links or node IDs are provided, load `references/figma-pre-analysis.md` and run its two-stage sequential retrieval protocol before building the Figma Evidence Packet. Load `references/context-firewall.md` before large design/runtime artifacts and `references/synapse-policy.md` when repeated massa-ai searches are expected.
 3. `recall` -> load current component conventions, design-system rules, approved platform/accessibility deviations, prior Figma mappings, asset pipelines, and reusable render recipes. Memory is context, not proof.
-4. Require a concrete feature/module target plus at least one design source: readable Figma node/selection or supplied screenshots. Resolve required visual and interactive states plus a requirements source for behavior not represented in the design source. Ask only when target ownership, runtime platforms, platform-frame mappings, or screenshot authority remain ambiguous after source inspection.
+4. Require a concrete feature/module target plus at least one design source: readable Figma node/selection or supplied screenshots. Resolve required visual and interactive states plus a requirements source for behavior not represented in the design source. Ask only when target ownership, runtime platforms, platform-frame mappings, or screenshot authority stay ambiguous after source inspection.
 5. Build the immutable Target Surface Packet before loading stack guidance. Classify each selected surface and load only its contracts:
    - Android Views XML -> `references/mobile-figma-matcher/android-views.md`.
    - Android Jetpack Compose -> `references/mobile-figma-matcher/android-compose.md`.
@@ -19,8 +27,8 @@ Do not use this workflow for Flutter, React Native, web UI, generic Figma explor
    - iOS SwiftUI -> `references/mobile-figma-matcher/ios-swiftui.md`.
    - Shared KMP Compose Multiplatform -> `references/mobile-figma-matcher/kmp-compose-multiplatform.md` plus native contracts only for selected native source sets, hosts, wrappers, or runtime targets.
 6. Build the Figma Evidence Packet with metadata when needed, design context, screenshot, variables, current Code Connect mappings, variants/states, annotations, and asset inventory. For screenshot-only sources, build a Screenshot Context Packet with provenance, target state, visible constraints, uncertainty, and `Design Evidence Class: screenshot-context-only`; do not infer exact Figma tokens, dimensions, variables, variants, or parity from screenshots alone. Stop if neither structured Figma evidence nor supplied screenshot context is available.
-7. Resolve current components, tokens, resources, assets, source-set ownership, platform adapters, requirements, and existing validation sensors. Create the Design-To-Code Mapping Matrix and one comparison configuration for every selected runtime surface; screenshot-only rows must use inferred visual intent rather than `Figma Value`.
-8. Size the work with the Verification Ladder. Route broad application work, unresolved architecture, cross-feature design-system migration, or implementation that will not fit one clean context window to `spec-driven`.
+7. Resolve current components, tokens, resources, assets, source-set ownership, platform adapters, requirements, and existing validation sensors. Create the Design-To-Code Mapping Matrix and one comparison configuration per selected runtime surface; screenshot-only rows use inferred visual intent, not `Figma Value`.
+8. Size the work with the Verification Ladder. Route broad application work, unresolved architecture, cross-feature design-system migration, or implementation that won't fit one clean context window to `spec-driven`.
 9. Establish the verification recipe before editing. Protect tests, snapshots, screenshot baselines, fixtures, previews, accessibility identifiers, test tags, and automation flows from weakening.
 10. Implement coherent slices using the smallest correct ownership boundary:
     - Reuse existing components and tokens only after resolving semantics, states, accessibility, and values.

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

@@ -1,20 +1,28 @@
+---
+name: exploration
+description: "Read-only workflow for understanding a codebase, module, data flow, runtime behavior, schema, dependency, or architecture area before requesting changes."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### 🔵 Exploration
 
-Use this workflow when the user wants to understand a codebase, module, data flow, runtime behavior, schema, dependency, or architecture area before asking for changes. Exploration is read-only: do not implement, refactor, rewrite docs, or mutate project files unless the user explicitly changes workflows or asks for edits.
+Use when the user wants to understand a codebase, module, data flow, runtime behavior, schema, dependency, or architecture area before asking for changes. Exploration is read-only: do not implement, refactor, rewrite docs, or mutate project files unless the user explicitly changes workflows or asks for edits.
 
-Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
 ## Golden Rules
 
 Inviolable across every exploration:
 
-1. **Never assume or invent.** Uncertainty is always preferable to fabrication; invented APIs, symbols, or patterns cascade into wrong answers.
+1. **Never assume or invent.** Uncertainty always beats fabrication; invented APIs, symbols, or patterns cascade into wrong answers.
 2. **Deserves-a-note.** When understanding is worth persisting, record what is durable — not trivia.
 3. **Pointers, not copies.** Link/reference source (`path`, symbol, line); do not duplicate bulk content into notes or reports.
 4. **Surgical precision.** Make the smallest sufficient change; in Exploration, that usually means the smallest sufficient read set.
 5. **Verify against source.** Treat indexed context, memories, and external summaries as leads until confirmed against current source.
 
-Write and search in the user's human language. Match the language of the user's prompt for explanations, notes, and questions; match the language of the codebase for identifiers, paths, and commands.
+Write and search in the user's human language. Match the user's prompt language for explanations, notes, and questions; match the codebase's language for identifiers, paths, and commands.
 
 ## Knowledge Verification Chain
 

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

@@ -1,10 +1,18 @@
+---
+name: feature
+description: "Use this workflow to add a new capability, screen, command, integration, or user-facing improvement with clear intent; route broken behavior to debug and broad work to spec-driven."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### 🟡 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`.
+Use when the user wants to add a new capability, screen, command, integration, behavior, or user-facing improvement with clear intent or acceptance criteria. Not for broken behavior — route to `workflows/debug.md`. Not for broad, ambiguous, migration-heavy, or cross-boundary work — route 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.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-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`.
+Before the first repository mutation, load `references/implementation-delivery.md` (delivery chain: worktree, atomic commits, PR, CI watch, merge gate) and `references/code-annotation.md` (doc blocks, rationale, test coverage). After two consecutive failed fixes on one 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
@@ -18,21 +26,14 @@ Before the first repository mutation, load `references/implementation-delivery.m
    - `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. When Figma links or node IDs are supplied, load `references/figma-pre-analysis.md` and run its two-stage sequential retrieval protocol before consuming the design evidence.
-   - Preserve mobile Figma routing by intent: compare/audit wording uses `workflows/mobile-figma/mobile-figma-audit.md`; saved `MFM-*` findings use `workflows/mobile-figma/mobile-figma-fix.md`.
-   - If Figma sources are supplied for unsupported targets such as Flutter, React Native, web, desktop, or generic design exploration, do not run mobile Figma. Record that the Figma source is outside mobile Figma scope and continue the normal feature workflow.
-   - Figma defines visible design intent and represented variants only. Screenshots are context-only unless paired with structured Figma evidence; do not claim exact Figma parity, tokens, variables, or dimensions from screenshots alone. Product behavior not represented by the design source still requires a separate requirements source.
+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 design-source intake gate from `references/mobile-context.md` (Design-Source Intake Gate) before implementation.
 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.
+   `search.sessionId`. For multi-search investigations, run the Synapse task envelope per `references/synapse-policy.md`: `synapse_task_begin` before the first search, `synapse_prefetch` on deep file open, `synapse_task_end` at completion (both `task` calls 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.
@@ -42,7 +43,7 @@ Before the first repository mutation, load `references/implementation-delivery.m
    - 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.
+   - When every group has a confirmed Jira key, follow the optional stacked branch flow in `references/pr-task-fix.md` (Jira-Key Stacked Branches).
 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`:
      `bun skills/massa-ai/scripts/lessons.ts --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):

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

@@ -1,14 +1,22 @@
+---
+name: general
+description: "Final fallback workflow for coding, planning, review, or implementation work when no specialized massa-ai workflow is a better match."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### 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.
+Use for coding, planning-before-coding, review, or implementation work when no specialized massa-ai workflow is a better match. 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.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-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`.
+Before the first repository mutation, load `references/implementation-delivery.md` (delivery chain: worktree, atomic commits, PR, CI watch, merge gate) and `references/code-annotation.md` (doc blocks, rationale, test coverage). After two consecutive failed fixes on one 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.
+3. Recall relevant durable context with `recall`. Treat recalled memory as a lead until current source confirms it. Confirm 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:
    `bun skills/massa-ai/scripts/lessons.ts --root . list --status confirmed`
@@ -30,10 +38,7 @@ Before the first repository mutation, load `references/implementation-delivery.m
 
 ## 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.
+On any tool/index/MCP failure, follow `references/graceful-degradation.md` (also `SKILL.md` Graceful Degradation).
 
 ## Output Contract
 

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

@@ -1,10 +1,18 @@
+---
+name: implementation-audit
+description: "Findings-only multi-lens audit of a concrete implementation target that dispatches child audit lenses and saves one durable report for implementation-fix."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### 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.
+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.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-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`.
+Not for a single requested 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:
@@ -45,18 +53,10 @@ Do not use this parent workflow when the user wants only one audit lens; route d
 
     - 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.
+9. Check whether SonarQube MCP is available and useful for the implementation scope. If available, use it per `references/sonarqube-mcp.md` (detection, firewall, normalization, ID mapping); otherwise record `SonarQube MCP: not evaluated` with the skipped-check reason and continue.
 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.
+   - Include SonarQube MCP evidence per `references/sonarqube-mcp.md` (Reporting Integration).
    - 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`.
@@ -69,8 +69,8 @@ Do not use this parent workflow when the user wants only one audit lens; route d
    - 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.
+   - Sonar-derived findings: see `references/sonarqube-mcp.md` (Reporting Integration) for execution-handoff eligibility.
+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 or raw child output; SonarQube output persistence follows `references/sonarqube-mcp.md`.
 13. Complete `references/evidence-gate.md`.
 
 ## Examples

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

@@ -1,10 +1,18 @@
+---
+name: implementation-fix
+description: "Executes confirmed findings from a saved implementation audit report; the saved audits/implementation report is the source of truth, not chat summaries."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Implementation Fix
 
-Use this workflow only to execute confirmed findings from a saved implementation audit markdown report.
+Execute confirmed findings from a saved implementation audit markdown report only.
 
-Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-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`.
+Before the first repository mutation, load `references/implementation-delivery.md` (delivery chain: worktree, atomic commits, PR, CI watch, merge gate) and `references/code-annotation.md` (doc blocks, rationale, test coverage). After two consecutive failed fixes on one 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`.
 
@@ -24,7 +32,7 @@ Do not execute from chat summaries, inline review comments, remembered findings,
    - 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`.
+   - Validate the report deterministically: `bun skills/massa-ai/scripts/validate_audit_report.ts <path> --family implementation` (`references/audit-report-io.md`, Deterministic Validation); non-zero exit rejects the report (missing metadata, or malformed/duplicate/gapped/mis-Area'd source-qualified IDs).
 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.
@@ -33,7 +41,7 @@ Do not execute from chat summaries, inline review comments, remembered findings,
 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.
+   - SonarQube-derived items: see `references/sonarqube-mcp.md` (Fix-Time Consumption) — actionable only via normalized report entries, never raw MCP output.
    - 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.

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

@@ -1,10 +1,18 @@
+---
+name: judge-with-debate
+description: "Explicit-route workflow to evaluate an artifact through multi-judge debate against a tailored specification, converging on a consensus verdict or honest no-consensus."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Judge With Debate
 
-Use this workflow when the user explicitly asks to evaluate an artifact through multi-judge
+Use when the user explicitly asks to evaluate an artifact through multi-judge
 debate — "judge this", "judge-with-debate", "evaluate with debate", "run the judges on X". The
 user supplies artifact path(s) plus a task description (what the artifact was supposed to
-accomplish) and optionally evaluation context. This is a standalone, explicit-route workflow: it
-is never auto-selected by the router for generic review work (use `reviewer`, `*-audit`, or
+accomplish) and optionally evaluation context. Standalone, explicit-route workflow: never
+auto-selected by the router for generic review work (use `reviewer`, `*-audit`, or
 `plan-critic` for those).
 
 The protocol: a meta-judge authors a tailored evaluation specification **once**; three
@@ -13,7 +21,7 @@ disagreements over **up to 3 rounds**; the panel converges on a consensus verdic
 honest no-consensus. Ported from the NeoLabHQ `judge-with-debate` pattern; this file is the
 canonical contract here — repository contracts win on any conflict with the base.
 
-Before the first substantive read, load `references/project-context.md` and run the
+Before the first substantive read, load `references/project-context.md` and run its
 project-context intake sweep for the target repository (the workspace holding the artifact
 under evaluation, which may differ from this repo).
 

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

@@ -1,8 +1,16 @@
+---
+name: long-session
+description: "Use this workflow for same-session handoff, continuation, or safe stopping when work is unfinished, context budget is low, or verbose context reduces execution quality."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### 🟠 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.
+Use 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.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
 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.
 

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

@@ -1,10 +1,18 @@
+---
+name: maestro-audit
+description: "Findings-only audit of existing Maestro mobile E2E flows, fixtures, setup/teardown, reports, selector stability, flake risk, and scenario coverage; does not edit code."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### 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.
+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.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-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.
+Do not edit code or flows in this workflow. Not for new flow implementation — route 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:

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

@@ -1,10 +1,18 @@
+---
+name: maestro-fix
+description: "Child-only workflow to fix confirmed MST-prefixed findings from a saved Maestro audit report or an explicit maestro-audit handoff."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Maestro Fix
 
-Use this child-only workflow to fix confirmed `MST-*` findings from a saved Maestro audit report or an explicit `maestro-audit` handoff.
+Child-only workflow: 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.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-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`.
+Before the first repository mutation, load `references/implementation-delivery.md` (delivery chain: worktree, atomic commits, PR, CI watch, merge gate) and `references/code-annotation.md` (doc blocks, rationale, test coverage). After two consecutive failed fixes on one 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.
 
@@ -32,7 +40,7 @@ Reject direct use without a saved `audits/maestro/<YYYY-MM-DD maestro-audit.md>`
 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.
+   - Validate metadata deterministically: `bun skills/massa-ai/scripts/validate_audit_report.ts <path> --family maestro` (`references/audit-report-io.md`, Deterministic Validation); non-zero exit blocks editing. Also confirm flow inventory, Maestro run matrix, JUnit report/artifact evidence, Verification/Test Fidelity Checklist, and Execution Handoff are present.
    - 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.

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

@@ -1,12 +1,20 @@
+---
+name: maestro
+description: "Implements new Maestro mobile E2E flows from Jira/Confluence, prompt text, attached scenario files, or inferred scenarios when no explicit source is supplied."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### 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.
+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.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-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`.
+Before the first repository mutation, load `references/implementation-delivery.md` (delivery chain: worktree, atomic commits, PR, CI watch, merge gate) and `references/code-annotation.md` (doc blocks, rationale, test coverage). After two consecutive failed fixes on one 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`.
+Not for findings-only review of existing flows — route to `workflows/maestro/maestro-audit.md`. Not to execute saved audit findings — route to `workflows/maestro/maestro-fix.md`. Not for app bug fixes or product behavior changes — route to `workflows/debug.md`, `workflows/feature.md`, or `workflows/requirements/requirements-audit.md`.
 
 1. Resolve/reuse `workflowSessionId`: `maestro-[entity]`.
 2. Load shared references:

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

@@ -1,10 +1,18 @@
+---
+name: mobile-figma-audit
+description: "Findings-only audit comparing an existing mobile UI implementation against Figma MCP evidence for a concrete feature, file set, screen, or commit range; does not edit code."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Mobile Figma Audit
 
-Use this workflow for a findings-only audit of whether an existing Android Views XML, Android Jetpack Compose, iOS UIKit, iOS SwiftUI, KMP Compose Multiplatform, or mixed KMP/native implementation matches a specific Figma design. It compares Figma MCP evidence with a concrete feature, file set, screen, class/composable/view, commit range, branch comparison, or modified-file target.
+Findings-only audit of whether an existing Android Views XML, Android Jetpack Compose, iOS UIKit, iOS SwiftUI, KMP Compose Multiplatform, or mixed KMP/native implementation matches a specific Figma design. It compares Figma MCP evidence with a concrete feature, file set, screen, class/composable/view, commit range, branch comparison, or modified-file target.
 
-Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-Do not edit code. Route direct design implementation to `design`. Do not use this workflow for Flutter, React Native, web styling, generic Figma exploration, or MCP troubleshooting.
+Do not edit code. Route direct design implementation to `design`. Not for Flutter, React Native, web styling, generic Figma exploration, or MCP troubleshooting.
 
 1. Resolve/reuse `workflowSessionId`: `mobile-figma-audit-[entity]`.
 2. Load shared references:

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

@@ -1,10 +1,18 @@
+---
+name: mobile-figma-fix
+description: "Fixes confirmed MFM-prefixed findings from a saved mobile Figma audit report; the saved audit report is the source of truth, not screenshots or chat summaries."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Mobile Figma Fix
 
-Use this workflow only to fix confirmed `MFM-*` findings from a saved mobile Figma audit report.
+Fix confirmed `MFM-*` findings from a saved mobile Figma audit report only.
 
-Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-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`.
+Before the first repository mutation, load `references/implementation-delivery.md` (delivery chain: worktree, atomic commits, PR, CI watch, merge gate) and `references/code-annotation.md` (doc blocks, rationale, test coverage). After two consecutive failed fixes on one symptom, stop editing and load `references/root-cause-scripts.md`.
 
 Do not execute from chat summaries, screenshots alone, remembered findings, or an unsaved comparison table. The saved `audits/mobile-figma/<YYYY-MM-DD mobile-figma-audit>.md` report is the source of truth. Route fresh comparison work to `mobile-figma-audit`.
 
@@ -23,7 +31,7 @@ Do not execute from chat summaries, screenshots alone, remembered findings, or a
 4. Select a report and target focus:
    - Prefer an exact report path plus optional `MFM-*` IDs.
    - For `latest` or omitted path, require a concrete target focus, then select only from `audits/mobile-figma/`.
-   - Stop if no report exists or metadata does not identify `Workflow: mobile-figma-audit`, project/session, target/focus/scope, source timestamp, repository classification, Target Surface Matrix, Figma source/node mappings/timestamp, per-surface platform configurations, capability matrix, and comparison matrix.
+   - Validate metadata deterministically: `bun skills/massa-ai/scripts/validate_audit_report.ts <path> --family mobile-figma` (`references/audit-report-io.md`, Deterministic Validation); non-zero exit blocks editing. Also stop if no report exists or the report lacks Target Surface Matrix, Figma source/node mappings/timestamp, per-surface platform configurations, capability matrix, or comparison matrix.
    - Reject legacy Android-only reports without the Target Surface Matrix and `Surface ID` fields. Require a fresh audit; do not infer or migrate the missing schema.
 5. Validate report freshness before editing:
    - Re-resolve the target files, rebuild the Target Surface Packet, and verify git scope/base/head when relevant.

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

@@ -1,8 +1,16 @@
+---
+name: onboarding
+description: "Use this workflow on a first session or with missing project context to resolve project identity, establish memory/index state, and capture an architecture overview."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### 🟢 Onboarding (New Project / First Session)
 
-Use this workflow for a first session, missing project context, or repo setup where the agent must resolve the project identity, establish usable memory/index state, and capture a high-level architecture overview before deeper work.
+Use for a first session, missing project context, or repo setup where the agent must resolve the project identity, establish usable memory/index state, and capture a high-level architecture overview before deeper work.
 
-Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
 1. Resolve `projectId` and `workflowSessionId` (`onboarding-[entity]`).
 2. `recall` -> check for existing project identity and knowledge.

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

@@ -1,10 +1,18 @@
+---
+name: refactor
+description: "Behavior-preserving structural cleanup, simplification, decoupling, and testability workflow; route broken behavior to debug and broad boundary redesign to architecture-audit or spec-driven."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### 🔨 Refactor
 
-Use this workflow for behavior-preserving structural cleanup, simplification, decoupling, testability improvements, and code organization changes where the intended external behavior stays the same. Do not use it for broken behavior; route that to `workflows/debug.md`. Do not use it for broad boundary redesign, migration, or unclear architecture direction; route that to `workflows/architecture/architecture-audit.md` or `workflows/spec-driven.md`.
+Use for behavior-preserving structural cleanup, simplification, decoupling, testability improvements, and code organization changes where the intended external behavior stays the same. Not for broken behavior — route to `workflows/debug.md`. Not for broad boundary redesign, migration, or unclear architecture direction — route to `workflows/architecture/architecture-audit.md` or `workflows/spec-driven.md`.
 
-Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-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`.
+Before the first repository mutation, load `references/implementation-delivery.md` (delivery chain: worktree, atomic commits, PR, CI watch, merge gate) and `references/code-annotation.md` (doc blocks, rationale, test coverage). After two consecutive failed fixes on one symptom, stop editing and load `references/root-cause-scripts.md`.
 
 1. Resolve/reuse `workflowSessionId`: `refactor-[entity]`
 2. `recall` → load architectural decisions and coupling patterns for the area
@@ -37,7 +45,7 @@ Before the first repository mutation, load `references/implementation-delivery.m
    - Order non-breaking groups by Data, Domain, then Presentation/Navigation, mapping those labels to repository boundaries when needed.
    - Validate each group with the characterization and 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.
+   - When every group has a confirmed Jira key, follow the optional stacked branch flow in `references/pr-task-fix.md` (Jira-Key Stacked Branches).
 10. Include file-integrity checks when tests, specs, benchmarks, fixtures, or snapshots are validation assets. If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
      `bun skills/massa-ai/scripts/lessons.ts --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
 11. Use `references/agent-orchestration.md` only for isolated implementation slices or independent verification

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

@@ -1,12 +1,20 @@
+---
+name: furps-refinement
+description: "Findings-only refinement of a PRD and/or ADR against the FURPS+ quality model before implementation, fanning out one sub-agent per dimension with a structured report."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### FURPS+ Refinement
 
-Use this workflow for findings-only refinement of a Product Requirements Document (PRD) and/or Architecture Decision Record (ADR) against the FURPS+ quality model, before implementation. It runs The Fool as an input-validation pre-pass, then fans out one sub-agent per FURPS+ dimension, and emits a structured refinement report with open questions, suggestions, insights, risks, and Definition-of-Ready coverage gaps.
+Findings-only refinement of a Product Requirements Document (PRD) and/or Architecture Decision Record (ADR) against the FURPS+ quality model, before implementation. It runs The Fool as an input-validation pre-pass, then fans out one sub-agent per FURPS+ dimension, and emits a structured refinement report with open questions, suggestions, insights, risks, and Definition-of-Ready coverage gaps.
 
-Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-Do not use this workflow to author a new PRD (use `to-prd` or `spec-driven` Specify), author an ADR (use `adr`), propose change (use `rfc`), audit implementation against requirements (use `requirements-audit`), or audit code/security/architecture. It refines the document itself; it does not edit code.
+Not for authoring a new PRD (use `to-prd` or `spec-driven` Specify), authoring an ADR (use `adr`), proposing change (use `rfc`), auditing implementation against requirements (use `requirements-audit`), or auditing code/security/architecture. It refines the document itself; it does not edit code.
 
-This workflow is findings-only. Do not edit the PRD/ADR unless the user separately asks.
+Findings-only: do not edit the PRD/ADR unless the user separately asks.
 
 1. Resolve/reuse `workflowSessionId`: `furps-refinement-[entity]`. Resolve `projectId` per the router. Budget `recall` (`limit <= 3`, `minImportance >= 0.7`, `types=["critical","decision","pattern"]`) for prior ADRs, accepted decisions, DoR, and refinement patterns.
 2. Load shared references: