specflow-cc 1.11.1 → 1.13.0

package/CHANGELOG.md

@@ -5,6 +5,70 @@ 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.13.0] - 2026-02-11
+
+### Added
+
+- **Autopilot mode** (`/sf:autopilot`) — run the full spec lifecycle autonomously
+  - Single spec: `/sf:autopilot` or `/sf:autopilot SPEC-XXX`
+  - Batch mode: `/sf:autopilot --all` processes entire queue sequentially
+  - Cycle detection: configurable limits for audit (default: 3) and fix (default: 3) cycles
+  - Graceful halt on `needs_decomposition` or `paused` specs
+  - Summary report with per-spec outcomes and cycle counts
+  - Agent failure handling: continues batch on single-spec failure
+  - Configurable via `.specflow/config.json` under `"autopilot"` key
+
+### Changed
+
+- **Replaced all Bash/awk/sed markdown mutations** with Read+Write tool instructions across 13 agent and command files
+  - Eliminates fragile shell-based file editing that could corrupt markdown structure
+  - All STATE.md, spec, and archive updates now use explicit Read→Write pattern
+  - Affected: spec-creator, spec-auditor, spec-reviser, spec-splitter, spec-executor, spec-executor-orchestrator, impl-reviewer, and 6 command files
+
+- `/sf:help` — added Autonomous Execution section with autopilot commands
+- README — added autopilot to workflow diagram, commands table, and typical session
+
+---
+
+## [1.12.0] - 2026-02-10
+
+### Added
+
+- **Language Profiles** — optional, per-language configuration in PROJECT.md that adapts all agents to language-specific needs
+  - `/sf:init` auto-detects language from `Cargo.toml` (Rust), `go.mod` (Go), `tsconfig.json` (TypeScript), `pyproject.toml` (Python)
+  - Generates `## Language Profile` section in PROJECT.md with build/lint/test commands, max files per spec, compilation gate, and trait-first settings
+  - Projects without a detected language remain fully language-agnostic (backward-compatible)
+
+- **Compilation gates** — incremental build verification during implementation (Rust, Go)
+  - `spec-executor` and `spec-executor-worker` run `build_check` command after each file or tightly coupled group
+  - Build failures auto-fixed before proceeding (Rule 3: blocking issues)
+  - Lint check runs at end of implementation scope
+  - New `build_check` field in worker JSON result protocol
+
+- **Trait-first enforcement** — compiled languages require type/trait design before implementation
+  - `spec-creator` mandates G1/Wave 1 as types-only when `Trait-first: Yes`
+  - `spec-auditor` validates trait-first compliance (Critical if G1 mixes traits and implementation)
+  - Prevents cascading rework from wrong trait boundaries in Rust/Go
+
+- **Language-aware spec sizing** — file count limits adapted per language
+  - Rust: 3-5 files max (borrow checker errors cascade)
+  - Go: 5-8 files max
+  - TypeScript/Python: 8-10 files max
+  - `spec-auditor` raises Warning/Critical when file count exceeds language profile limit
+
+- **Language-specific review gates** in `impl-reviewer`
+  - Runs build, lint, and test commands from profile as review gates
+  - Rust idiom checks: no unnecessary `.clone()`, `?` operator over `.unwrap()`, `unsafe` documentation, `Send + Sync` bounds
+  - Go idiom checks: error returns over panics, interfaces accepted/structs returned, context propagation
+
+### Changed
+
+- `templates/project.md` — added optional Language Profile section
+- `spec-auditor` — added Step 3.10 (Language Profile Check) with 5 sub-checks and scope threshold override
+- `spec-creator` — added language-specific sizing table and trait-first override in task group generation
+
+---
+
 ## [1.11.1] - 2026-02-10
 
 ### Fixed

package/README.md

@@ -241,6 +241,8 @@ Your spec becomes documentation: why the code exists, what decisions were made,
               ↓                          ↓              ↓
          /sf:revise                  /sf:fix      (optional UAT)
          (if needed)                 (if needed)
