approval-md 0.2.0 → 0.3.0

package/dist/src/core/protected-path-guard.js

@@ -22,6 +22,17 @@
  * execution. A change with no evidence fails the pull request. Session wiring
  * is not an input.
  *
+ * ## The unit of judgment: one commit (APRV-375)
+ *
+ * This file answers about ONE PAIR OF BLOBS, whichever pair the caller hands
+ * it, so the caller's choice of pair is where the question is really settled.
+ * Both callers choose the same one: for every commit of the range, base is that
+ * commit's first parent and head is the commit, because a grant binds one edit
+ * and the combined diff of a branch is a change nobody made. `core/commit-guard.ts`
+ * enumerates the commits, builds the per-commit inputs, states the argument
+ * that nothing goes unjudged, and is shared by the CI script and by
+ * `approval doctor`'s dark-session arm A.
+ *
  * ## What counts as evidence
  *
  * Evidence is about the CHANGE, not about the path (APRV-202). The guard reads
@@ -53,6 +64,18 @@
  *    match: a digest attested for one organ is not evidence for another, which
  *    is why the organ record carries a whole relative path where the policy
  *    record carries a basename.
+ *
+ *    Since APRV-338 the verdict ALSO covers an ordinary `policy.edit` path on a
+ *    `gate.path.signed_off` record carrying that path and the digest at head —
+ *    and it is reached LAST, after every grant search below has failed. That
+ *    ordering is the whole design. A sign-off is whole-file evidence: it says a
+ *    human read this file at these bytes, not that they saw a particular line
+ *    change. A grant binds the hunk. So a change a grant covers passes on the
+ *    grant and prints the grant as its reason, and the sign-off answers only
+ *    the case the pending-sign-off suffix was invented for — text a human has
+ *    read and agrees with, for which no grant was ever taken. The organ's
+ *    verdict stays first because an organ can have no grant at all, so for one
+ *    there is nothing weaker to prefer.
  * 2. `policy-authorized-file` — an exact Edit or Write whose verified
  *    `execution.started` is preceded by its unique matching registration and no
  *    approval request. The registration, start and recomputed stored payload
@@ -60,6 +83,21 @@
  *    change and the recorded class must be the class this path is routed to.
  *    This records authorization to execute, not successful completion; the
  *    exact hunk checks below establish whether those bytes landed.
