@xenonbyte/da-vinci-workflow 0.1.24 → 0.1.25

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v0.1.25 - 2026-03-29
+
+### Added
+- `scripts/test-audit-design-supervisor.js` now covers Chinese legacy review headings (for example `## Design-Supervisor Review（第2轮尝试）`) and ensures structured fallback parsing remains deterministic
+- `scripts/test-pen-persistence.js` now verifies metadata-payload error paths prefer concise relative paths when `--nodes-file` is under current working directory
+
+### Changed
+- `pen-persistence` now formats `--nodes-file` metadata-payload error locations using relative paths when possible (absolute path fallback when outside cwd)
+- design-supervisor heading parsing now accepts both ASCII and full-width parentheses in heading suffixes
+- legacy round-attempt heading detection now supports both English `Round ... Attempt` and Chinese `第N轮尝试` variants
+
 ## v0.1.24 - 2026-03-29
 
 ### Added
@@ -9,7 +20,7 @@
 - `scripts/test-supervisor-review-integration.js` optional real `codex exec` smoke test (`DA_VINCI_RUN_SUPERVISOR_INTEGRATION=1`)
 
 ### Changed
-- supervisor-review audit parsing now accepts latest `## Design-Supervisor Review (Round X Attempt)` sections, multiline issue/outcome fields, and `Result` as a status alias
+- supervisor-review audit parsing now prefers the latest structured `## Design-Supervisor Review` block, warns when the newest entry is a legacy/non-structured round attempt, and still supports multiline issue/outcome fields plus `Result` as a status alias
 - completion audit now enforces skill-backed supervisor evidence (`Review source: skill` + executed configured reviewers) when `Require Supervisor Review: true`
 - design prompts/skill docs now require configured reviewer skills to actually execute review before writing supervisor results
 - command references and constraint docs (EN/ZH) now document structured reviewer fields and required skill-backed behavior for hard-gate projects

package/README.md

@@ -28,12 +28,14 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.24`
+- `@xenonbyte/da-vinci-workflow@0.1.25`
 
 Release highlights:
 
 - `da-vinci supervisor-review --run-reviewers` now supports configurable parallel reviewer execution and resilient retry backoff (`--review-concurrency`, `--review-retries`, `--review-retry-delay-ms`)
 - added optional `test:supervisor-review-integration` smoke coverage for real `codex exec` review runner flows (enabled via `DA_VINCI_RUN_SUPERVISOR_INTEGRATION=1`)
+- supervisor-review parsing now explicitly handles legacy Chinese round-attempt headings (for example `## Design-Supervisor Review（第2轮尝试）`) and keeps canonical structured review fallback deterministic
+- `--nodes-file` metadata-payload guard now reports shorter relative file paths when possible, while preserving absolute-path fallback outside current working directory
 - audit parser logic is now split into `lib/audit-parsers.js`, reducing `lib/audit.js` size and making maintenance safer
 - recursive file traversal now uses bounded safe scans with depth/count limits and symlink skipping
 - completion/integrity audit now rejects out-of-root `.pen` references from `design-registry.md`

package/README.zh-CN.md

@@ -30,12 +30,14 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.24`
+- `@xenonbyte/da-vinci-workflow@0.1.25`
 
 已发布版本重点：
 
 - `da-vinci supervisor-review --run-reviewers` 现已支持 reviewer 并发执行与失败重试退避（`--review-concurrency`、`--review-retries`、`--review-retry-delay-ms`）
 - 新增可选 `test:supervisor-review-integration` 烟测，用于覆盖真实 `codex exec` 评审执行链路（通过 `DA_VINCI_RUN_SUPERVISOR_INTEGRATION=1` 启用）
+- supervisor-review 解析现已显式覆盖中文 legacy 轮次标题（例如 `## Design-Supervisor Review（第2轮尝试）`），并保持“优先结构化评审块”的回退策略可预测
+- `--nodes-file` 元数据误传保护现在优先输出更短的相对路径（在 cwd 外仍回退绝对路径），便于日志阅读
 - audit 解析职责已拆分到 `lib/audit-parsers.js`，`lib/audit.js` 体量下降，可维护性更好
 - 递归文件扫描改为安全有界遍历：增加深度/数量上限，并跳过符号链接
 - completion/integrity audit 现在会拦截并忽略 `design-registry.md` 中越出项目根目录的 `.pen` 引用

package/SKILL.md

