sdlc-agent-4-enterprise-server 1.0.0

package/extension/src/chat-panel/message-handler.ts

@@ -0,0 +1,116 @@
+/**
+ * Message Handler --- KSA-210
+ * Dispatches incoming webview messages to the appropriate engine actions.
+ */
+
+import * as vscode from "vscode";
+import { debugLog } from "../debug-logger";
+import { LangGraphEngine } from "../langgraph/langgraph-engine";
+import { ChatWebviewToExtMessage, ChatExtToWebviewMessage, AutopilotMode } from "./message-protocol";
+import { buildEnrichedText, routeUserMessage } from "./message-routing";
+
+export class MessageHandler {
+  private currentModel: string = "auto";
+  private currentMode: AutopilotMode = "autopilot";
+
+  constructor(
+    private readonly getEngine: () => LangGraphEngine,
+    private readonly sendToWebview: (msg: ChatExtToWebviewMessage) => void,
+    private readonly onPickContext?: (contextType: string) => void,
+    private readonly onPickAttachment?: () => void,
+    private readonly onApplyCode?: (code: string, filePath?: string) => void,
+    private readonly onInsertCode?: (code: string) => void,
+    private readonly onSetModel?: (model: string) => void
+  ) {}
+
+  async handle(msg: ChatWebviewToExtMessage): Promise<void> {
+    debugLog(` MessageHandler.handle: type="${msg.type}"`);
+    switch (msg.type) {
+      case "ready":
+      case "refresh":
+        await this.handleReady();
+        break;
+      case "chat:userMessage":
+        await this.handleUserMessage((msg as any).text, (msg as any).context);
+        break;
+      case "chat:approvalAction":
+        await this.handleApproval(msg.decision, msg.feedback);
+        break;
+      case "chat:cancelStream":
+        this.getEngine().cancel();
+        this.sendToWebview({ type: "chat:workingStatus", working: false });
+        this.sendToWebview({ type: "chat:streamComplete", streamId: "cancelled", nodeId: "user", finalContent: "Cancelled by user", metadata: {} } as any);
+        break;
+      case "chat:resumePipeline":
+        this.sendToWebview({ type: "chat:workingStatus", working: true, label: "Resuming..." });
+        await this.getEngine().resume(msg.threadId);
+        break;
+      case "chat:clearHistory": break;
+      case "chat:startFresh": break;
+      case "chat:graphNodeClick":
+        this.handleNodeClick(msg.nodeId);
+        break;
+      case "chat:openWorkflowGraph":
+        vscode.commands.executeCommand("kiroSdlc.openWorkflowGraph");
+        break;
+      case "chat:pickContext":
+        if (this.onPickContext) { this.onPickContext(msg.contextType); }
+        break;
+      case "chat:pickAttachment":
+        if (this.onPickAttachment) { this.onPickAttachment(); }
+        break;
+      case "chat:setModel":
+        this.currentModel = msg.model;
+        if (this.onSetModel) { this.onSetModel(msg.model); }
+        break;
+      case "chat:setMode":
+        this.currentMode = msg.mode;
+        break;
+      case "chat:applyCode":
+        if (this.onApplyCode) { this.onApplyCode(msg.code, msg.filePath); }
+        break;
+      case "chat:insertCode":
+        if (this.onInsertCode) { this.onInsertCode(msg.code); }
+        break;
+      case "tab:create": break;
+      case "tab:switch":
+        this.getEngine().switchActiveTab((msg as any).payload.tabId);
+        break;
+      case "tab:close": break;
+      case "tab:rename": break;
+    }
+  }
+
+  private async handleReady(): Promise<void> {
+    const pipelines = this.getEngine().listPersistedPipelines();
+    const paused = pipelines.find(p => p.status === "paused" || p.status === "running");
+    if (paused) {
+      this.sendToWebview({ type: "chat:resumePrompt", threadId: paused.threadId, ticketKey: paused.ticketKey, phase: paused.phase, pausedAt: paused.lastUpdatedAt });
+    }
+    const nodes = this.getEngine().getCurrentNodeStates();
+    this.sendToWebview({ type: "chat:graphUpdate", nodes });
+  }
+
+  private async handleUserMessage(text: string, context?: Array<{ type: string; label: string; path?: string; content?: string }>): Promise<void> {
+    const enrichedText = buildEnrichedText(text, context);
+    debugLog(` handleUserMessage: "${text.slice(0, 80)}" (context: ${context?.length || 0} items)`);
+    this.sendToWebview({ type: "chat:workingStatus", working: true, label: "Working..." });
+    try {
+      const engine = this.getEngine();
+      await engine.hookEngine.firePromptSubmit(text, engine.getStreamHandler());
+    } catch { /* hooks must never break main execution */ }
+    await routeUserMessage(text, enrichedText, this.getEngine, this.sendToWebview);
+  }
+
+  private async handleApproval(decision: string, feedback?: string): Promise<void> {
+    const validDecisions = ["approve", "reject", "revise"] as const;
+    if (!validDecisions.includes(decision as any)) { return; }
+    await this.getEngine().handleApproval(decision as any, feedback);
+  }
+
+  private handleNodeClick(nodeId: string): void {
+    const nodes = this.getEngine().getCurrentNodeStates();
+    const node = nodes.find(n => n.id === nodeId);
+    if (node) { this.sendToWebview({ type: "chat:nodeDetails", node, recentOutputs: [] }); }
+  }
+}

