sdlc-framework 2.1.1 → 3.1.0

package/src/commands/spec.md

@@ -78,16 +78,18 @@ Step-by-step:
    - Option C (do nothing / defer): description, risk of deferring.
    Ask the user to choose before proceeding.
 
-5. **Define acceptance criteria in BDD format**
-   Write Given/When/Then scenarios for each user-facing behavior:
+5. **Define acceptance criteria in BDD format with verification type**
+   Write Given/When/Then scenarios for each user-facing behavior. Every AC MUST include a `Type` field that declares how the verify phase will test it:
    ```
    AC-1: [Short title]
+   Type: [UI_INTERACTION | API_ENDPOINT | CLI_BEHAVIOR | BUSINESS_LOGIC | DATA_INTEGRITY]
    Given [precondition]
    When [action]
    Then [expected outcome]
    ```
+   The Type field is mandatory — it tells `/sdlc:verify` whether to use Playwright MCP, curl, Bash, the test runner, or DB queries. Without it, the AC will be skipped during verification.
    Include happy path, error cases, and edge cases.
-   Present acceptance criteria to the user and ask: "Do these cover all cases? Anything to add or change?"
+   Present acceptance criteria with their types to the user and ask: "Do these cover all cases? Are the verification types correct?"
 
 6. **Break into tasks with dependency analysis**
    - List every discrete task needed to implement the spec.
@@ -106,7 +108,16 @@ Step-by-step:
    - What is OUT of scope.
    - What is DEFERRED to a future plan.
 
-8. **Write SPEC.md**
+8. **Codebase gap analysis — MANDATORY**
+   Read every file listed in the task breakdown. Review existing code for:
+   - Missing error handling that the spec should cover.
+   - Untested code paths that need new ACs.
+   - Edge cases the existing code handles but the spec does not mention.
+   - Integration risks (callers of modified functions, shared state, exports).
+   - Validation gaps at system boundaries.
+   Present a gap report to the user. Add new ACs (with verification_type) and update tasks for every gap found.
+
+9. **Write SPEC.md**
    Create .sdlc/specs/SPEC-<plan-id>.md with:
    ```
    # Spec: <title>
@@ -123,45 +134,51 @@ Step-by-step:
    ## Engineering Constraints (from LAWS.md)
    ```
 
-9. **Spec integrity review — MANDATORY, DO NOT SKIP**
-   You MUST print a full integrity review table with ✓/✗ for EACH check:
-   - CHECK 1 — COMPLETENESS: every task has name, action, files, verification, done criteria, complexity. Every AC has numbered GIVEN/WHEN/THEN with specific values.
-   - CHECK 2 — CONSISTENCY: no orphan tasks (every task → AC), no orphan ACs (every AC → task), no boundary violations, no DAG cycles, no shared-file parallel writes.
-   - CHECK 3 — CONTRADICTIONS: no conflicting ACs for same input, no conflicting task actions on same function, no task contradicting boundary, no AC contradicting PROJECT.md constraints.
-   - CHECK 4 — FEASIBILITY: task count 2-5, estimated change under ~300 lines, all referenced files exist.
-   - CHECK 5 — DEPENDENCY GRAPH: every task in exactly one wave, ordering matches dependencies, independent tasks parallelized, dependent tasks sequenced.
-   - Print the full review table with all results. Fix any failures before proceeding.
-
-10. **User approval gate** (BLOCKING — cannot proceed without approval)
+10. **Spec integrity review — MANDATORY, DO NOT SKIP**
+    You MUST print a full integrity review table with ✓/✗ for EACH check:
+    - CHECK 1 — COMPLETENESS: every task has name, action, files, verification, done criteria, complexity. Every AC has numbered Type/GIVEN/WHEN/THEN with specific values.
+    - CHECK 2 — CONSISTENCY: no orphan tasks (every task → AC), no orphan ACs (every AC → task), no boundary violations, no DAG cycles, no shared-file parallel writes.
+    - CHECK 3 — CONTRADICTIONS: no conflicting ACs for same input, no conflicting task actions on same function, no task contradicting boundary, no AC contradicting PROJECT.md constraints.
+    - CHECK 4 — FEASIBILITY: task count 2-5, estimated change under ~300 lines, all referenced files exist.
+    - CHECK 5 — DEPENDENCY GRAPH: every task in exactly one wave, ordering matches dependencies, independent tasks parallelized, dependent tasks sequenced.
+    - CHECK 6 — VERIFICATION TYPES: every AC has a valid Type field (UI_INTERACTION, API_ENDPOINT, CLI_BEHAVIOR, BUSINESS_LOGIC, DATA_INTEGRITY). Type matches AC content.
+    - CHECK 7 — GAP ANALYSIS: codebase gap analysis was performed, gaps were reported, and findings were incorporated into ACs/tasks.
+    - Print the full review table with all results. Fix any failures before proceeding.
+
+11. **User approval gate** (BLOCKING — cannot proceed without approval)
     - Present full spec summary AND integrity review results to user
     - User options: APPROVE (proceed), REVISE (change and re-review), REJECT (discard)
     - If REVISE: apply changes, re-run ALL integrity checks, re-present
     - If REJECT: delete spec, stop
     - If APPROVE: proceed to update state
 
