specflow-cc 1.12.0 → 1.14.0

package/commands/sf/done.md

@@ -175,7 +175,7 @@ mkdir -p .specflow/archive
 Update frontmatter:
 - status → "done"
 
-Add completion timestamp:
+Add completion summary section to the spec:
 
 ```markdown
 ---
@@ -185,14 +185,33 @@ Add completion timestamp:
 **Completed:** {date} {time}
 **Total Commits:** {count from Execution Summary}
 **Review Cycles:** {count of Review v[N] entries}
+
+### Outcome
+
+{1-2 sentence summary of what was delivered}
+
+### Key Files
+
+- `{path}` — {what it does/why it matters}
+
+### Patterns Established
+
+{List any new patterns, conventions, or architectural decisions introduced.
+If none: "None — followed existing patterns."}
+
+### Deviations
+
+{Any deviations from the original spec during implementation.
+If none: "None — implemented as specified."}
 ```
 
 ## Step 7: Extract Decisions
 
-Scan specification for important decisions:
+Scan specification and Completion section for important decisions:
 - Technology choices mentioned in Context or Assumptions
 - Patterns established during implementation
 - Constraints discovered
+- Deviations that became new conventions
 
 If significant decisions found, add to STATE.md Decisions table:
 
@@ -228,75 +247,17 @@ If implementation established new patterns, add to Project Patterns section.
 
 After updating 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 10: Create Final Commit (if needed)
 

package/commands/sf/health.md

