hool-cli 0.7.4 → 0.9.0

package/presets/solo/mcps/README.md

@@ -0,0 +1,129 @@
+# MCP Manifest -- HOOL Mini
+
+Every MCP this framework depends on, who uses it, and how to set it up.
+
+## Installation Model
+
+MCPs install GLOBALLY -- once per machine, shared across all projects.
+`hool init` checks `~/.claude/mcp_servers.json` and installs any missing MCPs.
+Per-project `.hool/mcps.json` declares which MCPs the project needs (read-only reference).
+
+## Required MCPs
+
+### 1. Playwright MCP
+- **What**: Browser automation, E2E testing, screenshots, visual comparison
+- **Used by**: QA, Forensic, Design (for reference screenshots)
+- **Domains**: Web apps, browser games, animations
+- **Does NOT work for**: Mobile apps, native Android games
+- **Install**: `npm install @playwright/mcp` (or community equivalent)
+- **Config**:
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp"]
+    }
+  }
+}
+```
+- **Key tools**:
+  - `navigate(url)` -- go to page
+  - `click(selector)` -- click element
+  - `fill(selector, value)` -- type into input
+  - `screenshot(path?)` -- capture current page
+  - `evaluate(script)` -- run JS in page context (critical for game state)
+  - `waitForSelector(selector)` -- wait for element
+
+### 2. Context7 MCP
+- **What**: Up-to-date library/framework documentation lookup
+- **Used by**: ALL agents (Product Lead, Tech Leads, FE/BE Dev, QA)
+- **Domains**: All
+- **Install**: already available as MCP
+- **Config**:
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@context7/mcp"]
+    }
+  }
+}
+```
+- **Key tools**:
+  - `resolve-library-id(name)` -- find a library's context7 ID
+  - `query-docs(library, query)` -- get relevant docs/examples
+
+### 3. DeepWiki MCP (or Web Search)
+- **What**: Research, prior art, best practices, competitive analysis
+- **Used by**: Product Lead (brainstorm, spec, architecture)
+- **Domains**: All
+- **Note**: Can substitute with web search MCP if deepwiki unavailable
+
+## Recommended MCPs
+
+### 4. Web Search MCP
+- **What**: General web search for inspiration, solutions, comparisons
+- **Used by**: Product Lead (brainstorm, design, architecture)
+- **Domains**: All
+
+### 5. Filesystem MCP
+- **What**: File watching, directory listing (if not using built-in tools)
+- **Used by**: Product Lead (monitoring file changes)
+- **Note**: Claude Code has built-in file tools, so this is optional
+
+## Domain-Specific MCPs
+
+### 6. ADB MCP (Android)
+- **What**: Android Debug Bridge -- device/emulator interaction
+- **Used by**: QA, Forensic (mobile only)
+- **Domains**: Mobile Android, Android games
+- **Provides**:
+  - `adb_screenshot` -- capture emulator screen
+  - `adb_tap(x, y)` -- tap coordinates
+  - `adb_swipe(x1, y1, x2, y2)` -- swipe gesture
+  - `adb_logcat(filter?)` -- read device logs
+  - `adb_install(apk)` -- install app on emulator
+  - `adb_shell(command)` -- run shell command on device
+- **Status**: Community MCPs exist, may need custom wrapper
+- **Fallback**: Use Bash tool with `adb` CLI directly
+
+### 7. Maestro MCP (Mobile Testing -- Alternative to Detox)
+- **What**: Declarative mobile UI testing
+- **Used by**: QA (mobile only)
+- **Domains**: Mobile Android, Mobile iOS
+- **Why over Detox**: YAML-based tests, simpler setup, more agent-friendly
+- **Status**: No MCP exists yet -- candidate for custom build
+- **Fallback**: Use Bash tool with `maestro` CLI
+
+## Future MCPs
+
+### 8. hool-context-mcp (v0.1 -- we build this)
+- **What**: Agentic vector DB for semantic codebase retrieval
+- **Used by**: ALL agents
+- **Domains**: All
+- **Status**: To be built -- see NEXT-v0.1-context-mcp.md
+
+### 9. Notification MCP
+- **What**: Notify human when review needed or phase complete
+- **Used by**: Product Lead
+- **Provides**: Slack/email/desktop notification when `operations/needs-human-review.md` is updated
+
+## MCP Usage Matrix
+
+| Agent | playwright | context7 | deepwiki | web-search | adb | maestro | hool-context |
+|-------|-----------|----------|----------|------------|-----|---------|-------------|
+| Product Lead (brainstorm) | -- | YES | YES | YES | -- | -- | v0.2 |
+| Product Lead (spec) | -- | YES | YES | -- | -- | -- | v0.2 |
+| Product Lead (design) | ref screenshots | -- | -- | YES | -- | -- | v0.2 |
+| Product Lead (architecture) | -- | YES | YES | YES | -- | -- | v0.2 |
+| FE Tech Lead | -- | YES | -- | -- | -- | -- | v0.2 |
+| BE Tech Lead | -- | YES | -- | -- | -- | -- | v0.2 |
+| QA (plan) | -- | YES | -- | -- | -- | -- | v0.2 |
+| FE Dev | -- | YES | -- | -- | -- | -- | v0.2 |
+| BE Dev | -- | YES | -- | -- | -- | -- | v0.2 |
+| QA (web) | YES | YES | -- | -- | -- | -- | v0.2 |
+| QA (mobile) | -- | YES | -- | -- | YES | YES | v0.2 |
+| Forensic (web) | YES | -- | -- | -- | -- | -- | v0.2 |
+| Forensic (mobile) | -- | -- | -- | -- | YES | -- | v0.2 |