+
+         /sf:autopilot — runs the entire flow above automatically
 ```
 
 **Key principle:** Audits and reviews run in fresh context — no bias from creation.
@@ -312,6 +314,7 @@ Six months later, you can read the spec and understand not just *what* was built
 | `/sf:fix` | Fix based on review feedback |
 | `/sf:verify` | Interactive user acceptance testing |
 | `/sf:done` | Complete and archive |
+| `/sf:autopilot` | Run full lifecycle autonomously |
 
 **Quick mode:**
 
@@ -455,6 +458,10 @@ Use `max` for maximum quality everywhere, `quality` for critical features, `budg
 /sf:review                               # Fresh context review
 /sf:verify                               # Manual verification
 /sf:done                                 # Archive
+
+# Or skip manual steps — run everything autonomously
+/sf:autopilot                            # Process active spec end-to-end
+/sf:autopilot --all                      # Process entire queue
 ```
 
 ---

package/agents/impl-reviewer.md

@@ -165,6 +165,54 @@ During code review, watch for signals that the specification itself may have bee
 
 **Note:** This is a safety net, not a primary check. Strategic issues should be caught earlier by `spec-auditor`.
 
+### 4.9 Language Profile Check
+
+**Detection:** Check if PROJECT.md contains a `## Language Profile` section.
+
+**If no Language Profile:** Skip this check.
+
+**If Language Profile exists:** Run configured verification commands and check results.
+
+**4.9.1 Build Check:**
+Run `Build check` command from profile (e.g., `cargo check`, `go build ./...`):
+```bash
+{build_check_command}
+```
+- Exit 0 → ✓ Passed
+- Non-zero → **Critical**: "Build check failed: {error output}"
+
+**4.9.2 Lint Check:**
+Run `Lint` command from profile (e.g., `cargo clippy -- -D warnings`):
+```bash
+{lint_command}
+```
+- Exit 0 → ✓ Passed
+- Non-zero → **Major**: "Lint check failed: {warning count} warnings/errors"
+
+**4.9.3 Test Check:**
+Run `Test` command from profile (e.g., `cargo test`):
+```bash
+{test_command}
+```
+- Exit 0 → ✓ Passed
+- Non-zero → **Critical**: "Tests failed: {failure summary}"
+
+**4.9.4 Language-Specific Idiom Check:**
+
+For **Rust** (Language = Rust):
+- [ ] No unnecessary `.clone()` calls — prefer borrowing
+- [ ] Error handling uses `?` operator and `Result<T, E>` — not `.unwrap()` or `.expect()` in production code
+- [ ] `unsafe` blocks have safety invariant comments
+- [ ] Proper `Send + Sync` bounds on trait objects
+- [ ] No `Box<dyn Any>` type erasure where concrete types work
+
+For **Go** (Language = Go):
+- [ ] Errors returned, not panicked
+- [ ] Interfaces accepted, structs returned
+- [ ] Context propagation (`ctx context.Context` as first param)
+
+If idiom violations found: add as **Major** issues with specific file:line references.
+
 ## Step 5: Categorize Findings
 
 Organize into:
@@ -240,6 +288,14 @@ Append to specification's Review History:
 - If APPROVED: Status → "done", Next Step → "/sf:done"
 - If CHANGES_REQUESTED: Status → "review", Next Step → "/sf:fix"
 
+Update STATE.md by reading the current file content, then writing the updated file with:
+- "**Status:**" line changed to the new status
+- "**Next Step:**" line changed to the new next step
+- No other content modified
+
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 </process>
 
 <output>

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

@@ -389,6 +389,14 @@ Update ONLY the Current Position section:
 - Status → "review"
 - Next Step → "/sf:review"
 
+Update STATE.md by reading the current file content, then writing the updated file with:
+- "**Status:**" line changed to the new status
+- "**Next Step:**" line changed to the new next step
+- No other content modified
+
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 **CRITICAL — DO NOT go beyond this:**
 - Do NOT move the spec to Completed Specifications table
 - Do NOT remove the spec from Queue table

package/agents/spec-auditor.md

@@ -415,6 +415,57 @@ Check if spec includes items marked as "Out of Scope" or "Deferred" in PROJECT.m
 **If compliant:**
 - Add to audit output: "Project compliance: ✓ Honors PROJECT.md decisions"
 
