@massa-ai/codex-plugin 1.20.0 → 1.22.0

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.
 
 ---
 

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

@@ -9,7 +9,7 @@ If the feature has ambiguous gray areas (multiple valid approaches for user-faci
 - First user request and any supplied requirement source.
 - Current repository source and docs needed to understand scope.
 - Existing `.specs/features/<slug>/` artifacts when resuming.
-- `.specs/LESSONS.md` only when lessons are enabled by existing lesson artifacts.
+- `.specs/lessons.json` (via `lessons list`) only when lessons are enabled by existing lesson artifacts.
 
 ## Required Sections
 
@@ -65,7 +65,7 @@ The table is canonical; the prose is the applied sweep. **Large/Complex** work m
 
 ### 1. Clarify Requirements
 
-**Load confirmed lessons first:** Before clarifying, load the project's confirmed lessons so past verification failures shape this spec instead of repeating. Run `python3 skills/massa-ai/scripts/lessons.py --root . list --status confirmed` (optionally `--scope [area]` or `--query [term]` for the area this feature touches) and apply what comes back as guidance. Load only `confirmed` — never `candidate` or `quarantined`. If no store exists yet or no code tool is available, skip silently. See [lessons.md](../lessons.md).
+**Load confirmed lessons first:** Before clarifying, load the project's confirmed lessons so past verification failures shape this spec instead of repeating. Run `bun skills/massa-ai/scripts/lessons.ts --root . list --status confirmed` (optionally `--scope [area]` or `--query [term]` for the area this feature touches) and apply what comes back as guidance. Load only `confirmed` — never `candidate` or `quarantined`. If no store exists yet or no code tool is available, skip silently. See [lessons.md](../lessons.md).
 
 **Lightweight context scan first (Knowledge Verification Chain Step 1):** Before asking questions, briefly scan existing code, patterns, and neighboring features relevant to this feature. Prefer massa-ai tooling first (`list_projects`, `search`, `project_map`, `optimized_context`) before `ast-grep`/`rg`/`grep`, honoring freshness and source-precedence (current source overrides stale index/memory). Use what you find to ground your clarifying questions in reality — not to constrain the spec to current implementation. Keep it lightweight (stay within the <40k token budget; reuse the chain, no new machinery). The spec captures WHAT is needed, not only what exists.
 
@@ -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. `bun skills/massa-ai/scripts/validate_spec.ts` 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):** `bun skills/massa-ai/scripts/validate_spec.ts <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.ts` 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.ts` 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):** `bun skills/massa-ai/scripts/validate_state.ts <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.

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

@@ -58,7 +58,7 @@ This step ALWAYS runs — there is no precondition. Decide which of two paths to
 
 Before sampling tests or inferring anything, scan the project for documented quality and testing standards. Stack-agnostic sources to check (illustrative, not exhaustive):
 
-- Agent/AI instructions: `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/**`, `.github/copilot-instructions.md`
+- Agent/AI convention files, if the repo has any: `AGENTS.md` (the vendor-neutral standard) and any tool-specific rules file or rules directory the project happens to use
 - Contributor guides: `CONTRIBUTING.md`, `docs/` (testing, quality, or standards subdocs), README testing section
 - Tool configuration: coverage thresholds in the test runner config (e.g., `jest.config.*`, `vitest.config.*`, `pytest.ini`, `.nycrc`, `Makefile` coverage targets, CI coverage gates)
 
@@ -74,7 +74,7 @@ Before sampling tests or inferring anything, scan the project for documented qua
 **How to infer (path 1 — existing tests):**
 
 1. **Sample test files.** Locate 5–10 existing test files. Map each file's location relative to its source file to identify which code layers are exercised and at what level (unit, integration, e2e). Use these samples for style, location patterns, framework, and test type — and as a **floor** (never produce tests less thorough than existing ones for the same layer). Existing tests are NOT a ceiling on thoroughness; the thoroughness target comes from the spec ACs, listed edge cases, and guidelines (or strong default). The Coverage Expectation column captures the target per layer.
