@xenonbyte/da-vinci-workflow 0.2.2 → 0.2.4

package/lib/execution-profile.js

@@ -0,0 +1,143 @@
+const { unique } = require("./planning-parsers");
+
+const ROLE_TAXONOMY = Object.freeze([
+  { id: "coordinator", description: "Own route truth, sequencing, and conflict resolution." },
+  { id: "implementer", description: "Deliver scoped code and docs changes for a task group." },
+  { id: "spec-reviewer", description: "Review task output against spec/plan requirements first." },
+  { id: "quality-reviewer", description: "Review quality, maintainability, and risk after spec pass." },
+  { id: "verifier", description: "Run verification commands and evidence freshness checks." }
+]);
+
+const MODEL_TIER_GUIDANCE = Object.freeze({
+  coordinator: "high",
+  implementer: "balanced",
+  "spec-reviewer": "high",
+  "quality-reviewer": "high",
+  verifier: "balanced"
+});
+
+function normalizeOwnershipToken(value) {
+  const normalized = String(value || "")
+    .trim()
+    .replace(/\\/g, "/")
+    .replace(/^\.?\//, "");
+  if (!normalized) {
+    return "";
+  }
+  const segments = normalized.split("/").filter(Boolean);
+  if (segments.length === 0) {
+    return "";
+  }
+  if (segments.length === 1) {
+    return segments[0];
+  }
+  return `${segments[0]}/${segments[1]}`;
+}
+
+function collectOwnershipKeys(group) {
+  const fromTargets = Array.isArray(group.targetFiles) ? group.targetFiles : [];
+  const fromRefs = Array.isArray(group.fileReferences) ? group.fileReferences : [];
+  return unique([...fromTargets, ...fromRefs].map((item) => normalizeOwnershipToken(item)).filter(Boolean));
+}
+
+function buildOverlapMatrix(groups) {
+  const overlaps = [];
+  for (let left = 0; left < groups.length; left += 1) {
+    for (let right = left + 1; right < groups.length; right += 1) {
+      const leftGroup = groups[left];
+      const rightGroup = groups[right];
+      const shared = leftGroup.ownershipKeys.filter((token) => rightGroup.ownershipKeys.includes(token));
+      if (shared.length === 0) {
+        continue;
+      }
+      overlaps.push({
+        leftTaskGroupId: leftGroup.id,
+        rightTaskGroupId: rightGroup.id,
+        sharedOwnership: shared
+      });
+    }
+  }
+  return overlaps;
+}
+
+function deriveExecutionMode(stage, groups, overlaps) {
+  if (stage !== "build" && stage !== "verify") {
+    return "serial";
+  }
+  if (overlaps.length > 0) {
+    return "serial";
+  }
+  if (groups.some((group) => group.executionIntent.includes("review_required"))) {
+    return "review_heavy";
+  }
+  if (groups.length <= 1) {
+    return "serial";
+  }
+  return "bounded_parallel";
+}
+
+function deriveExecutionProfile(options = {}) {
+  const stage = String(options.stage || "");
+  const sourceTaskGroups = Array.isArray(options.taskGroups) ? options.taskGroups : [];
+  const normalizedGroups = sourceTaskGroups.map((group) => ({
+    id: group.taskGroupId || group.id || "",
+    title: group.title || "",
+    executionIntent: Array.isArray(group.executionIntent) ? group.executionIntent : [],
+    ownershipKeys: collectOwnershipKeys(group),
+    reviewIntent: group.reviewIntent === true
+  }));
+  const groups = normalizedGroups.filter((group) => group.id);
+  const overlaps = buildOverlapMatrix(groups);
+  const mode = deriveExecutionMode(stage, groups, overlaps);
+
+  let maxParallel = 1;
+  if (mode === "bounded_parallel") {
+    maxParallel = Math.min(3, Math.max(2, groups.length));
+  } else if (mode === "review_heavy") {
+    maxParallel = 2;
+  }
+
+  const rationale = [];
+  if (mode === "serial") {
+    if (overlaps.length > 0) {
+      rationale.push("ownership overlap detected across task groups");
+    } else if (stage !== "build" && stage !== "verify") {
+      rationale.push(`stage ${stage || "unknown"} prefers serial progression`);
+    } else {
+      rationale.push("single task-group or unspecified execution intent");
+    }
+  }
+  if (mode === "bounded_parallel") {
+    rationale.push("independent ownership detected across task groups");
+  }
+  if (mode === "review_heavy") {
+    rationale.push("review-required execution intent detected");
+  }
+
+  return {
+    advisory: true,
+    mode,
+    stage,
+    maxParallel,
+    roles: ROLE_TAXONOMY,
+    modelTierGuidance: MODEL_TIER_GUIDANCE,
+    overlaps,
+    rationale,
+    taskGroups: groups.map((group) => ({
+      taskGroupId: group.id,
+      title: group.title,
+      ownershipKeys: group.ownershipKeys,
+      executionIntent: group.executionIntent,
+      recommendedMode:
+        mode === "bounded_parallel" && group.executionIntent.includes("serial")
+          ? "serial"
+          : mode
+    }))
+  };
+}
+
+module.exports = {
+  ROLE_TAXONOMY,
+  MODEL_TIER_GUIDANCE,
+  deriveExecutionProfile
+};

package/lib/execution-signals.js

@@ -48,6 +48,7 @@ function writeExecutionSignal(projectRoot, payload) {
     failures: Array.isArray(payload.failures) ? payload.failures : [],
     warnings: Array.isArray(payload.warnings) ? payload.warnings : [],
     notes: Array.isArray(payload.notes) ? payload.notes : [],
+    details: payload && payload.details !== undefined ? payload.details : null,
     timestamp: new Date().toISOString(),
     changeId
   };
@@ -129,8 +130,25 @@ function summarizeSignalsBySurface(signals) {
   return summary;
 }
 
+function listSignalsBySurfacePrefix(signals, prefix) {
+  const normalizedPrefix = sanitizeSurfaceName(prefix);
+  if (!normalizedPrefix) {
+    return [];
+  }
+  return (signals || [])
+    .filter((signal) => sanitizeSurfaceName(signal.surface || "").startsWith(normalizedPrefix))
+    .sort((left, right) => String(right.timestamp || "").localeCompare(String(left.timestamp || "")));
+}
+
+function getLatestSignalBySurfacePrefix(signals, prefix) {
+  const matches = listSignalsBySurfacePrefix(signals, prefix);
+  return matches.length > 0 ? matches[0] : null;
+}
+
 module.exports = {
   writeExecutionSignal,
   readExecutionSignals,
-  summarizeSignalsBySurface
+  summarizeSignalsBySurface,
+  listSignalsBySurfacePrefix,
+  getLatestSignalBySurfacePrefix
 };

package/lib/lint-tasks.js

@@ -85,6 +85,13 @@ function lintTasks(projectPathInput, options = {}) {
 
   result.summary.groups = parsedTasks.taskGroups.length;
   result.summary.checklistItems = parsedTasks.checklistItems.length;
+  result.summary.discipline = {
+    groupsMissingTargets: 0,
+    groupsMissingExecutionIntent: 0,
+    groupsMissingVerificationCommands: 0,
+    groupsWithPlaceholders: 0,
+    groupsMissingTestingIntent: 0
+  };
 
   if (parsedTasks.taskGroups.length === 0) {
     result.failures.push("`tasks.md` is missing top-level numbered task groups (for example `## 1. Setup`).");
@@ -109,12 +116,86 @@ function lintTasks(projectPathInput, options = {}) {
   }
 
   const hasVerificationAction =
-    parsedTasks.taskGroups.some((group) => /verify|verification|coverage/i.test(group.title)) ||
-    parsedTasks.checklistItems.some((item) => /verify|verification|coverage/i.test(item.text));
+    parsedTasks.taskGroups.some(
+      (group) =>
+        /verify|verification|coverage/i.test(group.title) ||
+        (Array.isArray(group.verificationActions) && group.verificationActions.length > 0)
+    ) || parsedTasks.checklistItems.some((item) => /verify|verification|coverage/i.test(item.text));
   if (!hasVerificationAction) {
     result.warnings.push("Missing explicit verification actions in `tasks.md`.");
   }
 
+  if (parsedTasks.markers && Array.isArray(parsedTasks.markers.malformed) && parsedTasks.markers.malformed.length > 0) {
+    for (const malformed of parsedTasks.markers.malformed) {
+      result.warnings.push(
+        `Malformed discipline marker in tasks at line ${malformed.line}: ${malformed.reason}`
+      );
+    }
+  }
+
+  const markerSummary = parsedTasks.markerSummary || {};
+  if (!markerSummary.hasPlanSelfReview) {
+    result.warnings.push(
+      "Missing `plan_self_review` discipline marker in `tasks.md` (legacy plans may keep advisory fallback)."
+    );
+  }
+  if (!markerSummary.hasOperatorReviewAck) {
+    result.warnings.push(
+      "Missing `operator_review_ack` discipline marker in `tasks.md` (legacy plans may keep advisory fallback)."
+    );
+  }
+
+  for (const group of parsedTasks.taskGroups) {
+    const groupLabel = `${group.id}. ${group.title}`;
+    const hasTargets = Array.isArray(group.targetFiles) && group.targetFiles.length > 0;
+    const hasFileRefs = Array.isArray(group.fileReferences) && group.fileReferences.length > 0;
+    if (!hasTargets && !hasFileRefs) {
+      result.summary.discipline.groupsMissingTargets += 1;
+      result.warnings.push(
+        `Task group ${groupLabel} is missing exact file targets or code-area references.`
+      );
+    }
+
+    if (!Array.isArray(group.executionIntent) || group.executionIntent.length === 0) {
+      result.summary.discipline.groupsMissingExecutionIntent += 1;
+      result.warnings.push(
+        `Task group ${groupLabel} is missing execution-mode hints (serial, bounded parallel, or review-required).`
+      );
+    }
+
+    const hasVerificationCommands =
+      Array.isArray(group.verificationCommands) && group.verificationCommands.length > 0;
+    const hasVerificationIntent =
+      /verify|verification|coverage|test/i.test(group.title) ||
+      (Array.isArray(group.verificationActions) && group.verificationActions.length > 0);
+    if (hasVerificationIntent && !hasVerificationCommands) {
+      result.summary.discipline.groupsMissingVerificationCommands += 1;
+      result.warnings.push(
+        `Task group ${groupLabel} has verification intent but no explicit verification command (for example \`npm test\`).`
+      );
+    }
+
+    if (Array.isArray(group.placeholderItems) && group.placeholderItems.length > 0) {
+      result.summary.discipline.groupsWithPlaceholders += 1;
+      result.warnings.push(
+        `Task group ${groupLabel} contains placeholder wording (${group.placeholderItems.length} item(s)).`
+      );
+    }
+
+    if (group.codeChangeLikely && !group.testingIntent) {
+      result.summary.discipline.groupsMissingTestingIntent += 1;
+      result.warnings.push(
+        `Task group ${groupLabel} appears to change code behavior but omits testing intent.`
+      );
+    }
+
+    if (Array.isArray(group.executionIntent) && group.executionIntent.includes("review_required") && !group.reviewIntent) {
+      result.warnings.push(
+        `Task group ${groupLabel} hints review-required execution but does not declare concrete review intent.`
+      );
+    }
+  }
+
   for (const specRecord of specRecords) {
     const behaviorItems = specRecord.parsed.sections.behavior.items || [];
     for (const behaviorItem of behaviorItems) {
@@ -135,6 +216,9 @@ function lintTasks(projectPathInput, options = {}) {
   }
 
   result.notes.push("lint-tasks defaults to advisory mode; pass `--strict` to block on findings.");
+  result.notes.push(
+    "Strict-promotion guidance: require clean placeholder/file-target/execution-intent/verification-command findings before promoting to build."
+  );
   return finalize(result);
 }
 

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