@massa-ai/cursor-plugin 1.6.0

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

@@ -0,0 +1,125 @@
+### 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`.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+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.
+
+This workflow is findings-only. Do not edit code unless the user separately asks for fixes.
+
+1. Resolve/reuse `workflowSessionId`: `architecture-[entity]`
+2. Load shared references:
+   - `references/codebase-investigation.md`
+   - `references/audit-scope.md`
+   - `references/architecture-lenses.md`
+   - `references/architecture-domain-lens.md` only when scope includes bounded contexts, subdomains, ubiquitous language, cohesion, or integration pattern claims
+   - `references/architecture-coupling-lens.md` only when scope includes dependencies, imports, service calls, shared schemas/models, persistence reach-through, co-change, or contract leakage
+   - `references/architecture-deepening-lens.md` only when scope includes module depth, seams, adapters, deletion tests, locality, testability, or AI-navigability
+   - `references/audit-report-io.md` before writing the final direct audit report
+   - `references/context-firewall.md` before inspecting large diffs, dependency graphs, generated reports, or broad search output
+   - `references/synapse-policy.md` when repeated massa-ai searches are expected
+   - `references/agent-orchestration.md` only for large scopes, explicit parallel/subagent requests, PR subagent invocation, isolated audit slices, or independent verification of high-impact findings
+3. `recall` -> load ADRs, architecture decisions, known boundaries, coupling patterns, accepted exceptions, project constraints, and prior rejected refactors for the target area.
+   - Apply the Memory Freshness Gate from `references/audit-scope.md`; recalled exceptions are leads, not proof.
+4. Establish the investigation scope before proceeding:
+   - Modified files scope: use when the user says modified files, changed files, current changes, uncommitted changes, staged changes, or unstaged changes.
+   - Explicit files/globs scope: use when the user names files, directories, or globs.
+   - Commit range scope: use when the user provides commits/ranges or asks for commits made by me, my branch commits, or architecture issues introduced by branch commits.
+   - Branch comparison scope: use when the user names base/head branches, refs, or a branch diff.
+   - Codebase area scope: use when the user names a path, module, package, bounded context, feature area, architecture question, or glob.
+   - Symbol/class/function scope: use when the user names exported surfaces, classes, functions, adapters, interfaces, or dependency edges.
+   - Feature/flow scope: use when the user names a runtime flow or cross-module feature.
+   - Whole-repo scope: use only when the user explicitly asks for a whole-repo architecture audit.
+   - 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.
+   - 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.
+     - Coupling lens: dependency graph, knowledge direction, integration strength, distance, volatility, balance table result, and contract health.
+     - Deepening lens: module/interface/seam/adapter vocabulary, shallow modules, deletion test, dependency category, locality, leverage, and interface-as-test-surface evidence.
+   - 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:
+   - 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.
+   - Do not report domain truth inferred only from code names as fact; mark it `suspect` or report the evidence gap.
+   - 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`:
+
+> **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
+> - scope: exact files/modules/boundaries in the audit target
+> - permissions: read-only
+> - inputs: shared scope packet; lens sub-mode (`domain` for bounded-context mapping, `coupling` for dependency-graph/strength/distance/volatility, `deepening` for module-depth opportunities); recalled ADRs and rejected refactors
+> - sensors: `search_definitions` / `get_references` for exported surfaces and dependency direction; source inspection against current files
+> - output: findings with lens-specific evidence, provisional severity, tradeoff, and what would disprove it
+> - firewall: raw dependency graphs, generated reports, and broad search output summarized, not returned raw
+> - memory: suggest-only; main agent persists accepted constraints/rejected refactors
+
+> **Dispatch: `massa-ai-verification-agent`** (role: `verification-agent`) — charter `skills/agents/verification-agent/SKILL.md`
+> - trigger: independent verification of a high-impact architecture finding
+> - scope: the specific finding's claimed evidence and affected boundary/module
+> - permissions: read-only
+> - inputs: the candidate finding, its source evidence, ADRs, accepted exceptions, and the verification suggestion
+> - sensors: deterministic command or artifact check that would falsify the finding
+> - output: confirmed/disproven verdict with evidence; skipped-check reason if the sensor cannot run
+> - firewall: raw logs/snapshots summarized
+> - memory: suggest-only; main agent persists reusable verification recipes
+13. 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:
+   - 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.
+   - 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:
+   - 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`.

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

