Shepherd: prove an agent task is retained and least-privilege before it runs

The Stack

Steps

1. 1

   Declare the grants and validate the safety posture

   Write the task's per-repo grants and set apply_mode to retained so the output is held to one side, not applied. CI checks nothing auto-applies and that every write grant is explicitly acknowledged (least privilege: repos are read-only unless you say otherwise). Running the task and the OS-level enforcement are fenced.

   cat > grants.json <<'JSON'
   {
     "task": "refactor-auth",
     "apply_mode": "retained",
     "grants": [
       { "repo": "app", "access": "read_write", "acknowledged": true },
       { "repo": "vendor", "access": "read_only" },
       { "repo": "secrets", "access": "read_only" }
     ]
   }
   JSON
   node -e '
   const fs = require("fs");
   const c = JSON.parse(fs.readFileSync("grants.json", "utf8"));
   function bad(m) { console.error("BAD: " + m); process.exit(1); }
   if (c.apply_mode !== "retained") bad("apply_mode must be retained (nothing applies until you accept it)");
   const grants = c.grants || [];
   if (grants.length < 1) bad("declare at least one repo grant");
   let ro = 0, rw = 0;
   for (const g of grants) {
     if (!g.repo) bad("each grant needs a repo");
     if (g.access !== "read_only" && g.access !== "read_write") bad("grant for " + g.repo + " must be read_only or read_write");
     if (g.access === "read_write") {
       if (g.acknowledged !== true) bad("write grant for " + g.repo + " must be explicitly acknowledged (least privilege)");
       rw++;
     } else {
       ro++;
     }
   }
   console.log("grants OK: task retained (not auto-applied); " + grants.length + " repo(s), " + ro + " read-only, " + rw + " read-write (all acknowledged)");
   '

2. 2

   Run it, then keep or discard (the run step, not checked by CI)

   Install Shepherd (pip install shepherd-ai), shepherd init, run the task; its output is retained, not applied. Inspect the changeset (shepherd run changeset --latest), then shepherd run select to keep it or shepherd run discard to throw it away. On a supported OS the read-only grants are enforced by the kernel. The run and enforcement are fenced.