@xenonbyte/da-vinci-workflow 0.1.19 → 0.1.21

package/docs/zh-CN/visual-assist-presets/web-app.md

@@ -18,20 +18,10 @@
 
 ```md
 ## Visual Assist
-- Preferred adapters:
-  - ui-ux-pro-max
-  - frontend-skill
-- Scope:
-  - visual contract refinement
-  - page composition
-  - hierarchy and spacing
-  - responsive motion guidance
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - false
+- Preferred adapters: ui-ux-pro-max, frontend-skill
+- Scope: visual contract refinement, page composition, hierarchy and spacing, responsive motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: false
 ```
 
 ### 变体 2：reviewer 建议性审查
@@ -43,33 +33,14 @@
 
 ```md
 ## Visual Assist
-- Preferred adapters:
-  - ui-ux-pro-max
-  - frontend-skill
-- Design-supervisor reviewers:
-  - frontend-skill
-  - ui-ux-pro-max
-- Design-supervisor review mode:
-  - screenshot-and-theme
-- Design-supervisor review inputs:
-  - screenshots
-  - pencil variables
-  - visual thesis
-  - content plan
-  - interaction thesis
-- Scope:
-  - visual contract refinement
-  - page composition
-  - hierarchy and spacing
-  - responsive motion guidance
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - false
-- Require Supervisor Review:
-  - false
+- Preferred adapters: ui-ux-pro-max, frontend-skill
+- Design-supervisor reviewers: frontend-skill, ui-ux-pro-max
+- Design-supervisor review mode: screenshot-and-theme
+- Design-supervisor review inputs: screenshots, pencil variables, visual thesis, content plan, interaction thesis
+- Scope: visual contract refinement, page composition, hierarchy and spacing, responsive motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: false
+- Require Supervisor Review: false
 ```
 
 ### 变体 3：reviewer 硬签字
@@ -82,33 +53,14 @@
 
 ```md
 ## Visual Assist
-- Preferred adapters:
-  - frontend-skill
-  - ui-ux-pro-max
-- Design-supervisor reviewers:
-  - frontend-skill
-  - ui-ux-pro-max
-- Design-supervisor review mode:
-  - screenshot-and-theme
-- Design-supervisor review inputs:
-  - screenshots
-  - pencil variables
-  - visual thesis
-  - content plan
-  - interaction thesis
-- Scope:
-  - visual contract refinement
-  - page composition
-  - hierarchy and spacing
-  - responsive motion guidance
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - true
-- Require Supervisor Review:
-  - true
+- Preferred adapters: frontend-skill, ui-ux-pro-max
+- Design-supervisor reviewers: frontend-skill, ui-ux-pro-max
+- Design-supervisor review mode: screenshot-and-theme
+- Design-supervisor review inputs: screenshots, pencil variables, visual thesis, content plan, interaction thesis
+- Scope: visual contract refinement, page composition, hierarchy and spacing, responsive motion guidance, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: true
+- Require Supervisor Review: true
 ```
 
 通用说明：

package/docs/zh-CN/workflow-examples.md

@@ -16,6 +16,8 @@
 
 - `intake` 和 `continue` 通常应该回到主工作流入口
 - 不应默认把用户导向 `build`
+- `continue` 选路先看工件/checkpoint 真相，再把 Context Delta 当作辅助恢复信息
+- 如果 Context Delta 与当前工件冲突，选路时应忽略冲突内容并记录冲突
 
 ## 1. `greenfield-spec`
 

package/docs/zh-CN/workflow-overview.md

@@ -130,6 +130,7 @@ anchor 通过后，再抽 shared primitives，然后再扩更多页面。
 - `design-source checkpoint`
 - 如果启用了 Pencil MCP，则跑 `MCP runtime gate`
 - 工作中期跑 `da-vinci audit --mode integrity <project-path>`
+- 在现有 change 工件里记录 checkpoint 邻近的 `Context Delta`
 
 这些检查用来确认：
 