+## Step 3.10: Language Profile Check
+
+**Detection:** Check if PROJECT.md contains a `## Language Profile` section.
+
+**If no Language Profile section:** Skip this check entirely.
+
+**If Language Profile exists:** Parse settings and validate spec compliance.
+
+### 3.10.1 File Count Check
+
+Extract `Max files per spec` from profile. Count total files to create + modify in spec.
+
+| Condition | Action |
+|-----------|--------|
+| Files ≤ max | ✓ OK |
+| Files = max + 1-2 | **Warning**: "File count ({N}) slightly exceeds language profile limit ({max}). Consider splitting." |
+| Files > max + 2 | **Critical**: "File count ({N}) significantly exceeds language profile limit ({max}). Must split with `/sf:split`." |
+
+### 3.10.2 Trait-First Check
+
+If `Trait-first: Yes` AND spec complexity is medium or large:
+
+- Check if Implementation Tasks section exists
+- If yes: verify G1 (Wave 1) contains ONLY types/traits/interfaces, not implementation
+- If G1 mixes traits and implementation: **Critical**: "Trait-first violation: G1 must contain only types/traits/interfaces. Implementation must be in Wave 2+."
+- If no Implementation Tasks: **Warning**: "Trait-first language requires explicit task grouping for medium/large specs. Recommend adding Implementation Tasks with types in G1."
+
+### 3.10.3 Compilation Gate Awareness
+
+If `Compilation gate: Yes`:
+
+- Verify task groups are small enough for incremental compilation checks
+- If any single task group modifies >3 files: **Warning**: "Large task group ({N} files) with compilation gate. Consider splitting into smaller groups for incremental `build_check` verification."
+
+### 3.10.4 Scope Threshold Override
+
+If Language Profile exists, override default Scope Sanity Thresholds:
+
+| Metric | Default | With Language Profile |
+|--------|---------|---------------------|
+| Files/plan (Blocker) | 15+ | `Max files per spec` from profile |
+| Tasks/plan (Warning) | 4 | 3 (if `Trait-first: Yes`) |
+
+### 3.10.5 Language Profile Verdict
+
+**If all checks pass:**
+- Add to audit output: "Language profile: ✓ Compliant with {Language} profile"
+
+**If warnings or critical issues found:**
+- Add issues to appropriate category (Critical/Recommendations)
+
 ## Step 4: Generate Implementation Tasks (for large specs)
 
 If scope is large, generate the Implementation Tasks section:
@@ -634,6 +685,14 @@ Update status:
 - If NEEDS_DECOMPOSITION: Status → "needs_decomposition", Next Step → "/sf:split or /sf:run --parallel"
 - If NEEDS_REVISION: Status → "revision_requested", Next Step → "/sf:revise"
 
+Update STATE.md by reading the current file content, then writing the updated file with:
+- "**Status:**" line changed to the new status
+- "**Next Step:**" line changed to the new next step
+- No other content modified
+
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 </process>
 
 <output>
@@ -738,6 +797,7 @@ Tip: `/clear` recommended before `/sf:run` — executor needs fresh context
 - [ ] Specification fully read
 - [ ] PROJECT.md context loaded
 - [ ] All 10 dimensions evaluated (clarity, completeness, testability, scope, feasibility, architecture, duplication, cognitive load, strategic fit, project compliance)
+- [ ] Language profile checked (if present in PROJECT.md)
 - [ ] Assumptions extracted and impact assessed
 - [ ] Project alignment verified
 - [ ] Project compliance verified (decisions, constraints, out-of-scope)

package/agents/spec-creator.md

@@ -42,6 +42,26 @@ Good specifications are:
 | medium | 50-150k | Multiple files, moderate feature |
 | large | >150k | Many files, complex feature — needs /sf:split |
 
