@massa-ai/cursor-plugin 1.35.0 → 1.35.1

package/.cursor-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "massa-ai",
-  "version": "1.35.0",
+  "version": "1.35.1",
   "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.35.0",
+  "version": "1.35.1",
   "description": "massa-ai plugin for Cursor — semantic code search, memory, and context compression",
   "files": [
     "agents",

package/skills/massa-ai/references/agent-orchestration.md

@@ -79,6 +79,10 @@ Plan Challenge `plan-critic` is a standing policy exception to the normal dispat
 
 For all other roles, preserve the normal delegation gates above.
 
+## Independent Verification Exception (fix workflows + Standard+ light-workflow tiers)
+
+The Independent Verification Mandate in `references/verification-ladder.md` is a second standing policy exception, parallel to the Plan Challenge one: when a `*-fix` workflow closes a finding, or a light workflow (`debug`, `feature`, `general`, `refactor`) completes Standard+ work, always attempt the `massa-ai-verification-agent` dispatch when subagent tooling is available and platform policy permits spawning — it does not need to satisfy the ordinary dispatch triggers (file count, module count, explicit user delegation). Base packet-quality requirements still apply, and the mandate's own tier gates, security-fix unconditional rule, and fresh-eyes fallback live in that ladder section, not here.
+
 ## Name Resolution
 
 Charters live at `skills/agents/<role>/SKILL.md`. Hosts register every charter

package/skills/massa-ai/references/artifact-persistence.md

@@ -0,0 +1,46 @@
+# Artifact Persistence
+
+Use before any workflow reads or writes durable `.specs/` artifacts. This file owns the canonical-store mechanics shared by every workflow family. Logical paths stay per-workflow-owned: spec-driven's table lives in `references/spec-driven/artifact-store.md`; other workflows declare their own paths inline (e.g. `.specs/debug/<slug>/REPORT.md`, `.specs/refactors/<slug>/{CHARACTERIZATION,PLAN,SENSOR}.md`, `.specs/quick/NNN-slug/`, `.specs/project/onboarding/{CONCERNS,TESTING}.md`).
+
+## Canonical Store
+
+- Canonical state lives in `.specs/` files tracked in the repository, not massa-ai records, semantic memories, chat summaries, or root aliases.
+- Current repository source remains authoritative for implementation/code evidence.
+- `search`, `recall`, and durable memories may discover context, decisions, or reusable patterns, but must never reconstruct canonical artifact state.
+- If `.specs/` is unavailable or not writable, **block** the workflow's durable-state mutation and record the blocker; do not fall back to memory or chat as a substitute store.
+
+## STATE Precedence Chain
+
+Artifact reads resolve conflicts in this strict order (first match wins): fresh user instruction > approved `.specs/` artifact > STATE/HANDOFF > massa-ai memory. massa-ai memory and external summaries are discovery, not authority. In a repository with no `.specs/project/STATE.md`/`.specs/HANDOFF.md`, the chain simply has fewer links — the ordering is unchanged.
+
+## Quick Artifact Templates
+
+Quick-sized tasks persist under `.specs/quick/NNN-slug/` — `NNN` zero-padded and sequential per project, `slug` the short kebab-case intent. Exactly two files:
+
+**`.specs/quick/NNN-slug/TASK.md`:**
+
+```markdown
+# Quick NNN: <one-line intent>
+
+## Acceptance
+- <single testable criterion — the gate the Execute step must pass>
+```
+
+**`.specs/quick/NNN-slug/SUMMARY.md`:**
+
+```markdown
+# Quick NNN: <one-line intent>
+
+## Result
+- Status: Complete | Blocked | Partial
+- Files changed: <list or "none">
+- Gate: <command + pass/fail evidence>
+- SPEC_DEVIATION: <none | what diverged and why>
+```
+
+Quick artifacts are canonical `.specs/` state — same precedence chain, same section-scoped write rules; they are not a second store. Deterministic backing: `bun skills/massa-ai/scripts/check_specs_delivered.ts <slug> --kind quick`.
+
+## Failure Handling
+
+- `.specs/` directory missing or not writable: block the workflow's durable-state mutation; do not fall back to memory or chat.
+- Required artifact missing: create it only through an approved first write; otherwise block and ask for direction.

package/skills/massa-ai/references/audit-report-io.md

@@ -75,6 +75,8 @@ In Plan Mode, do not write report files. Return the proposed canonical path and
 
 In Default mode, write the canonical report unless acting as a child lens returning compact findings to implementation audit.
 
+The same rule covers Fix Closure Reports: in Plan Mode, return the proposed closure path and complete closure content instead of writing the file.
+
 ## Single-Lens Report Contract
 
 ```md
@@ -530,11 +532,58 @@ Implementation reports must preserve the exact parent scope packet and source-qu
 
 When implementation-audit uses SonarQube MCP, preserve the MCP availability result, project key or skipped-check reason, quality gate status when available, tool names used, and summarized issue/security-hotspot/measure evidence in Scope And Evidence. Sonar-derived findings are executable only after they are normalized to existing source-qualified IDs for Architecture, Correctness/Bugs, Code Quality, Security, or Tests; unmapped SonarQube output remains evidence only and does not enter Execution Handoff.
 
+## Fix Closure Report Contract
+
+Every `*-fix` workflow persists its closure evidence as a Fix Closure Report, a sibling of the audit report it closes:
+
+```text
+audits/<family>/<YYYY-MM-DD <family>-fix-closure>.md
+```
+
+`<family>` is the source report's directory (`architecture`, `bugs`, `code-quality`, `security`, `requirements`, `tests`, `maestro`, `mobile-figma`, `implementation`). Same local-date and same-day suffix rules as audit reports. Closure reports are output artifacts, **never** audit-report input: any filename containing `-fix-closure` is excluded from latest-report selection.
+
+Required header lines (same metadata style as audit reports):
+
+```md
+# <Family> Fix Closure
+
+Date: <YYYY-MM-DD>
+Workflow: <family>-fix
+ProjectId: <projectId>
+WorkflowSessionId: <workflowSessionId>
+Source Report: <exact path of the audit report consumed>
+Finding Selector: <all | explicit finding IDs>
+```
+
+Then a `## Closure Matrix` with one row per selected finding:
+
+```md
+## Closure Matrix
+
+| Finding ID | Status | Changed Files | Command/Artifact | Result | Skipped Reason | Discrimination Sensor | Independent Verifier | Ladder Level | Validation Assets Protected | Residual Risk | Next Step |
+|---|---|---|---|---|---|---|---|---|---|---|---|
+```
+
+Row rules:
+
+- **Finding ID**: verbatim from the source report (`PREFIX-N`, or `Area/PREFIX-N` for implementation reports).
+- **Status**: `fixed | blocked | deferred | skipped` — terminal statuses only; a selected finding with no row is an incomplete closure.
+- **Command/Artifact** and **Result**: the deterministic evidence per the Mandatory Verification Fix Gate. A `fixed` row must carry a real command/artifact and result — never an unfilled `<placeholder>`, `TBD`, or empty cell.
+- **Skipped Reason**: `none` or one allowed skipped-check reason.
+- **Discrimination Sensor**: killed/survived summary per `references/discrimination-sensor.md`, or `not available — <reason>`.
+- **Independent Verifier**: verdict plus dispatch-or-fallback record per the verification-ladder Independent Verification Mandate.
+- **Next Step**: required for `blocked` and `deferred` rows.
+
+Family-specific extras (extra columns, parsed by header name, appended after the standard set): requirements adds `Linked .specs/ Requirement ID`; maestro and mobile-figma add `JUnit Report`, `Artifact Directory`, and `Device/Platform`.
+
+Deterministic backing (run it, do not eyeball it): `bun skills/massa-ai/scripts/check_fix_closure.ts <closure.md> --family <family>` — a non-zero exit blocks Propose and the Evidence Gate. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
+
 ## Execution Report Input
 
 Execution workflows read a saved markdown report before changing code. Establish:
 
 - Report selector: exact path, `latest`, or omitted.
+- Delivery authorization is scoped **per execution run** (the report + finding selector named at Execute start), not per finding — one go-ahead covers every selected finding's local commits through PR creation. Force-push, deploy, and merge stay separately gated per `references/implementation-delivery.md` Stage 3/7.
 - Target focus: module, flow, files/globs, branch comparison, commit range, PR target, symbol/class/function, feature/screen, modified files, or explicit whole-repository target.
 - Finding selector: optional workflow IDs or source-qualified implementation IDs.
 
@@ -542,6 +591,7 @@ If a path is supplied, use it and validate it against any stated focus. For `lat
 
 Select the latest matching report by:
 
+0. Exclude any filename containing `-fix-closure` — closure reports are outputs, not audit reports.
 1. Highest `YYYY-MM-DD` parsed from matching filenames.
 2. Most recent mtime as tie-breaker.
 3. Lexicographically last path if still tied.

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

@@ -0,0 +1,22 @@
+# Brownfield Onboarding — 7-Doc Codebase Mapping
+
+Use when the target codebase has not yet been mapped (brownfield, new repo,
+or cold project). The map is the shared factual ground for requirements,
+design, task derivation, and gate-command discovery; each doc feeds a
+downstream phase or verification step.
+
+| Doc | Derives | Feeds |
+| --- | --- | --- |
+| `STACK.md` | languages, runtimes, frameworks, key libraries | Design constraints, verification commands |
+| `ARCHITECTURE.md` | layers, modules, boundaries, data flow | Design, risk surface |
+| `CONVENTIONS.md` | naming, file layout, commit/test conventions | Tasks, Execute |
+| `STRUCTURE.md` | directory map, where new code goes | Tasks, file placement |
+| `TESTING.md` | test runner, how to run gates, coverage tooling | Gate Check Commands, verification recipe |
+| `INTEGRATIONS.md` | external services, APIs, contracts, auth | Discuss, risk escalation |
+| `CONCERNS.md` | known risks, tech debt, migration landmines, security/privacy hotspots | Risk-domain escalation, validation focus |
+
+## Minimum Bar
+
+Derive at least **`CONCERNS.md`** (risk surface — drives risk-domain escalation and validation focus) and **`TESTING.md`** (gate derivation — the exact commands the workflow's verification gate will run). When time or access is constrained, these two are non-negotiable; the other five are derived as the work needs them. Confirm the map against current source, not memory or external summaries.
+
+Output path: spec-driven work records the map under `.specs/features/<slug>/`; every other workflow records it under `.specs/project/onboarding/` (`CONCERNS.md`, `TESTING.md`).

package/skills/massa-ai/references/codebase-investigation.md

@@ -40,7 +40,7 @@ Prefer sources in this order:
    than exact source.
 7. Local `.notebook/INDEX.md` only if the project already uses `.notebook/`.
 8. Focused shell search/read fallback when massa-ai is unavailable, stale, incomplete, or unindexed.
-9. Official docs or web search only when current external API behavior matters.
+9. External sources only when current external library/API behavior matters — and then strictly through the ordered chain in `references/knowledge-verification-chain.md` (project docs → Context7 MCP → web search → flag-as-uncertain, unavailable steps recorded as skipped sensors).
 
 Project maps, search results, and optimized context are leads until confirmed
 against source files read in the current session or returned with current

package/skills/massa-ai/references/discrimination-sensor.md

@@ -0,0 +1,42 @@
+# Discrimination Sensor
+
+Use when a workflow must prove its validation can actually detect wrong behavior — the empirical guarantee that tests discriminate, not merely pass. The sensor injects behavior-level faults in an isolated scratch state and confirms the covering tests kill them. The real working tree is never modified.
+
+## Mutation Target
+
+The mutation target is always **the code under the claim being verified** — a correctness requirement, not a style choice:
+
+| Claim being verified | What to mutate |
+|---|---|
+| New behavior matches spec/ACs (spec-driven, feature) | The new code introduced by the change |
+| Behavior preservation (refactor, code-quality) | The *moved or transformed* code — the pre-existing behavior the characterization tests must protect, not new code |
+| A guard blocks the exploit (security) | The specific guard just added — invert it and confirm the negative test kills it |
+| A new or repaired test catches its bug (tests family) | The new/repaired test's subject code |
+
+## How It Works
+
+1. **Prepare an isolated scratch.** Never mutate the real worktree. Choose one:
+   - Preferred: a temporary git worktree (`git worktree add <scratch-path> HEAD`), mutate and run tests there, then `git worktree remove --force <scratch-path>`. Name the scratch `<worktree>-sensor-<finding-id>` (or `<worktree>-sensor-<slug>`) so it never collides with the delivery worktree.
+   - Fallback (no git / worktree unavailable): copy only the affected file(s) to a temp directory, mutate the copies, point the test runner at those copies (or restore originals from the copies' backups), then delete the temp directory.
+   - **Forbidden:** `git stash` / `git stash pop`. A stash records state *before* the mutation; popping it does not reverse a mutation applied afterward, and on a clean tree `git stash` creates no entry at all — so the fault is left in the real worktree.
+2. **Capture a baseline.** Record `git status --porcelain` (or equivalent) of the real worktree *before* any sensor work. It must be unchanged after cleanup.
+3. **Inject a behavior-level fault** into the scratch copy of the target code. Choose a mutation proportional to the code's risk:
+   - Flip a boolean condition (`if (x)` → `if (!x)`, `>` → `>=`)
+   - Change a return value (return a wrong status code, wrong field, zero instead of a computed value)
+   - Off-by-one (shift a loop bound, change a slice index)
+   - Remove a required side effect (delete a method call that the spec requires)
+4. **Run the tests** that cover the mutated code (against the scratch), using the workflow's gate command.
+5. **Confirm the mutant is killed** (tests FAIL). Discard the scratch (remove worktree or delete temp copies).
+6. **Verify isolation.** Re-run `git status --porcelain` on the real worktree and confirm it matches the baseline from step 2. If it differs, STOP — restore the real tree before continuing, and treat the sensor run as invalid.
+7. **If a mutant survives** (tests still pass after the fault), the tests are not discriminating for that behavior. Consequence by workflow family: spec-driven/feature create a **fix task** to strengthen the assertion; fix workflows record the finding's closure row as **`blocked`** (unproven verification) and emit the `surviving_mutant` lessons signal.
+
+## Tiering (proportional, not optional)
+
+| Context | Sensor depth |
+| ------- | ------------ |
+| Default | Lightweight fault-injection: 1–3 targeted behavior-level mutations, focused on the highest-risk target code |
+| P0 / critical paths (payment, auth, data integrity) | Full mutation run: use language-appropriate mutation tooling if available (e.g., Stryker, mutmut, cargo-mutants, pitest); otherwise increase the number of manual fault-injection mutations to ≥5 covering all branches |
+
+**Stack-agnostic:** the sensor targets behavior-level semantics (what the code does), not a specific tool. Any language, any framework.
+
+**Report:** record killed/survived for each mutation attempt, plus the sensor depth used. If a safe reversible mutant cannot be made, record why and mark the claim `Blocked` unless equivalent existing deterministic mutation evidence proves discrimination.

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

@@ -61,9 +61,12 @@ 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
+from `workflows/ticket.md`, a spec-driven `tasks.md` with Phases/Waves, a TDD
+PR-group table, or a `references/pr-task-fix.md` PR-group split), create
+**one branch per Phase/Wave**, not one branch per task
+and not one branch for the whole feature. All Phases/PR groups of one feature
+share that feature's single Stage 3 delivery authorization — one go-ahead
+covers every group's commits, pushes, and PR creation. 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
@@ -89,6 +92,8 @@ Between Push and Propose, all feature `.specs/` artifacts (`spec/context/design/
 
 **Nominal path: this stage should never fire.** The feature's own close-out task (the last task before delivery — see `workflows/spec-driven.md` step 7) commits `.specs/` updates **before** the first push, so stage 3.5's remediation is a defensive fallback for the rare case something slipped through, not the normal place `.specs/` gets committed. On failure: commit the missing `.specs/` updates (a `docs(specs):`-type commit is normal), push, re-run this stage. No commits may land between the close-out commit and PR creation.
 
+**Kind variants.** `check_specs_delivered.ts` takes `--kind feature|quick|debug|refactor` (default `feature`, the behavior above): `quick` gates `.specs/quick/<slug>/` `TASK.md`+`SUMMARY.md`, `debug` gates `.specs/debug/<slug>/REPORT.md`, `refactor` gates `.specs/refactors/<slug>/CHARACTERIZATION.md` (plus `PLAN.md`/`SENSOR.md` when present) — none of the non-feature kinds require the project STATE files. The fix-family analogue of this stage is `bun skills/massa-ai/scripts/check_fix_closure.ts <closure.md> --family <family>` (Fix Closure Report Contract in `references/audit-report-io.md`). Neither gate fires for a workflow run with no durable artifact in scope.
+
 ### Stage 4 — propose carries the phase key prefix
 
 The PR/MR is created with `gh pr create --base <base> --title <t> --body <b>`.

package/skills/massa-ai/references/knowledge-verification-chain.md

@@ -0,0 +1,25 @@
+# Knowledge Verification Chain
+
+Use when researching, designing, or making any technical decision whose answer depends on external library/API behavior, unfamiliar patterns, or facts not already verified in this session. Follow this chain in strict order. Never skip steps.
+
+```
+Step 1: Codebase → existing code, conventions, patterns already in use
+Step 2: Project docs (leads, not truth) → README, docs/, inline comments, and, when present, .specs/project/STATE.md (Decisions) — verify against current source before relying
+Step 3: Context7 MCP → resolve library ID, then query for current API/patterns
+Step 4: Web search → official docs, reputable sources, community patterns
+Step 5: Flag as uncertain → "I'm not certain about X — here's my reasoning, but verify"
+```
+
+- If a chain step's tool is unavailable (Context7 MCP not registered, no web
+  access), record it as a skipped sensor with its reason and continue to the next
+  step. An unavailable step is skipped, never silently treated as answered.
+- Never skip to Step 5 if Steps 1-4 are available.
+- Step 5 is always flagged uncertain — never presented as fact.
+- Never assume or fabricate. If no answer is found, say "I don't know" or "I couldn't find documentation for this". Uncertainty is always preferable to fabrication; invented APIs/patterns cause cascading failures across design → tasks → implementation.
+
+Step 2 reads whatever project documentation the target repository actually has; a consumer running without `.specs/` (a Quick-mode refactor, a cold repository) simply has fewer Step 2 sources, not a skipped step.
+
+## Family Instantiations
+
+- **Requirements family:** the audit report's cited Requirement Source may be treated as Step 0 — the authoritative anchor the rest of the chain verifies implementation facts against. Step 0 answers *what was required*; Steps 1-5 still govern *how the code behaves*.
+- **Maestro:** `references/maestro/fact-ledger.md`'s Authority Order is the Maestro instantiation of this chain (official-doc → live-help → repo-convention → excluded/unverified). Do not layer the generic chain on top of it.

package/skills/massa-ai/references/maestro/cloud.md

@@ -65,3 +65,5 @@ Official Cloud limit: 15-minute soft execution limit per test execution. After t
 ## Cloud Boundary
 
 Use Cloud for hosted device execution, device matrix coverage, PR checks, and Cloud-only platform settings. Keep local CLI checks, static YAML checks, and repository validation as separate evidence.
+
+Authorization boundary: Cloud execution, binary upload, and `maestro test --analyze` are externally-visible operations — each needs its own explicit go-ahead, separate from the Execute authorization. Local `maestro test` against a local device/emulator stays inside the Execute authorization.

package/skills/massa-ai/references/maestro/fact-ledger.md

@@ -11,6 +11,8 @@ Use before making Maestro claims. Defines source authority, fact tags, local tra
 
 If sources conflict, prefer `official-doc` for product behavior and `live-help` for installed CLI syntax. Mention version drift when `live-help` differs from docs.
 
+This Authority Order is the Maestro instantiation of `references/knowledge-verification-chain.md` — `live-help` supersedes generic lookup for installed CLI facts; do not layer the generic chain on top of it.
+
 ## Fact Tag Rules
 
 Every normative statement in Maestro workflows, reports, or implementation notes must carry a source class in the agent's working notes:

package/skills/massa-ai/references/maestro/patterns.md

@@ -71,10 +71,16 @@ If cleanup cannot be guaranteed, isolate test data and record residual risk.
 - changed files
 - command/artifact evidence
 - skipped reason or `none`
-- JUnit/artifact paths
+- JUnit/artifact paths — cite the **on-disk** JUnit report path and artifact directory the run actually produced, never a remembered or expected path
 - validation assets protected
 - residual risk
 
+## Discrimination Sensor (Flow Mutation)
+
+The Maestro instantiation of `references/discrimination-sensor.md`: mutate a **scratch copy** of the flow under the claim being verified — perturb a selector (point it at a wrong element) or an assertion (invert or change its expected value) — and confirm the run fails. A run that still passes with a perturbed selector/assertion is not discriminating for that behavior.
+
+Deviation from the generic tier table, stated on purpose: device-backed runs are expensive, so the sensor is a **single lightweight mutation only** — the ≥5-mutation P0 tier does not apply to Maestro flows. Record killed/survived and restore the scratch per the shared reference's isolation rules.
+
 ## Routing Boundaries
 
 - Product bugs, missing test IDs, app architecture changes, backend data setup changes, or unclear requirements route to parent workflows.

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

@@ -9,6 +9,7 @@ Use after `repository-detection.md` identifies one or more target surfaces. Defi
 - Figma MCP is mandatory design evidence. A screenshot or pasted description alone is not a design contract.
 - Figma defines visible design intent and represented variants. Product behavior, navigation, data, analytics, error handling, and state transitions require a separate requirements source.
 - Accessibility, platform conventions, localization, safe areas/insets, minimum touch targets, Dynamic Type/font scale, and explicit product requirements outrank literal replication when supported by evidence. Record these as `CONSTRAINT DEVIATION`.
+- Figma defines the target **value**; it never defines the platform-API **technique**. The `references/knowledge-verification-chain.md` chain answers "how do I express this on the platform"; a fresh Figma node re-read answers "what value must render". Never let a platform-API lookup redefine the design contract.
 
 ## Figma Evidence Packet
 
@@ -96,6 +97,18 @@ Evidence classes:
 - `inferential-visual`: labeled visual comparison without deterministic measurement.
 - `missing`: required evidence is unavailable or unsafe to obtain.
 
+### Discrimination Sensor for Visual Parity (what a mutation is)
+
+The mobile-Figma instantiation of `references/discrimination-sensor.md` — mutations run only where a deterministic runtime sensor exists to kill them:
+
+| Evidence class of the row | Mutation | Expectation |
+|---|---|---|
+| `deterministic-runtime` | Perturb the implementation's token/value in a scratch copy (wrong color token, ±2dp spacing, wrong font scale) | The runtime sensor (snapshot/screenshot/render test) FAILS — mutant killed |
+| `deterministic-source` only | No runtime kill-check exists | Record `mutation: not available — no deterministic-runtime sensor for this row` |
+| `inferential-visual` / `missing` | Never mutate | Record `mutation: not available — <evidence class>` |
+
+A surviving token/value mutant means the render sensor does not discriminate for that property — the parity claim for that row is unproven.
+
 Statuses:
 
 - `MATCH`: sufficient evidence supports parity for the row and configuration.

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

@@ -4,14 +4,7 @@ Use before any spec-driven workflow reads or writes feature registry, progress,
 
 ## Source Of Truth
 
-- Canonical state lives in `.specs/` files tracked in the repository, not massa-ai records, semantic memories, or root aliases.
-- Current repository source remains authoritative for implementation/code evidence.
-- `search`, `recall`, and durable memories may discover context, decisions, or reusable patterns, but must never reconstruct canonical artifact state.
-- If `.specs/` is unavailable or not writable, block spec-driven state mutation and record the blocker.
-
-## STATE Precedence Chain
-
-Artifact reads resolve conflicts in this strict order (first match wins): fresh user instruction > approved `.specs/` artifact > STATE/HANDOFF > massa-ai memory. massa-ai memory and external summaries are discovery, not authority. Canonical ownership and full section rules live in `references/spec-driven/memory.md`; this store mirrors the chain so reads and writes stay consistent.
+The canonical-store principle, the STATE Precedence Chain, and the unwritable-→-block rule live in `references/artifact-persistence.md` — they apply to every workflow family, not just spec-driven. This store applies them to spec-driven's logical paths below. Canonical ownership and full section rules live in `references/spec-driven/memory.md`.
 
 ## Logical Paths
 
@@ -31,30 +24,7 @@ Use these logical paths:
 
 ## Quick Artifacts
 
-Quick-mode tasks (Quick mode guardrails in `workflows/spec-driven.md`) live under `.specs/quick/NNN-slug/`. `NNN` is zero-padded and sequential per project; `slug` is the short kebab-case intent. Each quick task has exactly two files:
-
-**`.specs/quick/NNN-slug/TASK.md`:**
-
-```markdown
-# Quick NNN: <one-line intent>
-
-## Acceptance
-- <single testable criterion — the gate the Execute step must pass>
-```
-
-**`.specs/quick/NNN-slug/SUMMARY.md`:**
-
-```markdown
-# Quick NNN: <one-line intent>
-
-## Result
-- Status: Complete | Blocked | Partial
-- Files changed: <list or "none">
-- Gate: <command + pass/fail evidence>
-- SPEC_DEVIATION: <none | what diverged and why>
-```
-
-Quick tasks are also listed in the STATE.md Quick Tasks table (see `references/spec-driven/memory.md`). When 5+ quick tasks accumulate in one area, promote to a feature: move the work under `.specs/features/<slug>/` and record the promotion in STATE. Quick artifacts are canonical `.specs/` state — same precedence chain, same section-scoped write rules; they are not a second store.
+Quick-mode tasks (Quick mode guardrails in `workflows/spec-driven.md`) live under `.specs/quick/NNN-slug/` with the two-file templates in `references/artifact-persistence.md` (Quick Artifact Templates). Spec-driven specifics on top: quick tasks are also listed in the STATE.md Quick Tasks table (see `references/spec-driven/memory.md`), and when 5+ quick tasks accumulate in one area, promote to a feature — move the work under `.specs/features/<slug>/` and record the promotion in STATE.
 
 ## Reading Artifacts
 

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

