@vpxa/kb 0.1.13 → 0.1.16

package/skills/c4-architecture/references/common-mistakes.md

@@ -0,0 +1,437 @@
+# Common C4 Model Mistakes to Avoid
+
+This guide documents frequent anti-patterns and errors when creating C4 architecture diagrams, with examples of what to do instead.
+
+## Abstraction Level Mistakes
+
+### 1. Confusing Containers and Components
+
+**The Problem:**
+Containers are **deployable units** (applications, services, databases). Components are **non-deployable elements inside a container** (modules, classes, packages).
+
+**Wrong - Java class shown as container:**
+```mermaid
+C4Container
+  title WRONG: Class as Container
+
+  Container(userController, "UserController", "Java Class", "Handles user requests")
+  Container(userService, "UserService", "Java Class", "Business logic")
+  ContainerDb(db, "Database", "PostgreSQL", "User data")
+
+  Rel(userController, userService, "Calls")
+  Rel(userService, db, "Queries")
+```
+
+**Correct - Classes as components inside a container:**
+```mermaid
+C4Component
+  title CORRECT: Classes as Components
+
+  ContainerDb(db, "Database", "PostgreSQL", "User data")
+
+  Container_Boundary(api, "User API Service") {
+    Component(userController, "UserController", "Spring MVC", "REST endpoints")
+    Component(userService, "UserService", "Spring Bean", "Business logic")
+    Component(userRepo, "UserRepository", "JPA", "Data access")
+  }
+
+  Rel(userController, userService, "Calls")
+  Rel(userService, userRepo, "Uses")
+  Rel(userRepo, db, "Queries", "JDBC")
+```
+
+### 2. Adding Undefined Abstraction Levels
+
+**The Problem:**
+C4 defines exactly four levels. Don't invent "subcomponents", "modules", or other arbitrary levels.
+
+**Wrong:**
+- Level 3.5: "Subcomponents"
+- Level 2.5: "Microservice groups"
+- Custom levels like "packages" or "modules"
+
+**Correct:**
+Stick to Person, Software System, Container, Component. If you need more detail, you're at Level 4 (Code) which should use UML class diagrams.
+
+### 3. Vague Subsystems
+
+**The Problem:**
+"Subsystem" is ambiguous. Is it a system, container, or component?
+
+**Wrong:**
+```
+Subsystem(orders, "Order Subsystem", "Handles orders")
+```
+
+**Correct - Be specific:**
+```
+System(orderSystem, "Order System", "Handles order lifecycle")
+# OR
+Container(orderService, "Order Service", "Java", "Order processing API")
+# OR
+Component(orderProcessor, "Order Processor", "Spring Bean", "Order business logic")
+```
+
+## Shared Libraries Mistake
+
+**The Problem:**
+Modeling a shared library as a container implies it's an independently running service. Libraries are copied into applications, not deployed separately.
+
+**Wrong - Library as separate container:**
+```mermaid
+C4Container
+  title WRONG: Library as Container
+
+  Container(serviceA, "Service A", "Java")
+  Container(serviceB, "Service B", "Java")
+  Container(sharedLib, "Shared Utils Library", "Java", "Common utilities")
+
+  Rel(serviceA, sharedLib, "Uses")
+  Rel(serviceB, sharedLib, "Uses")
+```
+
+**Correct - Show library within each service:**
+```mermaid
+C4Component
+  title CORRECT: Library in Each Service
+
+  Container_Boundary(serviceA, "Service A") {
+    Component(controllerA, "Controller", "Spring MVC")
+    Component(utilsA, "Shared Utils", "Java Library", "Bundled copy")
+  }
+
+  Container_Boundary(serviceB, "Service B") {
+    Component(controllerB, "Controller", "Spring MVC")
+    Component(utilsB, "Shared Utils", "Java Library", "Bundled copy")
+  }
+```
+
+Or simply omit the library from architecture diagrams since it's an implementation detail.
+
+## Message Broker Mistakes
+
+### Single Message Bus Anti-Pattern
+
+**The Problem:**
+Showing Kafka/RabbitMQ as a single container creates a misleading "hub and spoke" diagram that hides actual data flows.
+
+**Wrong - Central message bus:**
+```mermaid
+C4Container
+  title WRONG: Central Message Bus
+
+  Container(orderSvc, "Order Service", "Java")
+  Container(inventorySvc, "Inventory Service", "Java")
+  Container(paymentSvc, "Payment Service", "Java")
+  ContainerQueue(kafka, "Kafka", "Event Streaming", "Message bus")
+
+  Rel(orderSvc, kafka, "Publishes/Subscribes")
+  Rel(inventorySvc, kafka, "Publishes/Subscribes")
+  Rel(paymentSvc, kafka, "Publishes/Subscribes")
+```
+
+**Correct - Individual topics:**
+```mermaid
+C4Container
+  title CORRECT: Individual Topics
+
+  Container(orderSvc, "Order Service", "Java", "Creates orders")
+  Container(inventorySvc, "Inventory Service", "Java", "Manages stock")
+  Container(paymentSvc, "Payment Service", "Java", "Processes payments")
+
+  ContainerQueue(orderCreated, "order.created", "Kafka", "New orders")
+  ContainerQueue(stockReserved, "stock.reserved", "Kafka", "Stock events")
+  ContainerQueue(paymentComplete, "payment.complete", "Kafka", "Payment events")
+
+  Rel(orderSvc, orderCreated, "Publishes")
+  Rel(inventorySvc, orderCreated, "Consumes")
+  Rel(inventorySvc, stockReserved, "Publishes")
+  Rel(paymentSvc, stockReserved, "Consumes")
+  Rel(paymentSvc, paymentComplete, "Publishes")
+  Rel(orderSvc, paymentComplete, "Consumes")
+```
+
+**Alternative - Topics on relationship labels:**
+```mermaid
+C4Container
+  title ALTERNATIVE: Topics as Labels
+
+  Container(orderSvc, "Order Service", "Java")
+  Container(inventorySvc, "Inventory Service", "Java")
+  Container(paymentSvc, "Payment Service", "Java")
+
+  Rel(orderSvc, inventorySvc, "order.created", "Kafka")
+  Rel(inventorySvc, paymentSvc, "stock.reserved", "Kafka")
+  Rel(paymentSvc, orderSvc, "payment.complete", "Kafka")
+```
+
+## External Systems Mistakes
+
+### Showing Internal Details of External Systems
+
+**The Problem:**
+You don't control external systems. Showing their internals creates coupling and becomes stale quickly.
+
+**Wrong - External system internals:**
+```mermaid
+C4Container
+  title WRONG: External System Internals
+
+  Container(myApp, "My App", "Node.js")
+
+  System_Boundary(stripe, "Stripe") {
+    Container(stripeApi, "Stripe API", "Ruby")
+    Container(stripeWorker, "Payment Worker", "Java")
+    ContainerDb(stripeDb, "Payment DB", "MySQL")
+  }
+
+  Rel(myApp, stripeApi, "Charges cards")
+```
+
+**Correct - External system as black box:**
+```mermaid
+C4Context
+  title CORRECT: External System Black Box
+
+  Container(myApp, "My App", "Node.js", "E-commerce backend")
+  System_Ext(stripe, "Stripe", "Payment processing platform")
+
+  Rel(myApp, stripe, "Processes payments", "REST API")
+```
+
+## Metadata and Documentation Mistakes
+
+### 1. Removing Type Labels
+
+**The Problem:**
+Removing element type labels (Container, Component, System) to "simplify" diagrams creates ambiguity.
+
+**Wrong:**
+```
+Box(api, "API")  # What is this? System? Container? Component?
+```
+
+**Correct:**
+```
+Container(api, "API Application", "Spring Boot", "REST API backend")
+```
+
+### 2. Missing Descriptions
+
+**The Problem:**
+Elements without descriptions force viewers to guess their purpose.
+
+**Wrong:**
+```
+Container(svc, "Service", "Java")
+```
+
+**Correct:**
+```
+Container(orderSvc, "Order Service", "Spring Boot", "Manages order lifecycle and fulfillment")
+```
+
+### 3. Generic Relationship Labels
+
+**The Problem:**
+Labels like "uses" or "communicates with" don't explain what data flows or why.
+
+**Wrong:**
+```
+Rel(frontend, api, "Uses")
+Rel(api, db, "Accesses")
+```
+
+**Correct:**
+```
+Rel(frontend, api, "Fetches products, submits orders", "JSON/HTTPS")
+Rel(api, db, "Reads/writes order data", "JDBC")
+```
+
+## Diagram Scope Mistakes
+
+### 1. Not Tailoring to Audience
+
+**The Problem:**
+Showing Level 4 code diagrams to executives, or only Level 1 to developers who need implementation details.
+
+| Audience | Appropriate Levels |
+|----------|-------------------|
+| Executives | Level 1 (Context) only |
+| Product Managers | Levels 1-2 |
+| Architects | Levels 1-3 |
+| Developers | All levels as needed |
+| DevOps | Levels 2 + Deployment |
+
+### 2. Creating All Four Levels by Default
+
+**The Problem:**
+Not every system needs all four levels. Level 3 (Component) and Level 4 (Code) often add no value.
+
+**Guidance:**
+- **Always create:** Context (L1) and Container (L2)
+- **Create if valuable:** Component (L3) for complex containers
+- **Rarely create:** Code (L4) - let IDEs generate these
+
+### 3. Too Many Elements Per Diagram
+
+**The Problem:**
+Diagrams with 20+ elements become unreadable.
+
+**Simon Brown's advice:** "If a diagram with a dozen boxes is hard to understand, don't draw a diagram with a dozen boxes!"
+
+**Solutions:**
+- Split by bounded context or domain
+- Create separate diagrams per service
+- Show one service + its direct dependencies
+- Use multiple focused diagrams instead of one comprehensive diagram
+
+## Arrow Mistakes
+
+### 1. Bidirectional Arrows
+
+**The Problem:**
+Bidirectional arrows are ambiguous. Who initiates the call? What flows each direction?
+
+**Wrong:**
+```
+BiRel(frontend, api, "Data")  # Ambiguous direction
+```
+
+**Correct:**
+```
+Rel(frontend, api, "Requests products", "JSON/HTTPS")
+Rel(api, frontend, "Returns product data", "JSON/HTTPS")
+```
+
+Or show the initiator's perspective:
+```
+Rel(frontend, api, "Fetches products", "JSON/HTTPS")
+```
+
+### 2. Unlabeled Arrows
+
+**The Problem:**
+Arrows without labels force readers to guess what flows between elements.
+
+**Wrong:**
+```
+Rel(orderSvc, paymentSvc)
+```
+
+**Correct:**
+```
+Rel(orderSvc, paymentSvc, "Requests payment authorization", "gRPC")
+```
+
+## Deployment Diagram Mistakes
+
+### 1. Deployment Details in Container Diagrams
+
+**The Problem:**
+Container diagrams should show logical architecture, not infrastructure details.
+
+**Wrong - Infrastructure in container diagram:**
+```mermaid
+C4Container
+  title WRONG: Infrastructure in Container Diagram
+
+  Container(api1, "API (Instance 1)", "Java", "Primary")
+  Container(api2, "API (Instance 2)", "Java", "Replica")
+  Container(api3, "API (Instance 3)", "Java", "Replica")
+  Container(lb, "Load Balancer", "HAProxy", "Distributes traffic")
+  ContainerDb(primary, "Primary DB", "PostgreSQL", "Write")
+  ContainerDb(replica, "Read Replica", "PostgreSQL", "Read")
+```
+
+**Correct - Use Deployment diagram for infrastructure:**
+```mermaid
+C4Deployment
+  title CORRECT: Deployment Diagram for Infrastructure
+
+  Deployment_Node(lb, "Load Balancer", "AWS ALB") {
+    Container(alb, "ALB", "AWS", "Traffic distribution")
+  }
+
+  Deployment_Node(ecs, "ECS Cluster", "Fargate") {
+    Container(api1, "API Instance 1", "Spring Boot")
+    Container(api2, "API Instance 2", "Spring Boot")
+    Container(api3, "API Instance 3", "Spring Boot")
+  }
+
+  Deployment_Node(rds, "RDS", "Multi-AZ") {
+    ContainerDb(primary, "Primary", "PostgreSQL")
+    ContainerDb(replica, "Replica", "PostgreSQL")
+  }
+```
+
+### 2. Missing Environment Context
+
+**The Problem:**
+Deployment diagrams should specify which environment (production, staging, dev).
+
+**Wrong:**
+```
+C4Deployment
+  title Deployment Diagram  # Which environment?
+```
+
+**Correct:**
+```
+C4Deployment
+  title Deployment Diagram - Production (AWS us-east-1)
+```
+
+## Consistency Mistakes
+
+### 1. Inconsistent Notation Across Diagrams
+
+**The Problem:**
+Using different colors, shapes, or terminology for the same elements across diagrams.
+
+**Wrong:**
+- Context diagram: "Payment System" (blue)
+- Container diagram: "Payment Service" (green)
+- Component diagram: "Payment Module" (red)
+
+**Correct:**
+Use consistent naming, colors, and styling. Create a style guide for your team.
+
+### 2. No Legend/Key
+
+**The Problem:**
+Assuming viewers understand your notation without explanation.
+
+**Solution:**
+Always include a legend explaining colors, shapes, and line styles. Even for "obvious" elements.
+
+## Decision Documentation Mistakes
+
+### Showing Decision Process in Diagrams
+
+**The Problem:**
+Architecture diagrams show **outcomes** of decisions, not the decision-making process.
+
+**Wrong approach:**
+Including "Option A vs Option B" annotations in diagrams.
+
+**Correct approach:**
+- Document decisions separately in Architecture Decision Records (ADRs)
+- Link ADRs to relevant diagrams
+- Diagrams show the chosen architecture, ADRs explain why
+
+## Quick Reference: Checklist
+
+Before finalizing any C4 diagram, verify:
+
+- [ ] Every element has: name, type, technology (if applicable), description
+- [ ] All arrows are unidirectional with action verb labels
+- [ ] Technology/protocol included on relationships
+- [ ] Diagram has a clear, specific title
+- [ ] Under 20 elements (ideally under 15)
+- [ ] Appropriate level for the target audience
+- [ ] Containers are deployable, components are not
+- [ ] External systems shown as black boxes
+- [ ] Message topics shown individually (not as single broker)
+- [ ] No infrastructure details in container diagrams
+- [ ] Consistent with other diagrams in the set

