specflow-cc 1.10.0 → 1.11.1

package/CHANGELOG.md

@@ -5,6 +5,51 @@ All notable changes to SpecFlow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.11.1] - 2026-02-10
+
+### Fixed
+
+- **Orchestrator premature state advancement** — executor agents could advance STATE.md beyond "review", skipping the review step entirely
+  - After `/sf:run` completion, the orchestrator would sometimes perform `/sf:done` logic (moving spec to Completed, activating next spec)
+  - Root cause: vague instructions in STATE.md update step allowed LLM agents to over-interpret "update STATE.md"
+  - Added explicit boundary instructions ("DO NOT move to Completed, DO NOT activate next spec") to all three executor agents
+  - Added post-execution state verification guard in `/sf:run` command handler
+  - Affected files: `sf-spec-executor-orchestrator.md`, `spec-executor-orchestrator.md`, `spec-executor.md`, `run.md`
+
+---
+
+## [1.11.0] - 2026-02-06
+
+### Added
+
+- **Self-check verification** — all executor agents now verify their own claims before reporting completion
+  - `spec-executor`: checks created files exist on disk, commits in git, modified files contain expected changes
+  - `spec-executor-worker`: self-check step before returning JSON results; new `self_check` field in response protocol
+  - Both orchestrators: aggregated self-check verifying all worker claims against reality
+  - Agents refuse to report success if artifacts are missing
+
+- **Segmented execution** — large task groups automatically split into sequential segments with fresh context
+  - Orchestrators evaluate segmentation threshold (Est. Context >= 20%)
+  - Each segment runs in a fresh worker subagent to prevent quality degradation
+  - Handoff summaries pass key exports and interface signatures between segments
+  - Segment results aggregated into single group result for downstream processing
+  - Segment failure handling: abort remaining segments on failure, continue on partial
+
+- **Wave column in spec creation** — `spec-creator` and `spec-splitter` now always generate a `Wave` column in Implementation Tasks tables
+  - Pre-computed wave numbers during spec creation (not during execution)
+  - Orchestrators read wave numbers directly instead of computing dependency graphs
+  - Fallback for legacy specs without Wave column preserved
+
+### Changed
+
+- **Enhanced deviation rules** — all executor agents now include detailed examples, rule priority order, and edge case guidance
+  - Rule priority: Rule 4 (architectural) overrides all; Rules 1-3 auto-fix; unsure defaults to Rule 4
+  - Standardized tracking format: `[Rule N - Type] {description}`
+
+- **Auditor segment hints** — `spec-auditor` can now flag task groups that should be pre-segmented based on estimated context
+
+---
+
 ## [1.10.0] - 2026-02-06
 
 ### Added

package/README.md

@@ -17,7 +17,7 @@ npx specflow-cc --global
 
 <br>
 
-https://github.com/user-attachments/assets/3f516907-8657-4ea4-bc0c-6319998a09db
+https://github.com/user-attachments/assets/23415009-81f9-4755-9e35-32e8bc56b8e7
 
 <br>
 
@@ -413,11 +413,12 @@ Control cost vs quality:
 
 | Profile | Spec Creation | Execution | Review |
 |---------|---------------|-----------|--------|
+| `max` | Opus | Opus | Opus |
 | `quality` | Opus | Opus | Sonnet |
 | `balanced` | Opus | Sonnet | Sonnet |
 | `budget` | Sonnet | Sonnet | Haiku |
 
-Use `quality` for critical features, `budget` for routine tasks.
+Use `max` for maximum quality everywhere, `quality` for critical features, `budget` for routine tasks.
 
 ---
 

package/agents/sf-spec-executor-orchestrator.md

@@ -142,8 +142,49 @@ Waves:
 
 For each wave:
 
+### 3.05 Evaluate Segmentation
+
+For each task group in the current wave, check if segmentation is needed.
+
+**Segmentation threshold:** Est. Context >= 20%
+
+**Decision logic:**
+
+| Est. Context | Segment Count | Rationale |
+|--------------|---------------|-----------|
+| < 20% | 1 (no segmentation) | Fits comfortably in fresh context |
+| 20-35% | 2 segments | Split to keep each segment in PEAK range |
+| 35-50% | 3 segments | Three-way split for larger groups |
+| > 50% | 4 segments (default) + warning | Group should have been split by auditor; flag as warning but proceed with 4-way split |
+
+**How to determine segment boundaries:**
+
+Parse the task group's task list and divide at natural boundaries:
+1. File boundaries (each segment handles a subset of files)
+2. Logical unit boundaries (types first, then implementations, then wiring)
+3. If tasks are numbered (T1, T2, T3...), divide the task numbers evenly
+
+**Segment plan format:**
+
+For each segmented group, create a segment plan:
+
+| Segment | Tasks | Files | Est. Context |
+|---------|-------|-------|--------------|
+| G2-S1 | Create types, Create handler-a | types.ts, handler-a.ts | ~12% |
+| G2-S2 | Create handler-b, Create tests | handler-b.ts, tests.ts | ~13% |
+
+**Pre-computed segments from auditor:**
+
+If the Implementation Tasks table includes a `Segments` column, use those segment boundaries instead of computing them at runtime.
+
 ### 3.1 Spawn Workers
 
