forge-server 0.1.0

package/docs/plans/completed/2026-02-27-forge-swarm-learning/verification-checklist.md

@@ -0,0 +1,462 @@
+# Forge Swarm Learning — Inspector Verification Checklist
+
+> **ACTIVE VERIFICATION DOCUMENT** — This checklist is currently being used for the inspector pass on the swarm learning implementation. Do not archive or remove until inspection is complete.
+
+This checklist is for the inspector agent to systematically verify the swarm learning implementation across all 5 phases of the architecture plan.
+
+---
+
+## 1. Build Checks
+
+- [ ] `npm run build` succeeds with zero errors and zero warnings
+- [ ] No circular dependency warnings in the tsc output
+- [ ] All new imports use `.js` extensions (ESM requirement — `tsconfig.json` uses `module: ESNext`, `moduleResolution: bundler`)
+- [ ] `dist/` directory is rebuilt and matches source (the project commits dist/ to git for zero-build plugin install)
+- [ ] No `any` type suppressions introduced (grep for `as any` or `// eslint-disable.*@typescript-eslint/no-explicit-any` in new code — existing `context-tools.ts:358` is a known exception)
+
+---
+
+## 2. Type Checks
+
+### 2.1 Factory Signatures vs Call Sites in `src/server.ts`
+
+- [ ] `createPhaseTools(engine, contextInjector, vectorStore, graphStore)` — call at line 201 matches signature `(PipelineEngine, ContextInjector, VectorStore | null, GraphStore | null)` at `phase-tools.ts:209`
+- [ ] `createContextTools(knowledgeSearch, codebaseCtx, engine, memoryBridge, vectorStore, graphStore)` — call at line 202-204 matches signature `(KnowledgeSearch, CodebaseContext, PipelineEngine, MemoryBridge?, VectorStore?, GraphStore?)` at `context-tools.ts:52`
+- [ ] `createLearningTools(knowledgeSearch, confidenceManager, vectorStore)` — call at line 211-214 matches signature `(KnowledgeSearch, ConfidenceManager?, QdrantVectorStore?)` at `learning-tools.ts:41`
+- [ ] `createMemoryTools(memoryBridge, vectorStore, graphStore)` — call at line 219 matches signature `(MemoryBridge, VectorStore | null, GraphStore | null)` at `memory-tools.ts:49`
+- [ ] `createGraphTools(graphStore)` — call at line 220 matches signature `(GraphStore | null)` at `graph-tools.ts:36`
+- [ ] `createCollaborationTools(vectorStore, graphStore, db)` — call at line 221 matches signature `(VectorStore | null, GraphStore | null, PipelineDB)` at `collaboration-tools.ts:35`
+- [ ] `createIngestionTools(graphStore)` — call at line 216 matches signature `(GraphStore | null)` at `ingestion-tools.ts:32`
+- [ ] `createPipelineTools(engine, registry)` — call at line 200 matches signature `(PipelineEngine, RepoRegistry)` at `pipeline-tools.ts:34`
+- [ ] `createRegistrationTools(registry, stores)` — call at line 206-210 matches signature `(RepoRegistry, RegistrationToolStores?)` at `registration-tools.ts:61`
+- [ ] `ContextInjector` constructor at line 186-193 matches `(KnowledgeSearch, CodebaseContext, MemoryBridge, PipelineDB, ConfidenceManager?, QdrantVectorStore?)` at `injector.ts:145-152`
+
+### 2.2 New Types in `src/util/types.ts`
+
+- [ ] `FileChangeStats` type exists with fields: `commitCount`, `stabilityScore`, `changeVelocity`, `lastCommitHash`, `lastCommitTs`, `recentMessages[]`
+- [ ] `CommitRecord` type exists with fields: `hash`, `message`, `author`, `timestamp`, `files[]`
+- [ ] `GitCommitPayload` type exists for Qdrant: `repo_id`, `commit_hash`, `message`, `author`, `timestamp`, `file_paths[]`
+- [ ] `ObservationPayload` type is used correctly in `collaboration-tools.ts` (imported at line 10)
+- [ ] `QueryIntent` type includes all 4 values: `read`, `modify`, `debug`, `refactor`
+- [ ] `IndexStatusOutput` type used in `registration-tools.ts:366` exists and is correct
+
+### 2.3 No `any` Types in New Code
+
+- [ ] `src/tools/memory-tools.ts` — no untyped `any`
+- [ ] `src/tools/graph-tools.ts` — no untyped `any`
+- [ ] `src/tools/collaboration-tools.ts` — no untyped `any`
+- [ ] `src/tools/ingestion-tools.ts` — no untyped `any`
+- [ ] `src/query/ranking.ts` — no untyped `any`
+
+---
+
+## 3. New Tool Verification
+
+### Expected Tool Count: 34 total
+
+Baseline 22 + 12 new tools. Verify `Object.keys(allTools).length` logged at server startup matches 34.
+
+### 3.1 Phase 1 Tools (6 new)
+
+#### `save_observation`
+- [ ] Registered in `allTools` via `...memoryTools` spread (server.ts:230)
+- [ ] Schema: `{ content: string, symbols?: string[], repo_id?: string, importance?: number [0-1, default 0.5], tags?: string[], category?: string, type?: 'episodic'|'semantic'|'procedural'|'working' }`
+- [ ] Returns: `{ id, stored, linked_symbols, unresolved_symbols }` on success
+- [ ] Graceful degradation: returns `{ error: 'VECTOR_STORE_UNAVAILABLE', stored: false }` when vectorStore is null
+- [ ] Uses no-op graph store when graphStore is null (does NOT throw)
+
+#### `search_memory`
+- [ ] Registered in `allTools` via `...memoryTools` spread
+- [ ] Schema: `{ query: string, repo_id?: string, session_id?: string, limit?: number [1-50, default 10], score_threshold?: number [0-1, default 0.3] }`
+- [ ] Returns: `{ results: [{ content, created_at, relevance_score, session_id }] }`
+- [ ] Graceful degradation: catches errors and returns `{ error, results: [] }`
+
+#### `get_session_context`
+- [ ] Registered in `allTools` via `...memoryTools` spread
+- [ ] Schema: `{ query?: string, session_count?: number [1-10, default 3], limit?: number [1-50, default 20] }`
+- [ ] Returns: `{ current_session: { session_id, started_at, uptime_seconds, observation_count }, recent_sessions: [...] }`
+- [ ] Graceful degradation: returns `{ error: 'VECTOR_STORE_UNAVAILABLE', current_session: null, recent_sessions: [] }` when vectorStore is null
+- [ ] Calls `persistSessionMarker()` before querying
+
+#### `get_impact_graph`
+- [ ] Registered in `allTools` via `...graphTools` spread (server.ts:231)
+- [ ] Schema: `{ symbol: string, repo_id: string, direction: 'inbound'|'outbound'|'both' [default 'both'], depth?: number [1-5, default 3] }`
+- [ ] Returns: `{ symbol, direction, nodes: [...], edges: [...], total_nodes, total_edges }`
+- [ ] Graceful degradation: returns `{ error: 'GRAPH_UNAVAILABLE' }` when graphStore is null OR unhealthy
+- [ ] Uses both `QUERY_INBOUND_IMPACT` and `QUERY_OUTBOUND_IMPACT` from `graph-queries.ts`
+
+#### `search_logic_flow`
+- [ ] Registered in `allTools` via `...graphTools` spread
+- [ ] Schema: `{ from_symbol: string, to_symbol: string, repo_id: string, max_depth?: number [1-10, default 5] }`
+- [ ] Returns: `{ from_symbol, to_symbol, paths: [{ nodes, edges, length }], connected: boolean }`
+- [ ] Graceful degradation: returns `{ error: 'GRAPH_UNAVAILABLE' }` when graphStore is null OR unhealthy
+- [ ] Uses `QUERY_SHORTEST_PATH` from `graph-queries.ts`
+
+#### `get_index_status`
+- [ ] Registered in `allTools` via `...registrationTools` spread
+- [ ] Schema: `{ repo_id?: string }`
+- [ ] Returns: `{ repos, graph: { total_nodes, total_edges, node_counts }, vector: { code_chunks_count, observations_count }, cache, health: 'healthy'|'degraded'|'unavailable', embedding_model, uptime_seconds }`
+- [ ] Graceful degradation: returns status for available backends only, reports health accurately
+
+### 3.2 Phase 2 Tools (2 new)
+
+#### `boost_knowledge`
+- [ ] Registered in `allTools` via `...learningTools` spread (server.ts:228)
+- [ ] Schema: `{ knowledge_id: string, amount?: number [0-1, default 0.05], reason?: string }`
+- [ ] Returns: `{ knowledge_id, boosted: true, amount, reason }` on success
+- [ ] Graceful degradation: returns `{ error: 'CONFIDENCE_UNAVAILABLE' }` when confidenceManager or vectorStore is missing
+
+#### `decay_knowledge`
+- [ ] Registered in `allTools` via `...learningTools` spread
+- [ ] Schema: `{ decay_rate?: number [0-1, default 0.01] }`
+- [ ] Returns: `{ decayed_count, decay_rate }`
+- [ ] Graceful degradation: returns `{ error: 'CONFIDENCE_UNAVAILABLE' }` when confidenceManager or vectorStore is missing
+
+### 3.3 Phase 3 Tools (1 new)
+
+#### `get_git_context`
+- [ ] Registered in `allTools` via `...contextTools` spread (server.ts:227)
+- [ ] Schema: `{ mode: 'hotspots'|'commit_search'|'file_history', repo_id?: string, query?: string, file_path?: string, limit?: number [1-100, default 20] }`
+- [ ] Mode `hotspots` returns: `{ mode: 'hotspots', results: [{ file_path, commit_count, stability_score, change_velocity }], total }`
+- [ ] Mode `commit_search` returns: `{ mode: 'commit_search', results: [...], total }`
+- [ ] Mode `file_history` returns: `{ mode: 'file_history', results: [{ file_path, commit_count, stability_score, change_velocity, last_commit_hash, last_commit_ts }], total }`
+- [ ] Graceful degradation: `hotspots` requires graphStore, `commit_search` requires vectorStore + `searchGitCommits` method, `file_history` requires graphStore
+- [ ] Returns descriptive error objects (not throws) when backends unavailable
+
+### 3.4 Phase 4 Tools (1 new)
+
+#### `submit_lsp_edges`
+- [ ] Registered in `allTools` via `...ingestionTools` spread (server.ts:229)
+- [ ] Schema: `{ repo_id: string, edges: [{ from_file: string, from_symbol: string, to_file: string, to_symbol: string, edge_type: string }] }`
+- [ ] Returns: `{ accepted: number, failed: number, errors?: string[] }`
+- [ ] Graceful degradation: returns `{ error: 'GRAPH_UNAVAILABLE' }` when graphStore is null OR unhealthy
+- [ ] Upserts both source and target Symbol nodes before creating the edge
+- [ ] Sets `source: 'lsp'` on nodes to distinguish from AST-parsed nodes
+
+### 3.5 Phase 5 Tools (2 new)
+
+#### `broadcast_finding`
+- [ ] Registered in `allTools` via `...collaborationTools` spread (server.ts:232)
+- [ ] Schema: `{ project_id: string, content: string, severity: 'info'|'warning'|'critical' [default 'info'], target_agents?: string[], symbols?: string[] }`
+- [ ] Returns: `{ broadcast: true, observation_id, severity, project_id }`
+- [ ] Saves observation to Qdrant (when available) with `category: 'agent_broadcast'`, `type: 'working'`
+- [ ] Records in SQLite `pipeline_events` as `event_type: 'agent_broadcast'`
+- [ ] Importance scaled by severity: critical=0.9, warning=0.7, info=0.5
+
+#### `get_broadcasts`
+- [ ] Registered in `allTools` via `...collaborationTools` spread
+- [ ] Schema: `{ project_id: string, since?: number, severity?: 'info'|'warning'|'critical' }`
+- [ ] Returns: `{ project_id, broadcasts: [...], count }`
+- [ ] Queries SQLite `pipeline_events` table with `event_type = 'agent_broadcast'`
+- [ ] Supports filtering by `since` timestamp and `severity`
+
+---
+
+## 4. Integration Points
+
+### 4.1 server.ts Wiring
+
+- [ ] All 9 tool factory imports present (lines 35-43): `createPipelineTools`, `createPhaseTools`, `createContextTools`, `createRegistrationTools`, `createLearningTools`, `createIngestionTools`, `createMemoryTools`, `createGraphTools`, `createCollaborationTools`
+- [ ] `ConfidenceManager` imported from `./learning/confidence.js` (line 45)
+- [ ] `ConfidenceManager` instantiated at line 134
+- [ ] `confidenceManager` passed to `ContextInjector` constructor (line 191)
+- [ ] `confidenceManager` passed to `createLearningTools` (line 213)
+- [ ] `vectorStore` passed as `QdrantVectorStore` to `ContextInjector` (line 192)
+- [ ] `vectorStore` passed as `QdrantVectorStore | null` to `createLearningTools` (line 214)
+- [ ] All tool objects spread into `allTools`: `pipelineTools`, `phaseTools`, `contextTools`, `registrationTools`, `learningTools`, `ingestionTools`, `memoryTools`, `graphTools`, `collaborationTools` (lines 223-233)
+- [ ] Periodic confidence decay interval set at 24 hours (line 303-309)
+- [ ] Decay interval calls `confidenceManager.decayAll(vectorStore)` with proper null guard (line 305)
+
+### 4.2 Auto-Observation in Phase Handlers (Phase 2)
+
+- [ ] `phase-tools.ts` imports `saveObservation` from `observation-store.ts` (line 11)
+- [ ] `phase-tools.ts` imports `getCurrentSessionId` from `session-tracker.ts` (line 12)
+- [ ] `autoObserve` helper defined with null guards (line 170-202)
+- [ ] `autoObserve` guards against `vectorStore === null` (line 181)
+- [ ] `autoObserve` uses `noOpGraphStore` when graphStore is null (line 196)
+- [ ] `autoObserve` wraps in `.catch()` — NEVER blocks phase transition (line 197-202)
+- [ ] `submit_vision` calls `autoObserve` with `category: 'vision'`, `importance: 0.6` (line 302)
+- [ ] `submit_plan` calls `autoObserve` with `category: 'architecture'`, `importance: 0.6` (line 442)
+- [ ] `submit_design` calls `autoObserve` with `category: 'design'`, `importance: 0.5` (line 557)
+- [ ] `submit_test_plan` calls `autoObserve` with `category: 'test_plan'`, `importance: 0.5` (line 672)
+- [ ] `submit_implementation` calls `autoObserve` with `category: 'implementation'`, `importance: 0.5` (line 811)
+- [ ] `submit_verdict` calls `autoObserve` with `category: 'inspection'`, `importance: 0.7` (line 947)
+- [ ] All auto-observations tagged with `['auto_observation', phase_name, project_id]`
+
+### 4.3 Intent Detection in `get_codebase_context` (Phase 1)
+
+- [ ] `context-tools.ts` imports `detectIntent` and `getIntentStrategy` from `intent-detector.ts` (line 11)
+- [ ] `detectIntent(input.query)` called in `get_codebase_context` handler (line 115)
+- [ ] `getIntentStrategy(queryIntent)` called to get weight adjustments (line 116)
+- [ ] `strategy.vectorWeight` passed to `codebaseContext.getContext()` (line 125)
+- [ ] `strategy.graphWeight` passed to `codebaseContext.getContext()` (line 126)
+- [ ] `strategy.includeTests` used as fallback for include_tests (line 122)
+- [ ] `queryIntent` returned in response (not hardcoded `'read'`) (line 175)
+
+### 4.4 Related Memories in `get_codebase_context`
+
+- [ ] `memoryBridge` parameter accepted in `createContextTools` (line 56)
+- [ ] `memoryBridge` passed from server.ts (line 203)
+- [ ] `memoryBridge.searchMemories(input.query, ...)` called in handler (line 136)
+- [ ] Results mapped to `relatedMemories` array (line 140-143)
+- [ ] `related_memories` field populated in response (line 174)
+- [ ] Memory search failure is non-fatal (wrapped in try/catch, logged at debug level) (line 144-148)
+
+### 4.5 Confidence Boost in ContextInjector
+
+- [ ] `ContextInjector` accepts `ConfidenceManager` as optional constructor param (line 150)
+- [ ] `ContextInjector` accepts `QdrantVectorStore` as optional constructor param (line 151)
+- [ ] `boostConsumedKnowledge()` method defined as fire-and-forget (line 158-166)
+- [ ] Boost called after knowledge search results are consumed during phase context assembly
+- [ ] Boost is guarded against null `confidenceManager` or `vectorStore` (line 165)
+
+### 4.6 Hotspot Signal in Hybrid Search (Phase 3)
+
+- [ ] `ranking.ts` has 5-signal scoring: vector (0.55), graph (0.20), recency (0.05), hotspot (0.10), observation (0.10) (lines 11-15)
+- [ ] `ScoredResult` interface includes `hotspotScore` and `observationScore` fields (lines 26-27)
+- [ ] `computeScore()` accepts `hotspotScore`, `hotspotWeight`, `observationScore`, `observationWeight` parameters with backward-compatible defaults (lines 52-55)
+- [ ] `hybrid-search.ts` imports `QUERY_FILE_HOTSPOTS` from `graph-queries.ts` (line 15)
+- [ ] `HybridSearchOptions` includes `intent?: QueryIntent` (line 27)
+
+### 4.7 Git Commits Collection in Qdrant (Phase 3)
+
+- [ ] `qdrant-store.ts` has `ensureGitCommitsCollection()` method
+- [ ] `qdrant-store.ts` has `upsertGitCommits()` method
+- [ ] `qdrant-store.ts` has `searchGitCommits()` method
+- [ ] `qdrant-store.ts` has `deleteGitCommitsByRepo()` method
+- [ ] `context-tools.ts` checks for `'searchGitCommits' in vectorStore` before calling (line 337)
+
+### 4.8 Staleness Detection (Phase 2)
+
+- [ ] `indexer.ts` calls `MARK_SYMBOL_OBSERVATIONS_STALE` when entities change on re-index
+- [ ] Stale observations appear with `is_stale` flag in search results
+
+### 4.9 Pipeline-Tools Jira Fields (Phase 5)
+
+- [ ] `createProjectSchema` includes `jira_ticket: z.string().optional()` (line 23)
+- [ ] `createProjectSchema` includes `jira_epic: z.string().optional()` (line 24)
+- [ ] Jira fields stored in project metadata JSON (line 91-93)
+- [ ] Jira fields returned by `get_state` via project metadata
+
+---
+
+## 5. Agent Prompt Checks
+
+### 5.1 Memory & Observation Section (all 12 agents)
+
+- [ ] `plugin/agents/architect.md` has `## Memory & Observation Tools` section (line 245)
+- [ ] `plugin/agents/backend-specialist.md` has `## Memory & Observation Tools` section (line 153)
+- [ ] `plugin/agents/data-specialist.md` has `## Memory & Observation Tools` section (line 156)
+- [ ] `plugin/agents/designer.md` has `## Memory & Observation Tools` section (line 322)
+- [ ] `plugin/agents/frontend-specialist.md` has `## Memory & Observation Tools` section (line 131)
+- [ ] `plugin/agents/inspector.md` has `## Memory & Observation Tools` section (line 341)
+- [ ] `plugin/agents/knowledge-keeper.md` has `## Memory & Observation Tools` section (line 313)
+- [ ] `plugin/agents/platform-engineer.md` has `## Memory & Observation Tools` section (line 205)
+- [ ] `plugin/agents/product-manager.md` has `## Memory & Observation Tools` section (line 240)
+- [ ] `plugin/agents/qa-strategist.md` has `## Memory & Observation Tools` section (line 314)
+- [ ] `plugin/agents/strategist.md` has `## Memory & Observation Tools` section (line 274)
+- [ ] `plugin/agents/supervisor.md` has `## Memory & Observation Tools` section (line 212)
+
+### 5.2 Graph Analysis Section (7 agents)
+
+- [ ] `plugin/agents/architect.md` has `## Graph Analysis Tools` section (line 258)
+- [ ] `plugin/agents/backend-specialist.md` has `## Graph Analysis Tools` section (line 166)
+- [ ] `plugin/agents/data-specialist.md` has `## Graph Analysis Tools` section (line 169)
+- [ ] `plugin/agents/frontend-specialist.md` has `## Graph Analysis Tools` section (line 144)
+- [ ] `plugin/agents/inspector.md` has `## Graph Analysis Tools` section (line 354)
+- [ ] `plugin/agents/knowledge-keeper.md` has `## Graph Analysis Tools` section (line 326)
+- [ ] `plugin/agents/platform-engineer.md` has `## Graph Analysis Tools` section (line 219)
+- [ ] Agents WITHOUT Graph Analysis: `designer.md`, `product-manager.md`, `qa-strategist.md`, `strategist.md`, `supervisor.md` (5 agents -- confirm these do NOT have the section)
+
+### 5.3 Atlassian Section (7 agents)
+
+- [ ] `plugin/agents/architect.md` has `## Atlassian Context (Optional)` section (line 278)
+- [ ] `plugin/agents/inspector.md` has `## Atlassian Context (Optional)` section (line 374)
+- [ ] `plugin/agents/knowledge-keeper.md` has `## Atlassian Context (Optional)` section (line 340)
+- [ ] `plugin/agents/platform-engineer.md` has `## Atlassian Context (Optional)` section (line 239)
+- [ ] `plugin/agents/product-manager.md` has `## Atlassian Context (Optional)` section (line 260)
+- [ ] `plugin/agents/strategist.md` has `## Atlassian Context (Optional)` section (line 294)
+- [ ] `plugin/agents/supervisor.md` has `## Atlassian Context (Optional)` section (line 238)
+- [ ] All Atlassian sections include "If unavailable, skip without error" language
+- [ ] Agents WITHOUT Atlassian: `backend-specialist.md`, `data-specialist.md`, `designer.md`, `frontend-specialist.md`, `qa-strategist.md` (5 agents -- confirm these do NOT have the section)
+
+### 5.4 Cross-Agent Collaboration Section (all 12 agents)
+
+- [ ] `plugin/agents/architect.md` has `## Cross-Agent Collaboration` section (line 271)
+- [ ] `plugin/agents/backend-specialist.md` has `## Cross-Agent Collaboration` section (line 179)
+- [ ] `plugin/agents/data-specialist.md` has `## Cross-Agent Collaboration` section (line 182)
+- [ ] `plugin/agents/designer.md` has `## Cross-Agent Collaboration` section (line 335)
+- [ ] `plugin/agents/frontend-specialist.md` has `## Cross-Agent Collaboration` section (line 157)
+- [ ] `plugin/agents/inspector.md` has `## Cross-Agent Collaboration` section (line 367)
+- [ ] `plugin/agents/knowledge-keeper.md` has `## Cross-Agent Collaboration` section (line 333)
+- [ ] `plugin/agents/platform-engineer.md` has `## Cross-Agent Collaboration` section (line 232)
+- [ ] `plugin/agents/product-manager.md` has `## Cross-Agent Collaboration` section (line 253)
+- [ ] `plugin/agents/qa-strategist.md` has `## Cross-Agent Collaboration` section (line 327)
+- [ ] `plugin/agents/strategist.md` has `## Cross-Agent Collaboration` section (line 287)
+- [ ] `plugin/agents/supervisor.md` has `## Cross-Agent Collaboration` section (line 231)
+- [ ] All Collaboration sections reference `broadcast_finding` and `get_broadcasts`
+
+---
+
+## 6. Plugin Config
+
+### 6.1 `.mcp.json`
+
+- [ ] `plugin/.mcp.json` has `dk-forge` server entry with correct args (line 2-5)
+- [ ] `plugin/.mcp.json` has `atlassian` server entry (line 6-14)
+- [ ] Atlassian entry uses `uvx` command with `mcp-atlassian` arg
+- [ ] Atlassian entry references env vars: `JIRA_URL`, `JIRA_USERNAME`, `JIRA_API_TOKEN`
+- [ ] Env var references use `${VAR}` syntax
+
+### 6.2 Atlassian Integration Docs
+
+- [ ] `plugin/docs/atlassian-integration.md` exists
+- [ ] Doc covers prerequisites (Python 3.10+, uvx, Jira Cloud)
+- [ ] Doc covers environment variables table
+- [ ] Doc covers graceful degradation behavior
+- [ ] Doc lists which 7 agents use Jira and which 5 do not
+- [ ] Doc covers troubleshooting (MCP start failure, auth errors, env var issues)
+
+---
+
+## 7. VS Code Extension (`vscode-extension/`)
+
+### 7.1 Project Structure
+
+- [ ] `vscode-extension/package.json` exists
+- [ ] `vscode-extension/tsconfig.json` exists
+- [ ] `vscode-extension/src/extension.ts` exists
+- [ ] `vscode-extension/src/edge-collector.ts` exists
+- [ ] `vscode-extension/src/forge-client.ts` exists
+
+### 7.2 Extension Manifest (`package.json`)
+
+- [ ] Name is `forge-lsp-bridge`
+- [ ] Activates on `typescript`, `javascript`, `typescriptreact`, `javascriptreact` files
+- [ ] `main` points to `./out/extension.js`
+- [ ] Configuration contributes: `forge.lspBridge.enabled` (boolean, default true)
+- [ ] Configuration contributes: `forge.lspBridge.repoId` (string, auto-detected from manifest)
+- [ ] Configuration contributes: `forge.lspBridge.debounceMs` (number, default 5000, min 1000, max 30000)
+- [ ] Configuration contributes: `forge.lspBridge.mcpServerPath` (string, path to dist/index.js)
+- [ ] Commands: `forge.lspBridge.toggle` and `forge.lspBridge.flush`
+- [ ] VS Code engine: `^1.85.0`
+
+### 7.3 TypeScript Config (`tsconfig.json`)
+
+- [ ] `module: "commonjs"` (required for VS Code extensions)
+- [ ] `target: "ES2022"`
+- [ ] `outDir: "out"`
+- [ ] `rootDir: "src"`
+- [ ] `strict: true`
+- [ ] Does NOT conflict with the main project tsconfig (separate tsconfig in vscode-extension/)
+
+### 7.4 Extension Entry Point (`extension.ts`)
+
+- [ ] Exports `activate` and `deactivate` functions
+- [ ] Creates `EdgeCollector` with debounce callback
+- [ ] Creates `ForgeClient` for MCP communication
+- [ ] Auto-detects `repoId` from `.forge/manifest.yaml` in workspace root
+- [ ] Registers save listener on TS/JS files only (`SUPPORTED_LANGUAGES` set)
+- [ ] Status bar item shows enabled/disabled state
+- [ ] Toggle command registered (`forge.lspBridge.toggle`)
+- [ ] Flush command registered (`forge.lspBridge.flush`)
+- [ ] Configuration change watcher updates debounce, repoId, and enabled state
+- [ ] Deactivation flushes pending edges and disposes client
+
+### 7.5 Edge Collector (`edge-collector.ts`)
+
+- [ ] Uses `vscode.commands.executeCommand('vscode.prepareCallHierarchy')` for call hierarchy API
+- [ ] Uses `vscode.commands.executeCommand('vscode.provideOutgoingCalls')` for outgoing calls
+- [ ] Uses `vscode.commands.executeCommand('vscode.executeDocumentSymbolProvider')` for symbol discovery
+- [ ] Filters to callable symbols only: Function, Method, Constructor
+- [ ] Builds qualified symbol names (e.g. `ClassName.methodName`)
+- [ ] Collects `CALLS` edge type
+- [ ] Skips self-references and `node_modules` targets
+- [ ] Implements debounced flushing (configurable interval)
+- [ ] `flushNow()` method for manual/deactivation flush
+- [ ] Deduplicates edges within a batch before flushing
+- [ ] Re-queues edges on flush failure
+
+### 7.6 Forge Client (`forge-client.ts`)
+
+- [ ] Spawns dk-forge-server as child process on stdio
+- [ ] Uses JSON-RPC 2.0 protocol with Content-Length framing
+- [ ] Sends MCP `initialize` handshake with protocol version `2024-11-05`
+- [ ] Sends `notifications/initialized` after handshake
+- [ ] Calls `tools/call` with `name: 'submit_lsp_edges'` to submit edges
+- [ ] Parses MCP tool response content blocks
+- [ ] 30-second request timeout
+- [ ] Lazy initialization (spawns server on first use)
+- [ ] Proper cleanup on dispose (kills child process, clears pending requests)
+- [ ] Sets `FORGE_LOG_LEVEL=warn` to prevent server log pollution on stdout
+- [ ] Default server path resolves to `../../dist/index.js` relative to extension
+
+---
+
+## 8. Cross-Cutting Checks
+
+### 8.1 Graceful Degradation Matrix
+
+| Tool | vectorStore=null | graphStore=null | Both null |
+|------|-----------------|-----------------|-----------|
+| `save_observation` | [ ] Returns error, stored: false | [ ] Uses noOpGraphStore | [ ] Returns error |
+| `search_memory` | [ ] MemoryBridge handles internally | [ ] N/A | [ ] Returns empty |
+| `get_session_context` | [ ] Returns error | [ ] N/A | [ ] Returns error |
+| `get_impact_graph` | [ ] N/A | [ ] Returns GRAPH_UNAVAILABLE | [ ] Returns error |
+| `search_logic_flow` | [ ] N/A | [ ] Returns GRAPH_UNAVAILABLE | [ ] Returns error |
+| `get_index_status` | [ ] Reports degraded health | [ ] Reports degraded health | [ ] Reports unavailable |
+| `boost_knowledge` | [ ] Returns CONFIDENCE_UNAVAILABLE | [ ] N/A | [ ] Returns error |
+| `decay_knowledge` | [ ] Returns CONFIDENCE_UNAVAILABLE | [ ] N/A | [ ] Returns error |
+| `get_git_context` (hotspots) | [ ] N/A | [ ] Returns GRAPH_UNAVAILABLE | [ ] Returns error |
+| `get_git_context` (commit_search) | [ ] Returns GIT_COMMITS_UNAVAILABLE | [ ] N/A | [ ] Returns error |
+| `get_git_context` (file_history) | [ ] N/A | [ ] Returns GRAPH_UNAVAILABLE | [ ] Returns error |
+| `submit_lsp_edges` | [ ] N/A | [ ] Returns GRAPH_UNAVAILABLE | [ ] Returns error |
+| `broadcast_finding` | [ ] Saves to SQLite only, skips observation | [ ] Uses noOpGraphStore | [ ] SQLite-only |
+| `get_broadcasts` | [ ] Queries SQLite only | [ ] N/A | [ ] Queries SQLite only |
+| Auto-observations (phase) | [ ] Skipped silently (debug log) | [ ] Uses noOpGraphStore | [ ] Skipped silently |
+
+### 8.2 No Blocking on Failure
+
+- [ ] All `autoObserve` calls use `.catch()` (fire-and-forget pattern)
+- [ ] All confidence boost calls in `ContextInjector` are fire-and-forget (line 158-160)
+- [ ] Periodic decay interval uses `.catch()` (server.ts line 307)
+- [ ] `broadcast_finding` observation save failure is non-fatal (collaboration-tools.ts line 75-77)
+- [ ] Memory search in `get_codebase_context` is non-fatal (context-tools.ts line 144-148)
+
+### 8.3 Anti-Stub Checks
+
+- [ ] No placeholder/TODO comments in new tool handlers that skip actual implementation
+- [ ] All Zod schemas are complete (no `z.any()` or `z.unknown()` placeholders)
+- [ ] All handler functions have real return values (not `return {}` stubs)
+- [ ] `autoObserve` actually calls `saveObservation` (not stubbed)
+- [ ] `ContextInjector.boostConsumedKnowledge` actually calls `confidenceManager.boost` (not stubbed)
+- [ ] `ForgeClient.submitLspEdges` actually sends JSON-RPC request (not stubbed)
+- [ ] `EdgeCollector.collectFromDocument` actually queries VS Code APIs (not stubbed)
+
+### 8.4 Security
+
+- [ ] Cypher queries in `context-tools.ts` use `escCypher()` to prevent injection (line 488-494)
+- [ ] No raw user input concatenated into SQL queries (SQLite uses parameterized queries in collaboration-tools.ts)
+- [ ] No secrets/credentials hardcoded in any source file
+- [ ] Atlassian credentials referenced only via `${ENV_VAR}` syntax in `.mcp.json`
+
+---
+
+## 9. Functional Verification (Manual Test Plan)
+
+### After Build Succeeds
+
+1. [ ] Start forge server: `npm start` — verify tool count in startup log matches expected (34)
+2. [ ] Call `save_observation` with `{ content: "test", symbols: ["createForgeServer"] }` — verify `stored: true`
+3. [ ] Call `search_memory` with `{ query: "test" }` — verify the saved observation appears
+4. [ ] Call `get_session_context` — verify `current_session` has valid `session_id` and `uptime_seconds`
+5. [ ] Call `get_impact_graph` with `{ symbol: "createForgeServer", repo_id: "...", direction: "inbound" }` (requires FalkorDB running)
+6. [ ] Call `search_logic_flow` with two known connected symbols (requires FalkorDB)
+7. [ ] Call `get_codebase_context` with a debug-style query (e.g. "why is the build failing") — verify `query_intent` is `'debug'`, NOT `'read'`
+8. [ ] Call `get_codebase_context` — verify `related_memories` is populated (not `[]`) if observations exist
+9. [ ] Call `get_index_status` — verify health reflects actual backend connectivity
+10. [ ] Call `get_git_context` with `mode: 'hotspots'` — verify returns files sorted by commit count (requires indexed repo + FalkorDB)
+11. [ ] Call `broadcast_finding` with `{ project_id: "test", content: "test finding", severity: "warning" }` — verify `broadcast: true`
+12. [ ] Call `get_broadcasts` with `{ project_id: "test" }` — verify the broadcast appears
+13. [ ] Run a full pipeline through `submit_verdict` — verify auto-observations created (search for `tags: ['auto_observation']`)
+14. [ ] Verify `boost_knowledge` and `decay_knowledge` work with valid knowledge IDs

package/docs/plans/completed/2026-02-27-git-history-atlassian/git-jira-plan.md

@@ -0,0 +1,181 @@
+# Plan: Git History Enrichment + Atlassian Integration for dk-forge-server
+
+**Date**: 2026-02-27
+**Status**: ABSORBED — This plan was incorporated into the forge-swarm-learning architecture (`docs/plans/completed/2026-02-27-forge-swarm-learning/architecture.md`). Git enrichment was implemented as Phase 3 and Atlassian integration as Phase 5 of that plan. Both are now complete.
+**Author**: Architect (on behalf of Adam Reynolds)
+
+## Context
+
+The dk-forge-server indexes code for semantic search but **barely uses the git history it already captures**. The `git-analyzer.ts` extracts CO_MODIFIED edges (files changed together) but misses change frequency, hotspots, commit messages, and stability metrics. Meanwhile, agents have no access to Jira tickets, PR feedback, or sprint context — despite heavy Jira usage.
+
+**Goal**: Make agents smarter by giving them (1) enriched git history signals and (2) Atlassian project context.
+
+---
+
+## Part 1: Git History Enrichment (Server Code Changes)
+
+### What's new (beyond existing CO_MODIFIED edges)
+
+| Signal | Storage | Used By |
+|--------|---------|---------|
+| Per-file commit count | FalkorDB File node property | Hybrid search hotspot boost |
+| Stability score (0-1) | FalkorDB File node property | Architect, Inspector context |
+| Change velocity (-1 to +1) | FalkorDB File node property | Supervisor routing |
+| Last commit hash + timestamp | FalkorDB File node property | Recency awareness |
+| Recent commit messages (per file) | New Qdrant `git_commits` collection | Semantic commit search |
+
+### Files to modify
+
+**1. `src/util/types.ts`** — Add types
+- `FileChangeStats` interface (commitCount, stabilityScore, changeVelocity, lastCommitHash, lastCommitTs, recentMessages)
+- `CommitRecord` interface (hash, message, author, timestamp, files)
+- `GitCommitPayload` interface for Qdrant (repo_id, commit_hash, message, author, timestamp, file_paths)
+- Extend `GitAnalysisResult` → `EnrichedGitAnalysisResult` with `fileStats` and `commits`
+
+**2. `src/ingestion/git-analyzer.ts`** — Enrich git log parsing
+- Change `git log --format="%H"` → `git log --format="%H|%s|%an|%aI"` (add subject, author, date)
+- Add `analyzeFileStats()` — compute per-file: commit count, stability score, velocity (recent half vs. older half of history), last commit info
+- Add `extractCommitRecords()` — parse into `CommitRecord[]` (filter merge commits + bulk reformats >50 files)
+- Update `runGitAnalysis()` to return enriched result + upsert file stats onto FalkorDB File nodes
+
+**3. `src/storage/qdrant-store.ts`** — New `git_commits` collection
+- Add `ensureGitCommitsCollection()` to `ensureCollections()`
+- Payload indexes: `repo_id` (keyword), `commit_hash` (keyword), `author` (keyword), `timestamp` (integer), `file_paths` (keyword)
+- Add `upsertGitCommits()`, `searchGitCommits()`, `deleteGitCommitsByRepo()`
+
+**4. `src/ingestion/indexer.ts`** — Embed commit messages during indexing
+- After `runGitAnalysis()`, batch-embed commit messages via `embedBatch()`
+- Store as Qdrant points in `git_commits` collection with `GitCommitPayload`
+- ~300-400 commits after filtering → ~2-3s extra indexing time
+
+**5. `src/query/ranking.ts`** — Add hotspot signal to scoring
+- Change weights: 0.6/0.3/0.1 → 0.55/0.25/0.10/0.10
+- Add `hotspotScore` and `hotspotWeight` params to `computeScore()` (defaults to 0/0.10 — backward compatible)
+- Add `hotspotScore` to `ScoredResult` interface
+- Extend `buildMatchReason()` to include "hotspot (frequently changed)" when score > 0.5
+
+**6. `src/query/hybrid-search.ts`** — Integrate hotspot into search pipeline
+- After graph neighbor expansion, fetch file hotspot scores from FalkorDB
+- Normalize: `hotspot = file.commit_count / max_commit_count_in_results`
+- Pass to `computeScore()` as 4th signal
+- For `modify`/`debug`/`refactor` intent: hotspot boosts volatile files. For `read` intent: no boost
+
+**7. `src/query/graph-queries.ts`** — New graph queries
+- `QUERY_FILE_HOTSPOTS(repoId)` — top 100 files by commit_count
+- `QUERY_FILE_STATS(filePath, repoId)` — single file stats
+
+**8. `src/tools/context-tools.ts`** — New `get_git_context` MCP tool
+- Modes: `hotspots` | `commit_search` | `file_history`
+- `hotspots`: top N files by change frequency + stability + velocity
+- `commit_search`: semantic search over commit messages in Qdrant
+- `file_history`: last N commits for a specific file
+- Falls back to raw `git log` when FalkorDB/Qdrant unavailable
+
+**9. `src/server.ts`** — Wire new tool
+- Pass `vectorStore` to `createContextTools()`
+- Register `get_git_context` tool
+
+### Graceful degradation
+- No git → empty results (existing pattern)
+- No FalkorDB → hotspot score = 0, `hotspots` mode falls back to raw git
+- No Qdrant → `commit_search` returns empty, `file_history` falls back to raw git
+- All three down → all git features silently degrade, existing functionality unaffected
+
+---
+
+## Part 2: Atlassian Integration (Plugin-Level, No Server Code in Phase 1)
+
+### Architecture
+
+MCP is client→server only — dk-forge **cannot** call Atlassian MCP tools. But the plugin's `.mcp.json` can declare multiple servers. Claude (the client) mediates.
+
+### MCP server configuration
+
+```json
+{
+  "dk-forge": {
+    "command": "node",
+    "args": ["${CLAUDE_PLUGIN_ROOT}/../dist/index.js"]
+  },
+  "atlassian": {
+    "command": "uvx",
+    "args": ["mcp-atlassian"],
+    "env": {
+      "JIRA_URL": "${JIRA_URL}",
+      "JIRA_USERNAME": "${JIRA_USERNAME}",
+      "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
+    }
+  }
+}
+```
+
+Using [sooperset/mcp-atlassian](https://github.com/sooperset/mcp-atlassian) (68 tools: 52 Jira + 16 Confluence). Bitbucket can be added separately if needed.
+
+**Note**: Env vars use `${VAR}` interpolation — users set these in their environment. If vars are missing, the server fails to start but dk-forge works fine alone.
+
+### Agent prompt modifications (7 agents)
+
+| Agent | What to add | Tools referenced |
+|-------|------------|-----------------|
+| **Strategist** | Pre-interview: pull linked Jira issue, sprint context. Post-vision: comment on ticket | `jira_get_issue`, `jira_search`, `jira_get_sprint_issues`, `jira_add_comment` |
+| **Architect** | Check blocking issues, linked PRs, review feedback. Post-plan: comment on ticket | `jira_get_issue`, `jira_get_issue_development_info`, `jira_search`, `jira_add_comment` |
+| **Inspector** | Check acceptance criteria from ticket. Post-verdict: comment pass/fail on ticket | `jira_get_issue`, `jira_add_comment`, `jira_transition_issue` |
+| **Knowledge Keeper** | Pull ticket changelog for decision history. Post-extraction: comment summary | `jira_batch_get_changelogs`, `jira_add_comment` |
+| **Product Manager** | Pull existing stories/epics to avoid duplicate requirements | `jira_search`, `jira_get_issue` |
+| **Supervisor** | Check sprint capacity for routing priority | `jira_get_sprint_issues` |
+| **Platform Engineer** | Check CI pipeline status via Bitbucket (if configured) | Bitbucket tools (Phase 2) |
+
+**NOT modified**: Backend/Frontend/Data Specialists, Designer, QA Strategist — they receive context from upstream planning agents. Adding Jira calls to implementation agents = latency + token waste.
+
+### Graceful degradation pattern
+
+Every Atlassian section in agent prompts uses this pattern:
+```
+## Atlassian Context (Optional)
+These tools are OPTIONAL. If unavailable, skip without error and proceed normally.
+```
+
+Strategist probes `jira_search` on pipeline start. If it fails → sets `atlassian_available: false` in session state → all downstream agents skip Atlassian calls.
+
+### New documentation
+
+- `plugin/docs/atlassian-integration.md` — Setup guide, expected server names, what each agent does with Jira context
+
+---
+
+## Part 3: Phase 2 Server Changes for Atlassian (Future)
+
+Not in this implementation, but designed for:
+- Add `jira_ticket` and `jira_epic` optional fields to `create_project` schema
+- Store in project metadata → returned by `get_state` → agents auto-discover ticket key
+- Knowledge Keeper indexes closed ticket resolutions as knowledge items during `collect_knowledge`
+
+---
+
+## Implementation Order
+
+| Step | What | Parallelizable? |
+|------|------|----------------|
+| 1 | Types (`types.ts`) + ranking weights (`ranking.ts`) | Yes — independent |
+| 2 | Git analyzer enrichment + Qdrant git_commits collection | Yes — both in parallel |
+| 3 | Indexer integration (embed commits, store file stats) | After step 2 |
+| 4 | Hybrid search hotspot integration | After step 1 |
+| 5 | `get_git_context` MCP tool + server wiring | After steps 3+4 |
+| 6 | Agent prompt updates (git context references) | After step 5 |
+| 7 | `.mcp.json` Atlassian server + agent Atlassian sections | **Parallel with steps 1-5** |
+| 8 | `plugin/docs/atlassian-integration.md` | After step 7 |
+| 9 | Rebuild dist/, test end-to-end | After all |
+
+Steps 1-6 (git) and step 7 (Atlassian prompts) are fully independent — can be dispatched to parallel specialists.
+
+---
+
+## Verification
+
+1. **Build**: `npm run build` succeeds
+2. **Existing tests**: `npm test` passes (no regressions)
+3. **Git indexing**: Run `forge index --path . --force` on this repo → verify git_commits collection populated in Qdrant, File nodes have commit_count/stability_score in FalkorDB
+4. **New tool**: Call `mcp__dk-forge__get_git_context` with mode=hotspots → returns file list sorted by commit count
+5. **Commit search**: Call `mcp__dk-forge__get_git_context` with mode=commit_search, query="rebrand forge pipeline" → returns relevant commits
+6. **Hybrid search**: Call `mcp__dk-forge__get_codebase_context` → verify match_reason includes hotspot info for volatile files
+7. **Atlassian**: With `mcp-atlassian` configured, run `/forge new test-feature` and verify strategist attempts `jira_search`. Without it configured, verify no errors.