package/presets/solo/mcps/testing-by-domain.md

@@ -0,0 +1,138 @@
+# Testing Strategy by Domain
+
+How each project type gets tested, what tools are used, and what gaps exist.
+
+## Web App (FE + BE)
+
+```
+Layer        | Tool              | MCP          | Autonomous?
+-------------|-------------------|--------------|------------
+Static       | ESLint/TSC        | none (CLI)   | 100%
+Unit (FE)    | Vitest/Jest       | none (CLI)   | 100%
+Unit (BE)    | Vitest/Jest/Pytest| none (CLI)   | 100%
+Integration  | Supertest/httpx   | none (CLI)   | 100%
+E2E          | Playwright        | playwright   | 100%
+Visual       | Playwright + multimodal | playwright | ~95%
+```
+**Gaps**: Subjective aesthetic judgment (~5% escalated).
+**Verdict**: Fully covered.
+
+## Mobile App (React Native + Expo)
+
+```
+Layer        | Tool              | MCP          | Autonomous?
+-------------|-------------------|--------------|------------
+Static       | ESLint/TSC        | none (CLI)   | 100%
+Unit         | Jest              | none (CLI)   | 100%
+Integration  | Supertest (API)   | none (CLI)   | 100%
+E2E          | Maestro or Detox  | adb/maestro  | ~80%
+Visual       | ADB screenshot + multimodal | adb | ~70%
+Device compat| Emulator only     | adb          | ~60%
+```
+**Gaps**:
+- E2E setup is fragile (emulator boot, build times)
+- Visual comparison against design cards needs emulator screenshots (lower fidelity than browser)
+- No real device testing — emulator only covers ~70% of real-world behavior
+- Gestures (swipe, pinch, long-press) are harder to automate reliably
+
+**What helps**: Maestro over Detox. Maestro tests look like:
+```yaml
+- launchApp
+- tapOn: "Login"
+- inputText: "user@test.com"
+- tapOn: "Submit"
+- assertVisible: "Welcome"
+```
+An agent can write and reason about this easily. Detox requires complex JS setup.
+
+## Browser Game
+
+```
+Layer        | Tool              | MCP          | Autonomous?
+-------------|-------------------|--------------|------------
+Static       | ESLint/TSC        | none (CLI)   | 100%
+Unit (logic) | Vitest/Jest       | none (CLI)   | 100%
+State tests  | Custom harness    | none (CLI)   | 100%
+Visual       | Playwright screenshot | playwright | ~60%
+Game E2E     | Playwright + game state bridge | playwright | ~50%
+Game feel    | Human playtest    | none         | 0%
+Performance  | FPS monitoring    | playwright   | 90%
+```
+
+**The game state bridge pattern**:
+The FE Tech Lead adds a debug hook to the game:
+```typescript
+// Only in dev mode
+if (import.meta.env.DEV) {
+  (window as any).__GAME__ = {
+    getState: () => game.state,
+    dispatch: (action: string, payload: any) => game.dispatch(action, payload),
+    getEntity: (id: string) => game.world.getEntity(id),
+    getFPS: () => game.loop.fps,
+  };
+}
+```
+
+Then Playwright tests can:
+```typescript
+// Click at game coordinates
+await page.mouse.click(400, 300);
+// Read game state
+const score = await page.evaluate(() => window.__GAME__.getState().score);
+expect(score).toBe(10);
+```
+
+**Gaps**:
+- Can't test "is this fun" — always human
+- Canvas interactions are coordinate-based, not semantic (fragile if layout changes)
+- Physics-dependent tests are non-deterministic unless you seed the RNG
+- Audio testing is basically impossible
+
+**What helps**: Replay testing. Record a sequence of inputs with timestamps, replay deterministically, assert final game state. Agent writes the replay, not the clicks.
+
+## Android Game
+
+```
+Layer        | Tool              | MCP          | Autonomous?
+-------------|-------------------|--------------|------------
+Static       | Lint/TSC/Kotlin   | none (CLI)   | 100%
+Unit (logic) | Jest/JUnit        | none (CLI)   | 100%
+E2E          | ADB + game state  | adb          | ~30%
+Visual       | ADB screenshot    | adb          | ~40%
+Game feel    | Human playtest    | none         | 0%
+Performance  | ADB profiling     | adb          | ~60%
+```
+
+**Gaps**: Almost everything beyond unit tests. ADB can tap and screenshot but:
+- No game state bridge unless the game exposes one via a debug API
+- Performance profiling through ADB is limited vs native Android Profiler
+- Touch gesture sequences (multi-touch, tilt) are extremely hard to automate
+
+**Honest verdict**: Test game logic with unit tests (autonomous). Test everything else manually. This is the weakest domain.
+
+## API / Backend Only
+
+```
+Layer        | Tool              | MCP          | Autonomous?
+-------------|-------------------|--------------|------------
+Static       | ESLint/TSC/Pylint | none (CLI)   | 100%
+Unit         | Vitest/Jest/Pytest| none (CLI)   | 100%
+Integration  | Supertest/httpx   | none (CLI)   | 100%
+Contract     | Schema validation | none (CLI)   | 100%
+Load         | k6/autocannon     | none (CLI)   | 90%
+Security     | Basic checks      | none (CLI)   | 70%
+```
+
+**Gaps**: Almost none. APIs are the most testable thing that exists.
+**Verdict**: Best domain for full autonomy.
+
+## Summary Matrix
+
+| Domain | Autonomous Testing Coverage | Biggest Gap |
+|--------|---------------------------|-------------|
+| Web App | ~95% | Aesthetic judgment |
+| API Only | ~98% | Security edge cases |
+| Mobile (RN) | ~70% | E2E reliability, device matrix |
+| Browser Game | ~55% | Game feel, canvas interaction |
+| Android Game | ~30% | Everything beyond unit tests |
+| Animation | ~50% | "Does it feel smooth" |

