approval-md 0.2.0 → 0.3.0

package/dist/src/cli/amend.js

@@ -59,12 +59,14 @@ import { createHash } from "node:crypto";
 import { accessSync, constants, existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve as resolvePathSegments, sep } from "node:path";
-import { HUMAN_ACTOR_ENV, appendAttestation, checkAttestation, policyFileHash, resolveHumanActor, } from "../core/attest.js";
+import { HUMAN_ACTOR_ENV, appendAttestation, attestedPolicyPayloadHash, checkAttestation, policyBytesHash, resolveHumanActor, } from "../core/attest.js";
 import { compareChains } from "../core/log-reconcile.js";
 import { diffPolicies, renderDiff, SPEC_NAMESPACES } from "../core/policy-diff.js";
 import { checkPolicyExpectations, describeFailure, describePinChange, diffPinSources, expectationsFor, DOGFOOD_SUITE_BUILT, DOGFOOD_SUITE_SOURCE, EXPECTATIONS_MODULE, } from "../core/policy-expectations.js";
 import { loadPolicy, parseDuration, POLICY_FILENAMES, } from "../core/policy-load.js";
-import { proposalState, proposeAttestation, } from "../core/policy-proposal.js";
+import { payloadHash } from "../core/payload.js";
+import { payloadPath, payloadStoreDirFor } from "../core/payload-store.js";
+import { proposalPayloadValue, proposalState, proposeAttestation, } from "../core/policy-proposal.js";
 import { readVerifiedRecords } from "../core/state.js";
 import { boolFlag, parseFlags, stringFlag } from "./args.js";
 import { EXIT_INTEGRITY, EXIT_IO, EXIT_OK, EXIT_TORN_TAIL, EXIT_USAGE, } from "./exit-codes.js";