@@ -0,0 +1,220 @@
+---
+name: sf:health
+description: Diagnose .specflow/ directory health and optionally repair issues
+argument-hint: [--repair]
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Write
+  - AskUserQuestion
+---
+
+<purpose>
+Validate `.specflow/` directory integrity and report actionable issues. Checks for missing files, invalid state, orphaned specs, and queue inconsistencies. Optionally repairs auto-fixable issues.
+</purpose>
+
+<context>
+@.specflow/STATE.md
+</context>
+
+<workflow>
+
+## Step 1: Verify Initialization
+
+```bash
+[ -d .specflow ] && echo "OK" || echo "NOT_INITIALIZED"
+```
+
+**If NOT_INITIALIZED:**
+```
+SpecFlow not initialized. Run `/sf:init` first.
+```
+Exit.
+
+## Step 2: Parse Arguments
+
+Check if `--repair` flag is present.
+
+## Step 3: Run Health Checks
+
+Initialize collectors:
+- `errors[]` — critical issues
+- `warnings[]` — non-critical issues
+- `info[]` — informational notes
+- `repairs[]` — actions taken (if --repair)
+
+### 3.1 Core Files Check
+
+| Check | File | Severity | Repairable |
+|-------|------|----------|------------|
+| E001 | `.specflow/STATE.md` missing | error | Yes — regenerate minimal STATE.md |
+| E002 | `.specflow/STATE.md` missing `## Queue` section | error | No |
+| W001 | `.specflow/todos/TODO.md` missing | warning | Yes — create empty TODO.md |
+| W002 | `.specflow/specs/` directory missing | warning | Yes — create directory |
+| W003 | `.specflow/archive/` directory missing | warning | Yes — create directory |
+| W004 | `.specflow/execution/` directory missing | warning | Yes — create directory |
+
+For each check:
+1. Test existence
+2. If missing and repairable and `--repair`: fix it, add to `repairs[]`
+3. If missing and not repairable: add to `errors[]` or `warnings[]`
+
+### 3.2 STATE.md Integrity
+
+Read STATE.md and validate:
+
+**E003: Active spec references non-existent file**
+- Extract active spec ID from `## Active Specification`
+- If not "—" or empty, check `.specflow/specs/{ID}.md` exists
+- If missing: error (repairable — clear active spec to "—")
+
+**W005: Queue references non-existent spec file**
+- Parse queue table rows
+- For each spec ID, verify `.specflow/specs/{ID}.md` or `.specflow/archive/{ID}.md` exists
+- If missing: warning (not repairable — spec may have been manually deleted)
+
+**W006: Queue has duplicate spec IDs**
+- Parse all IDs from queue table
+- If duplicates found: warning (not repairable)
+
+**W007: STATUS.md malformed — missing required sections**
+- Check for: `## Active Specification`, `## Queue`
+- If missing: warning
+
+### 3.3 Orphaned Specs Check
+
+**I001: Spec file exists but not in queue or archive**
+- List all files in `.specflow/specs/`
+- For each, check if its ID appears in STATE.md queue
+- If not: info (may be work-in-progress)
+
+### 3.4 Archive Consistency
+
+**I002: Spec in queue marked as completed but not archived**
+- Parse queue for specs with status containing "done" or "complete"
+- Check if file exists in `.specflow/archive/`
+- If not: info
+
+### 3.5 Execution State
+
+**W008: Stale execution state files**
+- List `.specflow/execution/*.json`
+- For each, check if the spec ID is the currently active spec
+- If not active: warning (repairable — delete stale files)
+
+## Step 4: Calculate Status
+
+```
+HEALTHY  = 0 errors, 0 warnings
+DEGRADED = 0 errors, 1+ warnings
+BROKEN   = 1+ errors
+```
+
+## Step 5: Display Results
+
+**IMPORTANT:** Output the following directly as formatted text, NOT wrapped in a markdown code block:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecFlow Health Check
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Status:** HEALTHY | DEGRADED | BROKEN
+**Errors:** N | **Warnings:** N | **Info:** N
+```
+
+**If repairs were performed:**
+```
+### Repairs Performed
+
+- Repaired: {description}
+- Repaired: {description}
+```
+
+**If errors exist:**
+```
+### Errors
+
+- [{code}] {message}
+  Fix: {suggested fix}
+```
+
+**If warnings exist:**
+```
+### Warnings
+
+- [{code}] {message}
+  Fix: {suggested fix}
+```
+
+**If info exists:**
+```
+### Info
+
+- [{code}] {message}
+```
+
+**Footer (if repairable issues exist and --repair was NOT used):**
+```
+---
+{N} issues can be auto-repaired. Run: `/sf:health --repair`
+```
+
+## Step 6: Offer Repair (if applicable)
+
+If repairable issues found and `--repair` was NOT passed:
+- Ask user if they want to run repairs
+- If yes, execute repairs and re-run checks to verify
+
+## Step 7: Verify Repairs (if --repair was used)
+
+Re-run all checks without repair to confirm resolution.
+Display final status.
+
+</workflow>
+
+<error_codes>
+
+| Code | Severity | Description | Repairable |
+|------|----------|-------------|------------|
+| E001 | error | STATE.md not found | Yes |
+| E002 | error | STATE.md missing Queue section | No |
+| E003 | error | Active spec references non-existent file | Yes |
+| W001 | warning | TODO.md not found | Yes |
+| W002 | warning | specs/ directory missing | Yes |
+| W003 | warning | archive/ directory missing | Yes |
+| W004 | warning | execution/ directory missing | Yes |
+| W005 | warning | Queue references non-existent spec | No |
+| W006 | warning | Queue has duplicate spec IDs | No |
+| W007 | warning | STATE.md missing required sections | No |
+| W008 | warning | Stale execution state files | Yes |
+| I001 | info | Spec not in queue (may be WIP) | No |
+| I002 | info | Completed spec not archived | No |
+
+</error_codes>
+
+<repair_actions>
+
+| Action | Effect | Risk |
+|--------|--------|------|
+| Create STATE.md | Minimal template with empty queue | None |
+| Create TODO.md | Empty TODO template | None |
+| Create directories | specs/, archive/, execution/ | None |
+| Clear active spec | Set to "—" if spec file missing | Loses active reference |
+| Delete stale execution | Remove orphaned .json state files | None |
+
+**Not repairable (too risky):**
+- STATE.md content/queue entries
+- Spec file contents
+- Archive decisions
+
+</repair_actions>
+
+<success_criteria>
+- [ ] All health checks executed
+- [ ] Clear status reported (HEALTHY/DEGRADED/BROKEN)
+- [ ] Each issue has error code and suggested fix
+- [ ] --repair only fixes safe, non-destructive issues
+- [ ] Repairs verified by re-running checks
+</success_criteria>

package/commands/sf/help.md

@@ -226,6 +226,7 @@ Workflow: Spec → Audit → Revise → Run → Review → Fix → Done
 | /sf:revise   | Revise spec based on audit feedback     |
 | /sf:run      | Execute specification                   |
 | /sf:review   | Review implementation (fresh context)   |
+| /sf:validate | Run validation checklist from spec      |
 | /sf:verify   | Interactive human verification          |
 | /sf:fix      | Fix implementation based on review      |
 | /sf:done     | Finalize, commit, and archive           |
@@ -236,6 +237,12 @@ Workflow: Spec → Audit → Revise → Run → Review → Fix → Done
 |--------------|-----------------------------------------|
 | /sf:quick    | Execute minor tasks (1-3 files) fast    |
 
+## Autonomous Execution
+
+| Command      | Description                             |
+|--------------|-----------------------------------------|
+| /sf:autopilot | Run full lifecycle autonomously         |
+
 ## Navigation
 
 | Command      | Description                             |
@@ -282,6 +289,7 @@ Workflow: Spec → Audit → Revise → Run → Review → Fix → Done
 | Command      | Description                             |
 |--------------|-----------------------------------------|
 | /sf:help     | This help (or detailed: /sf:help new)   |
+| /sf:health   | Diagnose .specflow/ integrity (--repair)|
 | /sf:history  | View completed specifications           |
 | /sf:metrics  | Project statistics and insights         |
 
@@ -296,6 +304,7 @@ Workflow: Spec → Audit → Revise → Run → Review → Fix → Done
 5. `/sf:run` — Implement
 6. `/sf:review` — Review implementation
 7. `/sf:done` — Complete and archive
+8. Or skip steps 4-7: `/sf:autopilot` -- run everything autonomously
 
 ## Typical Session
 
@@ -309,6 +318,13 @@ Workflow: Spec → Audit → Revise → Run → Review → Fix → Done
 /sf:done          # Complete
 ```
 
