@veda-hq/dvara 0.5.4 → 0.6.4

package/README.md

@@ -29,8 +29,28 @@ file in your repository; dvara runs it.
   attaches to each run; it may stop a hung hook and decide the verdict. Without
   one, or when it fails to load, the hook runs exactly as it would anyway.
 
-Every one of these is fail-open: telemetry, quiet output and the watchdog never
-change a hook's verdict.
+- **A stage list, if you keep one.** `stages`, or the JSON file `stageList`
+  names (inside an installed package, say), gives each hook's stage names in
+  order. A passing run that marks a stage its hook's list does not have, or
+  marks one out of the list's order, is refused (exit 1) with the reason. So is
+  a run of a hook in `stageListRequired` (default `pre-push`) that marks a
+  stage and whose list file cannot be read, so a missing package never lets a
+  push that ran its stages through silently; any other hook passes then, with a
+  warning that its stages were not checked. A
+  stage may be marked again where it stands, a name may
+  appear more than once in a list, and dvara's own `startup` and
+  `runtime-selection` need no entry. A run that marks no stage reads no list.
+- **A push judges what git pushes.** Git picks the commits a push sends
+  before `pre-push` starts; the hook's checks read the worktree. A run of
+  `pre-push` (not a preflight) records HEAD when it starts and again when the
+  hook ends, and a passing run whose HEAD moved in between (something
+  committed, merged or checked out in the worktree mid-push) is refused
+  (exit 1), naming both commits: push again. A HEAD that cannot be read at
+  either end changes nothing. The refusal is the row's `error`.
+
+Telemetry, quiet output and a watchdog that fails to load never change a
+hook's verdict. Only a signal, an enforcing watchdog's stop, the stage list
+and a HEAD that moved during a push do.
 
 ## A hook under dvara
 
@@ -73,13 +93,16 @@ rename it in its messages (default "preflight" and "Preflight").
 `.dvara.json` at the repository's root, or the file `DVARA_CONFIG` names. Every
 field is optional; an unknown field is an error.
 
-| Field        | Default                                          | Meaning                                                        |
-| ------------ | ------------------------------------------------ | -------------------------------------------------------------- |
-| `historyDir` | `.dvara`                                         | where the history, the quiet log and scratch files go          |
-| `quietHooks` | `["pre-commit"]`                                 | hooks whose passing output is one line                         |
-| `watchdog`   | `null`                                           | a watchdog module, relative to the root                        |
-| `baseRefs`   | `origin/main`, `origin/develop`, `origin/master` | the refs tried for the base a run is judged against            |
-| `stages`     | `{}`                                             | each hook's stages in order; `dvara stages <hook>` prints them |
+| Field               | Default                                          | Meaning                                                                                                            |
+| ------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| `historyDir`        | `.dvara`                                         | where the history, the quiet log and scratch files go                                                              |
+| `quietHooks`        | `["pre-commit"]`                                 | hooks whose passing output is one line                                                                             |
+| `watchdog`          | `null`                                           | a watchdog module, relative to the root                                                                            |
+| `baseRefs`          | `origin/main`, `origin/develop`, `origin/master` | the refs tried for the base a run is judged against; to `dvara records`, every one that resolves is pushed history |
+| `stages`            | `{}`                                             | each hook's stages in order, which a passing run must keep to; `dvara stages <hook>` prints them                   |
+| `stageList`         | `null`                                           | a JSON file holding the same map instead, relative to the root and read when a run ends; not both                  |
+| `stageListRequired` | `["pre-push"]`                                   | hooks a list file that cannot be read refuses; any other hook passes with a warning                                |
+| `trailerKeys`       | `[]`                                             | the repository's own trailer keys, which `dvara trailers` checks beside git's                                      |
 
 `records`, an object, holds the settings of `dvara records` and `dvara frozen`
 (below). Each field is optional; an unknown one is an error.
@@ -152,6 +175,13 @@ grows and clones disagree on their length:
 - `unresolved-id`: a full id the change adds that is not a commit in this
   repository, compared with the ids the file cited at the merge base. No
   baseline holds these: they are new by construction.
