@massa-ai/cursor-plugin 1.26.0 → 1.27.0

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

@@ -1,12 +1,20 @@
+---
+name: architecture-audit
+description: "Findings-only audit workflow for domain boundaries, bounded contexts, coupling, and architecture health against a concrete target; not for SOLID or code quality scans."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Architecture Audit
 
-Use this workflow for findings-only audit of domain boundaries, bounded contexts, DDD strategic design, coupling, dependency health, architecture review, deepening opportunities, seams, adapters, module depth, and architecture-focused refactor planning in a concrete target: modified files, explicit files/globs, commit ranges, branch comparisons, modules/packages, symbols/classes/functions, feature/runtime flows, explicitly requested whole-repo scope, or an implementation scope packet supplied by `workflows/implementation/implementation-audit.md`.
+Findings-only audit of domain boundaries, bounded contexts, DDD strategic design, coupling, dependency health, architecture review, deepening opportunities, seams, adapters, module depth, and architecture-focused refactor planning, scoped to a concrete target: modified files, explicit files/globs, commit ranges, branch comparisons, modules/packages, symbols/classes/functions, feature/runtime flows, explicitly requested whole-repo scope, or an implementation scope packet supplied by `workflows/implementation/implementation-audit.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.
 
-Do not use this workflow for plain SOLID, Clean Code, KISS, YAGNI, DRY, or code smell scans; use `workflows/code-quality/code-quality-audit.md` for those.
+Not for plain SOLID, Clean Code, KISS, YAGNI, DRY, or code smell scans — use `workflows/code-quality/code-quality-audit.md` for those.
 
-This workflow is findings-only. Do not edit code unless the user separately asks for fixes.
+Findings-only: do not edit code unless the user separately asks for fixes.
 
 1. Resolve/reuse `workflowSessionId`: `architecture-[entity]`
 2. Load shared references:
@@ -34,34 +42,9 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - Implementation parent scope: use only when `workflows/implementation/implementation-audit.md` invokes this workflow with a concrete implementation scope packet.
    - If the target focus is missing, vague, or too broad, ask for a concrete target from the supported scope types in `references/audit-scope.md`.
    - Build the shared scope packet from `references/audit-scope.md` and carry it into the report.
-5. For modified files scope:
-   - Include staged and unstaged tracked files from the working tree.
-   - Include untracked non-generated source, test, fixture, schema, config, and docs files only when they can affect architecture contracts or module boundaries.
-   - Exclude deleted files unless their deletion can break imports, exports, routing, migrations, config, tests, packaging, or architecture contracts.
-   - Exclude generated, dependency, build, log, cache, temporary, and secret paths per repo rules.
-   - Inspect diffs first, then only the surrounding code needed to understand architecture behavior.
-6. For commit range scope:
-   - If the user supplied explicit commits or a revision range, use that exact range.
-   - If the user asked for commits made by me, resolve author identity from `git config user.email`; if empty, use `git config user.name`.
-   - For branch-relative commit scopes, resolve the branch base from the upstream merge-base first, then fall back in order to `origin/main`, `origin/master`, `main`, and `master`.
-   - If the user asked for commits made by me, review branch-unique commits authored by the resolved identity.
-   - If no explicit range, required author identity, or branch base can be resolved, ask the user for the missing value before proceeding.
-   - Inspect changed files and diffs from those commits, then exported surfaces, references, dependency direction, tests, config, and ADRs only as needed.
-7. For codebase area scope:
-   - Require a concrete path, module, package, feature area, architecture question, or glob.
-   - If the target area is missing, ask for it before proceeding.
-   - Follow the shared retrieval order from `references/codebase-investigation.md` to find target modules, entry points, exported surfaces, references, semantic hotspots, tests, and adjacent config.
-   - If scope is broad, map only top-level modules first and ask or recommend a narrower second pass.
-8. For explicit files/globs, branch comparison, symbol/class/function, feature/flow, or explicitly requested whole-repo scope:
-   - Resolve the target with `references/audit-scope.md` and record the resolution method, base/head when relevant, resolved files, exclusions, and freshness timestamp.
-   - For symbol/class/function targets, verify definitions, references, dependency direction, exported surfaces, callers, tests, and ADRs only as needed for architecture claims.
-   - For feature/flow targets, map entry points through main transformations, contracts, and side effects before applying architecture lenses.
-   - If whole-repo scope is requested, map top-level modules first and report skipped depth checks rather than pretending exhaustive coverage.
-9. For implementation parent scope:
-   - Accept the exact scope packet from `implementation-audit`; do not broaden beyond resolved files, surrounding code, exported surfaces, references, config, tests, and ADRs needed to verify an architecture claim.
-   - Return compact findings to the parent implementation audit; do not write broad project memories unless explicitly assigned.
-10. Investigation pass:
-   - Call `get_architecture` with `id` (projectId) for the architecture-specific deep map: packages, entry points, routes, hotspots, communities, layers, and opt-in cycles (pass `aspects:["cycles"]` for Tarjan SCC over CALL edges). `get_architecture` is distinct from `project_map` (general overview: PageRank backbone + symbol counts) — use `get_architecture` for architecture-specific structure and `project_map` for the general overview. Both only count as evidence when the index is fresh for the current repository path and commit/worktree state; fall back to `search`/`get_references` and record reduced retrieval confidence when the index is stale or unavailable.
+5. Resolve the selected branch's mechanics (modified files, commit range, codebase area, explicit-files/branch/symbol/feature/whole-repo, or implementation parent scope) per `references/audit-scope.md` (Lens Audit Scope Resolution Procedure, Architecture row of Per-Lens Scope Deltas).
+6. Investigation pass:
+   - Call `get_architecture` with `id` (projectId) for the architecture-specific deep map: packages, entry points, routes, hotspots, communities, layers, and opt-in cycles (pass `aspects:["cycles"]` for Tarjan SCC over CALL edges). `get_architecture` differs from `project_map` (general overview: PageRank backbone + symbol counts) — use `get_architecture` for architecture-specific structure, `project_map` for the general overview. Both count as evidence only when the index is fresh for the current repository path and commit/worktree state; otherwise fall back to `search`/`get_references` and record reduced retrieval confidence.
    - Call `impact_analysis` with `project`, `projectPath`, and `scope` (unstaged/staged/committed/all) to assess the centrality-ranked blast radius of a change set. An empty diff returns an empty impact set (not an error).
    - Apply the smallest relevant lens set from `references/architecture-lenses.md` and load detail references only when their evidence is needed:
      - Domain lens: subdomains, bounded contexts, ubiquitous language, cohesion score, colliding concepts, cross-domain ownership, and integration pattern fit.
@@ -70,7 +53,7 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - Use `search_definitions` and `get_references` to verify exported surfaces and dependency direction where needed.
    - Capture positive architecture patterns when they materially disprove a concern, such as versioned contracts, anti-corruption layers, cohesive local coupling, or a deep interface that concentrates tests.
    - For each candidate finding, record the concrete claim, source evidence, lens-specific evidence, impacted boundary or module, provisional severity, tradeoff, simplest sufficient direction, and what would disprove it.
-11. False-positive pass:
+7. False-positive pass:
    - Try to disprove every candidate before reporting it.
    - Check ADRs, accepted exceptions, current domain docs, dependency direction, call paths, tests, package boundaries, framework constraints, git history when cheap, and prior rejected refactors.
    - Treat recalled memories and standalone skill heuristics as leads, not proof.
@@ -78,8 +61,8 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - Do not report strong coupling as a defect when strength is local, stable, or cohesive and no change friction is shown.
    - Do not recommend ports/adapters, service extraction, VSA migration, or new seams unless evidence shows real variation, volatility, external dependency pressure, or boundary friction.
    - Drop candidates disproven by evidence, downgrade candidates with partial mitigation, and mark judgment-heavy conclusions as `suspect`.
-   - When you reject a refactor candidate, record its load-bearing reason in ruled-out candidates; if it is likely to be re-proposed, offer an ADR via `workflows/adr.md` so the rejection is not re-litigated next audit.
-12. Use agent orchestration only when it improves signal. Dispatch per `references/agent-orchestration.md`:
+   - When you reject a refactor candidate, record its load-bearing reason in ruled-out candidates; if likely to be re-proposed, offer an ADR via `workflows/adr.md` so the rejection is not re-litigated next audit.
+8. Use agent orchestration only when it improves signal. Dispatch per `references/agent-orchestration.md`:
 
 > **Dispatch: `massa-ai-architecture-specialist`** (role: `architecture-specialist`) — charter `skills/agents/architecture-specialist/SKILL.md`
 > - trigger: large scope, explicit parallel/subagent request, PR subagent invocation, isolated audit slice, or independent verification of high-impact finding
@@ -102,26 +85,26 @@ This workflow is findings-only. Do not edit code unless the user separately asks
 > - firewall: raw logs/snapshots summarized
 > - memory: suggest-only; main agent persists reusable verification recipes
 > - persona: optional — the active route's cataloged id only, never the persona prompt, passed as advisory framing only — it never overrides the agent's charter Restrictions, scope, or permissions; omit when no persona is routed
-13. Severity rules (apply the countable threshold first, then the qualitative clause):
+9. Severity rules (apply the countable threshold first, then the qualitative clause):
    - `critical`: architecture issue likely causes data loss, auth/privacy break, production outage, irreversible corruption, OR affects >10 files; otherwise use the qualitative clause below.
    - `high`: strong coupling with high volatility, boundary violation, dependency inversion break, or shallow module design likely to cause major change friction or regression.
    - `medium`: meaningful but recoverable coupling, unclear boundary, missing seam, duplicated architecture rule, or module-depth issue with localized impact (<=10 affected files, recoverable).
    - `low`: architecture hardening opportunity, low-impact naming/layering issue, incomplete evidence, or weakly supported concern.
-14. Final report:
+10. Final report:
    - Findings first, ordered by severity.
    - Each finding must use `ARCH-<N>` and include the canonical fields from `references/audit-report-io.md`: lens, boundary/module, tradeoff, dependency direction when relevant, severity, confidence, file/module, concrete evidence, impact, simplest sufficient fix, and verification suggestion.
    - Mark uncertain or judgment-heavy conclusions as `suspect`.
    - Do not relitigate ADR-backed decisions unless current evidence shows real friction worth reopening.
    - Prefer merge, inline, move, or clarify-seam recommendations before adding new abstractions.
-   - Include lens-specific evidence in existing fields: domain findings should name language/cohesion/integration evidence; coupling findings should name strength/distance/volatility and dependency direction; deepening findings should name interface complexity, deletion-test result, dependency category, and test-surface impact.
+   - Include lens-specific evidence in existing fields: domain findings name language/cohesion/integration evidence; coupling findings name strength/distance/volatility and dependency direction; deepening findings name interface complexity, deletion-test result, dependency category, and test-surface impact.
    - If no architecture findings are found, say that clearly and list scope checked plus skipped checks.
    - Include ruled-out candidates when they were plausible enough to matter.
    - Include scope checked, deterministic evidence or skipped-check notes, memory outcome, and residual risk.
    - Include the Verification/Test Fidelity Checklist from `references/audit-report-io.md`; tie every `ARCH-*` 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.
    - For direct top-level invocation, use the Plan Mode save rule and canonical report contract from `references/audit-report-io.md` for `audits/architecture/<YYYY-MM-DD architecture-audit>.md`.
    - For implementation audit child invocation, return compact findings to the parent unless the parent explicitly requests saved audit artifacts.
-15. Persist only durable knowledge:
+11. Persist only durable knowledge:
    - Persist accepted architecture constraints, repeated coupling patterns, accepted exceptions, rejected refactors, or reusable verification recipes.
    - Do not persist every one-off finding.
    - Use required tags: `project:<projectId>`, `session:<workflowSessionId>`, `workflow:architecture-audit`, `entity:<entity>`, and one `memory:<tier>` tag.
-16. Complete the Evidence Gate from `references/evidence-gate.md`.
+12. Complete the Evidence Gate from `references/evidence-gate.md`.

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

@@ -1,12 +1,20 @@
+---
+name: architecture-fix
+description: "Executes fixes from a saved architecture audit report; not for findings-only review or broad new design work with missing requirements."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Architecture Fix
 
-Use this workflow only to execute fixes from an architecture audit markdown report.
+Execute fixes from an architecture 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 use this workflow for findings-only architecture review; route that to `workflows/architecture/architecture-audit.md`. Do not use it for broad new design work with missing requirements; route that to `workflows/spec-driven.md`.
+Not for findings-only architecture review — route to `workflows/architecture/architecture-audit.md`. Not for broad new design work with missing requirements — route to `workflows/spec-driven.md`.
 
 1. Resolve/reuse `workflowSessionId`: `architecture-fix-[entity]`
 2. Load shared references:
@@ -27,7 +35,7 @@ Do not use this workflow for findings-only architecture review; route that to `w
    - If the user asks for "latest" or gives no path, require a concrete target focus first; do not run the latest architecture report against an unspecified target.
    - Select the latest `audits/architecture/<YYYY-MM-DD architecture-audit>.md` only after target focus is known, using `references/audit-report-io.md`.
    - Stop if no report exists; do not infer findings from conversation history.
