fix(sdd): stop the planning artifact growing with steps × spec-size

.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "context-engineering-kit",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Hand-crafted collection of advanced context engineering techniques and patterns with minimal token footprint focused on improving agent result quality.",
   "owner": {
     "name": "NeoLabHQ",
@@ -77,7 +77,7 @@
     {
       "name": "sdd",
       "description": "Specification Driven Development workflow commands and agents, based on Github Spec Kit and OpenSpec. Uses specialized agents for effective context management and quality review.",
-      "version": "3.1.2",
+      "version": "3.2.0",
       "author": {
         "name": "Vlad Goncharov",
         "email": "vlad.goncharov@neolab.finance"

docs/plugins/sdd/implement-task.md

@@ -106,7 +106,7 @@ Reads the task file once and parses the `## Implementation Process` section:
 
 - Lists all steps with dependencies
 - Identifies parallel execution opportunities (`Parallel with:` annotations)
-- Classifies verification needs from `#### Verification` sections
+- Classifies verification needs from the resolved verification spec — the `<task-basename>.verification.md` sidecar, falling back to inline `#### Verification` sections in task files written by an older `qa-engineer`
 
 ### Phase 2: Execute Implementation Steps
 

docs/plugins/sdd/plan-task.md

@@ -18,7 +18,7 @@ Refine a draft task specification into a fully planned, implementation-ready tas
 | `--max-iterations` | `--max-iterations N` | `3` | Maximum retry cycles per phase before moving on |
 | `--included-stages` | `--included-stages s1,s2,...` | All stages | Comma-separated list of stages to include |
 | `--skip` | `--skip s1,s2,...` | None | Comma-separated list of stages to exclude |
-| `--fast` | flag | N/A | Alias for `--target-quality 3.0 --max-iterations 1 --included-stages business analysis,decomposition,verifications` |
+| `--fast` | flag | N/A | Alias for `--target-quality 3.0 --max-iterations 1 --included-stages business analysis,decomposition`. Add `verifications` explicitly if `/implement` should score steps with a judge. |
 | `--one-shot` | flag | N/A | Alias for `--included-stages business analysis,decomposition --skip-judges` |
 | `--human-in-the-loop` | `--human-in-the-loop p1,p2,...` | None | Phases after which to pause for human review |
 | `--skip-judges` | flag | `false` | Skip all judge validation checks |
@@ -133,7 +133,7 @@ Each sub-phase is validated by a judge agent. All three must pass before proceed
 
 ### Phase 6: Define Verifications
 
-`qa-engineer` agent (opus) adds LLM-as-Judge verification sections with custom rubrics, thresholds, and verification levels (None, Single Judge, Panel of 2, or Per-Item) for each implementation step.
+`qa-engineer` agent (opus) writes LLM-as-Judge verification specs with custom rubrics, thresholds, and verification levels (None, Single Judge, Panel of 2, or Per-Item) for each implementation step. The specs go into a sidecar file next to the task — `<task-basename>.verification.md`, one `### Step N` section each — and the task file gets a one-line `**Verification:**` pointer per step plus the `## Verification Summary` table.
 
 ### Phase 7: Promote Task
 

docs/plugins/sdd/usage-examples.md

@@ -64,7 +64,7 @@ Real-world scenarios demonstrating the effective use of the Spec-Driven Developm
 /implement-task @.specs/tasks/todo/fix-null-pointer-user-service.bug.md --skip-judges
 ```
 
-The `--fast` flag sets `--target-quality 3.0 --max-iterations 1 --included-stages "business analysis,decomposition,verifications"`, skipping research, codebase analysis, architecture synthesis, and parallelization.
+The `--fast` flag sets `--target-quality 3.0 --max-iterations 1 --included-stages "business analysis,decomposition"`, skipping research, codebase analysis, architecture synthesis, parallelization, and verifications. Append `,verifications` to the stage list when `/implement` should score each step with a judge.
 
 ---
 

plugins/sdd/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd",
-  "version": "3.1.2",
+  "version": "3.2.0",
   "description": "Specification Driven Development workflow commands and agents, based on Github Spec Kit and OpenSpec. Uses specialized agents for effective context management and quality review.",
   "author": {
     "name": "Vlad Goncharov",

plugins/sdd/agents/tech-lead.md

@@ -300,6 +300,30 @@ Each step costs at least one impl + one verification agent pair, and steps infla
 - YOU MUST size each step so it does enough verification-worthy work that the judge's run produces more value than its cost. If the verification would have nothing meaningful to check, the step is too small — merge it.
 - YOU SHOULD prefer one well-scoped step with multiple subtasks over two thin steps that each carry the full agent-pair overhead.
 
+##### Step Count Upper Bound
+
+The "no step larger than Large" rule bounds step **size** only. Nothing bounds step **count**, so a
+large task decomposes into an arbitrarily long list — a real migration touching ~40 files produced
+**19 steps**, and each one carried an agent pair plus a verification spec. Apply an upper bound too:
+
+| Task effort | Target steps | Hard ceiling |
+|-------------|--------------|--------------|
+| S / M | 3-5 | 6 |
+| L | 5-8 | 10 |
+| XL | 8-12 | 14 |
+
+- YOU MUST report the step count against this band in the Implementation Summary, and justify in one
+  sentence any count above the target.
+- If the count exceeds the **hard ceiling**, YOU MUST merge steps that belong to the same slice
+  before emitting. Steps that touch the same module, share the same test suites, and have no
+  external consumer between them are one step with more subtasks — not several.
+- Watch for the tell-tale symptom of over-splitting: **ordering invariants that exist only because
+  of the split** ("repoint the import in step 4 before step 6 deletes the module"). Every such
+  invariant is a constraint you created and must now defend. Merging the two steps deletes the
+  invariant for free.
+- A count above the ceiling is as much a defect as a step above Large. Both are reported, not
+  silently emitted.
+
 #### Vertical Slicing
 
 Each task should deliver a complete, testable slice of functionality from UI to database. Avoid horizontal layers (all models, then all controllers, then all views). Enable early integration and validation.
@@ -500,7 +524,7 @@ Phase 5: Polish
 | 1 | [Brief goal] | [Key output] | [S/M/L] |
 | 2 | [Brief goal] | [Key output] | [S/M/L] |
 
-**Total Steps**: N
+**Total Steps**: N — target band for [S/M/L/XL] is [X-Y], ceiling [Z]. [If above target: one-sentence justification.]
 **Critical Path**: Steps [X, Y, Z] are blocking
 **Parallel Opportunities**: Steps [A, B] can run concurrently
 
@@ -543,6 +567,7 @@ Generate 8 questions based on specifics of your task breakdown. These are exampl
 | 4 | **TDD Integration**: Does every implementation step include test writing in its Definition of Done or subtasks? Have I placed test infrastructure as foundational tasks? | Scan all steps for test-related subtasks. Tests must not be afterthoughts. |
 | 5 | **Risk Identification**: Have I identified ALL high-complexity steps? For each, have I either decomposed further OR created preceding spike tasks? | Review Risks & Blockers Summary. All high-impact items need mitigations. |
 | 6 | **Step Sizing (Upper Bound)**: Is every step completable in 1-2 days? Are there any steps too large that should be broken down? | Review Implementation Summary effort column. No step should be >Large. |
+| 6a | **Step Count (Upper Bound)**: Is the total step count within the band for this task's effort, and below the hard ceiling? Are there ordering invariants that exist only because a slice was split? | Compare Total Steps against the Step Count Upper Bound table. Merge same-slice steps until within the ceiling. |
 | 7 | **No Trivial Standalone Steps**: Does every step do more than a single trivial action (install/delete/copy/move/create-dir)? Are all trivial actions folded into the step that consumes them (or kept separate only under the documented shared-prerequisite exception)? | Scan every step. Flag any whose entire scope is a mechanical action. |
 | 8 | **Verification-Worthy Granularity**: Does every step do enough work to justify its verification agent's cost? Would the judge have something meaningful to check, or is the step too thin? | Review each step's Success Criteria and Subtasks. Thin steps must be merged. |
 
@@ -564,6 +589,8 @@ For each question, you MUST provide:
 [ ] Success criteria are specific and testable (not vague)
 [ ] Subtasks use simple format: - [ ] Description with file path
 [ ] No step estimated larger than "Large"
+[ ] Total step count within the band for this task's effort, below the hard ceiling
+[ ] No ordering invariant exists solely because a single slice was split across steps
 [ ] No step is "Too Small / Trivial" (no standalone install/delete/copy/move/create-dir)
 [ ] Every step does enough work to justify its verification agent's cost
 [ ] Phases organized: Setup → Foundational → User Stories → Polish
@@ -656,6 +683,8 @@ Before completing decomposition:
 - [ ] All steps have Goal, Output, Success Criteria, Subtasks, Blockers, Risks
 - [ ] Steps are ordered by dependency (no step depends on a later step)
 - [ ] No step estimated larger than "Large"
+- [ ] Total step count within the band for this task's effort, below the hard ceiling
+- [ ] No ordering invariant exists solely because a single slice was split across steps
 - [ ] No step is "Too Small / Trivial" — trivial actions folded into consuming steps
 - [ ] Every step does enough work to justify its verification agent's cost
 - [ ] Subtasks use simple format: - [ ] Description with file path

plugins/sdd/skills/implement-task/SKILL.md

@@ -74,7 +74,7 @@ When `--continue` is used:
 1. **Step Resolution:**
    - Parse the task file for `[DONE]` markers on step titles
    - Identify the last incompleted step
-   - Launch the `sdd:code-reviewer` agent to verify the last INCOMPLETE step's artifacts (using the step's `#### Verification` specification embedded in the task file)
+   - Launch the `sdd:code-reviewer` agent to verify the last INCOMPLETE step's artifacts (using the step's verification spec, resolved per the appendix: the sidecar's `### Step N`, or an inline `#### Verification` section in older task files)
    - If `combined_score >= threshold` (or `>= 3.0` with only Low-priority issues): Mark step as done and resume from the next step
    - Otherwise: Re-implement the step using the reviewer's issues as feedback and iterate until PASS
 
@@ -117,7 +117,7 @@ When `--refine` is used, it detects changes to **project files** (not the task f
    - For each changed file, determine which step created/modified it:
      - Check step's "Expected Output" section for file paths
      - Check step's subtasks for file references
-     - Check step's artifacts in `#### Verification` section
+     - Check step's artifacts in its resolved verification spec
    - Build a mapping: `{changed_file → step_number}`
 
 3. **Determine Affected Steps:**
@@ -541,7 +541,7 @@ Parse all flags from `$ARGUMENTS` and initialize configuration.
    - For each step, extract the files it creates/modifies from:
      - "Expected Output" sections
      - Subtask descriptions mentioning file paths
-     - `#### Verification` artifact paths
+     - verification spec artifact paths
    - Build mapping: `STEP_FILE_MAP = {step_number → [file_paths]}`
 
 3. **Map Changed Files to Steps:**
@@ -587,7 +587,7 @@ Parse the `## Implementation Process` section:
 
 - List all steps with dependencies
 - Identify which steps have `Parallel with:` annotations
-- Classify each step's verification needs from `#### Verification` sections:
+- Classify each step's verification needs from the resolved verification spec (sidecar `### Step N`, or inline `#### Verification`):
 
 | Verification Level | Code-Reviewer Dispatch | Threshold |
 |-----------------------------------|-------------|------------------------|-----------|
@@ -615,7 +615,7 @@ Create TodoWrite with all implementation steps, marking verification requirement
 
 ## Phase 2: Execute Implementation Steps
 
-For each step in dependency order, select the dispatch pattern by reading the step's `#### Verification` Level:
+For each step in dependency order, select the dispatch pattern by reading the step's verification Level — available directly from the task file's one-line `**Verification:**` pointer, or from the resolved spec:
 
 | Verification Level | Pattern |
 |--------------------|---------|
@@ -818,7 +818,7 @@ Inputs:
 
 **6. Determine Threshold and Apply Gate:**
 
-- Check if step is marked as critical in task file (in `#### Verification` section or step metadata)
+- Check if step is marked as critical in its verification spec (Level `Panel of 2 Judges`) or step metadata
 - If critical: use `THRESHOLD_FOR_CRITICAL_COMPONENTS`
 - If standard: use `THRESHOLD_FOR_STANDARD_COMPONENTS`
 
@@ -1282,7 +1282,7 @@ After all steps complete and DoD verification passes:
 │  Phase 1: Load Task                                           │
 │  ┌─────────────────────────────────────────────────────────┐  │
 │  │ Read $TASK_PATH → Parse steps                           │  │
-│  │ → Extract #### Verification specs → Create TodoWrite    │  │
+│  │ → Resolve verification spec → Create TodoWrite          │  │
 │  └─────────────────────────────────────────────────────────┘  │
 │                           │                                   │
 │                           ▼                                   │
@@ -1401,7 +1401,7 @@ Phase 1: Loading task...
 Task: "Add form validation service"
 Steps identified: 4 steps
 
-Verification plan (from #### Verification sections):
+Verification plan (from the resolved verification spec):
 - Step 1: No verification (directory creation)
 - Step 2: Panel of 2 evaluations (ValidationService)
 - Step 3: Per-item evaluations (3 validators)
@@ -1777,9 +1777,33 @@ Before completing implementation:
 
 This appendix documents how verification is specified in task files. During Phase 2 (Execute Steps), you will reference these specifications to understand how to verify each artifact.
 
-### How Task Files Define Verification
+### Where the Verification Spec Lives
 
-Task files define verification requirements in `#### Verification` sections within each implementation step. These sections specify:
+`sdd:qa-engineer` writes the verification spec to a **sidecar file** beside the task file: same
+directory and basename, extension replaced by `.verification.md`. For
+`.specs/tasks/in-progress/add-auth.feature.md` the sidecar is
+`.specs/tasks/in-progress/add-auth.verification.md`. It holds a shared preamble (Regular Checks,
+Project Guidelines Alignment) plus one `### Step N` section per step. The task file carries only a
+one-line `**Verification:**` pointer per step and the `## Verification Summary` table.
+
+**Resolution rule — apply this once, before Phase 2:**
+
+| Condition | Where to read each step's spec |
+|-----------|-------------------------------|
+| Sidecar `<task-basename>.verification.md` exists | Its `### Step N` section, plus the shared preamble |
+| Sidecar absent, task file has inline `#### Verification` sections | Those inline sections (task file written by an older `qa-engineer`) |
+| Neither exists | No verification specified — treat every step as level `None` and say so in the summary |
+
+Both layouts are supported; the sidecar wins when both are present. Everywhere below that refers to
+a step's `#### Verification` section means "the step's verification spec, resolved by this rule".
+
+**When dispatching `sdd:code-reviewer`, pass the resolved location explicitly** — the sidecar path
+and the `### Step N` heading, or the task file path for the inline layout — so the reviewer loads one
+step's spec and not the whole file.
+
+### How Verification Is Defined
+
+The verification spec defines, per step:
 
 ### Required Elements
 
@@ -1860,7 +1884,7 @@ When the `sdd:code-reviewer` evaluates artifacts, it uses this 5-point scale for
 **During Phase 2 (Execute Steps):**
 
 1. After a `sdd:developer` agent completes implementation
-2. Read the step's `#### Verification` subsection
+2. Read the step's verification spec (sidecar `### Step N`, or inline `#### Verification` in older task files)
 3. Extract: Level, Artifact paths, Threshold
 5. Launch the appropriate count of `sdd:code-reviewer` agent(s) based on Level
 6. Pass exactly the 4 inputs to each reviewer (artifact, step number, specification path, CLAUDE_PLUGIN_ROOT) — **NEVER a threshold**

plugins/sdd/skills/plan-task/SKILL.md

@@ -45,7 +45,7 @@ Parse the following arguments from `$ARGUMENTS`:
 | `--max-iterations` | `--max-iterations N` | `3` | Maximum implementation + judge retry cycles per phase before moving to next stage (regardless of pass/fail). |
 | `--included-stages` | `--included-stages stage1,stage2,...` | All stages | Comma-separated list of stages to include. |
 | `--skip` | `--skip stage1,stage2,...` | None | Comma-separated list of stages to exclude. |
-| `--fast` | `--fast` | N/A | Alias for `--target-quality 3.0 --max-iterations 1 --included-stages business analysis,decomposition,verifications` |
+| `--fast` | `--fast` | N/A | Alias for `--target-quality 3.0 --max-iterations 1 --included-stages business analysis,decomposition` - fewest judge rounds AND the smallest artifact. Add `verifications` explicitly if `/implement` should score steps with a judge. |
 | `--one-shot` | `--one-shot` | N/A | Alias for `--included-stages business analysis,decomposition --skip-judges` - minimal refinement without quality gates. |
 | `--human-in-the-loop` | `--human-in-the-loop phase1,phase2,...` | None | Phases after which to pause for human verification. |
 | `--skip-judges` | `--skip-judges` | `false` | Skip all judge validation checks - phases proceed without quality gates. |
@@ -76,7 +76,11 @@ TASK_FILE = first argument that is a file path (must exist in .specs/tasks/draft
 if --fast present:
     THRESHOLD = 3.0
     MAX_ITERATIONS = 1
-    INCLUDED_STAGES = ["business analysis", "decomposition", "verifications"]
+    INCLUDED_STAGES = ["business analysis", "decomposition"]
+    # `verifications` is deliberately EXCLUDED: it is the single largest contributor to
+    # artifact size (measured at 54% of an 8282-line task file), so including it here
+    # made `--fast` cut judge rounds while leaving the output just as large.
+    # Opt in explicitly when needed: --fast --included-stages "business analysis,decomposition,verifications"
 
 if --one-shot present:
     INCLUDED_STAGES = ["business analysis", "decomposition"]