sdlc-framework 1.0.0 → 1.0.1

package/src/commands/fast.md

@@ -11,14 +11,14 @@ The primary entry point for getting work done. Describe what you need in plain l
 **When to use:** Anytime. This is the default command for starting work. Use it instead of figuring out which specific command to run.
 
 **What it does:**
-1. Classify the work type (feature, bug, refactor, test, docs, research).
+1. Classify the work type (feature, bug, refactor, test, docs, critical).
 2. Estimate complexity (files, lines, dependencies).
 3. Route based on classification and complexity:
-   - Simple work (≤3 files, ≤100 lines): execute full loop inline (spec→impl→verify→review→close).
+   - Simple work (≤3 files, ≤100 lines): execute full loop inline (spec→impl→verify→close).
    - Complex feature: route to /sdlc:spec with pre-filled context.
    - Bug: route to /sdlc:debug with reproduction context.
-   - Research question: route to /sdlc:research with topic.
-   - Critical production issue: route to /sdlc:hotfix with context.
+   - Brainstorming or research: route to /sdlc:discuss with topic.
+   - Critical production issue: execute hotfix inline (minimal spec→fix→full verify).
 4. For inline execution: run compressed loop with full engineering law enforcement.
 
 **What happens next:** Depends on routing — either the task is complete, or you are directed to the appropriate specialized command.
@@ -58,9 +58,9 @@ Step-by-step:
 
    | Type | Indicators | Route |
    |------|-----------|-------|
+   | CRITICAL | "urgent", "production", "down", "outage", "critical", "P0", "hotfix" | inline hotfix |
    | BUG | "fix", "bug", "error", "broken", "crash", "fails", "wrong", "regression" | /sdlc:debug |
-   | CRITICAL | "urgent", "production", "down", "outage", "critical", "P0", "hotfix" | /sdlc:hotfix |
-   | RESEARCH | "explore", "investigate", "research", "compare", "evaluate", "options" | /sdlc:research |
+   | DISCUSS | "brainstorm", "discuss", "idea", "what if", "think about", "concept", "should we", "could we", "explore", "investigate", "research", "compare", "evaluate", "options" | /sdlc:discuss |
    | FEATURE | "add", "create", "build", "implement", "new", "introduce" | complexity-dependent |
    | REFACTOR | "refactor", "clean", "rename", "extract", "move", "simplify" | complexity-dependent |
    | TEST | "test", "coverage", "spec", "assertion" | complexity-dependent |
@@ -69,9 +69,9 @@ Step-by-step:
    Display: "Classified as: {type}"
 
 3. **Immediate routing** (for specialized types)
-   - BUG → Display: "Bug detected. NEXT ACTION REQUIRED: /sdlc:debug {original description}" — STOP.
-   - CRITICAL → Display: "Critical issue. NEXT ACTION REQUIRED: /sdlc:hotfix {original description}" — STOP.
-   - RESEARCH → Display: "Research task. NEXT ACTION REQUIRED: /sdlc:research {original description}" — STOP.
+   - BUG → Display: "Bug detected." End with auto-advance directive to /sdlc:debug — STOP.
+   - DISCUSS → Display: "Brainstorming or research topic." End with auto-advance directive to /sdlc:discuss — STOP.
+   - CRITICAL → proceed to inline hotfix (step 10).
 
 4. **Complexity estimation** (for feature/refactor/test/docs)
    - Scan codebase for files related to the description.
@@ -90,10 +90,10 @@ Step-by-step:
    Task exceeds inline threshold ({N} files, ~{N} lines).
    Routing to full spec for proper task decomposition and parallel sub-agent execution.
 
