coding-agent-harness 1.0.1 → 1.0.4

package/references/walkthrough-closeout.md

@@ -35,8 +35,8 @@
 - 本轮有没有发现 reference / workflow / checker 不够用或有误：[有/无，写一句理由]
 - 有没有反复出现、跨页面/跨模块/跨阶段的共性问题：[有/无，写一句理由]
 - 有没有下次 agent 也可能重复踩的坑：[有/无，写一句理由]
-- Lessons 结果：[checked-created: L-YYYY-MM-DD-NNN / checked-none: 一句话原因]
-- Lessons Detail Doc：[如 checked-created，填 `docs/01-GOVERNANCE/lessons/...md`；否则写"无"]
+- Lessons 结果：[checked-created: L-YYYY-MM-DD-NNN / queued-promotion: LC-YYYYMMDD-NNN / checked-candidate: LC-YYYYMMDD-NNN / checked-none: 一句话原因]
+- Lessons Detail Doc：[如 checked-created，填 `docs/01-GOVERNANCE/lessons/...md`；如 queued/checked-candidate，填 `lesson_candidates.md` 和任务本地 `lessons/LC-...md`；否则写"无"]
 
 ## 相关文件
 - Task Plan: [路径]
@@ -106,22 +106,23 @@ docs/10-WALKTHROUGH/Closeout-SSoT.md
 
 如果任何一条答案是“有”：
 
-1. 完整读一遍 `docs/01-GOVERNANCE/Lessons-SSoT.md`
+1. 查找任务本地 `lesson_candidates.md`、任务本地 `lessons/LC-*.md` 和 `docs/01-GOVERNANCE/lessons/*.md`
 2. 按 `references/lessons-governance.md` 中的规则处理冲突
-3. 在 `docs/01-GOVERNANCE/lessons/` 下写入详细建议（使用 `templates/lessons/` 下的对应模板）
-4. 更新 Lessons SSoT 表，`Detail Doc` 必须指向刚写的详情文档
-5. 在 Closeout SSoT 和 Harness Ledger 中记录 `checked-created: L-YYYY-MM-DD-NNN`
+3. 先在任务目录 `lesson_candidates.md` 中登记候选；候选进入 `needs-promotion` 时同步写任务本地 `lessons/LC-*.md` 详情文件并在 `Detail Artifact` 链接
+4. 人工确认后，如需沉淀，使用 maintenance CLI 写入 `docs/01-GOVERNANCE/lessons/` promoted 详情文档
+5. 在 Closeout SSoT 和 Harness Ledger 中记录 `queued-promotion: LC-...` 或 `checked-created: L-YYYY-MM-DD-NNN`
 
 如果所有答案都是“没有”，不能静默跳过；在 Closeout SSoT 和 Harness Ledger 中记录
+新任务在 `lesson_candidates.md` 中写 `no-candidate-accepted` 和 No-Candidate Reason；旧任务可记录
 `checked-none: <一句话原因>`。
 
 ## Harness Ledger 回写
 
-写完 Walkthrough、更新 Feature/Regression SSoT，并完成 Lessons 检查后，Agent 必须更新
-`docs/Harness-Ledger.md` 和 `docs/10-WALKTHROUGH/Closeout-SSoT.md`：
+写完 Walkthrough、更新 Regression SSoT 或其他本轮实际触达的非任务生命周期 SSoT，并完成 Lessons 检查后，Agent 必须更新
+`docs/10-WALKTHROUGH/Closeout-SSoT.md`；任务生命周期总账由 CLI 重新生成 `docs/Harness-Ledger.md`：
 
 1. 为本轮任务追加或更新对应 `HL-*` 条目
-2. 记录 Task Plan、Feature SSoT、Regression SSoT、Review Report、Walkthrough、Lessons Check 的结果
+2. 记录 Task Plan、Regression SSoT、Review Report、Walkthrough、Lessons Check 的结果
 3. 列出本轮触碰的 harness 文档
 4. 如有未完成项，使用 `missing` 或 `skipped-with-reason` 并写明 residual
 

package/scripts/check-harness.mjs

@@ -2,6 +2,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { checkModuleParallelStructure } from "./lib/check-module-parallel.mjs";
 
 const targetRoot = path.resolve(process.argv[2] || process.cwd());
 const requireGlobalModuleSync = process.env.HARNESS_REQUIRE_GLOBAL_MODULE_SYNC === "1";
