@massa-ai/cursor-plugin 1.6.0

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

@@ -0,0 +1,214 @@
+# Spec-Driven Memory And State
+
+Use this reference when recording decisions, progress, blockers, handoff, or completion evidence for a spec-driven feature.
+
+This memory layer is split across two artifacts with distinct lifecycles. Each has its own write triggers; writes are always section-scoped — never whole-file overwrites.
+
+- `.specs/project/STATE.md` owns project-level **Decisions** (append-only) plus current objective, progress, blockers, verification evidence, changed files, and exact next step.
+- `.specs/HANDOFF.md` owns the local **Handoff** snapshot (replace-on-pause).
+- `.specs/project/FEATURES.json` owns the feature registry: `active_feature`, status, dependencies, and completion evidence.
+- `.specs/features/<slug>/` owns approved feature artifacts.
+- Use `references/spec-driven/artifact-store.md` for artifact read/write operations.
+
+## STATE Precedence Chain
+
+When sources conflict, resolve in this strict order — first match wins, lower sources never override higher:
+
+1. **Fresh user instruction** — the live user's explicit direction for the current decision.
+2. **Approved `.specs/` artifact** — the current `spec.md`/`design.md`/`tasks.md` approved for the active feature.
+3. **STATE / HANDOFF** — `.specs/project/STATE.md` and `.specs/HANDOFF.md` position and decision logs.
+4. **massa-ai memory** — durable cross-session recall; context until confirmed against current source.
+
+massa-ai memory and external summaries are discovery, not authority. If a higher source is silent, the next source decides; if a lower source contradicts a higher one, the higher source wins and the lower one is corrected. Record the resolution in STATE so the chain stays auditable. `references/spec-driven/artifact-store.md` mirrors this chain for artifact reads.
+
+---
+
+## Artifact State
+
+- `.specs/project/FEATURES.json` owns feature registry, `active_feature`, status, dependencies, and completion evidence.
+- `.specs/project/STATE.md` owns current objective, progress, blockers, verification evidence, changed files, exact next step, and project-level Decisions.
+- `.specs/HANDOFF.md` owns local handoff state.
+- `.specs/features/<slug>/` owns approved feature artifacts.
+- Writes to `.specs/project/STATE.md` are section-scoped: update only the section needed for the current event instead of rewriting unrelated history.
+
+---
+
+## Decision Log
+
+Records **project-level** decisions only: conventions, patterns, constraints, or cross-cutting technology choices that future features must follow or supersede. Record `AD-NNN` entries in `.specs/project/STATE.md` only when they affect future work. Include decision, status, context, alternatives rejected, and evidence.
+
+**Not project-level → stays in the feature's `design.md` Tech Decisions table.**
+Heuristic: would a different feature need to know about this? If yes → project-level. If no → feature-local.
+
+**Format** (one entry per decision):
+
+```markdown
+### AD-001
+- **Decision**: [what was decided — one sentence]
+- **Reason**: [why this option was chosen]
+- **Trade-off**: [what was given up]
+- **Scope**: [which features / packages / layers this governs]
+- **Date**: YYYY-MM-DD
+- **Status**: active | superseded by AD-NNN
+```
+
+Decision status values:
+
+- `active`: current project standard.
+- `superseded by AD-NNN`: replaced by a newer decision.
+
+**Supersession rule:** when a new decision replaces an old one, append a new `AD-NNN` entry and update the old entry's `status` field to `superseded by AD-NNN`. Never delete old entries — the history is the audit trail.
+
+### AD-NNN numbering
+
+- Numbers are sequential, project-scoped, and permanent — never reused.
+- The counter starts at `AD-001`. Check existing entries before assigning the next number.
+- If `.specs/project/STATE.md` does not exist, the first decision is `AD-001`.
+
+---
+
+## Handoff
+
+Captures mid-task / in-flight state so work can resume without re-reading the full task history. This is the sole position tracker; it complements `tasks.md` by recording state that `tasks.md` does not capture.
+
+**File:** `.specs/HANDOFF.md` (replace-on-pause, ~500 tokens).
+
+**Format:**
+
+```markdown
+- **Feature**: [feature name / .specs path]
+- **Phase / Task**: [e.g., Phase 2 / T4 — implement repository layer]
+- **Completed**: [comma-separated task IDs or "none"]
+- **In-progress** (file:line): [e.g., `src/billing/subscription.service.ts:88` — mid-write]
+- **Next step**: [one sentence — exactly what to do next]
+- **Blockers**: [none | description]
+- **Uncommitted files**: [list or "none"]
+- **Branch**: [git branch name]
+```
+
+Before pausing, update `.specs/project/STATE.md` and `.specs/HANDOFF.md` with:
+
+- Current objective.
+- Completed work.
+- Pending work.
+- Blockers and risks.
+- Changed files.
+- Verification evidence.
+- Exact next step.
+
+---
+
+## File shape
+
+`.specs/project/STATE.md`:
+
+```markdown
+# STATE
+
+## Decisions
+
+[AD-NNN entries…]
+
+## Blockers
+
+- B-001: [blocker — what is blocked, why, unblock condition] (added YYYY-MM-DD)
+
+## Deferred Ideas
+
+- [idea / candidate scope] — deferred because [reason]; revisit when [trigger]
+
+## Quick Tasks
+
+| ID | Slug | Files | Status | Summary |
+| --- | --- | --- | --- | --- |
+| 001 | fix-typo-in-readme | 1 | done | README typo; gate green |
+
+## Preferences
+
+- model-guidance-shown: true | false
+```
+
+Plus objective, progress, blockers, verification evidence, changed files, and next step sections per `references/spec-driven/artifact-store.md`.
+
+**Structured section rules:**
+
+- **Blockers** use stable `B-NNN` ids (project-scoped, sequential, permanent — like `AD-NNN`). Each entry names what is blocked, why, and the unblock condition. Clear the entry (mark resolved with date) when the blocker lifts; never delete — the history is the audit trail.
+- **Deferred Ideas** are explicit parking: candidate work deliberately not taken now, with the revisit trigger. They are not blockers and not tasks — they prevent rediscovery loops.
+- **Quick Tasks** table mirrors `.specs/quick/NNN-slug/` entries (see `references/spec-driven/artifact-store.md`). When 5+ quick tasks accumulate in one area, promote to a feature (Quick mode guardrails in `workflows/spec-driven.md`).
+- **Preferences** tracks cross-cutting flags. `model-guidance-shown` records whether the per-session model-tier guidance note has already been delivered, so it is shown at most once per session.
+
+`.specs/HANDOFF.md`:
+
+```markdown
+# HANDOFF
+
+[latest snapshot…]
+```
+
+If either file does not yet exist, create it with its section headers and an empty body.
+
+---
+
+## Read / Write Triggers
+
+| Trigger | Section | Operation |
+| ------- | ------- | --------- |
+| Design phase, Step 1 (Load Context) | `## Decisions` | **Read** — conform to active decisions or supersede |
+| Design phase, Tech Decisions step | `## Decisions` | **Append** — only for project-level decisions |
+| Pause work / end of session | `.specs/HANDOFF.md` | **Replace** — overwrite Handoff snapshot only |
+| Resume work / start of session | `.specs/HANDOFF.md` | **Read** — load snapshot, propose next step |
+| Resume work / start of session | `## Decisions` | **Read** — re-confirm active constraints before designing |
+
+---
+
+## Section-scoped write rule (critical)
+
+Two artifacts hold two distinct lifecycles. Writes MUST target their section only:
+
+- **Design appends** to `## Decisions` in `.specs/project/STATE.md`. It MUST NOT touch `.specs/HANDOFF.md`.
+- **Pause replaces** `.specs/HANDOFF.md`. It MUST NOT rewrite, reorder, or drop any entry in `## Decisions`.
+
+The correct technique: locate the target section header, replace only the content between it and the next `##` header (or end of file). Never overwrite the full file.
+
+Violating this rule causes one of two failures:
+1. A pause write clobbers the decisions log → decisions are silently lost.
+2. A design append touches the handoff snapshot → mid-task state is corrupted.
+
+Both are silent data loss. The section-scoped write rule is the single correctness invariant of this memory layer.
+
+---
+
+## Pause / Resume Procedure
+
+### Pause
+
+1. Locate the `## Handoff` content in `.specs/HANDOFF.md` (and the objective/progress/next-step sections in `.specs/project/STATE.md`).
+2. Replace the Handoff body (everything between the header and the next `##` or EOF) with the current snapshot.
+3. Do NOT modify anything above the Handoff section or touch `## Decisions`.
+4. Commit or stash outstanding changes as appropriate.
+
+### Resume
+
+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.
+
+---
+
+## Durable Memory
+
+Use `remember` for durable cross-session decisions, rejected approaches, reusable verification recipes, repeated lessons, and high-signal gotchas after recall and importance scoring. Do not persist one-off command output, chat summaries, raw transcripts, raw logs, copied source, raw search output, raw subagent output, customer data, secrets, or already-captured facts.
+
+Required massa-ai tags for durable memory:
+
+- `project:<projectId>`
+- `session:<workflowSessionId>`
+- `workflow:spec-driven`
+- `entity:<feature-or-domain>`
+- one of `memory:working`, `memory:episodic`, `memory:semantic`, or `memory:procedural`
+
+Current source and `.specs/` artifacts remain authoritative for implementation evidence; massa-ai durable memory is context until confirmed against current source.
+
+Completion and handoff reports must state the memory outcome:
+written, intentionally skipped with reason, duplicate skipped, forbidden payload skipped, or failed write with recovery note.

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

