@hustle-together/api-dev-tools 1.3.0 → 1.6.0

package/README.md

@@ -26,11 +26,13 @@ Five powerful slash commands for Claude Code:
 - **`/api-status [endpoint]`** - Track implementation progress and phase completion
 
 ### Enforcement Hooks
-Three Python hooks that provide **real programmatic guarantees**:
+Five Python hooks that provide **real programmatic guarantees**:
 
 - **`enforce-research.py`** - Blocks API code writing until research is complete
-- **`track-tool-use.py`** - Logs all research activity (Context7, WebSearch, WebFetch)
-- **`api-workflow-check.py`** - Prevents stopping until required phases are complete
+- **`enforce-interview.py`** - Verifies user questions were actually asked (prevents self-answering)
+- **`verify-implementation.py`** - Checks implementation matches interview requirements
+- **`track-tool-use.py`** - Logs all research activity (Context7, WebSearch, WebFetch, AskUserQuestion)
+- **`api-workflow-check.py`** - Prevents stopping until required phases are complete + git diff verification
 
 ### State Tracking
 - **`.claude/api-dev-state.json`** - Persistent state file tracking all workflow progress
@@ -402,6 +404,47 @@ The `.claude/api-dev-state.json` file tracks:
 - All research activity is **logged** - auditable trail
 - Workflow completion is **verified** - can't stop early
 
+## 🔍 Gap Detection & Verification (v1.6.0+)
+
+The workflow now includes automatic detection of common implementation gaps:
+
+### Gap 1: Exact Term Matching
+**Problem:** AI paraphrases user terminology instead of using exact terms for research.
+
+**Example:**
+- User says: "Use Vercel AI Gateway"
+- AI searches for: "Vercel AI SDK" (wrong!)
+
+**Fix:** `verify-implementation.py` extracts key terms from interview answers and warns if those exact terms weren't used in research queries.
+
+### Gap 2: File Change Tracking
+**Problem:** AI claims "all files updated" but doesn't verify which files actually changed.
+
+**Fix:** `api-workflow-check.py` runs `git diff --name-only` and compares against tracked `files_created`/`files_modified` in state. Warns about untracked changes.
+
+### Gap 3: Skipped Test Investigation
+**Problem:** AI accepts "9 tests skipped" without investigating why.
+
+**Fix:** `verification_warnings` in state file tracks issues that need review. Stop hook shows unaddressed warnings.
+
+### Gap 4: Implementation Verification
+**Problem:** AI marks task complete without verifying implementation matches interview.
+
+**Fix:** Stop hook checks that:
+- Route files exist if endpoints mentioned
+- Test files are tracked
+- Key terms from interview appear in implementation
+
+### Gap 5: Test/Production Alignment
+**Problem:** Test files check different environment variables than production code.
+
+**Example:**
+- Interview: "single gateway key"
+- Production: uses `AI_GATEWAY_API_KEY`
+- Test: still checks `OPENAI_API_KEY` (wrong!)
+
+**Fix:** `verify-implementation.py` warns when test files check env vars that don't match interview requirements.
+
 ## 🔧 Requirements
 
 - **Node.js** 14.0.0 or higher