@supersuit/superskill 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.4.0 (2026-09-29)
+
+**Approve from your phone.** `superskill approve` worked only at an interactive terminal, so an
+operator who reviews on a phone had to find a laptop to say yes. (Gary Sheng: *"The best way for
+me to approve it is to click yes, approve, not you telling me to go to my terminal. I'm normally
+mobile first."*) Away from a terminal it now accepts `--approved-by "<the person>"` and
+`--via "<where they said yes>"`, after that person approved with a tap on a board or a review page.
+Both are required and both are recorded (`via` on the approval), so an approval an agent relayed is
+always distinguishable from one typed at a terminal, and an agent still cannot approve with no
+named person and no channel. A rationale is required either way.
+
+- Tests: refused with no name, refused with a name and no channel, refused with no rationale;
+  recorded with person, channel and basis. The channel requirement was mutated out and went red.
+
 ## 0.3.1 (2026-09-29)
 
 The 0.3.0 changes below, released. The v0.3.0 tag's publish refused on a red test (SPEC.md still

package/README.md

@@ -54,7 +54,7 @@ Every rule and threshold is in [SPEC.md](SPEC.md).
 | `superskill init <skill> --from-session <transcript>` | Turn the session where you did the job by hand into the first eval and a golden candidate (Claude Code `.jsonl`, or any text file as the request). |
 | `superskill miss <skill> "<what happened>" [--expected "..."]` | Log a time the skill got it wrong. |
 | `superskill fix <skill> <miss-id> --eval <id> [--commit <sha>]` | Close a miss. Refuses without an eval that exists. |
-| `superskill approve <skill> <golden> [--basis judgment\|outcome] [--rationale ...] [--evidence ...]` | A person signs off on a golden, saying why and what it rests on: `judgment` (it reads right) or `outcome` (it produced a checkable result, with evidence). Terminal only, asks for your name, so an agent cannot approve its own output. Approvals accumulate. |
+| `superskill approve <skill> <golden> [--basis judgment\|outcome] [--rationale ...] [--evidence ...]` | A person signs off on a golden, saying why and what it rests on: `judgment` (it reads right) or `outcome` (it produced a checkable result, with evidence). At a terminal it asks for your name; from your phone, an agent records your tap with `--approved-by` and `--via`. Approvals accumulate. |
 | `superskill collection <folder...> [--budget <chars>] [--overlap 0.5]` | Listing budget used, descriptions that get cut off, pairs of skills an agent could confuse (with near-miss triggers to add). |
 | `superskill miss import <skill> --freedom-ledger [--ledger <file>]` | Import runs that needed correcting from Freedom's run ledger. |
 | `superskill snippet` | Print a block for `AGENTS.md` / `CLAUDE.md` that teaches any agent these habits. |

package/SPEC.md

@@ -1,6 +1,6 @@
 # The superskill standard
 
-**Version 0.3.1** (2026-09-29). The reference checker is `@supersuit/superskill`; where this
+**Version 0.4.0** (2026-09-29). The reference checker is `@supersuit/superskill`; where this
 document and the checker disagree, the checker has a bug.
 
 A **superskill** runs on frontier intelligence, is checked against examples a person approved,
@@ -157,7 +157,7 @@ A bare array of cases is accepted on read, as is `assertions` for `expectations`
 - `input.md`: the real request.
 - `output.md` (or any other file that is not `input.*` or `APPROVAL.json`): the output a person
   said was right.
-- `APPROVAL.json`, written only by `superskill approve` at an interactive terminal:
+- `APPROVAL.json`, written only by `superskill approve`: at an interactive terminal, or relayed by an agent with `--approved-by` and `--via` after the person approved with a tap (the `via` field records where):
 
 ```json
 { "approvals": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/superskill",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Score any agent skill folder as skill, tested, or superskill. An open standard and a zero-dependency CLI.",
   "type": "module",
   "bin": {

package/src/commands/approve.mjs

@@ -8,8 +8,10 @@ import { readGoldens, approvalEntry, withApproval, BASES } from "../goldens.mjs"
 
 export const help = `superskill approve <skill> <golden-id> [--rationale "<why it is right>"] [--basis judgment|outcome] [--evidence "<what happened, where to check>"]
 
-Record that a person checked goldens/<id>/ and signs off on its output. Works only at an
-interactive terminal and asks for your name, so an agent cannot approve its own output.
+Record that a person checked goldens/<id>/ and signs off on its output. At a terminal it asks
+for your name. From an agent (a phone tap on a board or review page), pass --approved-by
+"<the person>" and --via "<where they said yes>": both are required and both are recorded, so an
+approval an agent relayed is always distinguishable from one typed at a terminal.
 
 Every approval says WHY (--rationale, or asked) and WHAT IT RESTS ON (--basis, or asked):
   judgment  you read it and it is right (the default)
@@ -24,10 +26,25 @@ export async function run(argv) {
   const dir = skillDir(a._[0], "approve");
   const id = a._[1];
   if (!id) throw new UsageError("approve needs a golden id");
-  if (!(process.stdin.isTTY && process.stdout.isTTY)) return refuse("approval needs a person at a terminal. Run this yourself, not through an agent.");
   const g = readGoldens(dir).find((x) => x.id === id);
   if (!g) return refuse(`no goldens/${id}/`);
   if (g.input === null || g.output === null || !g.output.trim()) return refuse(`goldens/${id}/ needs an input file and a non-empty output file before it can be approved`);
+  if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+    // Mobile first: a person approves with a tap (a board, a review page) and an agent records it.
+    // The record names the person AND the channel, so an approval relayed by an agent is never
+    // mistaken for one typed at a terminal. Without both, an agent could approve its own output.
+    const name = String(a.flags["approved-by"] || "").trim();
+    const via = String(a.flags.via || "").trim();
+    if (!name || !via) return refuse("approval needs a person. At a terminal it asks for your name; from an agent, pass --approved-by \"<the person>\" and --via \"<where they approved: the tap, the page, the message>\", after that person said yes");
+    const sha = createHash("sha256").update(readFileSync(join(dir, "SKILL.md"))).digest("hex");
+    const made = approvalEntry({ name, rationale: a.flags.rationale || a.flags.note, basis: a.flags.basis || "judgment", evidence: a.flags.evidence, at: clock(a.flags).toISOString(), sha });
+    if (made.error) return refuse(made.error);
+    const p = join(dir, "goldens", id, "APPROVAL.json");
+    const existed = existsSync(p);
+    writeFileSync(p, JSON.stringify(withApproval(existed ? g.approval : null, { ...made.entry, via }), null, 2) + "\n");
+    process.stdout.write(`${existed ? "added an approval to" : "approved"} goldens/${id}/ by ${name} (${made.entry.basis}, via ${via})\n`);
+    return 0;
+  }
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
     process.stdout.write(`\n--- goldens/${id}/${g.outputFile} ---\n${g.output.slice(0, 2000)}${g.output.length > 2000 ? "\n[...]" : ""}\n---\n`);

package/src/goldens.mjs

@@ -54,6 +54,7 @@ export function approvalsOf(approval) {
       rationale: String(a.rationale ?? a.note ?? "").trim(),
       basis: a.basis === "outcome" ? "outcome" : "judgment",
       evidence: String(a.evidence ?? "").trim(),
+      via: String(a.via ?? "").trim(),
     }));
 }