@@ -283,6 +283,7 @@ During active Pencil work:
 - if `DA-VINCI.md` declares `Design-supervisor reviewers`, run an explicit review pass with those reviewer skills on the approved anchor set, then persist the structured result with `da-vinci supervisor-review --project <project-path> --change <change-id> --run-reviewers --write` (or the compatibility alias `design-supervisor review --run-reviewers --write`)
 - keep `Design-supervisor reviewers` separate from `Preferred adapters`; adapters lead the design pass, reviewers judge whether the final style quality is strong enough to expand or implement
 - when `design-supervisor review` is active, review screenshots together with Pencil theme variables, `visual-thesis.md`, `content-plan.md`, and `interaction-thesis.md`; record `Configured reviewers`, `Executed reviewers`, `Review source`, explicit `PASS`/`WARN`/`BLOCK`, issue list, and revision outcome in `pencil-design.md`
+- do not hand-write ad-hoc headings such as `## Design-Supervisor Review (Round X Attempt)`; use `da-vinci supervisor-review --write` (or overwrite the canonical `## Design-Supervisor Review` block) so audit can consume structured evidence deterministically
 - if `DA-VINCI.md` sets `Require Supervisor Review: true`, treat missing, blocked, or unaccepted `design-supervisor review` as a blocker before broad expansion, implementation-task handoff, or terminal completion
 
 ## Load References On Demand

package/commands/claude/dv/design.md

@@ -26,5 +26,5 @@ If a registered project-local `.pen` already exists, reopen it for continuity bu
 After the first successful Pencil write, run `da-vinci audit --mode integrity <project-path>` before broad expansion continues.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the issue list and revision outcome; "looks good" is not a valid review record.
-If `DA-VINCI.md` declares `Design-supervisor reviewers`, execute those reviewer skills on the approved anchor screenshots (do not skip to inferred review), then persist the structured result via `da-vinci supervisor-review --project <project-path> --change <change-id> --run-reviewers --write` (or the compatibility alias `design-supervisor review --run-reviewers --write`). Record configured/ executed reviewers, review source, status, issue list, and revision outcome in `pencil-design.md`. If `Require Supervisor Review: true`, treat missing, blocked, unaccepted, or non-skill-backed review results as blocking before broad expansion or terminal completion.
+If `DA-VINCI.md` declares `Design-supervisor reviewers`, execute those reviewer skills on the approved anchor screenshots (do not skip to inferred review), then persist the structured result via `da-vinci supervisor-review --project <project-path> --change <change-id> --run-reviewers --write` (or the compatibility alias `design-supervisor review --run-reviewers --write`). Record configured/ executed reviewers, review source, status, issue list, and revision outcome in `pencil-design.md`. Do not add ad-hoc headings like `## Design-Supervisor Review (Round X Attempt)`; keep a canonical structured section so audit can parse it deterministically. If `Require Supervisor Review: true`, treat missing, blocked, unaccepted, or non-skill-backed review results as blocking before broad expansion or terminal completion.
 Before reporting `design complete` or `workflow complete`, run `da-vinci audit --mode completion --change <change-id> <project-path>` and treat any failure as blocking.

package/commands/codex/prompts/dv-design.md

@@ -20,5 +20,5 @@ If a registered project-local `.pen` already exists, reopen it for continuity bu
 After the first successful Pencil write, run `da-vinci audit --mode integrity <project-path>` before broad expansion continues.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the issue list and revision outcome; "looks good" is not a valid review record.
-If `DA-VINCI.md` declares `Design-supervisor reviewers`, execute those reviewer skills on the approved anchor screenshots (do not skip to inferred review), then persist the structured result via `da-vinci supervisor-review --project <project-path> --change <change-id> --run-reviewers --write` (or the compatibility alias `design-supervisor review --run-reviewers --write`). Record configured/ executed reviewers, review source, status, issue list, and revision outcome in `pencil-design.md`. If `Require Supervisor Review: true`, treat missing, blocked, unaccepted, or non-skill-backed review results as blocking before broad expansion or terminal completion.
+If `DA-VINCI.md` declares `Design-supervisor reviewers`, execute those reviewer skills on the approved anchor screenshots (do not skip to inferred review), then persist the structured result via `da-vinci supervisor-review --project <project-path> --change <change-id> --run-reviewers --write` (or the compatibility alias `design-supervisor review --run-reviewers --write`). Record configured/ executed reviewers, review source, status, issue list, and revision outcome in `pencil-design.md`. Do not add ad-hoc headings like `## Design-Supervisor Review (Round X Attempt)`; keep a canonical structured section so audit can parse it deterministically. If `Require Supervisor Review: true`, treat missing, blocked, unaccepted, or non-skill-backed review results as blocking before broad expansion or terminal completion.
 Before claiming `design complete` or `workflow complete`, run `da-vinci audit --mode completion --change <change-id> <project-path>` and treat any failure as blocking.

