@christang/keel 5.14.0 → 5.20.0

package/src/core/gates.js

@@ -14,7 +14,7 @@ const {
   isPassingReviewStatus,
   parseTasks,
 } = require("./task-contract");
-const { startGuard } = require("./guard");
+const { gitPaths, readManifest, startGuard } = require("./guard");
 
 const GATE_STAGES = new Set(["task-start", "task-complete", "change-close"]);
 
@@ -372,6 +372,35 @@ const DURABLE_OWNER_FORMS =
   + "repository's own ledger; `keel/HANDOFF.md` is a pointer override rather "
   + "than an owner";
 
+// Trailing punctuation a declared path can abut in prose. ASCII sentence marks
+// and their CJK counterparts both belong here: once the extractor stops
+// assuming ASCII, its terminators cannot assume ASCII either. A Chinese
+// sentence ends in `。`, which is not whitespace, so a non-whitespace run
+// swallows it and the gate looks for a file that cannot exist.
+const DECLARED_PATH_TRAILING = /[.,;:!?)\]}"'\u2019\u201d\u3002\uff0c\u3001\uff1b\uff1a\uff01\uff1f\uff09\u3011\u300b\u300d\u300f]+$/;
+
+// A declared path is a run of non-whitespace holding a separator. What ends a
+// path is whitespace; what a path is *made of* is the filesystem's business,
+// and answering the first question with the second is what refused
+// `notes/note-006-转岗最难的不是流程/note.md` by reporting that
+// `notes/note-006-` does not exist — a path nobody wrote (issue #60). It is the
+// same class as #40 on the worktree-reading side, which survived because that
+// fix repaired one reader rather than how paths are extracted; this is the one
+// extractor every gate reader of a declared path now uses.
+//
+// The backtick form wins when present. It is the only way to write a path
+// containing whitespace, and `touchEntries` already strips backticks from a
+// Touch entry, so one authorship stops being spelled two ways depending on
+// which reader will read it.
+function declaredPath(value) {
+  const text = String(value || "");
+  const quoted = text.match(/`([^`\n]*\/[^`\n]*)`/);
+  if (quoted) return quoted[1].trim() || null;
+  const bare = text.match(/[^\s`]+\/[^\s`]+/);
+  if (!bare) return null;
+  return bare[0].replace(DECLARED_PATH_TRAILING, "") || null;
+}
+
 // Classify a declared `Durable owner:` value. A gate runs without network, so a
 // URL is accepted on shape alone; a path is the one form it can actually check,
 // and checking it is stricter than the prefix whitelist this replaced.
@@ -380,10 +409,10 @@ function durableOwnerVerdict(repo, value) {
   if (!owner) return { ok: false, reason: "unrecognized" };
   if (/keel\/HANDOFF\.md/i.test(owner)) return { ok: false, reason: "handoff" };
   if (TRACKER_REFERENCE.test(owner)) return { ok: true };
-  const candidate = owner.match(/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)+/);
+  const candidate = declaredPath(owner);
   if (!candidate) return { ok: false, reason: "unrecognized" };
-  if (fs.existsSync(path.join(repo, candidate[0]))) return { ok: true };
-  return { ok: false, reason: "missing", path: candidate[0] };
+  if (fs.existsSync(path.join(repo, candidate))) return { ok: true };
+  return { ok: false, reason: "missing", path: candidate };
 }
 
 // A finding has three dispositions and the gate recognized two. One found and
@@ -423,10 +452,10 @@ function resolutionEvidenceVerdict(repo, value, commands) {
     if (commands.includes(cited[0])) return { ok: true };
     return { ok: false, reason: "unknown-check", label: cited[0] };
   }
-  const candidate = evidence.match(/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)+/);
+  const candidate = declaredPath(evidence);
   if (!candidate) return { ok: false, reason: "unrecognized" };