package/extension/src/chat-panel/message-protocol.ts

@@ -0,0 +1,107 @@
+/**
+ * Chat Panel Message Protocol — KSA-210 + KSA-230
+ * Type definitions for postMessage communication between
+ * the Chat Panel webview and extension host.
+ * Enhanced with Kiro-style UI features: context mentions, attachments,
+ * model selector, autopilot toggle, tool calls, inline actions.
+ */
+
+import {
+  SDLCPhase,
+  PipelineStatus,
+  ApprovalDecision,
+  StreamEventType,
+  PipelineGraphNode,
+  QualityGateCheckpoint,
+  ChatMessage,
+  AgentOutput,
+} from "../langgraph/state";
+import { ContextUsagePayload } from "./context-usage-tracker";
+
+// === Context & Attachment Types ===
+
+export interface ContextItem {
+  type: "file" | "folder" | "problems" | "gitDiff" | "terminal" | "spec" | "currentFile" | "steering" | "mcp";
+  label: string;
+  path?: string;
+  content?: string;
+}
+
+export interface AttachmentItem {
+  name: string;
+  type: string; // MIME type
+  size: number;
+  uri: string; // webview-local URI or base64 data URI
+}
+
+export interface ToolCallDisplay {
+  id: string;
+  name: string;
+  args?: Record<string, unknown>;
+  status: "running" | "completed" | "failed";
+  result?: string;
+  duration?: number;
+}
+
+export type AutopilotMode = "autopilot" | "supervised";
+export type ModelOption = "auto" | "claude-sonnet" | "claude-haiku" | "gpt-4o" | "ollama" | "kiro";
+
+/** A model entry presented in the Chat Panel model dropdown */
+export interface ChatModelEntry {
+  id: string;
+  name: string;
+  /** Short description of the model's capabilities (from Kiro API). KSA-237 */
+  description?: string;
+  /** Credit cost multiplier (1 = standard, 1.9 = premium, 0 = free). KSA-237 */
+  rateMultiplier?: number;
+}
+
+// === Webview → Extension Messages ===
+
+export type ChatWebviewToExtMessage =
+  | { type: "chat:userMessage"; text: string; context?: ContextItem[]; attachments?: AttachmentItem[] }
+  | { type: "chat:approvalAction"; decision: ApprovalDecision; feedback?: string }
+  | { type: "chat:graphNodeClick"; nodeId: string }
+  | { type: "chat:cancelStream"; streamId?: string }
+  | { type: "chat:clearHistory" }
+  | { type: "chat:resumePipeline"; threadId: string }
+  | { type: "chat:startFresh" }
+  | { type: "chat:pickContext"; contextType: "file" | "folder" | "problems" | "gitDiff" | "terminal" | "spec" | "currentFile" | "steering" | "mcp" }
+  | { type: "chat:pickAttachment" }
+  | { type: "chat:setModel"; model: string }
+  | { type: "chat:setMode"; mode: AutopilotMode }
+  | { type: "chat:applyCode"; code: string; filePath?: string }
+  | { type: "chat:insertCode"; code: string }
+  | { type: "tab:create" }
+  | { type: "tab:switch"; payload: { tabId: string } }
+  | { type: "tab:close"; payload: { tabId: string } }
+  | { type: "tab:rename"; payload: { tabId: string; newName: string } }
+  | { type: "chat:openWorkflowGraph" }
+  | { type: "chat:saveState"; payload: { tabs: unknown[]; activeTabId: string } }
+  | { type: "ready" }
+  | { type: "refresh" };
+
+// === Extension → Webview Messages ===
+
+export type ChatExtToWebviewMessage =
+  | { type: "chat:streamChunk"; streamId: string; nodeId: string; eventType: StreamEventType; content: string; timestamp: string; metadata?: Record<string, unknown> }
+  | { type: "chat:streamComplete"; streamId: string; nodeId: string; finalContent: string; metadata?: Record<string, unknown> }
+  | { type: "chat:graphUpdate"; nodes: PipelineGraphNode[] }
+  | { type: "chat:approvalRequest"; checkpoint: QualityGateCheckpoint }
+  | { type: "chat:chatHistory"; messages: ChatMessage[] }
+  | { type: "chat:pipelineStatus"; status: PipelineStatus; phase: SDLCPhase; ticketKey: string }
+  | { type: "chat:nodeDetails"; node: PipelineGraphNode; recentOutputs: AgentOutput[] }
+  | { type: "chat:resumePrompt"; threadId: string; ticketKey: string; phase: SDLCPhase; pausedAt: string }
+  | { type: "chat:error"; code: string; message: string; retryable: boolean }
+  | { type: "chat:toolCall"; toolCall: ToolCallDisplay }
+  | { type: "chat:toolCallUpdate"; id: string; status: ToolCallDisplay["status"]; result?: string; duration?: number }
+  | { type: "chat:contextPicked"; item: ContextItem }
+  | { type: "chat:configUpdate"; model: string; mode: AutopilotMode; availableModels: ModelOption[] }
+  | { type: "chat:models"; provider: string; models: ChatModelEntry[]; selected: string; supportsAuto: boolean }
+  | { type: "chat:workingStatus"; working: boolean; label?: string }
+  | { type: "tab:updated"; payload: { tabs: Array<{ id: string; name: string; messages: unknown[]; tokenCount: number; maxTokens: number }>; activeTabId: string } }
+  | { type: "tab:contextUpdate"; payload: { tabId: string; tokenCount: number; maxTokens: number; percentage: number; threshold: string } }
+  | { type: "chat:steeringLoaded"; rules: Array<{ name: string; file: string }> }
+  | { type: "chat:hookTriggered"; hook: { name: string; type: string; status: "running" | "completed" | "skipped" } }
+  | { type: "chat:contextUsage"; payload: ContextUsagePayload }
+  | { type: "serverStatus"; status: "connected" | "disconnected" | "failed" };

package/extension/src/chat-panel/message-routing.ts

@@ -0,0 +1,111 @@
+/**
+ * Message Handler chat/pipeline routing --- KSA-210
+ */
+
+import * as vscode from "vscode";
+import { debugLog } from "../debug-logger";
+import { LangGraphEngine } from "../langgraph/langgraph-engine";
+import { ChatExtToWebviewMessage, AutopilotMode } from "./message-protocol";
+import { SDLCPhase } from "../langgraph/state";
+
+/** Pattern matching for ticket-based commands */
+const TICKET_PATTERN = /^([A-Z]+-\d+)\s+(.+)$/;
+
+/** Direct command patterns */
+const DIRECT_COMMANDS: Record<string, string> = { status: "status", resume: "resume", cancel: "cancel" };
+
+/** Phase keywords for ticket commands */
+const PHASE_KEYWORDS: Record<string, SDLCPhase> = {
+  brd: "requirements", "tao brd": "requirements", fsd: "specification",
+  "tao fsd": "specification", tdd: "design", "tao tdd": "design",
+  stp: "test_planning", "tao stp": "test_planning", implement: "implementation",
+  test: "testing", deploy: "deployment", full: "all",
+};
+
+export function parsePhase(action: string): SDLCPhase {
+  for (const [keyword, phase] of Object.entries(PHASE_KEYWORDS)) {
+    if (action.includes(keyword)) { return phase; }
+  }
+  return "all";
+}
+
+export function buildEnrichedText(text: string, context?: Array<{ type: string; label: string; path?: string; content?: string }>): string {
+  if (!context || context.length === 0) return text;
+  const sections: string[] = [];
+  for (const item of context) {
+    if (item.content) { sections.push(`<${item.type} name="${item.label}">\n${item.content}\n</${item.type}>`); }
+    else if (item.path) { sections.push(`<${item.type} name="${item.label}" path="${item.path}" />`); }
+  }
+  if (sections.length > 0) { return `<context>\n${sections.join("\n")}\n</context>\n\n${text}`; }
+  return text;
+}
+
+export async function routeUserMessage(
+  text: string,
+  enrichedText: string,
+  getEngine: () => LangGraphEngine,
+  sendToWebview: (msg: ChatExtToWebviewMessage) => void
+): Promise<void> {
+  const textTrimmed = text.trim().toLowerCase();
+
+  // Direct commands
+  if (DIRECT_COMMANDS[textTrimmed]) {
+    debugLog(` handleUserMessage: routed to DIRECT COMMAND "${textTrimmed}"`);
+    await handleDirectCommand(DIRECT_COMMANDS[textTrimmed], getEngine, sendToWebview);
+    sendToWebview({ type: "chat:workingStatus", working: false });
+    return;
+  }
+
+  // Agent command prefix
+  const agentMatch = text.trim().match(/^\/([a-z][-a-z]*)\s+(.+)$/i);
+  if (agentMatch) {
+    const [, agentName, agentTask] = agentMatch;
+    debugLog(` handleUserMessage: routed to AGENT "${agentName}"`);
+    sendToWebview({ type: "chat:workingStatus", working: true, label: `${agentName} --- working...` });
+    await getEngine().invokeChat(`[Agent: ${agentName}] ${agentTask}`);
+    sendToWebview({ type: "chat:workingStatus", working: false });
+    return;
+  }
+
+  // Ticket pattern
+  const match = text.trim().match(TICKET_PATTERN);
+  if (match) {
+    const ticketKey = match[1];
+    const action = match[2].trim().toLowerCase();
+    const phase = parsePhase(action);
+    debugLog(` handleUserMessage: routed to SDLC ticket=${ticketKey} phase=${phase}`);
+    sendToWebview({ type: "chat:workingStatus", working: true, label: `${ticketKey} --- ${phase}` });
+    await getEngine().invoke(ticketKey, phase, enrichedText);
+    sendToWebview({ type: "chat:workingStatus", working: false });
+    return;
+  }
+
+  // All other -> chat
+  debugLog(` handleUserMessage: routed to CHAT (invokeChat)`);
+  await getEngine().invokeChat(enrichedText);
+  debugLog(` handleUserMessage: invokeChat RETURNED`);
+
+  // Fire agentStop hooks
+  try { const engine = getEngine(); await engine.hookEngine.fireAgentStop(engine.getStreamHandler()); } catch { /* */ }
+  sendToWebview({ type: "chat:workingStatus", working: false });
+}
+
+async function handleDirectCommand(command: string, getEngine: () => LangGraphEngine, sendToWebview: (msg: ChatExtToWebviewMessage) => void): Promise<void> {
+  switch (command) {
+    case "status": {
+      const nodes = getEngine().getCurrentNodeStates();
+      sendToWebview({ type: "chat:graphUpdate", nodes });
+      break;
+    }
+    case "resume": {
+      const pipelines = getEngine().listPersistedPipelines();
+      const paused = pipelines.find(p => p.status === "paused");
+      if (paused) { await getEngine().resume(paused.threadId); }
+      else { sendToWebview({ type: "chat:error", code: "NO_PIPELINE", message: "No paused pipeline to resume.", retryable: false }); }
+      break;
+    }
+    case "cancel":
+      getEngine().cancel();
+      break;
+  }
+}

package/extension/src/chat-panel/token-counter.ts

@@ -0,0 +1,103 @@
+/**
+ * TokenCounter — KSA-240
+ * Calculates token usage for conversations.
+ * Uses character-based estimation (4 chars ~ 1 token) as default.
+ * Can be upgraded to use tiktoken for exact counts.
+ */
+
+import { TabMessage, ContextThreshold } from "./conversation-types";
+
+export interface TokenCounterConfig {
+  warningThreshold: number;  // default 0.6 (60%)
+  criticalThreshold: number; // default 0.8 (80%)
+  fullThreshold: number;     // default 0.95 (95%)
+}
+
+const DEFAULT_CONFIG: TokenCounterConfig = {
+  warningThreshold: 0.6,
+  criticalThreshold: 0.8,
+  fullThreshold: 0.95,
+};
+
+export class TokenCounter {
+  private config: TokenCounterConfig;
+
+  constructor(config: Partial<TokenCounterConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Estimate token count for a single message.
+   * Uses ~4 characters per token heuristic.
+   * Override with tiktoken integration for production accuracy.
+   */
+  countMessageTokens(content: string): number {
+    if (!content) return 0;
+    // ~4 chars per token is a reasonable English estimate
+    // Add overhead for message formatting (role, separators)
+    return Math.ceil(content.length / 4) + 4;
+  }
+
+  /**
+   * Calculate total token count for all messages in a conversation.
+   */
+  countConversationTokens(messages: TabMessage[]): number {
+    let total = 0;
+    for (const msg of messages) {
+      total += msg.tokenCount || this.countMessageTokens(msg.content);
+    }
+    // Add base overhead (system prompt, formatting)
+    total += 100;
+    return total;
+  }
+
+  /**
+   * Get usage percentage (0-100).
+   */
+  getUsagePercentage(tokenCount: number, maxTokens: number): number {
+    if (maxTokens <= 0) return 0;
+    return Math.min(100, Math.round((tokenCount / maxTokens) * 100));
+  }
+
+  /**
+   * Determine the threshold state based on usage percentage.
+   */
+  getThresholdState(percentage: number): ContextThreshold {
+    const ratio = percentage / 100;
+    if (ratio >= this.config.fullThreshold) return "full";
+    if (ratio >= this.config.criticalThreshold) return "critical";
+    if (ratio >= this.config.warningThreshold) return "warning";
+    return "safe";
+  }
+
+  /**
+   * Get max tokens for a given model.
+   * Returns reasonable defaults based on known model context windows.
+   */
+  getMaxTokensForModel(model: string): number {
+    const modelLimits: Record<string, number> = {
+      "claude-sonnet-4-20250514": 200000,
+      "claude-3-5-sonnet-20241022": 200000,
+      "claude-3-haiku-20240307": 200000,
+      "claude-3-opus-20240229": 200000,
+      "gpt-4o": 128000,
+      "gpt-4o-mini": 128000,
+      "gpt-4-turbo": 128000,
+      "deepseek-chat": 64000,
+      "deepseek-coder": 64000,
+    };
+
+    // Check exact match first
+    if (modelLimits[model]) return modelLimits[model];
+
+    // Check prefix match
+    for (const [key, value] of Object.entries(modelLimits)) {
+      if (model.startsWith(key.split("-").slice(0, 2).join("-"))) {
+        return value;
+      }
+    }
+
+    // Default fallback
+    return 128000;
+  }
+}

package/extension/src/checksum.ts

@@ -0,0 +1,197 @@
+// Checksum management --- per-file version tracking and modification detection
+import * as fs from "fs";
+import * as path from "path";
+import * as crypto from "crypto";
+
+export interface ChecksumManifest {
+    version: string;
+    generatedAt: string;
+    files: Record<string, FileChecksum>;
+}
+
+export interface FileChecksum {
+    hash: string;
+    version: string;
+    injectedAt: string;
+}
+
+export interface WorkspaceManifest {
+    lastUpdated: string;
+    files: Record<string, WorkspaceFileEntry>;
+}
+
+export interface WorkspaceFileEntry {
+    version: string;
+    hash: string;
+    injectedAt: string;
+}
+
+export interface FileStatus {
+    relativePath: string;
+    workspaceVersion: string;
+    bundledVersion: string;
+    state: "current" | "outdated" | "modified" | "missing";
+}
+
+export interface ModifiedFile {
+    relativePath: string;
+    expectedHash: string;
+    actualHash: string;
+    injectedVersion: string;
+}
+
+const WORKSPACE_MANIFEST = ".kiro/.sdlc-manifest.json";
+const LEGACY_VERSION_FILE = ".kiro/.sdlc-version";
+const BUNDLED_MANIFEST = "resources/.sdlc-checksums.json";
+
+/** Compute SHA-256 hash of a file's content. */
+export function computeFileHash(filePath: string): string {
+    const content = fs.readFileSync(filePath);
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+/** Load bundled checksums manifest from extension package. */
+export function loadBundledManifest(extensionPath: string): ChecksumManifest | null {
+    const manifestFile = path.join(extensionPath, BUNDLED_MANIFEST);
+    if (!fs.existsSync(manifestFile)) { return null; }
+    try {
+        return JSON.parse(fs.readFileSync(manifestFile, "utf-8"));
+    } catch {
+        return null;
+    }
+}
+
+/** Load per-file workspace manifest. */
+export function loadWorkspaceManifest(root: string): WorkspaceManifest | null {
+    const manifestFile = path.join(root, WORKSPACE_MANIFEST);
+    if (!fs.existsSync(manifestFile)) { return null; }
+    try {
+        return JSON.parse(fs.readFileSync(manifestFile, "utf-8"));
+    } catch {
+        return null;
+    }
+}
+
+/** Save workspace manifest to disk. */
+export function saveWorkspaceManifest(root: string, manifest: WorkspaceManifest): void {
+    const manifestFile = path.join(root, WORKSPACE_MANIFEST);
+    fs.mkdirSync(path.dirname(manifestFile), { recursive: true });
+    manifest.lastUpdated = new Date().toISOString();
+    fs.writeFileSync(manifestFile, JSON.stringify(manifest, null, 2), "utf-8");
+}
+
+/** Get per-file status comparing workspace vs bundled manifest. */
+export function getFileStatuses(root: string, extensionPath: string): FileStatus[] {
+    const bundled = loadBundledManifest(extensionPath);
+    if (!bundled) { return []; }
+    const wsManifest = loadWorkspaceManifest(root);
+
+    const statuses: FileStatus[] = [];
+    for (const [relativePath, entry] of Object.entries(bundled.files)) {
+        const fullPath = path.join(root, relativePath);
+        const wsEntry = wsManifest?.files[relativePath];
+        const wsVersion = wsEntry?.version || "0.0.0";
+
+        if (!fs.existsSync(fullPath)) {
+            statuses.push({ relativePath, workspaceVersion: wsVersion, bundledVersion: entry.version, state: "missing" });
+            continue;
+        }
+
+        if (wsVersion !== entry.version) {
+            statuses.push({ relativePath, workspaceVersion: wsVersion, bundledVersion: entry.version, state: "outdated" });
+        } else {
+            const currentHash = computeFileHash(fullPath);
+            if (currentHash !== entry.hash) {
+                statuses.push({ relativePath, workspaceVersion: wsVersion, bundledVersion: entry.version, state: "modified" });
+            } else {
+                statuses.push({ relativePath, workspaceVersion: wsVersion, bundledVersion: entry.version, state: "current" });
+            }
+        }
+    }
+    return statuses;
+}
+
+/** Detect files whose hash differs from bundled (for update prompts). */
+export function detectModifiedFiles(root: string, extensionPath: string): ModifiedFile[] {
+    const bundled = loadBundledManifest(extensionPath);
+    if (!bundled) { return []; }
+
+    const modified: ModifiedFile[] = [];
+    for (const [relativePath, entry] of Object.entries(bundled.files)) {
+        const fullPath = path.join(root, relativePath);
+        if (!fs.existsSync(fullPath)) { continue; }
+        const currentHash = computeFileHash(fullPath);
+        if (currentHash !== entry.hash) {
+            modified.push({
+                relativePath,
+                expectedHash: entry.hash,
+                actualHash: currentHash,
+                injectedVersion: entry.version
+            });
+        }
+    }
+    return modified;
+}
+
+/** Check if any bundled file is newer than workspace version. */
+export function isUpgradeAvailable(root: string, extensionPath: string): boolean {
+    const bundled = loadBundledManifest(extensionPath);
+    if (!bundled) { return false; }
+    const wsManifest = loadWorkspaceManifest(root);
+    if (!wsManifest) { return true; }
+
+    for (const [relativePath, entry] of Object.entries(bundled.files)) {
+        const wsEntry = wsManifest.files[relativePath];
+        if (!wsEntry || wsEntry.version !== entry.version) { return true; }
+    }
+    return false;
+}
+
+/** Migrate from legacy .sdlc-version to new per-file manifest. */
+export function migrateLegacyVersion(root: string, extensionPath: string): void {
+    const legacyFile = path.join(root, LEGACY_VERSION_FILE);
+    if (!fs.existsSync(legacyFile)) { return; }
+
+    const bundled = loadBundledManifest(extensionPath);
+    if (!bundled) { return; }
+
+    let legacyVersion = "1.0.0";
+    try {
+        const raw = JSON.parse(fs.readFileSync(legacyFile, "utf-8"));
+        legacyVersion = raw.version || "1.0.0";
+    } catch { /* default to 1.0.0 */ }
+
+    const wsManifest: WorkspaceManifest = { lastUpdated: new Date().toISOString(), files: {} };
+    for (const [relativePath] of Object.entries(bundled.files)) {
+        const fullPath = path.join(root, relativePath);
+        if (fs.existsSync(fullPath)) {
+            wsManifest.files[relativePath] = {
+                version: legacyVersion,
+                hash: computeFileHash(fullPath),
+                injectedAt: new Date().toISOString()
+            };
+        }
+    }
+
+    saveWorkspaceManifest(root, wsManifest);
+    fs.unlinkSync(legacyFile);
+}
+
+/** Build workspace manifest after a full inject. */
+export function buildManifestAfterInject(root: string, extensionPath: string): void {
+    const bundled = loadBundledManifest(extensionPath);
+    if (!bundled) { return; }
+
+    const wsManifest: WorkspaceManifest = { lastUpdated: new Date().toISOString(), files: {} };
+    for (const [relativePath, entry] of Object.entries(bundled.files)) {
+        const fullPath = path.join(root, relativePath);
+        if (fs.existsSync(fullPath)) {
+            wsManifest.files[relativePath] = {
+                version: entry.version,
+                hash: computeFileHash(fullPath),
+                injectedAt: new Date().toISOString()
+            };
+        }
+    }
+    saveWorkspaceManifest(root, wsManifest);
+}