package/commands/gemini/dv/design.toml

@@ -19,6 +19,6 @@ If a registered project-local `.pen` already exists, reopen it for continuity bu
 After the first successful Pencil write, run `da-vinci audit --mode integrity <project-path>` before broad expansion continues.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the issue list and revision outcome; "looks good" is not a valid review record.
-If `DA-VINCI.md` declares `Design-supervisor reviewers`, execute those reviewer skills on the approved anchor screenshots (do not skip to inferred review), then persist the structured result via `da-vinci supervisor-review --project <project-path> --change <change-id> --run-reviewers --write` (or the compatibility alias `design-supervisor review --run-reviewers --write`). Record configured/ executed reviewers, review source, status, issue list, and revision outcome in `pencil-design.md`. If `Require Supervisor Review: true`, treat missing, blocked, unaccepted, or non-skill-backed review results as blocking before broad expansion or terminal completion.
+If `DA-VINCI.md` declares `Design-supervisor reviewers`, execute those reviewer skills on the approved anchor screenshots (do not skip to inferred review), then persist the structured result via `da-vinci supervisor-review --project <project-path> --change <change-id> --run-reviewers --write` (or the compatibility alias `design-supervisor review --run-reviewers --write`). Record configured/ executed reviewers, review source, status, issue list, and revision outcome in `pencil-design.md`. Do not add ad-hoc headings like `## Design-Supervisor Review (Round X Attempt)`; keep a canonical structured section so audit can parse it deterministically. If `Require Supervisor Review: true`, treat missing, blocked, unaccepted, or non-skill-backed review results as blocking before broad expansion or terminal completion.
 Before reporting `design complete` or `workflow complete`, run `da-vinci audit --mode completion --change <change-id> <project-path>` and treat any failure as blocking.
 """

package/docs/constraint-files.md

@@ -46,6 +46,7 @@ The workflow audit currently parses specific fields. Keep these names stable.
 - `Revision outcome`
 
 When supervisor review is required, missing, blocked, unaccepted, or non-skill-backed review evidence blocks completion.
+Avoid ad-hoc headings such as `## Design-Supervisor Review (Round X Attempt)`; keep a canonical structured supervisor-review section (prefer `da-vinci supervisor-review --write`) so audit can parse the latest review deterministically.
 
 ## Advisory Constraint Sections (Customizable)
 

package/docs/zh-CN/constraint-files.md

@@ -48,6 +48,7 @@
 - `Revision outcome`
 
 当 supervisor review 是必需时，缺失、`BLOCK`、未接受、或非 skill-backed 的评审证据都会阻断 completion。
+避免写临时标题（例如 `## Design-Supervisor Review (Round X Attempt)`）；应保持规范化、结构化的 supervisor-review 段（优先使用 `da-vinci supervisor-review --write`），这样 audit 才能稳定解析最新评审证据。
 
 ## 指导型约束段（可定制）
 

package/lib/audit-parsers.js

@@ -39,7 +39,9 @@ function getMarkdownSectionsByHeading(text, heading, options = {}) {
 
   const escapedHeading = escapeRegExp(heading);
   const allowParentheticalSuffix = options.allowParentheticalSuffix === true;
-  const suffixPattern = allowParentheticalSuffix ? String.raw`(?:\s*\([^)\n]*\))?` : "";
+  const suffixPattern = allowParentheticalSuffix
+    ? String.raw`(?:\s*[（(][^)）\n]*[)）])?`
+    : "";
   const headingPattern = new RegExp(`^##\\s+${escapedHeading}${suffixPattern}\\s*$`, "i");
   const anyHeadingPattern = /^##\s+/;
   const lines = String(text).replace(/\r\n?/g, "\n").split("\n");
@@ -547,39 +549,89 @@ function inspectDesignSupervisorReview(pencilDesignText) {
       status: null,
       acceptedWarn: false,
       hasIssueList: false,
-      hasRevisionOutcome: false
+      hasRevisionOutcome: false,
+      selectedFromLatest: true,
+      usedStructuredSectionFallback: false,
+      latestSectionLooksLegacyAttempt: false,
+      latestSectionStructuredFieldPresent: false,
+      selectedSectionHeading: "",
+      selectedSectionLooksLegacyAttempt: false
     };
   }
 
-  const section = sections[sections.length - 1].content;
-  const statusMatch = section.match(
-    /(?:^|\n)\s*-\s*(?:Status|状态|Result|结果)\s*:\s*`?(PASS|WARN|BLOCK)`?\b/i
-  );
-  const status = statusMatch ? statusMatch[1].toUpperCase() : null;
-  const issueList = extractReviewFieldValue(section, ["Issue list", "问题列表"]);
-  const revisionOutcome = extractReviewFieldValue(section, ["Revision outcome", "修订结果"]);
-  const configuredReviewersRaw = extractReviewFieldValue(section, ["Configured reviewers", "配置评审"]);
-  const executedReviewersRaw = extractReviewFieldValue(section, ["Executed reviewers", "Executed reviewer skills", "执行评审"]);
-  const reviewSource = extractReviewFieldValue(section, ["Review source", "评审来源"]).toLowerCase();
-  const acceptedWarn =
-    status === "WARN" &&
-    /(accepted|accepted with follow-up|accepted warning|warn accepted|接受|已接受|接受警告)/i.test(
-      revisionOutcome
+  const legacyRoundAttemptPattern =
+    /[（(]\s*(?:round[^)\n）]*attempt|第?\s*[0-9一二三四五六七八九十百零两]+\s*轮\s*尝试)\s*[)）]/i;
+  const parsedSections = sections.map((sectionRecord, index) => {
+    const section = sectionRecord.content;
+    const statusMatch = section.match(
+      /(?:^|\n)\s*-\s*(?:Status|状态|Result|结果)\s*:\s*`?(PASS|WARN|BLOCK)`?\b/i
     );
-  const configuredReviewers = parseListTokens(configuredReviewersRaw);
-  const executedReviewers = parseListTokens(executedReviewersRaw);
+    const status = statusMatch ? statusMatch[1].toUpperCase() : null;
+    const issueList = extractReviewFieldValue(section, ["Issue list", "问题列表"]);
+    const revisionOutcome = extractReviewFieldValue(section, ["Revision outcome", "修订结果"]);
+    const configuredReviewersRaw = extractReviewFieldValue(section, ["Configured reviewers", "配置评审"]);
+    const executedReviewersRaw = extractReviewFieldValue(section, [
+      "Executed reviewers",
+      "Executed reviewer skills",
+      "执行评审"
+    ]);
+    const reviewSource = extractReviewFieldValue(section, ["Review source", "评审来源"]).toLowerCase();
+    const configuredReviewers = parseListTokens(configuredReviewersRaw);
+    const executedReviewers = parseListTokens(executedReviewersRaw);
+    const hasConfiguredField = /(?:^|\n)\s*-\s*(?:Configured reviewers|配置评审)\s*:/i.test(section);
+    const hasExecutedField = /(?:^|\n)\s*-\s*(?:Executed reviewers|Executed reviewer skills|执行评审)\s*:/i.test(section);
+    const hasReviewSourceField = /(?:^|\n)\s*-\s*(?:Review source|评审来源)\s*:/i.test(section);
+    const structuredFieldPresent = hasConfiguredField || hasExecutedField || hasReviewSourceField;
+    const acceptedWarn =
+      status === "WARN" &&
+      /(accepted|accepted with follow-up|accepted warning|warn accepted|接受|已接受|接受警告)/i.test(
+        revisionOutcome
+      );
+    return {
+      index,
+      heading: sectionRecord.heading,
+      status,
+      issueList,
+      revisionOutcome,
+      configuredReviewers,
+      executedReviewers,
+      reviewSource,
+      acceptedWarn,
+      hasIssueList: Boolean(issueList),
+      hasRevisionOutcome: Boolean(revisionOutcome),
+      hasConfiguredReviewers: configuredReviewers.length > 0,
+      hasExecutedReviewers: executedReviewers.length > 0,
+      structuredFieldPresent,
+      looksLegacyRoundAttempt: legacyRoundAttemptPattern.test(sectionRecord.heading)
+    };
+  });
+
+  const latestSection = parsedSections[parsedSections.length - 1];
+  const selectedSection =
+    [...parsedSections].reverse().find((section) => section.structuredFieldPresent) || latestSection;
+  const selectedFromLatest = selectedSection.index === latestSection.index;
+  const usedStructuredSectionFallback =
+    !selectedFromLatest &&
+    latestSection.structuredFieldPresent === false &&
+    selectedSection.structuredFieldPresent === true;
 
   return {
     found: true,
-    status,
-    acceptedWarn,
-    hasIssueList: Boolean(issueList),
-    hasRevisionOutcome: Boolean(revisionOutcome),
-    configuredReviewers,
-    executedReviewers,
-    reviewSource,
-    hasConfiguredReviewers: configuredReviewers.length > 0,
-    hasExecutedReviewers: executedReviewers.length > 0
+    status: selectedSection.status,
+    acceptedWarn: selectedSection.acceptedWarn,
+    hasIssueList: selectedSection.hasIssueList,
+    hasRevisionOutcome: selectedSection.hasRevisionOutcome,
+    configuredReviewers: selectedSection.configuredReviewers,
+    executedReviewers: selectedSection.executedReviewers,
+    reviewSource: selectedSection.reviewSource,
+    hasConfiguredReviewers: selectedSection.hasConfiguredReviewers,
+    hasExecutedReviewers: selectedSection.hasExecutedReviewers,
+    selectedFromLatest,
+    usedStructuredSectionFallback,
+    latestSectionLooksLegacyAttempt: latestSection.looksLegacyRoundAttempt,
+    latestSectionStructuredFieldPresent: latestSection.structuredFieldPresent,
+    selectedSectionHeading: selectedSection.heading,
+    selectedSectionLooksLegacyAttempt: selectedSection.looksLegacyRoundAttempt
   };
 }
 

package/lib/audit.js

@@ -474,6 +474,13 @@ function auditProject(projectPathInput, options = {}) {
       const enforceAsFailure =
         mode === "completion" && scopedChangeDirs.includes(changeDir) && designSupervisorRequired;
 
+      if (review.usedStructuredSectionFallback) {
+        warnings.push(
+          `Latest design-supervisor review entry in ${relativeTo(projectRoot, pencilDesignPath)} ` +
+            `is a legacy/non-structured format; gate evaluation used ${review.selectedSectionHeading}.`
+        );
+      }
+
       let reviewRecordValid = true;
 
       if (!review.found) {

package/lib/pen-persistence.js

@@ -110,7 +110,52 @@ function hasTruncatedChildren(value) {
   return Object.values(value).some((item) => hasTruncatedChildren(item));
 }
 
+function looksLikePenStatePayload(payload) {
+  if (!isPlainObject(payload)) {
+    return false;
+  }
+
+  const hasLiveNodes = Array.isArray(payload.nodes);
+  if (hasLiveNodes) {
+    return false;
+  }
+
+  const hasSnapshotHash = typeof payload.snapshotHash === "string" && payload.snapshotHash.length > 0;
+  const hasPenPath = typeof payload.penPath === "string" && payload.penPath.length > 0;
+  const hasStateCounters =
+    Object.prototype.hasOwnProperty.call(payload, "topLevelCount") ||
+    Object.prototype.hasOwnProperty.call(payload, "topLevelIds");
+  return hasSnapshotHash && hasPenPath && hasStateCounters;
+}
+
+function assertNodesPayloadIsLiveSnapshot(payload, sourcePath) {
+  if (!looksLikePenStatePayload(payload)) {
+    return;
+  }
+
+  const location = sourcePath ? ` (${formatPathForError(sourcePath)})` : "";
+  throw new Error(
+    `\`--nodes-file\` payload${location} appears to be pen state metadata, not a live MCP nodes snapshot. ` +
+      "Use JSON from `batch_get` (an array or an object with `nodes`)."
+  );
+}
+
+function formatPathForError(sourcePath) {
+  const resolved = path.resolve(sourcePath);
+  const relative = path.relative(process.cwd(), resolved);
+  if (!relative || relative === "") {
+    return ".";
+  }
+
+  if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
+    return relative;
+  }
+
+  return resolved;
+}
+
 function normalizeNodesPayload(payload) {
+  assertNodesPayloadIsLiveSnapshot(payload);
   const nodes = getNodesArray(payload);
 
   if (!nodes) {
@@ -318,6 +363,7 @@ function verifyPenFileWithPencil(filePath, options = {}) {
 function writePenFromPayloadFiles(options) {
   const outputPath = path.resolve(options.outputPath);
   const nodes = readJsonPayload(options.nodesFile);
+  assertNodesPayloadIsLiveSnapshot(nodes, options.nodesFile);
   const variables = options.variablesFile ? readJsonPayload(options.variablesFile) : undefined;
   const document = buildPenDocument({
     version: options.version || DEFAULT_PEN_VERSION,
@@ -447,6 +493,7 @@ function ensurePenFile(options) {
 
 function hashPayloadFiles(options) {
   const nodes = readJsonPayload(options.nodesFile);
+  assertNodesPayloadIsLiveSnapshot(nodes, options.nodesFile);
   const variables = options.variablesFile ? readJsonPayload(options.variablesFile) : undefined;
   const document = buildPenDocument({
     version: options.version || DEFAULT_PEN_VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/da-vinci-workflow",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "Requirement-to-design-to-code workflow skill for Codex, Claude, and Gemini",
   "bin": {
     "da-vinci": "bin/da-vinci.js",

package/references/artifact-templates.md

@@ -569,6 +569,7 @@ Use this structure:
 - Revision outcome
 - Whether broad expansion is approved
 - Whether implementation-task handoff is approved
+- Keep one canonical structured supervisor-review section; avoid ad-hoc headings such as `## Design-Supervisor Review (Round X Attempt)`
 
 ## Anchor Surfaces
 - Which 1-3 anchor screens were designed first

package/scripts/test-audit-design-supervisor.js

@@ -5,6 +5,7 @@ const path = require("path");
 const { spawnSync } = require("child_process");
 
 const { auditProject } = require("../lib/audit");
+const { inspectDesignSupervisorReview } = require("../lib/audit-parsers");
 
 const repo = path.resolve(__dirname, "..");
 const cli = path.join(repo, "bin", "da-vinci.js");
@@ -347,7 +348,7 @@ runTest("completion audit passes when required supervisor review is recorded as
   );
 });
 
-runTest("completion audit accepts the latest round section when multiple Design-Supervisor Review headings exist", () => {
+runTest("completion audit accepts the latest structured round section when multiple Design-Supervisor Review headings exist", () => {
   const harness = createHarness();
   const project = setupProject(harness, "latest-supervisor-round-wins", {
     requireSupervisorReview: true
@@ -391,6 +392,159 @@ runTest("completion audit accepts the latest round section when multiple Design-
     result.notes.join("\n"),
     /Detected design-supervisor review status PASS/i
   );
+  assert.doesNotMatch(
+    result.warnings.join("\n"),
+    /legacy\/non-structured format/i
+  );
+});
+
+runTest("completion audit falls back to the latest structured section when newest review entry is legacy-style", () => {
+  const harness = createHarness();
+  const project = setupProject(harness, "legacy-supervisor-entry-fallback", {
+    requireSupervisorReview: true
+  });
+
+  writeText(
+    project.pencilDesignPath,
+    [
+      "# Pencil Design",
+      "",
+      "## Design-Supervisor Review",
+      "- Configured reviewers: frontend-skill",
+      "- Executed reviewers: frontend-skill",
+      "- Review source: skill",
+      "- Status: PASS",
+      "- Issue list: none",
+      "- Revision outcome: approved",
+      "",
+      "## Design-Supervisor Review (Round 2 Attempt)",
+      "- Result: BLOCK",
+      "- Issue list: style quality not approved",
+      "- Revision outcome: pending",
+      ""
+    ].join("\n")
+  );
+
+  const result = auditProject(project.root, {
+    mode: "completion",
+    changeId
+  });
+
+  assert.equal(
+    result.status,
+    "WARN",
+    `expected completion audit to warn but not fail when latest entry is legacy:\n${JSON.stringify(result, null, 2)}`
+  );
+  assert.match(
+    result.notes.join("\n"),
+    /Detected design-supervisor review status PASS/i
+  );
+  assert.match(
+    result.warnings.join("\n"),
+    /legacy\/non-structured format; gate evaluation used ## Design-Supervisor Review/i
+  );
+});
+
+runTest("completion audit fails when only legacy-style Design-Supervisor Review sections exist", () => {
+  const harness = createHarness();
+  const project = setupProject(harness, "legacy-supervisor-only", {
+    requireSupervisorReview: true
+  });
+
+  writeText(
+    project.pencilDesignPath,
+    [
+      "# Pencil Design",
+      "",
+      "## Design-Supervisor Review (Round 3 Attempt)",
+      "- Result: PASS",
+      "- Issue list: none",
+      "- Revision outcome: accepted",
+      ""
+    ].join("\n")
+  );
+
+  const result = auditProject(project.root, {
+    mode: "completion",
+    changeId
+  });
+
+  assert.equal(result.status, "FAIL");
+  assert.match(
+    result.failures.join("\n"),
+    /missing required field\(s\): Configured reviewers/i
+  );
+});
+
+runTest("completion audit treats Chinese round-attempt heading as legacy and falls back to latest structured section", () => {
+  const harness = createHarness();
+  const project = setupProject(harness, "legacy-supervisor-chinese-heading", {
+    requireSupervisorReview: true
+  });
+
+  writeText(
+    project.pencilDesignPath,
+    [
+      "# Pencil Design",
+      "",
+      "## Design-Supervisor Review",
+      "- Configured reviewers: frontend-skill",
+      "- Executed reviewers: frontend-skill",
+      "- Review source: skill",
+      "- Status: PASS",
+      "- Issue list: none",
+      "- Revision outcome: approved",
+      "",
+      "## Design-Supervisor Review（第2轮尝试）",
+      "- Result: BLOCK",
+      "- Issue list: 视觉层级仍需调整",
+      "- Revision outcome: 待修订",
+      ""
+    ].join("\n")
+  );
+
+  const result = auditProject(project.root, {
+    mode: "completion",
+    changeId
+  });
+
+  assert.equal(result.status, "WARN");
+  assert.match(
+    result.warnings.join("\n"),
+    /legacy\/non-structured format; gate evaluation used ## Design-Supervisor Review/i
+  );
+  assert.match(
+    result.notes.join("\n"),
+    /Detected design-supervisor review status PASS/i
+  );
+});
+
+runTest("inspectDesignSupervisorReview marks Chinese round-attempt suffix as legacy", () => {
+  const review = inspectDesignSupervisorReview(
+    [
+      "# Pencil Design",
+      "",
+      "## Design-Supervisor Review",
+      "- Configured reviewers: frontend-skill",
+      "- Executed reviewers: frontend-skill",
+      "- Review source: skill",
+      "- Status: PASS",
+      "- Issue list: none",
+      "- Revision outcome: approved",
+      "",
+      "## Design-Supervisor Review（第3轮尝试）",
+      "- Result: BLOCK",
+      "- Issue list: 继续迭代",
+      "- Revision outcome: pending",
+      ""
+    ].join("\n")
+  );
+
+  assert.equal(review.found, true);
+  assert.equal(review.latestSectionLooksLegacyAttempt, true);
+  assert.equal(review.usedStructuredSectionFallback, true);
+  assert.equal(review.selectedFromLatest, false);
+  assert.equal(review.status, "PASS");
 });
 
 runTest("completion audit accepts multiline Issue list and Revision outcome fields", () => {

package/scripts/test-mode-consistency.js

@@ -283,6 +283,11 @@ runTest("design-supervisor review stays distinct from preferred adapters and is
     const content = read(file);
     assert.match(content, /design-supervisor review/, `${file} should instruct design flows to run design-supervisor review when configured`);
     assert.match(content, /Require Supervisor Review: true/, `${file} should explain the hard-gate branch for supervisor review`);
+    assert.doesNotMatch(
+      content,
+      /^\s*##\s*Design-Supervisor Review\s*\(Round [^)]+Attempt\)\s*$/im,
+      `${file} should not provide ad-hoc supervisor-review heading templates`
+    );
   }
 });
 

package/scripts/test-pen-persistence.js

@@ -33,6 +33,10 @@ function createTempDir() {
   return fs.mkdtempSync(path.join(os.tmpdir(), "da-vinci-pen-persistence-"));
 }
 
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 function writePayloadFiles(tempDir, fixture) {
   const nodesFile = path.join(tempDir, "nodes.json");
   const variablesFile = path.join(tempDir, "variables.json");
@@ -183,6 +187,151 @@ runTest("comparePenSync fails when live payload is newer than disk", () => {
   assert.notEqual(result.liveHash, result.persistedHash);
 });
 
+runTest("writePenFromPayloadFiles rejects pen-state metadata passed as nodes payload", () => {
+  const tempDir = createTempDir();
+  const outputPath = path.join(tempDir, "written.pen");
+  const nodesFile = path.join(tempDir, "state-like.json");
+
+  fs.writeFileSync(
+    nodesFile,
+    JSON.stringify(
+      {
+        schema: 1,
+        penPath: "/tmp/demo.pen",
+        snapshotHash: "abc123",
+        topLevelIds: [],
+        topLevelCount: 0
+      },
+      null,
+      2
+    )
+  );
+
+  assert.throws(
+    () =>
+      writePenFromPayloadFiles({
+        outputPath,
+        nodesFile
+      }),
+    /appears to be pen state metadata/i
+  );
+});
+
+runTest("comparePenSync rejects pen-state metadata passed as nodes payload", () => {
+  const fixture = JSON.parse(fs.readFileSync(fixturePath, "utf8"));
+  const tempDir = createTempDir();
+  const { nodesFile, variablesFile } = writePayloadFiles(tempDir, fixture);
+  const outputPath = path.join(tempDir, "written.pen");
+  const invalidNodesFile = path.join(tempDir, "state-like.json");
+
+  writePenFromPayloadFiles({
+    outputPath,
+    nodesFile,
+    variablesFile,
+    version: fixture.version
+  });
+
+  fs.writeFileSync(
+    invalidNodesFile,
+    JSON.stringify(
+      {
+        schema: 1,
+        penPath: outputPath,
+        snapshotHash: "abc123",
+        topLevelIds: fixture.children.map((node) => node.id),
+        topLevelCount: fixture.children.length
+      },
+      null,
+      2
+    )
+  );
+
+  assert.throws(
+    () =>
+      comparePenSync({
+        penPath: outputPath,
+        nodesFile: invalidNodesFile,
+        version: fixture.version
+      }),
+    /appears to be pen state metadata/i
+  );
+});
+
+runTest("writePenFromPayloadFiles accepts nodes payload even when metadata keys are present", () => {
+  const fixture = JSON.parse(fs.readFileSync(fixturePath, "utf8"));
+  const tempDir = createTempDir();
+  const nodesFile = path.join(tempDir, "nodes-with-metadata.json");
+  const variablesFile = path.join(tempDir, "variables.json");
+  const outputPath = path.join(tempDir, "written.pen");
+
+  fs.writeFileSync(
+    nodesFile,
+    JSON.stringify(
+      {
+        nodes: fixture.children,
+        penPath: "/tmp/demo.pen",
+        snapshotHash: "abc123",
+        topLevelIds: fixture.children.map((node) => node.id),
+        topLevelCount: fixture.children.length
+      },
+      null,
+      2
+    )
+  );
+  fs.writeFileSync(variablesFile, JSON.stringify({ variables: fixture.variables }, null, 2));
+
+  writePenFromPayloadFiles({
+    outputPath,
+    nodesFile,
+    variablesFile,
+    version: fixture.version
+  });
+
+  assert.deepEqual(JSON.parse(fs.readFileSync(outputPath, "utf8")), fixture);
+});
+
+runTest("writePenFromPayloadFiles shows relative nodes path in metadata-payload error when file is under cwd", () => {
+  const originalCwd = process.cwd();
+  const localRoot = fs.mkdtempSync(path.join(originalCwd, ".tmp-da-vinci-pen-path-"));
+
+  try {
+    process.chdir(localRoot);
+    const outputPath = path.join(localRoot, "written.pen");
+    const nodesFile = path.join(localRoot, "state-like.json");
+
+    fs.writeFileSync(
+      nodesFile,
+      JSON.stringify(
+        {
+          schema: 1,
+          penPath: "/tmp/demo.pen",
+          snapshotHash: "abc123",
+          topLevelIds: [],
+          topLevelCount: 0
+        },
+        null,
+        2
+      )
+    );
+
+    assert.throws(
+      () =>
+        writePenFromPayloadFiles({
+          outputPath,
+          nodesFile
+        }),
+      (error) => {
+        assert.match(error.message, /\(state-like\.json\)/i);
+        assert.doesNotMatch(error.message, new RegExp(escapeRegExp(localRoot)));
+        return true;
+      }
+    );
+  } finally {
+    process.chdir(originalCwd);
+    fs.rmSync(localRoot, { recursive: true, force: true });
+  }
+});
+
 runTest("global Pencil lock serializes projects", () => {
   const tempDir = createTempDir();
   const homeDir = path.join(tempDir, "home");