@ai-content-space/loopx 0.1.10 → 0.2.1

package/src/plan-runtime.mjs

@@ -4,6 +4,12 @@ import { mkdir } from 'node:fs/promises';
 import { runCodexExecJson } from './codex-exec-runtime.mjs';
 
 const DEFAULT_MAX_ITERATIONS = 5;
+const DEFAULT_PLAN_CODEX_TIMEOUT_MS = 600000;
+
+function planCodexTimeoutMs() {
+  const value = Number(process.env.LOOPX_PLAN_CODEX_TIMEOUT_MS || DEFAULT_PLAN_CODEX_TIMEOUT_MS);
+  return Number.isFinite(value) && value > 0 ? value : DEFAULT_PLAN_CODEX_TIMEOUT_MS;
+}
 
 function extractSection(text, heading) {
   const pattern = new RegExp(`## ${heading}\\n\\n([\\s\\S]*?)(?=\\n## |$)`, 'i');
@@ -59,141 +65,195 @@ function buildSourceSummary(sourceText) {
   };
 }
 
+function mdTable(headers, rows) {
+  return [
+    `| ${headers.join(' | ')} |`,
+    `| ${headers.map(() => '---').join(' | ')} |`,
+    ...rows.map((row) => `| ${row.map((cell) => String(cell ?? '').replace(/\n/g, ' ').replace(/\|/g, '\\|')).join(' | ')} |`),
+  ].join('\n');
+}
+
 function plannerDraftFromSource({ slug, sourceText, deliberateMode }) {
   const summary = buildSourceSummary(sourceText);
   const executionInputs = bulletsFromSection(extractSection(sourceText, 'Execution Inputs'), []);
   const executionInputsResolved = executionInputs.length > 0 && executionInputs.every((item) => !/\b(TBD|待定|unknown|later)\b/i.test(item));
+  const inScope = summary.inScope.slice(0, 16);
+  const acceptance = summary.acceptance.slice(0, 16);
+  const constraints = summary.constraints.slice(0, 12);
+  const decisions = summary.decisions.slice(0, 12);
   const preMortem = deliberateMode
     ? [
-        '如果运行时没有独立的规划适配层，真实编排与测试替身会相互污染。',
-        '如果 docs 只是附加产物，plan 完成判定会再次与文档契约脱节。',
-        '如果 status 只显示 plan_package_status，规划阶段故障仍然无法诊断。',
+        '如果架构边界没有明确外部依赖和副作用控制，build 阶段容易把 mock 范围误做成真实集成。',
+        '如果开发切片只按模块拆分而不是按可验收行为拆分，后续实现容易出现页面、接口和数据闭环脱节。',
+        '如果测试计划没有覆盖核心验收样例、异常路径和人工确认点，review 阶段无法判断是否满足需求。',
       ]
     : [];
 
   return {
     principles: [
-      '运行时行为必须与已发布的 planning contract 对齐。',
-      '规划阶段只做规划，不自动进入执行阶段。',
-      '完成判定必须机器可检查。',
-      '中文 docs 是阻塞产物，不是附加导出。',
-      '保持变更范围集中在 plan runtime、status 和测试。',
+      '计划必须完整承接已澄清需求，不把核心范围压缩成泛化条目。',
+      '架构、详细设计、开发计划和测试计划必须分别回答不同问题，避免 build 阶段自行补设计。',
+      '涉及人工确认、外部系统、资金资产、交易、权限或通知的边界必须显式写清。',
+      '每个可交付切片都必须有可验证信号和人工确认点。',
+      '计划阶段只输出方案和执行输入，不自动进入实现。',
     ],
     decisionDrivers: [
-      '当前 skill contract 与 runtime truth 不一致。',
-      'approved plan 与中文 docs 都是必需产物。',
-      '现有 clarify/build/review 行为需要保持稳定。',
+      summary.intent,
+      summary.outcome,
+      '后续 build 需要可直接执行的模块边界、数据结构、接口契约和验收矩阵。',
     ],
     options: [
       {
-        name: '在 plan runtime 内嵌编排',
-        pros: ['runtime 真相与产品契约保持一致', '由同一个状态机管理 gate 与工件'],
-        cons: ['需要额外的 adapter 边界来支撑确定性测试'],
+        name: '统一平台底座 + 场景扩展',
+        pros: ['共享状态、日志、异常和验收闭环', '减少重复实现', '便于后续接入真实 adapter'],
+        cons: ['需要严格控制扩展字段和状态机边界'],
       },
       {
-        name: '在轻量 plan 外包一层共识流程',
-        pros: ['短期 diff 更小'],
-        cons: ['wrapper 与 runtime 的事实仍然分裂', 'status 与调试信息继续碎片化'],
+        name: '按场景分别实现',
+        pros: ['单个场景领域表达更直接'],
+        cons: ['重复状态机、接口、日志和页面结构，首期交付和回归成本高'],
       },
     ],
     planText: [
-      `# loopx 计划: ${slug}`,
+      `# 计划：${slug}`,
       '',
       '## 需求摘要',
       '',
       `- ${summary.intent}`,
       `- ${summary.outcome}`,
       '',
-      '## 交付物',
+      '## 交付范围',
       '',
-      ...summary.acceptance.map((item, index) => `${index + 1}. ${item}`),
+      ...inScope.map((item) => `- ${item}`),
       '',
-      '## 实施步骤',
+      '## 方案选择',
       '',
-      '1. 为 planner、architect、critic 增加 plan orchestration adapter。',
-      '2. 在 workflow state 中记录 plan iteration、review verdict 和 execution-input blockers。',
-      '3. 从已批准的 planning source 生成中文主规划工件与 canonical plan artifacts。',
-      '4. 在 CLI status 中暴露 plan 阶段进度。',
-      '5. 为 happy path、iterate path 和 execution input 未收口路径补 deterministic regression coverage。',
+      '采用统一平台底座承载核心流程，并通过场景配置、受控扩展结构或子表表达差异。该方案优先保证人工确认边界、数据追溯、异常处理和验收闭环。',
       '',
-      '## 执行输入',
+      '## 关键里程碑',
+      '',
+      '1. 明确架构边界、数据模型、状态机和外部依赖隔离方式。',
+      '2. 定义接口、函数、组件、字段和错误处理契约。',
+      '3. 按可验收行为拆分开发切片并逐项落地。',
+      '4. 按需求验收矩阵完成自动化验证和必要人工确认。',
       '',
-      ...(executionInputs.length > 0 ? executionInputs.map((item) => `- ${item}`) : ['- TBD: execution inputs not yet mapped to concrete sources.']),
+      '## 验收目标',
+      '',
+      ...acceptance.map((item) => `- ${item}`),
       '',
       '## 风险',
       '',
-      ...summary.constraints.map((item) => `- ${item}`),
+      ...constraints.map((item) => `- ${item}`),
       '',
-      '## 验证',
+      '## 执行输入',
       '',
-      '- 运行 workflow tests',
-      '- 运行 CLI status checks',
-      '- 证明 execution input blockers 与 iterate path 生效',
+      ...(executionInputs.length > 0 ? executionInputs.map((item) => `- ${item}`) : ['- 源需求规格、产品文档、原型说明和当前代码事实。']),
     ].join('\n'),
     architectureText: [
-      `# 架构文档: ${slug}`,
+      `# 架构方案：${slug}`,
       '',
-      '## 目标',
+      '## 文档定位',
       '',
-      `- ${summary.intent}`,
+      '架构方案是本阶段的架构文档，回答系统边界、模块职责、数据/状态流、接口边界、架构决策和质量属性，不负责逐文件排期或字段级默认值。',
+      '',
+      '## 架构目标与非目标',
+      '',
+      `目标：${summary.intent}`,
       '',
-      '## 边界',
+      '非目标：',
       '',
-      ...summary.decisions.map((item) => `- ${item}`),
+      ...summary.nonGoals.map((item) => `- ${item}`),
       '',
-      '## 选定方案',
+      '## 上下文与系统边界',
       '',
-      '- plan runtime 负责 planner -> architect -> critic 闭环',
-      '- 通过专用 adapter 隔离生产编排与确定性测试',
-      '- canonical plan artifacts 保持写入 `.loopx/plans/`',
-      '- `.loopx/workflows/<slug>/` 下的主规划工件直接作为中文产物',
+      ...decisions.map((item) => `- ${item}`),
       '',
-      '## 备选方案',
+      '## 组件与职责',
       '',
-      '- 保持 plan 轻量并在外层包一层流程',
-      '- 推迟 runtime 对齐，仅把 skill contract 当目标状态',
+      '| 组件 | 职责 | 边界 |',
+      '| --- | --- | --- |',
+      '| 入口层 | 接收用户、API、任务或页面操作 | 只做参数适配和鉴权，不承载核心业务规则 |',
+      '| 业务层 | 编排状态机、明细生成、异常处理和人工动作 | 不直接调用未声明的真实外部副作用 |',
+      '| 数据层 | 持久化核心实体、日志、状态和追溯字段 | 结构化字段优先，扩展字段受控 |',
+      '| 前端/交互层 | 展示任务、明细、进度、操作和验收反馈 | 不自行推导状态机或绕过后端校验 |',
+      '',
+      '## 数据与状态模型',
+      '',
+      '- 核心数据必须支持来源追溯、状态推进、人工操作留痕、异常处理和验收核对。',
+      '- 状态机必须集中定义合法动作、前置条件、后置状态和非法路径。',
+      '- 外部来源、下游回写和真实副作用必须通过明确 adapter/provider 边界隔离。',
+      '',
+      '## 接口与集成契约',
+      '',
+      '- API、任务入口、页面路由和 provider 方法必须列明输入、输出、权限、错误和幂等边界。',
+      '- mock 与真实集成必须可区分；首期未批准的真实依赖不得暗接。',
+      '',
+      '## 架构决策记录',
+      '',
+      '| 决策 | 取舍 | 后续影响 |',
+      '| --- | --- | --- |',
+      '| 统一平台底座 | 降低重复实现并集中控制状态/日志/异常 | 场景差异必须进入受控扩展点 |',
     ].join('\n'),
     developmentPlanText: [
-      `# 开发计划: ${slug}`,
+      `# 开发计划：${slug}`,
+      '',
+      '## 文档定位',
+      '',
+      '开发计划回答交付顺序、切片、依赖、验证、人工确认点、回滚和完成定义，不重新选择架构方向。',
+      '',
+      '## 交付切片',
+      '',
+      '1. 领域/数据/状态底座：定义核心实体、状态机、repository/usecase 边界和基础测试。',
+      '2. 主流程闭环：实现数据生成、查询、人工动作、日志和异常处理。',
+      '3. 入口与交互：接入 API、页面、权限和必要的前端组件。',
+      '4. 验收收敛：按源需求逐项跑自动化验证和人工验收。',
+      '',
+      '## 实施顺序与依赖',
       '',
-      '## 执行拆解',
+      '- 先完成数据和状态机，再暴露入口，最后做页面和端到端验收。',
+      '- 涉及外部副作用、权限、资金资产、交易或通知的切片必须 HITL。',
+      '- 如果实现发现源需求与代码事实冲突，必须回到 plan/clarify 修订。',
       '',
-      '1. 扩展 plan state schema 与 status 输出。',
-      '2. 实现带有有界迭代的 planner/architect/critic 编排。',
-      '3. 直接输出中文主规划工件与 canonical plan artifacts。',
-      '4. 增加 deterministic test seams 与 regression coverage。',
+      '## 文件级变更清单',
       '',
-      '## 责任分工',
+      '- 后端业务域、API/handler、数据 schema/repository、service/server wiring。',
+      '- 前端页面、组件、API client、构建配置。',
+      '- 单元测试、接口测试、构建验证和人工验收记录。',
       '',
-      '- owner: plan runtime',
-      '- reviewer: architect and critic',
-      '- downstream execution: 仅在后续显式批准后进入',
+      '## 验证计划',
       '',
-      '## 时序要求',
+      ...acceptance.map((item) => `- 验证：${item}`),
       '',
-      '- architect 未完成前不得运行 critic',
-      '- plan blockers 清除前不得批准 build',
-      '- plan 阶段不得自动启动执行',
+      '## 完成定义',
+      '',
+      '- 所有源需求都有实现证据或明确非目标说明。',
+      '- 自动化测试、构建和人工验收信号与开发切片一一对应。',
+      '- 未完成、风险和回滚路径在交付说明中明确记录。',
     ].join('\n'),
     testPlanText: [
-      `# 测试计划: ${slug}`,
+      `# 测试计划：${slug}`,
+      '',
+      '## 需求到测试矩阵',
+      '',
+      ...acceptance.map((item) => `- ${item}`),
       '',
-      '## 单元测试',
+      '## 自动化测试',
       '',
-      '- plan consensus mode 的 state 初始化',
-      '- 中文主规划工件的 blocking checks',
-      '- planner/architect/critic review artifact 记录',
+      '- 状态机合法/非法转换。',
+      '- 数据去重、持久化、查询和日志写入。',
+      '- API 参数、权限、错误和响应结构。',
+      '- 前端构建和关键页面渲染。',
       '',
-      '## 集成测试',
+      '## 人工验收',
       '',
-      '- clarify -> plan happy path',
-      '- critic iterate 再 approve 的路径',
-      '- 主规划工件缺失或非中文时的 blocking 路径',
-      '- execution inputs 缺失或标记 TBD 的 blocking 路径',
+      '- 页面/流程是否符合原型和产品文档。',
+      '- 人工确认动作是否清晰且不可被系统自动跳过。',
+      '- mock/真实边界是否符合非目标。',
       '',
-      '## 可观测性',
+      '## 回归门禁',
       '',
-      '- status 输出 iteration、architect review status、critic verdict 与 execution input blockers',
+      '- build 阶段必须记录命令、结果、截图或人工确认证据。',
+      '- review 阶段必须能按需求矩阵追溯每个验收项。',
     ].join('\n'),
     preMortem,
     principlesResolved: true,
@@ -282,6 +342,21 @@ function defaultCriticReview({ plannerDraft, iteration }) {
   });
 }
 
+function isCodexTimeoutError(error) {
+  return /codex_exec_failed:timeout|timeout/i.test(error instanceof Error ? error.message : String(error));
+}
+
+function shouldUseSourceDrivenDefault(context) {
+  const mode = String(process.env.LOOPX_PLAN_RUNTIME || '').trim().toLowerCase();
+  if (mode === 'local' || mode === 'source' || mode === 'source-driven') {
+    return true;
+  }
+  if (mode === 'codex' || mode === 'real') {
+    return false;
+  }
+  return String(context?.sourceText || '').length > 45000;
+}
+
 function scriptedVerdict(script, index, fallback) {
   if (!Array.isArray(script) || script.length === 0) {
     return fallback;
@@ -335,7 +410,19 @@ export function createScriptedPlanAdapter(script = {}) {
 }
 
 export function createDefaultPlanAdapter() {
-  return createRealPlanAdapter();
+  const local = createScriptedPlanAdapter();
+  const real = createRealPlanAdapter();
+  return {
+    async planner(context) {
+      return shouldUseSourceDrivenDefault(context) ? local.planner(context) : real.planner(context);
+    },
+    async architect(context) {
+      return shouldUseSourceDrivenDefault(context) ? local.architect(context) : real.architect(context);
+    },
+    async critic(context) {
+      return shouldUseSourceDrivenDefault(context) ? local.critic(context) : real.critic(context);
+    },
+  };
 }
 
 export function createRealPlanAdapter({ model } = {}) {
@@ -343,9 +430,11 @@ export function createRealPlanAdapter({ model } = {}) {
     async planner(context) {
       const outputPath = join(context.root, 'plan-reviews', `planner-iteration-${context.iteration}.json`);
       await mkdir(join(context.root, 'plan-reviews'), { recursive: true });
+      const timeoutMs = planCodexTimeoutMs();
       const prompt = [
         `You are acting as the real loopx plan runtime for workflow "${context.slug}".`,
         'Read the source requirements and produce planning content for this workflow.',
+        'Use only the source requirements included in this prompt and the Brownfield Evidence already written there. Do not inspect the repository, run shell commands, or search generated code. If a code fact is not in the source, mark it as an assumption or build-time confirmation point.',
         'Return only raw JSON matching this shape:',
         '{',
         '  "principles": string[],',
@@ -364,8 +453,14 @@ export function createRealPlanAdapter({ model } = {}) {
         `Deliberate mode: ${Boolean(context.deliberateMode)}`,
         '',
         'planText, architectureText, developmentPlanText, and testPlanText MUST be written in Chinese for human review. Do not write English headings or English prose except literal code paths, API names, commands, enum values, and product terms.',
-        'Make the artifacts reviewable: use clear Chinese section headings, concise tables for coverage/options/risks, and explicit approval-ready handoff sections. Avoid generic filler.',
-        'Treat the source requirements/PRD as the source of truth. Explicitly cover every named event, field, processing mode, table row, and acceptance item that appears in the source, or clearly mark it out of scope with rationale.',
+        'Make the artifacts approval-ready, not summary-only: each Markdown body must include enough detail for a human reviewer to approve or reject without opening JSON runtime state.',
+        'Required reviewer-facing sections: 原始需求清单, 原始需求映射, 方案选择/ADR, 架构边界, 开发切片, 测试矩阵, 风险与非目标, 人工确认点, build handoff.',
+        'architectureText is the architecture document: it MUST define 文档定位, 架构目标与非目标, 上下文与系统边界, 组件与职责, 数据与状态模型, 接口与集成契约, 关键流程, 质量属性与风险, 架构决策记录. It answers system boundaries and design tradeoffs, not implementation scheduling.',
+        'developmentPlanText is the development plan: it MUST define 文档定位, 交付切片, 实施顺序与依赖, 需求到开发切片, 文件级变更清单, 验证计划, 人工确认点, 回滚/降级策略, 完成定义. It answers execution sequence and completion gates, not architecture selection.',
+        'The detailed design is generated as change design.md from the plan package and MUST define 文档定位, 需求到设计映射, 数据结构与字段, 接口、函数与组件契约, 状态机与流程细节, 错误处理与边界条件, 测试设计, 实现注意事项. It answers field/function/component-level implementation details.',
+        'Treat the source requirements/PRD as the source of truth. Explicitly enumerate every named event, field, workflow, processing mode, table row, and acceptance item that appears in the source, or clearly mark it out of scope with rationale.',
+        'Do not collapse broad requirements into generic bullets such as "新增后台页面" or "覆盖 8 类工作流"; expand them into reviewable subitems, ownership, verification signals, and residual risks.',
+        'The HTML reading view is derived from these Markdown bodies, so the Markdown itself must contain detailed tables and sections instead of relying on a separate visual summary.',
         'If previous review feedback is present, revise the plan to explicitly resolve it. Do not repeat the same plan unchanged.',
         'Do not ask questions. Do not wrap JSON in markdown.',
         '',
@@ -375,16 +470,26 @@ export function createRealPlanAdapter({ model } = {}) {
         'Source requirements:',
         context.sourceText,
       ].join('\n');
-      return runCodexExecJson({
-        cwd: context.cwd,
-        prompt,
-        outputPath,
-        model,
-      });
+      try {
+        return await runCodexExecJson({
+          cwd: context.cwd,
+          prompt,
+          outputPath,
+          model,
+          timeoutMs,
+          promptViaStdin: true,
+        });
+      } catch (error) {
+        if (isCodexTimeoutError(error)) {
+          return plannerDraftFromSource(context);
+        }
+        throw error;
+      }
     },
     async architect(context) {
       const outputPath = join(context.root, 'plan-reviews', `architect-iteration-${context.iteration}.json`);
       await mkdir(join(context.root, 'plan-reviews'), { recursive: true });
+      const timeoutMs = planCodexTimeoutMs();
       const draftText = [
         context.plannerDraft.planText,
         '',
@@ -396,6 +501,7 @@ export function createRealPlanAdapter({ model } = {}) {
       ].join('\n');
       const prompt = [
         `You are acting as the real loopx architect review for workflow "${context.slug}".`,
+        'Use only the planning draft in this prompt. Do not inspect the repository or run searches.',
         'Review the provided planning draft and return only raw JSON with this shape:',
         '{',
         '  "status": "complete" | "changes-requested",',
@@ -409,16 +515,26 @@ export function createRealPlanAdapter({ model } = {}) {
         'Planning draft:',
         draftText,
       ].join('\n');
-      return runCodexExecJson({
-        cwd: context.cwd,
-        prompt,
-        outputPath,
-        model,
-      });
+      try {
+        return await runCodexExecJson({
+          cwd: context.cwd,
+          prompt,
+          outputPath,
+          model,
+          timeoutMs,
+          promptViaStdin: true,
+        });
+      } catch (error) {
+        if (isCodexTimeoutError(error)) {
+          return defaultArchitectReview(context);
+        }
+        throw error;
+      }
     },
     async critic(context) {
       const outputPath = join(context.root, 'plan-reviews', `critic-iteration-${context.iteration}.json`);
       await mkdir(join(context.root, 'plan-reviews'), { recursive: true });
+      const timeoutMs = planCodexTimeoutMs();
       const draftText = [
         context.plannerDraft.planText,
         '',
@@ -430,6 +546,7 @@ export function createRealPlanAdapter({ model } = {}) {
       ].join('\n');
       const prompt = [
         `You are acting as the real loopx critic gate for workflow "${context.slug}".`,
+        'Use only the planning draft and architect review in this prompt. Do not inspect the repository or run searches.',
         'Review the planning draft plus architect review and return only raw JSON with this shape:',
         '{',
         '  "verdict": "approve" | "iterate" | "reject",',
@@ -446,12 +563,21 @@ export function createRealPlanAdapter({ model } = {}) {
         'Architect review:',
         JSON.stringify(context.architectReview, null, 2),
       ].join('\n');
-      return runCodexExecJson({
-        cwd: context.cwd,
-        prompt,
-        outputPath,
-        model,
-      });
+      try {
+        return await runCodexExecJson({
+          cwd: context.cwd,
+          prompt,
+          outputPath,
+          model,
+          timeoutMs,
+          promptViaStdin: true,
+        });
+      } catch (error) {
+        if (isCodexTimeoutError(error)) {
+          return defaultCriticReview(context);
+        }
+        throw error;
+      }
     },
   };
 }

package/src/runtime-maintenance.mjs

@@ -369,7 +369,8 @@ function createMigratedWorkflowBaseState(slug, legacyState, change) {
 async function migrateLegacyWorkflowState(cwd, slug, workflowRoot, legacyState) {
   const change = await findActiveChangeForWorkflow(cwd, slug);
   const reviewState = await inferReviewState(workflowRoot);
-  const canonicalPlanPath = join(resolveLoopxRoot(cwd), 'plans', `prd-${slug}.md`);
+  const canonicalPlanPath = join(resolveLoopxRoot(cwd), 'plans', `requirements-snapshot-${slug}.md`);
+  const legacyCanonicalPlanPath = join(resolveLoopxRoot(cwd), 'plans', `prd-${slug}.md`);
   const canonicalTestSpecPath = join(resolveLoopxRoot(cwd), 'plans', `test-spec-${slug}.md`);
   const baseState = createMigratedWorkflowBaseState(slug, legacyState, change);
   const planBlockers = await legacyPlanArtifactBlockers(workflowRoot);
@@ -422,7 +423,9 @@ async function migrateLegacyWorkflowState(cwd, slug, workflowRoot, legacyState)
     schema_version: WORKFLOW_SCHEMA_VERSION,
     slug,
     clarify_profile: legacyState.clarify_profile || legacyState.profile || 'standard',
-    plan_artifact_path: existsSync(canonicalPlanPath) ? canonicalPlanPath : join(workflowRoot, 'plan.md'),
+    plan_artifact_path: existsSync(canonicalPlanPath)
+      ? canonicalPlanPath
+      : (existsSync(legacyCanonicalPlanPath) ? legacyCanonicalPlanPath : join(workflowRoot, 'plan.md')),
     test_spec_artifact_path: existsSync(canonicalTestSpecPath) ? canonicalTestSpecPath : join(workflowRoot, 'test-plan.md'),
     execution_record_status: executionRecordStatus,
     ...(reviewState || {}),