-   - Validate the report with `references/audit-report-io.md`: workflow, `ProjectId`, `Target`, `Target Focus`, scope, git base/head, required fields, `ARCH-` IDs, resolved files or material scope evidence, and current file/module evidence. Stop on invalid, stale, target-drifted, or ambiguous reports before editing.
+   - Validate the report deterministically: `bun skills/massa-ai/scripts/validate_audit_report.ts <path> --family architecture` (`references/audit-report-io.md`, Deterministic Validation); non-zero exit blocks editing. Also confirm resolved files or material scope evidence and current file/module evidence; stop on stale, target-drifted, or ambiguous reports.
 5. Extract actionable architecture findings:
    - Keep findings with concrete `Lens`, `Boundary/Module`, `Tradeoff`, `Location`, `Evidence`, `Impact`, `Simplest Fix Direction`, and `Verification Suggestion`.
    - Require lens-specific closure evidence: domain findings need language/ownership or integration evidence; coupling findings need strength/distance/volatility or dependency-direction evidence; deepening findings need deletion-test, seam, dependency-category, or test-surface evidence.
@@ -47,7 +55,7 @@ Do not use this workflow for findings-only architecture review; route that to `w
    - Coupling: reduce strength before distance; replace internal model sharing with explicit contracts, remove cross-boundary knowledge of internals, invert dependencies at stable seams, keep cohesive local coupling close, and avoid cycles.
    - Deepening: delete shallow pass-through modules, merge split concepts when locality improves, deepen useful interfaces by hiding invariants and ordering, test through the interface, and clarify seams only where variation, dependency direction, external I/O, or test substitution justifies it.
    - When a deepening candidate has two or more viable interface shapes, load the Interface Design Method from `references/architecture-deepening-lens.md` (Design It Twice) and pick by leverage and locality before editing.
-   - When you decide not to apply a reported refactor, record the load-bearing reason; if it is likely to recur, offer an ADR via `workflows/adr.md` so the rejection is not re-litigated.
+   - When you decide not to apply a reported refactor, record the load-bearing reason; if likely to recur, offer an ADR via `workflows/adr.md` so the rejection is not re-litigated.
    - Prefer move, merge, inline, or clarify existing seams before adding new abstractions.
    - Use ports/adapters or anti-corruption layers only when the report evidence shows real volatility, boundary pressure, external dependency pressure, model leakage, or at least two real adapters such as production plus test.
    - Do not turn a local code-quality concern into an architecture migration; route broad new design, VSA migration, new service boundaries, or unclear ownership to `workflows/spec-driven.md`.

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

@@ -1,12 +1,20 @@
+---
+name: bugs-audit
+description: "Findings-only bug discovery workflow for a concrete target; route known broken behavior to debug and code-quality concerns to code-quality-audit."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Bugs Audit
 
-Use this workflow for findings-only bug discovery in a concrete target: modified files, explicit files/globs, commit ranges, branch comparisons, modules/packages, symbols/classes/functions, feature/runtime flows, explicitly requested whole-repo scope, or an implementation scope packet supplied by `workflows/implementation/implementation-audit.md`.
+Findings-only bug discovery scoped to a concrete target: modified files, explicit files/globs, commit ranges, branch comparisons, modules/packages, symbols/classes/functions, feature/runtime flows, explicitly requested whole-repo scope, or an implementation scope packet supplied by `workflows/implementation/implementation-audit.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.
 
