@xenonbyte/da-vinci-workflow 0.2.5 → 0.2.7

package/lib/lint-tasks.js

@@ -3,22 +3,34 @@ const { STATUS } = require("./workflow-contract");
 const {
   normalizeText,
   unique,
-  resolveChangeDir,
   parseTasksArtifact,
+  parseBindingsArtifact,
   parseRuntimeSpecs,
   readChangeArtifacts,
   readArtifactTexts
 } = require("./planning-parsers");
+const {
+  loadPlanningAnchorIndex,
+  resolvePlanningAnchorRefs
+} = require("./sidecars");
+const { buildGateEnvelope, finalizeGateEnvelope } = require("./gate-utils");
+const { pathExists, readTextIfExists } = require("./utils");
+const { readExecutionSignals, summarizeSignalsBySurface } = require("./execution-signals");
+const { lintRuntimeSpecs } = require("./lint-spec");
+const { runScopeCheck } = require("./scope-check");
+const { evaluatePlanningSignalFreshness } = require("./planning-signal-freshness");
+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: {
+      taskCheckpoint: null
+    },
     summary: {
       groups: 0,
       checklistItems: 0
@@ -30,13 +42,46 @@ 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 normalizeKnownStatus(status) {
+  const normalized = String(status || "").trim().toUpperCase();
+  if (normalized === STATUS.BLOCK || normalized === STATUS.WARN || normalized === STATUS.PASS) {
+    return normalized;
+  }
+  return "";
+}
+
+function statusPriority(status) {
+  const normalized = normalizeKnownStatus(status);
+  if (normalized === STATUS.BLOCK) {
+    return 2;
   }
-  result.status = result.strict ? STATUS.BLOCK : STATUS.WARN;
-  return result;
+  if (normalized === STATUS.WARN) {
+    return 1;
+  }
+  if (normalized === STATUS.PASS) {
+    return 0;
+  }
+  return -1;
+}
+
+function resolveWorseStatus(left, right) {
+  const leftNormalized = normalizeKnownStatus(left);
+  const rightNormalized = normalizeKnownStatus(right);
+  if (!leftNormalized && !rightNormalized) {
+    return STATUS.PASS;
+  }
+  if (!leftNormalized) {
+    return rightNormalized;
+  }
+  if (!rightNormalized) {
+    return leftNormalized;
+  }
+  return statusPriority(leftNormalized) >= statusPriority(rightNormalized)
+    ? leftNormalized
+    : rightNormalized;
 }
 
 function findMissingTaskGroupSequence(taskGroups) {
@@ -56,22 +101,395 @@ function findMissingTaskGroupSequence(taskGroups) {
   return missing;
 }
 
+function attachTaskCheckpointFindings(result, gate) {
+  for (const message of gate.blocking || []) {
+    result.failures.push(`[gate:taskCheckpoint] ${message}`);
+  }
+  for (const message of gate.advisory || []) {
+    result.warnings.push(`[gate:taskCheckpoint] ${message}`);
+  }
+  for (const message of gate.compatibility || []) {
+    result.notes.push(`[gate:taskCheckpoint] ${message}`);
+  }
+}
+
+function clampGateStatusBySignal(gateStatus, signalStatus) {
+  const gateNormalized = normalizeKnownStatus(gateStatus);
+  const signalNormalized = normalizeKnownStatus(signalStatus);
+  if (![STATUS.PASS, STATUS.WARN, STATUS.BLOCK].includes(gateNormalized)) {
+    return [STATUS.PASS, STATUS.WARN, STATUS.BLOCK].includes(signalNormalized)
+      ? signalNormalized
+      : STATUS.PASS;
+  }
+  if (![STATUS.PASS, STATUS.WARN, STATUS.BLOCK].includes(signalNormalized)) {
+    return gateNormalized;
+  }
+  return statusPriority(gateNormalized) >= statusPriority(signalNormalized) ? gateNormalized : signalNormalized;
+}
+
+function applyUpstreamPlanningGateContext(taskCheckpointGate, signalSummary, strict, derivedGateContext = {}) {
+  const lintSpecSignal = signalSummary["lint-spec"];
+  const scopeCheckSignal = signalSummary["scope-check"];
+
+  const clarifyGate =
+    lintSpecSignal && lintSpecSignal.details && lintSpecSignal.details.gates
+      ? lintSpecSignal.details.gates.clarify
+      : null;
+  const analyzeGate =
+    scopeCheckSignal && scopeCheckSignal.details && scopeCheckSignal.details.gates
+      ? scopeCheckSignal.details.gates.analyze
+      : null;
+
+  const check = [
+    {
+      id: "clarify",
+      signal: lintSpecSignal,
+      gate: clarifyGate,
+      derived: derivedGateContext.clarify || null,
+      message:
+        "upstream clarify gate is unresolved; task-checkpoint cannot be treated as healthy until clarify is cleared."
+    },
+    {
+      id: "analyze",
+      signal: scopeCheckSignal,
+      gate: analyzeGate,
+      derived: derivedGateContext.analyze || null,
+      message:
+        "upstream analyze gate is unresolved; task-checkpoint cannot be treated as healthy until coherence drift is cleared."
+    }
+  ];
+
+  for (const entry of check) {
+    const signalStatus = entry.signal && entry.signal.status ? entry.signal.status : STATUS.PASS;
+    const rawGateStatus = entry.gate && entry.gate.status ? entry.gate.status : signalStatus;
+    const signalHasBlockingFindings =
+      normalizeKnownStatus(signalStatus) === STATUS.BLOCK ||
+      (entry.gate && Array.isArray(entry.gate.blocking) && entry.gate.blocking.length > 0);
+    const derivedHasBlockingFindings = entry.derived && entry.derived.hasBlocking === true;
+    const signalEffectiveStatus = clampGateStatusBySignal(rawGateStatus, signalStatus);
+    const derivedStatus = normalizeKnownStatus(entry.derived && entry.derived.status);
+    const effectiveStatus =
+      signalHasBlockingFindings || derivedHasBlockingFindings
+        ? STATUS.BLOCK
+        : resolveWorseStatus(signalEffectiveStatus, derivedStatus);
+    const evidence = unique([
+      ...(entry.gate && Array.isArray(entry.gate.evidence) ? entry.gate.evidence : []),
+      ...(entry.derived && Array.isArray(entry.derived.evidence) ? entry.derived.evidence : [])
+    ]);
+    if (entry.id === "clarify") {
+      const boundedContext = unique([
+        ...(entry.gate && Array.isArray(entry.gate.bounded) ? entry.gate.bounded : []),
+        ...(entry.derived && Array.isArray(entry.derived.bounded) ? entry.derived.bounded : [])
+      ]);
+      for (const message of boundedContext) {
+        taskCheckpointGate.compatibility.push(
+          `upstream clarify gate has bounded ambiguity context: ${message}`
+        );
+      }
+    }
+    if (effectiveStatus === STATUS.BLOCK) {
+      if (strict) {
+        taskCheckpointGate.blocking.push(entry.message);
+      } else {
+        taskCheckpointGate.advisory.push(entry.message);
+      }
+      taskCheckpointGate.evidence.push(...evidence.slice(0, 3));
+    }
+  }
+}
+
+function collectDerivedUpstreamGateContext(projectRoot, changeId, signalSummary = {}) {
+  const context = {
+    clarify: null,
+    analyze: null,
+    notes: [],
+    ignoredSurfaces: []
+  };
+
+  const lintSpecSignal = signalSummary["lint-spec"] || null;
+  const lintSpecFreshness = evaluatePlanningSignalFreshness(projectRoot, {
+    changeId,
+    surface: "lint-spec",
+    signal: lintSpecSignal
+  });
+  const shouldDeriveClarify = !lintSpecSignal || !lintSpecFreshness.fresh;
+  if (lintSpecSignal && !lintSpecFreshness.fresh) {
+    context.ignoredSurfaces.push("lint-spec");
+    context.notes.push(
+      `lint-tasks ignored stale lint-spec signal and derived clarify gate from current artifacts (${lintSpecFreshness.reasons.join(", ")}).`
+    );
+  }
+  if (shouldDeriveClarify) {
+    try {
+      const lintResult = lintRuntimeSpecs(projectRoot, {
+        changeId,
+        strict: false
+      });
+      const clarifyGate =
+        lintResult && lintResult.gates && lintResult.gates.clarify
+          ? lintResult.gates.clarify
+          : null;
+      if (clarifyGate) {
+        context.clarify = {
+          status: clarifyGate.status,
+          evidence: Array.isArray(clarifyGate.evidence) ? clarifyGate.evidence : [],
+          hasBlocking: Array.isArray(clarifyGate.blocking) && clarifyGate.blocking.length > 0,
+          bounded: Array.isArray(clarifyGate.bounded) ? clarifyGate.bounded : []
+        };
+      }
+    } catch (error) {
+      context.notes.push(
+        `lint-tasks could not derive clarify gate from current artifacts (${error && error.message ? error.message : error}).`
+      );
+    }
+  }
+
+  const scopeCheckSignal = signalSummary["scope-check"] || null;
+  const scopeCheckFreshness = evaluatePlanningSignalFreshness(projectRoot, {
+    changeId,
+    surface: "scope-check",
+    signal: scopeCheckSignal
+  });
+  const shouldDeriveAnalyze = !scopeCheckSignal || !scopeCheckFreshness.fresh;
+  if (scopeCheckSignal && !scopeCheckFreshness.fresh) {
+    context.ignoredSurfaces.push("scope-check");
+    context.notes.push(
+      `lint-tasks ignored stale scope-check signal and derived analyze gate from current artifacts (${scopeCheckFreshness.reasons.join(", ")}).`
+    );
+  }
+  if (shouldDeriveAnalyze) {
+    try {
+      const scopeResult = runScopeCheck(projectRoot, {
+        changeId,
+        strict: false
+      });
+      const analyzeGate =
+        scopeResult && scopeResult.gates && scopeResult.gates.analyze
+          ? scopeResult.gates.analyze
+          : null;
+      if (analyzeGate) {
+        context.analyze = {
+          status: analyzeGate.status,
+          evidence: Array.isArray(analyzeGate.evidence) ? analyzeGate.evidence : [],
+          hasBlocking: Array.isArray(analyzeGate.blocking) && analyzeGate.blocking.length > 0
+        };
+      }
+    } catch (error) {
+      context.notes.push(
+        `lint-tasks could not derive analyze gate from current artifacts (${error && error.message ? error.message : error}).`
+      );
+    }
+  }
+
+  return context;
+}
+
+function isImplementationRelevantGroup(group) {
+  const hasTargets = Array.isArray(group.targetFiles) && group.targetFiles.length > 0;
+  const hasFileRefs = Array.isArray(group.fileReferences) && group.fileReferences.length > 0;
+  const hasChecklist = Array.isArray(group.checklistItems) && group.checklistItems.length > 0;
+  return (
+    group.codeChangeLikely === true ||
+    group.testingIntent === true ||
+    group.reviewIntent === true ||
+    hasTargets ||
+    hasFileRefs ||
+    hasChecklist
+  );
+}
+
+function groupLikelyNeedsMappingAnchor(group) {
+  const combined = normalizeText(
+    [
+      group.title,
+      ...(Array.isArray(group.checklistItems)
+        ? group.checklistItems.map((item) => item.text || "")
+        : [])
+    ].join(" ")
+  );
+  return /binding|map|mapping|design source|screen id|pencil/i.test(combined);
+}
+
+function resolveArtifactAnchor(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 buildArtifactFallbackAnchorIndex(specRecords, bindingsText) {
+  const index = {
+    behavior: new Set(),
+    acceptance: new Set(),
+    state: new Set(),
+    mapping: new Set()
+  };
+  const FAMILY_ID_PATTERN = /\b(behavior|acceptance|state|mapping)-(\d{1,6})\b/gi;
+
+  const registerRef = (family, digits) => {
+    const normalizedFamily = String(family || "").toLowerCase();
+    const parsed = Number.parseInt(String(digits || "").trim(), 10);
+    if (!Number.isFinite(parsed) || parsed <= 0 || !index[normalizedFamily]) {
+      return;
+    }
+    index[normalizedFamily].add(`${normalizedFamily}-${String(parsed).padStart(3, "0")}`);
+    index[normalizedFamily].add(`${normalizedFamily}-${String(parsed)}`);
+  };
+  const registerOrdinalRefs = (family, items) => {
+    const normalizedFamily = String(family || "").toLowerCase();
+    if (!index[normalizedFamily]) {
+      return;
+    }
+    const list = Array.isArray(items) ? items : [];
+    for (let cursor = 0; cursor < list.length; cursor += 1) {
+      registerRef(normalizedFamily, String(cursor + 1));
+    }
+  };
+
+  for (const record of Array.isArray(specRecords) ? specRecords : []) {
+    const text = String(record && record.text ? record.text : "");
+    const sections = record && record.parsed && record.parsed.sections ? record.parsed.sections : {};
+    registerOrdinalRefs("behavior", sections.behavior && sections.behavior.items);
+    registerOrdinalRefs("acceptance", sections.acceptance && sections.acceptance.items);
+    registerOrdinalRefs("state", sections.states && sections.states.items);
+    FAMILY_ID_PATTERN.lastIndex = 0;
+    let match;
+    while ((match = FAMILY_ID_PATTERN.exec(text)) !== null) {
+      registerRef(match[1], match[2]);
+    }
+  }
+
+  const parsedBindings = parseBindingsArtifact(bindingsText || "");
+  const mappings = Array.isArray(parsedBindings.mappings) ? parsedBindings.mappings : [];
+  for (let cursor = 0; cursor < mappings.length; cursor += 1) {
+    const mapping = mappings[cursor];
+    registerRef("mapping", String(cursor + 1));
+    const id = String(mapping && mapping.id ? mapping.id : "").trim();
+    const raw = String(mapping && mapping.raw ? mapping.raw : "");
+    const inlineCandidates = [];
+    if (id) {
+      inlineCandidates.push(id);
+    }
+    if (raw) {
+      inlineCandidates.push(raw);
+    }
+    for (const candidate of inlineCandidates) {
+      FAMILY_ID_PATTERN.lastIndex = 0;
+      let match;
+      while ((match = FAMILY_ID_PATTERN.exec(candidate)) !== null) {
+        registerRef(match[1], match[2]);
+      }
+    }
+  }
+
+  return index;
+}
+
+function sectionContainsToken(items, normalizedToken) {
+  if (!normalizedToken) {
+    return false;
+  }
+  return (Array.isArray(items) ? items : []).some((item) =>
+    normalizeText(String(item || "")).includes(normalizedToken)
+  );
+}
+
+function inferFamiliesFromArtifactAnchor(anchor, specRecords) {
+  const families = new Set();
+  const source = String(anchor && anchor.source ? anchor.source : "").toLowerCase();
+  if (source !== "artifact") {
+    return families;
+  }
+
+  const artifactPath = String(anchor && anchor.artifactPath ? anchor.artifactPath : "").toLowerCase();
+  const normalizedToken = normalizeText(String(anchor && anchor.artifactToken ? anchor.artifactToken : ""));
+
+  if (/pencil-bindings\.md$/i.test(artifactPath)) {
+    families.add("mapping");
+  }
+  if (!/spec\.md$/i.test(artifactPath) && !/\/specs\//i.test(artifactPath)) {
+    return families;
+  }
+  if (!normalizedToken) {
+    return families;
+  }
+
+  for (const record of Array.isArray(specRecords) ? specRecords : []) {
+    const sections = record && record.parsed && record.parsed.sections ? record.parsed.sections : {};
+    if (sectionContainsToken(sections.behavior && sections.behavior.items, normalizedToken)) {
+      families.add("behavior");
+    }
+    if (sectionContainsToken(sections.states && sections.states.items, normalizedToken)) {
+      families.add("state");
+    }
+    if (sectionContainsToken(sections.acceptance && sections.acceptance.items, normalizedToken)) {
+      families.add("acceptance");
+    }
+  }
+
+  return families;
+}
+
 function lintTasks(projectPathInput, options = {}) {
   const projectRoot = path.resolve(projectPathInput || process.cwd());
   const strict = options.strict === true;
   const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
   const result = buildEnvelope(projectRoot, strict);
 
-  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.notes.push("lint-tasks defaults to advisory mode; pass `--strict` to block on findings.");
     return finalize(result);
   }
-  result.changeId = resolved.changeId;
+  result.changeId = path.basename(changeDir);
+  const anchorIndex = loadPlanningAnchorIndex(changeDir);
+  result.notes.push(...anchorIndex.notes);
+  result.notes.push(...anchorIndex.warnings.map((item) => `[sidecars] ${item}`));
 
-  const artifactPaths = readChangeArtifacts(projectRoot, resolved.changeId);
+  const artifactPaths = readChangeArtifacts(projectRoot, result.changeId);
   const artifacts = readArtifactTexts(artifactPaths);
   if (!artifacts.tasks) {
     result.failures.push("Missing `tasks.md` for lint-tasks.");
@@ -80,8 +498,16 @@ function lintTasks(projectPathInput, options = {}) {
   }
 
   const parsedTasks = parseTasksArtifact(artifacts.tasks);
-  const specRecords = parseRuntimeSpecs(resolved.changeDir, projectRoot);
+  const specRecords = parseRuntimeSpecs(changeDir, projectRoot);
+  const fallbackAnchorIndex = buildArtifactFallbackAnchorIndex(specRecords, artifacts.bindings || "");
   const taskText = normalizeText(artifacts.tasks);
+  const taskCheckpointGate = buildGateEnvelope("taskCheckpoint");
+  const hasAnyAnchorEvidence = parsedTasks.taskGroups.some(
+    (group) =>
+      (Array.isArray(group.planningAnchors) && group.planningAnchors.length > 0) ||
+      (Array.isArray(group.malformedAnchors) && group.malformedAnchors.length > 0)
+  );
+  const legacyNoAnchorMode = !hasAnyAnchorEvidence;
 
   result.summary.groups = parsedTasks.taskGroups.length;
   result.summary.checklistItems = parsedTasks.checklistItems.length;
@@ -194,6 +620,109 @@ function lintTasks(projectPathInput, options = {}) {
         `Task group ${groupLabel} hints review-required execution but does not declare concrete review intent.`
       );
     }
+
+    const implementationRelevant = isImplementationRelevantGroup(group);
+    const anchorRefs = Array.isArray(group.planningAnchors) ? group.planningAnchors : [];
+    const malformedAnchors = Array.isArray(group.malformedAnchors) ? group.malformedAnchors : [];
+    for (const malformed of malformedAnchors) {
+      taskCheckpointGate.blocking.push(
+        `${groupLabel} contains malformed planning anchor (${malformed.reason || "invalid format"}).`
+      );
+      taskCheckpointGate.evidence.push(`tasks.md:${group.startLine || "?"}`);
+    }
+
+    if (implementationRelevant && anchorRefs.length === 0) {
+      if (legacyNoAnchorMode) {
+        taskCheckpointGate.compatibility.push(
+          `${groupLabel} has no explicit planning anchors (legacy compatibility mode).`
+        );
+      } else {
+        taskCheckpointGate.blocking.push(
+          `${groupLabel} declares implementation-relevant work but has no planning anchors.`
+        );
+      }
+      taskCheckpointGate.evidence.push(`tasks.md:${group.startLine || "?"}`);
+      continue;
+    }
+
+    if (anchorRefs.length > 0) {
+      const resolvedAnchors = resolvePlanningAnchorRefs(anchorRefs, {
+        sidecarIndex: anchorIndex,
+        resolveAnchorIdRef: (reference) => {
+          const ref = String(reference && reference.ref ? reference.ref : "").trim();
+          const family = String(reference && reference.family ? reference.family : "").trim().toLowerCase();
+          if (!ref || !family || !fallbackAnchorIndex[family]) {
+            return {
+              ok: false,
+              reason: "anchor_id_unresolved",
+              classification: "invalid_or_stale_sidecar_anchor"
+            };
+          }
+          const normalizedRef = ref.toLowerCase();
+          return {
+            ok: fallbackAnchorIndex[family].has(normalizedRef),
+            reason: fallbackAnchorIndex[family].has(normalizedRef) ? "" : "anchor_id_unresolved",
+            classification: fallbackAnchorIndex[family].has(normalizedRef)
+              ? ""
+              : "invalid_or_stale_sidecar_anchor"
+          };
+        },
+        resolveArtifactRef: (reference) =>
+          resolveArtifactAnchor(changeDir, projectRoot, reference)
+      });
+      for (const unresolved of resolvedAnchors.unresolved) {
+        const reason = String(unresolved.reason || "unresolved").trim();
+        if (reason === "sidecar_unavailable") {
+          taskCheckpointGate.compatibility.push(
+            `${groupLabel} anchor \`${unresolved.ref}\` cannot be validated because sidecars are unavailable/stale.`
+          );
+        } else {
+          taskCheckpointGate.blocking.push(
+            `${groupLabel} anchor \`${unresolved.ref}\` is unresolved (${reason}).`
+          );
+        }
+        taskCheckpointGate.evidence.push(`tasks.md:${group.startLine || "?"}`);
+      }
+
+      const families = new Set(
+        resolvedAnchors.resolved
+          .filter((item) => item.source === "sidecar" || item.source === "artifact-parse")
+          .map((item) => String(item.family || "").toLowerCase())
+      );
+      for (const anchor of resolvedAnchors.resolved) {
+        for (const family of inferFamiliesFromArtifactAnchor(anchor, specRecords)) {
+          families.add(family);
+        }
+      }
+      const needsBehaviorCoverage = group.codeChangeLikely === true;
+      const needsAcceptanceCoverage = group.testingIntent === true || group.reviewIntent === true;
+      const needsMappingCoverage = groupLikelyNeedsMappingAnchor(group);
+      if (needsBehaviorCoverage && !families.has("behavior") && !families.has("state")) {
+        taskCheckpointGate.advisory.push(
+          `${groupLabel} changes behavior but anchor set is missing behavior/state coverage.`
+        );
+        taskCheckpointGate.evidence.push(`tasks.md:${group.startLine || "?"}`);
+      }
+      if (needsAcceptanceCoverage && !families.has("acceptance")) {
+        taskCheckpointGate.advisory.push(
+          `${groupLabel} has review/testing intent but anchor set is missing acceptance coverage.`
+        );
+        taskCheckpointGate.evidence.push(`tasks.md:${group.startLine || "?"}`);
+      }
+      if (needsMappingCoverage && !families.has("mapping")) {
+        taskCheckpointGate.advisory.push(
+          `${groupLabel} mentions mapping/design-binding intent but anchor set is missing mapping coverage.`
+        );
+        taskCheckpointGate.evidence.push(`tasks.md:${group.startLine || "?"}`);
+      }
+    }
+
+    if (implementationRelevant && Array.isArray(group.placeholderItems) && group.placeholderItems.length > 0) {
+      taskCheckpointGate.advisory.push(
+        `${groupLabel} is placeholder-heavy (${group.placeholderItems.length} placeholder item(s)); checkpoint health remains degraded.`
+      );
+      taskCheckpointGate.evidence.push(`tasks.md:${group.startLine || "?"}`);
+    }
   }
 
   for (const specRecord of specRecords) {
@@ -215,6 +744,27 @@ function lintTasks(projectPathInput, options = {}) {
     }
   }
 
+  const signalSummary = summarizeSignalsBySurface(
+    readExecutionSignals(projectRoot, {
+      changeId: result.changeId
+    })
+  );
+  const derivedUpstreamGateContext = collectDerivedUpstreamGateContext(projectRoot, result.changeId, signalSummary);
+  const effectiveSignalSummary = { ...signalSummary };
+  for (const surface of derivedUpstreamGateContext.ignoredSurfaces || []) {
+    delete effectiveSignalSummary[surface];
+  }
+  result.notes.push(...derivedUpstreamGateContext.notes);
+  applyUpstreamPlanningGateContext(
+    taskCheckpointGate,
+    effectiveSignalSummary,
+    strict,
+    derivedUpstreamGateContext
+  );
+
+  result.gates.taskCheckpoint = finalizeGateEnvelope(taskCheckpointGate, { strict });
+  attachTaskCheckpointFindings(result, result.gates.taskCheckpoint);
+
   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."