@christang/keel 5.62.0 → 5.64.0

package/src/core/config.js

@@ -280,6 +280,65 @@ function readStandingAuthorization(repo) {
   return { declared, scopes, unknown, message: null };
 }
 
+// `full_mode_paths:` — the paths whose change always routes Full, whatever the
+// diff size says. One direction only: there is no key that holds a path *out* of
+// the complete flow however large its change, because every other declaration in
+// this file removes a confirmation and never a gate, and a routing entry that
+// skipped the flow would be the first to break that.
+//
+// Each entry carries its reason. A bare path declares that a file is special and
+// leaves a reader unable to recognise the sibling the list does not name; the
+// reason is the part that transfers, so an entry without one is reported rather
+// than read.
+//
+// Neither existing reader can hold the form. `configList` takes one token per
+// item and a sentence is not one; `configMap` keys on `\w+`, which
+// `results/experiments.jsonl` is not, and values on a single token. So this gets
+// its own reader, confined to this key rather than loosening a pattern the other
+// declarations rely on being exact.
+const FULL_MODE_PATH_ENTRY = /^\s+-\s*(\S+?)\s*:\s*(\S.*?)\s*$/;
+
+function readFullModePaths(repo) {
+  const configPath = path.join(repo, "keel", "config.yaml");
+  const paths = [];
+  const unreadable = [];
+  if (!fs.existsSync(configPath)) return { paths, unreadable };
+  const opener = /^full_mode_paths\s*:\s*$/;
+  let inBlock = false;
+  for (const line of fs.readFileSync(configPath, "utf8").split(/\r?\n/)) {
+    if (/^\s*#/.test(line)) continue;
+    if (opener.test(line)) {
+      inBlock = true;
+      continue;
+    }
+    if (!inBlock) continue;
+    if (line.trim() === "") continue;
+    const item = line.match(/^\s+-\s*(.*?)\s*$/);
+    // Anything that is not a list item closes the block, exactly as it does for
+    // the other two readers.
+    if (!item) break;
+    const entry = line.match(FULL_MODE_PATH_ENTRY);
+    if (!entry) {
+      unreadable.push(item[1]);
+      continue;
+    }
+    // The path's shape is read and its existence is not. An entry may name a
+    // file that does not exist yet, which is much of the point: the schema
+    // change that has not happened is the one worth routing Full.
+    paths.push({ path: entry[1], reason: entry[2] });
+  }
+  return { paths, unreadable };
+}
+
+function fullModePathsUnreadableMessage(unreadable) {
+  return `keel/config.yaml declares a full_mode_paths ${
+    unreadable.length === 1 ? "entry" : "entries"
+  } Keel could not read: ${unreadable.join(", ")}. Write each entry as `
+    + "`- <path>: <reason>`. The reason is required: a bare path says a file is "
+    + "special without saying what makes it so, and the agent reading it cannot "
+    + "then recognise the sibling the list does not name.";
+}
+
 // A nested block of `name: value` entries under one top-level key. Delegation
 // needs a key with a value rather than a bare list, so it cannot reuse
 // configList; the reader stays line-oriented for the same reason the others do.
@@ -476,6 +535,8 @@ module.exports = {
   DELEGATION_TIERS,
   STANDING_AUTHORIZATION_ACTIONS,
   SCOPED_AUTHORIZATION_ACTIONS,
+  readFullModePaths,
+  fullModePathsUnreadableMessage,
   readDelegationPolicy,
   readPrecedentStore,
   readStandingAuthorization,

package/src/core/context.js

@@ -11,7 +11,11 @@ const {
   field,
   parseTasks,
 } = require("./task-contract");
-const { readStandingAuthorization } = require("./config");
+const {
+  readStandingAuthorization,
+  readFullModePaths,
+  fullModePathsUnreadableMessage,
+} = require("./config");
 
 const NEXT_ACTIONS = new Set([
   "discuss",
@@ -671,6 +675,27 @@ function resolveContext(repo, options) {
   if (authorization.unknown.length > 0) {
     context.warnings.push(authorization.message);
   }
+  // Routing is the first decision of a session and the only durable rule with
+  // no gate behind it, so a project's declared exceptions are reported here —
+  // the one surface the protocol already requires an agent to read before
+  // deciding anything. Reported only when a declaration exists: a line printed
+  // every session for the repositories that declared nothing is a line a reader
+  // learns to skip (#131).
+  const routing = readFullModePaths(repo);
+  if (routing.unreadable.length > 0) {
+    // The other declarations in this file fail closed, and closed for them
+    // means *less proceeds without a human* — `authorize:` authorizes nothing,
+    // `triage:` admits nothing. The shared principle is to fail toward more
+    // scrutiny, and for a declaration whose whole purpose is to add process,
+    // more scrutiny is more Full mode. Reporting the entries it could read
+    // would let a typo silently lower the floor, which is the outcome the
+    // one-directional design exists to prevent.
+    context.routing = [];
+    context.routingUnreadable = true;
+    context.warnings.push(fullModePathsUnreadableMessage(routing.unreadable));
+  } else {
+    context.routing = routing.paths;
+  }
   // Set here rather than by the caller, so every consumer of the projection —
   // text, JSON, and any host reading it — carries the version without having
   // to know to add it.
@@ -714,6 +739,15 @@ function renderContext(result) {
         + ` (${result.selection.source})`
     );
   }
+  if (result.routingUnreadable) {
+    lines.push(
+      "Routing: every change routes Full until keel/config.yaml's "
+        + "full_mode_paths is corrected"
+    );
+  }
+  for (const entry of result.routing || []) {
+    lines.push(`Routing: ${entry.path} always routes Full — ${entry.reason}`);
+  }
   for (const reason of result.reasons) lines.push(`Reason: ${reason}`);
   for (const warning of result.warnings) lines.push(`Warning: ${warning}`);
   return `${lines.join("\n")}\n`;

package/src/core/gates.js

@@ -1022,6 +1022,68 @@ function completionChecks(repo, task, contract = null, changeVerify = null, chan
       );
     }
   }
+  // A declared measurement is held against the check's own bare `M<n>` Evidence
+  // — the entry where the command and its output are recorded. A literal that
+  // output does not contain is either unpasted or not measured, and free prose
+  // gives a reader no way to tell those from a real reading (issue #132).
+  for (const entry of contract ? contract.capsule.verification.commands : []) {
+    if (!entry.measured || !entry.label) continue;
+    const recorded = evidenceValue(task, entry.label);
+    if (!isConcrete(recorded)) continue;
+    if (!String(recorded).includes(entry.measured)) {
+      problems.push(
+        problem(
+          "measurement-missing-from-evidence",
+          `${entry.label} declares the measurement \`${entry.measured}\`, and `
+            + `its recorded ${entry.label} Evidence does not contain that `
+            + "string. Paste the output the number came from, or correct the "
+            + "declaration — which moves the contract fingerprint, because a "
+            + "number reconciled to the output after the run is a transcription "
+            + "of it.",
+        )
+      );
+    }
+  }
+  // A declared injection is enforced whatever the strategy and whatever the
+  // tags. It is not a red-green artifact: `.red` proves the check failed before
+  // the implementation existed and a failure signature predicts the red of an
+  // *absent* feature, while an injection answers what neither can — whether the
+  // check still fails once the feature exists and is broken. A `(regression)`
+  // check is where it matters most, because it has no honest red at all, so
+  // exempting it here would remove the clause from its best use (issue #132).
+  //
+  // Keel does not run the mutation. What it holds is that the failure the author
+  // declared before the run appears in what they recorded after it.
+  for (const entry of contract ? contract.capsule.verification.commands : []) {
+    if (!entry.detects || !entry.label) continue;
+    const recorded = evidenceValue(task, `${entry.label}.detects`);
+    if (!isConcrete(recorded)) {
+      problems.push(
+        problem(
+          "missing-injection-evidence",
+          `${entry.label} declares that \`${entry.detects.mutation}\` must make `
+            + `it fail with \`${entry.detects.failure}\`, and records no `
+            + `${entry.label}.detects Evidence. Run the mutation, record what it `
+            + "printed, and revert it — a green check that has never been made "
+            + "to fail on the defect it names is not evidence that it would.",
+        )
+      );
+      continue;
+    }
+    if (!String(recorded).includes(entry.detects.failure)) {
+      problems.push(
+        problem(
+          "injection-missing-declared-failure",
+          `${entry.label} declares that its injection fails with `
+            + `\`${entry.detects.failure}\`, and the recorded `
+            + `${entry.label}.detects Evidence does not contain that string. `
+            + "Record what the mutation actually printed, or correct the "
+            + "declaration — which moves the contract fingerprint, because an "
+            + "injection edited after the run is a transcription of it.",
+        )
+      );
+    }
+  }
   const strategy = contract
     ? contract.capsule.verification.strategy.toLowerCase()
     : "";

package/src/core/task-contract.js

@@ -153,28 +153,88 @@ const RED_GREEN_VERIFICATION_STRATEGIES = new Set([
 // Tags an M<n> check may carry after its label, as a comma-separated set.
 const COMMAND_TAGS = new Set(["fast", "full", "regression"]);
 
-// A check may end by declaring the failure its red is expected to show, so that
-// what the red proves is written down before the red is run. The clause closes
-// the check: `Fails with:` followed by one inline-code literal and nothing more.
-// End-anchored on purpose — a check that describes this rule mentions the marker
-// mid-sentence, and a mention is not a declaration.
-const FAILURE_SIGNATURE = /\bFails with:[ \t]*`([^`\n]+)`[ \t]*$/i;
-const FAILURE_MARKER = /\bFails with:/i;
+// A check may end by declaring things about itself, so that each is written down
+// before the run it describes. Every clause has the same shape: it closes the
+// clause sequence with inline-code literals, it lives inside the check text and
+// therefore inside the contract fingerprint, and it is enforced by requiring its
+// literal in a named Evidence entry. Keel judges none of them.
+//
+// The clauses chain. A check is one line — `fieldValues` splits the field per
+// line and treats each as its own entry — so a single end-anchored slot would
+// make the clauses mutually exclusive, and the case that motivated `Detects:`
+// declares an injection beside a failure signature on one check (issue #132).
+//
+// Each is still anchored at the end of what remains, on purpose: a check that
+// describes this rule mentions a marker mid-sentence, and a mention is not a
+// declaration.
+//
+// - `Fails with:` — the failure the check's red must show. Predicts the red of an
+//   *absent* feature.
+// - `Detects:` — a mutation that puts a defect in, and the failure it must
+//   produce. Answers the question a red cannot: the red of a *broken* feature.
+//   The two can be entirely unrelated, which is the whole reason this exists.
+const DECLARATION_CLAUSES = [
+  {
+    name: "failure",
+    pattern: /\bFails with:[ \t]*`([^`\n]+)`[ \t]*$/i,
+    marker: /\bFails with:/i,
+    build: (match) => match[1].trim(),
+  },
+  {
+    name: "detects",
+    pattern: /\bDetects:[ \t]*`([^`\n]+)`[ \t]*->[ \t]*`([^`\n]+)`[ \t]*$/i,
+    marker: /\bDetects:/i,
+    build: (match) => ({
+      mutation: match[1].trim(),
+      failure: match[2].trim(),
+    }),
+  },
+  {
+    // `Measured:` — a literal the check's own recorded output must contain. The
+    // failure class is a number that reads like a measurement and is an estimate
+    // or a recollection; free prose cannot tell a reader which it is. Opt-in on
+    // purpose: a universal rule over every number in Evidence would reach 847
+    // inline-code spans in this repository's own archive, most of them version
+    // strings, counts the author computed, and quoted references that appear in
+    // no command output, and each would be a false stop.
+    name: "measured",
+    pattern: /\bMeasured:[ \t]*`([^`\n]+)`[ \t]*$/i,
+    marker: /\bMeasured:/i,
+    build: (match) => match[1].trim(),
+  },
+];
 
-// Classify a check's `Fails with:` marker. `signature` is the declared literal;
-// `malformed` marks a marker that is present and is not a closing clause — a
-// typo shape, and ignoring it would leave the author believing a signature is
-// enforced when none was parsed. A marker written inside inline code is quoted
-// material rather than a declaration, the meaning inline code already carries
-// here, which is what lets this file's own tasks name the marker.
-function failureSignature(check) {
-  const text = String(check || "");
-  const match = text.match(FAILURE_SIGNATURE);
-  if (match) return { signature: match[1].trim(), malformed: false };
+// Strip one matching trailing clause at a time until none matches, then report a
+// marker surviving in the remaining prose as malformed. Malformed rather than
+// ignored: a declaration that parsed as nothing reads to its author as a check
+// being enforced. A marker inside inline code is quoted material, the meaning
+// inline code already carries here, which is what lets this file's own tasks
+// name the markers.
+function declarationClauses(check) {
+  let text = String(check || "");
+  const declared = {};
+  for (let matched = true; matched; ) {
+    matched = false;
+    for (const clause of DECLARATION_CLAUSES) {
+      const match = text.match(clause.pattern);
+      if (!match) continue;
+      if (!(clause.name in declared)) declared[clause.name] = clause.build(match);
+      text = text.slice(0, match.index).replace(/[ \t]+$/, "");
+      matched = true;
+      break;
+    }
+  }
   const remainder = withoutInlineCode(text);
+  const malformed = {};
+  for (const clause of DECLARATION_CLAUSES) {
+    malformed[clause.name] =
+      !(clause.name in declared) && clause.marker.test(remainder);
+  }
   return {
-    signature: null,
-    malformed: FAILURE_MARKER.test(remainder),
+    signature: declared.failure == null ? null : declared.failure,
+    detects: declared.detects == null ? null : declared.detects,
+    measured: declared.measured == null ? null : declared.measured,
+    malformed,
   };
 }
 
@@ -226,6 +286,10 @@ function verification(task) {
         check: entry,
         failsWith: null,
         malformedSignature: false,
+        detects: null,
+        malformedInjection: false,
+        measured: null,
+        malformedMeasurement: false,
       };
     }
     const tags = (match[2] || "")
@@ -240,17 +304,25 @@ function verification(task) {
         check: entry,
         failsWith: null,
         malformedSignature: false,
+        detects: null,
+        malformedInjection: false,
+        measured: null,
+        malformedMeasurement: false,
       };
     }
     const check = normalizeText(match[3]);
-    const failure = failureSignature(check);
+    const clauses = declarationClauses(check);
     return {
       label: match[1],
       layer: tags.includes("fast") ? "fast" : "full",
       regression: tags.includes("regression"),
       check,
-      failsWith: failure.signature,
-      malformedSignature: failure.malformed,
+      failsWith: clauses.signature,
+      malformedSignature: clauses.malformed.failure,
+      detects: clauses.detects,
+      malformedInjection: clauses.malformed.detects,
+      measured: clauses.measured,
+      malformedMeasurement: clauses.malformed.measured,
     };
   });
   return {
@@ -443,6 +515,29 @@ function failureSignatureProblems(task) {
       });
       continue;
     }
+    if (entry.malformedMeasurement) {
+      problems.push({
+        code: "malformed-measurement",
+        message:
+          `${entry.label} carries a \`Measured:\` marker that does not close `
+          + "the check with a literal. Write it as `Measured: `<literal>`` at "
+          + "the end of the check, or fence the marker in inline code when the "
+          + "check is describing it rather than declaring one.",
+      });
+      continue;
+    }
+    if (entry.malformedInjection) {
+      problems.push({
+        code: "malformed-injection",
+        message:
+          `${entry.label} carries a \`Detects:\` marker that does not close `
+          + "the check with a mutation and the failure it must produce. Write "
+          + "it as `Detects: `<mutation>` -> `<failure>`` at the end of the "
+          + "check, or fence the marker in inline code when the check is "
+          + "describing it rather than declaring one.",
+      });
+      continue;
+    }
     if (!entry.failsWith) continue;
     if (!redGreen) {
       problems.push({
@@ -1229,6 +1324,8 @@ function compileTaskContract(repo, change, task) {
           // field is what the gate reads. Emitted only when declared, so every
           // check without one keeps the capsule shape and fingerprint it had.
           if (entry.failsWith) emitted.failsWith = entry.failsWith;
+          if (entry.detects) emitted.detects = entry.detects;
+          if (entry.measured) emitted.measured = entry.measured;
           return emitted;
         }),
     },