-   NEXT ACTION REQUIRED: /sdlc:spec
    Context pre-loaded: {task description, identified files, estimated scope}
    ```
    Write pre-filled context to .sdlc/STATE.md fast_context field so /sdlc:spec picks it up.
+   End with auto-advance directive to /sdlc:spec.
    STOP.
 
 5. **Inline execution — Mini-SPEC**
@@ -121,7 +121,7 @@ Step-by-step:
    - Check each AC: PASS or FAIL.
    - If ANY FAIL: display failures, suggest fixes. User must fix and re-run.
 
-8. **Inline execution — Mini-REVIEW**
+8. **Inline execution — Mini-review (engineering laws check)**
    - Quick engineering laws check on changed files only.
    - Function length, params, nesting, DRY, security, error handling, tests.
    - If BLOCKERS: fix inline (do not route to /sdlc:fix for fast tasks).
@@ -132,15 +132,51 @@ Step-by-step:
    - Update STATE.md history.
    - Restore prior state (fast does not advance the phase).
    - Display completion summary.
+
+10. **Inline hotfix** (CRITICAL type only)
+    Emergency fix with minimal ceremony, maximum verification.
+
+    a. **Triage:** Ask 3 questions:
+       - "What is broken? (specific symptom)"
+       - "What is the impact? (who is affected)"
+       - "When did it start? (recent deploy, config change)"
+       Classify severity: P0 (system down), P1 (data risk), P2 (major feature broken).
+       If not P0/P1: suggest /sdlc:debug instead. Let user override.
+
+    b. **3-line inline spec:**
+       - Line 1: WHAT is broken (from $ARGUMENTS + triage).
+       - Line 2: WHERE is the likely location (quick Grep search).
+       - Line 3: WHAT the fix should achieve (expected behavior).
+       Display inline spec. Do NOT wait for approval — speed matters in emergencies.
+
+    c. **Fix directly:**
+       - Single-threaded. No sub-agents.
+       - Apply MINIMAL fix — change as few lines as possible.
+       - Engineering laws still apply. No empty catch blocks. No hardcoded secrets.
+       - Add a regression test for the specific failure.
+       - Mark technical debt with TODO(hotfix-{date}).
+
+    d. **Full verification:**
+       - Run FULL test suite (not just affected tests).
+       - For UI: Playwright verification.
+       - If any fail: fix before proceeding.
+
+    e. **Record:**
+       - Determine hotfix number: {phase}.{count+1} (e.g., 02.1).
+       - Create .sdlc/phases/{phase}/HOTFIX-{number}-SUMMARY.md.
+       - Update STATE.md: restore prior state, add history entry.
+       - Update ROADMAP.md: note hotfix under current phase.
+       - Display: "Hotfix {number} applied and verified. State restored."
 </process>
 
 <success_criteria>
 - [ ] Work classified correctly from natural language description
 - [ ] Bugs routed to /sdlc:debug — never processed inline
-- [ ] Critical issues routed to /sdlc:hotfix
-- [ ] Research tasks routed to /sdlc:research
+- [ ] Critical issues handled as inline hotfix with full verify (ACs + laws review)
+- [ ] Brainstorming and research topics routed to /sdlc:discuss
 - [ ] Complex work (>3 files or >100 lines) routed to /sdlc:spec with pre-filled context
 - [ ] Simple work executed inline through full compressed loop
+- [ ] Hotfix: minimal fix, full test suite, engineering laws enforced
 - [ ] All code changes comply with engineering laws
 - [ ] Tests run and pass
 - [ ] STATE.md updated appropriately

package/src/commands/fix.md

@@ -1,25 +1,25 @@
 ---
 name: sdlc:fix
 description: Fix review findings and re-verify compliance
-argument-hint: "[review-path]"
+argument-hint: "[verify-path]"
 allowed-tools: [Read, Write, Bash, Glob, Grep, Edit, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList, AskUserQuestion]
 ---
 
 <objective>
-Systematically fix all blocker findings from /sdlc:review. Read the REVIEW.md, fix each violation, then re-run review to confirm compliance.
+Systematically fix all blocker findings from /sdlc:verify. Read the VERIFY.md review section, fix each violation, then re-run verify to confirm compliance.
 
-**When to use:** After /sdlc:review reports blockers that must be fixed before /sdlc:close.
+**When to use:** After /sdlc:verify reports code quality blockers that must be fixed before /sdlc:close.
 
 **What it does:**
-1. Read the REVIEW.md to load all findings.
+1. Read the VERIFY.md Phase 2 section to load all findings.
 2. Separate blockers (must fix) from warnings (should fix) and info (consider).
 3. Analyze dependencies between findings (fixing one may resolve others).
 4. For independent fixes: spawn parallel sub-agents per file.
 5. For dependent fixes: apply sequentially.
-6. After all blockers fixed: automatically re-run /sdlc:review to confirm compliance.
+6. After all blockers fixed: automatically re-run /sdlc:verify to confirm compliance.
 7. If warnings exist: present to user and ask which to fix (optional).
 
-**What happens next:** Re-runs /sdlc:review automatically. If review passes, routes to /sdlc:close.
+**What happens next:** Re-runs /sdlc:verify automatically. If verify passes, routes to /sdlc:close.
 
 **Critical rule:** Fixes MUST follow the same engineering laws. A fix that introduces a new violation is not a fix.
 </objective>
@@ -30,13 +30,13 @@ Systematically fix all blocker findings from /sdlc:review. Read the REVIEW.md, f
 </execution_context>
 
 <context>
-$ARGUMENTS — optional path to REVIEW.md. If not provided, finds the most recent review file.
+$ARGUMENTS — optional path to VERIFY.md. If not provided, finds the most recent verify file.
 
 Read these files:
 - .sdlc/STATE.md — current loop position and plan reference.
-- The current REVIEW.md — findings to fix.
+- The current VERIFY.md (Phase 2 section) — review findings to fix.
 - .sdlc/LAWS.md — engineering laws for context on each violation.
-- All files listed in REVIEW.md findings.
+- All files listed in VERIFY.md findings.
 </context>
 
 <process>
@@ -45,7 +45,7 @@ Follow workflow: @~/.claude/sdlc-framework/workflows/fix-findings.md
 Step-by-step:
 
 1. **Load review findings**
-   - Read REVIEW.md from .sdlc/phases/{phase}/{plan}-REVIEW.md
+   - Read VERIFY.md from .sdlc/phases/{phase}/{plan}-VERIFY.md (Phase 2 section)
    - Parse all findings: file, line, law, severity, description, suggested fix
    - Count: blockers, warnings, info
 
@@ -82,23 +82,23 @@ Step-by-step:
 5. **Fix approved warnings** (after blockers are done)
    - Same process for user-approved warnings
 
-6. **Re-run review**
-   - After all fixes applied, automatically trigger /sdlc:review
-   - Display: "Fixes applied. Re-running review to confirm compliance..."
+6. **Re-run verify**
+   - After all fixes applied, automatically trigger /sdlc:verify
+   - Display: "Fixes applied. Re-running verify to confirm compliance..."
 
-7. **Handle re-review results**
+7. **Handle re-verify results**
    - If new blockers found (fix introduced new violations): report and loop
    - If clean: route to /sdlc:close
 </process>
 
 <success_criteria>
-- [ ] All blocker findings from REVIEW.md addressed
+- [ ] All blocker findings from VERIFY.md addressed
 - [ ] Fixes follow engineering laws (no new violations introduced)
 - [ ] Findings grouped by file for efficient parallel fixing
 - [ ] Fix dependencies identified and ordered correctly
 - [ ] User approved the fix plan before execution
 - [ ] Sub-agents spawned for independent file fixes
-- [ ] /sdlc:review automatically re-runs after fixes
-- [ ] If review passes: output ends with NEXT ACTION REQUIRED: /sdlc:close
-- [ ] If review fails again: output ends with "New findings found. Re-run /sdlc:fix"
+- [ ] /sdlc:verify automatically re-runs after fixes
+- [ ] If verify passes: output ends with auto-advance directive to /sdlc:close
+- [ ] If verify fails again: output ends with auto-advance directive to /sdlc:fix
 </success_criteria>

package/src/commands/help.md

@@ -1,6 +1,7 @@
 ---
 name: sdlc:help
 description: "Show SDLC framework command reference"
+argument-hint: "[command]"
 allowed-tools: [Read]
 ---
 
@@ -31,9 +32,9 @@ Display the following reference document:
 THE CORE LOOP
 ─────────────
 
-  SPEC ──→ IMPLEMENT ──→ VERIFY ──→ REVIEW ──→ CLOSE
-   │                                              │
-   └──────────────── next cycle ←─────────────────┘
+  SPEC ──→ IMPLEMENT ──→ VERIFY ──→ CLOSE
+   │                                   │
+   └──────────── next cycle ←──────────┘
 
 Every unit of work flows through this loop. No exceptions.
 The framework forces the next action at every step.
@@ -44,9 +45,8 @@ COMMANDS — Core Loop
 
   /sdlc:spec      Define a unit of work. Produces a plan with acceptance criteria.
   /sdlc:impl      Implement the plan. Spawns subagents to write code.
-  /sdlc:verify    Run tests and Playwright checks. Confirm acceptance criteria met.
-  /sdlc:review    Review code against engineering laws. Flag violations.
-  /sdlc:close     Archive the plan. Update STATE.md. Advance to next cycle.
+  /sdlc:verify    Two-phase: test ACs (Playwright MCP, curl, tests) + engineering laws review.
+  /sdlc:close     Close the loop. Handles phase transitions and milestone completion inline.
 
 
 COMMANDS — Quick Entry
@@ -54,30 +54,28 @@ COMMANDS — Quick Entry
 
   /sdlc:fast      THE DEFAULT. Describe work, framework routes + executes.
                   Simple work runs inline. Complex work routes to /sdlc:spec.
-                  Bugs route to /sdlc:debug. Critical issues to /sdlc:hotfix.
+                  Bugs route to /sdlc:debug. Critical issues run as inline hotfix.
 
 COMMANDS — Fix & Debug
 ──────────────────────
 
-  /sdlc:fix       Fix review blockers systematically, then auto re-review.
+  /sdlc:fix       Fix code quality blockers systematically, then auto re-verify.
   /sdlc:debug     Structured debugging: reproduce → isolate → root-cause → fix → verify.
-  /sdlc:hotfix    Emergency fix. Minimal ceremony, maximum verification.
 
 
-COMMANDS — Session Management
-─────────────────────────────
+COMMANDS — Session & Status
+───────────────────────────
 
-  /sdlc:pause     Save context for a break. Creates HANDOFF.md.
-  /sdlc:resume    Restore context. Determines ONE next action.
-  /sdlc:status    Show current loop position, progress, and forced next action.
+  /sdlc:status              Show loop position, progress, forced next action.
+  /sdlc:status pause        Save context for a break. Creates HANDOFF.md.
+  /sdlc:status resume       Restore context. Determines ONE next action.
 
 
-COMMANDS — Planning & Research
-──────────────────────────────
+COMMANDS — Planning & Discovery
+───────────────────────────────
 
-  /sdlc:milestone Create or complete project milestones.
-  /sdlc:research  Deploy subagents for codebase or web research.
-  /sdlc:init      Initialize the framework in a project. Run once.
+  /sdlc:discuss   Brainstorm an idea into a PRD. Spawns research subagents when unknowns are detected.
+  /sdlc:init      Initialize framework or add milestones. Run once.
   /sdlc:help      Show this reference.
 
 
@@ -110,10 +108,17 @@ FOR BUGS
   Example: /sdlc:debug login form submits twice on slow connections
 
 
+AUTO-ADVANCE
+─────────────
+  Steps chain automatically with a 10-second delay.
+  Reply during the delay to intervene.
+  Disable: set auto_advance: false in .sdlc/STATE.md
+
+
 ENGINEERING LAWS (summary)
 ──────────────────────────
 
-  These laws are enforced during REVIEW. Violations block CLOSE.
+  These laws are enforced during VERIFY (Phase 2). Violations block CLOSE.
 
   DRY            Search before writing. Reuse existing patterns.
   Named Types    No inline object shapes with 2+ properties.
@@ -134,7 +139,7 @@ If .sdlc/LAWS.md exists, read it and append any project-specific law customizati
 
 <success_criteria>
 - [ ] Core loop diagram displayed
-- [ ] All 15 commands listed with one-line descriptions
+- [ ] All 11 commands listed with one-line descriptions
 - [ ] Commands grouped by purpose (core loop, shortcuts, session, planning)
 - [ ] Quick start guide shown (3 steps)
 - [ ] Small tasks shortcut mentioned (/sdlc:fast)

package/src/commands/impl.md

@@ -20,11 +20,11 @@ Execute an approved specification by spawning parallel sub-agents for independen
 
 **What happens next:** Framework directs you to /sdlc:verify to validate the implementation against acceptance criteria.
 
-**Critical rule:** Sub-agents do the work. This command orchestrates. Each sub-agent operates within strict boundaries defined by the spec.
+**CRITICAL MANDATORY RULE:** You MUST use the Agent tool to spawn sub-agents for EVERY task. DO NOT implement tasks yourself in the main session. DO NOT skip agent spawning. DO NOT write code directly. This command ORCHESTRATES — the Agent tool EXECUTES. Each sub-agent gets its task, files, laws, and boundaries. All agents in the same wave are spawned in ONE message with run_in_background: true. Use TaskCreate to track every task. This is NON-NEGOTIABLE.
 </objective>
 
 <execution_context>
-@~/.claude/sdlc-framework/workflows/execute-impl.md
+@~/.claude/sdlc-framework/workflows/impl-phase.md
 @.sdlc/STATE.md
 @.sdlc/LAWS.md
 The SPEC.md path is read from STATE.md or provided via $ARGUMENTS.
@@ -40,7 +40,7 @@ Read these files:
 </context>
 
 <process>
-Follow workflow: @~/.claude/sdlc-framework/workflows/execute-impl.md
+Follow workflow: @~/.claude/sdlc-framework/workflows/impl-phase.md
 
 Step-by-step:
 
@@ -80,12 +80,13 @@ Step-by-step:
    - Report what you created, modified, and tested.
    ```
 
