@xenonbyte/da-vinci-workflow 0.2.2 → 0.2.4

package/lib/audit-parsers.js

@@ -244,18 +244,27 @@ function normalizeCheckpointLabel(value) {
 
 function parseCheckpointStatusMap(markdownText) {
   const section = getMarkdownSection(markdownText, "Checkpoint Status");
-  if (!section) {
-    return {};
+  const statuses = {};
+
+  if (section) {
+    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();
+    }
   }
 
-  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;
+  const runtimeGateSection = getMarkdownSection(markdownText, "MCP Runtime Gate");
+  if (runtimeGateSection) {
+    const runtimeGateMatch = String(runtimeGateSection).match(
+      /(?:^|\n)\s*-\s*(?:Final runtime gate status|Status|状态)\s*:\s*`?(PASS|WARN|BLOCK)`?\b/i
+    );
+    if (runtimeGateMatch) {
+      statuses[normalizeCheckpointLabel("mcp runtime gate")] = String(runtimeGateMatch[1]).toUpperCase();
     }
-    statuses[label] = String(match[2]).toUpperCase();
   }
 
   return statuses;
@@ -751,6 +760,149 @@ function inspectDesignSupervisorReview(pencilDesignText) {
   };
 }
 
+const DISCIPLINE_MARKER_NAMES = Object.freeze({
+  designApproval: "design_approval",
+  planSelfReview: "plan_self_review",
+  operatorReviewAck: "operator_review_ack"
+});
+
+const DISCIPLINE_MARKER_ALIASES = Object.freeze({
+  [DISCIPLINE_MARKER_NAMES.designApproval]: [
+    "design approval",
+    "design-approved",
+    "design approved",
+    "design_approval",
+    "design-approval"
+  ],
+  [DISCIPLINE_MARKER_NAMES.planSelfReview]: [
+    "plan self review",
+    "plan_self_review",
+    "plan-self-review",
+    "plan review",
+    "plan-review"
+  ],
+  [DISCIPLINE_MARKER_NAMES.operatorReviewAck]: [
+    "operator review ack",
+    "operator review acknowledgement",
+    "operator review acknowledgment",
+    "operator_ack",
+    "operator-review-ack",
+    "operator-review-acknowledgement",
+    "operator-review-acknowledgment"
+  ]
+});
+
+const DISCIPLINE_MARKER_KEYWORDS = Object.freeze(
+  Object.values(DISCIPLINE_MARKER_ALIASES)
+    .flat()
+    .map((token) => String(token).replace(/[_-]+/g, " ").toLowerCase())
+);
+
+function normalizeDisciplineMarkerName(value) {
+  const normalized = String(value || "")
+    .toLowerCase()
+    .replace(/[`*_~]/g, "")
+    .replace(/[_-]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!normalized) {
+    return "";
+  }
+  for (const [canonicalName, aliases] of Object.entries(DISCIPLINE_MARKER_ALIASES)) {
+    if (aliases.some((alias) => normalized === String(alias).replace(/[_-]+/g, " ").toLowerCase())) {
+      return canonicalName;
+    }
+  }
+  return "";
+}
+
+function normalizeDisciplineMarkerStatus(value) {
+  return String(value || "")
+    .toUpperCase()
+    .replace(/[`*_~]/g, "")
+    .replace(/[()]/g, "")
+    .replace(/\s+/g, "_")
+    .replace(/[^A-Z0-9_]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+}
+
+function parseDisciplineMarkers(markdownText) {
+  const markers = {};
+  const ordered = [];
+  const malformed = [];
+  const lines = String(markdownText || "").replace(/\r\n?/g, "\n").split("\n");
+  const markerPattern =
+    /^\s*-\s*`?([A-Za-z][A-Za-z0-9 _-]{1,80})`?\s*:\s*`?([A-Za-z0-9 _-]{1,80})`?(?:\s*@\s*`?([^`]+?)`?)?\s*$/;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const rawLine = lines[index];
+    const match = rawLine.match(markerPattern);
+    if (!match) {
+      const normalizedLine = String(rawLine || "")
+        .toLowerCase()
+        .replace(/[_-]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+      if (!normalizedLine.startsWith("-")) {
+        continue;
+      }
+      if (DISCIPLINE_MARKER_KEYWORDS.some((keyword) => normalizedLine.includes(keyword))) {
+        malformed.push({
+          line: index + 1,
+          reason: "Malformed discipline marker syntax.",
+          raw: rawLine
+        });
+      }
+      continue;
+    }
+
+    const markerName = normalizeDisciplineMarkerName(match[1]);
+    if (!markerName) {
+      continue;
+    }
+
+    const status = normalizeDisciplineMarkerStatus(match[2]);
+    if (!status) {
+      malformed.push({
+        line: index + 1,
+        reason: "Missing marker status token.",
+        raw: rawLine
+      });
+      continue;
+    }
+
+    const rawTime = String(match[3] || "").trim();
+    let time = "";
+    if (rawTime) {
+      time = normalizeTimeToken(rawTime);
+      if (!time) {
+        malformed.push({
+          line: index + 1,
+          reason: "Invalid marker timestamp.",
+          raw: rawLine
+        });
+      }
+    }
+
+    const record = {
+      name: markerName,
+      status,
+      time,
+      rawTime,
+      line: index + 1,
+      raw: rawLine
+    };
+    ordered.push(record);
+    markers[markerName] = record;
+  }
+
+  return {
+    markers,
+    ordered,
+    malformed
+  };
+}
+
 module.exports = {
   hasMarkdownHeading,
   getMarkdownSection,
@@ -766,5 +918,9 @@ module.exports = {
   getConfiguredDesignSupervisorReviewers,
   hasConfiguredDesignSupervisorReview,
   isDesignSupervisorReviewRequired,
-  inspectDesignSupervisorReview
+  inspectDesignSupervisorReview,
+  DISCIPLINE_MARKER_NAMES,
+  normalizeDisciplineMarkerName,
+  normalizeDisciplineMarkerStatus,
+  parseDisciplineMarkers
 };

package/lib/audit.js

@@ -8,7 +8,8 @@ const {
   assertPenDocumentShape
 } = require("./pen-persistence");
 const { getSessionStatePath, readSessionState } = require("./pencil-session");
-const { isPathInside, listFilesRecursiveSafe } = require("./fs-safety");
+const { listFilesRecursiveSafe } = require("./fs-safety");
+const { collectRegisteredPenPaths } = require("./design-source-registry");
 const { pathExists, readTextIfExists } = require("./utils");
 const { runModuleExportInWorker } = require("./async-offload");
 const { readExecutionSignals, summarizeSignalsBySurface } = require("./execution-signals");
@@ -69,30 +70,6 @@ function relativeTo(projectRoot, targetPath) {
   return path.relative(projectRoot, targetPath) || ".";
 }
 
-function collectRegisteredPenPaths(projectRoot, designRegistryPath) {
-  const registryText = readTextIfExists(designRegistryPath);
-  const matches = registryText.match(/\.da-vinci\/designs\/[^\s`]+\.pen/g) || [];
-  const validPaths = [];
-  const escapedPaths = [];
-
-  for (const relativePath of [...new Set(matches)]) {
-    const resolvedPath = path.resolve(projectRoot, relativePath);
-    if (!isPathInside(projectRoot, resolvedPath)) {
-      escapedPaths.push({
-        relativePath,
-        resolvedPath
-      });
-      continue;
-    }
-    validPaths.push(resolvedPath);
-  }
-
-  return {
-    validPaths,
-    escapedPaths
-  };
-}
-
 function getNonEmptyChangeDirs(changesDir) {
   return listChildDirs(changesDir).filter((changeDir) => {
     const scan = listFilesRecursive(changeDir, CHANGE_SCAN_LIMITS);
@@ -368,7 +345,7 @@ function auditProject(projectPathInput, options = {}) {
   const {
     validPaths: registeredPenPaths,
     escapedPaths: escapedRegisteredPenPaths
-  } = collectRegisteredPenPaths(projectRoot, designRegistryPath);
+  } = collectRegisteredPenPaths(projectRoot, readTextIfExists(designRegistryPath));
   for (const escapedPath of escapedRegisteredPenPaths) {
     const message =
       `Registered design source escapes project root and will be ignored: ${escapedPath.relativePath} ` +

package/lib/cli.js

@@ -32,6 +32,11 @@ const {
   endPencilSession,
   getPencilSessionStatus
 } = require("./pencil-session");
+const {
+  SAVE_STATUS,
+  saveCurrentDesign,
+  formatSaveCurrentDesignReport
+} = require("./save-current-design");
 const {
   searchIconLibrary,
   formatIconSearchReport
@@ -74,6 +79,18 @@ const {
 const { diffSpec, formatDiffSpecReport } = require("./diff-spec");
 const { scaffoldFromBindings, formatScaffoldReport } = require("./scaffold");
 const { writeExecutionSignal } = require("./execution-signals");
+const {
+  writeTaskExecutionEnvelope,
+  formatTaskExecutionReport
+} = require("./task-execution");
+const {
+  writeTaskReviewEnvelope,
+  formatTaskReviewReport
+} = require("./task-review");
+const {
+  runWorktreePreflight,
+  formatWorktreePreflightReport
+} = require("./worktree-preflight");
 const { formatTuiHelp, launchTui } = require("../tui");
 
 const DEFAULT_MAX_PREFLIGHT_STDIN_BYTES = 1024 * 1024;
@@ -83,6 +100,7 @@ const OPTION_FLAGS_WITH_VALUES = new Set([
   "--home",
   "--platform",
   "--lang",
+  "--tui-width",
   "--project",
   "--mode",
   "--change",
@@ -95,6 +113,15 @@ const OPTION_FLAGS_WITH_VALUES = new Set([
   "--aliases",
   "--pencil-design",
   "--status",
+  "--stage",
+  "--summary",
+  "--task-group",
+  "--changed-files",
+  "--test-evidence",
+  "--concerns",
+  "--blockers",
+  "--issues",
+  "--reviewer",
   "--source",
   "--executed-reviewers",
   "--codex-bin",
@@ -113,6 +140,7 @@ const OPTION_FLAGS_WITH_VALUES = new Set([
   "--from",
   "--to",
   "--pen",
+  "--pencil-bin",
   "--nodes-file",
   "--variables-file",
   "--version",
@@ -123,6 +151,7 @@ const OPTION_FLAGS_WITH_VALUES = new Set([
 const HELP_OPTION_SPECS = [
   { flag: "--platform <value>", description: "codex, claude, gemini, or all" },
   { flag: "--lang <value>", description: "ui language for `da-vinci tui`: en or zh" },
+  { flag: "--tui-width <cols>", description: "fixed layout width (columns) for `da-vinci tui`" },
   { flag: "--home <path>", description: "override HOME for installation targets" },
   { flag: "--project <path>", description: "override project path for audit" },
   {
@@ -155,6 +184,16 @@ const HELP_OPTION_SPECS = [
     description: "icon-search family filter: all, material, rounded, outlined, sharp, lucide, feather, phosphor"
   },
   { flag: "--status <value>", description: "PASS, WARN, or BLOCK for supervisor-review" },
+  { flag: "--stage <value>", description: "task-review stage: spec or quality" },
+  { flag: "--summary <text>", description: "task-execution/task-review summary text" },
+  { flag: "--task-group <id>", description: "task group identifier for task-execution/task-review" },
+  { flag: "--changed-files <csv>", description: "comma-separated changed files for task-execution" },
+  { flag: "--test-evidence <csv>", description: "comma-separated test evidence commands for task-execution" },
+  { flag: "--concerns <csv>", description: "comma-separated concern text for task-execution" },
+  { flag: "--blockers <csv>", description: "comma-separated blocker text for task-execution" },
+  { flag: "--issues <csv>", description: "comma-separated issue text for task-review" },
+  { flag: "--reviewer <name>", description: "reviewer identifier for task-review" },
+  { flag: "--write-verification", description: "append task-review evidence into verification.md" },
   { flag: "--source <value>", description: "review source: skill, manual, inferred" },
   { flag: "--executed-reviewers <csv>", description: "reviewer skills that executed this review" },
   { flag: "--run-reviewers", description: "execute configured reviewer skills through codex exec" },
@@ -188,12 +227,15 @@ const HELP_OPTION_SPECS = [
     flag: "--strict",
     description: "enable strict failure mode for commands that support advisory defaults (for example icon-sync, lint-spec)"
   },
+  { flag: "--alt-screen", description: "enable alternate terminal screen buffer for `da-vinci tui`" },
+  { flag: "--no-alt-screen", description: "disable alternate terminal screen buffer for `da-vinci tui`" },
   {
     flag: "--continue-on-error",
     description: "print BLOCK/FAIL command results without throwing process errors"
   },
   { flag: "--json", description: "print structured JSON output when supported by the command" },
   { flag: "--pen <path>", description: "registered .pen path for sync checks" },
+  { flag: "--pencil-bin <path>", description: "override Pencil executable for interactive capture/verify flows" },
   {
     flag: "--from <path>",
     description: "source path for sync-pen-source, or baseline sidecars directory for diff-spec"
@@ -475,7 +517,7 @@ function printHelp() {
       "  da-vinci install --platform codex,claude,gemini",
       "  da-vinci uninstall --platform codex,claude,gemini",
       "  da-vinci status",
-      "  da-vinci tui [--project <path>] [--change <id>] [--lang en|zh] [--strict] [--json] [--continue-on-error]",
+      "  da-vinci tui [--project <path>] [--change <id>] [--lang en|zh] [--strict] [--json] [--continue-on-error] [--tui-width <cols>] [--alt-screen|--no-alt-screen]",
       "  da-vinci workflow-status [--project <path>] [--change <id>] [--json]",
       "  da-vinci next-step [--project <path>] [--change <id>] [--json]",
       "  da-vinci lint-spec [--project <path>] [--change <id>] [--strict] [--json]",
@@ -487,6 +529,9 @@ function printHelp() {
       "  da-vinci verify-implementation [--project <path>] [--change <id>] [--strict] [--json]",
       "  da-vinci verify-structure [--project <path>] [--change <id>] [--strict] [--json]",
       "  da-vinci verify-coverage [--project <path>] [--change <id>] [--strict] [--json]",
+      "  da-vinci task-execution --project <path> --change <id> --task-group <id> --status <DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED> --summary <text> [--changed-files <csv>] [--test-evidence <csv>] [--concerns <csv>] [--blockers <csv>] [--json]",
+      "  da-vinci task-review --project <path> --change <id> --task-group <id> --stage <spec|quality> --status <PASS|WARN|BLOCK> --summary <text> [--issues <csv>] [--reviewer <name>] [--write-verification] [--json]",
+      "  da-vinci worktree-preflight --project <path> [--change <id>] [--json]",
       "  da-vinci diff-spec [--project <path>] [--change <id>] [--from <sidecars-dir>] [--json]",
       "  da-vinci scaffold [--project <path>] [--change <id>] [--output <path>] [--json]",
       "  da-vinci validate-assets",
@@ -502,6 +547,7 @@ function printHelp() {
       "  da-vinci check-pen-baseline --pen <path> --baseline <path>[,<path>...] [--baseline <path>] [--prefer-source <path>]",
       "  da-vinci sync-pen-source --from <path> --to <path>",
       "  da-vinci snapshot-pen --input <path> --output <path>",
+      "  da-vinci save-current-design --project <path> [--json] [--continue-on-error]",
       "  da-vinci pencil-lock acquire --project <path>",
       "  da-vinci pencil-lock release --project <path>",
       "  da-vinci pencil-lock status",
@@ -945,6 +991,12 @@ async function runCli(argv) {
     const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
     const changeId = getOption(argv, "--change");
     const lang = getOption(argv, "--lang");
+    const tuiWidth = getOption(argv, "--tui-width");
+    const altScreen = argv.includes("--alt-screen")
+      ? true
+      : argv.includes("--no-alt-screen")
+        ? false
+        : undefined;
     if (argv.includes("--help") || argv.includes("-h")) {
       console.log(formatTuiHelp(lang));
       return;
@@ -953,6 +1005,8 @@ async function runCli(argv) {
       projectPath,
       changeId,
       lang,
+      tuiWidth,
+      altScreen,
       strict: argv.includes("--strict"),
       jsonOutput: argv.includes("--json"),
       continueOnError
@@ -980,7 +1034,21 @@ async function runCli(argv) {
     const result = deriveWorkflowStatus(projectPath, { changeId });
 
     if (argv.includes("--json")) {
-      console.log(JSON.stringify(result.nextStep || null, null, 2));
+      console.log(
+        JSON.stringify(
+          {
+            stage: result.stage,
+            checkpointState: result.checkpointState,
+            nextStep: result.nextStep || null,
+            discipline: result.discipline || null,
+            executionProfile: result.executionProfile || null,
+            worktreePreflight: result.worktreePreflight || null,
+            verificationFreshness: result.verificationFreshness || null
+          },
+          null,
+          2
+        )
+      );
       return;
     }
 
@@ -1140,6 +1208,63 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "task-execution") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const result = writeTaskExecutionEnvelope(projectPath, {
+      changeId,
+      taskGroupId: getOption(argv, "--task-group"),
+      status: getOption(argv, "--status"),
+      summary: getOption(argv, "--summary"),
+      changedFiles: getCommaSeparatedOptionValues(argv, "--changed-files"),
+      testEvidence: getCommaSeparatedOptionValues(argv, "--test-evidence"),
+      concerns: getCommaSeparatedOptionValues(argv, "--concerns"),
+      blockers: getCommaSeparatedOptionValues(argv, "--blockers")
+    });
+    const useJson = argv.includes("--json");
+    const output = useJson ? JSON.stringify(result, null, 2) : formatTaskExecutionReport(result);
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+    console.log(output);
+    return;
+  }
+
+  if (command === "task-review") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const result = writeTaskReviewEnvelope(projectPath, {
+      changeId,
+      taskGroupId: getOption(argv, "--task-group"),
+      stage: getOption(argv, "--stage"),
+      status: getOption(argv, "--status"),
+      summary: getOption(argv, "--summary"),
+      issues: getCommaSeparatedOptionValues(argv, "--issues"),
+      reviewer: getOption(argv, "--reviewer"),
+      writeVerification: argv.includes("--write-verification")
+    });
+    const useJson = argv.includes("--json");
+    const output = useJson ? JSON.stringify(result, null, 2) : formatTaskReviewReport(result);
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+    console.log(output);
+    return;
+  }
+
+  if (command === "worktree-preflight") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const result = runWorktreePreflight(projectPath);
+    persistExecutionSignal(projectPath, changeId || "global", "worktree-preflight", result, false);
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(formatWorktreePreflightReport(result));
+    return;
+  }
+
   if (command === "diff-spec") {
     const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
     const changeId = getOption(argv, "--change");
@@ -1425,6 +1550,35 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "save-current-design") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const pencilBin = getOption(argv, "--pencil-bin");
+    const result = await saveCurrentDesign({
+      projectPath,
+      homeDir,
+      pencilBin,
+      allowLocalBridge: true
+    });
+    const useJson = argv.includes("--json");
+    const output = useJson
+      ? JSON.stringify(result, null, 2)
+      : formatSaveCurrentDesignReport(result);
+
+    if (
+      emitOrThrowOnStatus(
+        result.status,
+        [SAVE_STATUS.BLOCKED, SAVE_STATUS.UNAVAILABLE],
+        output,
+        continueOnError
+      )
+    ) {
+      return;
+    }
+
+    console.log(output);
+    return;
+  }
+
   if (command === "pencil-lock") {
     handlePencilLockCommand(argv, homeDir);
     return;

package/lib/design-source-registry.js

@@ -0,0 +1,146 @@
+const path = require("path");
+const { isPathInside } = require("./fs-safety");
+
+const REGISTERED_PEN_PATTERN = /\.da-vinci\/designs\/[^\s`]+\.pen/g;
+
+function normalizeProjectRoot(projectRoot) {
+  return path.resolve(projectRoot || process.cwd());
+}
+
+function collectRegisteredPenReferences(registryText) {
+  const matches = String(registryText || "").match(REGISTERED_PEN_PATTERN) || [];
+  const seen = new Set();
+  const unique = [];
+
+  for (const match of matches) {
+    const normalized = String(match || "").trim();
+    if (!normalized || seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    unique.push(normalized);
+  }
+
+  return unique;
+}
+
+function normalizeBoundPenPath(projectRoot, penPath, options = {}) {
+  const root = normalizeProjectRoot(projectRoot);
+  const raw = typeof penPath === "string" ? penPath.trim() : "";
+
+  if (!raw) {
+    return {
+      ok: false,
+      code: options.missingCode || "missing_path",
+      input: raw,
+      resolvedPath: ""
+    };
+  }
+
+  if (options.rejectNew && raw.toLowerCase() === "new") {
+    return {
+      ok: false,
+      code: options.newCode || "active_editor_new",
+      input: raw,
+      resolvedPath: ""
+    };
+  }
+
+  const resolvedPath = path.normalize(path.isAbsolute(raw) ? raw : path.resolve(root, raw));
+  if (!isPathInside(root, resolvedPath)) {
+    return {
+      ok: false,
+      code: options.outsideCode || "outside_project_root",
+      input: raw,
+      resolvedPath
+    };
+  }
+
+  if (options.requirePenExtension !== false && !/\.pen$/i.test(resolvedPath)) {
+    return {
+      ok: false,
+      code: options.extensionCode || "not_pen_path",
+      input: raw,
+      resolvedPath
+    };
+  }
+
+  return {
+    ok: true,
+    code: "ok",
+    input: raw,
+    resolvedPath
+  };
+}
+
+function normalizeRegisteredPenPath(projectRoot, penPath) {
+  return normalizeBoundPenPath(projectRoot, penPath, {
+    missingCode: "registered_pen_missing",
+    outsideCode: "registered_pen_outside_project_root",
+    extensionCode: "registered_pen_not_pen_path"
+  });
+}
+
+function normalizeSessionPenPath(projectRoot, penPath) {
+  return normalizeBoundPenPath(projectRoot, penPath, {
+    missingCode: "session_pen_missing",
+    outsideCode: "session_pen_outside_project_root",
+    extensionCode: "session_pen_not_pen_path"
+  });
+}
+
+function normalizeActiveEditorPath(projectRoot, activeEditorPath) {
+  return normalizeBoundPenPath(projectRoot, activeEditorPath, {
+    rejectNew: true,
+    missingCode: "active_editor_missing",
+    newCode: "active_editor_new",
+    outsideCode: "active_editor_outside_project_root",
+    extensionCode: "active_editor_not_pen_path"
+  });
+}
+
+function collectRegisteredPenPaths(projectRoot, registryText) {
+  const root = normalizeProjectRoot(projectRoot);
+  const references = collectRegisteredPenReferences(registryText);
+  const validPaths = [];
+  const escapedPaths = [];
+  const seenResolved = new Set();
+
+  for (const relativePath of references) {
+    const normalized = normalizeRegisteredPenPath(root, relativePath);
+    if (normalized.ok) {
+      if (!seenResolved.has(normalized.resolvedPath)) {
+        seenResolved.add(normalized.resolvedPath);
+        validPaths.push(normalized.resolvedPath);
+      }
+      continue;
+    }
+
+    if (normalized.code === "registered_pen_outside_project_root") {
+      escapedPaths.push({
+        relativePath,
+        resolvedPath: normalized.resolvedPath
+      });
+    }
+  }
+
+  return {
+    validPaths,
+    escapedPaths
+  };
+}
+
+function resolvePreferredRegisteredPenPath(projectRoot, registryText) {
+  const resolved = collectRegisteredPenPaths(projectRoot, registryText);
+  return resolved.validPaths[0] || "";
+}
+
+module.exports = {
+  collectRegisteredPenReferences,
+  normalizeBoundPenPath,
+  normalizeRegisteredPenPath,
+  normalizeSessionPenPath,
+  normalizeActiveEditorPath,
+  collectRegisteredPenPaths,
+  resolvePreferredRegisteredPenPath
+};