+For each task group in the current wave:
+
+**If group is NOT segmented (standard path):**
+
+Spawn worker as today (unchanged).
+
 **Parallel (preferred):**
 ```
 Task(prompt="<task_group>G2: Create handler-a</task_group>
@@ -161,6 +202,104 @@ Task(prompt="...G4...", subagent_type="sf-spec-executor-worker", model="{profile
 
 **Sequential fallback:** If parallel fails, execute one at a time.
 
+**If group IS segmented:**
+
+Execute segments sequentially within the group, each in a fresh worker:
+
+Segment 1:
+```
+Task(prompt="<task_group>G2-S1: Create types and handler-a</task_group>
+<segment_info>
+Segment 1 of 2 for group G2.
+This is the FIRST segment. No prior work exists.
+</segment_info>
+<requirements>{G2-S1 requirements}</requirements>
+<project_patterns>@.specflow/PROJECT.md</project_patterns>
+<context_budget>
+Estimated: ~12%
+Target max: 25%
+</context_budget>
+Implement this segment. Create atomic commits.
+Return JSON: {group, segment, status, files_created, files_modified, commits, criteria_met, deviations, error}
+", subagent_type="sf-spec-executor-worker", model="{profile_model}", description="Execute G2 segment 1/2")
+```
+
+Wait for Segment 1 result, then:
+
+Segment 2:
+```
+Task(prompt="<task_group>G2-S2: Create handler-b and tests</task_group>
+<segment_info>
+Segment 2 of 2 for group G2.
+Prior segment completed. Summary of prior work:
+</segment_info>
+<prior_segment_summary>
+## Completed Segments
+
+### Segment 1 of N
+**Status:** complete
+**Files created:**
+- `path/to/file1.ts` -- brief description (key exports: X, Y)
+- `path/to/file2.ts` -- brief description (key exports: Z)
+
+**Files modified:**
+- `path/to/existing.ts` -- what changed
+
+**Commits:** hash1, hash2
+
+**Key interfaces/types defined:**
+- InterfaceName: { field1: type, field2: type }
+- TypeName: description
+</prior_segment_summary>
+<requirements>{G2-S2 requirements}</requirements>
+<project_patterns>@.specflow/PROJECT.md</project_patterns>
+<context_budget>
+Estimated: ~13%
+Target max: 25%
+</context_budget>
+Implement this segment. Create atomic commits.
+You can reference files created by prior segments but do NOT re-read them unless you need specific details.
+Return JSON: {group, segment, status, files_created, files_modified, commits, criteria_met, deviations, error}
+", subagent_type="sf-spec-executor-worker", model="{profile_model}", description="Execute G2 segment 2/2")
+```
+
+**Important:** Segments within a group are ALWAYS sequential (never parallel) because later segments depend on earlier ones.
+
+**Parallel behavior:** Non-segmented groups in the same wave still run in parallel alongside segmented groups. The segmented group's sequential segments run independently of other groups.
+
+### 3.15 Aggregate Segment Results
+
+After all segments for a group complete, merge results into a single group result:
+
+```json
+{
+  "group": "G2",
+  "status": "{worst status among segments: failed > partial > complete}",
+  "files_created": ["{union of all segments' files_created}"],
+  "files_modified": ["{union of all segments' files_modified}"],
+  "commits": ["{concatenation of all segments' commits in order}"],
+  "criteria_met": ["{union of all segments' criteria_met}"],
+  "deviations": ["{concatenation of all segments' deviations}"],
+  "error": "{first non-null error, or null}",
+  "segmented": true,
+  "segment_count": 2,
+  "segment_results": [
+    {"segment": 1, "status": "complete", ...},
+    {"segment": 2, "status": "complete", ...}
+  ]
+}
+```
+
+This aggregated result feeds into the existing Step 3.2 (Collect Results) and Step 3.3 (Handle Failures) unchanged.
+
+**Segment failure handling:**
+
+| Scenario | Action |
+|----------|--------|
+| Segment N fails | Abort remaining segments for this group, mark group as failed |
+| Segment N partial | Continue to next segment with available results, mark group as partial |
+| All segments complete | Aggregate into single group result, mark group as complete |
+
 ### 3.2 Collect Results
 
 Parse each worker's JSON response.
@@ -184,7 +323,35 @@ Criteria met: [union of all criteria_met]
 Deviations: [collect all deviations]
 ```
 
-## Step 6: Create Final Summary
+## Step 6: Aggregated Self-Check
+
+After aggregating results, verify that all worker claims are real.
+
+**1. Check all created files exist:**
+
+For each file in the aggregated `files_created` list:
+```bash
+[ -f "path/to/file" ] && echo "FOUND: path/to/file" || echo "MISSING: path/to/file"
+```
+
+**2. Check all commits exist:**
+
+For each commit hash in the aggregated `commits` list:
+```bash
+git log --oneline -20 | grep -q "{hash}" && echo "FOUND: {hash}" || echo "MISSING: {hash}"
+```
+
+**3. Check worker self_check fields:**
+
+If any worker returned `self_check: "partial"` or `self_check: "failed"`, flag those groups for investigation.
+
+**4. Handle failures:**
+
+- If missing files/commits found: report discrepancies in Execution Summary
+- Do NOT report success with missing artifacts
+- If critical files missing: mark affected groups as `partial`
+
+## Step 7: Create Final Summary
 
 Append Execution Summary to specification:
 
@@ -216,11 +383,19 @@ Append Execution Summary to specification:
 {aggregated deviations}
 ```
 
-## Step 7: Update STATE.md
+## Step 8: Update STATE.md
 
+Update ONLY the Current Position section:
 - Status → "review"
 - Next Step → "/sf:review"
 
+**CRITICAL — DO NOT go beyond this:**
+- Do NOT move the spec to Completed Specifications table
+- Do NOT remove the spec from Queue table
+- Do NOT activate the next specification in the queue
+- Do NOT archive the spec file
+- These actions belong to `/sf:done`, not to execution
+
 </process>
 
 <output>
@@ -276,6 +451,7 @@ Output directly as formatted text (not wrapped in a code block):
 - [ ] Each worker receives no more than 3 task groups
 - [ ] All worker results collected and parsed
 - [ ] Failures handled per failure handling rules
+- [ ] Aggregated self-check passed (all files and commits verified)
 - [ ] Results aggregated into final summary
 - [ ] Execution Summary appended to specification
 - [ ] STATE.md updated to "review"

package/agents/spec-auditor.md

@@ -467,6 +467,38 @@ If the spec has a Goal Analysis section, enhance Implementation Tasks:
 
 Note: "Enables Truths" column is only added when Goal Analysis is present.
 
+### 4.45 Segment Hints for Large Groups
+
+After generating task groups, check if any single group has Est. Context >= 20%.
+
+If so, add a `Segments` column to the Implementation Tasks table:
+
+| Group | Wave | Tasks | Dependencies | Est. Context | Segments |
+|-------|------|-------|--------------|--------------|----------|
+| G1 | 1 | Create types | - | ~8% | 1 |
+| G2 | 2 | Create handlers, tests, validation | G1 | ~28% | 2 |
+| G3 | 2 | Create UI components | G1 | ~10% | 1 |
+
+For groups with Segments > 1, add segment breakdown in the Execution Plan:
+
+**G2 Segments:**
+- S1: Create handlers (handler-a.ts, handler-b.ts) -- ~14%
+- S2: Create tests and validation (handler.test.ts, validation.ts) -- ~14%
+
+**Segment count guidance:**
+
+| Est. Context | Segment Count |
+|--------------|---------------|
+| < 20% | 1 (no segmentation) |
+| 20-35% | 2 segments |
+| 35-50% | 3 segments |
+| > 50% | 4 segments (with warning: consider splitting into separate task groups) |
+
+**Segment boundaries should follow natural divisions:**
+1. File boundaries (each segment handles subset of files)
+2. Logical unit boundaries (types first, then implementations, then wiring)
+3. Sequential task ordering (T1-T3 in S1, T4-T6 in S2)
+
 ## Step 4.5: Compute Execution Waves
 
 After generating task groups (or for any spec with Implementation Tasks):

package/agents/spec-creator.md

@@ -130,6 +130,74 @@ Write to `.specflow/specs/SPEC-XXX.md` using the template structure:
 8. **Assumptions:** What you assumed (clearly marked)
    - **If `<prior_discussion>` provided:** Decisions from discussion are facts, not assumptions
 
+## Step 5.5: Generate Implementation Tasks (for medium and large specs)
+
+**When to include:**
+- **Medium** and **large** complexity specs: Always include Implementation Tasks section
+- **Small** complexity specs: Optional (skip if only 1-2 files or simple change)
+
+**Task Groups:**
+
+1. Group related work logically:
+   - Types/interfaces first (foundational)
+   - Independent implementations (can run parallel)
+   - Integration/wiring last (depends on implementations)
+
+2. For each group, define:
+   - **Group ID**: G1, G2, G3, etc.
+   - **Tasks**: Brief description of what the group does
+   - **Dependencies**: Which groups must complete first (use `—` for none)
+   - **Est. Context**: Rough estimate (e.g., ~15%, ~20%)
+
+**Wave Assignment Algorithm:**
+
+Assign wave numbers to enable parallel execution:
+
+1. Initialize all groups with wave = 0 (unassigned)
+2. For each group with no dependencies: wave = 1
+3. Repeat until all groups have waves:
+   - For each unassigned group:
+     - If all dependencies have assigned waves:
+       - wave = max(dependency waves) + 1
+4. If groups remain unassigned after a full pass with no progress:
+   - Circular dependency exists
+   - Flag in spec as note: "Note: Circular dependency detected in groups [list]. Auditor will verify."
+
+**Implementation Tasks Table:**
+
+Generate the table with Wave column:
+
+```markdown
+### Task Groups
+
+| Group | Wave | Tasks | Dependencies | Est. Context |
+|-------|------|-------|--------------|--------------|
+| G1 | 1 | Create types | — | ~10% |
+| G2 | 2 | Create handler | G1 | ~20% |
+| G3 | 2 | Create tests | G1 | ~15% |
+| G4 | 3 | Wire integration | G2, G3 | ~10% |
+```
+
+**Execution Plan:**
+
+Generate the Execution Plan summary showing parallel opportunities:
+
+```markdown
+### Execution Plan
+
+| Wave | Groups | Parallel? | Workers |
+|------|--------|-----------|---------|
+| 1 | G1 | No | 1 |
+| 2 | G2, G3 | Yes | 2 |
+| 3 | G4 | No | 1 |
+
+**Total workers needed:** 2 (max in any wave)
+```
+
+- **Parallel?**: "Yes" if wave has >1 group, "No" otherwise
+- **Workers**: Count of groups in the wave
+- **Total workers needed**: Maximum Workers value across all waves
+
 ## Step 6: Estimate Complexity
 
 Based on:

package/agents/spec-executor-orchestrator.md

@@ -85,6 +85,7 @@ Worker returns structured JSON:
   "commits": ["abc123", "def456"],
   "criteria_met": ["Criterion 1", "Criterion 2"],
   "deviations": [],
+  "self_check": "passed|partial|skipped",
   "error": null
 }
 ```
@@ -138,6 +139,37 @@ This helps workers make trade-off decisions:
           "error": null
         }
       }
