mutation-gate

RHDH write gate

An external write is anything the user cannot undo by closing the session: a pushed commit, an opened pull request, a Jira transition, a posted message, a file changed in someone else's repository.

Reading is not a write. A request to fetch, triage, analyse, or report is intent to read, and it approves nothing.

The gate

1. State the operations. List every operation you are about to perform, in the order you will perform them. For each one give:

Field	What it carries
Target	The exact thing being changed: owner/repo#412, RHIDP-1234, a branch name, a channel
Command	The exact command or request, as it will run. Not a paraphrase
Preview	The body, label, field value, or diff that will land
Precondition	What must already be true. Check it immediately before executing, and stop the batch if it is not
On failure	What happens to the operations after this one if it fails
Recovery	How to undo or contain this operation once it has happened

Render this as a table in the conversation. Approval happens where the user already is, so the plan goes to them rather than to a file.

Recovery is not optional, and it is not the same as failure handling. Failure handling says what happens to the operations that have not run yet. Recovery says what to do about the one that already did. Write it before asking for approval: an operation you cannot say how to undo is one the user is approving blind. Where there is genuinely no undo — a posted message, a triggered pipeline, a published package — say that, in those words. "Cannot be undone; the message stays" is a complete and useful recovery entry. Silence is not.

When a plan is too large to read in the transcript — a multi-repository bump, a catalog change touching dozens of files — write it to a file in the operating system temporary directory instead, following /handoff's convention, and print the absolute path. Do not write it into the user's checkout, where it can reach a commit.

2. Get approval for that stated set. The user approves what they were shown. Earlier intent to publish never authorizes an operation whose exact target and payload have not been shown. If the plan changes after approval — a different target, an extra operation, an edited body — it is a new plan and needs new approval.

3. Execute, then report every operation. Report each one as completed, failed, or skipped, in the order it was planned. An operation that never ran because an earlier one failed is reported as skipped, not omitted. A failed write is reported, never quietly retried into a different shape.

Credentials never reach a preview

A preview shows a command as it will run, so it can carry a token that was pasted, interpolated from the environment, or returned by a tool. Scan before showing:

uv run scripts/scan_credentials.py <plan.json> --json
uv run scripts/scan_credentials.py --text "<a single command or body>"

It exits non-zero and names the offending path when it finds a credential-shaped field or value — an authorization header, a PEM private key, a ghp_, glpat-, xox, sk-, or AKIA token, or a field named like a secret at any depth. It reports the field, never the secret.

A credential in a plan is a bug in how the command was built, not something to redact and continue past. Fix the construction so the secret is supplied by the authenticated tool at run time.

Who executes

The skill that owns the target executes it. A caller that needs a Jira write invokes /rhdh-jira-update; one that needs a forge write builds the command and runs it itself. /rhdh-forge constructs forge payloads and never executes them — that separation is what makes this gate enforceable, because the module that knows how to build the command cannot run it.

Completion

Complete when every operation the user approved has an outcome, the outcomes are in the planned order, and each one names its target. An operation missing from the report, or reported without the target it changed, means the gate did not close.