@@ -0,0 +1,283 @@
+# Spec-Driven Specify
+
+Use this reference for the required Specify phase. **Goal**: Capture WHAT to build with testable, traceable requirements. The output is `.specs/features/<slug>/spec.md`.
+
+If the feature has ambiguous gray areas (multiple valid approaches for user-facing behavior), the agent will automatically trigger the [discuss gray areas](discuss.md) process within this phase. For clear, well-defined features, it goes straight to the next phase.
+
+## Inputs
+
+- 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.
+
+## Required Sections
+
+`spec.md` must include:
+
+- Feature name and slug.
+- Problem statement.
+- Requirements table with stable requirement IDs such as `REQ-001`.
+- Testable acceptance criteria linked to requirement IDs.
+- Edge cases and failure modes.
+- Explicit out-of-scope table.
+- Open questions table.
+- Accepted assumptions table.
+- Verification approach.
+- Discuss context summary when `references/spec-driven/discuss.md` was triggered.
+- Artifact-store evidence: active artifact key, version, and checksum after write.
+
+## Implicit-Requirement Dimensions
+
+The canonical rubric for requirements that are easy to miss. Referenced by [discuss.md](discuss.md) — defined here, not duplicated.
+
+| Dimension | What to cover |
+| --------- | ------------- |
+| Input validation & bounds | Limits, formats, sanitization |
+| Failure / partial-failure states | Timeouts, partial saves, rollbacks |
+| Idempotency / retry / duplicate handling | Safe retries, dedup keys |
+| Auth boundaries & rate limits | Who can call what, throttle rules |
+| Concurrency / ordering | Race conditions, ordering guarantees |
+| Data lifecycle / expiry | TTL, archival, deletion |
+| Observability | Logging, metrics, tracing hooks |
+| External-dependency failure | Circuit breakers, fallbacks |
+| State-transition integrity | Valid transitions, guards |
+
+---
+
+## Implicit-Requirement Sweep
+
+Before requirements close, check the dimensions above (and the prose list below) and either produce a requirement, accepted assumption, explicit out-of-scope row, or `N/A because <reason>` entry:
+
+- Users, actors, permissions, and ownership.
+- Inputs, outputs, payload fields, persisted records, emitted events, and returned objects.
+- State transitions, concurrency, retries, idempotency, cancellation, and partial failure.
+- Data migration, compatibility, privacy, auth, security, auditability, and irreversible behavior.
+- Empty, loading, error, timeout, offline, unavailable dependency, and malformed-input states.
+- Performance, observability, accessibility, localization, and platform-specific behavior when relevant.
+- Testing and validation expectations, including which acceptance criteria require deterministic assertions.
+
+The table is canonical; the prose is the applied sweep. **Large/Complex** work must cover every dimension above. **Medium** work resolves obvious ambiguities and records accepted assumptions for the rest. **Small** work can skip the sweep only when the skip reason is recorded and no dimension changes behavior or acceptance criteria.
+
+---
+
+## Process
+
+### 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).
+
+**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.
+
+You are a thinking partner, not an interviewer. Start open — let the user dump their mental model. Follow the energy: whatever they emphasize, dig into that.
+
+Ask conversationally (not as a checklist):
+
+- "What problem are you solving?"
+- "Who is the user and what's their pain?"
+- "What does success look like?"
+
+If needed:
+
+- "What are the constraints (time, tech, resources)?"
+- "What is explicitly out of scope?"
+
+**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:
+
+- **Large / Complex:** Cover every dimension above — each must resolve to a requirement OR an explicit `N/A because [reason]`. No blank entries allowed.
+- **Medium:** Cover only dimensions obviously present for this feature's domain; collapse the rest to a single `remaining dimensions N/A for this scope`.
+- **Small:** Skip the sweep entirely.
+
+The `N/A because...` escape is mandatory — it prevents inventing requirements to fill the checklist. Bound the sweep to THIS feature's scope; never add requirements outside the feature boundary.
+
+### 2. Capture User Stories with Priorities
+
+**P1 = MVP** (must ship), **P2** (should have), **P3** (nice to have)
+
+Each story MUST be **independently testable** — you can implement and demo just that story.
+
+### 3. Write Acceptance Criteria
+
+Use **WHEN/THEN/SHALL** format — it's precise and testable:
+
+- WHEN [event/action] THEN [system] SHALL [response/behavior]
+
+### 4. Requirement Closure Gate (before confirm)
+
+Before Design, Tasks, or Execute — and before presenting the spec for confirmation — run the checks below. The spec is not presentable for confirmation until every item is resolved or assumption-logged. This is the guarantee that no requirement leaves the spec silently unclear.
+
+**Scope-tiered:** Large/Complex = full gate; Medium = resolve obvious ambiguities, log the rest as assumptions; Small = skip entirely (consistent with skipping the sweep).
+
+1. **List every open requirement question.** Enumerate every unresolved decision that surfaced during clarification.
+
+2. **Resolve each question with the user** when it changes behavior, scope, data, security/privacy, compatibility, or acceptance criteria.
+
+3. **Unambiguity + precision (hard).** Every AC must (a) have a single interpretation and (b) define a precise, spec-defined expected outcome. Any AC that fails either check: resolve with the user, split it, or log it as an explicit assumption with the chosen interpretation and rationale. No AC proceeds readable two ways or with an undefined outcome.
+
+4. **Open-questions / assumptions closure.** Each question must be either (a) resolved with the user OR (b) recorded as an **assumption** (chosen default + rationale) in the spec's Assumptions & Open Questions section. If the user accepts a default, record it as an accepted assumption with the affected requirement IDs. Nothing proceeds unmarked.
+
+5. **Declined gray areas become assumptions.** Any gray area the user declined to discuss or that went undiscussed is written to the spec's Assumptions & Open Questions section (agent's chosen default + rationale) — never silently dropped. Refused, deferred, or intentionally excluded areas go in the out-of-scope table. See [discuss.md](discuss.md).
+
+6. **Continue only when** the Open Questions table is empty or every row has an accepted assumption.
+
+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.
+
+---
+
+## Discuss Trigger
+
+Load `references/spec-driven/discuss.md` during Specify when the request has gray areas that change behavior or acceptance criteria, especially persistence/state, external calls, auth, payments, concurrency, state transitions, compatibility, permissions, user-facing workflows, data loss, implicit requirements, or multiple plausible interpretations. Record the result in `.specs/features/<slug>/context.md` or a compact Discuss section in `spec.md`.
+
+---
+
+## Sizing Signals
+
+After requirements close, decide the remaining phases:
+
+- Include **Design** when architecture, interfaces, data model, migration, security/privacy, public contract, reusable pattern decisions, or Large/Complex approach tradeoffs exist.
+- Include **Tasks** when execution has more than 3 obvious linear steps or dependency/parallelism complexity.
+- Record skipped phase reasons in `spec.md`, and reopen the phase if later evidence invalidates the skip.
+
+---
+
+## Template: `.specs/features/<slug>/spec.md`
+
+```markdown
+# [Feature Name] Specification
+
+## Problem Statement
+
+[Describe the problem in 2-3 sentences. What pain point are we solving? Why now?]
+
+## Goals
+
+- [ ] [Primary goal with measurable outcome]
+- [ ] [Secondary goal with measurable outcome]
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature     | Reason         |
+| ----------- | -------------- |
+| [Feature X] | [Why excluded] |
+| [Feature Y] | [Why excluded] |
+
+---
+
+## Assumptions & Open Questions
+
+Every ambiguity is resolved or recorded here — nothing is left silently unclear.
+
+| Assumption / decision | Chosen default  | Rationale | Confirmed? |
+| --------------------- | --------------- | --------- | ---------- |
+| [ambiguity]           | [what we'll do] | [why]     | [y/n]      |
+
+**Open questions:** none — all resolved or logged above (required before the spec is confirmed).
+
+---
+
+## User Stories
+
+### P1: [Story Title] ⭐ MVP
+
+**User Story**: As a [role], I want [capability] so that [benefit].
+
+**Why P1**: [Why this is critical for MVP]
+
+**Acceptance Criteria**:
+
+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]
+
+**Independent Test**: [How to verify this story works alone - e.g., "Can demo by doing X and seeing Y"]
+
+---
+
+### P2: [Story Title]
+
+**User Story**: As a [role], I want [capability] so that [benefit].
+
+**Why P2**: [Why this isn't MVP but important]
+
+**Acceptance Criteria**:
+
+1. WHEN [event] THEN system SHALL [behavior]
+2. WHEN [event] THEN system SHALL [behavior]
+
+**Independent Test**: [How to verify]
+
+---
+
+### P3: [Story Title]
+
+**User Story**: As a [role], I want [capability] so that [benefit].
+
+**Why P3**: [Why this is nice-to-have]
+
+**Acceptance Criteria**:
+
+1. WHEN [event] THEN system SHALL [behavior]
+
+---
+
+## Edge Cases
+
+- WHEN [boundary condition] THEN system SHALL [behavior]
+- WHEN [error scenario] THEN system SHALL [graceful handling]
+- WHEN [unexpected input] THEN system SHALL [validation response]
+
+---
+
+## Requirement Traceability
+
+Each requirement gets a unique ID for tracking across design, tasks, and validation.
+
+| Requirement ID | Story       | Phase  | Status  |
+| -------------- | ----------- | ------ | ------- |
+| [FEAT]-01      | P1: [Story] | Design | Pending |
+| [FEAT]-02      | P1: [Story] | Design | Pending |
+| [FEAT]-03      | P2: [Story] | -      | Pending |
+
+**ID format:** `[CATEGORY]-[NUMBER]` (e.g., `AUTH-01`, `CART-03`, `NOTIF-02`)
+
+**Status values:** Pending → In Design → In Tasks → Implementing → Verified
+
+**Coverage:** X total, Y mapped to tasks, Z unmapped ⚠️
+
+---
+
+## Success Criteria
+
+How we know the feature is successful:
+
+- [ ] [Measurable outcome - e.g., "User can complete X in < 2 minutes"]
+- [ ] [Measurable outcome - e.g., "Zero errors in Y scenario"]
+```
+
+---
+
+## 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
+- **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
+
+---
+
+## 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.
+
+## Massa-ai Integration
+
+- **Code analysis:** Use massa-ai tools first (`list_projects`, `search`, `project_map`, `optimized_context`) before `ast-grep`/`rg`/`grep` for the lightweight context scan. Current source overrides a stale index or memory (source-precedence rule).
+- **Memory:** Persist verified outcomes worth reusing with `remember`, tagging `project:<id>`, `session:<id>`, `workflow:spec-driven`, `entity:<slug>`, `memory:working|episodic|semantic|procedural`.
+- **Validation:** Evidence-or-zero. Every confirmed lesson applied, requirement resolved, and assumption logged is checked against current source.

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

@@ -0,0 +1,151 @@
+# 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.
+
+## Phase-Batch Workers
+
+**Two layers — keep them distinct:**
+
+- **Phase** = the semantic / dependency unit (Foundation → Core → Integration), authored during Tasks. Indivisible.
+- **Batch** = the execution / logistics unit — one or more *consecutive whole phases* assigned to a single worker.
+
+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.
+
+**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.
+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.
+
+Result ≈ `ceil(T / 7)` workers, scaling linearly. Unevenness is absorbed by greedy packing — phases never need to divide evenly. Worked examples (20 tasks):
+
+- Phases `[3,3,3,3,4,4]` → `{P1+P2=6, P3+P4=6, P5+P6=8}` = **3 workers**
+- Phases `[8,2,2,8]` → `{P1=8, P2+P3=4, P4=8}` = **3 workers** (no even split needed)
+- Phases `[5,5,5,5]` → `{P1+P2=10, P3+P4=10}` = **2 workers** (phases too coarse to hit 3 — see below)
+
+**Coarse-phase caveat:** Because the cut lands only on phase boundaries, very coarse phases limit how finely you can pack. If a single phase alone exceeds ~1.5× the budget (~10+ tasks), that is a Tasks-authoring smell — split it into real sub-phases during Tasks (at a genuine dependency/cohesion boundary), never at dispatch time.
+
+**Offer-then-confirm (never auto-spawn):**
+
+> "This feature has [T] tasks across [N] phases. I can pack them into [K] sub-agents (~7 tasks each, whole phases per worker) — every worker runs its phases in order, reports a compact summary, and the orchestrator advances to the next batch. This keeps the main window lean without over-fragmenting. Want to proceed that way?"
+
+The user must explicitly accept. If they decline (or if the feature fits one batch), execute inline.
+
+**Execution model — one worker per task-budgeted batch, sequential:**
+
+```
+Phases 1+2 (7 tasks)  ──→ Batch Worker 1 ──→ compact summary ──→ orchestrator updates tasks.md
+Phases 3+4 (6 tasks)  ──→ Batch Worker 2 ──→ compact summary ──→ orchestrator updates tasks.md
+Phase 5    (7 tasks)  ──→ Batch Worker 3 ──→ compact summary ──→ orchestrator updates tasks.md
+...
+```
+
+Batches run strictly sequentially: a batch never starts until the previous batch's summary shows all its tasks complete.
+
+**What a batch worker receives:**
+
+- The task definitions for **every** phase in its batch (from `.specs/features/<slug>/tasks.md`)
+- The Test Coverage Matrix and Gate Check Commands (from `.specs/features/<slug>/tasks.md`)
+- `references/spec-driven/coding-principles.md`
+- Relevant `spec.md`, `context.md`, and `design.md` sections for the feature (not all specs)
+
+**What a batch worker does:**
+
+Executes ALL tasks in its assigned batch **in order** — finishing every task in one phase before starting the next phase in the batch — following the `references/spec-driven/execute.md` cycle for each task (implement → gate → atomic commit). It does NOT spawn further sub-agents. After completing all tasks in the batch, the worker reports a **compact summary** to the orchestrator using the structured return contract:
+
+```
+Batch (phases [N]–[M]) return:
+- Status: Complete | Blocked | Partial
+- Tasks done: [list with commit hashes]
+- Tests: [N passed, 0 failed]
+- SPEC_DEVIATION: [none | <task-id>: <what diverged from spec/tasks.md and why>]
+```
+
+**Return contract fields:**
+
+- **Status** — `Complete` (all batch tasks done, gate green), `Blocked` (a task could not proceed; worker stopped), or `Partial` (some tasks done, remaining tasks deferred with reason). The orchestrator advances only on `Complete`.
+- **SPEC_DEVIATION** — any divergence from the approved `spec.md`/`tasks.md`: a skipped test, a changed interface, an added dependency, an out-of-scope edit. `none` is the only silent value; every real deviation is named with its task id and reason so the orchestrator can decide accept/fix/escalate before the next batch.
+
+No raw logs, no full test output — only the above fields keep the main context clean.
+
+**No nesting:** Batch workers execute their tasks themselves. They never spawn sub-sub-agents. Execution is strictly sequential within and across batches — there is no intra-phase or intra-batch parallelism.
+
+## Delegation Activity Table
+
+The batching trigger above governs **when** batch workers are offered. This table governs **what** may be delegated at all. Delegation is activity-scoped, not blanket.
+
+| Activity | Delegate? | Notes |
+| --- | --- | --- |
+| Research / codebase investigation | Yes | Read-only gatherer; returns compact findings, never decisions |
+| Implementation of an approved task | Yes (batch worker) | Task + gate already defined in `tasks.md`; worker executes the defined cycle |
+| Planning (Specify / Design / Tasks authoring) | **Do not delegate** | Planning owns the contract; delegation fragments accountability |
+| Task creation / task-list authoring | **Do not delegate** | The orchestrator owns `tasks.md` integrity and ordering |
+| Validation (Verifier role) | **Do not delegate to a batch worker** | Use the dedicated Verifier sub-agent; author ≠ verifier is the gate's trust basis |
+
+Delegated work returns through the compact summary contract above. Planning, task-creation, and validation never enter that return path — they stay with the orchestrator or the dedicated Verifier.
+
+**The orchestrating agent's role during Execute:**
+
+1. Count total tasks and pack phases into task-budgeted batches (~7 tasks each) — if that yields more than one batch, offer batch sub-agents and wait for the user to accept
+2. Dispatch the next batch to a worker (or execute inline if not using sub-agents)
+3. Receive the compact summary
+4. Update `.specs/features/<slug>/tasks.md` with results
+5. If all tasks in the summary show complete: dispatch the next batch
+6. If a task failed: the worker has already stopped; decide fix/escalate before dispatching the next batch
+
+**Failure handling:** If a task in a batch fails (gate does not pass, blocker hit), the worker stops and includes the failure in its summary. The next batch does not start until the current batch's summary shows all tasks complete. The orchestrator decides: fix and re-run, or escalate to the user.
+
+**Context sizing signal:** If a batch's task list would likely push the worker's context beyond ~40k tokens, close the batch at an earlier phase boundary (fewer phases per worker). If a *single* phase alone would blow the budget, that phase is too coarse — split it during Tasks per the granularity guidance in `references/spec-driven/tasks.md`.
+
+---
+
+## Verifier Sub-Agent
+
+**Always-on, never prompted — one per feature completion.** The Verifier is a separate role from the batch worker. It runs once — after the last task of the feature is committed — as an independent quality gate, dispatched automatically by the orchestrator. It is **not** gated behind the batching offer; it always runs. Do NOT ask the user whether to run validation; it is mandatory.
+
+**Author ≠ verifier:** The agent (or batch worker) that wrote the code and tests is the author. The Verifier is a fresh sub-agent dispatched by the orchestrator after the final commit. It does not inherit the author's context, mental model, or assumptions. This separation is what makes the gate trustworthy.
+
+**What the Verifier receives:**
+
+- `spec.md` for the feature (ACs = source of truth)
+- The git diff surface for the feature (scoped to the feature branch or commit range)
+- The test files in scope
+- `references/spec-driven/validate.md` as its operating checklist
+
+**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.
+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.
+6. Does **NOT** write, modify, or fix any code or tests — the real working tree is never mutated (sensor mutations run in scratch state only).
+
+**What the Verifier reports back (compact chat format):**
+
+```
+## Validation: [feature name] — [PASS ✅ | FAIL ❌]
+
+**Spec-anchored check**: [N/N ACs matched spec outcome | M spec-precision gaps flagged]
+**Gate**: [X passed, 0 failed]
+**Sensor**: [N mutations injected, N killed, N survived]
+**Report**: `.specs/features/<slug>/validation.md`
+
+**Ranked gaps** (if FAIL):
+1. [Gap description] — [AC or criterion] — [file:line or "no evidence"]
+2. ...
+```
+
+**Failure handling:** The orchestrator routes the ranked gaps to an implementer as fix tasks, then re-dispatches the Verifier. This fix→re-verify loop is bounded to a maximum of **3 iterations**. If gaps remain after 3 iterations, escalate to the user.
+
+---
+
+## 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.