helloloop 0.2.1 → 0.6.1

package/src/completion_review.mjs

@@ -0,0 +1,243 @@
+import path from "node:path";
+
+import { formatList, tailText } from "./common.mjs";
+import { runEngineTask } from "./process.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 normalizeDocEntry(doc) {
+  return String(doc || "").trim().replaceAll("\\", "/");
+}
+
+function normalizeDocList(items) {
+  const result = [];
+  const seen = new Set();
+
+  for (const item of items || []) {
+    const normalized = normalizeDocEntry(item);
+    if (!normalized) {
+      continue;
+    }
+
+    const key = normalized.toLowerCase();
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    result.push(normalized);
+  }
+
+  return result;
+}
+
+function renderVerifyResultLines(verifyResult) {
+  if (!verifyResult?.results?.length) {
+    return [
+      "- 未执行额外验证命令",
+    ];
+  }
+
+  return verifyResult.results.map((item) => {
+    const stdoutTail = tailText(item.stdout, 6) || "无";
+    const stderrTail = tailText(item.stderr, 6) || "无";
+    return [
+      `- ${item.ok ? "通过" : "失败"}：${item.command}`,
+      `  stdout: ${stdoutTail}`,
+      `  stderr: ${stderrTail}`,
+    ].join("\n");
+  });
+}
+
+function buildTaskReviewPrompt({
+  task,
+  requiredDocs = [],
+  constraints = [],
+  repoStateText = "",
+  engineFinalMessage = "",
+  verifyResult = null,
+}) {
+  const allDocs = normalizeDocList([
+    ...requiredDocs,
+    ...(task.docs || []),
+  ]);
+
+  return [
+    "你要做的是“任务完成复核”，目标是判断当前任务是否真的已经完成。",
+    "不要相信执行代理口头说“已完成”；必须直接检查仓库当前代码、测试和产物。",
+    "如果只是做到一半、只改了部分文件、或者验收条件仍缺项，都不能判定为完成。",
+    "",
+    section("当前任务", [
+      `- 标题：${task.title}`,
+      `- 编号：${task.id}`,
+      `- 目标：${task.goal || "按文档完成当前工作包。"}`,
+      `- 风险：${task.risk || "low"}`,
+    ].join("\n")),
+    listSection("开发文档", allDocs),
+    listSection("涉及路径", task.paths || []),
+    listSection("验收条件", task.acceptance || []),
+    constraints.length ? listSection("项目约束", constraints) : "",
+    repoStateText ? section("当前仓库状态摘要", repoStateText) : "",
+    engineFinalMessage
+      ? section("执行代理最后输出", tailText(engineFinalMessage, 20))
+      : "",
+    section("验证结果", renderVerifyResultLines(verifyResult).join("\n")),
+    section("判定规则", [
+      "1. 只有当所有验收条件都有明确仓库证据支撑时，才能输出 `complete`。",
+      "2. 只要有任一验收条件未满足、证据不足、或只能部分成立，就输出 `incomplete`。",
+      "3. 只有外部权限、环境损坏、文档缺口、不可获得依赖等真正硬阻塞，才允许输出 `blocked`。",
+      "4. “代理提前停止”“只完成一部分”“建议下次继续”都属于 `incomplete`，不是 `blocked`。",
+      "5. 不要给泛泛建议，`missing` 和 `nextAction` 必须直接指出还差什么。",
+    ].join("\n")),
+    section("输出要求", [
+      "1. 严格输出 JSON，不要带 Markdown 代码块。",
+      "2. `verdict` 只能是 `complete`、`incomplete`、`blocked`。",
+      "3. `acceptanceChecks` 必须逐条覆盖本任务所有验收条件。",
+      "4. `acceptanceChecks[].status` 只能是 `met`、`not_met`、`uncertain`。",
+      "5. `acceptanceChecks[].evidence` 必须写具体证据或缺口，不能只写“已完成”。",
+      "6. 若 `verdict=complete`，则所有 `acceptanceChecks[].status` 必须都是 `met`，且 `missing` 为空。",
+      "7. 若 `verdict=blocked`，`blockerReason` 必须明确写出硬阻塞原因。",
+    ].join("\n")),
+  ].filter(Boolean).join("\n");
+}
+
+function normalizeAcceptanceCheck(check) {
+  return {
+    item: String(check?.item || "").trim(),
+    status: ["met", "not_met", "uncertain"].includes(String(check?.status || ""))
+      ? String(check.status)
+      : "uncertain",
+    evidence: String(check?.evidence || "").trim() || "未提供可用证据。",
+  };
+}
+
+function normalizeTaskReviewPayload(payload, task) {
+  const requestedAcceptance = Array.isArray(task?.acceptance)
+    ? task.acceptance.map((item) => String(item || "").trim()).filter(Boolean)
+    : [];
+  const receivedChecks = Array.isArray(payload?.acceptanceChecks)
+    ? payload.acceptanceChecks.map((item) => normalizeAcceptanceCheck(item)).filter((item) => item.item)
+    : [];
+
+  const normalizedChecks = requestedAcceptance.map((item) => {
+    const matched = receivedChecks.find((check) => check.item === item);
+    return matched || {
+      item,
+      status: "uncertain",
+      evidence: "复核结果未覆盖该验收条件。",
+    };
+  });
+
+  const missing = Array.isArray(payload?.missing)
+    ? payload.missing.map((item) => String(item || "").trim()).filter(Boolean)
+    : [];
+  const blockerReason = String(payload?.blockerReason || "").trim();
+  const requestedVerdict = ["complete", "incomplete", "blocked"].includes(String(payload?.verdict || ""))
+    ? String(payload.verdict)
+    : "incomplete";
+  const hasUnmetAcceptance = normalizedChecks.some((item) => item.status !== "met");
+  const verdict = requestedVerdict === "complete" && (hasUnmetAcceptance || missing.length)
+    ? "incomplete"
+    : requestedVerdict;
+
+  return {
+    verdict,
+    summary: String(payload?.summary || "").trim() || "任务完成复核已结束。",
+    acceptanceChecks: normalizedChecks,
+    missing,
+    blockerReason,
+    nextAction: String(payload?.nextAction || "").trim() || "请根据缺口继续完成当前任务。",
+    isComplete: verdict === "complete" && !hasUnmetAcceptance && missing.length === 0,
+  };
+}
+
+export function renderTaskReviewSummary(review) {
+  const acceptanceLines = review.acceptanceChecks.map((item) => (
+    `- ${item.status === "met" ? "已满足" : (item.status === "not_met" ? "未满足" : "待确认")}：${item.item}；${item.evidence}`
+  ));
+
+  return [
+    `任务复核结论：${review.summary}`,
+    ...acceptanceLines,
+    ...(review.missing.length
+      ? review.missing.map((item) => `- 剩余缺口：${item}`)
+      : []),
+    review.blockerReason ? `- 硬阻塞：${review.blockerReason}` : "",
+    `- 下一动作：${review.nextAction}`,
+  ].filter(Boolean).join("\n");
+}
+
+export async function reviewTaskCompletion({
+  engine,
+  context,
+  task,
+  requiredDocs = [],
+  constraints = [],
+  repoStateText = "",
+  engineFinalMessage = "",
+  verifyResult = null,
+  runDir,
+  policy = {},
+}) {
+  const prompt = buildTaskReviewPrompt({
+    task,
+    requiredDocs,
+    constraints,
+    repoStateText,
+    engineFinalMessage,
+    verifyResult,
+  });
+  const schemaFile = path.join(context.templatesDir, "task-review-output.schema.json");
+  const reviewResult = await runEngineTask({
+    engine,
+    context,
+    prompt,
+    runDir,
+    policy,
+    executionMode: "analyze",
+    outputSchemaFile: schemaFile,
+    outputPrefix: `${engine}-task-review`,
+    skipGitRepoCheck: true,
+  });
+
+  if (!reviewResult.ok) {
+    return {
+      ok: false,
+      code: "task_review_failed",
+      summary: reviewResult.stderr || reviewResult.stdout || "任务完成复核失败。",
+      raw: reviewResult,
+    };
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(reviewResult.finalMessage);
+  } catch (error) {
+    return {
+      ok: false,
+      code: "invalid_task_review_json",
+      summary: `任务完成复核结果无法解析为 JSON：${String(error?.message || error || "")}`,
+      raw: reviewResult,
+    };
+  }
+
+  const review = normalizeTaskReviewPayload(payload, task);
+  return {
+    ok: true,
+    code: "task_reviewed",
+    review,
+    summary: renderTaskReviewSummary(review),
+    raw: reviewResult,
+  };
+}

package/src/config.mjs

@@ -15,8 +15,21 @@ const defaultPolicy = {
   maxLoopTasks: 4,
   maxTaskAttempts: 2,
   maxTaskStrategies: 4,
+  maxReanalysisPasses: 3,
   stopOnFailure: false,
   stopOnHighRisk: true,
+  runtimeRecovery: {
+    enabled: true,
+    allowEngineSwitch: false,
+    heartbeatIntervalSeconds: 60,
+    stallWarningSeconds: 900,
+    maxIdleSeconds: 2700,
+    killGraceSeconds: 10,
+    maxPhaseRecoveries: 4,
+    retryDelaysSeconds: [120, 300, 900, 1800],
+    retryOnUnknownFailure: true,
+    maxUnknownRecoveries: 1,
+  },
   codex: {
     model: "",
     executable: "",
@@ -24,6 +37,20 @@ const defaultPolicy = {
     dangerouslyBypassSandbox: false,
     jsonOutput: true,
   },
+  claude: {
+    model: "",
+    executable: "",
+    permissionMode: "bypassPermissions",
+    analysisPermissionMode: "plan",
+    outputFormat: "text",
+  },
+  gemini: {
+    model: "",
+    executable: "",
+    approvalMode: "yolo",
+    analysisApprovalMode: "plan",
+    outputFormat: "text",
+  },
 };
 
 const defaultPlanner = {
@@ -46,6 +73,21 @@ export function loadPolicy(context) {
     ...defaultPolicy.codex,
     ...(policy.codex || {}),
   };
+  policy.claude = {
+    ...defaultPolicy.claude,
+    ...(policy.claude || {}),
+  };
+  policy.gemini = {
+    ...defaultPolicy.gemini,
+    ...(policy.gemini || {}),
+  };
+  policy.runtimeRecovery = {
+    ...defaultPolicy.runtimeRecovery,
+    ...(policy.runtimeRecovery || {}),
+    retryDelaysSeconds: Array.isArray(policy?.runtimeRecovery?.retryDelaysSeconds)
+      ? policy.runtimeRecovery.retryDelaysSeconds
+      : defaultPolicy.runtimeRecovery.retryDelaysSeconds,
+  };
   return policy;
 }
 
@@ -54,6 +96,8 @@ export function loadProjectConfig(context) {
     return {
       requiredDocs: [],
       constraints: [],
+      defaultEngine: "",
+      lastSelectedEngine: "",
       planner: defaultPlanner,
     };
   }
@@ -62,6 +106,8 @@ export function loadProjectConfig(context) {
   return {
     requiredDocs: Array.isArray(config.requiredDocs) ? config.requiredDocs : [],
     constraints: Array.isArray(config.constraints) ? config.constraints : [],
+    defaultEngine: typeof config.defaultEngine === "string" ? config.defaultEngine : "",
+    lastSelectedEngine: typeof config.lastSelectedEngine === "string" ? config.lastSelectedEngine : "",
     planner: {
       ...defaultPlanner,
       ...(config.planner || {}),
@@ -87,6 +133,10 @@ export function saveBacklog(context, backlog) {
   });
 }
 
+export function saveProjectConfig(context, config) {
+  writeJson(context.projectFile, config);
+}
+
 export function loadVerifyCommands(context) {
   const raw = readTextIfExists(context.repoVerifyFile, "");
   return raw

package/src/discovery.mjs

@@ -8,25 +8,130 @@ import {
   normalizeForRepo,
   pathExists,
   resolveAbsolute,
+  uniquePaths,
 } from "./discovery_paths.mjs";
 import {
   inferDocsForRepo,
   inferRepoFromDocs,
+  inspectWorkspaceDirectory,
   renderMissingDocsMessage,
   renderMissingRepoMessage,
 } from "./discovery_inference.mjs";
 
 export { findRepoRootFromPath } from "./discovery_paths.mjs";
 
+const CONFIDENCE_LABELS = {
+  high: "高",
+  medium: "中",
+  low: "低",
+};
+
+const REPO_SOURCE_META = {
+  explicit_flag: { label: "命令参数", confidence: "high" },
+  explicit_input: { label: "命令附带路径", confidence: "high" },
+  new_repo_input: { label: "命令附带路径", confidence: "high" },
+  interactive: { label: "交互确认", confidence: "high" },
+  interactive_new_repo: { label: "交互确认", confidence: "high" },
+  cwd_repo: { label: "当前目录", confidence: "medium" },
+  workspace_single_repo: { label: "工作区唯一候选项目", confidence: "medium" },
+  docs_ancestor: { label: "文档同树回溯", confidence: "medium" },
+  doc_path_hint: { label: "文档中的路径线索", confidence: "medium" },
+  doc_repo_name_hint: { label: "文档中的仓库名线索", confidence: "low" },
+};
+
+const DOCS_SOURCE_META = {
+  explicit_flag: { label: "命令参数", confidence: "high" },
+  explicit_input: { label: "命令附带路径", confidence: "high" },
+  interactive: { label: "交互确认", confidence: "high" },
+  cwd_docs: { label: "当前目录", confidence: "medium" },
+  workspace_single_doc: { label: "工作区唯一文档候选", confidence: "medium" },
+  existing_state: { label: "已有 .helloloop 配置", confidence: "medium" },
+  repo_docs: { label: "仓库 docs 目录", confidence: "medium" },
+};
+
+function pushBasis(basis, message) {
+  if (message && !basis.includes(message)) {
+    basis.push(message);
+  }
+}
+
+function repoSourceFromSelection(selectionSource, allowNewRepoRoot, repoRoot) {
+  if (selectionSource === "flag") {
+    return allowNewRepoRoot && repoRoot && !pathExists(repoRoot) ? "new_repo_input" : "explicit_flag";
+  }
+  if (selectionSource === "positional") {
+    return allowNewRepoRoot && repoRoot && !pathExists(repoRoot) ? "new_repo_input" : "explicit_input";
+  }
+  if (selectionSource === "interactive_new_repo") {
+    return "interactive_new_repo";
+  }
+  if (selectionSource === "interactive") {
+    return "interactive";
+  }
+  if (selectionSource === "workspace_single_repo") {
+    return "workspace_single_repo";
+  }
+  return "";
+}
+
+function docsSourceFromSelection(selectionSource) {
+  if (selectionSource === "flag") {
+    return "explicit_flag";
+  }
+  if (selectionSource === "positional") {
+    return "explicit_input";
+  }
+  if (selectionSource === "interactive") {
+    return "interactive";
+  }
+  if (selectionSource === "workspace_single_doc") {
+    return "workspace_single_doc";
+  }
+  return "";
+}
+
+function createResolution(kind, payload) {
+  const meta = kind === "repo" ? REPO_SOURCE_META : DOCS_SOURCE_META;
+  const selected = meta[payload.source] || { label: "自动判断", confidence: "medium" };
+  return {
+    ...payload,
+    sourceLabel: selected.label,
+    confidence: selected.confidence,
+    confidenceLabel: CONFIDENCE_LABELS[selected.confidence] || "中",
+    basis: Array.isArray(payload.basis) ? payload.basis.filter(Boolean) : [],
+  };
+}
+
+function createRepoResolution(repoRoot, source, basis) {
+  return createResolution("repo", {
+    source,
+    path: repoRoot,
+    exists: pathExists(repoRoot),
+    basis,
+  });
+}
+
+function createDocsResolution(docsEntries, source, basis) {
+  return createResolution("docs", {
+    source,
+    entries: docsEntries,
+    basis,
+  });
+}
+
 export function discoverWorkspace(options = {}) {
   const cwd = path.resolve(options.cwd || process.cwd());
   const configDirName = options.configDirName || ".helloloop";
+  const allowNewRepoRoot = Boolean(options.allowNewRepoRoot);
+  const selectionSources = options.selectionSources || {};
   const explicitRepoRoot = options.repoRoot ? resolveAbsolute(options.repoRoot, cwd) : "";
   const explicitDocsPath = options.docsPath ? resolveAbsolute(options.docsPath, cwd) : "";
   const explicitInputPath = options.inputPath ? resolveAbsolute(options.inputPath, cwd) : "";
 
   if (explicitRepoRoot && !pathExists(explicitRepoRoot)) {
-    return { ok: false, code: "missing_repo_path", message: `项目路径不存在：${explicitRepoRoot}` };
+    if (!allowNewRepoRoot) {
+      return { ok: false, code: "missing_repo_path", message: `项目路径不存在：${explicitRepoRoot}` };
+    }
   }
   if (explicitDocsPath && !pathExists(explicitDocsPath)) {
     return { ok: false, code: "missing_docs_path", message: `开发文档路径不存在：${explicitDocsPath}` };
@@ -36,6 +141,39 @@ export function discoverWorkspace(options = {}) {
   let docsEntries = explicitDocsPath ? [explicitDocsPath] : [];
   let docCandidates = [];
   let repoCandidates = [];
+  let workspaceRoot = "";
+  let docsDerivedFromWorkspace = false;
+  let repoSource = repoSourceFromSelection(selectionSources.repo, allowNewRepoRoot, explicitRepoRoot);
+  let docsSource = docsSourceFromSelection(selectionSources.docs);
+  const repoBasis = [];
+  const docsBasis = [];
+
+  if (explicitRepoRoot && !repoSource) {
+    repoSource = allowNewRepoRoot && !pathExists(explicitRepoRoot) ? "new_repo_input" : "explicit_input";
+  }
+  if (explicitDocsPath && !docsSource) {
+    docsSource = "explicit_input";
+  }
+
+  if (repoSource === "explicit_flag") {
+    pushBasis(repoBasis, "目标项目来自命令参数 `--repo`。");
+  } else if (repoSource === "explicit_input") {
+    pushBasis(repoBasis, "目标项目来自命令中显式提供的路径。");
+  } else if (repoSource === "new_repo_input") {
+    pushBasis(repoBasis, "目标项目来自显式提供的项目路径；该目录当前不存在，将按新项目创建。");
+  } else if (repoSource === "interactive_new_repo") {
+    pushBasis(repoBasis, "目标项目由用户在确认流程中指定；该目录当前不存在，将按新项目创建。");
+  } else if (repoSource === "interactive") {
+    pushBasis(repoBasis, "目标项目由用户在确认流程中手动指定。");
+  }
+
+  if (docsSource === "explicit_flag") {
+    pushBasis(docsBasis, "开发文档来自命令参数 `--docs`。");
+  } else if (docsSource === "explicit_input") {
+    pushBasis(docsBasis, "开发文档来自命令中显式提供的路径。");
+  } else if (docsSource === "interactive") {
+    pushBasis(docsBasis, "开发文档由用户在确认流程中手动指定。");
+  }
 
   if (!repoRoot && !docsEntries.length) {
     const classified = classifyExplicitPath(explicitInputPath);
@@ -44,9 +182,16 @@ export function discoverWorkspace(options = {}) {
     }
     if (classified.kind === "docs") {
       docsEntries = [classified.absolutePath];
+      docsSource = "explicit_input";
+      pushBasis(docsBasis, "开发文档来自命令中传入的单一路径。");
     }
     if (classified.kind === "repo") {
       repoRoot = classified.absolutePath;
+      repoSource = "explicit_input";
+      pushBasis(repoBasis, "目标项目来自命令中传入的单一路径。");
+    }
+    if (classified.kind === "workspace" || classified.kind === "directory") {
+      workspaceRoot = classified.absolutePath;
     }
   }
 
@@ -54,17 +199,75 @@ export function discoverWorkspace(options = {}) {
     const cwdRepoRoot = findRepoRootFromPath(cwd);
     if (cwdRepoRoot) {
       repoRoot = cwdRepoRoot;
-    } else if (classifyExplicitPath(cwd).kind === "docs") {
-      docsEntries = [cwd];
-    } else if (looksLikeProjectRoot(cwd)) {
-      repoRoot = cwd;
+      repoSource = "cwd_repo";
+      pushBasis(repoBasis, "当前终端目录已经位于一个项目仓库内。");
+    } else {
+      const cwdClassified = classifyExplicitPath(cwd);
+      if (cwdClassified.kind === "docs") {
+        docsEntries = [cwdClassified.absolutePath];
+        docsSource = "cwd_docs";
+        pushBasis(docsBasis, "当前终端目录本身就是开发文档目录或文件。");
+      } else if (cwdClassified.kind === "repo") {
+        repoRoot = cwdClassified.absolutePath;
+        repoSource = "cwd_repo";
+        pushBasis(repoBasis, "当前终端目录本身就是项目仓库。");
+      } else if (cwdClassified.kind === "workspace" || cwdClassified.kind === "directory") {
+        workspaceRoot = cwdClassified.absolutePath;
+      } else if (looksLikeProjectRoot(cwd)) {
+        repoRoot = cwd;
+        repoSource = "cwd_repo";
+        pushBasis(repoBasis, "当前终端目录具备项目仓库特征。");
+      }
+    }
+  }
+
+  if (!repoRoot && !docsEntries.length && workspaceRoot) {
+    const workspace = inspectWorkspaceDirectory(workspaceRoot);
+    docCandidates = workspace.docCandidates;
+    repoCandidates = workspace.repoCandidates;
+
+    if (workspace.docsEntries.length === 1) {
+      docsEntries = workspace.docsEntries;
+      docsDerivedFromWorkspace = true;
+      docsSource = "workspace_single_doc";
+      pushBasis(docsBasis, "工作区扫描后只发现一个顶层开发文档入口。");
+    }
+
+    if (workspace.repoCandidates.length === 1) {
+      repoRoot = workspace.repoCandidates[0];
+      repoSource = "workspace_single_repo";
+      pushBasis(repoBasis, "工作区扫描后只发现一个顶层项目候选目录。");
     }
   }
 
   if (!repoRoot && docsEntries.length) {
+    if (docsDerivedFromWorkspace && repoCandidates.length > 1) {
+      return {
+        ok: false,
+        code: "missing_repo",
+        message: renderMissingRepoMessage(docsEntries, repoCandidates),
+        docsEntries,
+        docCandidates,
+        repoCandidates,
+        workspaceRoot,
+      };
+    }
+
     const inferred = inferRepoFromDocs(docsEntries, cwd);
     repoRoot = inferred.repoRoot;
-    repoCandidates = inferred.candidates;
+    repoCandidates = uniquePaths([...repoCandidates, ...inferred.candidates]);
+    if (repoRoot) {
+      if (inferred.source === "ancestor") {
+        repoSource = "docs_ancestor";
+        pushBasis(repoBasis, "开发文档位于该仓库目录树内，已回溯到真实项目根目录。");
+      } else if (inferred.source === "doc_path_hint") {
+        repoSource = "doc_path_hint";
+        pushBasis(repoBasis, "开发文档内容中出现了指向该仓库的实际路径线索。");
+      } else if (inferred.source === "doc_repo_name_hint") {
+        repoSource = "doc_repo_name_hint";
+        pushBasis(repoBasis, "开发文档内容中出现了与该仓库名称一致的线索。");
+      }
+    }
   }
 
   if (!repoRoot) {
@@ -72,16 +275,35 @@ export function discoverWorkspace(options = {}) {
       ok: false,
       code: "missing_repo",
       message: renderMissingRepoMessage(docsEntries, repoCandidates),
+      docsEntries,
+      docCandidates,
+      repoCandidates,
+      workspaceRoot,
     };
   }
 
-  repoRoot = findRepoRootFromPath(repoRoot) || repoRoot;
+  const normalizedRepoRoot = findRepoRootFromPath(repoRoot) || repoRoot;
+  if (normalizedRepoRoot !== repoRoot) {
+    pushBasis(repoBasis, "已自动回溯到项目仓库根目录。");
+  }
+  repoRoot = normalizedRepoRoot;
   docsEntries = docsEntries.map((entry) => normalizeForRepo(repoRoot, entry));
 
   if (!docsEntries.length) {
     const inferred = inferDocsForRepo(repoRoot, cwd, configDirName);
     docsEntries = inferred.docsEntries;
     docCandidates = inferred.candidates;
+    if (docsEntries.length) {
+      docsSource = inferred.source || docsSource;
+      if (inferred.source === "existing_state") {
+        pushBasis(docsBasis, "已复用 `.helloloop/project.json` 中记录的 requiredDocs。");
+      } else if (inferred.source === "cwd") {
+        docsSource = "cwd_docs";
+        pushBasis(docsBasis, "当前终端目录本身就是开发文档目录或文件。");
+      } else if (inferred.source === "repo_docs") {
+        pushBasis(docsBasis, "已使用目标仓库中的 `docs/` 目录作为默认开发文档入口。");
+      }
+    }
   }
 
   if (!docsEntries.length) {
@@ -89,8 +311,12 @@ export function discoverWorkspace(options = {}) {
       ok: false,
       code: "missing_docs",
       repoRoot,
-      message: renderMissingDocsMessage(repoRoot),
+      message: renderMissingDocsMessage(repoRoot, docCandidates),
       candidates: docCandidates,
+      docsEntries,
+      docCandidates,
+      repoCandidates,
+      workspaceRoot,
     };
   }
 
@@ -100,7 +326,11 @@ export function discoverWorkspace(options = {}) {
       ok: false,
       code: "invalid_docs",
       repoRoot,
-      message: renderMissingDocsMessage(repoRoot),
+      message: renderMissingDocsMessage(repoRoot, docCandidates),
+      docsEntries,
+      docCandidates,
+      repoCandidates,
+      workspaceRoot,
     };
   }
 
@@ -109,6 +339,10 @@ export function discoverWorkspace(options = {}) {
     repoRoot,
     docsEntries,
     resolvedDocs,
+    resolution: {
+      repo: createRepoResolution(repoRoot, repoSource || "cwd_repo", repoBasis),
+      docs: createDocsResolution(docsEntries, docsSource || "repo_docs", docsBasis),
+    },
   };
 }