@christang/keel 5.7.0 → 5.16.0

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/helper.js

@@ -56,8 +56,34 @@ function blockedBrief(target, reason, extra = {}) {
   };
 }
 
+// Symbolic links are resolved on both sides, because `process.cwd()` comes
+// back already resolved while `path.resolve` never follows a link — on macOS,
+// where `/tmp` is a link to `/private/tmp`, that made a path inside the
+// worktree look external and let the helper write its baseline into the
+// repository it had just promised not to touch. The baseline usually does not
+// exist yet, so the nearest existing ancestor is what resolves. The write
+// guard hook answers the same question and keeps its own copy of this rule,
+// because it is a standalone script that cannot import from here.
+function realPathOrNearest(target) {
+  let current = path.resolve(target);
+  const trailing = [];
+  for (;;) {
+    try {
+      return path.join(fs.realpathSync(current), ...trailing);
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) return path.resolve(target);
+      trailing.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
 function isExternal(repo, candidate) {
-  const rel = path.relative(repo, path.resolve(candidate));
+  const rel = path.relative(
+    realPathOrNearest(repo),
+    realPathOrNearest(candidate)
+  );
   return (
     rel === ".."
     || rel.startsWith(`..${path.sep}`)

package/src/core/projection.js

@@ -2,6 +2,10 @@
 
 // Keel 4.1.0 one-way native projection contract.
 
+const fs = require("fs");
+const path = require("path");
+
+const { readDelegationPolicy } = require("./config");
 const { resolveContext } = require("./context");
 const { loadTaskContract } = require("./task-contract");
 const { probeCapabilities } = require("./capabilities");
@@ -34,6 +38,39 @@ function blocked(target, event, reason, warnings = []) {
   };
 }
 
+// Both refusals are decided before a delegate starts, never inferred from what
+// it did. An absent manifest passes every write through silently, so a delegate
+// that wrote successfully under one proves nothing about having been checked —
+// there is no observable difference afterwards, which is why the condition has
+// to be answered here.
+function delegationRefusal(repo, delegation) {
+  // The policy is read directly rather than through the capsule, because the
+  // capsule cannot express the difference this refusal turns on. A tier outside
+  // the vocabulary fails closed at the config layer and reaches the capsule as
+  // no delegation at all — identical to a repository that declared nothing. One
+  // of those should proceed silently and the other must be reported, so the
+  // unresolved declaration has to be seen where it still exists.
+  const { unknown, accepted } = readDelegationPolicy(repo);
+  if (unknown.length > 0) {
+    return (
+      `Delegation declares tier "${unknown.join(", ")}", which this target `
+      + `does not provide. Accepted: ${accepted.join(", ")}. Keel refuses `
+      + "rather than substituting a tier, because work would otherwise run at "
+      + "a capability nobody declared while reporting success."
+    );
+  }
+  if (!delegation) return null;
+  if (!fs.existsSync(path.join(repo, "keel", "guard.json"))) {
+    return (
+      "Delegation requires an active write guard, and keel/guard.json is "
+      + "absent. Without it every write passes through unchecked and looks "
+      + "identical to a write the guard allowed. Run `keel gate task-start` "
+      + "for the selected task, then delegate."
+    );
+  }
+  return null;
+}
+
 function capabilityKey(event) {
   if (event === "startup") return "continuity.start";
   if (["resume", "compaction"].includes(event)) return "continuity.reinject";
@@ -157,6 +194,24 @@ function projectRuntime(repo, options) {
   if (event === "subagent-stop") {
     projection.returnAuthority = "report-and-evidence-only";
   }
+  // Delegation extends the brief Keel already publishes rather than adding a
+  // carrier beside the host's own agent interface. The host spawns; this is the
+  // one-way view of OpenSpec it is handed.
+  if (event === "subagent-start") {
+    const refusal = delegationRefusal(repo, capsule.delegation);
+    if (refusal) return blocked(options.target, event, refusal, warnings);
+  }
+  if (event === "subagent-start" && capsule.delegation) {
+    projection.delegation = {
+      tier: capsule.delegation.tier,
+      source: capsule.delegation.source,
+      writeBoundary: capsule.touch,
+      note:
+        "Keel carries the declared tier and does not select a model; the "
+        + "target resolves it. Keel cannot observe which model executed, so "
+        + "the tier is what is recorded and never a claim about what ran.",
+    };
+  }
 
   return {
     schemaVersion: 1,

package/src/core/task-contract.js

@@ -6,6 +6,7 @@ const path = require("path");
 
 const {
   CONFIG_RELATIVE_PATH,
+  readDelegationPolicy,
   readStandingAuthorization,
 } = require("./config");
 
@@ -866,6 +867,24 @@ function compileTaskContract(repo, change, task) {
   if (!autonomy.some((item) => /^Pre-authorized fallback:/i.test(item))) {
     autonomy.push("Pre-authorized fallback: none");
   }
+  // Who runs this task, resolved exactly as the autonomy boundary above is: the
+  // task keeps whatever it authored, the repository declaration supplies only
+  // what the task left silent, and the entry names its source. A declaration
+  // that could overwrite an authored tier would make the capsule unreadable on
+  // its own — you could not tell what this task decided from what the file did.
+  const authoredTier = normalizeText(field(task, "Delegation")).toLowerCase();
+  let delegation = { tier: null, source: null };
+  if (authoredTier) {
+    delegation = { tier: authoredTier, source: "task" };
+  } else {
+    const { tier } = readDelegationPolicy(repo);
+    if (tier) {
+      delegation = {
+        tier,
+        source: CONFIG_RELATIVE_PATH.split(path.sep).join("/"),
+      };
+    }
+  }
   // A question is unresolved authority when it is the subject of its Covers
   // entry. Scanning the whole field also matched a resolved question named as
   // supporting detail beside the fact that closed it, and the only fix
@@ -940,7 +959,18 @@ function compileTaskContract(repo, change, task) {
         couplingMode === "required" ? candidateBoundary : [],
       designContract: coupledContract,
     },
+    // A helper and a delegate are different roles. A helper is never a second
+    // writer and this stays true whatever the repository declares; delegation
+    // is a separate entry beside it, never a helper with the guard removed.
     helperAuthority: "read-only-evidence-only",
+    // Present only when a tier actually resolved. An unconditional field would
+    // change the compiled capsule for every task everywhere, moving every
+    // recorded anchor and drifting every live change in every consumer repo on
+    // upgrade — for repositories that declared nothing and asked for nothing.
+    // Omission keeps this release's invariant: no behavior change without a
+    // declaration. A repository that does declare gets a different capsule,
+    // which is honest, because its execution genuinely differs.
+    ...(delegation.tier ? { delegation } : {}),
     prohibitions: [
       "must not change Acceptance",
       // repo-action is the one mode whose authorized effect is the repository