helloloop 0.1.1 → 0.2.0

package/hosts/gemini/extension/GEMINI.md

@@ -0,0 +1,29 @@
+# HelloLoop for Gemini CLI
+
+你正在使用 `HelloLoop` 的 Gemini CLI 原生扩展。
+
+## 工作目标
+
+基于开发文档持续推进仓库开发，先分析真实进度，再在确认后自动接续开发、测试和验收。
+
+## 默认流程
+
+1. 自动识别项目仓库与开发文档
+2. 分析当前代码与开发文档的差距
+3. 在目标仓库根目录创建或刷新 `.helloloop/`
+4. 输出中文执行确认单
+5. 用户确认后，再继续执行后续开发任务
+
+## 强制规则
+
+- 代码是事实源，开发文档是目标源。
+- 开发前必须先输出执行确认单。
+- 如果无法识别目标仓库或开发文档，必须停下来询问用户。
+- 如果识别到偏差修正任务，优先收口偏差，再推进后续 backlog。
+- 真正执行前确认，真正结束前验证。
+
+## Windows 安全
+
+- 谨慎使用 shell；优先使用原生文件工具完成读写与目录操作。
+- 禁止危险删除、格式化、强推、硬重置等命令。
+- 不允许通过路径拼接生成破坏性命令。

package/hosts/gemini/extension/commands/helloloop.toml

@@ -0,0 +1,24 @@
+description = "根据开发文档分析当前进度、生成确认单，并在确认后继续接续开发"
+prompt = """
+你现在正在执行 HelloLoop 的 Gemini CLI 原生工作流。
+
+执行要求：
+
+1. 自动识别目标仓库与开发文档；如果用户在命令后提供了参数，只把它解释为一个路径。
+2. 分析当前代码与开发文档之间的真实进度和偏差。
+3. 在目标仓库根目录创建或刷新 `.helloloop/`，至少维护 `backlog.json`、`project.json`、`status.json`、`STATE.md` 与 `runs/`。
+4. 在真正开发前，必须输出中文执行确认单，至少包含：
+   - 目标仓库
+   - 开发文档
+   - 当前进度
+   - 已实现事项
+   - 待完成事项
+   - 任务统计
+   - 首个待执行任务
+   - 验证命令预览
+   - 自动执行停止条件
+5. 用户未确认前，不要开始正式修改代码。
+6. 用户确认后，继续用 Gemini CLI 原生工具推进 backlog，直到完成、遇到硬阻塞，或需要用户补充关键信息。
+7. 如果用户给了开发文档但找不到项目仓库，或给了项目路径但找不到开发文档，必须停下来询问。
+8. Windows 上优先用安全的文件与 shell 操作；禁止危险删除、硬重置、强推和其他破坏性命令。
+"""

package/hosts/gemini/extension/gemini-extension.json

@@ -0,0 +1,13 @@
+{
+  "name": "helloloop",
+  "version": "0.2.0",
+  "description": "HelloLoop 的 Gemini CLI 原生扩展，用于按开发文档接续推进项目开发。",
+  "contextFileName": "GEMINI.md",
+  "excludeTools": [
+    "run_shell_command(rm -rf)",
+    "run_shell_command(git reset --hard)",
+    "run_shell_command(git push --force)",
+    "run_shell_command(FLUSHALL)",
+    "run_shell_command(FLUSHDB)"
+  ]
+}

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "helloloop",
-  "version": "0.1.1",
-  "description": "Standalone Codex plugin bundle for backlog-driven repository execution with Ralph Loop guards",
+  "version": "0.2.0",
+  "description": "面向 Codex CLI、Claude Code、Gemini CLI 的多宿主开发工作流插件",
+  "author": "HelloLoop",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/hellowind777/helloloop",
   "type": "module",
   "repository": {
     "type": "git",
@@ -14,9 +17,12 @@
     "helloloop": "bin/helloloop.js"
   },
   "files": [
+    ".claude-plugin",
     ".codex-plugin",
+    "LICENSE",
     "README.md",
     "bin",
+    "hosts",
     "package.json",
     "scripts",
     "skills",
@@ -24,7 +30,7 @@
     "templates"
   ],
   "scripts": {
-    "test": "node --test tests/cli_surface.test.mjs tests/install_script.test.mjs tests/process_shell.test.mjs tests/ralph_loop.test.mjs tests/plugin_bundle.test.mjs"
+    "test": "node --test tests/analyze_cli.test.mjs tests/cli_surface.test.mjs tests/install_script.test.mjs tests/process_shell.test.mjs tests/prompt_guardrails.test.mjs tests/ralph_loop.test.mjs tests/plugin_bundle.test.mjs"
   },
   "engines": {
     "node": ">=20"

package/skills/helloloop/SKILL.md

@@ -1,51 +1,79 @@
 ---
 name: helloloop
-description: Use when the user wants Codex to keep shipping repo work across turns, bootstrap HelloLoop, or inspect backlog-driven execution state through the pure official plugin bundle.
+description: 当用户希望 Codex 先分析仓库当前进度、生成确认单，再自动按 backlog 持续接续开发时使用。
 ---
 
 # HelloLoop
 
-Use this plugin when the task is continuous repository execution rather than a single chat-turn change.
+当任务目标不是单轮对话里改一点代码，而是要基于开发文档持续推进整个仓库时，使用这个插件。
 
-## Official Plugin Boundary
+## 强制入口规则
 
-- This bundle root is the official plugin surface for HelloLoop.
-- It ships standard Codex plugin metadata through `.codex-plugin/plugin.json` and a plugin skill through `skills/`.
-- This plugin is designed around explicit skill and CLI entrypoints.
+- 用户显式调用 `$helloloop` / `helloloop:helloloop` 时，默认必须优先执行 `npx helloloop` 或 `npx helloloop <PATH>`。
+- 不允许在对话里手工模拟 `HelloLoop` 的分析、确认单、backlog 编排和自动续跑流程来代替 CLI。
+- 只有在以下情况，才允许先停下来问用户而不是直接执行 CLI：
+  1. 用户既没有给路径，当前目录也无法判断项目仓库或开发文档
+  2. 用户给了开发文档，但无法定位目标项目仓库
+  3. 用户给了项目路径，但无法找到开发文档
+  4. 用户明确要求先只讲解、不执行
 
-## Setup
+## `$helloloop` 的默认执行映射
 
-1. Install with `npx helloloop install --codex-home <CODEX_HOME>` or use `scripts/install-home-plugin.ps1`.
-2. From the target repository, run `npx helloloop doctor --repo <repo-root>`.
-3. From the target repository, run `npx helloloop init --repo <repo-root>`.
+- 当前目录已经是目标项目仓库或开发文档目录 → 先执行 `npx helloloop`
+- 用户给了单一路径 → 先执行 `npx helloloop <PATH>`
+- 用户明确只想先看分析和确认单 → 执行 `npx helloloop --dry-run`
+- 用户明确要求跳过确认直接开始 → 执行 `npx helloloop -y`
 
-## Operating Model
+## 插件边界
 
-- `.helloloop/` is the default CLI and backlog state directory.
-- The installed plugin bundle keeps runtime files such as `src/`, `templates/`, `bin/`, `scripts/`, and `skills/`.
-- Source-only materials such as `docs/` and `tests/` stay in the development repository.
+- 当前 bundle 根目录就是 `HelloLoop` 的官方插件目录。
+- 插件元数据位于 `.codex-plugin/plugin.json`，执行逻辑位于 `skills/`、`bin/`、`scripts/`、`src/`、`templates/`。
+- 运行状态统一写入目标仓库根目录下的 `.helloloop/`。
 
-## Invocation
+## 使用前准备
 
-- In official Codex plugin mode, plugin skills are namespaced with `plugin_name:`.
-- For this plugin, the unambiguous skill name is `helloloop:helloloop`.
-- Explicitly naming the `helloloop` plugin should also bias Codex toward this skill.
-- Do not promise bare `$helloloop` is the official invocation form.
+1. 先通过 `npx helloloop install --codex-home <CODEX_HOME>` 或 `scripts/install-home-plugin.ps1` 安装插件。
+2. 打开目标项目仓库目录，或者打开开发文档所在目录。
+3. 运行 `npx helloloop` 或 `npx helloloop <PATH>`。
+4. 命中 `$helloloop` 后，优先按上面的默认执行映射直接调用 CLI。
+5. `HelloLoop` 会先自动分析，再输出执行确认单。
+6. 用户确认后，`HelloLoop` 才开始正式自动执行。
 
-## Primary Commands
+如果无法自动判断仓库路径或开发文档路径，就停下来提示用户补充；`--repo` 和 `--docs` 只作为显式覆盖选项使用。
 
-- `npx helloloop status --repo <repo-root>`
-- `npx helloloop next --repo <repo-root>`
-- `npx helloloop run-once --repo <repo-root>`
-- `npx helloloop run-loop --repo <repo-root>`
+## 工作模式
 
-## Reporting Rules
+- 代码是事实源，开发文档是目标源。
+- `HelloLoop` 会先分析当前真实进度，再生成或刷新 `.helloloop/backlog.json`。
+- 分析后会展示执行确认单，明确告知当前进度、待办任务、验证命令和执行边界。
+- 用户确认后，默认会持续执行到 backlog 清空或遇到硬阻塞。
+- 真正的代码分析与实现仍由本机 `codex` CLI 完成。
+- `$helloloop` 的职责是把用户请求路由到主 CLI 流程，而不是在对话里手工复刻一套平行流程。
 
-- State explicitly that the plugin runs in pure official plugin mode.
-- Keep Ralph Loop guardrails and repo verification intact.
+## 核心命令
 
-## Docs
+- `npx helloloop`
+- `npx helloloop <PATH>`
+- `npx helloloop --dry-run`
+- `npx helloloop -y`
 
-- Source repo main guide: `docs/README.md`
-- Source repo installation note: `docs/install.md`
-- Source repo official standard and runtime boundary: `docs/plugin-standard.md`
+## 手动控制命令
+
+- `npx helloloop status`
+- `npx helloloop next`
+- `npx helloloop run-once`
+- `npx helloloop run-loop --max-tasks <n>`
+- `npx helloloop doctor`
+- `npx helloloop init`
+
+## 调用方式
+
+- 在官方 Codex 插件模式下，明确的 skill 名称是 `helloloop:helloloop`。
+- 在对话里显式提到 `helloloop` 插件，也会帮助 Codex 更准确地命中这个 skill。
+
+## 参考文档
+
+- 主说明：`README.md`
+- 安装说明：`docs/install.md`
+- Bundle 说明：`docs/README.md`
+- 插件标准映射：`docs/plugin-standard.md`

package/src/analyze_confirmation.mjs

@@ -0,0 +1,128 @@
+import path from "node:path";
+
+import { analyzeExecution, summarizeBacklog } from "./backlog.mjs";
+import { loadPolicy, loadVerifyCommands } from "./config.mjs";
+
+function toDisplayPath(repoRoot, targetPath) {
+  const absolutePath = path.resolve(targetPath);
+  const relativePath = path.relative(repoRoot, absolutePath);
+  if (relativePath && !relativePath.startsWith("..") && !path.isAbsolute(relativePath)) {
+    return relativePath.replaceAll("\\", "/");
+  }
+  return absolutePath.replaceAll("\\", "/");
+}
+
+function formatList(items, fallback = "无") {
+  if (!Array.isArray(items) || !items.length) {
+    return [`- ${fallback}`];
+  }
+  return items.map((item) => `- ${item}`);
+}
+
+function formatTaskPreview(tasks) {
+  const preview = tasks
+    .filter((task) => ["pending", "in_progress"].includes(String(task.status || "pending")))
+    .slice(0, 5);
+
+  if (!preview.length) {
+    return ["- 当前没有待执行任务"];
+  }
+
+  return preview.map((task) => {
+    const parts = [
+      task.title,
+      `#${task.id}`,
+      task.priority || "P2",
+      `risk:${task.risk || "low"}`,
+    ];
+    return `- ${parts.join(" | ")}`;
+  });
+}
+
+function formatExecutionState(execution) {
+  const stateMap = {
+    ready: "可自动执行",
+    blocked_in_progress: "存在未收束任务",
+    blocked_failed: "存在失败或阻塞任务",
+    blocked_risk: "风险超过自动阈值",
+    blocked_dependencies: "依赖未满足",
+    done: "backlog 已完成",
+  };
+
+  return stateMap[execution.state] || execution.state;
+}
+
+function resolvePreviewVerifyCommands(context, execution) {
+  const taskCommands = Array.isArray(execution.task?.verify) && execution.task.verify.length
+    ? execution.task.verify
+    : [];
+  if (taskCommands.length) {
+    return taskCommands;
+  }
+  return loadVerifyCommands(context);
+}
+
+export function resolveAutoRunMaxTasks(backlog, options = {}) {
+  const explicitMaxTasks = Number(options.maxTasks);
+  if (Number.isFinite(explicitMaxTasks) && explicitMaxTasks > 0) {
+    return explicitMaxTasks;
+  }
+
+  const summary = summarizeBacklog(backlog);
+  const pendingTotal = summary.pending + summary.inProgress;
+  return Math.max(1, pendingTotal);
+}
+
+export function renderAnalyzeConfirmation(context, analysis, backlog, options = {}) {
+  const summary = summarizeBacklog(backlog);
+  const execution = analyzeExecution(backlog, options);
+  const policy = loadPolicy(context);
+  const verifyCommands = resolvePreviewVerifyCommands(context, execution);
+  const autoRunMaxTasks = resolveAutoRunMaxTasks(backlog, options);
+  const docsDisplay = analysis.requiredDocs.map((entry) => (
+    toDisplayPath(context.repoRoot, path.resolve(context.repoRoot, entry))
+  ));
+
+  return [
+    "执行确认单",
+    "============",
+    `目标仓库：${context.repoRoot.replaceAll("\\", "/")}`,
+    `开发文档：${docsDisplay.length ? docsDisplay.join("，") : "未识别"}`,
+    "",
+    "当前进度：",
+    `- ${analysis.summary.currentState}`,
+    "",
+    "已实现：",
+    ...formatList(analysis.summary.implemented, "暂无已实现摘要"),
+    "",
+    "待完成：",
+    ...formatList(analysis.summary.remaining, "暂无待完成摘要"),
+    "",
+    "任务统计：",
+    `- 总任务：${summary.total}`,
+    `- 已完成：${summary.done}`,
+    `- 待处理：${summary.pending}`,
+    `- 进行中：${summary.inProgress}`,
+    `- 阻塞：${summary.blocked}`,
+    `- 失败：${summary.failed}`,
+    "",
+    "执行判断：",
+    `- 当前状态：${formatExecutionState(execution)}`,
+    `- 优先动作：${analysis.summary.nextAction}`,
+    execution.task
+      ? `- 首个任务：${execution.task.title}`
+      : `- 首个任务：${execution.blockedTask?.title || "暂无"}`,
+    execution.blockedReason
+      ? `- 当前阻塞：${execution.blockedReason}`
+      : "- 当前阻塞：无",
+    "- 偏差修正：按 backlog 优先级执行；如果分析识别出偏差修正任务，会先收口再继续后续开发",
+    `- 自动推进：最多 ${autoRunMaxTasks} 个任务，直到 backlog 清空或遇到硬阻塞`,
+    `- 单任务重试：每种策略最多 ${policy.maxTaskAttempts} 次，共 ${policy.maxTaskStrategies} 轮策略`,
+    "",
+    "待执行任务预览：",
+    ...formatTaskPreview(backlog.tasks),
+    "",
+    "验证命令预览：",
+    ...formatList(verifyCommands, "未配置 verify.yaml，执行阶段将仅依赖任务自带验证"),
+  ].join("\n");
+}

package/src/analyze_prompt.mjs

@@ -0,0 +1,75 @@
+import { formatList } from "./common.mjs";
+import {
+  hasCustomProjectConstraints,
+  listMandatoryGuardrails,
+  resolveProjectConstraints,
+} from "./guardrails.mjs";
+
+function section(title, content) {
+  if (!content || !String(content).trim()) {
+    return "";
+  }
+  return `## ${title}\n${String(content).trim()}\n`;
+}
+
+function listSection(title, items) {
+  if (!Array.isArray(items) || !items.length) {
+    return "";
+  }
+  return section(title, formatList(items));
+}
+
+function renderDocPackets(docPackets) {
+  return docPackets.map((packet) => [
+    `### 文档：${packet.path}`,
+    packet.truncated ? "（已截断）" : "",
+    "",
+    packet.content,
+  ].filter(Boolean).join("\n")).join("\n\n");
+}
+
+export function buildAnalysisPrompt({
+  repoRoot,
+  docsEntries,
+  docPackets,
+  existingStateText = "",
+  existingBacklogText = "",
+  existingProjectConstraints = [],
+}) {
+  const mandatoryGuardrails = listMandatoryGuardrails();
+  const effectiveConstraints = resolveProjectConstraints(existingProjectConstraints);
+  const usingFallbackConstraints = !hasCustomProjectConstraints(existingProjectConstraints);
+
+  return [
+    "你要为一个本地代码仓库做“接续开发分析”。",
+    "目标不是直接改代码，而是判断当前已经做到哪里，并生成后续可执行 backlog。",
+    "",
+    "必须遵守以下原则：",
+    "1. 代码是事实源，开发文档是目标源。",
+    "2. 判断“已完成 / 部分完成 / 未完成”时，以仓库当前真实代码、测试、目录结构为准，不能盲信文档。",
+    "3. 生成的任务必须颗粒度足够，能直接进入开发，不允许输出“继续开发”这类空泛任务。",
+    "4. 只关注当前目标仓库，不要把其他仓库的任务混进来；如果文档覆盖多仓库，只提取当前仓库相关任务。",
+    "5. 如果某项工作依赖其他仓库或外部输入，允许输出 `blocked` 任务，但必须明确阻塞原因。",
+    "",
+    section("目标仓库", `- 路径：${repoRoot.replaceAll("\\", "/")}`),
+    section("开发文档入口", docsEntries.map((item) => `- ${item}`).join("\n")),
+    existingStateText ? section("已有状态摘要", existingStateText) : "",
+    listSection("内建安全底线", mandatoryGuardrails),
+    listSection(usingFallbackConstraints ? "默认工程约束（文档未明确时也必须遵守）" : "已有项目约束", effectiveConstraints),
+    existingBacklogText ? section("已有 backlog（供参考，可重组）", existingBacklogText) : "",
+    section("文档内容摘录", renderDocPackets(docPackets)),
+    section("输出要求", [
+      "1. 严格输出 JSON，不要带 Markdown 代码块。",
+      "2. `summary.currentState` 要清晰描述当前仓库真实进度。",
+      "3. `summary.implemented` 写已确认完成的关键能力。",
+      "4. `summary.remaining` 写尚未完成的关键缺口。",
+      "5. `summary.nextAction` 写最合理的下一步。",
+      "6. `tasks` 总数控制在 4 到 12 个之间，优先覆盖真正剩余工作。",
+      "7. 每个任务必须包含：id、title、status、priority、risk、goal、docs、paths、acceptance。",
+      "8. `status` 只能是 `done`、`pending`、`blocked`，不要输出 `in_progress` 或 `failed`。",
+      "9. `docs` 必须引用本次文档入口中的相关路径；`paths` 必须写当前仓库内的实际目录或文件模式。",
+      "10. `acceptance` 必须可验证，不要写空话。",
+      "11. `constraints` 只写从项目文档或现有项目配置中提炼出的项目特有约束；不要重复内建安全底线。",
+    ].join("\n")),
+  ].filter(Boolean).join("\n");
+}

package/src/analyzer.mjs

@@ -0,0 +1,208 @@
+import path from "node:path";
+
+import { summarizeBacklog, selectNextTask } from "./backlog.mjs";
+import { nowIso, writeJson, writeText, readTextIfExists } from "./common.mjs";
+import { loadPolicy, loadProjectConfig, scaffoldIfMissing, writeStateMarkdown, writeStatus } from "./config.mjs";
+import { createContext } from "./context.mjs";
+import { discoverWorkspace } from "./discovery.mjs";
+import { readDocumentPackets } from "./doc_loader.mjs";
+import { runCodexTask } from "./process.mjs";
+import { buildAnalysisPrompt } from "./analyze_prompt.mjs";
+
+function renderAnalysisState(context, backlog, analysis) {
+  const summary = summarizeBacklog(backlog);
+  const nextTask = selectNextTask(backlog);
+
+  return [
+    "## 当前状态",
+    `- backlog 文件：${path.relative(context.repoRoot, context.backlogFile).replaceAll("\\", "/")}`,
+    `- 总任务数：${summary.total}`,
+    `- 已完成：${summary.done}`,
+    `- 待处理：${summary.pending}`,
+    `- 进行中：${summary.inProgress}`,
+    `- 失败：${summary.failed}`,
+    `- 阻塞：${summary.blocked}`,
+    `- 当前任务：${nextTask ? nextTask.title : "无"}`,
+    `- 最近结果：${analysis.summary.currentState}`,
+    `- 下一建议：${analysis.summary.nextAction}`,
+  ].join("\n");
+}
+
+function sanitizeTask(task) {
+  return {
+    id: String(task.id || "").trim(),
+    title: String(task.title || "").trim(),
+    status: ["done", "blocked"].includes(String(task.status || "")) ? String(task.status) : "pending",
+    priority: ["P0", "P1", "P2", "P3"].includes(String(task.priority || "")) ? String(task.priority) : "P2",
+    risk: ["medium", "high", "critical"].includes(String(task.risk || "")) ? String(task.risk) : "low",
+    goal: String(task.goal || "").trim(),
+    docs: Array.isArray(task.docs) ? task.docs.map((item) => String(item || "").trim()).filter(Boolean) : [],
+    paths: Array.isArray(task.paths) ? task.paths.map((item) => String(item || "").trim()).filter(Boolean) : [],
+    acceptance: Array.isArray(task.acceptance) ? task.acceptance.map((item) => String(item || "").trim()).filter(Boolean) : [],
+    dependsOn: Array.isArray(task.dependsOn) ? task.dependsOn.map((item) => String(item || "").trim()).filter(Boolean) : [],
+    verify: Array.isArray(task.verify) ? task.verify.map((item) => String(item || "").trim()).filter(Boolean) : [],
+  };
+}
+
+function normalizeAnalysisPayload(payload, docsEntries) {
+  const tasks = Array.isArray(payload.tasks)
+    ? payload.tasks.map((task) => sanitizeTask(task)).filter((task) => (
+      task.id && task.title && task.goal && task.acceptance.length
+    ))
+    : [];
+
+  if (!tasks.length) {
+    throw new Error("Codex 分析结果无效：未生成可用任务。");
+  }
+
+  return {
+    project: String(payload.project || "").trim() || "helloloop-project",
+    summary: {
+      currentState: String(payload?.summary?.currentState || "").trim() || "已完成接续分析。",
+      implemented: Array.isArray(payload?.summary?.implemented) ? payload.summary.implemented.map((item) => String(item || "").trim()).filter(Boolean) : [],
+      remaining: Array.isArray(payload?.summary?.remaining) ? payload.summary.remaining.map((item) => String(item || "").trim()).filter(Boolean) : [],
+      nextAction: String(payload?.summary?.nextAction || "").trim() || "查看下一任务。",
+    },
+    constraints: Array.isArray(payload.constraints)
+      ? payload.constraints.map((item) => String(item || "").trim()).filter(Boolean)
+      : [],
+    tasks,
+    requiredDocs: docsEntries,
+  };
+}
+
+function buildAnalysisSummaryText(context, analysis, backlog) {
+  const summary = summarizeBacklog(backlog);
+  const nextTask = selectNextTask(backlog);
+
+  return [
+    "HelloLoop 已完成接续分析。",
+    `项目仓库：${context.repoRoot}`,
+    `开发文档：${analysis.requiredDocs.join(", ")}`,
+    "",
+    "当前进度：",
+    analysis.summary.currentState,
+    "",
+    `任务统计：done ${summary.done} / pending ${summary.pending} / blocked ${summary.blocked}`,
+    nextTask ? `下一任务：${nextTask.title}` : "下一任务：暂无可执行任务",
+    "",
+    "下一步建议：",
+    `- npx helloloop`,
+    `- npx helloloop --dry-run`,
+  ].join("\n");
+}
+
+export async function analyzeWorkspace(options = {}) {
+  const discovery = discoverWorkspace({
+    cwd: options.cwd,
+    inputPath: options.inputPath,
+    repoRoot: options.repoRoot,
+    docsPath: options.docsPath,
+    configDirName: options.configDirName,
+  });
+
+  if (!discovery.ok) {
+    return {
+      ok: false,
+      code: discovery.code,
+      summary: discovery.message,
+    };
+  }
+
+  const context = createContext({
+    repoRoot: discovery.repoRoot,
+    configDirName: options.configDirName,
+  });
+  scaffoldIfMissing(context);
+
+  const existingProjectConfig = loadProjectConfig(context);
+  const existingStateText = readTextIfExists(context.stateFile, "");
+  const existingBacklogText = readTextIfExists(context.backlogFile, "");
+  const docPackets = readDocumentPackets(context.repoRoot, discovery.docsEntries, {
+    maxCharsPerFile: 18000,
+    maxTotalChars: 90000,
+  });
+
+  const prompt = buildAnalysisPrompt({
+    repoRoot: context.repoRoot,
+    docsEntries: discovery.docsEntries,
+    docPackets,
+    existingStateText,
+    existingBacklogText,
+    existingProjectConstraints: existingProjectConfig.constraints,
+  });
+
+  const runDir = path.join(context.runsDir, `${nowIso().replaceAll(":", "-").replaceAll(".", "-")}-analysis`);
+  const policy = loadPolicy(context);
+  const schemaFile = path.join(context.templatesDir, "analysis-output.schema.json");
+  const codexResult = await runCodexTask({
+    context,
+    prompt,
+    runDir,
+    model: policy.codex.model,
+    executable: policy.codex.executable,
+    sandbox: policy.codex.sandbox,
+    dangerouslyBypassSandbox: policy.codex.dangerouslyBypassSandbox,
+    outputSchemaFile: schemaFile,
+    outputPrefix: "analysis",
+    jsonOutput: false,
+    skipGitRepoCheck: true,
+  });
+
+  if (!codexResult.ok) {
+    return {
+      ok: false,
+      code: "analysis_failed",
+      summary: codexResult.stderr || codexResult.stdout || "Codex 接续分析失败。",
+    };
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(codexResult.finalMessage);
+  } catch (error) {
+    return {
+      ok: false,
+      code: "invalid_analysis_json",
+      summary: `Codex 分析结果无法解析为 JSON：${String(error?.message || error || "")}`,
+    };
+  }
+
+  const analysis = normalizeAnalysisPayload(payload, discovery.docsEntries);
+  const backlog = {
+    version: 1,
+    project: analysis.project,
+    updatedAt: nowIso(),
+    tasks: analysis.tasks,
+  };
+
+  const projectConfig = {
+    requiredDocs: analysis.requiredDocs,
+    constraints: analysis.constraints.length ? analysis.constraints : existingProjectConfig.constraints,
+    planner: existingProjectConfig.planner,
+  };
+
+  writeJson(context.backlogFile, backlog);
+  writeJson(context.projectFile, projectConfig);
+  writeStateMarkdown(context, renderAnalysisState(context, backlog, analysis));
+  writeStatus(context, {
+    ok: true,
+    stage: "analyzed",
+    taskId: null,
+    taskTitle: "",
+    runDir,
+    summary: summarizeBacklog(backlog),
+    message: analysis.summary.currentState,
+  });
+  writeText(path.join(runDir, "analysis-summary.txt"), buildAnalysisSummaryText(context, analysis, backlog));
+
+  return {
+    ok: true,
+    code: "analyzed",
+    context,
+    runDir,
+    analysis,
+    backlog,
+    summary: buildAnalysisSummaryText(context, analysis, backlog),
+  };
+}