-Do not use this workflow to fix a known broken behavior; route that to `workflows/debug.md`. Do not use it for SOLID, Clean Code, KISS, YAGNI, DRY, maintainability, or overengineering analysis; route that to `workflows/code-quality/code-quality-audit.md`. For a multi-lens implementation review, route to `workflows/implementation/implementation-audit.md`. When invoked by implementation audit, this workflow is the Correctness lens only.
+Not to fix a known broken behavior — route to `workflows/debug.md`. Not for SOLID, Clean Code, KISS, YAGNI, DRY, maintainability, or overengineering analysis — route to `workflows/code-quality/code-quality-audit.md`. For a multi-lens implementation review, route to `workflows/implementation/implementation-audit.md`. When invoked by implementation audit, this workflow is the Correctness lens only.
 
-This workflow is findings-only. Do not edit code unless the user separately asks for fixes.
+Findings-only: do not edit code unless the user separately asks for fixes.
 
 1. Resolve/reuse `workflowSessionId`: `bugs-audit-[entity]`
 2. Load shared references:
@@ -30,32 +38,8 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - Implementation parent scope: use only when `workflows/implementation/implementation-audit.md` invokes this workflow with a concrete implementation scope packet.
    - If the target focus is missing, vague, or too broad, ask for a concrete target from the supported scope types in `references/audit-scope.md`.
    - Build or accept the shared scope packet from `references/audit-scope.md` and carry it into the report.
