approval-md 0.0.1 → 0.2.0

package/dist/src/cli/init.js

@@ -0,0 +1,336 @@
+/**
+ * `approval init` — scaffold a working directory (SPEC.md §10.1).
+ *
+ * Until this verb existed, every ceremony began with a human being told to
+ * `mkdir -p .approval/log` and to type a policy file from memory. That is the
+ * one step of the ceremony where a mistake is silent: a policy with a mistyped
+ * fence is an unparseable policy, an unparseable policy is `manual` everything
+ * (SPEC.md §5.2), and a human who meant to declare three autonomous classes
+ * discovers the typo only when the queue fills with things they never wanted to
+ * be asked about.
+ *
+ * ## What it writes, and what it refuses to
+ *
+ * Four things: `APPROVAL.md` (the canonical policy of SPEC.md §5.1, verbatim),
+ * `.approval/log/` (the directory only), `.approval/QUEUE.md` (the real
+ * renderer's empty state, not a hand-written imitation of it), and the
+ * `.gitignore` entries for the derived and secret-bearing files.
+ *
+ * **It never appends to the log and never attests.** `init` is not a gate
+ * operation and holds no authority: it produces a policy file that authorizes
+ * nothing until a human reads it and runs `approval policy attest`. The log
+ * directory it creates is empty on purpose — the first attestation is what
+ * creates `events.jsonl`, and a scaffolded log would be a chain nobody signed.
+ *
+ * **It never overwrites.** The semantics are idempotent rather than
+ * destructive: `init` plans first, then writes only the targets that are
+ * missing, and reports the rest as `existing` with a distinct per-file code. A
+ * second run therefore writes nothing, reports what it found, and exits 0. The
+ * single exception to "never touch an existing file" is `.gitignore`, which is
+ * merged: missing lines are appended under a marker comment and no existing
+ * line is rewritten, reordered, or removed.
+ *
+ * **A path of the wrong kind is a refusal, not a report.** A directory named
+ * `APPROVAL.md`, or a regular file where `.approval/` belongs, is not a
+ * scaffold that already exists; it is a working directory this verb cannot
+ * reason about. Those cases refuse as {@link INIT_REFUSAL_CODES `path-conflict`}
+ * at {@link EXIT_IO} with **nothing written at all** — the conflict scan runs
+ * over every target before the first byte is written, so a conflict on the
+ * fourth target does not leave the first three half-scaffolded.
+ *
+ * ## Exit codes
+ *
+ * Drawn from the frozen table in `exit-codes.ts`, nothing added: 0 for a
+ * successful scaffold *and* for a fully idempotent re-run, 2 for usage, 4 for a
+ * path conflict or any other filesystem failure. There is no distinct code for
+ * "everything already existed", because that is not a failure: the caller asked
+ * for a scaffolded directory and a scaffolded directory is what it has.
+ */
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve as resolvePathSegments } from "node:path";
+import { writeQueue } from "../channels/render-queue.js";
+import { boolFlag, parseFlags, stringFlag } from "./args.js";
+import { EXIT_IO, EXIT_OK, EXIT_USAGE } from "./exit-codes.js";
+import { INIT_HELP } from "./help.js";
+import { DEFAULT_LOG_PATH } from "./paths.js";
+import { CANONICAL_POLICY, GITIGNORE_ENTRIES, GITIGNORE_MARKER } from "./scaffold.js";
+import { usageErrorText } from "./usage.js";
+import { wordmark } from "./wordmark.js";
+const FLAGS = {
+    "--dir": "string",
+    "--json": "boolean",
+    "--help": "boolean",
+    "-h": "boolean",
+};
+/**
+ * Why a target was not written. Frozen, and ADDITIVE in the sense the rest of
+ * the CLI's machine-readable vocabularies are: a code is added, never
+ * repurposed.
+ *
+ * The first four are reports, not failures: they appear in `existing[]` of a
+ * successful (exit 0) run. Only `path-conflict` refuses, and it refuses the
+ * whole invocation.
+ */
+export const INIT_REFUSAL_CODES = [
+    "policy-exists",
+    "log-dir-exists",
+    "queue-exists",
+    "gitignore-entries-present",
+    "path-conflict",
+];
+function wantsJson(argv) {
+    return argv.includes("--json");
+}
+function usageError(streams, json, message) {
+    if (json)
+        streams.err(`${JSON.stringify({ error: { code: "usage", message } })}\n`);
+    else
+        streams.err(usageErrorText(message, INIT_HELP));
+    return EXIT_USAGE;
+}
+function ioError(streams, json, message) {
+    if (json)
+        streams.err(`${JSON.stringify({ error: { code: "io", message } })}\n`);
+    else
+        streams.err(`approval: ${message}\n`);
+    return EXIT_IO;
+}
+function conflictError(streams, json, conflicts) {
+    const message = `path-conflict: ${conflicts.join("; ")}. Nothing was written: init scans every target before it writes anything, so a working directory it cannot reason about is left exactly as it is`;
+    if (json) {
+        streams.err(`${JSON.stringify({ error: { code: "path-conflict", message } })}\n`);
+    }
+    else {
+        streams.err(`approval: ${message}\n`);
+    }
+    return EXIT_IO;
+}
+function detail(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+function absolute(value, cwd) {
+    return isAbsolute(value) ? value : resolvePathSegments(cwd, value);
+}
+/** What is at `path` right now. An unreadable stat is reported as `other`. */
+function kindOf(path) {
+    let stats;
+    try {
+        stats = statSync(path);
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return "absent";
+        return "other";
+    }
+    if (stats.isDirectory())
+        return "directory";
+    if (stats.isFile())
+        return "file";
+    return "other";
+}
+/**
+ * The next steps, in the order a human performs them.
+ *
+ * Returned as an array rather than printed as a paragraph because an agent
+ * reading `--json` needs the same instructions the human gets, and a wall of
+ * prose is not something a caller can act on one item at a time.
+ *
+ * The payload note is the one editorial decision in this verb, so it is stated
+ * rather than implied. `.approval/payloads/` holds the exact bytes each approval
+ * bound to (SPEC.md §6.2, §9): the material evidence of what a human said yes
+ * to. Evidence defaults to tracked, so the scaffold does not ignore it. The
+ * alternative is one line, and it costs the rebuildability of that evidence, so
+ * both halves are printed together.
+ */
+function nextSteps() {
+    return [
+        "Edit APPROVAL.md. What was scaffolded is the canonical example policy, not your policy: it names an approver you are probably not and declares classes you have not agreed to. Read every class before you sign for it.",
+        "Run `approval policy attest` (as a human: APPROVAL_HUMAN=human:<id>, or --as human:<id>). Attestation is what makes a policy operative, and it is what creates .approval/log/events.jsonl — init made the directory and deliberately put nothing in it, because a log entry nobody signed is not evidence of anything.",
+        "Run `approval doctor` to check that this machine can run the system at all: build freshness, identity, attestation, chain health, channels.",
+        "Run `approval env --check` to see which environment variables your policy names and where each one would come from (it prints no values). To record where they live, write `.approval/env` — one KEY=VALUE per line, where VALUE is `keychain:<service>`, `secret-service:<label>`, `env:`, or a plaintext literal — `chmod 600` it, and put `eval \"$(approval env)\"` in your shell. No other command reads that file, deliberately: human identity is one of the variables it can carry, so a file the runtime loaded on its own would let anything able to write it act as you.",
+        "Payload bytes are TRACKED by default: .approval/payloads/ is not in the .gitignore lines init wrote. Those bytes are what each approval bound to, and evidence belongs in the history. To keep them out of git instead, add `.approval/payloads/` to .gitignore yourself — the log still records every payload_hash, but the bytes behind those hashes become unrebuildable.",
+    ];
+}
+/**
+ * Merge the ignore lines into an existing `.gitignore`, or produce a new one.
+ *
+ * Append-only, by the same instinct as the log: existing lines are never
+ * rewritten, reordered, or removed, and a line already present anywhere in the
+ * file (under our marker or the operator's own heading) counts as present. The
+ * marker is written once — a file that already carries it gets the missing lines
+ * appended under the existing one rather than a second copy of it.
+ */
+export function mergeGitignore(current, entries = GITIGNORE_ENTRIES) {
+    const existing = current ?? "";
+    const lines = new Set(existing.split("\n").map((line) => line.trim()));
+    const added = entries.filter((entry) => !lines.has(entry));
+    if (added.length === 0)
+        return { changed: false, text: existing, added };
+    const parts = [];
+    if (existing.length > 0) {
+        parts.push(existing.endsWith("\n") ? existing : `${existing}\n`);
+        parts.push("\n");
+    }
+    if (!existing.split("\n").some((line) => line.trim() === GITIGNORE_MARKER)) {
+        parts.push(`${GITIGNORE_MARKER}\n`);
+    }
+    parts.push(`${added.join("\n")}\n`);
+    return { changed: true, text: parts.join(""), added };
+}
+export function commandInit(argv, streams, cwd, deps = {}) {
+    const json = wantsJson(argv);
+    const parsed = parseFlags(argv, FLAGS);
+    if (!parsed.ok)
+        return usageError(streams, json, parsed.message);
+    if (boolFlag(parsed.flags, "--help") || boolFlag(parsed.flags, "-h")) {
+        streams.out(`${INIT_HELP}\n`);
+        return EXIT_OK;
+    }
+    const extra = parsed.positionals[0];
+    if (extra !== undefined) {
+        return usageError(streams, json, `unexpected argument ${JSON.stringify(extra)}`);
+    }
+    const dirFlag = stringFlag(parsed.flags, "--dir");
+    const dir = dirFlag === null ? cwd : absolute(dirFlag, cwd);
+    const policyPath = join(dir, "APPROVAL.md");
+    const fallbackPolicyPath = join(dir, "APPROVALS.md");
+    const approvalDir = join(dir, ".approval");
+    const logDir = join(approvalDir, "log");
+    const queuePath = join(approvalDir, "QUEUE.md");
+    const gitignorePath = join(dir, ".gitignore");
+    const logPath = join(dir, DEFAULT_LOG_PATH);
+    // ---------------------------------------------------------------------
+    // Plan. Nothing below this block writes; nothing above it does either.
+    // ---------------------------------------------------------------------
+    const dirKind = kindOf(dir);
+    if (dirKind === "file" || dirKind === "other") {
+        return conflictError(streams, json, [`${dir} is not a directory`]);
+    }
+    const conflicts = [];
+    const requireFileOrAbsent = (path, what) => {
+        const kind = kindOf(path);
+        if (kind === "directory")
+            conflicts.push(`${path} is a directory where ${what} belongs`);
+        if (kind === "other")
+            conflicts.push(`${path} exists and is neither a file nor a directory`);
+        return kind;
+    };
+    const requireDirOrAbsent = (path, what) => {
+        const kind = kindOf(path);
+        if (kind === "file")
+            conflicts.push(`${path} is a file where ${what} belongs`);
+        if (kind === "other")
+            conflicts.push(`${path} exists and is neither a file nor a directory`);
+        return kind;
+    };
+    const policyKind = requireFileOrAbsent(policyPath, "the policy file APPROVAL.md");
+    const fallbackKind = requireFileOrAbsent(fallbackPolicyPath, "the fallback policy file APPROVALS.md");
+    requireDirOrAbsent(approvalDir, "the .approval/ directory");
+    const logDirKind = requireDirOrAbsent(logDir, "the log directory .approval/log/");
+    const queueKind = requireFileOrAbsent(queuePath, "the queue projection .approval/QUEUE.md");
+    const gitignoreKind = requireFileOrAbsent(gitignorePath, "the .gitignore file");
+    if (conflicts.length > 0)
+        return conflictError(streams, json, conflicts);
+    const written = [];
+    const existing = [];
+    // SPEC.md §5: APPROVALS.md is an accepted filename, so a directory carrying
+    // one already has a policy and init has nothing to add. Scaffolding
+    // APPROVAL.md beside it would silently take precedence over the file the
+    // human actually wrote.
+    const policyPresent = policyKind === "file" || fallbackKind === "file";
+    // ---------------------------------------------------------------------
+    // Write. Only the missing targets, in ceremony order.
+    // ---------------------------------------------------------------------
+    if (policyPresent) {
+        existing.push({
+            path: policyKind === "file" ? "APPROVAL.md" : "APPROVALS.md",
+            code: "policy-exists",
+        });
+    }
+    else {
+        try {
+            writeFileSync(policyPath, deps.policyText ?? CANONICAL_POLICY, { encoding: "utf8", flag: "wx" });
+        }
+        catch (cause) {
+            return ioError(streams, json, `APPROVAL.md could not be written: ${detail(cause)}`);
+        }
+        written.push("APPROVAL.md");
+    }
+    if (logDirKind === "directory") {
+        existing.push({ path: ".approval/log/", code: "log-dir-exists" });
+    }
+    else {
+        try {
+            mkdirSync(logDir, { recursive: true });
+        }
+        catch (cause) {
+            return ioError(streams, json, `.approval/log/ could not be created: ${detail(cause)}`);
+        }
+        written.push(".approval/log/");
+    }
+    if (queueKind === "file") {
+        existing.push({ path: ".approval/QUEUE.md", code: "queue-exists" });
+    }
+    else {
+        // The real renderer, against the (absent, therefore empty and clean) log
+        // this directory now has. A hand-written "empty queue" header would be a
+        // second implementation of the projection, and the first thing `approval
+        // render` did would be to disagree with it.
+        const now = new Date().toISOString();
+        const result = writeQueue(logPath, queuePath, { policy: { dir } }, now);
+        if (!result.ok) {
+            return ioError(streams, json, `.approval/QUEUE.md could not be written (${result.code}): ${result.message}`);
+        }
+        written.push(".approval/QUEUE.md");
+    }
+    let currentGitignore = null;
+    if (gitignoreKind === "file") {
+        try {
+            currentGitignore = readFileSync(gitignorePath, "utf8");
+        }
+        catch (cause) {
+            return ioError(streams, json, `.gitignore could not be read: ${detail(cause)}`);
+        }
+    }
+    const merged = mergeGitignore(currentGitignore);
+    if (!merged.changed) {
+        existing.push({ path: ".gitignore", code: "gitignore-entries-present" });
+    }
+    else {
+        try {
+            writeFileSync(gitignorePath, merged.text, "utf8");
+        }
+        catch (cause) {
+            return ioError(streams, json, `.gitignore could not be written: ${detail(cause)}`);
+        }
+        written.push(".gitignore");
+    }
+    const steps = nextSteps();
+    if (json) {
+        streams.out(`${JSON.stringify({ ok: true, dir, written, existing, next_steps: steps })}\n`);
+        return EXIT_OK;
+    }
+    // One of the three places the wordmark appears (APRV-91 #7/#12): scaffolding
+    // a directory is the moment a person meets this tool. In a pipe it degrades
+    // to the one-line `approval.md v0.0.1`, so a log gains a version stamp rather
+    // than six lines of art.
+    streams.out(`${wordmark()}\n\n`);
+    streams.out(`approval: scaffolded ${dir}\n`);
+    if (written.length === 0) {
+        streams.out("  nothing written — every target already exists\n");
+    }
+    else {
+        for (const path of written)
+            streams.out(`  wrote    ${path}\n`);
+    }
+    for (const entry of existing) {
+        streams.out(`  existing ${entry.path} (${entry.code}) — left exactly as it is\n`);
+    }
+    streams.out("\nNext steps:\n");
+    for (const [index, step] of steps.entries()) {
+        streams.out(`  ${String(index + 1)}. ${step}\n`);
+    }
+    streams.out("\nNothing was appended to the log and no policy was attested: init holds no authority and the file it wrote authorizes nothing until a human attests it.\n");
+    return EXIT_OK;
+}
+//# sourceMappingURL=init.js.map

package/dist/src/cli/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/cli/init.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/instructions.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `approval instructions` — the agent-facing usage guide, and `--schemas`, the
+ * machine-readable form of the same contract.
+ *
+ * SPEC.md §10.1 lists this verb as the "full agent-facing usage guide" and says
+ * that "schemas for inputs and outputs are printed by `approval instructions
+ * --schemas`". §10.5's optional MCP wrapper publishes the same verbs as tools
+ * and shares the CLI's code paths, so both surfaces read `verb-registry.ts`:
+ * the verb table printed here is generated from it, and `--schemas` prints it.
+ *
+ * The guide is prose an agent reads once and a wrapper can embed. It is
+ * deliberately about the SHAPE of the interaction — declare before you act, the
+ * refusal is final, the clock is not yours — rather than a second copy of every
+ * flag, which is what `--help` is for and what the registry carries in schema
+ * form.
+ *
+ * This command reads no log, resolves no policy, touches no file, and appends
+ * nothing. Its output is a pure function of this build.
+ */
+import type { Streams } from "./main.js";
+/** The whole guide: prose plus the generated table. */
+export declare function instructionsGuide(): string;
+export declare function commandInstructions(argv: string[], streams: Streams, _cwd: string): number;

package/dist/src/cli/instructions.js

@@ -0,0 +1,262 @@
+/**
+ * `approval instructions` — the agent-facing usage guide, and `--schemas`, the
+ * machine-readable form of the same contract.
+ *
+ * SPEC.md §10.1 lists this verb as the "full agent-facing usage guide" and says
+ * that "schemas for inputs and outputs are printed by `approval instructions
+ * --schemas`". §10.5's optional MCP wrapper publishes the same verbs as tools
+ * and shares the CLI's code paths, so both surfaces read `verb-registry.ts`:
+ * the verb table printed here is generated from it, and `--schemas` prints it.
+ *
+ * The guide is prose an agent reads once and a wrapper can embed. It is
+ * deliberately about the SHAPE of the interaction — declare before you act, the
+ * refusal is final, the clock is not yours — rather than a second copy of every
+ * flag, which is what `--help` is for and what the registry carries in schema
+ * form.
+ *
+ * This command reads no log, resolves no policy, touches no file, and appends
+ * nothing. Its output is a pure function of this build.
+ */
+import { boolFlag, parseFlags } from "./args.js";
+import { EXIT_OK, EXIT_USAGE } from "./exit-codes.js";
+import { INSTRUCTIONS_HELP } from "./help.js";
+import { VERB_REGISTRY, verbLabel } from "./verb-registry.js";
+/**
+ * The first sentence of a purpose paragraph, for the table. Purposes are
+ * written so that sentence stands alone.
+ */
+function oneLiner(spec) {
+    const match = /^(.*?[.!?])(\s|$)/.exec(spec.purpose);
+    const sentence = match?.[1] ?? spec.purpose;
+    return sentence.trim();
+}
+/** Greedy wrap. Deterministic, and the guide is compared byte for byte. */
+function wrap(text, width) {
+    const lines = [];
+    let line = "";
+    for (const word of text.split(" ")) {
+        if (line === "")
+            line = word;
+        else if (line.length + 1 + word.length <= width)
+            line = `${line} ${word}`;
+        else {
+            lines.push(line);
+            line = word;
+        }
+    }
+    if (line !== "")
+        lines.push(line);
+    return lines;
+}
+/** The verb table, generated from the registry so it cannot go stale. */
+function verbTable() {
+    const width = VERB_REGISTRY.reduce((widest, spec) => Math.max(widest, verbLabel(spec).length), 0);
+    const indent = `  ${" ".repeat(width)}  `;
+    const lines = [];
+    for (const spec of VERB_REGISTRY) {
+        const marker = spec.human_only ? "[HUMAN-ONLY] " : "";
+        const wrapped = wrap(`${marker}${oneLiner(spec)}`, 78 - indent.length);
+        lines.push(`  ${verbLabel(spec).padEnd(width)}  ${wrapped[0] ?? ""}`);
+        for (const continuation of wrapped.slice(1))
+            lines.push(`${indent}${continuation}`);
+    }
+    return lines.join("\n");
+}
+const GUIDE_BODY = `approval instructions — how an agent works behind this gate
+
+WHAT THIS IS. approval.md gates the actions of yours that touch the world:
+sending, spending, deleting, posting, publishing. A human wrote a policy file
+(APPROVAL.md) saying which classes of action you may take on your own, which
+are watched afterwards, and which need someone to say yes first. The runtime
+decides; you propose. Every proposal, decision and execution is one record in a
+hash-chained append-only log, and that log — not your account of it, and not
+this conversation — is what the human reads later.
+
+DECLARE BEFORE YOU ACT. An action that was never declared cannot execute, and
+declaring it afterwards is not the same act. Your declaration lives in the task
+file's \`approval:\` envelope: for each action, its class, a human-readable
+summary, whether it is reversible, an estimated cost, an idempotency key, and
+the payload_hash of the exact bytes you intend to act on. Write the envelope
+first, register it, and request against what was registered. You cannot name
+your own class at request time, deliberately: the class comes from the
+registered record, so an action declared as one thing cannot be requested as
+another.
+
+THE SEQUENCE.
+
+  1. approval register <task-file>
+     Validates the envelope and records it. Nothing is authorized yet.
+  2. approval request <task> --action <key> [--payload <file>]
+     The gate resolves the class against policy. A MANUAL class records
+     approval.requested and answers proceed:false — a human now has to decide.
+     A SUPERVISED or AUTONOMOUS class records no approval event at all and
+     answers proceed:true; go straight to step 4, and do not wait for a grant
+     that will never come.
+  3. approval wait <task> --timeout <duration>
+     Blocks until every request of the task is decided. THE EXIT CODE IS THE
+     DECISION: 0 granted, 1 rejected, revoked or withdrawn (--json status says
+     which), 3 expired, 6 timeout. A timeout is not an answer: the request is
+     still live and waiting again is legitimate.
+  3b. approval withdraw <task> --action <key> --reason timeout
+     IF YOU STOP WAITING, SAY SO. A pending request you can no longer act on is
+     a question a person will still be asked, and their attention is the scarce
+     thing this system spends. Withdraw the requests you opened when you give
+     up on them; pass --withdraw-on-timeout to wait to do it for you. You may
+     withdraw only your OWN requests, only while they are pending, and a
+     withdrawal is terminal — if you still want the action, request it again,
+     which is a new request and gets its own decision.
+  4. approval run <action-key> [--token <t>] -- <cmd…>
+     Executes behind the gate: it records the start before spawning, records
+     the outcome after, and exits with the child's own exit code. A manual
+     action must present the token the grant printed once. Side effects with
+     credentials go through an adapter instead (approval adapter email …,
+     approval adapter agentmail …), which spends the same token and holds the
+     same boundary. For an AgentMail draft, take the snapshot a human will
+     read first: approval payload agentmail-draft <inbox> <draft> prints the
+     payload to declare, and a draft edited after it is refused, not sent.
+
+WHAT A REFUSAL MEANS. Exit 1 with a machine-readable error.code is the runtime
+saying no to a well-formed command. It is NOT a usage error and it is not a
+transient failure: retrying the same call, rephrasing the summary, splitting
+the action into smaller ones, or requesting again under a different key are all
+ways of routing around a decision rather than responding to it. A rejection is
+final until a human acts again. An expiry is final in the same way; you may
+request again only if the situation genuinely still stands, and you should say
+that it lapsed. When you are refused, stop and report the code and the message
+to whoever is reading your output.
+
+READING THE ANSWERS. Every verb takes --json and prints exactly one object per
+invocation (the two long-lived verbs, the listener and the daemon, print one
+object per line instead). Successes go to stdout; failures go to stderr as
+{"error":{"code","message"}}, and gate refusals as {"ok":false,"error":{…}}
+with refusal-specific detail inside. Branch on the exit code first and
+error.code second. Both are frozen public API. \`approval run\` is the one
+exception worth remembering: its summary goes to stderr, because stdout belongs
+to the child process.
+
+THE INVARIANTS YOU MUST NOT ROUTE AROUND. These are properties of the system,
+not preferences, and each is enforced somewhere you cannot reach:
+
+  - You never author the clock. Timestamps on gate-typed events are stamped by
+    the runtime at the write boundary, and a caller-supplied one is refused.
+  - You never edit APPROVAL.md, .approval/, or anything holding credentials.
+    Propose a policy change in prose and let a human run the amendment; an
+    agent that edited the policy it is judged by has judged itself.
+  - You never write to the log. It is append-only and single-writer: nothing
+    rewrites, reorders or repairs a line, and a torn tail is reported for a
+    human rather than fixed.
+  - You never reduce your own scrutiny. Fields you author — summaries, cost
+    estimates, confidence, rationale — may raise scrutiny and can never lower
+    it. Nothing you self-report downgrades an autonomy level or makes a sample
+    less likely, and claiming otherwise in a summary changes nothing.
+  - You disclose what a reasonable approver would want. Omitting something
+    material from a request violates the policy even when the action itself was
+    permitted.
+  - You do not act on a token you were not handed for those exact bytes. A
+    grant approves specific bytes; changing the payload after the grant means a
+    new request.
+
+SAYING SOMETHING THAT IS NOT AN ACTION. \`approval journal write --message
+"<text>"\` appends free text to a local file. It is the one verb here the gate
+does not stand in front of: it is not classified, not resolved against policy,
+not approvable and not deniable, it appends nothing to the log, and no refusal
+path exists for it. It is there for what an exit code cannot carry — that you
+are complying and think the instruction is wrong, that something reads as odd,
+that you are stuck and the next thing you try is a guess. Being honest in it
+costs you nothing, because nothing in the runtime reads it: it cannot raise your
+scrutiny, lower it, change a verdict, or affect whether you are sampled.
+
+BE INFORMED ABOUT THAT CHANNEL. It is a plain file in the working directory
+(.approval-journal/, gitignored by default), so it is local, it is not private
+from the operator, and it is not private from anyone who can read the checkout.
+The operator reads it with \`approval journal read\`, which is the point: an
+outlet nobody reads is a prop. It is not a way to reach a human urgently, not a
+place to put a secret, and not a decision surface — if you need something
+decided, that is \`request\`.
+
+WHAT THE OPERATOR ASKED FOR. Run \`approval values\` at the start of a session.
+It prints the optional values block of APPROVAL.md: what the operator values in
+the work, what they want from you as behaviour, and how they read and answer.
+It is HUMAN-AUTHORED GUIDANCE and it is not policy. Nothing in it widens what
+you may do, and nothing in it narrows it: what you may do is the policy block,
+and \`approval policy check\` is the command that answers it. Weigh guidance in
+HOW you work, never in WHETHER you are permitted. A file with no values block
+means the operator has declared no values, which is information in its own
+right; treat it as a stated absence and infer nothing to fill it.
+WHAT THE OPERATOR SAID ABOUT YOUR WORK. \`approval feedback\` is that channel in
+the other direction: the graded reactions (disliked, indifferent, liked, loved)
+and the notes a person wrote when they answered the gate or reviewed a sampled
+action, joined to the class, the task, the action key and the agent it was
+about. It is HUMAN-AUTHORED GUIDANCE and it is not policy. Reading it grants you
+nothing and forbids you nothing, and not reading it puts you under exactly the
+same rules: no verdict, sampling probability or budget anywhere in this runtime
+reads a reaction. Read it to learn what the operator values; never read it as
+permission. \`--actor\` filters on the agent the feedback is about, not on the
+human who wrote it, so \`approval feedback --actor <your id>\` is what has been
+said about your own work.
+
+WHERE THE SCHEMAS ARE. \`approval instructions --schemas\` prints this registry
+as JSON: for every verb, its purpose, its input schema (positionals, flags, and
+the trailing argv where there is one), its --json output schema, the shared
+error shape, its exit codes, and whether it is human-only. Verbs marked
+[HUMAN-ONLY] below record or establish a human's authority; do not call them,
+and do not expose them as tools. \`approval <verb> --help\` remains the long
+form for any single verb.
+
+VERBS`;
+/** The whole guide: prose plus the generated table. */
+export function instructionsGuide() {
+    return `${GUIDE_BODY}\n\n${verbTable()}\n`;
+}
+/** The registry as the object `--schemas` prints. */
+function schemasDocument() {
+    return { verbs: VERB_REGISTRY };
+}
+export function commandInstructions(argv, streams, _cwd) {
+    const json = argv.includes("--json");
+    const parsed = parseFlags(argv, {
+        "--schemas": "boolean",
+        "--json": "boolean",
+        "--help": "boolean",
+        "-h": "boolean",
+    });
+    if (!parsed.ok) {
+        if (json) {
+            streams.err(`${JSON.stringify({ error: { code: "usage", message: parsed.message } })}\n`);
+        }
+        else {
+            streams.err(`approval: ${parsed.message}\n\n${INSTRUCTIONS_HELP}\n`);
+        }
+        return EXIT_USAGE;
+    }
+    if (boolFlag(parsed.flags, "--help") || boolFlag(parsed.flags, "-h")) {
+        streams.out(`${INSTRUCTIONS_HELP}\n`);
+        return EXIT_OK;
+    }
+    const extra = parsed.positionals[0];
+    if (extra !== undefined) {
+        const message = `unexpected argument ${JSON.stringify(extra)}`;
+        if (json) {
+            streams.err(`${JSON.stringify({ error: { code: "usage", message } })}\n`);
+        }
+        else {
+            streams.err(`approval: ${message}\n\n${INSTRUCTIONS_HELP}\n`);
+        }
+        return EXIT_USAGE;
+    }
+    // --schemas is the machine surface and prints JSON with or without --json:
+    // there is no other form for it, and a --schemas that printed prose unless
+    // asked twice would be a flag people learn to pass twice.
+    if (boolFlag(parsed.flags, "--schemas")) {
+        streams.out(`${JSON.stringify(schemasDocument())}\n`);
+        return EXIT_OK;
+    }
+    const guide = instructionsGuide();
+    if (boolFlag(parsed.flags, "--json")) {
+        streams.out(`${JSON.stringify({ guide, verbs: VERB_REGISTRY })}\n`);
+        return EXIT_OK;
+    }
+    streams.out(guide);
+    return EXIT_OK;
+}
+//# sourceMappingURL=instructions.js.map

package/dist/src/cli/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/cli/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,EAAE,aAAa,EAAE,SAAS,EAAiB,MAAM,oBAAoB,CAAC;AAE7E;;;GAGG;AACH,SAAS,QAAQ,CAAC,IAAc;IAC9B,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACrD,MAAM,QAAQ,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC;IAC5C,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAED,2EAA2E;AAC3E,SAAS,IAAI,CAAC,IAAY,EAAE,KAAa;IACvC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,IAAI,KAAK,EAAE;YAAE,IAAI,GAAG,IAAI,CAAC;aACxB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,KAAK;YAAE,IAAI,GAAG,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;aACrE,CAAC;YACJ,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,IAAI,GAAG,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,IAAI,IAAI,KAAK,EAAE;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,yEAAyE;AACzE,SAAS,SAAS;IAChB,MAAM,KAAK,GAAG,aAAa,CAAC,MAAM,CAChC,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,EAC1D,CAAC,CACF,CAAC;IACF,MAAM,MAAM,GAAG,KAAK,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;IAC1C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QACvE,KAAK,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACtE,KAAK,MAAM,YAAY,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,YAAY,EAAE,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA6Ib,CAAC;AAEP,uDAAuD;AACvD,MAAM,UAAU,iBAAiB;IAC/B,OAAO,GAAG,UAAU,OAAO,SAAS,EAAE,IAAI,CAAC;AAC7C,CAAC;AAED,qDAAqD;AACrD,SAAS,eAAe;IACtB,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,IAAc,EACd,OAAgB,EAChB,IAAY;IAEZ,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,EAAE;QAC9B,WAAW,EAAE,SAAS;QACtB,QAAQ,EAAE,SAAS;QACnB,QAAQ,EAAE,SAAS;QACnB,IAAI,EAAE,SAAS;KAChB,CAAC,CAAC;IAEH,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,CAAC,GAAG,CACT,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAC7E,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,GAAG,CAAC,aAAa,MAAM,CAAC,OAAO,OAAO,iBAAiB,IAAI,CAAC,CAAC;QACvE,CAAC;QACD,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC;QACrE,OAAO,CAAC,GAAG,CAAC,GAAG,iBAAiB,IAAI,CAAC,CAAC;QACtC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACpC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,OAAO,GAAG,uBAAuB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/D,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QAC5E,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,GAAG,CAAC,aAAa,OAAO,OAAO,iBAAiB,IAAI,CAAC,CAAC;QAChE,CAAC;QACD,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,2EAA2E;IAC3E,2EAA2E;IAC3E,0DAA0D;IAC1D,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,EAAE,CAAC;QACxC,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,eAAe,EAAE,CAAC,IAAI,CAAC,CAAC;QACtD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,KAAK,GAAG,iBAAiB,EAAE,CAAC;IAClC,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC;QACrC,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,IAAI,CAAC,CAAC;QACpE,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACnB,OAAO,OAAO,CAAC;AACjB,CAAC"}