@christang/keel 5.3.6 → 5.3.8

package/src/core/gates.js

@@ -103,13 +103,56 @@ function loadSelection(repo, options, requireTask = true) {
   return { change, tasksPath, content, tasks, selected: [selected] };
 }
 
+// The documented order is gate-then-checkbox, so first-unchecked is the right
+// inference for task-start and stays. The hazard is narrower: completing without
+// an explicit task infers a task that has not started, then reports its
+// readiness problems under a selection heading the author reads as the failure
+// of the task they just finished. A task that has started records a fingerprint
+// in its Evidence `Contract` anchor, so that anchor is what makes the inference
+// safe — and without one there is nothing for completion to compare against.
+function hasRecordedAnchor(selection, task) {
+  const plan = contractAnchorPlan(selection, task);
+  return Boolean(plan && anchoredFingerprint(plan.previous));
+}
+
+// A task that recorded no anchor has no drift detection at all while presenting
+// as fully gated: completion skipped the comparison rather than reporting that
+// it had nothing to compare. Recording is already the documented step; this is
+// what makes the guarantee unconditional instead of aspirational.
+function missingAnchorProblem(selection, task) {
+  if (hasRecordedAnchor(selection, task)) return null;
+  return problem(
+    "missing-contract-anchor",
+    `${selection.change}#${task.id} records no compiled fingerprint in its `
+      + "Evidence `Contract` anchor, so completion has nothing to compare and "
+      + "the task has no drift detection. Run `keel gate task-start --record` "
+      + "for this task, which rewrites the anchor in place, then complete it."
+  );
+}
+
+function unstartedInferenceProblem(selection) {
+  const task = selection.selected[0];
+  if (hasRecordedAnchor(selection, task)) return null;
+  const checked = [...selection.tasks].filter((item) => item.checked).pop();
+  return problem(
+    "ambiguous-completion-selection",
+    `task-complete inferred ${selection.change}#${task.id}, the first unchecked `
+      + "task, but that task records no start fingerprint in its Evidence "
+      + "`Contract` anchor, so it has not started and there is nothing to "
+      + `compare. ${
+        checked
+          ? `The most recently checked task is ${checked.id}. `
+          : ""
+      }Name the task you mean with \`--task\`, or run \`task-start --record\` `
+      + "first."
+  );
+}
+
 function contractAnchorPlan(selection, task) {
   const lines = selection.content.split("\n");
-  const index = selection.tasks.findIndex((item) => item.id === task.id);
-  const end =
-    index + 1 < selection.tasks.length
-      ? selection.tasks[index + 1].line
-      : lines.length;
+  // The task carries its own extent, so the anchor search cannot reach a
+  // `- Contract:` line sitting in a trailing change-level section.
+  const end = task.endLine !== undefined ? task.endLine : lines.length;
   for (let cursor = task.line; cursor < end; cursor += 1) {
     const match = lines[cursor].match(/^(\s*)-\s*Contract:\s*(.*?)(\r?)$/);
     if (match) {
@@ -559,10 +602,30 @@ function completionChecks(repo, task, contract = null) {
 function taskComplete(repo, options) {
   const selection = loadSelection(repo, options);
   const task = selection.selected[0];
+  // Selection ambiguity short-circuits, because the gate does not know which
+  // task the caller meant and evaluating the wrong one is the defect. A named
+  // task is not ambiguous: its missing anchor is one problem among however many
+  // else it has, so it joins the list rather than hiding the rest.
+  if (!options.task) {
+    const ambiguous = unstartedInferenceProblem(selection);
+    if (ambiguous) {
+      return gateResult(
+        "task-complete",
+        "fail",
+        selection.change,
+        [task.id],
+        [ambiguous],
+        [],
+        null
+      );
+    }
+  }
   const contract = compileTaskContract(repo, selection.change, task);
   const usableContract = contract.diagnostics.length === 0 ? contract : null;
   const checks = completionChecks(repo, task, usableContract);
   checks.problems.push(...contract.diagnostics);
+  const missingAnchor = missingAnchorProblem(selection, task);
+  if (missingAnchor) checks.problems.push(missingAnchor);
   const scope = scopeEvidence(
     repo,
     task,

package/src/core/task-contract.js

@@ -68,7 +68,21 @@ function parseTasks(content) {
     });
   }
   for (let index = 0; index < tasks.length; index += 1) {
-    const end = index + 1 < tasks.length ? tasks[index + 1].line : lines.length;
+    // A task body ends at the next task or the next `##` heading, whichever
+    // comes first. Without the heading bound a change-level section such as
+    // `## Invalidates` was appended to whichever field was open last — the
+    // Evidence, in every shipped template — so a token quoted there made the
+    // Evidence non-concrete and the gate blamed a task that was fine.
+    const nextTask =
+      index + 1 < tasks.length ? tasks[index + 1].line : lines.length;
+    let end = nextTask;
+    for (let cursor = tasks[index].line + 1; cursor < nextTask; cursor += 1) {
+      if (/^\s*##\s/.test(lines[cursor])) {
+        end = cursor;
+        break;
+      }
+    }
+    tasks[index].endLine = end;
     const bodyLines = lines.slice(tasks[index].line, end);
     tasks[index].body = bodyLines.join("\n");
     tasks[index].fields = new Map();
@@ -192,6 +206,16 @@ function verification(task) {
 }
 
 function commandLabelProblems(task) {
+  // A task that declared no verification form at all is reported once, by
+  // requiredFieldProblems, as the one field it is missing. Its orphan Evidence
+  // labels are a consequence of that same absence, and restating them here is
+  // the cascade that buries the actionable line.
+  if (
+    fieldValues(task, "Verify").length === 0
+    && fieldValues(task, "Commands").length === 0
+  ) {
+    return [];
+  }
   const problems = [];
   const seen = new Set();
   const labels = [];
@@ -222,9 +246,18 @@ function commandLabelProblems(task) {
     seen.add(command[1]);
     labels.push(command[1]);
     if (!isConcrete(command[2])) {
+      // Name the matched slot, the way the Verify diagnostic already does. The
+      // unqualified wording described the consequence, so an author with
+      // several slots in one check had to guess which one was read.
+      const token = unfilledToken(command[2]);
       problems.push({
         code: "missing-command-check",
-        message: `${command[1]} must define a concrete public check.`,
+        message: token
+          ? `${command[1]} carries the unfilled slot \`${token}\`, so it does `
+            + "not define a concrete public check. Replace that slot with the "
+            + "value the check actually runs against, or fence it in inline "
+            + "code when it is a documented pattern rather than a slot."
+          : `${command[1]} must define a concrete public check.`,
       });
     }
   }
@@ -343,38 +376,44 @@ function requiredFieldProblems(task) {
         },
       ];
     }
-  }
-  const required = compact
-    ? ["Covers", "Verify", "Evidence"]
-    : [
-        "Owner",
-        "Mode",
-        "Covers",
-        "Read",
-        "Commands",
-        "Acceptance",
-        "Candidate Boundary",
-        "Stop Rules",
-        "Evidence",
-        "Report",
+    // Neither verification form declared. That is a compact v4 task missing one
+    // field, not an expanded v3 task missing nine — and listing the v3 set here
+    // reported a schema this author never chose.
+    if (!isConcrete(field(task, "Commands"))) {
+      return [
+        {
+          code: "missing-verification-form",
+          message:
+            "The task declares no verification form. Add a `Verify` field with "
+            + "a `Strategy:` entry and one `M<n>:` check per behavior the task "
+            + "proves. The expanded v3 `Commands` field is the other accepted "
+            + "form; the remaining v3 fields are not required.",
+        },
+        // The rest of the compact set is still reported, so a near-empty task
+        // learns everything it is missing. Only the v3 cascade is replaced.
+        ...missingFieldProblems(task, ["Covers", "Evidence"]),
       ];
-  const problems = required
+    }
+  }
+  // The expanded set is the compact set with `Commands` in place of `Verify`.
+  // Owner, Mode, Read, and Acceptance resolve to documented defaults or derive
+  // from Covers, Report is consumed nowhere, and Candidate Boundary and Stop
+  // Rules belong to couplingProblems, which requires them when the coupling
+  // contract does. Requiring them here reported fields that were already in
+  // effect.
+  return missingFieldProblems(
+    task,
+    compact ? ["Covers", "Verify", "Evidence"] : ["Covers", "Commands", "Evidence"]
+  );
+}
+
+function missingFieldProblems(task, names) {
+  return names
     .filter((name) => !isConcrete(field(task, name)))
     .map((name) => ({
       code: "missing-field",
       message: `${name} must be concrete.`,
     }));
-  if (
-    !compact
-    && !isConcrete(field(task, "Autonomy boundary"))
-    && !isConcrete(field(task, "Stop if"))
-  ) {
-    problems.push({
-      code: "missing-boundary",
-      message: "Stop if or Autonomy boundary must be concrete.",
-    });
-  }
-  return problems;
 }
 
 function canonical(value) {
@@ -808,8 +847,18 @@ function compileTaskContract(repo, change, task) {
   if (!autonomy.some((item) => /^Pre-authorized fallback:/i.test(item))) {
     autonomy.push("Pre-authorized fallback: none");
   }
+  // A question is unresolved authority when it is the subject of its Covers
+  // entry. Scanning the whole field also matched a resolved question named as
+  // supporting detail beside the fact that closed it, and the only fix
+  // available to the author was deleting the reference — so the check punished
+  // the traceability it exists to protect.
   const questionIds = [
-    ...new Set(field(task, "Covers").match(/\bQ\d+\b/g) || []),
+    ...new Set(
+      normalizedValues(task, "Covers", { ordered: true })
+        .map((entry) => entry.match(/^(Q\d+)\b/))
+        .filter(Boolean)
+        .map((match) => match[1])
+    ),
   ];
   const fallback = autonomy.find((item) =>
     /^Pre-authorized fallback:/i.test(item)