-4. **Execute wave 1 (independent tasks)**
+4. **Execute wave 1 (independent tasks) — MUST USE Agent TOOL**
    - Identify all tasks with no dependencies (wave 1).
-   - Spawn one Agent per task with `run_in_background: true`.
-   - Spawn ALL wave 1 agents in a single message.
-   - Update each task status to "in_progress" via TaskUpdate.
-   - Wait for all wave 1 agents to complete.
+   - Call TaskCreate for each task (ALL in one message).
+   - Call the Agent tool for EACH task with run_in_background: true.
+   - ALL Agent calls for this wave MUST be in a SINGLE message (parallel spawn).
+   - DO NOT write any implementation code yourself — agents do ALL the work.
+   - Wait for all wave 1 agents to complete (you will be notified).
 
 5. **Process wave results**
    - When a wave completes, review each agent's output:
@@ -124,7 +125,7 @@ Step-by-step:
 
 10. **Output confirmation**
     - Print implementation summary: tasks completed, files modified, build status.
-    - End with NEXT ACTION REQUIRED.
+    - End with auto-advance directive to /sdlc:verify.
 </process>
 
 <success_criteria>
@@ -138,5 +139,5 @@ Step-by-step:
 - [ ] IMPL-<plan-id>.md created with completion summary
 - [ ] STATE.md updated with loop_position: IMPL_COMPLETE
 - [ ] No files modified outside spec boundaries