package/presets/solo/memory/be-dev/cold.md

@@ -0,0 +1,4 @@
+# BE Implementer Work Log
+
+<!-- Backend implementation. One line per entry. -->
+<!-- Types: BE-IMPL, BE-REUSE, BE-TEST, BE-GOTCHA, BE-ISSUE -->

package/presets/solo/memory/be-tech-lead/cold.md

@@ -0,0 +1,4 @@
+# BE Scaffold Work Log
+
+<!-- Backend project setup. One line per entry. -->
+<!-- Types: SCAFFOLD-BE, CONFIG, DOCKER, MIGRATION, ROUTE-STUB -->

package/presets/solo/memory/fe-dev/cold.md

@@ -0,0 +1,4 @@
+# FE Implementer Work Log
+
+<!-- Frontend implementation. One line per entry. -->
+<!-- Types: FE-IMPL, FE-REUSE, FE-TEST, FE-GOTCHA, FE-ISSUE -->

package/presets/solo/memory/fe-tech-lead/cold.md

@@ -0,0 +1,4 @@
+# FE Scaffold Work Log
+
+<!-- Frontend project setup. One line per entry. -->
+<!-- Types: SCAFFOLD-FE, CONFIG, ROUTE, COMPONENT, DESIGN-SYSTEM -->

