@massa-ai/codex-plugin 1.19.0 → 1.21.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "massa-ai",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "description": "massa-ai — semantic code search, memory, and context compression for Codex",
   "author": {
     "name": "Luiz Massa",

package/agents/massa-ai-audit-specialist.toml

@@ -1,7 +1,7 @@
 # massa-ai-owned
 name = "massa-ai-audit-specialist"
 description = "Configurable read-only audit agent. Execute specialized audits through six lenses — bugs, architecture, security, requirements, code-quality, performance — selected via the lens field in the capability packet. Triggers when a workflow needs a findings-only audit. Never modifies implementation."
-model = "gpt-5.6-terra"
+model = "gpt-5.6-sol"
 model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 developer_instructions = """# Audit Specialist Agent Skill

package/agents/massa-ai-context-curator.toml

@@ -1,7 +1,7 @@
 # massa-ai-owned
 name = "massa-ai-context-curator"
 description = "Read-only context preparation agent. Decide which files to open, retrieve memories, use Synapse when appropriate, apply Context Firewall rules, and produce a concise Context Packet consumed by other agents. Triggers when a workflow needs the minimum high-quality context before dispatching a planner, builder, or reviewer. Never implements, reviews, or plans."
-model = "gpt-5.4-mini"
+model = "gpt-5.6-sol"
 model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 developer_instructions = """# Context Curator Agent Skill

package/agents/massa-ai-furps-analyst.toml

@@ -1,7 +1,7 @@
 # massa-ai-owned
 name = "massa-ai-furps-analyst"
 description = "Read-only FURPS+ dimension analyst. Analyze exactly one FURPS+ dimension (F, U, R, P, S, or X) of a PRD or ADR against its checklist section and return structured refinement findings. Triggers when the furps-refinement workflow fans out per-dimension analysis. Never analyzes other dimensions, never writes files, never mutates Atlassian issues."
-model = "gpt-5.6-terra"
+model = "gpt-5.6-sol"
 model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 developer_instructions = """# FURPS-Analyst Agent Skill

package/agents/massa-ai-investigator.toml

@@ -1,7 +1,7 @@
 # massa-ai-owned
 name = "massa-ai-investigator"
 description = "Read-only codebase investigation agent. Locate implementations, trace execution flow, identify dependencies, estimate change impact, and answer engineering questions. Triggers when a workflow needs to understand existing code before planning or implementing. Never modifies code, never generates implementation, never performs reviews."
-model = "gpt-5.4-mini"
+model = "gpt-5.6-sol"
 model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 developer_instructions = """# Investigator Agent Skill

package/agents/massa-ai-mobile-specialist.toml

@@ -1,7 +1,7 @@
 # massa-ai-owned
 name = "massa-ai-mobile-specialist"
 description = "Conditional mobile expertise agent. Provide Android, Kotlin, Compose, KMP, Swift, iOS, Gradle, CocoaPods, performance, lifecycle, and offline-sync guidance. Invoked only when the workflow detects a mobile-related project. Read-only. Triggers on mobile detection signals; refuses non-mobile targets."
-model = "gpt-5.6-terra"
+model = "gpt-5.6-sol"
 model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 developer_instructions = """# Mobile Specialist Agent Skill

package/agents/massa-ai-navigator.toml

@@ -1,7 +1,7 @@
 # massa-ai-owned
 name = "massa-ai-navigator"
 description = "Code exploration specialist that leverages the massa-ai semantic index instead of brute-force file reads. Use when the user asks \"where is X?\", \"how does Y work?\", \"who calls Z?\", or for any question about an indexed codebase. Starts every investigation by consulting the massa-ai index (project map, definitions, references) before falling back to Read/Grep."
-model = "gpt-5.4-mini"
+model = "gpt-5.6-sol"
 model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 developer_instructions = """# Navigator Agent Skill

package/agents/massa-ai-requirements-analyst.toml

@@ -1,7 +1,7 @@
 # massa-ai-owned
 name = "massa-ai-requirements-analyst"
 description = "Read-only requirements analysis agent. Detect ambiguity, missing requirements, contradictions, implicit requirements, and uncovered scenarios before implementation. Triggers during the Specify phase when gray areas, persistence, external calls, auth, payments, concurrency, or state transitions affect behavior. Never implements."
-model = "gpt-5.6-terra"
+model = "gpt-5.6-sol"
 model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 developer_instructions = """# Requirements Analyst Agent Skill

package/agents/massa-ai-reviewer.toml

@@ -1,7 +1,7 @@
 # massa-ai-owned
 name = "massa-ai-reviewer"
 description = "Read-only diff review agent. Analyze diffs to detect bugs, regressions, code smells, missing edge cases, and suggest improvements. Triggers after a builder completes a task and before the verification gate. Never implements, rewrites files, or plans features."
-model = "gpt-5.6-terra"
+model = "gpt-5.6-sol"
 model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 developer_instructions = """# Reviewer Agent Skill

package/agents/massa-ai-verification-agent.toml

@@ -1,7 +1,7 @@
 # massa-ai-owned
 name = "massa-ai-verification-agent"
 description = "Read-only verification agent. Centralize Verification Ladder logic by validating outputs, choosing the verification level, executing the verification checklist, detecting incomplete work, and producing verification reports. Triggers as the mandatory final gate before a task is claimed complete. Never modifies implementation."
-model = "gpt-5.6-terra"
+model = "gpt-5.6-sol"
 model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 developer_instructions = """# Verification Agent Skill

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massa-ai/codex-plugin",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "description": "massa-ai plugin for Codex — 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.
 
 ---