@mytechtoday/augment-sdd 1.0.0

package/src/commands/fullPipeline.ts

@@ -0,0 +1,120 @@
+/**
+ * fullPipeline — Bead 8 command implementation.
+ *
+ * Steps (tasks 8.1-8.4):
+ *  8.1 Wire generateOpenSpec -> generateBeads -> executeBeadsBatch behind
+ *      a VS Code progress notification.
+ *  8.2 Update progress indicator at each step boundary.
+ *  8.3 Halt pipeline on step failure; show step name, error, and offer
+ *      Resume from step X quick-pick options.
+ *  8.4 Implement resume logic: skip steps before the selected resume point.
+ */
+import * as vscode from 'vscode';
+import { log } from '../utils/logger';
+import { getConfig } from '../utils/getConfig';
+import { DashboardPanel } from '../dashboard/DashboardPanel';
+import { generateOpenSpec } from './generateOpenSpec';
+import { generateBeads } from './generateBeads';
+import { executeBeadsBatch } from './executeBeadsBatch';
+
+/** Represents a single pipeline step. */
+interface PipelineStep {
+  name: string;
+  label: string;
+  run: () => Promise<void>;
+}
+
+/** All pipeline steps in execution order. */
+const PIPELINE_STEPS: PipelineStep[] = [
+  { name: 'generateOpenSpec', label: 'Generating OpenSpec…',   run: generateOpenSpec },
+  { name: 'generateBeads',    label: 'Generating Beads…',      run: generateBeads },
+  { name: 'executeBeadsBatch', label: 'Executing Beads Batch…', run: executeBeadsBatch },
+];
+
+/** Entry point registered as `augmentSdd.fullPipeline`. */
+export async function fullPipeline(startFromIndex = 0): Promise<void> {
+  const steps = PIPELINE_STEPS.slice(startFromIndex);
+  const totalSteps = PIPELINE_STEPS.length;
+  const workspaceRoot = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
+
+  await vscode.window.withProgress(
+    {
+      location: vscode.ProgressLocation.Notification,
+      title: 'Augment SDD: Full Pipeline',
+      cancellable: false,
+    },
+    async (progress) => {
+      for (const step of steps) {
+        const globalIndex = PIPELINE_STEPS.indexOf(step);
+        const stepNum = globalIndex + 1;
+        const pct = Math.round(((globalIndex) / totalSteps) * 100);
+        progress.report({
+          message: `Step ${stepNum}/${totalSteps}: ${step.label}`,
+          increment: pct === 0 ? 0 : Math.round(100 / totalSteps),
+        });
+        log(`fullPipeline: starting step ${stepNum}/${totalSteps} — ${step.name}`);
+
+        try {
+          await step.run();
+          log(`fullPipeline: step ${stepNum} completed — ${step.name}`);
+          // Open / refresh the dashboard after each successful step if the setting is enabled.
+          if (getConfig<boolean>('enableWebviewDashboard', true) && workspaceRoot) {
+            DashboardPanel.show(workspaceRoot);
+          }
+        } catch (err) {
+          const errMsg = err instanceof Error ? err.message : String(err);
+          log(`fullPipeline: step ${stepNum} FAILED — ${step.name}: ${errMsg}`);
+          await handleStepFailure(step.name, stepNum, errMsg);
+          return; // abort progress handler; resume handled separately
+        }
+      }
+
+      // All steps succeeded
+      progress.report({ message: 'Complete!', increment: 100 });
+      log('fullPipeline: all steps completed successfully');
+      vscode.window.showInformationMessage(
+        'Augment SDD: Full pipeline complete — OpenSpec generated, beads created, and batch executed.'
+      );
+    }
+  );
+}
+
+/**
+ * 8.3: Show error notification with Resume from step X quick-pick options.
+ * Launches a new pipeline run from the selected resume point.
+ */
+async function handleStepFailure(
+  stepName: string,
+  failedStepNum: number,
+  errMsg: string
+): Promise<void> {
+  // Build resume options for the failed step and all subsequent steps
+  const resumeOptions = PIPELINE_STEPS
+    .slice(failedStepNum - 1)
+    .map((s, i) => ({
+      label: `Resume from step ${failedStepNum + i}: ${s.name}`,
+      index: failedStepNum - 1 + i,
+    }));
+
+  const picked = await vscode.window.showErrorMessage(
+    `Augment SDD: Pipeline failed at step ${failedStepNum} (${stepName}): ${errMsg}`,
+    ...resumeOptions.map(o => o.label)
+  );
+
+  if (!picked) {
+    log('fullPipeline: user dismissed resume dialog — pipeline aborted');
+    return;
+  }
+
+  const selected = resumeOptions.find(o => o.label === picked);
+  if (selected !== undefined) {
+    log(`fullPipeline: user selected resume from index ${selected.index} (${PIPELINE_STEPS[selected.index].name})`);
+    // Run the resumed pipeline (non-awaited so the progress handler can close)
+    setImmediate(() => {
+      fullPipeline(selected.index).catch(e => {
+        log(`fullPipeline(resume): unexpected error — ${String(e)}`);
+      });
+    });
+  }
+}
+

package/src/commands/generateBeads.ts

@@ -0,0 +1,127 @@
+/**
+ * generateBeads — Bead 6 command implementation.
+ *
+ * Steps (tasks 6.1–6.5):
+ *  6.1 Glob openspec/changes/{id}/tasks.md and select the most recently modified.
+ *  6.2 Parse using parseTasksMarkdown (heading-based regex, design D3).
+ *  6.3 Execute bd create --title --description for each task.
+ *  6.4 Continue processing on individual bd create failures; log each one.
+ *  6.5 Run bd ready --json after all creates; display ready-bead count.
+ */
+import * as vscode from 'vscode';
+import * as fs from 'fs';
+import * as path from 'path';
+import { runCli } from '../utils/runCli';
+import { log, revealOutputChannel } from '../utils/logger';
+import { parseTasksMarkdown } from '../parsers/parseTasksMarkdown';
+
+/** Entry point registered as `augmentSdd.generateBeads`. */
+export async function generateBeads(): Promise<void> {
+  const workspaceRoot = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
+  if (!workspaceRoot) {
+    vscode.window.showErrorMessage('Augment SDD: No workspace folder open.');
+    return;
+  }
+
+  // 6.1 — Find the most recently modified tasks.md.
+  const tasksFile = findNewestTasksFile(workspaceRoot);
+  if (!tasksFile) {
+    vscode.window.showErrorMessage(
+      'Augment SDD: No tasks.md found in openspec/changes/. ' +
+      'Please run "Augment SDD: Generate OpenSpec" first.'
+    );
+    return;
+  }
+  log(`Using tasks.md: ${tasksFile}`);
+
+  // 6.2 — Parse headings into tasks.
+  const content = fs.readFileSync(tasksFile, 'utf8');
+  const tasks = parseTasksMarkdown(content);
+
+  if (tasks.length === 0) {
+    const snippet = content.slice(0, 300);
+    vscode.window.showErrorMessage(
+      `Augment SDD: No markdown headings found in tasks.md.\n\nFile begins:\n${snippet}`
+    );
+    return;
+  }
+  log(`Parsed ${tasks.length} task(s) from ${path.basename(path.dirname(tasksFile))}/tasks.md`);
+
+  // 6.3–6.4 — Create beads; continue on individual failures.
+  let created = 0;
+  for (const task of tasks) {
+    try {
+      // Shell-quote title and description so spaces are preserved correctly
+      // when spawn joins args into a shell command string (shell: true).
+      const quotedTitle = `"${task.title.replace(/"/g, '\\"')}"`;
+      const quotedDesc  = `"${task.description.replace(/"/g, '\\"')}"`;
+      await runCli(
+        'bd',
+        ['create', quotedTitle, '--description', quotedDesc],
+        workspaceRoot,
+        30_000,
+        log
+      );
+      created++;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      log(`bd create failed for "${task.title}": ${msg}`);
+      // Do NOT break — spec 6.4 requires continuing with remaining tasks.
+    }
+  }
+  log(`Created ${created}/${tasks.length} bead(s).`);
+
+  // 6.5 — Run bd ready --json and display count.
+  try {
+    const readyJson = await runCli('bd', ['ready', '--json'], workspaceRoot, 30_000, log);
+    let readyCount = 0;
+    try {
+      const parsed = JSON.parse(readyJson) as unknown[];
+      readyCount = Array.isArray(parsed) ? parsed.length : 0;
+    } catch {
+      log('Warning: could not parse bd ready --json output as JSON array');
+    }
+    vscode.window.showInformationMessage(
+      `Augment SDD: Created ${created}/${tasks.length} bead(s). ` +
+      `${readyCount} bead(s) ready to execute.`
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log(`bd ready --json failed: ${msg}`);
+    const action = await vscode.window.showInformationMessage(
+      `Augment SDD: Created ${created}/${tasks.length} bead(s). ` +
+      `(Could not retrieve ready count.)`,
+      'View Logs'
+    );
+    if (action === 'View Logs') { revealOutputChannel(); }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+/**
+ * 6.1: Scan openspec/changes/{id}/tasks.md and return the path to the most
+ * recently modified file.  Skips the 'archive' subdirectory.
+ * Returns undefined when no tasks.md is found.
+ */
+function findNewestTasksFile(workspaceRoot: string): string | undefined {
+  const changesDir = path.join(workspaceRoot, 'openspec', 'changes');
+  if (!fs.existsSync(changesDir)) { return undefined; }
+
+  const candidates: Array<{ filePath: string; mtime: number }> = [];
+
+  for (const entry of fs.readdirSync(changesDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name === 'archive') { continue; }
+    const tasksPath = path.join(changesDir, entry.name, 'tasks.md');
+    if (fs.existsSync(tasksPath)) {
+      candidates.push({ filePath: tasksPath, mtime: fs.statSync(tasksPath).mtimeMs });
+    }
+  }
+
+  if (candidates.length === 0) { return undefined; }
+  candidates.sort((a, b) => b.mtime - a.mtime);
+  return candidates[0].filePath;
+}
+

package/src/commands/generateOpenSpec.ts

@@ -0,0 +1,227 @@
+/**
+ * generateOpenSpec — Bead 5 command implementation.
+ *
+ * Steps (tasks 5.1–5.7):
+ *  5.1 File selection: file-picker dialog with fallback auto-detect from jiraFolder.
+ *  5.2 Run `openspec init --tools auggie --force`.
+ *  5.3 Retrieve proposal template via `openspec instructions proposal --json`;
+ *      fallback to `spec` then `tasks`.
+ *  5.4 Build Auggie prompt: template + JIRA Markdown (truncate at 8 000 chars).
+ *  5.5 Execute `auggie --print --quiet <prompt>`; retry once on empty response.
+ *  5.6 Save Auggie output to `openspec/changes/<id>/proposal.md`.
+ *  5.7 Run `openspec validate`; surface result as info or error notification.
+ */
+import * as vscode from 'vscode';
+import * as fs from 'fs';
+import * as path from 'path';
+import { runCli } from '../utils/runCli';
+import { getConfig } from '../utils/getConfig';
+import { log, revealOutputChannel } from '../utils/logger';
+
+/** Maximum JIRA content characters included in the Auggie prompt (risk D62). */
+const MAX_JIRA_CHARS = 8_000;
+
+/** Entry point registered as `augmentSdd.generateOpenSpec`. */
+export async function generateOpenSpec(): Promise<void> {
+  const workspaceRoot = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
+  if (!workspaceRoot) {
+    vscode.window.showErrorMessage('Augment SDD: No workspace folder open.');
+    return;
+  }
+
+  // 5.1 — Select the JIRA Markdown file.
+  const jiraFile = await selectJiraFile(workspaceRoot);
+  if (!jiraFile) {
+    vscode.window.showInformationMessage('Augment SDD: No file selected. Operation cancelled.');
+    return;
+  }
+  log(`JIRA file selected: ${jiraFile}`);
+
+  // 5.2 — openspec init.
+  try {
+    await runCli('openspec', ['init', '--tools', 'auggie', '--force'], workspaceRoot, 60_000, log);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log(`openspec init failed: ${msg}`);
+    const action = await vscode.window.showErrorMessage(
+      `Augment SDD: openspec init failed.\n${msg}`, 'View Logs'
+    );
+    if (action === 'View Logs') { revealOutputChannel(); }
+    return;
+  }
+
+  // Determine the change directory created by openspec init.
+  const changeId = findNewestChangeDir(workspaceRoot);
+  if (!changeId) {
+    vscode.window.showErrorMessage(
+      'Augment SDD: Could not locate an openspec change directory after init.'
+    );
+    return;
+  }
+  const changeDir = path.join(workspaceRoot, 'openspec', 'changes', changeId);
+  log(`Using openspec change directory: ${changeId}`);
+
+  // 5.3 — Retrieve the proposal template (with fallbacks).
+  const template = await fetchProposalTemplate(workspaceRoot);
+
+  // 5.4 — Build the Auggie prompt.
+  const jiraRaw = fs.readFileSync(jiraFile, 'utf8');
+  let jiraContent = jiraRaw;
+  if (jiraRaw.length > MAX_JIRA_CHARS) {
+    jiraContent = jiraRaw.slice(0, MAX_JIRA_CHARS) + '\n[...truncated]';
+    log(`Warning: JIRA content truncated from ${jiraRaw.length} to ${MAX_JIRA_CHARS} chars`);
+  }
+  const prompt = template ? `${template}\n\n---\n\n${jiraContent}` : jiraContent;
+
+  // 5.5 — Run Auggie with one retry on empty output.
+  let auggieOutput: string;
+  try {
+    auggieOutput = await runAuggieWithRetry(workspaceRoot, prompt);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log(`Auggie execution failed: ${msg}`);
+    const action = await vscode.window.showErrorMessage(
+      `Augment SDD: Auggie failed.\n${msg}`, 'View Logs'
+    );
+    if (action === 'View Logs') { revealOutputChannel(); }
+    return;
+  }
+
+  // 5.6 — Save proposal.md.
+  const proposalPath = path.join(changeDir, 'proposal.md');
+  fs.mkdirSync(changeDir, { recursive: true });
+  fs.writeFileSync(proposalPath, auggieOutput, 'utf8');
+  log(`Saved proposal.md → ${proposalPath}`);
+
+  // 5.7 — openspec validate.
+  try {
+    await runCli('openspec', ['validate'], workspaceRoot, 30_000, log);
+    vscode.window.showInformationMessage(
+      `Augment SDD: OpenSpec generated and validated. Change: ${changeId}`
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log(`openspec validate failed: ${msg}`);
+    const action = await vscode.window.showErrorMessage(
+      `Augment SDD: OpenSpec generated but validation failed.\n${msg}`, 'View Logs'
+    );
+    if (action === 'View Logs') { revealOutputChannel(); }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * 5.1: Present a file-picker dialog filtered to Markdown files. If exactly one
+ * `.md` file exists in the configured `jiraFolder`, auto-select it; if multiple
+ * exist, show a Quick Pick; otherwise fall back to the OS open-file dialog.
+ */
+async function selectJiraFile(workspaceRoot: string): Promise<string | undefined> {
+  const jiraFolder = getConfig<string>('jiraFolder', '.jira');
+  const jiraDir = path.join(workspaceRoot, jiraFolder);
+
+  if (fs.existsSync(jiraDir)) {
+    const mdFiles = fs.readdirSync(jiraDir)
+      .filter(f => f.toLowerCase().endsWith('.md'))
+      .map(f => path.join(jiraDir, f));
+
+    if (mdFiles.length === 1) {
+      log(`Auto-detected JIRA file: ${mdFiles[0]}`);
+      return mdFiles[0];
+    }
+
+    if (mdFiles.length > 1) {
+      const items = mdFiles.map(f => ({ label: path.basename(f), description: f }));
+      const pick = await vscode.window.showQuickPick(items, {
+        placeHolder: 'Select JIRA Markdown ticket file',
+      });
+      return pick?.description;
+    }
+  }
+
+  // Fall back to the OS file-picker dialog.
+  const uris = await vscode.window.showOpenDialog({
+    canSelectMany: false,
+    filters: { 'Markdown': ['md'] },
+    title: 'Select JIRA Ticket Markdown File',
+  });
+  return uris?.[0]?.fsPath;
+}
+
+/**
+ * Return the name of the most-recently-modified directory inside
+ * `openspec/changes/` (excluding the `archive` subdirectory).
+ * Returns `undefined` when no directories are found.
+ */
+function findNewestChangeDir(workspaceRoot: string): string | undefined {
+  const changesDir = path.join(workspaceRoot, 'openspec', 'changes');
+  if (!fs.existsSync(changesDir)) { return undefined; }
+
+  const dirs = fs.readdirSync(changesDir, { withFileTypes: true })
+    .filter(e => e.isDirectory() && e.name !== 'archive')
+    .map(e => ({
+      name: e.name,
+      mtime: fs.statSync(path.join(changesDir, e.name)).mtimeMs,
+    }))
+    .sort((a, b) => b.mtime - a.mtime);
+
+  return dirs[0]?.name;
+}
+
+/**
+ * 5.3: Try `openspec instructions proposal --json`, then `spec`, then `tasks`.
+ * Returns the template string, or an empty string if all attempts fail.
+ */
+async function fetchProposalTemplate(workspaceRoot: string): Promise<string> {
+  for (const type of ['proposal', 'spec', 'tasks']) {
+    try {
+      const raw = await runCli(
+        'openspec', ['instructions', type, '--json'], workspaceRoot, 30_000, log
+      );
+      // The JSON may have a `template` or `content` field; fall back to raw text.
+      try {
+        const parsed = JSON.parse(raw) as Record<string, unknown>;
+        const tmpl = (parsed['template'] ?? parsed['content'] ?? raw) as string;
+        log(`Fetched ${type} template (${String(tmpl).length} chars)`);
+        return String(tmpl);
+      } catch {
+        log(`Fetched ${type} template as raw text (${raw.length} chars)`);
+        return raw;
+      }
+    } catch {
+      log(`openspec instructions ${type} --json failed; trying next fallback`);
+    }
+  }
+  log('Warning: could not retrieve any proposal template; proceeding with JIRA content only');
+  return '';
+}
+
+/**
+ * 5.5: Run `auggie --print --quiet <prompt>`, retrying once with a reinforced
+ * suffix when the first attempt returns an empty string (design D6).
+ */
+async function runAuggieWithRetry(workspaceRoot: string, prompt: string): Promise<string> {
+  const extraFlags = getConfig<string>('auggieExtraFlags', '');
+  const buildArgs = (p: string): string[] => {
+    const base = ['--print', '--quiet', p];
+    if (extraFlags) {
+      base.push(...extraFlags.split(/\s+/).filter(Boolean));
+    }
+    return base;
+  };
+
+  let output = await runCli('auggie', buildArgs(prompt), workspaceRoot, 300_000, log);
+  if (!output) {
+    log('Auggie returned empty output; retrying with reinforced prompt…');
+    const retryPrompt = prompt + '\nPlease provide the full output.';
+    output = await runCli('auggie', buildArgs(retryPrompt), workspaceRoot, 300_000, log);
+    if (!output) {
+      throw new Error('Auggie returned empty output after retry (max 2 attempts)');
+    }
+  }
+  return output;
+}
+
+

package/src/dashboard/DashboardPanel.ts

@@ -0,0 +1,168 @@
+/**
+ * DashboardPanel — Webview panel for the Augment SDD Dashboard (Bead 10 / bd-d47o).
+ *
+ * Renders a list of ready Beads fetched from `bd ready --json`.
+ * Provides "Run Next Batch" (triggers augmentSdd.executeBeadsBatch then refreshes)
+ * and "Refresh" (re-fetches and re-renders) buttons.
+ *
+ * The singleton is kept alive as long as the panel is visible.
+ * Callers: fullPipeline.ts (opens after each pipeline step when enabled).
+ */
+import * as vscode from 'vscode';
+import { runCli } from '../utils/runCli';
+import { log } from '../utils/logger';
+
+/** Shape returned by `bd ready --json`. */
+interface ReadyBead {
+  id: string;
+  title: string;
+  description: string;
+}
+
+export class DashboardPanel {
+  public static readonly viewType = 'augmentSddDashboard';
+  private static _current: DashboardPanel | undefined;
+
+  private readonly _panel: vscode.WebviewPanel;
+  private _workspaceRoot: string;
+  private readonly _disposables: vscode.Disposable[] = [];
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Open (or reveal + refresh) the Augment SDD Dashboard.
+   * Safe to call multiple times; only one panel is ever open.
+   */
+  public static show(workspaceRoot: string): void {
+    if (DashboardPanel._current) {
+      DashboardPanel._current._panel.reveal(vscode.ViewColumn.Two);
+      DashboardPanel._current._workspaceRoot = workspaceRoot;
+      DashboardPanel._current._refresh().catch(e =>
+        log(`DashboardPanel.refresh error: ${String(e)}`)
+      );
+      return;
+    }
+
+    const panel = vscode.window.createWebviewPanel(
+      DashboardPanel.viewType,
+      'Augment SDD Dashboard',
+      vscode.ViewColumn.Two,
+      { enableScripts: true, retainContextWhenHidden: true }
+    );
+
+    DashboardPanel._current = new DashboardPanel(panel, workspaceRoot);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Constructor
+  // ---------------------------------------------------------------------------
+
+  private constructor(panel: vscode.WebviewPanel, workspaceRoot: string) {
+    this._panel          = panel;
+    this._workspaceRoot  = workspaceRoot;
+
+    // Initial render
+    this._refresh().catch(e => log(`DashboardPanel initial render error: ${String(e)}`));
+
+    // Dispose when the user closes the panel
+    this._panel.onDidDispose(() => this._dispose(), null, this._disposables);
+
+    // Handle messages sent from the webview script
+    this._panel.webview.onDidReceiveMessage(
+      async (message: { command: string }) => {
+        if (message.command === 'runBatch') {
+          log('DashboardPanel: Run Next Batch clicked');
+          await vscode.commands.executeCommand('augmentSdd.executeBeadsBatch');
+          await this._refresh();
+        } else if (message.command === 'refresh') {
+          log('DashboardPanel: Refresh clicked');
+          await this._refresh();
+        }
+      },
+      null,
+      this._disposables
+    );
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  private _dispose(): void {
+    DashboardPanel._current = undefined;
+    this._panel.dispose();
+    for (const d of this._disposables) { d.dispose(); }
+    this._disposables.length = 0;
+  }
+
+  /** Fetch beads and re-render the webview HTML. */
+  private async _refresh(): Promise<void> {
+    let beads: ReadyBead[] = [];
+    try {
+      const raw = await runCli('bd', ['ready', '--json'], this._workspaceRoot, 30_000, log);
+      beads = JSON.parse(raw) as ReadyBead[];
+    } catch (err) {
+      log(`DashboardPanel: failed to fetch ready beads — ${err instanceof Error ? err.message : String(err)}`);
+    }
+    this._panel.webview.html = this._buildHtml(beads);
+  }
+
+  private _buildHtml(beads: ReadyBead[]): string {
+    const cards = beads.length > 0
+      ? beads.map(b => `
+        <div class="card">
+          <span class="bead-id">${esc(b.id)}</span>
+          <div class="bead-title">${esc(b.title)}</div>
+          <div class="bead-desc">${esc(b.description)}</div>
+        </div>`).join('')
+      : '<p class="empty">No beads ready.</p>';
+
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline';">
+  <title>Augment SDD Dashboard</title>
+  <style>
+    body { font-family: var(--vscode-font-family); color: var(--vscode-foreground); padding: 16px; margin: 0; }
+    h1 { font-size: 1.1em; margin-bottom: 10px; }
+    .actions { margin-bottom: 14px; }
+    button { margin-right: 8px; padding: 5px 14px; cursor: pointer;
+             background: var(--vscode-button-background); color: var(--vscode-button-foreground);
+             border: none; border-radius: 2px; }
+    button:hover { background: var(--vscode-button-hoverBackground); }
+    .card { border: 1px solid var(--vscode-panel-border); border-radius: 4px;
+            padding: 10px 14px; margin-bottom: 8px; }
+    .bead-id { font-size: 0.8em; color: var(--vscode-descriptionForeground); }
+    .bead-title { font-weight: bold; margin: 3px 0; }
+    .bead-desc  { font-size: 0.9em; }
+    .empty { color: var(--vscode-descriptionForeground); }
+  </style>
+</head>
+<body>
+  <h1>Augment SDD Dashboard</h1>
+  <div class="actions">
+    <button onclick="post('runBatch')">Run Next Batch</button>
+    <button onclick="post('refresh')">Refresh</button>
+  </div>
+  <div id="beads">${cards}</div>
+  <script>
+    const vscode = acquireVsCodeApi();
+    function post(cmd) { vscode.postMessage({ command: cmd }); }
+  </script>
+</body>
+</html>`;
+  }
+}
+
+/** Minimal HTML entity escaping to prevent XSS in bead data. */
+function esc(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+