@massa-ai/cursor-plugin 1.9.1 → 1.10.0

package/.cursor-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "massa-ai",
-  "version": "1.9.1",
+  "version": "1.10.0",
   "description": "massa-ai — semantic code search, memory, and context compression for Cursor"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massa-ai/cursor-plugin",
-  "version": "1.9.1",
+  "version": "1.10.0",
   "description": "massa-ai plugin for Cursor — semantic code search, memory, and context compression",
   "files": [
     "agents",

package/skills/massa-ai/SKILL.md

@@ -278,6 +278,7 @@ Load only when a selected workflow asks for them:
 - `references/project-context.md`
 - `references/implementation-delivery.md`
 - `references/code-annotation.md`
+- `references/repo-rules-discovery.md`
 - `references/root-cause-scripts.md`
 - `references/conversation-feedback.md`
 - `references/maestro.md`

package/skills/massa-ai/references/code-annotation.md

@@ -104,6 +104,34 @@ Rules:
 - If no valid test seam exists, document why in the completion report rather
   than silently shipping untested code.
 
+### Exception — data and domain models are not unit-tested
+
+Data models and anemic domain models carry state, not behavior. A unit test
+that constructs them and asserts their own getters, setters, fields, or
+constructor defaults mirrors the implementation and cannot detect that the
+model is wrong — it is the "test that mirrors the code" anti-pattern from the
+rule above. **Do not write unit tests for these kinds:**
+
+- **Data models** — persistence-layer entities: ORM-mapped classes, database
+  schema-mapped types, Prisma/TypeORM/Entity Framework/Hibernate/JPA entities,
+  SQL row types, and repository entity structs.
+- **Anemic domain models** — DDD value objects and domain entities whose public
+  surface is fields, accessors, and constructors with no meaningful behavior
+  (no invariants, no state transitions, no domain rules).
+
+This applies across every language the workflows touch (TypeScript/JavaScript,
+Kotlin, Swift, Java, Python, Go, Rust, C#, Ruby, PHP, SQL). Test the **behavior**
+that uses the model at the seam where it lives — the repository, service,
+use-case, or mapper that creates, validates, persists, or transforms it.
+
+This exception does **not** weaken the "test every changed code path" rule for
+code that has behavior. A model with invariants, validation, state machines, or
+domain rules is not anemic — test those rules at the model or the seam that
+exercises them, wherever the contract is observable. When unsure whether a model
+is anemic, the test is: "does this type have a method whose outcome is not fully
+determined by its inputs and field assignments?" If yes, it has behavior; test
+it. If no, it is a data model; test its consumers instead.
+
 ## Completion Evidence
 
 Report, per changed unit: doc block present (yes / not-applicable-because), the

package/skills/massa-ai/references/implementation-delivery.md

@@ -29,11 +29,13 @@ human chose to merge it".
 
 ### Stage 1 — worktree isolation is mandatory
 
-Every implementation task runs in its own git worktree. There is **no size
-exemption**: a one-line typo fix is isolated exactly like a twelve-file feature.
-The reason is that the exemption, not the ceremony, is what costs time —
-"this one is too small to isolate" is the judgment call that puts half-finished
-work on a shared branch.
+Every implementation task runs in its own git worktree. **Mandatory worktree
+creation is the rule, not a preference:** a one-line typo fix is isolated
+exactly like a twelve-file feature. There is **no size exemption**. The reason
+is that the exemption, not the ceremony, is what costs time — "this one is too
+small to isolate" is the judgment call that puts half-finished work on a shared
+branch. Worktree creation happens **before the first repository mutation**, not
+after implementation.
 
 The only two legal skip reasons:
 
@@ -48,6 +50,17 @@ no `node_modules`, no `dist`, and no `.env`. A gate that fails only because the
 worktree was never provisioned is an environment failure; say so rather than
 reporting it as a code failure.
 
+**Phased work — one branch per Phase/Wave.** When the work is phased (sourced
+from `workflows/ticket.md`, a spec-driven `tasks.md` with Phases/Waves, or a TDD
+PR-group table), create **one branch per Phase/Wave**, not one branch per task
+and not one branch for the whole feature. Name the branch with the phase's Jira
+Task key, e.g. `feat/<PHASE-KEY>-<slug>` (so `feat/SA-100-phase-1-search-split`
+for phase SA-100). The phase key comes from `workflows/ticket.md` or the user.
+Each Task inside the phase is then one atomic commit on that branch, prefixed
+with its own sub-task key — the commit contract is owned by
+`workflows/commit.md`; do not restate it here. Non-phased work keeps the
+`<type>/<slug>` branch shape unchanged.
+
 ### Stage 2 — one commit per task
 
 Commit message content, staging rules, audit-report exclusions, and Jira
@@ -56,6 +69,16 @@ that workflow. This reference owns only the cadence: **one atomic commit per
 completed task, after its gate passes.** Never batch tasks into one commit and
 never commit a task whose gate is red.
 
+### Stage 4 — propose carries the phase key prefix
+
+The PR/MR is created with `gh pr create --base <base> --title <t> --body <b>`.
+For **phased work**, the PR title and body include the Phase/Wave Jira Task key
+prefix, matching the branch naming (the branch is named with that phase key per
+Stage 1). Source the key from the branch; do not ask the user again. Example
+title: `[SA-100] Phase 1: search facade split`. The per-task commit prefixes on
+the branch are owned by `workflows/commit.md`; this stage owns only the PR-level
+phase prefix. Non-phased work keeps the existing PR title behavior unchanged.
+
 ### Stage 7 — merge is never automatic
 
 Do not run `gh pr merge` without explicit user approval given in the current

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

@@ -0,0 +1,103 @@
+# Repo Rules Discovery
+
+Use this reference from `workflows/spec-driven.md` before the first repository
+mutation. It defines how to discover, load, and enforce the target repository's
+own AI-harness rules and implementation conventions, so spec-driven
+implementation conforms to the repo it runs in rather than only to the
+skill's defaults.
+
+massa-ai is shipped to many repositories. This reference is **conditional on
+the target repo**: it loads what is present and never invents what is absent.
+
+## Principle
+
+A repository's rules live in its own harness files and conventions. spec-driven
+must read them before implementing and enforce conformance, because a change
+that follows the skill's defaults but violates the repo's module layout, test
+placement, or lint rules is not deliverable. Silence here reads as "the repo
+has no rules", which is almost never true — it means they were not looked up.
+
+## 1. Discovery list
+
+Look for the target repo's AI-harness rule sources in this order. Record each
+one found with its path; record `none present` for any that are absent.
+
+### `.claude/` harness
+
+- `.claude/CLAUDE.md` — the primary Claude Code instructions file.
+- `.claude/rules/**` — rule files imported by CLAUDE.md.
+- `.claude/settings.json` — permissions and tool policy (read-only; never mutate).
+- A root `CLAUDE.md` when `.claude/CLAUDE.md` is absent.
+
+### `.cursor/` harness
+
+- `.cursor/rules/*.mdc` and `.cursor/rules/*.md` — Cursor rule files (MDC format).
+- `.cursorrules` — the legacy single-file Cursor rules at repo root.
+
+### Other harness sources
+
+- `AGENTS.md` at the repo root and in subdirectories (the cross-host standard).
+- `CONTRIBUTING.md`, `README.md`, and `docs/` when they state implementation,
+  testing, or layout rules.
+- The repo's test-runner config (`bunfig.toml`, `jest.config.*`, `vitest.config.*`,
+  `pytest.ini`/`pyproject.toml`, `gradle` test blocks, Xcode test schemes) —
+  these pin **where tests live and how the gate runs**.
+
+### Repo / module implementation pattern
+
+Derive the repo's own conventions by reading current source, not by assuming
+the skill's defaults:
+
+- **Module layout** — where new source files go (layer folders, feature folders,
+  package boundaries).
+- **Unit-test location** — the source set or directory the repo uses for unit
+  tests (`__tests__/`, `src/test/`, `commonTest/`, `androidUnitTest/`,
+  `unitTest/`, `tests/`, the repo's actual equivalent).
+- **Testing areas** — integration vs unit vs e2e boundaries the repo already
+  enforces, and which test runner command exercises each.
+
+## 2. Loading order
+
+1. Read each present source from §1; skip absent ones without erroring.
+2. Summarize what binds implementation into a compact `repo-rules` record:
+   - the paths loaded,
+   - the rules that constrain implementation (layout, naming, lint, test
+     placement, commit/branch conventions),
+   - any rule that conflicts with the skill's default.
+3. If a repo rule conflicts with a skill default, the **repo rule wins** for
+   implementation placement and gate commands; record the conflict and the
+   resolution.
+
+## 3. Absence is valid
+
+If none of the sources in §1 are present, record:
+
+```
+repo-rules: none present
+```
+
+and continue. **Never fabricate rules. Never create `.claude/`, `.cursor/`, or
+any harness directory in a repo that lacks them.** A repo with no harness rules
+is implemented against its own source conventions (§1 "Repo / module
+implementation pattern") and the skill's defaults — that is a legitimate state,
+not a failure.
+
+## 4. Enforcement hook (spec-driven)
+
+Before the first repository mutation, spec-driven:
+
+1. runs this discovery,
+2. records the `repo-rules` summary (paths loaded, or `none present`),
+3. implements so that every new or changed file conforms to the discovered
+   module layout, unit-test location, and testing-area conventions,
+4. records any deviation with an explicit reason in the completion evidence.
+
+A deviation is allowed only with a recorded reason; an unrecorded deviation is
+a protocol violation, not a shortcut.
+
+## Completion Evidence
+
+Report, in one block: the harness sources loaded (paths), the repo's module /
+unit-test / testing-area conventions in effect, any repo-rule vs skill-default
+conflict and its resolution, or `repo-rules: none present` with the conventions
+derived from source.

package/skills/massa-ai/references/spec-driven/execute.md

@@ -67,6 +67,8 @@ If `tasks.md` exists, check dependencies. If using the inline plan, follow the o
 
 If blocked: "T3 depends on T2 which isn't done. Should I do T2 first?"
 
+**Wire dependencies in this task, not later.** The task that introduces a component also wires it — registration, binding, and composition-root/module setup are part of the task, never deferred to a trailing "DI" or "integration" phase. Code whose dependencies are not wired is incomplete and fails this task's gate; "wiring happens in a later phase" is not a valid state. See `references/spec-driven/tasks.md` → *Dependency Injection And Wiring Is Per-Task, Never a Separate Phase* for the planning-side rule and the restructure options (wire inline / merge backward / merge forward).
+
 ### 3. State Implementation Plan
 
 Before writing code:

package/skills/massa-ai/references/spec-driven/tasks.md

@@ -151,6 +151,8 @@ Group tasks into ordered phases. Each phase depends on the ones before it; tasks
 
 This keeps phase boundaries meaningful while letting the packing hit its target worker count.
 
+**No trailing wiring phase.** A phase whose purpose is DI, wiring, or integration of this feature's own components is prohibited — that work belongs in the task that introduces each component (see *Dependency Injection And Wiring Is Per-Task, Never a Separate Phase* below). Split phases at genuine dependency/cohesion seams, never to gather wiring into one place.
+
 ### 5. Validate Before Presenting (MANDATORY)
 
 Before showing tasks to the user, run ALL three pre-approval checks. These are NOT optional — they are gates. If any check fails, restructure the tasks and re-run until all pass.
@@ -427,6 +429,26 @@ Pick whichever option keeps tasks atomic and cohesive. The goal: no task produce
 
 ---
 
+## Dependency Injection And Wiring Is Per-Task, Never a Separate Phase
+
+Dependency injection, module/dependency wiring, container/service registration, and composition-root setup for a unit of code are done **inside the task (or its phase) that introduces that unit**. **Never collect wiring into a dedicated trailing "DI", "wiring", or "integration" phase.** A final phase whose purpose is "wire everything together" is the same defect class as deferring tests to a separate task (see *Resolving compilation dependencies* above): every intermediate task ships code that cannot build or run until a much later phase, so none of their gates actually prove the code works in context, and a failure or skip in the trailing phase strands all preceding work.
+
+This rule is the dependency-side twin of test co-location: tests live with the code that creates it, and so does its wiring.
+
+**Rule:** each task must leave the repository buildable and its own gate green against code whose dependencies are wired **by that task or an earlier one**. Code whose dependencies are not yet wired is incomplete — it is a gate failure, not a deferred item.
+
+**When a task introduces code that needs wiring, restructure rather than defer:**
+
+1. **Wire inline:** the task that creates the component/service also registers it, binds its dependencies, and adds it to the composition root or module it belongs to.
+2. **Merge backward:** if the wiring depends on a container or module a later task introduces, pull that container/module into this task so the code is wired and runnable now.
+3. **Merge forward:** only when wiring is genuinely shared across several components, fold the wiring into the earliest task where the wired unit becomes runnable — never into a phase whose only job is wiring.
+
+Pick whichever keeps tasks atomic and the repository green at every commit. The goal: no task produces code that cannot run until a later phase. If a unit cannot be wired in the task that creates it, the task or phase boundaries are wrong.
+
+**Phase-planning consequence:** the execution plan must not contain a phase whose stated purpose is DI, wiring, or integration of everything built earlier. "Integration" phases are allowed only when they integrate *externally* delivered components (a third-party service, another team's API) that were not available to earlier tasks — never as a catch-all for wiring this feature's own code. A phase that exists only to wire the feature's own components is a planning smell: redistribute its work into the tasks that own each component.
+
+---
+
 ## Tips
 
 - **Phases are ordered** — Each phase completes before the next; tasks run in order within a phase
@@ -486,6 +508,7 @@ Before sampling tests manually, prefer massa-ai tooling to read the codebase:
 
 - Keep tasks atomic enough to verify independently.
 - Order tasks so earlier tasks leave the repository buildable and testable.
+- **Dependency injection and wiring are per-task/per-phase.** The task that introduces a component wires it (registration, binding, composition root). Never defer wiring to a separate trailing "DI"/"wiring"/"integration" phase; a phase that only wires this feature's own code is a planning smell. See *Dependency Injection And Wiring Is Per-Task, Never a Separate Phase* above.
 - Do not create tasks that require hidden chat context; every task must point to the spec/design evidence it needs.
 - If a task reveals a missing requirement or design decision, stop and update the earlier artifact (`.specs/features/<slug>/spec.md` or `design.md`) before continuing.
 

package/skills/massa-ai/references/ticket/intake-and-sources.md

@@ -11,6 +11,7 @@ Resolve inputs in this order:
    - `epic-tickets`: create a new Epic and standard child issues.
    - `epic-tickets-subtasks`: create a new Epic, standard child issues, and sub-tasks.
    - `tickets-subtasks`: create standard issues and optional sub-tasks without creating an Epic. Ask for an existing Epic key only when the user wants those standard issues attached and Jira supports that relationship.
+   - A phased source (spec-driven `tasks.md` organized into Phases/Waves, or a TDD implementation PR-group table) selects the **phased mapping** under `tickets-subtasks`: one standard Task per Phase/Wave, one sub-task per Task inside the phase. See `templates-and-quality.md` → Phased Decomposition.
 3. **Ticket template source**: ask whether to use a Jira reference issue, an explicitly supplied local file or pasted template, or the built-in templates. A Jira reference may be supplied as a key or URL.
 4. **Definition of Ready and Definition of Done**: ask whether the user wants to provide either source. Accept Jira or Confluence content through Atlassian MCP, explicitly supplied local files, or pasted text. Use built-in checklists when omitted.
 5. **Jira-required choices**: after metadata inspection, ask only for unresolved issue types, priorities, components, labels, ownership, versions, or custom fields that are required by Jira or material to the user's intent.

package/skills/massa-ai/references/ticket/templates-and-quality.md

@@ -111,6 +111,30 @@ A sub-task cannot exist without one standard parent issue. Do not use sub-tasks
 - Do not enforce fixed day estimates. Size by outcome coherence, dependency boundaries, reviewability, and whether an assignee can complete the work without reopening product decisions.
 - Express dependency edges through stable draft IDs before Jira keys exist. Reject self-dependencies and cycles.
 
+### Phased Decomposition (spec-driven / TDD source)
+
+When the source plan is already phased — a spec-driven `tasks.md` with
+Phases/Waves, or a TDD implementation PR-group table — decompose to match the
+phases, not by layer:
+
+- **Phase/Wave → one standard Jira Task.** Each phase or wave becomes one
+  standard issue whose acceptance criteria are the phase's exit gate.
+- **Task inside a phase → one sub-task.** Each atomic task listed inside a
+  phase becomes one sub-task parented to that phase's Task. The sub-task's
+  acceptance criteria are the task's own gate.
+- **Branch naming follows the Phase/Wave key.** One branch per phase, named with
+  the phase's Jira key; the branch command itself is owned by
+  `references/implementation-delivery.md` Stage 1 — do not restate it here.
+- **One commit per task sub-task.** Each sub-task maps to exactly one atomic
+  commit prefixed with its sub-task key `[XXX-YYYY]`; the commit contract is
+  owned by `workflows/commit.md` — do not restate it here.
+- Emit every created phase-Task key and task-sub-task key back to the caller so
+  the branch/commit/PR rules can consume them.
+
+This is the `tickets-subtasks` hierarchy mode driven by a phased input. It does
+not create a new issue type and does not require an Epic; the Epic layer stays
+optional.
+
 ## Deterministic Quality Gate
 
 Before review approval, verify every draft:

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

@@ -16,7 +16,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.
+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.
 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/spec-driven.md

@@ -4,7 +4,7 @@ Use this workflow for explicit spec-driven requests and broad, ambiguous, migrat
 
 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`.
+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, and `references/repo-rules-discovery.md` to discover and enforce the target repository's own `.claude/`, `.cursor/`, and module/unit-test/testing-area conventions. If two consecutive fix attempts fail on the same symptom, stop editing and load `references/root-cause-scripts.md`.
 
 ## TLC v3 Flow
 
@@ -90,6 +90,7 @@ Quick artifacts live under `.specs/quick/NNN-slug/` with a `TASK.md` (one-line i
 5. Decide whether `Tasks` is required. If yes, run `references/spec-driven/tasks.md`; if no, list the inline atomic execution steps before editing. If the inline list reveals more than 5 steps or complex dependencies, stop and create `tasks.md` — the Tasks phase was wrongly skipped (safety valve).
 6. Run `Execute` with `references/spec-driven/execute.md`.
    - Load `references/spec-driven/coding-principles.md` before implementation.
+   - Run repo-rules discovery from `references/repo-rules-discovery.md` before the first repository mutation: record the harness sources loaded (or `repo-rules: none present`), and implement so every new or changed file conforms to the target repo's module layout, unit-test location, and testing-area conventions. A repo rule wins over a skill default for placement and gate commands; record any deviation with an explicit reason. Never fabricate rules or create `.claude/`/`.cursor/` directories the repo lacks.
    - Use the Test Coverage Matrix and Gate Check Commands from `tasks.md`, or state their inline equivalents when Tasks was skipped.
    - Ask the MCP and skill question in Tasks or inline Execute when tool choice can change correctness or verification.
    - If a formal `tasks.md` packs into more than one task-budgeted batch (> ~8 tasks), present the sub-agent offer from `references/spec-driven/sub-agents.md` before starting Execute. Offer-then-confirm — never auto-spawn; the user must accept before any sub-agent is dispatched. One worker per batch (~7 tasks, whole phases): each batch worker executes all its tasks in order (implement → gate → atomic commit), then reports a compact summary (tasks done, commit hashes, test counts, deviations). Workers never spawn further sub-agents.

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

@@ -18,6 +18,7 @@ Before the first substantive read, load `references/project-context.md` and run
 6. When code grounding is useful, run a bounded read-only child pass using `workflows/exploration.md`, then return to the ticket session. Never search Git history, branches, commits, or repository ticket references for ticket examples or templates.
 7. Inspect the selected Jira project's issue types, required fields, parent rules, and relevant field options before finalizing the draft. A reference ticket controls format and tone only; it does not authorize copying project facts.
 8. Draft the requested hierarchy using `templates-and-quality.md`. Keep each standard issue independently understandable, use sub-tasks only for atomic work owned by one parent, and make dependencies explicit.
+   - **Phased source mapping:** when the source is a phased plan — a spec-driven `tasks.md` organized into Phases/Waves, or a TDD implementation PR-group table — map the hierarchy to the phases: **one standard Jira Task per Phase/Wave**, and **one sub-task per Task inside that phase**, each sub-task parented to its phase's Task. This reuses the `tickets-subtasks` hierarchy mode; do not invent new issue types. The Epic layer stays optional and unchanged. Record every created phase-Task key and task-sub-task key so `workflows/commit.md` (per-task commit prefix) and the Implementation Delivery Protocol (phase branch + PR prefix) can consume them. See `templates-and-quality.md` → Phased Decomposition.
 9. Search the selected Jira project for potential duplicates using the proposed summary and distinctive scope terms. Record candidates in the review artifact; do not silently merge, skip, or close work.
 10. Resolve the agent-native external plans directory and create one temporary review file named `ticket-<project>-<slug>-<YYYYMMDDTHHMMSSZ>.md`. The artifact must be outside the repository and contain stable draft IDs, draft revision, approval status, creation order, Jira fields, full descriptions, duplicate candidates, open questions, and created keys or URLs when present.
 11. Run every deterministic quality gate from `templates-and-quality.md`. Present the current artifact for review. Any content or field revision increments `Draft Revision` and resets `Approval Status` to `NOT APPROVED`.