+- `unpushed-id`: a full id the change adds that is a commit here but on no
+  pushed history: neither HEAD (nor, at pre-commit, a merge's other parent)
+  nor any of `baseRefs` or `--base` reaches it. A commit made here and never
+  pushed, or one on a branch since deleted, resolves in this clone and in no
+  CI clone. One `git rev-list` answers for every citation. A shallow clone
+  cannot tell where a commit stands, so it judges none. No baseline holds
+  these either.
 
 In Markdown, a fence's captured output is not read for tokens; its command
 lines are (`$ ` lines of a transcript, every line of an `sh` fence). Fences are
@@ -190,6 +220,26 @@ In a merge, a path staged exactly as a merged-in parent has it is that
 parent's change and passes; a hand resolution counts. With no frozen paths
 configured it passes without asking git. Exit 0, 1 or 2 as above.
 
+## Trailers: `dvara trailers`
+
+Git reads a message's trailers only from its last paragraph, so a trailer
+line above a blank line is prose to git: the commit lands without it, and
+nothing says so. For a commit-msg hook, `dvara trailers <commit-msg-file>`
+refuses (exit 1) a line whose key is `Co-Authored-By`, `Signed-off-by` or one
+of `trailerKeys` or a `--key KEY` (any case, `Key: value` at the start of the line) in any
+paragraph before the last, or in the title's paragraph, which git never reads
+trailers from (so a message of one paragraph keeps none). The title line
+itself is never judged. Each is named with its line number. The file is
+read raw: comment lines (`#`) are dropped, the scissors line ends the
+message, whitespace-only lines separate paragraphs and trailing ones start
+none. Exit 2: bad arguments, or a config or file it cannot read.
+
+```bash
+#!/usr/bin/env bash
+# .husky/commit-msg
+exec node node_modules/@veda-hq/dvara/dist/cli.js trailers --key Slice "$1"
+```
+
 ## Commands
 
 ```sh
@@ -198,5 +248,6 @@ dvara stages <hook>                  # the stages .dvara.json lists for it
 dvara shell <stages|keep-going>      # the path of a shell helper
 dvara records <--staged | --all [--base REF] [--write-baseline | --survey] | --base REF>
 dvara frozen <--staged | --base REF [--head REF]>
+dvara trailers [--key KEY]… <commit-msg-file>  # refuse trailer lines git would not read
 dvara --version
 ```

package/dist/cli.js

@@ -7,7 +7,9 @@ import { configName, loadConfig } from "./config.js";
 import { frozen, parseArgs as parseFrozenArgs, USAGE as FROZEN_USAGE, } from "./records/frozen.js";
 import { parseArgs as parseRecordsArgs, records, USAGE as RECORDS_USAGE, } from "./records/gate.js";
 import { runner } from "./records/git.js";
+import { listFor, readStageLists } from "./stages.js";
 import { supervise } from "./supervisor.js";
+import { GIT_TRAILER_KEYS, misplacedTrailers, refusal } from "./trailers.js";
 export const USAGE = [
     "usage: dvara run <hook-file> [hook args…]   run a git hook under the supervisor",
     "       dvara stages <hook>                  the hook stages the config lists, one per line",
@@ -16,8 +18,11 @@ export const USAGE = [
     "                                            the record gate: no new non-durable paths, a baseline that only falls",
     "       dvara frozen <--staged | --base REF [--head REF]>",
     "                                            refuse changes to the frozen paths",
+    "       dvara trailers [--key KEY]… <commit-msg-file>",
+    "                                            refuse trailer lines git would not read (commit-msg)",
     "       dvara --version",
 ].join("\n");
+export const TRAILERS_USAGE = "usage: dvara trailers [--key KEY]… <commit-msg-file>";
 const SHELL_HELPERS = new Set(["stages", "keep-going"]);
 export const ownVersion = () => {
     const pkg = join(import.meta.dirname, "..", "package.json");
@@ -25,19 +30,80 @@ export const ownVersion = () => {
 };
 /** The path of a shell helper this package ships. */
 export const shellHelper = (name) => resolve(import.meta.dirname, "..", "shell", `${name}.sh`);
+const CHECK_USAGE = {
+    records: RECORDS_USAGE,
+    frozen: FROZEN_USAGE,
+    trailers: TRAILERS_USAGE,
+};
+/** A trailer key, as `--key` and `trailerKeys` take one. */
+const TRAILER_KEY = /^[A-Za-z0-9-]+$/;
+/**
+ * `dvara trailers` takes the commit message file git passes, and any number
+ * of `--key <Key>`: a repository's own keys, given on the command line so a
+ * hook can name them without a config field an older dvara would refuse.
+ */
+export const parseTrailersArgs = (args) => {
+    const files = [];
+    const keys = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i] ?? "";
+        if (arg !== "--key") {
+            files.push(arg);
+            continue;
+        }
+        const key = args[i + 1];
+        if (key === undefined || !TRAILER_KEY.test(key))
+            return { error: "--key takes a trailer key: letters, digits and -" };
+        keys.push(key);
+        i += 1;
+    }
+    const [file] = files;
+    return file === undefined || files.length !== 1
+        ? { error: "give one commit message file" }
+        : { file, keys };
+};
+/**
+ * `dvara trailers <file>`: 1 when a known trailer line sits above the last
+ * paragraph. The file is read relative to `cwd`, as git runs a hook at the
+ * top of the working tree and passes `.git/COMMIT_EDITMSG`.
+ */
+const trailers = (file, keys, { io, cwd }) => {
+    let text;
+    try {
+        text = readFileSync(resolve(cwd, file), "utf8");
+    }
+    catch (error) {
+        throw new Error(`cannot read ${file}: ${error.message}`, {
+            cause: error,
+        });
+    }
+    const misplaced = misplacedTrailers(text, [...GIT_TRAILER_KEYS, ...keys]);
+    if (misplaced.length === 0)
+        return 0;
+    for (const line of refusal(file, misplaced))
+        io.err(line);
+    return 1;
+};
 /**
- * `dvara records` or `dvara frozen` at the root `cwd`: 2 on bad arguments, a
- * config it cannot read, or git failing.
+ * `dvara records`, `dvara frozen` or `dvara trailers` at the root `cwd`: 2 on
+ * bad arguments, a config or file it cannot read, or git failing.
  */
-const checkCommand = (command, args, { io, cwd, env }) => {
-    const parsed = command === "records" ? parseRecordsArgs(args) : parseFrozenArgs(args);
+const checkCommand = (command, args, context) => {
+    const { io, cwd, env } = context;
+    const parsed = command === "records"
+        ? parseRecordsArgs(args)
+        : command === "frozen"
+            ? parseFrozenArgs(args)
+            : parseTrailersArgs(args);
     if ("error" in parsed) {
         io.err(`dvara ${command}: ${parsed.error}`);
-        io.err(command === "records" ? RECORDS_USAGE : FROZEN_USAGE);
+        io.err(CHECK_USAGE[command]);
         return 2;
     }
     try {
         const config = loadConfig(cwd, env);
+        if ("file" in parsed)
+            return trailers(parsed.file, [...config.trailerKeys, ...parsed.keys], context);
         const repo = { cwd, env };
         if ("mode" in parsed)
             return records(parsed, repo, io.out, {
@@ -71,7 +137,7 @@ export const run = async (argv, context) => {
         io.out(shellHelper(rest[0] ?? ""));
         return 0;
     }
-    if (command === "records" || command === "frozen")
+    if (command === "records" || command === "frozen" || command === "trailers")
         return checkCommand(command, rest, context);
     if ((command === "run" && rest.length > 0) ||
         (command === "stages" && rest.length === 1)) {
@@ -85,7 +151,15 @@ export const run = async (argv, context) => {
             return 2;
         }
         if (command === "stages") {
-            for (const name of config.stages[rest[0] ?? ""] ?? [])
+            let lists;
+            try {
+                lists = readStageLists(cwd, config);
+            }
+            catch (error) {
+                io.err(error.message);
+                return 2;
+            }
+            for (const name of lists ? (listFor(lists, rest[0] ?? "") ?? []) : [])
                 io.out(name);
             return 0;
         }

package/dist/config.js

@@ -2,6 +2,7 @@
 // DVARA_CONFIG names (relative to the root). Every field is optional.
 import { readFileSync } from "node:fs";
 import { isAbsolute, posix, resolve } from "node:path";
+import { parseStageLists } from "./stages.js";
 export const PACKAGE_MANAGERS = ["pnpm", "npm", "yarn"];
 export const DEFAULTS = {
     historyDir: ".dvara",
@@ -9,6 +10,9 @@ export const DEFAULTS = {
     watchdog: null,
     baseRefs: ["origin/main", "origin/develop", "origin/master"],
     stages: {},
+    stageList: null,
+    stageListRequired: ["pre-push"],
+    trailerKeys: [],
     records: {
         baseline: ".dvara/records-baseline.json",
         skip: [],
@@ -137,14 +141,31 @@ export const parseConfig = (text) => {
     }
     if ("baseRefs" in entries)
         config.baseRefs = strings(entries.baseRefs, "baseRefs");
-    if ("stages" in entries) {
-        const stages = entries.stages;
-        if (typeof stages !== "object" || stages === null || Array.isArray(stages))
-            throw new Error("stages must map each hook to its stage names");
-        const out = {};
-        for (const [hook, names] of Object.entries(stages))
-            out[hook] = strings(names, `stages.${hook}`);
-        config.stages = out;
+    if ("stages" in entries)
+        config.stages = parseStageLists(entries.stages, "stages");
+    if ("stageList" in entries) {
+        const path = entries.stageList;
+        if (path !== null &&
+            (typeof path !== "string" ||
+                path === "" ||
+                isAbsolute(path) ||
+                escapes(path) ||
+                // Read with the platform's resolve: on Windows `..\x` and `C:x` leave the root.
+                path.includes("\\") ||
+                /^[A-Za-z]:/.test(path)))
+            throw new Error("stageList must be a file path inside the repository, with / separators, or null");
+        if (path !== null && "stages" in entries)
+            throw new Error("give stages or stageList, not both");
+        config.stageList = path;
+    }
+    if ("stageListRequired" in entries)
+        config.stageListRequired = strings(entries.stageListRequired, "stageListRequired");
+    if ("trailerKeys" in entries) {
+        const keys = strings(entries.trailerKeys, "trailerKeys");
+        // Git reads a key as letters, digits and `-`; a key with other characters matches no line.
+        if (!keys.every((key) => /^[A-Za-z0-9-]+$/.test(key)))
+            throw new Error("trailerKeys must hold trailer keys: letters, digits and -");
+        config.trailerKeys = keys;
     }
     if ("records" in entries)
         config.records = parseRecordsConfig(entries.records);

package/dist/head.js

@@ -0,0 +1,30 @@
+// HEAD at both ends of a push hook. Git has chosen what it pushes before
+// pre-push starts; the hook's checks read the worktree. Something that
+// commits, merges or checks out in the worktree while the hook runs (an app
+// merging main in, a second session) leaves the checks judging one commit
+// while git pushes another, and the push goes out unchecked.
+import { execFileSync } from "node:child_process";
+/** The commit HEAD names, or null when git cannot say (no commit yet, no repository). */
+export const readHead = (root, env) => {
+    try {
+        return execFileSync("git", ["rev-parse", "HEAD"], {
+            cwd: root,
+            env,
+            // git's complaint is not the hook's output.
+            stdio: "pipe",
+        })
+            .toString()
+            .trim();
+    }
+    catch {
+        // fail-open: a HEAD git cannot read is no evidence that it moved.
+        return null;
+    }
+};
+/**
+ * The refusal for a hook during which HEAD moved, or null. A HEAD that could
+ * not be read at either end is no evidence of a move, so it refuses nothing.
+ */
+export const headMoved = (hook, start, end) => start === null || end === null || start === end
+    ? null
+    : `dvara: HEAD moved from ${start} to ${end} while ${hook} ran (something committed, merged or checked out in this worktree mid-push), so the checks did not judge what git is pushing. Push again.`;

package/dist/records/gate.js

@@ -241,7 +241,14 @@ const runChecks = (options, repo, log, settings) => {
         baseRenames ??= renamesIn(repo, planned.ref === ":" ? ["--cached", base] : [base, "HEAD"]);
         return baseRenames.get(path);
     };
-    const tree = treeContext(repo, planned.ref, planned.branchBase, renamedFrom);
+    // Pushed history: HEAD's, and that of the ref CI names and the base refs.
+    const pushed = [
+        ...new Set([
+            ...(options.base === null ? [] : [options.base]),
+            ...settings.baseRefs,
+        ]),
+    ];
+    const tree = treeContext(repo, planned.ref, planned.branchBase, renamedFrom, pushed);
     const recording = options.writeBaseline || options.survey;
     let baseline = { files: pathMap() };
     let before = null;

package/dist/records/git.js

@@ -195,9 +195,32 @@ export const resolveRef = (repo, ref) => {
     ]);
     return out === null ? null : out.trim();
 };
+/**
+ * Of `commits`, the ones no commit of `tips` reaches, in one walk:
+ * `git rev-list <commits> --not <tips>` prints exactly the commits reachable
+ * from the first and from none of the second, so a cited commit that is an
+ * ancestor of a tip (or a tip itself) is not printed. The walk covers only
+ * what the tips do not reach, which for a branch's citations is a handful of
+ * commits. Only commits are asked: rev-list walks commits and lists no blob
+ * or tree, so one passed here would read as reached.
+ */
+export const unreachable = (repo, commits, tips) => {
+    if (commits.length === 0)
+        return new Set();
+    const input = [...commits, ...tips.map((tip) => `^${tip}`)].join("\n");
+    const printed = new Set(git(repo, ["rev-list", "--stdin"], `${input}\n`).split("\n"));
+    return new Set(commits.filter((commit) => printed.has(commit)));
+};
+/**
+ * Whether the clone is shallow. Its history stops at a cut, so a commit
+ * below the cut that the store has anyway cannot be shown an ancestor of
+ * anything: a shallow clone cannot judge where a commit stands.
+ */
+export const isShallow = (repo) => git(repo, ["rev-parse", "--is-shallow-repository"]).trim() === "true";
 export const noQuestions = () => ({
     shas: new Set(),
     bases: new Set(),
+    history: new Set(),
 });
 /**
  * A context that answers without git and records each question. Running the
@@ -210,6 +233,13 @@ export const recordingContext = (tree, asked) => ({
             asked.shas.add(sha);
         return new Map(shas.map((sha) => [sha, "commit"]));
     },
+    // Every id passed for a commit above, so blobs and missing ids are asked
+    // here too: `warm` sends git only the ones that are commits.
+    onHistory: (commits) => {
+        for (const commit of commits)
+            asked.history.add(commit);
+        return null;
+    },
     baseText: (path) => {
         if (typeof tree.base !== "string")
             return tree.base;
@@ -220,13 +250,57 @@ export const recordingContext = (tree, asked) => ({
 /** A tree context over one git tree, with an optional merge base for branch rules. */
 export const treeContext = (repo, ref, base, 
 /** The path a file had at the base, when the branch renamed it. */
-renamedFrom = () => undefined) => {
+renamedFrom = () => undefined, 
+/**
+ * The base refs whose history counts as pushed, beside HEAD: a cited
+ * commit off all of them exists in this clone only.
+ */
+pushed = []) => {
     const modes = listModes(repo, ref);
     const present = new Set(modes.keys());
     const cache = new Map();
     const baseCache = new Map();
     /** Object type by name; null when the store does not have it. */
     const objects = new Map();
+    /** Whether each commit judged is off pushed history. */
+    const off = new Map();
+    let standing = null;
+    /** What pushed history is here, asked once and only when a commit needs it. */
+    const history = () => {
+        if (standing !== null)
+            return standing;
+        if (isShallow(repo))
+            return (standing = { shallow: true, tips: [], refs: [] });
+        const tips = [];
+        const refs = [];
+        // A staged merge commits MERGE_HEAD as a parent, so its history is the
+        // new commit's too. A ref that does not resolve here is no tip.
+        for (const name of [
+            "HEAD",
+            ...(ref === ":" ? ["MERGE_HEAD"] : []),
+            ...pushed,
+        ]) {
+            const id = resolveRef(repo, name);
+            if (id === null)
+                continue;
+            tips.push(id);
+            if (pushed.includes(name) && !refs.includes(name))
+                refs.push(name);
+        }
+        return (standing = { shallow: false, tips, refs });
+    };
+    const judge = (commits) => {
+        probe(commits);
+        const fresh = [...new Set(commits)].filter((commit) => objects.get(commit) === "commit" && !off.has(commit));
+        if (fresh.length === 0)
+            return;
+        const { shallow, tips } = history();
+        if (shallow)
+            return;
+        const unreached = unreachable(repo, fresh, tips);
+        for (const commit of fresh)
+            off.set(commit, unreached.has(commit));
+    };
     const readInto = (into, rev, wanted) => {
         const missing = wanted.filter((path) => !into.has(path));
         const names = missing.map((path) => objectName(rev, path));
@@ -297,6 +371,15 @@ renamedFrom = () => undefined) => {
             }
             return types;
         },
+        onHistory: (commits) => {
+            judge(commits);
+            if (standing?.shallow)
+                return null;
+            return {
+                unreached: new Set(commits.filter((commit) => off.get(commit) === true)),
+                refs: standing?.refs ?? [],
+            };
+        },
         baseText: (path) => {
             if (typeof base !== "string")
                 return base;
@@ -307,6 +390,7 @@ renamedFrom = () => undefined) => {
             if (typeof base === "string")
                 readBases(base, [...asked.bases]);
             probe([...asked.shas]);
+            judge([...asked.history]);
         },
     };
 };

package/dist/records/identity.js

@@ -244,8 +244,26 @@ export const commitIdentity = (records) => {
         if (full.length === 0)
             return found;
         const types = tree.typesOf([...new Set(full.map((f) => f.sha))]);
+        // A commit this clone has may still be one CI's clone lacks: one made
+        // here and never pushed, or on a branch since deleted. Only history HEAD
+        // or a base ref reaches is fetched there. Asked of every commit, however
+        // the line names it: CI fails to resolve a bare id the same way.
+        const commits = [...types]
+            .filter(([, t]) => t === "commit")
+            .map(([s]) => s);
+        const history = commits.length === 0 ? null : tree.onHistory(commits);
         for (const { n, sha, asCommit } of full) {
             const type = types.get(sha);
+            if (type === "commit" && history?.unreached.has(sha)) {
+                const refs = history.refs.length === 0
+                    ? "a base ref (none resolves in this clone)"
+                    : history.refs.join(" or ");
+                found.push({
+                    ...finding(path, n, "unpushed-id", `${sha} is not on pushed history: it is neither an ancestor of HEAD nor of ${refs}, so CI cannot resolve it. Cite a commit that is merged or on this branch.`),
+                    ratchet: false,
+                });
+                continue;
+            }
             // Git prints blob and tree ids too: every object resolves, unless the
             // line names it a commit.
             if (type !== undefined && (!asCommit || type === "commit"))

package/dist/stages.js

@@ -0,0 +1,106 @@
+// Each hook's stage names, in the order they run, and the check a passing run
+// must pass: every stage it marks is in its hook's list, in the list's order.
+// The lists are `stages` in the config, or the JSON file `stageList` names
+// (inside an installed package, say), read when the run ends: a pre-commit
+// that installs dependencies first finds the file its install put there.
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+/** The stages dvara marks itself, which no list names. */
+export const OWN_STAGES = new Set([
+    "startup",
+    "runtime-selection",
+]);
+/** A name a stage file line can carry: not empty, no tab or line break (records.ts splits on them). */
+const isStageName = (name) => typeof name === "string" && name !== "" && !/[\t\r\n]/.test(name);
+/** Each hook's names, from `value`; anything else is an error naming `field`. */
+export const parseStageLists = (value, field) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error(`${field} must map each hook to its stage names`);
+    const entries = Object.entries(value).map(([hook, names]) => {
+        if (!Array.isArray(names) || !names.every(isStageName))
+            throw new Error(`${field}.${hook} must be a list of stage names`);
+        return [hook, names];
+    });
+    // fromEntries defines each key as its own, `__proto__` included.
+    return Object.fromEntries(entries);
+};
+/** `hook`'s own list, never one inherited from Object's prototype (`toString`). */
+export const listFor = (lists, hook) => Object.hasOwn(lists, hook) ? lists[hook] : undefined;
+/**
+ * The lists a run is checked against: the file `stageList` names, else
+ * `stages`, else null (no lists: nothing is checked). A file that cannot be
+ * read or parsed is an error naming it.
+ */
+export const readStageLists = (root, config) => {
+    if (config.stageList === null)
+        return Object.keys(config.stages).length > 0 ? config.stages : null;
+    const path = resolve(root, config.stageList);
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        throw new Error(`dvara: cannot read the stage list ${path}: ${error.message}. Is the package that ships it installed?`);
+    }
+    try {
+        return parseStageLists(JSON.parse(text), "the stage list");
+    }
+    catch (error) {
+        throw new Error(`dvara: ${path}: ${error.message}`);
+    }
+};
+/**
+ * Why `marked` breaks `hook`'s list, or null when it keeps to it. A stage may
+ * be marked again where it stands (a loop), and a name may appear more than
+ * once in a list; each mark takes the first place at or after the last one's.
+ */
+export const stageViolation = (hook, marked, lists) => {
+    const names = marked.filter((name) => !OWN_STAGES.has(name));
+    if (names.length === 0)
+        return null;
+    const list = listFor(lists, hook);
+    if (list === undefined)
+        return `${hook} marked stage "${names[0]}", but the stage list has no ${hook} list`;
+    let at = 0;
+    for (const [index, name] of names.entries()) {
+        const found = list.indexOf(name, at);
+        if (found >= 0) {
+            at = found;
+            continue;
+        }
+        if (!list.includes(name))
+            return `${hook} marked stage "${name}", which its stage list does not have`;
+        return `${hook} marked stage "${name}" after "${names[index - 1] ?? ""}", out of its stage list's order`;
+    }
+    return null;
+};
+const PASS = { refusal: null, warning: null };
+/**
+ * What the stage list says of a passing run of `hook` that marked `marked`.
+ * With no stage of its own marked nothing is read. A list that cannot be read
+ * refuses a hook in `required`, since a check that cannot run must not pass
+ * there; any other hook passes with a warning saying it was not checked.
+ */
+export const stageVerdict = (hook, marked, lists, required) => {
+    if (marked.every((name) => OWN_STAGES.has(name)))
+        return PASS;
+    let read;
+    try {
+        read = lists();
+    }
+    catch (error) {
+        const message = error.message;
+        return required.includes(hook)
+            ? { refusal: message, warning: null }
+            : {
+                refusal: null,
+                warning: `${message} ${hook}'s stages were not checked.`,
+            };
+    }
+    if (read === null)
+        return PASS;
+    const violation = stageViolation(hook, marked, read);
+    return violation === null
+        ? PASS
+        : { refusal: `dvara: ${violation}.`, warning: null };
+};

package/dist/supervisor.js

@@ -7,9 +7,13 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 // The hook supervisor: runs a git hook under bash, forwards the terminal's
-// signals to it, and writes one history row per run. It never changes the
-// hook's verdict except to report a signalled run as cancelled; every failure
-// of its own (telemetry, watchdog, quiet output) is fail-open.
+// signals to it, and writes one history row per run. It changes the hook's
+// verdict only to report a signalled run as cancelled, to let an enforcing
+// watchdog's stop decide it, to refuse a passing run that broke its stage
+// list (stages.ts), or, for a hook in stageListRequired, whose list cannot be
+// read, and to refuse a passing pre-push during which HEAD moved (head.ts).
+// Every other failure of its own (telemetry, watchdog, quiet output) is
+// fail-open.
 import { execFileSync, spawn, spawnSync, } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
@@ -17,8 +21,10 @@ import { cpus, totalmem } from "node:os";
 import { relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { hookKind, invocationContext, perfLevelNames } from "./context.js";
+import { headMoved, readHead } from "./head.js";
 import { isQuiet, successLine, successNotices } from "./quiet.js";
 import { parseRecords, parseStages, treeUsage } from "./records.js";
+import { readStageLists, stageVerdict } from "./stages.js";
 /** Exit code per signal, shared by the pre-launch path and the exit handler. */
 export const SIGNAL_EXIT_CODES = {
     SIGINT: 130,
@@ -96,7 +102,8 @@ export const judgedAgainst = (root, env, baseRefs) => {
     const clean = diff === null || untracked === null
         ? null
         : diff === "" && untracked === "";
-    return { branch, fingerprint, base, tree, clean };
+    const head = revision?.trim() || null;
+    return { head, branch, fingerprint, base, tree, clean };
 };
 /**
  * Run `hook` under supervision and resolve with the exit code git must see.
@@ -163,7 +170,7 @@ export const supervise = async ([hook, ...args], options) => {
         for (const [name, listener] of listeners)
             signals.off(name, listener);
     };
-    const { branch, fingerprint, base, tree, clean } = judgedAgainst(root, env, config.baseRefs);
+    const { head, branch, fingerprint, base, tree, clean } = judgedAgainst(root, env, config.baseRefs);
     let watchdogModule = null;
     if (config.watchdog) {
         try {
@@ -278,9 +285,27 @@ export const supervise = async ([hook, ...args], options) => {
         if (imposed)
             code = imposed.code;
         const ended = Date.now();
+        const marks = parseStages(readOrNull(events), bootstrapMs);
+        // Only a run that would pass is checked: a failure keeps its own story.
+        const passing = code === 0 && !imposed && !signal;
+        const { refusal: stageRefusal, warning } = passing
+            ? stageVerdict(hookName, marks.map((mark) => mark.name), () => readStageLists(root, config), config.stageListRequired)
+            : { refusal: null, warning: null };
+        // A push, not a preflight: only a push has a commit git sends. Asked
+        // after the stage list, so a run that broke both says both.
+        const moved = passing && kind === "pre-push"
+            ? headMoved(hookName, head, readHead(root, env))
+            : null;
+        const refusals = [stageRefusal, moved].filter((r) => r !== null);
+        const refusal = refusals.length === 0 ? null : refusals.join("\n");
+        if (refusal !== null)
+            code = 1;
         if (quiet)
             report(code, ended - started);
-        const marks = parseStages(readOrNull(events), bootstrapMs);
+        if (refusal !== null)
+            stderr(`${refusal}\n`);
+        if (warning !== null)
+            stderr(`⚠️  ${warning}\n`);
         const { pushed, declared, proof, proofDiagnostics } = parseRecords(readOrNull(records));
         const verdict = (last) => imposed
             ? imposed.status
@@ -310,7 +335,7 @@ export const supervise = async ([hook, ...args], options) => {
                 durationMs: ended - started,
                 exitCode: code,
                 signal,
-                error,
+                error: error ?? refusal ?? warning ?? undefined,
                 status: verdict(false),
                 branch,
                 fingerprint,

package/dist/trailers.js

@@ -0,0 +1,61 @@
+// `dvara trailers <commit-msg-file>`, for a commit-msg hook. Git reads a
+// message's trailers (Co-Authored-By, Signed-off-by, a repository's own) only
+// from its last paragraph. A trailer line above a blank line is prose to git:
+// the commit lands, and the trailer is silently not there. This finds such
+// lines, so the hook can refuse the commit before that happens.
+/** The keys git and its hosts use themselves; a repository adds its own in `trailerKeys`. */
+export const GIT_TRAILER_KEYS = [
+    "Co-Authored-By",
+    "Signed-off-by",
+];
+/**
+ * Git's scissors line, with its default comment character: everything below
+ * it (the diff `commit -v` shows) is not the message.
+ */
+const SCISSORS = "# ------------------------ >8 ------------------------";
+/** A trailer key, as git reads one: letters, digits and `-`, then a colon. */
+const KEY = /^([A-Za-z0-9-]+)[ \t]*:/;
+/**
+ * The lines in `message` whose key is one of `keys` (any case) and that sit
+ * in a paragraph before the last, or in the title's paragraph (the title line
+ * aside), which git never reads trailers from. Comment lines are dropped, as git drops
+ * them, so a comment neither splits a paragraph nor ends one; blank lines
+ * (whitespace only) separate paragraphs; trailing ones start no new one.
+ */
+export const misplacedTrailers = (message, keys) => {
+    const known = new Set(keys.map((key) => key.toLowerCase()));
+    const paragraphs = [];
+    let open = null;
+    for (const [i, text] of message.split(/\r?\n/).entries()) {
+        if (text === SCISSORS)
+            break;
+        if (text.startsWith("#"))
+            continue;
+        if (text.trim() === "") {
+            open = null;
+            continue;
+        }
+        if (open === null) {
+            open = [];
+            paragraphs.push(open);
+        }
+        open.push({ line: i + 1, text });
+    }
+    // Git reads no trailers from the title's paragraph either, so a message of
+    // one paragraph keeps none; the title line itself is never a trailer.
+    const unread = paragraphs.length > 1 ? paragraphs.slice(0, -1) : paragraphs;
+    return unread
+        .flat()
+        .slice(1)
+        .filter(({ text }) => {
+        const key = KEY.exec(text)?.[1];
+        return key !== undefined && known.has(key.toLowerCase());
+    });
+};
+export const ADVICE = "Git reads trailers only from the last paragraph. Move these lines into the final block with no blank line between them (one `-F <file>` message), then check with `git log -1 --format=%(trailers)`.";
+/** The refusal for `misplaced` lines of `file`, one line per entry. */
+export const refusal = (file, misplaced) => [
+    `❌ trailers: ${file} has trailer lines git does not read (above a blank line, or in the title's paragraph):`,
+    ...misplaced.map(({ line, text }) => `  ${file}:${line} ${text}`),
+    ADVICE,
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veda-hq/dvara",
-  "version": "0.5.4",
+  "version": "0.6.4",
   "description": "Git hooks for repositories coding agents work in: runs each hook under a supervisor that times its stages, forwards signals and keeps one history row per run, with quiet output on success and a keep-going mode for preflights.",
   "keywords": [
     "git hooks",