@christang/keel 5.2.2 → 5.2.4

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;
 }
@@ -215,12 +246,21 @@ function reviewValue(task, label) {
   return match ? match[1].trim() : "";
 }
 
+// The durable-owner forms that are pure shape checks, shared by the Review
+// Findings check and the Expectation Coverage check so a form added to one is
+// never missing from the other. Gates run without network and have never
+// 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;
+
 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 (/\bkeel\/archive\/[A-Za-z0-9._/-]+/i.test(findings)) return true;
+  if (SHARED_DURABLE_OWNER_FORMS.test(findings)) return true;
   const owner = findings.match(
     /\b(openspec\/changes\/[A-Za-z0-9][A-Za-z0-9._-]*\/(?:proposal|design|tasks)\.md)(?:#\d+(?:\.\d+)*)?/i
   );
@@ -421,8 +461,8 @@ function completionChecks(repo, task, contract = null) {
         "finding-owner",
         "Review Findings must be `none` or carry a durable owner — a "
           + "`Discard reason:`/`Discard rationale:` prefix, a `keel/archive/…` "
-          + "path, or an existing `openspec/changes/…` artifact; "
-          + "`keel/HANDOFF.md` is not an owner."
+          + "path, an existing `openspec/changes/…` artifact, or an absolute "
+          + "`https://…` tracker reference; `keel/HANDOFF.md` is not an owner."
       )
     );
   }
@@ -489,7 +529,8 @@ function expectationProblems(content, tasks) {
         "expectation-coverage",
         "Expectation Coverage must declare each `E<n>` closure — "
           + "`- E<n>: <expectation> Covered by: <task ids>`, a `Durable owner:` "
-          + "path, or a `Discard reason:` — or `- None.`."
+          + "path or `https://…` tracker reference, or a `Discard reason:` — "
+          + "or `- None.`."
       ),
     ];
   }
@@ -497,8 +538,12 @@ function expectationProblems(content, tasks) {
   for (const entry of entries) {
     const [, id, body] = entry;
     const covered = body.match(/Covered by:\s*([0-9.,\s-]+)/i);
-    const hasDurableOwner =
-      /Durable owner:\s*(?:openspec\/changes\/|keel\/archive\/)/i.test(body);
+    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 discarded = /Discard(?:ed)? (?:reason|rationale):\s*\S/i.test(body);
     if (!covered && !hasDurableOwner && !discarded) {
       problems.push(
@@ -658,7 +703,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/guard.js

@@ -35,6 +35,14 @@ function guardResult(subcommand, status, extra = {}) {
       "The guard manifest is a disposable enforcement pointer; OpenSpec and "
         + "Git remain the only durable authority 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.",
     ],
     ...extra,
   };

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) {
@@ -245,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"]
     : [
@@ -313,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",
@@ -330,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");
@@ -361,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)),
           },
         };
       }
@@ -383,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),
     },
   };
 }
@@ -657,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 = {