-  if (fs.existsSync(path.join(repo, candidate[0]))) return { ok: true };
-  return { ok: false, reason: "missing", path: candidate[0] };
+  if (fs.existsSync(path.join(repo, candidate))) return { ok: true };
+  return { ok: false, reason: "missing", path: candidate };
 }
 
 function resolutionEvidenceMessage(verdict) {
@@ -466,13 +495,12 @@ function findingOwnerIsDurable(repo, findings) {
     /\b(openspec\/changes\/[A-Za-z0-9][A-Za-z0-9._-]*\/(?:proposal|design|tasks)\.md)(?:#\d+(?:\.\d+)*)?/i
   );
   if (artifact && fs.existsSync(path.join(repo, artifact[1]))) return true;
-  return /\bkeel\/archive\/[A-Za-z0-9._/-]+/i.test(findings)
-    && fs.existsSync(
-      path.join(
-        repo,
-        findings.match(/\bkeel\/archive\/[A-Za-z0-9._/-]+/i)[0]
-      )
-    );
+  // Same extractor, scoped to the archive prefix: the segment after
+  // `keel/archive/` is a path like any other and was equally ASCII-bound.
+  const archive = findings.match(/keel\/archive\/[^\s`]*/i);
+  if (!archive) return false;
+  const archivePath = declaredPath(archive[0]);
+  return Boolean(archivePath) && fs.existsSync(path.join(repo, archivePath));
 }
 
 // Read in `-z` form, because every other form escapes. Git octal-escapes any
@@ -483,33 +511,21 @@ function findingOwnerIsDurable(repo, findings) {
 // decoder — and it is a flag rather than a repository setting, so the answer
 // does not depend on how the repository happens to be configured.
 //
-// Nothing rewrites backslashes here any more. Git emits forward slashes on
-// every platform, so the rewrite normalized a separator that never arrives
-// while turning `\346` into `/346`, which is how a path declared on the first
-// line of Touch was reported as outside Touch (issue #40).
-function gitPaths(repo) {
-  const status = spawnSync(
-    "git",
-    ["status", "--porcelain=v1", "-z", "--untracked-files=all"],
-    { cwd: repo, encoding: "utf8" }
-  );
-  if (status.error || status.status !== 0) return [];
-  // Each record is `XY <path>`, NUL-terminated. A rename or copy is followed
-  // by a second bare field holding its other endpoint — the new path first in
-  // `-z`, the reverse of the ` -> ` line format. The order is immaterial:
-  // both endpoints are attributed, so a rename whose paths are both in Touch
-  // is not a false outside-Touch failure.
-  const fields = status.stdout.split("\0").filter(Boolean);
-  const paths = [];
-  for (let index = 0; index < fields.length; index += 1) {
-    const record = fields[index];
-    paths.push(record.slice(3));
-    if (record[0] === "R" || record[0] === "C") {
-      index += 1;
-      if (index < fields.length) paths.push(fields[index]);
-    }
-  }
-  return paths;
+// `gitPaths` moved to guard.js, which owns the worktree reading now that the
+// task-start record and this comparison must use the same one.
+
+// The dirty set recorded when this task was authorized, or null when nobody
+// recorded one. Null and empty are different answers: an empty list says
+// nothing was dirty at task start, and null says no record exists, which is
+// what a manifest written before this field, a cleared guard, or a
+// `--no-guard` start all produce. Reading null as empty would attribute the
+// whole worktree to the task and fail every completion in a dirty repository.
+function recordedBaseline(repo, change, task) {
+  const loaded = readManifest(repo);
+  if (loaded.state !== "ok") return null;
+  const manifest = loaded.manifest;
+  if (manifest.change !== change || manifest.task !== task) return null;
+  return Array.isArray(manifest.startedDirty) ? manifest.startedDirty : null;
 }
 
 function touchEntries(task, contract = null) {
@@ -570,7 +586,15 @@ function scopeEvidence(
   tasks = null
 ) {
   const dirtyPaths = gitPaths(repo);
-  if (!base) {
+  // An explicit base wins. It asks a broader question than the record does —
+  // everything since that commit, not only since this task started — and
+  // substituting the narrower answer would make `--base` mean something other
+  // than what it says.
+  const baseline = base ? null : recordedBaseline(repo, change, task.id);
+  if (!base && !baseline) {
+    // No base and no record: the original conservatism, and the reason for it
+    // is unchanged. Git alone cannot say which task of a half-finished change
+    // wrote a given path, so the dirty state stays semantic review evidence.
     return {
       problems: [],
       warnings:
@@ -583,6 +607,27 @@ function scopeEvidence(
     };
   }
 
+  if (!base) {
+    // Dirty now and not dirty when the task started. This answers "did this
+    // task write it", which is the question the boundary actually asks; it
+    // does not answer "which task wrote it", which is why the completed-
+    // sibling exclusion below still applies and still reports itself.
+    //
+    // A path already dirty at task start is subtracted even if the task also
+    // modified it. That is the price of a baseline that is not a commit, and
+    // it buys the far larger class this exists to avoid: failing every
+    // completion in a worktree that was dirty before the task began.
+    const startedDirty = new Set(baseline);
+    return attributeChanged(
+      repo,
+      task,
+      dirtyPaths.filter((item) => !startedDirty.has(item)),
+      contract,
+      change,
+      tasks
+    );
+  }
+
   const verified = spawnSync(
     "git",
     ["rev-parse", "--verify", `${base}^{commit}`],
@@ -601,10 +646,23 @@ function scopeEvidence(
   if (diff.error || diff.status !== 0) {
     throw new GateInputError(`could not compare Git base: ${base}`);
   }
-  const changed = new Set([
-    ...diff.stdout.split("\0").filter(Boolean),
-    ...dirtyPaths,
-  ]);
+  return attributeChanged(
+    repo,
+    task,
+    [...diff.stdout.split("\0").filter(Boolean), ...dirtyPaths],
+    contract,
+    change,
+    tasks
+  );
+}
+
+// The one place a candidate path becomes a problem, whichever comparison
+// produced it. Both callers reach it: the recorded-baseline path and the
+// explicit-base path differ only in how they decide which paths are
+// candidates, and a second copy of this would be a second definition of what
+// Touch means.
+function attributeChanged(repo, task, changedList, contract, change, tasks) {
+  const changed = new Set(changedList);
   const touch = touchEntries(task, contract);
   // The disposable guard manifest is the one artifact the gate contract itself
   // permits a gate to write, and the selected change's own authoring artifacts
@@ -648,7 +706,13 @@ function completionChecks(repo, task, contract = null) {
   const commands = contract
     ? contract.capsule.verification.commands.map((item) => item.label)
     : commandLabels(task);
-  if (commands.length === 0) {
+  // With no contract, the labels came from the expanded v3 `Commands` field,
+  // which a compact task never declares — so their absence is a fact about the
+  // fallback, not about the task. The compiler's own diagnostics are already in
+  // `problems` (the caller pushes them unconditionally, and an unusable
+  // contract has at least one), so this cannot turn a refusal into a pass. The
+  // per-label evidence checks below stay: a genuine v3 task yields real labels.
+  if (contract && commands.length === 0) {
     problems.push(problem("missing-commands", "Commands must define at least one M<n>."));
   }
   for (const label of commands) {

package/src/core/guard.js

@@ -9,8 +9,44 @@
 const crypto = require("crypto");
 const fs = require("fs");
 const path = require("path");
+const { spawnSync } = require("child_process");
 const { loadTaskContract } = require("./task-contract");
 
+// Nothing rewrites backslashes here. Git emits forward slashes on every
+// platform, so the rewrite normalized a separator that never arrives while
+// turning `\346` into `/346`, which is how a path declared on the first line
+// of Touch was reported as outside Touch (issue #40).
+//
+// This lives here rather than in gates.js because both the task-start record
+// and the completion comparison read it, and gates.js already requires this
+// module. One implementation is the point: a baseline and a comparison that
+// disagreed about what "dirty" means, or about how a rename is represented,
+// would attribute a path nobody wrote.
+function gitPaths(repo) {
+  const status = spawnSync(
+    "git",
+    ["status", "--porcelain=v1", "-z", "--untracked-files=all"],
+    { cwd: repo, encoding: "utf8" }
+  );
+  if (status.error || status.status !== 0) return [];
+  // Each record is `XY <path>`, NUL-terminated. A rename or copy is followed
+  // by a second bare field holding its other endpoint — the new path first in
+  // `-z`, the reverse of the ` -> ` line format. The order is immaterial:
+  // both endpoints are attributed, so a rename whose paths are both in Touch
+  // is not a false outside-Touch failure.
+  const fields = status.stdout.split("\0").filter(Boolean);
+  const paths = [];
+  for (let index = 0; index < fields.length; index += 1) {
+    const record = fields[index];
+    paths.push(record.slice(3));
+    if (record[0] === "R" || record[0] === "C") {
+      index += 1;
+      if (index < fields.length) paths.push(fields[index]);
+    }
+  }
+  return paths;
+}
+
 const MANIFEST_SCHEMA = "keel-write-guard/v1";
 
 class GuardInputError extends Error {}
@@ -121,6 +157,18 @@ function readManifest(repo) {
   ) {
     shapeErrors.push("authority must list hashed source files");
   }
+  // Optional on purpose. A manifest written before this field existed, and one
+  // 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".
+  if (
+    manifest.startedDirty !== undefined
+    && (!Array.isArray(manifest.startedDirty)
+      || manifest.startedDirty.some((item) => typeof item !== "string"))
+  ) {
+    shapeErrors.push("startedDirty must be a string list when present");
+  }
   if (shapeErrors.length > 0) {
     return {
       state: "invalid",
@@ -182,6 +230,9 @@ 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);
   const manifest = {
     schema: MANIFEST_SCHEMA,
     change: options.change,
@@ -189,6 +240,7 @@ function startGuard(repo, options) {
     fingerprint: loaded.contract.fingerprint,
     touch: loaded.contract.capsule.touch,
     authority: hashAuthority(repo, paths),
+    startedDirty,
   };
   fs.mkdirSync(path.join(repo, "keel"), { recursive: true });
   fs.writeFileSync(
@@ -302,6 +354,7 @@ module.exports = {
   GuardInputError,
   MANIFEST_SCHEMA,
   clearGuard,
+  gitPaths,
   guardStatus,
   readManifest,
   renderGuard,

package/src/core/task-contract.js

@@ -416,10 +416,24 @@ function requiredFieldProblems(task) {
 function missingFieldProblems(task, names) {
   return names
     .filter((name) => !isConcrete(field(task, name)))
-    .map((name) => ({
-      code: "missing-field",
-      message: `${name} must be concrete.`,
-    }));
+    .map((name) => {
+      // Name the matched slot, the way the check and Verify diagnostics already
+      // do. The unqualified wording stated only the verdict, so an author whose
+      // field held a token in ordinary prose had nothing to search for — and
+      // the first problem they saw named a field of the other schema instead.
+      // The code is unchanged: the verdict is the same either way, and a new
+      // one would hide this case from every consumer keying on `missing-field`.
+      const token = unfilledToken(field(task, name));
+      return {
+        code: "missing-field",
+        message: token
+          ? `${name} carries the unfilled slot \`${token}\`, so it is not `
+            + "concrete. Replace that slot with the value it stands for, or "
+            + "fence it in inline code when it is literal text — a numeric "
+            + "range or test output — rather than a slot left to fill."
+          : `${name} must be concrete.`,
+      };
+    });
 }
 
 function canonical(value) {