@@ -0,0 +1,110 @@
+### Architecture Fix
+
+Use this workflow only to execute fixes from an architecture audit markdown report.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+Before the first repository mutation, load `references/implementation-delivery.md` for worktree isolation, atomic commits, PR creation, CI watch, and the merge gate, and `references/code-annotation.md` for doc blocks, rationale comments, and test coverage on every created or updated unit. If two consecutive fix attempts fail on the same symptom, stop editing and load `references/root-cause-scripts.md`.
+
+Do not 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`.
+
+1. Resolve/reuse `workflowSessionId`: `architecture-fix-[entity]`
+2. Load shared references:
+   - `references/audit-report-io.md` before any code change
+   - `references/architecture-lenses.md`
+   - `references/architecture-domain-lens.md` when executing domain or bounded-context findings
+   - `references/architecture-coupling-lens.md` when executing dependency, contract, or coupling findings
+   - `references/architecture-deepening-lens.md` when executing module-depth, seam, adapter, locality, or testability findings
+   - `references/lessons.md` to load confirmed project lessons
+   - `references/codebase-investigation.md` before changing unfamiliar modules
+   - `references/verification-ladder.md` before non-trivial edits
+   - `references/context-firewall.md` before inspecting large diffs, dependency graphs, generated reports, or broad search output
+   - `references/agent-orchestration.md` only for large/high-risk findings, disjoint implementation slices, or independent verification
+3. `recall` -> load ADRs, known boundaries, coupling patterns, accepted exceptions, rejected refactors, verification recipes, and project constraints for the report target.
+4. Select the architecture audit report with execution focus:
+   - Establish the report selector, target focus, and optional finding selector before selecting a report. Target focus can be a module, boundary, flow, files/globs, branch comparison, commit range, symbol/class/function, or explicit whole-repo target.
+   - If the user gives a path, read that exact markdown file.
+   - 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.
+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.
+   - Ignore ruled-out candidates and no-finding sections.
+   - Ignore `suspect` findings unless the user explicitly asks to address suspects or the report supplies a deterministic follow-up check that confirms them.
+   - If the user supplied finding IDs, extract only those IDs after validating they exist and match the current target focus.
+   - Rank by severity, dependency order, boundary blast radius, and ease of deterministic verification.
+6. Build an execution map before editing:
+   - Finding ID -> target modules, affected bounded context or seam, current dependency direction, desired dependency direction, behavior that must stay unchanged, validation assets, and rollback path.
+   - Split work when one report contains independent findings. Do not mix unrelated architecture moves in one edit loop.
+7. Size each finding with `references/verification-ladder.md`:
+   - Quick: local move/inline/rename/adapter clarification with small blast radius.
+   - Standard: multi-file behavior-preserving refactor, public API adjustment, package boundary change, or test impact; define characterization checks first.
+   - Spec-driven: migration, broad boundary redesign, new service boundary, unclear ownership, or user-visible behavior change; pause and route to `workflows/spec-driven.md` or ask for approval.
+8. Apply architecture fixing methods:
+   - Domain: align language and ownership, move misplaced concepts into the right bounded context, separate generic/supporting concerns from core domain logic, and preserve ubiquitous language in names.
+   - 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.
+   - 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`.
+9. Preserve behavior:
+   - Characterize current behavior before moving code with tests, static checks, import graphs, source inspection, or artifact snapshots.
+   - Keep public contracts stable unless the audit finding explicitly requires contract change.
+   - Update tests, docs, and imports only where required by the architecture fix.
+10. Use agent orchestration only when it improves signal. Dispatch per `references/agent-orchestration.md`:
+
+> **Dispatch: `massa-ai-builder`** (role: `builder`) — charter `skills/agents/builder/SKILL.md`
+> - trigger: large/high-risk finding, disjoint implementation slice, or explicit subagent request
+> - scope: one isolated architecture finding with a disjoint write set
+> - permissions: write (disjoint write set)
+> - inputs: the finding ID, target modules, affected bounded context or seam, current/desired dependency direction, behavior that must stay unchanged, validation assets, rollback path
+> - sensors: report's verification suggestion or equivalent deterministic command; static dependency-direction/import-cycle checks
+> - output: implementation summary, commands run, test counts, deviations
+> - firewall: raw diffs/logs summarized
+> - memory: suggest-only; main agent persists reusable architecture patterns
+
+> **Dispatch: `massa-ai-verification-agent`** (role: `verification-agent`) — charter `skills/agents/verification-agent/SKILL.md`
+> - trigger: independent verification of a high-risk or multi-file architecture fix
+> - scope: the fixed finding's dependency direction, tests, imports, and report claim closure
+> - permissions: read-only
+> - inputs: the finding, the applied fix, the verification suggestion, and validation assets
+> - sensors: deterministic command (targeted tests, import-cycle check, dependency-direction check) and report claim closure check
+> - output: confirmed/disproven closure verdict with evidence
+> - firewall: raw test output/logs summarized
+> - memory: suggest-only; main agent persists reusable verification recipes
+11. Verify each completed finding:
+   - If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
+     `python3 skills/massa-ai/scripts/lessons.py --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
+   - Apply the Mandatory Verification Fix Gate from `references/verification-ladder.md`: run the report's Verification Suggestion or an equivalent deterministic command/artifact check for each selected finding or coherent group.
+   - A finding cannot be marked `fixed` when a target-relevant command or artifact check exists but was not attempted; if verification cannot run, mark it `blocked`, `deferred`, or `skipped` with an allowed skipped-check reason.
+   - Run the report's verification suggestion when available.
+   - Add static checks for dependency direction/import cycles when feasible.
+   - For domain findings, verify names, ownership, contracts, or tests reflect the intended ubiquitous language without inventing undocumented domain truth.
+   - For coupling findings, verify the risky edge was removed, weakened to a contract, moved closer, or explicitly documented as stable.
+   - For deepening findings, verify callers/tests use the intended interface and no new hypothetical seam was added without real variation.
+   - Run targeted tests or builds affected by moved boundaries.
+   - Record command/artifact, result, skipped reason or `none`, highest Verification Ladder level reached, validation assets protected, and residual risk.
+12. At completion, persist only durable knowledge:
+   - Accepted architecture constraints, new seams, rejected broad refactors, reusable dependency checks, or recurring coupling patterns after scoring with the Importance Calibration System.
+   - Use required tags: `project:<projectId>`, `session:<workflowSessionId>`, `workflow:architecture-fix`, `entity:<entity>`, and one `memory:<tier>` tag.
+13. Complete the Evidence Gate from `references/evidence-gate.md`.
+
+## Examples
+
+User asks: "Use architecture-fix to fix the latest architecture audit for the billing boundary."
+
+1. Confirm target focus is `billing boundary`, then read the latest matching `audits/architecture/* architecture-audit.md`.
+2. Validate metadata, target focus, freshness, required fields, and current evidence before editing.
+3. Extract actionable findings and build a finding-by-finding execution map.
+4. Fix one boundary or coupling issue at a time.
+5. Verify dependency direction and behavior before moving to the next finding.
+
+User asks: "Fix finding ARCH-2 from audits/architecture/2026-06-06 architecture-audit.md."
+
+1. Read the specified report and only execute `ARCH-2`.
+2. Preserve unaffected architecture findings for later.
+3. Report evidence for `ARCH-2` closure and residual risks.

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

@@ -0,0 +1,113 @@
+### 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`.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+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.
+
+This workflow is findings-only. Do not edit code unless the user separately asks for fixes.
+
+1. Resolve/reuse `workflowSessionId`: `bugs-audit-[entity]`
+2. Load shared references:
+   - `references/codebase-investigation.md`
+   - `references/audit-scope.md`
+   - `references/audit-report-io.md` before writing the final direct audit report
+   - `references/context-firewall.md` before inspecting large diffs, logs, snapshots, generated reports, or broad search output
+   - `references/synapse-policy.md` when repeated massa-ai searches are expected
+   - `references/agent-orchestration.md` only for large scopes, explicit parallel/subagent requests, PR subagent invocation, or independent verification of high-impact findings
+3. `recall` -> load prior bug patterns, known regressions, project constraints, ADRs, fragile flows, and accepted exceptions for the target area.
+   - Apply the Memory Freshness Gate from `references/audit-scope.md`; recalled exceptions are leads, not proof.
+4. Establish the investigation scope before proceeding:
+   - Modified files scope: use when the user says modified files, changed files, current changes, uncommitted changes, staged changes, or unstaged changes.
+   - Explicit files/globs scope: use when the user names files, directories, or globs.
+   - Commit range scope: use when the user provides commits/ranges or asks for commits made by me, my branch commits, or bugs introduced by branch commits.
+   - Branch comparison scope: use when the user names base/head branches, refs, or a branch diff.
+   - Codebase area scope: use when the user names a path, module, package, feature area, service, or glob.
+   - Symbol/class/function scope: use when the user names public classes, functions, APIs, handlers, or exported surfaces.
+   - Feature/flow scope: use when the user names a runtime flow, user journey, or feature area.
+   - Whole-repo scope: use only when the user explicitly asks for a whole-repo bug audit.
+   - 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:
+
+> **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
+> - scope: the bugs audit target — files, diffs, suspicious paths
+> - permissions: read-only
+> - inputs: shared scope packet; `lens: bugs`; recalled regressions, known bug patterns, accepted exceptions
+> - sensors: trace input -> transformation -> output; check diffs, callers/callees, tests, config, migrations; prioritize correctness bugs, crashes, data loss, security regressions, broken contracts, async/race issues
+> - output: findings with bug category, location, evidence, trigger, severity, confidence, simplest fix direction, verification suggestion
+> - firewall: raw diffs/logs/search output summarized, not returned raw
+> - memory: suggest-only; main agent persists reusable bug patterns
+
+    - Trace input -> transformation -> output for each suspicious path.
+   - 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:
+   - 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):
+   - `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:
+   - 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.
+   - 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 `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:
+   - 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`.
+
+## Examples
+
+User asks: "Find bugs in modified files."
+
+1. Use `workflowSessionId=bugs-audit-modified-files`.
+2. Scope to staged, unstaged, and relevant untracked files; exclude generated/dependency/build/log/cache/secret paths.
+3. Inspect diffs first, then surrounding code and tests for suspicious changes.
+4. Run a false-positive pass before reporting findings.
+
+User asks: "Review commits made by me in this branch for bugs."
+
+1. Use `workflowSessionId=bugs-audit-branch-commits`.
+2. Resolve author from Git config and branch base from upstream or main/master fallback.
+3. Review only branch-unique commits authored by that identity.
+4. Report findings by severity with confidence, evidence, and verification suggestions.

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

@@ -0,0 +1,97 @@
+### Bugs Fix
+
+Use this workflow only to execute fixes from a bugs audit markdown report.
+
+Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+
+Before the first repository mutation, load `references/implementation-delivery.md` for worktree isolation, atomic commits, PR creation, CI watch, and the merge gate, and `references/code-annotation.md` for doc blocks, rationale comments, and test coverage on every created or updated unit. If two consecutive fix attempts fail on the same symptom, stop editing and load `references/root-cause-scripts.md`.
+
+Do not 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`.
+
+1. Resolve/reuse `workflowSessionId`: `bugs-fix-[entity]`
+2. Load shared references:
+   - `references/audit-report-io.md` before any code or test change
+   - `references/lessons.md` to load confirmed project lessons
+   - `references/codebase-investigation.md` before changing unfamiliar bug paths
+   - `references/verification-ladder.md` before non-trivial edits
+   - `references/context-firewall.md` before inspecting large diffs, logs, snapshots, generated reports, or broad search output
+   - `references/agent-orchestration.md` only for large/high-risk findings, disjoint implementation slices, or independent verification
+3. `recall` -> load prior bug patterns, known regressions, fragile flows, accepted exceptions, testing conventions, and reusable verification recipes for the report target.
+4. Select the bugs audit report with execution focus:
+   - Establish the report selector, target focus, and optional finding selector before selecting a report. Target focus can be a flow, module, files/globs, branch comparison, commit range, symbol/class/function, feature area, or explicit whole-repo target.
+   - If the user gives a path, read that exact markdown file.
+   - 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.
+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.
+   - If the user supplied finding IDs, extract only those IDs after validating they exist and match the current target focus.
+   - Rank by severity, trigger likelihood, regression risk, dependency order, and verification cost.
+6. Build a bug-fix map before editing:
+   - Finding ID -> impacted flow, trigger/repro path, suspected root cause, expected behavior, current behavior, files likely affected, validation assets, and verification command.
+   - Group findings only when one small fix addresses the same root cause.
+   - Keep unrelated cleanup out of scope.
+7. Size each finding with `references/verification-ladder.md`:
+   - Quick: local guard, null/state fix, small validation correction, deterministic branch fix, config/default correction, or focused regression test.
+   - Standard: multi-file data-flow fix, persistence or async behavior change, public contract correction, migration-adjacent repair, or meaningful test impact; define repro and verification recipe first.
+   - Spec-driven: new behavior policy, broad design change, cross-boundary ownership decision, migration strategy, or unclear expected behavior; pause and route to `workflows/spec-driven.md` or ask for approval.
+8. Apply bug fixing methods:
+   - Reproduce or confirm the trigger first when feasible; otherwise prove the root-cause path from current source evidence.
+   - Trace input -> transformation -> output and fix the divergence point closest to the root cause.
+   - Preserve existing public contracts unless the report explicitly identifies them as the bug.
+   - Prefer the smallest behavior-preserving fix: guard, validation, state update, ordering, await/async correction, persistence constraint, config default, or call-site contract alignment.
+   - Add or update regression tests for the trigger path when feasible; include positive coverage so the fix does not over-block valid behavior.
+   - Do not weaken tests, fixtures, snapshots, types, or public contracts to make the fix pass.
+9. Use agent orchestration only when it improves signal. Dispatch per `references/agent-orchestration.md`:
+
+> **Dispatch: `massa-ai-builder`** (role: `builder`) — charter `skills/agents/builder/SKILL.md`
+> - trigger: large/high-risk finding, disjoint implementation slice, or explicit subagent request
+> - scope: one isolated bug finding with a disjoint write set
+> - permissions: write (disjoint write set)
+> - inputs: the finding ID, repro path, root cause, and simplest fix direction
+> - sensors: report's verification suggestion or equivalent deterministic command; repro path must fail before fix and pass after
+> - output: implementation summary, commands run, test counts, deviations
+> - firewall: raw diffs/logs summarized
+> - memory: suggest-only; main agent persists reusable bug patterns
+
+> **Dispatch: `massa-ai-verification-agent`** (role: `verification-agent`) — charter `skills/agents/verification-agent/SKILL.md`
+> - trigger: independent verification of a high-risk bug fix
+> - scope: the fixed finding's repro path, tests, and report claim closure
+> - permissions: read-only
+> - inputs: the finding, the applied fix, the verification suggestion, and validation assets
+> - sensors: deterministic command (repro path, focused tests, inspection) and report claim closure
+> - output: confirmed/disproven closure verdict with evidence
+> - firewall: raw test output/logs summarized
+> - memory: suggest-only; main agent persists reusable verification recipes
+   - Main agent owns report parsing, prioritization, memory writes, final synthesis, and Evidence Gate.
+10. Verify each completed finding:
+   - If verification found a reusable signal (`ac_gap`, `surviving_mutant`, `spec_precision_gap`, `spec_deviation`, `gate_fail`), record it via `references/lessons.md`:
+     `python3 skills/massa-ai/scripts/lessons.py --root . add --feature "<slug>" --signal "<signal>" --source "<ref>" --text "<one terse lesson>"`
+   - Apply the Mandatory Verification Fix Gate from `references/verification-ladder.md`: run the report's Verification Suggestion or an equivalent deterministic command/artifact check for each selected finding or coherent group.
+   - A finding cannot be marked `fixed` when a target-relevant command or artifact check exists but was not attempted; if verification cannot run, mark it `blocked`, `deferred`, or `skipped` with an allowed skipped-check reason.
+   - Run the report's verification suggestion when available.
+   - Run focused regression tests first, then relevant lint/type/build/test commands when feasible.
+   - Confirm validation assets were not weakened.
+   - Record command/artifact, result, skipped reason or `none`, highest Verification Ladder level reached, validation assets protected, and residual risk.
+11. At completion, persist only durable knowledge:
+   - Root causes, fragile project-specific flows, accepted exceptions, or reusable regression-test recipes after scoring with the Importance Calibration System.
+   - Use required tags: `project:<projectId>`, `session:<workflowSessionId>`, `workflow:bugs-fix`, `entity:<entity>`, and one `memory:<tier>` tag.
+12. Complete the Evidence Gate from `references/evidence-gate.md`.
+
+## Examples
+
+User asks: "Use bugs-fix to fix latest audit findings for checkout persistence."
+
+1. Confirm target focus is `checkout persistence`, then read the latest matching `audits/bugs/* bugs-audit.md`.
+2. Validate metadata, target focus, freshness, required fields, and current evidence before editing.
+3. Confirm each trigger or root-cause path.
+4. Fix the smallest root-cause divergence and add regression coverage when feasible.
+5. Run focused verification and report skipped broader checks.
+
+User asks: "Fix BUG-2 from audits/bugs/2026-06-07 bugs-audit.md."
+
+1. Read the specified report and only execute `BUG-2`.
+2. Preserve other bug findings for later.
+3. Report evidence for `BUG-2` closure and residual risks.