Add approval gates

Author: marcofortina

README.md

@@ -232,6 +232,15 @@ fix the host manually, then restart from the next checkpoint with `automax
 resume --from` or `automax run --from`. See
 `docs/guides/job-inspection-and-recovery.md` for the full operator workflow.
 
+Approval gates let operators bind a reviewed, secret-free plan to a JSON approval file before execution:
+
+```bash
+automax approval create --job job.yaml --inventory inventory.yaml --approved-by change-1234 --output approval.json
+automax approval verify --job job.yaml --inventory inventory.yaml --approval approval.json
+automax run --job job.yaml --inventory inventory.yaml --secrets secrets.yaml --approval approval.json
+```
+
+
 ## External files
 
 Job, inventory, variable and secret files can live anywhere. They do not need to

docs/guides/approval-gates.md

@@ -0,0 +1,70 @@
+<!--
+Copyright (C) 2026 Marco Fortina
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Approval gates
+
+Approval gates bind a reviewed Automax plan to a JSON approval file. Operators can create an approval after reviewing the same job, inventory, vars and selector inputs that will later be executed.
+
+Approval files are intentionally secret-free. Create them without `--secrets`; runs can still pass `--secrets` later because approval verification compares the secret-free review surface.
+
+## Create an approval
+
+```bash
+automax approval create \
+  --job job.yaml \
+  --inventory inventory.yaml \
+  --vars vars.yaml \
+  --approved-by change-1234 \
+  --reason "Approved maintenance window" \
+  --expires-at 2026-06-30T23:00:00Z \
+  --output approvals/change-1234.json
+```
+
+The approval file records:
+
+- approver identity;
+- approval timestamp;
+- optional expiry timestamp;
+- optional reason or ticket reference;
+- SHA-256 digest of the secret-free operator review;
+- short review summary.
+
+## Verify an approval
+
+```bash
+automax approval verify \
+  --job job.yaml \
+  --inventory inventory.yaml \
+  --vars vars.yaml \
+  --approval approvals/change-1234.json
+```
+
+Verification fails when the selected plan, inventory, vars, filters or tags no longer match the reviewed content. It also fails after `expires_at`.
+
+## Run with an approval gate
+
+```bash
+automax run \
+  --job job.yaml \
+  --inventory inventory.yaml \
+  --vars vars.yaml \
+  --secrets secrets.yaml \
+  --approval approvals/change-1234.json
+```
+
+The run verifies the approval file before execution. Dry runs do not require approval verification, so operators can still preview changes before asking for sign-off.
+
+## Operator workflow
+
+A typical change workflow is:
+
+```bash
+automax review --job job.yaml --inventory inventory.yaml --vars vars.yaml --output review.md
+automax approval create --job job.yaml --inventory inventory.yaml --vars vars.yaml --approved-by change-1234 --output approval.json
+automax approval verify --job job.yaml --inventory inventory.yaml --vars vars.yaml --approval approval.json
+automax run --job job.yaml --inventory inventory.yaml --vars vars.yaml --secrets secrets.yaml --approval approval.json
+```
+
+Keep approval files with the release or change record when the environment requires auditable operator sign-off.

docs/reference/cli.md

@@ -35,6 +35,18 @@ coverage, resume points and ready-to-copy operator commands. Review reports
 that use `--secrets` are printed to stdout only; `--output` is accepted only
 when the review does not load a secrets file.
 
+## Approval gates
+
+```bash
+automax approval create --job job.yaml --inventory inventory.yaml --approved-by change-1234 --output approval.json
+automax approval verify --job job.yaml --inventory inventory.yaml --approval approval.json
+automax run --job job.yaml --inventory inventory.yaml --approval approval.json
+```
+
+Approval files are secret-free JSON gates for reviewed plans. Create and verify
+them without `--secrets`; execution may still pass `--secrets` because the gate
+compares the secret-free review digest.
+
 ## Plan
 
 ```bash

docs/reference/future-work.md

@@ -55,20 +55,6 @@ high: os.package.upgrade, identity.user.remove, fs.dir.remove recursive=true
 This would give operators a quick review surface before running jobs on real
 targets.
 
-## Approval gates
-
-Automax may support explicit operator approval points in interactive sessions:
-
-```yaml
-- id: approve_restart
-  use: operator.approval
-  with:
-    message: Restart production web services?
-```
-
-CI and unattended runs would need a non-interactive approval policy such as
-`--approve` or a signed approval file.
-
 ## Event stream contract
 
 Run state already records events. A future contract may formalize an append-only

docs/reference/release.md

@@ -79,6 +79,7 @@ Keep the following with the release record:
 - `dist/runtime-evidence-index.json` generated with checksum verification;
 - runtime validation pack output from `scripts/runtime-validation-packs.sh`;
 - policy/risk preflight output from `scripts/policy-risk-preflight.sh`;
+- approval gate files for release operations that require sign-off;
 - `automax plugins coverage --strict` output for builtin and release-loaded
   plugins;
 - package smoke output for the built sdist and wheel.

mkdocs.yml

@@ -71,6 +71,7 @@ nav:
     - Runtime Evidence Suite: guides/runtime-evidence.md
     - Runtime Validation Packs: guides/runtime-validation-packs.md
     - Policy and Risk Preflight: guides/policy-risk-preflight.md
+    - Approval Gates: guides/approval-gates.md
     - Runtime Evidence Index: guides/runtime-evidence-index.md
     - Publishing Documentation: guides/publishing-docs.md
   - Reference:

src/automax/cli/cli.py

@@ -22,6 +22,7 @@
 from automax.core.engine import AutomaxEngine, AutomaxError
 from automax.core.evidence import build_run_evidence, render_run_evidence_markdown, write_run_evidence_bundle
 from automax.core.review import build_operator_review, build_saved_operator_review, render_operator_review_markdown
+from automax.core.approvals import ApprovalError, build_approval_payload, verify_approval_file, write_approval_file
 from automax.core.capabilities import package_for_tool
 from automax.core.inventory import Inventory, InventoryError, load_inventory_document
 from automax.core.known_hosts import KnownHostEntry, KnownHostsError, scan_known_hosts, write_known_hosts
@@ -455,6 +456,7 @@ def _apply_common_options(function):
 @click.option("--lock-timeout", type=float, default=0.0, show_default=True, help="Seconds to wait for locks.")
 @click.option("--preflight-capabilities", is_flag=True, help="Compatibility flag; capability preflight is implicit for normal runs.")
 @click.option("--sudo-password-env", help="Environment variable containing the sudo password for sudo-enabled remote substeps.")
+@click.option("--approval", "approval_path", type=click.Path(exists=True, dir_okay=False), help="Approval gate JSON file to verify before execution.")
 @click.option("--format", "output_format", type=click.Choice(["text", "json"]), default="text", show_default=True, help="Output format for the final run summary.")
 def run(
     job_path: str,
@@ -477,6 +479,7 @@ def run(
     lock_timeout: float,
     preflight_capabilities: bool,
     sudo_password_env: str | None,
+    approval_path: str | None,
     output_format: str,
 ) -> None:
     """Run a job from external YAML definitions."""
@@ -498,6 +501,19 @@ def run(
             if not payload["ok"]:
                 raise click.ClickException("check-mode preview found errors")
             return
+        if approval_path and not dry_run:
+            verify_approval_file(
+                approval_path,
+                engine,
+                job_path=job_path,
+                inventory_path=inventory_path,
+                vars_path=vars_path,
+                limit=_split_selectors(limit),
+                exclude=_split_selectors(exclude),
+                tags=_split_selectors(tags),
+                skip_tags=_split_selectors(skip_tags),
+                cli_vars=_parse_vars(cli_vars),
+            )
         rc = engine.run(
             job_path=job_path,
             inventory_path=inventory_path,
@@ -518,7 +534,7 @@ def run(
             preflight_capabilities=preflight_capabilities,
             sudo_password_env=sudo_password_env,
         )
-    except (AutomaxError, ValueError, RuntimeError) as exc:
+    except (AutomaxError, ApprovalError, ValueError, RuntimeError) as exc:
         raise click.ClickException(str(exc)) from exc
     sys.exit(rc)
 
@@ -792,6 +808,110 @@ def _render_operator_review_payload(payload: Dict[str, Any], output_format: str)
     return render_operator_review_markdown(payload)
 
 
+@cli.group()
+def approval() -> None:
+    """Create and verify approval gate files."""
+
+
+@approval.command("create")
+@_apply_common_options
+@click.option("--limit", multiple=True, help="Limit targets. Accepts server, group or group:name.")
+@click.option("--exclude", multiple=True, help="Exclude targets. Accepts server, group or group:name.")
+@click.option("--tags", multiple=True, help="Approve only substeps matching one of these tags.")
+@click.option("--skip-tags", multiple=True, help="Exclude substeps matching one of these tags.")
+@click.option("--plugin-path", multiple=True, help="External plugin file, directory or ZIP package.")
+@click.option("--approved-by", required=True, help="Operator, ticket or approval identity.")
+@click.option("--reason", default="", help="Short approval reason or ticket reference.")
+@click.option("--expires-at", help="Optional ISO datetime after which the approval is invalid.")
+@click.option("--output", "output_path", required=True, type=click.Path(dir_okay=False), help="Approval JSON file to write.")
+def approval_create(
+    job_path: str,
+    inventory_path: str,
+    vars_path: str | None,
+    secrets_path: str | None,
+    cli_vars: tuple[str, ...],
+    limit: tuple[str, ...],
+    exclude: tuple[str, ...],
+    tags: tuple[str, ...],
+    skip_tags: tuple[str, ...],
+    plugin_path: tuple[str, ...],
+    approved_by: str,
+    reason: str,
+    expires_at: str | None,
+    output_path: str,
+) -> None:
+    """Create an approval gate file from the current secret-free review."""
+    if secrets_path:
+        raise click.ClickException("approval files are secret-free; omit --secrets when creating approvals")
+    try:
+        payload = build_approval_payload(
+            _engine(plugin_path),
+            approved_by=approved_by,
+            reason=reason,
+            expires_at=expires_at,
+            job_path=job_path,
+            inventory_path=inventory_path,
+            vars_path=vars_path,
+            limit=_split_selectors(limit),
+            exclude=_split_selectors(exclude),
+            tags=_split_selectors(tags),
+            skip_tags=_split_selectors(skip_tags),
+            cli_vars=_parse_vars(cli_vars),
+        )
+        output = write_approval_file(payload, output_path)
+    except (AutomaxError, ApprovalError, ValueError, RuntimeError) as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(f"Wrote approval gate {output}")
+
+
+@approval.command("verify")
+@_apply_common_options
+@click.option("--limit", multiple=True, help="Limit targets. Accepts server, group or group:name.")
+@click.option("--exclude", multiple=True, help="Exclude targets. Accepts server, group or group:name.")
+@click.option("--tags", multiple=True, help="Verify only substeps matching one of these tags.")
+@click.option("--skip-tags", multiple=True, help="Exclude substeps matching one of these tags.")
+@click.option("--plugin-path", multiple=True, help="External plugin file, directory or ZIP package.")
+@click.option("--approval", "approval_path", required=True, type=click.Path(exists=True, dir_okay=False), help="Approval JSON file to verify.")
+@click.option("--format", "output_format", type=click.Choice(["text", "json"]), default="text", show_default=True, help="Output format.")
+def approval_verify(
+    job_path: str,
+    inventory_path: str,
+    vars_path: str | None,
+    secrets_path: str | None,
+    cli_vars: tuple[str, ...],
+    limit: tuple[str, ...],
+    exclude: tuple[str, ...],
+    tags: tuple[str, ...],
+    skip_tags: tuple[str, ...],
+    plugin_path: tuple[str, ...],
+    approval_path: str,
+    output_format: str,
+) -> None:
+    """Verify that an approval gate file matches the current review."""
+    if secrets_path:
+        raise click.ClickException("approval verification is secret-free; omit --secrets")
+    try:
+        result = verify_approval_file(
+            approval_path,
+            _engine(plugin_path),
+            job_path=job_path,
+            inventory_path=inventory_path,
+            vars_path=vars_path,
+            limit=_split_selectors(limit),
+            exclude=_split_selectors(exclude),
+            tags=_split_selectors(tags),
+            skip_tags=_split_selectors(skip_tags),
+            cli_vars=_parse_vars(cli_vars),
+        )
+    except (AutomaxError, ApprovalError, ValueError, RuntimeError) as exc:
+        raise click.ClickException(str(exc)) from exc
+    if output_format == "json":
+        click.echo(json.dumps(result, indent=2, sort_keys=True))
+        return
+    click.echo(f"Approval gate OK: {result['review_sha256']}")
+    click.echo(f"Approved by: {result['approved_by']}")
+
+
 @cli.group()
 def ssh() -> None:
     """SSH helper commands."""