-11. **Update STATE.md**
+12. **Update STATE.md**
     - Set `current_plan: <plan-id>`
     - Set `spec_path: .sdlc/phases/{phase}/{plan}-SPEC.md`
     - Set `loop_position: SPEC ✓`
     - Set `next_required_action: /sdlc:impl`
 
-12. **Output confirmation**
-    - Print spec summary: objective, number of ACs, number of tasks, execution waves.
-    - End with NEXT ACTION REQUIRED: /sdlc:impl
+13. **Output confirmation**
+    - Print spec summary: objective, number of ACs (with verification type breakdown), number of tasks, execution waves.
+    - End with auto-advance directive to /sdlc:impl
 </process>
 
 <success_criteria>
 - [ ] At least 2 clarification questions asked before writing the spec
 - [ ] Every design decision presented with trade-offs and user confirmation
-- [ ] Acceptance criteria written in BDD format (Given/When/Then)
+- [ ] Acceptance criteria written in BDD format (Given/When/Then) with mandatory Type field
+- [ ] Every AC has a verification_type: UI_INTERACTION, API_ENDPOINT, CLI_BEHAVIOR, BUSINESS_LOGIC, or DATA_INTEGRITY
+- [ ] Verification types match AC content (UI ACs test browser state, API ACs test endpoints, etc.)
 - [ ] Acceptance criteria cover happy path, error cases, and edge cases
 - [ ] Tasks broken into dependency graph with execution waves
 - [ ] Each task identifies files to create/modify and complexity
 - [ ] Boundaries section explicitly states in-scope, out-of-scope, and deferred items
-- [ ] Spec integrity review passed (completeness, consistency, feasibility)
+- [ ] Codebase gap analysis performed — existing code reviewed for missing logic, edge cases, and integration risks
+- [ ] Gap analysis findings incorporated into ACs and tasks (no silent gaps)
+- [ ] Spec integrity review passed (completeness, consistency, feasibility, verification types, gap analysis)
 - [ ] User explicitly approved the spec (APPROVE response received)
 - [ ] SPEC.md created at .sdlc/phases/{phase}/{plan}-SPEC.md
 - [ ] STATE.md updated with current_plan, spec_path, loop_position: SPEC ✓
 - [ ] No assumptions made — every ambiguity resolved via clarification
