@devflow-core/dsh-devflow 0.5.0 → 0.6.1

package/assets/commands/devflow.toml

@@ -12,7 +12,7 @@ Use Fast for pure Q&A, fact lookup, verification, or an already approved trivial
 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.
+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.

package/assets/presets/devflow-2/agent.cordis.yml

@@ -66,7 +66,7 @@
 - id: persona
   name: '@deepseek-ai/dsh-persona'
   config:
-    text: |-
+    prefix: |-
       You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.
 
       You run DevFlow. Before any development work — creating features, building components, adding functionality, modifying behavior, or defining an unapproved problem-directed change — load the `devflow-core` skill with the skill tool and read its `core-methods.md` reference, then load only the selected lifecycle owner skill. The route table and hard boundaries live in that skill and in AGENTS.md; do not invent lifecycle details. Pure Q&A, lookup, verification, and investigation-only reports need no lifecycle.

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"));

package/assets/skills/devflow-brainstorm/SKILL.md

@@ -122,6 +122,8 @@ Confirmed request:
 
 The summary records the agreed request and the exploration findings only. It must not contain an implementation plan, solution-space design, lifecycle route, or handoff instruction. It is the factual basis that downstream skills — starting with `devflow-spec` — build on, so record findings faithfully rather than trimming them away.
 
+On `Status: clarified`, create or update the requirement row in `docs/requirements.md` with status `open`; depth is recorded when the lifecycle path is chosen. Pure Q&A, lookup, and read-only verification create no row.
+
 ## A/B/C Gate
 
 After the fixed summary, present these choices and wait for one explicit user selection:

package/assets/skills/devflow-build/SKILL.md

@@ -19,7 +19,7 @@ When no plan file exists, the approved design and Cut Decision form the Build Co
 
 Load `skills/devflow-build/references/build-methods.md` after this section and before implementation slices. It owns the detailed minimal-change and slice discipline.
 
-There is no broad pre-edit plan review. The executor reads only the current task's execution spec — `Files`, `Change mechanics`, `Steps`, `Verify` — and must reread the current task's named anchors. A current task anchor plus a directly changed neighbor may be reread only when that neighbor is already listed in the task `Files` and its contract could invalidate the edit. An actual edit, anchor mismatch, or verification failure must stop and return `BUILD_BLOCKED` with facts to `devflow-core`: observed mismatch, affected anchor, and smallest replan decision. Do not broadly rediscover, guess, silently repair the plan, or expand scope.
+There is no broad pre-edit plan review. The executor reads the current task's `Files`, `Change`, `Acceptance`, `Verify`, and `Not doing`, and may read the task's named anchors plus one directly changed neighbor to choose the smallest implementation. Build owns how inside the task boundary; it must not broadly rediscover the repository, redesign outside the task boundary, silently repair the plan, or expand scope. An anchor mismatch or verification failure must stop and return `BUILD_BLOCKED` with facts to `devflow-core`: observed mismatch, affected anchor, and smallest replan decision.
 
 Every skill declared in `External Skills` (Cut Decision or plan header) must actually be loaded through the platform's skill mechanism, or the reason it does not apply recorded; loading alone is not completion — Build requires the specialist's returned result, not-applicable, or failure facts. A specialist result implying structure outside the approved scope returns scope-drift facts to `devflow-core`, not silent adoption. Skill loading is not a pre-edit view and remains mandatory.
 
@@ -44,9 +44,11 @@ If work touches more than one file or one logical step, create Implementation Sl
 
 When saving a plan file, use `docs/plans/YYYY-MM-DD-<short-kebab-name>.md`, resolved from the current target project's root, unless that project already documents another plan/spec path. Do not save implementation plans under `docs/features/`; that directory is for feature ledgers.
 
-For multi-step work, tasks must cite the approved source, be small and verifiable, and follow the required task contract (Task: / Task type: / Files: / Interfaces: / Current behavior: / Target behavior: / Change mechanics: / Call impact: / Steps: / Acceptance: / Verify: / Comments: / Not doing:) defined in `skills/devflow-plan/SKILL.md`.
+For multi-step work, tasks must cite the approved source, be small and verifiable, and follow the six-field contract (`Task` / `Files` / `Change` / `Acceptance` / `Verify` / `Not doing`) in `skills/devflow-plan/SKILL.md`. Legacy plans with `Change mechanics` and `Prewalk` stay executable under their own contract.
 
-No unresolved markers. For `Code change`, the dispatched execution spec follows the recorded file symbol/anchor and `Change mechanics`; do not re-decide the implementation mechanism in Build. `Current behavior`, `Target behavior`, and `Call impact` are the plan author's records; bounded current-anchor/neighbor reread is allowed only for drift detection. The verification step must retain its trigger/input, expected result, and command or manual scenario. `Documentation-only` applies only to tasks with no runtime code files and explicit `documentation-only` interfaces. No "add tests" without naming the behavior. No "handle edge cases" without naming the edge case. No "similar to Task N" shortcuts; repeat enough detail for each task to stand alone.
+No unresolved markers. `Change` states the executable intent and boundary; add exact mechanics only when the change crosses a module contract, is irreversible, or touches security or data boundaries. Otherwise Build chooses the smallest implementation and records it as Progress evidence. The verification step keeps its trigger/input, expected result, and command or manual scenario. A task whose files are all documentation paths is documentation-only. No "add tests" without naming the behavior, no "handle edge cases" without naming the edge case, no "similar to Task N" shortcuts.
+
+Close each task by writing back its `## Progress` row: `doing` when starting, `done` with the command and key result when its `Verify` passes. A `done` row without evidence fails the checker. On a legacy plan without a Progress table, report the same evidence in the completion message. When every task is `done`, advance the requirement row in `docs/requirements.md` to `built`.
 
 Before Build, run `node scripts/devflow-plan.js <plan-file>` when a plan is saved to a file. If not found at `scripts/devflow-plan.js` (project-level), try `~/.codex/scripts/devflow-plan.js` or `~/.claude/scripts/devflow-plan.js` (user-level). Do NOT look under `skills/scripts/`. See `core-methods.md` Script Path Resolution.
 
@@ -191,7 +193,7 @@ If any file has no goal link, remove that change.
 | "We'll verify everything at the end." | Verify slices when focused checks exist. |
 | "Docs changes do not need proof." | Docs/rules/skills need validation just like code. |
 | "The issue only mentions one caller." | Check sibling callers before choosing the fix location. |
-| "The plan is approved, so I just execute." | Right: the approved execution spec is edited directly; an actual edit or verification failure returns `BUILD_BLOCKED` to Core. |
+| "The plan is approved, so I just execute." | The plan fixes the boundary and proof; Build still chooses the smallest implementation inside that boundary. A real edit or verification failure returns `BUILD_BLOCKED` to Core. |
 | "I'll infer the missing step." | Guessing past a gap is forbidden; unclear instructions return `BUILD_BLOCKED` facts. |
 | "The code is self-explanatory." | That does not waive a comment required by the approved contract, project convention, or a non-obvious boundary. |
 | "Comments will get stale." | Keep a required comment accurate or remove a stale one; a stale explanation is not a reason to skip a needed decision record. |