approval-md 0.4.2 → 0.4.5

package/dist/src/core/command-class.js

@@ -47,6 +47,8 @@
  * of those doors and leave the other open. The import is type-safe in the
  * dependency sense as well: `policy-match.ts` itself imports only types.
  */
+import { isDateDisplay } from "./date-argv.js";
+import { isBareInfo, isDfDisplay, isFreeDisplay, isHostnameDisplay, isPasteRead, isSeqDisplay, } from "./sysinfo-argv.js";
 import { HARNESS_LAUNCH_PREFIX } from "./policy-match.js";
 import { READ_OUT_OF_SCOPE_CLASS, isUnreadableTarget, readTargetVerdict, readTargetsOf, } from "./read-scope.js";
 /**
@@ -674,11 +676,19 @@ function secretEnvReference(word) {
  * appear in the log" invariant survives a refusal message that names what it
  * refused.
  */
-function credentialTouch(basename, args, positionals) {
+/**
+ * Does this binary only WRITE the paths it names? ({@link CREDENTIAL_WRITE_BINS}
+ * plus `sed -i`.) Then a credential path among its positionals is a write to the
+ * gate's directory rather than a read of the material.
+ */
+function credentialWritesOnly(basename, args) {
     const inPlaceSed = basename === "sed" &&
         (hasFlag(args, ["--in-place"]) ||
             args.some((arg) => arg.startsWith("-i") && !arg.startsWith("--")));
-    const writesOnly = CREDENTIAL_WRITE_BINS.includes(basename) || inPlaceSed;
+    return CREDENTIAL_WRITE_BINS.includes(basename) || inPlaceSed;
+}
+function credentialTouch(basename, args, positionals) {
+    const writesOnly = credentialWritesOnly(basename, args);
     if (!writesOnly) {
         const named = positionals.find((arg) => isCredentialPath(arg));
         if (named !== undefined) {
@@ -692,6 +702,42 @@ function credentialTouch(basename, args, positionals) {
     }
     return null;
 }
+/**
+ * Is this segment a credential touch through a REDIRECTION? (APRV-503.)
+ *
+ * The same two shapes {@link credentialTouch} reads from the argument list, read
+ * from the redirection targets, which the lexer keeps out of the word list. An
+ * input redirection's direction is known in a way a positional's is not: `<`
+ * (and `0<`, `3<`, any descriptor) opens its target for READING, whatever the
+ * binary in front of it is, so a credential file there is a read of the
+ * material and the {@link CREDENTIAL_WRITE_BINS} exemption does not apply
+ * (`tee out.txt < .approval/env` copies the secret out). Until this, `cat <
+ * ~/.hermes/.env` was `read.shell` while `cat ~/.hermes/.env` was
+ * `account.credential`, and so was `echo "$(< ~/.hermes/.env)"`, the bash idiom
+ * whose inner command is nothing but the redirection.
+ *
+ * A secret-named variable in ANY redirection target, read or write, carries the
+ * secret the way it does in an argument: the shell expands it into a file name,
+ * and a missing file prints that name on stderr.
+ *
+ * The rule id is the argument rule's own, so a channel, a doc table and a
+ * policy reader see one mechanism; `path` names the target word.
+ *
+ * This answers WHETHER a redirect touches credential material, not which
+ * class the segment takes: `classifySegment` defers it whenever the segment
+ * names a protected path that outranks the credential class
+ * ({@link outranksCredential}), so a redirect can never loosen an answer.
+ */
+function redirectCredentialTouch(readTargets, allTargets) {
+    const named = readTargets.find((target) => isCredentialPath(target));
+    if (named !== undefined) {
+        return { class: CREDENTIAL_CLASS, rule: "credential-path", path: named };
+    }
+    if (allTargets.some((target) => secretEnvReference(target) !== null)) {
+        return { class: CREDENTIAL_CLASS, rule: "credential-env" };
+    }
+    return null;
+}
 /** `printenv` prints one variable, or all of them. */
 function refinePrintenv(ctx) {
     if (ctx.positionals.length === 0) {
@@ -746,21 +792,24 @@ function lex(command) {
     const segments = [];
     let words = [];
     let redirects = [];
+    let bodySubstitutions = [];
     let opaque = null;
     let segmentStart = 0;
     let index = 0;
     const pending = [];
     const flush = (end) => {
-        if (words.length > 0 || redirects.length > 0 || opaque !== null) {
+        if (words.length > 0 || redirects.length > 0 || bodySubstitutions.length > 0 || opaque !== null) {
             segments.push({
                 text: command.slice(segmentStart, end).trim(),
                 words,
                 redirects,
+                bodySubstitutions,
                 opaque,
             });
         }
         words = [];
         redirects = [];
+        bodySubstitutions = [];
         opaque = null;
         segmentStart = end;
     };
@@ -863,13 +912,26 @@ function lex(command) {
             const boundary = index;
             index += 1;
             // Heredoc bodies belong to the line that opened them, so they are
-            // consumed here and never classified. A body is data, not commands.
+            // consumed here. A quoted delimiter's body is data. An UNQUOTED one is
+            // expanded by the shell when it is read (APRV-504, folded into
+            // APRV-508): its `$(…)` run, so they are collected for recursive
+            // classification, and a backtick or an arithmetic expansion there is
+            // opaque, exactly as inside double quotes.
             while (pending.length > 0) {
                 const heredoc = pending.shift();
                 const consumed = skipHeredocBody(command, index, heredoc);
                 if (consumed === null) {
                     return { ok: false, detail: `heredoc <<${heredoc.terminator} is never terminated` };
                 }
+                if (heredoc.expands) {
+                    const body = heredocBodyExpansions(command, index, consumed);
+                    if (body === null) {
+                        return { ok: false, detail: `heredoc <<${heredoc.terminator} has a substitution that does not close` };
+                    }
+                    bodySubstitutions.push(...body.substitutions);
+                    if (body.opaque !== null)
+                        opaque = body.opaque;
+                }
                 index = consumed;
             }
             flush(boundary);
@@ -881,20 +943,71 @@ function lex(command) {
         if (redirect !== null) {
             const op = redirect[2];
             index += redirect[0].length;
+            if (op === "<<" && command[index] === "<") {
+                // A here-string (`<<<word`). Refused, as it always was, and named
+                // (APRV-503): the shell expands its word, and that word is the
+                // command's stdin. Parsing it would only ever loosen a refusal
+                // (`cat <<< hello` would become a read), while a credential read
+                // through it already has spellings that classify, so the refusal is
+                // the fail-closed answer and the detail says how to rewrite it.
+                return {
+                    ok: false,
+                    detail: "a here-string (<<<) is not read by this classifier; pipe the text in with printf or name the file as an argument",
+                };
+            }
             if (op === "<<" || op === "<<-") {
                 while (command[index] === " " || command[index] === "\t")
                     index += 1;
+                const delimiterStart = index;
                 const terminator = readWord();
                 if (terminator === null) {
                     return { ok: false, detail: "heredoc has no terminator word" };
                 }
-                pending.push({ terminator: terminator.text, stripTabs: op === "<<-" });
+                // APRV-508: bash takes a heredoc delimiter literally (quote removal
+                // only, no expansion), while `readWord` sets a substitution's text
+                // aside. So `cat <<$(x)` waited here for a terminator line bash never
+                // looks for, and every command line after bash's real terminator was
+                // swallowed as body and never classified. A delimiter carrying `$` or
+                // a backtick is refused rather than guessed at.
+                if (/[$`]/u.test(command.slice(delimiterStart, index))) {
+                    return {
+                        ok: false,
+                        detail: "a heredoc delimiter carrying $ or a backtick is not read by this classifier; use a plain word such as EOF",
+                    };
+                }
+                const raw = command.slice(delimiterStart, index);
+                pending.push({
+                    terminator: terminator.text,
+                    stripTabs: op === "<<-",
+                    expands: !terminator.quoted && !raw.includes("\\"),
+                });
                 continue;
             }
             if (op === ">&" || op === "<&") {
-                // `2>&1` and friends: a file descriptor dup, no path involved.
-                while (index < command.length && /[\d-]/u.test(command[index]))
+                // `2>&1`, `>&2`, `3<&0`, `2>&-`: a descriptor dup or close, no path
+                // involved. Anything else after `>&` is a FILE (APRV-508 refutation
+                // M1): bash reads `>&word` as `>word 2>&1`, so `paste a >& APPROVAL.md`
+                // truncates the policy file. The word is read in full, as the shell
+                // reads it, and is a dup only when it is exactly digits with an
+                // optional trailing `-`, or a lone `-`. A word whose value the text
+                // cannot settle (`>&$fd`) is taken as a file: a write is the stricter
+                // reading. After `<&` a non-descriptor word is refused.
+                while (command[index] === " " || command[index] === "\t")
                     index += 1;
+                const target = readWord();
+                if (target === null || target.text === "") {
+                    return { ok: false, detail: `redirection ${op} has no target` };
+                }
+                const dup = target.substitutions.length === 0 && (/^\d+-?$/u.test(target.text) || target.text === "-");
+                if (dup)
+                    continue;
+                if (op === "<&") {
+                    return {
+                        ok: false,
+                        detail: `redirection <&${target.text} names no file descriptor; this classifier does not read it`,
+                    };
+                }
+                redirects.push({ op: ">", target });
                 continue;
             }
             while (command[index] === " " || command[index] === "\t")
@@ -913,6 +1026,18 @@ function lex(command) {
             segmentStart = index;
             continue;
         }
+        // A comment (APRV-508, found by the shell differential). bash ends the
+        // line at a `#` that begins a word, so `cat #<<EOF` is `cat` and the
+        // lines after it are commands; read as a word, the `#<<EOF` opened a
+        // heredoc here and swallowed them. The comment runs to the newline, which
+        // is left for the loop. Only a `#` after a space, a tab, a newline or an
+        // operator begins a word to bash; after a carriage return (whitespace to
+        // this loop, a word character to bash) it does not, and is read as a word.
+        if (ch === "#" && (index === 0 || /[ \t\n;&|()<>]/u.test(command[index - 1]))) {
+            const newline = command.indexOf("\n", index);
+            index = newline === -1 ? command.length : newline;
+            continue;
+        }
         const word = readWord();
         if (word === null) {
             return { ok: false, detail: "unterminated quote or command substitution" };
@@ -1036,6 +1161,45 @@ function closingDoubleQuote(command, start) {
     return null;
 }
 /** Consume a heredoc body; returns the index after it, or `null` if unclosed. */
+/**
+ * The expansions in an unquoted heredoc body, `command[start, end)`: every
+ * `$(…)` for recursive classification, and a backtick or an arithmetic
+ * expansion as opaque. A backslash escapes the next character, as it does in a
+ * body; quotes are literal there, except inside a `$(…)`, which
+ * {@link readSubstitution} scans as the shell does. `null` when a substitution
+ * runs past the body.
+ */
+function heredocBodyExpansions(command, start, end) {
+    const substitutions = [];
+    let opaque = null;
+    for (let index = start; index < end; index += 1) {
+        const ch = command[index];
+        if (ch === "\\") {
+            index += 1;
+            continue;
+        }
+        if (ch === "`") {
+            opaque = "backtick command substitution in a heredoc body";
+            continue;
+        }
+        if (ch === "$" && command[index + 1] === "[") {
+            opaque = "arithmetic expansion in a heredoc body";
+            continue;
+        }
+        if (ch === "$" && command[index + 1] === "(") {
+            if (command[index + 2] === "(") {
+                opaque = "arithmetic expansion in a heredoc body";
+                continue;
+            }
+            const scan = readSubstitution(command, index + 1);
+            if (scan === null || scan.end >= end)
+                return null;
+            substitutions.push(scan.inner);
+            index = scan.end;
+        }
+    }
+    return { substitutions, opaque };
+}
 function skipHeredocBody(command, start, heredoc) {
     let index = start;
     for (;;) {
@@ -2473,9 +2637,143 @@ function refineApprovalVerb(positionals, args = []) {
 function refineApproval(ctx) {
     return (refineApprovalVerb(ctx.positionals, ctx.args) ?? { class: GATE_SELF_CLASS, rule: "approval" });
 }
+// ---------------------------------------------------------------------------
+// Skill scripts (APRV-502)
+// ---------------------------------------------------------------------------
+/**
+ * The class an interpreter run of a skill script takes: SPEC.md §7's
+ * `exec.local`, "tests, lint, build, scripts inside the workspace". No new
+ * class is minted; the classifier simply had no row that emitted this one.
+ */
+const SKILL_SCRIPT_CLASS = "exec.local";
+/** The rule id for `bun` / `python` / `python3` running a skill script. */
+export const SKILL_SCRIPT_RULE = "skill-script";
+/** The rule id `refineNode` returns for `node` running a skill script. */
+export const NODE_SKILL_SCRIPT_RULE = "node-skill-script";
+/**
+ * The flags an interpreter may carry BEFORE a skill script, per binary
+ * (APRV-502). An ALLOWLIST: a flag outside it, a `--flag=value`, a lone `-`
+ * (stdin) or `--` means the rule does not match at all, so the command keeps
+ * exactly the answer it had before this rule existed (`unclassified` for
+ * `bun --cwd /etc …` and `python3 -m x`, opaque for `python3 -c`, `node -e`).
+ *
+ * Every flag here is inert in the sense that matters: it changes neither WHICH
+ * file runs nor where code comes from. A flag that takes a value (`--cwd`,
+ * `--require`, `--import`, `-W`, `-X`) is absent on purpose, because its value
+ * would be a second thing the interpreter loads or a different directory the
+ * script path is read from. The same flags spelled through the environment
+ * (`BUN_OPTIONS`, `NODE_OPTIONS`, `PYTHONPATH`, `PYTHONSTARTUP`, `HOME`) are
+ * refused the same way: any `NAME=value` prefix on the segment declines the
+ * shape ({@link matchRule}, `RuleContext.assigned`).
+ */
+const SKILL_SCRIPT_FLAGS = {
+    bun: ["--bun", "--smol"],
+    node: ["--no-warnings", "--enable-source-maps", "--experimental-strip-types"],
+    python: [],
+    python3: [],
+};
+/**
+ * Python's inert single-letter flags, alone or clustered (`-I`, `-IB`, `-OO`):
+ * isolated mode, unbuffered, no bytecode, ignore `PYTHON*` variables, no user
+ * site, no `site` import, optimise, quiet. None of them takes a value, so a
+ * cluster cannot hide one; `-c`, `-m`, `-W` and `-X` are not letters here.
+ */
+const PYTHON_SKILL_SCRIPT_FLAGS = /^-[IuBEsSOq]+$/u;
+/**
+ * One segment of a skill-script path: non-empty, not `.` or `..`, not
+ * flag-shaped, and free of anything a shell could expand (`$`, backtick, a
+ * glob or brace character, a home shortcut) or a platform could read as a
+ * separator (`\`).
+ */
+function isSkillScriptSegment(segment) {
+    if (segment.length === 0 || segment === "." || segment === "..")
+        return false;
+    if (segment.startsWith("-"))
+        return false;
+    return !/[*?[\]{}$`~\\]/u.test(segment);
+}
+/**
+ * Is `word` a skill-script path, in exactly one of the two shapes (APRV-502)?
+ *
+ * - Relative: `skills/<skill>/scripts/<file>`, with any number of leading
+ *   `./` normalised away. Four segments, no more: `skills/x/scripts/sub/f.ts`
+ *   and `.hermes/skills/x/scripts/f.ts` are not this shape.
+ * - Absolute: a path ending `.hermes/skills/<skill>/scripts/<file>` or
+ *   `.hermes/profiles/<p>/skills/<skill>/scripts/<file>`, the same Hermes-home
+ *   grammar {@link protectedPathClass} reads (a profile home is a home of its
+ *   own, one level down).
+ *
+ * Every segment of either shape, the absolute prefix included, must pass
+ * {@link isSkillScriptSegment}: an empty segment (`skills//x`), a `.` or `..`
+ * anywhere, a glob, a variable or a backtick, and the shape does not match.
+ * An unexpanded `$HERMES_HOME/skills/…` or `~/.hermes/skills/…` is therefore
+ * not this rule; the text cannot say where it points.
+ *
+ * Text only, like everything in this file. Whether the file really sits in
+ * the directory it was spelled in is `src/cli/hook.ts`'s disk pass, which can
+ * only tighten this answer.
+ */
+export function isSkillScriptPath(word) {
+    if (word.startsWith("/")) {
+        const parts = word.slice(1).split("/");
+        if (!parts.every(isSkillScriptSegment))
+            return false;
+        const n = parts.length;
+        const tail = (offset) => parts[n - offset] === ".hermes" && parts[n - 4] === "skills" && parts[n - 2] === "scripts";
+        if (n >= 5 && tail(5))
+            return true;
+        return n >= 7 && parts[n - 6] === "profiles" && tail(7);
+    }
+    let rest = word;
+    while (rest.startsWith("./"))
+        rest = rest.slice(2);
+    const parts = rest.split("/");
+    return (parts.length === 4 &&
+        parts.every(isSkillScriptSegment) &&
+        parts[0] === "skills" &&
+        parts[2] === "scripts");
+}
+/**
+ * The skill script this interpreter argv runs, or `null` when the argv is not
+ * exactly `[allowlisted flags…] <skill-script path> [arguments…]` (APRV-502).
+ *
+ * Words AFTER the script are the script's own arguments and are not read here:
+ * `python3 skills/agent-commons/scripts/search_forum.py --q x` is the shape.
+ * They are still scanned for protected and credential paths by
+ * `classifySegment`, which runs after the table and can only tighten.
+ */
+export function skillScriptArg(bin, args) {
+    const allowed = SKILL_SCRIPT_FLAGS[bin];
+    if (allowed === undefined)
+        return null;
+    const python = bin === "python" || bin === "python3";
+    for (const arg of args) {
+        if (!arg.startsWith("-"))
+            return isSkillScriptPath(arg) ? arg : null;
+        if (allowed.includes(arg))
+            continue;
+        if (python && PYTHON_SKILL_SCRIPT_FLAGS.test(arg))
+            continue;
+        // Anything else: a value-taking flag, `--flag=value`, inline code (`-c`,
+        // `-e`, `-m`, `-p`), a lone `-` (stdin) or `--`. Not this rule.
+        return null;
+    }
+    return null;
+}
+/** `bun` / `python` / `python3` running a skill script; binds the script path. */
+function refineSkillScript(ctx) {
+    // `matchRule` only lets this row match when `skillScriptArg` found a script,
+    // so the fallback is unreachable; it is spelled as the row's own answer
+    // rather than as a `null`, which would be read as "opaque".
+    const script = skillScriptArg(ctx.bin, ctx.args);
+    return script === null
+        ? { class: SKILL_SCRIPT_CLASS, rule: SKILL_SCRIPT_RULE }
+        : { class: SKILL_SCRIPT_CLASS, rule: SKILL_SCRIPT_RULE, path: script };
+}
 /**
  * `node` — an inline script is opaque, the gate's own entry point is
- * pass-through, and anything else is a workspace script.
+ * pass-through, a skill script is `exec.local` (APRV-502), and anything else
+ * is a workspace script.
  */
 function refineNode(ctx) {
     if (hasFlag(ctx.args, ["-e", "--eval", "-p", "--print"]))
@@ -2489,6 +2787,14 @@ function refineNode(ctx) {
             rule: "node-approval-cli",
         });
     }
+    // APRV-502. A substituted word is a hole in the text, and an assignment
+    // prefix (`NODE_OPTIONS='--require …'`) is a flag spelled through the
+    // environment, so either declines the skill-script reading and the segment
+    // keeps the answer it had before.
+    const skill = ctx.substituted || ctx.assigned ? null : skillScriptArg("node", ctx.args);
+    if (skill !== null) {
+        return { class: SKILL_SCRIPT_CLASS, rule: NODE_SKILL_SCRIPT_RULE, path: skill };
+    }
     return { class: "files.write.workspace", rule: "node-script" };
 }
 /**
@@ -2686,9 +2992,24 @@ export const COMMAND_RULES = [
         id: "node",
         bins: ["node"],
         class: "files.write.workspace",
-        emits: [GATE_SELF_CLASS, "log.sync", "log.advance", "policy.core"],
+        emits: [GATE_SELF_CLASS, "log.sync", "log.advance", "policy.core", SKILL_SCRIPT_CLASS],
         refine: refineNode,
     },
+    // APRV-502. An interpreter running a skill script, `exec.local`. Below every
+    // `bun` row of the package-manager group, so `bun run x`, `bun install` and
+    // `bun --version` keep their classes; `skillScript` makes the row match ONLY
+    // the exact shape, so every other `bun`, `python` or `python3` argv keeps the
+    // answer it had before the row existed. `node` reaches the same answer
+    // inside {@link refineNode}, because its row has no `subs` to sit beside.
+    // Named in {@link CODE_EXECUTING_RULES}: a skill script is code the runtime
+    // did not author.
+    {
+        id: SKILL_SCRIPT_RULE,
+        bins: ["bun", "python", "python3"],
+        class: SKILL_SCRIPT_CLASS,
+        skillScript: true,
+        refine: refineSkillScript,
+    },
     {
         id: "approval",
         bins: ["approval"],
@@ -2799,9 +3120,67 @@ export const COMMAND_RULES = [
         refine: refinePrintenv,
     },
     // -- reads ---------------------------------------------------------------
+    // APRV-508. `date` prints the time or sets the clock, with one binary and
+    // overlapping flags, so it is a shape row rather than a seat in the read
+    // table: only the display forms {@link isDateDisplay} reads match, and every
+    // setting form (`-s`, `--set`, a bare `MMDDhhmm` operand), every file-reading
+    // form (`-f`, `-r`) and everything else keeps the `unclassified` refusal it
+    // had. The only assignments the row admits are the zone and the locale, with
+    // values that cannot name a file (`TZ=Asia/Kolkata date`).
+    {
+        id: "date-read",
+        bins: ["date"],
+        class: "read.shell",
+        shape: isDateDisplay,
+    },
+    // APRV-508. The system-information readers, each a strict allow-grammar in
+    // `sysinfo-argv.ts`: `hostname NAME` sets the host name, `free -s` loops,
+    // `uptime FILE` reads a utmp file, so none of them is a plain seat in the
+    // read table. No assignment rides in front of any of them.
+    {
+        id: "sysinfo-read",
+        bins: ["uptime", "whoami"],
+        class: "read.shell",
+        shape: (args, assignments) => assignments.length === 0 && isBareInfo(args),
+    },
+    {
+        id: "hostname-read",
+        bins: ["hostname"],
+        class: "read.shell",
+        shape: (args, assignments) => assignments.length === 0 && isHostnameDisplay(args),
+    },
+    {
+        id: "df-read",
+        bins: ["df"],
+        class: "read.shell",
+        shape: (args, assignments) => assignments.length === 0 && isDfDisplay(args),
+    },
+    {
+        id: "free-read",
+        bins: ["free"],
+        class: "read.shell",
+        shape: (args, assignments) => assignments.length === 0 && isFreeDisplay(args),
+    },
+    {
+        id: "seq-read",
+        bins: ["seq"],
+        class: "read.shell",
+        shape: (args, assignments) => assignments.length === 0 && isSeqDisplay(args),
+    },
+    // `paste` reads the files it names, and the read scope takes them exactly as
+    // it takes `cat`'s (`paste: "all"` in read-scope.ts).
+    {
+        id: "paste-read",
+        bins: ["paste"],
+        class: "read.shell",
+        shape: (args, assignments) => assignments.length === 0 && isPasteRead(args),
+    },
     {
         id: "read-shell",
         bins: [
+            // APRV-508: `[` is `test` under its other name; the closing `]` is an
+            // argument. Both read nothing but their operands and the file modes.
+            "[",
             "basename",
             "cat",
             "cd",
@@ -3081,6 +3460,43 @@ function protectedRank(surface) {
     const index = PROTECTED_PRECEDENCE.indexOf(surface);
     return index === -1 ? PROTECTED_PRECEDENCE.indexOf("policy.edit") : index;
 }
+/**
+ * Does this protected surface outrank `account.credential`? (APRV-503.)
+ *
+ * Where the credential class sits in {@link PROTECTED_PRECEDENCE}: below
+ * `log.mutate` and `policy.core`, above `policy.edit` and its routed
+ * sub-classes. `log.mutate` is the one class the open window refuses with no
+ * policy consulted, and `policy.core` is an edit of the gate's own organs; a
+ * credential READ named by a redirection must never displace either of them,
+ * under any policy's ordering of the three. `policy.edit` is prose about the
+ * gate, and a secret leaving the machine is the stricter statement.
+ */
+function outranksCredential(surface) {
+    return protectedRank(surface) <= protectedRank("policy.core");
+}
+/**
+ * The protected path, if any, that outranks a credential answer for this
+ * segment (APRV-503). `null` when none does, which is when the credential tier
+ * may answer at once.
+ *
+ * Scanned as the protected scan reads the segment: the positionals with the
+ * prose skip, and the `<` targets. A credential file is ALSO a protected path
+ * (`.approval/env` lies under the gate's directory), so the words that ARE the
+ * credential read are left out, or every credential read would outrank itself:
+ * the `<` targets that are credential files, and the credential positionals of
+ * a binary that reads what it names. A write-only binary's credential
+ * positional stays in, because for it that word is a write to the gate's
+ * directory (`tee .approval/env < .approval/vault.enc` is `policy.core`, as
+ * `tee .approval/env` is). On equal rank the positional is the one named.
+ */
+function outrankingProtected(positionals, readTargets, writesOnly, protectedPaths) {
+    const named = strictestProtected(writesOnly ? positionals : positionals.filter((arg) => !isCredentialPath(arg)), protectedPaths, true);
+    const fed = strictestProtected(readTargets.filter((target) => !isCredentialPath(target)), protectedPaths);
+    const found = fed === null || (named !== null && protectedRank(named.surface) <= protectedRank(fed.surface))
+        ? named
+        : fed;
+    return found !== null && outranksCredential(found.surface) ? found : null;
+}
 /**
  * Is this word PROSE that merely spells a protected path, rather than a path?
  * (APRV-409.)
@@ -3198,6 +3614,13 @@ export const CODE_EXECUTING_RULES = [
     "npm-script",
     /** `node <script>` — the plainest spelling of "run what I just wrote". */
     "node-script",
+    /**
+     * `bun` / `python3` / `node` running `skills/<skill>/scripts/<file>`
+     * (APRV-502). A skill script is a file in the workspace an agent may have
+     * written a minute ago, exactly as `node x.mjs` is.
+     */
+    SKILL_SCRIPT_RULE,
+    NODE_SKILL_SCRIPT_RULE,
     /** `npx`, `tsx`, `tsc`, `vitest`, `jest`, `make`, and kin. */
     "workspace-tool",
     /**
@@ -3406,18 +3829,63 @@ function sandboxWrapper(words, start) {
     // can produce (`docs/sandboxed-exec.md`, and APRV-193's Linux follow-up).
     return null;
 }
+/**
+ * Does this `NAME=value` set a variable that steers which program runs, what
+ * it loads, which file it reads as a zone, locale or converter, or where `cd`
+ * goes? (APRV-508 refutation S1; `HOME` and `CDPATH` from the recheck.)
+ */
+function isSteeringAssignment(word) {
+    const name = word.slice(0, word.indexOf("="));
+    if (["TZ", "TZDIR", "PATH", "LOCPATH", "GCONV_PATH", "LANG", "LANGUAGE", "HOME", "CDPATH"].includes(name)) {
+        return true;
+    }
+    return name.startsWith("LC_") || name.startsWith("LD_");
+}
+/** The directories a shape row's binary may be spelled from, besides a bare name. */
+const SYSTEM_BIN_DIRS = ["/bin/", "/usr/bin/", "/usr/local/bin/", "/sbin/", "/usr/sbin/"];
+/**
+ * Is this command word the system's binary rather than a file the agent can
+ * place? A bare name is looked up on PATH; a path in a system directory names
+ * that file. `./date` or `/tmp/x/date` is whatever program sits there, and a
+ * shape row (APRV-508) does not vouch for it.
+ */
+function isSystemBinWord(word) {
+    if (!word.includes("/"))
+        return true;
+    if (word.includes("..") || word.includes("//"))
+        return false;
+    return SYSTEM_BIN_DIRS.some((dir) => word.startsWith(dir) && !word.slice(dir.length).includes("/"));
+}
 /**
  * Find the first table row matching this binary, subcommand and argv.
  *
- * The argv is read for one purpose only (APRV-397): a `probe` row matches an
- * argv that is nothing but version or help flags, and no other row reads it.
+ * The argv is read for two purposes only: a `probe` row matches an argv that
+ * is nothing but version or help flags (APRV-397), and a `skillScript` row
+ * matches an argv that runs a skill script (APRV-502). No other row reads it.
+ *
+ * `substituted` and `assigned` are read by the `skillScript` row alone: a
+ * substituted word is a hole in the text, and an assignment prefix is a flag
+ * spelled through the environment (`BUN_OPTIONS='--cwd ../x'` makes bun read
+ * a different directory's file), so either one means the shape is not matched
+ * and the segment keeps the answer it had before (fail closed).
+ *
+ * A `shape` row (APRV-508) reads the argv through its own predicate, which is
+ * handed the assignment words so it can admit the harmless ones (`TZ=Zone`)
+ * and decline the rest; a substituted word declines it outright.
  */
-function matchRule(bin, sub, args) {
+function matchRule(bin, sub, args, substituted = false, assigned = false, assignments = [], binWord = bin) {
     for (const rule of COMMAND_RULES) {
         if (!rule.bins.includes(bin))
             continue;
         if (rule.probe === true && !isVersionProbe(args))
             continue;
+        if (rule.shape !== undefined && (substituted || !isSystemBinWord(binWord) || !rule.shape(args, assignments)))
+            continue;
+        // APRV-502: see the doc comment above; any of the three declines the row.
+        if (rule.skillScript === true &&
+            (substituted || assigned || skillScriptArg(bin, args) === null)) {
+            continue;
+        }
         if (rule.subs !== undefined) {
             if (sub === null || !rule.subs.includes(sub))
                 continue;
@@ -3433,7 +3901,19 @@ function classifySegment(segment, protectedPaths, context) {
     // `$(…)` is classified recursively. A substitution that only reads is inert;
     // anything else taints the segment, because its effect happens before the
     // outer command even starts and the outer class would not describe it.
-    for (const word of segment.words) {
+    //
+    // Redirection targets are words too, and the shell expands them the same
+    // way (APRV-508 recheck M-R1): `cat a < "x$(rm -rf y)"` runs the `rm` before
+    // `cat` opens anything. Until this loop read them, a substitution in a
+    // target ran with no class of its own, under `read.shell` for a `<` and
+    // under the write class for a `>`, on 0.4.3 as well.
+    const expanded = [
+        ...segment.words,
+        ...segment.redirects.map((redirect) => redirect.target),
+        // APRV-504: the `$(…)` of an unquoted heredoc body run when it is read.
+        { text: "", quoted: false, substitutions: segment.bodySubstitutions },
+    ];
+    for (const word of expanded) {
         for (const inner of word.substitutions) {
             const nested = classifyCommand(inner, protectedPaths, context);
             if (!nested.ok) {
@@ -3457,6 +3937,10 @@ function classifySegment(segment, protectedPaths, context) {
     let cursor = 0;
     while (cursor < words.length && ASSIGNMENT.test(words[cursor]))
         cursor += 1;
+    // APRV-502: read by the skill-script shape only ({@link matchRule}).
+    const assigned = cursor > 0;
+    // APRV-508: the same words, for a `shape` row that admits some.
+    const assignments = words.slice(0, cursor);
     // APRV-193. A sandbox wrapper is not a command: it is a room, and what
     // matters is what runs inside it. `approval sandbox -- npm install` is
     // `deps.add`, and it has to be, in both directions.
@@ -3492,22 +3976,64 @@ function classifySegment(segment, protectedPaths, context) {
         // a write. `2>/dev/null` is the suffix an agent writes on half its reads,
         // and until this it turned every one of them into `files.write.workspace`.
         .filter((target) => !isDiscardTarget(target));
+    // APRV-503: the paths this segment READS through `<`, at any descriptor. They
+    // are judged where a named argument is judged, below: a credential target is
+    // `account.credential` and a protected one joins the effectful scan.
+    const readTargets = segment.redirects
+        .filter((redirect) => redirect.op === "<")
+        .map((redirect) => redirect.target.text);
+    const redirectTargets = segment.redirects.map((redirect) => redirect.target.text);
     // A redirection onto a protected path is a write to that path, whatever the
     // command in front of it was going to do. The CLASS says which surface was
     // aimed at (APRV-198); the RULE stays `redirect-protected`, because the
     // mechanism is unchanged and the hook's tiers and the channel's protected-path
     // view are keyed on the rule.
     const redirected = strictestProtected(writeTargets, protectedPaths);
+    const bin = words[cursor];
     if (redirected !== null) {
+        // APRV-503 recheck (SHOULD-FIX-R1): a segment that writes a protected path
+        // AND reads credential material (`cat .approval/env > APPROVAL.md`, `cat <
+        // ~/.hermes/.env > APPROVAL.md`) carries both classes. The protected class
+        // still answers the segment; the credential touch rides beside it.
+        const writerArgs = bin === undefined ? [] : words.slice(cursor + 1);
+        const writer = bin === undefined ? null : (pathSegments(bin).slice(-1)[0] ?? bin);
+        const touched = (writer === null
+            ? null
+            : credentialTouch(writer, writerArgs, writerArgs.filter((arg) => !isFlag(arg)))) ??
+            redirectCredentialTouch(readTargets, redirectTargets);
         return {
             ok: true,
             class: redirected.surface,
             rule: "redirect-protected",
             path: redirected.path,
+            ...(touched === null ? {} : { also: touched }),
         };
     }
-    const bin = words[cursor];
     if (bin === undefined) {
+        // A bare input redirection opens its target, and inside `$(…)` it IS the
+        // read: `$(< ~/.hermes/.env)` is bash for "the file's contents" (APRV-503).
+        // Nothing here can outrank it: there are no positionals, and a protected
+        // write target has already answered above, so the precedence rule the
+        // binary path applies below has nothing to defer to.
+        const bareCredential = redirectCredentialTouch(readTargets, redirectTargets);
+        if (bareCredential !== null)
+            return { ok: true, ...bareCredential };
+        // APRV-508 refutation S1: an assignment on its own sets a shell variable,
+        // and when that variable is already exported (PATH and LANG always are)
+        // the new value reaches every later command on the line. `TZ=/etc/x;
+        // date` opens the file the date row refuses to let `TZ=/etc/x date`
+        // open, and `PATH=/tmp/x; cat f` runs whatever `cat` sits there. So the
+        // variables that pick which program runs, which libraries it loads, or
+        // which file it reads as a zone, a locale or a charset converter are not
+        // answered as reads.
+        const steering = assignments.find((word) => isSteeringAssignment(word));
+        if (steering !== undefined) {
+            return {
+                ok: false,
+                code: "unclassified",
+                detail: `no rule for the assignment ${steering.slice(0, steering.indexOf("="))}=…: it steers which program or file later commands use`,
+            };
+        }
         // `VAR=value` alone, or a bare redirection. `> file` truncates, so it is a
         // write; an assignment on its own touches nothing.
         return writeTargets.length > 0
@@ -3533,15 +4059,86 @@ function classifySegment(segment, protectedPaths, context) {
         return { ok: false, code: "opaque", detail: `${basename} runs inline source` };
     }
     const positionals = args.filter((arg) => !isFlag(arg));
+    // APRV-508 recheck S-R1: `printf -v NAME` assigns NAME, so `printf -v PATH
+    // %s /tmp/x; cat f` is the bare `PATH=/tmp/x` the assignment rule above
+    // refuses, spelled through a builtin. A steering NAME (a subscript stripped:
+    // `PATH[0]` is PATH), or a NAME the text cannot read, is refused.
+    if (basename === "printf") {
+        for (let at = 0; at < args.length; at += 1) {
+            const arg = args[at];
+            if (arg === "--")
+                break;
+            const name = arg === "-v" ? args[at + 1] : arg.startsWith("-v") ? arg.slice(2) : undefined;
+            if (name === undefined)
+                continue;
+            const bare = name.replace(/\[.*$/su, "");
+            if (/[$`]/u.test(name) || isSteeringAssignment(`${bare}=`)) {
+                return {
+                    ok: false,
+                    code: "unclassified",
+                    detail: `no rule for printf -v ${name}: it sets a variable that steers which program or file later commands use`,
+                };
+            }
+        }
+    }
+    // APRV-508 refutation S3: `test -v 'a[$(id)]'` evaluates the subscript as
+    // arithmetic, and bash expands a `$(…)` inside it, so the operand runs a
+    // command. `[` is `test`; both refuse a `-v`/`-R` operand carrying `[`, and
+    // an unquoted substitution, whose output the shell would split into words
+    // (a `-v` and a subscript among them) that this text never shows.
+    if (basename === "test" || basename === "[") {
+        const operandWords = segment.words.slice(cursor + 1);
+        const probe = args.findIndex((arg, at) => (arg === "-v" || arg === "-R") && (args[at + 1] ?? "").includes("["));
+        if (probe !== -1 || operandWords.some((word) => word.substitutions.length > 0 && !word.quoted)) {
+            return {
+                ok: false,
+                code: "unclassified",
+                detail: `no rule for ${basename} with an array subscript or an unquoted substitution: the shell may evaluate it as a command`,
+            };
+        }
+    }
     // Credential material, below the opaque checks so `sudo cat .approval/env`
     // stays opaque (a refusal) rather than being softened into a request, and
     // above the binary table so a reader the table does not know (`base64`,
     // `xxd`, `less`) is named rather than answered `unclassified` (APRV-194).
+    // APRV-503: the same tier read from the redirection targets, at the same
+    // place in the order (`sudo cat < .approval/env` stays a refusal, and `less
+    // < .approval/env` is named rather than `unclassified`).
+    //
+    // A credential path, named or redirected, never lowers a `log.mutate` or
+    // `policy.core` answer (APRV-503 refutation, BLOCKING-1 and its named-argument
+    // twin). Both classes outrank `account.credential` ({@link
+    // outranksCredential}), and the open window refuses `log.mutate` with no
+    // policy consulted while it bypasses `account.credential` under a policy that
+    // does not load: `rm -rf .approval/log < .approval/env` and `cp .approval/env
+    // .approval/log/events.jsonl` were both relabelled `account.credential` by an
+    // early return here, and so both reached the log through a window. So the
+    // credential answer is taken HERE only when the segment names no protected
+    // path that outranks it. When one is named the answer is DEFERRED: the
+    // segment goes on through the table and the protected scan exactly as it
+    // would without the credential word, a protected class or a refusal stands,
+    // and the credential class answers only where that walk ends on an answer it
+    // is stricter than (a read, `gate.self`). Where the walk ends on the
+    // protected class, the credential touch is carried beside it as a second
+    // class of the command (`also`), never dropped. Write targets need no check
+    // here: a protected one has already answered above, carrying it the same way.
     const credential = credentialTouch(basename, args, positionals);
-    if (credential !== null)
-        return { ok: true, ...credential };
+    const redirectCredential = redirectCredentialTouch(readTargets, redirectTargets);
+    const outranking = credential === null && redirectCredential === null
+        ? null
+        : outrankingProtected(positionals, readTargets, credentialWritesOnly(basename, args), protectedPaths);
+    if (outranking === null) {
+        if (credential !== null)
+            return { ok: true, ...credential };
+        if (redirectCredential !== null)
+            return { ok: true, ...redirectCredential };
+    }
+    const deferredCredential = credential ?? redirectCredential;
     const sub = positionals[0] ?? null;
-    const rule = matchRule(basename, sub, args);
+    const substituted = segment.words
+        .slice(cursor + 1)
+        .some((word) => word.substitutions.length > 0);
+    const rule = matchRule(basename, sub, args, substituted, assigned, assignments, bin);
     if (rule === null) {
         return {
             ok: false,
@@ -3551,10 +4148,7 @@ function classifySegment(segment, protectedPaths, context) {
                 : `no rule for ${basename} ${sub}`,
         };
     }
-    const substituted = segment.words
-        .slice(cursor + 1)
-        .some((word) => word.substitutions.length > 0);
-    const ctx = { bin: basename, args, positionals, sub, substituted, context };
+    const ctx = { bin: basename, args, positionals, sub, substituted, assigned, context };
     const refined = rule.refine === undefined ? null : rule.refine(ctx);
     if (rule.refine !== undefined && refined === null) {
         return { ok: false, code: "opaque", detail: `${basename} runs inline source` };
@@ -3582,12 +4176,59 @@ function classifySegment(segment, protectedPaths, context) {
     // a directory path is a sentence rather than a file. Redirection targets
     // above, and the apply-patch and file-tool paths elsewhere, are paths by
     // construction and are not offered the skip.
+    //
+    // APRV-503: an INPUT redirection's target is scanned here too, as the named
+    // argument it stands in for (`node x.js < APPROVAL.md` is `node x.js
+    // APPROVAL.md` with the file on stdin), and without the prose skip, because a
+    // redirection target is a path by construction. Its direction is known to be a
+    // read, so this is the stricter of two defensible answers, which is the one
+    // the protected tier takes everywhere else. A read segment keeps `read.*`
+    // either way: `cat < APPROVAL.md` reads the policy as `cat APPROVAL.md` does.
+    //
+    // The rule, stated exactly. The strictest surface among the positionals and
+    // the `<` targets answers; on equal rank the positional's path is the one
+    // bound. So a `<` target can move an effectful segment only to a STRICTER
+    // protected class than its positionals earned (`node CLAUDE.md < APPROVAL.md`
+    // is `policy.core`), never to a looser one, and a segment whose positionals
+    // earn no protected class can only move from its own class to a protected one.
     if (!cls.startsWith("read.") && cls !== GATE_SELF_CLASS) {
+        // A deferred credential answer (above) names the path that outranked it,
+        // which is the strictest protected path among the words that are not the
+        // credential read itself: the segment's answer without that word.
+        //
+        // The credential touch is NOT dropped (APRV-503 recheck, SHOULD-FIX-R1): it
+        // rides beside the protected class as a second class of the command, so
+        // the precedence above decides what the segment is called and never what a
+        // policy gets to see. A policy holding `account.credential` stricter than
+        // `policy.core` still refuses `cp .approval/env APPROVAL.md`, and SPEC.md
+        // §7's "a copy is classified `account.credential` in either direction"
+        // holds as written.
+        if (deferredCredential !== null && outranking !== null) {
+            return {
+                ok: true,
+                class: outranking.surface,
+                rule: "protected-path",
+                path: outranking.path,
+                also: deferredCredential,
+            };
+        }
         const named = strictestProtected(positionals, protectedPaths, true);
-        if (named !== null) {
-            return { ok: true, class: named.surface, rule: "protected-path", path: named.path };
+        const fed = strictestProtected(readTargets, protectedPaths);
+        const touched = fed === null || (named !== null && protectedRank(named.surface) <= protectedRank(fed.surface))
+            ? named
+            : fed;
+        if (touched !== null) {
+            return { ok: true, class: touched.surface, rule: "protected-path", path: touched.path };
         }
     }
+    // APRV-503: a credential answer deferred above, because the segment also
+    // names a protected path that outranks it. The walk did not end on that
+    // protected class (a reader, or the gate's own CLI, is not scanned), so it
+    // ended on an answer the credential class is stricter than, and the credential
+    // class answers: `cat .approval/log/events.jsonl < .approval/env` reads the
+    // environment map. A named credential is reported ahead of a redirected one.
+    if (deferredCredential !== null)
+        return { ok: true, ...deferredCredential };
     // A read command with a write redirection writes. `ls > out.txt` creates a
     // file, and the class has to say so.
     if (cls.startsWith("read.") && writeTargets.length > 0) {
@@ -3692,6 +4333,20 @@ export function classifyCommand(command, protectedPaths = [], context = {}) {
         });
         if (!classes.includes(outcome.class))
             classes.push(outcome.class);
+        // APRV-503 recheck: the credential touch a protected answer outranked, as
+        // its own entry over the same segment text. The shape a pipeline already
+        // has (one entry per class-bearing part), so every reader of `segments`
+        // and `classes` sees it without learning a new field.
+        if (outcome.also !== undefined) {
+            segments.push({
+                text: segment.text,
+                class: outcome.also.class,
+                rule: outcome.also.rule,
+                ...(outcome.also.path === undefined ? {} : { path: outcome.also.path }),
+            });
+            if (!classes.includes(outcome.also.class))
+                classes.push(outcome.also.class);
+        }
     }
     return { ok: true, segments, classes };
 }