@xenonbyte/da-vinci-workflow 0.2.3 → 0.2.4

package/lib/cli.js

@@ -79,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;
@@ -101,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",
@@ -163,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" },
@@ -498,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",
@@ -1000,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;
     }
 
@@ -1160,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");

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