-5. For modified files scope:
-   - Include staged and unstaged tracked files from the working tree.
-   - Include untracked non-generated source, test, fixture, schema, config, and docs files only when they can affect runtime or validation behavior.
-   - Exclude deleted files unless their deletion can break imports, exports, routing, migrations, config, tests, or packaging.
-   - Exclude generated, dependency, build, log, cache, temporary, and secret paths per repo rules.
-   - Inspect diffs first, then only the surrounding code needed to understand behavior.
-6. For commit range scope:
-   - If the user supplied explicit commits or a revision range, use that exact range.
-   - If the user asked for commits made by me, resolve author identity from `git config user.email`; if empty, use `git config user.name`.
-   - For branch-relative commit scopes, resolve the branch base from the upstream merge-base first, then fall back in order to `origin/main`, `origin/master`, `main`, and `master`.
-   - If the user asked for commits made by me, review branch-unique commits authored by the resolved identity.
-   - If no explicit range, required author identity, or branch base can be resolved, ask the user for the missing value before proceeding.
-   - Inspect changed files and diffs from those commits, then surrounding code, callers, tests, and config only as needed.
-7. For codebase area scope:
-   - Require a concrete path, module, package, feature area, or glob.
-   - If the target area is missing, ask for it before proceeding.
-   - Follow the shared retrieval order from `references/codebase-investigation.md` to find entry points, public API, tests, and adjacent config.
-8. For explicit files/globs, branch comparison, symbol/class/function, feature/flow, or explicitly requested whole-repo scope:
-   - Resolve the target with `references/audit-scope.md` and record the resolution method, base/head when relevant, resolved files, exclusions, and freshness timestamp.
-   - For symbol/class/function targets, inspect definitions, callers, callees, tests, contracts, and config only as needed to verify likely bugs.
-   - For feature/flow targets, trace input -> transformation -> output through the named flow.
-   - If whole-repo scope is requested, map high-risk entry points first and report skipped depth checks rather than implying exhaustive review.
-9. For implementation parent scope:
-   - Accept the exact scope packet from `implementation-audit`; do not broaden beyond resolved files, surrounding code, callers, callees, tests, config, migrations, schemas, and public contracts needed to verify a correctness claim.
-   - Return compact Correctness findings to the parent implementation audit; do not write broad project memories unless explicitly assigned.
-10. Investigation pass. Dispatch `audit-specialist` per `references/agent-orchestration.md` when the scope justifies an isolated read-only subagent:
+5. Resolve the selected branch's mechanics (modified files, commit range, codebase area, explicit-files/branch/symbol/feature/whole-repo, or implementation parent scope) per `references/audit-scope.md` (Lens Audit Scope Resolution Procedure, Bugs row of Per-Lens Scope Deltas).
+6. Investigation pass. Dispatch `audit-specialist` per `references/agent-orchestration.md` when the scope justifies an isolated read-only subagent:
 
 > **Dispatch: `massa-ai-audit-specialist`** (role: `audit-specialist`) — charter `skills/agents/audit-specialist/SKILL.md`
 > - trigger: large scope, explicit parallel/subagent request, PR subagent invocation, or independent verification of high-impact finding
@@ -72,17 +56,17 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - Check diffs, surrounding code, callers and callees, tests, config, migrations, schemas, and recalled project patterns.
    - Prioritize correctness bugs, crashes, data loss, security regressions, broken contracts, async or race issues, validation or authorization gaps, persistence and migration bugs, environment/config issues, and behavior that contradicts tests or public API contracts.
    - For each candidate finding, record the concrete claim, bug class, source evidence, impacted flow, trigger or repro path, root-cause hypothesis, regression risk, provisional severity, and what would disprove it.
-11. False-positive pass:
+7. False-positive pass:
    - Try to disprove every candidate before reporting it.
    - Check guards, type checks, tests, feature flags, framework contracts, call paths, existing invariants, ADRs, and accepted exceptions.
    - Use official docs or web research only when current external API or framework behavior matters.
    - Drop candidates disproven by evidence, downgrade candidates with partial mitigation, and mark low-confidence findings explicitly.
-12. Severity rules (apply the countable threshold first, then the qualitative clause):
+8. Severity rules (apply the countable threshold first, then the qualitative clause):
    - `critical`: likely data loss, security bypass, production outage, irreversible corruption, auth/privacy break, OR affects >10 files; otherwise use the qualitative clause below.
    - `high`: likely crash, major regression, broken core flow, incorrect persistence, missing required validation, or severe operational risk.
    - `medium`: real edge-flow bug, recoverable incorrect behavior (<=10 affected files), flaky async/state risk, incomplete error handling, or meaningful test gap around changed logic.
    - `low`: minor bug, low-impact incorrect behavior, defensive hardening opportunity, incomplete evidence, or weakly supported concern.
-13. Final report:
+9. Final report:
    - Findings first, ordered by severity: `critical`, `high`, `medium`, `low`.
    - Each finding must use `BUG-<N>` and include the canonical fields from `references/audit-report-io.md`: severity, confidence, file/line, evidence, bug class, impacted flow, trigger or repro path, root-cause hypothesis, regression risk, impact, simplest fix direction, and verification suggestion.
    - If no bugs are found, say that clearly and list scope checked plus skipped checks.
@@ -91,11 +75,11 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - Include the Verification/Test Fidelity Checklist from `references/audit-report-io.md`; tie every `BUG-*` 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.
    - For direct top-level invocation, use the Plan Mode save rule and canonical report contract from `references/audit-report-io.md` for `audits/bugs/<YYYY-MM-DD bugs-audit>.md`.
    - For implementation audit child invocation, return compact findings to the parent unless the parent explicitly requests saved audit artifacts.
-14. Persist only durable knowledge:
+10. Persist only durable knowledge:
    - Do not persist one-off findings.
    - Persist repeated bug patterns, fragile project-specific flows, accepted exceptions, or reusable verification recipes after scoring with the Importance Calibration System.
    - Use required tags: `project:<projectId>`, `session:<workflowSessionId>`, `workflow:bugs-audit`, `entity:<entity>`, and one `memory:<tier>` tag.
