@ai-content-space/loopx 0.1.3 → 0.1.4

package/plugins/loopx/skills/plan/SKILL.md

@@ -40,7 +40,7 @@ By default, `plan` includes the full consensus review loop formerly documented u
 Accepted inputs:
 
 - an approved loopx clarify workflow slug
-- `.loopx/specs/clarify-*.md`
+- `.loopx/intake/clarify-*.md`
 - `.omx/specs/deep-interview-*.md`
 - a direct task description when enough context is already present
 - `--direct <spec-path>` to force a specific requirements artifact
@@ -174,7 +174,7 @@ The final plan must include:
 
 - ADR: Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups
 - concrete implementation steps sized to the actual task
-- target long-lived spec domains and the requirements delta for archive
+- target long-lived spec domains and an OpenSpec-style requirements delta for archive
 - vertical slices sized as independently verifiable tracer bullets, not horizontal layer-only task groups
 - execution inputs mapped to concrete sources before build starts
 - available execution lanes and recommended lane
@@ -220,7 +220,8 @@ The plan gate is blocked until:
 
 - plan package artifacts exist
 - change proposal, spec delta, design, tasks, vertical slices, and artifact graph exist
-- spec delta declares target domains and added or modified requirements
+- spec delta declares target domains and `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` blocks
+- every ADDED or MODIFIED requirement uses `### Requirement:`, contains SHALL or MUST text, and includes at least one `#### Scenario:`
 - vertical slices contain at least one `AFK` or `HITL` end-to-end slice with acceptance criteria and verification signal
 - Architect review is complete
 - Critic verdict is `approve`

package/scripts/codex-workflow-hook.mjs

@@ -3,7 +3,6 @@
 import { existsSync, readdirSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
-import { nextSkillCommand } from '../src/next-skill.mjs';
 
 function readStdin() {
   return new Promise((resolveValue) => {
@@ -29,9 +28,61 @@ function readStdin() {
 }
 
 function nextSkill(state) {
-  const command = nextSkillCommand(state);
-  if (command) {
-    return command;
+  if (!state || !state.slug) {
+    return null;
+  }
+  const reviewBuildCommand = `$build --from-review .loopx/workflows/${state.slug}/review-report.md`;
+  if (isClarifyReadyForPlan(state)) {
+    return `$plan ${state.slug}`;
+  }
+  if (state.current_stage === 'done'
+    && state.completion_confirmed === true
+    && state.archive_status !== 'archived') {
+    return `$archive ${state.slug}`;
+  }
+  if (state.stage_status === 'awaiting-approval'
+    && state.current_stage === 'plan'
+    && Array.isArray(state.plan_blockers)
+    && state.plan_blockers.length === 0) {
+    return `$build .loopx/plans/prd-${state.slug}.md`;
+  }
+  if (state.current_stage === 'build'
+    && state.stage_status === 'awaiting-approval'
+    && state.pending_user_decision === 'build->review'
+    && state.review_status === 'ready-for-review'
+    && state.execution_record_status === 'complete'
+    && Array.isArray(state.build_blockers)
+    && state.build_blockers.length === 0) {
+    return `$review .loopx/workflows/${state.slug}/execution-record.md`;
+  }
+  if (state.current_stage === 'review'
+    && state.review_verdict === 'request-changes'
+    && state.rollback_target === 'build'
+    && (
+      state.pending_user_decision === 'review->build'
+      || state.requested_transition === 'review->build'
+      || state.approval?.build === 'requested'
+      || state.approval?.build === 'approved'
+    )) {
+    return reviewBuildCommand;
+  }
+  if (state.current_stage === 'review'
+    && state.review_verdict === 'request-changes'
+    && state.requested_transition === 'review->build'
+    && state.approval?.build === 'approved') {
+    return reviewBuildCommand;
+  }
+  if (state.current_stage === 'review'
+    && state.review_verdict === 'request-changes'
+    && state.requested_transition === 'review->plan'
+    && state.approval?.rollback === 'approved') {
+    return `$plan ${state.slug}`;
+  }
+  if (state.current_stage === 'review'
+    && state.review_verdict === 'request-changes'
+    && state.requested_transition === 'review->clarify'
+    && state.approval?.rollback === 'approved') {
+    return `$clarify ${state.slug}`;
   }
   if (state.current_stage === 'review' && state.review_verdict === 'approve' && state.pending_user_decision === 'review->done') {
     return `loopx approve ${state.slug} --from review --to done`;
@@ -59,6 +110,49 @@ function stateLine(key, value) {
   return `${key}: ${value ?? 'unknown'}`;
 }
 
+function isClarifyReadyForPlan(state) {
+  return (state.current_stage === 'clarify' || (!state.current_stage && typeof state.clarify_current_round === 'number'))
+    && state.clarify_current_round > 0
+    && state.unresolved_ambiguity_count === 0
+    && state.clarify_non_goals_resolved === true
+    && state.clarify_decision_boundaries_resolved === true
+    && state.clarify_pressure_pass_complete === true
+    && typeof state.clarify_ambiguity_score === 'number'
+    && typeof state.clarify_target_ambiguity_threshold === 'number'
+    && state.clarify_ambiguity_score <= state.clarify_target_ambiguity_threshold;
+}
+
+function isLegacyClarifyState(state) {
+  return !state.current_stage && typeof state.clarify_current_round === 'number';
+}
+
+function nextActionLine(state, workflow) {
+  if (isLegacyClarifyState(state) && isClarifyReadyForPlan(state)) {
+    return `loopx migrate, then $plan ${state.slug || workflow}`;
+  }
+  if (isClarifyReadyForPlan(state) && state.approval?.plan !== 'approved') {
+    return `approve clarify -> plan, then $plan ${state.slug || workflow}`;
+  }
+  return nextSkill(state) || state.recommended_next_action || 'none';
+}
+
+function implementationGateLines(state) {
+  if (isClarifyReadyForPlan(state) && state.approval?.build !== 'approved') {
+    return [
+      'implementation gate: blocked until plan is approved',
+      'do not start build, TDD, or code edits from clarify',
+    ];
+  }
+  return [];
+}
+
+function stageText(state) {
+  if (isLegacyClarifyState(state)) {
+    return `legacy-clarify (${isClarifyReadyForPlan(state) ? 'blocked' : 'incomplete'})`;
+  }
+  return `${state.current_stage || 'unknown'} (${state.stage_status || 'unknown'})`;
+}
+
 function evidenceLines(state) {
   const evidence = Array.isArray(state.current_evidence_chain) ? state.current_evidence_chain : [];
   if (evidence.length === 0) {
@@ -131,9 +225,10 @@ try {
     '</loopx_instructions>',
     '<loopx_state>',
     `loopx workflow: ${state.slug || workflow}`,
-    `stage: ${state.current_stage || 'unknown'} (${state.stage_status || 'unknown'})`,
-    `next: ${nextSkill(state) || state.recommended_next_action || 'none'}`,
+    `stage: ${stageText(state)}`,
+    `next: ${nextActionLine(state, workflow)}`,
     `blockers: ${blockers(state)}`,
+    ...implementationGateLines(state),
     `approval: ${JSON.stringify(state.approval || {})}`,
     stateLine('readiness.plan.ready', boolText(state.readiness?.plan?.ready)),
     stateLine('readiness.build.ready', boolText(state.readiness?.build?.ready)),

package/skills/archive/SKILL.md

@@ -10,6 +10,15 @@ argument-hint: "<workflow slug>"
 
 Use `archive` after a loopx workflow has reached `done`. It syncs the accepted change delta into long-lived `.loopx/specs/` files, archives the change staging directory, and writes an advisory ADR candidate.
 
+The accepted delta is requirement-based, not a changelog block. Archive applies:
+
+- `## ADDED Requirements`
+- `## MODIFIED Requirements`
+- `## REMOVED Requirements`
+- `## RENAMED Requirements`
+
+into the current long-lived `## Requirements` state for each target domain.
+
 ## Inputs
 
 - `<workflow slug>` for a completed loopx workflow
@@ -33,6 +42,7 @@ Then report in Chinese:
 ## Boundaries
 
 - Do not run archive before `review -> done` has been approved.
+- Do not archive malformed requirement deltas. ADDED and MODIFIED entries must use `### Requirement:`, SHALL/MUST language, and at least one `#### Scenario:`.
 - Do not archive when `execution-record.md` declares non-empty `remaining_scope`, `completion_claim` other than `full`, or a mismatch between `planned_scope` and `implemented_scope`; route back to build/plan instead.
 - Do not edit implementation code.
 - Do not promote ADR candidates into `docs/adr/` automatically; report the candidate path for human follow-up.

package/skills/clarify/SKILL.md

@@ -23,7 +23,7 @@ Its job is not just to ask questions. Its job is to turn a vague or overloaded r
 - The request is broad, ambiguous, or mixes problem, solution, and implementation detail.
 - The user needs help defining scope, non-goals, acceptance criteria, or tradeoffs before planning.
 - A design direction exists only implicitly and would otherwise be invented during implementation.
-- The task will later be handed to `plan`, `build`, or `autopilot`, and you want a high-signal spec first.
+- The task will later be handed to `plan`, and you want a high-signal spec first.
 </Use_When>
 
 <Do_Not_Use_When>
@@ -33,7 +33,7 @@ Its job is not just to ask questions. Its job is to turn a vague or overloaded r
 </Do_Not_Use_When>
 
 <Why_This_Exists>
-Most implementation drift happens before coding begins. Teams often think they need “more planning,” when the real problem is weaker intent clarity, hidden assumptions, fuzzy boundaries, or a design shape that was never made explicit. `clarify` exists to solve those upstream failures before `plan` or `build` magnifies them.
+Most implementation drift happens before coding begins. Teams often think they need “more planning,” when the real problem is weaker intent clarity, hidden assumptions, fuzzy boundaries, or a design shape that was never made explicit. `clarify` exists to solve those upstream failures before `plan` turns the clarified intent into an execution contract.
 </Why_This_Exists>
 
 <Core_Principles>
@@ -268,7 +268,7 @@ Before marking a clarify spec handoff-ready, perform a self-review pass:
 
 Write the output to the loopx runtime namespace:
 
-- `.loopx/specs/clarify-<slug>-<timestamp>.md`
+- `.loopx/intake/clarify-<slug>-<timestamp>.md`
 
 The clarify spec should include:
 
@@ -299,17 +299,17 @@ The clarify spec should include:
 
 After the clarify spec is ready:
 
-- hand off to `plan` by default
-- hand off to `build` only if the user explicitly wants direct execution and the task is already concrete enough
-- hand off to `autopilot` only when the scope is sufficiently tight for a bounded end-to-end run
+- hand off to `plan`; do not start implementation, TDD, `build`, or `autopilot` from `clarify`
+- if the user asks to execute immediately, explain that loopx requires the `plan` gate first and provide the plan invocation
+- if a task is too small to justify planning, do not use `clarify`; handle that request outside the clarify workflow from the start
 
 Preferred explicit handoff contract:
 
 - Recommended invocation: `$plan <slug>`
-- Artifact-pinned invocation when needed: `$plan --direct .loopx/specs/clarify-<slug>-<timestamp>.md`
+- Artifact-pinned invocation when needed: `$plan --direct .loopx/intake/clarify-<slug>-<timestamp>.md`
 - Consumer behavior: treat the clarify spec as the source of truth for intent, non-goals, decision boundaries, constraints, and design direction; do not reopen clarification by default
 
-`clarify` itself does not implement the feature.
+`clarify` itself does not implement the feature. The handoff recommendation must name `plan` as the next workflow step.
 
 </Process>
 
@@ -328,6 +328,7 @@ Preferred explicit handoff contract:
 
 <Must_Not_Decide_Automatically>
 - approval to move from clarify into plan
+- skipping `plan` after producing a clarify spec
 - implementation details that were never clarified or grounded
 - widening the task because a broader redesign sounds cleaner
 </Must_Not_Decide_Automatically>

package/skills/plan/SKILL.md

@@ -40,7 +40,7 @@ By default, `plan` includes the full consensus review loop formerly documented u
 Accepted inputs:
 
 - an approved loopx clarify workflow slug
-- `.loopx/specs/clarify-*.md`
+- `.loopx/intake/clarify-*.md`
 - `.omx/specs/deep-interview-*.md`
 - a direct task description when enough context is already present
 - `--direct <spec-path>` to force a specific requirements artifact
@@ -174,7 +174,7 @@ The final plan must include:
 
 - ADR: Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups
 - concrete implementation steps sized to the actual task
-- target long-lived spec domains and the requirements delta for archive
+- target long-lived spec domains and an OpenSpec-style requirements delta for archive
 - vertical slices sized as independently verifiable tracer bullets, not horizontal layer-only task groups
 - execution inputs mapped to concrete sources before build starts
 - available execution lanes and recommended lane
@@ -220,7 +220,8 @@ The plan gate is blocked until:
 
 - plan package artifacts exist
 - change proposal, spec delta, design, tasks, vertical slices, and artifact graph exist
-- spec delta declares target domains and added or modified requirements
+- spec delta declares target domains and `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` blocks
+- every ADDED or MODIFIED requirement uses `### Requirement:`, contains SHALL or MUST text, and includes at least one `#### Scenario:`
 - vertical slices contain at least one `AFK` or `HITL` end-to-end slice with acceptance criteria and verification signal
 - Architect review is complete
 - Critic verdict is `approve`

package/src/build-runtime.mjs

@@ -135,6 +135,7 @@ function buildIterationData({ slug, iteration, noDeslop = false }, scriptEntry =
       `deslop=${deslopStatus}`,
       `regression=${regressionStatus}`,
     ],
+    changedFiles: normalizeArray(scriptEntry.changedFiles),
     delegations: normalizeDelegations(scriptEntry.delegations),
     architectFindings: scriptEntry.architectFindings || (
       architectVerdict === 'approve'
@@ -222,6 +223,7 @@ function lanePrompt(context, laneName) {
     '  "summary": string,',
     '  "evidence": [{"id": string, "kind": string, "summary": string, "ref": string}],',
     '  "delegations": [{"id": string, "role": string, "status": "active" | "complete" | "failed" | "blocked" | "pending" | "skipped", "blocking": boolean, "scope": string[], "evidence_path": string | null, "summary": string}],',
+    '  "changedFiles": string[],',
     '  "executionEvidence": string[],',
     '  "verificationEvidence": string[],',
     '  "limitations": string[]',
@@ -262,6 +264,7 @@ function deslopPrompt(context, changedEvidence) {
     '  "status": "complete" | "failed" | "pending" | "skipped",',
     '  "summary": string,',
     '  "evidence": [{"id": string, "kind": string, "summary": string, "ref": string}],',
+    '  "changedFiles": string[],',
     '  "limitations": string[]',
     '}',
     '',
@@ -396,6 +399,11 @@ export function createRealBuildAdapter({ model, codexExecJson = runCodexExecJson
           ...normalizeEvidence(regressionReport.evidence).map((item) => `${item.kind}:${item.summary}:${item.ref}`),
         ],
         architectFindings: normalizeArray(architectReport.findings, ['Architect gate returned no findings.']),
+        changedFiles: normalizeArray([
+          ...normalizeArray(executionLane.changedFiles),
+          ...normalizeArray(evidenceLane.changedFiles),
+          ...normalizeArray(deslopReport.changedFiles),
+        ]),
         delegations: lanes.flatMap((lane) => normalizeDelegations(lane.delegations)),
         limitations: [
           ...normalizeArray(executionLane.limitations),

package/src/cli.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { archiveStage, autopilotStage, approveStage, buildStage, clarifyStage, initWorkspace, planStage, reviewStage, statusSummary } from './workflow.mjs';
+import { renderHtmlViews } from './html-views.mjs';
 import { installBundledSkills } from './install-discovery.mjs';
 import { nextSkillCommand, withNextSkill } from './next-skill.mjs';
 import { doctorRuntime, migrateLegacyRuntime } from './runtime-maintenance.mjs';
@@ -18,6 +19,7 @@ function usage() {
     '  loopx review <slug> [--reviewer <name>]',
     '  loopx archive <slug>',
     '  loopx autopilot <slug> [--reviewer <name>]',
+    '  loopx render [slug|--all]',
     '  loopx status [slug] [--json]',
     '  loopx setup-context',
     '  loopx doctor',
@@ -202,6 +204,14 @@ async function main() {
         console.log(JSON.stringify({ ok: true, command, root: result.root, state: result.state, runPath: result.runPath }, null, 2));
         return;
       }
+      case 'render': {
+        const result = await renderHtmlViews(process.cwd(), {
+          slug: positionals[0],
+          all: Boolean(options.get('--all')),
+        });
+        console.log(JSON.stringify({ ok: true, command, ...result }, null, 2));
+        return;
+      }
       case 'status': {
         const result = await statusSummary(process.cwd(), positionals[0]);
         if (options.get('--json')) {

package/src/context-manifest.mjs

@@ -8,7 +8,7 @@ export const CONTEXT_MANIFEST_SCHEMA_VERSION = 1;
 const MAX_MANIFEST_ROWS = 80;
 
 function normalizePath(cwd, path) {
-  const resolved = resolve(path);
+  const resolved = resolve(cwd, path);
   const rel = relative(cwd, resolved);
   return rel && !rel.startsWith('..') ? rel : resolved;
 }

package/src/html-views.mjs

@@ -0,0 +1,316 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, join, relative } from 'node:path';
+
+import { nextSkillCommand } from './next-skill.mjs';
+import { statusSummary } from './workflow.mjs';
+
+const WORKFLOW_ARTIFACTS = [
+  { name: 'spec.md', label: '需求工作副本', page: 'intake.html' },
+  { name: 'plan.md', label: '计划', page: 'plan.html' },
+  { name: 'architecture.md', label: '架构', page: 'plan.html' },
+  { name: 'development-plan.md', label: '开发计划', page: 'plan.html' },
+  { name: 'test-plan.md', label: '测试计划', page: 'plan.html' },
+  { name: 'execution-record.md', label: '执行记录', page: 'build.html' },
+  { name: 'review-report.md', label: '评审报告', page: 'review.html' },
+];
+
+const PAGE_GROUPS = [
+  { file: 'intake.html', title: '需求澄清', artifacts: ['spec.md'] },
+  { file: 'plan.html', title: '计划与架构', artifacts: ['plan.md', 'architecture.md', 'development-plan.md', 'test-plan.md'] },
+  { file: 'build.html', title: '执行与验证', artifacts: ['execution-record.md'] },
+  { file: 'review.html', title: '评审结论', artifacts: ['review-report.md'] },
+];
+
+function escapeHtml(value) {
+  return String(value ?? '')
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+
+function htmlDoc({ title, body }) {
+  return [
+    '<!doctype html>',
+    '<html lang="zh-CN">',
+    '<head>',
+    '  <meta charset="utf-8">',
+    '  <meta name="viewport" content="width=device-width, initial-scale=1">',
+    `  <title>${escapeHtml(title)}</title>`,
+    '  <style>',
+    '    :root { color-scheme: light; --text: #17202a; --muted: #5f6f7f; --line: #d8e0e8; --bg: #f6f8fa; --panel: #ffffff; --accent: #1769aa; }',
+    '    * { box-sizing: border-box; }',
+    '    body { margin: 0; font: 15px/1.65 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; color: var(--text); background: var(--bg); }',
+    '    main { max-width: 1080px; margin: 0 auto; padding: 28px 20px 48px; }',
+    '    header { margin-bottom: 20px; }',
+    '    h1 { margin: 0 0 8px; font-size: 28px; line-height: 1.25; }',
+    '    h2 { margin: 24px 0 10px; font-size: 18px; }',
+    '    h3 { margin: 18px 0 8px; font-size: 16px; }',
+    '    a { color: var(--accent); text-decoration: none; }',
+    '    a:hover { text-decoration: underline; }',
+    '    .muted { color: var(--muted); }',
+    '    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 12px; }',
+    '    .panel { background: var(--panel); border: 1px solid var(--line); border-radius: 8px; padding: 14px 16px; }',
+    '    .badge { display: inline-block; border: 1px solid var(--line); border-radius: 999px; padding: 2px 9px; margin: 2px 4px 2px 0; color: var(--muted); background: #fff; font-size: 12px; }',
+    '    table { width: 100%; border-collapse: collapse; background: var(--panel); border: 1px solid var(--line); }',
+    '    th, td { padding: 8px 10px; border-bottom: 1px solid var(--line); text-align: left; vertical-align: top; }',
+    '    th { color: var(--muted); font-weight: 600; }',
+    '    pre { overflow: auto; padding: 12px; background: #0f1720; color: #edf4fb; border-radius: 8px; }',
+    '    code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }',
+    '    .markdown { background: var(--panel); border: 1px solid var(--line); border-radius: 8px; padding: 16px; }',
+    '  </style>',
+    '</head>',
+    '<body>',
+    '<main>',
+    body,
+    '</main>',
+    '</body>',
+    '</html>',
+  ].join('\n');
+}
+
+function listItems(items) {
+  const values = Array.isArray(items) ? items.filter(Boolean) : [];
+  if (values.length === 0) {
+    return '<span class="muted">无</span>';
+  }
+  return values.map((item) => `<span class="badge">${escapeHtml(item)}</span>`).join(' ');
+}
+
+function markdownToHtml(markdown) {
+  const lines = String(markdown || '').split('\n');
+  const html = [];
+  let inCode = false;
+  let listOpen = false;
+
+  const closeList = () => {
+    if (listOpen) {
+      html.push('</ul>');
+      listOpen = false;
+    }
+  };
+
+  for (const line of lines) {
+    if (line.startsWith('```')) {
+      if (inCode) {
+        html.push('</code></pre>');
+        inCode = false;
+      } else {
+        closeList();
+        html.push('<pre><code>');
+        inCode = true;
+      }
+      continue;
+    }
+    if (inCode) {
+      html.push(escapeHtml(line));
+      continue;
+    }
+    if (/^#{1,4}\s+/.test(line)) {
+      closeList();
+      const level = Math.min(4, line.match(/^#+/)?.[0].length || 2);
+      html.push(`<h${level}>${escapeHtml(line.replace(/^#{1,4}\s+/, ''))}</h${level}>`);
+      continue;
+    }
+    if (line.startsWith('- ')) {
+      if (!listOpen) {
+        html.push('<ul>');
+        listOpen = true;
+      }
+      html.push(`<li>${escapeHtml(line.slice(2))}</li>`);
+      continue;
+    }
+    if (!line.trim()) {
+      closeList();
+      continue;
+    }
+    closeList();
+    html.push(`<p>${escapeHtml(line)}</p>`);
+  }
+  closeList();
+  if (inCode) {
+    html.push('</code></pre>');
+  }
+  return html.join('\n');
+}
+
+function artifactLink(viewRoot, artifactPath, label) {
+  const href = relative(viewRoot, artifactPath).replaceAll('\\', '/');
+  return `<a href="${escapeHtml(href)}">${escapeHtml(label)}</a>`;
+}
+
+function statusPanels(status) {
+  const state = status.state || {};
+  const readiness = state.readiness || {};
+  const authorization = state.authorization || {};
+  const nextSkill = nextSkillCommand(state);
+  return [
+    '<section class="grid">',
+    `<div class="panel"><strong>阶段</strong><br>${escapeHtml(state.current_stage || '(none)')}</div>`,
+    `<div class="panel"><strong>状态</strong><br>${escapeHtml(state.stage_status || '(unknown)')}</div>`,
+    `<div class="panel"><strong>下一步</strong><br><code>${escapeHtml(nextSkill || status.next_action || 'none')}</code></div>`,
+    `<div class="panel"><strong>归档</strong><br>${escapeHtml(state.archive_status || 'pending')}</div>`,
+    '</section>',
+    '<section class="panel">',
+    '<h2>readiness / authorization</h2>',
+    '<table><thead><tr><th>关卡</th><th>ready</th><th>authorized</th><th>blockers</th></tr></thead><tbody>',
+    ...['plan', 'build', 'review', 'done', 'archive'].map((key) => [
+      '<tr>',
+      `<td>${escapeHtml(key)}</td>`,
+      `<td>${escapeHtml(readiness[key]?.ready ?? false)}</td>`,
+      `<td>${escapeHtml(authorization[key]?.authorized ?? false)}</td>`,
+      `<td>${listItems(readiness[key]?.blockers || [])}</td>`,
+      '</tr>',
+    ].join('')),
+    '</tbody></table>',
+    '</section>',
+  ].join('\n');
+}
+
+async function renderWorkflowPages(status) {
+  const root = status.root;
+  const viewRoot = join(root, 'view');
+  await mkdir(viewRoot, { recursive: true });
+
+  const artifactRows = WORKFLOW_ARTIFACTS.map((artifact) => {
+    const artifactPath = join(root, artifact.name);
+    return {
+      ...artifact,
+      path: artifactPath,
+      exists: existsSync(artifactPath),
+    };
+  });
+
+  for (const group of PAGE_GROUPS) {
+    const sections = [];
+    for (const artifactName of group.artifacts) {
+      const artifact = artifactRows.find((item) => item.name === artifactName);
+      if (!artifact?.exists) {
+        continue;
+      }
+      const text = await readFile(artifact.path, 'utf8');
+      sections.push([
+        `<section class="markdown">`,
+        `<p class="muted">${artifactLink(viewRoot, artifact.path, artifact.name)}</p>`,
+        markdownToHtml(text),
+        '</section>',
+      ].join('\n'));
+    }
+    await writeFile(join(viewRoot, group.file), htmlDoc({
+      title: `${group.title} - ${status.slug}`,
+      body: [
+        '<header>',
+        `<h1>${escapeHtml(group.title)}</h1>`,
+        `<p class="muted">工作流：${escapeHtml(status.slug)}</p>`,
+        '<p><a href="index.html">返回工作流首页</a></p>',
+        '</header>',
+        sections.length > 0 ? sections.join('\n') : '<section class="panel muted">暂无对应产物。</section>',
+      ].join('\n'),
+    }));
+  }
+
+  const indexBody = [
+    '<header>',
+    `<h1>工作流 ${escapeHtml(status.slug)}</h1>`,
+    `<p class="muted">HTML 是派生阅读视图；Markdown 和 JSON 仍是运行时事实源。</p>`,
+    '</header>',
+    statusPanels(status),
+    '<section class="panel">',
+    '<h2>关键产物</h2>',
+    '<table><thead><tr><th>产物</th><th>状态</th><th>阅读视图</th><th>原始文件</th></tr></thead><tbody>',
+    ...artifactRows.map((artifact) => [
+      '<tr>',
+      `<td>${escapeHtml(artifact.label)}</td>`,
+      `<td>${artifact.exists ? '存在' : '缺失'}</td>`,
+      `<td>${artifact.exists ? `<a href="${escapeHtml(artifact.page)}">${escapeHtml(basename(artifact.page))}</a>` : '<span class="muted">无</span>'}</td>`,
+      `<td>${artifact.exists ? artifactLink(viewRoot, artifact.path, artifact.name) : '<span class="muted">无</span>'}</td>`,
+      '</tr>',
+    ].join('')),
+    '</tbody></table>',
+    '</section>',
+  ].join('\n');
+
+  const workflowViewPath = join(viewRoot, 'index.html');
+  await writeFile(workflowViewPath, htmlDoc({
+    title: `loopx 工作流 ${status.slug}`,
+    body: indexBody,
+  }));
+
+  return workflowViewPath;
+}
+
+async function renderWorkspaceIndex(workspaceStatus, renderedSlugs = []) {
+  const viewsRoot = join(workspaceStatus.workspaceRoot, 'views');
+  await mkdir(viewsRoot, { recursive: true });
+  const rendered = new Set(renderedSlugs);
+  const rows = (workspaceStatus.workflows || []).map((workflow) => {
+    const href = `../workflows/${workflow.slug}/view/index.html`;
+    const link = rendered.has(workflow.slug)
+      ? `<a href="${escapeHtml(href)}">${escapeHtml(workflow.slug)}</a>`
+      : escapeHtml(workflow.slug);
+    return [
+      '<tr>',
+      `<td>${link}</td>`,
+      `<td>${escapeHtml(workflow.current_stage || '(none)')}</td>`,
+      `<td>${escapeHtml(workflow.contract)}</td>`,
+      `<td>${escapeHtml(workflow.missing_artifact_count)}</td>`,
+      '</tr>',
+    ].join('');
+  });
+  const workspaceViewPath = join(viewsRoot, 'index.html');
+  await writeFile(workspaceViewPath, htmlDoc({
+    title: 'loopx 工作台',
+    body: [
+      '<header>',
+      '<h1>loopx 工作台</h1>',
+      `<p class="muted">工作区：${escapeHtml(workspaceStatus.workspaceRoot)}</p>`,
+      '</header>',
+      '<section class="panel">',
+      '<h2>工作流</h2>',
+      '<table><thead><tr><th>工作流</th><th>阶段</th><th>契约</th><th>缺失产物数</th></tr></thead><tbody>',
+      rows.join('\n') || '<tr><td colspan="4" class="muted">暂无工作流。</td></tr>',
+      '</tbody></table>',
+      '</section>',
+    ].join('\n'),
+  }));
+  return workspaceViewPath;
+}
+
+export async function renderHtmlViews(cwd, { slug = null, all = false } = {}) {
+  const workspaceStatus = await statusSummary(cwd);
+  if (!workspaceStatus.initialized) {
+    throw new Error('loopx_workspace_not_initialized');
+  }
+
+  const workflowViews = [];
+  if (all || !slug) {
+    for (const workflow of workspaceStatus.workflows) {
+      if (workflow.legacy) {
+        continue;
+      }
+      const workflowStatus = await statusSummary(cwd, workflow.slug);
+      workflowViews.push({
+        slug: workflow.slug,
+        path: await renderWorkflowPages(workflowStatus),
+      });
+    }
+  } else if (slug) {
+    const workflowStatus = await statusSummary(cwd, slug);
+    if (!workflowStatus.state || workflowStatus.legacy) {
+      throw new Error('render_workflow_not_available');
+    }
+    workflowViews.push({
+      slug: workflowStatus.slug,
+      path: await renderWorkflowPages(workflowStatus),
+    });
+  }
+
+  const workspaceViewPath = await renderWorkspaceIndex(workspaceStatus, workflowViews.map((item) => item.slug));
+  return {
+    workflowViews,
+    workflowViewPath: workflowViews[0]?.path || null,
+    workspaceViewPath,
+  };
+}