codemini-cli 0.4.3 → 0.4.5

package/deployment.md

@@ -13,13 +13,13 @@ npm pack
 Expected output:
 
 ```text
-codemini-cli-0.4.3.tgz
+codemini-cli-0.4.5.tgz
 ```
 
 If you want to verify the package contents:
 
 ```bash
-tar -tf codemini-cli-0.4.3.tgz
+tar -tf codemini-cli-0.4.5.tgz
 ```
 
 ## 2. Copy To The Target Machine
@@ -34,7 +34,7 @@ Copy the generated `.tgz` file to the Win10 machine by one of these methods:
 Recommended target path:
 
 ```powershell
-C:\temp\codemini-cli-0.4.3.tgz
+C:\temp\codemini-cli-0.4.5.tgz
 ```
 
 ## 3. Environment Requirements
@@ -58,7 +58,7 @@ npm -v
 Global install:
 
 ```powershell
-npm install -g C:\temp\codemini-cli-0.4.3.tgz
+npm install -g C:\temp\codemini-cli-0.4.5.tgz
 ```
 
 If global install is blocked by company policy, install in a working directory instead:
@@ -66,7 +66,7 @@ If global install is blocked by company policy, install in a working directory i
 ```powershell
 mkdir C:\temp\coder-test
 cd C:\temp\coder-test
-npm install C:\temp\codemini-cli-0.4.3.tgz
+npm install C:\temp\codemini-cli-0.4.5.tgz
 ```
 
 ## 5. Confirm Installation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codemini-cli",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Coding CLI optimized for small-model workflows and Windows PowerShell",
   "keywords": [
     "cli",

package/skills/project-requirements/SKILL.md

@@ -21,17 +21,19 @@ Honor any concrete user request above, such as output format, report path, focus
 Create the primary report at:
 
 ```text
-docs/requirements/YYYY-MM-DD-project-requirements.html
+docs/requirements/{{date}}-project-requirements.html
 ```
 
 If a companion Markdown file is useful, create:
 
 ```text
-docs/requirements/YYYY-MM-DD-project-requirements.md
+docs/requirements/{{date}}-project-requirements.md
 ```
 
 The HTML should be self-contained: inline CSS, inline JavaScript, no build step, no required external assets.
 
+When the target HTML file already exists and contains `REQUIREMENTS_*` marker sections, treat it as the canonical report shell. Edit those marker sections in place instead of replacing the whole file. Preserve the existing CSS, JavaScript, navigation, metadata, and surrounding structure unless the user explicitly asks to redesign the shell.
+
 Diagrams must be visible when the HTML is opened directly from disk:
 
 - Prefer inline SVG for architecture maps, dependency graphs, sequence summaries, and state diagrams.

package/src/commands/chat.js

@@ -42,6 +42,72 @@ function parseChatArgs(args) {
   return parsed;
 }
 
+export async function submitAndPrint(runtime, line, { output: out = process.stdout } = {}) {
+  let streamed = false;
+  let atLineStart = true;
+  const write = (text) => {
+    const value = String(text || '');
+    if (!value) return;
+    out.write(value);
+    atLineStart = value.endsWith('\n');
+  };
+  const writeActivity = (event, label) => {
+    const name = String(event?.name || '').trim();
+    if (!name) return;
+    const summary = String(event?.summary || '').trim();
+    if (!atLineStart) write('\n');
+    write(`[${label}] ${name}${summary ? ` - ${summary}` : ''}\n`);
+  };
+  const result = await runtime.submit(line, (event) => {
+    if (event?.type === 'assistant:delta' && event.text) {
+      streamed = true;
+      write(event.text);
+      return;
+    }
+    if (event?.type === 'tool:start') {
+      streamed = true;
+      writeActivity(event, 'tool:start');
+      return;
+    }
+    if (event?.type === 'tool:end') {
+      streamed = true;
+      writeActivity(event, 'tool:end');
+      return;
+    }
+    if (event?.type === 'tool:blocked') {
+      streamed = true;
+      writeActivity(event, 'tool:blocked');
+      return;
+    }
+    if (event?.type === 'tool:error') {
+      streamed = true;
+      writeActivity(event, 'tool:error');
+      return;
+    }
+    if (event?.type === 'system_tool:start') {
+      streamed = true;
+      writeActivity(event, 'system:start');
+      return;
+    }
+    if (event?.type === 'system_tool:end') {
+      streamed = true;
+      writeActivity(event, 'system:end');
+      return;
+    }
+    if (event?.type === 'system_tool:error') {
+      streamed = true;
+      writeActivity(event, 'system:error');
+    }
+  });
+  if (result.type === 'exit' || result.type === 'noop') return result;
+  if (streamed) {
+    if (!atLineStart) write('\n');
+    return result;
+  }
+  if (result.text) write(`${result.text}\n`);
+  return result;
+}
+
 async function runPlainLoop(runtime) {
   console.log('CodeMini CLI plain mode. Use /help and /exit.');
   const rl = readline.createInterface({ input, output });
@@ -53,10 +119,8 @@ async function runPlainLoop(runtime) {
       } catch {
         break;
       }
-      const result = await runtime.submit(line);
+      const result = await submitAndPrint(runtime, line, { output });
       if (result.type === 'exit') break;
-      if (result.type === 'noop') continue;
-      if (result.text) console.log(result.text);
     }
   } finally {
     rl.close();
@@ -80,8 +144,7 @@ export async function handleChat(args) {
 
   try {
     if (parsed.prompt) {
-      const result = await runtime.submit(parsed.prompt);
-      if (result.text) console.log(result.text);
+      await submitAndPrint(runtime, parsed.prompt, { output: process.stdout });
       return;
     }
 

package/src/core/chat-runtime.js

@@ -1,10 +1,11 @@
 import { parseInput } from './input-parser.js';
-import { loadCommandsAndSkills, renderCommandPrompt } from './command-loader.js';
+import { formatLocalDate, loadCommandsAndSkills, renderCommandPrompt } from './command-loader.js';
 import { runAgentLoop } from './agent-loop.js';
 import { setResultDir, clearResultStore } from './tool-result-store.js';
 import { trimInline, normalizePath } from './string-utils.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import {
   createChatCompletion,
   createChatCompletionStream
@@ -38,6 +39,8 @@ import {
 } from './reflect-skill.js';
 
 const STREAM_SAVE_DEBOUNCE_MS = 120;
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_REQUIREMENTS_TEMPLATE = path.resolve(MODULE_DIR, '..', '..', 'templates', 'project-requirements', 'report-shell.html');
 
 function toOpenAIMessages(sessionMessages) {
   const mapped = [];
@@ -312,7 +315,7 @@ export const ROLE_TOOL_POLICY = {
   coder: ['read', 'grep', 'list', 'edit', 'write', 'delete', 'run', 'ast_query', 'read_ast_node', 'glob', 'tool_search', 'web_fetch', 'web_search', 'update_todos', 'read_plan', 'update_plan'],
   reviewer: ['read', 'grep', 'list', 'glob', 'tool_search', 'ast_query', 'read_ast_node', 'read_plan'],
   tester: ['read', 'grep', 'list', 'run', 'glob', 'tool_search', 'read_plan'],
-  summarizer: ['read_plan']
+  summarizer: ['read', 'read_plan']
 };
 const SUB_AGENT_CONTEXT_MAX_MESSAGES = 4;
 const SUB_AGENT_CONTEXT_MAX_CHARS = 1200;
@@ -395,6 +398,7 @@ export function getSubAgentRolePrompt(role) {
       'You are the summarizer in a multi-step agent pipeline.',
       'Your job is to synthesize the results of all prior steps into a concise, actionable final summary.',
       'Do NOT re-analyze the codebase or make new tool calls unless the handed-off evidence is clearly insufficient.',
+      'You may read handed-off artifact files, such as generated reports, when needed to summarize or verify their existence.',
       'Instead, read the accumulated step results in the plan file context provided to you.',
       'Output format — keep it short and direct:',
       'Summary:',
@@ -2708,6 +2712,16 @@ async function executePlanWithSubAgents({
     const step = steps[i];
     if (signal?.aborted) break;
 
+    emitPlanEvent({
+      type: 'plan:progress',
+      planFile: planFilePath,
+      step: i + 1,
+      total: steps.length,
+      role: step.role,
+      title: step.title,
+      status: 'running'
+    });
+
     emitPlanEvent({
       type: 'assistant:delta',
       text: `\n[plan] Step ${i + 1}/${steps.length} -> ${step.role}: ${step.title}\n`
@@ -2771,6 +2785,17 @@ async function executePlanWithSubAgents({
       );
     }
 
+    emitPlanEvent({
+      type: 'plan:progress',
+      planFile: planFilePath,
+      step: i + 1,
+      total: steps.length,
+      role: step.role,
+      title: step.title,
+      status: stepRecord.failed ? 'failed' : 'done',
+      summary: stepRecord.failed ? stepRecord.failureReason : trimInline(stepRecord.output, 160)
+    });
+
     if (stepRecord.failed && i < steps.length - 1) {
       const summarizerIndex = steps.findIndex((candidate, index) => index > i && candidate.role === 'summarizer');
       if (summarizerIndex > i) {
@@ -2968,6 +2993,313 @@ function renderAutoPlanMarkdown({
   return lines.join('\n');
 }
 
+function buildProjectRequirementsSteps(renderedSkillPrompt, args = []) {
+  const userArgs = args.join(' ').trim();
+  const requestedFocus = userArgs ? `User request/focus: ${userArgs}` : 'User request/focus: full workspace requirements report.';
+  const reportDate = formatLocalDate();
+  const reportPath = `docs/requirements/${reportDate}-project-requirements.html`;
+  const companionPath = `docs/requirements/${reportDate}-project-requirements.md`;
+  const reportContract = [
+    requestedFocus,
+    `Primary report path: ${reportPath}`,
+    `Optional companion Markdown path: ${companionPath}`,
+    'A pre-created HTML shell already exists at the primary report path.',
+    'Fill or replace only the named marker sections in that shell instead of rewriting the whole document.',
+    'Required marker sections: REQUIREMENTS_SUMMARY, REQUIREMENTS_ARCHITECTURE, REQUIREMENTS_INTERFACE_INVENTORY, REQUIREMENTS_API_CARDS, REQUIREMENTS_FLOWS, REQUIREMENTS_SECURITY, REQUIREMENTS_NONFUNCTIONAL, REQUIREMENTS_OPEN_QUESTIONS, REQUIREMENTS_EVIDENCE_INDEX.',
+    'Use EXTRACTED, INFERRED, and UNKNOWN labels. Preserve source evidence paths.',
+    'Do not invent dates; use the report paths above.'
+  ].join('\n');
+
+  return [
+    {
+      title: 'Map project interfaces and evidence',
+      role: 'planner',
+      task: [
+        'Map project interfaces and evidence before any report writing.',
+        reportContract,
+        'Inspect top-level docs, package manifests, route/command entry points, tests, and obvious interface files.',
+        'Produce a concise interface inventory grouped by CLI commands, HTTP/API/RPC surfaces, tools, storage/config, UI flows, and operations.',
+        'Include evidence paths and open questions. Do not write the final report.'
+      ].join('\n')
+    },
+    {
+      title: 'Analyze runtime, tools, and providers',
+      role: 'advisor',
+      task: [
+        'Analyze the core execution layer and tool/provider surfaces using the prior planner inventory.',
+        reportContract,
+        'Focus on runtime flow, agent loop, built-in/deferred tools, provider streaming/tool-call behavior, sessions, memory, and plan state.',
+        'Return requirement-ready findings with evidence paths, inferred requirements, edge cases, and unknowns. Do not write the final report.'
+      ].join('\n')
+    },
+    {
+      title: 'Analyze product flows, storage, security, and operations',
+      role: 'advisor',
+      task: [
+        'Analyze user-facing workflows and non-functional requirements using the accumulated plan context.',
+        reportContract,
+        'Cover core product journeys, persistence paths, configuration, security/policy behavior, deployment/operations notes, error handling, and acceptance criteria.',
+        'Return requirement-ready findings with evidence paths, inferred requirements, edge cases, and unknowns. Do not write the final report.'
+      ].join('\n')
+    },
+    {
+      title: 'Write requirements HTML report',
+      role: 'coder',
+      task: [
+        'Create the final project requirements report from the accumulated plan context.',
+        reportContract,
+        'Follow the project-requirements skill instructions below exactly, including chunked HTML writing for medium/large reports.',
+        'The final HTML must be self-contained and directly openable from disk.',
+        'Write the primary report to the exact primary report path above. Create the companion Markdown only if useful.',
+        'Skill instructions:',
+        renderedSkillPrompt
+      ].join('\n\n')
+    },
+    {
+      title: 'Review report coverage and traceability',
+      role: 'reviewer',
+      task: [
+        'Review the generated requirements report against the project-requirements contract and accumulated evidence.',
+        reportContract,
+        'Check that major interfaces are represented, evidence paths are present, inferred/unknown content is labeled, diagrams are visible without Mermaid as the only renderer, and the report path matches the required local date.',
+        'Report concrete gaps and risks only. Do not rewrite the whole report.'
+      ].join('\n')
+    },
+    {
+      title: 'Summarize final requirements report',
+      role: 'summarizer',
+      task: [
+        'Synthesize the project requirements pipeline results into a concise final status for the user.',
+        reportContract,
+        'Mention the generated report path, what was covered, what was not verified, and the best next action.',
+        'Do not re-analyze the codebase unless the accumulated evidence is clearly insufficient.'
+      ].join('\n')
+    }
+  ];
+}
+
+function renderProjectRequirementsPlanMarkdown({ goal, steps, reportPath, companionPath }) {
+  const autoPlan = {
+    summary: 'Dedicated sub-agent pipeline for project requirements discovery and HTML report generation.',
+    steps
+  };
+  const progressLines = steps
+    .map((step, index) => `- [ ] Step ${index + 1} [${step.role}] ${step.title}`)
+    .join('\n');
+  return [
+    `# Project Requirements Pipeline: ${goal}`,
+    '',
+    `Primary Report: ${reportPath}`,
+    `Optional Companion: ${companionPath}`,
+    '',
+    renderAutoPlanMarkdown({
+      goal,
+      autoPlan,
+      finalSummary: 'Project requirements pipeline created and will execute immediately.',
+      approvalText: 'No approval required. Triggered explicitly by /project-requirements.',
+      progressLine: progressLines
+    })
+  ].join('\n');
+}
+
+function replaceTemplateVariables(template, variables) {
+  let out = String(template || '');
+  for (const [key, value] of Object.entries(variables || {})) {
+    out = out.replaceAll(`{{${key}}}`, String(value ?? ''));
+  }
+  return out;
+}
+
+async function createProjectRequirementsShell({
+  reportPath,
+  companionPath,
+  manifestPath,
+  planFile,
+  goal,
+  steps
+}) {
+  const workspaceRoot = process.cwd();
+  const absoluteReportPath = path.resolve(workspaceRoot, reportPath);
+  const absoluteManifestPath = path.resolve(workspaceRoot, manifestPath);
+  await fs.mkdir(path.dirname(absoluteReportPath), { recursive: true });
+  const template = await fs.readFile(PROJECT_REQUIREMENTS_TEMPLATE, 'utf8');
+  const now = new Date().toISOString();
+  const html = replaceTemplateVariables(template, {
+    title: 'Project Requirements Report',
+    workspace_name: path.basename(workspaceRoot) || workspaceRoot,
+    date: formatLocalDate(),
+    generated_at: now
+  });
+  await fs.writeFile(absoluteReportPath, html, 'utf8');
+
+  const sectionNames = [
+    'summary',
+    'architecture',
+    'interfaces',
+    'requirements',
+    'flows',
+    'security',
+    'nonfunctional',
+    'questions',
+    'evidence'
+  ];
+  const manifest = {
+    status: 'running',
+    goal,
+    html: reportPath,
+    markdown: companionPath,
+    manifest: manifestPath,
+    plan: planFile,
+    createdAt: now,
+    updatedAt: now,
+    sections: Object.fromEntries(sectionNames.map((name) => [name, 'pending'])),
+    steps: steps.map((step, index) => ({
+      step: index + 1,
+      role: step.role,
+      title: step.title,
+      status: 'pending'
+    }))
+  };
+  await fs.writeFile(absoluteManifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+  return manifest;
+}
+
+async function updateProjectRequirementsManifest(manifestPath, updates = {}) {
+  if (!manifestPath) return;
+  try {
+    const absoluteManifestPath = path.resolve(process.cwd(), manifestPath);
+    const current = JSON.parse(await fs.readFile(absoluteManifestPath, 'utf8'));
+    const next = {
+      ...current,
+      ...updates,
+      updatedAt: new Date().toISOString()
+    };
+    await fs.writeFile(absoluteManifestPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+  } catch {
+    // Manifest is best-effort; plan file and events remain the source of truth.
+  }
+}
+
+async function runProjectRequirementsPipeline({
+  custom,
+  parsedInput,
+  currentSession,
+  config,
+  model,
+  systemPrompt,
+  onAgentEvent,
+  signal,
+  onSubSessionActive
+}) {
+  const renderedSkillPrompt = await expandFileMentions(renderCommandPrompt(custom, parsedInput.args), process.cwd());
+  const userFocus = parsedInput.args.join(' ').trim();
+  const goal = userFocus ? `project requirements report: ${userFocus}` : 'project requirements report';
+  const reportDate = formatLocalDate();
+  const reportPath = `docs/requirements/${reportDate}-project-requirements.html`;
+  const companionPath = `docs/requirements/${reportDate}-project-requirements.md`;
+  const manifestPath = `docs/requirements/${reportDate}-project-requirements.manifest.json`;
+  const steps = buildProjectRequirementsSteps(renderedSkillPrompt, parsedInput.args);
+  const planFile = await writeMarkdownInProjectDir(
+    'plans',
+    'project-requirements-pipeline',
+    renderProjectRequirementsPlanMarkdown({ goal, steps, reportPath, companionPath }),
+    'project-requirements',
+    currentSession.id
+  );
+  await createProjectRequirementsShell({
+    reportPath,
+    companionPath,
+    manifestPath,
+    planFile,
+    goal,
+    steps
+  });
+  const planState = {
+    status: 'approved',
+    source: 'project-requirements',
+    goal,
+    filePath: planFile,
+    summary: 'Dedicated sub-agent pipeline for project requirements report generation.',
+    finalSummary: 'Executing project requirements pipeline.',
+    steps
+  };
+  if (onAgentEvent) {
+    onAgentEvent({ type: 'skill:start', name: custom.name });
+    onAgentEvent({
+      type: 'plan:progress',
+      planFile,
+      reportPath,
+      manifestPath,
+      step: 0,
+      total: steps.length,
+      status: 'created',
+      summary: 'Project requirements pipeline created'
+    });
+  }
+  let execution;
+  try {
+    execution = await executePlanWithSubAgents({
+      planState,
+      parentSession: currentSession,
+      config,
+      model,
+      systemPrompt,
+      onAgentEvent,
+      signal,
+      onSubSessionActive
+    });
+  } catch (error) {
+    if (onAgentEvent) {
+      onAgentEvent({
+        type: 'skill:error',
+        name: custom.name,
+        summary: error instanceof Error ? error.message : String(error)
+      });
+    }
+    throw error;
+  }
+  if (onAgentEvent) {
+    onAgentEvent({
+      type: 'plan:progress',
+      planFile,
+      reportPath,
+      manifestPath,
+      step: steps.length,
+      total: steps.length,
+      status: execution.aborted ? 'aborted' : 'done',
+      summary: 'Project requirements pipeline finished'
+    });
+    onAgentEvent({ type: 'skill:end', name: custom.name });
+  }
+  const failedCount = Array.isArray(execution.results)
+    ? execution.results.filter((item) => item.failed).length
+    : 0;
+  await updateProjectRequirementsManifest(manifestPath, {
+    status: execution.aborted ? 'aborted' : failedCount > 0 ? 'failed' : 'completed',
+    failedCount
+  });
+  const text = [
+    execution.text || '',
+    '',
+    'Project requirements pipeline completed.',
+    `Plan File: ${planFile}`,
+    `Report Path: ${reportPath}`,
+    `Manifest: ${manifestPath}`,
+    `Steps: ${steps.length} total`,
+    `Failed: ${failedCount}`
+  ]
+    .filter(Boolean)
+    .join('\n');
+  return {
+    type: 'assistant',
+    text,
+    planFile,
+    reportPath,
+    manifestPath,
+    aborted: !!execution.aborted
+  };
+}
+
 async function revisePendingPlanWithModel({
   planState,
   feedback,
@@ -4541,6 +4873,23 @@ export async function createChatRuntime({
       if (custom.metadata.type === 'skill' && !isSkillEnabled(config, custom.name, custom)) {
         return { type: 'system', text: `Skill is disabled: ${custom.name}` };
       }
+      if (custom.metadata.type === 'skill' && custom.name === 'project-requirements') {
+        try {
+          return await runProjectRequirementsPipeline({
+            custom,
+            parsedInput,
+            currentSession,
+            config,
+            model,
+            systemPrompt: activeReplySystemPrompt,
+            onAgentEvent,
+            signal,
+            onSubSessionActive: (sub) => { activeSubSession = sub; }
+          });
+        } finally {
+          activeSubSession = null;
+        }
+      }
 
       const customPrompt =
         custom.name === 'brainstorm'

package/src/core/command-loader.js

@@ -178,6 +178,14 @@ function loadInstalledSkillsFromRegistry(baseDir, registry, out) {
   }
 }
 
+export function formatLocalDate(date = new Date()) {
+  const value = date instanceof Date ? date : new Date(date);
+  const year = value.getFullYear();
+  const month = String(value.getMonth() + 1).padStart(2, '0');
+  const day = String(value.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
 function substituteVariables(text, args = []) {
   let out = text;
   args.forEach((arg, index) => {
@@ -185,6 +193,7 @@ function substituteVariables(text, args = []) {
   });
   out = out.replaceAll('{{args}}', args.join(' '));
   out = out.replaceAll('{{cwd}}', process.cwd());
+  out = out.replaceAll('{{date}}', formatLocalDate());
   return out;
 }
 

package/src/core/fff-adapter.js

@@ -111,7 +111,7 @@ class FffMcpClient {
       capabilities: {},
       clientInfo: {
         name: 'codemini-cli',
-        version: '0.4.3'
+        version: '0.4.5'
       }
     });
     this.sendNotification('notifications/initialized', {});

package/src/tui/chat-app.js

@@ -1386,6 +1386,7 @@ export function shouldRefreshRuntimeStateForEvent(event) {
     type === 'assistant:delta' ||
     type === 'assistant:response' ||
     type === 'tool:result' ||
+    type === 'plan:progress' ||
     type === 'compact:auto' ||
     type === 'dream:auto' ||
     type === 'dream:complete'
@@ -4182,13 +4183,6 @@ export function ChatApp({ runtime, sessionId, model, sdkProvider = 'openai-compa
           setRuntimeStatus(makeStatus(copy.runtime.toolBlocked, detail, 'redBright'));
           setInputStage('thinking');
           setActiveAssistantMeta({ loading: true, phase: 'thinking', liveStatus: copy.toolActivity.waitingModelAdjust(detail) });
-          setPlanState((prev) => ({
-            ...prev,
-            failed: prev.total > 0,
-            steps: (prev.steps || []).map((step) =>
-              step.index === prev.current ? { ...step, status: 'failed' } : step
-            )
-          }));
           updateActivityStatusOnActiveAssistant({
             type: 'tool',
             id: event.id,
@@ -4202,13 +4196,6 @@ export function ChatApp({ runtime, sessionId, model, sdkProvider = 'openai-compa
           setRuntimeStatus(makeStatus(copy.runtime.toolFailed, event.summary || detail, 'redBright'));
           setInputStage('thinking');
           setActiveAssistantMeta({ loading: true, phase: 'thinking', liveStatus: copy.toolActivity.waitingModelAdjust(detail) });
-          setPlanState((prev) => ({
-            ...prev,
-            failed: prev.total > 0,
-            steps: (prev.steps || []).map((step) =>
-              step.index === prev.current ? { ...step, status: 'failed' } : step
-            )
-          }));
           updateActivityStatusOnActiveAssistant({
             type: 'tool',
             id: event.id,
@@ -4286,6 +4273,52 @@ export function ChatApp({ runtime, sessionId, model, sdkProvider = 'openai-compa
             }));
           }
         }
+        if (event?.type === 'plan:progress') {
+          const current = Number(event.step || 0);
+          const total = Number(event.total || 0);
+          const status = String(event.status || '').trim().toLowerCase();
+          if (current > 0 && total > 0) {
+            const role = String(event.role || '').trim().toLowerCase();
+            const normalizedRole = PLAN_AGENT_ROLES.has(role) ? role : 'coder';
+            const title = String(event.title || '').trim();
+            setPlanState((prev) => {
+              const existingSteps = Array.isArray(prev.steps) ? prev.steps : [];
+              const merged = existingSteps.some((step) => step.index === current)
+                ? existingSteps.map((step) =>
+                    step.index === current
+                      ? {
+                          ...step,
+                          total,
+                          role: event.role || step.role || normalizedRole,
+                          title: title || step.title || '',
+                          status: status === 'failed' ? 'failed' : status === 'done' ? 'done' : status === 'running' ? 'active' : step.status
+                        }
+                      : step
+                  )
+                : [
+                    ...existingSteps,
+                    {
+                      index: current,
+                      total,
+                      role: event.role || normalizedRole,
+                      title,
+                      status: status === 'failed' ? 'failed' : status === 'done' ? 'done' : 'active'
+                    }
+                  ];
+              return {
+                ...prev,
+                current,
+                total,
+                role: event.role || prev.role || normalizedRole,
+                title: title || prev.title || '',
+                failed: status === 'failed' ? true : prev.failed,
+                completed: status === 'done' && current === total && !prev.failed,
+                pendingApproval: false,
+                steps: merged.sort((a, b) => a.index - b.index)
+              };
+            });
+          }
+        }
         if (event?.type === 'skill:start') {
           ensureActiveAssistant();
           const detail = describeSkillActivity(event.name, copy);

package/templates/project-requirements/report-shell.html

@@ -0,0 +1,178 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{{title}}</title>
+  <style>
+    :root {
+      color-scheme: light dark;
+      --bg: #f7f8fb;
+      --panel: #ffffff;
+      --text: #182033;
+      --muted: #657086;
+      --line: #d9deea;
+      --accent: #2563eb;
+      --ok: #147a4a;
+      --warn: #a16207;
+      --unknown: #7c3aed;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg: #111521;
+        --panel: #181d2b;
+        --text: #edf2ff;
+        --muted: #a6afc3;
+        --line: #30384f;
+        --accent: #7aa2ff;
+      }
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      background: var(--bg);
+      color: var(--text);
+      font: 15px/1.55 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    }
+    header {
+      padding: 32px min(5vw, 56px) 22px;
+      border-bottom: 1px solid var(--line);
+      background: var(--panel);
+    }
+    h1, h2, h3 { line-height: 1.2; }
+    h1 { margin: 0 0 10px; font-size: clamp(28px, 4vw, 44px); }
+    h2 { margin: 36px 0 14px; font-size: 24px; }
+    h3 { margin: 24px 0 10px; font-size: 18px; }
+    a { color: var(--accent); }
+    .meta { color: var(--muted); display: flex; gap: 16px; flex-wrap: wrap; }
+    .layout { display: grid; grid-template-columns: minmax(180px, 260px) minmax(0, 1fr); gap: 28px; padding: 24px min(5vw, 56px) 56px; }
+    nav { position: sticky; top: 16px; align-self: start; }
+    nav a { display: block; padding: 8px 0; text-decoration: none; border-bottom: 1px solid color-mix(in srgb, var(--line), transparent 45%); }
+    main { max-width: 1180px; }
+    section { padding: 2px 0 18px; border-bottom: 1px solid var(--line); }
+    .controls { display: flex; gap: 10px; flex-wrap: wrap; margin: 12px 0 22px; }
+    input[type="search"] {
+      width: min(520px, 100%);
+      padding: 10px 12px;
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      background: var(--panel);
+      color: var(--text);
+    }
+    .card {
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      background: var(--panel);
+      padding: 16px;
+      margin: 12px 0;
+    }
+    .tag { display: inline-flex; align-items: center; border-radius: 999px; padding: 2px 8px; font-size: 12px; font-weight: 700; }
+    .tag.extracted { color: var(--ok); border: 1px solid color-mix(in srgb, var(--ok), transparent 45%); }
+    .tag.inferred { color: var(--warn); border: 1px solid color-mix(in srgb, var(--warn), transparent 45%); }
+    .tag.unknown { color: var(--unknown); border: 1px solid color-mix(in srgb, var(--unknown), transparent 45%); }
+    table { width: 100%; border-collapse: collapse; margin: 12px 0; }
+    th, td { text-align: left; vertical-align: top; padding: 9px 10px; border-bottom: 1px solid var(--line); }
+    th { color: var(--muted); font-size: 13px; }
+    code, pre { font-family: ui-monospace, SFMono-Regular, Consolas, "Liberation Mono", monospace; }
+    pre { overflow: auto; padding: 14px; border-radius: 8px; background: color-mix(in srgb, var(--panel), var(--line) 18%); }
+    .diagram { overflow: auto; }
+    .placeholder { color: var(--muted); font-style: italic; }
+    @media (max-width: 820px) {
+      .layout { grid-template-columns: 1fr; }
+      nav { position: static; }
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>{{title}}</h1>
+    <div class="meta">
+      <span>Workspace: {{workspace_name}}</span>
+      <span>Date: {{date}}</span>
+      <span>Generated: {{generated_at}}</span>
+    </div>
+  </header>
+  <div class="layout">
+    <nav aria-label="Report sections">
+      <a href="#summary">Summary</a>
+      <a href="#architecture">Architecture</a>
+      <a href="#interfaces">Interfaces</a>
+      <a href="#requirements">Requirements</a>
+      <a href="#flows">Flows</a>
+      <a href="#security">Security</a>
+      <a href="#nonfunctional">Non-functional</a>
+      <a href="#questions">Open Questions</a>
+      <a href="#evidence">Evidence</a>
+    </nav>
+    <main>
+      <div class="controls">
+        <input id="report-search" type="search" placeholder="Filter cards, APIs, modules, and evidence">
+      </div>
+      <section id="summary">
+        <h2>Executive Summary</h2>
+        <!-- REQUIREMENTS_SUMMARY -->
+        <p class="placeholder">Pending summary.</p>
+        <!-- /REQUIREMENTS_SUMMARY -->
+      </section>
+      <section id="architecture">
+        <h2>System Architecture</h2>
+        <!-- REQUIREMENTS_ARCHITECTURE -->
+        <p class="placeholder">Pending architecture map.</p>
+        <!-- /REQUIREMENTS_ARCHITECTURE -->
+      </section>
+      <section id="interfaces">
+        <h2>Interface Inventory</h2>
+        <!-- REQUIREMENTS_INTERFACE_INVENTORY -->
+        <p class="placeholder">Pending interface inventory.</p>
+        <!-- /REQUIREMENTS_INTERFACE_INVENTORY -->
+      </section>
+      <section id="requirements">
+        <h2>Requirement Cards</h2>
+        <!-- REQUIREMENTS_API_CARDS -->
+        <p class="placeholder">Pending requirement cards.</p>
+        <!-- /REQUIREMENTS_API_CARDS -->
+      </section>
+      <section id="flows">
+        <h2>Core Flows</h2>
+        <!-- REQUIREMENTS_FLOWS -->
+        <p class="placeholder">Pending flow diagrams.</p>
+        <!-- /REQUIREMENTS_FLOWS -->
+      </section>
+      <section id="security">
+        <h2>Security, Permissions, And Errors</h2>
+        <!-- REQUIREMENTS_SECURITY -->
+        <p class="placeholder">Pending security and error notes.</p>
+        <!-- /REQUIREMENTS_SECURITY -->
+      </section>
+      <section id="nonfunctional">
+        <h2>Non-functional Requirements</h2>
+        <!-- REQUIREMENTS_NONFUNCTIONAL -->
+        <p class="placeholder">Pending non-functional requirements.</p>
+        <!-- /REQUIREMENTS_NONFUNCTIONAL -->
+      </section>
+      <section id="questions">
+        <h2>Open Questions</h2>
+        <!-- REQUIREMENTS_OPEN_QUESTIONS -->
+        <p class="placeholder">Pending open questions.</p>
+        <!-- /REQUIREMENTS_OPEN_QUESTIONS -->
+      </section>
+      <section id="evidence">
+        <h2>Source Evidence Index</h2>
+        <!-- REQUIREMENTS_EVIDENCE_INDEX -->
+        <p class="placeholder">Pending evidence index.</p>
+        <!-- /REQUIREMENTS_EVIDENCE_INDEX -->
+      </section>
+    </main>
+  </div>
+  <script>
+    const search = document.querySelector('#report-search');
+    search?.addEventListener('input', () => {
+      const query = search.value.trim().toLowerCase();
+      for (const card of document.querySelectorAll('.card, details, table')) {
+        const matched = !query || card.textContent.toLowerCase().includes(query);
+        card.style.display = matched ? '' : 'none';
+      }
+    });
+  </script>
+</body>
+</html>