-2. **Discover commands from the repo.** Do NOT invent commands and do NOT assume an ecosystem. Read the project's own build/task manifests, test config, and CI workflows to extract the actual commands — for example: `package.json` / `project.json` (JS/TS), `Makefile`, `pyproject.toml` / `tox.ini` / `pytest` (Python), `Cargo.toml` (Rust), `go test` invocations (Go), `pom.xml` / `build.gradle` (Java/Kotlin), `Gemfile` / `Rakefile` (Ruby), `composer.json` (PHP), `.github/workflows` / `.gitlab-ci.yml`. The list is illustrative; detect what this repo actually uses.
+2. **Discover commands from the repo.** Do NOT invent commands and do NOT assume an ecosystem. Read the project's own build/task manifests, test config, and CI workflows to extract the actual commands — for example: `package.json` / `project.json` (JS/TS), `Makefile`, `pyproject.toml` / `tox.ini` / `pytest` (Python), `Cargo.toml` (Rust), `go test` invocations (Go), `pom.xml` / `build.gradle` (Java/Kotlin), `Gemfile` / `Rakefile` (Ruby), `composer.json` (PHP), `.github/workflows` / `.gitlab-ci.yml`. The list is illustrative; detect what this repo actually uses. Capture the **linter/formatter** command too (e.g. the configured `lint`/`format`/`typecheck` script, or a `.pre-commit-config`, `.golangci.yml`, `ruff`/`eslint`/`biome` config) — the Build gate runs it alongside the tests.
 
 **Output contract — render these two sections verbatim into `tasks.md`** (the exact headings downstream phases reference):
 
@@ -157,6 +157,8 @@ This keeps phase boundaries meaningful while letting the packing hit its target
 
 Before showing tasks to the user, run ALL three pre-approval checks. These are NOT optional — they are gates. If any check fails, restructure the tasks and re-run until all pass.
 
+**Deterministic backing (run it, do not eyeball it):** `bun skills/massa-ai/scripts/validate_tasks.ts <feature> [--root .]` enforces the structural half of these checks so they cannot drift: it flags a `Where` that names multiple files (granularity smell, Check 1), a diagram edge with no matching `Depends on` within a phase and vice-versa (Check 2), a task missing its `Tests` or `Gate` field, a `Tests: none` to confirm against the matrix (Check 3), and any dependency pointing to a later phase. A non-zero exit means restructure before presenting. The script checks structure; the two tables below (the layer-to-test co-location judgment) are still yours. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
+
 **Check 1: Task Granularity** — verify each task is atomic (see Granularity Check section).
 
 **Check 2: Diagram-Definition Cross-Check** — verify the execution diagram matches every task's `Depends on` field (see Diagram-Definition Cross-Check section). Build the cross-check table and include it in the output.
@@ -350,12 +352,12 @@ Execution is strictly sequential — there is no intra-phase parallelism. A sing
 
 **How phase-based execution works:**
 
-At Execute, the agent counts total tasks and packs phases into **task-budgeted batches** (~7 tasks per worker, whole phases — the benchmarked sweet spot is ~20 tasks → ~3 workers). A **phase** is the semantic/dependency unit; a **batch** is one or more *consecutive whole phases* assigned to one worker. The cut only ever lands on a phase boundary — a phase is never split across workers. When packing yields more than one batch (> ~8 tasks), the agent offers to dispatch batch sub-agents. Batches run sequentially: each worker executes ALL its tasks in order, then reports a compact summary before the next batch starts. This right-sizes the worker count by workload instead of by phase count (one-per-phase is too fragmented; expensive and slow). See `references/spec-driven/sub-agents.md` for the full model — packing algorithm, offer-then-confirm, worker payload, compact summary contract, failure handling, and context sizing guidance.
+At Execute, the agent counts total tasks and packs phases into **task-budgeted batches** (~7 tasks per worker, whole phases — the benchmarked sweet spot is ~20 tasks → ~3 workers). A **phase** is the semantic/dependency unit; a **batch** is one or more *consecutive whole phases* assigned to one worker. The cut only ever lands on a phase boundary — a phase is never split across workers. **The sub-agent offer fires whenever the feature has more than 3 tasks** — a 4–8-task feature still packs into a single batch and is offered as one batch worker; only a feature with 3 or fewer tasks executes inline with no offer. Batches run sequentially: each worker executes ALL its tasks in order, then reports a compact summary before the next batch starts. This right-sizes the worker count by workload instead of by phase count (one-per-phase is too fragmented; expensive and slow). See `references/spec-driven/sub-agents.md` for the full model — packing algorithm, offer-then-confirm, worker payload, compact summary contract, failure handling, and context sizing guidance.
 
-When the whole feature fits a single batch (≤ ~8 tasks), execution happens inline in the main window with no sub-agents spawned.
+When the whole feature has 3 or fewer tasks, execution happens inline in the main window with no sub-agents spawned and no offer made.
 
 **The orchestrating agent's role during Execute:**
