@christang/keel 5.3.1 → 5.3.4

package/src/core/gates.js

@@ -134,7 +134,10 @@ function taskStart(repo, options) {
   const selection = loadSelection(repo, options);
   const task = selection.selected[0];
   const compiled = compileTaskContract(repo, selection.change, task);
-  const problems = [...compiled.diagnostics];
+  const problems = [
+    ...compiled.diagnostics,
+    ...invalidationProblems(repo, selection.content, selection.tasks),
+  ];
   // Recording the current fingerprint is idempotent: --record replaces the
   // selected task's Contract anchor whatever it holds, so reauthorizing a task
   // whose authority changed — the path the guard's own drift messages direct
@@ -252,19 +255,52 @@ function reviewValue(task, label) {
 // confirmed that an archive path resolves either, so an external tracker
 // reference is no less checkable than what was already accepted; whether the
 // owner is real stays a Review judgment.
-const SHARED_DURABLE_OWNER_FORMS =
-  /(?:\bkeel\/archive\/[A-Za-z0-9._/-]+|\bhttps?:\/\/\S)/i;
+const TRACKER_REFERENCE = /\bhttps?:\/\/\S/i;
+
+// The owner forms, stated once so every refusal that lists them agrees with
+// every other and with what the checks below actually accept.
+const DURABLE_OWNER_FORMS =
+  "an absolute `https://…` tracker reference, or any repo-relative path that "
+  + "exists — `keel/archive/…`, an `openspec/changes/…` artifact, or the "
+  + "repository's own ledger; `keel/HANDOFF.md` is a pointer override rather "
+  + "than an owner";
+
+// Classify a declared `Durable owner:` value. A gate runs without network, so a
+// URL is accepted on shape alone; a path is the one form it can actually check,
+// and checking it is stricter than the prefix whitelist this replaced.
+function durableOwnerVerdict(repo, value) {
+  const owner = String(value || "").trim();
+  if (!owner) return { ok: false, reason: "unrecognized" };
+  if (/keel\/HANDOFF\.md/i.test(owner)) return { ok: false, reason: "handoff" };
+  if (TRACKER_REFERENCE.test(owner)) return { ok: true };
+  const candidate = owner.match(/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)+/);
+  if (!candidate) return { ok: false, reason: "unrecognized" };
+  if (fs.existsSync(path.join(repo, candidate[0]))) return { ok: true };
+  return { ok: false, reason: "missing", path: candidate[0] };
+}
 
 function findingOwnerIsDurable(repo, findings) {
   if (/keel\/HANDOFF\.md/i.test(findings)) return false;
   if (/\b(?:explicit\s+)?discard (?:reason|rationale)\s*:/i.test(findings)) {
     return true;
   }
-  if (SHARED_DURABLE_OWNER_FORMS.test(findings)) return true;
-  const owner = findings.match(
+  if (TRACKER_REFERENCE.test(findings)) return true;
+  // A path counts here only when it is named as the owner. Findings is free
+  // prose, and a finding that merely mentions the source file it concerns has
+  // not thereby given that finding an owner.
+  const declared = findings.match(/Durable owner:\s*(\S[^\n]*)/i);
+  if (declared) return durableOwnerVerdict(repo, declared[1]).ok;
+  const artifact = findings.match(
     /\b(openspec\/changes\/[A-Za-z0-9][A-Za-z0-9._-]*\/(?:proposal|design|tasks)\.md)(?:#\d+(?:\.\d+)*)?/i
   );
-  return Boolean(owner && fs.existsSync(path.join(repo, owner[1])));
+  if (artifact && fs.existsSync(path.join(repo, artifact[1]))) return true;
+  return /\bkeel\/archive\/[A-Za-z0-9._/-]+/i.test(findings)
+    && fs.existsSync(
+      path.join(
+        repo,
+        findings.match(/\bkeel\/archive\/[A-Za-z0-9._/-]+/i)[0]
+      )
+    );
 }
 
 function gitPaths(repo) {
@@ -432,14 +468,24 @@ function completionChecks(repo, task, contract = null) {
     ? contract.capsule.verification.strategy.toLowerCase()
     : "";
   if (RED_GREEN_VERIFICATION_STRATEGIES.has(strategy)) {
+    // A `(regression)` check asserts that something already green is still
+    // green, so it has no honest red. It is exempt from red-green but not from
+    // evidence: the bare-label check above still applies to it.
+    const exempt = new Set(
+      (contract ? contract.capsule.verification.commands : [])
+        .filter((entry) => entry.regression)
+        .map((entry) => entry.label)
+    );
     for (const label of commands) {
+      if (exempt.has(label)) continue;
       for (const phase of ["red", "green"]) {
         if (!isConcrete(evidenceValue(task, `${label}.${phase}`))) {
           problems.push(
             problem(
               "missing-strategy-evidence",
               `${strategy} requires concrete ${label}.${phase} Evidence for `
-                + "the same behavior check."
+                + "the same behavior check. Tag the check `(regression)` if it "
+                + "asserts that something already green stays green."
             )
           );
         }
@@ -501,9 +547,9 @@ function completionChecks(repo, task, contract = null) {
       problem(
         "finding-owner",
         "Review Findings must be `none` or carry a durable owner — a "
-          + "`Discard reason:`/`Discard rationale:` prefix, a `keel/archive/…` "
-          + "path, an existing `openspec/changes/…` artifact, or an absolute "
-          + "`https://…` tracker reference; `keel/HANDOFF.md` is not an owner."
+          + "`Discard reason:`/`Discard rationale:` prefix, or "
+          + `${DURABLE_OWNER_FORMS}. Name a path after \`Durable owner:\` so `
+          + "it reads as the owner rather than a file the finding mentions."
       )
     );
   }
@@ -543,7 +589,122 @@ function taskComplete(repo, options) {
   );
 }
 
-function expectationProblems(content, tasks) {
+// 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
+// affected paths enter Touch before implementation — asking at the close finds
+// the same facts after the reauthorization it was meant to prevent.
+//
+// A location list is refused on purpose. The text that goes stale is the text
+// the author was not already holding in mind, so a list of remembered files
+// reproduces the failure; a searchable phrase is what turns the declaration
+// into a grep. What the phrase says is the agent's judgment, not the gate's.
+function invalidationProblems(repo, content, tasks) {
+  const heading = content.search(/^## Invalidates\s*$/m);
+  if (heading < 0) {
+    return [
+      problem(
+        "invalidation-declaration",
+        "tasks.md requires a `## Invalidates` section before its tasks are "
+          + "executable: one `- I<n>: \"searchable phrase\" — where it lives. "
+          + "Updated by: <task ids>` line per statement this change makes "
+          + "stale, using `Durable owner:` or `Discard reason:` instead when "
+          + "no task of this change updates it, or `- None.`."
+      ),
+    ];
+  }
+  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);
+  if (/^\s*-\s+None\.?\s*$/im.test(section)) return [];
+  const entries = [
+    ...section.matchAll(
+      /^\s*-\s+(I\d+)\s*:\s*([\s\S]*?)(?=^\s*-\s+I\d+\s*:|(?![\s\S]))/gm
+    ),
+  ];
+  if (entries.length === 0) {
+    return [
+      problem(
+        "invalidation-declaration",
+        "Invalidates must declare each `I<n>` entry — a quoted searchable "
+          + "phrase, where it lives, and a closure (`Updated by:`, "
+          + "`Durable owner:`, or `Discard reason:`) — or `- None.`."
+      ),
+    ];
+  }
+  const problems = [];
+  for (const entry of entries) {
+    const [, id, body] = entry;
+    if (!/"[^"\n]{3,}"/.test(body)) {
+      problems.push(
+        problem(
+          "invalidation-phrase",
+          `${id} names where to look but not what to look for. Quote the `
+            + "wording a reader would search for, so the entry is a search "
+            + "rather than a reminder."
+        )
+      );
+      continue;
+    }
+    const updated = body.match(/Updated by:\s*([0-9.,\s-]+)/i);
+    const declaredOwner = body.match(/Durable owner:\s*(\S[^\n]*)/i);
+    const verdict = declaredOwner
+      ? durableOwnerVerdict(repo, declaredOwner[1])
+      : { ok: false, reason: "absent" };
+    const discarded = /Discard(?:ed)? (?:reason|rationale):\s*\S/i.test(body);
+    if (!updated && !verdict.ok && !discarded) {
+      if (verdict.reason === "missing") {
+        problems.push(
+          problem(
+            "invalidation-owner-missing",
+            `${id} names \`${verdict.path}\` as its durable owner, but no such `
+              + "file exists in this repository."
+          )
+        );
+      } else if (verdict.reason === "handoff") {
+        problems.push(
+          problem(
+            "invalidation-closure",
+            `${id} names keel/HANDOFF.md, which is a pointer override rather `
+              + `than a durable owner. Accepted forms: ${DURABLE_OWNER_FORMS}.`
+          )
+        );
+      } else {
+        problems.push(
+          problem(
+            "invalidation-closure",
+            `${id} lacks an updating task, a durable owner, or a discard `
+              + "rationale. Close it with `Updated by: <task ids>` naming tasks "
+              + "of this change, a `Discard reason:`, or a `Durable owner:` "
+              + `naming ${DURABLE_OWNER_FORMS}.`
+          )
+        );
+      }
+      continue;
+    }
+    // Deliberately weaker than Expectation Coverage, which requires a checked
+    // task: at authoring time the updater has not run yet, so existence is the
+    // only honest assertion. Completion is then structural — the named task
+    // carries the paths in its Touch and passes its own gate.
+    if (updated) {
+      const ids = updated[1].match(/\d+(?:\.\d+)+/g) || [];
+      for (const taskId of ids) {
+        if (!tasks.some((task) => task.id === taskId)) {
+          problems.push(
+            problem(
+              "invalidation-owner",
+              `${id} names task ${taskId}, which this change does not define.`
+            )
+          );
+        }
+      }
+    }
+  }
+  return problems;
+}
+
+function expectationProblems(repo, content, tasks) {
   const heading = content.search(/^## Expectation Coverage\s*$/m);
   if (heading < 0) {
     return [
@@ -581,19 +742,30 @@ function expectationProblems(content, tasks) {
     const [, id, body] = entry;
     const covered = body.match(/Covered by:\s*([0-9.,\s-]+)/i);
     const declaredOwner = body.match(/Durable owner:\s*(\S[^\n]*)/i);
-    const hasDurableOwner = Boolean(
-      declaredOwner
-      && (/^openspec\/changes\//i.test(declaredOwner[1].trim())
-        || SHARED_DURABLE_OWNER_FORMS.test(declaredOwner[1]))
-    );
+    const verdict = declaredOwner
+      ? durableOwnerVerdict(repo, declaredOwner[1])
+      : { ok: false, reason: "absent" };
     const discarded = /Discard(?:ed)? (?:reason|rationale):\s*\S/i.test(body);
-    if (!covered && !hasDurableOwner && !discarded) {
-      problems.push(
-        problem(
-          "expectation-closure",
-          `${id} lacks behavior coverage, durable owner, or discard rationale.`
-        )
-      );
+    if (!covered && !verdict.ok && !discarded) {
+      if (verdict.reason === "missing") {
+        problems.push(
+          problem(
+            "expectation-owner-missing",
+            `${id} names \`${verdict.path}\` as its durable owner, but no such `
+              + "file exists in this repository."
+          )
+        );
+      } else {
+        problems.push(
+          problem(
+            "expectation-closure",
+            `${id} lacks behavior coverage, durable owner, or discard `
+              + "rationale. Close it with `Covered by: <task ids>`, a "
+              + "`Discard reason:`, or a `Durable owner:` naming "
+              + `${DURABLE_OWNER_FORMS}.`
+          )
+        );
+      }
       continue;
     }
     if (covered) {
@@ -675,7 +847,7 @@ function changeClose(repo, options) {
       )
     );
   }
-  problems.push(...expectationProblems(selection.content, selection.tasks));
+  problems.push(...expectationProblems(repo, selection.content, selection.tasks));
 
   const changePath = path.dirname(selection.tasksPath);
   if (!hasDeltaSpec(changePath)) {

package/src/core/task-contract.js

@@ -130,6 +130,9 @@ const RED_GREEN_VERIFICATION_STRATEGIES = new Set([
   "regression-first",
 ]);
 
+// Tags an M<n> check may carry after its label, as a comma-separated set.
+const COMMAND_TAGS = new Set(["fast", "full", "regression"]);
+
 // Single source of truth for the accepted completion Review `Status`
 // vocabulary. Consumed by both the completion gate (src/core/gates.js) and the
 // context "already reviewed" probe (src/core/context.js) so the two never
@@ -156,12 +159,26 @@ function verification(task) {
     ? compact.filter((entry) => !/^Strategy:\s*/i.test(entry))
     : fieldValues(task, "Commands");
   const commands = commandSource.map((entry) => {
-    // An optional (fast)/(full) layer tag after the M<n> label marks which
-    // checks the fast inner loop runs; an untagged check is full.
-    const match = entry.match(/^(M[1-9]\d*)(?:\s*\((fast|full)\))?:\s*(.*)$/);
-    return match
-      ? { label: match[1], layer: match[2] || "full", check: normalizeText(match[3]) }
-      : { label: null, layer: "full", check: entry };
+    // An optional tag set after the M<n> label. `fast`/`full` marks which checks
+    // the fast inner loop runs; `regression` marks a check that asserts
+    // something already green is still green, which has no honest red and is
+    // therefore exempt from the red-green evidence requirement. A check may
+    // carry both, so the tag is a comma-separated set rather than one word.
+    const match = entry.match(/^(M[1-9]\d*)(?:\s*\(([^)\n]*)\))?:\s*(.*)$/);
+    if (!match) return { label: null, layer: "full", regression: false, check: entry };
+    const tags = (match[2] || "")
+      .split(",")
+      .map((tag) => tag.trim().toLowerCase())
+      .filter(Boolean);
+    if (tags.some((tag) => !COMMAND_TAGS.has(tag))) {
+      return { label: null, layer: "full", regression: false, check: entry };
+    }
+    return {
+      label: match[1],
+      layer: tags.includes("fast") ? "fast" : "full",
+      regression: tags.includes("regression"),
+      check: normalizeText(match[3]),
+    };
   });
   return {
     compact: compact.length > 0,
@@ -189,7 +206,9 @@ function commandLabelProblems(task) {
       malformed = true;
       problems.push({
         code: "invalid-command-label",
-        message: `Command entry must use an M<n> label: ${entry}`,
+        message: `Command entry must use an M<n> label, optionally followed by `
+          + `a tag set drawn from ${[...COMMAND_TAGS].join(", ")} — `
+          + `for example \`M2 (regression): …\`: ${entry}`,
       });
       continue;
     }
@@ -264,7 +283,7 @@ function taskStartContractProblems(task) {
         },
       ];
     }
-    return commandLabelProblems(task);
+    return [...commandLabelProblems(task), ...regressionOnlyProblems(task)];
   }
   if (!touch.some((entry) => isConcrete(entry))) {
     return [
@@ -273,9 +292,34 @@ function taskStartContractProblems(task) {
         message: "implementation and plan-first require a concrete Touch path.",
       },
       ...commandLabelProblems(task),
+      ...regressionOnlyProblems(task),
     ];
   }
-  return commandLabelProblems(task);
+  return [...commandLabelProblems(task), ...regressionOnlyProblems(task)];
+}
+
+// A red-green strategy whose every check is exempt from red-green is that
+// strategy in name only, and the tag would become the escape hatch rather than
+// the declaration it is meant to be.
+function regressionOnlyProblems(task) {
+  const parsed = verification(task);
+  if (!RED_GREEN_VERIFICATION_STRATEGIES.has(parsed.strategy.toLowerCase())) {
+    return [];
+  }
+  const labelled = parsed.commands.filter((entry) => entry.label);
+  if (labelled.length === 0 || labelled.some((entry) => !entry.regression)) {
+    return [];
+  }
+  return [
+    {
+      code: "regression-only-strategy",
+      message:
+        `\`${parsed.strategy}\` requires at least one check that is not tagged `
+        + "`(regression)`, because a regression check has no red to record. "
+        + "Untag the check that proves the new behavior, or name a strategy "
+        + "that is not red-green.",
+    },
+  ];
 }
 
 function requiredFieldProblems(task) {
@@ -803,15 +847,17 @@ function compileTaskContract(repo, change, task) {
     acceptance: [...new Set([...derivedAcceptance, ...explicitAcceptance])],
     verification: {
       strategy: taskVerification.strategy,
-      // Emit the layer only when a check opts into the fast inner loop, so
-      // untagged (full) checks keep their existing capsule shape and fingerprint.
+      // Emit a tag only when the check opts out of a default, so an untagged
+      // check keeps the capsule shape and fingerprint it had before either tag
+      // existed. `layer` appears only for `fast`, `regression` only when true.
       commands: taskVerification.commands
         .filter((entry) => entry.label)
-        .map((entry) =>
-          entry.layer && entry.layer !== "full"
-            ? { label: entry.label, check: entry.check, layer: entry.layer }
-            : { label: entry.label, check: entry.check }
-        ),
+        .map((entry) => {
+          const emitted = { label: entry.label, check: entry.check };
+          if (entry.layer && entry.layer !== "full") emitted.layer = entry.layer;
+          if (entry.regression) emitted.regression = true;
+          return emitted;
+        }),
     },
     boundaries: {
       autonomy,