@@ -23,7 +24,6 @@ const requiredFiles = [
   "docs/10-WALKTHROUGH/Closeout-SSoT.md",
   "docs/05-TEST-QA/Regression-SSoT.md",
   "docs/05-TEST-QA/Cadence-Ledger.md",
-  "docs/01-GOVERNANCE/Lessons-SSoT.md",
 ];
 
 const legacyPlanningFiles = [
@@ -41,7 +41,6 @@ const agAgentsRefs = [
   "adversarial-review-standard.md",
   "review-routing-standard.md",
   "walkthrough-standard.md",
-  "Lessons-SSoT.md",
   "harness-ledger-standard.md",
   "Closeout-SSoT.md",
 ];
@@ -63,6 +62,8 @@ const allowedWalkthroughSkip =
   /walkthrough skipped-with-reason:\s*(docs-only|no-runtime|superseded|historical-backfill|owner-deferred)/i;
 const lessonsCreatedPattern = /checked-created:\s*(L-\d{4}-\d{2}-\d{2}-\d{3}|L-\d+)/i;
 const lessonsNonePattern = /checked-none:\s*\S+/i;
+const lessonsCandidatePattern = /checked-candidate:\s*(LC-[A-Za-z0-9-]+)/i;
+const lessonsQueuedPromotionPattern = /queued-promotion:\s*(LC-[A-Za-z0-9-]+)/i;
 
 const failures = [];
 const warnings = [];
@@ -107,7 +108,18 @@ function checkRequiredFiles() {
 
 function checkPlanningStructure() {
   if (exists("docs/09-PLANNING/Module-Registry.md")) {
-    checkModuleParallelStructure();
+    checkModuleParallelStructure({
+      exists,
+      fail,
+      filePath,
+      markdownTable,
+      read,
+      rel,
+      requireFile,
+      requireGlobalModuleSync,
+      targetRoot,
+      warn,
+    });
     return;
   }
   for (const legacyFile of legacyPlanningFiles) {
@@ -115,239 +127,6 @@ function checkPlanningStructure() {
   }
 }
 
-function stripMarkdownCode(value) {
-  return String(value || "").replace(/`/g, "").trim();
-}
-
-function modulePromptBlock(content, key) {
-  const heading = `## Module: ${key}`;
-  const start = content.indexOf(heading);
-  if (start < 0) return "";
-  const rest = content.slice(start + heading.length);
-  const next = rest.search(/\n## Module: /);
-  return next >= 0 ? rest.slice(0, next) : rest;
-}
-
-function checkModuleParallelStructure() {
-  if (!exists("docs/09-PLANNING/Module-Registry.md")) return;
-
-  requireFile("docs/09-PLANNING/MODULES/Session-Prompt-Pack.md");
-  const hasPromptPack = exists("docs/09-PLANNING/MODULES/Session-Prompt-Pack.md");
-  for (const templateFile of [
-    "docs/09-PLANNING/MODULES/_task-template/task_plan.md",
-    "docs/09-PLANNING/MODULES/_task-template/progress.md",
-    "docs/09-PLANNING/MODULES/_task-template/findings.md",
-    "docs/09-PLANNING/MODULES/_task-template/review.md",
-  ]) {
-    requireFile(templateFile);
-  }
-
-  const registryContent = read("docs/09-PLANNING/Module-Registry.md");
-  for (const term of ["PREFIX", "Current Step", "Status", "Write Scope"]) {
-    if (!registryContent.includes(term)) {
-      fail(`docs/09-PLANNING/Module-Registry.md missing registry column or section: ${term}`);
-    }
-  }
-
-  const registryRows = markdownTable(registryContent)
-    .filter((cells) => cells.length >= 6)
-    .filter((cells) => /^(_shared|[a-z][a-z0-9-]*)$/.test(cells[0] || "") && /^[A-Z]{2,5}$/.test(cells[2] || ""));
-
-  if (registryRows.length === 0) {
-    fail("docs/09-PLANNING/Module-Registry.md has no active module rows");
-  }
-
-  const promptPack = hasPromptPack ? read("docs/09-PLANNING/MODULES/Session-Prompt-Pack.md") : "";
-  if (hasPromptPack && !/Subagent Worker Invariant|worker[\s\S]{0,120}worktree[\s\S]{0,120}commit SHA/i.test(promptPack)) {
-    fail("docs/09-PLANNING/MODULES/Session-Prompt-Pack.md missing subagent worker worktree/commit handoff rule");
-  }
-  for (const cells of registryRows) {
-    const [key, , prefix, branch, currentStep, status] = cells;
-    requireFile(`docs/09-PLANNING/MODULES/${key}/module_plan.md`);
-    if (!/^(planned|in-progress|paused|completed)$/.test(status)) {
-      fail(`docs/09-PLANNING/Module-Registry.md row ${key} has invalid status: ${status}`);
-    }
-    if (currentStep !== `${prefix}-00` && !currentStep.startsWith(`${prefix}-`)) {
-      fail(`docs/09-PLANNING/Module-Registry.md row ${key} current step does not match prefix ${prefix}: ${currentStep}`);
-    }
-    const branchName = stripMarkdownCode(branch);
-    if (!branchName.startsWith("codex/")) {
-      fail(`docs/09-PLANNING/Module-Registry.md row ${key} branch must use codex/ prefix: ${branch}`);
-    }
-
-    const block = modulePromptBlock(promptPack, key);
-    if (!block) {
-      if (!exists(`docs/09-PLANNING/MODULES/${key}/session_prompt.md`)) {
-        fail(`missing module session prompt for ${key}`);
-      }
-      continue;
-    }
-    for (const term of [
-      "Current Step",
-      branchName,
-      "Preflight:",
-      "Before code edits:",
-      "Write scope:",
-      "Forbidden without coordination:",
-      "Shared Coordination:",
-      "Verification:",
-      "Closeout:",
-      "Stop conditions:",
-    ]) {
-      if (!block.includes(term)) {
-        fail(`module session prompt for ${key} missing required term: ${term}`);
-      }
-    }
-  }
-  checkModuleTaskSsotIndex(registryRows);
-}
-
-function checkModuleTaskSsotIndex(registryRows) {
-  const registryByModule = new Map(registryRows.map((cells) => [cells[0], cells]));
-  const ledgerContent = exists("docs/Harness-Ledger.md") ? read("docs/Harness-Ledger.md") : "";
-  const taskPlans = listModuleTaskPlans();
-
-  for (const taskPlanPath of taskPlans) {
-    const parsed = parseModuleTaskPath(taskPlanPath);
-    if (!parsed) continue;
-    const { moduleKey, taskDir } = parsed;
-    const modulePlanPath = `docs/09-PLANNING/MODULES/${moduleKey}/module_plan.md`;
-    if (!exists(modulePlanPath)) continue;
-
-    const taskPlan = read(taskPlanPath);
-    const taskProgress = readTaskProgress(taskPlanPath);
-    const taskProgressStatus = readTaskProgressStatus(taskPlanPath);
-    const taskIsActive = isActiveModuleTaskStatus(taskProgressStatus);
-    const stepId = extractStepId(taskPlan, taskDir);
-    if (!stepId) {
-      if (taskIsActive) {
-        fail(`${taskPlanPath} does not expose a Step ID and task directory does not start with <PREFIX-NN>`);
-      }
-      continue;
-    }
-
-    const modulePlan = read(modulePlanPath);
-    const moduleRelativeTaskPlan = `TASKS/${taskDir}/task_plan.md`;
-    if (!modulePlan.includes(stepId) || !modulePlan.includes(moduleRelativeTaskPlan)) {
-      fail(`${modulePlanPath} does not index ${stepId} task plan ${moduleRelativeTaskPlan}`);
-    }
-
-    if (!taskIsActive) continue;
-
-    const registryRow = registryByModule.get(moduleKey);
-    const reviewPath = taskPlanPath.replace(/task_plan\.md$/, "review.md");
-    const registrySynced = Boolean(registryRow && registryRow[4] === stepId);
-    const ledgerSynced = ledgerContent.includes(taskPlanPath) && (!exists(reviewPath) || ledgerContent.includes(reviewPath));
-    if (registrySynced && ledgerSynced) continue;
-
-    if (requireGlobalModuleSync) {
-      if (!registryRow) {
-        fail(`docs/09-PLANNING/Module-Registry.md does not include active module ${moduleKey} for ${taskPlanPath}`);
-      } else if (registryRow[4] !== stepId) {
-        fail(`docs/09-PLANNING/Module-Registry.md row ${moduleKey} current step is ${registryRow[4]}, but active task is ${stepId}`);
-      }
-      if (!ledgerContent.includes(taskPlanPath)) {
-        fail(`docs/Harness-Ledger.md does not index active module task plan ${taskPlanPath}`);
-      }
-      if (exists(reviewPath) && !ledgerContent.includes(reviewPath)) {
-        fail(`docs/Harness-Ledger.md does not index active module review ${reviewPath}`);
-      }
-      continue;
-    }
-
-    if (hasPendingCoordinatorHandoff(taskPlan, taskProgress)) {
-      warn(`${taskPlanPath} has pending coordinator handoff; run coordinator pass before final integration or set HARNESS_REQUIRE_GLOBAL_MODULE_SYNC=1 for strict gate`);
-      continue;
-    }
-    fail(`${taskPlanPath} is active but is neither globally synced nor marked with Coordinator Handoff: pending-coordinator-pass`);
-  }
-}
-
-function listModuleTaskPlans() {
-  const modulesRoot = filePath("docs/09-PLANNING/MODULES");
-  if (!fs.existsSync(modulesRoot)) return [];
-  const results = [];
-  function walk(dir) {
-    for (const entry of fs.readdirSync(dir)) {
-      const full = path.join(dir, entry);
-      const relativePath = rel(path.relative(targetRoot, full));
-      const stat = fs.statSync(full);
-      if (stat.isDirectory()) {
-        if (relativePath.includes("/_archive/") || relativePath.endsWith("/_task-template")) continue;
-        walk(full);
-      } else if (/\/TASKS\/[^/]+\/task_plan\.md$/.test(relativePath)) {
-        results.push(relativePath);
-      }
-    }
-  }
-  walk(modulesRoot);
-  return results;
-}
-
-function parseModuleTaskPath(taskPlanPath) {
-  const match = taskPlanPath.match(/^docs\/09-PLANNING\/MODULES\/([^/]+)\/TASKS\/([^/]+)\/task_plan\.md$/);
-  if (!match) return null;
-  return { moduleKey: match[1], taskDir: match[2] };
-}
-
-function extractStepId(taskPlanContent, taskDir) {
-  const fromPlan = taskPlanContent.match(/^- Step ID:\s*`?([A-Z]{2,5}-\d{2})`?/m);
-  if (fromPlan) return fromPlan[1];
-  const fromModuleSection = taskPlanContent.match(/^- Step:\s*`?([A-Z]{2,5}-\d{2})`?/m);
-  if (fromModuleSection) return fromModuleSection[1];
-  const fromDir = taskDir.match(/^([A-Z]{2,5}-\d{2})-/);
-  return fromDir ? fromDir[1] : "";
-}
-
-function readTaskProgress(taskPlanPath) {
-  const progressPath = taskPlanPath.replace(/task_plan\.md$/, "progress.md");
-  return exists(progressPath) ? read(progressPath) : "";
-}
-
-function readTaskProgressStatus(taskPlanPath) {
-  const progress = readTaskProgress(taskPlanPath);
-  if (!progress) return "";
-  const match = progress.match(/^##\s*(?:Status|状态)\s*[:：]?\s*(?:\n\s*)?([^\n]+)/im);
-  return match ? normalizeModuleTaskStatus(stripMarkdownCode(match[1])) : "";
-}
-
-function normalizeModuleTaskStatus(status) {
-  const value = String(status || "").trim().toLowerCase();
-  const aliases = new Map([
-    ["未开始", "not-started"],
-    ["未启动", "not-started"],
-    ["进行中", "in-progress"],
-    ["开发中", "in-progress"],
-    ["规划审查", "planning-review"],
-    ["已完成", "completed"],
-    ["完成", "completed"],
-    ["已关闭", "closed"],
-    ["关闭", "closed"],
-    ["已阻塞", "blocked"],
-    ["阻塞", "blocked"],
-  ]);
-  return aliases.get(value) || value;
-}
-
-function isActiveModuleTaskStatus(status) {
-  if (!status) return false;
-  return !new Set([
-    "not-started",
-    "blocked-not-started",
-    "complete",
-    "completed",
-    "closed",
-    "closed-with-residual",
-    "closed-local-only",
-    "superseded",
-  ]).has(status);
-}
-
-function hasPendingCoordinatorHandoff(taskPlanContent, progressContent) {
-  const combined = `${taskPlanContent}\n${progressContent}`;
-  return /Coordinator Handoff/i.test(combined) && /pending-coordinator-pass/i.test(combined);
-}
-
 function checkAgentsIndex() {
   if (!exists("AGENTS.md")) return;
   const content = read("AGENTS.md");
@@ -387,15 +166,15 @@ function checkGovernanceContent() {
   if (!exists(governancePath)) return;
   const content = read(governancePath);
   const requiredTerms = [
-    "Repo Platform Profile",
-    "Branch Model",
-    "PR Policy",
-    "Required Checks",
-    "Branch Protection",
-    "Worktree Concurrency",
+    ["Repo Platform Profile", "仓库平台画像"],
+    ["Branch Model", "分支模型"],
+    ["PR Policy", "PR 规则"],
+    ["Required Checks", "必要检查"],
+    ["Branch Protection", "分支保护"],
+    ["Worktree Concurrency", "Worktree 并发"],
   ];
-  for (const term of requiredTerms) {
-    if (!content.includes(term)) fail(`${governancePath} missing section: ${term}`);
+  for (const terms of requiredTerms) {
+    if (!contentIncludesAny(content, terms)) fail(`${governancePath} missing section: ${terms[0]}`);
   }
   if (!statusWords.some((status) => content.includes(status))) {
     fail(`${governancePath} does not use evidence status model`);
@@ -408,13 +187,13 @@ function checkCiCdContent() {
   if (!exists(ciPath)) return;
   const content = read(ciPath);
   const requiredTerms = [
-    "CI Profile",
-    "Workflow",
-    "Required Checks",
-    "Evidence Status",
+    ["CI Profile", "CI 画像"],
+    ["Workflow", "工作流"],
+    ["Required Checks", "必要检查"],
+    ["Evidence Status", "证据状态"],
   ];
-  for (const term of requiredTerms) {
-    if (!content.includes(term)) fail(`${ciPath} missing section: ${term}`);
+  for (const terms of requiredTerms) {
+    if (!contentIncludesAny(content, terms)) fail(`${ciPath} missing section: ${terms[0]}`);
   }
   if (!statusWords.some((status) => content.includes(status))) {
     fail(`${ciPath} does not use evidence status model`);
@@ -428,14 +207,14 @@ function checkDeliveryOperatingModelContent() {
   const content = read(deliveryPath);
   const normalized = content.toLowerCase();
   const requiredTerms = [
-    "operating model profile",
-    "work decomposition rule",
-    "agent visibility",
-    "integration owner",
-    "delivery ssot",
+    ["operating model profile", "运行模型"],
+    ["work decomposition rule", "工作拆分规则"],
+    ["agent visibility", "agent 可见性"],
+    ["integration owner", "集成 owner"],
+    ["delivery ssot", "交付 ssot"],
   ];
-  for (const term of requiredTerms) {
-    if (!normalized.includes(term)) fail(`${deliveryPath} missing section: ${term}`);
+  for (const terms of requiredTerms) {
+    if (!contentIncludesAny(normalized, terms.map((term) => term.toLowerCase()))) fail(`${deliveryPath} missing section: ${terms[0]}`);
   }
   if (!/solo-orchestrator|team-feature-lead|split-repo-contract|program-multi-repo|waterfall-stage-gate|kanban-continuous/.test(content)) {
     fail(`${deliveryPath} does not define a recognized operating model`);
@@ -480,7 +259,7 @@ function checkReviewTemplate() {
   const reviewPath = "docs/09-PLANNING/TASKS/_task-template/review.md";
   if (!exists(reviewPath)) return;
   const content = read(reviewPath);
-  if (!content.includes("Confidence Challenge")) {
+  if (!contentIncludesAny(content, ["Confidence Challenge", "信心挑战"])) {
     fail(`${reviewPath} missing Confidence Challenge`);
   }
   if (/\|\s*R-001\s*\|\s*P[01]\s*\|.*\|\s*open\s*\|/i.test(content)) {
@@ -515,8 +294,12 @@ function findHeaderIndex(rows, pattern) {
   return rows.findIndex((cells) => cells.some((cell) => pattern.test(cell)));
 }
 
-function columnIndex(header, pattern) {
-  return header.findIndex((cell) => pattern.test(cell));
+function contentIncludesAny(content, terms) {
+  return terms.some((term) => (term instanceof RegExp ? term.test(content) : content.includes(term)));
+}
+
+function columnIndexAny(header, patterns) {
+  return header.findIndex((cell) => patterns.some((pattern) => pattern.test(cell)));
 }
 
 function checkDuplicateIds(rows, sourcePath) {
@@ -535,9 +318,9 @@ function checkCloseoutSsot() {
   if (!exists(closeoutPath)) return;
 
   const closeoutContent = read(closeoutPath);
-  for (const term of ["Walkthrough", "Lessons Check", "Closeout Status"]) {
-    if (!closeoutContent.includes(term)) {
-      fail(`${closeoutPath} missing required closeout column or section: ${term}`);
+  for (const terms of [["Walkthrough"], ["Lessons Check", "Lessons 检查"], ["Closeout Status", "收口状态"]]) {
+    if (!contentIncludesAny(closeoutContent, terms)) {
+      fail(`${closeoutPath} missing required closeout column or section: ${terms[0]}`);
     }
   }
   checkNoGenericPlaceholders(closeoutPath);
@@ -545,7 +328,7 @@ function checkCloseoutSsot() {
   const closeoutTable = markdownTable(closeoutContent);
   const closeoutHeaderIndex = findHeaderIndex(closeoutTable, /^Harness ID$/i);
   const closeoutHeader = closeoutHeaderIndex >= 0 ? closeoutTable[closeoutHeaderIndex] : [];
-  const lessonsColumn = columnIndex(closeoutHeader, /^Lessons Check$/i);
+  const lessonsColumn = columnIndexAny(closeoutHeader, [/^Lessons Check$/i, /^Lessons 检查$/i, /^Lessons 检查\s*\/\s*Lessons Check$/i]);
   if (lessonsColumn < 0) {
     fail(`${closeoutPath} missing Lessons Check column`);
   }
@@ -553,10 +336,11 @@ function checkCloseoutSsot() {
   if (!exists("docs/Harness-Ledger.md")) return;
   const ledgerContent = read("docs/Harness-Ledger.md");
   const lessonIds = collectLessonIds();
+  const lessonCandidateIds = collectLessonCandidateIds();
   const ledgerTable = markdownTable(ledgerContent);
   const ledgerHeaderIndex = findHeaderIndex(ledgerTable, /^ID$/i);
   const ledgerHeader = ledgerHeaderIndex >= 0 ? ledgerTable[ledgerHeaderIndex] : [];
-  const ledgerLessonsColumn = columnIndex(ledgerHeader, /^Lessons Check$/i);
+  const ledgerLessonsColumn = columnIndexAny(ledgerHeader, [/^Lessons Check$/i, /^Lessons 检查$/i, /^Lessons 检查\s*\/\s*Lessons Check$/i]);
   if (ledgerLessonsColumn < 0) {
     fail("docs/Harness-Ledger.md missing Lessons Check column");
   }
@@ -587,86 +371,82 @@ function checkCloseoutSsot() {
     if (lessonsColumn >= 0) {
       const lessonsCheck = closeout[lessonsColumn] || "";
       const createdMatch = lessonsCheck.match(lessonsCreatedPattern);
-      if (!createdMatch && !lessonsNonePattern.test(lessonsCheck)) {
-        fail(`${closeoutPath} row ${id} needs Lessons Check value: checked-created:<lesson-id> or checked-none:<reason>`);
+      const candidateMatch = lessonsCheck.match(lessonsCandidatePattern) || lessonsCheck.match(lessonsQueuedPromotionPattern);
+      if (!createdMatch && !candidateMatch && !lessonsNonePattern.test(lessonsCheck)) {
+        fail(`${closeoutPath} row ${id} needs Lessons Check value: checked-created:<lesson-id>, checked-candidate:<candidate-id>, queued-promotion:<candidate-id>, or checked-none:<reason>`);
       } else if (createdMatch && !lessonIds.has(createdMatch[1])) {
-        fail(`${closeoutPath} row ${id} references missing Lessons SSoT id: ${createdMatch[1]}`);
+        fail(`${closeoutPath} row ${id} references missing lesson detail doc id: ${createdMatch[1]}`);
+      } else if (candidateMatch && !lessonCandidateIds.has(candidateMatch[1])) {
+        fail(`${closeoutPath} row ${id} references missing lesson candidate id: ${candidateMatch[1]}`);
       }
     }
 
     if (ledgerLessonsColumn >= 0) {
       const ledgerLessonsCheck = cells[ledgerLessonsColumn] || "";
       const ledgerCreatedMatch = ledgerLessonsCheck.match(lessonsCreatedPattern);
-      if (!ledgerCreatedMatch && !lessonsNonePattern.test(ledgerLessonsCheck)) {
-        fail(`docs/Harness-Ledger.md row ${id} needs Lessons Check value: checked-created:<lesson-id> or checked-none:<reason>`);
+      const ledgerCandidateMatch = ledgerLessonsCheck.match(lessonsCandidatePattern) || ledgerLessonsCheck.match(lessonsQueuedPromotionPattern);
+      if (!ledgerCreatedMatch && !ledgerCandidateMatch && !lessonsNonePattern.test(ledgerLessonsCheck)) {
+        fail(`docs/Harness-Ledger.md row ${id} needs Lessons Check value: checked-created:<lesson-id>, checked-candidate:<candidate-id>, queued-promotion:<candidate-id>, or checked-none:<reason>`);
       } else if (ledgerCreatedMatch && !lessonIds.has(ledgerCreatedMatch[1])) {
-        fail(`docs/Harness-Ledger.md row ${id} references missing Lessons SSoT id: ${ledgerCreatedMatch[1]}`);
+        fail(`docs/Harness-Ledger.md row ${id} references missing lesson detail doc id: ${ledgerCreatedMatch[1]}`);
+      } else if (ledgerCandidateMatch && !lessonCandidateIds.has(ledgerCandidateMatch[1])) {
+        fail(`docs/Harness-Ledger.md row ${id} references missing lesson candidate id: ${ledgerCandidateMatch[1]}`);
       }
     }
   }
 }
 
 function collectLessonIds() {
-  const lessonsPath = "docs/01-GOVERNANCE/Lessons-SSoT.md";
-  if (!exists(lessonsPath)) return new Set();
-  const table = markdownTable(read(lessonsPath));
-  const headerIndex = findHeaderIndex(table, /^ID$/i);
-  const header = headerIndex >= 0 ? table[headerIndex] : [];
-  const idColumn = columnIndex(header, /^ID$/i);
-  if (idColumn < 0) return new Set();
-  return new Set(
-    table
-      .map((cells) => cells[idColumn] || "")
-      .filter((id) => /^L-\d{4}(-\d{2}-\d{2})?-\d+/i.test(id)),
-  );
+  const root = filePath("docs/01-GOVERNANCE/lessons");
+  const ids = new Set();
+  if (!fs.existsSync(root)) return ids;
+  for (const entry of fs.readdirSync(root)) {
+    if (!entry.endsWith(".md")) continue;
+    const full = path.join(root, entry);
+    if (!fs.statSync(full).isFile()) continue;
+    const content = fs.readFileSync(full, "utf8");
+    const pathMatch = entry.match(/(L-\d{4}(?:-\d{2}-\d{2})?-\d+)/i);
+    const titleMatch = content.match(/#\s*(L-\d{4}(?:-\d{2}-\d{2})?-\d+)/i);
+    const id = titleMatch?.[1] || pathMatch?.[1];
+    if (id) ids.add(id);
+  }
+  return ids;
+}
+
+function collectLessonCandidateIds() {
+  const root = filePath("docs/09-PLANNING");
+  const ids = new Set();
+  if (!fs.existsSync(root)) return ids;
+  function visit(dir) {
+    for (const entry of fs.readdirSync(dir)) {
+      const full = path.join(dir, entry);
+      const stat = fs.statSync(full);
+      if (stat.isDirectory()) {
+        if (entry === "_archive") continue;
+        visit(full);
+        continue;
+      }
+      if (entry !== "lesson_candidates.md") continue;
+      const content = fs.readFileSync(full, "utf8");
+      for (const match of content.matchAll(/\|\s*(LC-[A-Za-z0-9-]+)\s*\|/g)) {
+        ids.add(match[1]);
+      }
+    }
+  }
+  visit(root);
+  return ids;
 }
 
-function checkLessonsSsot() {
-  const lessonsPath = "docs/01-GOVERNANCE/Lessons-SSoT.md";
-  if (!exists(lessonsPath)) return;
-
-  const content = read(lessonsPath);
-  if (!/Detail Doc/i.test(content)) {
-    fail(`${lessonsPath} missing Detail Doc column`);
-  }
-
-  const table = markdownTable(content);
-  const headerIndex = findHeaderIndex(table, /^ID$/i);
-  const header = headerIndex >= 0 ? table[headerIndex] : [];
-  const detailColumn = columnIndex(header, /^(Detail Doc|Detail)$/i);
-  const idColumn = columnIndex(header, /^ID$/i);
-  const statusColumn = columnIndex(header, /^Status$/i);
-  if (idColumn < 0) fail(`${lessonsPath} missing ID column`);
-  if (detailColumn < 0) fail(`${lessonsPath} missing Detail Doc column`);
-  if (statusColumn < 0) fail(`${lessonsPath} missing Status column`);
-  if (idColumn < 0 || detailColumn < 0 || statusColumn < 0) return;
-
-  const lessonRows = table.filter((cells) => /^L-\d{4}(-\d{2}-\d{2})?-\d+/i.test(cells[idColumn] || ""));
-  for (const cells of lessonRows) {
-    const id = cells[idColumn] || "";
-    const status = cells[statusColumn] || "";
-    const detail = cells[detailColumn] || "";
-    if (!/pending|approved|merged|rejected|superseded|🟡|🟢|✅|❌|🔀/i.test(status)) {
-      fail(`${lessonsPath} row ${id} has unrecognized status: ${status}`);
-    }
-    const detailMatch = detail.match(/docs\/01-GOVERNANCE\/lessons\/[^|\s`]+\.md/);
-    if (!detailMatch) {
-      fail(`${lessonsPath} row ${id} Detail Doc must point to docs/01-GOVERNANCE/lessons/*.md`);
-      continue;
-    }
-    const detailPath = detailMatch[0];
-    if (!exists(detailPath)) {
-      fail(`${lessonsPath} row ${id} Detail Doc missing file: ${detailPath}`);
-      continue;
-    }
-    const detailContent = read(detailPath);
-    if (!detailContent.includes(id)) {
-      fail(`${detailPath} does not include lesson id ${id}`);
-    }
-    for (const requiredTerm of ["背景", "冲突声明"]) {
-      if (!detailContent.includes(requiredTerm)) {
-        fail(`${detailPath} missing required lesson section: ${requiredTerm}`);
-      }
+function checkLessonDetailDocs() {
+  const root = filePath("docs/01-GOVERNANCE/lessons");
+  if (!fs.existsSync(root)) return;
+  for (const entry of fs.readdirSync(root)) {
+    if (!entry.endsWith(".md")) continue;
+    const relativePath = `docs/01-GOVERNANCE/lessons/${entry}`;
+    const content = read(relativePath);
+    const id = entry.match(/(L-\d{4}(?:-\d{2}-\d{2})?-\d+)/i)?.[1];
+    if (id && !content.includes(id)) {
+      fail(`${relativePath} does not include lesson id ${id}`);
     }
   }
 }
@@ -675,7 +455,7 @@ function checkWalkthroughTemplate() {
   const walkthroughTemplate = "docs/10-WALKTHROUGH/_walkthrough-template.md";
   if (!exists(walkthroughTemplate)) return;
   const content = read(walkthroughTemplate);
-  if (!content.includes("Lessons Reflection")) {
+  if (!contentIncludesAny(content, ["Lessons Reflection", "Lessons 回看"])) {
     fail(`${walkthroughTemplate} missing Lessons Reflection section`);
   }
 }
@@ -707,7 +487,7 @@ function main() {
   checkReviewTemplate();
   checkHarnessLedger();
   checkCloseoutSsot();
-  checkLessonsSsot();
+  checkLessonDetailDocs();
   checkWalkthroughTemplate();
   checkReferencePlaceholders();