@christang/keel 5.2.1 → 5.2.3

package/src/core/capabilities.js

@@ -35,10 +35,33 @@ function codexHome() {
   return path.resolve(configured || path.join(os.homedir(), ".codex"));
 }
 
+// Keel's own repository ships the plugin source under plugins/keel/. A project
+// that consumes Keel never has it, and `keel --init` never creates it, so any
+// check reading that path is a development-only check. Require both signals so
+// a project that merely vendors a plugins/keel/ directory is not misread as
+// Keel's own source.
+function isKeelSourceRepo(repo) {
+  try {
+    const manifest = JSON.parse(
+      fs.readFileSync(path.join(repo, "package.json"), "utf8")
+    );
+    if (manifest.name !== "@christang/keel") return false;
+  } catch {
+    return false;
+  }
+  return fs.existsSync(path.join(repo, "plugins", "keel"));
+}
+
+const PLUGIN_RUNTIME_OBSERVATION =
+  "installed/enabled/trusted/active/behavior-verified plugin states need "
+  + "native runtime evidence and remain advisory or manual until probed";
+
 function pluginObservation(repo, target) {
   if (target === "opencode") {
     return "OpenCode has no v4 native plugin surface; manual CLI compatibility only";
   }
+  // The plugin source path is meaningful only in Keel's own repository.
+  if (!isKeelSourceRepo(repo)) return PLUGIN_RUNTIME_OBSERVATION;
   const manifestRelative = path.join(
     "plugins",
     "keel",
@@ -58,11 +81,7 @@ function pluginObservation(repo, target) {
       sourceState = `plugin source unreadable at ${manifestRelative}`;
     }
   }
-  return (
-    `${sourceState}; installed/enabled/trusted/active/behavior-verified plugin `
-      + "states need native runtime evidence and remain advisory or manual "
-      + "until probed"
-  );
+  return `${sourceState}; ${PLUGIN_RUNTIME_OBSERVATION}`;
 }
 
 function targetObservation(repo, target) {
@@ -286,6 +305,7 @@ function renderCapabilities(result) {
 
 module.exports = {
   CAPABILITY_COMMANDS,
+  isKeelSourceRepo,
   probeCapabilities,
   renderCapabilities,
 };

package/src/core/gates.js

@@ -111,24 +111,36 @@ function contractAnchorPlan(selection, task) {
       ? selection.tasks[index + 1].line
       : lines.length;
   for (let cursor = task.line; cursor < end; cursor += 1) {
-    const match = lines[cursor].match(/^(\s*)-\s*Contract:\s*pending(\r?)$/);
+    const match = lines[cursor].match(/^(\s*)-\s*Contract:\s*(.*?)(\r?)$/);
     if (match) {
-      return { lines, cursor, indent: match[1], cr: match[2] };
+      return {
+        lines,
+        cursor,
+        indent: match[1],
+        previous: match[2].trim(),
+        cr: match[3],
+      };
     }
   }
   return null;
 }
 
+function anchoredFingerprint(previous) {
+  const match = previous.match(/sha-?256[\s:`]*([a-f0-9]{64})/i);
+  return match ? match[1].toLowerCase() : null;
+}
+
 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];
-  // The explicit --record anchor write is refused loudly when the selected
-  // task's Evidence has no literal pending Contract line: a silent skip would
-  // hide a stale anchor and an overwrite would destroy the recorded start
-  // evidence drift detection depends on. Refusal writes nothing, guard
-  // manifest included.
+  // 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
+  // authors to — needs no manual edit. Refusal is kept only for a task with no
+  // anchor at all, which is a malformed capsule rather than a reauthorization,
+  // and it writes nothing, guard manifest included.
   let anchorPlan = null;
   if (options.record && problems.length === 0) {
     anchorPlan = contractAnchorPlan(selection, task);
@@ -136,9 +148,9 @@ function taskStart(repo, options) {
       problems.push(
         problem(
           "record-refused",
-          "--record requires the selected task's Evidence to contain the "
-            + 'literal line "- Contract: pending"; the anchor is already '
-            + "recorded or missing, so nothing was written."
+          "--record needs a \"- Contract:\" Evidence line on the selected "
+            + "task to anchor, and this task has none, so nothing was "
+            + 'written. Add "- Contract: pending" to its Evidence.'
         )
       );
     }
@@ -177,19 +189,38 @@ function taskStart(repo, options) {
     }
   }
   if (result.status === "pass" && anchorPlan) {
-    anchorPlan.lines[anchorPlan.cursor] =
+    const anchorLine =
       `${anchorPlan.indent}- Contract: keel-task-capsule/v1 `
       + `sha256:${compiled.fingerprint.value}${anchorPlan.cr}`;
-    fs.writeFileSync(
-      selection.tasksPath,
-      anchorPlan.lines.join("\n"),
-      "utf8"
-    );
+    const unchanged = anchorPlan.lines[anchorPlan.cursor] === anchorLine;
+    if (!unchanged) {
+      anchorPlan.lines[anchorPlan.cursor] = anchorLine;
+      fs.writeFileSync(
+        selection.tasksPath,
+        anchorPlan.lines.join("\n"),
+        "utf8"
+      );
+    }
+    const wasPending = /^pending$/i.test(anchorPlan.previous);
     result.record = {
-      status: "recorded",
+      status: unchanged ? "unchanged" : wasPending ? "recorded" : "rerecorded",
       path: `openspec/changes/${selection.change}/tasks.md`,
       line: anchorPlan.cursor + 1,
+      previous: anchorPlan.previous,
     };
+    // A re-record that lands a different fingerprint is a contract change, so
+    // any Evidence already produced under the previous one is stale. The gate
+    // cannot judge which Evidence survives; it names the change and leaves the
+    // call to the current agent's Review.
+    const replaced = anchoredFingerprint(anchorPlan.previous);
+    if (replaced && replaced !== compiled.fingerprint.value) {
+      result.warnings.push(
+        `Re-recorded over a different contract: was sha256:${replaced}, now `
+          + `sha256:${compiled.fingerprint.value}. Execution evidence produced `
+          + "under the previous contract is stale; clear or re-verify it "
+          + "before completing this task."
+      );
+    }
   }
   return result;
 }
@@ -658,7 +689,8 @@ function renderGate(result) {
   }
   if (result.record) {
     lines.push(
-      `Recorded: ${result.record.path}:${result.record.line} (Contract anchor)`
+      `Contract anchor ${result.record.status}: ${result.record.path}:`
+        + result.record.line
     );
   }
   return `${lines.join("\n")}\n`;

package/src/core/task-contract.js

@@ -10,13 +10,37 @@ const SUPPORTED_MODES = new Set([
   "plan-first",
 ]);
 
-function isConcrete(value) {
-  const normalized = String(value || "")
+const UNFILLED_TOKEN = /(<[^>]+>|\bTODO\b|\bTBD\b|\bplaceholder\b)/i;
+
+function normalizeFieldText(value) {
+  return String(value || "")
     .replace(/<!--[\s\S]*?-->/g, "")
     .replace(/^\s*-\s*/gm, "")
     .trim();
+}
+
+// Inline code spans hold documented patterns — a filename shape, or prose that
+// has to name the token forms themselves. Strip them before looking for an
+// unfilled slot, but only after the emptiness test, so a field whose whole
+// value is one code span is not mistaken for an empty field.
+function withoutInlineCode(text) {
+  return text.replace(/`[^`]*`/g, " ");
+}
+
+function isConcrete(value) {
+  const normalized = normalizeFieldText(value);
   if (!normalized || /^(?:none|pending)\.?$/i.test(normalized)) return false;
-  return !/(<[^>]+>|\bTODO\b|\bTBD\b|\bplaceholder\b)/i.test(normalized);
+  return !UNFILLED_TOKEN.test(withoutInlineCode(normalized));
+}
+
+// The unfilled token that made a field non-concrete, or null when the field is
+// empty, `none`, or `pending`. Used to explain a non-concrete field instead of
+// letting the caller infer a different schema from it.
+function unfilledToken(value) {
+  const normalized = normalizeFieldText(value);
+  if (!normalized || /^(?:none|pending)\.?$/i.test(normalized)) return null;
+  const match = withoutInlineCode(normalized).match(UNFILLED_TOKEN);
+  return match ? match[0] : null;
 }
 
 function parseTasks(content) {
@@ -123,10 +147,12 @@ function verification(task) {
     ? compact.filter((entry) => !/^Strategy:\s*/i.test(entry))
     : fieldValues(task, "Commands");
   const commands = commandSource.map((entry) => {
-    const match = entry.match(/^(M[1-9]\d*):\s*(.*)$/);
+    // 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], check: normalizeText(match[2]) }
-      : { label: null, check: entry };
+      ? { label: match[1], layer: match[2] || "full", check: normalizeText(match[3]) }
+      : { label: null, layer: "full", check: entry };
   });
   return {
     compact: compact.length > 0,
@@ -243,7 +269,27 @@ function taskStartContractProblems(task) {
 }
 
 function requiredFieldProblems(task) {
-  const compact = isConcrete(field(task, "Verify"));
+  const verify = field(task, "Verify");
+  const compact = isConcrete(verify);
+  // A task that declared Verify but left an unfilled token in it is a compact
+  // v4 task with one bad token, not an expanded v3 task. Say which token, and
+  // do not report the v3 fields it never declared.
+  if (!compact) {
+    const token = unfilledToken(verify);
+    if (token) {
+      return [
+        {
+          code: "non-concrete-verify",
+          message:
+            `Verify contains the unfilled token \`${token}\`; compact v4 `
+            + "detection requires a concrete Verify. Replace or remove that "
+            + "token — the expanded v3 fields are not required. Angle "
+            + "brackets, TODO, TBD, and the word placeholder all read as "
+            + "unfilled, including inside prose.",
+        },
+      ];
+    }
+  }
   const required = compact
     ? ["Covers", "Verify", "Evidence"]
     : [
@@ -311,12 +357,8 @@ function scenarioOutcomes(content) {
   ].map((match) => normalizeText(match[1]));
 }
 
-function specAuthority(repo, change, reference) {
-  const parts = reference.split("/").map((part) => part.trim());
-  if (parts.length < 2 || parts.length > 3) return null;
-  const [capability, requirementName, scenarioName] = parts;
-  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(capability)) return null;
-  const candidates = [
+function specCandidatePaths(repo, change, capability) {
+  return [
     path.join(
       repo,
       "openspec",
@@ -328,6 +370,68 @@ function specAuthority(repo, change, reference) {
     ),
     path.join(repo, "openspec", "specs", capability, "spec.md"),
   ];
+}
+
+// Requirement and scenario names that contain the hierarchy separator can never
+// be referenced, whatever the author writes, so name them instead of leaving a
+// correct-looking reference unexplained.
+function separatorCollisions(repo, change, capability) {
+  const collisions = [];
+  for (const specPath of specCandidatePaths(repo, change, capability)) {
+    if (!fs.existsSync(specPath)) continue;
+    const content = fs.readFileSync(specPath, "utf8");
+    for (const pattern of [
+      /^### Requirement:\s*(.+?)\s*$/gm,
+      /^#### Scenario:\s*(.+?)\s*$/gm,
+    ]) {
+      for (const match of content.matchAll(pattern)) {
+        if (match[1].includes("/") && !collisions.includes(match[1])) {
+          collisions.push(match[1]);
+        }
+      }
+    }
+  }
+  return collisions;
+}
+
+function collisionHint(repo, change, capability) {
+  const collisions = separatorCollisions(repo, change, capability);
+  if (collisions.length === 0) return "";
+  const named = collisions.map((name) => `"${name}"`).join(", ");
+  return (
+    ` Capability ${capability} declares a name containing the / separator, `
+    + `which cannot be referenced: ${named}. Rename it in the spec, or `
+    + "reference its parent requirement instead."
+  );
+}
+
+function specAuthority(repo, change, reference) {
+  const parts = reference.split("/").map((part) => part.trim());
+  const [capability, requirementName, scenarioName] = parts;
+  const namesCapability =
+    /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(capability || "")
+    && specCandidatePaths(repo, change, capability).some((specPath) =>
+      fs.existsSync(specPath)
+    );
+  if (parts.length < 2 || parts.length > 3) {
+    // Only a reference that names a real capability is a failed spec
+    // reference; anything else is free text and stays a legacy reference.
+    if (parts.length > 3 && namesCapability) {
+      return {
+        diagnostic: {
+          code: "unresolved-covers",
+          message:
+            `Covers reference has ${parts.length} segments; the hierarchy is `
+            + "capability / requirement, or capability / requirement / "
+            + `scenario: ${reference}.`
+            + collisionHint(repo, change, capability),
+        },
+      };
+    }
+    return null;
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(capability)) return null;
+  const candidates = specCandidatePaths(repo, change, capability);
   for (const specPath of candidates) {
     if (!fs.existsSync(specPath)) continue;
     const content = fs.readFileSync(specPath, "utf8");
@@ -359,7 +463,10 @@ function specAuthority(repo, change, reference) {
             code: scenarios.length > 1 ? "ambiguous-covers" : "unresolved-covers",
             message:
               `${scenarios.length > 1 ? "Duplicated" : "Missing"} Covers `
-              + `scenario: ${reference}.`,
+              + `scenario: ${reference}.`
+              + (scenarios.length > 1
+                ? ""
+                : collisionHint(repo, change, capability)),
           },
         };
       }
@@ -381,7 +488,9 @@ function specAuthority(repo, change, reference) {
   return {
     diagnostic: {
       code: "unresolved-covers",
-      message: `Covers reference could not be resolved: ${reference}.`,
+      message:
+        `Covers reference could not be resolved: ${reference}.`
+        + collisionHint(repo, change, capability),
     },
   };
 }
@@ -655,11 +764,17 @@ function compileTaskContract(repo, change, task) {
     questionIds.length > 0
     && !isConcrete(fallback.replace(/^Pre-authorized fallback:\s*/i, ""))
   ) {
+    // Name the field and prefix this check actually reads. The previous
+    // wording said "documented design authority", which sent authors to
+    // design.md — where the answer usually already is.
     resolved.diagnostics.push(...questionIds.map((questionId) => ({
       code: "unresolved-authority",
       message:
-        `${questionId} requires documented design authority and an authorized `
-        + "fallback before implementation.",
+        `${questionId} is referenced in Covers but task ${task.id} declares no `
+        + "authorized fallback. Add an \"Autonomy boundary:\" field whose entry "
+        + "line begins \"Pre-authorized fallback:\" and states the reversible "
+        + "bound plus the evidence it requires. This check reads only that line "
+        + "on the task; prose in design.md does not satisfy it.",
     })));
   }
   const capsule = {
@@ -678,7 +793,15 @@ function compileTaskContract(repo, change, task) {
     acceptance: [...new Set([...derivedAcceptance, ...explicitAcceptance])],
     verification: {
       strategy: taskVerification.strategy,
-      commands: taskVerification.commands.filter((entry) => entry.label),
+      // Emit the layer only when a check opts into the fast inner loop, so
+      // untagged (full) checks keep their existing capsule shape and fingerprint.
+      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 }
+        ),
     },
     boundaries: {
       autonomy,