-15. Complete the Evidence Gate from `references/evidence-gate.md`.
+11. Complete the Evidence Gate from `references/evidence-gate.md`.
 
 ## Examples
 

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

@@ -1,12 +1,20 @@
+---
+name: bugs-fix
+description: "Executes fixes from a saved bugs audit report; not for findings-only discovery, single known issues without a report, or broad product changes."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Bugs Fix
 
-Use this workflow only to execute fixes from a bugs audit markdown report.
+Execute fixes from a bugs 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 use this workflow for findings-only bug discovery; route that to `workflows/bugs/bugs-audit.md`. Do not use it for one known broken behavior without an audit report; route that to `workflows/debug.md`. Do not use it for broad product/design changes; route those to `workflows/spec-driven.md`.
+Not for findings-only bug discovery — route to `workflows/bugs/bugs-audit.md`. Not for one known broken behavior without an audit report — route to `workflows/debug.md`. Not for broad product/design changes — route to `workflows/spec-driven.md`.
 
 1. Resolve/reuse `workflowSessionId`: `bugs-fix-[entity]`
 2. Load shared references:
@@ -23,7 +31,7 @@ Do not use this workflow for findings-only bug discovery; route that to `workflo
    - If the user asks for "latest" or gives no path, require a concrete target focus first; do not run the latest bugs report against an unspecified target.
    - Select the latest `audits/bugs/<YYYY-MM-DD bugs-audit>.md` only after target focus is known, using `references/audit-report-io.md`.
    - Stop if no report exists; do not infer findings from conversation history.
-   - Validate the report with `references/audit-report-io.md`: workflow, `ProjectId`, `Target`, `Target Focus`, scope, git base/head, required fields, `BUG-` IDs, resolved files or material scope evidence, and current file/line evidence. Stop on invalid, stale, target-drifted, or ambiguous reports before editing.
+   - Validate the report deterministically: `bun skills/massa-ai/scripts/validate_audit_report.ts <path> --family bugs` (`references/audit-report-io.md`, Deterministic Validation); non-zero exit blocks editing. Also confirm resolved files or material scope evidence and current file/line evidence; stop on stale, target-drifted, or ambiguous reports.
 5. Extract actionable bug findings:
    - Keep findings with concrete `Bug Class`, `Impacted Flow`, `Trigger or Repro Path`, `Root Cause Hypothesis`, `Regression Risk`, `Location`, `Evidence`, `Simplest Fix Direction`, and `Verification Suggestion`.
    - Ignore ruled-out candidates, no-finding sections, and low-confidence hardening ideas unless the user explicitly asks to include them.

package/skills/massa-ai/workflows/code-quality/code-quality-audit.md

@@ -1,12 +1,20 @@
+---
+name: code-quality-audit
+description: "Findings-only audit workflow for SOLID, Clean Code, KISS, YAGNI, DRY, maintainability, and code-smell issues in a concrete target; not for architecture concerns."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Code Quality Audit
 
-Use this workflow for findings-only audit of SOLID, Clean Code, KISS, YAGNI, DRY, maintainability, overengineering, code smell, or violations-check issues in a concrete target: modified files, explicit files/globs, commit ranges, branch comparisons, modules/packages, symbols/classes/functions, feature/runtime flows, explicitly requested whole-repo scope, or an implementation scope packet supplied by `workflows/implementation/implementation-audit.md`.
+Findings-only audit of SOLID, Clean Code, KISS, YAGNI, DRY, maintainability, overengineering, code smell, or violations-check issues, scoped to a concrete target: modified files, explicit files/globs, commit ranges, branch comparisons, modules/packages, symbols/classes/functions, feature/runtime flows, explicitly requested whole-repo scope, or an implementation scope packet supplied by `workflows/implementation/implementation-audit.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.
 
-Do not use this workflow for domain boundaries, bounded contexts, coupling analysis, module depth, seams, adapters, or architecture refactor opportunities. Route those to `workflows/architecture/architecture-audit.md`. Keep local pass-through wrappers, unused speculation, vague names, duplicate literals, and simple overengineering here when the finding does not require architecture-lens evidence.
+Not for domain boundaries, bounded contexts, coupling analysis, module depth, seams, adapters, or architecture refactor opportunities — route those to `workflows/architecture/architecture-audit.md`. Keep local pass-through wrappers, unused speculation, vague names, duplicate literals, and simple overengineering here when the finding does not require architecture-lens evidence.
 
-This workflow is findings-only. Do not edit code unless the user separately asks for fixes.
+Findings-only: do not edit code unless the user separately asks for fixes.
 
 1. Resolve/reuse `workflowSessionId`: `quality-[entity]`
 2. Load shared references:
@@ -32,32 +40,8 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - Implementation parent scope: use only when `workflows/implementation/implementation-audit.md` invokes this workflow with a concrete implementation scope packet.
    - If the target focus is missing, vague, or too broad, ask for a concrete target from the supported scope types in `references/audit-scope.md`.
    - Build the shared scope packet from `references/audit-scope.md` and carry it into the report.