package/skills/knowledge-base/SKILL.md

@@ -1,6 +1,11 @@
+---
+name: knowledge-base
+description: "Use the @anvpx/kb Knowledge Base MCP server for codebase search, analysis, and persistent memory. Load this skill when using kb_search, kb_remember, kb_analyze_*, or any kb_* tool. Covers all 64 MCP tools: search (hybrid/semantic/keyword), code analysis (structure, dependencies, symbols, patterns, entry points, diagrams, blast radius), knowledge graph (auto-populated module/symbol/import graph with traversal), context management (worksets, stash, checkpoints, lanes), code manipulation (rename, codemod, eval), knowledge management (remember/read/update/forget), web access (fetch, search, http), FORGE protocol (ground, classify, evidence map, stratum cards, digest), onboarding (full codebase analysis in one call), and developer utilities (regex, encode, measure, changelog, schema-validate, snippet, env, time)."
+---
+
 # @vpxa/kb — Knowledge Base Toolkit
 
-Local-first AI developer toolkit — 64 MCP tools for knowledge management, code analysis, context compression, code manipulation, execution, web access, and developer utilities.
+Local-first AI developer toolkit — 64 MCP tools for search, analysis, context compression, FORGE quality gates, knowledge management, code manipulation, execution, web access, and developer utilities.
 
 ## When to Use
 