@@ -83,6 +85,9 @@ const FLAGS = {
     "--require-load": "boolean",
     "--dry-run": "boolean",
     "--commit": "boolean",
+    // APRV-341: the whole ceremony in one word. Implies `--commit` and forces the
+    // branch flow, so the amendment reaches a protected trunk the only way it can.
+    "--pr": "boolean",
     "--no-publish": "boolean",
     "--branch": "string",
     "--direct": "boolean",
@@ -946,7 +951,11 @@ export function commandPolicyAmend(argv, streams, cwd) {
     }
     const dryRun = boolFlag(parsed.flags, "--dry-run");
     const requireLoad = boolFlag(parsed.flags, "--require-load");
-    const wantCommit = boolFlag(parsed.flags, "--commit");
+    // APRV-341. `--pr` is `--commit` plus "and finish the job": the branch flow,
+    // whatever the protection probe thinks, because the operator has said which
+    // ceremony they want. `--commit` alone keeps letting the probe decide.
+    const wantPr = boolFlag(parsed.flags, "--pr");
+    const wantCommit = boolFlag(parsed.flags, "--commit") || wantPr;
     // APRV-130: the ceremony publishes by default (push, and on a protected main
     // branch + push + PR). `--no-publish` is the operator who wants it to stop at
     // the commit, which is what `--commit` did before the publishing half existed.
@@ -960,6 +969,12 @@ export function commandPolicyAmend(argv, streams, cwd) {
     if (branchFlag !== null && branchFlag.trim().length === 0) {
         return usageError(streams, json, "--branch expects a branch name");
     }
+    if (wantPr && forceDirect) {
+        return usageError(streams, json, "--pr and --direct ask for opposite ceremonies: --pr publishes through a branch and a pull request, --direct commits on the branch you are standing on. Pass one of them");
+    }
+    if (wantPr && noPublish) {
+        return usageError(streams, json, "--pr and --no-publish ask for opposite ceremonies: --pr opens the pull request, --no-publish stops at the commit. Pass one of them");
+    }
     // Identity first, before a byte is read. Asking a human to read a diff and
     // only then telling them their sign-off cannot be attributed wastes the one
     // resource this system spends.
@@ -1006,13 +1021,54 @@ export function commandPolicyAmend(argv, streams, cwd) {
         return refuse(streams, json, "io", policy.message, EXIT_IO);
     const policyPath = policy.path;
     let liveSha256;
+    /**
+     * The live bytes as text, for the payload file this ceremony will commit
+     * (APRV-356).
+     *
+     * One read for both, on the rule `core/attest.ts` states for the same pair:
+     * two reads of a file an operator may still be editing can disagree, and the
+     * digest reported in the report has to be the digest of the bytes whose store
+     * file the `git add` names.
+     */
+    let liveText;
     try {
-        liveSha256 = policyFileHash(policyPath);
+        const liveBytes = readFileSync(policyPath);
+        liveSha256 = policyBytesHash(liveBytes);
+        liveText = liveBytes.toString("utf8");
     }
     catch (cause) {
         return refuse(streams, json, "io", `policy ${policyPath} could not be read: ${detail(cause)}`, EXIT_IO);
     }
     const logPath = resolvePath(stringFlag(parsed.flags, "--log"), DEFAULT_LOG_PATH, cwd);
+    /**
+     * The store file holding the attested policy text, absolute (APRV-356).
+     *
+     * The ceremony commit carries it beside the policy and the log, because a
+     * committed log carrying a binding whose payload file was never committed is
+     * a chain whose in-force bytes are unrecoverable to every reader of the
+     * committed copy, which is the state this task exists to end. The CI
+     * protected-path guard resolves payloads out of committed trees, so that copy
+     * is the one it reads.
+     *
+     * Which file it is depends on which door the attestation comes through, and
+     * both are addressable from the bytes on disk before anything is appended:
+     *
+     * - The HUMAN path appends the attestation here, and since APRV-356 that
+     *   record binds `{ text }` (`core/attest.ts`).
+     * - The AGENT path proposes and waits for a tap. The phone's attestation
+     *   stores nothing, which APRV-356 left unchanged; what carries the text on
+     *   that chain is the `policy.proposed` this ceremony appends, binding
+     *   `{ policy_path, text }` (`core/policy-proposal.ts`).
+     *
+     * Addressed from `liveText` rather than read back from the appended record,
+     * so it is a ceremony file from the start: `--dry-run` names it in the `git
+     * add` it would run, and `--commit` counts it as its own rather than as a
+     * stray in the index. An edit landing between here and the append moves the
+     * hash, and the append refuses on the digest before this path is used.
+     */
+    const payloadFile = payloadPath(payloadStoreDirFor(logPath), agentActor === null
+        ? attestedPolicyPayloadHash(liveText)
+        : payloadHash(proposalPayloadValue(policyPath, liveText)));
     // (a-pre) The thirty-three seconds of silence, ended (APRV-167).
     //
     // Everything from here to the `Policy` block below is work the operator could
@@ -1108,7 +1164,11 @@ export function commandPolicyAmend(argv, streams, cwd) {
     const onProtectedDefault = probe.protection === "protected" &&
         probe.currentBranch !== null &&
         probe.currentBranch === probe.defaultBranch;
-    const useBranch = branchFlag !== null || (!forceDirect && onProtectedDefault);
+    // APRV-341: `--pr` is a third way into the branch flow, and it is the
+    // operator's own instruction rather than an inference from a probe. A probe
+    // that cannot reach GitHub answers `unknown`, which used to mean "commit in
+    // place"; an operator who typed `--pr` has said what they want either way.
+    const useBranch = branchFlag !== null || wantPr || (!forceDirect && onProtectedDefault);
     const branchName = (seq) => branchFlag ?? `policy-amend-${seq}`;
     // The direct flow's push is about to hit a protected branch. Say so before
     // the human types it, rather than after GitHub says it.
@@ -1133,9 +1193,9 @@ export function commandPolicyAmend(argv, streams, cwd) {
      */
     let pinsChange = null;
     if (wantCommit && !dryRun) {
-        const plan = planCommit(policyPath, logPath, useBranch ? { branch: branchFlag } : null);
+        const plan = planCommit(policyPath, logPath, payloadFile, useBranch ? { branch: branchFlag } : null);
         if (!plan.ok) {
-            return refuse(streams, json, "commit-preconditions", plan.message, EXIT_USAGE);
+            return refuse(streams, json, plan.code, plan.message, EXIT_USAGE);
         }
         commitPlan = plan.plan;
         const prepared = prepareBase({ root: commitPlan.root, policyArg: commitPlan.policyArg, logPath, progress }, probe, attested?.sha256 ?? null);
@@ -1211,7 +1271,7 @@ export function commandPolicyAmend(argv, streams, cwd) {
         pinsChange = pinsChangeIn(amendRoot, policyPath, "HEAD");
     }
     /**
-     * The same command, with the two long absolute paths written the way the
+     * The same command, with the long absolute paths written the way the
      * operator would type them.
      *
      * This is a HUMAN transform and nothing else: `--json`'s `git.commands` keeps
@@ -1224,7 +1284,9 @@ export function commandPolicyAmend(argv, streams, cwd) {
             .split(policyPath)
             .join(relPath(policyPath, cwd))
             .split(logPath)
-            .join(relPath(logPath, cwd));
+            .join(relPath(logPath, cwd))
+            .split(payloadFile)
+            .join(relPath(payloadFile, cwd));
         return pinsChange === null
             ? shortened
             : shortened.split(pinsChange.path).join(relPath(pinsChange.path, cwd));
@@ -1242,8 +1304,13 @@ export function commandPolicyAmend(argv, streams, cwd) {
     };
     const summary = summarize(policyPath, diff, pinsChange);
     // APRV-274: the pins file is a member of the `git add` exactly when it moved,
-    // so a copied command lands the same three (or two) files the verb would.
-    const ceremonyFiles = [policyPath, logPath, ...(pinsChange === null ? [] : [pinsChange.path])];
+    // so a copied command lands the same three (or four) files the verb would.
+    const ceremonyFiles = [
+        policyPath,
+        logPath,
+        ...(pinsChange === null ? [] : [pinsChange.path]),
+        payloadFile,
+    ];
     const commitCommands = (seq) => [
         `git add ${ceremonyFiles.join(" ")}`,
         `git commit -m ${JSON.stringify(`Policy: ${summary} (attested seq ${seq})`)}`,
@@ -1251,15 +1318,31 @@ export function commandPolicyAmend(argv, streams, cwd) {
     const gitCommands = (seq) => {
         // APRV-203: `--commit` runs none of these; it assembles the commit on the
         // remote's tip without a checkout. These are the HAND procedure, and they
-        // start where `--commit` starts: at the remote, so the branch is not built
-        // on a local trunk that has fallen behind.
+        // start where `--commit` starts: with the checkout brought current, so the
+        // branch is not built on a local trunk that has fallen behind.
+        //
+        // APRV-360: and they never switch branches. The form printed before this
+        // opened with `git checkout -b policy-amend-<seq> origin/main`, which is
+        // the shape that forked the log on 2026-09-16 and that refused outright on
+        // 2026-09-18, when the primary's main was fourteen commits behind and the
+        // switch would have overwritten QUEUE.md, the working log and six
+        // payloads. A branch switch in the primary is never the right answer: the
+        // daemon is appending to the working log while the operator reads this.
+        //
+        // What replaces it is what the 2026-09-18 recovery actually did. `approval
+        // log sync` brings the checkout current (and refuses `log-diverged` rather
+        // than fast-forwarding over a fork), the commit is made where the operator
+        // is standing, and the branch is created on the REMOTE by refspec, so it
+        // exists without any local ref ever being checked out.
         if (useBranch) {
+            const branch = branchName(seq);
+            const base = probe.defaultBranch === null ? "" : ` --base ${probe.defaultBranch}`;
             return [
-                "git fetch origin",
-                `git checkout -b ${branchName(seq)} origin/${probe.defaultBranch ?? "main"}`,
+                "approval log sync",
                 ...commitCommands(seq),
-                `git push -u origin ${branchName(seq)}`,
-                `gh pr create --title ${JSON.stringify(prTitle(summary, seq))} --body ${JSON.stringify(prBody(seq))}`,
+                `git push origin HEAD:refs/heads/${branch}`,
+                `gh pr create --title ${JSON.stringify(prTitle(summary, seq))} --body ${JSON.stringify(prBody(seq))} --head ${branch}${base}`,
+                `gh pr merge ${branch} --auto --merge`,
             ];
         }
         return amendRoot === null
@@ -1506,6 +1589,7 @@ export function commandPolicyAmend(argv, streams, cwd) {
         branch: null,
         pushed: false,
         prUrl: null,
+        prUpdated: false,
         autoMerge: "not-attempted",
         steps: [],
         stoppedAt: null,
@@ -1615,6 +1699,11 @@ export function commandPolicyAmend(argv, streams, cwd) {
                 commitPlan.policyArg,
                 commitPlan.logArg,
                 ...(pinsChange === null ? [] : [pinsChange.arg]),
+                // APRV-356: the attested policy text, so the commit carrying the
+                // binding carries the bytes it binds. Without it the in-force policy is
+                // unrecoverable for every reader of the committed copy, the CI guard
+                // included.
+                commitPlan.payloadArg,
             ],
             message,
         });
@@ -1669,6 +1758,47 @@ export function commandPolicyAmend(argv, streams, cwd) {
             : `${commitSha.slice(0, 12)} on ${baseLabel} (held at ${anchor}; your checkout was not moved)`;
         /** `gh pr create …` as the operator would type it, for both flows. */
         const prCreateCommand = (head) => `gh pr create --title ${JSON.stringify(prTitle(summary, String(seq)))} --body ${JSON.stringify(prBody(String(seq)))} --head ${head}${probe.defaultBranch === null ? "" : ` --base ${probe.defaultBranch}`}`;
+        /**
+         * The open pull request for `head`, or `null` when there is none (APRV-341).
+         *
+         * Asked before `gh pr create`, because a second run of the ceremony onto a
+         * branch that already carries one is the ordinary shape of "the ceremony
+         * stopped half-way and I ran it again": `gh pr create` answers that with a
+         * failure, and a failure there used to end the verb holding an attestation
+         * it had already appended. A `gh` that cannot answer is `null`, which falls
+         * through to `create` — the path that was there before this existed.
+         */
+        const openPrFor = (head) => {
+            const listed = gh(["pr", "list", "--head", head, "--state", "open", "--json", "url"], commitPlan.root);
+            if (!listed.ok)
+                return null;
+            const text = listed.stdout.trim();
+            if (text.length === 0)
+                return null;
+            let rows;
+            try {
+                rows = JSON.parse(text);
+            }
+            catch {
+                return null;
+            }
+            if (!Array.isArray(rows))
+                return null;
+            const first = rows[0];
+            if (typeof first !== "object" || first === null)
+                return null;
+            const url = first.url;
+            return typeof url === "string" && url.length > 0 ? url : null;
+        };
+        const prEditArgs = (head) => [
+            "pr",
+            "edit",
+            head,
+            "--title",
+            prTitle(summary, String(seq)),
+            "--body",
+            prBody(String(seq)),
+        ];
         const prCreateArgs = (head) => [
             "pr",
             "create",
@@ -1714,11 +1844,22 @@ export function commandPolicyAmend(argv, streams, cwd) {
             publishing.pushed = true;
             output = `${output}\n${`${push.stdout}${push.stderr}`.trim()}`.trim();
             if (ghAvailable(commitPlan.root)) {
-                const pr = gh(prCreateArgs(branch), commitPlan.root);
-                publishing.steps.push({ command: prCreateCommand(branch), ok: pr.ok });
+                // APRV-341: open, or update the one that is already open for this
+                // branch. A ceremony re-run onto a branch a pull request already stands
+                // on is not an error to report, it is the state to bring up to date.
+                const standing = openPrFor(branch);
+                const pr = standing === null
+                    ? gh(prCreateArgs(branch), commitPlan.root)
+                    : gh(prEditArgs(branch), commitPlan.root);
+                publishing.steps.push({
+                    command: standing === null ? prCreateCommand(branch) : `gh pr edit ${branch} --title … --body …`,
+                    ok: pr.ok,
+                });
                 if (!pr.ok) {
                     const ghFailure = pr.stderr.trim() || pr.stdout.trim() || "gh did not run";
-                    return stalled("pr-failed", "`gh pr create` failed; the branch is already on origin", pr, `the attestation was appended at seq ${seq}, committed on ${branch} and pushed, but \`gh pr create\` failed: ${ghFailure}; open the pull request by hand and merge it with a merge commit`, [
+                    return stalled("pr-failed", standing === null
+                        ? "`gh pr create` failed; the branch is already on origin"
+                        : "`gh pr edit` failed; the branch and its pull request are already on origin", pr, `the attestation was appended at seq ${seq}, committed on ${branch} and pushed, but \`gh pr create\` failed: ${ghFailure}; open the pull request by hand and merge it with a merge commit`, [
                         `attestation appended at seq ${seq}: it is in the log, on disk`,
                         `committed on ${branch} and PUSHED: origin has the branch`,
                         "no pull request: origin's default branch still carries the previous policy",
@@ -1727,8 +1868,12 @@ export function commandPolicyAmend(argv, streams, cwd) {
                         { command: `gh pr merge ${branch} --merge`, note: "or merge it in the web UI" },
                     ], 0, [MERGE_COMMIT_LINE]);
                 }
-                prUrl = lastUrl(pr.stdout);
+                // `gh pr edit` prints the pull request's URL too, but the one this
+                // ceremony already knows is the one it asked for; `create` has nothing
+                // but its own output. Either way `null` is an honest answer.
+                prUrl = standing ?? lastUrl(pr.stdout);
                 publishing.prUrl = prUrl;
+                publishing.prUpdated = standing !== null;
                 publishing.complete = true;
                 // APRV-130: the ceremony offers to finish the last step too.
                 armAutoMerge(commitPlan.root, branch);
@@ -1865,7 +2010,10 @@ export function commandPolicyAmend(argv, streams, cwd) {
             // APRV-274: the headline names what the commit actually carries. A reader
             // who is told "the policy and the log" and finds a third file in the diff
             // has been told something false about the one commit that must not lie.
-            const carried = pinsChange === null ? "the policy and the log" : "the policy, the log and the pins";
+            // APRV-356 added the fourth: the store file holding the attested bytes.
+            const carried = pinsChange === null
+                ? "the policy, the log and the attested policy text"
+                : "the policy, the log, the pins and the attested policy text";
             const done = [
                 branch === null
                     ? `${st.glyph("ok")} committed ${carried} together:`
@@ -1958,6 +2106,8 @@ export function commandPolicyAmend(argv, streams, cwd) {
  * across two commits and a hand-run cherry-pick.
  */
 function planCommit(policyPath, logPath, 
+/** The store file holding the attested policy text, absolute (APRV-356). */
+payloadFile, 
 /**
  * The branch flow's preconditions, checked here for the same reason: an
  * `origin` that does not exist, or a branch name already taken, would fail
@@ -1971,11 +2121,16 @@ branchFlow) {
     if (root === null) {
         return {
             ok: false,
+            code: "commit-preconditions",
             message: `--commit needs a git repository and ${policyPath} is not inside one; nothing was attested`,
         };
     }
     const policyArg = repoPath(root, policyPath);
     const logArg = repoPath(root, logPath);
+    // APRV-356. The payload store is a sibling of the log directory, so a log
+    // inside the repository puts this inside it too; the check below covers both
+    // with one sentence rather than naming a path no operator chose.
+    const payloadArg = repoPath(root, payloadFile);
     // APRV-274. `null` where these pins do not govern this policy, and where the
     // repository simply has no pins module: in both cases the ceremony's file set
     // is the two it always was.
@@ -1985,32 +2140,59 @@ branchFlow) {
     if (policyArg.startsWith("../") || logArg.startsWith("../")) {
         return {
             ok: false,
+            code: "commit-preconditions",
             message: `--commit needs the policy (${policyPath}) and the log (${logPath}) inside the same repository (${root}); nothing was attested`,
         };
     }
     const status = git(["status", "--porcelain"], root);
     if (!status.ok) {
-        return { ok: false, message: `--commit could not read git status: ${status.stderr.trim()}` };
+        return {
+            ok: false,
+            code: "commit-preconditions",
+            message: `--commit could not read git status: ${status.stderr.trim()}`,
+        };
     }
+    const ceremonyFiles = [policyArg, logArg, payloadArg, ...(pinsArg === null ? [] : [pinsArg])];
+    const carried = pinsArg === null
+        ? "the policy, the log and the attested policy text"
+        : `the policy, the log, the attested policy text and ${pinsArg}`;
     const strays = [];
+    /** Ceremony files staged in one state and left in another (APRV-341). */
+    const split = [];
     for (const line of status.stdout.split("\n")) {
         if (line.trim().length === 0)
             continue;
         const index = line[0] ?? " ";
-        // Only the INDEX column matters: an unstaged or untracked file elsewhere is
-        // not going into this commit, and refusing over it would make the verb
-        // unusable in any working repository.
+        const worktree = line[1] ?? " ";
+        const path = line.slice(3).trim();
+        const ceremony = ceremonyFiles.includes(path);
+        // A ceremony file the operator staged and then edited again. The commit is
+        // assembled from the working tree, so the bytes it would carry are not the
+        // bytes `git diff --cached` shows, and an amendment is the one commit that
+        // may not be a surprise to the person who signed it.
+        if (ceremony && index !== " " && index !== "?" && worktree === "M")
+            split.push(path);
+        // Only the INDEX column matters for everything else: an unstaged or
+        // untracked file elsewhere is not going into this commit (the scratch index
+        // lays exactly the ceremony paths over the remote's tree), and refusing
+        // over one would make the verb unusable in any working repository.
         if (index === " " || index === "?")
             continue;
-        const path = line.slice(3).trim();
-        if (path === policyArg || path === logArg || path === pinsArg)
+        if (ceremony)
             continue;
         strays.push(path);
     }
+    if (split.length > 0) {
+        return {
+            ok: false,
+            code: "dirty-tree",
+            message: `--commit refuses: ${split.join(", ")} ${split.length === 1 ? "is" : "are"} staged in one state and modified again in the working tree. The amendment commit is assembled from the WORKING TREE, so it would carry bytes your \`git diff --cached\` does not show, and the one commit that may not surprise the person who signed it is this one. Stage the file as it stands (\`git add ${split.join(" ")}\`) or unstage it, then run this again. Nothing was attested`,
+        };
+    }
     if (strays.length > 0) {
-        const carried = pinsArg === null ? "the policy and the log" : `the policy, the log and ${pinsArg}`;
         return {
             ok: false,
+            code: "staged-unrelated",
             message: `--commit refuses: the index carries ${strays.length} staged change(s) beyond ${carried} (${strays.join(", ")}). The amendment commit carries EXACTLY those files, so that "this commit is the amendment" stays true. Unstage them, or drop --commit and run the printed commands yourself. Nothing was attested`,
         };
     }
@@ -2019,6 +2201,7 @@ branchFlow) {
         if (!remote.ok) {
             return {
                 ok: false,
+                code: "commit-preconditions",
                 message: `--commit on a branch needs an "origin" remote to push to, and ${root} has none (${remote.stderr.trim()}); pass --direct to commit in place, or add the remote. Nothing was attested`,
             };
         }
@@ -2027,12 +2210,13 @@ branchFlow) {
             if (exists.ok) {
                 return {
                     ok: false,
+                    code: "commit-preconditions",
                     message: `--branch ${branchFlow.branch} already exists in ${root}; the amendment branch is created fresh so it carries exactly one commit. Pick another name. Nothing was attested`,
                 };
             }
         }
     }
-    return { ok: true, plan: { root, policyArg, logArg, pinsArg } };
+    return { ok: true, plan: { root, policyArg, logArg, pinsArg, payloadArg } };
 }
 /**
  * Fetch the remote and establish that this ceremony may be based on it (APRV-203).