@christang/keel 5.66.0 → 5.68.0

package/src/core/config.js

@@ -81,6 +81,7 @@ const CONFIG_DECLARATIONS = [
   "triage",
   "delegation",
   "full_mode_paths",
+  "executor_tier",
 ];
 
 const CONFIG_RELATIVE_PATH = path.join("keel", "config.yaml");
@@ -402,6 +403,55 @@ function readDelegationPolicy(repo) {
   return { declared: true, tier, unknown: [], accepted };
 }
 
+// Which guidance an executor loads, declared by the repository rather than
+// judged by the executor. #135's argument is that "do I need this help?" is the
+// judgement a weak executor gets most wrong, so the skip is written down; the
+// absent default therefore reads the guidance, and the worst an unconfigured
+// repository does is pay for a read.
+const EXECUTOR_TIERS = ["standard", "high"];
+const EXECUTOR_TIER_DEFAULT = "standard";
+
+// The tier reaches guidance and nothing else. It is a separate key from
+// `delegation:`'s tier on purpose: that one names who runs a *delegated* task,
+// and a repository may hand routine work to a weak delegate while its own
+// session is strong, so one field cannot answer both without lying about one.
+function readExecutorTier(repo) {
+  const declared = configScalar(repo, "executor_tier");
+  const accepted = [...EXECUTOR_TIERS];
+  if (!declared) {
+    return {
+      declared: false,
+      tier: EXECUTOR_TIER_DEFAULT,
+      unknown: [],
+      accepted,
+    };
+  }
+  // Fail closed, the same rule `delegation:` and `authorize:` follow — except
+  // that closed here means *reading* the guidance rather than skipping it. A
+  // misspelling must not silently buy the reduction it asked for.
+  if (!EXECUTOR_TIERS.includes(declared)) {
+    return {
+      declared: true,
+      tier: EXECUTOR_TIER_DEFAULT,
+      unknown: [declared],
+      accepted,
+      message: executorTierUnreadableMessage(declared, accepted),
+    };
+  }
+  return { declared: true, tier: declared, unknown: [], accepted };
+}
+
+// Names the value and the alternatives, never just the key: a reader told their
+// declaration is wrong without being told what is right has to go find the
+// documentation the declaration was supposed to replace.
+function executorTierUnreadableMessage(value, accepted) {
+  return (
+    `keel/config.yaml declares executor_tier: ${value}, which is not one of `
+    + `${accepted.join(", ")}; the ${EXECUTOR_TIER_DEFAULT} tier applies until `
+    + "it is corrected, so skill guidance is read rather than skipped"
+  );
+}
+
 function configScalar(repo, key) {
   const configPath = path.join(repo, "keel", "config.yaml");
   if (!fs.existsSync(configPath)) return null;
@@ -548,12 +598,16 @@ function triageIssue(repo, labels, issue = null) {
 module.exports = {
   CONFIG_RELATIVE_PATH,
   DELEGATION_TIERS,
+  EXECUTOR_TIERS,
+  EXECUTOR_TIER_DEFAULT,
   CONFIG_DECLARATIONS,
   STANDING_AUTHORIZATION_ACTIONS,
   SCOPED_AUTHORIZATION_ACTIONS,
   readFullModePaths,
   fullModePathsUnreadableMessage,
   readDelegationPolicy,
+  readExecutorTier,
+  executorTierUnreadableMessage,
   readPrecedentStore,
   readStandingAuthorization,
   readTriagePolicy,

package/src/core/context.js

@@ -15,6 +15,7 @@ const {
   readStandingAuthorization,
   readFullModePaths,
   fullModePathsUnreadableMessage,
+  readExecutorTier,
 } = require("./config");
 
 const NEXT_ACTIONS = new Set([
@@ -696,6 +697,14 @@ function resolveContext(repo, options) {
   } else {
     context.routing = routing.paths;
   }
+  // Reported every session, declared or not, unlike `full_mode_paths` above:
+  // the default is the one a reader most needs to see, because a repository
+  // that declared nothing is loading guidance it may not want and has no other
+  // surface that would tell it so.
+  const executor = readExecutorTier(repo);
+  context.executorTier = executor.tier;
+  if (executor.unknown.length > 0) context.warnings.push(executor.message);
+
   // 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.
@@ -748,6 +757,13 @@ function renderContext(result) {
   for (const entry of result.routing || []) {
     lines.push(`Routing: ${entry.path} always routes Full — ${entry.reason}`);
   }
+  if (result.executorTier) {
+    lines.push(
+      `Executor tier: ${result.executorTier} — affects which skill guidance is `
+        + "read and nothing else; no gate, criterion, evidence requirement, or "
+        + "Review changes with it"
+    );
+  }
   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

@@ -2,6 +2,7 @@
 
 // Keel 4.1.0 deterministic gate contract.
 
+const crypto = require("crypto");
 const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
@@ -293,6 +294,112 @@ function taskShapeWarnings(repo, selection, task, compiled) {
   ];
 }
 
+// The requirement names a change declares as new, read from the `## ADDED
+// Requirements` sections of its delta specs. A `## MODIFIED` requirement is
+// deliberately not here: behavior that changed is still behavior an equivalence
+// task can legitimately claim is measurement-stable.
+function addedRequirementNames(repo, change) {
+  const specsRoot = path.join(repo, "openspec", "changes", change, "specs");
+  const names = new Set();
+  let capabilities = [];
+  try {
+    capabilities = fs.readdirSync(specsRoot);
+  } catch {
+    return names;
+  }
+  for (const capability of capabilities) {
+    const specPath = path.join(specsRoot, capability, "spec.md");
+    let content = "";
+    try {
+      content = fs.readFileSync(specPath, "utf8");
+    } catch {
+      continue;
+    }
+    // Only the ADDED section, bounded by the next `## ` heading, so a
+    // requirement listed under MODIFIED or REMOVED is not read as new.
+    for (const section of content.split(/^##\s+/m).slice(1)) {
+      if (!/^ADDED Requirements\s*$/m.test(section.split(/\r?\n/)[0])) continue;
+      for (const match of section.matchAll(/^###\s+Requirement:\s*(.+?)\s*$/gm)) {
+        names.add(match[1]);
+      }
+    }
+  }
+  return names;
+}
+
+// A task's declared strategy, from the text it wrote. Both forms: the compact
+// `Strategy:` entry under `Verify`, and the expanded `Verification Strategy`
+// field beside `Commands`.
+function declaredStrategy(task) {
+  const compact = String(field(task, "Verify") || "").match(
+    /^\s*-?\s*Strategy:\s*(.+?)\s*$/m
+  );
+  const value = compact
+    ? compact[1]
+    : String(field(task, "Verification Strategy") || "");
+  return value.trim().toLowerCase();
+}
+
+// A `Covers` entry naming a spec scenario: `capability / Requirement / Scenario`.
+// Identifier entries (`D4`, `F1`, `E2`) have no slashes and are not spec claims.
+function specCoverEntries(task) {
+  return String(field(task, "Covers") || "")
+    .split(/\r?\n/)
+    .map((line) => line.replace(/^\s*-\s*/, "").trim())
+    .filter((entry) => entry.split("/").length >= 3)
+    .map((entry) => entry.split("/").map((part) => part.trim()));
+}
+
+// `equivalence` owes no red, which makes it the first strategy reached for by a
+// task that should have one. A task covering a scenario its own change *adds* is
+// claiming that behavior is new and that behavior is unchanged at the same time,
+// and without this guard one of the two claims has no proof anywhere in the
+// change. Satisfied only by a sibling covering the same entry, never by the mere
+// presence of a red-green task somewhere in the change.
+function equivalenceEscapeProblems(repo, selection, task, compiled) {
+  const strategy = String(
+    ((compiled.capsule || {}).verification || {}).strategy || ""
+  ).toLowerCase();
+  if (strategy !== "equivalence") return [];
+  const added = addedRequirementNames(repo, selection.change);
+  if (added.size === 0) return [];
+  const problems = [];
+  for (const parts of specCoverEntries(task)) {
+    const requirement = parts[1];
+    if (!added.has(requirement)) continue;
+    const entry = parts.join(" / ");
+    const scenario = parts.slice(2).join(" / ");
+    const covered = selection.tasks.some((sibling) => {
+      if (sibling.id === task.id) return false;
+      // Read from the sibling's own `Verify` text rather than by compiling it.
+      // Compiling made the guard depend on the sibling being otherwise valid: a
+      // sibling with any unrelated contract error produced no capsule, so its
+      // strategy read as absent and it silently stopped satisfying the guard.
+      const siblingStrategy = declaredStrategy(sibling);
+      if (!RED_GREEN_VERIFICATION_STRATEGIES.has(siblingStrategy)) return false;
+      // The same entry, not any entry. A guard satisfied by the presence of a
+      // red-green task would be a check that the change contains one, which
+      // every change with more than one task passes.
+      return specCoverEntries(sibling).some(
+        (other) => other.join(" / ") === entry
+      );
+    });
+    if (!covered) {
+      problems.push(
+        problem(
+          "equivalence-covers-added-behavior",
+          `This task declares \`Strategy: equivalence\` and covers `
+            + `"${scenario}", a scenario this change adds. Behavior that is new `
+            + "is not behavior that is unchanged, and no task of this change "
+            + "proves the new half: name a red-green task that covers the same "
+            + "entry, or move this Covers entry to the task that implements it."
+        )
+      );
+    }
+  }
+  return problems;
+}
+
 function taskStart(repo, options) {
   const selection = loadSelection(repo, options);
   const task = selection.selected[0];
@@ -300,6 +407,7 @@ function taskStart(repo, options) {
   const problems = [
     ...compiled.diagnostics,
     ...invalidationProblems(repo, selection.content, selection.tasks, selection.change),
+    ...equivalenceEscapeProblems(repo, selection, task, compiled),
   ];
   // Recording the current fingerprint is idempotent: --record replaces the
   // selected task's Contract anchor whatever it holds, so reauthorizing a task
@@ -454,6 +562,72 @@ function commandLabels(task) {
   ].map((match) => match[1]);
 }
 
+// `artifact <path> sha256:<digest>`, or null for prose. The path is
+// repo-relative; the digest is what Review is entitled to assume it is reading.
+const ARTIFACT_EVIDENCE =
+  /^artifact\s+(\S+)\s+sha256:([0-9a-f]{64})\s*$/i;
+
+function artifactReference(value) {
+  const match = String(value || "").trim().match(ARTIFACT_EVIDENCE);
+  return match ? { path: match[1], digest: match[2].toLowerCase() } : null;
+}
+
+// Keel checks identity and reads nothing else: it does not parse the artifact,
+// does not know what a field is, and compares nothing in it. The claim that the
+// numbers agree stays the author's, recorded before Review exactly as
+// `Fails with:` and `Detects:` are. What the digest buys is that the file Review
+// opens is the file the author meant, which a retelling cannot offer.
+function artifactProblems(repo, change, label, reference) {
+  if (!reference) return [];
+  // The inverse of the `Durable owner:` rule, and for the opposite reason: a
+  // follow-up pointer has to outlive the change, while an evidence artifact has
+  // to travel with it. `openspec archive` moves the change directory and
+  // nothing else, so a path outside it is one the archive is guaranteed to
+  // leave behind — and an evidence pointer that breaks on archive is worse than
+  // a retelling, which at least survives.
+  const changeDir = path.join("openspec", "changes", change);
+  const normalized = reference.path.split(path.sep).join("/");
+  if (!normalized.startsWith(`${changeDir.split(path.sep).join("/")}/`)) {
+    return [
+      problem(
+        "artifact-outside-change",
+        `${label} Evidence references \`${reference.path}\`, which is outside `
+          + `\`${changeDir}\`. Archiving moves the change directory and nothing `
+          + "else, so this pointer breaks the moment the change is archived. "
+          + "Put the artifact inside the change's own directory."
+      ),
+    ];
+  }
+  const absolute = path.join(repo, reference.path);
+  if (!fs.existsSync(absolute) || !fs.statSync(absolute).isFile()) {
+    return [
+      problem(
+        "artifact-missing",
+        `${label} Evidence references the artifact \`${reference.path}\`, and `
+          + "no file is there. An unresolvable reference is worse than a "
+          + "retelling: the retelling at least carries the result."
+      ),
+    ];
+  }
+  const actual = crypto
+    .createHash("sha256")
+    .update(fs.readFileSync(absolute))
+    .digest("hex");
+  if (actual !== reference.digest) {
+    return [
+      problem(
+        "artifact-digest-mismatch",
+        `${label} Evidence records \`${reference.path}\` at `
+          + `sha256:${reference.digest}, and the file there hashes to `
+          + `sha256:${actual}. Re-record the digest if the command was re-run, `
+          + "or correct the path — naming both is what lets a reader tell a "
+          + "stale record from a pointer at the wrong file."
+      ),
+    ];
+  }
+  return [];
+}
+
 function evidenceValue(task, label) {
   const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const match = field(task, "Evidence").match(
@@ -1049,11 +1223,21 @@ function completionChecks(repo, task, contract = null, changeVerify = null, chan
     problems.push(problem("missing-commands", "Commands must define at least one M<n>."));
   }
   for (const label of commands) {
-    if (!isConcrete(evidenceValue(task, label))) {
+    const recorded = evidenceValue(task, label);
+    if (!isConcrete(recorded)) {
       problems.push(
         problem("missing-evidence", `Missing concrete Evidence for ${label}.`)
       );
+      continue;
     }
+    // An A/B pairing or a sweep summary *is* the output of one command, and
+    // retelling it into tasks.md is a transcription that can be wrong and that
+    // nobody can re-check (issue #142). A reference is checked rather than
+    // tolerated: as prose it would already have passed as concrete, so without
+    // this the form would buy nothing at all.
+    problems.push(
+      ...artifactProblems(repo, change, label, artifactReference(recorded))
+    );
   }
   // 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

package/src/core/task-contract.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const crypto = require("crypto");
+const { execFileSync } = require("child_process");
 const fs = require("fs");
 const path = require("path");
 
@@ -143,6 +144,13 @@ const SUPPORTED_VERIFICATION_STRATEGIES = [
   "snapshot-characterization",
   "rendered-behavior",
   "evidence-first",
+  // Zero difference, not "nothing could fail first". `evidence-first` is the
+  // only other strategy without a red-green obligation, and it is scoped by an
+  // absence; an A/B against a base is the opposite — a criterion stronger than
+  // red-green, because it also catches the change that incidentally moved a
+  // result. Issue #142 measured a task re-recording its contract twice to get
+  // past the shape rather than the criterion.
+  "equivalence",
 ];
 
 const RED_GREEN_VERIFICATION_STRATEGIES = new Set([
@@ -257,6 +265,77 @@ function isPassingReviewStatus(value) {
   );
 }
 
+// A git ref resolved locally, or null. Reads the repository the gate is already
+// reading and reaches nothing else: a gate that fetched would stop being local
+// and offline, which is the property its verdict rests on.
+function resolveCommit(repo, ref) {
+  try {
+    return execFileSync(
+      "git",
+      ["-C", repo, "rev-parse", "--verify", "--quiet", `${ref}^{commit}`],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
+    ).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// Four ways an `equivalence` task's shape can be complete and still compare
+// nothing. Each names the declaration it is about: a diagnostic naming the
+// strategy would send the author to the one line that is correct.
+function equivalenceProblems(repo, taskVerification) {
+  const problems = [];
+  const declaredFields = taskVerification.fieldsDeclared;
+  if (!isConcrete(taskVerification.base)) {
+    problems.push({
+      code: "missing-equivalence-base",
+      message:
+        "equivalence compares one code path at two commits and declares which "
+        + "one it is compared against. Add a `Base:` entry beside `Strategy:` "
+        + "naming a git ref — without it the criterion is `the numbers are the "
+        + "same as some other numbers`.",
+    });
+  }
+  if (taskVerification.fields.length === 0) {
+    problems.push({
+      code: "missing-equivalence-fields",
+      message: declaredFields
+        ? "`Fields:` is declared and resolves to an empty set, so the "
+          + "comparison has nothing to compare. It reads as a declaration to "
+          + "every reader except the comparison; name the fields, separated by "
+          + "commas."
+        : "equivalence declares which fields are compared. Add a `Fields:` "
+          + "entry beside `Strategy:` listing them, separated by commas — a "
+          + "comparison with no field set agrees with everything.",
+    });
+  }
+  if (isConcrete(taskVerification.base)) {
+    const base = resolveCommit(repo, taskVerification.base);
+    if (!base) {
+      problems.push({
+        code: "unresolvable-equivalence-base",
+        message:
+          `\`Base: ${taskVerification.base}\` resolves to no commit in this `
+          + "repository. The base is read locally and never fetched, so a ref "
+          + "that exists only on a remote is not one this gate can see.",
+      });
+    } else {
+      const head = resolveCommit(repo, "HEAD");
+      if (head && head === base) {
+        problems.push({
+          code: "equivalence-base-is-head",
+          message:
+            `\`Base: ${taskVerification.base}\` resolves to ${base}, which is `
+            + "HEAD. An A/B against itself always agrees, so the check would "
+            + "pass having compared nothing — the one shape here that is "
+            + "complete, resolvable, and still empty.",
+        });
+      }
+    }
+  }
+  return problems;
+}
+
 function verification(task) {
   const compact = fieldValues(task, "Verify");
   const strategyEntry = compact.find((entry) => /^Strategy:\s*/i.test(entry));
@@ -266,8 +345,19 @@ function verification(task) {
   // command, and a reason that took an `M<n>` label would be a check the author
   // never wrote and evidence nobody can record.
   const reasonEntry = compact.find((entry) => /^Reason:\s*/i.test(entry));
+  // `equivalence` compares one code path at two commits. Neither half of that
+  // fits in a check: the check is the command, and what it cannot say by itself
+  // is which commit it is compared against and which fields are compared. #142
+  // proposed a third field for the command too; commands already have exactly
+  // one home here, and a second would put half of them outside the labelled
+  // evidence `task-complete` enforces.
+  const baseEntry = compact.find((entry) => /^Base:\s*/i.test(entry));
+  const fieldsEntry = compact.find((entry) => /^Fields:\s*/i.test(entry));
   const isVerificationField = (entry) =>
-    /^Strategy:\s*/i.test(entry) || /^Reason:\s*/i.test(entry);
+    /^Strategy:\s*/i.test(entry)
+    || /^Reason:\s*/i.test(entry)
+    || /^Base:\s*/i.test(entry)
+    || /^Fields:\s*/i.test(entry);
   const commandSource = compact.length > 0
     ? compact.filter((entry) => !isVerificationField(entry))
     : fieldValues(task, "Commands");
@@ -342,6 +432,24 @@ function verification(task) {
         ? reasonEntry.replace(/^Reason:\s*/i, "")
         : field(task, "Verification Reason")
     ),
+    base: normalizeText(
+      baseEntry ? baseEntry.replace(/^Base:\s*/i, "") : field(task, "Verification Base")
+    ),
+    // A set, so "declared but empty" is a state the gate can see. `Fields:` with
+    // nothing behind it is the shape that passes while comparing nothing, and it
+    // reads as a declaration to everyone except the comparison.
+    // Whether the line was written at all, kept beside the parsed set so a
+    // refusal can tell an author who wrote nothing from one who wrote an empty
+    // set. To the comparison they are the same state; to the author they are
+    // opposite mistakes.
+    fieldsDeclared: Boolean(fieldsEntry || field(task, "Verification Fields")),
+    fields: (fieldsEntry
+      ? fieldsEntry.replace(/^Fields:\s*/i, "")
+      : field(task, "Verification Fields") || ""
+    )
+      .split(",")
+      .map((entry) => normalizeText(entry))
+      .filter(Boolean),
     commands,
   };
 }
@@ -1191,6 +1299,11 @@ function compileTaskContract(repo, change, task) {
         + "needs no reason.",
     });
   }
+  if (taskVerification.strategy.toLowerCase() === "equivalence") {
+    resolved.diagnostics.push(
+      ...equivalenceProblems(repo, taskVerification)
+    );
+  }
   const couplingMode = normalizeText(field(task, "Coupling")).toLowerCase()
     || "none";
   const candidateBoundary = normalizedValues(task, "Candidate Boundary", {
@@ -1311,6 +1424,14 @@ function compileTaskContract(repo, change, task) {
       // other task keeps the capsule shape and fingerprint it had before the
       // field existed.
       ...(taskVerification.reason ? { reason: taskVerification.reason } : {}),
+      // Same rule: emitted only by the strategy that declares them, so every
+      // existing task's capsule shape and fingerprint are untouched. They belong
+      // in the capsule rather than only in the file because a declaration
+      // outside the fingerprint could be edited after the run it describes.
+      ...(taskVerification.base ? { base: taskVerification.base } : {}),
+      ...(taskVerification.fields.length > 0
+        ? { fields: taskVerification.fields }
+        : {}),
       // 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.