@massa-ai/cursor-plugin 1.20.0 → 1.21.0

package/.cursor-plugin/plugin.json

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

package/skills/agents/audit-specialist/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 metadata:
   author: S1LV4, luizgmassa
   version: "1.0.0"
-  model_tier: standard
+  model_tier: deep
   permission: read-only
 ---
 

package/skills/agents/context-curator/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 metadata:
   author: S1LV4, luizgmassa
   version: "1.0.0"
-  model_tier: light
+  model_tier: deep
   permission: read-only
 ---
 

package/skills/agents/furps-analyst/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 metadata:
   author: S1LV4, luizgmassa
   version: "1.0.0"
-  model_tier: standard
+  model_tier: deep
   permission: read-only
 ---
 

package/skills/agents/investigator/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 metadata:
   author: S1LV4, luizgmassa
   version: "1.0.0"
-  model_tier: light
+  model_tier: deep
   permission: read-only
 ---
 

package/skills/agents/mobile-specialist/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 metadata:
   author: S1LV4, luizgmassa
   version: "1.0.0"
-  model_tier: standard
+  model_tier: deep
   permission: read-only
 ---
 

package/skills/agents/navigator/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 metadata:
   author: S1LV4, luizgmassa
   version: "1.0.0"
-  model_tier: light
+  model_tier: deep
   permission: read-only
   tools: mcp-index
 ---

package/skills/agents/requirements-analyst/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 metadata:
   author: S1LV4, luizgmassa
   version: "1.0.0"
-  model_tier: standard
+  model_tier: deep
   permission: read-only
 ---
 

package/skills/agents/reviewer/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 metadata:
   author: S1LV4, luizgmassa
   version: "1.0.0"
-  model_tier: standard
+  model_tier: deep
   permission: read-only
 ---
 

package/skills/agents/verification-agent/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 metadata:
   author: S1LV4, luizgmassa
   version: "1.0.0"
-  model_tier: standard
+  model_tier: deep
   permission: read-only
 ---
 

package/skills/massa-ai/SKILL.md

@@ -62,6 +62,16 @@ Before reading any massa-ai file:
   to remove obsolete ones.
 - Emit concise user-facing status updates at meaningful workflow boundaries
   when the Conversation Feedback Policy is active.
+- Verify, don't assume: every factual claim that drives a decision is
+  verified against current codebase/command evidence or confirmed with the
+  user. Documentation of any kind — README, docs/, inline comments, external
+  summaries, even `.specs/` prose — is a lead to verify against current
+  source, never a trustable source of truth by itself. Unverifiable claims
+  become explicit assumptions the user confirms or accepts.
+- Ask when in doubt: when genuine doubt remains after looking it up —
+  requirement meaning, scope boundaries, destructive/irreversible choices,
+  contradictory evidence — ask the user rather than choose silently. Facts
+  are looked up; decisions are asked.
 - Complete Evidence Gate before claiming done.
 
 Use internal references only when needed:

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

@@ -22,7 +22,8 @@ human chose to merge it".
 | 1 | Isolate | `git fetch origin <base> && git worktree add -b <type>/<slug> <path> origin/<base>` | Branch name taken → suffix `-2`. Worktree path taken → reuse it only if its branch matches |
 | 2 | Implement | one task → gate → `git commit` | Gate red → fix before committing. Never commit through a failing gate |
 | 3 | Push | `git push -u origin <type>/<slug>` | Rejected non-fast-forward → `git fetch` + rebase, never force-push a shared branch |
-| 4 | Propose | `gh pr create --base <base> --title <t> --body <b>` | `gh` absent/unauthenticated → degraded path |
+| 3.5 | Deliver specs | `python3 skills/massa-ai/scripts/check_specs_delivered.py <feature> [--root .]` | Non-zero → commit the missing `.specs/` updates (a `docs(specs):`-type commit is normal), push, re-run. Defensive fallback — should not fire when the close-out task already committed `.specs/` before the first push |
+| 4 | Propose — precondition: Stage 3.5 (`check_specs_delivered.py`) green | `gh pr create --base <base> --title <t> --body <b>` | `gh` absent/unauthenticated → degraded path |
 | 5 | Watch | `gh pr checks --watch` | No checks configured → say so; do not claim CI passed |
 | 6 | Repair | fix on the branch, commit, return to stage 5 | Capped at 3 iterations, then stop as `Blocked` |
 | 7 | **Ask** | report the PR URL and the green check list, then **stop** | — |
@@ -69,6 +70,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 3 — push carries the feature's delivery authorization
+
+One explicit delivery authorization per feature, obtained before implementation begins, covers task commits, the branch push, and `gh pr create` for that feature — a single approval, not a push-by-push confirmation. Force-push, deploy, production database changes, merges, and any other remote/externally-visible/destructive operation always require a separate explicit go-ahead, even after that authorization. Workflows that gate Execute behind a batch/delegation offer (e.g. `workflows/spec-driven.md`) obtain this authorization at that same moment.
+
+### Stage 3.5 — deliver specs before PR (defensive fallback)
+
+Between Push and Propose, all feature `.specs/` artifacts (`spec/context/design/tasks/validation` as applicable), `.specs/project/STATE.md`, `.specs/HANDOFF.md`, and `.specs/project/FEATURES.json` must be updated and committed on the branch. **Deterministic backing (run it, do not eyeball it):** `python3 skills/massa-ai/scripts/check_specs_delivered.py <feature> [--root .]` — a non-zero exit blocks Propose. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
+
+**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.
+
 ### 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/spec-driven/coding-principles.md

@@ -78,3 +78,19 @@ Artifact-store evidence: active artifact key, version, and checksum after write
 
 Ask: "Would senior engineer call this overcomplicated?"
 If yes → simplify before proceeding.
+
+---
+
+## Writing Voice (specs, ADRs, reports, commits, summaries)
+
+The artifacts this skill produces should read like a decided engineer wrote them, not like generated boilerplate.
+
+- **Lead with the verdict.** Validation reports and chat summaries open with PASS/FAIL and the one thing that matters, not a warm-up paragraph.
+- **Decisions are definitive.** An ADR or a recorded decision states what you chose: "we will", not "we might" or "we should probably". If it still hedges, it is not a decision yet.
+- **Cut filler and mechanical hedging.** Drop "it is worth noting", "as you can see", "in order to", and reflexive "may/might/could" on claims you are actually sure about. Reserve hedging for genuine uncertainty; using it everywhere signals nothing.
+- **One idea per sentence; short sentences.** Prefer the plain verb over the nominalization ("evaluated", not "performed an evaluation of"). Keep subject-verb-object near the front.
+- **Do not announce the phase.** Produce the artifact; do not narrate "I will now run Specify."
+- **Avoid the em dash as a default connector.** A comma, colon, or two sentences usually read cleaner.
+- **Writing in Portuguese:** keep sentences short; do not carry the long, multi-clause subordinate structure of Portuguese into the artifact. Plain and direct beats formal.
+
+None of this means dumbing down the content — only the prose carrying it.

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

@@ -44,7 +44,7 @@ If the feature involves unfamiliar technology, patterns, or integrations, resear
 Follow the **Knowledge Verification Chain** (see SKILL.md) in strict order:
 
 ```
-Codebase → Project docs → Context7 MCP → Web search → Flag as uncertain
+Codebase → Project docs (leads, not truth) → Context7 MCP → Web search → Flag as uncertain
 ```
 
 When verifying codebase claims, prefer the massa-ai tool chain FIRST — `list_projects`, `search`, `project_map`, `optimized_context` — before falling back to ast-grep / ripgrep / grep. Apply freshness and source-precedence rules: current source code overrides a stale index, and a stale index or durable memory never overrides current evidence. When uncertain about index freshness, read the live file directly.
@@ -110,7 +110,7 @@ When the design replaces an existing decision, never delete the old entry. Appen
 Use this order for technical claims:
 
 1. Current codebase.
-2. Project docs and approved specs.
+2. Project docs and approved specs (leads, not truth) — verify against current source before relying.
 3. Context7 MCP or available local MCP source for current library behavior when relevant.
 4. Official documentation or primary source when current APIs or external services matter.
 5. Mark uncertainty explicitly when evidence is unavailable.

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

@@ -60,22 +60,42 @@ Present the feature boundary (from `spec.md`) and the gray areas to the user. Le
 
 Any gray area the user **declines** to discuss, or that goes undiscussed, is written to the spec's **Assumptions & Open Questions** section (agent's chosen default + rationale) — never silently dropped. This ensures the spec's closure gate can pass: every gray area is either resolved through discussion or recorded as a signed-off assumption.
 
-### 3. Deep-Dive Each Area
+### 3. Choose discussion pace (once)
 
-For each selected area:
+Before deep-diving, ask **one** pace question. Recommend **Guided** as the default. If the user skips, says "whatever", or "you choose", use Guided.
 
-1. Ask 3-4 concrete questions with specific options (not vague categories)
-2. After the questions, check: "More about [area], or move on?"
-3. If more → ask 3-4 more, check again
-4. After all areas → "Ready to create context?"
+| Pace         | When it fits                                      | Cadence                                                                 |
+| ------------ | -------------------------------------------------- | ------------------------------------------------------------------------ |
+| **Quick**    | User wants speed; trusts defaults                 | Propose defaults per area (rationale included); user accepts / overrides |
+| **Guided**   | Default — balances depth and turn count           | Adaptive elicitation (see below)                                        |
+| **Detailed** | High ambiguity; user wants Socratic control       | Exactly one decision per turn, dependency order                         |
 
-**Question design:**
+Honor mid-discussion switches immediately ("go faster", "slow down", "just decide") — change pace without restarting or re-asking settled decisions.
 
-- Options should be concrete ("Card layout" not "Option A")
-- Each answer should inform the next question
-- Include "You decide" as an option when reasonable — captures agent discretion
+### 4. Deep-Dive Each Area
 
-### 4. Scope Guardrail (CRITICAL)
+Shared rules for every pace:
+
+1. Options must be concrete ("Card layout" or "Table layout" — not "Option A" or "how should it look?").
+2. Lead with your recommended answer and one line of reasoning. You have read the codebase; the user should be able to accept or override in a word.
+3. Offer "You decide" when reasonable — it records agent discretion explicitly.
+4. Resolve anything discoverable from the code yourself (Knowledge Verification Chain); only put genuine product decisions to the user.
+5. When an area is settled: "More on [area], or move on?" After all areas: "Ready to create context?"
+
+**Quick:** For each selected gray area, present the recommended decisions for that area in one turn (defaults + short rationale). Wait for accept / override. Do not drip-feed single questions unless the user challenges a default and opens a real fork.
+
+**Guided:** Adaptive elicitation — questions are a decision tree to prune, not a checklist to finish.
+
+1. Classify upcoming decisions as **independent** vs **dependent**.
+2. Low-stakes / safe-to-default → state the assumption and invite correction (no blocking question).
+3. Independent product decisions → ask **at most 2** in the same turn, each with options + recommended default.
+4. Dependent decisions → ask **exactly one**, wait, then continue (the earlier answer should prune later questions).
+5. Never dump 3+ questions in one turn. Never ask what the code already answers.
+6. Stop the area as soon as enough is decided.
+
+**Detailed:** Walk selected gray areas as a strict decision tree — one concrete question per turn, dependency order, wait for each answer before the next. Use when the user wants maximum control or the feature is highly ambiguous.
+
+### 5. Scope Guardrail (CRITICAL)
 
 The feature boundary from `spec.md` is **fixed**. Discussion clarifies HOW to implement, never WHETHER to add new capabilities.
 
@@ -84,7 +104,7 @@ The feature boundary from `spec.md` is **fixed**. Discussion clarifies HOW to im
 
 When user suggests scope creep: "That sounds like a separate feature. I'll note it in Deferred Ideas. Back to [current area]."
 
-### 5. Write `context.md`
+### 6. Write `context.md`
 
 Write `.specs/features/<slug>/context.md` (see template below).
 
@@ -175,6 +195,9 @@ Discuss is done when every gray area is either resolved with the user, recorded
 
 ## Tips
 
+- **Pace is a user choice; Guided is the default** — Quick for speed, Guided for balance, Detailed for Socratic depth; honor mid-discussion switches
+- **Guided ≠ interrogation and ≠ form dump** — Assume-first when safe, ≤2 independent questions per turn, one-at-a-time only when answers depend on each other
+- **Look it up, don't ask** — Resolve anything discoverable from the code yourself; ask only genuine product decisions
 - **Decisions, not vision** — "Card-based layout with subtle shadows" is a decision. "Should feel modern" is not.
 - **Scope is sacred** — Deferred Ideas captures scope creep without losing ideas
 - **User = visionary, Agent = builder** — Ask about how they imagine it, not about technical implementation

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

@@ -11,7 +11,7 @@ Use this reference for the required Execute phase. Implement ONE task at a time:
 - `.specs/features/<slug>/tasks.md` when Tasks was included, otherwise the inline atomic step list from `workflows/spec-driven.md`.
 - Current `.specs/project/STATE.md`.
 - `references/spec-driven/coding-principles.md`.
-- `references/spec-driven/sub-agents.md` when a formal task plan packs into more than one task-budgeted batch (> ~8 tasks), or final validation needs the standalone verifier fallback.
+- `references/spec-driven/sub-agents.md` when a formal task plan has more than 3 tasks (the batch offer trigger — packing still uses ~7-task batches), or final validation needs the standalone verifier fallback.
 
 Artifact-store evidence: active artifact key, version, and checksum after write (see `references/spec-driven/artifact-store.md`).
 
@@ -35,7 +35,7 @@ Do not proceed without stating these explicitly.
 
 ### Before implementing: assess sub-agent delegation (MANDATORY — before the first task)
 
-Before implementing anything, if a formal `.specs/features/<slug>/tasks.md` with an Execution Plan exists, **count its total tasks** and pack the phases into task-budgeted batches (~7 tasks per worker, whole phases — see [sub-agents.md](sub-agents.md)). If that yields **more than one batch** (> ~8 tasks), you MUST present the sub-agent offer to the user and wait for their choice before starting Execute — do not silently proceed inline. If the feature fits a single batch (≤ ~8 tasks, or the user declines), execute inline. Skip this check only when you are already a batch worker executing a delegated batch (the orchestrator already made the delegation decision).
+Before implementing anything, if a formal `.specs/features/<slug>/tasks.md` with an Execution Plan exists, **count its total tasks**. If the feature has **more than 3 tasks**, you MUST present the sub-agent offer to the user and wait for their choice before starting Execute — do not silently proceed inline. Packing itself still uses task-budgeted batches (~7 tasks per worker, whole phases — see [sub-agents.md](sub-agents.md)); a 4–8-task feature packs into a single batch and is still offered as one batch worker. If the feature has 3 or fewer tasks, or the user declines the offer, execute inline. Skip this check only when you are already a batch worker executing a delegated batch (the orchestrator already made the delegation decision).
 
 ### 0. List Atomic Steps (MANDATORY when Tasks phase was skipped)
 
@@ -222,11 +222,16 @@ After the gate check passes:
 
    **On any failure** → rewrite or remove the affected test(s), re-run the gate, then re-run this review.
 
-   *Honest caveat:* This is an inspection-based review (model judgment), complementary to — not a replacement for — the deterministic gate. The gate confirms the test suite runs; the feature-level discrimination sensor (step 10) confirms the tests can detect regressions. This review confirms the suite is meaningful and bounded.
+   *Honest caveat:* This is an inspection-based review (model judgment), complementary to — not a replacement for — the deterministic gate. The gate confirms the test suite runs; the feature-level discrimination sensor (step 9) confirms the tests can detect regressions. This review confirms the suite is meaningful and bounded.
 
    Add the two mapping tables and a one-line adequacy verdict to the Execution Template's Post-Gate section.
 
-### 7. Atomic Git Commit
+### 7. Status + Atomic Commit (same commit)
+
+After the gate is green, close the task record **before** creating the commit, then commit code and status together. Never leave `tasks.md` still open after a successful task commit — a crash between those steps is how resume redoes finished work.
+
+1. Mark the task complete in `.specs/features/<slug>/tasks.md`. Update requirement traceability in `spec.md` if requirement IDs are used. Update logical feature artifact status and `.specs/project/STATE.md` with evidence and the exact next step.
+2. Create **one** atomic commit that includes the implementation, its tests, and those status/traceability updates.
 
 Each task gets its own commit immediately after verification. Never batch multiple tasks into one commit. Use one atomic commit per task when the environment and user permissions allow commits; otherwise record why the commit was skipped.
 
@@ -293,27 +298,20 @@ for reuse across multiple endpoints.
 
 - One task = one commit.
 - Description references what was DONE, not what was planned.
-- Include only files listed in the task — never sneak in "while I'm here" changes.
+- Include only files listed in the task — plus the `tasks.md` / `spec.md` status updates for this task.
+- Never sneak in "while I'm here" changes.
 - If tests are part of the task, include them in the same commit.
 
-### 8. Scope Guardrail / Scope Control
-
-During implementation, you will notice things that could be improved, refactored, or added. **Do not act on them.** Instead:
-
-- If it's a bug: surface it to the user (or capture it as a separate task).
-- If it's an improvement: add it to the feature's `.specs/features/<slug>/context.md` under "Deferred Ideas" (or surface it to the user if there is no `context.md`).
-- If it's related to the current task: only include it if it is in the "Done when" criteria.
-
-**The heuristic:** "Is this in my task definition?" If no, don't touch it. "While I'm here" scope creep during implementation is the #1 quality killer.
+**Deterministic backing (run it, do not eyeball it):** `python3 skills/massa-ai/scripts/check_commit.py --message "<your message>"` before committing. A non-zero exit means fix the format first — this makes the format rule enforceable instead of memory-dependent. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
 
-- Do not add requirements during Execute. New behavior goes back to Specify.
-- Do not make unapproved architecture or contract decisions. New decisions go back to Design.
-- Do not expand task scope to opportunistic refactors.
-- Keep changed files limited to the approved scope and validation.
+**Optional git-level guard (git only, no agent dependency).** In a git repo the same check can run on every commit by wiring it as a `commit-msg` hook, so a malformed message is rejected regardless of who or what drives the commit:
 
-### 9. Update Task Status
+```bash
+# from the repo root, one time:
+ln -sf skills/massa-ai/scripts/check_commit.py .git/hooks/commit-msg && chmod +x .git/hooks/commit-msg
+```
 
-Mark the task complete in `.specs/features/<slug>/tasks.md`. Update requirement traceability in `spec.md` if requirement IDs are used. Update logical feature artifact status and `.specs/project/STATE.md` with evidence and the exact next step.
+This is a plain git hook, not tied to any editor or assistant. Skip it if the project manages hooks its own way (for example a pre-commit framework); the manual check above still applies.
 
 **Distill a confirmed lesson** when a task produced a reusable signal (an unexpected failure mode, a confirmed pattern, a corrected assumption):
 
@@ -328,7 +326,24 @@ python3 skills/massa-ai/scripts/lessons.py --root . add \
 python3 skills/massa-ai/scripts/lessons.py --root . list --status confirmed [--scope <relevant>]
 ```
 
-### 10. Feature-Level Validation (after the LAST task — MANDATORY, always runs)
+### 8. Scope Guardrail / Scope Control
+
+During implementation, you will notice things that could be improved, refactored, or added. **Do not act on them.** Instead:
+
+- If it's a bug: surface it to the user (or capture it as a separate task).
+- If it's an improvement: add it to the feature's `.specs/features/<slug>/context.md` under "Deferred Ideas" (or surface it to the user if there is no `context.md`).
+- If it's related to the current task: only include it if it is in the "Done when" criteria.
+
+**The heuristic:** "Is this in my task definition?" If no, don't touch it. "While I'm here" scope creep during implementation is the #1 quality killer.
+
+- Do not add requirements during Execute. New behavior goes back to Specify.
+- Do not make unapproved architecture or contract decisions. New decisions go back to Design.
+- Do not expand task scope to opportunistic refactors.
+- Keep changed files limited to the approved scope and validation.
+
+**Blast radius (approval ≠ remote authority):** Approving Execute for this feature authorizes local implementation and local commits, and covers one delivery through PR creation — branch push and `gh pr create` — under one explicit go-ahead given at Execute start. Force-push, deploy, production database changes, merges, and any other remote/externally-visible/destructive operation always require a separate explicit go-ahead, even after that authorization.
+
+### 9. Feature-Level Validation (after the LAST task — MANDATORY, always runs)
 
 When the task you just completed is the **last task of the feature** (or of a priority group being delivered on its own, e.g. all P1 tasks), you MUST run feature-level validation before reporting the work as done. **This is not optional and is never prompted — it runs automatically.** Do not stop at the final task's commit.
 
@@ -336,7 +351,7 @@ When the task you just completed is the **last task of the feature** (or of a pr
 
 **Layering:**
 - Per-task adequacy self-check (steps 5–6): cheap, always runs, author does it, confirms each task in isolation.
-- Feature-level validation (step 10): one trustworthy independent gate at completion, always-on, Verifier sub-agent does it.
+- Feature-level validation (step 9): one trustworthy independent gate at completion, always-on, Verifier sub-agent does it.
 
 **How to delegate to the Verifier:**
 Dispatch a fresh sub-agent following the **Verifier** role described in [sub-agents.md](sub-agents.md). Provide it with:
@@ -437,7 +452,7 @@ Then run `references/spec-driven/validate.md` as the final Execute gate. The ver
 **Status**: ✅ Complete | ❌ Blocked | ⚠️ Partial
 ```
 
-**After the LAST task:** dispatch the Verifier sub-agent (see step 10 and [sub-agents.md](sub-agents.md)) for independent feature-level validation, including the spec-anchored check and discrimination sensor. Validation always runs automatically — never prompted. Execute is not done until the Verifier reports PASS and the validation report is written.
+**After the LAST task:** dispatch the Verifier sub-agent (see step 9 and [sub-agents.md](sub-agents.md)) for independent feature-level validation, including the spec-anchored check and discrimination sensor. Validation always runs automatically — never prompted. Execute is not done until the Verifier reports PASS and the validation report is written, confirmed deterministically by `python3 skills/massa-ai/scripts/validate_state.py <feature> [--root .]` (exit non-zero = not done); see [validate.md](validate.md). If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
 
 ---
 
@@ -447,11 +462,13 @@ Then run `references/spec-driven/validate.md` as the final Execute gate. The ver
 - **Tools matter** — Wrong MCP = wrong approach; ask the MCP and skill question when tool choice changes correctness or verification.
 - **Reuses save tokens** — Copy patterns, don't reinvent; reach for massa-ai tooling first to locate existing reuse.
 - **Check before commit** — Verify all criteria, then commit.
+- **Status then commit, same commit** — Mark `tasks.md` complete before the atomic commit and include that update in it; a crash between the two steps is how resume redoes finished work.
 - **Stay surgical** — Touch only what's necessary.
 - **Commit per task** — Clean git history enables bisect and rollback.
 - **Never "while I'm here"** — Scope creep during implementation is the #1 quality killer.
+- **Approval is local** — Push, deploy, and other remote/destructive ops need an explicit go-ahead beyond Execute's initial delivery authorization.
 - **Learn from mistakes** — If something goes wrong, distill a confirmed lesson and surface it so it informs the next task.
-- **Don't stop at the last commit** — Feature-level validation (step 10) is the final step of Execute, not optional.
+- **Don't stop at the last commit** — Feature-level validation (step 9) is the final step of Execute, not optional.
 
 ---
 

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

@@ -191,8 +191,18 @@ Both are silent data loss. The section-scoped write rule is the single correctne
 
 1. Read `.specs/project/STATE.md` and `.specs/HANDOFF.md` — both.
 2. Re-confirm active decisions from `## Decisions` — nothing superseded since last session?
-3. Read `.specs/HANDOFF.md` — identify feature, phase/task, next step, blockers, uncommitted files, branch.
-4. Propose the next step to the user before writing any code.
+3. Read `.specs/HANDOFF.md` — treat it as a **hypothesis** for feature, phase/task, next step, blockers, uncommitted files, branch — not as ground truth by itself.
+4. **Reconcile with git before editing anything:**
+   - Current branch vs Handoff `Branch`
+   - `git status --porcelain` (uncommitted / unexpected paths)
+   - Recent commits on the branch (messages and touched files)
+   - `tasks.md` completion marks and, when present, gate evidence / commit references
+5. **Resolve conflicts with evidence, not narrative:**
+   - A task with a green gate and an atomic commit already on the branch → do **not** redo it; mark it complete in `tasks.md` if the file still shows it open, then continue from the next incomplete task
+   - Partial unverified work in the working tree → preserve it, re-run the relevant gate, then finish the status+commit cycle
+   - Stale or missing Handoff → rebuild next-step from git + `tasks.md`, then propose that to the user
+   - Unexplained local changes you cannot map to the current task → STOP and ask; do not discard them
+6. Propose the reconciled next step to the user before writing any code.
 
 ---
 

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

@@ -82,6 +82,8 @@ If needed:
 - "What are the constraints (time, tech, resources)?"
 - "What is explicitly out of scope?"
 
+**Facts you look up; decisions you ask.** Anything discoverable by reading the environment (the codebase, config, docs, existing conventions) you resolve yourself through the Knowledge Verification Chain — do not spend the user's attention asking for it. Reserve questions for genuine decisions that are the user's to make: scope, priorities, product behavior, trade-offs. A question you could have answered by reading the code erodes trust and wastes a turn.
+
 **Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how? Make the abstract concrete: "Walk me through using this." "What does that actually look like?"
 
 **Know when to stop — then run the dimensions sweep.** When you understand what they're building, why, who it's for, and what done looks like, run a closing **implicit-requirement dimensions sweep** before offering to proceed:
@@ -98,11 +100,22 @@ The `N/A because...` escape is mandatory — it prevents inventing requirements
 
 Each story MUST be **independently testable** — you can implement and demo just that story.
 
-### 3. Write Acceptance Criteria
+### 3. Write Acceptance Criteria (EARS notation)
+
+Write every acceptance criterion in **EARS** (Easy Approach to Requirements Syntax). Each criterion resolves to exactly one pattern, which keeps it unambiguous and directly testable. Choose the pattern that fits the requirement instead of forcing everything into a single shape:
+
+| Pattern | Keyword | Template | Use for |
+| ------- | ------- | -------- | ------- |
+| Ubiquitous | (none) | The [system] SHALL [response] | Always-on invariants and constraints |
+| Event-driven | WHEN | WHEN [trigger] THEN the [system] SHALL [response] | A response to a discrete trigger |
+| State-driven | WHILE | WHILE [state] the [system] SHALL [response] | Behavior that holds during a state |
+| Optional-feature | WHERE | WHERE [feature is present] the [system] SHALL [response] | Behavior gated behind an optional capability or flag |
+| Unwanted-behavior | IF / THEN | IF [undesired condition] THEN the [system] SHALL [response] | Errors, failures, invalid input, timeouts |
+| Complex | combination | WHILE [state], WHEN [trigger] the [system] SHALL [response] | Richer behavior combining the above |
 
-Use **WHEN/THEN/SHALL** format — it's precise and testable:
+**Why patterns beat one shape:** failure states, state transitions, and optional behavior become first-class criteria instead of footnotes squeezed into WHEN/THEN. The patterns map onto the implicit-requirement dimensions above: state-transition integrity to State-driven; failure and external-dependency failure to Unwanted-behavior; feature flags to Optional-feature.
 
-- WHEN [event/action] THEN [system] SHALL [response/behavior]
+**Rules:** one requirement per criterion (never bundle two behaviors); use concrete values (a specific status code, a specific message, a bound) rather than "quickly" or "gracefully"; every criterion contains a SHALL and is measurable. `python3 skills/massa-ai/scripts/validate_spec.py` flags any criterion without a SHALL and any that matches no recognized pattern.
 
 ### 4. Requirement Closure Gate (before confirm)
 
@@ -122,6 +135,8 @@ Before Design, Tasks, or Execute — and before presenting the spec for confirma
 
 6. **Continue only when** the Open Questions table is empty or every row has an accepted assumption.
 
+7. **Deterministic backing (run it, do not eyeball it):** `python3 skills/massa-ai/scripts/validate_spec.py <feature> [--root .]` checks that required sections exist, every AC is EARS-shaped (has a SHALL), no Assumptions row has an empty default or rationale, and requirement IDs are well-formed. A non-zero exit means fix before confirming — the script checks structure; the judgment calls (is the interpretation right, is the outcome precise) stay yours. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
+
 Fix inline. This gate is bounded to THIS feature's stated dimensions and actual behavior — never to "anything imaginable." The Out of Scope table and anti-scope-creep rules remain the counterweights: the gate clarifies existing requirements, it never invents new ones.
 
 ---
@@ -187,11 +202,12 @@ Every ambiguity is resolved or recorded here — nothing is left silently unclea
 
 **Why P1**: [Why this is critical for MVP]
 
-**Acceptance Criteria**:
+**Acceptance Criteria** (each line is one EARS pattern):
 
-1. WHEN [user action/event] THEN system SHALL [expected behavior]
-2. WHEN [user action/event] THEN system SHALL [expected behavior]
-3. WHEN [edge case] THEN system SHALL [graceful handling]
+1. WHEN [user action/event] THEN system SHALL [expected behavior]  <!-- event-driven -->
+2. IF [invalid input / failure] THEN system SHALL [graceful handling]  <!-- unwanted-behavior -->
+3. WHILE [state holds] system SHALL [behavior during that state]  <!-- state-driven -->
+4. The system SHALL [always-on invariant]  <!-- ubiquitous -->
 
 **Independent Test**: [How to verify this story works alone - e.g., "Can demo by doing X and seeing Y"]
 
@@ -226,9 +242,11 @@ Every ambiguity is resolved or recorded here — nothing is left silently unclea
 
 ## Edge Cases
 
+Edge cases are usually unwanted-behavior (IF/THEN) or boundary (WHEN) criteria:
+
+- IF [error scenario] THEN system SHALL [graceful handling]
+- IF [unexpected input] THEN system SHALL [validation response]
 - WHEN [boundary condition] THEN system SHALL [behavior]
-- WHEN [error scenario] THEN system SHALL [graceful handling]
-- WHEN [unexpected input] THEN system SHALL [validation response]
 
 ---
 
@@ -263,18 +281,18 @@ How we know the feature is successful:
 ## Tips
 
 - **P1 = Vertical Slice** — A complete, demo-able feature, not just backend or frontend
-- **WHEN/THEN is code** — If you can't write it as a test, rewrite it
+- **EARS is code** — If you can't write a criterion as a test, rewrite it; pick the pattern (WHEN / WHILE / WHERE / IF / ubiquitous) that fits
 - **Requirement IDs are mandatory** — Every story maps to trackable IDs
 - **Edge cases matter** — What breaks? What's empty? What's huge?
 - **Out of Scope prevents creep** — If it's not here, it doesn't get built
 - **Closure gate before confirm** — Three checks: unambiguity + precision, open-questions/assumptions closure, declined gray areas logged; scope-tiered; bounded to stated dimensions; never invents requirements
-- **Confirm after the gate passes** — Present the spec for user confirmation only after the closure gate passes (no unresolved-and-unmarked items remain); user approves spec before moving to the discuss phase
+- **Confirm after the gate passes** — Present the spec for user confirmation only after the closure gate passes (no unresolved-and-unmarked items remain) and `validate_spec.py` exits clean; user approves spec before moving to the discuss phase
 
 ---
 
 ## Done
 
-Specify is done when every requirement has an ID, acceptance criteria are testable, edge cases are named, out-of-scope boundaries are explicit, implicit-requirement dimensions are resolved or marked `N/A because <reason>`, and the Requirement Closure Gate is satisfied.
+Specify is done when every requirement has an ID, acceptance criteria are testable EARS statements, edge cases are named, out-of-scope boundaries are explicit, implicit-requirement dimensions are resolved or marked `N/A because <reason>`, the Requirement Closure Gate is satisfied, and `validate_spec.py` exits clean (or the no-code-execution-tool fallback was applied).
 
 ## Massa-ai Integration
 

package/skills/massa-ai/references/spec-driven/sub-agents.md

@@ -1,6 +1,6 @@
 # Sub-Agent Delegation
 
-Use this reference during Execute when formal task planning packs into more than one task-budgeted batch (> ~8 tasks), when the user explicitly asks for delegation, or when final validation needs an independent verifier. Full mechanics for phase-batch workers and the Verifier sub-agent used during Execute.
+Use this reference during Execute when formal task planning has more than 3 tasks, when the user explicitly asks for delegation, or when final validation needs an independent verifier. Full mechanics for phase-batch workers and the Verifier sub-agent used during Execute.
 
 ## Phase-Batch Workers
 
@@ -11,15 +11,15 @@ Use this reference during Execute when formal task planning packs into more than
 
 Conflating the two (one worker per phase) is what fragments execution: a feature's dependency-layer count has nothing to do with the ideal per-worker workload. Batching by task budget separates the two concerns without breaking phases.
 
-**Trigger:** Count total tasks across all phases. If the feature packs into **more than one batch** (> ~8 tasks), offer the user phase-batch sub-agents before starting Execute. If it fits a single batch (≤ ~8 tasks), execute inline in the main window — no sub-agents spawned.
+**Trigger:** Count total tasks across all phases. If the feature has **more than 3 tasks**, offer the user phase-batch sub-agents before starting Execute — even when packing yields a single batch (a 4–8-task feature is offered as one batch worker). If the feature has 3 or fewer tasks, execute inline in the main window — no sub-agents spawned, no offer made.
 
 **Batching algorithm (task budget ≈ 7 tasks/worker, phase-aligned):**
 
 The benchmarked sweet spot is ~7 tasks of context per worker (~20 tasks → 3 workers). Pack whole phases into that budget:
 
 1. Count total tasks `T`.
-2. If `T ≤ ~8` → inline, no sub-agents.
-3. Otherwise walk phases **in order**, accumulating whole phases into the current batch. When the batch's running task count reaches ~7 **and** phases remain, close the batch and start the next.
+2. If `T ≤ 3` → inline, no sub-agents, no offer.
+3. Otherwise (even for `T` as low as 4) offer sub-agents and walk phases **in order**, accumulating whole phases into the current batch. When the batch's running task count reaches ~7 **and** phases remain, close the batch and start the next.
 4. **Never split a phase** across workers — the cut only ever lands on a phase boundary. This preserves dependency ordering and keeps a phase's tasks + shared context in one worker.
 5. If the final batch is a lone tail (1–2 tasks), fold it into the previous batch.
 
@@ -121,7 +121,7 @@ Delegated work returns through the compact summary contract above. Planning, tas
 **What the Verifier does (full process in `validate.md`):**
 
 1. **Spec-anchored coverage check** — re-derives coverage evidence-or-zero: every AC traced to `file:line` + assertion expression. For each covered criterion, confirms the test's asserted value matches the **spec-defined expected outcome** (not just that an assertion exists). Where the spec does not define a precise outcome, flags a **spec-precision gap** rather than passing silently.
