@xenonbyte/da-vinci-workflow 0.2.5 → 0.2.7

package/lib/scope-check.js

@@ -1,28 +1,125 @@
 const path = require("path");
 const { getMarkdownSection } = require("./audit-parsers");
 const { pathExists, readTextIfExists } = require("./utils");
-const { STATUS } = require("./workflow-contract");
 const {
+  normalizeText: normalizeWhitespace,
+  tokenizeNormalizedWords,
+  textContainsAnyNormalizedToken,
   parseListItems,
   unique,
-  resolveChangeDir,
-  parseRuntimeSpecs
+  parseRuntimeSpecs,
+  parseTasksArtifact,
+  parseBindingsArtifact
 } = require("./planning-parsers");
-
-const PAGE_NAME_PATTERN = /`([^`]+)`|([a-z0-9][a-z0-9 \-/]{1,80}?)\s+pages?\b/gi;
+const {
+  loadAnalyzeEvidenceIndex,
+  resolveAnalyzeEvidenceRefs,
+  loadPlanningAnchorIndex,
+  resolvePlanningAnchorRefs
+} = require("./sidecars");
+const { buildGateEnvelope, finalizeGateEnvelope } = require("./gate-utils");
+const {
+  buildStopWordSet,
+  buildBasePlanningResultEnvelope,
+  finalizePlanningResult,
+  resolveChangeWithFindings
+} = require("./planning-quality-utils");
+
+const PAGE_NAME_PATTERN = /`([^`]+)`|([a-z0-9][a-z0-9 \-/]{1,80}?)\s+pages?\b/i;
+const ANALYZE_TOKEN_PATTERN = /[a-z0-9_-]{3,}/g;
 const STATE_SYNONYMS = {
   success: ["success", "succeed", "succeeds", "succeeded"],
   error: ["error", "fail", "fails", "failed", "failure"],
   loading: ["loading", "load", "spinner"]
 };
-
-function normalizeWhitespace(value) {
-  return String(value || "")
-    .toLowerCase()
-    .replace(/[`*_~]/g, "")
-    .replace(/\s+/g, " ")
-    .trim();
-}
+const ANALYZE_STOP_WORDS = buildStopWordSet(["pages"]);
+const ANALYZE_GENERIC_TASK_TOKENS = buildStopWordSet([
+  "implement",
+  "implementation",
+  "verify",
+  "verification",
+  "run",
+  "test",
+  "tests",
+  "page",
+  "pages",
+  "screen",
+  "screens",
+  "section",
+  "sections",
+  "state",
+  "states",
+  "task",
+  "tasks",
+  "group",
+  "groups",
+  "coverage",
+  "build",
+  "update",
+  "create",
+  "add",
+  "review",
+  "check",
+  "loading",
+  "success",
+  "error",
+  "fallback",
+  "handling",
+  "placeholder",
+  "layout",
+  "copy",
+  "view",
+  "views",
+  "regression",
+  "npm",
+  "pnpm",
+  "yarn",
+  "npx",
+  "node",
+  "for",
+  "with",
+  "from",
+  "into",
+  "when",
+  "then",
+  "this",
+  "that",
+  "and",
+  "the",
+  "all",
+  "both"
+]);
+const PAGE_ACTION_VERBS = new Set([
+  "implement",
+  "create",
+  "add",
+  "update",
+  "refactor",
+  "build",
+  "verify",
+  "test",
+  "run",
+  "check",
+  "document",
+  "wire",
+  "sync",
+  "review",
+  "finalize",
+  "ship",
+  "prepare"
+]);
+const PAGE_COMMAND_HEADS = new Set([
+  "npm",
+  "pnpm",
+  "yarn",
+  "npx",
+  "node",
+  "da-vinci",
+  "git",
+  "bash",
+  "sh",
+  "zsh"
+]);
 
 function normalizePageKey(value) {
   return normalizeWhitespace(value)
@@ -48,12 +145,61 @@ function registerName(map, key, label) {
   }
 }
 
+function normalizePageCandidate(value) {
+  let candidate = String(value || "")
+    .replace(/[`"'()]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!candidate) {
+    return "";
+  }
+  const lowered = normalizeWhitespace(candidate);
+  if (!lowered) {
+    return "";
+  }
+  if (candidate.includes("/") || /\.(?:html?|tsx?|jsx?|vue|svelte|md)$/i.test(candidate)) {
+    return "";
+  }
+  if (/--|<|>/.test(candidate)) {
+    return "";
+  }
+
+  const words = lowered.split(" ").filter(Boolean);
+  if (words.length === 0) {
+    return "";
+  }
+  if (PAGE_COMMAND_HEADS.has(words[0])) {
+    return "";
+  }
+
+  let start = 0;
+  while (start < words.length && PAGE_ACTION_VERBS.has(words[start])) {
+    start += 1;
+  }
+  let end = words.length;
+  while (end > start && /^(?:page|pages|screen|screens|section|sections|layout|copy)$/.test(words[end - 1])) {
+    end -= 1;
+  }
+  const scoped = words.slice(start, end);
+  if (scoped.length === 0 || scoped.length > 4) {
+    return "";
+  }
+  if (scoped.every((token) => token.length <= 2)) {
+    return "";
+  }
+
+  return scoped
+    .map((token) => token.charAt(0).toUpperCase() + token.slice(1))
+    .join(" ");
+}
+
 function extractPageCandidatesFromItem(item) {
   const text = String(item || "");
   const pages = [];
+  const matcher = new RegExp(PAGE_NAME_PATTERN.source, "gi");
   let match;
-  while ((match = PAGE_NAME_PATTERN.exec(text)) !== null) {
-    const pageName = String(match[1] || match[2] || "").trim();
+  while ((match = matcher.exec(text)) !== null) {
+    const pageName = normalizePageCandidate(String(match[1] || match[2] || "").trim());
     if (pageName) {
       pages.push(pageName);
     }
@@ -143,13 +289,23 @@ function parseSpecs(changeDir, projectRoot) {
       const value = String(item || "").split(":")[0].trim();
       return value || item;
     });
+    const behaviorItems = parsed.sections.behavior.items || [];
+    const acceptanceItems = parsed.sections.acceptance.items || [];
+    const inputItems = parsed.sections.inputs.items || [];
+    const outputItems = parsed.sections.outputs.items || [];
+    const edgeCaseItems = parsed.sections.edgeCases.items || [];
     stateNames.push(...states);
     combinedTextChunks.push(text);
     records.push({
       path: relativePath,
       missingSections: parsed.missingSections,
       emptySections: parsed.emptySections,
-      states
+      states,
+      behaviorItems,
+      acceptanceItems,
+      inputItems,
+      outputItems,
+      edgeCaseItems
     });
   }
 
@@ -196,30 +352,32 @@ function parsePencilDesign(text) {
   };
 }
 
+function parseBindings(text) {
+  if (!String(text || "").trim()) {
+    return {
+      mappings: [],
+      designPages: [],
+      implementationPaths: []
+    };
+  }
+  const parsed = parseBindingsArtifact(text);
+  const mappings = Array.isArray(parsed.mappings) ? parsed.mappings : [];
+  return {
+    mappings,
+    designPages: unique(mappings.map((mapping) => String(mapping.designPage || "").trim()).filter(Boolean)),
+    implementationPaths: unique(
+      mappings.map((mapping) => String(mapping.implementation || "").replace(/`/g, "").trim()).filter(Boolean)
+    )
+  };
+}
+
 function parseTasks(text) {
   const normalizedText = normalizeWhitespace(text);
-  const taskGroups = [];
-  const checklistItems = [];
-
-  const lines = String(text || "").replace(/\r\n?/g, "\n").split("\n");
-  for (const line of lines) {
-    const groupMatch = line.match(/^\s{0,3}##\s+(\d+(?:\.\d+)*)\.\s+(.+)$/);
-    if (groupMatch) {
-      taskGroups.push({
-        id: groupMatch[1],
-        title: String(groupMatch[2] || "").trim()
-      });
-      continue;
-    }
-
-    const checklistMatch = line.match(/^\s*-\s*\[[ xX]\]\s+(.+)$/);
-    if (checklistMatch) {
-      const item = String(checklistMatch[1] || "").trim();
-      if (item) {
-        checklistItems.push(item);
-      }
-    }
-  }
+  const parsed = parseTasksArtifact(text);
+  const taskGroups = Array.isArray(parsed.taskGroups) ? parsed.taskGroups : [];
+  const checklistItems = Array.isArray(parsed.checklistItems)
+    ? parsed.checklistItems.map((item) => item.text)
+    : [];
 
   const mentionedPages = unique(checklistItems.flatMap((item) => extractPageCandidatesFromItem(item)));
 
@@ -245,15 +403,477 @@ function containsAnyToken(source, tokens) {
   return (tokens || []).some((token) => normalizedSource.includes(normalizeWhitespace(token)));
 }
 
-function buildScopeResultEnvelope(projectRoot, strict) {
+function attachAnalyzeGateFindings(result, gate) {
+  for (const message of gate.blocking || []) {
+    result.failures.push(`[gate:analyze] ${message}`);
+  }
+  for (const message of gate.advisory || []) {
+    result.warnings.push(`[gate:analyze] ${message}`);
+  }
+  for (const message of gate.compatibility || []) {
+    result.notes.push(`[gate:analyze] ${message}`);
+  }
+}
+
+function addAnalyzeFinding(gate, evidenceIndex, severity, message, evidenceItems) {
+  const level = severity === "blocking" ? "blocking" : "advisory";
+  gate[level].push(message);
+  const resolvedEvidence = resolveAnalyzeEvidenceRefs(evidenceItems, {
+    index: evidenceIndex
+  });
+  gate.evidence.push(...resolvedEvidence.refs);
+  gate.compatibility.push(...resolvedEvidence.notes);
+}
+
+function collectScopedPageTokens(proposal = {}, pageMap = {}) {
+  const tokens = new Set();
+  for (const page of unique([...(proposal.scopePages || []), ...(pageMap.pages || [])])) {
+    const pageTokens = tokenizeNormalizedWords(page, {
+      pattern: ANALYZE_TOKEN_PATTERN,
+      stopWords: ANALYZE_STOP_WORDS
+    });
+    for (const token of pageTokens) {
+      tokens.add(token);
+    }
+  }
+  return tokens;
+}
+
+function evaluateTaskGroupUpstreamSupport(groupTokens, upstreamCorpus, scopedPageTokens) {
+  const matchedTokens = groupTokens.filter((token) => upstreamCorpus.includes(token));
+  const semanticTokens = groupTokens.filter(
+    (token) => !scopedPageTokens.has(token) && !ANALYZE_GENERIC_TASK_TOKENS.has(token)
+  );
+  const semanticMatches = semanticTokens.filter((token) => upstreamCorpus.includes(token));
+  if (semanticTokens.length === 0) {
+    return matchedTokens.length > 0;
+  }
+  return semanticMatches.length > 0;
+}
+
+function resolveAnalyzeAnchorArtifact(changeDir, projectRoot, reference) {
+  const ref = reference && typeof reference === "object" ? reference : {};
+  const artifactPath = String(ref.artifactPath || "").trim();
+  const artifactToken = String(ref.artifactToken || "").trim();
+  if (!artifactPath) {
+    return {
+      ok: false,
+      reason: "empty_artifact_path"
+    };
+  }
+
+  const candidates = [];
+  if (path.isAbsolute(artifactPath)) {
+    candidates.push(artifactPath);
+  } else {
+    candidates.push(path.join(changeDir, artifactPath));
+    candidates.push(path.join(projectRoot, artifactPath));
+  }
+  const absolutePath = candidates.find((candidate) => pathExists(candidate));
+  if (!absolutePath) {
+    return {
+      ok: false,
+      reason: "artifact_path_missing"
+    };
+  }
+
+  if (!artifactToken) {
+    return {
+      ok: true,
+      path: absolutePath
+    };
+  }
+
+  const content = readTextIfExists(absolutePath);
+  if (!content) {
+    return {
+      ok: false,
+      reason: "artifact_unreadable"
+    };
+  }
+  if (!String(content).toLowerCase().includes(artifactToken.toLowerCase())) {
+    return {
+      ok: false,
+      reason: "artifact_token_unmatched"
+    };
+  }
+  return {
+    ok: true,
+    path: absolutePath
+  };
+}
+
+function collectTaskGroupAnchorSignal(group, context = {}) {
+  const anchorRefs = Array.isArray(group && group.planningAnchors) ? group.planningAnchors : [];
+  const malformedAnchors = Array.isArray(group && group.malformedAnchors) ? group.malformedAnchors : [];
+  const hasAnchorSignal = anchorRefs.length > 0 || malformedAnchors.length > 0;
+  if (!hasAnchorSignal) {
+    return {
+      hasAnchorSignal: false,
+      supported: false,
+      advisory: null,
+      notes: []
+    };
+  }
+
+  const sidecarIndex = context.sidecarIndex || {
+    available: false,
+    index: {
+      behavior: new Set(),
+      acceptance: new Set(),
+      state: new Set(),
+      mapping: new Set()
+    }
+  };
+  const groupId = String((group && group.id) || "").trim() || "unknown";
+  const groupTitle = String((group && group.title) || "").trim();
+  const groupLabel = `${groupId}. ${groupTitle}`.trim();
+  const notes = [];
+
+  for (const malformed of malformedAnchors) {
+    const reason = String((malformed && malformed.reason) || "unsupported_anchor_format").trim();
+    notes.push(`${groupLabel} has malformed planning anchor syntax (${reason}).`);
+  }
+
+  const resolvedAnchors = resolvePlanningAnchorRefs(anchorRefs, {
+    sidecarIndex,
+    resolveArtifactRef: (reference) =>
+      resolveAnalyzeAnchorArtifact(context.changeDir || "", context.projectRoot || "", reference)
+  });
+  for (const note of resolvedAnchors.notes || []) {
+    notes.push(`${groupLabel} anchor resolution note: ${note}`);
+  }
+
+  if (resolvedAnchors.resolved.length > 0) {
+    return {
+      hasAnchorSignal: true,
+      supported: true,
+      advisory: null,
+      notes
+    };
+  }
+
+  const unresolvedReasons = unique(
+    (resolvedAnchors.unresolved || []).map((item) => String(item && item.reason ? item.reason : "").trim())
+  ).filter(Boolean);
+  const reasonSuffix = unresolvedReasons.length > 0 ? ` (${unresolvedReasons.join(", ")})` : "";
   return {
-    status: STATUS.PASS,
-    failures: [],
-    warnings: [],
+    hasAnchorSignal: true,
+    supported: false,
+    advisory: `task group anchor coverage is unresolved; orphan detection is downgraded to advisory: ${groupLabel}${reasonSuffix}.`,
+    notes
+  };
+}
+
+function collectAnalyzeGate(context = {}) {
+  const gate = buildGateEnvelope("analyze");
+  const proposal = context.proposal || { scopeItems: [], nonGoalItems: [], scopePages: [] };
+  const pageMap = context.pageMap || { pages: [] };
+  const pencilDesign = context.pencilDesign || { pages: [] };
+  const specs = context.specs || { records: [], combinedText: "" };
+  const bindings = context.bindings || { mappings: [], designPages: [], implementationPaths: [] };
+  const tasks = context.tasks || { text: "", taskGroups: [] };
+  const verificationText = String(context.verificationText || "");
+  const evidenceIndex = context.evidenceIndex || {
+    available: false,
+    maps: {
+      behavior: new Map(),
+      acceptance: new Map(),
+      state: new Map(),
+      mappingByImplementation: new Map()
+    },
     notes: [],
-    projectRoot,
-    changeId: null,
-    strict,
+    warnings: []
+  };
+  const paths = context.paths || {
+    proposalPath: "proposal.md",
+    pencilDesignPath: "pencil-design.md",
+    bindingsPath: "pencil-bindings.md",
+    tasksPath: "tasks.md",
+    verificationPath: "verification.md",
+    pageMapPath: "page-map.md"
+  };
+  const planningAnchorIndex = context.planningAnchorIndex || {
+    available: false,
+    index: {
+      behavior: new Set(),
+      acceptance: new Set(),
+      state: new Set(),
+      mapping: new Set()
+    },
+    notes: [],
+    warnings: []
+  };
+
+  gate.compatibility.push(...(evidenceIndex.notes || []));
+  gate.compatibility.push(...(evidenceIndex.warnings || []));
+  gate.compatibility.push(...(planningAnchorIndex.notes || []));
+  gate.compatibility.push(...(planningAnchorIndex.warnings || []));
+  if (!verificationText.trim()) {
+    gate.compatibility.push("Missing `verification.md`; analyze evidence uses tasks-only fallback.");
+  }
+  if (!Array.isArray(bindings.mappings) || bindings.mappings.length === 0) {
+    gate.compatibility.push("Missing or empty `pencil-bindings.md`; analyze mapping coverage is degraded.");
+  }
+
+  const downstreamText = `${tasks.text}\n${verificationText}`;
+  for (const record of specs.records || []) {
+    for (const behaviorItem of record.behaviorItems || []) {
+      const tokens = tokenizeNormalizedWords(behaviorItem, {
+        pattern: ANALYZE_TOKEN_PATTERN,
+        stopWords: ANALYZE_STOP_WORDS
+      });
+      if (tokens.length < 2) {
+        continue;
+      }
+      if (!textContainsAnyNormalizedToken(downstreamText, tokens)) {
+        addAnalyzeFinding(
+          gate,
+          evidenceIndex,
+          "blocking",
+          `orphan upstream behavior lacks downstream support: "${behaviorItem}" (${record.path}).`,
+          [
+            { artifactPath: record.path, itemText: behaviorItem, kind: "behavior" },
+            { artifactPath: paths.tasksPath, itemText: behaviorItem, kind: "behavior" },
+            { artifactPath: paths.verificationPath, itemText: behaviorItem, kind: "behavior" }
+          ]
+        );
+      }
+    }
+    for (const acceptanceItem of record.acceptanceItems || []) {
+      const tokens = tokenizeNormalizedWords(acceptanceItem, {
+        pattern: ANALYZE_TOKEN_PATTERN,
+        stopWords: ANALYZE_STOP_WORDS
+      });
+      if (tokens.length < 2) {
+        continue;
+      }
+      if (!textContainsAnyNormalizedToken(downstreamText, tokens)) {
+        addAnalyzeFinding(
+          gate,
+          evidenceIndex,
+          "blocking",
+          `acceptance outcome lacks tasks/verification support: "${acceptanceItem}" (${record.path}).`,
+          [
+            { artifactPath: record.path, itemText: acceptanceItem, kind: "acceptance" },
+            { artifactPath: paths.tasksPath, itemText: acceptanceItem, kind: "acceptance" },
+            { artifactPath: paths.verificationPath, itemText: acceptanceItem, kind: "acceptance" }
+          ]
+        );
+      }
+    }
+  }
+
+  const upstreamCorpus = normalizeWhitespace(
+    [
+      ...(proposal.scopeItems || []),
+      ...(proposal.scopePages || []),
+      ...(pageMap.pages || []),
+      ...((specs.records || []).flatMap((record) => [
+        ...(record.behaviorItems || []),
+        ...(record.acceptanceItems || [])
+      ]))
+    ].join(" ")
+  );
+  const scopedPageTokens = collectScopedPageTokens(proposal, pageMap);
+  for (const group of tasks.taskGroups || []) {
+    const groupText = normalizeWhitespace(
+      [
+        group.title,
+        ...(Array.isArray(group.checklistItems) ? group.checklistItems.map((item) => item.text || "") : [])
+      ].join(" ")
+    );
+    const groupTokens = tokenizeNormalizedWords(groupText, {
+      pattern: ANALYZE_TOKEN_PATTERN,
+      stopWords: ANALYZE_STOP_WORDS
+    });
+    if (groupTokens.length === 0) {
+      continue;
+    }
+    if (/verify|verification/i.test(String(group.title || ""))) {
+      continue;
+    }
+    const anchorSignal = collectTaskGroupAnchorSignal(group, {
+      sidecarIndex: planningAnchorIndex,
+      changeDir: context.changeDir || "",
+      projectRoot: context.projectRoot || ""
+    });
+    gate.compatibility.push(...(anchorSignal.notes || []));
+    if (anchorSignal.hasAnchorSignal) {
+      if (anchorSignal.supported) {
+        continue;
+      }
+      addAnalyzeFinding(
+        gate,
+        evidenceIndex,
+        "advisory",
+        anchorSignal.advisory,
+        [{ artifactPath: paths.tasksPath, itemText: `${group.id || "unknown"}. ${group.title || ""}`, kind: "behavior" }]
+      );
+      continue;
+    }
+    const supported = evaluateTaskGroupUpstreamSupport(groupTokens, upstreamCorpus, scopedPageTokens);
+    if (!supported) {
+      const groupId = String(group.id || "").trim() || "unknown";
+      addAnalyzeFinding(
+        gate,
+        evidenceIndex,
+        "blocking",
+        `orphan task group has no upstream planning support: ${groupId}. ${group.title}`,
+        [{ artifactPath: paths.tasksPath, itemText: `${groupId}. ${group.title}`, kind: "behavior" }]
+      );
+    }
+  }
+
+  const tasksText = normalizeWhitespace(tasks.text);
+  const specsText = normalizeWhitespace(specs.combinedText);
+  for (const nonGoal of proposal.nonGoalItems || []) {
+    const tokens = tokenizeNormalizedWords(nonGoal, {
+      pattern: ANALYZE_TOKEN_PATTERN,
+      stopWords: ANALYZE_STOP_WORDS
+    });
+    if (tokens.length === 0) {
+      continue;
+    }
+    const leakedToTasks = textContainsAnyNormalizedToken(tasksText, tokens);
+    const leakedToSpecs = textContainsAnyNormalizedToken(specsText, tokens);
+    const leakedToVerification = textContainsAnyNormalizedToken(verificationText, tokens);
+    if (leakedToTasks || leakedToSpecs || leakedToVerification) {
+      addAnalyzeFinding(
+        gate,
+        evidenceIndex,
+        "blocking",
+        `non-goal leakage detected for "${nonGoal}" across downstream planning artifacts.`,
+        [
+          { artifactPath: paths.proposalPath, itemText: nonGoal, kind: "behavior" },
+          { artifactPath: paths.tasksPath, itemText: nonGoal, kind: "behavior" },
+          { artifactPath: paths.verificationPath, itemText: nonGoal, kind: "behavior" }
+        ]
+      );
+    }
+  }
+
+  const proposalPageSet = new Set((proposal.scopePages || []).map((item) => normalizePageKey(item)));
+  const pageMapSet = new Set((pageMap.pages || []).map((item) => normalizePageKey(item)));
+  for (const page of pageMap.pages || []) {
+    const key = normalizePageKey(page);
+    if (!key || proposalPageSet.has(key)) {
+      continue;
+    }
+    addAnalyzeFinding(
+      gate,
+      evidenceIndex,
+      "blocking",
+      `material page/surface disagreement: page-map page "${page}" is outside proposal scope.`,
+      [
+        { artifactPath: paths.pageMapPath, itemText: page, kind: "behavior" },
+        { artifactPath: paths.proposalPath, itemText: page, kind: "behavior" }
+      ]
+    );
+  }
+  for (const page of proposal.scopePages || []) {
+    const key = normalizePageKey(page);
+    if (!key || pageMapSet.has(key)) {
+      continue;
+    }
+    addAnalyzeFinding(
+      gate,
+      evidenceIndex,
+      "blocking",
+      `material page/surface disagreement: proposal scope page "${page}" is missing from page-map.`,
+      [
+        { artifactPath: paths.proposalPath, itemText: page, kind: "behavior" },
+        { artifactPath: paths.pageMapPath, itemText: page, kind: "behavior" }
+      ]
+    );
+  }
+  const pencilSet = new Set((pencilDesign.pages || []).map((item) => normalizePageKey(item)));
+  const upstreamPageSet = new Set([...proposalPageSet, ...pageMapSet]);
+  for (const page of pencilDesign.pages || []) {
+    const key = normalizePageKey(page);
+    if (!key || upstreamPageSet.has(key)) {
+      continue;
+    }
+    addAnalyzeFinding(
+      gate,
+      evidenceIndex,
+      "blocking",
+      `material page/surface disagreement: pencil-design page "${page}" is outside proposal/page-map scope.`,
+      [
+        { artifactPath: paths.pencilDesignPath, itemText: page, kind: "behavior" },
+        { artifactPath: paths.proposalPath, itemText: page, kind: "behavior" },
+        { artifactPath: paths.pageMapPath, itemText: page, kind: "behavior" }
+      ]
+    );
+  }
+  if (pencilSet.size > 0) {
+    for (const page of unique([...(proposal.scopePages || []), ...(pageMap.pages || [])])) {
+      const key = normalizePageKey(page);
+      if (!key || pencilSet.has(key)) {
+        continue;
+      }
+      addAnalyzeFinding(
+        gate,
+        evidenceIndex,
+        "blocking",
+        `material page/surface disagreement: in-scope page "${page}" is missing from pencil-design.`,
+        [
+          { artifactPath: paths.proposalPath, itemText: page, kind: "behavior" },
+          { artifactPath: paths.pageMapPath, itemText: page, kind: "behavior" },
+          { artifactPath: paths.pencilDesignPath, itemText: page, kind: "behavior" }
+        ]
+      );
+    }
+  }
+
+  const bindingsPageSet = new Set((bindings.designPages || []).map((page) => normalizePageKey(page)));
+  for (const page of pageMap.pages || []) {
+    const key = normalizePageKey(page);
+    if (!key || bindingsPageSet.has(key)) {
+      continue;
+    }
+    addAnalyzeFinding(
+      gate,
+      evidenceIndex,
+      "blocking",
+      `binding mapping drift: in-scope page "${page}" is missing from pencil-bindings mappings.`,
+      [{ artifactPath: paths.bindingsPath, itemText: page, kind: "mapping" }]
+    );
+  }
+  for (const mapping of bindings.mappings || []) {
+    const designPage = String(mapping.designPage || "").trim();
+    const key = normalizePageKey(designPage);
+    if (!key) {
+      continue;
+    }
+    if (proposalPageSet.has(key) || pageMapSet.has(key)) {
+      continue;
+    }
+    addAnalyzeFinding(
+      gate,
+      evidenceIndex,
+      "blocking",
+      `binding mapping drift: mapping page "${designPage}" is outside proposal/page-map scope.`,
+      [
+        {
+          artifactPath: paths.bindingsPath,
+          itemText: designPage,
+          kind: "mapping",
+          implementationPath: mapping.implementation || ""
+        }
+      ]
+    );
+  }
+
+  return gate;
+}
+
+function buildScopeResultEnvelope(projectRoot, strict) {
+  return {
+    ...buildBasePlanningResultEnvelope(projectRoot, strict),
+    gates: {
+      analyze: null
+    },
     coverage: null,
     matrix: {
       pages: [],
@@ -266,30 +886,8 @@ function buildScopeResultEnvelope(projectRoot, strict) {
   };
 }
 
-function resolveChange(projectRoot, requestedChangeId, failures, notes) {
-  const resolved = resolveChangeDir(projectRoot, requestedChangeId);
-  failures.push(...resolved.failures);
-  notes.push(...resolved.notes);
-  return resolved.changeDir;
-}
-
-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 analyzeScopePropagation(result, proposal, pageMap, specs, pencilDesign, tasks) {
+  const propagationWarnings = [];
   const pageNames = new Map();
   const stateNames = new Map();
 
@@ -414,39 +1012,41 @@ function analyzeScopePropagation(result, proposal, pageMap, specs, pencilDesign,
 
   for (const row of result.matrix.pages) {
     if (row.pageMap && !row.proposal) {
-      result.warnings.push(
+      propagationWarnings.push(
         `Page propagation gap: \`${row.label}\` is in page-map but missing from proposal scope.`
       );
     }
     if (row.proposal && !row.pageMap) {
-      result.warnings.push(
+      propagationWarnings.push(
         `Page propagation gap: \`${row.label}\` is in proposal scope but missing from page-map.`
       );
     }
     if (row.pageMap && !row.spec) {
-      result.warnings.push(`Page propagation gap: \`${row.label}\` is in page-map but missing from specs.`);
+      propagationWarnings.push(`Page propagation gap: \`${row.label}\` is in page-map but missing from specs.`);
     }
     if (row.pageMap && !row.tasks) {
-      result.warnings.push(`Page propagation gap: \`${row.label}\` is in page-map but missing from tasks.`);
+      propagationWarnings.push(`Page propagation gap: \`${row.label}\` is in page-map but missing from tasks.`);
     }
     if (row.tasks && !row.proposal && !row.pageMap) {
-      result.warnings.push(`Overscoped task surface: \`${row.label}\` appears in tasks but is outside proposal/page-map scope.`);
+      propagationWarnings.push(
+        `Overscoped task surface: \`${row.label}\` appears in tasks but is outside proposal/page-map scope.`
+      );
     }
   }
 
   for (const row of result.matrix.states) {
     if (row.spec && !row.pageMap) {
-      result.warnings.push(
+      propagationWarnings.push(
         `State propagation gap: \`${row.label}\` is in specs but missing from page-map states.`
       );
     }
     if (row.spec && !row.pencil) {
-      result.warnings.push(
+      propagationWarnings.push(
         `State propagation gap: \`${row.label}\` is in specs but missing from pencil-design states.`
       );
     }
     if (row.spec && !row.tasks) {
-      result.warnings.push(`State propagation gap: \`${row.label}\` is in specs but missing from tasks.`);
+      propagationWarnings.push(`State propagation gap: \`${row.label}\` is in specs but missing from tasks.`);
     }
   }
 
@@ -455,7 +1055,7 @@ function analyzeScopePropagation(result, proposal, pageMap, specs, pencilDesign,
     .map((item) => normalizeWhitespace(item))
     .filter((item) => scopeSet.has(item));
   for (const value of unique(nonGoalOverlap)) {
-    result.warnings.push(`Contradictory scope signal: \`${value}\` appears in both Scope and Non-Goals.`);
+    propagationWarnings.push(`Contradictory scope signal: \`${value}\` appears in both Scope and Non-Goals.`);
   }
 
   result.coverage = {
@@ -482,6 +1082,7 @@ function analyzeScopePropagation(result, proposal, pageMap, specs, pencilDesign,
       pages: tasks.mentionedPages
     }
   };
+  return propagationWarnings;
 }
 
 function runScopeCheck(projectPathInput, options = {}) {
@@ -496,16 +1097,16 @@ function runScopeCheck(projectPathInput, options = {}) {
     result.notes.push(
       "Promotion criteria: turn on `--strict` in CI after scope-check warning baselines are stable and reviewed."
     );
-    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("scope-check defaults to advisory mode; pass `--strict` to block on findings.");
     result.notes.push(
       "Promotion criteria: turn on `--strict` in CI after scope-check warning baselines are stable and reviewed."
     );
-    return finalizeResult(result);
+    return finalizePlanningResult(result);
   }
   result.changeId = path.basename(changeDir);
 
@@ -513,12 +1114,16 @@ function runScopeCheck(projectPathInput, options = {}) {
   const pageMapPath = path.join(projectRoot, ".da-vinci", "page-map.md");
   const fallbackPageMapPath = path.join(changeDir, "page-map.md");
   const pencilDesignPath = path.join(changeDir, "pencil-design.md");
+  const bindingsPath = path.join(changeDir, "pencil-bindings.md");
   const tasksPath = path.join(changeDir, "tasks.md");
+  const verificationPath = path.join(changeDir, "verification.md");
 
   const proposalText = readTextIfExists(proposalPath);
   const pageMapText = readTextIfExists(pageMapPath) || readTextIfExists(fallbackPageMapPath);
   const pencilDesignText = readTextIfExists(pencilDesignPath);
+  const bindingsText = readTextIfExists(bindingsPath);
   const tasksText = readTextIfExists(tasksPath);
+  const verificationText = readTextIfExists(verificationPath);
 
   if (!proposalText) {
     result.failures.push("Missing `proposal.md` for scope-check.");
@@ -549,8 +1154,45 @@ function runScopeCheck(projectPathInput, options = {}) {
     const proposal = parseProposal(proposalText);
     const pageMap = parsePageMap(pageMapText);
     const pencilDesign = parsePencilDesign(pencilDesignText);
+    const bindings = parseBindings(bindingsText);
     const tasks = parseTasks(tasksText);
-    analyzeScopePropagation(result, proposal, pageMap, specs, pencilDesign, tasks);
+    const evidenceIndex = loadAnalyzeEvidenceIndex(changeDir);
+    const planningAnchorIndex = loadPlanningAnchorIndex(changeDir);
+    const propagationWarnings = analyzeScopePropagation(result, proposal, pageMap, specs, pencilDesign, tasks);
+    const analyzeGate = collectAnalyzeGate({
+      projectRoot,
+      changeDir,
+      proposal,
+      pageMap,
+      pencilDesign,
+      specs,
+      bindings,
+      tasks,
+      verificationText,
+      evidenceIndex,
+      planningAnchorIndex,
+      paths: {
+        proposalPath: path.relative(projectRoot, proposalPath) || proposalPath,
+        pencilDesignPath: path.relative(projectRoot, pencilDesignPath) || pencilDesignPath,
+        bindingsPath: path.relative(projectRoot, bindingsPath) || bindingsPath,
+        tasksPath: path.relative(projectRoot, tasksPath) || tasksPath,
+        verificationPath: path.relative(projectRoot, verificationPath) || verificationPath,
+        pageMapPath:
+          path.relative(projectRoot, pageMapPath) || path.relative(projectRoot, fallbackPageMapPath) || pageMapPath
+      }
+    });
+    if (propagationWarnings.length > 0) {
+      analyzeGate.advisory = unique([
+        ...(Array.isArray(analyzeGate.advisory) ? analyzeGate.advisory : []),
+        ...propagationWarnings.map((item) => `scope propagation: ${item}`)
+      ]);
+    }
+    result.gates.analyze = finalizeGateEnvelope(analyzeGate, {
+      strict,
+      // Compatibility findings (for example sidecar availability) must degrade gracefully.
+      warnOnCompatibility: false
+    });
+    attachAnalyzeGateFindings(result, result.gates.analyze);
   }
 
   result.warnings = unique(result.warnings);
@@ -560,10 +1202,13 @@ function runScopeCheck(projectPathInput, options = {}) {
     "Promotion criteria: turn on `--strict` in CI after scope-check warning baselines are stable and reviewed."
   );
 
-  return finalizeResult(result);
+  return finalizePlanningResult(result);
 }
 
 function formatScopeCheckReport(result) {
+  const formatBool = (value) => (value ? "Y" : "N");
+  const pageRows = Array.isArray(result.matrix && result.matrix.pages) ? result.matrix.pages : [];
+  const stateRows = Array.isArray(result.matrix && result.matrix.states) ? result.matrix.states : [];
   const lines = [
     "Da Vinci scope-check",
     `Project: ${result.projectRoot}`,
@@ -587,6 +1232,30 @@ function formatScopeCheckReport(result) {
     }
   }
 
+  if (pageRows.length > 0) {
+    lines.push("", "Page Matrix (sample):");
+    for (const row of pageRows.slice(0, 8)) {
+      lines.push(
+        `- ${row.label || row.key}: proposal=${formatBool(row.proposal)}, page-map=${formatBool(row.pageMap)}, spec=${formatBool(row.spec)}, pencil=${formatBool(row.pencil)}, tasks=${formatBool(row.tasks)}`
+      );
+    }
+    if (pageRows.length > 8) {
+      lines.push(`- ... ${pageRows.length - 8} more page row(s); use --json for full matrix.`);
+    }
+  }
+
+  if (stateRows.length > 0) {
+    lines.push("", "State Matrix (sample):");
+    for (const row of stateRows.slice(0, 8)) {
+      lines.push(
+        `- ${row.label || row.key}: spec=${formatBool(row.spec)}, page-map=${formatBool(row.pageMap)}, pencil=${formatBool(row.pencil)}, tasks=${formatBool(row.tasks)}`
+      );
+    }
+    if (stateRows.length > 8) {
+      lines.push(`- ... ${stateRows.length - 8} more state row(s); use --json for full matrix.`);
+    }
+  }
+
   if (result.notes.length > 0) {
     lines.push("", "Notes:");
     for (const note of result.notes) {