fix(tooling): 🛠 resolve pnpm dev:start issues and update documentation

claude/dot-claude/instructions/safety-rules.md

@@ -337,6 +337,18 @@ pnpm dev:start analytics --dry-run      # Preview what would start
 pnpm dev:start --stop                   # Clean shutdown
 ```
 
+### When pnpm dev:start Doesn't Work
+
+If the command fails or isn't configured for a feature, **DO NOT fall back to manual commands**.
+
+Instead, use the Blocker Protocol:
+1. **STOP** - No manual uvicorn/node commands
+2. **REPORT** - "Blocker: `pnpm dev:start {feature}` not configured"
+3. **REQUEST** - "Need to update tooling: add services.yaml or update dev-start.sh"
+4. **WAIT** - Get user direction
+
+**The fix is to update the tooling**, not bypass it.
+
 **Full documentation**: `docs/technical/SERVICE_DEV.md` and `instructions/service-startup.md`
 
 ---

claude/dot-claude/instructions/service-startup.md

@@ -50,6 +50,22 @@ pnpm dev:start --stop                   # Clean shutdown
 - PID tracking for clean shutdown
 - Deduplication of already-running services
 
+### When pnpm dev:start Doesn't Work
+
+If `pnpm dev:start <feature>` fails or isn't configured for a feature:
+
+1. **STOP** - Do not fall back to manual commands
+2. **REPORT** - "Blocker: `pnpm dev:start {feature}` not configured"
+3. **REQUEST** - "Need to add {feature} to dev:start script or create services.yaml"
+4. **WAIT** - Get direction before proceeding
+
+**The fix is to update the tooling**, not to bypass it with manual commands.
+
+Common missing configurations:
+- Feature missing from `infrastructure/scripts/dev-start.sh`
+- Missing `services.yaml` in `codebase/features/{feature}/`
+- Missing entry in `infrastructure/ports.yaml`
+
 ---
 
 ## Root-Level Scripts