@christang/keel 5.7.0 → 5.14.0

package/src/core/config.js

@@ -9,6 +9,14 @@ const path = require("path");
 // author believing they authorized something they did not.
 const STANDING_AUTHORIZATION_ACTIONS = ["commit", "push", "release", "archive"];
 
+// The closed vocabulary of capability tiers a repository may declare for a
+// delegated task. The names describe the capability the work requires, never
+// the size of the work: a tier named for size would authorize the agent's guess
+// about difficulty, which is the judgement 5.7.0 refused for triage. Keel names
+// no concrete model — one is target-specific and expires at the next release,
+// and the declaration must still be correct after both.
+const DELEGATION_TIERS = ["routine", "standard", "deep"];
+
 const CONFIG_RELATIVE_PATH = path.join("keel", "config.yaml");
 
 // The declarations share keel/config.yaml with fast_check, so the reader stays
@@ -61,6 +69,54 @@ function readStandingAuthorization(repo) {
   return { declared, unknown };
 }
 
+// A nested block of `name: value` entries under one top-level key. Delegation
+// needs a key with a value rather than a bare list, so it cannot reuse
+// configList; the reader stays line-oriented for the same reason the others do.
+function configMap(repo, key) {
+  const configPath = path.join(repo, "keel", "config.yaml");
+  const entries = {};
+  if (!fs.existsSync(configPath)) return entries;
+  const opener = new RegExp(`^${key}\\s*:\\s*$`);
+  let inBlock = false;
+  for (const line of fs.readFileSync(configPath, "utf8").split(/\r?\n/)) {
+    if (/^\s*#/.test(line)) continue;
+    if (opener.test(line)) {
+      inBlock = true;
+      continue;
+    }
+    if (!inBlock) continue;
+    if (line.trim() === "") continue;
+    const entry = line.match(/^\s+(\w+)\s*:\s*(\S+)\s*$/);
+    // Anything that is not an indented entry closes the block, exactly as it
+    // does for a list; the next top-level key belongs to the rest of the file.
+    if (!entry) break;
+    entries[entry[1]] = entry[2];
+  }
+  return entries;
+}
+
+// Who runs a task. Declaring a tier is what permits delegation at that tier —
+// there is no separate on/off entry, because a tier with no permission and a
+// permission with no tier are both incomplete, and one field cannot disagree
+// with itself. An absent declaration delegates nothing, which is the default.
+function readDelegationPolicy(repo) {
+  const block = configMap(repo, "delegation");
+  const tier = block.tier;
+  // The accepted set travels with every answer so a caller reporting a refusal
+  // can name the alternatives without importing the vocabulary itself. A copy,
+  // because a caller that sorted or spliced it in place would edit the closed
+  // set for everyone who read it afterward.
+  const accepted = [...DELEGATION_TIERS];
+  if (!tier) return { declared: false, tier: null, unknown: [], accepted };
+  // Fail closed, the same way an unrecognized `authorize:` action does: a
+  // declaration Keel cannot fully read authorizes nothing, because the author
+  // of a typo believes they declared what they typed.
+  if (!DELEGATION_TIERS.includes(tier)) {
+    return { declared: true, tier: null, unknown: [tier], accepted };
+  }
+  return { declared: true, tier, unknown: [], accepted };
+}
+
 function configScalar(repo, key) {
   const configPath = path.join(repo, "keel", "config.yaml");
   if (!fs.existsSync(configPath)) return null;
@@ -159,7 +215,9 @@ function triageIssue(repo, labels) {
 
 module.exports = {
   CONFIG_RELATIVE_PATH,
+  DELEGATION_TIERS,
   STANDING_AUTHORIZATION_ACTIONS,
+  readDelegationPolicy,
   readPrecedentStore,
   readStandingAuthorization,
   readTriagePolicy,

package/src/core/context.js

@@ -471,16 +471,27 @@ function resolveHandoff(repo, handoff) {
 }
 
 function gitWarnings(repo) {
+  // `-z`, so a non-ASCII path is reported as the filesystem spells it rather
+  // than as the octal escape Git produces in every other form. The gate's
+  // `gitPaths` reads the same way, for the same reason.
   const git = spawnSync(
     "git",
-    ["status", "--short", "--untracked-files=all"],
+    ["status", "--porcelain=v1", "-z", "--untracked-files=all"],
     { cwd: repo, encoding: "utf8" }
   );
   if (git.error || git.status !== 0 || !git.stdout.trim()) return [];
-  const paths = git.stdout
-    .split(/\r?\n/)
-    .filter(Boolean)
-    .map((line) => line.slice(3).trim());
+  // Each record is `XY <path>`; a rename or copy adds a second bare field for
+  // its other endpoint, which carries no status prefix to strip.
+  const fields = git.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.length > 0
     ? [`Working tree has uncommitted paths (selection-neutral): ${paths.join(", ")}`]
     : [];
@@ -495,11 +506,36 @@ function resolveContext(repo, options) {
     context = handoff ? resolveHandoff(repo, handoff) : inferContext(repo);
   }
   context.warnings.push(...gitWarnings(repo));
+  // Set here rather than by the caller, so every consumer of the projection —
+  // text, JSON, and any host reading it — carries the version without having
+  // to know to add it.
+  context.keel = keelVersion();
   return context;
 }
 
+// The version comparison has to survive a runtime too old to contain it. The
+// SessionStart check shipped in 5.9.0, so a plugin older than that carries no
+// check at all, and its silence is indistinguishable from three versions
+// agreeing — measured 2026-08-02 with plugin 5.7.1, CLI 5.7.0, and protocol
+// 5.12.0, where nothing was reported. An absent mechanism cannot announce
+// itself, so the answer is not another check inside the plugin: the version
+// rides on the surface the protocol already requires an agent to read, and
+// `AGENTS.md` — which is read from the working tree and therefore cannot be
+// stale — asks for it to be reported beside the version the repository
+// declares.
+function keelVersion() {
+  try {
+    return require(path.join(__dirname, "..", "..", "package.json")).version;
+  } catch {
+    return "unknown";
+  }
+}
+
 function renderContext(result) {
   const lines = [
+    // First, because it is the provenance of everything under it. A result
+    // that does not say which Keel produced it cannot be compared to anything.
+    `Keel: ${result.keel || keelVersion()}`,
     `Keel context: ${result.status}`,
     `Next action: ${result.nextAction.kind}`,
   ];

package/src/core/gates.js

@@ -110,9 +110,36 @@ function loadSelection(repo, options, requireTask = true) {
 // of the task they just finished. A task that has started records a fingerprint
 // in its Evidence `Contract` anchor, so that anchor is what makes the inference
 // safe — and without one there is nothing for completion to compare against.
-function hasRecordedAnchor(selection, task) {
+function recordedAnchor(selection, task) {
   const plan = contractAnchorPlan(selection, task);
-  return Boolean(plan && anchoredFingerprint(plan.previous));
+  return plan ? anchoredFingerprint(plan.previous) : null;
+}
+
+function hasRecordedAnchor(selection, task) {
+  return Boolean(recordedAnchor(selection, task));
+}
+
+// The anchor was parsed, shape-checked, and then discarded: completion asked
+// whether sixty-four hex characters were present and never whether they were
+// the ones this task compiles to. `keel context` and `keel guard status` both
+// already compared, and two shipped requirements already described completion
+// as comparing, so this is the one surface that did not do what was written
+// down about it. A digest that matches can only have come from the schema that
+// produced it, so the `keel-task-capsule/v1` prefix is diagnostic detail here
+// rather than a second thing to require.
+function contractDriftProblem(recorded, contract) {
+  if (!recorded || recorded === contract.fingerprint.value) return null;
+  return problem(
+    "contract-drift",
+    `The Evidence \`Contract\` anchor records sha256:${recorded}, but this `
+      + `task now compiles to ${contract.fingerprint.algorithm}:`
+      + `${contract.fingerprint.value} under ${contract.schema}. The contract `
+      + "changed after the anchor was recorded, so the authority this task was "
+      + "implemented under is not the authority it is being judged against. "
+      + "Reauthorize with `keel gate task-start --record`, which rewrites the "
+      + "anchor in place; execution evidence produced under the previous "
+      + "contract is stale and has to be cleared or re-verified first."
+  );
 }
 
 // A task that recorded no anchor has no drift detection at all while presenting
@@ -173,6 +200,43 @@ function anchoredFingerprint(previous) {
   return match ? match[1].toLowerCase() : null;
 }
 
+// Two tasks in one change declaring the same Touch set, both driven red-green,
+// are shaped like one behavior split in half. Issue #41 records the case that
+// produced this: a split that passed task-start and the Slice Start Gate and
+// was not executable — implementing the first alone broke a shipping scenario,
+// and once it was right the second had no honest red left.
+//
+// A warning, deliberately, not a `needs-review`. A genuine vertical split can
+// share files, so the shape is a signal rather than a verdict; and there is no
+// way to acknowledge a `needs-review`, so making it one would leave a
+// legitimate split unstartable. The reader is given the other task's id and
+// compares two things, rather than being told something is wrong.
+function taskShapeWarnings(repo, selection, task, compiled) {
+  if (!compiled || compiled.diagnostics.length > 0) return [];
+  const strategy = compiled.capsule.verification.strategy.toLowerCase();
+  if (!RED_GREEN_VERIFICATION_STRATEGIES.has(strategy)) return [];
+  const touch = [...compiled.capsule.touch].sort().join("\n");
+  if (!touch) return [];
+  const matches = [];
+  for (const sibling of selection.tasks) {
+    if (sibling.id === task.id) continue;
+    const other = compileTaskContract(repo, selection.change, sibling);
+    if (other.diagnostics.length > 0) continue;
+    if ([...other.capsule.touch].sort().join("\n") !== touch) continue;
+    matches.push(sibling.id);
+  }
+  if (matches.length === 0) return [];
+  return [
+    `Task ${task.id} declares the same Touch set as `
+      + `${matches.join(", ")} and both are driven ${strategy}. Two tasks over `
+      + "the same files under a red-green strategy are often one behavior "
+      + "split in half, where the first half is wrong on its own and the "
+      + "second has no honest red left. This is a prompt, not a verdict — a "
+      + "genuine vertical split can share files. Compare them before "
+      + "implementing.",
+  ];
+}
+
 function taskStart(repo, options) {
   const selection = loadSelection(repo, options);
   const task = selection.selected[0];
@@ -207,7 +271,7 @@ function taskStart(repo, options) {
     selection.change,
     [task.id],
     problems,
-    [],
+    taskShapeWarnings(repo, selection, task, compiled),
     problems.length === 0
       ? compiled
       : null
@@ -322,6 +386,71 @@ function durableOwnerVerdict(repo, value) {
   return { ok: false, reason: "missing", path: candidate[0] };
 }
 
+// A finding has three dispositions and the gate recognized two. One found and
+// fixed inside the task recording it has no owner to name and nothing to
+// discard, so the only text that passed was `Discard reason:` — filing a repair
+// as a dismissal. This capability and `keel-review-checklist` both already
+// scoped the ownership requirement to an *unresolved* finding; only the
+// implementation applied it to all of them. `## Invalidates` has carried the
+// same third slot since it shipped, where `Updated by:` names tasks of this
+// change.
+// The capture is the single token after the marker, not the rest of the line.
+// Findings is one line of free prose that normally holds several findings with
+// different dispositions, so a capture reaching to the newline swallows every
+// marker after it — a block recording one fix and one tracker-owned follow-up
+// was refused because the *follow-up's* URL was read as the *fix's* evidence.
+// Measured on this change's own task 1.3. The match is global because each
+// resolved claim owes its own evidence; checking only the first would let a
+// second one assert itself for free.
+const RESOLVED_HERE = /\bresolved here\s*:[ \t]*(\S*)/gi;
+
+// Resolution evidence is deliberately narrower than a durable owner. An
+// `http`/`https` reference says someone else will do the work later, which is
+// exactly the durable-owner state; what proves a fix is the check that covers
+// it or the artifact that shows it. A bare marker is refused because a
+// disposition that asserts its own conclusion would be a way out of the other
+// two, and the third state would decay into the easiest exit.
+function resolutionEvidenceVerdict(repo, value, commands) {
+  const evidence = String(value || "").trim();
+  if (!evidence) return { ok: false, reason: "empty" };
+  // The tracker form is tested before the path form: a URL contains something
+  // shaped like a path, so leaving it to fall through would refuse
+  // `https://…/issues/43` by reporting that `github.com/…/issues/43` is not a
+  // file — a true sentence about the wrong thing.
+  if (TRACKER_REFERENCE.test(evidence)) return { ok: false, reason: "tracker" };
+  const cited = evidence.match(/\bM\d+\b/);
+  if (cited) {
+    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._-]+)+/);
+  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] };
+}
+
+function resolutionEvidenceMessage(verdict) {
+  const lead = "Review Findings records a finding as resolved here, but its "
+    + "evidence is not usable — ";
+  const tail = " Resolution evidence is an `M<n>` check this task declares, or "
+    + "a repo-relative path that exists.";
+  if (verdict.reason === "empty") {
+    return `${lead}the marker names nothing at all.${tail}`;
+  }
+  if (verdict.reason === "tracker") {
+    return `${lead}a tracker reference says the work is owned elsewhere, which `
+      + "is the durable-owner state, not a proof that this task fixed it. Write "
+      + `\`Durable owner:\` instead, or name what proves the fix.${tail}`;
+  }
+  if (verdict.reason === "unknown-check") {
+    return `${lead}${verdict.label} is not a check this task declares.${tail}`;
+  }
+  if (verdict.reason === "missing") {
+    return `${lead}\`${verdict.path}\` does not exist.${tail}`;
+  }
+  return `${lead}it names neither a check nor a path.${tail}`;
+}
+
 function findingOwnerIsDurable(repo, findings) {
   if (/keel\/HANDOFF\.md/i.test(findings)) return false;
   if (/\b(?:explicit\s+)?discard (?:reason|rationale)\s*:/i.test(findings)) {
@@ -346,26 +475,41 @@ function findingOwnerIsDurable(repo, findings) {
     );
 }
 
+// Read in `-z` form, because every other form escapes. Git octal-escapes any
+// path holding a non-ASCII byte and quotes it; `core.quotepath=false` removes
+// the octal and still quotes a space, a quote, or a backslash; and `status`
+// and `diff` do not agree on which cases they quote. `-z` emits raw bytes in
+// all of them, which deletes the decoding problem rather than adding a
+// 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", "--short", "--untracked-files=all"],
+    ["status", "--porcelain=v1", "-z", "--untracked-files=all"],
     { cwd: repo, encoding: "utf8" }
   );
   if (status.error || status.status !== 0) return [];
-  return status.stdout
-    .split(/\r?\n/)
-    .filter(Boolean)
-    .flatMap((line) => {
-      // A staged rename/copy is one porcelain line, `R  old -> new`; attribute
-      // both endpoints so a rename whose old and new paths are in Touch is not
-      // a false outside-Touch failure. Every other line carries one path.
-      const entry = line.slice(3).trim().replace(/\\/g, "/");
-      const arrow = entry.indexOf(" -> ");
-      return arrow === -1
-        ? [entry]
-        : [entry.slice(0, arrow), entry.slice(arrow + 4)];
-    });
+  // 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;
 }
 
 function touchEntries(task, contract = null) {
@@ -386,9 +530,15 @@ function globPattern(value) {
   );
 }
 
+// No separator rewriting on either side. Git emits forward slashes on every
+// platform, so rewriting backslashes normalized a separator that never
+// arrives — and it did so on the Touch entry and on the candidate, two wrongs
+// that cancelled for a filename holding a literal backslash while making
+// `src/back/slash.js` in Touch match a changed `src/back\slash.js`, a file the
+// task never declared.
 function pathAllowed(candidate, touch) {
   return touch.some((entry) => {
-    const normalized = entry.replace(/\\/g, "/").replace(/^\.\//, "");
+    const normalized = entry.replace(/^\.\//, "");
     if (normalized.endsWith("/")) return candidate.startsWith(normalized);
     if (normalized.includes("*")) return globPattern(normalized).test(candidate);
     return candidate === normalized;
@@ -441,16 +591,18 @@ function scopeEvidence(
   if (verified.error || verified.status !== 0) {
     throw new GateInputError(`invalid trustworthy Git base: ${base}`);
   }
+  // `-z` for the same reason as `gitPaths`: `--name-only` escapes a non-ASCII
+  // path to octal, and it does not quote the same cases `status` quotes.
   const diff = spawnSync(
     "git",
-    ["diff", "--name-only", base, "--"],
+    ["diff", "--name-only", "-z", base, "--"],
     { cwd: repo, encoding: "utf8" }
   );
   if (diff.error || diff.status !== 0) {
     throw new GateInputError(`could not compare Git base: ${base}`);
   }
   const changed = new Set([
-    ...diff.stdout.split(/\r?\n/).filter(Boolean),
+    ...diff.stdout.split("\0").filter(Boolean),
     ...dirtyPaths,
   ]);
   const touch = touchEntries(task, contract);
@@ -464,7 +616,6 @@ function scopeEvidence(
   const warnings = [];
   const outside = [];
   const candidates = [...changed]
-    .map((item) => item.replace(/\\/g, "/"))
     .filter((item) => item !== "keel/guard.json")
     .filter((item) => !(authoringPrefix && item.startsWith(authoringPrefix)))
     .filter((item) => !pathAllowed(item, touch))
@@ -582,19 +733,37 @@ function completionChecks(repo, task, contract = null) {
         `Current-agent Review is incomplete — ${details.join("; ")}.`
       )
     );
-  } else if (
-    !/^none\.?$/i.test(reviewFields.Findings)
-    && !findingOwnerIsDurable(repo, reviewFields.Findings)
-  ) {
-    problems.push(
-      problem(
-        "finding-owner",
-        "Review Findings must be `none` or carry a durable owner — a "
-          + "`Discard reason:`/`Discard rationale:` prefix, or "
-          + `${DURABLE_OWNER_FORMS}. Name a path after \`Durable owner:\` so `
-          + "it reads as the owner rather than a file the finding mentions."
-      )
-    );
+  } else if (!/^none\.?$/i.test(reviewFields.Findings)) {
+    // `Resolved here:` is evaluated on its own terms rather than falling
+    // through to the owner forms. Otherwise `Resolved here: https://…` would
+    // pass as a tracker owner, which is the one reading this disposition must
+    // not have: a link to work someone else will do is not evidence that this
+    // task did it.
+    const resolved = [...reviewFields.Findings.matchAll(RESOLVED_HERE)];
+    if (resolved.length > 0) {
+      for (const claim of resolved) {
+        const verdict = resolutionEvidenceVerdict(repo, claim[1], commands);
+        if (verdict.ok) continue;
+        problems.push(
+          problem("finding-resolution-evidence", resolutionEvidenceMessage(verdict))
+        );
+        break;
+      }
+    } else if (!findingOwnerIsDurable(repo, reviewFields.Findings)) {
+      problems.push(
+        problem(
+          "finding-owner",
+          "Review Findings must be `none` or carry a disposition. A finding "
+            + "fixed in this task is `Resolved here:` naming an `M<n>` check "
+            + "this task declares or a repo-relative path that exists; one "
+            + "someone must still do is `Durable owner:` naming "
+            + `${DURABLE_OWNER_FORMS}; one deliberately not being done is a `
+            + "`Discard reason:`/`Discard rationale:` prefix. Name a path after "
+            + "`Durable owner:` so it reads as the owner rather than a file the "
+            + "finding mentions."
+        )
+      );
+    }
   }
   return { problems, reviewProblems };
 }
@@ -625,7 +794,17 @@ function taskComplete(repo, options) {
   const checks = completionChecks(repo, task, usableContract);
   checks.problems.push(...contract.diagnostics);
   const missingAnchor = missingAnchorProblem(selection, task);
-  if (missingAnchor) checks.problems.push(missingAnchor);
+  if (missingAnchor) {
+    checks.problems.push(missingAnchor);
+  } else if (usableContract) {
+    // Only when an anchor exists: a missing one is already its own problem, and
+    // reporting drift on top of it would name a comparison that never ran.
+    const drift = contractDriftProblem(
+      recordedAnchor(selection, task),
+      usableContract
+    );
+    if (drift) checks.problems.push(drift);
+  }
   const scope = scopeEvidence(
     repo,
     task,
@@ -894,6 +1073,28 @@ function changeClose(repo, options) {
       );
       continue;
     }
+    // Completion is not the last moment a live change's contract can move. The
+    // window between the final checkbox and the archive was unguarded, at the
+    // one gate whose job is closing that window — and the loop already compiled
+    // every task's capsule, so the comparison costs nothing here either.
+    const anchor = recordedAnchor(selection, task);
+    if (!anchor) {
+      problems.push(
+        problem(
+          "missing-contract-anchor",
+          `Task ${task.id} is checked complete but its Evidence \`Contract\` `
+            + "anchor holds no compiled fingerprint, so the close has nothing "
+            + "to compare and cannot verify the contract this task was "
+            + "completed under. Return it through `keel gate task-start "
+            + "--record` and `keel gate task-complete` before closing."
+        )
+      );
+    } else if (contract.diagnostics.length === 0) {
+      const drift = contractDriftProblem(anchor, contract);
+      if (drift) {
+        problems.push(problem(drift.code, `Task ${task.id}: ${drift.message}`));
+      }
+    }
     const checks = completionChecks(
       repo,
       task,

package/src/core/goal.js

@@ -47,7 +47,14 @@ function renderCondition(goal) {
     `Write boundary (Touch): ${goal.touch.join(", ")}.`,
     "Stop/Autonomy boundary:",
     ...goal.stopBoundary.map((item) => `- ${item}`),
-    "Ownership: the current agent is the sole writer and owns Review, gate invocation, the task checkbox, and completion.",
+    "Ownership: the current agent is the sole holder of write authority and owns Review, gate invocation, the task checkbox, and completion. A declared delegate writes only inside Touch and the current agent re-runs each check before recording Evidence.",
+    ...(goal.delegation
+      ? [
+        `Delegation: tier ${goal.delegation.tier}, declared by `
+          + `${goal.delegation.source}. Keel carries the tier and does not `
+          + "select or observe a model.",
+      ]
+      : []),
     "Done only when: task-complete passes and the current agent has durably checked the task; then stop and require a new explicit authorization before any next task.",
   ];
   return lines.join("\n");
@@ -166,6 +173,11 @@ function compileGoalProjection(repo, options) {
     owner: capsule.owner,
     ownership: "current-agent-sole-writer",
     helperPolicy: capsule.helperAuthority,
+    // Carried inside the condition rather than beside it, so a declared
+    // delegation is subject to the same budget as everything else the
+    // activation must state. A field that never reaches the condition
+    // cannot overflow it, and would then be a boundary the goal omits.
+    delegation: capsule.delegation || null,
     terminalStates: TERMINAL_STATES,
     evidencePresentation: EVIDENCE_PRESENTATION,
     authorizationEvidence: {

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,