@xenonbyte/da-vinci-workflow 0.2.5 → 0.2.7

package/lib/install.js

@@ -18,6 +18,7 @@ const REQUIRED_FILES = [
   ...listFiles(path.join(REPO_ROOT, "docs")).map((filePath) => path.relative(REPO_ROOT, filePath)),
   ...listFiles(path.join(REPO_ROOT, "examples")).map((filePath) => path.relative(REPO_ROOT, filePath))
 ];
+const SUPPORTED_PLATFORMS = ["codex", "claude", "gemini"];
 
 const CODEX_PROMPT_TARGET_PAIRS = listFiles(path.join(REPO_ROOT, "commands", "codex", "prompts")).map(
   (filePath) => ({
@@ -90,7 +91,7 @@ function resolveHome(homeDir) {
 
 function parsePlatforms(raw) {
   if (!raw || raw === "all") {
-    return ["codex", "claude", "gemini"];
+    return SUPPORTED_PLATFORMS.slice();
   }
 
   const platforms = raw
@@ -99,7 +100,7 @@ function parsePlatforms(raw) {
     .filter(Boolean);
 
   const unique = [...new Set(platforms)];
-  const invalid = unique.filter((value) => !["codex", "claude", "gemini"].includes(value));
+  const invalid = unique.filter((value) => !SUPPORTED_PLATFORMS.includes(value));
 
   if (invalid.length > 0) {
     throw new Error(`Unsupported platform value: ${invalid.join(", ")}`);
@@ -108,6 +109,129 @@ function parsePlatforms(raw) {
   return unique;
 }
 
+function summarizePlatformInstallConfidence(statusPayload) {
+  const status = statusPayload && typeof statusPayload === "object" ? statusPayload : {};
+  const codex = status.codex && typeof status.codex === "object" ? status.codex : {};
+  const claude = status.claude && typeof status.claude === "object" ? status.claude : {};
+  const gemini = status.gemini && typeof status.gemini === "object" ? status.gemini : {};
+
+  return {
+    codex: {
+      checks: {
+        prompt: codex.prompt === true,
+        skill: codex.skill === true
+      },
+      missing: [...(codex.promptMissing || []), ...(codex.skillMissing || [])],
+      mismatched: [...(codex.promptMismatched || []), ...(codex.skillMismatched || [])],
+      unreadable: [...(codex.promptUnreadable || []), ...(codex.skillUnreadable || [])]
+    },
+    claude: {
+      checks: {
+        command: claude.command === true,
+        actionSet: claude.actionSet === true
+      },
+      missing: [...(claude.commandMissing || []), ...(claude.actionSetMissing || [])],
+      mismatched: [...(claude.commandMismatched || []), ...(claude.actionSetMismatched || [])],
+      unreadable: [...(claude.commandUnreadable || []), ...(claude.actionSetUnreadable || [])]
+    },
+    gemini: {
+      checks: {
+        command: gemini.command === true,
+        actionSet: gemini.actionSet === true
+      },
+      missing: [...(gemini.commandMissing || []), ...(gemini.actionSetMissing || [])],
+      mismatched: [...(gemini.commandMismatched || []), ...(gemini.actionSetMismatched || [])],
+      unreadable: [...(gemini.commandUnreadable || []), ...(gemini.actionSetUnreadable || [])]
+    }
+  };
+}
+
+function verifyInstall(options = {}) {
+  const homeDir = resolveHome(options.homeDir);
+  const explicitScopeRaw = String(options.platforms || "").trim();
+  const scopeKnown = explicitScopeRaw.length > 0;
+  const selectedPlatforms = scopeKnown ? parsePlatforms(explicitScopeRaw) : [];
+  const status = getStatus({ homeDir });
+  const confidence = summarizePlatformInstallConfidence(status);
+  const platformCoverage = {};
+  const failures = [];
+  const warnings = [];
+  const notes = [];
+
+  for (const platform of SUPPORTED_PLATFORMS) {
+    const selected = selectedPlatforms.includes(platform);
+    const scope = scopeKnown ? (selected ? "selected" : "out_of_scope") : "unknown";
+    const platformConfidence = confidence[platform];
+    const failedChecks = Object.keys(platformConfidence.checks).filter(
+      (checkKey) => platformConfidence.checks[checkKey] !== true
+    );
+    const healthy = failedChecks.length === 0;
+    platformCoverage[platform] = {
+      scope,
+      healthy,
+      checks: platformConfidence.checks,
+      missing: platformConfidence.missing,
+      mismatched: platformConfidence.mismatched,
+      unreadable: platformConfidence.unreadable
+    };
+
+    if (scope === "selected" && !healthy) {
+      failures.push(
+        `${platform} install verification failed for selected scope (${failedChecks.join(
+          ", "
+        )}). Run \`da-vinci install --platform ${platform}\` and re-run verify-install.`
+      );
+    }
+    if (scope === "unknown" && !healthy) {
+      warnings.push(
+        `${platform} install verification is incomplete, but selected platform scope is unknown.`
+      );
+    }
+    if (scope === "out_of_scope" && !healthy) {
+      notes.push(
+        `${platform} is out-of-scope for this verify-install run and is reported as degraded coverage.`
+      );
+    }
+  }
+
+  if (!scopeKnown) {
+    warnings.push(
+      "Selected platform scope is unknown; pass `--platform <value>` so verify-install can evaluate selected targets explicitly."
+    );
+  }
+
+  const statusToken = failures.length > 0 ? "BLOCK" : warnings.length > 0 ? "WARN" : "PASS";
+  const nextSteps = [];
+  if (failures.length > 0) {
+    nextSteps.push("Fix selected-platform install failures, then rerun `da-vinci verify-install`.");
+  }
+  if (!scopeKnown) {
+    nextSteps.push(
+      "Rerun with explicit scope, for example `da-vinci verify-install --platform codex`, to avoid unknown-scope coverage."
+    );
+  }
+  if (statusToken === "PASS") {
+    nextSteps.push(
+      "Continue with repository readiness checks (for example `da-vinci maintainer-readiness`)."
+    );
+  }
+
+  return {
+    status: statusToken,
+    homeDir,
+    scope: {
+      known: scopeKnown,
+      selectedPlatforms,
+      supportedPlatforms: SUPPORTED_PLATFORMS.slice()
+    },
+    platformCoverage,
+    failures: failures,
+    warnings: warnings,
+    notes: notes,
+    nextSteps
+  };
+}
+
 function ensureDir(targetPath) {
   fs.mkdirSync(targetPath, { recursive: true });
 }
@@ -407,25 +531,29 @@ function getStatus(options = {}) {
   };
 }
 
-function validateAssets() {
+function validateAssets(options = {}) {
+  const repoRoot = options.repoRoot ? path.resolve(String(options.repoRoot)) : REPO_ROOT;
   const missing = REQUIRED_FILES.filter((relativePath) => {
-    return !fs.existsSync(path.join(REPO_ROOT, relativePath));
+    return !fs.existsSync(path.join(repoRoot, relativePath));
   });
 
   if (missing.length > 0) {
-    throw new Error(`Missing required assets:\n${missing.join("\n")}`);
+    throw new Error(`Missing required assets under ${repoRoot}:\n${missing.join("\n")}`);
   }
 
   return {
     version: VERSION,
-    requiredAssets: REQUIRED_FILES.length
+    requiredAssets: REQUIRED_FILES.length,
+    repoRoot
   };
 }
 
 module.exports = {
   VERSION,
+  SUPPORTED_PLATFORMS,
   installPlatforms,
   uninstallPlatforms,
   getStatus,
+  verifyInstall,
   validateAssets
 };

package/lib/isolated-worker-handoff.js

@@ -0,0 +1,181 @@
+const VALID_IMPLEMENTER_RESULT_STATUSES = new Set([
+  "DONE",
+  "DONE_WITH_CONCERNS",
+  "NEEDS_CONTEXT",
+  "BLOCKED"
+]);
+
+const IMPLEMENTER_INPUT_REQUIRED_FIELDS = Object.freeze([
+  "changeId",
+  "taskGroupId",
+  "title",
+  "executionIntent",
+  "targetFiles",
+  "fileReferences",
+  "reviewIntent",
+  "verificationActions",
+  "verificationCommands",
+  "canonicalProjectRoot",
+  "isolatedWorkspaceRoot"
+]);
+
+const IMPLEMENTER_RESULT_REQUIRED_FIELDS = Object.freeze([
+  "changeId",
+  "taskGroupId",
+  "status",
+  "summary",
+  "changedFiles",
+  "testEvidence",
+  "concerns",
+  "blockers",
+  "outOfScopeWrites",
+  "recordedAt"
+]);
+
+const IMPLEMENTER_PROGRESS_REQUIRED_FIELDS = Object.freeze([
+  ...IMPLEMENTER_RESULT_REQUIRED_FIELDS,
+  "partial"
+]);
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeList(value) {
+  const source = Array.isArray(value)
+    ? value
+    : String(value || "")
+        .split(/[,\n;]/)
+        .map((item) => item.trim());
+  return Array.from(
+    new Set(
+      source
+        .map((item) => String(item || "").trim())
+        .filter(Boolean)
+    )
+  );
+}
+
+function assertRequiredFields(payload, requiredFields, label) {
+  const missing = requiredFields.filter((field) => !Object.prototype.hasOwnProperty.call(payload || {}, field));
+  if (missing.length > 0) {
+    throw new Error(`${label} is missing required fields: ${missing.join(", ")}`);
+  }
+}
+
+function assertNoUnknownFields(payload, allowedFields, label) {
+  const allowed = new Set(allowedFields);
+  const unknown = Object.keys(payload || {}).filter((field) => !allowed.has(field));
+  if (unknown.length > 0) {
+    throw new Error(`${label} contains unsupported fields: ${unknown.join(", ")}`);
+  }
+}
+
+function normalizeStatus(status) {
+  const normalized = normalizeString(status).toUpperCase();
+  if (!VALID_IMPLEMENTER_RESULT_STATUSES.has(normalized)) {
+    throw new Error(
+      `isolated implementer result status must be one of ${Array.from(VALID_IMPLEMENTER_RESULT_STATUSES).join(", ")}.`
+    );
+  }
+  return normalized;
+}
+
+function normalizeRecordedAt(value, label) {
+  const normalized = normalizeString(value);
+  if (!normalized) {
+    throw new Error(`${label} requires recordedAt.`);
+  }
+  const parsed = Date.parse(normalized);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`${label} recordedAt must be a valid ISO-8601 timestamp.`);
+  }
+  return new Date(parsed).toISOString();
+}
+
+function normalizeIsolatedImplementerInputPayload(payload = {}) {
+  assertRequiredFields(payload, IMPLEMENTER_INPUT_REQUIRED_FIELDS, "isolated implementer input payload");
+  assertNoUnknownFields(payload, IMPLEMENTER_INPUT_REQUIRED_FIELDS, "isolated implementer input payload");
+
+  const changeId = normalizeString(payload.changeId);
+  const taskGroupId = normalizeString(payload.taskGroupId);
+  const title = normalizeString(payload.title);
+  const canonicalProjectRoot = normalizeString(payload.canonicalProjectRoot);
+  const isolatedWorkspaceRoot = normalizeString(payload.isolatedWorkspaceRoot);
+  if (!changeId || !taskGroupId || !title || !canonicalProjectRoot || !isolatedWorkspaceRoot) {
+    throw new Error(
+      "isolated implementer input payload requires non-empty changeId, taskGroupId, title, canonicalProjectRoot, and isolatedWorkspaceRoot."
+    );
+  }
+
+  return {
+    changeId,
+    taskGroupId,
+    title,
+    executionIntent: normalizeList(payload.executionIntent),
+    targetFiles: normalizeList(payload.targetFiles),
+    fileReferences: normalizeList(payload.fileReferences),
+    reviewIntent: payload.reviewIntent === true,
+    verificationActions: normalizeList(payload.verificationActions),
+    verificationCommands: normalizeList(payload.verificationCommands),
+    canonicalProjectRoot,
+    isolatedWorkspaceRoot
+  };
+}
+
+function normalizeIsolatedImplementerResultPayload(payload = {}) {
+  assertRequiredFields(payload, IMPLEMENTER_RESULT_REQUIRED_FIELDS, "isolated implementer result payload");
+  assertNoUnknownFields(payload, IMPLEMENTER_RESULT_REQUIRED_FIELDS, "isolated implementer result payload");
+
+  const changeId = normalizeString(payload.changeId);
+  const taskGroupId = normalizeString(payload.taskGroupId);
+  const summary = normalizeString(payload.summary);
+  if (!changeId || !taskGroupId || !summary) {
+    throw new Error("isolated implementer result payload requires non-empty changeId, taskGroupId, and summary.");
+  }
+
+  return {
+    changeId,
+    taskGroupId,
+    status: normalizeStatus(payload.status),
+    summary,
+    changedFiles: normalizeList(payload.changedFiles),
+    testEvidence: normalizeList(payload.testEvidence),
+    concerns: normalizeList(payload.concerns),
+    blockers: normalizeList(payload.blockers),
+    outOfScopeWrites: normalizeList(payload.outOfScopeWrites),
+    recordedAt: normalizeRecordedAt(payload.recordedAt, "isolated implementer result payload")
+  };
+}
+
+function normalizeIsolatedImplementerProgressPayload(payload = {}) {
+  assertRequiredFields(payload, IMPLEMENTER_PROGRESS_REQUIRED_FIELDS, "isolated implementer progress payload");
+  assertNoUnknownFields(payload, IMPLEMENTER_PROGRESS_REQUIRED_FIELDS, "isolated implementer progress payload");
+  if (payload.partial !== true) {
+    throw new Error("isolated implementer progress payload requires partial=true.");
+  }
+
+  const {
+    partial: _partial,
+    ...resultShape
+  } = payload;
+  const normalizedResult = normalizeIsolatedImplementerResultPayload(resultShape);
+  if (normalizedResult.status === "DONE") {
+    throw new Error("isolated implementer progress payload cannot use status DONE because partial snapshots are non-final.");
+  }
+
+  return {
+    ...normalizedResult,
+    partial: true
+  };
+}
+
+module.exports = {
+  VALID_IMPLEMENTER_RESULT_STATUSES,
+  IMPLEMENTER_INPUT_REQUIRED_FIELDS,
+  IMPLEMENTER_RESULT_REQUIRED_FIELDS,
+  IMPLEMENTER_PROGRESS_REQUIRED_FIELDS,
+  normalizeIsolatedImplementerInputPayload,
+  normalizeIsolatedImplementerResultPayload,
+  normalizeIsolatedImplementerProgressPayload
+};

package/lib/lint-bindings.js

@@ -1,23 +1,24 @@
 const path = require("path");
-const { STATUS } = require("./workflow-contract");
 const {
   unique,
   resolveImplementationLanding,
-  resolveChangeDir,
   parseBindingsArtifact,
   readChangeArtifacts,
   readArtifactTexts
 } = require("./planning-parsers");
+const { buildGateEnvelope, finalizeGateEnvelope } = require("./gate-utils");
+const {
+  buildBasePlanningResultEnvelope,
+  finalizePlanningResult,
+  resolveChangeWithFindings
+} = require("./planning-quality-utils");
 
 function buildEnvelope(projectRoot, strict) {
   return {
-    status: STATUS.PASS,
-    failures: [],
-    warnings: [],
-    notes: [],
-    projectRoot,
-    changeId: null,
-    strict,
+    ...buildBasePlanningResultEnvelope(projectRoot, strict),
+    gates: {
+      bindingsHealth: null
+    },
     summary: {
       mappings: 0,
       malformed: 0
@@ -29,13 +30,19 @@ function finalize(result) {
   result.failures = unique(result.failures);
   result.warnings = unique(result.warnings);
   result.notes = unique(result.notes);
-  const hasFindings = result.failures.length > 0 || result.warnings.length > 0;
-  if (!hasFindings) {
-    result.status = STATUS.PASS;
-    return result;
+  return finalizePlanningResult(result);
+}
+
+function attachBindingsGateFindings(result, gate) {
+  for (const message of gate.blocking || []) {
+    result.failures.push(`[gate:bindingsHealth] ${message}`);
+  }
+  for (const message of gate.advisory || []) {
+    result.warnings.push(`[gate:bindingsHealth] ${message}`);
+  }
+  for (const message of gate.compatibility || []) {
+    result.notes.push(`[gate:bindingsHealth] ${message}`);
   }
-  result.status = result.strict ? STATUS.BLOCK : STATUS.WARN;
-  return result;
 }
 
 function lintBindings(projectPathInput, options = {}) {
@@ -43,20 +50,22 @@ function lintBindings(projectPathInput, options = {}) {
   const strict = options.strict === true;
   const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
   const result = buildEnvelope(projectRoot, strict);
+  const bindingsGate = buildGateEnvelope("bindingsHealth");
 
-  const resolved = resolveChangeDir(projectRoot, requestedChangeId);
-  result.failures.push(...resolved.failures);
-  result.notes.push(...resolved.notes);
-  if (!resolved.changeDir) {
+  const changeDir = resolveChangeWithFindings(projectRoot, requestedChangeId, result.failures, result.notes);
+  if (!changeDir) {
+    result.gates.bindingsHealth = finalizeGateEnvelope(bindingsGate, { strict });
     result.notes.push("lint-bindings defaults to advisory mode; pass `--strict` to block on findings.");
     return finalize(result);
   }
-  result.changeId = resolved.changeId;
+  result.changeId = path.basename(changeDir);
 
-  const artifactPaths = readChangeArtifacts(projectRoot, resolved.changeId);
+  const artifactPaths = readChangeArtifacts(projectRoot, result.changeId);
   const artifacts = readArtifactTexts(artifactPaths);
   if (!artifacts.bindings) {
-    result.failures.push("Missing `pencil-bindings.md` for lint-bindings.");
+    bindingsGate.blocking.push("Missing `pencil-bindings.md` for lint-bindings.");
+    result.gates.bindingsHealth = finalizeGateEnvelope(bindingsGate, { strict });
+    attachBindingsGateFindings(result, result.gates.bindingsHealth);
     result.notes.push("lint-bindings defaults to advisory mode; pass `--strict` to block on findings.");
     return finalize(result);
   }
@@ -66,17 +75,19 @@ function lintBindings(projectPathInput, options = {}) {
   result.summary.malformed = parsed.malformed.length;
 
   if (parsed.mappings.length === 0) {
-    result.failures.push("No implementation-to-Pencil mappings were parsed from `pencil-bindings.md`.");
+    bindingsGate.blocking.push(
+      "No implementation-to-Pencil mappings were parsed from `pencil-bindings.md`."
+    );
   }
   if (parsed.malformed.length > 0) {
     for (const malformed of parsed.malformed) {
-      result.warnings.push(`Malformed binding mapping entry: "${malformed}".`);
+      bindingsGate.advisory.push(`Malformed binding mapping entry: "${malformed}".`);
     }
   }
 
   for (const mapping of parsed.mappings) {
     if (!mapping.implementation || !mapping.designPage) {
-      result.warnings.push(`Malformed binding mapping entry: "${mapping.raw}".`);
+      bindingsGate.advisory.push(`Malformed binding mapping entry: "${mapping.raw}".`);
       continue;
     }
 
@@ -86,21 +97,23 @@ function lintBindings(projectPathInput, options = {}) {
         /missing|todo|gap|pending|temporary/i.test(note)
       );
       if (noteContainsIntentionalGap) {
-        result.warnings.push(
+        bindingsGate.compatibility.push(
           `Unresolved implementation landing for "${mapping.implementation}" (allowed by explicit notes).`
         );
       } else {
-        result.warnings.push(`Unresolved implementation landing for "${mapping.implementation}".`);
+        bindingsGate.advisory.push(`Unresolved implementation landing for "${mapping.implementation}".`);
       }
     }
 
     if (mapping.designSource && !String(mapping.designSource).includes(".pen")) {
-      result.warnings.push(
+      bindingsGate.advisory.push(
         `Binding source for "${mapping.implementation}" does not look like a .pen path: "${mapping.designSource}".`
       );
     }
   }
 
+  result.gates.bindingsHealth = finalizeGateEnvelope(bindingsGate, { strict });
+  attachBindingsGateFindings(result, result.gates.bindingsHealth);
   result.notes.push("lint-bindings defaults to advisory mode; pass `--strict` to block on findings.");
   return finalize(result);
 }