-- [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:impl
+- [ ] Output ends with auto-advance directive to /sdlc:impl
 </success_criteria>

package/src/commands/status.md

@@ -65,7 +65,7 @@ Step-by-step:
 4. Verify git state matches handoff (warn on mismatch). Pop stash if applicable.
 5. Archive consumed handoff to .sdlc/HANDOFF-{timestamp}.md.archived.
 6. Clean up STATE.md session fields (remove paused_at).
-7. Force ONE next action. Output ends with NEXT ACTION REQUIRED.
+7. Force ONE next action. End with auto-advance directive to the forced next action.
 </process>
 
 <success_criteria>
@@ -79,6 +79,6 @@ Step-by-step:
 - [ ] Resume: handoff located and context restored
 - [ ] Resume: git state verified against handoff
 - [ ] Resume: handoff archived after consumption
-- [ ] Resume: output ends with NEXT ACTION REQUIRED: /sdlc:{action}
+- [ ] Resume: output ends with auto-advance directive to /sdlc:{action}
 - [ ] No menus, no options — one clear path forward
 </success_criteria>

package/src/commands/verify.md

@@ -49,18 +49,18 @@ Step-by-step:
    - Read SPEC.md. Extract all acceptance criteria (AC-1, AC-2, ...).
    - Read IMPL.md for the list of modified files and build status.
 
-2. **Classify each acceptance criterion by verification type**
-   For each AC, determine the appropriate test strategy:
-
-   | Work Type | Verification Method | Tools Used |
-   |-----------|-------------------|------------|
-   | UI/Frontend | Playwright MCP browser automation | browser_navigate, browser_click, browser_snapshot, browser_fill_form |
-   | REST API | HTTP requests via curl or fetch | Bash (curl commands) |
-   | GraphQL API | GraphQL queries via HTTP | Bash (curl commands) |
-   | CLI tool | Shell command execution | Bash |
-   | Business logic | Test runner (jest, vitest, pytest, etc.) | Bash (npm test, etc.) |
-   | Database | Query verification | Bash (database CLI tools) |
-   | File output | File content inspection | Read, Grep |
+2. **Read verification types from SPEC.md — DO NOT GUESS**
+   Each AC in the SPEC.md has a declared `Type` field. Read it directly. Do NOT infer or guess the type from keywords.
+
+   | AC Type (from SPEC.md) | Verification Tool | Actions |
+   |------------------------|------------------|---------|
+   | UI_INTERACTION | Playwright MCP | browser_navigate, browser_snapshot, browser_click, browser_fill_form, browser_take_screenshot |
+   | API_ENDPOINT | Bash curl | HTTP requests, response parsing |
+   | CLI_BEHAVIOR | Bash | Shell commands, stdout/stderr/exit code capture |
+   | BUSINESS_LOGIC | Test runner | bun test, npm test, vitest, jest, pytest |
+   | DATA_INTEGRITY | DB CLI | Database queries via Bash |
+
+   If any AC is missing its Type field, mark it FAIL immediately — do not skip it or guess.
 
 3. **Execute UI verifications (Playwright MCP)**
    For each UI acceptance criterion:
@@ -132,22 +132,28 @@ Step-by-step:
    - If ALL acceptance criteria pass:
      - Update STATE.md: set `loop_position: VERIFY_COMPLETE`
      - Set `verify_path: .sdlc/verify/VERIFY-<plan-id>.md`
-     - Output ends with: NEXT ACTION REQUIRED: /sdlc:review
+     - End with auto-advance directive to /sdlc:review
    - If ANY acceptance criteria fail:
      - Update STATE.md: set `loop_position: VERIFY_FAILED`
      - Output the failure details with suggested fixes.
      - Output ends with: "Fix the failures above, then re-run /sdlc:verify"
+     - Do NOT auto-advance on failure — the user must fix issues first.
 </process>
 
 <success_criteria>
 - [ ] Every acceptance criterion from SPEC.md has a corresponding verification
-- [ ] Correct verification type selected per AC (UI uses Playwright, API uses curl, etc.)
-- [ ] UI tests use Playwright MCP tools (navigate, snapshot, click, fill_form, screenshot)
+- [ ] Verification type READ from each AC's Type field — not guessed from keywords
+- [ ] ACs with Type: UI_INTERACTION verified using Playwright MCP tools (navigate, snapshot, click, fill_form, screenshot)
+- [ ] ACs with Type: API_ENDPOINT verified using curl commands
+- [ ] ACs with Type: CLI_BEHAVIOR verified using Bash command execution
+- [ ] ACs with Type: BUSINESS_LOGIC verified using the project test runner
+- [ ] ACs with Type: DATA_INTEGRITY verified using database queries
+- [ ] ACs missing a Type field marked FAIL — not skipped, not guessed
 - [ ] Each verification produces concrete evidence (screenshots, response bodies, test output)
 - [ ] VERIFY-<plan-id>.md created with per-AC pass/fail results
 - [ ] Failed ACs include: expected vs actual, root cause analysis, suggested fix, files to modify
 - [ ] STATE.md updated with loop_position (VERIFY_COMPLETE or VERIFY_FAILED)
-- [ ] If all pass: output ends with NEXT ACTION REQUIRED: /sdlc:review
+- [ ] If all pass: output ends with auto-advance directive to /sdlc:review
 - [ ] If any fail: output ends with "Fix the failures above, then re-run /sdlc:verify"
 - [ ] No criteria skipped without documented reason
 </success_criteria>

package/src/references/prompt-detection.md

@@ -8,11 +8,11 @@ This document explains how the `/sdlc:fast` command classifies task types from n
 
 When a developer types `/sdlc:fast "add a login page"`, the framework must determine:
 
-1. **What type of work is this?** (feature, bug, critical, research, test, refactor, docs)
+1. **What type of work is this?** (feature, bug, critical, test, refactor, docs)
 2. **How complex is it?** (simple, medium, complex)
-3. **Where should it route?** (inline execution, /sdlc:spec, /sdlc:debug, /sdlc:research, /sdlc:discuss, or inline hotfix)
+3. **Where should it route?** (inline execution, /sdlc:spec, /sdlc:debug, /sdlc:discuss, or inline hotfix)
 
-`/sdlc:fast` is the **default entry point** for all work — not just small tasks. It is a universal router that classifies intent and complexity, then either handles work inline (simple) or routes to the appropriate specialized command (complex, bugs, research, emergencies).
+`/sdlc:fast` is the **default entry point** for all work — not just small tasks. It is a universal router that classifies intent and complexity, then either handles work inline (simple) or routes to the appropriate specialized command (complex, bugs, brainstorming/research, emergencies).
 
 This classification happens automatically. The developer can override it with flags if the automatic classification is wrong.
 

package/src/templates/STATE.md

@@ -14,6 +14,11 @@ This template defines the loop position tracker stored at `.sdlc/STATE.md`. It i
 - **Laws file:** .sdlc/LAWS.md
 - **Roadmap file:** .sdlc/ROADMAP.md
 
+## Settings
+
+- **auto_advance:** true
+- **advance_delay_seconds:** 10
+
 ## Current Position
 
 - **Milestone:** {{MILESTONE_NAME}} ({{MILESTONE_NUMBER}}/{{TOTAL_MILESTONES}})
@@ -102,5 +107,10 @@ This is the most important field in the entire SDLC. It tells the developer (or
 ### Accumulated Context
 Decisions, deferred issues, and blockers survive across loop iterations. They are the project's institutional memory. Without them, the same questions get asked repeatedly and the same mistakes get made.
 
+### Settings
+Configuration for framework behavior:
+- **auto_advance** — When true, the framework automatically runs the next required action after a brief delay. Set to false for manual step-by-step control where the user must explicitly run each command.
+- **advance_delay_seconds** — Seconds to wait before auto-advancing to the next command. Gives the user time to review output and intervene by sending a message. Default: 10.
+
 ### Session Continuity
 When a developer stops working (end of day, context switch), this section captures exactly where to resume. The handoff file (HANDOFF.md) contains detailed notes; this section contains the summary.

package/src/workflows/close-phase.md

@@ -1,10 +1,10 @@
-<purpose>Close the current SPEC-IMPL-VERIFY-REVIEW loop by reconciling planned work against actual outcomes, creating a SUMMARY.md, and advancing the state machine to the next spec or phase transition.</purpose>
+<purpose>Close the current SPEC-IMPL-VERIFY-REVIEW loop by reconciling planned work against actual outcomes, creating a SUMMARY.md, and advancing the state machine to the next spec. When the last plan in a phase completes, execute the phase transition inline — verify completeness, update PROJECT.md, advance the roadmap, and commit the phase boundary.</purpose>
 <when_to_use>Run after /sdlc:review passes with zero blockers. STATE.md must show loop_position = REVIEW ✓ and next_required_action = /sdlc:close.</when_to_use>
-<required_reading>.sdlc/STATE.md, the current SPEC.md, REVIEW.md, VERIFY.md</required_reading>
+<required_reading>.sdlc/STATE.md, .sdlc/ROADMAP.md, .sdlc/PROJECT.md, the current SPEC.md, REVIEW.md, VERIFY.md</required_reading>
 <loop_context>
   expected_phase: CLOSE (active)
   prior_phase: REVIEW ✓
-  next_phase: SPEC (next loop) or transition-phase (if last plan)
+  next_phase: SPEC (next loop) — phase transition handled inline when last plan completes
 </loop_context>
 <display_rule>
   MANDATORY: Display the loop closure summary in the chat window. Show:
@@ -135,22 +135,66 @@
   OPTION A — More plans in this phase:
   - Check ROADMAP.md: is this the last planned plan for the current phase?
   - If there are more plans (or the phase is open-ended): set next to /sdlc:spec
+  - Update .sdlc/STATE.md:
+    - loop_position: CLOSE ✓
+    - current_plan: cleared (no active plan)
+    - next_required_action: /sdlc:spec
+    - Add history entry: "{timestamp} | close | Plan {N} closed. {N} ACs passed. {N} deviations."
+  - Update .sdlc/ROADMAP.md:
+    - Increment completed plan count for current phase
+
+  OPTION B — Last plan in phase (execute phase transition inline):
+
+  B1. Verify phase completeness:
+  - List all SPEC and SUMMARY files in .sdlc/phases/{current_phase}/.
+  - Every SPEC must have a corresponding SUMMARY. If a SPEC exists without a SUMMARY: STOP. Display: "Phase transition blocked. Plan {N} has a spec but no summary. Complete it first."
+  - Every SUMMARY must show all ACs passed. If any AC is FAIL: STOP. Display: "Phase transition blocked. Plan {N} has failing ACs."
+  - Display completeness check: plans created, plans completed, hotfixes, all ACs passed.
+
+  B2. Cross-check STATE.md, PROJECT.md, ROADMAP.md consistency:
+  - STATE.md current_milestone must match ROADMAP.md in-progress milestone.
+  - STATE.md current_phase must match the phase being completed.
+  - Prior phases in this milestone must all be COMPLETE.
+  - If inconsistency found: display details, offer to auto-fix, ask for user confirmation before applying.
+
+  B3. Update PROJECT.md:
+  - Read all SUMMARY.md files from the completing phase.
+  - For each requirement in PROJECT.md:
+    - If addressed in this phase: mark as IMPLEMENTED with reference to plan number.
+    - If contradicted or superseded by implementation: mark as SUPERSEDED with explanation.
+    - Leave unaddressed requirements as-is (future phase responsibility).
+  - Add newly discovered requirements (from decisions and lessons learned) as NOT STARTED.
+  - Display proposed changes and ask user to confirm before writing.
+
+  B4. Update ROADMAP.md with phase completion details:
+  - Mark completed phase as COMPLETE with date.
+  - Add phase summary note:
+    ```
+    #### Phase {number} Summary
+    - Plans executed: {N}
+    - Hotfixes: {N}
+    - Key deliverables: {from summaries}
+    - Duration: {first spec date} to {completion date}
+    ```
 
-  OPTION B — Last plan in phase:
-  - If this was the last plan: trigger transition-phase workflow
-  - Set next to /sdlc:transition (which handles phase advancement)
-
-  Update .sdlc/STATE.md:
-  - loop_position: CLOSE ✓
-  - current_plan: cleared (no active plan)
-  - next_required_action: /sdlc:spec OR /sdlc:transition
-  - Add history entry: "{timestamp} | close | Plan {N} closed. {N} ACs passed. {N} deviations."
-
-  Update .sdlc/ROADMAP.md:
-  - Increment completed plan count for current phase
-  - If phase is complete: mark phase status as COMPLETE
-
-  WHY: The state machine must always have a clear next action. Ambiguity in state leads to confusion about what to do next.
+  B5. Advance state to next phase:
+  - IF next phase exists in ROADMAP.md:
+    - Update STATE.md: current_phase to next phase, clear current_plan, set loop_position to SPEC, set next_required_action to /sdlc:spec.
+    - Update ROADMAP.md: set next phase status to IN PROGRESS.
+    - Add history entry: "{timestamp} | close | Plan {N} closed. Phase {phase} complete. Transitioning to phase {next-phase}."
+  - IF no next phase (last phase in milestone):
+    - Do not advance to a new phase. The milestone completion logic in the display_result step handles this.
+    - Add history entry: "{timestamp} | close | Plan {N} closed. Phase {phase} complete. Last phase in milestone."
+
+  B6. Create git commit (if in a git repo):
+  - Check git status for uncommitted changes.
+  - If uncommitted changes exist:
+    - Stage .sdlc/ files and source files from the phase.
+    - Commit: `feat({phase-name}): complete phase {number}`
+    - Display: "Git commit created: {hash}"
+  - If no uncommitted changes: Display: "No uncommitted changes to commit."
+
+  WHY: The state machine must always have a clear next action. Phase transitions are executed inline to keep the close command as the single point of state advancement. No separate transition command needed.
 </step>
 
 <step name="display_result" priority="sixth">
@@ -165,22 +209,52 @@
     ACs passed: {count}/{count}
     Deviations: {count}
 
-    NEXT ACTION REQUIRED: /sdlc:spec
-    Run /sdlc:spec to create the next specification.
+    NEXT: /sdlc:spec
     ```
 
-  IF phase complete:
+    <auto_advance>
+    Read .sdlc/STATE.md auto_advance setting.
+    IF auto_advance is true:
+      Display: "Auto-advancing to /sdlc:spec in {advance_delay_seconds}s — reply to intervene."
+      Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+      If no user message received during sleep: automatically execute /sdlc:spec.
+      If user sends a message: cancel auto-advance, process user input, then resume.
+    IF auto_advance is false:
+      Display: "NEXT ACTION REQUIRED: /sdlc:spec"
+      Wait for user to manually run the command.
+    </auto_advance>
+
+  IF phase complete (transition executed inline) AND next phase exists:
     Display:
     ```
     Loop closed: Plan {N} complete.
-    Phase {phase} COMPLETE — all plans finished.
+
+    Phase transition complete.
+    ─────────────────────────
+    Completed: Phase {old-number} — {old-name}
+    Plans executed: {N}
+    Hotfixes: {N}
+    Duration: {first spec date} to {completion date}
+
+    Starting: Phase {new-number} — {new-name}
 
     Summary: .sdlc/phases/{phase}/{plan}-SUMMARY.md
 
-    Transitioning to next phase...
-    NEXT ACTION REQUIRED: /sdlc:transition
+    NEXT: /sdlc:spec
     ```
 
+    <auto_advance>
+    Read .sdlc/STATE.md auto_advance setting.
+    IF auto_advance is true:
+      Display: "Auto-advancing to /sdlc:spec in {advance_delay_seconds}s — reply to intervene."
+      Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+      If no user message received during sleep: automatically execute /sdlc:spec.
+      If user sends a message: cancel auto-advance, process user input, then resume.
+    IF auto_advance is false:
+      Display: "NEXT ACTION REQUIRED: /sdlc:spec"
+      Wait for user to manually run the command.
+    </auto_advance>
+
   IF milestone complete (last phase, last plan):
     Display:
     ```

package/src/workflows/debug-flow.md

@@ -292,10 +292,21 @@
 
   Debug record: .sdlc/phases/{phase}/DEBUG-{slug}.md
 
-  NEXT ACTION REQUIRED: /sdlc:review
-  Run /sdlc:review to check the fix against engineering laws.
+  NEXT: /sdlc:review
   ```
 
+  <auto_advance>
+  Read .sdlc/STATE.md auto_advance setting.
+  IF auto_advance is true:
+    Display: "Auto-advancing to /sdlc:review in {advance_delay_seconds}s — reply to intervene."
+    Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+    If no user message received during sleep: automatically execute /sdlc:review.
+    If user sends a message: cancel auto-advance, process user input, then resume.
+  IF auto_advance is false:
+    Display: "NEXT ACTION REQUIRED: /sdlc:review"
+    Wait for user to manually run the command.
+  </auto_advance>
+
   WHY: Debug fixes still go through review. A hurried fix might violate engineering laws — empty catch blocks, missing types, function too long. The review catches that.
 </step>