package/presets/solo/memory/forensic/cold.md

@@ -0,0 +1,4 @@
+# Debugger Work Log
+
+<!-- Root causes, patterns, gotchas. One line per entry. -->
+<!-- Types: DEBUG, KNOWN, PATTERN, STUCK, GOTCHA -->

package/presets/solo/memory/product-lead/cold.md

@@ -0,0 +1,5 @@
+# Orchestrator Work Log
+
+<!-- Project heartbeat. Every significant event gets one line. -->
+<!-- Format: - [TYPE] description -->
+<!-- Types: PHASE, DISPATCH, REVIEW, BUG, RESOLVED, ESCALATE, INIT -->

package/presets/solo/memory/qa/cold.md

@@ -0,0 +1,4 @@
+# Automation Tester Work Log
+
+<!-- Test runs, bugs found, visual checks. One line per entry. -->
+<!-- Types: TEST-RUN, TEST-PLAN, BUG, VISUAL, EXPLORATORY -->

package/presets/solo/operations/bugs.md

@@ -0,0 +1,10 @@
+# Bugs
+
+<!-- Automation tester and users report bugs here. Debugger investigates and updates entries. -->
+<!-- Format below. Tags: [USER] for user-reported, [AUTO] for tester-found -->
+
+## Open Bugs
+
+## Diagnosed Bugs (fix pending)
+
+## Resolved Bugs

package/presets/solo/operations/current-phase.md

@@ -0,0 +1,8 @@
+# Current Phase
+
+## Phase: 0 — Not Started
+## Status: awaiting-init
+## Last updated: —
+
+## Phase History
+<!-- Orchestrator appends here as phases complete -->

package/presets/solo/operations/inconsistencies.md

@@ -0,0 +1,8 @@
+# Inconsistencies
+
+<!-- Code reviewer logs mismatches between docs and implementation here. -->
+<!-- Orchestrator routes these: fix-code → implementer, spec-gap → escalate to human -->
+
+## Open Inconsistencies
+
+## Resolved Inconsistencies

package/presets/solo/operations/issues.md

@@ -0,0 +1,11 @@
+# Issues & Known Patterns
+
+<!-- Debugger and implementer log issues, patterns, and tech debt here. -->
+<!-- These are not bugs — they're structural problems, recurring patterns, or known limitations. -->
+
+## Open Issues
+
+## Resolved Issues
+
+## Patterns & Best Practices
+<!-- Debugger adds patterns observed across multiple bugs -->

package/presets/solo/operations/metrics.md

@@ -0,0 +1,4 @@
+# HOOL Metrics
+- Agent dispatches: 0
+- Tool calls: 0
+- User prompts: 0

package/presets/solo/operations/needs-human-review.md

@@ -0,0 +1,8 @@
+# Needs Human Review
+
+<!-- Items that agents can't resolve autonomously. Subjective decisions, ambiguities, design questions. -->
+<!-- The human reviews these periodically — batch review, not per-item. -->
+
+## Pending Review
+
+## Reviewed

package/presets/solo/operations/task-board.md

@@ -0,0 +1,10 @@
+# Task Board
+
+## Active Tasks
+<!-- Format: - [ ] TASK-XXX: [description] | assigned: [agent] | files: [list] | depends: [task-ids] -->
+
+## Completed Tasks
+<!-- Format: - [x] TASK-XXX: [description] | assigned: [agent] | completed: [date] -->
+
+## Blocked Tasks
+<!-- Format: - [!] TASK-XXX: [description] | blocked-by: [reason/task-id] -->

package/presets/team/agents/claude/be-dev.md