-- [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:verify
+- [ ] Output ends with auto-advance directive to /sdlc:verify
 </success_criteria>

package/src/commands/init.md

@@ -6,15 +6,16 @@ allowed-tools: [Read, Write, Bash, Glob, Grep, Edit, AskUserQuestion]
 ---
 
 <objective>
-Initialize the SDLC framework for a project. Create the .sdlc/ directory with four core files: PROJECT.md, STATE.md, ROADMAP.md, and LAWS.md.
+Initialize the SDLC framework for a project. Create the .sdlc/ directory with core files: PROJECT.md, STATE.md, ROADMAP.md, and LAWS.md. Define the first milestone with phases.
 
-**When to use:** First time setting up SDLC in a project. Run this once per repository.
+**When to use:** First time setting up SDLC in a project. Run this once per repository. Also use to create additional milestones: `/sdlc:init milestone <name>`.
 
 **What it does:**
 1. Scan the current directory to understand project structure (language, framework, existing config).
 2. Ask clarification questions about project goals, team conventions, and quality thresholds.
 3. Create .sdlc/ directory with populated templates.
-4. Set the loop position to SPEC (the first phase of the development cycle).
+4. Define the first milestone with phases (or add a new milestone if already initialized).
+5. Set the loop position to SPEC (the first phase of the development cycle).
 
 **What happens next:** Framework directs you to /sdlc:spec to define your first unit of work.
 </objective>
@@ -28,10 +29,12 @@ Initialize the SDLC framework for a project. Create the .sdlc/ directory with fo
 </execution_context>
 
 <context>
-$ARGUMENTS
+$ARGUMENTS — optional project name, or "milestone <name>" to create an additional milestone.
 
 Current directory contents (run ls to inspect).
-Check if .sdlc/ already exists — if it does, warn the user and ask whether to reinitialize or abort.
+Check if .sdlc/ already exists:
+- If "milestone <name>" in $ARGUMENTS: add a new milestone (skip project setup).
+- Otherwise: warn the user and ask whether to reinitialize or abort.
 Read any existing package.json, Cargo.toml, pyproject.toml, go.mod, or similar to detect project type.
 </context>
 
@@ -79,7 +82,20 @@ Step-by-step:
 8. **Output confirmation**
    - Print summary of created files.
    - Print the first milestone and phase.
-   - End with NEXT ACTION REQUIRED.
+   - End with auto-advance directive to /sdlc:spec.
+
+### If "milestone <name>" in $ARGUMENTS: ADD MILESTONE
+
+1. Verify .sdlc/ exists. If not: "Run /sdlc:init first (without 'milestone')."
+2. Read .sdlc/ROADMAP.md. Calculate next milestone number.
+3. Ask clarification questions:
+   - "What is the goal of this milestone? What will be true when it is done?"
+   - "What phases make up this milestone? (2-5 phases in order)"
+   - "Any dependencies on prior milestones?"
+4. Create phase directories: mkdir -p .sdlc/phases/{phase-number}-{phase-name}
+5. Update ROADMAP.md with new milestone section, phases, and status.
+6. Update STATE.md: set current_milestone if none active. Add history entry.
+7. Output: "Milestone created." End with auto-advance directive to /sdlc:spec.
 </process>
 
 <success_criteria>
@@ -89,5 +105,5 @@ Step-by-step:
 - [ ] ROADMAP.md has at least one milestone with at least one phase
 - [ ] LAWS.md contains engineering laws with severity levels configured for the project type
 - [ ] No guessing — all project context gathered via clarification questions
-- [ ] Output ends with NEXT ACTION REQUIRED: /sdlc:spec
+- [ ] Output ends with auto-advance directive to /sdlc:spec
 </success_criteria>

package/src/commands/spec.md

@@ -26,7 +26,7 @@ Define a complete specification for one unit of work (a "plan"). Produce a SPEC.
 </objective>
 
 <execution_context>
-@~/.claude/sdlc-framework/workflows/create-spec.md
+@~/.claude/sdlc-framework/workflows/spec-phase.md
 @.sdlc/STATE.md
 @.sdlc/PROJECT.md
 @.sdlc/ROADMAP.md
@@ -46,7 +46,7 @@ Scan the codebase to understand existing structure, patterns, and conventions.
 </context>
 
 <process>
-Follow workflow: @~/.claude/sdlc-framework/workflows/create-spec.md
+Follow workflow: @~/.claude/sdlc-framework/workflows/spec-phase.md
 
 Step-by-step:
 
@@ -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,42 +134,51 @@ Step-by-step:
    ## Engineering Constraints (from LAWS.md)
    ```
 
-9. **Spec integrity review**
-   - CHECK completeness: all tasks have required fields, all ACs have Given/When/Then
-   - CHECK consistency: every task links to an AC, no boundary violations, no cycles in DAG
-   - CHECK feasibility: task count 2-5, estimated change under ~300 lines
-   - Fix any issues found before presenting for approval
-
-10. **User approval gate** (BLOCKING — cannot proceed without approval)
-    - Present full spec summary to user
+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 integrity review, re-present
+    - 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>