@christang/keel 5.20.0 → 5.44.0

package/src/core/guard.js

@@ -59,6 +59,20 @@ function sha256(buffer) {
   return crypto.createHash("sha256").update(buffer).digest("hex");
 }
 
+// The content a dirty path held at the moment it was read, or `null` when
+// nothing could be read — a deleted path, mid-rename, or one that never
+// existed. `null` is a signature like any other: it round-trips through the
+// same equality check a real hash does, so a path that stays absent compares
+// equal and one that gets created or deleted compares unequal, with no
+// special case for either direction.
+function contentSignature(repo, relative) {
+  try {
+    return sha256(fs.readFileSync(path.join(repo, relative)));
+  } catch {
+    return null;
+  }
+}
+
 function guardResult(subcommand, status, extra = {}) {
   return {
     schemaVersion: 1,
@@ -68,17 +82,17 @@ function guardResult(subcommand, status, extra = {}) {
     manifestPath: "keel/guard.json",
     problems: [],
     warnings: [
-      "The guard manifest is a disposable enforcement pointer; OpenSpec and "
-        + "Git remain the only durable authority and selection never derives "
+      "The guard manifest is a disposable enforcement pointer, not durable "
+        + "authority — OpenSpec and Git are, 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.",
+      "This describes the manifest only. Enforcement runs as a runtime hook "
+        + "Keel cannot observe, so a written manifest proves no write was "
+        + "checked.",
     ],
     ...extra,
   };
@@ -161,13 +175,25 @@ function readManifest(repo) {
   // written by a Keel that omits it, are both valid; what they are not is
   // evidence that nothing was dirty. The consumer distinguishes absent from
   // empty, so an empty list means "nothing was dirty" and an absent one means
-  // "nobody looked".
+  // "nobody looked". Each entry carries the path's content signature, not
+  // just its name, so completion can tell "still the content recorded at
+  // task start" from "dirty again for a different reason" — `sha256` is
+  // `null` for a path that had nothing to read.
   if (
     manifest.startedDirty !== undefined
     && (!Array.isArray(manifest.startedDirty)
-      || manifest.startedDirty.some((item) => typeof item !== "string"))
+      || manifest.startedDirty.some(
+        (item) =>
+          !item
+          || typeof item.path !== "string"
+          || !item.path
+          || (item.sha256 !== null
+            && !/^[0-9a-f]{64}$/.test(String(item.sha256 || "")))
+      ))
   ) {
-    shapeErrors.push("startedDirty must be a string list when present");
+    shapeErrors.push(
+      "startedDirty must be a list of hashed dirty paths when present"
+    );
   }
   if (shapeErrors.length > 0) {
     return {
@@ -231,8 +257,14 @@ function startGuard(repo, options) {
 
   const paths = authorityPaths(repo, options.change, loaded.contract);
   // Read before the manifest is written, so the manifest is never in its own
-  // record and cannot be attributed to the task it authorizes.
-  const startedDirty = gitPaths(repo);
+  // record and cannot be attributed to the task it authorizes. Each dirty
+  // path is hashed at this same moment, so a later comparison can tell
+  // whether the task changed it again rather than only whether it stayed
+  // dirty.
+  const startedDirty = gitPaths(repo).map((relative) => ({
+    path: relative,
+    sha256: contentSignature(repo, relative),
+  }));
   const manifest = {
     schema: MANIFEST_SCHEMA,
     change: options.change,
@@ -265,12 +297,40 @@ function guardStatus(repo) {
   const problems = [];
   const loaded = loadTaskContract(repo, manifest.change, manifest.task);
   if (!loaded) {
-    problems.push({
-      code: "authority-drift",
-      message:
-        `Guarded task ${manifest.change}#${manifest.task} no longer resolves; `
-        + "reauthorize through `keel gate task-start` and `keel guard start`.",
-    });
+    // `loadTaskContract` returns null for two unrelated reasons — the tasks
+    // file is not there, or the task id is not in it — and only one of them
+    // has a reauthorization to perform. Telling the reader to reauthorize a
+    // change that has been archived sends them to `keel gate task-start`,
+    // which reports a missing tasks file, and to `keel guard start`, which
+    // reports that the task does not exist; neither names `keel guard clear`,
+    // which is the only action that resolves it.
+    //
+    // The change *directory* is the test, not the tasks file, and it is the
+    // same object `plugins/keel/scripts/pretooluse-guard.js` tests for the
+    // same question. Two surfaces deciding it by different means would
+    // eventually disagree about a state a reader is looking at from both. It
+    // also leaves a live change whose tasks.md is absent — mid-authoring — on
+    // the reauthorize path, where reauthorizing genuinely is the way out.
+    const changeDir = path.join(repo, "openspec", "changes", manifest.change);
+    problems.push(
+      fs.existsSync(changeDir)
+        ? {
+          code: "authority-drift",
+          message:
+            `Guarded task ${manifest.change}#${manifest.task} no longer `
+            + "resolves; reauthorize through `keel gate task-start` and "
+            + "`keel guard start`.",
+        }
+        : {
+          code: "stale-manifest",
+          message:
+            `This manifest is stale: it guards ${manifest.change}`
+            + `#${manifest.task}, but openspec/changes/${manifest.change} no `
+            + "longer exists, so the task it names cannot be reauthorized and "
+            + "its Touch list authorizes nothing. Run `keel guard clear`, then "
+            + "start the task you are actually working on.",
+        }
+    );
     const drifted = guardResult("status", "drifted", { manifest });
     drifted.problems = problems;
     return drifted;
@@ -354,6 +414,7 @@ module.exports = {
   GuardInputError,
   MANIFEST_SCHEMA,
   clearGuard,
+  contentSignature,
   gitPaths,
   guardStatus,
   readManifest,

package/src/core/task-contract.js

@@ -518,6 +518,67 @@ function collisionHint(repo, change, capability) {
   );
 }
 
+// One phrasing, so an author who has read the over-segmented refusal recognizes
+// the unresolved one. It used to be reachable only by writing too many
+// segments, which withheld it from the reference people actually write wrong.
+const COVERS_HIERARCHY =
+  "the hierarchy is capability / requirement, or capability / requirement "
+  + "/ scenario";
+
+// Say which segment failed. The candidate specs were opened by the caller and
+// the name the author typed is very often a heading one level below where they
+// put it — the shipped task template taught exactly that reference — so the
+// refusal can name the requirement it belongs to instead of handing the
+// reference back. Reporting what a spec contains is not heuristic matching: the
+// reference still fails, and no near miss is resolved on the author's behalf.
+function unresolvedDetail(repo, change, capability, name) {
+  const candidates = specCandidatePaths(repo, change, capability);
+  const existing = candidates.filter((specPath) => fs.existsSync(specPath));
+  if (existing.length === 0) {
+    const looked = candidates
+      .map((specPath) => path.relative(repo, specPath).replace(/\\/g, "/"))
+      .join(" and ");
+    return ` No spec declares capability ${capability}; ${looked} do not exist.`;
+  }
+  const parents = [];
+  for (const specPath of existing) {
+    const content = fs.readFileSync(specPath, "utf8");
+    for (const requirement of headingSections(
+      content,
+      /^### Requirement:\s*(.+?)\s*$/
+    )) {
+      const holdsName = headingSections(
+        requirement.content,
+        /^#### Scenario:\s*(.+?)\s*$/
+      ).some((item) => item.title === name);
+      if (holdsName && !parents.includes(requirement.title)) {
+        parents.push(requirement.title);
+      }
+    }
+  }
+  if (parents.length === 1) {
+    return (
+      ` "${name}" is a Scenario of Requirement "${parents[0]}", not a `
+      + `Requirement; ${COVERS_HIERARCHY}. Write it as: `
+      + `${capability} / ${parents[0]} / ${name}.`
+    );
+  }
+  if (parents.length > 1) {
+    // No single reference corrects this one, so none is offered: sending the
+    // author to a reference that fails as ambiguous would cost them the round
+    // this diagnostic exists to save.
+    const named = parents.map((title) => `"${title}"`).join(", ");
+    return (
+      ` "${name}" is a Scenario of more than one Requirement — ${named} — so `
+      + `no single reference corrects it; ${COVERS_HIERARCHY}.`
+    );
+  }
+  return (
+    ` Capability ${capability} declares no Requirement or Scenario named `
+    + `"${name}"; ${COVERS_HIERARCHY}.`
+  );
+}
+
 function specAuthority(repo, change, reference) {
   const parts = reference.split("/").map((part) => part.trim());
   const [capability, requirementName, scenarioName] = parts;
@@ -534,9 +595,8 @@ function specAuthority(repo, change, reference) {
         diagnostic: {
           code: "unresolved-covers",
           message:
-            `Covers reference has ${parts.length} segments; the hierarchy is `
-            + "capability / requirement, or capability / requirement / "
-            + `scenario: ${reference}.`
+            `Covers reference has ${parts.length} segments; `
+            + `${COVERS_HIERARCHY}: ${reference}.`
             + collisionHint(repo, change, capability),
         },
       };
@@ -603,6 +663,7 @@ function specAuthority(repo, change, reference) {
       code: "unresolved-covers",
       message:
         `Covers reference could not be resolved: ${reference}.`
+        + unresolvedDetail(repo, change, capability, requirementName)
         + collisionHint(repo, change, capability),
     },
   };
@@ -626,12 +687,41 @@ function criticalAuthority(repo, change, reference) {
     };
   }
   const content = fs.readFileSync(designPath, "utf8");
+  // Accepted line shapes: an optional CommonMark list bullet, the identifier
+  // bare or wrapped in balanced `**`, then the dash and statement. Authors
+  // overwhelmingly write the bulleted and bold shapes (issue #49).
   const matches = [
     ...content.matchAll(
-      new RegExp(`^\\s*${reference}\\s*[—-]\\s*(.+?)\\s*$`, "gmi")
+      new RegExp(
+        `^\\s*(?:[-*+]\\s+)?(?:\\*\\*${reference}\\*\\*|${reference})`
+        + `\\s*[—-]\\s*(.+?)\\s*$`,
+        "gmi"
+      )
     ),
   ];
   if (matches.length !== 1) {
+    // Zero matches is ambiguous: the identifier may never appear in design.md,
+    // or it may appear in some other shape (bulleted, bold) that the strict
+    // regex above does not accept. A whole-word scan tells those apart so the
+    // message sends the author to the actual defect — a shape fix, not a
+    // statement that already exists — instead of collapsing both into "Missing".
+    if (
+      matches.length === 0
+      && new RegExp(`\\b${reference}\\b`).test(content)
+    ) {
+      return {
+        diagnostic: {
+          code: "unresolved-covers",
+          message:
+            `Unparsed Covers critical statement: ${reference}. It appears in `
+            + "design.md but not in an accepted line shape — write it as a "
+            + "line opening with the identifier and a dash, "
+            + `\`${reference} — one-line statement\`, optionally as a list `
+            + `bullet (\`- ${reference} — …\`) and/or with the identifier `
+            + `bold (\`**${reference}** — …\`).`,
+        },
+      };
+    }
     return {
       diagnostic: {
         code: matches.length > 1 ? "ambiguous-covers" : "unresolved-covers",
@@ -677,7 +767,17 @@ function resolveAuthority(repo, change, task) {
   }
   const entries = [...seen].sort();
   for (const entry of entries) {
-    const critical = criticalAuthority(repo, change, entry);
+    // A critical-statement reference may open its entry with a trailing
+    // annotation after a dash (`D2 — note`); the identifier resolves and the
+    // annotation stays annotation — design.md owns the statement text. The
+    // boundary after the identifier is whitespace or an em dash so that free
+    // text like `D2-compatible` does not become a reference.
+    const annotated = entry.match(/^([DFAQ]\d+)(?=\s|—)\s*[—-]\s*.+$/);
+    const critical = criticalAuthority(
+      repo,
+      change,
+      annotated ? annotated[1] : entry
+    );
     if (critical) {
       if (critical.diagnostic) diagnostics.push(critical.diagnostic);
       if (critical.authority) authority.push(critical.authority);
@@ -1049,4 +1149,5 @@ module.exports = {
   loadTaskContract,
   parseTasks,
   taskStartContractProblems,
+  unfilledToken,
 };