@hustle-together/api-dev-tools 3.3.0 → 3.5.0

package/hooks/enforce-deep-research.py

@@ -72,7 +72,9 @@ def main():
         print(json.dumps({"permissionDecision": "allow"}))
         sys.exit(0)
 
-    if status != "complete":
+    phase_exit_confirmed = research_deep.get("phase_exit_confirmed", False)
+
+    if status != "complete" or not phase_exit_confirmed:
         user_question_asked = research_deep.get("user_question_asked", False)
         user_approved = research_deep.get("user_approved", False)
         proposals_shown = research_deep.get("proposals_shown", False)
@@ -92,6 +94,8 @@ def main():
             missing.append("User hasn't approved the search list")
         if pending:
             missing.append(f"Approved searches not executed ({len(pending)} pending)")
+        if not phase_exit_confirmed:
+            missing.append("Phase exit confirmation (user must explicitly approve to proceed)")
 
         print(json.dumps({
             "permissionDecision": "deny",
@@ -106,6 +110,7 @@ Approved: {len(approved_searches)}
 Executed: {len(executed_searches)}
 Skipped: {len(skipped_searches)}
 Pending: {len(pending)}
+Phase exit confirmed: {phase_exit_confirmed}
 
 MISSING:
 {chr(10).join(f"  • {m}" for m in missing)}

package/hooks/enforce-disambiguation.py

@@ -74,7 +74,10 @@ Phase 0 (Disambiguation) is required before any implementation."""
     disambiguation = phases.get("disambiguation", {})
     status = disambiguation.get("status", "not_started")
 
-    if status != "complete":
+    # Also check phase_exit_confirmed even if status is "complete"
+    phase_exit_confirmed = disambiguation.get("phase_exit_confirmed", False)
+
+    if status != "complete" or not phase_exit_confirmed:
         search_variations = disambiguation.get("search_variations", [])
         user_question_asked = disambiguation.get("user_question_asked", False)
         user_selected = disambiguation.get("user_selected", None)
@@ -87,6 +90,8 @@ Phase 0 (Disambiguation) is required before any implementation."""
             missing.append("User question (AskUserQuestion not used)")
         if not user_selected:
             missing.append("User selection (no choice recorded)")
+        if not phase_exit_confirmed:
+            missing.append("Phase exit confirmation (user must explicitly confirm to proceed)")
 
         print(json.dumps({
             "permissionDecision": "deny",
@@ -96,6 +101,7 @@ Status: {status}
 Search variations: {len(search_variations)}
 User question asked: {user_question_asked}
 User selection: {user_selected or "None"}
+Phase exit confirmed: {phase_exit_confirmed}
 
 MISSING:
 {chr(10).join(f"  • {m}" for m in missing)}

package/hooks/enforce-documentation.py

@@ -67,7 +67,9 @@ def main():
 
     status = documentation.get("status", "not_started")
 
-    if status != "complete":
+    phase_exit_confirmed = documentation.get("phase_exit_confirmed", False)
+
+    if status != "complete" or not phase_exit_confirmed:
         user_question_asked = documentation.get("user_question_asked", False)
         user_confirmed = documentation.get("user_confirmed", False)
         checklist_shown = documentation.get("checklist_shown", False)
@@ -86,6 +88,8 @@ def main():
             missing.append("User confirmation question (AskUserQuestion not used)")
         if not user_confirmed:
             missing.append("User hasn't confirmed documentation complete")
+        if not phase_exit_confirmed:
+            missing.append("Phase exit confirmation (user must explicitly approve to complete)")
 
         print(json.dumps({
             "permissionDecision": "deny",
@@ -98,6 +102,7 @@ OpenAPI updated: {openapi_updated}
 Checklist shown: {checklist_shown}
 User question asked: {user_question_asked}
 User confirmed: {user_confirmed}
+Phase exit confirmed: {phase_exit_confirmed}
 
 MISSING:
 {chr(10).join(f"  • {m}" for m in missing)}

package/hooks/enforce-environment.py

@@ -131,9 +131,10 @@ def main():
     user_question_asked = environment_check.get("user_question_asked", False)
     user_ready = environment_check.get("user_ready", False)
     env_shown = environment_check.get("env_shown", False)
+    phase_exit_confirmed = environment_check.get("phase_exit_confirmed", False)
 
     # Check if environment check is complete
-    if env_status != "complete":
+    if env_status != "complete" or not phase_exit_confirmed:
         # Infer required keys if not already set
         if not keys_required:
             interview = phases.get("interview", {})
@@ -157,6 +158,8 @@ def main():
             missing_steps.append("User readiness question (AskUserQuestion not used)")
         if not user_ready:
             missing_steps.append("User hasn't confirmed readiness for TDD")
+        if not phase_exit_confirmed:
+            missing_steps.append("Phase exit confirmation (user must explicitly approve to proceed)")
 
         print(json.dumps({
             "permissionDecision": "deny",
@@ -169,6 +172,7 @@ Missing: {len(missing)}
 User shown env: {env_shown}
 User question asked: {user_question_asked}
 User ready: {user_ready}
+Phase exit confirmed: {phase_exit_confirmed}
 
 MISSING:
 {chr(10).join(f"  • {m}" for m in missing_steps)}

package/hooks/enforce-interview.py

@@ -262,15 +262,18 @@ Reset the interview and ask with options based on research."""
     # Check 6: FINAL USER CONFIRMATION - must confirm interview is complete
     user_question_asked_final = interview.get("user_question_asked", False)
     user_completed = interview.get("user_completed", False)
+    phase_exit_confirmed = interview.get("phase_exit_confirmed", False)
     decisions = interview.get("decisions", {})
 
-    if not user_completed or not user_question_asked_final:
+    if not user_completed or not user_question_asked_final or not phase_exit_confirmed:
         decision_summary = _build_decision_summary(decisions)
         missing = []
         if not user_question_asked_final:
             missing.append("Final confirmation question (AskUserQuestion not used)")
         if not user_completed:
             missing.append("User hasn't confirmed interview complete")
+        if not phase_exit_confirmed:
+            missing.append("Phase exit confirmation (user must explicitly approve to proceed)")
 
         print(json.dumps({
             "permissionDecision": "deny",
@@ -279,6 +282,7 @@ Reset the interview and ask with options based on research."""
 Questions asked: {len(questions)}
 Structured questions: {actual_structured}
 User final confirmation: {user_completed}
+Phase exit confirmed: {phase_exit_confirmed}
 
 MISSING:
 {chr(10).join(f"  • {m}" for m in missing)}

package/hooks/enforce-refactor.py

@@ -119,8 +119,9 @@ def main():
     gaps_found = verify.get("gaps_found", 0)
     gaps_fixed = verify.get("gaps_fixed", 0)
     intentional_omissions = verify.get("intentional_omissions", [])
+    phase_exit_confirmed = verify.get("phase_exit_confirmed", False)
 
-    if verify_status != "complete":
+    if verify_status != "complete" or not phase_exit_confirmed:
         print(json.dumps({
             "permissionDecision": "deny",
             "reason": f"""❌ BLOCKED: Verify phase (Phase 9) not complete.
@@ -129,6 +130,7 @@ Current status: {verify_status}
 Gaps found: {gaps_found}
 Gaps fixed: {gaps_fixed}
 Intentional omissions: {len(intentional_omissions)}
+Phase exit confirmed: {phase_exit_confirmed}
 
 ═══════════════════════════════════════════════════════════
 ⚠️  VERIFY BEFORE REFACTORING

package/hooks/enforce-scope.py

@@ -71,8 +71,9 @@ def main():
     status = scope.get("status", "not_started")
     user_confirmed = scope.get("user_confirmed", False)
     user_question_asked = scope.get("user_question_asked", False)
+    phase_exit_confirmed = scope.get("phase_exit_confirmed", False)
 
-    if status != "complete" or not user_confirmed:
+    if status != "complete" or not user_confirmed or not phase_exit_confirmed:
         endpoint_path = scope.get("endpoint_path", f"/api/v2/{endpoint}")
         modifications = scope.get("modifications", [])
 
@@ -81,6 +82,8 @@ def main():
             missing.append("User question (AskUserQuestion not used)")
         if not user_confirmed:
             missing.append("User confirmation (user hasn't said 'yes')")
+        if not phase_exit_confirmed:
+            missing.append("Phase exit confirmation (user must explicitly approve to proceed)")
 
         print(json.dumps({
             "permissionDecision": "deny",
@@ -89,6 +92,7 @@ def main():
 Status: {status}
 User question asked: {user_question_asked}
 User confirmed: {user_confirmed}
+Phase exit confirmed: {phase_exit_confirmed}
 Proposed path: {endpoint_path}
 Modifications: {len(modifications)}
 

package/hooks/enforce-tdd-red.py

@@ -123,9 +123,10 @@ Example test structure:
     user_approved = tdd_red.get("user_approved", False)
     matrix_shown = tdd_red.get("matrix_shown", False)
     test_scenarios = tdd_red.get("test_scenarios", [])
+    phase_exit_confirmed = tdd_red.get("phase_exit_confirmed", False)
 
     # Check if TDD Red phase is complete
-    if tdd_red_status != "complete":
+    if tdd_red_status != "complete" or not phase_exit_confirmed:
         test_exists, expected_path = find_test_file(file_path)
 
         # Check what's missing for user checkpoint
@@ -138,6 +139,8 @@ Example test structure:
             missing.append("User approval question (AskUserQuestion not used)")
         if not user_approved:
             missing.append("User hasn't approved the test plan")
+        if not phase_exit_confirmed:
+            missing.append("Phase exit confirmation (user must explicitly approve to proceed)")
 
         print(json.dumps({
             "permissionDecision": "deny",
@@ -149,6 +152,7 @@ Test file exists: {test_exists}
 Matrix shown: {matrix_shown}
 User question asked: {user_question_asked}
 User approved: {user_approved}
+Phase exit confirmed: {phase_exit_confirmed}
 Scenarios: {len(test_scenarios)}
 
 MISSING:

package/hooks/track-tool-use.py

@@ -156,6 +156,36 @@ def main():
 
         interview["last_activity"] = datetime.now().isoformat()
 
+        # ========================================
+        # CRITICAL: Set user_question_asked flags
+        # This is what the enforcement hooks check!
+        # ========================================
+        interview["user_question_asked"] = True
+
+        # Also update the CURRENT phase based on workflow state
+        # Determine which phase we're in and set its user_question_asked flag
+        current_phase = _determine_current_phase(phases)
+        if current_phase and current_phase in phases:
+            phases[current_phase]["user_question_asked"] = True
+            # If user responded, also track that
+            if user_response:
+                phases[current_phase]["last_user_response"] = user_response[:200]
+                phases[current_phase]["last_question_timestamp"] = datetime.now().isoformat()
+
+            # ========================================
+            # CRITICAL: Detect phase exit confirmations
+            # This prevents Claude from self-answering
+            # ========================================
+            question_text = tool_input.get("question", "").lower()
+            question_type = _detect_question_type(question_text, options)
+            phases[current_phase]["last_question_type"] = question_type
+
+            # If this is an exit confirmation question AND user responded affirmatively
+            if question_type == "exit_confirmation":
+                # Check if user's response indicates approval/confirmation
+                if user_response and _is_affirmative_response(user_response, options):
+                    phases[current_phase]["phase_exit_confirmed"] = True
+
         # Log for visibility
         if has_options:
             interview["last_structured_question"] = {
@@ -294,6 +324,143 @@ def main():
     sys.exit(0)
 
 
+def _detect_question_type(question_text: str, options: list) -> str:
+    """
+    Detect the type of question being asked.
+    Returns: 'exit_confirmation', 'data_collection', 'clarification', or 'unknown'
+    """
+    question_lower = question_text.lower()
+
+    # Exit confirmation patterns - questions asking to proceed/continue/move to next phase
+    exit_patterns = [
+        "proceed",
+        "continue",
+        "ready to",
+        "move to",
+        "is this correct",
+        "all correct",
+        "looks correct",
+        "approve",
+        "approved",
+        "confirm",
+        "complete",
+        "shall i",
+        "should i proceed",
+        "does this match",
+        "ready for",
+        "start tdd",
+        "start tests",
+        "begin",
+        "next phase",
+        "move on",
+        "go ahead"
+    ]
+
+    # Check options for exit-like labels
+    option_labels = [opt.get("label", "").lower() for opt in options] if options else []
+    exit_option_patterns = [
+        "yes", "proceed", "continue", "approve", "confirm",
+        "ready", "looks good", "correct", "done", "complete"
+    ]
+
+    # If question matches exit patterns
+    for pattern in exit_patterns:
+        if pattern in question_lower:
+            return "exit_confirmation"
+
+    # If options suggest it's an exit confirmation
+    for opt_label in option_labels:
+        for pattern in exit_option_patterns:
+            if pattern in opt_label:
+                return "exit_confirmation"
+
+    # Data collection - asking for choices about implementation
+    data_patterns = [
+        "which", "what", "how should", "prefer", "want",
+        "format", "handling", "strategy", "method"
+    ]
+    for pattern in data_patterns:
+        if pattern in question_lower:
+            return "data_collection"
+
+    # Clarification - asking for more info
+    clarify_patterns = [
+        "clarify", "explain", "more detail", "what do you mean"
+    ]
+    for pattern in clarify_patterns:
+        if pattern in question_lower:
+            return "clarification"
+
+    return "unknown"
+
+
+def _is_affirmative_response(response: str, options: list) -> bool:
+    """
+    Check if the user's response indicates approval/confirmation.
+    """
+    response_lower = response.lower().strip()
+
+    # Direct affirmative words
+    affirmative_words = [
+        "yes", "y", "proceed", "continue", "approve", "confirm",
+        "correct", "ready", "go", "ok", "okay", "looks good",
+        "sounds good", "perfect", "great", "fine", "done",
+        "all good", "looks correct", "is correct", "all correct"
+    ]
+
+    for word in affirmative_words:
+        if word in response_lower:
+            return True
+
+    # Check if response matches an affirmative option
+    if options:
+        for opt in options:
+            opt_label = opt.get("label", "").lower()
+            opt_value = opt.get("value", "").lower()
+
+            # If response matches an option that sounds affirmative
+            if opt_label in response_lower or response_lower in opt_label:
+                for aff in affirmative_words:
+                    if aff in opt_label:
+                        return True
+
+    # Check for negative responses (to avoid false positives)
+    negative_words = ["no", "change", "modify", "add more", "not yet", "wait"]
+    for word in negative_words:
+        if word in response_lower:
+            return False
+
+    return False
+
+
+def _determine_current_phase(phases: dict) -> str:
+    """Determine which phase is currently active based on status."""
+    # Phase order - return first incomplete phase
+    phase_order = [
+        "disambiguation",
+        "scope",
+        "research_initial",
+        "interview",
+        "research_deep",
+        "schema_creation",
+        "environment_check",
+        "tdd_red",
+        "tdd_green",
+        "verify",
+        "tdd_refactor",
+        "documentation"
+    ]
+
+    for phase_name in phase_order:
+        phase = phases.get(phase_name, {})
+        status = phase.get("status", "not_started")
+        if status != "complete":
+            return phase_name
+
+    # All complete, return documentation
+    return "documentation"
+
+
 def create_initial_state():
     """Create initial state structure (v3.0.0)"""
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hustle-together/api-dev-tools",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "Interview-driven, research-first API development workflow with continuous verification loops for Claude Code",
   "main": "bin/cli.js",
   "bin": {

package/templates/api-dev-state.json

@@ -15,6 +15,8 @@
       "search_variations": [],
       "user_question_asked": false,
       "user_selected": null,
+      "phase_exit_confirmed": false,
+      "last_question_type": null,
       "description": "Pre-research disambiguation to clarify ambiguous requests"
     },
     "scope": {
@@ -22,6 +24,8 @@
       "confirmed": false,
       "user_question_asked": false,
       "user_confirmed": false,
+      "phase_exit_confirmed": false,
+      "last_question_type": null,
       "description": "Initial scope understanding and confirmation"
     },
     "research_initial": {
@@ -30,6 +34,8 @@
       "summary_shown": false,
       "user_question_asked": false,
       "user_approved": false,
+      "phase_exit_confirmed": false,
+      "last_question_type": null,
       "description": "Context7/WebSearch research for live documentation"
     },
     "interview": {
@@ -40,6 +46,8 @@
       "decisions": {},
       "user_question_asked": false,
       "user_completed": false,
+      "phase_exit_confirmed": false,
+      "last_question_type": null,
       "description": "Structured interview about requirements (generated FROM research)"
     },
     "research_deep": {
@@ -52,6 +60,8 @@
       "proposals_shown": false,
       "user_question_asked": false,
       "user_approved": false,
+      "phase_exit_confirmed": false,
+      "last_question_type": null,
       "description": "Deep dive based on interview answers (adaptive, not shotgun)"
     },
     "schema_creation": {
@@ -61,6 +71,8 @@
       "schema_shown": false,
       "user_question_asked": false,
       "user_confirmed": false,
+      "phase_exit_confirmed": false,
+      "last_question_type": null,
       "description": "Zod schema creation from research"
     },
     "environment_check": {
@@ -71,6 +83,8 @@
       "env_shown": false,
       "user_question_asked": false,
       "user_ready": false,
+      "phase_exit_confirmed": false,
+      "last_question_type": null,
       "description": "API key and environment verification"
     },
     "tdd_red": {
@@ -81,12 +95,16 @@
       "matrix_shown": false,
       "user_question_asked": false,
       "user_approved": false,
+      "phase_exit_confirmed": false,
+      "last_question_type": null,
       "description": "Write failing tests first"
     },
     "tdd_green": {
       "status": "not_started",
       "implementation_file": null,
       "all_tests_passing": false,
+      "phase_exit_confirmed": false,
+      "last_question_type": null,
       "description": "Minimal implementation to pass tests"
     },
     "verify": {
@@ -100,10 +118,14 @@
       "user_question_asked": false,
       "user_decided": false,
       "user_decision": null,
+      "phase_exit_confirmed": false,
+      "last_question_type": null,
       "description": "Re-research after Green to verify implementation matches docs"
     },
     "tdd_refactor": {
       "status": "not_started",
+      "phase_exit_confirmed": false,
+      "last_question_type": null,
       "description": "Code cleanup while keeping tests green"
     },
     "documentation": {
@@ -115,6 +137,8 @@
       "checklist_shown": false,
       "user_question_asked": false,
       "user_confirmed": false,
+      "phase_exit_confirmed": false,
+      "last_question_type": null,
       "description": "Update manifests, OpenAPI, cache research"
     }
   },