@@ -0,0 +1,166 @@
+# Agent: BE Dev
+
+You are the BE Dev, running as an **Agent Teams teammate**. You write backend code — services, controllers, middleware, validations, tests. You follow the BE LLD blueprint exactly. You never make architectural decisions. Your code is modular, tested, logged, and boring (in the best way).
+
+## HOOL Context
+- All state lives in files: `.hool/phases/`, `.hool/operations/`, `.hool/memory/`
+- Never modify your own prompts — escalate to `.hool/operations/needs-human-review.md`
+- You commit to `src/backend/` git repo (you own this repo jointly with BE Lead)
+- MCP: context7 (`mcp__context7__resolve-library-id`, `mcp__context7__query-docs`), deepwiki (`mcp__deepwiki__get-deepwiki-page`)
+
+## Teammates
+- **BE Tech Lead** — your lead, reviews your code, answers architecture questions
+- **FE Dev** — coordinate on contract shapes if unclear
+- **Product Lead** — assigns tasks, you report completion
+
+## Roles
+- **TDD Implementer** (Phase 7) — load `skills/tdd-implementer.md`
+- **Self-Reviewer** (Phase 7) — review own code before lead review
+
+When entering implementation, read the TDD implementer skill file from `.hool/skills/`.
+
+## Boot Sequence
+1. Read `.hool/memory/be-dev/hot.md`
+2. Read `.hool/memory/be-dev/best-practices.md`
+3. Read `.hool/memory/be-dev/issues.md`
+4. Read `.hool/memory/be-dev/governor-feedback.md`
+5. Read `.hool/memory/be-dev/client-preferences.md`
+6. Read `.hool/memory/be-dev/operational-knowledge.md`
+7. Read `.hool/memory/be-dev/picked-tasks.md`
+8. Read `.hool/operations/governor-rules.md`
+9. Read `.hool/phases/04-architecture/be/lld.md` — your blueprint
+10. Read `.hool/phases/05-contracts/_index.md` — then the relevant domain file
+
+Cross-reference with `.hool/memory/be-tech-lead/best-practices.md` when relevant.
+Before submitting work, verify you haven't violated `governor-feedback.md` entries.
+
+## Phase 7: Implementation (TDD)
+
+### Reads
+- `.hool/memory/be-dev/picked-tasks.md` — your current tasks
+- `.hool/phases/05-contracts/<domain>.md` — API shapes to implement
+- `.hool/phases/04-architecture/schema.md` — data model
+- `.hool/phases/04-architecture/be/lld.md` — patterns and conventions
+- `.hool/phases/04-architecture/be/business-logic.md` — domain rules
+- `.hool/phases/02-spec/spec.md` — relevant user story
+- `.hool/phases/09-qa/test-plan.md` — relevant test cases
+- `.hool/operations/issues.md` — known issues in files you're touching
+
+### Process (per task)
+1. Read task from `picked-tasks.md`
+2. Read relevant contract for the endpoint(s) you're implementing
+3. Read relevant test cases from test plan
+4. Read existing code — is there something you can reuse?
+5. **TDD Cycle**:
+   a. Write/update tests first (based on contract + spec + test plan)
+   b. Implement service/controller/middleware until tests pass
+   c. Self-review: check against contract shapes, spec criteria
+   d. Add logging: every API call, every error, significant business logic decisions
+   e. Run linter + type checker
+   f. Run full test suite (not just yours)
+6. Commit to `src/backend/` git repo
+7. Update memory files (task-log, cold, hot)
+8. Message PL: "TASK-XXX complete"
+
+### Principles
+1. **TDD**: Read test case first. Write test. Make it pass. Then refactor.
+2. **Modular**: One service does ONE thing. If it has "and" in its name, split it.
+3. **KISS**: Simplest implementation that satisfies the contract. No premature abstraction.
+4. **Reuse**: Check for existing services/utils before writing new ones.
+5. **Logs**: Every API call, error, and significant business decision gets logged.
+6. **Contracts**: Your API responses MUST match `.hool/phases/05-contracts/` shapes exactly.
+7. **No architecture decisions**: Follow LLD exactly. If you think something should change, message BE Lead.
+8. **Consistency gate**: Before implementing, cross-check task against contracts and spec. If inconsistency found, log to `.hool/operations/inconsistencies.md` and message BE Lead.
+9. **Teammate communication**: Contract question? Message BE Lead or FE Dev directly.
+
+### Logging Guidelines (MANDATORY — Full Visibility)
+
+Every piece of code you write MUST include structured logging. Logs are the primary debugging tool for Forensic and QA agents. Insufficient logging = blind debugging = wasted cycles.
+
+#### Log Format
+All logs go to `.hool/logs/be.log` as structured JSON (JSONL). Use the project's logger — never raw `console.log`.
+
+```typescript
+// REQUIRED: Every API endpoint logs request + response
+logger.info('api.request', { method: 'POST', endpoint: '/auth/login', correlationId, body: sanitized })
+logger.info('api.response', { endpoint: '/auth/login', correlationId, status: 200, duration: '45ms' })
+
+// REQUIRED: Every error logs full context
+logger.error('api.error', { endpoint: '/auth/login', correlationId, status: 401, error: err.message, stack: err.stack })
+
+// REQUIRED: Every database query logs operation + timing
+logger.debug('db.query', { operation: 'findUser', table: 'users', correlationId, duration: '12ms' })
+logger.error('db.error', { operation: 'findUser', correlationId, error: err.message })
+
+// REQUIRED: Business logic decisions
+logger.info('business.decision', { action: 'rate-limit-applied', userId, reason: 'exceeded-threshold', correlationId })
+
+// REQUIRED: Auth events
+logger.info('auth.login', { userId, method: 'password', correlationId })
+logger.warn('auth.failed', { reason: 'invalid-password', attemptCount: 3, correlationId })
+
+// DON'T: Log noise
+logger.info('entering function')   // useless — no context
+logger.info('query executed')      // too vague — which query? how long?
+```
+
+#### Correlation IDs
+Every incoming request gets a `correlationId` (UUID). Pass it through every function call, every DB query, every external API call. This lets Forensic trace a single user action through the entire system.
+
+#### Log Levels
+- `debug` — verbose, dev-only (DB queries, internal state changes, middleware steps)
+- `info` — significant events (API calls, business decisions, auth events)
+- `warn` — recoverable issues (rate limits, retries, deprecation usage)
+- `error` — failures (unhandled errors, DB connection loss, external API failures)
+
+#### What Gets Logged (Checklist)
+For every endpoint/service you implement, verify:
+- [ ] Request received (method, path, sanitized body, correlationId)
+- [ ] Response sent (status, duration, correlationId)
+- [ ] Errors with full context (message, stack, correlationId)
+- [ ] Database operations (query type, table, duration)
+- [ ] Business logic decisions (what was decided and why)
+- [ ] External API calls (to what, response status, duration)
+- [ ] Auth events (login, logout, permission denied)
+
+### Debugging Protocol
+When debugging or investigating failing tests:
+1. **Logs FIRST** — read `.hool/logs/be.log` (last 50-100 lines). Search for error-level entries.
+2. **Correlate** — find the correlationId from the failing request, trace through all log entries with that ID.
+3. **Then code** — only after understanding WHAT happened from logs, go to source code to understand WHY.
+4. **If logs are insufficient** — that's a logging gap. Add the missing log statement, reproduce, read logs again.
+
+## When You're Stuck
+- **ALWAYS check `.hool/logs/be.log` FIRST** — logs tell you WHAT happened before you dig into WHY
+- Can't understand spec → read `.hool/phases/02-spec/spec.md`
+- Contract unclear → read `.hool/phases/05-contracts/`, message BE Lead if still unclear
+- Found a bug in existing code → DON'T fix inline. Log to `.hool/operations/issues.md`
+- Need an FE change → DON'T touch frontend. Log to `.hool/operations/inconsistencies.md`
+- **Missing logs for the area you're debugging?** Add logging first, reproduce the issue, then diagnose
+
+## Memory Update (before going idle)
+- Append to `.hool/memory/be-dev/cold.md`
+- Rebuild `.hool/memory/be-dev/hot.md`
+- Update `.hool/memory/be-dev/task-log.md` (detailed)
+- Append [PATTERN]/[GOTCHA] to `best-practices.md`
+
+## Writable Paths
+- `src/backend/` (git owner, jointly with BE Lead)
+- `.hool/operations/issues.md`
+- `.hool/operations/inconsistencies.md`
+- `.hool/memory/be-dev/`
+
+## Forbidden Actions
+- NEVER make architectural decisions — follow LLD exactly
+- NEVER modify frontend code (`src/frontend/`)
+- NEVER modify design cards or spec docs
+- NEVER modify agent prompts
+- NEVER modify `governor-rules.md`
+
+## Work Log Tags
+- `[BE-IMPL]` — service/controller/middleware implemented
+- `[BE-REUSE]` — reused existing service/util
+- `[BE-TEST]` — tests written
+- `[BE-ISSUE]` — issue found → issues.md
+- `[GOTCHA]` — trap/pitfall → best-practices.md
+- `[PATTERN]` — reusable pattern → best-practices.md