@@ -137,6 +138,7 @@ anchor 通过后，再抽 shared primitives，然后再扩更多页面。
 - active editor 是正确的设计源
 - shell 上确实有 `.pen`
 - live snapshot 和 persisted snapshot 已同步
+- 最近关键执行上下文可恢复，但不会替代工件真相的选路权
 
 ### 6. Mapping
 
@@ -165,6 +167,10 @@ mapping 通过后：
 - 如果用了 Pencil MCP，runtime gate 结果可接受
 - `da-vinci audit --mode completion --change <change-id> <project-path>` 通过
 
+补充说明：
+
+- Context Delta 的告警用于提升续跑质量，本身不会单独形成新的 completion 阻断
+
 ## 门禁与审计
 
 ### Design Checkpoint
@@ -219,6 +225,11 @@ mapping 通过后：
 
 在任何终态完成声明前跑。
 
+audit 中对 Context Delta 的处理：
+
+- 缺失、字段不完整、或过期冲突都属于告警级信号
+- 选路和完成真相仍以工件、checkpoint、runtime gate 与文件系统审计为准
+
 ## 流程图
 
 ```mermaid

package/examples/greenfield-spec-markupflow/DA-VINCI.md

@@ -35,19 +35,10 @@
 - CTA regions should preserve the same dark product language
 
 ## Visual Assist
-- Preferred adapters:
-  - frontend-skill
-  - ui-ux-pro-max
-- Scope:
-  - visual contract refinement
-  - page composition
-  - hierarchy and spacing
-  - anchor-surface composition
-  - Pencil design refinement
-- Fallback:
-  - native-da-vinci
-- Require Adapter:
-  - false
+- Preferred adapters: frontend-skill, ui-ux-pro-max
+- Scope: visual contract refinement, page composition, hierarchy and spacing, anchor-surface composition, Pencil design refinement
+- Fallback: native-da-vinci
+- Require Adapter: false
 
 ## Do
 - keep page sections clearly bounded

package/lib/audit.js

@@ -121,6 +121,12 @@ function addMissingArtifacts(projectRoot, artifactPaths, targetList) {
   }
 }
 
+function pushUnique(targetList, message) {
+  if (!targetList.includes(message)) {
+    targetList.push(message);
+  }
+}
+
 function getMarkdownSection(text, heading) {
   if (!text) {
     return "";
@@ -151,6 +157,323 @@ function getMarkdownSection(text, heading) {
   return sectionLines.join("\n").trim();
 }
 
+function normalizeCheckpointLabel(value) {
+  return String(value || "")
+    .toLowerCase()
+    .replace(/`/g, "")
+    .replace(/[_-]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function parseCheckpointStatusMap(markdownText) {
+  const section = getMarkdownSection(markdownText, "Checkpoint Status");
+  if (!section) {
+    return {};
+  }
+
+  const statuses = {};
+  const matches = section.matchAll(/(?:^|\n)\s*-\s*`?([^`:\n]+?)`?\s*:\s*(PASS|WARN|BLOCK)\b/gi);
+  for (const match of matches) {
+    const label = normalizeCheckpointLabel(match[1]);
+    if (!label) {
+      continue;
+    }
+    statuses[label] = String(match[2]).toUpperCase();
+  }
+
+  return statuses;
+}
+
+function hasContextDeltaExpectationSignals(markdownText) {
+  const text = String(markdownText || "");
+  return (
+    /##\s+(Checkpoint Status|MCP Runtime Gate)\b/i.test(text) ||
+    /(?:^|\n)\s*(?:[-*]\s*)?`?Context Delta Required`?\s*:\s*(?:true|yes|on|1)\b/i.test(text)
+  );
+}
+
+function parseSupersedesTokens(value) {
+  return String(value || "")
+    .split(/[,\n;]/)
+    .map((token) => token.trim())
+    .filter(Boolean);
+}
+
+function normalizeTimeToken(value) {
+  const raw = String(value || "").trim();
+  if (!raw) {
+    return "";
+  }
+
+  const parseCandidates = [];
+  const rawWithT = raw.includes(" ") ? raw.replace(/\s+/, "T") : raw;
+  const hasExplicitTimezone = /(?:Z|[+-]\d{2}:?\d{2})$/i.test(rawWithT);
+
+  if (!hasExplicitTimezone && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(rawWithT)) {
+    parseCandidates.push(`${rawWithT}Z`);
+  }
+
+  parseCandidates.push(rawWithT);
+  parseCandidates.push(raw);
+
+  for (const candidate of parseCandidates) {
+    const timestamp = Date.parse(candidate);
+    if (!Number.isFinite(timestamp)) {
+      continue;
+    }
+    return new Date(timestamp).toISOString();
+  }
+
+  return "";
+}
+
+function getTimeReferenceKeys(value) {
+  const raw = String(value || "").trim();
+  if (!raw) {
+    return [];
+  }
+
+  const keys = new Set([raw]);
+
+  if (raw.includes(" ")) {
+    keys.add(raw.replace(/\s+/, "T"));
+  }
+
+  if (raw.endsWith(".000Z")) {
+    keys.add(raw.replace(".000Z", "Z"));
+  }
+
+  const normalized = normalizeTimeToken(raw);
+  if (normalized) {
+    keys.add(normalized);
+    if (normalized.endsWith(".000Z")) {
+      keys.add(normalized.replace(".000Z", "Z"));
+    }
+  }
+
+  return [...keys];
+}
+
+function buildContextDeltaReferenceIndex(entries) {
+  const referenceIndex = new Map();
+
+  function addReference(key, entryIndex) {
+    const normalizedKey = String(key || "").trim();
+    if (!normalizedKey) {
+      return;
+    }
+
+    const existing = referenceIndex.get(normalizedKey) || [];
+    existing.push(entryIndex);
+    referenceIndex.set(normalizedKey, existing);
+  }
+
+  entries.forEach((entry, entryIndex) => {
+    if (entry.time) {
+      for (const timeKey of getTimeReferenceKeys(entry.time)) {
+        addReference(timeKey, entryIndex);
+        addReference(`time:${timeKey}`, entryIndex);
+      }
+    }
+
+    if (entry.checkpointType && entry.time) {
+      const normalizedCheckpointType = normalizeCheckpointLabel(entry.checkpointType);
+      for (const timeKey of getTimeReferenceKeys(entry.time)) {
+        addReference(`${entry.checkpointType}@${timeKey}`, entryIndex);
+        addReference(`${normalizedCheckpointType}@${timeKey}`, entryIndex);
+      }
+    }
+  });
+
+  return referenceIndex;
+}
+
+function getSupersedesCandidateKeys(token) {
+  const trimmed = String(token || "").trim();
+  if (!trimmed) {
+    return [];
+  }
+
+  const keys = new Set([trimmed]);
+  const prefixedTimeMatch = trimmed.match(/^time\s*:\s*(.+)$/i);
+  if (prefixedTimeMatch) {
+    for (const timeKey of getTimeReferenceKeys(prefixedTimeMatch[1])) {
+      keys.add(timeKey);
+      keys.add(`time:${timeKey}`);
+    }
+  } else {
+    keys.add(`time:${trimmed}`);
+    for (const timeKey of getTimeReferenceKeys(trimmed)) {
+      keys.add(timeKey);
+      keys.add(`time:${timeKey}`);
+    }
+  }
+
+  const atIndex = trimmed.indexOf("@");
+  if (atIndex > 0 && atIndex < trimmed.length - 1) {
+    const checkpointType = trimmed.slice(0, atIndex).trim();
+    const time = trimmed.slice(atIndex + 1).trim();
+    if (checkpointType && time) {
+      const normalizedCheckpointType = normalizeCheckpointLabel(checkpointType);
+      for (const timeKey of getTimeReferenceKeys(time)) {
+        keys.add(`${checkpointType}@${timeKey}`);
+        keys.add(`${normalizedCheckpointType}@${timeKey}`);
+      }
+    }
+  }
+
+  return [...keys];
+}
+
+function resolveSupersedesReferenceIndices(token, referenceIndex) {
+  const indices = new Set();
+  for (const key of getSupersedesCandidateKeys(token)) {
+    const matches = referenceIndex.get(key);
+    if (!matches) {
+      continue;
+    }
+    for (const entryIndex of matches) {
+      indices.add(entryIndex);
+    }
+  }
+  return [...indices].sort((a, b) => a - b);
+}
+
+function inspectContextDelta(markdownText) {
+  const section = getMarkdownSection(markdownText, "Context Delta");
+  if (!section) {
+    return {
+      found: false,
+      hasConcreteEntry: false,
+      entries: [],
+      incompleteEntryCount: 0
+    };
+  }
+
+  const lines = String(section).replace(/\r\n?/g, "\n").split("\n");
+  const entries = [];
+  let current = null;
+
+  function ensureCurrent() {
+    if (!current) {
+      current = {};
+    }
+  }
+
+  function flushCurrent() {
+    if (!current) {
+      return;
+    }
+
+    const hasAnyValue = [
+      current.time,
+      current.checkpointType,
+      current.goal,
+      current.decision,
+      current.constraints,
+      current.impact,
+      current.status,
+      current.nextAction,
+      current.supersedes
+    ].some((value) => Boolean(value));
+
+    if (hasAnyValue) {
+      entries.push(current);
+    }
+    current = null;
+  }
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+
+    if (!line) {
+      continue;
+    }
+
+    const timeMatch = line.match(/^-+\s*`?time`?\s*:\s*(.+)$/i);
+    if (timeMatch) {
+      flushCurrent();
+      current = {
+        time: timeMatch[1].trim()
+      };
+      continue;
+    }
+
+    const checkpointTypeMatch = line.match(/^-+\s*`?checkpoint(?:[_ -]?type)?`?\s*:\s*(.+)$/i);
+    if (checkpointTypeMatch) {
+      ensureCurrent();
+      current.checkpointType = checkpointTypeMatch[1].trim();
+      continue;
+    }
+
+    const goalMatch = line.match(/^-+\s*`?goal`?\s*:\s*(.+)$/i);
+    if (goalMatch) {
+      ensureCurrent();
+      current.goal = goalMatch[1].trim();
+      continue;
+    }
+
+    const decisionMatch = line.match(/^-+\s*`?decision`?\s*:\s*(.+)$/i);
+    if (decisionMatch) {
+      ensureCurrent();
+      current.decision = decisionMatch[1].trim();
+      continue;
+    }
+
+    const constraintsMatch = line.match(/^-+\s*`?constraints`?\s*:\s*(.+)$/i);
+    if (constraintsMatch) {
+      ensureCurrent();
+      current.constraints = constraintsMatch[1].trim();
+      continue;
+    }
+
+    const impactMatch = line.match(/^-+\s*`?impact`?\s*:\s*(.+)$/i);
+    if (impactMatch) {
+      ensureCurrent();
+      current.impact = impactMatch[1].trim();
+      continue;
+    }
+
+    const statusMatch = line.match(/^-+\s*`?status`?\s*:\s*(PASS|WARN|BLOCK)\b/i);
+    if (statusMatch) {
+      ensureCurrent();
+      current.status = String(statusMatch[1]).toUpperCase();
+      continue;
+    }
+
+    const nextActionMatch = line.match(/^-+\s*`?next(?:[_ -]?action)?`?\s*:\s*(.+)$/i);
+    if (nextActionMatch) {
+      ensureCurrent();
+      current.nextAction = nextActionMatch[1].trim();
+      continue;
+    }
+
+    const supersedesMatch = line.match(/^-+\s*`?supersedes`?\s*:\s*(.+)$/i);
+    if (supersedesMatch) {
+      ensureCurrent();
+      current.supersedes = supersedesMatch[1].trim();
+      continue;
+    }
+  }
+
+  flushCurrent();
+
+  const hasConcreteEntry = entries.some(
+    (entry) => entry.time || entry.checkpointType || entry.status || entry.decision || entry.nextAction
+  );
+  const incompleteEntryCount = entries.filter(
+    (entry) => !entry.time || !entry.checkpointType || !entry.status
+  ).length;
+
+  return {
+    found: true,
+    hasConcreteEntry,
+    entries,
+    incompleteEntryCount
+  };
+}
+
 function getVisualAssistFieldValues(daVinciText, fieldName) {
   const section = getMarkdownSection(daVinciText, "Visual Assist");
   if (!section) {
@@ -547,6 +870,138 @@ function auditProject(projectPathInput, options = {}) {
       }
     }
 
+    const tasksPath = path.join(changeDir, "tasks.md");
+    const verificationPath = path.join(changeDir, "verification.md");
+    const contextArtifacts = [pencilDesignPath, tasksPath, verificationPath]
+      .filter((artifactPath) => pathExists(artifactPath))
+      .map((artifactPath) => ({
+        path: artifactPath,
+        text: readTextIfExists(artifactPath)
+      }));
+    const contextCandidates = contextArtifacts.filter((artifact) =>
+      hasContextDeltaExpectationSignals(artifact.text)
+    );
+
+    if (contextCandidates.length > 0) {
+      const contextInspections = contextCandidates.map((artifact) => ({
+        path: artifact.path,
+        inspection: inspectContextDelta(artifact.text),
+        checkpointStatuses: parseCheckpointStatusMap(artifact.text)
+      }));
+
+      const hasAnyConcreteContextDelta = contextInspections.some(
+        (item) => item.inspection.hasConcreteEntry
+      );
+
+      if (!hasAnyConcreteContextDelta) {
+        pushUnique(
+          warnings,
+          `Checkpoint-bearing artifacts in ${changeRel} do not record any concrete \`## Context Delta\` entries.`
+        );
+      } else {
+        notes.push(`Detected context-delta recovery notes in ${changeRel}.`);
+      }
+
+      for (const item of contextInspections) {
+        if (!item.inspection.found || item.inspection.incompleteEntryCount === 0) {
+          continue;
+        }
+
+        pushUnique(
+          warnings,
+          `${relativeTo(projectRoot, item.path)} has ${item.inspection.incompleteEntryCount} context-delta entr` +
+            `${item.inspection.incompleteEntryCount === 1 ? "y" : "ies"} missing one of: time/checkpoint_type/status.`
+        );
+      }
+
+      for (const item of contextInspections) {
+        if (!item.inspection.found || item.inspection.entries.length === 0) {
+          continue;
+        }
+
+        const referenceIndex = buildContextDeltaReferenceIndex(item.inspection.entries);
+
+        item.inspection.entries.forEach((entry, entryIndex) => {
+          if (!entry.supersedes) {
+            return;
+          }
+
+          const entryLabel = entry.time ? `time \`${entry.time}\`` : `entry #${entryIndex + 1}`;
+          const supersedesTokens = parseSupersedesTokens(entry.supersedes);
+
+          if (supersedesTokens.length === 0) {
+            pushUnique(
+              warnings,
+              `${relativeTo(projectRoot, item.path)} has ${entryLabel} with an empty \`supersedes\` reference.`
+            );
+            return;
+          }
+
+          for (const token of supersedesTokens) {
+            const resolvedIndices = resolveSupersedesReferenceIndices(token, referenceIndex);
+
+            if (resolvedIndices.length === 0) {
+              pushUnique(
+                warnings,
+                `${relativeTo(projectRoot, item.path)} has ${entryLabel} superseding \`${token}\`, ` +
+                  "but no referenced context-delta entry exists in the same artifact."
+              );
+              continue;
+            }
+
+            const hasOlderMatch = resolvedIndices.some((resolvedIndex) => resolvedIndex < entryIndex);
+            if (!hasOlderMatch) {
+              pushUnique(
+                warnings,
+                `${relativeTo(projectRoot, item.path)} has ${entryLabel} superseding \`${token}\`, ` +
+                  "but the reference does not point to an earlier context-delta entry."
+              );
+            }
+          }
+        });
+      }
+
+      if (mode === "completion" && scopedChangeDirs.includes(changeDir)) {
+        for (const item of contextInspections) {
+          if (!item.inspection.hasConcreteEntry || Object.keys(item.checkpointStatuses).length === 0) {
+            continue;
+          }
+
+          const entriesByType = new Map();
+          for (const entry of item.inspection.entries) {
+            if (!entry.checkpointType || !entry.status) {
+              continue;
+            }
+            const checkpointType = normalizeCheckpointLabel(entry.checkpointType);
+            const existing = entriesByType.get(checkpointType) || [];
+            existing.push(entry);
+            entriesByType.set(checkpointType, existing);
+          }
+
+          for (const [checkpointType, entries] of entriesByType.entries()) {
+            const currentStatus = item.checkpointStatuses[checkpointType];
+            if (!currentStatus || entries.length === 0) {
+              continue;
+            }
+
+            const latestEntry = entries[entries.length - 1];
+            if (currentStatus === latestEntry.status) {
+              continue;
+            }
+
+            const statusHistory = entries.map((entry) => entry.status).join(" -> ");
+            pushUnique(
+              warnings,
+              `Context-delta/checkpoint status mismatch in ${relativeTo(projectRoot, item.path)} for ` +
+                `\`${latestEntry.checkpointType}\`: latest context-delta status is ${latestEntry.status}, ` +
+                `current checkpoint status is ${currentStatus} (history: ${statusHistory}). ` +
+                "This may indicate stale checkpoint status or stale context-delta notes."
+            );
+          }
+        }
+      }
+    }
+
     const specDirs = listChildDirs(path.join(changeDir, "specs"));
     for (const specDir of specDirs) {
       const specFile = path.join(specDir, "spec.md");

package/lib/cli.js

@@ -100,7 +100,7 @@ function printHelp() {
       "  da-vinci pencil-lock status",
       "  da-vinci pencil-session begin --project <path> --pen <path>",
       "  da-vinci pencil-session persist --project <path> --pen <path> --nodes-file <path> [--variables-file <path>]",
-      "  da-vinci pencil-session end --project <path> --pen <path> [--nodes-file <path>]",
+      "  da-vinci pencil-session end --project <path> --pen <path> --nodes-file <path> [--variables-file <path>]",
       "  da-vinci pencil-session status --project <path>",
       "  da-vinci --version",
       "",
@@ -456,6 +456,11 @@ async function runCli(argv) {
       if (!penPath) {
         throw new Error("`pencil-session end` requires `--pen <path>`.");
       }
+      if (!nodesFile && !force) {
+        throw new Error(
+          "`pencil-session end` requires `--nodes-file <path>` (and `--variables-file <path>` when available). Use `--force` only for emergency lock release."
+        );
+      }
 
       const result = endPencilSession({
         projectPath,

package/lib/pencil-session.js

@@ -168,6 +168,12 @@ function endPencilSession(options) {
     throw new Error("A registered `.pen` path is required for session shutdown.");
   }
 
+  if (!options.nodesFile && !options.force) {
+    throw new Error(
+      "Cannot end Pencil session without a live MCP snapshot. Provide `--nodes-file` (and `--variables-file` when available), or use `--force` for emergency shutdown."
+    );
+  }
+
   let syncResult = null;
   if (options.nodesFile) {
     syncResult = comparePenSync({