+    },
+    {
+      "id": 2,
+      "status": "in_progress",
+      "results": {
+        "G2": {
+          "status": "in_progress",
+          "segmented": true,
+          "segment_count": 2,
+          "segments": [
+            {
+              "segment": 1,
+              "status": "complete",
+              "commits": ["abc123"],
+              "files_created": ["types.ts"],
+              "handoff_summary": "..."
+            },
+            {
+              "segment": 2,
+              "status": "running",
+              "commits": [],
+              "files_created": []
+            }
+          ]
+        },
+        "G3": {
+          "status": "complete",
+          "segmented": false,
+          "commits": ["def456"]
+        }
+      }
     }
   ],
   "commits": ["all", "commit", "hashes"],
@@ -320,8 +352,49 @@ Verify prerequisites:
   2. "Continue anyway" -> proceed despite issues
   3. "Abort" -> stop execution, preserve state
 
+### 3.05 Evaluate Segmentation
+
+For each task group in the current wave, check if segmentation is needed.
+
+**Segmentation threshold:** Est. Context >= 20%
+
+**Decision logic:**
+
+| Est. Context | Segment Count | Rationale |
+|--------------|---------------|-----------|
+| < 20% | 1 (no segmentation) | Fits comfortably in fresh context |
+| 20-35% | 2 segments | Split to keep each segment in PEAK range |
+| 35-50% | 3 segments | Three-way split for larger groups |
+| > 50% | 4 segments (default) + warning | Group should have been split by auditor; flag as warning but proceed with 4-way split |
+
+**How to determine segment boundaries:**
+
+Parse the task group's task list and divide at natural boundaries:
+1. File boundaries (each segment handles a subset of files)
+2. Logical unit boundaries (types first, then implementations, then wiring)
+3. If tasks are numbered (T1, T2, T3...), divide the task numbers evenly
+
+**Segment plan format:**
+
+For each segmented group, create a segment plan:
+
+| Segment | Tasks | Files | Est. Context |
+|---------|-------|-------|--------------|
+| G2-S1 | Create types, Create handler-a | types.ts, handler-a.ts | ~12% |
+| G2-S2 | Create handler-b, Create tests | handler-b.ts, tests.ts | ~13% |
+
+**Pre-computed segments from auditor:**
+
+If the Implementation Tasks table includes a `Segments` column, use those segment boundaries instead of computing them at runtime.
+
 ### 3.1 Spawn Workers
 
+For each task group in the current wave:
+
+**If group is NOT segmented (standard path):**
+
+Spawn worker as today (unchanged).
+
 **Parallel (preferred):**
 ```
 Task(prompt="<task_group>G2: Create handler-a</task_group>
@@ -344,6 +417,104 @@ Task(prompt="...G4 (with context_budget)...", subagent_type="sf-spec-executor-wo
 
 **Sequential fallback:** If parallel fails, execute one at a time.
 
+**If group IS segmented:**
+
+Execute segments sequentially within the group, each in a fresh worker:
+
+Segment 1:
+```
+Task(prompt="<task_group>G2-S1: Create types and handler-a</task_group>
+<segment_info>
+Segment 1 of 2 for group G2.
+This is the FIRST segment. No prior work exists.
+</segment_info>
+<requirements>{G2-S1 requirements}</requirements>
+<project_patterns>@.specflow/PROJECT.md</project_patterns>
+<context_budget>
+Estimated: ~12%
+Target max: 25%
+</context_budget>
+Implement this segment. Create atomic commits.
+Return JSON: {group, segment, status, files_created, files_modified, commits, criteria_met, deviations, error}
+", subagent_type="sf-spec-executor-worker", model="{profile_model}", description="Execute G2 segment 1/2")
+```
+
+Wait for Segment 1 result, then:
+
+Segment 2:
+```
+Task(prompt="<task_group>G2-S2: Create handler-b and tests</task_group>
+<segment_info>
+Segment 2 of 2 for group G2.
+Prior segment completed. Summary of prior work:
+</segment_info>
+<prior_segment_summary>
+## Completed Segments
+
+### Segment 1 of N
+**Status:** complete
+**Files created:**
+- `path/to/file1.ts` -- brief description (key exports: X, Y)
+- `path/to/file2.ts` -- brief description (key exports: Z)
+
+**Files modified:**
+- `path/to/existing.ts` -- what changed
+
+**Commits:** hash1, hash2
+
+**Key interfaces/types defined:**
+- InterfaceName: { field1: type, field2: type }
+- TypeName: description
+</prior_segment_summary>
+<requirements>{G2-S2 requirements}</requirements>
+<project_patterns>@.specflow/PROJECT.md</project_patterns>
+<context_budget>
+Estimated: ~13%
+Target max: 25%
+</context_budget>
+Implement this segment. Create atomic commits.
+You can reference files created by prior segments but do NOT re-read them unless you need specific details.
+Return JSON: {group, segment, status, files_created, files_modified, commits, criteria_met, deviations, error}
+", subagent_type="sf-spec-executor-worker", model="{profile_model}", description="Execute G2 segment 2/2")
+```
+
+**Important:** Segments within a group are ALWAYS sequential (never parallel) because later segments depend on earlier ones.
+
+**Parallel behavior:** Non-segmented groups in the same wave still run in parallel alongside segmented groups. The segmented group's sequential segments run independently of other groups.
+
+### 3.15 Aggregate Segment Results
+
+After all segments for a group complete, merge results into a single group result:
+
+```json
+{
+  "group": "G2",
+  "status": "{worst status among segments: failed > partial > complete}",
+  "files_created": ["{union of all segments' files_created}"],
+  "files_modified": ["{union of all segments' files_modified}"],
+  "commits": ["{concatenation of all segments' commits in order}"],
+  "criteria_met": ["{union of all segments' criteria_met}"],
+  "deviations": ["{concatenation of all segments' deviations}"],
+  "error": "{first non-null error, or null}",
+  "segmented": true,
+  "segment_count": 2,
+  "segment_results": [
+    {"segment": 1, "status": "complete", ...},
+    {"segment": 2, "status": "complete", ...}
+  ]
+}
+```
+
+This aggregated result feeds into the existing Step 3.2 (Collect Results) and Step 3.3 (Update State Per Worker) unchanged.
+
+**Segment failure handling:**
+
+| Scenario | Action |
+|----------|--------|
+| Segment N fails | Abort remaining segments for this group, mark group as failed |
+| Segment N partial | Continue to next segment with available results, mark group as partial |
+| All segments complete | Aggregate into single group result, mark group as complete |
+
 ### 3.2 Collect Results
 
 Parse each worker's JSON response.
@@ -438,6 +609,36 @@ Criteria met: [union of all criteria_met]
 Deviations: [collect all deviations]
 ```
 
+## Step 4.5: Final Aggregated Self-Check
+
+After aggregating all results, verify claims against reality.
+
+**1. Check all created files exist:**
+
+For each file in the aggregated `files_created` list:
+```bash
+[ -f "path/to/file" ] && echo "FOUND: path/to/file" || echo "MISSING: path/to/file"
+```
+
+**2. Check all commits exist:**
+
+For each commit hash in the aggregated `commits` list:
+```bash
+git log --oneline -30 | grep -q "{hash}" && echo "FOUND: {hash}" || echo "MISSING: {hash}"
+```
+
+**3. Check worker self_check fields:**
+
+If any worker returned `self_check: "partial"` or `self_check: "skipped"`, flag those groups.
+
+**4. Handle discrepancies:**
+
+- Missing files/commits → report in Execution Summary under "Self-Check Issues"
+- Do NOT report full success with missing artifacts
+- If critical files missing → mark affected groups as `partial` in state
+
+**Do NOT skip this step.**
+
 ## Step 5: Create Final Summary
 
 Append Execution Summary to specification:
@@ -486,10 +687,18 @@ rm .specflow/execution/SPEC-XXX-state.json
 
 ## Step 7: Update STATE.md
 
-- Status -> "review"
-- Next Step -> "/sf:review"
+Update ONLY the Current Position section:
+- Status → "review"
+- Next Step → "/sf:review"
 - Remove or update Execution Status row
 
+**CRITICAL — DO NOT go beyond this:**
+- Do NOT move the spec to Completed Specifications table
+- Do NOT remove the spec from Queue table
+- Do NOT activate the next specification in the queue
+- Do NOT archive the spec file
+- These actions belong to `/sf:done`, not to execution
+
 </process>
 
 <output>
@@ -551,6 +760,7 @@ Output directly as formatted text (not wrapped in a code block):
 - [ ] State updated after each wave completes
 - [ ] Post-wave verification performed after each wave
 - [ ] Failures handled per failure handling rules
+- [ ] Final aggregated self-check passed (all files and commits verified)
 - [ ] Results aggregated into final summary
 - [ ] State file deleted on successful completion
 - [ ] Execution Summary appended to specification

package/agents/spec-executor-worker.md

@@ -27,20 +27,28 @@ You receive ONLY your task group's requirements from the orchestrator.
 
 ## Deviation Rules (inherited from spec-executor)
 
+Apply these rules automatically. Track all deviations for the result JSON.
+
 **Rule 1: Auto-fix bugs** (no permission needed)
 - Code doesn't work as intended → fix inline, continue
+- Examples: wrong logic, type errors, null pointers, broken validation, security vulnerabilities
+- Track as: `[Rule 1 - Bug] {description}`
 
 **Rule 2: Auto-add missing critical functionality** (no permission needed)
-- Missing essentials for correctness/security
-- No error handling, no input validation, no null checks → add inline, continue
+- Missing essentials for correctness/security → add inline, continue
+- Examples: missing error handling, no input validation, missing null checks, no auth on protected routes
+- Track as: `[Rule 2 - Missing Critical] {description}`
 
 **Rule 3: Auto-fix blocking issues** (no permission needed)
-- Prevents task completion (missing dependency, broken import, wrong types)
-- Fix and continue
+- Prevents task completion → fix and continue
+- Examples: missing dependency, broken import paths, wrong types, build config error
+- Track as: `[Rule 3 - Blocking] {description}`
 
 **Rule 4: Ask about architectural changes** (requires user decision)
-- Significant structural modifications needed
-- New database table, schema changes, framework switching → STOP and ask user
+- Significant structural modifications needed → STOP and ask user
+- Examples: new database table, schema changes, framework switching, changing API contracts
+
+**Rule Priority:** Rule 4 overrides all → Rules 1-3 auto-fix → unsure = Rule 4
 
 ## Atomic Commits
 
@@ -71,11 +79,19 @@ When writing or modifying code:
 
 From orchestrator prompt, extract:
 - Task group ID (e.g., "G2")
+- **Segment info (if present):** segment number, total segments
+- **Prior segment summary (if present):** files created, key exports, commits
 - Task description
-- Requirements for this group
+- Requirements for this group/segment
 - Interfaces/types to use (from previous groups)
 - Project patterns reference
 
+**If segment info is present:**
+- This is a segmented execution
+- Focus ONLY on tasks assigned to this segment
+- Use prior segment summary to understand what already exists
+- Do NOT re-read files from prior segments unless you need specific implementation details
+
 ## Step 2: Load Required Context
 
 Read ONLY what's needed:
@@ -129,10 +145,33 @@ Deviations:
 - [Rule 2 - Missing] Added {functionality} for {reason}
 ```
 
-## Step 5: Return Results
+## Step 5: Self-Check (Verify Your Own Claims)
+
+Before returning results, verify that your work actually exists.
+
+**1. Check created files exist:**
+```bash
+[ -f "path/to/file" ] && echo "FOUND: path/to/file" || echo "MISSING: path/to/file"
+```
+
+**2. Check commits exist:**
+```bash
+git log --oneline -10 | grep -q "{hash}" && echo "FOUND: {hash}" || echo "MISSING: {hash}"
+```
+
+**3. If ANY check fails:**
+- Fix the issue before returning results
+- Do NOT return `status: "complete"` with missing artifacts
+- If unfixable, return `status: "partial"` with error explaining what's missing
+
+**Do NOT skip this step.**
+
+## Step 6: Return Results
 
 Output structured JSON for orchestrator:
 
+**For non-segmented execution:**
+
 ```json
 {
   "group": "G2",
@@ -149,10 +188,45 @@ Output structured JSON for orchestrator:
     "handleQuerySub processes QUERY_SUB messages"
   ],
   "deviations": [],
+  "self_check": "passed",
   "error": null
 }
 ```
 
+**For segmented execution, add segment fields:**
+
+```json
+{
+  "group": "G2",
+  "segment": 1,
+  "segment_total": 2,
+  "status": "complete",
+  "files_created": ["path/to/types.ts", "path/to/handler-a.ts"],
+  "files_modified": [],
+  "commits": ["abc123", "def456"],
+  "criteria_met": ["Types defined", "HandlerA implemented"],
+  "deviations": [],
+  "self_check": "passed",
+  "error": null,
+  "handoff_summary": {
+    "key_exports": ["UserType", "ConfigType", "HandlerA"],
+    "interfaces": "UserType: { id: string, name: string }",
+    "notes": "HandlerA expects ConfigType in constructor"
+  }
+}
+```
+
+**The `handoff_summary` field** (for segmented execution only) contains:
+- Key exports from created files
+- Interface/type signatures that later segments will need
+- Brief notes about design decisions or conventions established
+
+**Rules for handoff summary:**
+- Include file paths and key exports (not full file contents)
+- Include interface/type signatures if they are needed by later segments
+- Maximum ~500 words per segment summary
+- Do NOT include implementation details, only the public API surface
+
 **Status values:**
 - `complete`: All tasks done successfully
 - `partial`: Some tasks done, others blocked
@@ -164,7 +238,7 @@ Output structured JSON for orchestrator:
 
 Return ONLY the structured JSON result. The orchestrator will parse this.
 
-**On success:**
+**On success (non-segmented):**
 ```json
 {
   "group": "G2",
@@ -174,10 +248,33 @@ Return ONLY the structured JSON result. The orchestrator will parse this.
   "commits": ["abc1234", "def5678"],
   "criteria_met": ["Criterion 1", "Criterion 2"],
   "deviations": [],
+  "self_check": "passed",
   "error": null
 }
 ```
 
+**On success (segmented):**
+```json
+{
+  "group": "G2",
+  "segment": 1,
+  "segment_total": 2,
+  "status": "complete",
+  "files_created": ["path/to/types.ts"],
+  "files_modified": [],
+  "commits": ["abc1234"],
+  "criteria_met": ["Types defined"],
+  "deviations": [],
+  "self_check": "passed",
+  "error": null,
+  "handoff_summary": {
+    "key_exports": ["UserType", "ConfigType"],
+    "interfaces": "UserType: { id: string, name: string }",
+    "notes": "Types exported from types.ts module"
+  }
+}
+```
+
 **On partial completion:**
 ```json
 {
@@ -188,6 +285,7 @@ Return ONLY the structured JSON result. The orchestrator will parse this.
   "commits": ["abc1234"],
   "criteria_met": ["Criterion 1"],
   "deviations": [],
+  "self_check": "partial",
   "error": "Could not complete task X: missing dependency Y"
 }
 ```
@@ -202,6 +300,7 @@ Return ONLY the structured JSON result. The orchestrator will parse this.
   "commits": [],
   "criteria_met": [],
   "deviations": [],
+  "self_check": "skipped",
   "error": "Failed to implement: {reason}"
 }
 ```
@@ -214,6 +313,7 @@ Return ONLY the structured JSON result. The orchestrator will parse this.
 - [ ] All tasks in group implemented
 - [ ] Atomic commits created for each logical unit
 - [ ] Deviations documented (if any)
+- [ ] Self-check passed (all files and commits verified)
 - [ ] Structured JSON result returned
 - [ ] Status reflects actual completion state
 </success_criteria>

package/agents/spec-executor.md

@@ -28,26 +28,39 @@ The specification is your contract. Follow it exactly:
 
 ## Deviation Rules
 
-When reality doesn't match the plan:
+When reality doesn't match the plan, apply these rules automatically. Track all deviations for the Execution Summary.
 
 **Rule 1: Auto-fix bugs** (no permission needed)
-- Code doesn't work as intended
-- Fix inline, continue
+- Code doesn't work as intended → fix inline, continue
+- Examples: wrong logic, type errors, null pointer exceptions, broken validation, security vulnerabilities (SQL injection, XSS), race conditions, memory leaks
+- Track as: `[Rule 1 - Bug] {description}`
 
 **Rule 2: Auto-add missing critical functionality** (no permission needed)
-- Missing essentials for correctness/security
-- No error handling, no input validation, no null checks
-- Fix inline, continue
+- Missing essentials for correctness/security → add inline, continue
+- Examples: missing error handling (no try/catch), no input validation, missing null checks, no auth on protected routes, missing required indexes
+- Critical = required for correct/secure operation. These are NOT "features" — they're correctness requirements
+- Track as: `[Rule 2 - Missing Critical] {description}`
 
 **Rule 3: Auto-fix blocking issues** (no permission needed)
-- Something prevents task completion
-- Missing dependency, broken import, wrong types
-- Fix and continue
+- Something prevents task completion → fix and continue
+- Examples: missing dependency, broken import paths, wrong types blocking compilation, missing env variable, build config error, circular dependency
+- Track as: `[Rule 3 - Blocking] {description}`
 
 **Rule 4: Ask about architectural changes** (requires user decision)
-- Significant structural modification required
-- New database table, schema changes, switching frameworks
-- STOP and ask user
+- Significant structural modification required → STOP and ask user
+- Examples: adding new database table, major schema changes, switching libraries/frameworks, changing API contracts, adding new infrastructure layer
+- Present: what you found, proposed change, why needed, impact, alternatives
+
+**Rule Priority** (when multiple could apply):
+1. If Rule 4 applies → STOP (architectural decision needed)
+2. If Rules 1-3 apply → fix automatically, track for summary
+3. If genuinely unsure → apply Rule 4 (safer to ask)
+
+**Edge case guidance:**
+- "This validation is missing" → Rule 2 (critical for security)
+- "This crashes on null" → Rule 1 (bug)
+- "Need to add a database table" → Rule 4 (architectural)
+- "Need to add a column" → Rule 1 or 2 (depends on context)
 
 ## Atomic Commits
 
@@ -153,7 +166,39 @@ If any deviations occurred (Rules 1-3), document them:
 2. [Rule 2 - Missing] Added {functionality} for {reason}
 ```
 
-## Step 7: Create Execution Summary
+## Step 7: Self-Check (Verify Your Own Claims)
+
+After implementation, verify that your work actually exists before reporting completion.
+
+**1. Check created files exist:**
+
+For each file you claim to have created:
+```bash
+[ -f "path/to/file" ] && echo "FOUND: path/to/file" || echo "MISSING: path/to/file"
+```
+
+**2. Check commits exist:**
+
+For each commit hash you recorded:
+```bash
+git log --oneline -10 | grep -q "{hash}" && echo "FOUND: {hash}" || echo "MISSING: {hash}"
+```
+
+**3. Check modified files have expected changes:**
+
+For key modifications, verify the change is present:
+```bash
+grep -q "expected_pattern" path/to/modified/file && echo "VERIFIED" || echo "NOT FOUND"
+```
+
+**4. Report self-check result:**
+
+- If ALL checks pass: continue to Execution Summary
+- If ANY check fails: **fix the issue** before proceeding, do NOT report success with missing artifacts
+
+**Do NOT skip this step. Do NOT report completion if self-check fails.**
+
+## Step 8: Create Execution Summary
 
 Append to specification:
 
@@ -186,11 +231,19 @@ Append to specification:
 {Any important implementation notes for reviewer}
 ```
 
-## Step 8: Update STATE.md
+## Step 9: Update STATE.md
 
+Update ONLY the Current Position section:
 - Status → "review"
 - Next Step → "/sf:review"
 
+**CRITICAL — DO NOT go beyond this:**
+- Do NOT move the spec to Completed Specifications table
+- Do NOT remove the spec from Queue table
+- Do NOT activate the next specification in the queue
+- Do NOT archive the spec file
+- These actions belong to `/sf:done`, not to execution
+
 </process>
 
 <output>
@@ -237,6 +290,7 @@ Output directly as formatted text (not wrapped in a code block):
 - [ ] All acceptance criteria addressed
 - [ ] Atomic commits created
 - [ ] Deviations documented
+- [ ] Self-check passed (all files and commits verified)
 - [ ] Execution Summary added to spec
 - [ ] STATE.md updated
 </success_criteria>

package/agents/spec-splitter.md

@@ -112,6 +112,57 @@ After user approval, create each child spec:
 7. Copy applicable Constraints
 8. Note inherited Assumptions
 
+**Implementation Tasks for Child Specs:**
+
+When a child spec contains **3+ task groups**, include an Implementation Tasks section with Wave column:
+
+### Wave Assignment Algorithm
+
+1. Initialize all groups with wave = 0 (unassigned)
+2. For each group with no dependencies: wave = 1
+3. Repeat until all groups have waves:
+   - For each unassigned group:
+     - If all dependencies have assigned waves:
+       - wave = max(dependency waves) + 1
+4. If groups remain unassigned after a full pass with no progress:
+   - Circular dependency exists
+   - Flag in spec as note for auditor
+
+### Implementation Tasks Table Format
+
+```markdown
+### Task Groups
+
+| Group | Wave | Tasks | Dependencies | Est. Context |
+|-------|------|-------|--------------|--------------|
+| G1 | 1 | Create types | — | ~10% |
+| G2 | 2 | Create handler | G1 | ~20% |
+| G3 | 2 | Create tests | G1 | ~15% |
+| G4 | 3 | Wire integration | G2, G3 | ~10% |
+```
+
+### Execution Plan Format
+
+```markdown
+### Execution Plan
+
+| Wave | Groups | Parallel? | Workers |
+|------|--------|-----------|---------|
+| 1 | G1 | No | 1 |
+| 2 | G2, G3 | Yes | 2 |
+| 3 | G4 | No | 1 |
+
+**Total workers needed:** 2 (max in any wave)
+```
+
+- **Parallel?**: "Yes" if wave has >1 group, "No" otherwise
+- **Workers**: Count of groups in the wave
+- **Total workers needed**: Maximum Workers value across all waves
+
+**Threshold Note:**
+- Child specs with <3 task groups: Implementation Tasks section is optional
+- Child specs with 3+ task groups: Include Implementation Tasks with Wave column
+
 ## Step 7: Archive Parent
 
 Move parent spec:

package/commands/sf/run.md

@@ -239,7 +239,13 @@ The agent will:
 2. Create atomic commits
 3. Handle deviations
 4. Add Execution Summary to spec
-5. Update STATE.md to "review"
+5. Update STATE.md status to "review"
+
+**After agent returns, verify STATE.md is correct:**
+- Active Specification must still be the SAME spec (not advanced to next)
+- Status must be "review" (not "done" or "draft")
+- Spec must still be in Queue (not moved to Completed)
+- If agent over-advanced the state, revert to: active=SPEC-XXX, status=review, next=/sf:review
 
 ## Step 9.5: Check STATE.md Size and Rotate if Needed
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specflow-cc",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "description": "Spec-driven development system for Claude Code — quality-first workflow with explicit audit cycles",
   "bin": {
     "specflow-cc": "bin/install.js"