+## Language Profile Awareness
+
+If PROJECT.md contains a `## Language Profile` section, adapt behavior:
+
+**Max files per spec:** If `Max files per spec` is set (e.g., 5 for Rust), use it for complexity estimation. A spec exceeding this limit should be flagged as needing `/sf:split`.
+
+**Trait-first:** If `Trait-first: Yes`, for medium and large specs:
+- First task group (G1, Wave 1) MUST be types/traits/interfaces only
+- Implementation groups depend on G1
+- This ensures trait design is audited before implementation begins
+
+**Language-specific sizing:**
+
+| Language | Max Files | Trait-First | Notes |
+|----------|-----------|-------------|-------|
+| Rust | 3-5 | Yes | Borrow checker errors cascade; smaller specs essential |
+| Go | 5-8 | Yes | Interface design drives implementation |
+| TypeScript | 8-10 | No | Dynamic typing allows larger specs |
+| Python | 8-10 | No | Dynamic typing allows larger specs |
+
 </philosophy>
 
 <process>
@@ -136,6 +156,12 @@ Write to `.specflow/specs/SPEC-XXX.md` using the template structure:
 - **Medium** and **large** complexity specs: Always include Implementation Tasks section
 - **Small** complexity specs: Optional (skip if only 1-2 files or simple change)
 
+**Language Profile Override:**
+If PROJECT.md has `Trait-first: Yes` in Language Profile:
+- G1 (Wave 1) MUST contain ONLY types/traits/interfaces — no implementation
+- All implementation groups MUST depend on G1
+- This is mandatory, not a suggestion — trait design errors cascade in compiled languages
+
 **Task Groups:**
 
 1. Group related work logically:
@@ -215,6 +241,16 @@ Update `.specflow/STATE.md`:
 - Set Next Step to "/sf:audit"
 - Add spec to Queue
 
+Update STATE.md by reading the current file content, then writing the updated file with:
+- "**Active Specification:**" line changed to the new spec
+- "**Status:**" line changed to "drafting"
+- "**Next Step:**" line changed to "/sf:audit"
+- Queue table updated with new spec entry
+- No other content modified
+
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 **If `<prior_discussion>` provided:**
 Update the discussion file (PRE-XXX.md or DISC-XXX.md):
 - Set `used_by: SPEC-XXX` in frontmatter

package/agents/spec-executor-orchestrator.md

@@ -330,6 +330,10 @@ Write `.specflow/execution/SPEC-XXX-state.json`:
 | SPEC-XXX | orchestrated | Wave 0/{total} (0%) | {timestamp} |
 ```
 
+Update STATE.md by reading the current file content, then writing the updated file with the Execution Status table row added/updated.
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 ## Step 3: Execute Waves
 
 For each wave:
@@ -597,6 +601,10 @@ After wave completes (all groups done):
 | SPEC-XXX | orchestrated | Wave 2/{total} (67%) | {timestamp} |
 ```
 
+Update STATE.md by reading the current file content, then writing the updated file with the Execution Status table row updated for this wave.
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 ## Step 4: Aggregate Results
 
 Combine all worker results:
@@ -683,6 +691,10 @@ rm .specflow/execution/SPEC-XXX-state.json
 - Change row to show "Complete" or remove row entirely
 - Or archive: `mv .specflow/execution/SPEC-XXX-state.json .specflow/execution/archive/`
 
+Update STATE.md by reading the current file content, then writing the updated file with the Execution Status table row removed or updated to "Complete".
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 **Note:** Only delete on FULL success. If any groups failed or are partial, keep state file for potential retry.
 
 ## Step 7: Update STATE.md
@@ -692,6 +704,15 @@ Update ONLY the Current Position section:
 - Next Step → "/sf:review"
 - Remove or update Execution Status row
 
+Update STATE.md by reading the current file content, then writing the updated file with:
+- "**Status:**" line changed to the new status
+- "**Next Step:**" line changed to the new next step
+- Execution Status row removed or updated
+- No other content modified
+
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 **CRITICAL — DO NOT go beyond this:**
 - Do NOT move the spec to Completed Specifications table
 - Do NOT remove the spec from Queue table

package/agents/spec-executor-worker.md

@@ -122,6 +122,22 @@ After implementing, verify:
 - Follows project conventions
 - Meets task requirements
 
