@hustle-together/api-dev-tools 2.0.7 → 3.1.0

package/hooks/enforce-verify.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Block refactoring until verification complete WITH USER GAP DECISION
+
+Phase 9 (Verify) requires:
+  1. Re-read original documentation (after tests pass)
+  2. Compare implementation to docs - find gaps
+  3. SHOW gap analysis to user
+  4. USE AskUserQuestion: "Fix gaps? [Y] / Skip? [n]"
+  5. Loop back to Phase 7 if user wants fixes
+  6. Only proceed to refactor when user decides
+
+Returns:
+  - {"permissionDecision": "allow"} - Let the tool run
+  - {"permissionDecision": "deny", "reason": "..."} - Block with explanation
+"""
+import json
+import sys
+from pathlib import Path
+
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    tool_input = input_data.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+
+    # Only enforce for API route files
+    is_api_file = "/api/" in file_path and file_path.endswith(".ts")
+
+    if not is_api_file:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Skip test files
+    if ".test." in file_path or "/__tests__/" in file_path or ".spec." in file_path:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Skip documentation/config files
+    if file_path.endswith(".md") or file_path.endswith(".json"):
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    if not STATE_FILE.exists():
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    endpoint = state.get("endpoint", "unknown")
+    phases = state.get("phases", {})
+    tdd_green = phases.get("tdd_green", {})
+    verify = phases.get("verify", {})
+
+    # Only enforce after TDD Green is complete
+    if tdd_green.get("status") != "complete":
+        # Let earlier hooks handle this
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    status = verify.get("status", "not_started")
+
+    if status != "complete":
+        user_question_asked = verify.get("user_question_asked", False)
+        user_decided = verify.get("user_decided", False)
+        gap_analysis_shown = verify.get("gap_analysis_shown", False)
+        re_research_done = verify.get("re_research_done", False)
+        gaps_found = verify.get("gaps_found", 0)
+        gaps_fixed = verify.get("gaps_fixed", 0)
+        gaps_skipped = verify.get("gaps_skipped", 0)
+        user_decision = verify.get("user_decision", None)
+
+        missing = []
+        if not re_research_done:
+            missing.append("Re-research original docs not done")
+        if not gap_analysis_shown:
+            missing.append("Gap analysis not shown to user")
+        if not user_question_asked:
+            missing.append("User gap decision question (AskUserQuestion not used)")
+        if not user_decided:
+            missing.append("User hasn't decided on gaps")
+
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ BLOCKED: Verification (Phase 9) not complete.
+
+Status: {status}
+Re-research done: {re_research_done}
+Gap analysis shown: {gap_analysis_shown}
+User question asked: {user_question_asked}
+User decided: {user_decided}
+User decision: {user_decision or "None yet"}
+Gaps found: {gaps_found}
+Gaps fixed: {gaps_fixed}
+Gaps skipped: {gaps_skipped}
+
+MISSING:
+{chr(10).join(f"  • {m}" for m in missing)}
+
+═══════════════════════════════════════════════════════════
+⚠️  GET USER DECISION ON IMPLEMENTATION GAPS
+═══════════════════════════════════════════════════════════
+
+REQUIRED STEPS:
+
+1. Re-read the ORIGINAL API documentation:
+   • Use Context7 or WebSearch with SAME queries from Phase 2
+   • Compare EVERY documented feature to your implementation
+   • Don't rely on memory - actually re-read the docs
+
+2. Create and SHOW gap analysis table:
+   ┌───────────────────────────────────────────────────────┐
+   │ VERIFICATION RESULTS                                  │
+   │                                                       │
+   │ │ Feature         │ In Docs │ Implemented │ Status   │
+   │ ├─────────────────┼─────────┼─────────────┼──────────│
+   │ │ domain param    │ Yes     │ Yes         │ ✓ Match  │
+   │ │ format option   │ Yes     │ Yes         │ ✓ Match  │
+   │ │ include_fonts   │ Yes     │ No          │ ❌ GAP   │
+   │ │ webhook_url     │ No      │ Yes         │ ⚠ Extra │
+   │                                                       │
+   │ Found 1 gap in implementation.                        │
+   │                                                       │
+   │ Fix the gap? [Y] - Loop back to add missing feature  │
+   │ Skip? [n] - Document as intentional omission          │
+   └───────────────────────────────────────────────────────┘
+
+3. USE AskUserQuestion:
+   question: "I found {gaps_found} gap(s). How should I proceed?"
+   options: [
+     {{"value": "fix", "label": "Fix gaps - loop back to Red phase"}},
+     {{"value": "skip", "label": "Skip - these are intentional omissions"}},
+     {{"value": "partial", "label": "Fix some, skip others - [specify]"}}
+   ]
+
+4. If user says "fix":
+   • Loop back to Phase 7 (TDD Red)
+   • Write new tests for missing features
+   • Implement and verify again
+   • REPEAT until no gaps or user says skip
+
+5. If user says "skip":
+   • Document each skipped gap with reason
+   • Set verify.gaps_skipped = count
+   • Proceed to refactor
+
+6. After user decides:
+   • Set verify.user_decided = true
+   • Set verify.user_question_asked = true
+   • Set verify.gap_analysis_shown = true
+   • Set verify.re_research_done = true
+   • Set verify.user_decision = "fix" or "skip" or "partial"
+   • Set verify.status = "complete"
+
+WHY: Catch memory-based implementation errors BEFORE refactoring."""
+        }))
+        sys.exit(0)
+
+    # Verify complete
+    user_decision = verify.get("user_decision", "unknown")
+    print(json.dumps({
+        "permissionDecision": "allow",
+        "message": f"""✅ Verification complete.
+User decision: {user_decision}
+Gaps found: {gaps_found}
+Gaps fixed: {gaps_fixed}
+Gaps skipped (intentional): {gaps_skipped}
+Proceeding to refactor phase."""
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/periodic-reground.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""
+Hook: PostToolUse (for periodic re-grounding)
+Purpose: Inject context reminders every N turns to prevent context dilution
+
+This hook tracks turn count and periodically injects a summary of:
+  - Current endpoint and phase
+  - Key decisions from interview
+  - Research cache status
+  - Important file locations
+
+The goal is to keep Claude grounded during long sessions where
+the original CLAUDE.md context may get diluted.
+
+Configuration:
+  - REGROUND_INTERVAL: Number of turns between re-grounding (default: 7)
+
+Returns:
+  - {"continue": true} with optional additionalContext on reground turns
+"""
+import json
+import sys
+import os
+from datetime import datetime
+from pathlib import Path
+
+# Configuration
+REGROUND_INTERVAL = 7  # Re-ground every N turns
+
+# State file is in .claude/ directory (sibling to hooks/)
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if state file exists
+    if not STATE_FILE.exists():
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Increment turn count
+    turn_count = state.get("turn_count", 0) + 1
+    state["turn_count"] = turn_count
+    state["last_turn_timestamp"] = datetime.now().isoformat()
+
+    # Check if we should re-ground
+    should_reground = turn_count % REGROUND_INTERVAL == 0
+
+    if should_reground and state.get("endpoint"):
+        # Build re-grounding context
+        context_parts = []
+        context_parts.append(f"## Re-Grounding Reminder (Turn {turn_count})")
+        context_parts.append("")
+
+        endpoint = state.get("endpoint", "unknown")
+        context_parts.append(f"**Active Endpoint:** {endpoint}")
+
+        # Get current phase
+        phases = state.get("phases", {})
+        phase_order = [
+            "disambiguation", "scope", "research_initial", "interview",
+            "research_deep", "schema_creation", "environment_check",
+            "tdd_red", "tdd_green", "verify", "tdd_refactor", "documentation"
+        ]
+
+        current_phase = None
+        completed_phases = []
+        for phase_name in phase_order:
+            phase = phases.get(phase_name, {})
+            status = phase.get("status", "not_started")
+            if status == "complete":
+                completed_phases.append(phase_name)
+            elif status == "in_progress" and not current_phase:
+                current_phase = phase_name
+
+        if not current_phase:
+            # Find first not_started phase
+            for phase_name in phase_order:
+                phase = phases.get(phase_name, {})
+                if phase.get("status", "not_started") == "not_started":
+                    current_phase = phase_name
+                    break
+
+        context_parts.append(f"**Current Phase:** {current_phase or 'documentation'}")
+        context_parts.append(f"**Completed:** {', '.join(completed_phases) if completed_phases else 'None'}")
+
+        # Key decisions summary
+        interview = phases.get("interview", {})
+        decisions = interview.get("decisions", {})
+        if decisions:
+            context_parts.append("")
+            context_parts.append("**Key Decisions:**")
+            for key, value in list(decisions.items())[:5]:  # Limit to 5 key decisions
+                response = value.get("value", value.get("response", "N/A"))
+                if response:
+                    context_parts.append(f"  - {key}: {str(response)[:50]}")
+
+        # Research freshness warning
+        research_index = state.get("research_index", {})
+        if endpoint in research_index:
+            entry = research_index[endpoint]
+            days_old = entry.get("days_old", 0)
+            if days_old > 7:
+                context_parts.append("")
+                context_parts.append(f"**WARNING:** Research is {days_old} days old. Consider re-researching.")
+
+        # File reminders
+        context_parts.append("")
+        context_parts.append("**Key Files:** .claude/api-dev-state.json, .claude/research/")
+
+        # Add to reground history
+        reground_history = state.setdefault("reground_history", [])
+        reground_history.append({
+            "turn": turn_count,
+            "timestamp": datetime.now().isoformat(),
+            "phase": current_phase
+        })
+        # Keep only last 10 reground events
+        state["reground_history"] = reground_history[-10:]
+
+        # Save state
+        STATE_FILE.write_text(json.dumps(state, indent=2))
+
+        # Output with context injection
+        output = {
+            "continue": True,
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": "\n".join(context_parts)
+            }
+        }
+        print(json.dumps(output))
+    else:
+        # Just update turn count and continue
+        STATE_FILE.write_text(json.dumps(state, indent=2))
+        print(json.dumps({"continue": True}))
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session-startup.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""
+Hook: SessionStart
+Purpose: Inject current state and context at the beginning of each session
+
+This hook runs when Claude Code starts a new session or resumes.
+It reads the api-dev-state.json and injects a summary into Claude's context,
+helping to re-ground Claude on:
+  - Current endpoint being developed
+  - Which phases are complete/in-progress
+  - Key decisions from interviews
+  - Research cache location and freshness
+
+Returns:
+  - JSON with additionalContext to inject into Claude's context
+"""
+import json
+import sys
+import os
+from datetime import datetime
+from pathlib import Path
+
+# State file is in .claude/ directory (sibling to hooks/)
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+RESEARCH_INDEX = Path(__file__).parent.parent / "research" / "index.json"
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        input_data = {}
+
+    cwd = input_data.get("cwd", os.getcwd())
+
+    # Check if state file exists
+    if not STATE_FILE.exists():
+        # No active workflow - just continue without injection
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if there's an active workflow
+    endpoint = state.get("endpoint")
+    if not endpoint:
+        # No active endpoint - just continue
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Build context summary
+    context_parts = []
+    context_parts.append("## API Development Session Context")
+    context_parts.append("")
+    context_parts.append(f"**Active Endpoint:** {endpoint}")
+
+    # Get phase status
+    phases = state.get("phases", {})
+    completed = []
+    in_progress = []
+    not_started = []
+
+    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":
+            completed.append(phase_name)
+        elif status == "in_progress":
+            in_progress.append(phase_name)
+        else:
+            not_started.append(phase_name)
+
+    context_parts.append("")
+    context_parts.append("**Phase Status:**")
+    if completed:
+        context_parts.append(f"  - Completed: {', '.join(completed)}")
+    if in_progress:
+        context_parts.append(f"  - In Progress: {', '.join(in_progress)}")
+
+    # Current phase (first in_progress or first not_started)
+    current_phase = in_progress[0] if in_progress else (not_started[0] if not_started else "documentation")
+    context_parts.append(f"  - Current: **{current_phase}**")
+
+    # Key decisions from interview
+    interview = phases.get("interview", {})
+    decisions = interview.get("decisions", {})
+    if decisions:
+        context_parts.append("")
+        context_parts.append("**Key Interview Decisions:**")
+        for key, value in decisions.items():
+            response = value.get("response", value.get("value", "N/A"))
+            if response:
+                context_parts.append(f"  - {key}: {str(response)[:100]}")
+
+    # Research cache info
+    research_index = state.get("research_index", {})
+    if endpoint in research_index:
+        entry = research_index[endpoint]
+        days_old = entry.get("days_old", 0)
+        context_parts.append("")
+        context_parts.append("**Research Cache:**")
+        context_parts.append(f"  - Location: .claude/research/{endpoint}/CURRENT.md")
+        context_parts.append(f"  - Last Updated: {entry.get('last_updated', 'Unknown')}")
+        if days_old > 7:
+            context_parts.append(f"  - WARNING: Research is {days_old} days old. Consider re-researching.")
+
+    # Turn count for re-grounding awareness
+    turn_count = state.get("turn_count", 0)
+    if turn_count > 0:
+        context_parts.append("")
+        context_parts.append(f"**Session Info:** Turn {turn_count} of previous session")
+
+    # Important file locations
+    context_parts.append("")
+    context_parts.append("**Key Files:**")
+    context_parts.append("  - State: .claude/api-dev-state.json")
+    context_parts.append("  - Research: .claude/research/")
+    context_parts.append("  - Manifest: src/app/api-test/api-tests-manifest.json (if exists)")
+
+    # Workflow reminder
+    context_parts.append("")
+    context_parts.append("**Workflow Reminder:** This project uses interview-driven API development.")
+    context_parts.append("Phases loop back if verification fails. Research before answering API questions.")
+
+    # Build the output
+    additional_context = "\n".join(context_parts)
+
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": additional_context
+        }
+    }
+
+    print(json.dumps(output))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/track-tool-use.py

@@ -1,13 +1,16 @@
 #!/usr/bin/env python3
 """
-Hook: PostToolUse for WebSearch, WebFetch, Context7 MCP
-Purpose: Track all research activity in the state file
+Hook: PostToolUse for WebSearch, WebFetch, Context7 MCP, AskUserQuestion
+Purpose: Track all research activity and turn counts in the state file
 
 This hook runs AFTER Claude uses research tools (WebSearch, WebFetch, Context7).
 It logs each research action to api-dev-state.json for:
   - Auditing what research was done
   - Verifying prerequisites before allowing implementation
   - Providing visibility to the user
+  - Tracking turn counts for periodic re-grounding
+
+Version: 3.0.0
 
 Returns:
   - {"continue": true} - Always continues (logging only, no blocking)
@@ -20,6 +23,9 @@ from pathlib import Path
 # State file is in .claude/ directory (sibling to hooks/)
 STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
 
+# Re-grounding interval (also used by periodic-reground.py)
+REGROUND_INTERVAL = 7
+
 
 def main():
     # Read hook input from stdin
@@ -52,6 +58,14 @@ def main():
     else:
         state = create_initial_state()
 
+    # ========================================
+    # TURN COUNTING (for periodic re-grounding)
+    # ========================================
+    # Increment turn count on every tracked tool use
+    turn_count = state.get("turn_count", 0) + 1
+    state["turn_count"] = turn_count
+    state["last_turn_timestamp"] = datetime.now().isoformat()
+
     # Get phases
     phases = state.setdefault("phases", {})
 
@@ -281,30 +295,108 @@ def main():
 
 
 def create_initial_state():
-    """Create initial state structure"""
+    """Create initial state structure (v3.0.0)"""
     return {
-        "version": "1.1.0",
+        "version": "3.0.0",
         "created_at": datetime.now().isoformat(),
+        "endpoint": None,
+        "library": None,
+        "session_id": None,
+        "turn_count": 0,
+        "last_turn_timestamp": None,
+        "research_queries": [],
+        "prompt_detections": [],
         "phases": {
-            "scope": {"status": "not_started"},
-            "research_initial": {"status": "not_started", "sources": []},
-            "interview": {"status": "not_started"},
-            "research_deep": {"status": "not_started", "sources": []},
-            "schema_creation": {"status": "not_started"},
-            "environment_check": {"status": "not_started"},
-            "tdd_red": {"status": "not_started"},
-            "tdd_green": {"status": "not_started"},
-            "tdd_refactor": {"status": "not_started"},
-            "documentation": {"status": "not_started"}
+            "disambiguation": {
+                "status": "not_started",
+                "clarified": None,
+                "search_variations": [],
+                "description": "Pre-research disambiguation to clarify ambiguous requests"
+            },
+            "scope": {
+                "status": "not_started",
+                "confirmed": False,
+                "description": "Initial scope understanding and confirmation"
+            },
+            "research_initial": {
+                "status": "not_started",
+                "sources": [],
+                "summary_approved": False,
+                "description": "Context7/WebSearch research for live documentation"
+            },
+            "interview": {
+                "status": "not_started",
+                "questions": [],
+                "user_question_count": 0,
+                "structured_question_count": 0,
+                "decisions": {},
+                "description": "Structured interview about requirements (generated FROM research)"
+            },
+            "research_deep": {
+                "status": "not_started",
+                "sources": [],
+                "proposed_searches": [],
+                "approved_searches": [],
+                "skipped_searches": [],
+                "description": "Deep dive based on interview answers (adaptive, not shotgun)"
+            },
+            "schema_creation": {
+                "status": "not_started",
+                "schema_file": None,
+                "schema_approved": False,
+                "description": "Zod schema creation from research"
+            },
+            "environment_check": {
+                "status": "not_started",
+                "keys_verified": [],
+                "keys_missing": [],
+                "confirmed": False,
+                "description": "API key and environment verification"
+            },
+            "tdd_red": {
+                "status": "not_started",
+                "test_file": None,
+                "test_count": 0,
+                "test_matrix_approved": False,
+                "description": "Write failing tests first"
+            },
+            "tdd_green": {
+                "status": "not_started",
+                "implementation_file": None,
+                "all_tests_passing": False,
+                "description": "Minimal implementation to pass tests"
+            },
+            "verify": {
+                "status": "not_started",
+                "gaps_found": 0,
+                "gaps_fixed": 0,
+                "intentional_omissions": [],
+                "re_research_done": False,
+                "description": "Re-research after Green to verify implementation matches docs"
+            },
+            "tdd_refactor": {
+                "status": "not_started",
+                "description": "Code cleanup while keeping tests green"
+            },
+            "documentation": {
+                "status": "not_started",
+                "files_updated": [],
+                "manifest_updated": False,
+                "openapi_updated": False,
+                "research_cached": False,
+                "description": "Update manifests, OpenAPI, cache research"
+            }
         },
         "verification": {
             "all_sources_fetched": False,
             "schema_matches_docs": False,
             "tests_cover_params": False,
-            "all_tests_passing": False
+            "all_tests_passing": False,
+            "coverage_percent": None,
+            "post_green_verification": False
         },
-        "research_queries": [],
-        "prompt_detections": []
+        "research_index": {},
+        "reground_history": []
     }