@christang/keel 5.20.0 → 5.39.0

package/src/core/gates.js

@@ -13,8 +13,9 @@ const {
   isConcrete,
   isPassingReviewStatus,
   parseTasks,
+  unfilledToken,
 } = require("./task-contract");
-const { gitPaths, readManifest, startGuard } = require("./guard");
+const { contentSignature, gitPaths, readManifest, startGuard } = require("./guard");
 
 const GATE_STAGES = new Set(["task-start", "task-complete", "change-close"]);
 
@@ -349,11 +350,38 @@ function evidenceValue(task, label) {
   return match ? match[1] : "";
 }
 
+// A Review entry is the text the author wrote under its label, not its first
+// line. `parseTasks()` already gathers the whole Evidence body, so the
+// continuation lines arrive here; a line-anchored `(.*)` used to drop them
+// before any check saw them. That failed in both directions: a `Findings` whose
+// `Durable owner:` sat on the fourth line was refused with the owner present
+// and the path existing, and a `Findings` reading `none` above three lines of
+// real findings passed, because the check tested the word and never saw them
+// (issue #49).
+//
+// The entry ends at the next entry at the same or shallower indentation.
+// Without that bound `Findings` — always the last of the four — would run to
+// the end of Evidence and read `- Blocker:` as its own text, trading a
+// fail-closed defect for a fail-open one. A deeper-indented `- ` line is a
+// continuation, which is what makes a Findings written as a sub-list one entry.
+const REVIEW_SIBLING = /^(\s*)-\s*[^\s:][^:\n]*:/;
+
 function reviewValue(task, label) {
-  const match = field(task, "Evidence").match(
-    new RegExp(`^\\s*-\\s*${label}:\\s*(.*)$`, "im")
-  );
-  return match ? match[1].trim() : "";
+  const lines = field(task, "Evidence").split(/\r?\n/);
+  const opener = new RegExp(`^(\\s*)-\\s*${label}:\\s*(.*)$`, "i");
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = lines[index].match(opener);
+    if (!match) continue;
+    const indent = match[1].length;
+    const value = [match[2]];
+    for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+      const sibling = lines[cursor].match(REVIEW_SIBLING);
+      if (sibling && sibling[1].length <= indent) break;
+      value.push(lines[cursor]);
+    }
+    return value.join("\n").trim();
+  }
+  return "";
 }
 
 // The durable-owner forms that are pure shape checks, shared by the Review