@@ -25,7 +30,7 @@ Local-first AI developer toolkit — 64 MCP tools for knowledge management, code
 core → store → embeddings → chunker → indexer → analyzers → tools → server → cli → tui
 ```
 
-- **MCP server**: 65 tools + 2 resources (via `@modelcontextprotocol/sdk`)
+- **MCP server**: 64 tools + 2 resources (via `@modelcontextprotocol/sdk`)
 - **CLI**: 45 commands (thin dispatcher + 10 command groups)
 - **Search**: Hybrid vector + keyword + RRF fusion
 - **Embeddings**: ONNX local (mxbai-embed-large-v1, 1024 dimensions)
@@ -54,9 +59,9 @@ remember                                         (capture insights)
 remember({ title: "Session checkpoint: <topic>", content: "<what was done, decisions made, next steps>", category: "conventions" })
 ```
 
-## Tool Catalog (65 tools)
+## Tool Catalog (64 tools)
 
-### Search & Discovery (9)
+### Search & Discovery (8)
 | Tool | CLI | Purpose |
 |------|-----|---------|
 | `search` | `kb search` | Hybrid/semantic/keyword search with `search_mode` param |
@@ -98,7 +103,7 @@ remember({ title: "Session checkpoint: <topic>", content: "<what was done, decis
 
 ### Execution & Validation (5)
 | Tool | CLI | Purpose |
-|------|-----|---------||
+|------|-----|---------|
 | `eval` | `kb eval` | Sandboxed JavaScript/TypeScript execution |
 | `check` | `kb check` | Incremental typecheck + lint. `detail` param: summary (default, ~300 tokens), errors, full |
 | `test_run` | `kb test` | Run tests with structured pass/fail results |
@@ -142,25 +147,108 @@ Lane actions: `create` (copy files to lane), `list`, `status` (modified/added/de
 |------|-----|---------|
 | `regex_test` | — | Test regex patterns with match/replace/split modes |
 | `encode` | — | Base64, URL, SHA-256, MD5, hex encode/decode, JWT decode |
-| `measure` | — | Code complexity metrics (cyclomatic, lines, functions) |
+| `measure` | — | Code complexity metrics (cyclomatic, cognitive complexity, lines, functions) |
 | `changelog` | — | Generate changelog from git history (conventional commits) |
 | `schema_validate` | — | Validate JSON data against JSON Schema |
 | `snippet` | — | Save/get/search/delete persistent code snippets |
 | `env` | — | System and runtime environment info (sensitive values redacted) |
 | `time` | — | Date parsing, timezone conversion, duration math |
 
-### System (6)
+### FORGE Quality Gates (5)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `forge_ground` | — | Full Ground phase: classify tier, scope map, unknowns, constraints |
+| `forge_classify` | — | Quick tier classification (Floor/Standard/Critical) |
+| `evidence_map` | — | CRUD + Gate evaluation for verified/assumed/unknown claims |
+| `stratum_card` | — | Generate T1/T2 compressed context cards from files (10-100x token reduction) |
+| `digest` | — | Compress N text sources into token-budgeted summary |
+
+### System (8)
 | Tool | CLI | Purpose |
-|------|-----|--------|
+|------|-----|---------|
 | `status` | `kb status` | Index statistics |
 | `reindex` | `kb reindex` | Rebuild index |
 | `health` | `kb health` | Project health checks (package.json, tsconfig, lockfile, circular deps) |
 | `guide` | `kb guide` | Tool discovery — given a goal, recommends tools and workflow order |
+| `onboard` | `kb onboard` | Full codebase onboarding in one call (structure + deps + patterns + knowledge) |
+| `graph` | `kb graph` | Query the auto-populated knowledge graph (modules, symbols, imports) |
 | `queue` | `kb queue` | Task queue for sequential agent operations (create/push/next/done/fail) |
 | `replay` | `kb replay` | View or clear the audit trail of tool invocations (action: list/clear) |
 
 ## Search Strategy
 
+## CRITICAL: Use KB Tools Instead of Native IDE Tools
+
+KB tools provide **10x richer output** than native IDE tools — with AST-analyzed call graphs, scope context, import classification, and cognitive complexity. **Always prefer KB tools.**
+
+### Tool Replacement Table
+
+| Instead of... | Use KB Tool | Why |
+|---------------|-------------|-----|
+| `read_file` (full file) | `file_summary` | Exports, imports, call edges — **10x fewer tokens** |
+| `read_file` (specific section) | `compact({ path, query })` | Server-side read + extract — **5-20x reduction** |
+| `grep_search` / `textSearch` | `search` | Semantic + keyword hybrid across all indexed content |
+| `grep_search` for a symbol | `symbol` | Definition + references **with scope context** |
+| Multiple `read_file` calls | `digest` | Compresses multiple sources into token-budgeted summary |
+| `listDirectory` + `read_file` | `scope_map` | Identifies relevant files for a task automatically |
+| Manual code tracing | `trace` | AST call-graph traversal with scope context |
+| Line counting / `wc` | `measure` | Lines, complexity, **cognitive complexity**, functions |
+| Grep for unused exports | `dead_symbols` | AST-powered export detection with regex fallback |
+| Repeated file reads | `stratum_card` | Reusable compressed context — **10-100x reduction** |
+
+### Decision Tree — How to Read Code
+
+```
+Need to understand a file?
+├─ Just structure? → file_summary (exports, imports, call edges — ~50 tokens)
+├─ Specific section? → compact({ path: "file.ts", query: "topic" }) — 5-20x reduction
+├─ Multiple files? → digest (multi-source compression — token-budgeted)
+├─ Repeated reference? → stratum_card (T1/T2 card — 10-100x reduction)
+└─ Full file needed? → ONLY as last resort, and compact it after reading
+```
+
+### What KB Tools Return (AST-Enhanced)
+
+These tools use Tree-sitter WASM to analyze source code at the AST level, providing structured data that raw file reads cannot:
+
+| Tool | Rich Output |
+|------|-------------|
+| `file_summary` | Imports classified as **external vs internal** (`isExternal` flag). **Call edges** between functions (e.g., `handleRequest() → validateInput() @ line 42`). `exported` flag on interfaces and types. Import count breakdown. |
+| `symbol` | References include **scope** — which function/class/method contains each usage (e.g., `referenced in processOrder() at auth-service.ts:55`). |
+| `trace` | **Call-graph edges** discovered via AST syntax tree, not text matching. Supports forward (who does X call?) and backward (who calls X?) tracing. Scope context on each node. |
+| `measure` | **Cognitive complexity** — weights nesting depth (nested `if` inside `for` inside `try` scores higher). More useful than cyclomatic complexity for understanding code difficulty. |
+| `dead_symbols` | **AST export enumeration** — catches `export default`, barrel re-exports (`export { x } from`), `export =`, and `export type`. Regex fallback for non-AST-supported languages. |
+
+### Example: `file_summary` Output
+
+```
+src/auth-service.ts
+Language: typescript | Lines: 180 | Estimated tokens: ~1400
+
+Imports (6): 3 external, 3 internal
+  - import { hash } from 'bcrypt'          [external]
+  - import { UserRepo } from './user-repo' [internal]
+
+Functions (4):
+  - authenticate @ line 22 [exported]
+  - validateToken @ line 55 [exported]
+  - hashPassword @ line 90
+  - generateJwt @ line 110
+
+Call edges (12 intra-file):
+  - authenticate() → hashPassword() @ line 35
+  - authenticate() → generateJwt() @ line 42
+  - validateToken() → UserRepo.findById() @ line 68
+
+Interfaces (2):
+  - AuthResult @ line 8 [exported]
+  - TokenPayload @ line 14
+```
+
+Compare: `read_file` would cost ~1400 tokens for raw text. `file_summary` gives structured data in ~120 tokens — **12x reduction** with richer information.
+
+## Search Strategy
+
 1. **Start broad**: `search({ query: "topic", search_mode: "hybrid" })`
 2. **Narrow**: Add `content_type`, `origin`, or `category` filters
 3. **Exact match**: Use `search_mode: "keyword"` for identifiers
@@ -221,8 +309,10 @@ git_context({ diff: true })
 ## CLI Quick Reference
 
 ```bash
-kb init          # Scaffold KB in current directory
-kb serve         # Start MCP server (stdio or HTTP)
+kb init              # Scaffold KB in current directory
+kb init --force      # Overwrite all scaffold/skill files
+kb init --guide      # JSON report of stale files for LLM-driven updates
+kb serve             # Start MCP server (stdio or HTTP)
 kb search <q>    # Hybrid search
 kb find <q>      # Federated search
 kb symbol <name> # Resolve symbol