@@ -41,7 +41,7 @@ Silently ignoring an active decision is not an option — it creates invisible i
 
 If the feature involves unfamiliar technology, patterns, or integrations, research before designing. Document findings briefly in the design doc or as inline notes. This prevents incorrect assumptions from propagating into tasks.
 
-Follow the **Knowledge Verification Chain** (see SKILL.md) in strict order:
+Follow the **Knowledge Verification Chain** (see `references/knowledge-verification-chain.md`) in strict order:
 
 ```
 Codebase → Project docs (leads, not truth) → Context7 MCP → Web search → Flag as uncertain

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

@@ -17,7 +17,7 @@ Use for the mandatory final Execute validation gate. This is not a separate phas
    - Runs the **spec-anchored outcome check** and the **discrimination sensor** (both described below)
    - Writes `.specs/features/<slug>/validation.md` with the full evidence report
    - Returns a compact verdict + ranked gap list to the orchestrator in chat
-   - Gaps become **fix tasks** routed back to an implementer; re-verification follows with a maximum of **3 fix→re-verify iterations** before escalating to the user
+   - Gaps become **fix tasks** routed back to an implementer; re-verification follows, bounded by the Bounded Fix→Re-verify Loop in `references/verification-ladder.md`
 
 3. **Interactive UAT (for user-facing features only):** The feature has complex user-facing behavior where human judgment matters (UI flows, interaction patterns, visual design). For backend-only, harness-only, or infrastructure work, automated checks are sufficient — record `UAT: not applicable` with reason.
 
@@ -96,35 +96,14 @@ Run the Build-level gate check from the **Gate Check Commands** section in tasks
 
 ### 5. Discrimination Sensor (MANDATORY — always runs after gate check passes)
 
-The sensor provides the empirical guarantee that the tests can actually detect regressions. It runs in a scratch/throwaway state — the real working tree is never modified.
+The sensor provides the empirical guarantee that the tests can actually detect regressions. Run the full mechanics from `references/discrimination-sensor.md` — scratch git-worktree isolation (never `git stash`), porcelain baseline before/after, behavior-level mutation forms, and the lightweight/P0 tier table.
 
-**How it works:**
+Spec-driven specifics on top of that shared mechanic:
 
-1. **Prepare an isolated scratch.** Never mutate the real worktree. Choose one:
-   - Preferred: a temporary git worktree (`git worktree add <scratch-path> HEAD`), mutate and run tests there, then `git worktree remove --force <scratch-path>`.
-   - Fallback (no git / worktree unavailable): copy only the affected file(s) to a temp directory, mutate the copies, point the test runner at those copies (or restore originals from the copies' backups), then delete the temp directory.
-   - **Forbidden:** `git stash` / `git stash pop`. A stash records state *before* the mutation; popping it does not reverse a mutation applied afterward, and on a clean tree `git stash` creates no entry at all — so the fault is left in the real worktree.
-2. **Capture a baseline.** Record `git status --porcelain` (or equivalent) of the real worktree *before* any sensor work. It must be unchanged after cleanup.
-3. **Inject a behavior-level fault** into the scratch copy of the new code introduced by this feature. Choose a mutation proportional to the code's risk:
-   - Flip a boolean condition (`if (x)` → `if (!x)`, `>` → `>=`)
-   - Change a return value (return a wrong status code, wrong field, zero instead of a computed value)
-   - Off-by-one (shift a loop bound, change a slice index)
-   - Remove a required side effect (delete a method call that the spec requires)
-4. **Run the tests** that cover the mutated code (against the scratch). Use the Quick or Full gate command from tasks.md.
-5. **Confirm the mutant is killed** (tests FAIL). Discard the scratch (remove worktree or delete temp copies).
-6. **Verify isolation.** Re-run `git status --porcelain` on the real worktree and confirm it matches the baseline from step 2. If it differs, STOP — restore the real tree before continuing, and treat the sensor run as invalid.
-7. **If a mutant survives** (tests still pass after the fault), the tests are not discriminating for that behavior — add a fix task to strengthen the assertion.
-
-**Tiering (proportional, not optional):**
-
-| Context | Sensor depth |
-| ------- | ------------ |
-| Default (all features) | Lightweight fault-injection: 1–3 targeted behavior-level mutations per feature, focused on the highest-risk new code |
-| P0 / critical paths (payment, auth, data integrity) | Full mutation run: use language-appropriate mutation tooling if available (e.g., Stryker, mutmut, cargo-mutants, pitest); otherwise increase the number of manual fault-injection mutations to ≥5 covering all branches |
-
-**Stack-agnostic:** The sensor targets behavior-level semantics (what the code does), not a specific tool. Any language, any framework.
-
-**Report:** Record killed/survived for each mutation attempt. Surviving mutants → create fix tasks before marking the feature done.
+- The mutation target is the **new code introduced by this feature** (the "code under the claim" for a spec-driven change).
+- Use the Quick or Full gate command from tasks.md as the sensor's test run.
+- **Surviving mutants → create fix tasks** to strengthen the assertion before marking the feature done.
+- Record killed/survived per mutation in the validation report's Discrimination Sensor table below.
 
 If a safe reversible mutant cannot be made, record why and mark `Blocked` unless equivalent existing mutation evidence proves discrimination.
 
@@ -195,7 +174,7 @@ For each issue found during UAT or from the Verifier:
 
 Fix tasks follow the same format as regular tasks and can be executed with the implement phase (see [references/spec-driven/execute.md](execute.md)).
 
-**Guardrail:** Maximum 3 diagnostic iterations per issue. If root cause isn't found after 3 attempts, flag for human investigation. The same 3-iteration bound applies to the Verifier's fix→re-verify cycle: if gaps persist after 3 rounds, escalate to the user rather than continuing to loop.
+**Guardrail:** Maximum 3 diagnostic iterations per issue. If root cause isn't found after 3 attempts, flag for human investigation. The Verifier's fix→re-verify cycle is separately bounded by the Bounded Fix→Re-verify Loop in `references/verification-ladder.md`.
 
 ### 9. Write Validation Report File + Return Chat Summary (MANDATORY)
 
@@ -239,8 +218,7 @@ Derive the flags from this validation's own evidence: `--result` from the Verdic
 ## Fix Loop
 
 - Return `Needs Fix` findings to Execute as fix tasks.
-- Cap the loop at 3 verification iterations.
-- After 3 unsuccessful iterations, mark `Blocked` with remaining findings and exact next step.
+- Cap: 3 verification iterations, per the Bounded Fix→Re-verify Loop in `references/verification-ladder.md`; at the cap, mark `Blocked` with remaining findings and exact next step.
 
 ---
 

package/skills/massa-ai/references/verification-ladder.md

@@ -46,6 +46,22 @@ Every `*-fix` workflow must execute this gate for each selected finding or coher
 - Reinspect validation assets after changes and record that tests, specs, fixtures, snapshots, benchmarks, public contracts, and generated baselines were not weakened unless the user explicitly requested that validation-asset change.
 - Closure evidence must include command/artifact, result, skipped reason or `none`, highest Verification Ladder level reached, validation assets protected, and residual risk.
 
+### Independent Verification Mandate (author ≠ verifier)
+
+- At **Standard+ or Spec-driven size, or for any high/critical-severity finding**, dispatching `massa-ai-verification-agent` is **mandatory** before closure — the author must not be the sole verifier of their own work. At Quick size, the subagent hop may be skipped, but the check itself is never skipped: run a standalone fresh-eyes re-check (re-read the finding/ACs, changed files, tests, and diff from scratch) against the same output contract.
+- **Exception — `security-fix` dispatches the verifier unconditionally** for every finding closed `fixed`, at every tier.
+- Fallback discipline: when the subagent is unavailable (not registered, spawning forbidden), run the standalone fresh-eyes re-check from scratch and record the skipped-delegation reason in closure evidence.
+- Reviewer + verifier both dispatching at Standard+ is intentional cost, mirroring spec-driven's always-on pair — not accidental duplication.
+
+### Discrimination Sensor
+
+At the same tiers as the mandate above (and unconditionally for security-fix `fixed` closures at Standard+/critical), run the sensor from `references/discrimination-sensor.md` against the code under the claim being verified. A surviving mutant means the verification cannot discriminate: the claim is not proven.
+
+### Bounded Fix→Re-verify Loop
+
+- The fix → re-verify cycle is capped at **3 verification iterations** per finding or feature. After 3 unsuccessful iterations, stop with `Blocked` (fix workflows: closure row `blocked`), preserve the evidence collected, and ask the user for direction.
+- This is a *verification-cycle* counter, independent of two other counters: the *edit-attempt* breaker ("two consecutive failed fixes on one symptom → load `references/root-cause-scripts.md`") fires *inside* a single iteration and neither consumes nor resets it; and `references/implementation-delivery.md` Stage 6's CI-repair cap is a third, post-push loop with its own count.
+
 ## Ladder
 
 Use the cheapest sufficient evidence first: