@xenonbyte/da-vinci-workflow 0.2.5 → 0.2.7

package/lib/lint-spec.js

@@ -1,9 +1,24 @@
 const fs = require("fs");
 const path = require("path");
-const { pathExists } = require("./utils");
+const { pathExists, readTextIfExists } = require("./utils");
 const { STATUS } = require("./workflow-contract");
 const { parseRuntimeSpecMarkdown } = require("./artifact-parsers");
-const { resolveChangeDir, detectSpecFiles } = require("./planning-parsers");
+const {
+  normalizeText,
+  tokenizeNormalizedWords,
+  textContainsAnyNormalizedToken,
+  detectSpecFiles,
+  parseAmbiguityRecords,
+  readChangeArtifacts,
+  readArtifactTexts
+} = require("./planning-parsers");
+const { buildGateEnvelope, finalizeGateEnvelope, dedupe } = require("./gate-utils");
+const {
+  buildStopWordSet,
+  buildBasePlanningResultEnvelope,
+  finalizePlanningResult,
+  resolveChangeWithFindings
+} = require("./planning-quality-utils");
 
 const MAX_EXAMPLE_ITEMS = 3;
 const TESTABLE_ACCEPTANCE_PATTERN =
@@ -11,43 +26,7 @@ const TESTABLE_ACCEPTANCE_PATTERN =
 const VAGUE_ACCEPTANCE_PATTERN =
   /\b(good|nice|better|clean|intuitive|seamless|smooth|easy|simple|beautiful|fast)\b/i;
 const WORD_PATTERN = /[a-z][a-z0-9_-]{2,}/gi;
-const STOP_WORDS = new Set([
-  "the",
-  "and",
-  "for",
-  "with",
-  "from",
-  "that",
-  "this",
-  "then",
-  "when",
-  "into",
-  "only",
-  "each",
-  "user",
-  "users",
-  "page",
-  "state",
-  "states",
-  "input",
-  "inputs",
-  "output",
-  "outputs",
-  "should",
-  "must",
-  "shall",
-  "able",
-  "about",
-  "after",
-  "before",
-  "during",
-  "while",
-  "where",
-  "there",
-  "have",
-  "has",
-  "into"
-]);
+const STOP_WORDS = buildStopWordSet();
 const EXPLICIT_CONTRADICTORY_PAIRS = [
   ["enabled", "disabled"],
   ["active", "inactive"],
@@ -58,16 +37,66 @@ const EXPLICIT_CONTRADICTORY_PAIRS = [
   ["authenticated", "unauthenticated"],
   ["authorized", "unauthorized"]
 ];
+const PLACEHOLDER_AMBIGUITY_PATTERN = /\b(TODO|TBD|unknown)\b/i;
+const PRINCIPLE_DRIFT_PATTERNS = [
+  {
+    id: "spec_only_truth",
+    message: "artifact implies spec-only truth and conflicts with requirement/design/code truth boundaries",
+    pattern:
+      /\b(spec|specification)\b[\s\S]{0,60}\b(only|single|sole)\b[\s\S]{0,40}\b(truth|source of truth)\b/i
+  },
+  {
+    id: "design_truth_erasure",
+    message: "artifact implies design truth can be ignored in planning",
+    pattern: /\b(ignore|skip|bypass)\b[\s\S]{0,40}\b(design|pencil)\b[\s\S]{0,40}\btruth\b/i
+  },
+  {
+    id: "second_principle_source",
+    message: "artifact introduces a new constitution-style principle source",
+    pattern: /\b(constitution\.md|new constitution|principle manifesto)\b/i
+  }
+];
+const PRINCIPLE_TRUTH_BOUNDARY_CONTRADICTION_PATTERNS = [
+  {
+    id: "design_controls_behavior",
+    message: "artifact assigns behavior authority to design/pencil instead of requirements",
+    pattern:
+      /\b(pencil|design)\b[\s\S]{0,48}\b(decide|decides|determine|determines|govern|governs|define|defines|control|controls|drive|drives)\b[\s\S]{0,48}\bbehavior\b/i
+  },
+  {
+    id: "requirements_controls_presentation",
+    message: "artifact assigns presentation authority to requirements/spec instead of design/pencil",
+    pattern:
+      /\b(requirement|requirements|spec|specification)\b[\s\S]{0,48}\b(decide|decides|determine|determines|govern|governs|define|defines|control|controls|drive|drives)\b[\s\S]{0,48}\b(presentation|visual|layout|ui)\b/i
+  },
+  {
+    id: "code_controls_planning_truth",
+    message: "artifact assigns planning truth authority to code instead of requirements/design boundaries",
+    pattern:
+      /\b(code|implementation)\b[\s\S]{0,48}\b(decide|decides|determine|determines|govern|governs|define|defines|control|controls|drive|drives)\b[\s\S]{0,48}\b(behavior|presentation|visual|layout|ui|requirements?)\b/i
+  }
+];
+const ACCEPTED_AMBIGUITY_CLASSES = new Set([
+  "behavior",
+  "scope",
+  "page",
+  "surface",
+  "state",
+  "input",
+  "data",
+  "acceptance",
+  "design_dependency",
+  "design-dependency"
+]);
 
 function buildResultEnvelope(projectRoot, strict) {
   return {
-    status: STATUS.PASS,
-    failures: [],
-    warnings: [],
-    notes: [],
-    projectRoot,
-    changeId: null,
-    strict,
+    ...buildBasePlanningResultEnvelope(projectRoot, strict),
+    gates: {
+      principleInheritance: null,
+      clarify: null,
+      scenarioQuality: null
+    },
     specs: [],
     summary: {
       checked: 0
@@ -75,45 +104,12 @@ function buildResultEnvelope(projectRoot, strict) {
   };
 }
 
-function finalizeResult(result) {
-  const hasFindings = result.failures.length > 0 || result.warnings.length > 0;
-  if (!hasFindings) {
-    result.status = STATUS.PASS;
-    return result;
-  }
-
-  if (result.strict) {
-    result.status = STATUS.BLOCK;
-    return result;
-  }
-
-  result.status = STATUS.WARN;
-  return result;
-}
-
-function normalizeText(value) {
-  return String(value || "")
-    .toLowerCase()
-    .replace(/[`*_~]/g, "")
-    .replace(/\s+/g, " ")
-    .trim();
-}
-
 function toKeywordSet(value) {
-  const words = String(value || "").match(WORD_PATTERN) || [];
-  return new Set(
-    words
-      .map((word) => String(word || "").toLowerCase())
-      .filter((word) => word && !STOP_WORDS.has(word))
-  );
+  return new Set(tokenizeNormalizedWords(value, { pattern: WORD_PATTERN, stopWords: STOP_WORDS }));
 }
 
 function containsAnyKeyword(text, keywords) {
-  if (!Array.isArray(keywords) || keywords.length === 0) {
-    return false;
-  }
-  const source = normalizeText(text);
-  return keywords.some((keyword) => source.includes(keyword));
+  return textContainsAnyNormalizedToken(text, keywords);
 }
 
 function expandCoverageKeywords(keywords) {
@@ -139,8 +135,298 @@ function expandCoverageKeywords(keywords) {
   return dedupe(expanded);
 }
 
-function dedupe(values) {
-  return Array.from(new Set((values || []).filter(Boolean)));
+function collectPrincipleInheritanceGate(projectRoot, artifactEntries, strict = false) {
+  const gate = buildGateEnvelope("principleInheritance");
+  const repoPrinciplesPath = path.join(projectRoot, "openspec", "config.yaml");
+  const projectPrinciplesPath = path.join(projectRoot, "DA-VINCI.md");
+  const repoPrinciplesText = readTextIfExists(repoPrinciplesPath);
+  const projectPrinciplesText = readTextIfExists(projectPrinciplesPath);
+  if (!pathExists(repoPrinciplesPath)) {
+    gate.compatibility.push("repo-level principle source is missing (`openspec/config.yaml`).");
+  }
+  if (!pathExists(projectPrinciplesPath)) {
+    gate.compatibility.push("project-level principle source is missing (`DA-VINCI.md`); repo-level baseline only.");
+  } else if (projectPrinciplesText && /constitution\.md|principle manifesto|new constitution/i.test(projectPrinciplesText)) {
+    gate.blocking.push(
+      `DA-VINCI.md introduces a second constitution-style principle source and violates inheritance contract.`
+    );
+    gate.evidence.push("DA-VINCI.md");
+  }
+
+  const repoHasTruthBoundary =
+    /requirements.*behavior[\s\S]{0,80}pencil.*presentation[\s\S]{0,80}code/sim.test(
+      String(repoPrinciplesText || "")
+    ) || /requirements decide behavior/i.test(String(repoPrinciplesText || ""));
+  const collectTruthBoundaryContradictions = (text) => {
+    const findings = [];
+    const payload = String(text || "");
+    for (const pattern of PRINCIPLE_TRUTH_BOUNDARY_CONTRADICTION_PATTERNS) {
+      if (!pattern.pattern.test(payload)) {
+        continue;
+      }
+      findings.push(pattern.message);
+    }
+    return dedupe(findings);
+  };
+  if (repoHasTruthBoundary && projectPrinciplesText) {
+    for (const pattern of PRINCIPLE_DRIFT_PATTERNS) {
+      if (!pattern.pattern.test(projectPrinciplesText)) {
+        continue;
+      }
+      gate.blocking.push(
+        `DA-VINCI.md conflicts with repo-level principle baseline (\`openspec/config.yaml\`): ${pattern.message}.`
+      );
+      gate.evidence.push("openspec/config.yaml");
+      gate.evidence.push("DA-VINCI.md");
+    }
+    for (const message of collectTruthBoundaryContradictions(projectPrinciplesText)) {
+      gate.blocking.push(
+        `DA-VINCI.md conflicts with repo-level principle baseline (\`openspec/config.yaml\`): ${message}.`
+      );
+      gate.evidence.push("openspec/config.yaml");
+      gate.evidence.push("DA-VINCI.md");
+    }
+  }
+
+  for (const entry of artifactEntries) {
+    const text = String(entry.text || "");
+    for (const pattern of PRINCIPLE_DRIFT_PATTERNS) {
+      if (!pattern.pattern.test(text)) {
+        continue;
+      }
+      gate.blocking.push(
+        `${entry.path}: ${pattern.message} (violated source: openspec/config.yaml + DA-VINCI.md inheritance boundary).`
+      );
+      gate.evidence.push(entry.path);
+    }
+    if (repoHasTruthBoundary) {
+      for (const message of collectTruthBoundaryContradictions(text)) {
+        gate.blocking.push(
+          `${entry.path}: ${message} (violated source: openspec/config.yaml + DA-VINCI.md inheritance boundary).`
+        );
+        gate.evidence.push(entry.path);
+      }
+    }
+  }
+
+  return finalizeGateEnvelope(gate, {
+    strict,
+    // Missing project-level refinements are compatibility-only and must not become WARN by default.
+    warnOnCompatibility: false
+  });
+}
+
+function collectClarifyGate(artifactEntries, strict = false) {
+  const gate = buildGateEnvelope("clarify", { includeBounded: true });
+  let explicitRecordCount = 0;
+  for (const entry of artifactEntries) {
+    const parsed = parseAmbiguityRecords(entry.text);
+    const explicitRecordLines = new Set((parsed.records || []).map((record) => Number(record.line)));
+    for (const malformed of parsed.malformed) {
+      gate.advisory.push(
+        `${entry.path}:${malformed.line}: malformed ambiguity record (${malformed.reason}).`
+      );
+      gate.evidence.push(`${entry.path}:${malformed.line}`);
+    }
+    for (const record of parsed.records) {
+      explicitRecordCount += 1;
+      const metadata = record.metadata || {};
+      const summary = `${entry.path}:${record.line}: ${record.ambiguityClass} - ${record.summary}`;
+      gate.evidence.push(`${entry.path}:${record.line}`);
+      if (!ACCEPTED_AMBIGUITY_CLASSES.has(record.ambiguityClass)) {
+        gate.advisory.push(
+          `${entry.path}:${record.line}: ambiguity class "${record.ambiguityClass}" is non-canonical and should be normalized.`
+        );
+      }
+      if (record.severity === "blocking") {
+        gate.blocking.push(summary);
+        continue;
+      }
+      if (record.severity === "bounded") {
+        const missingKeys = ["owner", "impact", "next", "artifact"].filter((key) => !metadata[key]);
+        if (missingKeys.length > 0) {
+          gate.blocking.push(`${summary} (bounded record missing: ${missingKeys.join(", ")}).`);
+        } else {
+          gate.bounded.push(summary);
+        }
+        continue;
+      }
+      gate.advisory.push(summary);
+    }
+
+    const lines = String(entry.text || "").replace(/\r\n?/g, "\n").split("\n");
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+      const line = String(lines[lineIndex] || "");
+      if (!PLACEHOLDER_AMBIGUITY_PATTERN.test(line)) {
+        continue;
+      }
+      if (explicitRecordLines.has(lineIndex + 1)) {
+        continue;
+      }
+      gate.blocking.push(
+        `${entry.path}:${lineIndex + 1}: unresolved placeholder-style ambiguity (${line.trim().slice(0, 120)}).`
+      );
+      gate.evidence.push(`${entry.path}:${lineIndex + 1}`);
+    }
+  }
+
+  if (explicitRecordCount === 0) {
+    gate.compatibility.push(
+      "no explicit ambiguity records found; fallback placeholder heuristics applied (legacy compatibility)."
+    );
+  }
+
+  return finalizeGateEnvelope(gate, {
+    strict,
+    includeBounded: true,
+    warnOnBounded: false
+  });
+}
+
+function isScenarioShapedAcceptance(itemText) {
+  const text = String(itemText || "");
+  const hasTrigger = /\b(when|if|on|after|before|while)\b/i.test(text);
+  const hasOutcomeVerb =
+    /\b(show|shows|render|renders|return|returns|emit|emits|display|displays|appear|appears|visible|hidden|error|success|retry|fallback|within)\b/i.test(
+      text
+    );
+  const hasMeasuredOutcome =
+    /\b(within|at\s+most|no\s+more\s+than|less\s+than|greater\s+than|at\s+least)\s+\d+\b/i.test(text) ||
+    /\b\d+(?:\.\d+)?\s*(ms|s|sec|secs|seconds|minutes?|hours?|px|%)\b/i.test(text);
+  const hasOutcome = hasOutcomeVerb || hasMeasuredOutcome;
+  return hasTrigger && hasOutcome;
+}
+
+function collectScenarioQualityGate(specRecords, strict = false) {
+  const gate = buildGateEnvelope("scenarioQuality");
+  for (const record of specRecords) {
+    const acceptanceItems =
+      record && record.parsed && record.parsed.sections && record.parsed.sections.acceptance
+        ? record.parsed.sections.acceptance.items
+        : [];
+    const behaviorItems =
+      record && record.parsed && record.parsed.sections && record.parsed.sections.behavior
+        ? record.parsed.sections.behavior.items
+        : [];
+    const stateItems =
+      record && record.parsed && record.parsed.sections && record.parsed.sections.states
+        ? record.parsed.sections.states.items
+        : [];
+    const inputItems =
+      record && record.parsed && record.parsed.sections && record.parsed.sections.inputs
+        ? record.parsed.sections.inputs.items
+        : [];
+    const outputItems =
+      record && record.parsed && record.parsed.sections && record.parsed.sections.outputs
+        ? record.parsed.sections.outputs.items
+        : [];
+    const edgeCaseItems =
+      record && record.parsed && record.parsed.sections && record.parsed.sections.edgeCases
+        ? record.parsed.sections.edgeCases.items
+        : [];
+
+    if (!Array.isArray(acceptanceItems) || acceptanceItems.length === 0) {
+      continue;
+    }
+    const shaped = acceptanceItems.filter((item) => isScenarioShapedAcceptance(item));
+    if (shaped.length === 0) {
+      gate.blocking.push(
+        `${record.path}: acceptance section is non-empty but has no scenario-shaped acceptance item.`
+      );
+      gate.evidence.push(`${record.path}:Acceptance`);
+      continue;
+    }
+
+    const hasScenarioIds = acceptanceItems.some((item) => /\bscenario[-_ ]?\d+\b/i.test(String(item || "")));
+    if (!hasScenarioIds) {
+      gate.compatibility.push(
+        `${record.path}: acceptance remains compatible without explicit scenario ids (legacy runtime schema).`
+      );
+    }
+
+    if (shaped.length < acceptanceItems.length) {
+      gate.advisory.push(
+        `${record.path}: ${acceptanceItems.length - shaped.length} acceptance item(s) remain weakly scenario-shaped.`
+      );
+      gate.evidence.push(`${record.path}:Acceptance`);
+    }
+
+    const behaviorText = behaviorItems.join(" ");
+    const acceptanceText = acceptanceItems.join(" ");
+    const behaviorAcceptanceText = `${behaviorText} ${acceptanceText}`.trim();
+    for (const stateItem of stateItems) {
+      const keywords = expandCoverageKeywords(Array.from(toKeywordSet(stateItem)));
+      if (keywords.length === 0) {
+        continue;
+      }
+      if (!containsAnyKeyword(behaviorAcceptanceText, keywords)) {
+        gate.advisory.push(
+          `${record.path}: state/behavior/acceptance coherence gap for state "${stateItem}".`
+        );
+        gate.evidence.push(`${record.path}:States`);
+      }
+    }
+
+    for (const inputItem of inputItems) {
+      const keywords = Array.from(toKeywordSet(inputItem));
+      if (keywords.length === 0) {
+        continue;
+      }
+      if (!containsAnyKeyword(`${behaviorText} ${acceptanceText}`, keywords)) {
+        gate.advisory.push(
+          `${record.path}: input linkage gap for "${inputItem}" (not connected to behavior/acceptance).`
+        );
+        gate.evidence.push(`${record.path}:Inputs`);
+      }
+    }
+    for (const outputItem of outputItems) {
+      const keywords = Array.from(toKeywordSet(outputItem));
+      if (keywords.length === 0) {
+        continue;
+      }
+      if (!containsAnyKeyword(`${behaviorText} ${acceptanceText}`, keywords)) {
+        gate.advisory.push(
+          `${record.path}: output linkage gap for "${outputItem}" (not connected to behavior/acceptance).`
+        );
+        gate.evidence.push(`${record.path}:Outputs`);
+      }
+    }
+    for (const edgeCaseItem of edgeCaseItems) {
+      const keywords = Array.from(toKeywordSet(edgeCaseItem));
+      if (keywords.length === 0) {
+        continue;
+      }
+      const sourceText = `${behaviorText} ${acceptanceText} ${stateItems.join(" ")} ${inputItems.join(" ")}`;
+      if (!containsAnyKeyword(sourceText, keywords)) {
+        gate.advisory.push(
+          `${record.path}: edge-case linkage gap for "${edgeCaseItem}" (not traceable to behavior/state/input/acceptance).`
+        );
+        gate.evidence.push(`${record.path}:Edge Cases`);
+      }
+    }
+  }
+  return finalizeGateEnvelope(gate, {
+    strict,
+    warnOnCompatibility: false
+  });
+}
+
+function attachGateFindings(result, gate) {
+  const gateId = gate && gate.id ? gate.id : "unknown";
+  for (const finding of gate.blocking || []) {
+    result.failures.push(`[gate:${gateId}] ${finding}`);
+  }
+  for (const finding of gate.advisory || []) {
+    result.warnings.push(`[gate:${gateId}] ${finding}`);
+  }
+  for (const finding of gate.compatibility || []) {
+    result.notes.push(`[gate:${gateId}] ${finding}`);
+  }
+  if (gateId === "clarify") {
+    for (const finding of gate.bounded || []) {
+      result.notes.push(`[gate:${gateId}] bounded ambiguity: ${finding}`);
+    }
+  }
 }
 
 function appendSectionPresenceFindings(relativePath, parsed, failures) {
@@ -232,24 +518,10 @@ function appendStateContradictionFindings(relativePath, parsed, warnings) {
 
 function appendCoverageFindings(relativePath, parsed, warnings) {
   const behaviorItems = parsed.sections.behavior ? parsed.sections.behavior.items : [];
-  const stateItems = parsed.sections.states ? parsed.sections.states.items : [];
   const acceptanceItems = parsed.sections.acceptance ? parsed.sections.acceptance.items : [];
 
   const behaviorText = behaviorItems.join(" ");
   const acceptanceText = acceptanceItems.join(" ");
-  const combinedCoverageText = `${behaviorText} ${acceptanceText}`.trim();
-
-  for (const stateItem of stateItems) {
-    const keywords = expandCoverageKeywords(Array.from(toKeywordSet(stateItem)));
-    if (keywords.length === 0) {
-      continue;
-    }
-    if (!containsAnyKeyword(combinedCoverageText, keywords)) {
-      warnings.push(
-        `${relativePath}: state coverage gap: "${stateItem}" does not appear in behavior or acceptance sections.`
-      );
-    }
-  }
 
   const uncoveredBehaviorItems = [];
   for (const behaviorItem of behaviorItems) {
@@ -270,13 +542,6 @@ function appendCoverageFindings(relativePath, parsed, warnings) {
   }
 }
 
-function resolveChange(projectRoot, requestedChangeId, failures, notes) {
-  const resolved = resolveChangeDir(projectRoot, requestedChangeId);
-  failures.push(...resolved.failures);
-  notes.push(...resolved.notes);
-  return resolved.changeDir;
-}
-
 function lintRuntimeSpecs(projectPathInput, options = {}) {
   const projectRoot = path.resolve(projectPathInput || process.cwd());
   const strict = options.strict === true;
@@ -286,13 +551,13 @@ function lintRuntimeSpecs(projectPathInput, options = {}) {
   if (!pathExists(projectRoot)) {
     result.failures.push(`Project path does not exist: ${projectRoot}`);
     result.notes.push("lint-spec uses advisory mode by default; use `--strict` to block on findings.");
-    return finalizeResult(result);
+    return finalizePlanningResult(result);
   }
 
-  const changeDir = resolveChange(projectRoot, requestedChangeId, result.failures, result.notes);
+  const changeDir = resolveChangeWithFindings(projectRoot, requestedChangeId, result.failures, result.notes);
   if (!changeDir) {
     result.notes.push("lint-spec uses advisory mode by default; use `--strict` to block on findings.");
-    return finalizeResult(result);
+    return finalizePlanningResult(result);
   }
   result.changeId = path.basename(changeDir);
 
@@ -301,13 +566,19 @@ function lintRuntimeSpecs(projectPathInput, options = {}) {
   if (specFiles.length === 0) {
     result.failures.push("No runtime spec files found under `.da-vinci/changes/<change-id>/specs/*/spec.md`.");
     result.notes.push("lint-spec uses advisory mode by default; use `--strict` to block on findings.");
-    return finalizeResult(result);
+    return finalizePlanningResult(result);
   }
 
+  const specRecords = [];
   for (const specPath of specFiles) {
     const relativePath = path.relative(projectRoot, specPath) || specPath;
     const raw = fs.readFileSync(specPath, "utf8");
     const parsed = parseRuntimeSpecMarkdown(raw);
+    specRecords.push({
+      path: relativePath,
+      text: raw,
+      parsed
+    });
     const fileFailures = [];
     const fileWarnings = [];
     const fileNotes = [];
@@ -352,13 +623,36 @@ function lintRuntimeSpecs(projectPathInput, options = {}) {
     });
   }
 
+  const changeArtifacts = readChangeArtifacts(projectRoot, result.changeId);
+  const changeArtifactTexts = readArtifactTexts(changeArtifacts);
+  const artifactEntries = [
+    ...Object.entries(changeArtifactTexts)
+      .filter(([, text]) => String(text || "").trim())
+      .map(([key, text]) => ({
+        path: path.relative(projectRoot, changeArtifacts[`${key}Path`]) || changeArtifacts[`${key}Path`],
+        text
+      })),
+    ...specRecords.map((record) => ({
+      path: record.path,
+      text: record.text
+    }))
+  ];
+
+  result.gates.principleInheritance = collectPrincipleInheritanceGate(projectRoot, artifactEntries, strict);
+  result.gates.clarify = collectClarifyGate(artifactEntries, strict);
+  result.gates.scenarioQuality = collectScenarioQualityGate(specRecords, strict);
+
+  attachGateFindings(result, result.gates.principleInheritance);
+  attachGateFindings(result, result.gates.clarify);
+  attachGateFindings(result, result.gates.scenarioQuality);
+
   result.summary.checked = result.specs.length;
   result.failures = dedupe(result.failures);
   result.warnings = dedupe(result.warnings);
   result.notes = dedupe(result.notes);
   result.notes.push("lint-spec uses advisory mode by default; use `--strict` to block on findings.");
 
-  return finalizeResult(result);
+  return finalizePlanningResult(result);
 }
 
 function formatLintSpecReport(result) {