@@ -424,13 +452,15 @@ function durableOwnerVerdict(repo, value) {
 // same third slot since it shipped, where `Updated by:` names tasks of this
 // change.
 // The capture is the single token after the marker, not the rest of the line.
-// Findings is one line of free prose that normally holds several findings with
-// different dispositions, so a capture reaching to the newline swallows every
-// marker after it — a block recording one fix and one tracker-owned follow-up
-// was refused because the *follow-up's* URL was read as the *fix's* evidence.
-// Measured on this change's own task 1.3. The match is global because each
-// resolved claim owes its own evidence; checking only the first would let a
-// second one assert itself for free.
+// Findings is free prose that normally holds several findings with different
+// dispositions, so a capture reaching to the newline swallows every marker
+// after it — a block recording one fix and one tracker-owned follow-up was
+// refused because the *follow-up's* URL was read as the *fix's* evidence.
+// Measured on this change's own task 1.3. That block used to be one line and
+// may now wrap across several, which widens what a greedy capture would
+// swallow and changes nothing about why this one is narrow. The match is
+// global because each resolved claim owes its own evidence; checking only the
+// first would let a second one assert itself for free.
 const RESOLVED_HERE = /\bresolved here\s*:[ \t]*(\S*)/gi;
 
 // Resolution evidence is deliberately narrower than a durable owner. An
@@ -520,6 +550,9 @@ function findingOwnerIsDurable(repo, findings) {
 // what a manifest written before this field, a cleared guard, or a
 // `--no-guard` start all produce. Reading null as empty would attribute the
 // whole worktree to the task and fail every completion in a dirty repository.
+// Each entry is `{ path, sha256 }`, the content signature `contentSignature`
+// read at that same moment — the record of *what* was dirty, not only that a
+// path was.
 function recordedBaseline(repo, change, task) {
   const loaded = readManifest(repo);
   if (loaded.state !== "ok") return null;
@@ -608,20 +641,27 @@ function scopeEvidence(
   }
 
   if (!base) {
-    // Dirty now and not dirty when the task started. This answers "did this
-    // task write it", which is the question the boundary actually asks; it
-    // does not answer "which task wrote it", which is why the completed-
-    // sibling exclusion below still applies and still reports itself.
+    // Dirty now and not dirty when the task started, or dirty now with
+    // content that no longer matches what was there at task start. Either
+    // answers "did this task write it", which is the question the boundary
+    // actually asks; it does not answer "which task wrote it", which is why
+    // the completed-sibling exclusion below still applies and still reports
+    // itself.
     //
-    // A path already dirty at task start is subtracted even if the task also
-    // modified it. That is the price of a baseline that is not a commit, and
-    // it buys the far larger class this exists to avoid: failing every
-    // completion in a worktree that was dirty before the task began.
-    const startedDirty = new Set(baseline);
+    // A path already dirty at task start is exempt only while its content
+    // stays the one recorded then — recording a hash instead of only a name
+    // is what lets that hold without falling back to subtracting the whole
+    // path, which exempted every later write to it, not just the one that
+    // predated the task (#72).
+    const unchangedSinceStart = new Set(
+      baseline
+        .filter((entry) => contentSignature(repo, entry.path) === entry.sha256)
+        .map((entry) => entry.path)
+    );
     return attributeChanged(
       repo,
       task,
-      dirtyPaths.filter((item) => !startedDirty.has(item)),
+      dirtyPaths.filter((item) => !unchangedSinceStart.has(item)),
       contract,
       change,
       tasks
@@ -701,7 +741,7 @@ function attributeChanged(repo, task, changedList, contract, change, tasks) {
   };
 }
 
-function completionChecks(repo, task, contract = null) {
+function completionChecks(repo, task, contract = null, changeVerify = null) {
   const problems = [];
   const commands = contract
     ? contract.capsule.verification.commands.map((item) => item.label)
@@ -750,11 +790,65 @@ function completionChecks(repo, task, contract = null) {
       }
     }
   }
+  // A `(regression)` check's bare Evidence may defer to a change-level `C<n>`
+  // check instead of recording its own result (issue #95). The regression
+  // flag comes from the compiled contract, the same source the exemption
+  // above already trusts, so this cannot disagree with what `(regression)`
+  // itself decided. Resolution only — whether the reference is declared, not
+  // whether it has run yet — because at task-complete time it legitimately
+  // may not have; `changeVerifyProblems` requires it answered by close.
+  if (contract) {
+    const declaredLabels = new Set(
+      (changeVerify ? changeVerify.checks : []).map((entry) => entry.label)
+    );
+    for (const entry of contract.capsule.verification.commands) {
+      const deferred = deferredChangeCheck(evidenceValue(task, entry.label));
+      if (!deferred) continue;
+      if (!entry.regression) {
+        problems.push(
+          problem(
+            "deferred-evidence-not-regression",
+            `${entry.label} Evidence defers to ${deferred}, but ${entry.label} `
+              + "is not tagged `(regression)`; only a `(regression)`-tagged "
+              + "check may defer to a change-level check."
+          )
+        );
+        continue;
+      }
+      if (!declaredLabels.has(deferred)) {
+        problems.push(
+          problem(
+            "deferred-check-unresolved",
+            `${entry.label} defers to ${deferred}, but tasks.md's \`## `
+              + `Change Verify\` does not declare it. Declare it there, or `
+              + `record concrete Evidence for ${entry.label} directly.`
+          )
+        );
+      }
+    }
+  }
   const blocker = evidenceValue(task, "Blocker");
   if (isConcrete(blocker)) {
     problems.push(problem("blocker", `Task records a blocker: ${blocker}`));
   }
 
+  // Reauthorizations (#70) is a log, not a stop condition: absent, `none`, and
+  // concrete text all pass. Only an abandoned `<slot>` token — real content
+  // the author started and never finished — is refused, the same distinction
+  // `unfilledToken()` already draws for every other field that uses it.
+  const reauthorizationsToken = unfilledToken(reviewValue(task, "Reauthorizations"));
+  if (reauthorizationsToken) {
+    problems.push(
+      problem(
+        "reauthorizations-shape",
+        `Reauthorizations carries the unfilled slot \`${reauthorizationsToken}\`, `
+          + "so it is not concrete. Replace that slot with the value it stands "
+          + "for, or fence it in inline code when it is literal text rather "
+          + "than a slot left to fill."
+      )
+    );
+  }
+
   const reviewFields = {
     Status: reviewValue(task, "Status"),
     "Acceptance check": reviewValue(task, "Acceptance check"),
@@ -817,14 +911,14 @@ function completionChecks(repo, task, contract = null) {
       problems.push(
         problem(
           "finding-owner",
-          "Review Findings must be `none` or carry a disposition. A finding "
-            + "fixed in this task is `Resolved here:` naming an `M<n>` check "
-            + "this task declares or a repo-relative path that exists; one "
-            + "someone must still do is `Durable owner:` naming "
+          "Review Findings must be `none` or carry a disposition — name a "
+            + "path after `Durable owner:` so it reads as the owner rather "
+            + "than a file the finding mentions. A finding fixed in this "
+            + "task is `Resolved here:` naming an `M<n>` check this task "
+            + "declares or a repo-relative path that exists; one someone "
+            + "must still do is `Durable owner:` naming "
             + `${DURABLE_OWNER_FORMS}; one deliberately not being done is a `
-            + "`Discard reason:`/`Discard rationale:` prefix. Name a path after "
-            + "`Durable owner:` so it reads as the owner rather than a file the "
-            + "finding mentions."
+            + "`Discard reason:`/`Discard rationale:` prefix."
         )
       );
     }
@@ -855,7 +949,8 @@ function taskComplete(repo, options) {
   }
   const contract = compileTaskContract(repo, selection.change, task);
   const usableContract = contract.diagnostics.length === 0 ? contract : null;
-  const checks = completionChecks(repo, task, usableContract);
+  const changeVerify = changeVerifyChecks(selection.content, selection.tasks);
+  const checks = completionChecks(repo, task, usableContract, changeVerify);
   checks.problems.push(...contract.diagnostics);
   const missingAnchor = missingAnchorProblem(selection, task);
   if (missingAnchor) {
@@ -895,6 +990,131 @@ function taskComplete(repo, options) {
   );
 }
 
+// The body of a change-level section — `## Invalidates`, `## Expectation
+// Coverage` — ending at the next `##` heading or at the next task, whichever
+// comes first. The heading half alone is the right bound for a document made of
+// headings, and a tasks file is not one: its dominant structure is a list, so a
+// section that is not the file's last one ran over the whole task list and read
+// what the tasks had declared. An `E<n>` line under a task's `Covers` was
+// judged as a coverage entry and reported unclosed; a `repo-action` task's
+// `Touch` of a bare `- none` was read as the section's `- None.` and closed a
+// declaration that closed nothing. The first failed loudly and named an entry
+// that was fine, the second failed silently, and which one an author met
+// depended only on where they had put the section — a position no template,
+// diagnostic, or document has ever stated.
+//
+// The task half is the task list already parsed for this file rather than a
+// second checkbox pattern, so it cannot drift from the boundary `parseTasks()`
+// applies to a task's own body. The heading half stays as it was: the two
+// spellings are not interchangeable, and unifying them truncates a tail-position
+// section at an indented `##` line inside its own body, which is this same
+// defect pointed the other way.
+function sectionBody(content, headingOffset, tasks) {
+  const lines = content.split(/\r?\n/);
+  const headingLine = content.slice(0, headingOffset).split(/\r?\n/).length - 1;
+  let end = lines.length;
+  for (const task of tasks) {
+    if (task.line > headingLine && task.line < end) end = task.line;
+  }
+  for (let cursor = headingLine + 1; cursor < end; cursor += 1) {
+    if (/^##\s+/.test(lines[cursor])) {
+      end = cursor;
+      break;
+    }
+  }
+  return lines.slice(headingLine + 1, end).join("\n");
+}
+
+// A `(regression)` check's bare Evidence may point at a change-level check
+// instead of recording its own result — issue #95. `deferred to C<n>` is
+// matched at the front of the value, the same way `Resolved here:`/`Durable
+// owner:` prefixes are read elsewhere in this file, so a real result that
+// happens to mention "deferred" mid-sentence is not misread as one.
+function deferredChangeCheck(value) {
+  const match = String(value || "").trim().match(/^deferred to (C[1-9]\d*)\b/i);
+  return match ? match[1] : null;
+}
+
+// `## Change Verify` is a change-level section a `(regression)` check's
+// Evidence can defer to — a check that only needs to run once for the whole
+// change instead of once per task. Parsed the same way as `## Invalidates`/
+// `## Expectation Coverage`: located by heading, bounded by `sectionBody()`.
+// Absent by default; a change that no task defers in never needs it.
+function changeVerifyChecks(content, tasks) {
+  const heading = content.search(/^## Change Verify\s*$/m);
+  if (heading < 0) return null;
+  const section = sectionBody(content, heading, tasks);
+  const strategyEntry = section.match(/^\s*-\s*Strategy:\s*(.*)$/im);
+  const checks = [
+    ...section.matchAll(/^\s*-\s*(C[1-9]\d*):\s*(.*)$/gim),
+  ].map((match) => ({ label: match[1], check: match[2].trim() }));
+  return {
+    strategy: strategyEntry ? strategyEntry[1].trim() : "",
+    checks,
+  };
+}
+
+// The `## Change Evidence` counterpart to `changeVerifyChecks` — one `C<n>:`
+// result per declared check, read the same way a task's own `M<n>` Evidence
+// already is.
+function changeEvidenceValue(content, tasks, label) {
+  const heading = content.search(/^## Change Evidence\s*$/m);
+  if (heading < 0) return "";
+  const section = sectionBody(content, heading, tasks);
+  const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = section.match(new RegExp(`^\\s*-\\s*${escaped}:\\s*(.*)$`, "im"));
+  return match ? match[1].trim() : "";
+}
+
+// `change-close`-only: `## Change Verify`'s own shape, and completeness of
+// `## Change Evidence` for every check it declares — whether or not any task
+// actually defers to it, because a declared check still owes its own result.
+// Per-task resolution (does a deferred reference resolve at all) runs inside
+// `completionChecks`, shared by `task-complete` and this loop's own call to
+// it, so it is not repeated here.
+function changeVerifyProblems(content, tasks) {
+  const changeVerify = changeVerifyChecks(content, tasks);
+  if (!changeVerify) return [];
+  const problems = [];
+  const labels = changeVerify.checks.map((entry) => entry.label);
+  const expected = labels.map((_, index) => `C${index + 1}`);
+  if (labels.length === 0 || !isConcrete(changeVerify.strategy)) {
+    problems.push(
+      problem(
+        "change-verify-shape",
+        "`## Change Verify` requires a concrete `Strategy:` line and at "
+          + "least one `C<n>:` check."
+      )
+    );
+  } else if (labels.some((label, index) => label !== expected[index])) {
+    problems.push(
+      problem(
+        "change-verify-shape",
+        "`## Change Verify` labels must be contiguous and ordered: "
+          + `expected ${expected.join(", ")}; found ${labels.join(", ")}.`
+      )
+    );
+  }
+  for (const entry of changeVerify.checks) {
+    if (!isConcrete(entry.check)) {
+      problems.push(
+        problem("change-verify-shape", `${entry.label} must define a concrete check.`)
+      );
+    }
+  }
+  for (const entry of changeVerify.checks) {
+    if (!isConcrete(changeEvidenceValue(content, tasks, entry.label))) {
+      problems.push(
+        problem(
+          "change-evidence-missing",
+          `Missing concrete \`## Change Evidence\` for ${entry.label}.`
+        )
+      );
+    }
+  }
+  return problems;
+}
+
 // Follow-up Ownership governs work a change left undone. This is the opposite
 // shape: statements left standing by work the change completed. It is asked at
 // task-start rather than change-close because the whole value is that the
@@ -919,10 +1139,7 @@ function invalidationProblems(repo, content, tasks) {
       ),
     ];
   }
-  const bodyStart = content.indexOf("\n", heading);
-  const remainder = bodyStart < 0 ? "" : content.slice(bodyStart + 1);
-  const nextHeading = remainder.search(/^##\s+/m);
-  const section = nextHeading < 0 ? remainder : remainder.slice(0, nextHeading);
+  const section = sectionBody(content, heading, tasks);
   if (/^\s*-\s+None\.?\s*$/im.test(section)) return [];
   const entries = [
     ...section.matchAll(
@@ -1022,10 +1239,7 @@ function expectationProblems(repo, content, tasks) {
       ),
     ];
   }
-  const bodyStart = content.indexOf("\n", heading);
-  const remainder = bodyStart < 0 ? "" : content.slice(bodyStart + 1);
-  const nextHeading = remainder.search(/^##\s+/m);
-  const section = nextHeading < 0 ? remainder : remainder.slice(0, nextHeading);
+  const section = sectionBody(content, heading, tasks);
   if (/^\s*-\s+None\.?\s*$/im.test(section)) return [];
   const entries = [
     ...section.matchAll(
@@ -1117,6 +1331,7 @@ function changeClose(repo, options) {
   const problems = [];
   const reviewProblems = [];
   const contracts = [];
+  const changeVerify = changeVerifyChecks(selection.content, selection.tasks);
   if (selection.tasks.length === 0) {
     problems.push(problem("missing-tasks", "Change has no executable tasks."));
   }
@@ -1162,7 +1377,8 @@ function changeClose(repo, options) {
     const checks = completionChecks(
       repo,
       task,
-      contract.diagnostics.length === 0 ? contract : null
+      contract.diagnostics.length === 0 ? contract : null,
+      changeVerify
     );
     problems.push(
       ...checks.problems.map((item) =>
@@ -1176,6 +1392,7 @@ function changeClose(repo, options) {
     );
   }
   problems.push(...expectationProblems(repo, selection.content, selection.tasks));
+  problems.push(...changeVerifyProblems(selection.content, selection.tasks));
 
   const changePath = path.dirname(selection.tasksPath);
   if (!hasDeltaSpec(changePath)) {

package/src/core/guard.js

@@ -59,6 +59,20 @@ function sha256(buffer) {
   return crypto.createHash("sha256").update(buffer).digest("hex");
 }
 
+// The content a dirty path held at the moment it was read, or `null` when
+// nothing could be read — a deleted path, mid-rename, or one that never
+// existed. `null` is a signature like any other: it round-trips through the
+// same equality check a real hash does, so a path that stays absent compares
+// equal and one that gets created or deleted compares unequal, with no
+// special case for either direction.
+function contentSignature(repo, relative) {
+  try {
+    return sha256(fs.readFileSync(path.join(repo, relative)));
+  } catch {
+    return null;
+  }
+}
+
 function guardResult(subcommand, status, extra = {}) {
   return {
     schemaVersion: 1,
@@ -68,17 +82,17 @@ function guardResult(subcommand, status, extra = {}) {
     manifestPath: "keel/guard.json",
     problems: [],
     warnings: [
-      "The guard manifest is a disposable enforcement pointer; OpenSpec and "
-        + "Git remain the only durable authority and selection never derives "
+      "The guard manifest is a disposable enforcement pointer, not durable "
+        + "authority — OpenSpec and Git are, and selection never derives "
         + "from it.",
       // The status describes a file Keel wrote. Whether anything reads that
       // file is a target-side fact: enforcement runs as a runtime hook the
       // host loads, and a host that loaded different plugins keeps them for
       // the life of its session. Reporting `started` as though it were a probe
       // result is the same inference `--doctor` already refuses to make.
-      "This status describes the manifest only. Enforcement runs as a runtime "
-        + "hook in the host, which Keel cannot observe from the repository, so "
-        + "a written manifest is not evidence that any write was checked.",
+      "This describes the manifest only. Enforcement runs as a runtime hook "
+        + "Keel cannot observe, so a written manifest proves no write was "
+        + "checked.",
     ],
     ...extra,
   };
@@ -161,13 +175,25 @@ function readManifest(repo) {
   // written by a Keel that omits it, are both valid; what they are not is
   // evidence that nothing was dirty. The consumer distinguishes absent from
   // empty, so an empty list means "nothing was dirty" and an absent one means
-  // "nobody looked".
+  // "nobody looked". Each entry carries the path's content signature, not
+  // just its name, so completion can tell "still the content recorded at
+  // task start" from "dirty again for a different reason" — `sha256` is
+  // `null` for a path that had nothing to read.
   if (
     manifest.startedDirty !== undefined
     && (!Array.isArray(manifest.startedDirty)
-      || manifest.startedDirty.some((item) => typeof item !== "string"))
+      || manifest.startedDirty.some(
+        (item) =>
+          !item
+          || typeof item.path !== "string"
+          || !item.path
+          || (item.sha256 !== null
+            && !/^[0-9a-f]{64}$/.test(String(item.sha256 || "")))
+      ))
   ) {
-    shapeErrors.push("startedDirty must be a string list when present");
+    shapeErrors.push(
+      "startedDirty must be a list of hashed dirty paths when present"
+    );
   }
   if (shapeErrors.length > 0) {
     return {
@@ -231,8 +257,14 @@ function startGuard(repo, options) {
 
   const paths = authorityPaths(repo, options.change, loaded.contract);
   // Read before the manifest is written, so the manifest is never in its own
-  // record and cannot be attributed to the task it authorizes.
-  const startedDirty = gitPaths(repo);
+  // record and cannot be attributed to the task it authorizes. Each dirty
+  // path is hashed at this same moment, so a later comparison can tell
+  // whether the task changed it again rather than only whether it stayed
+  // dirty.
+  const startedDirty = gitPaths(repo).map((relative) => ({
+    path: relative,
+    sha256: contentSignature(repo, relative),
+  }));
   const manifest = {
     schema: MANIFEST_SCHEMA,
     change: options.change,
@@ -265,12 +297,40 @@ function guardStatus(repo) {
   const problems = [];
   const loaded = loadTaskContract(repo, manifest.change, manifest.task);
   if (!loaded) {
-    problems.push({
-      code: "authority-drift",
-      message:
-        `Guarded task ${manifest.change}#${manifest.task} no longer resolves; `
-        + "reauthorize through `keel gate task-start` and `keel guard start`.",
-    });
+    // `loadTaskContract` returns null for two unrelated reasons — the tasks
+    // file is not there, or the task id is not in it — and only one of them
+    // has a reauthorization to perform. Telling the reader to reauthorize a
+    // change that has been archived sends them to `keel gate task-start`,
+    // which reports a missing tasks file, and to `keel guard start`, which
+    // reports that the task does not exist; neither names `keel guard clear`,
+    // which is the only action that resolves it.
+    //
+    // The change *directory* is the test, not the tasks file, and it is the
+    // same object `plugins/keel/scripts/pretooluse-guard.js` tests for the
+    // same question. Two surfaces deciding it by different means would
+    // eventually disagree about a state a reader is looking at from both. It
+    // also leaves a live change whose tasks.md is absent — mid-authoring — on
+    // the reauthorize path, where reauthorizing genuinely is the way out.
+    const changeDir = path.join(repo, "openspec", "changes", manifest.change);
+    problems.push(
+      fs.existsSync(changeDir)
+        ? {
+          code: "authority-drift",
+          message:
+            `Guarded task ${manifest.change}#${manifest.task} no longer `
+            + "resolves; reauthorize through `keel gate task-start` and "
+            + "`keel guard start`.",
+        }
+        : {
+          code: "stale-manifest",
+          message:
+            `This manifest is stale: it guards ${manifest.change}`
+            + `#${manifest.task}, but openspec/changes/${manifest.change} no `
+            + "longer exists, so the task it names cannot be reauthorized and "
+            + "its Touch list authorizes nothing. Run `keel guard clear`, then "
+            + "start the task you are actually working on.",
+        }
+    );
     const drifted = guardResult("status", "drifted", { manifest });
     drifted.problems = problems;
     return drifted;
@@ -354,6 +414,7 @@ module.exports = {
   GuardInputError,
   MANIFEST_SCHEMA,
   clearGuard,
+  contentSignature,
   gitPaths,
   guardStatus,
   readManifest,