-5. For modified files scope:
-   - Include staged and unstaged tracked files from the working tree.
-   - Include untracked non-generated source, test, fixture, schema, config, and docs files only when they can affect maintainability, validation behavior, or public contracts.
-   - Exclude deleted files unless their deletion can break imports, exports, routing, migrations, config, tests, or packaging.
-   - Exclude generated, dependency, build, log, cache, temporary, and secret paths per repo rules.
-   - Inspect diffs first, then only the surrounding code needed to understand quality claims.
-6. For commit range scope:
-   - If the user supplied explicit commits or a revision range, use that exact range.
-   - If the user asked for commits made by me, resolve author identity from `git config user.email`; if empty, use `git config user.name`.
-   - For branch-relative commit scopes, resolve the branch base from the upstream merge-base first, then fall back in order to `origin/main`, `origin/master`, `main`, and `master`.
-   - If the user asked for commits made by me, review branch-unique commits authored by the resolved identity.
-   - If no explicit range, required author identity, or branch base can be resolved, ask the user for the missing value before proceeding.
-   - Inspect changed files and diffs from those commits, then surrounding code, callers, tests, config, and public API only as needed.
-7. For codebase area scope:
-   - Require a concrete path, module, package, feature area, or glob.
-   - If the target area is missing, ask for it before proceeding.
-   - Follow the shared retrieval order from `references/codebase-investigation.md` to find target modules, semantic hotspots, public API, tests, and adjacent config.
-8. For explicit files/globs, branch comparison, symbol/class/function, feature/flow, or explicitly requested whole-repo scope:
-   - Resolve the target with `references/audit-scope.md` and record the resolution method, base/head when relevant, resolved files, exclusions, and freshness timestamp.
-   - For symbol/class/function targets, inspect definitions, references, call sites, tests, and current usage evidence before reporting quality claims.
-   - For feature/flow targets, map the main code path only as far as needed to identify local maintainability or overengineering issues.
-   - If whole-repo scope is requested, report sampled/top-level coverage and skipped deep checks instead of implying exhaustive review.
-9. For implementation parent scope:
-   - Accept the exact scope packet from `implementation-audit`; do not broaden beyond resolved files, surrounding code, public API, tests, config, and project patterns needed to verify a quality claim.
-   - Return compact findings to the parent implementation audit; do not write broad project memories unless explicitly assigned.
-10. Input rules:
+5. Resolve the selected branch's mechanics (modified files, commit range, codebase area, explicit-files/branch/symbol/feature/whole-repo, or implementation parent scope) per `references/audit-scope.md` (Lens Audit Scope Resolution Procedure, Code Quality row of Per-Lens Scope Deltas).
+6. Input rules:
    - SOLID inputs: non-test source files only.
    - Clean Code inputs: test and non-test source files.
    - KISS/YAGNI/DRY inputs: test and non-test source files, plus docs/config only when they define behavior or public contracts.
@@ -65,7 +49,7 @@ This workflow is findings-only. Do not edit code unless the user separately asks
      - Keep local quality issues in this workflow when the fix is delete, inline, rename, extract a constant, collapse a trivial wrapper, simplify control flow, or consolidate duplicated local rules.
      - Route to `workflows/architecture/architecture-audit.md` when the claim needs bounded-context language, dependency direction, strength/distance/volatility, module depth, seam placement, adapter reality, or cross-domain ownership evidence.
      - If unsure, report as `suspect` only when concrete local maintainability evidence exists; otherwise recommend an architecture-audit follow-up instead of forcing a CQ finding.
-11. Decide whether to use agent orchestration:
+7. Decide whether to use agent orchestration:
    - Load it only for large PRs, codebase-wide audits, explicit parallel/subagent requests, or independent verification of judgment-heavy findings.
    - Keep the audit local for small scopes, unresolved user intent, tightly coupled code without clear owners, or platforms that do not permit subagents.
    - The main agent still owns scope, memory recall, static leads, synthesis, final report, persistence, and Evidence Gate.
@@ -84,7 +68,7 @@ This workflow is findings-only. Do not edit code unless the user separately asks
 
     - Do not delegate every check by default; avoid duplicate source reading when one main-agent pass is cheaper.
     - Subagents may suggest memory content, but the main agent decides what durable knowledge to persist.
-12. Gather deterministic leads with static scans where useful:
+8. Gather deterministic leads with static scans where useful:
    - Type-tag branches: `switch`, `case`, `if/else if`, discriminant fields such as `type`, `kind`, `variant`, `mode`.
    - Concrete construction: `new [A-Z]` inside class or service bodies.
    - Half-finished surfaces: `TODO`, `implement later`, exported stubs, `return null`, empty method bodies.
@@ -97,7 +81,7 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - Complexity without payoff: deep nesting, miniature state machines, or polymorphism where a direct branch or data map would preserve clarity.
    - AI-slop surfaces: generic abstractions with no domain vocabulary, fabricated-looking type names, unnecessary factories/builders, wrappers around one call, comments that narrate obvious code, and broad configurability not supported by current requirements.
    - Android/KMP Compose recomposition leads: `@Composable`, `remember`, `rememberSaveable`, `derivedStateOf`, `LaunchedEffect`, `DisposableEffect`, `SideEffect`, `produceState`, `snapshotFlow`, `mutableStateOf`, `SnapshotStateList`, stability annotations/config, Compose compiler reports, Compose UI tests, and screenshot tests.
-13. Investigation pass:
+9. Investigation pass:
    - Use summary/enriched search, symbol tools, and targeted file reads to inspect target modules, semantic hotspots, public classes, interfaces, functions, and exported API surface.
    - Apply SOLID checks to non-test source only:
      - Single Responsibility: flag classes/modules with distinct concern groups, such as validation plus persistence or formatting plus dispatch.
@@ -113,9 +97,9 @@ This workflow is findings-only. Do not edit code unless the user separately asks
      - Half-finished surfaces: flag exported TODOs, stubs, placeholder returns, and "implement later" code.
      - Long parameter lists: flag more than 3-4 positional parameters; suggest an options object.
    - Apply KISS/YAGNI/DRY checks:
-     - KISS: flag abstractions, layers, indirection, or control flow that increase cognitive load without clearly improving readability, correctness, or constraint handling. Call out premature generalization, deep call chains, excessive configuration, and clever patterns that obscure intent. Prefer straightforward, explicit code that a new reader can follow end-to-end. Simplify by inlining trivial abstractions, collapsing unnecessary layers, and choosing boring solutions unless complexity is justified (e.g., real variability, hard constraints, or measured bottlenecks).
-     - YAGNI: flag speculative features, extension points, and generic infrastructure that have no concrete caller, requirement, or near-term use. Call out “just in case” hooks, over-parameterization, unused toggles, and frameworks introduced ahead of need. Prefer implementing only what current use cases demand, with code structured so it can evolve when real requirements appear. Defer generalization until duplication or constraints make it necessary, and remove dead or unused paths aggressively.
-     - DRY: flag duplicated logic, data transformations, or domain rules that appear in multiple places without a strong reason (e.g., performance isolation or explicit decoupling). Highlight copy-paste patterns, parallel conditionals, and repeated constants that increase maintenance cost or risk of inconsistency. Recommend consolidation into a single source of truth when it improves clarity and reduces bugs, but avoid over-abstraction that harms readability or introduces indirection for trivial reuse.
+     - KISS: flag abstractions, layers, indirection, or control flow that raise cognitive load without clearly improving readability, correctness, or constraint handling. Call out premature generalization, deep call chains, excessive configuration, and clever patterns that obscure intent. Prefer straightforward, explicit code a new reader can follow end-to-end: inline trivial abstractions, collapse unnecessary layers, choose boring solutions unless complexity is justified (real variability, hard constraints, or measured bottlenecks).
+     - YAGNI: flag speculative features, extension points, and generic infrastructure with no concrete caller, requirement, or near-term use. Call out "just in case" hooks, over-parameterization, unused toggles, and frameworks introduced ahead of need. Prefer implementing only what current use cases demand, structured to evolve when real requirements appear. Defer generalization until duplication or constraints force it, and remove dead or unused paths aggressively.
+     - DRY: flag duplicated logic, data transformations, or domain rules repeated without a strong reason (e.g., performance isolation or explicit decoupling). Highlight copy-paste patterns, parallel conditionals, and repeated constants that raise maintenance cost or inconsistency risk. Recommend consolidation into a single source of truth when it improves clarity and reduces bugs, but avoid over-abstraction that harms readability or adds indirection for trivial reuse.
      - Prefer delete, inline, or merge recommendations over replacement abstractions when simpler code preserves behavior.
      - Require usage evidence before calling a surface unnecessary; if evidence is incomplete, mark the item `suspect`.
      - Do not recommend ports, adapters, bounded contexts, new service/module boundaries, or VSA migration from this workflow; hand those to architecture-audit.
@@ -126,16 +110,16 @@ This workflow is findings-only. Do not edit code unless the user separately asks
      - Mark semantic recomposition claims as `suspect` unless supported by Compose compiler stability/skippability reports, existing Compose UI tests, screenshot tests, benchmark/runtime traces, or a clear deterministic static source pattern.
      - Verification suggestions should name the cheapest available sensor: Compose compiler metrics/reports, focused Compose UI test, screenshot/golden test, instrumentation/emulator check, or static lint/build command.
    - For each candidate finding, record the concrete claim, source evidence, impacted maintainability or change-risk flow, provisional severity, and what would disprove it.
-14. False-positive pass:
+10. False-positive pass:
    - Try to disprove every candidate before reporting it.
    - Check framework-required signatures, public SDK or plugin surfaces, ADR-backed extension points, test fixtures/builders, harmless local literals, intentionally tiny adapters, usage evidence, and accepted exceptions.
    - Drop candidates disproven by evidence, downgrade candidates with partial mitigation, and mark judgment-heavy items as `suspect`.
-15. Severity rules (apply the countable threshold first, then the qualitative clause):
+11. Severity rules (apply the countable threshold first, then the qualitative clause):
    - `critical`: quality issue likely causes production outage, data loss, auth/privacy break, OR affects >10 files; otherwise use the qualitative clause below.
    - `high`: strong SOLID/Clean Code/KISS/YAGNI/DRY violation with high change volatility likely to cause major regression, repeated bugs, or high-cost change friction.
    - `medium`: real maintainability issue, speculative surface, duplicated rule, weak naming/comment pattern, or avoidable complexity with localized impact (<=10 affected files).
    - `low`: minor hardening opportunity, low-impact cleanup, incomplete evidence, or weakly supported concern.
-16. Final report:
+12. Final report:
    - Findings first, ordered by severity.
    - Each finding must use `CQ-<N>` and include the canonical fields from `references/audit-report-io.md`: rule, current shape, simplest safe transformation, severity, confidence, file/line, concrete evidence, impact, simplest sufficient fix, and verification suggestion.
    - For Android/KMP Compose recomposition findings, include whether the risk is excessive recomposition or missing/stale recomposition, the affected composable or state boundary, UX impact, confidence, and the deterministic sensor that would prove or disprove the claim.
@@ -148,8 +132,8 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - Include the Verification/Test Fidelity Checklist from `references/audit-report-io.md`; tie every `CQ-*` 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.
    - For direct top-level invocation, use the Plan Mode save rule and canonical report contract from `references/audit-report-io.md` for `audits/code-quality/<YYYY-MM-DD code-quality-audit>.md`.
    - For implementation audit child invocation, return compact findings to the parent unless the parent explicitly requests saved audit artifacts.
-17. Persist only durable knowledge:
+13. Persist only durable knowledge:
    - Do not persist one-off findings.
    - Persist repeated anti-patterns, project-specific quality rules, accepted exceptions, or repeated overengineering patterns via `remember` after scoring with the Importance Calibration System.
    - Use required tags: `project:<projectId>`, `session:<workflowSessionId>`, `workflow:code-quality-audit`, `entity:<entity>`, and one `memory:<tier>` tag.
-18. Complete the Evidence Gate from `references/evidence-gate.md`.
+14. Complete the Evidence Gate from `references/evidence-gate.md`.

package/skills/massa-ai/workflows/code-quality/code-quality-fix.md

@@ -1,12 +1,20 @@
+---
+name: code-quality-fix
+description: "Executes fixes from a saved code quality audit report; not for findings-only SOLID, Clean Code, KISS, YAGNI, DRY, or overengineering analysis."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Code Quality Fix
 
-Use this workflow only to execute fixes from a code quality audit markdown report.
+Execute fixes from a code quality 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 use this workflow for findings-only SOLID, Clean Code, KISS, YAGNI, DRY, maintainability, or overengineering analysis; route that to `workflows/code-quality/code-quality-audit.md`.
+Not for findings-only SOLID, Clean Code, KISS, YAGNI, DRY, maintainability, or overengineering analysis — route to `workflows/code-quality/code-quality-audit.md`.
 
 1. Resolve/reuse `workflowSessionId`: `code-quality-fix-[entity]`
 2. Load shared references:
@@ -24,7 +32,7 @@ Do not use this workflow for findings-only SOLID, Clean Code, KISS, YAGNI, DRY,
    - If the user asks for "latest" or gives no path, require a concrete target focus first; do not run the latest code quality report against an unspecified target.
    - Select the latest `audits/code-quality/<YYYY-MM-DD code-quality-audit>.md` only after target focus is known, using `references/audit-report-io.md`.
    - Stop if no report exists; do not infer findings from conversation history.
-   - Validate the report with `references/audit-report-io.md`: workflow, `ProjectId`, `Target`, `Target Focus`, scope, git base/head, required fields, `CQ-` IDs, resolved files or material scope evidence, and current file/line evidence. Stop on invalid, stale, target-drifted, or ambiguous reports before editing.
+   - Validate the report deterministically: `bun skills/massa-ai/scripts/validate_audit_report.ts <path> --family code-quality` (`references/audit-report-io.md`, Deterministic Validation); non-zero exit blocks editing. Also confirm resolved files or material scope evidence and current file/line evidence; stop on stale, target-drifted, or ambiguous reports.
 5. Extract actionable findings:
    - Keep findings with concrete `Rule`, `Current Shape`, `Simplest Safe Transformation`, `Location`, `Evidence`, `Impact`, `Simplest Fix Direction`, and `Verification Suggestion`.
    - Ignore ruled-out candidates, no-finding sections, and `suspect` items unless the user explicitly asks to address suspects.

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

@@ -1,10 +1,18 @@
+---
+name: commit
+description: "Use this workflow to draft a commit message, prepare, or commit current repository changes; not for Jira tickets, release notes, changelogs, or history rewriting."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Commit
 
-Use this workflow when the user wants to draft a commit message, prepare a commit, or commit current repository changes. This workflow adapts the local caveman-commit rules into a safe Git workflow for changed files.
+Use when the user wants to draft a commit message, prepare a commit, or commit current repository changes. Adapts the local caveman-commit rules into a safe Git workflow for changed files.
 
-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 for Jira ticket creation, release notes, changelogs, PR descriptions, or history rewriting. Route Jira issue work to `workflows/ticket.md`. Route broad release documentation to the relevant feature, RFC, or general workflow.
+Not for Jira ticket creation, release notes, changelogs, PR descriptions, or history rewriting. Route Jira issue work to `workflows/ticket.md`. Route broad release documentation to the relevant feature, RFC, or general workflow.
 
 ## Workflow
 
@@ -16,8 +24,8 @@ Do not use this workflow for Jira ticket creation, release notes, changelogs, PR
    - unstaged changed paths from `git diff --name-only`
    - status summary from `git status --short`
    - staged diff when anything is staged; otherwise the unstaged diff for allowed paths
-4. Extract the first Jira key from the branch with case-insensitive regex `(?<![A-Z0-9])([A-Z][A-Z0-9]{1,9}-[0-9]+)(?![A-Z0-9])`. Normalize the key to uppercase. If no key is found, proceed without a prefix and do not ask. When an explicit task key is supplied (from `workflows/ticket.md` for phased work, or by the user), it takes precedence over the branch-derived key.
-   - **Phased work — one commit per task, prefixed with the task's sub-task key.** When committing phased work sourced from `workflows/ticket.md`, each Task inside a Phase/Wave is exactly **one atomic commit** (never batched; the one-commit-per-task cadence is owned by the Implementation Delivery Protocol, Stage 2). That commit's subject is prefixed with the Task's Jira **sub-task** key as `[XXX-YYYY]`, for example `[SA-142] feat(auth): reject expired tokens`. The prefix format is the same `[<KEY>] ` rule below; the sub-task key simply replaces the generic branch key.
+4. Extract the first Jira key from the branch with case-insensitive regex `(?<![A-Z0-9])([A-Z][A-Z0-9]{1,9}-[0-9]+)(?![A-Z0-9])`. Normalize to uppercase. If no key is found, proceed without a prefix and do not ask. An explicit task key (from `workflows/ticket.md` for phased work, or from the user) takes precedence over the branch-derived key.
+   - **Phased work — one commit per task, prefixed with the task's sub-task key.** When committing phased work sourced from `workflows/ticket.md`, each Task inside a Phase/Wave is exactly **one atomic commit** (never batched; the one-commit-per-task cadence is owned by the Implementation Delivery Protocol, Stage 2). Prefix that commit's subject with the Task's Jira **sub-task** key as `[XXX-YYYY]`, e.g. `[SA-142] feat(auth): reject expired tokens` — same `[<KEY>] ` rule below, sub-task key replacing the generic branch key.
 5. Resolve commit scope:
    - If files are already staged, treat staged files as the user-selected commit scope and do not stage additional files.
    - If nothing is staged and the user explicitly asked to commit, stage only allowed changed files one path at a time with pathspec-safe commands.

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

@@ -1,10 +1,18 @@
+---
+name: debug
+description: "Use this workflow for evidence-backed root-cause diagnosis of broken behavior, failures, regressions, or crashes; route new capabilities to feature and broad redesign to spec-driven."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### 🔴 Debug
 
-Use this workflow when the user reports broken behavior, failures, regressions, crashes, unexpected output, flaky behavior, or any issue that needs evidence-backed root-cause diagnosis before a fix. Do not use it for new capabilities; route that to `workflows/feature.md`. Do not use it for broad redesign or unclear cross-boundary changes; route that to `workflows/spec-driven.md`.
+Use when the user reports broken behavior, failures, regressions, crashes, unexpected output, flaky behavior, or any issue needing evidence-backed root-cause diagnosis before a fix. Not for new capabilities — route to `workflows/feature.md`. Not for broad redesign or unclear cross-boundary changes — 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. Generate/reuse `workflowSessionId`: `debug-[entity]`
 2. Load shared references: