@massa-ai/cursor-plugin 1.20.0 → 1.22.0

package/.cursor-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "massa-ai",
-  "version": "1.20.0",
+  "version": "1.22.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.22.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/evidence-gate.md

@@ -38,7 +38,7 @@ Use this compact shape when closing docs or skill work:
 ✅ [Verified] Skill validation and stale-reference scans passed.
 🏁 [Finished] Updated massa-ai references. Memory outcome: durable decision stored. Remaining risk: none found.
 
-Evidence: `rtk python3 skills/skill-architect/scripts/validate_skill.py skills/massa-ai --format json` passed; stale-reference and local-link scans passed.
+Evidence: `bun run scripts/generate-skill-artifacts.ts --check` passed; stale-reference and local-link scans passed.
 Changed artifacts: `skills/massa-ai/SKILL.md`, `workflows/spec-driven.md`, `references/spec-driven/`, and `references/memory-policy.md`.
 Memory outcome: wrote decision memory `dec_...`; no failed memory writes.
 Residual risk: none found.

package/skills/massa-ai/references/hook-enforcement.md

@@ -44,7 +44,7 @@ Every hook exits 0 on bad stdin or non-critical error. Blocking hooks are
 | Hook | Event | Enforces |
 |---|---|---|
 | `stop_evidence_gate.py` | Stop | `references/evidence-gate.md` |
-| `continuous_learning_evaluate.py` | Stop | `references/lessons.md`, `scripts/lessons.py` |
+| `continuous_learning_evaluate.py` | Stop | `references/lessons.md`, `scripts/lessons.ts` |
 | `precompact_save_state.py` | PreCompact | `workflows/long-session.md`, `references/context-firewall.md` |
 | `suggest_compact.py` | PreToolUse(Edit\|Write) | `references/context-firewall.md` (compaction boundary) |
 | `gateguard_fact_force.py` | PreToolUse(Edit) | `references/context-firewall.md` (investigate-before-edit) |
@@ -100,7 +100,7 @@ absent, it falls back to the flat evidence matrix (graceful degradation).
 
 The continuous-learning loop writes two stores, not one:
 
-- `lessons.py add` / `import` — deterministic grounded file store
+- `lessons.ts add` / `import` — deterministic grounded file store
   (`.specs/lessons.json`); refuses ungrounded lessons; promotion/quarantine.
 - `remember` — durable memory, best-effort via REST (`MASSA_AI_API_URL`),
   file-only fallback when REST is unavailable.

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 | `bun skills/massa-ai/scripts/check_specs_delivered.ts <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.ts`) 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):** `bun skills/massa-ai/scripts/check_specs_delivered.ts <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/lessons.md

@@ -4,9 +4,8 @@ Use this reference when loading confirmed project lessons during startup, or rec
 
 ## Artifacts
 
-- `.specs/lessons.json` — canonical machine-owned lesson state. Read it; do not hand-edit.
-- `.specs/LESSONS.md` — rendered playbook generated by the script. Read it; do not hand-edit.
-- `skills/massa-ai/scripts/lessons.py` — deterministic bookkeeping script.
+- `.specs/lessons.json` — canonical machine-owned lesson state, the single lessons store. Read it; do not hand-edit.
+- `skills/massa-ai/scripts/lessons.ts` — deterministic bookkeeping script; `lessons list` is the on-demand view.
 
 ## Lesson Signal Table
 
@@ -23,7 +22,7 @@ Use this reference when loading confirmed project lessons during startup, or rec
 After a workflow's verification step finds a concrete reusable signal, record it:
 
 ```bash
-python3 skills/massa-ai/scripts/lessons.py --root . add \
+bun skills/massa-ai/scripts/lessons.ts --root . add \
   --feature "<feature-slug>" \
   --signal "<ac_gap|surviving_mutant|spec_precision_gap|spec_deviation|gate_fail>" \
   --source "<validation.md source, AC id, file:line, mutant id, or SPEC_DEVIATION ref>" \
