@christang/keel 5.14.0 → 5.16.0

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.14.0 -->
+<!-- keel:start version=5.16.0 -->
 ## Keel Bootstrap
 
 - Start every session with `keel context`; OpenSpec artifacts and Git are the only durable authority — never native memory, goals, or transcripts.

package/bin/keel.js

@@ -699,21 +699,35 @@ function openspecReportedVersion(command) {
   return match ? match[0] : null;
 }
 
-function lockedOpenSpecVersion() {
+// The root is the repository under diagnosis, never PACKAGE_ROOT. Rooting this
+// at Keel's own install location made the line a statement about a repository
+// the reader was never shown: a consumer pinning 9.9.9 was told the version
+// Keel's checkout pins, and a global install — which ships no lockfile — was
+// told `unreadable` forever, which is exactly the drift this check was added
+// to expose. There is no fallback to PACKAGE_ROOT on purpose; falling back
+// would reinstate the misattribution and leave the reader unable to tell which
+// case they were in.
+//
+// Three outcomes, not two. A repository with no lockfile and one whose lockfile
+// names no OpenSpec both *declare* nothing, which is the ordinary case for any
+// project that does not depend on OpenSpec directly. A lockfile that exists and
+// cannot be parsed is a read failure. Collapsing them would either warn at
+// everyone or hide a real failure.
+function declaredOpenSpecVersion(repo) {
+  const lockPath = path.join(repo, "package-lock.json");
+  if (!fs.existsSync(lockPath)) return { state: "none", version: null };
+  let lock;
   try {
-    const lock = JSON.parse(
-      fs.readFileSync(path.join(PACKAGE_ROOT, "package-lock.json"), "utf8")
-    );
-    for (const [name, entry] of Object.entries(lock.packages || {})) {
-      if (name.endsWith("@fission-ai/openspec") && entry && entry.version) {
-        return entry.version;
-      }
-    }
+    lock = JSON.parse(fs.readFileSync(lockPath, "utf8"));
   } catch {
-    // No lockfile in a published install; there is then nothing to disagree
-    // with, which is not the same as agreement and is reported as such.
+    return { state: "unreadable", version: null };
   }
-  return null;
+  for (const [name, entry] of Object.entries(lock.packages || {})) {
+    if (name.endsWith("@fission-ai/openspec") && entry && entry.version) {
+      return { state: "declared", version: entry.version };
+    }
+  }
+  return { state: "none", version: null };
 }
 
 function findOpenSpecCommand() {
@@ -1426,16 +1440,24 @@ function runDoctor(options) {
         silentNotFound: true,
       }) === 0;
     const resolvedVersion = openspecReportedVersion(openspec);
-    const locked = lockedOpenSpecVersion();
+    const declared = declaredOpenSpecVersion(repo);
     const mismatched = Boolean(
-      resolvedVersion && locked && resolvedVersion !== locked
+      resolvedVersion
+      && declared.state === "declared"
+      && resolvedVersion !== declared.version
     );
     const where = bareOpenSpecOnPath
       ? openspec
       : `${openspec} is keel-resolvable but bare \`openspec\` is not on PATH — use \`keel openspec\``;
-    const versions = `${resolvedVersion || "version unreadable"}, lockfile ${
-      locked || "unreadable"
-    }`;
+    // Two versions on one line need two owners. `repo` is the repository named
+    // on doctor's first line; the answering build is attributed by the path
+    // already printed beside it.
+    const declaredText = {
+      declared: `repo pins ${declared.version}`,
+      none: "repo declares no OpenSpec version",
+      unreadable: "repo package-lock.json unreadable",
+    }[declared.state];
+    const versions = `${resolvedVersion || "version unreadable"}, ${declaredText}`;
     printDoctorLine(
       "openspec",
       mismatched || !bareOpenSpecOnPath ? "warning" : "ok",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@christang/keel",
   "displayName": "Keel",
   "description": "Keel OpenSpec execution discipline CLI for Claude Code, Codex, and OpenCode.",
-  "version": "5.14.0",
+  "version": "5.16.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/plugins/keel/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.14.0",
+  "version": "5.16.0",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/plugins/keel/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.14.0",
+  "version": "5.16.0",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/plugins/keel/skills/keel-review-checklist/SKILL.md

@@ -23,7 +23,7 @@ Read the selected OpenSpec proposal, design, specs, tasks, diff, and command evi
 - For a red-green strategy (`vertical-tdd`, `regression-first`), confirm concrete per-label `.red` and `.green` Evidence exists for the same check; evidence-first tasks instead name their observable proof.
 - A failure message must **name the actual cause** of what it reports. Watch for one condition guarding **two distinct failures** — `if result is None or result["status"] != expected` reports the first failure's message when the second one happened, sending the reader to a place with no problem in it. Split the condition. No gate can judge this: deciding whether a sentence misleads needs a model, so it stays here.
 - When two tasks in the change declared the same Touch set under a red-green strategy — `keel gate task-start` warns about this — ask whether they turned out to be **one behavior** split in half. The tell is that the first task's minimal implementation was wrong in the field, or that the second had no honest red left because the first already made its checks pass. The gate can only see the shape; by completion you can see the outcome, which is the only point at which this is answerable.
-- When no trustworthy explicit Git base exists, do not attribute dirty paths automatically. Review scope semantically.
+- Scope attribution is now the gate's job by default: `keel gate task-complete` compares the worktree against the dirty set `task-start` recorded and refuses a path outside Touch, so a `pass` is evidence about scope rather than silence about it. Two cases still need you. When the gate reports paths as *unattributed* — no recorded set, because the manifest predates the field or the guard was cleared — nothing was checked and the review is the only scope evidence. And a path already dirty when the task started is never attributed even if the task changed it again, so read the gate's silence about such a path as absence of a check rather than absence of a write.
 - For `Coupling: required`, confirm one complete candidate reached its completion gate and generated artifacts are aligned.
 
 ## Semantic Review

package/scripts/validate_plugin.py

@@ -37,8 +37,8 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.14.0"
-PROTOCOL_VERSION = "5.14.0"
+PACKAGE_VERSION = "5.16.0"
+PROTOCOL_VERSION = "5.16.0"
 LEGACY_MANAGED_START = "<!-- keel:start version=2.1 -->"
 OPENSPEC_SCHEMA_NAME = "keel-spec-driven"
 # Mirrors KEEL_PACKAGE_NAME in scripts/install_to_repo.py, one of the two
@@ -5594,6 +5594,146 @@ def validate_runtime_versions_are_checked_scenario() -> int:
     return 0
 
 
+def validate_doctor_reads_the_diagnosed_repository_scenario() -> int:
+    """Issue #57: doctor named one repository and answered about another.
+
+    The OpenSpec declaration was read from `PACKAGE_ROOT/package-lock.json` —
+    the directory Keel is installed in — while the line above it says
+    `keel doctor for <repo>`. The two coincide only when `node bin/keel.js`
+    runs from Keel's own checkout, which is the one arrangement every existing
+    scenario uses: `run_keel` always spawns `node <ROOT>/bin/keel.js`, so
+    `PACKAGE_ROOT` is Keel's checkout no matter what `cwd` is. Driving the
+    diagnosis at a repository that declares its own version is what separates
+    the two roots without needing a second installation.
+    """
+    label = "doctor-reads-the-diagnosed-repository"
+
+    def openspec_line(stdout: str) -> str:
+        return next(
+            (line for line in stdout.splitlines() if line.startswith("openspec:")),
+            "",
+        )
+
+    # M1 first half — a repository that declares a version Keel's own tree does
+    # not. The sentinel is deliberately one no published OpenSpec reports, so a
+    # line carrying it cannot have come from the resolved binary either.
+    declared = "0.0.1"
+    with tempfile.TemporaryDirectory(prefix="keel-doctor-declares-") as raw:
+        declares = Path(raw).resolve()
+        write_text(
+            declares / "package-lock.json",
+            json.dumps(
+                {
+                    "name": "consumer",
+                    "lockfileVersion": 3,
+                    "packages": {
+                        "node_modules/@fission-ai/openspec": {"version": declared}
+                    },
+                },
+                indent=2,
+            )
+            + "\n",
+        )
+        doctor = run_keel(declares, "--doctor")
+        line = openspec_line(doctor.stdout or "")
+        if not line:
+            report(f"{label} M1 `keel --doctor` emitted no openspec line.")
+            report((doctor.stdout or doctor.stderr or "").strip())
+            return 1
+        own_lock = json.loads((ROOT / "package-lock.json").read_text(encoding="utf-8"))
+        own_declared = None
+        for name, entry in own_lock.get("packages", {}).items():
+            if name.endswith("@fission-ai/openspec"):
+                own_declared = entry.get("version")
+        if not own_declared:
+            report(f"{label} could not read Keel's own declared OpenSpec version.")
+            return 1
+        # The reader sees two versions on this line: the one the resolved binary
+        # reports and the one the repository declares. Assert on the declared
+        # POSITION, not on bare presence — the resolved binary's version may
+        # legitimately equal Keel's own declared version, and a test that reads
+        # any occurrence cannot tell the two apart.
+        # Two distinct failures, two conditions. A line carrying the right
+        # version with no attribution and a line attributing the wrong version
+        # need different fixes, and one message covering both would send half
+        # its readers to a place with no problem in it.
+        if "repo pins" not in line:
+            report(
+                f"{label} M1 the openspec line does not attribute any declared "
+                "version to the repository, so a reader seeing two versions "
+                "cannot tell which one is theirs."
+            )
+            report(f"  {line}")
+            return 1
+        if f"repo pins {declared}" not in line:
+            report(
+                f"{label} M1 the openspec line attributes a declared version "
+                f"to the repository, but not {declared}, which is what this "
+                "repository declares. It is answering about some other "
+                "repository."
+            )
+            report(f"  {line}")
+            return 1
+        if own_declared != declared and f"repo pins {own_declared}" in line:
+            report(
+                f"{label} M1 the openspec line reports {own_declared} as the "
+                "declared version. That is what is declared where Keel is "
+                "installed, not where it was pointed."
+            )
+            report(f"  {line}")
+            return 1
+        if not line.startswith("openspec: warning"):
+            report(
+                f"{label} M1 the resolved binary and the declared version "
+                f"disagree ({declared} is declared and no release reports it), "
+                "and the line does not state the disagreement."
+            )
+            report(f"  {line}")
+            return 1
+
+    # M1 second half — absence is a statement about the repository, not a read
+    # failure, and not a disagreement. Most repositories do not depend on
+    # OpenSpec at all, so warning here would train readers to ignore the line.
+    with tempfile.TemporaryDirectory(prefix="keel-doctor-silent-") as raw:
+        silent = Path(raw).resolve()
+        write_text(silent / "README.md", "# consumer\n")
+        doctor = run_keel(silent, "--doctor")
+        line = openspec_line(doctor.stdout or "")
+        if not line:
+            report(f"{label} M1 `keel --doctor` emitted no openspec line.")
+            report((doctor.stdout or doctor.stderr or "").strip())
+            return 1
+        if "declares no OpenSpec" not in line:
+            report(
+                f"{label} M1 a repository declaring no OpenSpec version is not "
+                "reported as declaring none."
+            )
+            report(f"  {line}")
+            return 1
+        if "unreadable" in line:
+            report(
+                f"{label} M1 the absence of a declaration is reported as a "
+                "failure to read one. The two are different facts and only one "
+                "of them is true here."
+            )
+            report(f"  {line}")
+            return 1
+        if "answering from a different" in line:
+            report(
+                f"{label} M1 a repository declaring nothing is reported as "
+                "disagreeing with the resolved binary. There is nothing for it "
+                "to disagree with."
+            )
+            report(f"  {line}")
+            return 1
+
+    if label not in {name for name, _ in SCENARIOS}:
+        report(f"{label}: the scenario registry does not include it.")
+        return 1
+    report(f"{label} scenario passed.")
+    return 0
+
+
 TASK_SHAPE_TEMPLATE = """## 1. Work
 
 - [ ] 1.1 First half
@@ -6054,6 +6194,174 @@ def validate_interpreter_surfaces_agree_scenario() -> int:
     return 0
 
 
+def validate_default_completion_attributes_writes_scenario() -> int:
+    """A write outside Touch has to fail the gate the author actually runs.
+
+    `attributionResult` refuses an out-of-Touch path in full — diff, union with
+    the dirty set, `pathAllowed` filter, `outside-touch` problem — behind
+    `if (!base) return { problems: [] }`. Without `--base` the whole comparison
+    is skipped and the paths are printed as a warning instead. Measured at
+    5.15.0 on one tree and one task: `pass` with the offending path in a
+    warning, `fail` once `--base HEAD` was added.
+
+    It was found by it happening. During the 5.15.0 release task a file was
+    written that the task had not declared, through a `python3` heredoc in
+    Bash — the write guard binds the host's file-writing tools and cannot bind
+    a shell — and `task-complete` returned `pass`. A human reading `git status`
+    caught it. Nobody reads `git status` in an unattended run, and this
+    repository admits work into unattended runs by declaration.
+
+    The base does not have to come from the caller. `task-start` already writes
+    the manifest at the instant the task is authorized; recording what was
+    dirty then answers "did this task write it" without asking Git to answer
+    "which task wrote it", which is the question it cannot answer in a
+    half-finished change.
+    """
+    label = "default-completion-attributes-writes"
+
+    def git(repo: Path, *args: str) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            ["git", "-C", str(repo), *args], capture_output=True, text=True
+        )
+
+    def tasks_doc() -> str:
+        return (
+            "# Tasks\n\n## Invalidates\n\n- None.\n\n"
+            "- [ ] 1.1 Exercise task contract\n"
+            "  - Covers:\n    - E1: Public behavior passes.\n"
+            "  - Touch:\n    - src/declared.js\n"
+            "  - Verify:\n    - Strategy: evidence-first\n"
+            "    - M1: node test.js asserts the recorded feed status\n"
+            "  - Evidence:\n    - Contract: pending\n    - M1: the suite passed\n"
+            "    - Review:\n      - Status: pass\n"
+            "      - Acceptance check: behavior asserted at the interface\n"
+            "      - Scope check: only Touch files changed\n"
+            "      - Findings: none\n"
+            "    - Blocker: none\n"
+        )
+
+    with tempfile.TemporaryDirectory(prefix="keel-default-attribution-") as raw:
+        repo = (Path(raw) / "repo").resolve()
+        repo.mkdir()
+        git(repo, "init", "-q")
+        git(repo, "config", "user.email", "t@example.com")
+        git(repo, "config", "user.name", "keel-test")
+        write_text(repo / "src/declared.js", "// product\n")
+        write_text(repo / "src/undeclared.js", "// product\n")
+        write_text(repo / "src/already-dirty.js", "// product\n")
+        write_text(repo / "openspec/changes/demo/tasks.md", tasks_doc())
+        git(repo, "add", "-A")
+        git(repo, "-c", "commit.gpgsign=false", "commit", "-q", "-m", "base")
+
+        def start(*extra: str) -> subprocess.CompletedProcess[str]:
+            return run_keel(
+                repo, "gate", "task-start", "--change", "demo", "--task", "1.1",
+                "--record", *extra, "--json",
+            )
+
+        def gate(*extra: str) -> dict:
+            return json.loads(
+                run_keel(
+                    repo, "gate", "task-complete", "--change", "demo",
+                    "--task", "1.1", *extra, "--json",
+                ).stdout
+            )
+
+        def outside(payload: dict) -> list[str]:
+            return [
+                problem.get("message", "")
+                for problem in payload.get("problems", [])
+                if problem.get("code") == "outside-touch"
+            ]
+
+        # A path already dirty before the task is authorized. It must stay
+        # unattributed afterwards: subtracting the start set is what removes
+        # the false-positive class that made automatic attribution unsafe.
+        write_text(repo / "src/already-dirty.js", "// touched before the task\n")
+
+        if start().returncode != 0:
+            report(f"{label} could not authorize the fixture task.")
+            return 1
+
+        # M1 — the reported defect. A write the guard never saw, and the gate
+        # invoked the way an author actually invokes it.
+        write_text(repo / "src/undeclared.js", "// written outside Touch\n")
+        payload = gate()
+        problems = outside(payload)
+        if not any("src/undeclared.js" in message for message in problems):
+            report(
+                f"{label} M1 a path written outside Touch after task start was "
+                "not refused by the default completion gate. The boundary "
+                "holds only when the caller asks for it."
+            )
+            report(f"  status={payload.get('status')!r}")
+            for warning in payload.get("warnings", []):
+                report(f"  warning: {warning}")
+            return 1
+        if payload.get("status") != "fail":
+            report(
+                f"{label} M1 the gate named the out-of-Touch path but did not "
+                f"fail; got status {payload.get('status')!r}. A boundary that "
+                "reports without refusing is not a boundary."
+            )
+            return 1
+        if any("src/already-dirty.js" in message for message in problems):
+            report(
+                f"{label} M1 a path that was already dirty when the task "
+                "started was attributed to the task. The recorded set is not "
+                "being subtracted, so an unrelated dirty worktree fails the "
+                "gate."
+            )
+            return 1
+
+        # M1 — an explicit base answers the question the caller asked, which is
+        # the broader one: everything since that commit, including what was
+        # already dirty when the task started.
+        base_problems = outside(gate("--base", "HEAD"))
+        if not any("src/already-dirty.js" in message for message in base_problems):
+            report(
+                f"{label} M1 an explicit --base did not attribute a path that "
+                "changed since that base, so the recorded set is overriding "
+                "the base the caller supplied instead of yielding to it."
+            )
+            for message in base_problems:
+                report(f"  {message}")
+            return 1
+
+        # M1 — no record means no attribution. A manifest written before this
+        # existed, or a cleared one, must not be read as a clean start: absence
+        # of a record is not a record of absence.
+        run_keel(repo, "guard", "clear")
+        if start("--no-guard").returncode != 0:
+            report(f"{label} could not re-authorize without a manifest.")
+            return 1
+        payload = gate()
+        if outside(payload):
+            report(
+                f"{label} M1 the gate attributed paths with no recorded "
+                "task-start set. A missing record is being read as a clean "
+                "start, which fails every completion in a dirty repository."
+            )
+            for message in outside(payload):
+                report(f"  {message}")
+            return 1
+        if not any(
+            "not attributed" in warning for warning in payload.get("warnings", [])
+        ):
+            report(
+                f"{label} M1 with no record the gate neither attributed nor "
+                "reported the dirty paths, so the fallback lost the semantic "
+                "review evidence it is supposed to preserve."
+            )
+            return 1
+
+    if label not in {name for name, _ in SCENARIOS}:
+        report(f"{label}: the scenario registry does not include it.")
+        return 1
+    report(f"{label} scenario passed.")
+    return 0
+
+
 CJK_PATH = "src/摄影光影规划工具.js"
 SPACE_PATH = "src/has space.js"
 QUOTE_PATH = 'src/has"quote.js'
@@ -19286,10 +19594,18 @@ SCENARIOS: tuple = (
         "git-paths-carry-no-escaping",
         validate_git_paths_carry_no_escaping_scenario,
     ),
+    (
+        "default-completion-attributes-writes",
+        validate_default_completion_attributes_writes_scenario,
+    ),
     (
         "runtime-versions-are-checked",
         validate_runtime_versions_are_checked_scenario,
     ),
+    (
+        "doctor-reads-the-diagnosed-repository",
+        validate_doctor_reads_the_diagnosed_repository_scenario,
+    ),
     ("task-shape-warning", validate_task_shape_warning_scenario),
     ("context-names-its-keel", validate_context_names_its_keel_scenario),
     ("interpreter-surfaces-agree", validate_interpreter_surfaces_agree_scenario),

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"]);
 
@@ -483,33 +483,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 +558,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 +579,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 +618,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

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,