+ *
+ *    The payload's `file` is the path the hook bound, and the hook binds an
+ *    ABSOLUTE one: `fileToolGate` resolves the declared target against the
+ *    session's `cwd`, so an Edit of SPEC.md in a worktree is recorded as
+ *    `/Users/carter/dev/approval-md/.claude/worktrees/<name>/SPEC.md`. This
+ *    tier accepts that shape and the bare repository-relative path, matching
+ *    an absolute one by its trailing segments (see
+ *    {@link namesProtectedFile}). Until APRV-337 it accepted only the relative
+ *    shape, which no hook has ever written, so every unsampled
+ *    supervised-live edit to SPEC.md failed CI (PR #393). Tail matching is
+ *    sound HERE because the bytes carry the proof: `before` has to occur in
+ *    the blob at base, `after` in the blob at head, and the replay has to
+ *    reach HEAD byte-identical, so a scratch copy holding other bytes covers
+ *    nothing whatever its path says. Verdict 4 below keeps the stricter
+ *    cwd-join rule, because a command payload describes no bytes.
  * 3. `granted-file` — a file-tool edit. The hook binds the CHANGE rather than
  *    the touch (APRV-124), so the bound material carries `file` plus the exact
  *    edit: `{before, after}` for an Edit, `{content}` for a Write. That is
@@ -134,6 +172,22 @@
  * against the head commit would have been theatre. The finding says which of
  * the two it got, every time.
  *
+ * ## Two anchors, because git keeps two dates (APRV-339)
+ *
+ * A commit carries an author date and a committer date, and they answer
+ * different questions. ORDERING — could this record have written these bytes,
+ * or does it come after them — is measured against the COMMITTER date, the
+ * moment those bytes were committed: an amend or a rebase only ever moves it
+ * later, so it cannot turn a genuine earlier start into a post-hoc one.
+ * STALENESS — is this evidence about this change or about some edit months ago
+ * — is measured against the AUTHOR date, which a rebase does not move, so
+ * replaying history does not expire evidence. Measuring both against the author
+ * date is what refused PR #393: `git commit --amend` kept the first author date
+ * while the bytes were committed 98 seconds later, and the unattended start
+ * that wrote them sat between the two and was read as having happened after the
+ * change. A caller that has only one date supplies it alone, and it answers
+ * both questions, which is where every caller stood before this.
+ *
  * ## How a hunk is decided to be covered
  *
  * The unit is a line of text. `added` is the multiset of lines the head blob
@@ -145,6 +199,18 @@
  * several approved edits to one file; the finding names every contributing
  * grant and puts the strongest and nearest at the head.
  *
+ * A bound Edit may describe LESS than a line, because the hook binds exactly
+ * what the tool replaced: rewriting part of a long paragraph binds a fragment
+ * and covers neither the line it removed nor the line it added. So before the
+ * replay below there is a line-local step (APRV-340). A fragment that occurs
+ * exactly once in exactly one line of the blob at base has one possible
+ * effect — that line, rewritten — and when the line it rewrites is one this
+ * change removes and the line it produces is one this change adds, both lines
+ * are credited to it. It is a one-step replay that needs no search, and it
+ * carries every eligibility condition the replay carries; what it does not
+ * carry is the replay's budget, which a 200 KB file with forty naming
+ * candidates exhausts before reaching a proof (PR #393).
+ *
  * Three properties of that choice are worth stating, because each is a limit:
  *
  * - A blob that differs while its line multiset does not is a REORDERING, and
@@ -198,7 +264,7 @@
  * This module appends nothing, reads no clock, and performs no IO of its own —
  * git plumbing and file reads live in the caller.
  */
-import { organAttestationOf } from "./attest.js";
+import { organAttestationOf, pathSignOffOf } from "./attest.js";
 import { parseApplyPatch } from "./apply-patch.js";
 import { classifyCommand, isGateOrganPath, isProtectedPath, normalizePathSpelling, POLICY_EDIT_SUBCLASS, protectedPathClass, } from "./command-class.js";
 import { payloadHash } from "./payload.js";
@@ -315,6 +381,50 @@ function endsWithSegments(candidate, want) {
     const offset = have.length - tail.length;
     return tail.every((segment, index) => segment === have[offset + index]);
 }
+/**
+ * Is this changed path the POLICY FILE, whichever end carries the longer
+ * spelling?
+ *
+ * The guard is handed a repository-relative path from git and a policy location
+ * from its caller, and either may be the more qualified of the two, so the test
+ * is run both ways. One named predicate rather than the comparison written out
+ * at each of the two sites that ask it.
+ */
+function namesPolicyFile(path, policyPath) {
+    return endsWithSegments(policyPath, path) || endsWithSegments(path, policyPath);
+}
+/**
+ * Does a bound payload's `file` name this checkout's copy of `path`?
+ *
+ * The hook writes the ABSOLUTE path: `fileToolGate` resolves the declared
+ * target against the session's `cwd`, so a real Edit of SPEC.md in a worktree
+ * binds `/Users/carter/dev/approval-md/.claude/worktrees/<name>/SPEC.md`. Two
+ * shapes pass: the repository-relative path itself, and an absolute path whose
+ * TRAILING segments are that path. A relative path carrying extra leading
+ * directories (`dry/SPEC.md`) is refused, as is any `..` segment or backslash,
+ * either of which would make the tail test claim something it cannot know.
+ *
+ * Matching an absolute path by its tail is safe for Edit and Write material,
+ * and only for that material, because there the bytes are the proof: `before`
+ * has to occur in the blob at base, `after` in the blob at head, and the
+ * replay has to reach HEAD byte-identical. A payload naming another checkout's
+ * copy of SPEC.md carries that copy's bytes, which are not these, so it covers
+ * nothing. Command material describes no bytes at all, which is why
+ * {@link commandTargetsPath} keeps the stricter cwd-join rule for it.
+ */
+function namesProtectedFile(file, path) {
+    if (file.includes("\\"))
+        return false;
+    const named = segmentsOf(file);
+    if (named.includes(".."))
+        return false;
+    const wanted = segmentsOf(path);
+    if (wanted.length === 0)
+        return false;
+    if (file.startsWith("/"))
+        return endsWithSegments(file, path);
+    return named.length === wanted.length && named.every((part, index) => part === wanted[index]);
+}
 /**
  * Does this command line WRITE `path`, as the runtime's own classifier reads it?
  *
@@ -555,12 +665,7 @@ function policyFileEvidence(material, path, policyProtectedPaths) {
     const map = material;
     const tool = map["tool"];
     const file = map["file"];
-    if (typeof file !== "string" ||
-        file.startsWith("/") ||
-        file.includes("\\"))
-        return null;
-    const named = segmentsOf(file);
-    if (named.includes("..") || named.join("/") !== segmentsOf(path).join("/"))
+    if (typeof file !== "string" || !namesProtectedFile(file, path))
         return null;
     const keys = Object.keys(map);
     const hasOnly = (allowed) => keys.every((key) => allowed.includes(key));
@@ -612,6 +717,28 @@ function hasAmbiguousRoute(path, policyProtectedPaths) {
     }
     return classes.size > 1;
 }
+/** Normalize whatever the caller supplied into one {@link ChangeAnchor}. */
+function changeAnchorOf(supplied) {
+    const pair = supplied === null || typeof supplied === "string"
+        ? { author: supplied, committer: supplied }
+        : supplied;
+    const authorTs = pair.author ?? pair.committer;
+    const committerTs = pair.committer ?? pair.author;
+    const parse = (ts) => {
+        if (ts === null)
+            return null;
+        const ms = Date.parse(ts);
+        return Number.isNaN(ms) ? null : ms;
+    };
+    const authorMs = parse(authorTs);
+    const committerMs = parse(committerTs);
+    return {
+        authorTs,
+        committerTs,
+        authorMs: authorMs ?? committerMs,
+        committerMs: committerMs ?? authorMs,
+    };
+}
 /**
  * Exact-file evidence from an unattended execution authorized by policy.
  *
@@ -619,7 +746,7 @@ function hasAmbiguousRoute(path, policyProtectedPaths) {
  * committed payload must hash back to that declaration. A prior request means
  * the action entered the human-decision path, so this tier cannot carry it.
  */
-function policyAuthorizedEvidence(records, start, path, policyProtectedPaths, payloadFor, anchorMs, lookbackMs) {
+function policyAuthorizedEvidence(records, start, path, policyProtectedPaths, payloadFor, anchor, lookbackMs) {
     if (start.event !== "execution.started")
         return null;
     const task = start.task;
@@ -657,12 +784,15 @@ function policyAuthorizedEvidence(records, start, path, policyProtectedPaths, pa
         record.action_key === actionKey &&
         record.event === "approval.requested"))
         return null;
-    // A start cannot authorize a change that already happened. This tier also
-    // requires a usable commit timestamp; missing temporal evidence fails closed.
-    if (anchorMs === null)
+    // A start cannot authorize a change that already happened, and a start from
+    // months ago is about some earlier edit. Ordering is asked of the COMMITTER
+    // date and staleness of the AUTHOR date (APRV-339). This tier also requires a
+    // usable commit timestamp; missing temporal evidence fails closed.
+    const { authorMs, committerMs } = anchor;
+    if (authorMs === null || committerMs === null)
         return null;
     const at = Date.parse(start.ts);
-    if (Number.isNaN(at) || at > anchorMs || anchorMs - at > lookbackMs)
+    if (Number.isNaN(at) || at > committerMs || authorMs - at > lookbackMs)
         return null;
     const material = payloadFor(hash);
     if (material === null)
@@ -676,7 +806,7 @@ function policyAuthorizedEvidence(records, start, path, policyProtectedPaths, pa
     }
     return policyFileEvidence(material, path, policyProtectedPaths);
 }
-/** The closed, repository-relative Edit shape eligible for byte replay. */
+/** The closed Edit shape, naming this path, eligible for byte replay. */
 function exactReplayEdit(material, path) {
     if (typeof material !== "object" || material === null || Array.isArray(material))
         return null;
@@ -687,8 +817,7 @@ function exactReplayEdit(material, path) {
         return null;
     if (map["tool"] !== "Edit" ||
         typeof map["file"] !== "string" ||
-        map["file"].startsWith("/") ||
-        map["file"].includes("\\") ||
+        !namesProtectedFile(map["file"], path) ||
         (map["rule"] !== undefined && typeof map["rule"] !== "string") ||
         typeof map["before"] !== "string" ||
         map["before"].length === 0 ||
@@ -696,17 +825,12 @@ function exactReplayEdit(material, path) {
         map["before"] === map["after"] ||
         (map["replace_all"] !== undefined && map["replace_all"] !== false))
         return null;
-    const named = segmentsOf(map["file"]);
-    const changed = segmentsOf(path);
-    if (named.includes("..") ||
-        named.length !== changed.length ||
-        !named.every((segment, index) => segment === changed[index]))
-        return null;
     return { before: map["before"], after: map["after"] };
 }
 /** The one token or harness spend that proves this manual grant actually ran. */
-function startForReplayGrant(candidate, records, anchorMs, lookbackMs, path, policyProtectedPaths) {
-    if (anchorMs === null)
+function startForReplayGrant(candidate, records, anchor, lookbackMs, path, policyProtectedPaths) {
+    const { authorMs, committerMs } = anchor;
+    if (authorMs === null || committerMs === null)
         return null;
     const grant = candidate.record;
     const task = grant.task;
@@ -752,8 +876,10 @@ function startForReplayGrant(candidate, records, anchorMs, lookbackMs, path, pol
         if (hasTokenLink &&
             (typeof grantToken !== "string" || started["token_sha256"] !== grantToken))
             return false;
+        // Ordering against the committer date, staleness against the author date
+        // (APRV-339), exactly as the policy-authorized tier asks them.
         const at = Date.parse(record.ts);
-        return !Number.isNaN(at) && at <= anchorMs && anchorMs - at <= lookbackMs;
+        return !Number.isNaN(at) && at <= committerMs && authorMs - at <= lookbackMs;
     });
     if (starts.length !== 1)
         return null;
@@ -795,7 +921,7 @@ function startForReplayGrant(candidate, records, anchorMs, lookbackMs, path, pol
  * examined. Crossing any bound refuses the fallback rather than pruning a
  * potentially valid branch and claiming the remaining search was complete.
  */
-function exactEditReplay(candidates, records, base, head, anchorMs, lookbackMs, path, policyProtectedPaths) {
+function exactEditReplay(candidates, records, base, head, anchor, lookbackMs, path, policyProtectedPaths) {
     if (base === null ||
         head === null ||
         base.includes("\uFFFD") ||
@@ -815,7 +941,7 @@ function exactEditReplay(candidates, records, base, head, anchorMs, lookbackMs,
             continue;
         const start = candidate.source === "policy"
             ? candidate.record
-            : startForReplayGrant(candidate, records, anchorMs, lookbackMs, path, policyProtectedPaths);
+            : startForReplayGrant(candidate, records, anchor, lookbackMs, path, policyProtectedPaths);
         if (start !== null)
             gathered.push({ candidate, start, ...edit });
     }
@@ -912,6 +1038,38 @@ function linesOf(text) {
         parts.pop();
     return parts;
 }
+/**
+ * Where a fragment anchors in the blob at base, and what replacing it yields.
+ *
+ * `null` unless the fragment sits inside ONE line and occurs exactly once in
+ * the whole file: a fragment with two homes does not say which occurrence the
+ * human approved, and a guess is not evidence. A fragment carrying a newline is
+ * not line-local at all and belongs to the global replay.
+ *
+ * Applying a uniquely-anchored edit to base can only produce base with that one
+ * line rewritten, so this is a one-step replay stated as the line it changes —
+ * the arithmetic the caller then checks against the hunks (APRV-340).
+ */
+function lineLocalReplacement(baseLines, edit) {
+    if (edit.before.includes("\n"))
+        return null;
+    let found = null;
+    for (const line of baseLines) {
+        const first = line.indexOf(edit.before);
+        if (first === -1)
+            continue;
+        if (found !== null || line.indexOf(edit.before, first + 1) !== -1)
+            return null;
+        found = { line, at: first };
+    }
+    if (found === null)
+        return null;
+    const { line, at } = found;
+    return {
+        removed: line,
+        added: `${line.slice(0, at)}${edit.after}${line.slice(at + edit.before.length)}`,
+    };
+}
 /** A line that carries content. Blank lines neither need coverage nor give it. */
 function substantive(line) {
     return line.trim().length > 0;
@@ -984,8 +1142,8 @@ function windowText(window) {
 }
 /**
  * How far past the change commit a run may still start and be its cause: five
- * minutes, for clock disagreement between the log and git's author date. It is
- * a skew allowance, not an ordering allowance.
+ * minutes, for clock disagreement between the log and git's committer date. It
+ * is a skew allowance, not an ordering allowance.
  */
 const SKEW_GRACE_MS = 5 * 60 * 1000;
 /** Milliseconds as something a failure message can say out loud. */
@@ -1009,7 +1167,12 @@ function spanText(ms) {
  * interval it actually occupied: a batch that started before the commit and
  * finished after it brackets the commit, which is the strongest form of this.
  */
-function attributeRun(grant, runs, anchorMs, attributionMs) {
+function attributeRun(grant, runs, anchor, attributionMs) {
+    // The same split the other two tiers make (APRV-339): "did this run start
+    // after the bytes were committed" is asked of the COMMITTER date, which an
+    // amend may only move later, and "how far from the change is it" of the
+    // AUTHOR date, which a rebase does not move.
+    const { authorMs, committerMs } = anchor;
     const key = grant.action_key;
     if (key === undefined) {
         return {
@@ -1027,7 +1190,7 @@ function attributeRun(grant, runs, anchorMs, attributionMs) {
     }
     const completed = tied.filter((record) => record.event === "execution.completed");
     const endOf = (record) => completed.find((done) => done.seq > record.seq);
-    if (anchorMs === null) {
+    if (authorMs === null || committerMs === null) {
         const first = started[0];
         return {
             ok: true,
@@ -1040,7 +1203,7 @@ function attributeRun(grant, runs, anchorMs, attributionMs) {
     // the record is appended before the process is spawned. The real log shows
     // what the symmetric window costs — a SPEC.md batch run four hours AFTER
     // PR #187's commit would otherwise have carried that commit's changes.
-    // `SKEW_GRACE_MS` is for the two clocks (the log's and git's author date)
+    // `SKEW_GRACE_MS` is for the two clocks (the log's and git's committer date)
     // disagreeing, not for ordering.
     let best = null;
     let laterOnly = null;
@@ -1048,7 +1211,7 @@ function attributeRun(grant, runs, anchorMs, attributionMs) {
         const from = Date.parse(record.ts);
         if (Number.isNaN(from))
             continue;
-        if (from > anchorMs + SKEW_GRACE_MS) {
+        if (from > committerMs + SKEW_GRACE_MS) {
             if (laterOnly === null)
                 laterOnly = record;
             continue;
@@ -1056,9 +1219,9 @@ function attributeRun(grant, runs, anchorMs, attributionMs) {
         const end = endOf(record);
         const to = end === undefined ? from : Date.parse(end.ts);
         const upper = Number.isNaN(to) ? from : to;
-        const distance = anchorMs >= Math.min(from, upper) && anchorMs <= Math.max(from, upper)
+        const distance = authorMs >= Math.min(from, upper) && authorMs <= Math.max(from, upper)
             ? 0
-            : Math.min(Math.abs(from - anchorMs), Math.abs(upper - anchorMs));
+            : Math.min(Math.abs(from - authorMs), Math.abs(upper - authorMs));
         if (best === null || distance < best.distance)
             best = { record, end, distance };
     }
@@ -1098,6 +1261,40 @@ function attributeRun(grant, runs, anchorMs, attributionMs) {
 function organKey(organPath, sha256) {
     return `${normalizePathSpelling(organPath)}\0${sha256}`;
 }
+/**
+ * May this path be evidenced by a `gate.path.signed_off` record? (APRV-338.)
+ *
+ * `policy.edit` and its sub-classes, and nothing else. The organs and the
+ * approval home are `policy.core` and answered by their own record; the log
+ * directory is `log.mutate` and answered by nobody. Asked with the policy's own
+ * entries, so a path a project routed to `policy.edit.design` is signable while
+ * a path no list protects is not.
+ */
+function signOffEligible(path, extra) {
+    const routed = protectedPathClass(path, extra);
+    return routed === "policy.edit" || (routed !== null && POLICY_EDIT_SUBCLASS.test(routed));
+}
+/**
+ * The sentence a failing `policy.edit` path gets about the sign-off route, or
+ * nothing at all.
+ *
+ * Deliberately last in every message it appears in, and deliberately hedged.
+ * The first repair for an uncovered change is to take it to the gate, which
+ * binds the hunk; a sign-off stands for the whole file and is what the
+ * pending-sign-off suffix was invented for — text a human has read at this
+ * commit and agrees with. Printing it first would read as an invitation to
+ * route around the gate, which is the one thing this guard exists to notice.
+ */
+function signOffRepair(path, digest) {
+    if (digest === null)
+        return "";
+    // The two flags are named because the digest is the thing that has to match,
+    // and the bytes under review are on the BRANCH while the log lives in the
+    // primary checkout. `--dir` says which bytes to hash and `--log` says where
+    // the record goes, so one command can span both without the log ever being
+    // written from a worktree.
+    return ` If a human has READ this change at this commit and stands behind the file as it now is, they may ratify it with \`approval policy attest --path ${path} --dir <a checkout at this commit> --log <the primary checkout's log> --as human:<id>\`, which must hash to ${digest}, followed by a log advance carrying that record; that is whole-file evidence and weaker than a grant, so prefer the gate wherever the edit can still go through it.`;
+}
 /** The ordering rule, stated identically on every failure that could be lag. */
 const ORDERING_RULE = "the committed log trails the primary checkout's live log, so if this edit WAS granted, " +
     "the log advance carrying the grant must be pushed to a records branch or merged to main " +
@@ -1162,6 +1359,18 @@ export function evaluateProtectedPaths(input) {
             continue;
         organAttestations.set(organKey(fields.organPath, fields.sha256), record);
     }
+    // The SIGN-OFF index (APRV-338), keyed the same way and fed by its own event
+    // type, so a sign-off can never answer an organ's question or the policy
+    // file's and neither can answer a sign-off's. Built here and consulted at the
+    // END of each path's evidence search: see the module note on why hunk
+    // evidence has to be preferred over whole-file evidence.
+    const signOffs = new Map();
+    for (const record of records) {
+        const fields = pathSignOffOf(record);
+        if (fields === null)
+            continue;
+        signOffs.set(organKey(fields.path, fields.sha256), record);
+    }
     // The grants of a class that can authorize a protected write.
     const grants = records.filter((record) => record.event === "approval.granted" &&
         isGrantingClass(String(payloadOf(record)["class"] ?? "")));
@@ -1186,8 +1395,7 @@ export function evaluateProtectedPaths(input) {
     const findings = [];
     for (const path of guarded) {
         // 1. The policy file, by attestation.
-        if (endsWithSegments(input.policyPath, path) ||
-            endsWithSegments(path, input.policyPath)) {
+        if (namesPolicyFile(path, input.policyPath)) {
             if (input.policySha256AtHead !== null) {
                 const attested = attestations.get(input.policySha256AtHead);
                 if (attested !== undefined) {
@@ -1235,18 +1443,24 @@ export function evaluateProtectedPaths(input) {
         const lookbackMs = input.lookbackMs ?? DEFAULT_LOOKBACK_MS;
         // ONE derivation of the anchor, so the bound that is enforced and the bound
         // that is reported cannot disagree. An unparseable timestamp is no anchor,
-        // exactly as a missing one is not: both land in `anchorMs === null`.
-        const parsed = changeTs === null ? Number.NaN : Date.parse(changeTs);
-        const anchorMs = Number.isNaN(parsed) ? null : parsed;
+        // exactly as a missing one is not: both land in `anchorMs === null`. Two
+        // instants since APRV-339, and the one asked here is the AUTHOR date: this
+        // is the staleness pre-filter, and ordering belongs to the tiers that can
+        // say which record wrote which bytes.
+        const anchor = changeAnchorOf(changeTs);
+        const anchorMs = anchor.authorMs;
         const inWindow = (ts) => {
             if (anchorMs === null)
                 return true;
             const at = Date.parse(ts);
             return !Number.isNaN(at) && Math.abs(at - anchorMs) <= lookbackMs;
         };
+        const datedText = anchor.committerTs === null || anchor.committerTs === anchor.authorTs
+            ? `${anchor.authorTs}`
+            : `authored ${anchor.authorTs}, committed ${anchor.committerTs}`;
         const boundText = anchorMs === null
-            ? `no usable commit timestamp for this path (${changeTs === null ? "git named none" : `git named ${JSON.stringify(changeTs)}, which does not parse`}), so NO recency bound was applied and this evidence rests on the path match alone`
-            : `within ${Math.round(lookbackMs / 86_400_000)}d of the commit that changed it (${changeTs})`;
+            ? `no usable commit timestamp for this path (${anchor.authorTs === null ? "git named none" : `git named ${JSON.stringify(datedText)}, which does not parse`}), so NO recency bound was applied and this evidence rests on the path match alone`
+            : `within ${Math.round(lookbackMs / 86_400_000)}d of the commit that changed it (${datedText})`;
         // EVERY qualifying grant is collected and the best one is reported, rather
         // than the first one found. The first-match version passed commit 41d2c9f
         // on a `cp SPEC.md <dir>/` granted four days earlier while the grant that
@@ -1276,7 +1490,7 @@ export function evaluateProtectedPaths(input) {
             candidates.push({ record: grant, match: found, source: "grant", material, payloadHash: hash });
         }
         for (const start of records) {
-            const found = policyAuthorizedEvidence(records, start, path, input.policyProtectedPaths, input.payloadFor, anchorMs, lookbackMs);
+            const found = policyAuthorizedEvidence(records, start, path, input.policyProtectedPaths, input.payloadFor, anchor, lookbackMs);
             const hash = payloadOf(start)["payload_hash"];
             if (found !== null && typeof hash === "string") {
                 const material = input.payloadFor(hash);
@@ -1337,7 +1551,7 @@ export function evaluateProtectedPaths(input) {
                     rejected.push(`${at} writes ${JSON.stringify(match.target ?? "")} from ${JSON.stringify(match.cwd ?? "(no cwd recorded)")}, which is not this checkout's ${path}: a granted write to a copy of the file elsewhere (a dry run into a scratch directory, another worktree) authorizes nothing here`);
                     continue;
                 }
-                const run = attributeRun(record, runs, anchorMs, attributionMs);
+                const run = attributeRun(record, runs, anchor, attributionMs);
                 if (!run.ok) {
                     rejected.push(run.why);
                     continue;
@@ -1400,6 +1614,71 @@ export function evaluateProtectedPaths(input) {
                 contributors.push({ record, kind: match.kind, why: contributed, whole: wholeHere, source });
             }
         }
+        // One fragment inside one line, credited by bytes alone (APRV-340).
+        //
+        // The hook binds exactly what the Edit tool replaced, so an edit that
+        // rewrites part of a long paragraph binds a fragment and whole-line set
+        // membership cannot credit either line. That used to leave only the global
+        // replay, which on a 200 KB file with forty naming candidates refuses on
+        // its byte limit before it can reach a proof (PR #393, the fragment inside
+        // SPEC.md line 139). A uniquely-anchored fragment needs no search: applying
+        // it to base can only produce base with that ONE line rewritten, so if the
+        // line it rewrites is a line this change removes and the line it produces
+        // is a line this change adds, the bytes have proved both lines at the cost
+        // of one scan. Every eligibility condition is the global replay's own — the
+        // material rehashed, the Edit shape naming this path, and the same start
+        // resolution, which for a grant is the registration, the request, the
+        // class, the spend and the timing. A line-local step substitutes for none
+        // of them; it only spends less to ask the same question.
+        //
+        // Bytes that did not decode are not bytes anyone can prove anything about,
+        // so a blob carrying U+FFFD is refused here exactly as the replay refuses
+        // it: byte equality against a lossy decoding says nothing.
+        if (!whole &&
+            !hunks.identical &&
+            !baseText.includes("\uFFFD") &&
+            !headText.includes("\uFFFD")) {
+            const baseLines = linesOf(baseText);
+            const addsLine = new Set(hunks.added);
+            const removesLine = new Set(hunks.removed);
+            for (const candidate of candidates) {
+                const edit = exactReplayEdit(candidate.material, path);
+                if (edit === null)
+                    continue;
+                try {
+                    if (payloadHash(candidate.material) !== candidate.payloadHash)
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                const start = candidate.source === "policy"
+                    ? candidate.record
+                    : startForReplayGrant(candidate, records, anchor, lookbackMs, path, input.policyProtectedPaths);
+                if (start === null)
+                    continue;
+                const local = lineLocalReplacement(baseLines, edit);
+                if (local === null)
+                    continue;
+                if (!removesLine.has(local.removed) || !addsLine.has(local.added))
+                    continue;
+                addedCover.add(local.added);
+                removedCover.add(local.removed);
+                const why = `replacing that fragment in the one line of the blob at base that carries it yields a line this change adds, and that base line is one this change removes (line-local replay at execution.started seq ${start.seq})`;
+                const already = contributors.find((one) => one.record.seq === candidate.record.seq);
+                if (already === undefined) {
+                    contributors.push({
+                        record: candidate.record,
+                        kind: candidate.match.kind,
+                        why: `${candidate.match.detail}, and ${why}`,
+                        whole: false,
+                        source: candidate.source,
+                    });
+                    continue;
+                }
+                already.why = `${already.why}, and ${why}`;
+            }
+        }
         // Exact Edit payloads may bind fragments within a line, including several
         // independent fragments of the same long line. Whole-line set membership
         // cannot express that safely. Replay is the bounded fallback: genuine
@@ -1410,7 +1689,7 @@ export function evaluateProtectedPaths(input) {
                 hunks.added.some((line) => !addedCover.has(line)) ||
                 hunks.removed.some((line) => !removedCover.has(line)));
         const replay = needsReplay
-            ? exactEditReplay(candidates, records, blobs.base, blobs.head, anchorMs, lookbackMs, path, input.policyProtectedPaths)
+            ? exactEditReplay(candidates, records, blobs.base, blobs.head, anchor, lookbackMs, path, input.policyProtectedPaths)
             : { steps: null, bound: null };
         if (replay.bound !== null) {
             rejected.unshift(`exact BASE-to-HEAD replay refused after reaching its ${replay.bound.replace("-", " ")}`);
@@ -1487,6 +1766,35 @@ export function evaluateProtectedPaths(input) {
             });
             continue;
         }
+        // The LAST thing tried for this path, and deliberately last: a human's
+        // whole-file sign-off (APRV-338).
+        //
+        // Everything above is hunk evidence, and everything above has now failed
+        // to cover this change. Only here does the guard ask the weaker question —
+        // did a human read this file at exactly these bytes and say so — and the
+        // finding says in words that this is what it rests on, so a reader can
+        // never mistake it for a grant. Running it here rather than beside the
+        // organ verdict is what keeps that true: consulted first, a sign-off would
+        // have silently answered for every change a grant already covered, and the
+        // reasons this guard prints are half its value.
+        const signOffDigest = signOffEligible(path, input.policyProtectedPaths)
+            ? (input.pathSha256AtHead?.(path) ?? null)
+            : null;
+        if (signOffDigest !== null) {
+            const signed = signOffs.get(organKey(path, signOffDigest));
+            if (signed !== undefined) {
+                findings.push({
+                    path,
+                    ok: true,
+                    evidence: "attested",
+                    seq: signed.seq,
+                    ts: signed.ts,
+                    actor: signed.actor,
+                    detail: `${path} at ${input.window.head} hashes to ${signOffDigest}, which ${signed.actor} signed off FOR THAT PATH at seq ${signed.seq}. This is WHOLE-FILE evidence and weaker than a grant: it says a human read this file at these exact bytes, not that they saw this hunk. It was read only because no grant covers this change — ${candidates.length} ${evidenceNoun} name this path ${boundText}${contributors.length > 0 ? `, and ${contributors.length} of them covered part of it (seq ${contributors.map((one) => one.record.seq).join(", ")})` : ""}`,
+                });
+                continue;
+            }
+        }
         // Naming grants exist and the change is not made of them: the repeat-edit
         // shape. Its own code, because the reader's next move differs from
         // `no-evidence` — take THIS change to the gate, rather than hunt for a
@@ -1502,7 +1810,7 @@ export function evaluateProtectedPaths(input) {
                     ? `${contributors.length} evidence record${contributors.length === 1 ? "" : "s"} covered part of it (seq ${contributors.map((one) => one.record.seq).join(", ")}); `
                     : ""}${rejected.length > 0
                     ? `${rejected.slice(0, 6).join("; ")}${rejected.length > 6 ? `; … and ${rejected.length - 6} other naming grants set aside for the same kinds of reason` : ""}. `
-                    : ""}uncovered: ${sample.map((line) => JSON.stringify(line)).join(", ")}${uncovered.length > sample.length ? `, … ${uncovered.length - sample.length} more` : ""}. ${windowText(input.window)}. ${ORDERING_RULE}.`,
+                    : ""}uncovered: ${sample.map((line) => JSON.stringify(line)).join(", ")}${uncovered.length > sample.length ? `, … ${uncovered.length - sample.length} more` : ""}. ${windowText(input.window)}. ${ORDERING_RULE}.${signOffRepair(path, signOffDigest)}`,
             });
             continue;
         }
@@ -1516,10 +1824,16 @@ export function evaluateProtectedPaths(input) {
         if (unresolved.length > 0) {
             diagnosis.push(`${unresolved.length} grant payload${unresolved.length === 1 ? "" : "s"} could not be resolved from the committed payload store (${unresolved.slice(0, 3).join(", ")}${unresolved.length > 3 ? ", …" : ""}), and a grant whose bytes cannot be read is not evidence for any path`);
         }
-        if ((endsWithSegments(input.policyPath, path) || endsWithSegments(path, input.policyPath)) &&
-            input.policySha256AtHead !== null) {
+        if (namesPolicyFile(path, input.policyPath) && input.policySha256AtHead !== null) {
             diagnosis.push(`no policy.updated record attests the bytes this pull request would install (${input.policySha256AtHead}); an amendment lands through \`approval policy amend --commit\`, whose attestation record is the evidence`);
         }
+        if (signOffDigest !== null) {
+            // A protected path that COULD have been signed off and was not. Named
+            // second to the grant advice above, not first: taking the edit to the
+            // gate binds the hunk, and a sign-off stands for the whole file
+            // (APRV-338).
+            diagnosis.push(`no gate.path.signed_off record signs off ${path} at ${signOffDigest}, and a digest signed for some OTHER path is not evidence for this one`);
+        }
         if (isGateOrganPath(path)) {
             // The one failure in this guard whose repair is NOT "take the change to
             // the gate": there is no gate for it. `policy.core` is human-only, the
@@ -1535,7 +1849,7 @@ export function evaluateProtectedPaths(input) {
             path,
             ok: false,
             code: "no-evidence",
-            detail: `${path} is a protected path (edits classify policy.edit) and changed between ${input.window.base} and ${input.window.head}, and the committed log carries no evidence that a human decided it. ${windowText(input.window)}. ${diagnosis.join("; ")}. ${ORDERING_RULE}.`,
+            detail: `${path} is a protected path (edits classify policy.edit) and changed between ${input.window.base} and ${input.window.head}, and the committed log carries no evidence that a human decided it. ${windowText(input.window)}. ${diagnosis.join("; ")}. ${ORDERING_RULE}.${signOffRepair(path, signOffDigest)}`,
         });
     }
     return {