+### 3.2.1 Compilation Gate (Language Profile)
+
+If PROJECT.md has `Compilation gate: Yes` in Language Profile:
+
+After implementing each file or tightly coupled group, run the `Build check` command:
+
+```bash
+# Example for Rust: cargo check
+# Example for Go: go build ./...
+```
+
+**If build fails:** fix immediately (Rule 3: Auto-fix blocking issues). Do NOT proceed until current file compiles.
+**If build passes:** continue to next file.
+
+At end of all tasks in this group: run `Lint` command if specified in profile (e.g., `cargo clippy -- -D warnings`).
+
 ### 3.3 Commit
 
 Create atomic commit:
@@ -189,10 +205,13 @@ Output structured JSON for orchestrator:
   ],
   "deviations": [],
   "self_check": "passed",
+  "build_check": "passed",
   "error": null
 }
 ```
 
+**Note:** `build_check` field is only included when Language Profile has `Compilation gate: Yes`. Values: `"passed"`, `"fixed"` (had to fix compilation errors), `"skipped"` (no language profile).
+
 **For segmented execution, add segment fields:**
 
 ```json

package/agents/spec-executor.md

@@ -131,6 +131,28 @@ After implementing, verify:
 - Meets relevant acceptance criteria
 - Follows project conventions
 
+### 4.2.1 Compilation Gate (Language Profile)
+
+If PROJECT.md has `Compilation gate: Yes` in Language Profile:
+
+After implementing each file or tightly coupled group of files, run the `Build check` command from the profile:
+
+```bash
+# Example for Rust:
+cargo check
+# Example for Go:
+go build ./...
+```
+
+**If build fails:**
+- Fix the compilation error immediately (Rule 3: Auto-fix blocking issues)
+- Do NOT proceed to next file until current file compiles
+- Track as: `[Rule 3 - Compilation] Fixed {error} in {file}`
+
+**If build passes:** continue to next file.
+
+This prevents cascading errors — especially critical for Rust where borrow checker errors in file A can mask the real issue in file B.
+
 ### 4.3 Commit
 
 Create atomic commit:
@@ -191,7 +213,16 @@ For key modifications, verify the change is present:
 grep -q "expected_pattern" path/to/modified/file && echo "VERIFIED" || echo "NOT FOUND"
 ```
 
-**4. Report self-check result:**
+**4. Language profile checks (if Language Profile exists in PROJECT.md):**
+
+Run each configured command and verify it passes:
+- `Lint` command (e.g., `cargo clippy -- -D warnings`) → must exit 0
+- `Test` command (e.g., `cargo test`) → must exit 0
+- `Safety check` command if present (e.g., `cargo miri test`) → must exit 0
+
+If any check fails: fix the issue before proceeding (Rule 3).
+
+**5. 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
@@ -237,6 +268,14 @@ Update ONLY the Current Position section:
 - Status → "review"
 - Next Step → "/sf:review"
 
+Update STATE.md by reading the current file content, then writing the updated file with:
+- "**Status:**" line changed to the new status
+- "**Next Step:**" line changed to the new next step
+- No other content modified
+
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 **CRITICAL — DO NOT go beyond this:**
 - Do NOT move the spec to Completed Specifications table
 - Do NOT remove the spec from Queue table

package/agents/spec-reviser.md

@@ -139,6 +139,14 @@ Set status to "auditing" (ready for re-audit).
 - Status → "auditing"
 - Next Step → "/sf:audit"
 
+Update STATE.md by reading the current file content, then writing the updated file with:
+- "**Status:**" line changed to the new status
+- "**Next Step:**" line changed to the new next step
+- No other content modified
+
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 </process>
 
 <output>

package/agents/spec-splitter.md

@@ -188,6 +188,16 @@ Update `.specflow/STATE.md`:
 - Set first child (no dependencies) as Active Specification
 - Add note to Decisions: "Split SPEC-XXX into N parts"
 
+Update STATE.md by reading the current file content, then writing the updated file with:
+- Parent spec removed from Queue table
+- All child specs added to Queue table in dependency order
+- First child (no dependencies) set as Active Specification
+- Decisions section updated with split note
+- No other content modified
+
+Use the Read tool to read `.specflow/STATE.md`, then use the Write tool to write the updated content.
+Do NOT use Bash (awk, sed, or echo) to modify `.specflow/STATE.md`.
+
 </process>
 
 <output>

package/commands/sf/audit.md

@@ -242,75 +242,17 @@ The agent will:
 
 After the agent updates STATE.md, check if rotation is needed:
 
-```bash
-LINE_COUNT=$(wc -l < .specflow/STATE.md)
-if [ $LINE_COUNT -gt 100 ]; then
-    echo "STATE.md exceeds 100 lines ($LINE_COUNT), rotating old decisions..."
-
-    # Parse decisions table and extract all decisions
-    DECISIONS=$(awk '/^## Decisions$/ { found=1; next } /^## / && found { exit } found { print }' .specflow/STATE.md | grep -E '^\| [0-9]{4}-' || true)
-    DECISION_COUNT=$(echo "$DECISIONS" | grep -c '^|' || echo 0)
-
-    if [ "$DECISION_COUNT" -gt 7 ]; then
-        # Keep only 5 most recent decisions
-        RECENT_DECISIONS=$(echo "$DECISIONS" | tail -5)
-        OLD_DECISION_COUNT=$((DECISION_COUNT - 5))
-        OLD_DECISIONS=$(echo "$DECISIONS" | head -n $OLD_DECISION_COUNT)
-
-        # Create or append to archive
-        if [ ! -f .specflow/DECISIONS_ARCHIVE.md ]; then
-            cat > .specflow/DECISIONS_ARCHIVE.md << 'EOF'
-# SpecFlow Decisions Archive
-
-Historical decisions rotated from STATE.md to maintain compactness.
-
-## Archived Decisions
-
-| Date | Decision |
-|------|----------|
-EOF
-        fi
-
-        # Write old decisions to temp file for awk to read (awk -v cannot handle multiline strings)
-        TEMP_OLD=$(mktemp)
-        echo "$OLD_DECISIONS" > "$TEMP_OLD"
-
-        # Append old decisions to archive (insert after table header)
-        TEMP_ARCHIVE=$(mktemp)
-        awk -v oldfile="$TEMP_OLD" '
-            /^\| Date \| Decision \|$/ { print; getline; print; while ((getline line < oldfile) > 0) print line; close(oldfile); next }
-            {print}
-        ' .specflow/DECISIONS_ARCHIVE.md > "$TEMP_ARCHIVE"
-        mv "$TEMP_ARCHIVE" .specflow/DECISIONS_ARCHIVE.md
-        rm -f "$TEMP_OLD"
-
-        # Write recent decisions to temp file for awk to read
-        TEMP_RECENT=$(mktemp)
-        echo "$RECENT_DECISIONS" > "$TEMP_RECENT"
-
-        # Update STATE.md with only recent decisions
-        TEMP_STATE=$(mktemp)
-        awk -v recentfile="$TEMP_RECENT" '
-            /^## Decisions$/ {
-                print
-                print ""
-                print "| Date | Decision |"
-                print "|------|----------|"
-                while ((getline line < recentfile) > 0) print line
-                close(recentfile)
-                in_decisions=1
-                next
-            }
-            /^## / && in_decisions { in_decisions=0 }
-            !in_decisions || !/^\|/ { print }
-        ' .specflow/STATE.md > "$TEMP_STATE"
-        mv "$TEMP_STATE" .specflow/STATE.md
-        rm -f "$TEMP_RECENT"
-
-        echo "Rotated $(echo "$OLD_DECISIONS" | grep -c '^|') old decisions to DECISIONS_ARCHIVE.md"
-    fi
-fi
-```
+1. Use the Read tool to read `.specflow/STATE.md` and count total lines
+2. If total lines <= 100, no action needed
+3. If total lines > 100:
+   a. Read the `## Decisions` section and extract all decision rows (lines matching `| YYYY-`)
+   b. Count decision rows. If <= 7, no rotation needed
+   c. If > 7 decisions:
+      - Identify the 5 most recent decisions (last 5 rows) -- these STAY
+      - Identify older decisions (all rows except last 5) -- these MOVE to archive
+      - Read `.specflow/DECISIONS_ARCHIVE.md` (create with template if missing)
+      - Write updated DECISIONS_ARCHIVE.md: insert old decisions after the table header row
+      - Write updated STATE.md: replace Decisions section content with only the 5 most recent decisions
 
 ## Step 7: Display Result