@hustle-together/api-dev-tools 3.10.1 → 3.11.1

package/.claude/hooks/api-workflow-check.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+"""
+Hook: Stop
+Purpose: Check if all required phases are complete before allowing stop
+
+This hook runs when Claude tries to stop/end the conversation.
+It checks api-dev-state.json to ensure critical workflow phases completed.
+
+Gap Fixes Applied:
+- Gap 2: Shows files_created vs files_modified to verify all claimed changes
+- Gap 3: Warns if there are verification_warnings that weren't addressed
+- Gap 4: Requires explicit verification that implementation matches interview
+
+Returns:
+  - {"decision": "approve"} - Allow stopping
+  - {"decision": "block", "reason": "..."} - Prevent stopping with explanation
+"""
+import json
+import sys
+import subprocess
+from pathlib import Path
+
+# State file is in .claude/ directory (sibling to hooks/)
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+
+# Phases that MUST be complete before stopping
+REQUIRED_PHASES = [
+    ("research_initial", "Initial research (Context7/WebSearch)"),
+    ("interview", "User interview"),
+    ("tdd_red", "TDD Red phase (failing tests written)"),
+    ("tdd_green", "TDD Green phase (tests passing)"),
+    ("verify", "Verification phase (re-checked against docs)"),
+    ("documentation", "Documentation updates (manifest/research cached)"),
+]
+
+# Phases that SHOULD be complete (warning but don't block)
+RECOMMENDED_PHASES = [
+    ("schema_creation", "Schema creation"),
+    ("tdd_refactor", "TDD Refactor phase"),
+    ("documentation", "Documentation updates"),
+]
+
+
+def get_git_modified_files() -> list[str]:
+    """Get list of modified files from git.
+
+    Gap 2 Fix: Verify which files actually changed.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "HEAD"],
+            capture_output=True,
+            text=True,
+            cwd=STATE_FILE.parent.parent  # Project root
+        )
+        if result.returncode == 0:
+            return [f.strip() for f in result.stdout.strip().split("\n") if f.strip()]
+    except Exception:
+        pass
+    return []
+
+
+def check_verification_warnings(state: dict) -> list[str]:
+    """Check for unaddressed verification warnings.
+
+    Gap 3 Fix: Don't accept "skipped" or warnings without explanation.
+    """
+    warnings = state.get("verification_warnings", [])
+    if warnings:
+        return [
+            "⚠️ Unaddressed verification warnings:",
+            *[f"  - {w}" for w in warnings[-5:]],  # Show last 5
+            "",
+            "Please review and address these warnings before completing."
+        ]
+    return []
+
+
+def check_interview_implementation_match(state: dict) -> list[str]:
+    """Verify implementation matches interview requirements.
+
+    Gap 4 Fix: Define specific "done" criteria based on interview.
+    """
+    issues = []
+
+    interview = state.get("phases", {}).get("interview", {})
+    questions = interview.get("questions", [])
+
+    # Extract key requirements from interview
+    all_text = " ".join(str(q) for q in questions)
+
+    # Check files_created includes expected patterns
+    files_created = state.get("files_created", [])
+
+    # Look for route files if interview mentioned endpoints
+    if "endpoint" in all_text.lower() or "/api/" in all_text.lower():
+        route_files = [f for f in files_created if "route.ts" in f]
+        if not route_files:
+            issues.append("⚠️ Interview mentioned endpoints but no route.ts files were created")
+
+    # Look for test files
+    test_files = [f for f in files_created if ".test." in f or "__tests__" in f]
+    if not test_files:
+        issues.append("⚠️ No test files tracked in files_created")
+
+    return issues
+
+
+def main():
+    # If no state file, we're not in an API workflow - allow stop
+    if not STATE_FILE.exists():
+        print(json.dumps({"decision": "approve"}))
+        sys.exit(0)
+
+    # Load state
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        # Corrupted state, allow stop
+        print(json.dumps({"decision": "approve"}))
+        sys.exit(0)
+
+    phases = state.get("phases", {})
+
+    # Check if workflow was even started
+    research = phases.get("research_initial", {})
+    if research.get("status") == "not_started":
+        # Workflow not started, allow stop
+        print(json.dumps({"decision": "approve"}))
+        sys.exit(0)
+
+    # Collect all issues
+    all_issues = []
+
+    # Check required phases
+    incomplete_required = []
+    for phase_key, phase_name in REQUIRED_PHASES:
+        phase = phases.get(phase_key, {})
+        status = phase.get("status", "not_started")
+        if status != "complete":
+            incomplete_required.append(f"  - {phase_name} ({status})")
+
+    if incomplete_required:
+        all_issues.append("❌ REQUIRED phases incomplete:")
+        all_issues.extend(incomplete_required)
+
+    # Check recommended phases
+    incomplete_recommended = []
+    for phase_key, phase_name in RECOMMENDED_PHASES:
+        phase = phases.get(phase_key, {})
+        status = phase.get("status", "not_started")
+        if status != "complete":
+            incomplete_recommended.append(f"  - {phase_name} ({status})")
+
+    # Gap 2: Check git diff vs tracked files
+    git_files = get_git_modified_files()
+    tracked_files = state.get("files_created", []) + state.get("files_modified", [])
+
+    if git_files and tracked_files:
+        # Find files in git but not tracked
+        untracked_changes = []
+        for gf in git_files:
+            if not any(gf.endswith(tf) or tf in gf for tf in tracked_files):
+                if gf.endswith(".ts") and ("/api/" in gf or "/lib/" in gf):
+                    untracked_changes.append(gf)
+
+        if untracked_changes:
+            all_issues.append("\n⚠️ Gap 2: Files changed but not tracked:")
+            all_issues.extend([f"  - {f}" for f in untracked_changes[:5]])
+
+    # Gap 3: Check for unaddressed warnings
+    warning_issues = check_verification_warnings(state)
+    if warning_issues:
+        all_issues.append("\n" + "\n".join(warning_issues))
+
+    # Gap 4: Check interview-implementation match
+    match_issues = check_interview_implementation_match(state)
+    if match_issues:
+        all_issues.append("\n⚠️ Gap 4: Implementation verification:")
+        all_issues.extend([f"  {i}" for i in match_issues])
+
+    # Block if required phases incomplete
+    if incomplete_required:
+        all_issues.append("\n\nTo continue:")
+        all_issues.append("  1. Complete required phases above")
+        all_issues.append("  2. Use /api-status to see detailed progress")
+        all_issues.append("  3. Run `git diff --name-only` to verify changes")
+
+        print(json.dumps({
+            "decision": "block",
+            "reason": "\n".join(all_issues)
+        }))
+        sys.exit(0)
+
+    # Build completion message
+    message_parts = ["✅ API workflow completing"]
+
+    if incomplete_recommended:
+        message_parts.append("\n⚠️ Optional phases skipped:")
+        message_parts.extend(incomplete_recommended)
+
+    # Show summary of tracked files
+    files_created = state.get("files_created", [])
+    if files_created:
+        message_parts.append(f"\n📁 Files created: {len(files_created)}")
+        for f in files_created[:5]:
+            message_parts.append(f"  - {f}")
+        if len(files_created) > 5:
+            message_parts.append(f"  ... and {len(files_created) - 5} more")
+
+    # Show any remaining warnings
+    if warning_issues or match_issues:
+        message_parts.append("\n⚠️ Review suggested:")
+        if warning_issues:
+            message_parts.extend(warning_issues[:3])
+        if match_issues:
+            message_parts.extend(match_issues[:3])
+
+    print(json.dumps({
+        "decision": "approve",
+        "message": "\n".join(message_parts)
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.claude/hooks/enforce-deep-research.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Block writing if deep research not completed WITH USER APPROVAL
+
+Phase 5 requires:
+  1. PROPOSE searches based on interview answers
+  2. Show checkbox list to user
+  3. USE AskUserQuestion: "Approve? [Y] / Add more? ____"
+  4. Execute only approved searches
+  5. Loop back if user wants additions
+
+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 and schema files
+    is_api_file = "/api/" in file_path and file_path.endswith(".ts")
+    is_schema_file = "/schemas/" in file_path and file_path.endswith(".ts")
+
+    if not is_api_file and not is_schema_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)
+
+    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", {})
+    interview = phases.get("interview", {})
+    research_deep = phases.get("research_deep", {})
+
+    # Only enforce after interview is complete
+    if interview.get("status") != "complete":
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    status = research_deep.get("status", "not_started")
+
+    # If deep research was not needed (no proposed searches), allow
+    proposed = research_deep.get("proposed_searches", [])
+    if not proposed and status == "not_started":
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    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)
+        approved_searches = research_deep.get("approved_searches", [])
+        executed_searches = research_deep.get("executed_searches", [])
+        skipped_searches = research_deep.get("skipped_searches", [])
+
+        # Calculate pending
+        pending = [s for s in approved_searches if s not in executed_searches and s not in skipped_searches]
+
+        missing = []
+        if not proposals_shown:
+            missing.append("Proposed searches not shown to user")
+        if not user_question_asked:
+            missing.append("User approval question (AskUserQuestion not used)")
+        if not user_approved:
+            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",
+            "reason": f"""❌ BLOCKED: Deep research (Phase 5) not complete.
+
+Status: {status}
+Proposed searches: {len(proposed)}
+User shown proposals: {proposals_shown}
+User question asked: {user_question_asked}
+User approved: {user_approved}
+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)}
+
+═══════════════════════════════════════════════════════════
+⚠️  GET USER APPROVAL FOR DEEP RESEARCH
+═══════════════════════════════════════════════════════════
+
+REQUIRED STEPS:
+
+1. Based on interview, PROPOSE targeted searches:
+   ┌───────────────────────────────────────────────────────┐
+   │ PROPOSED DEEP RESEARCH                                │
+   │                                                       │
+   │ Based on your interview answers, I want to research:  │
+   │                                                       │
+   │ [x] Error response format (for error handling)        │
+   │ [x] Rate limiting behavior (caching selected)         │
+   │ [ ] Webhook support (not selected in interview)       │
+   │ [x] Authentication edge cases                         │
+   │                                                       │
+   │ Approve these searches? [Y]                           │
+   │ Add more: ____                                        │
+   │ Skip and proceed: [n]                                 │
+   └───────────────────────────────────────────────────────┘
+
+2. USE AskUserQuestion:
+   question: "Approve these deep research searches?"
+   options: [
+     {{"value": "approve", "label": "Yes, run these searches"}},
+     {{"value": "add", "label": "Add more - I also need [topic]"}},
+     {{"value": "skip", "label": "Skip deep research, proceed to schema"}}
+   ]
+
+3. If user says "add":
+   • Ask what additional topics they need
+   • Add to proposed_searches
+   • LOOP BACK and show updated list
+
+4. If user says "approve":
+   • Execute each approved search
+   • Record results in executed_searches
+
+5. If user says "skip":
+   • Record all as skipped_searches with reason
+   • Proceed to schema
+
+6. After all searches complete (or skipped):
+   • Set research_deep.user_approved = true
+   • Set research_deep.user_question_asked = true
+   • Set research_deep.proposals_shown = true
+   • Set research_deep.status = "complete"
+
+WHY: Research is ADAPTIVE based on interview, not shotgun."""
+        }))
+        sys.exit(0)
+
+    # Complete
+    executed = research_deep.get("executed_searches", [])
+    skipped = research_deep.get("skipped_searches", [])
+    print(json.dumps({
+        "permissionDecision": "allow",
+        "message": f"""✅ Deep research complete.
+Executed: {len(executed)} searches
+Skipped: {len(skipped)} (with reasons)
+User approved the search plan."""
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.claude/hooks/enforce-disambiguation.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Block writing API code if disambiguation phase not complete WITH USER CONFIRMATION
+
+Phase 1 requires:
+  1. Search 3-5 variations of the term
+  2. Present options to user via AskUserQuestion
+  3. User selects which interpretation
+  4. Loop back if still ambiguous
+
+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"
+
+# Minimum search variations required
+MIN_SEARCH_VARIATIONS = 2
+
+
+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
+    if "/api/" not in file_path:
+        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": "deny",
+            "reason": """❌ API workflow not started.
+
+Run /api-create [endpoint-name] to begin the interview-driven workflow.
+
+Phase 1 (Disambiguation) is required before any implementation."""
+        }))
+        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")
+    if not endpoint:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    phases = state.get("phases", {})
+    disambiguation = phases.get("disambiguation", {})
+    status = disambiguation.get("status", "not_started")
+
+    # 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)
+
+        # Check what's missing
+        missing = []
+        if len(search_variations) < MIN_SEARCH_VARIATIONS:
+            missing.append(f"Search variations ({len(search_variations)}/{MIN_SEARCH_VARIATIONS})")
+        if not user_question_asked:
+            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",
+            "reason": f"""❌ BLOCKED: Disambiguation phase (Phase 1) not complete.
+
+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)}
+
+═══════════════════════════════════════════════════════════
+⚠️  COMPLETE DISAMBIGUATION WITH USER CONFIRMATION
+═══════════════════════════════════════════════════════════
+
+REQUIRED STEPS:
+
+1. Search 2-3 variations:
+   • WebSearch: "{endpoint}"
+   • WebSearch: "{endpoint} API"
+   • WebSearch: "{endpoint} SDK npm package"
+
+2. USE AskUserQuestion with options:
+   ┌───────────────────────────────────────────────────────┐
+   │ I found multiple things matching "{endpoint}":        │
+   │                                                       │
+   │ [A] The official REST API                             │
+   │ [B] The npm/SDK wrapper package                       │
+   │ [C] Both (API + SDK)                                  │
+   │ [D] Something else: ____                              │
+   │                                                       │
+   │ Which should this endpoint use?                       │
+   └───────────────────────────────────────────────────────┘
+
+3. Record user's choice in state:
+   disambiguation.user_selected = "A" (or user's choice)
+   disambiguation.user_question_asked = true
+   disambiguation.status = "complete"
+
+4. LOOP BACK if user is still unsure - search more variations
+
+WHY: Different interpretations = different implementations."""
+        }))
+        sys.exit(0)
+
+    # Complete - inject context
+    selected = disambiguation.get("user_selected", "")
+    print(json.dumps({
+        "permissionDecision": "allow",
+        "message": f"""✅ Disambiguation complete.
+User selected: {selected}
+Proceeding with this interpretation."""
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()