-1. Count total tasks and pack phases into ~7-task batches — offer batch sub-agents if that yields more than one batch and the user accepts
+1. Count total tasks — if more than 3, pack phases into ~7-task batches and offer batch sub-agents (even a single resulting batch is offered); wait for the user's choice
 2. Dispatch the next batch (to a worker, or execute inline)
 3. Receive the compact batch summary
 4. Update tasks.md with results
@@ -514,4 +516,4 @@ Before sampling tests manually, prefer massa-ai tooling to read the codebase:
 
 ## Done
 
-Tasks is done when every in-scope requirement maps to one or more executable tasks, dependencies are explicit, the Test Coverage Matrix and Gate Check Commands are present, project testing guideline scan and pre-approval checks are recorded, the three mandatory pre-approval tables (Granularity, Diagram-Definition Cross-Check, Test Co-location Validation) pass, and each task has deterministic validation with artifact-store evidence recorded.
+Tasks is done when every in-scope requirement maps to one or more executable tasks, dependencies are explicit, the Test Coverage Matrix and Gate Check Commands are present, project testing guideline scan and pre-approval checks are recorded, the three mandatory pre-approval tables (Granularity, Diagram-Definition Cross-Check, Test Co-location Validation) pass, `validate_tasks.ts` exits clean (or the no-code-execution-tool fallback was applied), and each task has deterministic validation with artifact-store evidence recorded.

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

@@ -27,7 +27,7 @@ Use this reference for the mandatory final Execute validation gate. This is not
 
 Prefer a fresh read-only verifier agent or tool. The author must not verify their own work when independent verification tooling is available. When subagents are unavailable, run the standalone fresh-eyes fallback: re-read `spec.md`, changed files, tests, and diff from scratch before making a verdict.
 
-The verifier is read-only against the real worktree. Discrimination sensor mutations run only in scratch state such as a temporary worktree, stash-protected copy, or temp file copy, and must be reverted or discarded before verdict.
+The verifier is read-only against the real worktree. Discrimination sensor mutations run only in an isolated scratch state — a temporary git worktree (preferred) or temp file copies (fallback), never `git stash` — and must be reverted or discarded before verdict.
 
 ## Inputs
 
@@ -100,18 +100,20 @@ The sensor provides the empirical guarantee that the tests can actually detect r
 
 **How it works:**
 