@@ -51,7 +50,7 @@ Run this self-check after verification: if a failed acceptance criterion, surviv
 During startup of any applicable workflow, load confirmed lessons when `.specs/lessons.json` exists:
 
 ```bash
-python3 skills/massa-ai/scripts/lessons.py --root . list --status confirmed [--scope <relevant>]
+bun skills/massa-ai/scripts/lessons.ts --root . list --status confirmed [--scope <relevant>]
 ```
 
 - Use `--scope` or `--query` to keep the loaded set small.
@@ -69,7 +68,7 @@ python3 skills/massa-ai/scripts/lessons.py --root . list --status confirmed [--s
 
 ## No-Script Fallback
 
-If `lessons.py` is unavailable or cannot run, record `Lessons: skipped - script unavailable` in the validation report or evidence gate, keep the raw signal in the report, and do not hand-edit `lessons.json` or `LESSONS.md`. A future run with the script can import the validated signal.
+If `lessons.ts` is unavailable or cannot run, record `Lessons: skipped - script unavailable` in the validation report or evidence gate, keep the raw signal in the report, and do not hand-edit `lessons.json`. A future run with the script can import the validated signal.
 
 ## Continuous-Learning Loop (hook-fed)
 
@@ -82,13 +81,13 @@ The lessons layer is a closed loop, not manual-only. Two runtime hooks
 2. **evaluate** — `continuous_learning_evaluate.py` (Stop) reads the active
    massa-ai context from `.specs/project/STATE.md` and the observations
    buffer. For each observation that already carries grounded fields
-   (`signal`, `text`, `source`, `feature`), it calls `lessons.py add` with the
+   (`signal`, `text`, `source`, `feature`), it calls `lessons.ts add` with the
    `--project`/`--session`/`--workflow`/`--entity` context. Ungrounded
    observations are left in the buffer for agent input and logged as skipped.
 
 ### massa-ai Dual-Write
 
-`lessons.py add` and `import` best-effort write massa-ai memory so the file store
+`lessons.ts add` and `import` best-effort write massa-ai memory so the file store
 and durable memory stay consistent:
 
 - **type** is always `pattern` (lessons are procedural knowledge). `procedural`
@@ -105,8 +104,8 @@ and durable memory stay consistent:
 ### Round-Trip
 
 ```bash
-python3 skills/massa-ai/scripts/lessons.py --root . export --out lessons.export.json
-python3 skills/massa-ai/scripts/lessons.py --root . import --in lessons.export.json
+bun skills/massa-ai/scripts/lessons.ts --root . export --out lessons.export.json
+bun skills/massa-ai/scripts/lessons.ts --root . import --in lessons.export.json
 ```
 
 `export`/`import` round-trip the file store; `import` re-emits massa-ai memory

package/skills/massa-ai/references/mcp-tools.md

@@ -285,7 +285,7 @@ delay. Preferred shell pattern:
 MASSA_AI_API_URL="${MASSA_AI_API_URL:-http://localhost:3333}"
 for i in $(seq 1 40); do
   result=$(rtk curl -s "$MASSA_AI_API_URL/api/v1/project/index/status/JOB_ID")
-  status=$(printf '%s' "$result" | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['status'])")
+  status=$(printf '%s' "$result" | bun -e "console.log(JSON.parse(await Bun.stdin.text()).data.status)")
   printf '[%s] status=%s\n' "$i" "$status"
   [ "$status" = "completed" ] || [ "$status" = "failed" ] && break
   sleep 15

package/skills/massa-ai/references/project-context.md

@@ -23,7 +23,7 @@ continue only when the next decision still needs more.
 | 2 — Host config | `.claude/` (`settings.json`, `settings.local.json`, `commands/`, `agents/`, `skills/`, `hooks/`), `.cursor/` (`rules/`, `mcp.json`), `.github/copilot-instructions.md`, `.opencode/`, `.codex/` | Permissions, hooks, host-specific tooling, MCP registrations |
 | 3 — Product docs | `README.md`, `CONTRIBUTING.md`, `docs/`, `ARCHITECTURE.md` | Install/run/build surface, contribution protocol, architecture |
 | 4 — Delivery config | `.github/workflows/`, `CHANGELOG.md`, `package.json` / `Cargo.toml` / `build.gradle*` / `pyproject.toml`, `.tool-versions`, `mise.toml`, `Makefile` | CI gates, release rules, runtime and toolchain pins, task commands |
-| 5 — Live state | `.specs/project/STATE.md`, `.specs/project/FEATURES.json`, `.specs/HANDOFF.md`, `.specs/LESSONS.md` | In-flight work, decisions already made, confirmed lessons |
+| 5 — Live state | `.specs/project/STATE.md`, `.specs/project/FEATURES.json`, `.specs/HANDOFF.md`, `.specs/lessons.json` (single store; `lessons list` is the on-demand view) | In-flight work, decisions already made, confirmed lessons |
 
 Tier 1 and Tier 3 (`README.md`) are mandatory in every workflow. Tiers 2, 4, and
 5 are read when the task touches host tooling, a gate/release surface, or

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

@@ -27,8 +27,7 @@ Use these logical paths:
 - `.specs/features/<slug>/validation.md` — feature validation report
 - `.specs/quick/NNN-slug/TASK.md` — quick-mode task (one-line intent + acceptance)
 - `.specs/quick/NNN-slug/SUMMARY.md` — quick-mode result (files changed + gate evidence)
-- `.specs/lessons.json` — machine-owned lesson state (managed by `lessons.py`)
-- `.specs/LESSONS.md` — rendered lesson playbook (read-only, generated by `lessons.py`)
+- `.specs/lessons.json` — the single lessons store, machine-owned (managed by `lessons.ts`); `lessons list` is the on-demand view
 
 ## Quick Artifacts
 
@@ -61,21 +60,21 @@ Quick tasks are also listed in the STATE.md Quick Tasks table (see `references/s
 
 Load only what you need. Prefer metadata-only inspection before loading full content.
 
-- **Feature registry status:** `cat .specs/project/FEATURES.json | python3 -c "import json,sys; d=json.load(sys.stdin); print('active:', d.get('active_feature')); [print(f['id'], f['status']) for f in d.get('features',[])]"`
+- **Feature registry status:** `bun -e "const d=await Bun.file('.specs/project/FEATURES.json').json(); console.log('active:', d.active_feature); for (const f of d.features??[]) console.log(f.id, f.status);"`
 - **Full feature registry:** `cat .specs/project/FEATURES.json`
 - **Project state:** `cat .specs/project/STATE.md`
 - **Handoff:** `cat .specs/HANDOFF.md`
 - **Feature spec:** `cat .specs/features/<slug>/spec.md`
-- **Confirmed lessons:** `python3 skills/massa-ai/scripts/lessons.py --root . list --status confirmed [--scope <relevant>]`
+- **Confirmed lessons:** `bun skills/massa-ai/scripts/lessons.ts --root . list --status confirmed [--scope <relevant>]`
 
 ## Writing Artifacts
 
-Write artifacts directly to `.specs/` files. Use a here-doc or `printf` for Markdown, or `python3 -c` for JSON mutations.
+Write artifacts directly to `.specs/` files. Use a here-doc or `printf` for Markdown, or `bun -e` for JSON mutations.
 
 - **Update state:** `printf '...' > .specs/project/STATE.md`
 - **Update handoff:** `printf '...' > .specs/HANDOFF.md`
 - **Write feature artifact:** `printf '...' > .specs/features/<slug>/design.md`
-- **Update feature registry:** use `python3 -c` to read-modify-write `FEATURES.json`
+- **Update feature registry:** use `bun -e` to read-modify-write `FEATURES.json`
 
 Feature activate/complete flows update `.specs/project/FEATURES.json`, `.specs/project/STATE.md`, and `.specs/HANDOFF.md` through file writes.
 
@@ -83,7 +82,7 @@ Feature activate/complete flows update `.specs/project/FEATURES.json`, `.specs/p
 
 - Feature artifacts under `.specs/features/<slug>/` are versioned by design (one file per slug).
 - `.specs/project/FEATURES.json` and `.specs/project/STATE.md` are append-only versioned by their git history.
-- `lessons.json` versioning is managed automatically by `lessons.py`.
+- `lessons.json` versioning is managed automatically by `lessons.ts`.
 - When content must be superseded (e.g., a decision), update the existing file and rely on git history for the prior version.
 
 ## Debug Exports
@@ -94,5 +93,5 @@ Exports under `.specs-exports/` are optional, untracked review aids. Use `cp -r
 
 - `.specs/` directory missing or not writable: block spec-driven state mutation; do not fall back to memory or chat.
 - Required artifact missing: create it on first write or block unless it is an approved initial creation.
-- `lessons.py` unavailable: skip lessons loading/recording, record skipped reason in validation report.
+- `lessons.ts` unavailable: skip lessons loading/recording, record skipped reason in validation report.
 .specs/ files

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

@@ -35,7 +35,7 @@ Read `.specs/features/<slug>/spec.md` before designing. If `.specs/features/<slu
 
 Silently ignoring an active decision is not an option — it creates invisible inconsistency across features.
 
-**Also load confirmed lessons** relevant to this feature: `python3 skills/massa-ai/scripts/lessons.py list --status confirmed` (filter with `--scope`/`--query`). These are past verification failures distilled into guidance — apply them while designing. Load only `confirmed`. Skip silently if no store or no code tool. See [lessons.md](lessons.md).
+**Also load confirmed lessons** relevant to this feature: `bun skills/massa-ai/scripts/lessons.ts list --status confirmed` (filter with `--scope`/`--query`). These are past verification failures distilled into guidance — apply them while designing. Load only `confirmed`. Skip silently if no store or no code tool. See [lessons.md](lessons.md).
 
 ### 1.5. Research (Optional but Recommended)
 
@@ -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,9 +298,34 @@ 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.
 
+**Deterministic backing (run it, do not eyeball it):** `bun skills/massa-ai/scripts/check_commit.ts --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).
+
+**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:
+
+```bash
+# from the repo root, one time:
+ln -sf skills/massa-ai/scripts/check_commit.ts .git/hooks/commit-msg && chmod +x .git/hooks/commit-msg
+```
+
+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):
+
+```
+bun skills/massa-ai/scripts/lessons.ts --root . add \
+  --feature <slug> --signal <S> --source <src> --text "<T>" --scope <O>
+```
+
+`--source` is mandatory (grounding gate). Load applicable confirmed lessons before starting a task:
+
+```
+bun skills/massa-ai/scripts/lessons.ts --root . list --status confirmed [--scope <relevant>]
+```
+
 ### 8. Scope Guardrail / Scope Control
 
 During implementation, you will notice things that could be improved, refactored, or added. **Do not act on them.** Instead:
@@ -311,24 +341,9 @@ During implementation, you will notice things that could be improved, refactored
 - Do not expand task scope to opportunistic refactors.
 - Keep changed files limited to the approved scope and validation.
 
-### 9. Update Task Status
-
-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.
-
-**Distill a confirmed lesson** when a task produced a reusable signal (an unexpected failure mode, a confirmed pattern, a corrected assumption):
-
-```
-python3 skills/massa-ai/scripts/lessons.py --root . add \
-  --feature <slug> --signal <S> --source <src> --text "<T>" --scope <O>
-```
-
-`--source` is mandatory (grounding gate). Load applicable confirmed lessons before starting a task:
-
-```
-python3 skills/massa-ai/scripts/lessons.py --root . list --status confirmed [--scope <relevant>]
-```
+**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.
 
-### 10. Feature-Level Validation (after the LAST task — MANDATORY, always runs)
+### 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 `bun skills/massa-ai/scripts/validate_state.ts <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.
 
 ---