@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/operator-bootstrap/SKILL.md

@@ -0,0 +1,412 @@
+---
+name: operator-bootstrap
+description: "This skill should be used when a merge leaves two or more operator steps blocked on one credential: generate a runnable staged bootstrap.sh an agent runs, not a prose checklist."
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+<!-- Inspired by mattpocock/skills/skills/engineering/wizard/ (MIT, Copyright (c) 2026 Matt Pocock). -->
+
+# Operator Bootstrap — generate the script, not the checklist
+
+Two hard rules already mandate the artifact this skill produces.
+`hr-multi-step-post-merge-bootstrap-script` says a post-merge deferral with two or more steps ships
+as a runnable script; `hr-ship-message-no-operator-checklist` says the ship message does not hand the
+founder a checklist.
+
+This skill authors that script. It does **not** author the machinery: every script it produces
+`source`s `plugins/soleur/scripts/lib/operator-script.sh`, which is where the stage table, the plan
+and receipt gate, the secret handling, the `.env` upsert, the prompt classes and the run ledger live.
+
+**The script is run by an agent, one stage at a time, with no terminal** (ADR-264). The person never
+opens a terminal and is never handed a command list. Their acknowledgement of each production write
+is the harness approval prompt on the exact command the agent is about to run. §Running a generated
+script is the protocol.
+
+## The library header is the contract
+
+**The library is one file. The skill authors only stages. Never hand-edit the library.**
+
+Everything a generated script may rely on is documented **once**, in the header of
+`plugins/soleur/scripts/lib/operator-script.sh`, and is not restated here:
+
+- **Sourcing preconditions** (`set -euo pipefail` first; the xtrace/TLS prologue duplicated
+  *above* the `source` line; required binaries) — header §"SOURCING PRECONDITIONS".
+- **The library invariant** (it never expands a secret-shaped name; secrets arrive as positional
+  parameters; credential *entry* stays in the generated script) — header §"LIBRARY INVARIANT".
+- **The staged contract and the approval receipt** (stage table, plan, digest, one-time receipt,
+  the order inside `soleur_op_stage_gate`) — header §"Staged contract" and §"Approval receipts".
+- **The prompt classes** and their non-interactive behaviour — header §"Prompts".
+- **Exit codes and stdout markers**, including exit 75, `SOLEUR_BOOTSTRAP_LIB_MISSING` and
+  `SOLEUR_BOOTSTRAP_LIB_INCOMPATIBLE` — header §"EXIT CODES" and §"STDOUT MARKERS".
+- **The API contract** (`SOLEUR_OP_LIB_API`) — header §"API CONTRACT".
+
+When the header and this file disagree, the header is right and this file has drifted.
+
+## The staged contract in one screen
+
+A generated script carries the header line `# SOLEUR-GENERATED-OPERATOR-SCRIPT v2` on line 2. The
+approval hook recognises a script by that line (a v1 script never gets a receipt), never by file name.
+
+```text
+bash SCRIPT --list                                      the stages (static, needs no login)
+bash SCRIPT --stage NAME                                a READ stage runs; a WRITE stage prints its plan
+bash SCRIPT --stage NAME --apply --plan-digest D [--rotate-token]   the approved write
+```
+
+- There is **no run-all mode and no `--yes`**. A missing `--stage` exits 64.
+- A **read** stage only reads and reports. A **write** stage first prints a **plan** and changes
+  nothing: `SOLEUR_BOOTSTRAP_PLAN stage= operations= digest=`, one `SOLEUR_BOOTSTRAP_PLAN_OP` per
+  change, the stage's `SOLEUR_BOOTSTRAP_IMPACT` and `SOLEUR_BOOTSTRAP_ROLLBACK` sentences, and an
+  `SOLEUR_BOOTSTRAP_APPLY_COMMAND` line followed by the exact command to run.
+- `--apply --plan-digest D` performs the write. The script **recomputes** the plan and compares the
+  digest, so what runs is what was shown; a mismatch exits 75 `SOLEUR_BOOTSTRAP_PLAN_DRIFT` with
+  nothing written.
+- The **receipt**: a plugin PreToolUse hook (`plugins/soleur/hooks/operator-stage-approval.sh`) mints
+  a one-time record when the harness shows the person the exact command, and rewrites the command to
+  carry `SOLEUR_APPROVAL_NONCE`. The script consumes the record before its first write. An
+  environment variable or a flag set by the agent is never an approval. No valid receipt: exit 75,
+  nothing written.
+- **Keep the `.env` beside the script.** "Satisfied" and `verify` read the recorded slugs there (it is
+  gitignored). A fresh checkout without it turns a satisfied stage into a rotation plan and makes
+  `verify` report a healthy vendor state as failed: run `verify` from the checkout that ran the stages.
+- **Stages are idempotent.** A re-run of a satisfied stage changes nothing and needs no approval: its
+  plan has `operations=0`, so skip `--apply`.
+- Markers (stdout): `SOLEUR_BOOTSTRAP_STAGE_DECL stage= class=` (read or write); `_PLAN`; `_PLAN_OP`;
+  `_IMPACT`; `_ROLLBACK`; `_APPLY_COMMAND stage= approval_digest=`; `_APPROVAL_REQUIRED stage=
+  approval_digest= surface=`; `_APPROVAL_INVALID stage= reason=` (one of `no-record`, `expired`,
+  `digest-mismatch`, `consumed`, `algo`, `perms`, `format`); `_PLAN_DRIFT stage=`;
+  `_PRECONDITION_FAILED stage= need=`; `_STAGE_REQUIRED`, `_UNKNOWN_STAGE stage=` and
+  `_PLAN_DIGEST_REQUIRED stage=` (exit 64, your own invocation was wrong); `_MISSING_BINARY bin=`; `_STAGE_OK stage= changed=` (0 or 1, with `approval=` set to
+  `harness-receipt` or `tty-ack` after a write); `_STAGE_FAILED stage= rc=`; `_LIB_INCOMPATIBLE need=stage-1`.
+- Exit codes: 75 approval required, invalid or plan drift (nothing written); 64 missing input; 78
+  refused under xtrace; 1 the stage failed.
+
+**What the approval does and does not guard** (say it this way, in plain words): the approval guards
+against an agent acting on a mistaken instruction, not against a compromised one. Never write that a
+human approves every production write without that qualifier.
+
+## Process
+
+### 1. Scope the procedure
+
+Read the deferral that triggered this. Name, in order, every step the founder must take before the
+merged change is live. Stop when the list is complete, not when it is convenient.
+
+Then apply the ladder **before** deciding anything is a step at all:
+**environment variable → Doppler → MCP/CLI/REST → prompt.** `hr-exhaust-all-automated-options-before`
+ends with *"prompt for creds not in Doppler"* — the prompt is the last rung of the ladder, not an
+exception to it. A value that is missing and is not a credential is a hard failure with a named
+remedy, never a prompt.
+
+If fewer than two steps survive the ladder, do not generate a script. Say so.
+
+### 2. Map each stage's journey
+
+One stage per step. For each, write down five things before writing any code:
+
+- **its class** — `read` (it only reads) or `write` (it changes production);
+- **what the person is told** — for a write stage, one plain sentence of impact and one of rollback,
+  written for a founder, which become the stage's `# SOLEUR-STAGE` line;
+- **what it needs** — the value, and where on the ladder it comes from;
+- **how it knows it is already done** — the precondition. Every stage opens with an
+  "already satisfied?" check. This is what makes re-run idempotent over a non-idempotent create,
+  and it is why there is **no resume index**: re-running a stage *is* resume, because a satisfied
+  stage declares no operation and skips itself;
+- **how it proves it worked** — the verification. A stage that attests without verifying attests
+  nothing. The last stage of every script is a `verify` **read** stage that prints names only and
+  derives its result from vendor state; its stdout markers are the closure evidence.
+
+### 3. Author the stages
+
+Copy [`template.sh`](./template.sh) to the location in §Where, keep everything above the `STAGES`
+banner, and replace the example stages. Rules:
+
+- **Repo-relative paths.** Never compute the repo root as a fixed `../` count from `SCRIPT_DIR`: the
+  script moves one directory deeper when `archive-kb` archives its spec directory (see §Where).
+- **Stage lines.** Declare each stage once, in the table near the top of the script, as a comment
+  line of the form `# SOLEUR-STAGE name|class|impact|rollback` (class is `read` or `write`). One plain
+  sentence each for impact and rollback, no `|` inside them. `--list`, the dispatcher and the approval
+  hook all read these same lines, and the person sees the impact and rollback in the approval prompt,
+  so they are the only place those words are written.
+- **Functions.** A read stage is `read_<name>()`. A write stage is a pair: `plan_<name>()` (read-only)
+  and `apply_<name>()` (the writes; it runs only after the gate returned). `-` in a stage name
+  becomes `_` in the function name.
+- **A plan names operations and targets, never a value.** `soleur_op_plan_op <op-name> <target-name>`
+  once per change the stage would make; the targets are container, slug and secret NAMES. The digest
+  covers exactly this list, and the agent relays it, so a value in it would leak.
+- **A satisfied stage declares no operation.** Then the plan prints `operations=0`, no approval is
+  asked and `--apply` changes nothing.
+- **Later stages re-prove earlier stages' work.** Stages are separately addressable, so a stage whose
+  precondition is another stage's output calls `soleur_op_precondition_failed <stage> <need-stage>
+  "<sentence>"` (marker `SOLEUR_BOOTSTRAP_PRECONDITION_FAILED stage= need=`) instead of trusting that
+  the earlier one ran.
+- **A stage never calls `soleur_op_ack_or_die`.** That helper needs a typed `yes` at a terminal and
+  makes the stage unrunnable by an agent. The gate is `soleur_op_stage_gate`, called by the
+  template's dispatcher, not by the stage; a stage that gates itself is a defect the guard fails.
+- **Bake the library path.** The template carries a placeholder line
+  `SOLEUR_OP_LIB_BAKED="__SOLEUR_OP_LIB_BAKED__"`. The generator MUST replace it with the absolute
+  path of the library resolved at generation time, because the generated script lives in the
+  founder's repository where `CLAUDE_PLUGIN_ROOT` may be unset and no relative path to the plugin
+  exists:
+
+  ```bash
+  LIB="$(realpath "${CLAUDE_PLUGIN_ROOT}/scripts/lib/operator-script.sh")"
+  sed -i "s|^SOLEUR_OP_LIB_BAKED=.*|SOLEUR_OP_LIB_BAKED=\"${LIB}\"|" knowledge-base/project/specs/feat-<name>/bootstrap.sh
+  ```
+
+  Anchor on the assignment line, as above — a global replace of the placeholder would be harmless
+  today (the resolution loop deliberately does not spell it) but is not the documented form.
+- **Never echo a secret variable** for progress. That is the documented
+  `hr-never-paste-secrets-via-bang-prefix` leak path, whose Why cites a live prd-JWT leak.
+- **Credential entry stays a class-1 ladder rung** in the generated script (`read -rs` behind the
+  library's TTY gate — copy the shape from `provision-hetzner.sh`; the ladder tries the environment
+  and Doppler first). With no terminal the script exits 64 naming what to set up, and the agent never
+  asks for the secret in chat. `soleur_op_value` is for non-secret ladder values (a region, an
+  account id); it echoes its input.
+- **Write secrets through `soleur_op_gh_secret_set`** (stdin) and non-secrets through
+  `soleur_op_gh_variable_set` (argv, and it refuses secret-shaped names). Do not merge them.
+- **Write `.env` values through `soleur_op_env_upsert`.** It is exact-key: the trailing `=` is what
+  stops an upsert of `X_API_KEY` from removing `X_API_KEY_SECRET`.
+- **Keep the dispatcher.** The template's `dispatch_stage` is the one place that applies the staged
+  contract and records the stage the template's one `EXIT` trap reports on: a stop inside a stage
+  prints `SOLEUR_BOOTSTRAP_STAGE_FAILED stage= rc=` and one plain sentence, and settles the stage in
+  the ledger as `failed` with the exit code (exit 75 settles as `refused` and adds nothing).
+- **A destructive stage's precondition asks the vendor, never only a local marker written after the
+  create.** Between "create succeeded" and "marker written" an interruption leaves a resource the
+  next run cannot see, and it creates a second one. Keep the template's two controls: the vendor-side
+  read and the `*_ATTEMPTED` marker written *before* the create, which stops a re-run and sends the
+  person to the vendor console (`--reset <KEY>_ATTEMPTED` clears it once they have looked).
+- **A marker the script writes is not proof of vendor state, and "already satisfied" must be read from the vendor.**
+  Write the marker that skips a stage only AFTER the write and its verification succeed; treat an unreadable list as
+  INCONCLUSIVE (stop), never as "absent"; confirm a revoke by re-listing, not by its exit code; and when exactly one
+  vendor object exists that the script cannot show is the stored one, replace it new-before-old instead of dead-ending.
+  Environment secrets are write-only, so a name listing proves nothing about the value (#9321).
+- **Name skip variables by convention, and let `usage()` derive the list.** A class-1 value is
+  `SOLEUR_BOOTSTRAP_<WHAT>` (`SOLEUR_BOOTSTRAP_ACCOUNT_ID`); a class-3 barrier is
+  `SOLEUR_BOOTSTRAP_SKIP_<WHAT>_BARRIER`. The template's `--help` greps its own `soleur_op_value` /
+  `soleur_op_barrier` call sites for the list, so a prompt added on a line of its own is
+  documented without editing `usage()`. Keep each call on one line for that reason.
+- **Open a URL with `soleur_op_open_url`.** It prints the URL first and never branches on the
+  opener's exit code, so a headless box degrades to "here is the URL" instead of to a failed stage.
+  `SOLEUR_OP_NO_OPEN=1` prints the URL and launches nothing (CI, test harnesses).
+
+### 4. Verify and hand off
+
+Drive the generated script the way an agent will, with stdin closed:
+
+1. `--list` prints every stage with its class.
+2. Every **read** stage runs with the class-1 skip variables set and exits 0, or with none set and
+   exits 64 printing `SOLEUR_BOOTSTRAP_INPUT_REQUIRED` naming the **first** skip variable — before
+   any read, never after.
+3. Every **write** stage prints its plan with no mutating call, and `--apply` with no receipt exits 75
+   and writes nothing.
+
+`plugins/soleur/test/operator-agent-runnable.test.sh` does this for every v2 script in the tree
+(§Guards), and also drives every vendor call through a stub that counts anything not on its
+read-verb allowlist as a write: a `read_*` or `plan_*` function that writes is a defect, because the
+hook asks about `--apply` only, and the approval prompt is the one place a person sees a write. Then read the ledger beside the script (`bootstrap-runs.jsonl`): every stage that ran has a
+`begin` and a `settle` line. Hand off by **running the stages yourself** per §Running a generated
+script, not by giving the person a script path to run.
+
+## Running a generated script
+
+This is the AGENT PROTOCOL. A person with no terminal can complete a bootstrap with it, because the
+agent does every step and the person only answers the approval prompt.
+
+1. **List.** Run `bash <script> --list` and read the `SOLEUR_BOOTSTRAP_STAGE_DECL` lines. This needs
+   no library and no login.
+2. **Run the read stages** (class `read`) in order, one `bash <script> --stage <name>` each.
+3. **For each write stage**, run `bash <script> --stage <name>` first. This prints the plan and
+   changes nothing. If it prints `operations=0`, the stage is already satisfied: **skip the apply**.
+4. **Relay the impact and rollback.** Tell the person, in plain words and **verbatim from the
+   script's own `SOLEUR_BOOTSTRAP_IMPACT` and `SOLEUR_BOOTSTRAP_ROLLBACK` lines**, what the write will
+   change and how it is undone, **before** issuing the apply. Compose no impact or rollback sentence
+   of your own: the words the person reads are the words that were approved.
+5. **Announce it (headless or unknown entrypoint only).** State `SOLEUR_BOOTSTRAP_APPROVAL_PENDING stage=<s>`
+   in your reply. In a headless session the approval hook defers silently; this line is what makes the
+   wait visible. In an interactive session the prompt itself is the announcement: skip this step.
+6. **Issue exactly** `bash <script> --stage <name> --apply --plan-digest <d>` (plus `--rotate-token`
+   only if the plan was produced with it) as **ONE simple command**: no pipe, `;`, `&&`, redirect,
+   substitution or glob. The one accepted prefix is a leading `cd <dir> &&`. Use the line the plan
+   printed after `SOLEUR_BOOTSTRAP_APPLY_COMMAND`.
+7. **Let the harness prompt carry the approval.** The person sees the exact command (the hook has
+   rewritten it to carry the receipt) and decides. **Never** set an environment variable, a flag or a
+   file to approve; **never** pipe `yes`; **never** ask for a secret in chat.
+8. After the last write stage, run the `verify` stage and keep its stdout markers: they are the
+   closure evidence for the follow-through issue.
+
+**Surfaces.** Claude Code interactive (the terminal, the VS Code extension, the Desktop app): the
+permission prompt on the exact command. Headless, `-p` or one-shot: the hook defers and mints nothing;
+state `SOLEUR_BOOTSTRAP_APPROVAL_PENDING stage=<s>` in your reply (headless only), and a person runs `claude --resume`
+and approves at the prompt. There is no variable, setting or file that approves it; never suggest one.
+`bypassPermissions`, `dontAsk` and auto modes: the hook denies. The script itself accepts a typed `yes`
+only from a person at their own terminal with no agent harness around it, so never allocate a
+pseudo-terminal to answer it. Harnesses without the hook (Codex,
+Devin cloud, Grok) and the web app: the script exits 75 and writes nothing; say "this surface cannot
+make production changes yet" and **never** tell the person to open a terminal (the web approval
+adapter is #9388; per-harness adapters are #9389).
+
+**The scheduled follow-through sweeper never runs `--apply`.** A receipt expires after five minutes
+and a person must approve the prompt, which an unattended runner cannot satisfy. The follow-through issue's `auto_command:` for a staged
+script is attended-only: it names `--list` plus this protocol, and the issue closes on the `verify`
+stage's stdout markers pasted into a comment.
+
+### Outcome table
+
+| Outcome | Agent does | Founder is told |
+|---|---|---|
+| founder denied the prompt | stop; do not re-prompt in a loop; ask once whether to retry | "You declined, so nothing changed." |
+| 75 `APPROVAL_INVALID` reason `expired`, `consumed` or `digest-mismatch` | re-plan, re-issue once | "That approval timed out (or was already used), so I am asking again." |
+| 75 `APPROVAL_INVALID` reason `perms`, `algo` or `format` (a failed rename reads as `perms`) | stop and report | "A safety check failed and nothing changed; this needs a person to look at it." |
+| 75 `APPROVAL_INVALID` reason `expired` a second time | stop re-issuing; the receipt clock starts when the prompt is shown, not when it is approved | "Tell me when you are at the screen and I will ask again." |
+| 1 `PRECONDITION_FAILED need=<stage>` | run the named `need` stage (a read stage needs no approval), then re-plan; never re-run the same stage | "A step before this one is not done yet; I am doing it first." |
+| 64 `STAGE_REQUIRED`, `UNKNOWN_STAGE` or `PLAN_DIGEST_REQUIRED` | your own invocation was wrong: run `--list`, re-plan, use the printed digest | none |
+| 64 `MISSING_BINARY bin=<tool>` | stop; name the tool | "I need <tool> installed on this machine first." |
+| 75 `PLAN_DRIFT` | re-plan, relay the new impact, re-issue | "Something changed since I showed you the plan; here is what is different." |
+| 75 `APPROVAL_REQUIRED` on a no-hook or web surface | stop | "I can't make this change from here yet. Nothing changed and the plan is saved; it needs Claude Code with Soleur on your computer (tracked in #9388)." |
+| headless pending | print `SOLEUR_BOOTSTRAP_APPROVAL_PENDING stage=<s>` | "A change is waiting for your approval." |
+| bypass-mode deny | stop | "Approvals are switched off in this session; switch to the normal mode and I will ask again." |
+| 64 missing input | stop; name the input; never ask for a secret in chat | "I need (the login or input) set up first." |
+| 78 refused under xtrace | unset xtrace, re-run once | none |
+| 1 `STAGE_FAILED` | run the `verify` or a read stage; never re-apply blindly | a plain account of what changed and what did not |
+
+## The interactive surface
+
+Generated scripts are **non-interactive by default** (ADR-228) and, from v2, **agent-run** (ADR-264).
+The one interactive rung left in a script is credential **entry**
+(`hr-never-label-any-step-as-manual-without`): a class-1 ladder rung that tries the environment and
+Doppler first and prompts only as the last step, behind the library's TTY gate. With no terminal it
+exits 64 naming the missing input.
+
+The destructive-write acknowledgement is **not** a prompt in the script any more. It is the harness
+approval on the exact command and the receipt it mints (§The staged contract). The rulings an author
+must not undo:
+
+- **No environment variable, flag or file approves a write.** A skip variable for the write ack would
+  be exactly the "prior approval extending to a new command" that
+  `hr-menu-option-ack-not-prod-write-auth` forbids. The receipt is bound to one command and one use.
+- **A class-3 barrier must be followed by an independent verification.** A barrier only attests that
+  a human *says* they did something outside the script. Skipping it is safe **only** because a
+  `gh api /installation`, a `doppler projects get` or a `terraform output` runs immediately after
+  and fails if the attestation was false. A skippable barrier with no downstream verification is a
+  no-op wearing a prompt.
+
+## Recovering from a bad run
+
+- **A wrong credential was permanent.** The value is persisted before it can be validated, and the
+  environment-first ladder means a re-run never re-prompts — it fails identically forever. Every
+  generated script exposes `--reset <KEY>`, which calls `soleur_op_env_reset`.
+- **Re-run was not idempotent.** The precondition check is what makes it so, and it is also what makes
+  re-running a stage the resume mechanism. This is a rule for the author, not a feature of the library.
+- **A stage failed (`STAGE_FAILED`, exit 1).** Run the `verify` or a read stage to see what changed.
+  Never re-apply blindly: the failure sentence says whether production may already have changed.
+
+An interruption leaves a state byte-identical to a crash, and the ledger's completed-set-versus-declared
+comparison detects both. What every non-zero exit *inside a stage* gets is the template's single `EXIT`
+trap: `SOLEUR_BOOTSTRAP_STAGE_FAILED`, one sentence naming the stage, whether anything was changed and the
+command that shows where it stands, plus a `failed` settle line in the ledger. Every library refusal
+prints its marker **and** one plain sentence, and writes a `run_halt` ledger line before exiting.
+
+## Where the artifact lives
+
+**One location:** `knowledge-base/project/specs/feat-<name>/bootstrap.sh`, with the run ledger
+beside it as `knowledge-base/project/specs/feat-<name>/bootstrap-runs.jsonl`. The live ledger
+keeps that fixed name and is gitignored (re-runs would conflict on it); to keep a finished run's
+record, copy it to `bootstrap-runs-<issue>.jsonl` beside the archived script, a name the ignore
+rule does not match, and point to it from the spec's `tasks.md`.
+
+That is the rule's own `<feature>/` prefix (`hr-multi-step-post-merge-bootstrap-script` names
+`<feature>/bootstrap.sh`, and the feature's tracked artifact home is its spec directory); it is
+tracked, so the script survives `ship` reaping the worktree and is visible to the credential linter
+and to review; and a gitignored path (`provisioning/`, `.soleur/` — both are) would leave the
+follow-through issue's `auto_command:` pointing at a file that stops existing at ship Phase 7.
+
+The script does not stay at that depth: `archive-kb` later moves the spec directory one level deeper
+(`specs/archive/<ts>-feat-<name>/`). A repo root computed as a fixed `../` count from `SCRIPT_DIR`
+then points at the wrong directory without any error at generation time. Resolve it with
+`git -C "$SCRIPT_DIR" rev-parse --show-toplevel`, and refuse a root that does not track the file a
+stage is about to run under credentials. **Why:** #10058 — `verify` changed into `knowledge-base/`
+after archival and could not find its probe script.
+
+A tracked home has one consequence the founder must not discover from a pushed token: the `.env`
+beside the script — and the `.env.tmp.XXXXXX` sibling the upsert creates — must be covered by the
+repository's `.gitignore` (a bare `.env` pattern does not cover the sibling; `.env*` covers both).
+The template checks this **before its first write**, `--reset` included: inside a git work tree, an
+uncovered path stops the run with `SOLEUR_BOOTSTRAP_ENV_NOT_IGNORED path=<path>`, exit 64, and one
+sentence naming the fix. This repository's `.gitignore` carries both patterns.
+
+The ledger is written on the founder's machine and is committable in the founder's repository,
+which is where observability layer 7's "committed to the customer's own repository" condition is
+satisfied. Nothing is transmitted to Soleur infrastructure: the surface is the founder's own
+machine, and routing it anywhere else is a data-controller event, not an observability improvement.
+
+## Lifecycle
+
+- **Create:** this skill, from ship's operator-step gate (option 4).
+- **Read / run:** the agent runs it per §Running a generated script; `--list` shows the stages,
+  `--help` lists the skip variables, and the ledger beside it is the run history.
+- **Regenerate** (the procedure changed, the library's API number moved): re-run this skill. It
+  rewrites the script from the template; the `.env` and the ledger are left in place, and every
+  stage's precondition makes the next run skip what is already done.
+- **Delete:** when the follow-through issue that points at the script closes, remove the script,
+  the ledger (`bootstrap-runs.jsonl`) and the `.env` together — the `.env` holds live credentials
+  and has no reason to outlive the procedure that needed them. A kept `bootstrap-runs-<issue>.jsonl`
+  copy is a record, not live state, and stays. The
+  `SOLEUR-GENERATED-OPERATOR-SCRIPT v2` header line is what the approval hook and the guard use to
+  find every generated script by one grep.
+
+## Legacy scripts
+
+Three finished generated scripts still carry the v1 header and the typed-yes TTY acknowledgement: the
+8450 CI-concurrency script, the LinkedIn token renewal script and the runtime App key eviction script.
+So do `flag-create`, `flag-delete`, `user-set-role`, `flag-set-role`, `provision-hetzner` and
+`audit-sentry`. The approval hook never mints for a v1 script. Migrating them to the staged contract is
+tracked in #9387; until then their writes keep the typed-yes handoff, and credential entry in
+`provision-hetzner` stays a class-1 interactive carve-out.
+
+## Guards
+
+- [`plugins/soleur/test/operator-agent-runnable.test.sh`](../../test/operator-agent-runnable.test.sh)
+  (Guard 1) discovers every v2 generated script in the tree and drives every `--list` entry with stdin
+  closed and no terminal against PATH-stubbed vendor tools: every stage reaches a defined outcome, no
+  stage reaches a mutating call without a receipt (the apply is driven with every approve/force/skip-shaped
+  variable the script names set to `1`), an undeclared `--stage` name is refused, and no stage demands a
+  terminal or calls `soleur_op_ack_or_die`. A v1 script must be one of the three legacy paths, and that
+  list may only shrink. It is wired through the `plugins/soleur/test/*.test.sh` glob in
+  [test-all.sh](../../../../scripts/test-all.sh), so it runs in the repository's test suite and CI with no per-script entry.
+- [`plugins/soleur/test/operator-script.test.sh`](../../test/operator-script.test.sh) pins the library
+  controls below and the receipt algorithm's known-answer vectors.
+- Decision record: ADR-264 (generated operator scripts are agent-run in stages; the human
+  acknowledgement is a harness-approved receipt).
+
+## What protects the founder's credentials
+
+Seven vectors, six controls — five inside the library or the hook so no generated script re-decides
+them, one in the template because only the generated script knows where it lives:
+
+| Vector | Control |
+|---|---|
+| `.env` written at a default umask into a cloud-synced directory | `umask 077` in the library, `chmod 600` asserted **after** the `mv` that completes each upsert — `mv` replaces the inode and its mode |
+| a secret on argv, readable in `/proc/<pid>/cmdline` | the secret helper is stdin-only; the `--body` form is banned |
+| a secret echoed for progress, or a run under `set -x` | the xtrace refusal (exit 78) plus the repo-root `lint-shell-trace-credential-refusal.py` linter in CI |
+| a third-party CLI dumping unrelated secrets as a side effect of a write | the write's own output is redirected and the result confirmed by a separate read |
+| a half-populated `.env` and partly-set secrets after an interrupted run | **not** a library control — it is the precondition/`--reset` work above, and it is the author's job |
+| the `.env` (or its `.tmp.XXXXXX` sibling) sitting in a tracked directory that `.gitignore` does not cover | the template's `git check-ignore` probe on both paths before the first write — `SOLEUR_BOOTSTRAP_ENV_NOT_IGNORED`, exit 64 (a template control, not a library one: the library does not know where it is sourced from) |
+| a production write the person never saw | the one-time receipt bound to the exact command, the plan recomputed and its digest compared, the receipt consumed before the first write (the hook and the library). It guards against an agent acting on a mistaken instruction, not against a compromised one |
+
+The guards behind the library controls and the template's ignore probe live in
+`operator-script.test.sh`, whose mutation matrix drives each one red (the ignore probe is observed on
+a real git fixture, with the probe deleted from the generated script as the mutation). The same suite
+proves the bake in §3 is load-bearing: the unbaked template, placed at the documented location with no
+`CLAUDE_PLUGIN_ROOT`, exits 64.
+
+## Related
+
+- [`template.sh`](./template.sh) — the starting point. Copy it; do not copy the library.
+- `plugins/soleur/scripts/lib/operator-script.sh` — the library; its header is the contract.
+- `plugins/soleur/hooks/operator-stage-approval.sh` — the approval hook that mints the receipt.
+- `soleur:provision-hetzner` — the proving consumer; read its script for a real refactor onto the library.
+- `soleur:ship` — invokes this skill when a post-merge deferral carries two or more operator steps.