@xenonbyte/da-vinci-workflow 0.2.3 → 0.2.4

package/lib/planning-parsers.js

@@ -1,7 +1,11 @@
 const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
-const { getMarkdownSection } = require("./audit-parsers");
+const {
+  getMarkdownSection,
+  parseDisciplineMarkers,
+  DISCIPLINE_MARKER_NAMES
+} = require("./audit-parsers");
 const { parseRuntimeSpecMarkdown } = require("./artifact-parsers");
 const { pathExists, readTextIfExists } = require("./utils");
 
@@ -350,33 +354,239 @@ function parsePageMapArtifact(text) {
   };
 }
 
+function parseInlineCodeTokens(line) {
+  const tokens = [];
+  const matches = String(line || "").matchAll(/`([^`]+)`/g);
+  for (const match of matches) {
+    const token = String(match[1] || "").trim();
+    if (token) {
+      tokens.push(token);
+    }
+  }
+  return tokens;
+}
+
+function normalizeExecutionIntent(text) {
+  const normalized = normalizeText(text);
+  if (!normalized) {
+    return "";
+  }
+  if (/bounded parallel|parallel bounded|parallel-safe/.test(normalized)) {
+    return "bounded_parallel";
+  }
+  if (/serial|sequential|one by one/.test(normalized)) {
+    return "serial";
+  }
+  if (/review required|review-required|review heavy|spec review|quality review/.test(normalized)) {
+    return "review_required";
+  }
+  return "";
+}
+
+function hasVerificationIntent(text) {
+  return /verify|verification|coverage|assert|validate|smoke/i.test(String(text || ""));
+}
+
+function hasTestingIntent(text) {
+  return /(?:^|\b)(test|tests|unit test|integration test|e2e|regression|tdd|coverage)(?:\b|$)/i.test(
+    String(text || "")
+  );
+}
+
+function hasReviewIntent(text) {
+  return /review|reviewer|spec review|quality review|qa|audit/i.test(String(text || ""));
+}
+
+function looksLikeCodeChange(text) {
+  return /implement|modify|update|add|create|refactor|fix|remove|rename|rewrite|harden|extend/i.test(
+    String(text || "")
+  );
+}
+
+function isPlaceholderText(text) {
+  return /\b(TBD|TODO|implement later|later fill|to be decided)\b/i.test(String(text || ""));
+}
+
+function extractFileReferences(text) {
+  const references = [];
+  const seen = new Set();
+  const addReference = (value) => {
+    const candidate = String(value || "")
+      .replace(/[`"'(),]/g, "")
+      .trim();
+    if (!candidate) {
+      return;
+    }
+    if (!/[./]/.test(candidate)) {
+      return;
+    }
+    if (candidate.length < 3) {
+      return;
+    }
+    if (seen.has(candidate)) {
+      return;
+    }
+    seen.add(candidate);
+    references.push(candidate);
+  };
+
+  for (const token of parseInlineCodeTokens(text)) {
+    addReference(token);
+  }
+  const plainMatches = String(text || "").matchAll(/(?:^|[\s(])([A-Za-z0-9._/-]+(?:\.[A-Za-z0-9_*.-]+|\/))(?:$|[\s),])/g);
+  for (const match of plainMatches) {
+    addReference(match[1]);
+  }
+  return references;
+}
+
+function extractVerificationCommands(text) {
+  const commands = [];
+  const supportedCommandPattern =
+    /^(?:da-vinci\s+verify-(?:bindings|implementation|structure|coverage)|npm|pnpm|yarn|bun|node|npx|pytest|go test|cargo test|dotnet test|mvn test|gradle test|make test|vitest|jest)\b/i;
+  const addCommand = (value) => {
+    const command = String(value || "").trim();
+    if (!command) {
+      return;
+    }
+    if (!/\s/.test(command)) {
+      return;
+    }
+    if (!supportedCommandPattern.test(command)) {
+      return;
+    }
+    commands.push(command);
+  };
+  for (const token of parseInlineCodeTokens(text)) {
+    addCommand(token);
+  }
+  return unique(commands);
+}
+
+function analyzeTaskGroup(section) {
+  const targetFiles = [];
+  const verificationActions = [];
+  const verificationCommands = [];
+  const placeholderItems = [];
+  const rawFileReferences = [];
+  const executionHints = [];
+
+  const lines = Array.isArray(section.lines) ? section.lines : [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = String(lines[index] || "");
+    rawFileReferences.push(...extractFileReferences(line));
+    if (isPlaceholderText(line)) {
+      placeholderItems.push(line.trim());
+    }
+    if (hasVerificationIntent(line)) {
+      verificationActions.push(line.trim());
+    }
+    verificationCommands.push(...extractVerificationCommands(line));
+    const executionIntent = normalizeExecutionIntent(line);
+    if (executionIntent) {
+      executionHints.push(executionIntent);
+    }
+
+    if (/^\s*target files\s*:\s*$/i.test(line)) {
+      for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+        const followLine = String(lines[cursor] || "");
+        if (/^\s*$/.test(followLine)) {
+          continue;
+        }
+        if (/^\s{0,3}##\s+/.test(followLine)) {
+          break;
+        }
+        if (/^\s*[A-Za-z][A-Za-z0-9 _-]{0,80}\s*:\s*$/.test(followLine)) {
+          break;
+        }
+        const itemMatch = followLine.match(/^\s*-\s+(.+)$/);
+        if (!itemMatch) {
+          break;
+        }
+        const entry = String(itemMatch[1] || "").trim();
+        if (!entry) {
+          continue;
+        }
+        targetFiles.push(...extractFileReferences(entry));
+      }
+    }
+  }
+
+  for (const item of section.checklistItems) {
+    rawFileReferences.push(...extractFileReferences(item.text));
+    if (isPlaceholderText(item.text)) {
+      placeholderItems.push(item.text);
+    }
+    if (hasVerificationIntent(item.text)) {
+      verificationActions.push(item.text);
+    }
+    verificationCommands.push(...extractVerificationCommands(item.text));
+    const executionIntent = normalizeExecutionIntent(item.text);
+    if (executionIntent) {
+      executionHints.push(executionIntent);
+    }
+  }
+
+  const mergedFileReferences = unique([...targetFiles, ...rawFileReferences]);
+  const titleExecutionIntent = normalizeExecutionIntent(section.title);
+  if (titleExecutionIntent) {
+    executionHints.push(titleExecutionIntent);
+  }
+
+  const joinedContent = [section.title, ...lines, ...section.checklistItems.map((item) => item.text)].join("\n");
+  return {
+    ...section,
+    targetFiles: unique(targetFiles),
+    fileReferences: mergedFileReferences,
+    verificationActions: unique(verificationActions.filter(Boolean)),
+    verificationCommands: unique(verificationCommands),
+    executionIntent: unique(executionHints),
+    reviewIntent: hasReviewIntent(joinedContent),
+    testingIntent: hasTestingIntent(joinedContent),
+    codeChangeLikely: looksLikeCodeChange(joinedContent),
+    placeholderItems: unique(placeholderItems.filter(Boolean))
+  };
+}
+
 function parseTasksArtifact(text) {
   const lines = String(text || "").replace(/\r\n?/g, "\n").split("\n");
   const taskGroups = [];
   const checklistItems = [];
   const checkpointItems = [];
   const sections = [];
+  const markers = parseDisciplineMarkers(text);
   let currentSection = null;
 
-  for (const line of lines) {
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+    const line = lines[lineIndex];
     const groupMatch = line.match(/^\s{0,3}##\s+(\d+(?:\.\d+)*)\.\s+(.+)$/);
     if (groupMatch) {
       const group = {
         id: groupMatch[1],
-        title: String(groupMatch[2] || "").trim()
+        title: String(groupMatch[2] || "").trim(),
+        startLine: lineIndex + 1
       };
       taskGroups.push(group);
       if (currentSection) {
-        sections.push(currentSection);
+        currentSection.endLine = lineIndex;
+        sections.push(analyzeTaskGroup(currentSection));
       }
       currentSection = {
         id: group.id,
         title: group.title,
-        checklistItems: []
+        startLine: lineIndex + 1,
+        endLine: lineIndex + 1,
+        checklistItems: [],
+        lines: []
       };
       continue;
     }
 
+    if (currentSection) {
+      currentSection.lines.push(line);
+      currentSection.endLine = lineIndex + 1;
+    }
+
     const checklistMatch = line.match(/^\s*-\s*\[([ xX])\]\s+(.+)$/);
     if (checklistMatch) {
       const checked = String(checklistMatch[1] || "").toLowerCase() === "x";
@@ -384,33 +594,60 @@ function parseTasksArtifact(text) {
       if (!textValue) {
         continue;
       }
-      checklistItems.push({
+      const item = {
         checked,
-        text: textValue
-      });
+        text: textValue,
+        line: lineIndex + 1
+      };
+      checklistItems.push(item);
       if (currentSection) {
-        currentSection.checklistItems.push({
-          checked,
-          text: textValue
-        });
+        currentSection.checklistItems.push(item);
       }
       if (/checkpoint/i.test(textValue)) {
-        checkpointItems.push({
-          checked,
-          text: textValue
-        });
+        checkpointItems.push(item);
       }
     }
   }
   if (currentSection) {
-    sections.push(currentSection);
+    sections.push(analyzeTaskGroup(currentSection));
   }
 
+  const sectionById = new Map(sections.map((section) => [section.id, section]));
+  const normalizedTaskGroups = taskGroups.map((group) => {
+    const section = sectionById.get(group.id);
+    if (!section) {
+      return group;
+    }
+    return {
+      id: group.id,
+      title: group.title,
+      startLine: group.startLine,
+      endLine: section.endLine,
+      targetFiles: section.targetFiles,
+      fileReferences: section.fileReferences,
+      verificationActions: section.verificationActions,
+      verificationCommands: section.verificationCommands,
+      executionIntent: section.executionIntent,
+      reviewIntent: section.reviewIntent,
+      testingIntent: section.testingIntent,
+      codeChangeLikely: section.codeChangeLikely,
+      placeholderItems: section.placeholderItems,
+      checklistItems: section.checklistItems
+    };
+  });
+
   return {
-    taskGroups,
+    taskGroups: normalizedTaskGroups,
     checklistItems,
     checkpointItems,
     sections,
+    markers,
+    markerSummary: {
+      hasDesignApproval: Boolean(markers.markers[DISCIPLINE_MARKER_NAMES.designApproval]),
+      hasPlanSelfReview: Boolean(markers.markers[DISCIPLINE_MARKER_NAMES.planSelfReview]),
+      hasOperatorReviewAck: Boolean(markers.markers[DISCIPLINE_MARKER_NAMES.operatorReviewAck]),
+      malformedCount: markers.malformed.length
+    },
     text: String(text || "")
   };
 }

package/lib/supervisor-review.js

@@ -67,7 +67,8 @@ function resolveCodexBinaryPath(explicitPath) {
 }
 
 function normalizePositiveInt(value, fallback, minimum = 1, maximum = Number.POSITIVE_INFINITY) {
-  const parsed = Number.parseInt(String(value || ""), 10);
+  const raw = value === undefined || value === null ? "" : String(value).trim();
+  const parsed = Number.parseInt(raw, 10);
   if (!Number.isFinite(parsed)) {
     return fallback;
   }

package/lib/task-execution.js

@@ -0,0 +1,160 @@
+const path = require("path");
+const { resolveChangeDir, unique } = require("./planning-parsers");
+const { writeExecutionSignal } = require("./execution-signals");
+
+const VALID_IMPLEMENTER_STATUSES = new Set([
+  "DONE",
+  "DONE_WITH_CONCERNS",
+  "NEEDS_CONTEXT",
+  "BLOCKED"
+]);
+
+function normalizeStatus(value) {
+  const normalized = String(value || "").trim().toUpperCase();
+  if (!VALID_IMPLEMENTER_STATUSES.has(normalized)) {
+    throw new Error(
+      "`task-execution --status` must be one of DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED."
+    );
+  }
+  return normalized;
+}
+
+function normalizeList(value) {
+  if (Array.isArray(value)) {
+    return unique(value.map((item) => String(item || "").trim()).filter(Boolean));
+  }
+  return unique(
+    String(value || "")
+      .split(/[,\n;]/)
+      .map((item) => item.trim())
+      .filter(Boolean)
+  );
+}
+
+function normalizeTaskGroupId(value) {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    throw new Error("`task-execution` requires `--task-group <id>`.");
+  }
+  return normalized;
+}
+
+function mapImplementerStatusToSignal(status) {
+  if (status === "DONE") {
+    return "PASS";
+  }
+  if (status === "DONE_WITH_CONCERNS" || status === "NEEDS_CONTEXT") {
+    return "WARN";
+  }
+  return "BLOCK";
+}
+
+function buildSurface(taskGroupId) {
+  const safeId = String(taskGroupId || "")
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, "_");
+  return `task-execution.${safeId}`;
+}
+
+function normalizeTaskExecutionEnvelope(input = {}) {
+  const taskGroupId = normalizeTaskGroupId(input.taskGroupId);
+  const status = normalizeStatus(input.status);
+  const summary = String(input.summary || "").trim();
+  if (!summary) {
+    throw new Error("`task-execution` requires `--summary <text>`.");
+  }
+  const changedFiles = normalizeList(input.changedFiles);
+  const testEvidence = normalizeList(input.testEvidence);
+  const concerns = normalizeList(input.concerns);
+  const blockers = normalizeList(input.blockers);
+
+  return {
+    taskGroupId,
+    status,
+    summary,
+    changedFiles,
+    testEvidence,
+    concerns,
+    blockers,
+    recordedAt: new Date().toISOString()
+  };
+}
+
+function writeTaskExecutionEnvelope(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
+  const resolved = resolveChangeDir(projectRoot, requestedChangeId);
+  if (!resolved.changeDir || !resolved.changeId) {
+    const resolveError =
+      Array.isArray(resolved.failures) && resolved.failures.length > 0
+        ? String(resolved.failures[0] || "").trim()
+        : "";
+    throw new Error(resolveError || "Unable to resolve active change for task-execution.");
+  }
+
+  const envelope = normalizeTaskExecutionEnvelope(options);
+  const signalPath = writeExecutionSignal(projectRoot, {
+    changeId: resolved.changeId,
+    surface: buildSurface(envelope.taskGroupId),
+    status: mapImplementerStatusToSignal(envelope.status),
+    advisory: false,
+    strict: true,
+    failures: envelope.status === "BLOCKED" ? envelope.blockers : [],
+    warnings:
+      envelope.status === "DONE_WITH_CONCERNS" || envelope.status === "NEEDS_CONTEXT"
+        ? envelope.concerns
+        : [],
+    notes: [envelope.summary, ...envelope.testEvidence.map((item) => `test: ${item}`)],
+    details: {
+      type: "task_execution",
+      envelope
+    }
+  });
+
+  return {
+    status: mapImplementerStatusToSignal(envelope.status),
+    projectRoot,
+    changeId: resolved.changeId,
+    taskGroupId: envelope.taskGroupId,
+    implementerStatus: envelope.status,
+    summary: envelope.summary,
+    changedFiles: envelope.changedFiles,
+    testEvidence: envelope.testEvidence,
+    concerns: envelope.concerns,
+    blockers: envelope.blockers,
+    signalPath
+  };
+}
+
+function formatTaskExecutionReport(result) {
+  const lines = [
+    "Task execution envelope",
+    `Project: ${result.projectRoot}`,
+    `Change: ${result.changeId}`,
+    `Task group: ${result.taskGroupId}`,
+    `Implementer status: ${result.implementerStatus}`,
+    `Signal status: ${result.status}`,
+    `Summary: ${result.summary}`,
+    `Signal path: ${result.signalPath}`
+  ];
+  if (result.changedFiles.length > 0) {
+    lines.push(`Changed files: ${result.changedFiles.join(", ")}`);
+  }
+  if (result.testEvidence.length > 0) {
+    lines.push(`Test evidence: ${result.testEvidence.join(", ")}`);
+  }
+  if (result.concerns.length > 0) {
+    lines.push(`Concerns: ${result.concerns.join(", ")}`);
+  }
+  if (result.blockers.length > 0) {
+    lines.push(`Blockers: ${result.blockers.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  VALID_IMPLEMENTER_STATUSES,
+  normalizeTaskExecutionEnvelope,
+  writeTaskExecutionEnvelope,
+  formatTaskExecutionReport
+};

package/lib/task-review.js

@@ -0,0 +1,197 @@
+const fs = require("fs");
+const path = require("path");
+const { resolveChangeDir, unique } = require("./planning-parsers");
+const { readExecutionSignals, writeExecutionSignal } = require("./execution-signals");
+const { writeFileAtomic, readTextIfExists } = require("./utils");
+
+const VALID_REVIEW_STAGES = new Set(["spec", "quality"]);
+const VALID_REVIEW_STATUSES = new Set(["PASS", "WARN", "BLOCK"]);
+
+function normalizeReviewStage(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!VALID_REVIEW_STAGES.has(normalized)) {
+    throw new Error("`task-review --stage` must be `spec` or `quality`.");
+  }
+  return normalized;
+}
+
+function normalizeReviewStatus(value) {
+  const normalized = String(value || "").trim().toUpperCase();
+  if (!VALID_REVIEW_STATUSES.has(normalized)) {
+    throw new Error("`task-review --status` must be PASS, WARN, or BLOCK.");
+  }
+  return normalized;
+}
+
+function normalizeTaskGroupId(value) {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    throw new Error("`task-review` requires `--task-group <id>`.");
+  }
+  return normalized;
+}
+
+function normalizeList(value) {
+  if (Array.isArray(value)) {
+    return unique(value.map((item) => String(item || "").trim()).filter(Boolean));
+  }
+  return unique(
+    String(value || "")
+      .split(/[,\n;]/)
+      .map((item) => item.trim())
+      .filter(Boolean)
+  );
+}
+
+function buildSafeTaskGroupId(taskGroupId) {
+  return String(taskGroupId || "")
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, "_");
+}
+
+function buildTaskReviewSurface(taskGroupId, stage) {
+  return `task-review.${buildSafeTaskGroupId(taskGroupId)}.${stage}`;
+}
+
+function mapReviewStatusToSignalStatus(status) {
+  return status;
+}
+
+function normalizeTaskReviewEnvelope(input = {}) {
+  const taskGroupId = normalizeTaskGroupId(input.taskGroupId);
+  const stage = normalizeReviewStage(input.stage);
+  const status = normalizeReviewStatus(input.status);
+  const summary = String(input.summary || "").trim();
+  if (!summary) {
+    throw new Error("`task-review` requires `--summary <text>`.");
+  }
+  const issues = normalizeList(input.issues);
+  const reviewer = String(input.reviewer || "").trim() || "unspecified";
+
+  return {
+    taskGroupId,
+    stage,
+    status,
+    summary,
+    issues,
+    reviewer,
+    recordedAt: new Date().toISOString()
+  };
+}
+
+function findLatestTaskReviewSignal(signals, taskGroupId, stage) {
+  const surface = buildTaskReviewSurface(taskGroupId, stage);
+  return (signals || [])
+    .filter((signal) => String(signal.surface || "") === surface)
+    .sort((left, right) => String(right.timestamp || "").localeCompare(String(left.timestamp || "")))[0] || null;
+}
+
+function appendTaskReviewEvidence(verificationText, envelope) {
+  const existing = String(verificationText || "").trim();
+  const section = [
+    `### Task Review ${envelope.taskGroupId} (${envelope.stage})`,
+    `- Status: ${envelope.status}`,
+    `- Reviewer: ${envelope.reviewer}`,
+    `- Summary: ${envelope.summary}`,
+    `- Issues: ${envelope.issues.length > 0 ? envelope.issues.join("; ") : "none"}`,
+    `- Recorded at: ${envelope.recordedAt}`
+  ].join("\n");
+
+  if (!existing) {
+    return `# Verification\n\n## Task Review Evidence\n\n${section}\n`;
+  }
+  if (!/^\s*##\s+Task Review Evidence\s*$/im.test(existing)) {
+    return `${existing}\n\n## Task Review Evidence\n\n${section}\n`;
+  }
+  return `${existing}\n\n${section}\n`;
+}
+
+function writeTaskReviewEnvelope(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
+  const resolved = resolveChangeDir(projectRoot, requestedChangeId);
+  if (!resolved.changeDir || !resolved.changeId) {
+    const resolveError =
+      Array.isArray(resolved.failures) && resolved.failures.length > 0
+        ? String(resolved.failures[0] || "").trim()
+        : "";
+    throw new Error(resolveError || "Unable to resolve active change for task-review.");
+  }
+
+  const envelope = normalizeTaskReviewEnvelope(options);
+  const existingSignals = readExecutionSignals(projectRoot, { changeId: resolved.changeId });
+
+  if (envelope.stage === "quality") {
+    const specSignal = findLatestTaskReviewSignal(existingSignals, envelope.taskGroupId, "spec");
+    if (!specSignal || String(specSignal.status || "").toUpperCase() !== "PASS") {
+      throw new Error(
+        `Quality review for task group ${envelope.taskGroupId} requires a prior spec review PASS.`
+      );
+    }
+  }
+
+  const signalPath = writeExecutionSignal(projectRoot, {
+    changeId: resolved.changeId,
+    surface: buildTaskReviewSurface(envelope.taskGroupId, envelope.stage),
+    status: mapReviewStatusToSignalStatus(envelope.status),
+    advisory: false,
+    strict: true,
+    failures: envelope.status === "BLOCK" ? envelope.issues : [],
+    warnings: envelope.status === "WARN" ? envelope.issues : [],
+    notes: [envelope.summary, `reviewer: ${envelope.reviewer}`],
+    details: {
+      type: "task_review",
+      envelope
+    }
+  });
+
+  let verificationPath = null;
+  if (options.writeVerification === true) {
+    verificationPath = path.join(resolved.changeDir, "verification.md");
+    fs.mkdirSync(path.dirname(verificationPath), { recursive: true });
+    const nextVerification = appendTaskReviewEvidence(readTextIfExists(verificationPath), envelope);
+    writeFileAtomic(verificationPath, nextVerification);
+  }
+
+  return {
+    status: envelope.status,
+    projectRoot,
+    changeId: resolved.changeId,
+    taskGroupId: envelope.taskGroupId,
+    stage: envelope.stage,
+    summary: envelope.summary,
+    issues: envelope.issues,
+    reviewer: envelope.reviewer,
+    signalPath,
+    verificationPath
+  };
+}
+
+function formatTaskReviewReport(result) {
+  const lines = [
+    "Task review envelope",
+    `Project: ${result.projectRoot}`,
+    `Change: ${result.changeId}`,
+    `Task group: ${result.taskGroupId}`,
+    `Stage: ${result.stage}`,
+    `Status: ${result.status}`,
+    `Reviewer: ${result.reviewer}`,
+    `Summary: ${result.summary}`,
+    `Signal path: ${result.signalPath}`
+  ];
+  if (result.issues.length > 0) {
+    lines.push(`Issues: ${result.issues.join("; ")}`);
+  }
+  if (result.verificationPath) {
+    lines.push(`Verification write-back: ${result.verificationPath}`);
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  VALID_REVIEW_STAGES,
+  VALID_REVIEW_STATUSES,
+  normalizeTaskReviewEnvelope,
+  writeTaskReviewEnvelope,
+  formatTaskReviewReport
+};