-1. **Prepare a scratch state.** Use one of (choose the safest available for the environment):
-   - `git stash` the current state, apply a mutation, run tests, then `git stash pop`; OR
-   - A temporary worktree (`git worktree add`); OR
-   - A temp copy of the affected file(s).
-2. **Inject a behavior-level fault** into the new code introduced by this feature. Choose a mutation proportional to the code's risk:
+1. **Prepare an isolated scratch.** Never mutate the real worktree. Choose one:
+   - Preferred: a temporary git worktree (`git worktree add <scratch-path> HEAD`), mutate and run tests there, then `git worktree remove --force <scratch-path>`.
+   - Fallback (no git / worktree unavailable): copy only the affected file(s) to a temp directory, mutate the copies, point the test runner at those copies (or restore originals from the copies' backups), then delete the temp directory.
+   - **Forbidden:** `git stash` / `git stash pop`. A stash records state *before* the mutation; popping it does not reverse a mutation applied afterward, and on a clean tree `git stash` creates no entry at all — so the fault is left in the real worktree.
+2. **Capture a baseline.** Record `git status --porcelain` (or equivalent) of the real worktree *before* any sensor work. It must be unchanged after cleanup.
+3. **Inject a behavior-level fault** into the scratch copy of the new code introduced by this feature. Choose a mutation proportional to the code's risk:
    - Flip a boolean condition (`if (x)` → `if (!x)`, `>` → `>=`)
    - Change a return value (return a wrong status code, wrong field, zero instead of a computed value)
    - Off-by-one (shift a loop bound, change a slice index)
    - Remove a required side effect (delete a method call that the spec requires)
-3. **Run the tests** that cover the mutated code. Use the Quick or Full gate command from tasks.md.
-4. **Confirm the mutant is killed** (tests FAIL). Then discard the mutation (restore the scratch state).
-5. **If a mutant survives** (tests still pass after the fault), the tests are not discriminating for that behavior — add a fix task to strengthen the assertion.
+4. **Run the tests** that cover the mutated code (against the scratch). Use the Quick or Full gate command from tasks.md.
+5. **Confirm the mutant is killed** (tests FAIL). Discard the scratch (remove worktree or delete temp copies).
+6. **Verify isolation.** Re-run `git status --porcelain` on the real worktree and confirm it matches the baseline from step 2. If it differs, STOP — restore the real tree before continuing, and treat the sensor run as invalid.
+7. **If a mutant survives** (tests still pass after the fault), the tests are not discriminating for that behavior — add a fix task to strengthen the assertion.
 
 **Tiering (proportional, not optional):**
 
@@ -202,12 +204,14 @@ After all checks complete, the Verifier MUST:
 1. **Write the persisted report** to `.specs/features/<slug>/validation.md` (see template below). This file is the evidence artifact — it survives the session and can be referenced by CI, reviewers, or future agents. Record in `.specs/project/STATE.md` (Decisions) that validation evidence is available at that path.
 2. **Return a compact summary in chat** to the orchestrator (see Compact Chat Summary section below). The orchestrator surfaces it to the user and routes any ranked gaps to fix tasks.
 
+**Deterministic backing (run it, do not eyeball it):** after writing the report, run `bun skills/massa-ai/scripts/validate_state.ts <feature> [--root .]`. It confirms the report is real — present, verdict filled to PASS, and backed by at least one `file:line` evidence citation — so a missing, hollow, placeholder, or FAIL report cannot slip through as done. A non-zero exit means the feature is NOT done: repair the report or route the FAIL gaps to fix tasks, then re-run. This is the closing gate of Execute and runs automatically, the same way the lessons layer runs at distillation — never a manual step. If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved).
+
 ### 10. Distill Lessons (MANDATORY when validation.md has signal)
 
 This is the closing action of validation — not a separate phase. Immediately after the report is written, turn its grounded failures into reusable, project-local guidance by following [references/lessons.md](../lessons.md) and the stub at [references/spec-driven/lessons.md](lessons.md). In short: for each surviving mutant, spec-precision gap, failed/uncovered AC, or `// SPEC_DEVIATION`, record one terse general lesson via:
 
 ```bash
-python3 skills/massa-ai/scripts/lessons.py --root . add --feature <slug> --signal "<signal>" --source "<source>" --text "<lesson>" --scope "<scope>"
+bun skills/massa-ai/scripts/lessons.ts --root . add --feature <slug> --signal "<signal>" --source "<source>" --text "<lesson>" --scope "<scope>"
 ```
 
 The script enforces grounding (mandatory `--source`) and owns all bookkeeping. A clean PASS with no signal → record nothing. Run the self-check: if there was signal but no lesson was recorded, say so in chat. See [references/lessons.md](../lessons.md) for the exact commands, phrasing rules, scope discipline, and the no-script fallback.
@@ -364,6 +368,7 @@ Update `.specs/features/<slug>/spec.md` requirement statuses and reflect verifie
 ## Summary
 
 **Overall**: ✅ Ready | ⚠️ Issues | ❌ Not Ready
+**Result**: PASS | FAIL
 
 **Spec-anchored check**: [N/N ACs matched spec outcome | M spec-precision gaps]
 **Sensor**: [N/N mutations killed]
@@ -382,7 +387,7 @@ Update `.specs/features/<slug>/spec.md` requirement statuses and reflect verifie
 
 - **Validation is never prompted** — it always runs after the last task; do not ask the user whether to run it
 - **Spec-anchored, not just covered** — "there is an assertion" is not enough; the assertion must target the spec-defined outcome
-- **Sensor in scratch only** — never mutate the real tree; stash/worktree/temp copy, run, discard
+- **Sensor in scratch only** — never mutate the real tree; use a temp worktree or file copies (never `git stash`), run, discard, then confirm porcelain matches the pre-sensor baseline
 - **Surviving mutants are fix tasks** — do not mark the feature done if the sensor found weak tests
 - **P1 first** — MVP must work before P2/P3
 - **WHEN/THEN = Test** — Each criterion is a test case
@@ -393,5 +398,5 @@ Update `.specs/features/<slug>/spec.md` requirement statuses and reflect verifie
 - **Max 3 diagnostic iterations** — Prevents infinite investigation loops
 - **Update traceability** — Every verified requirement updates spec.md status and the FEATURES.json registry
 - **Always write the report file** — `.specs/features/<slug>/validation.md` is the persisted evidence artifact
-- **Distill after writing** — turn grounded failures into lessons via `python3 skills/massa-ai/scripts/lessons.py` ([references/lessons.md](../lessons.md)); clean PASS → no lesson
+- **Distill after writing** — turn grounded failures into lessons via `bun skills/massa-ai/scripts/lessons.ts` ([references/lessons.md](../lessons.md)); clean PASS → no lesson
 - **Independence first** — prefer a fresh read-only verifier; the author never verifies their own work when tooling allows