+## Autonomous Alternative
+
+```
+/sf:autopilot          # Process active spec end-to-end
+/sf:autopilot --all    # Process entire queue
+```
+
 ---
 
 **Detailed help:** `/sf:help <command>`

package/commands/sf/review.md

@@ -129,75 +129,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 8: Display Result
 

package/commands/sf/revise.md

@@ -156,13 +156,10 @@ Continue to Step 5 with analysis context available.
 | "..." | Treat as custom revision instructions |
 
 **Check for `--no-analysis` flag:**
-```bash
-if echo "$ARGS" | grep -q "\-\-no-analysis"; then
-    SKIP_ANALYSIS=true
-    # Remove flag from args for further processing
-    ARGS=$(echo "$ARGS" | sed 's/--no-analysis//g' | xargs)
-fi
-```
+
+If the arguments string contains `--no-analysis`:
+- Set SKIP_ANALYSIS to true
+- Remove the `--no-analysis` flag from the arguments string for further processing
 
 ### If Interactive Mode (no arguments):
 

package/commands/sf/run.md

@@ -251,75 +251,17 @@ The agent will:
 
 After updating 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 10: Display Result
 

package/commands/sf/split.md

@@ -201,9 +201,20 @@ Your choice [1]:
 
 **If 1 (Accept):**
 - Agent creates child specifications
-- Agent archives parent
-- Agent updates STATE.md
-- Continue to Step 7
+- Agent archives parent and updates STATE.md
+- **Verify archival:** After agent completes, check if parent was moved:
+
+```bash
+if [ -f ".specflow/specs/{ID}.md" ]; then
+  mkdir -p .specflow/archive
+  mv ".specflow/specs/{ID}.md" ".specflow/archive/{ID}.md"
+  echo "ARCHIVED"
+else
+  echo "ALREADY_ARCHIVED"
+fi
+```
+
+- Continue to Step 8
 
 **If 2 (Modify):**
 - Use AskUserQuestion to get modifications