-2. **Discrimination sensor** — injects a small behavior-level fault (flip a condition, change a return value, off-by-one, remove a required side effect) in a **scratch/throwaway state** (git stash or temp copy), runs the relevant tests, confirms they FAIL (kill the mutant), then discards the mutation. Tiered by risk: lightweight (1–3 mutations) for standard features; expanded (≥5 mutations or full mutation tooling) for P0/critical paths. Surviving mutants become fix tasks.
+2. **Discrimination sensor** — injects a small behavior-level fault (flip a condition, change a return value, off-by-one, remove a required side effect) in an **isolated scratch** (temporary `git worktree` or temp file copies — never `git stash`), runs the relevant tests there, confirms they FAIL (kill the mutant), discards the scratch, and verifies the real worktree's `git status --porcelain` matches the pre-sensor baseline. Tiered by risk: lightweight (1–3 mutations) for standard features; expanded (≥5 mutations or full mutation tooling) for P0/critical paths. Surviving mutants become fix tasks.
 3. Applies the **payload/conjunction rule**: checks payload fields are asserted on value/state, not just that the call occurred.
 4. **Writes the persisted report** to `.specs/features/<slug>/validation.md` — PASS/FAIL, per-AC evidence (`file:line` + assertion + spec outcome), sensor result (killed/survived per mutation), gate exit results, diff/commit range.
 5. **Returns a compact verdict in chat** to the orchestrator.
@@ -148,4 +148,31 @@ Delegated work returns through the compact summary contract above. Planning, tas
 
 ## Standalone Fallback
 
-When sub-agents are unavailable (a single agent executing the full feature), use the standalone fresh-eyes fallback: run `references/spec-driven/validate.md` as a standalone pass — clear implementation assumptions, re-read `spec.md` and the diff from scratch, apply evidence-or-zero, run the spec-anchored coverage check and discrimination sensor, write `.specs/features/<slug>/validation.md`, and report the PASS/FAIL verdict before marking the feature done.
+When sub-agents are unavailable (a single agent executing the full feature), use the standalone fresh-eyes fallback: run `references/spec-driven/validate.md` as a standalone pass — clear implementation assumptions, re-read `spec.md` and the diff from scratch, apply evidence-or-zero, run the spec-anchored coverage check and discrimination sensor, and write `.specs/features/<slug>/validation.md`. **Deterministic backing (run it, do not eyeball it):** `python3 skills/massa-ai/scripts/validate_state.py <feature> [--root .]` confirms the report is a real PASS before the feature is marked done. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
+
+---
+
+## Model Tier per Role
+
+**Applies only if the harness can assign a model per sub-agent.** If it cannot, ignore this section and run everything on the default model — the workflow is correct either way. The point is to spend high-reasoning capacity where ambiguity and consequence are high, and a faster tier where the work is mechanical, instead of paying top-tier cost uniformly.
+
+massa-ai resolves the actual model per agent through `metadata.model_tier` (`light` / `standard` / `deep`) in each sub-agent's charter (`skills/agents/<name>/SKILL.md`), combined with the host and the active profile in `skills/model-profiles.json` (see `CLAUDE.md` § Agent-harness surface). This section maps role/work characteristics onto that mechanism — it is not a separate free-floating table.
+
+Judge the tier by the work in front of the role, not by the role's title:
+
+| Role / work | Characteristic | Suggested tier |
+| ----------- | -------------- | -------------- |
+| Design phase | High ambiguity, hard-to-reverse structural decisions | `deep` |
+| Batch worker — core-domain or high-ambiguity phase | Non-obvious logic, tricky edge cases, novel integration | `deep` |
+| Batch worker — mechanical phase | Entities, DTOs, config, wiring, straightforward CRUD against a settled pattern | `light` / `standard` |
+| Verifier | Adversarial reasoning: designs mutations, re-derives coverage, judges outcome precision | `deep` (always — see below) |
+| Specify / Tasks authoring | Structured but judgment-heavy | `standard` / `deep` |
+| Read-only specialist (audit-specialist, context-curator, furps-analyst, investigator, mobile-specialist, navigator, requirements-analyst, reviewer) | No write access — findings, investigation, or review quality is the entire deliverable, with no implementation pass downstream to catch a missed nuance | `deep` (always — see below) |
+
+**Rules of thumb:**
+
+- When unsure, size up, not down. An under-powered worker on ambiguous logic produces gaps the Verifier then has to catch — more expensive than paying for reasoning once.
+- **The Verifier always runs on the deepest tier** — per project rule, `skills/agents/verification-agent/SKILL.md` pins `metadata.model_tier: deep`, structurally, not just as advisory guidance here. A weak Verifier defeats the author ≠ verifier gate.
+- **Read-only specialists always run on the deepest tier** — this generalizes the Verifier rule: every findings-only or investigation-only charter (`permission: read-only`) pins `metadata.model_tier: deep` structurally, because there is no later implementation pass to catch what a weaker read-only pass missed.
+- Set the tier per batch, from that batch's phases. A feature can mix tiers across batches.
+- Outside the Verifier's and read-only specialists' structural pins, this table is advisory metadata only — no gate, commit, or verification step depends on it.