@devflow-core/dsh-devflow 0.4.0 → 0.6.0

package/assets/commands/devflow-prove.toml

@@ -4,6 +4,8 @@ Run DevFlow Prove.
 
 Identify the narrowest sufficient command, test, build, lint, validation script, or manual scenario.
 Run it now if tools are available.
+Load `skills/devflow-prove/references/proof-recovery-methods.md` always. Load `skills/devflow-prove/references/flow-self-test.md` only for DevFlow runtime, skill, command, host, hook, validator, scenario, installer, or harness changes. For code, load `skills/devflow-prove/references/code-review-checklist.md`, always apply General Engineering Review, and apply only language sections matching changed extensions.
+Read the actual diff and the current task's named anchors; reread at most one already-listed neighbor needed to detect drift; do not restart broad repository discovery.
 For development work, run adversarial review before completion: state the strongest plausible reason the result is still wrong, incomplete, unreachable, over-broad, or under-verified, then check it against the acceptance criteria, touched files, likely regressions, activation path, and proof coverage.
 If adversarial review finds a real gap, report FAIL or continue the appropriate DevFlow route before any completion claim.
 Read the real output and exit status.

package/assets/commands/devflow.toml

@@ -2,17 +2,18 @@ description = "Route a task through DevFlow Core."
 prompt = '''
 Use DevFlow Core for this request.
 
-Route the work as Fast, Design-lite, Design, Build, or Recovery.
-Before creative work — creating features, building components, adding functionality, modifying behavior, or defining an unapproved problem-directed change — run Brainstorm to confirm the request: read facts, follow `skills/devflow-brainstorm/references/interview-discipline.md`, send a Semantic Echo-Back, apply the Understanding Revision Rule when a correction changes the request, ask one question at a time only for goal/scope/exclusions/constraints/acceptance/open-question gaps, then output `Confirmed request` with `Status: clarified`. Brainstorm then presents A/B/C and waits for the user's explicit choice: A directly starts Spec, B directly starts Cut then Plan, and C directly starts Cut then Build. Brainstorm never infers the depth; a missing or changed selection returns facts to Core.
+Route the work as Fast, Design-lite, Design, Build, or Recovery. Apply this precedence: explicit independent review -> investigation/pure inquiry -> approved scope -> risk gate -> lifecycle owner; keywords alone never choose a route.
+For creative work, run Brainstorm only when the request is ambiguous or materially risky. A clear existing-feature change may go directly to Cut only when all conditions hold: clear goal, existing local behavior, one plausible path, local impact, reversible change, no security/data-loss/permission/contract risk, and quick proof. This bypass compresses clarification only; Cut and Prove remain mandatory. When Brainstorm is selected, read `skills/devflow-brainstorm/references/interview-discipline.md`, send a Semantic Echo-Back, apply the Understanding Revision Rule when a correction changes the request, ask one question at a time only for decision-impact gaps, then output `Confirmed request` with `Status: clarified`. Brainstorm then presents A/B/C and waits for the user's explicit choice: A directly starts Spec, B directly starts Cut then Plan, and C directly starts Cut then Build. Brainstorm never infers the depth; a missing or changed selection returns facts to Core.
+An unapproved problem-directed change uses the same risk gate: ambiguity or material risk selects Brainstorm; otherwise the low-risk direct Cut criteria must all pass.
 An investigation-only problem report without a requested change uses Problem: Sense -> Prove facts. Pure Q&A, fact lookup, verification, and already approved changes are exceptions to the Brainstorm entry gate.
 If the user explicitly asks for upgraded adversarial review, deep adversarial review, red-team review, 对抗审查, or 升级版对抗审查, load `skills/devflow-adversarial/SKILL.md` directly. If the user explicitly asks to find faults, identify the biggest omission, surface a blind spot, name the least certain point, 找茬, 最大遗漏, 没有意识到什么, or 最没有把握, load `skills/devflow-find-fault/SKILL.md` directly. These are independent manual reviews: they may run at any stage and must not read, require, modify, or hand off to devflow-prove, PUA, Build, Learn, or any completion state.
 If the user challenges the result, says changed wrong, says your code is wrong/you wrote it wrong/has a problem/not right/missing/incomplete/still missing/有问题/不对/写错了/少了/少个/缺少/缺漏/遗漏/漏了, reports a quality complaint, or repeated edits miss, use Recovery through devflow-pua before more edits. For repeated challenge, explicit wrong-code signals, or repeated missing-piece complaints, return recovery facts to devflow-core; Core may restart devflow-brainstorm only for request re-confirmation, then selects the lifecycle work. Quarantine the old wrong context, diagnose the user-view miss, ask what is wrong and what result is wanted, then switch to a different/opposite method when the prior method failed.
-Use Fast for pure Q&A, fact lookup, verification, or an already approved trivial code change (one line, no logic change, no risk).
-Use Design-lite only after Brainstorm confirms a small unapproved change to an existing feature with clear behavior, one plausible path, low risk, local impact, and quick proof. Not for new requirements.
+Use Fast for pure Q&A, fact lookup, verification, or an already approved trivial code change (one line, no logic change, no risk). Unapproved edits are not Fast and must not skip Cut.
+Use Design-lite when the risk gate skips Brainstorm for a small unapproved change to an existing feature with all low-risk conditions holding. Design-lite states goal, acceptance, and exclusions, records Depth C, and selects Cut then Build. It does not wait for Brainstorm. Not for new requirements.
 If the boundary is unclear after Brainstorm, have Core select the smallest compatible route instead of guessing.
 Run Sense first by reading or citing relevant project facts.
-At Sense, probe `.copilot/LEARNING_INDEX.md` and `docs/project-knowledge/` when present. Read only matched learning cards or navigation-selected knowledge documents; missing locations are non-blocking and do not create storage.
-The direct success map is A: Brainstorm -> Spec -> Cut -> Plan -> Build -> Prove, B: Brainstorm -> Cut -> Plan -> Build -> Prove, C: Brainstorm -> Cut -> Build -> Prove. An approved A Spec directly starts Cut; A/B `CUT_PASS` directly starts Plan; C `CUT_PASS` directly starts Build; an approved A/B Plan directly starts Build; a completed Build directly starts Prove.
+At Sense, match the task keywords against `docs/features/INDEX.md` and `docs/plans/INDEX.md` when present and open only the matched row's entry file or ledger section (an index over 40 rows is filtered with `node scripts/devflow-plan.js --index --query 关键词`); do not bulk-read capability documents. Then probe `.copilot/LEARNING_INDEX.md` (global preference cards first) and `docs/project-knowledge/`, reading only matched learning cards or navigation-selected knowledge documents and applying known developer preferences; missing locations are non-blocking and do not create storage.
+The direct success map is Skip-Brainstorm Design-lite: Cut -> Build -> Prove, A: Brainstorm -> Spec -> Cut -> Plan -> Build -> Prove, B: Brainstorm -> Cut -> Plan -> Build -> Prove, C: Brainstorm -> Cut -> Build -> Prove. An approved A Spec directly starts Cut; A/B `CUT_PASS` directly starts Plan; C `CUT_PASS` and a skip-path `CUT_PASS` directly start Build; an approved A/B Plan directly starts Build; a completed Build directly starts Prove.
 Before implementation, run Cut with Required Gates: Reuse, Native, Overbuild, Diff, and Scope checks. Core keeps non-unique selection: `CUT_REDUCE`/`CUT_REUSE` STOP for user confirmation, then return facts to Core; `CUT_BLOCKED`, Plan scope drift, `BUILD_BLOCKED`, Proof `FAIL`/`BLOCKED`, changed intent, and PUA recovery return facts so Core chooses the next owner.
 For bug fixes, include Root-Cause Check: searched callers/references; shared vs narrow fix; reason.
 For deliberate simplifications, add or report `devflow: <ceiling>, revisit when <trigger>`.

package/assets/scripts/devflow-plan.js

@@ -1,4 +1,5 @@
 const fs = require("node:fs");
+const path = require("node:path");
 
 const requiredGlobalFields = ["Goal", "Architecture", "Tech Stack", "Source", "Spec coverage", "External Skills"];
 const requiredTaskFields = ["Task", "Task type", "Files", "Interfaces", "Steps", "Acceptance", "Verify", "Comments", "Not doing"];
@@ -38,10 +39,32 @@ const worklistItemPattern = /^\s*-\s*\[ \]\s+(.+)$/gim;
 const worklistDetailNames = ["Anchors", "Verify", "Done when"];
 const maximumWorklistItems = 12;
 
+// v2 契约（2026-09-10 可用性重构）：计划只保留排序与验收字段；实现改法归 Build。
+// 判定：含 `## Progress` 且不含 `Prewalk` 视为 v2；否则走 legacy 分支，旧计划无需迁移。
+const v2GlobalFields = ["Goal", "Not doing", "Cut"];
+const v2TaskFields = ["Task", "Files", "Change", "Acceptance", "Verify", "Not doing"];
+const v2AllFields = [...v2GlobalFields, ...v2TaskFields];
+const v2FieldPatterns = Object.fromEntries(
+  v2AllFields.map((field) => [field, new RegExp(`^(?:\\*\\*)?${field}(?:\\*\\*)?\\s*:`, "im")])
+);
+const progressHeadingPattern = /^##\s+Progress\s*$/im;
+const progressRowPattern = /^\s*\|\s*(\d+)\s*\|\s*([^|]*)\|\s*(todo|doing|done)\s*\|\s*([^|]*)\|/gim;
+const indexStatuses = ["active", "planned", "legacy", "retired"];
+const indexPaths = { plans: "docs/plans/INDEX.md", features: "docs/features/INDEX.md" };
+// 需求台账：一条需求从确认到落地的唯一记录；opt-out 表示用户显式跳过文档（仍必须有验证证据与原因）。
+const requirementPath = "docs/requirements.md";
+const requirementStatuses = ["open", "designed", "planned", "built", "landed", "opt-out", "dropped"];
+const terminalRequirementStatuses = ["landed", "opt-out", "dropped"];
+const promotionConfidence = 0.7;
+
 /** Print the checker command contract and default plan landing. */
 function usage() {
-  console.log("Usage: node scripts/devflow-plan.js [plan-file] [--self-test] [--json]");
+  console.log("Usage: node scripts/devflow-plan.js [plan-file] [--index] [--self-test] [--json]");
   console.log("Checks whether a DevFlow Plan Pack has an executable header, task contracts, and plan landing.");
+  console.log("v2 plans carry a slim header, per-task Files/Change/Acceptance/Verify/Not doing, and a ## Progress table; legacy plans keep the old contract.");
+  console.log("--index checks docs/plans/INDEX.md and docs/features/INDEX.md against the filesystem.");
+  console.log("--index --query <keyword> prints only matching index rows for progressive loading; an empty result still exits 0.");
+  console.log("--loop prints a read-only loop report: requirement status counts, plan landing rate, feature rows, and promotion candidates.");
   console.log("Default plan landing is docs/plans/YYYY-MM-DD-<short-kebab-name>.md unless the project documents another plan path.");
   console.log("--json prints a single-line machine-readable summary; optional Status header values: " + validStatuses.join(" | "));
 }
@@ -311,8 +334,369 @@ function checkTask(task, fileStructure) {
   };
 }
 
-/** Validate global plan headers and all independently scoped task contracts. */
+/** v2 计划判定：新格式带 Progress 表且不含 Prewalk；旧格式继续走 legacy 校验。 */
+function detectV2(body) {
+  return progressHeadingPattern.test(body) && !/^\s*Prewalk\s*:\s*$/im.test(body);
+}
+
+/** Extract one v2 field block; ends at the next v1 or v2 field line. */
+function v2FieldBlock(body, field) {
+  const lines = body.split(/\r?\n/);
+  const start = lines.findIndex((line) => v2FieldPatterns[field].test(line));
+  if (start < 0) return "";
+
+  const value = lines[start].replace(v2FieldPatterns[field], "").trim();
+  const end = lines.findIndex(
+    (line, index) =>
+      index > start && (v2AllFields.some((name) => v2FieldPatterns[name].test(line)) || /^#{1,6}\s+\S/.test(line))
+  );
+  return [value, ...lines.slice(start + 1, end < 0 ? lines.length : end)].join("\n").trim();
+}
+
+/** Split a v2 plan at Task fields; the Progress table is not part of any task body. */
+function splitTasksV2(body) {
+  const lines = body.split(/\r?\n/);
+  const progressIndex = lines.findIndex((line) => progressHeadingPattern.test(line));
+  const limit = progressIndex < 0 ? lines.length : progressIndex;
+  const taskStarts = [];
+  lines.forEach((line, index) => {
+    if (index < limit && v2FieldPatterns.Task.test(line)) taskStarts.push(index);
+  });
+  return taskStarts.map((start, index) => {
+    const end = taskStarts[index + 1] ?? limit;
+    return { number: index + 1, body: lines.slice(start, end).join("\n") };
+  });
+}
+
+/** Validate one v2 task: files, change intent, acceptance, proof, and exclusion. */
+function checkTaskV2(task) {
+  const missing = v2TaskFields.filter((field) => !v2FieldPatterns[field].test(task.body));
+  const files = v2FieldBlock(task.body, "Files");
+  const change = v2FieldBlock(task.body, "Change");
+  const verify = v2FieldBlock(task.body, "Verify");
+  const notDoing = v2FieldBlock(task.body, "Not doing");
+  const fileEntries = parseFileEntries(files);
+  const invalidFiles = fileEntries.filter(({ match }) => !match).map(({ line }) => line);
+  const unlocatedCodeFiles = findUnlocatedCodeFiles(fileEntries);
+  const unresolved = findMatches(task.body, unresolvedPatterns);
+  const vague = findMatches([change, v2FieldBlock(task.body, "Acceptance"), verify].join("\n"), vaguePatterns);
+  // v2 不强制精确改法；只要求 Change 说出可执行意图，具体实现归 Build。
+  const missingChange = !implementationVerbPattern.test(change) || genericMechanicsPattern.test(change);
+  const incompleteVerification = !hasVerificationExpectation(verify);
+
+  return {
+    number: task.number,
+    missing,
+    unresolved,
+    vague,
+    invalidFiles,
+    unlocatedCodeFiles,
+    missingChange,
+    incompleteVerification,
+    missingNotDoing: !notDoing,
+    ok:
+      missing.length === 0 &&
+      unresolved.length === 0 &&
+      vague.length === 0 &&
+      invalidFiles.length === 0 &&
+      unlocatedCodeFiles.length === 0 &&
+      !missingChange &&
+      !incompleteVerification &&
+      Boolean(notDoing)
+  };
+}
+
+/** Validate the v2 plan contract: slim header, task rows, Progress table, and Cut subtraction. */
+function checkPlanV2(body) {
+  const tasks = splitTasksV2(body);
+  const taskResults = tasks.map(checkTaskV2);
+  const missingGlobal = v2GlobalFields.filter((field) => !v2FieldPatterns[field].test(body));
+  const cutBlock = v2FieldBlock(body, "Cut");
+  const missingRejected = !/Rejected\s*:\s*\S/im.test(cutBlock);
+  const statusMatch = body.match(statusPattern);
+  const status = statusMatch ? statusMatch[1].trim() : "legacy";
+  const invalidStatus = statusMatch ? !validStatuses.includes(status) : false;
+  const progress = [...body.matchAll(progressRowPattern)].map((match) => ({
+    number: Number(match[1]),
+    state: match[3],
+    evidence: match[4].trim()
+  }));
+  const missingEvidence = progress.filter((row) => row.state === "done" && (!row.evidence || row.evidence === "-"));
+  const progressMismatch = progress.length !== tasks.length;
+  const doneStatusNeedsAllDone = status === "done" && progress.some((row) => row.state !== "done");
+
+  return {
+    v2: true,
+    status,
+    invalidStatus,
+    missingGlobal,
+    cut: { missingRejected },
+    tasks: taskResults,
+    progress: { count: progress.length, mismatch: progressMismatch, missingEvidence },
+    doneStatusNeedsAllDone,
+    ok:
+      missingGlobal.length === 0 &&
+      !missingRejected &&
+      !invalidStatus &&
+      tasks.length > 0 &&
+      taskResults.every((task) => task.ok) &&
+      !progressMismatch &&
+      missingEvidence.length === 0 &&
+      !doneStatusNeedsAllDone
+  };
+}
+
+/** Read every markdown table in a file as header cells plus data rows, skipping separator rows. */
+function readMarkdownTables(filePath) {
+  const lines = fs.readFileSync(filePath, "utf8").split(/\r?\n/);
+  const tables = [];
+  let current = [];
+  for (const line of lines) {
+    if (/^\s*\|/.test(line)) {
+      current.push(line.split("|").slice(1, -1).map((cell) => cell.trim()));
+      continue;
+    }
+    if (current.length) {
+      tables.push(current);
+      current = [];
+    }
+  }
+  if (current.length) tables.push(current);
+  return tables
+    .map((cells) => cells.filter((row) => !row.every((cell) => /^:?-{2,}:?$/.test(cell))))
+    .filter((cells) => cells.length > 1)
+    .map((cells) => ({ header: cells[0], rows: cells.slice(1) }));
+}
+
+/** Read the first markdown table into its header cells and data rows. */
+function readMarkdownTable(filePath) {
+  return readMarkdownTables(filePath)[0] || { header: [], rows: [] };
+}
+
+/** Resolve named column positions from the table header so a new column cannot shift the checks. */
+function columnIndexes(header, names) {
+  return Object.fromEntries(names.map((name) => [name, header.findIndex((cell) => cell.includes(name))]));
+}
+
+/** Read one index file's data rows, returning an empty list when the index does not exist yet. */
+function readIndexRows(root, kind) {
+  const filePath = path.join(root, ...indexPaths[kind].split("/"));
+  return fs.existsSync(filePath) ? readMarkdownTable(filePath).rows : [];
+}
+
+/** Return index rows whose text contains the query, for progressive index loading. */
+function matchIndexRows(rows, query) {
+  const needle = String(query || "").trim().toLowerCase();
+  if (!needle) return [];
+  return rows.filter((cells) => cells.join(" ").toLowerCase().includes(needle));
+}
+
+/** Read the value after a flag, or an empty string when it is absent or looks like another flag. */
+function argValue(args, flag) {
+  const index = args.indexOf(flag);
+  return index >= 0 && args[index + 1] && !args[index + 1].startsWith("-") ? args[index + 1] : "";
+}
+
+/** Check docs/plans/INDEX.md and docs/features/INDEX.md against the filesystem. */
+function checkIndexes(root) {
+  const problems = [];
+  const plansDir = path.join(root, "docs", "plans");
+  const featuresDir = path.join(root, "docs", "features");
+  const plansIndex = path.join(root, ...indexPaths.plans.split("/"));
+  const featuresIndex = path.join(root, ...indexPaths.features.split("/"));
+  const planFiles = fs.existsSync(plansDir)
+    ? fs.readdirSync(plansDir).filter((name) => name.endsWith(".md") && name !== "INDEX.md")
+    : [];
+  const planRows = readIndexRows(root, "plans");
+  const featureRows = readIndexRows(root, "features");
+  const plansTable = fs.existsSync(plansIndex) ? readMarkdownTable(plansIndex) : { header: [] };
+  const featuresTable = fs.existsSync(featuresIndex) ? readMarkdownTable(featuresIndex) : { header: [] };
+  const planCols = columnIndexes(plansTable.header, ["计划", "Status", "落地证据", "功能条目"]);
+  const featureCols = columnIndexes(featuresTable.header, ["功能", "Status", "关键文件", "来源计划"]);
+
+  if (planFiles.length > 0 && !fs.existsSync(plansIndex)) {
+    problems.push("docs/plans/INDEX.md missing while plan files exist");
+  }
+  for (const file of planFiles) {
+    const rows = planRows.filter((cells) => cells.some((cell) => cell.includes(file)));
+    if (rows.length === 0) problems.push(`plan not listed in docs/plans/INDEX.md: ${file}`);
+    if (rows.length > 1) problems.push(`plan listed more than once in docs/plans/INDEX.md: ${file}`);
+  }
+  for (const cells of planRows) {
+    const link = cells.find((cell) => cell.includes(".md"));
+    const file = link ? (link.match(/([^()/]+\.md)/) || [])[1] : null;
+    if (!file) continue;
+    if (!planFiles.includes(file)) problems.push(`docs/plans/INDEX.md lists unknown plan: ${file}`);
+    const filePath = path.join(plansDir, file);
+    if (!fs.existsSync(filePath)) continue;
+    const body = fs.readFileSync(filePath, "utf8");
+    const statusMatch = body.match(statusPattern);
+    const expected = statusMatch ? statusMatch[1].trim() : "legacy";
+    const rowStatus = (cells[planCols.Status] || "").trim();
+    if (rowStatus && rowStatus !== expected) {
+      problems.push(`status mismatch for ${file}: index ${rowStatus} vs file ${expected}`);
+    }
+    const evidence = (cells[planCols["落地证据"]] || "").trim();
+    if (rowStatus === "done" && (!evidence || evidence === "-")) {
+      problems.push(`done plan needs landing evidence in docs/plans/INDEX.md: ${file}`);
+    }
+    const featureCell = (cells[planCols["功能条目"]] || "").trim();
+    if (featureCell && featureCell !== "-" && !featureRows.some((row) => (row[featureCols["功能"]] || "").includes(featureCell))) {
+      problems.push(`feature entry not found in docs/features/INDEX.md: ${featureCell}`);
+    }
+  }
+  for (const cells of featureRows) {
+    const status = (cells[featureCols.Status] || "").trim();
+    if (status && !indexStatuses.includes(status)) {
+      problems.push(`invalid feature status in docs/features/INDEX.md: ${status}`);
+    }
+    const files = (cells[featureCols["关键文件"]] || "").split(",").map((value) => value.replaceAll("`", "").trim()).filter((value) => value && value !== "-");
+    for (const rel of files) {
+      if (!fs.existsSync(path.join(root, rel))) problems.push(`feature file missing: ${rel}`);
+    }
+    const plan = (cells[featureCols["来源计划"]] || "").replaceAll("`", "").trim();
+    if (plan && plan !== "-" && !fs.existsSync(path.join(root, "docs", "plans", plan))) {
+      problems.push(`feature source plan missing: ${plan}`);
+    }
+  }
+  const requirementTable = readRequirementTable(root);
+  problems.push(
+    ...checkRequirementTable(requirementTable.header, requirementTable.rows, (rel) => fs.existsSync(path.join(root, rel)))
+  );
+  return problems;
+}
+
+/** Run the plan and feature index consistency check, or answer a single query. */
+function runIndexCheck(json, query) {
+  const root = path.resolve(__dirname, "..");
+  if (query) {
+    const featureMatches = matchIndexRows(readIndexRows(root, "features"), query);
+    const planMatches = matchIndexRows(readIndexRows(root, "plans"), query);
+    if (json) {
+      console.log(JSON.stringify({ checker: "plan-index-query", query, features: featureMatches, plans: planMatches, judgment: "PASS" }));
+    } else {
+      console.log(`DevFlow index query: ${query}`);
+      for (const cells of featureMatches) console.log(`功能行: ${cells.join(" | ")}`);
+      for (const cells of planMatches) console.log(`计划行: ${cells.join(" | ")}`);
+      console.log(`Matches: ${featureMatches.length + planMatches.length}`);
+    }
+    return 0;
+  }
+  const problems = checkIndexes(root);
+  if (json) {
+    console.log(JSON.stringify({ checker: "plan-index", problems, judgment: problems.length === 0 ? "PASS" : "FAIL" }));
+  } else {
+    console.log("DevFlow plan and feature index report");
+    console.log(`Index files: ${indexPaths.plans} | ${indexPaths.features}`);
+    if (problems.length === 0) console.log("Problems: none");
+    for (const problem of problems) console.log(`Problem: ${problem}`);
+    console.log(`Judgment: ${problems.length === 0 ? "PASS" : "FAIL"}`);
+  }
+  return problems.length === 0 ? 0 : 1;
+}
+
+/** Validate the requirement ledger table: status whitelist, terminal evidence, opt-out reason, artifact paths. */
+function checkRequirementTable(header, rows, exists) {
+  const problems = [];
+  const cols = columnIndexes(header, ["需求", "日期", "落地物", "状态", "证据或跳过"]);
+  if (cols["状态"] < 0 || cols["证据或跳过"] < 0) {
+    problems.push("docs/requirements.md header must contain 状态 and 证据或跳过 columns");
+    return problems;
+  }
+  for (const cells of rows) {
+    const requirement = (cells[cols["需求"]] || "").trim();
+    const date = cols["日期"] >= 0 ? (cells[cols["日期"]] || "").trim() : "";
+    const status = (cells[cols["状态"]] || "").trim();
+    const evidence = (cells[cols["证据或跳过"]] || "").trim();
+    if (!requirement) problems.push("requirement row missing 需求 text");
+    if (!date) problems.push(`requirement row missing 日期: ${requirement}`);
+    if (!requirementStatuses.includes(status)) problems.push(`invalid requirement status: ${status}`);
+    if (terminalRequirementStatuses.includes(status) && (!evidence || evidence === "-")) {
+      problems.push(`terminal requirement needs evidence: ${requirement}`);
+    }
+    if (status === "opt-out" && !/原因|reason|skip/i.test(evidence)) {
+      problems.push(`opt-out needs a recorded reason: ${requirement}`);
+    }
+    const artifacts = (cells[cols["落地物"]] || "")
+      .split(",")
+      .map((value) => value.replaceAll("`", "").trim())
+      .filter((value) => value && value !== "-");
+    for (const rel of artifacts) {
+      if (!exists(rel)) problems.push(`requirement artifact missing: ${rel}`);
+    }
+  }
+  return problems;
+}
+
+/** Read the requirement ledger table, selecting the table that carries the ledger columns. */
+function readRequirementTable(root) {
+  const filePath = path.join(root, ...requirementPath.split("/"));
+  if (!fs.existsSync(filePath)) return { header: [], rows: [] };
+  const tables = readMarkdownTables(filePath);
+  const ledger = tables.find(
+    (table) => table.header.some((cell) => cell.includes("状态")) && table.header.some((cell) => cell.includes("证据或跳过"))
+  );
+  return ledger || tables[0] || { header: [], rows: [] };
+}
+
+/** Count requirement statuses and promotion candidates for the read-only loop report. */
+function summarizeLoop(root) {
+  const { header, rows } = readRequirementTable(root);
+  const cols = columnIndexes(header, ["状态", "需求"]);
+  const counts = Object.fromEntries(requirementStatuses.map((status) => [status, 0]));
+  for (const cells of rows) {
+    const status = cols["状态"] >= 0 ? (cells[cols["状态"]] || "").trim() : "";
+    if (Object.prototype.hasOwnProperty.call(counts, status)) counts[status] += 1;
+  }
+  const planRows = readIndexRows(root, "plans");
+  const plansWithStatus = planRows.filter((cells) => validStatuses.includes((cells[2] || "").trim()));
+  const plansDone = plansWithStatus.filter((cells) => (cells[2] || "").trim() === "done");
+  const learningIndex = path.join(root, ".copilot", "LEARNING_INDEX.md");
+  const learningTable = fs.existsSync(learningIndex) ? readMarkdownTable(learningIndex) : { header: [], rows: [] };
+  const cardCols = columnIndexes(learningTable.header, ["Card", "Confidence"]);
+  const candidates = learningTable.rows
+    .map((cells) => ({
+      name: ((cells[cardCols.Card] || "").match(/\[([^\]]+)\]/) || [])[1] || "",
+      confidence: Number((cells[cardCols.Confidence] || "").trim())
+    }))
+    .filter((card) => card.name && Number.isFinite(card.confidence) && card.confidence >= promotionConfidence);
+
+  return {
+    requirements: { total: rows.length, counts },
+    plans: { withStatus: plansWithStatus.length, done: plansDone.length },
+    features: readIndexRows(root, "features").length,
+    candidates
+  };
+}
+
+/** Run the read-only loop report: requirement counts, plan landing rate, feature rows, promotion candidates. */
+function runLoopReport(json) {
+  const summary = summarizeLoop(path.resolve(__dirname, ".."));
+  const counts = summary.requirements.counts;
+  const landingRate = summary.plans.withStatus
+    ? Math.round((summary.plans.done / summary.plans.withStatus) * 100)
+    : 0;
+  if (json) {
+    console.log(JSON.stringify({ checker: "devflow-loop", ...summary, landingRate, judgment: "PASS" }));
+    return 0;
+  }
+  console.log("DevFlow loop report");
+  console.log(`Requirements: total ${summary.requirements.total} | ${requirementStatuses.map((status) => `${status} ${counts[status]}`).join(" | ")}`);
+  console.log(`Plan landing: ${summary.plans.done}/${summary.plans.withStatus} with status (${landingRate}%)`);
+  console.log(`Feature rows: ${summary.features}`);
+  console.log(`Promotion candidates (confidence >= ${promotionConfidence}): ${summary.candidates.length}`);
+  for (const card of summary.candidates) console.log(`  - ${card.name} (${card.confidence})`);
+  console.log("Judgment: PASS");
+  return 0;
+}
+
+/** Dispatch the v2 and legacy plan contracts so old plans keep validating. */
 function checkPlan(body) {
+  return detectV2(body) ? checkPlanV2(body) : checkPlanLegacy(body);
+}
+
+/** Validate global plan headers and all independently scoped task contracts. */
+function checkPlanLegacy(body) {
   const fileStructure = checkFileStructure(body);
   const tasks = splitTasks(body);
   const requiresFileStructure = tasks.some((task) => fieldBlock(task.body, "Task type") === "Code change");
@@ -366,12 +750,21 @@ function report(body, filePath, json) {
     console.log(
       JSON.stringify({
         checker: "plan",
+        format: result.v2 ? "v2" : "legacy",
         landing: landing.message,
         status: result.status,
         invalidStatus: result.invalidStatus,
         missingGlobal: result.missingGlobal,
-        globalUnresolved: result.globalUnresolved,
-        fileStructure: result.fileStructure.ok ? "ok" : "missing or invalid",
+        globalUnresolved: result.globalUnresolved || [],
+        fileStructure: result.v2 ? "v2" : result.fileStructure.ok ? "ok" : "missing or invalid",
+        cut: result.v2 ? { missingRejected: result.cut.missingRejected } : null,
+        progress: result.v2
+          ? {
+              count: result.progress.count,
+              mismatch: result.progress.mismatch,
+              missingEvidence: result.progress.missingEvidence.length
+            }
+          : null,
         tasks: result.tasks.map((task) => ({ number: task.number, ok: task.ok })),
         judgment
       })
@@ -381,22 +774,43 @@ function report(body, filePath, json) {
 
   console.log("DevFlow plan pack report");
   console.log(landing.message);
+  console.log(`Format: ${result.v2 ? "v2" : "legacy"}`);
   console.log(`Status: ${result.invalidStatus ? "invalid" : result.status}`);
-  for (const field of requiredGlobalFields) console.log(`${field}: ${result.missingGlobal.includes(field) ? "missing" : "ok"}`);
-  console.log(`Global unresolved markers: ${result.globalUnresolved.join(", ") || "none"}`);
-  console.log(
-    `File Structure: ${
-      !result.requiresFileStructure ? "documentation-only exception" : result.fileStructure.ok ? "ok" : "missing or invalid"
-    }`
-  );
-  if (result.requiresFileStructure && !result.fileStructure.ok) {
-    console.log(`File Structure invalid rows: ${result.fileStructure.invalidRows.join("; ") || "none"}`);
+  for (const field of result.v2 ? v2GlobalFields : requiredGlobalFields) {
+    console.log(`${field}: ${result.missingGlobal.includes(field) ? "missing" : "ok"}`);
+  }
+  if (result.v2) {
+    console.log(`Cut Rejected: ${result.cut.missingRejected ? "missing" : "ok"}`);
+    console.log(`Progress rows: ${result.progress.count} (tasks ${result.tasks.length})${result.progress.mismatch ? " mismatch" : ""}`);
+    for (const row of result.progress.missingEvidence) console.log(`Progress row ${row.number} is done without evidence`);
+    if (result.doneStatusNeedsAllDone) console.log("Status done requires every Progress row done");
+  } else {
+    console.log(`Global unresolved markers: ${result.globalUnresolved.join(", ") || "none"}`);
+    console.log(
+      `File Structure: ${
+        !result.requiresFileStructure ? "documentation-only exception" : result.fileStructure.ok ? "ok" : "missing or invalid"
+      }`
+    );
+    if (result.requiresFileStructure && !result.fileStructure.ok) {
+      console.log(`File Structure invalid rows: ${result.fileStructure.invalidRows.join("; ") || "none"}`);
+    }
   }
   console.log(`Tasks: ${result.tasks.length}`);
   if (result.tasks.length === 0) console.log("Missing: at least one Task field");
 
   for (const task of result.tasks) {
-    const issues = [
+    const issues = result.v2
+      ? [
+          ...task.missing.map((field) => `missing ${field}`),
+          ...task.unresolved.map((match) => `unresolved ${match}`),
+          ...task.vague.map((match) => `vague ${match}`),
+          ...task.invalidFiles.map((line) => `unclassified file ${line}`),
+          ...task.unlocatedCodeFiles.map((line) => `missing file symbol/anchor ${line}`),
+          ...(task.missingChange ? ["Change needs an executable intent verb"] : []),
+          ...(task.missingNotDoing ? ["missing Not doing exclusion"] : []),
+          ...(task.incompleteVerification ? ["Verify needs command/scenario and expected result"] : [])
+        ]
+      : [
       ...task.missing.map((field) => `missing ${field}`),
       ...task.unresolved.map((match) => `unresolved ${match}`),
       ...task.vague.map((match) => `vague ${match}`),
@@ -621,8 +1035,61 @@ function selfTest() {
   if (!checkPlanLanding("docs/plans/2026-07-14-add-plan-scanner.md").ok) throw new Error("Self-test expected docs/plans landing to pass");
   if (checkPlanLanding("docs/features/add-plan-scanner.md").ok) throw new Error("Self-test expected docs/features plan landing to fail");
 
+  const validV2Plan = [
+    "Status: approved",
+    "Goal: validate the slim v2 plan contract",
+    "Not doing: architecture review",
+    "Cut: 做 checker | 不做 迁移旧计划 | 复用 既有 self-test | 验证 node scripts/devflow-plan.js | Rejected: 新增独立脚本 — 复用既有 checker",
+    "## Tasks",
+    "",
+    "Task: Add v2 validation",
+    "Files:",
+    "- Modify: scripts/devflow-plan.js | symbol: `checkPlanV2` | validate the slim contract",
+    "Change: add v2 field validation and dispatch",
+    "Acceptance: v2 plans pass and legacy plans keep passing",
+    "Verify: run `node scripts/devflow-plan.js --self-test` expect exit 0",
+    "Not doing: changing legacy validation",
+    "",
+    "## Progress",
+    "",
+    "| # | Task | Status | Evidence |",
+    "|---|---|---|---|",
+    "| 1 | Add v2 validation | todo | - |"
+  ].join("\n");
+  if (!detectV2(validV2Plan)) throw new Error("Self-test expected v2 detection to pass");
+  if (!checkPlan(validV2Plan).ok) throw new Error("Self-test expected valid v2 plan to pass");
+  if (checkPlan(validV2Plan.replace(/Rejected:[^\n]*/, "Rejected:")).ok) throw new Error("Self-test expected missing Rejected to fail");
+  if (checkPlan(validV2Plan.replace("| 1 | Add v2 validation | todo | - |", "| 1 | Add v2 validation | done | - |")).ok) {
+    throw new Error("Self-test expected a done Progress row without evidence to fail");
+  }
+  if (checkPlan(validV2Plan.replace("| 1 | Add v2 validation | todo | - |", "")).ok) {
+    throw new Error("Self-test expected a Progress/task count mismatch to fail");
+  }
+  if (typeof checkIndexes !== "function") throw new Error("Self-test expected the index checker to exist");
+  if (matchIndexRows([["功能A", "计划相关", "x"]], "计划").length !== 1) throw new Error("Self-test expected index query to match a row");
+  if (matchIndexRows([["功能A", "计划相关", "x"]], "不存在").length !== 0) throw new Error("Self-test expected index query to miss");
+  if (matchIndexRows([["功能A"]], "").length !== 0) throw new Error("Self-test expected an empty index query to match nothing");
+  if (argValue(["--index", "--query", "计划"], "--query") !== "计划") throw new Error("Self-test expected --query to read its value");
+  if (argValue(["--index", "--query", "--json"], "--query") !== "") throw new Error("Self-test expected --query to reject a flag as its value");
+
+  const requirementHeader = ["日期", "需求", "来源", "深度", "落地物", "状态", "证据或跳过", "更新日"];
+  const requirementRows = [
+    ["2026-09-10", "已落地需求", "用户请求", "A", "docs/specs/x.md", "landed", "npm test 通过", "2026-09-10"],
+    ["2026-09-10", "跳过文档需求", "用户请求", "C", "-", "opt-out", "原因：用户显式跳过", "2026-09-10"]
+  ];
+  const requirementProblems = checkRequirementTable(requirementHeader, requirementRows, () => true);
+  if (requirementProblems.length !== 0) throw new Error(`Self-test expected a valid requirement table to pass: ${requirementProblems.join("; ")}`);
+  const badStatus = checkRequirementTable(requirementHeader, [["2026-09-10", "状态非法", "用户请求", "A", "-", "shipped", "证据", "2026-09-10"]], () => true);
+  if (badStatus.length === 0) throw new Error("Self-test expected an invalid requirement status to fail");
+  const missingEvidence = checkRequirementTable(requirementHeader, [["2026-09-10", "终态无证据", "用户请求", "A", "-", "landed", "-", "2026-09-10"]], () => true);
+  if (missingEvidence.length === 0) throw new Error("Self-test expected a terminal requirement without evidence to fail");
+  const missingReason = checkRequirementTable(requirementHeader, [["2026-09-10", "跳过无原因", "用户请求", "C", "-", "opt-out", "验证通过", "2026-09-10"]], () => true);
+  if (missingReason.length === 0) throw new Error("Self-test expected an opt-out without a reason to fail");
+  const missingArtifact = checkRequirementTable(requirementHeader, [["2026-09-10", "落地物不存在", "用户请求", "A", "docs/specs/nope.md", "planned", "-", "2026-09-10"]], () => false);
+  if (missingArtifact.length === 0) throw new Error("Self-test expected a missing requirement artifact to fail");
+
   console.log("DevFlow plan self-test passed");
-  console.log("Checked code-level fields, precise file locations, mechanics evidence, verification expectations, Read-basis/Live anchors handoff facts, documentation-only exception, external-skill declaration, and plan landing guidance");
+  console.log("Checked v2 and legacy plan contracts, Progress evidence, Cut Rejected, code-level fields, precise file locations, verification expectations, documentation-only exception, external-skill declaration, and plan landing guidance");
 }
 
 const args = process.argv.slice(2);
@@ -634,5 +1101,11 @@ if (args.includes("--self-test")) {
   selfTest();
   process.exit(0);
 }
+if (args.includes("--loop")) {
+  process.exit(runLoopReport(args.includes("--json")));
+}
+if (args.includes("--index")) {
+  process.exit(runIndexCheck(args.includes("--json"), argValue(args, "--query")));
+}
 const targetArg = args.find((arg) => !arg.startsWith("-"));
 process.exitCode = report(readInput(args), targetArg, args.includes("--json"));