ciphergate-cli 0.11.0__tar.gz → 0.12.0__tar.gz

{ciphergate_cli-0.11.0 → ciphergate_cli-0.12.0}/CHANGELOG.md

@@ -6,6 +6,28 @@ versioning: [PEP 440](https://peps.python.org/pep-0440/) with SemVer meaning (pr
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-11-02
+
+Blocked runs now say what to do next, and directory runs no longer hide files they never
+scanned. A strict directory `rescan` that skips files with unrecognised extensions now exits 7
+instead of 0.
+
+### Added
+
+- Blocked, review and failed runs print `next:` lines in the terminal summary: what to pass,
+  what to change in the policy, or what to remove from the input. The hints come from reason
+  codes and never include input values. The JSON report is unchanged.
+- `docs/policy-schema.md` explains `hard` and `guardrail` rules.
+- `.out` and `.err` files are read as plain text, in directories and as single files.
+
+### Fixed
+
+- Directory runs warn when files were skipped because their extension is not recognised, so a
+  `COMPLETED` run no longer hides files that were never scanned. A strict directory `rescan` now
+  fails (exit 7) when it skipped such files, and `sanitize` says they are not in the output.
+- Directory runs warn when `--format` is applied to files whose extension means another format.
+- Directory summaries show the same `next:` hints as single-file runs.
+
 ## [0.11.0] - 2026-10-31
 
 Makes a clean rescan harder to mistake for proof of safety. Scripts that read `PASSED` from the
@@ -328,7 +350,8 @@ Pre-release (alpha). Licensed under Apache-2.0. Not a final release: the securit
 See `docs/limitations.md`. Deferred: optional NER/Presidio detectors, stdin/stdout streaming,
 directory processing, structured log parsers, key files, reversible token vault, lossy decoding.
 
-[Unreleased]: https://github.com/aashishkumar-tech/ciphergate/compare/v0.11.0...HEAD
+[Unreleased]: https://github.com/aashishkumar-tech/ciphergate/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/aashishkumar-tech/ciphergate/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/aashishkumar-tech/ciphergate/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/aashishkumar-tech/ciphergate/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/aashishkumar-tech/ciphergate/compare/v0.8.0...v0.9.0

{ciphergate_cli-0.11.0 → ciphergate_cli-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ciphergate-cli
-Version: 0.11.0
+Version: 0.12.0
 Summary: Local-first, environment- and destination-aware inspection and sanitization of logs and test datasets.
 Project-URL: Homepage, https://github.com/aashishkumar-tech/ciphergate
 Project-URL: Source, https://github.com/aashishkumar-tech/ciphergate
@@ -50,7 +50,7 @@ vendor ticket. CipherGate replaces that with a local, explainable, scriptable ga
 inspect  ->  plan  ->  sanitize --apply  ->  rescan
 ```
 
-> **Status: 0.11.0 (alpha).** No detector finds every sensitive value. A passing run means the
+> **Status: 0.12.0 (alpha).** No detector finds every sensitive value. A passing run means the
 > configured processing completed under the selected policy; it is **not** proof that the output
 > contains no sensitive information, and it is not a compliance (GDPR, HIPAA, PCI DSS, ...) or
 > anonymization guarantee. Policy templates must be reviewed before use.
@@ -287,10 +287,14 @@ ciphergate inspect logs/ --policy policies/developer_logs.yml --environment dev
 ciphergate sanitize logs/ --policy ... --output build/logs.sanitized --apply
 ```
 
-- Files are chosen by extension (`.csv`, `.json`, `.jsonl`, `.ndjson`, `.txt`, `.log`), or all
-  regular files when `--format` is given. Subdirectories are processed only with
+- Files are chosen by extension (`.csv`, `.json`, `.jsonl`, `.ndjson`, `.txt`, `.log`, `.out`,
+  `.err`), or all regular files when `--format` is given. Subdirectories are processed only with
   `--recursive`/`-r` (at most 32 levels). Symlinks, junctions, devices, FIFOs and other
   extensions are **skipped and listed** in the report with a reason; links are never followed.
+  Skipped extensions also produce a warning, because those files were never scanned; a strict
+  `rescan` fails (exit 7) when it skipped any, and `sanitize` leaves them out of the output.
+  `--format` on a directory applies to every file, and the run warns when that contradicts an
+  extension (for example a CSV read as text loses its column names).
   At most 1000 files by default (`--max-files N`); more fails the run (exit 4) before anything
   is processed. An empty selection fails with `batch_empty` (exit 4).
 - Each file is processed exactly like a single-file run, in sorted path order; a failing file

{ciphergate_cli-0.11.0 → ciphergate_cli-0.12.0}/README.md

@@ -11,7 +11,7 @@ vendor ticket. CipherGate replaces that with a local, explainable, scriptable ga
 inspect  ->  plan  ->  sanitize --apply  ->  rescan
 ```
 
-> **Status: 0.11.0 (alpha).** No detector finds every sensitive value. A passing run means the
+> **Status: 0.12.0 (alpha).** No detector finds every sensitive value. A passing run means the
 > configured processing completed under the selected policy; it is **not** proof that the output
 > contains no sensitive information, and it is not a compliance (GDPR, HIPAA, PCI DSS, ...) or
 > anonymization guarantee. Policy templates must be reviewed before use.
@@ -248,10 +248,14 @@ ciphergate inspect logs/ --policy policies/developer_logs.yml --environment dev
 ciphergate sanitize logs/ --policy ... --output build/logs.sanitized --apply
 ```
 
-- Files are chosen by extension (`.csv`, `.json`, `.jsonl`, `.ndjson`, `.txt`, `.log`), or all
-  regular files when `--format` is given. Subdirectories are processed only with
+- Files are chosen by extension (`.csv`, `.json`, `.jsonl`, `.ndjson`, `.txt`, `.log`, `.out`,
+  `.err`), or all regular files when `--format` is given. Subdirectories are processed only with
   `--recursive`/`-r` (at most 32 levels). Symlinks, junctions, devices, FIFOs and other
   extensions are **skipped and listed** in the report with a reason; links are never followed.
+  Skipped extensions also produce a warning, because those files were never scanned; a strict
+  `rescan` fails (exit 7) when it skipped any, and `sanitize` leaves them out of the output.
+  `--format` on a directory applies to every file, and the run warns when that contradicts an
+  extension (for example a CSV read as text loses its column names).
   At most 1000 files by default (`--max-files N`); more fails the run (exit 4) before anything
   is processed. An empty selection fails with `batch_empty` (exit 4).
 - Each file is processed exactly like a single-file run, in sorted path order; a failing file

{ciphergate_cli-0.11.0 → ciphergate_cli-0.12.0}/docs/policy-schema.md

@@ -150,6 +150,19 @@ actions/params are **rejected** (`policy_conflict`, naming both rule IDs).
 Several findings on one value combine: `drop_record` > `drop_field` > whole-value transform
 (most protective by rank) > span transforms (overlaps merged, most protective wins).
 
+## Hard rules and guardrails
+
+`hard: true` puts a rule at level 2, above guardrails, field rules and everything else except the
+engine's own constraints. Use it for "never, whatever other rules say", such as blocking
+credentials for untrusted destinations. A hard rule cannot `allow`.
+
+`guardrail: true` puts a rule at level 3. It must name `environments` and either
+`target_environments` or `destinations`, so it only fires for a specific environment-to-recipient
+move (for example PRD to `external_ai`). A guardrail cannot `allow`, and a rule cannot be both.
+
+A blocked run prints `next:` lines in the terminal summary with what to change, based on the
+reason codes. They never include input values.
+
 ## Transfers
 
 ```yaml

{ciphergate_cli-0.11.0 → ciphergate_cli-0.12.0}/src/ciphergate/__init__.py

@@ -24,7 +24,7 @@ Supported public API (everything else is internal and may change without notice)
     rescan_directory(root, policy, context=None, *, recursive=False, strict=None) -> BatchReport
 """
 
-__version__ = "0.11.0"
+__version__ = "0.12.0"
 
 from ciphergate.config import RuntimeSettings
 from ciphergate.constants import (

{ciphergate_cli-0.11.0 → ciphergate_cli-0.12.0}/src/ciphergate/pipeline/batch.py

@@ -96,6 +96,9 @@ class BatchReport:
     skipped: list[dict[str, str]]
     output: dict[str, Any] = field(default_factory=dict)
     warnings: list[str] = field(default_factory=list)
+    # Exit code when every processed file passed but the run still cannot count as
+    # complete, e.g. a strict rescan that skipped files it could not read.
+    incomplete_exit: int = 0
     run_id: str = field(default_factory=new_run_id)
     timestamp: str = field(default_factory=utc_now)
 
@@ -104,7 +107,7 @@ class BatchReport:
         for result in self.files:
             if result.exit_code != 0:
                 return result.exit_code
-        return 0
+        return self.incomplete_exit
 
     @property
     def status(self) -> str:
@@ -277,6 +280,34 @@ def _run_each(
     return results
 
 
+def coverage_warnings(
+    discovery: Discovery, fmt: InputFormat | None, *, sanitize: bool = False
+) -> list[str]:
+    """Say which files were not scanned, or were read as a format their extension contradicts."""
+    warnings: list[str] = []
+    unknown = sum(1 for _, reason in discovery.skipped if reason == "unsupported_extension")
+    if unknown:
+        warnings.append(
+            f"{unknown} file(s) were skipped and not scanned because their extension is not "
+            "recognised"
+            + ("; they are not in the output" if sanitize else "")
+            + "; rename them, or pass --format to read every file as one format"
+        )
+    if fmt is not None:
+        mismatched = sum(
+            1
+            for rel in discovery.files
+            if EXTENSION_FORMATS.get(rel.suffix.lower()) not in (None, fmt)
+        )
+        if mismatched:
+            warnings.append(
+                f"--format {fmt} was applied to {mismatched} file(s) whose extension means "
+                "another format; structure such as CSV columns or JSON keys may be lost. "
+                "Run those files separately without --format"
+            )
+    return warnings
+
+
 def _require_files(discovery: Discovery) -> None:
     if not discovery.files:
         raise InputFormatError(
@@ -312,6 +343,8 @@ def analyze_directory(
         return rescan_file(path, policy, context, strict=strict, runtime=runtime, fmt=fmt)
 
     mode = runtime.path_display
+    effective_strict = policy.document.settings.strict if strict is None else strict
+    unscanned = any(reason == "unsupported_extension" for _, reason in discovery.skipped)
     return BatchReport(
         command=command,
         input_display=display_relative(Path(root.name), 0, root.parent, mode)
@@ -320,6 +353,11 @@ def analyze_directory(
         recursive=recursive,
         files=_run_each(discovery, mode, run),
         skipped=_skipped(discovery, mode),
+        warnings=coverage_warnings(discovery, fmt),
+        # A strict rescan is a gate: files it could not read must not count as passed.
+        incomplete_exit=int(ExitCode.RESCAN_FAILED)
+        if command == "rescan" and effective_strict and unscanned
+        else 0,
     )
 
 
@@ -472,6 +510,7 @@ def sanitize_directory(
             results,
             _skipped(discovery, mode),
             output={"written": False, "path": shown_out, "withheld_reason": "apply_not_set"},
+            warnings=coverage_warnings(discovery, options.format, sanitize=True),
         )
 
     parent = output.parent if str(output.parent) else Path(".")
@@ -491,7 +530,14 @@ def sanitize_directory(
             mode,
             lambda path, rel: sanitize_file(path, staging / rel, policy, context, file_options),
         )
-        report = BatchReport("sanitize", shown_root, recursive, results, _skipped(discovery, mode))
+        report = BatchReport(
+            "sanitize",
+            shown_root,
+            recursive,
+            results,
+            _skipped(discovery, mode),
+            warnings=coverage_warnings(discovery, options.format, sanitize=True),
+        )
         for result in results:
             if result.report is not None:
                 result.report.output["path"] = f"{shown_out}/{result.display}"

{ciphergate_cli-0.11.0 → ciphergate_cli-0.12.0}/src/ciphergate/readers/__init__.py

@@ -33,6 +33,8 @@ EXTENSION_FORMATS: dict[str, InputFormat] = {
     ".ndjson": InputFormat.JSONL,
     ".txt": InputFormat.TEXT,
     ".log": InputFormat.TEXT,
+    ".out": InputFormat.TEXT,
+    ".err": InputFormat.TEXT,
 }
 
 _JSON_PREFIXES = (

ciphergate_cli-0.12.0/src/ciphergate/reporting/next_steps.py

@@ -0,0 +1,106 @@
+"""Short next-step hints for runs that did not complete. Built from reason codes only."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ciphergate.constants import ReasonCode
+
+_HINTS: dict[str, str] = {
+    ReasonCode.CREDENTIAL_DETECTED_HARD_BLOCK: (
+        "a credential was found: remove it from the input and rotate it if it is real; "
+        "no policy can let credentials through"
+    ),
+    ReasonCode.EXPLICIT_HARD_BLOCK: (
+        "a hard rule blocks these values for this destination: remove them from the input, or "
+        "use a policy written for a destination allowed to receive them; "
+        "'ciphergate explain' shows which rule wins"
+    ),
+    ReasonCode.ENVIRONMENT_GUARDRAIL: (
+        "a guardrail rule blocks this environment-to-destination move; check the context, or "
+        "change the guardrail in the policy after review"
+    ),
+    ReasonCode.PRD_TO_NONPRODUCTION_BLOCKED: (
+        "production data cannot go to a non-production target without a reviewed 'transfers' "
+        "approval in the policy (docs/policy-schema.md#transfers)"
+    ),
+    ReasonCode.NO_APPLICABLE_RULE_REQUIRES_REVIEW: (
+        "no rule covers some findings: add rules for the categories listed above, then run "
+        "'ciphergate plan' again"
+    ),
+    ReasonCode.NO_APPLICABLE_RULE_BLOCKS: (
+        "no rule covers some findings: add rules for the categories listed above, then run "
+        "'ciphergate plan' again"
+    ),
+    ReasonCode.UNKNOWN_CONTEXT_REQUIRES_REVIEW: (
+        "the environment or destination is 'unknown': pass the real values with --environment "
+        "and --destination"
+    ),
+    ReasonCode.HIGH_RISK_ALLOW_REQUIRES_ACKNOWLEDGEMENT: (
+        "an allow rule reaches high-risk data toward an untrusted destination: narrow the rule, "
+        "or set acknowledge_risk: true after review"
+    ),
+    ReasonCode.UNSUPPORTED_TRANSFORM: (
+        "a rule's action cannot run on this format or location: choose another action for it"
+    ),
+    ReasonCode.ENVIRONMENT_REQUIRED_BUT_MISSING: (
+        "pass --environment (dev, stg, prd) or pin context.environment in the policy"
+    ),
+    ReasonCode.DESTINATION_REQUIRED_BUT_MISSING: (
+        "pass --destination (for example local_dev or external_ai) or pin context.destination "
+        "in the policy"
+    ),
+    ReasonCode.TARGET_ENVIRONMENT_REQUIRED_BUT_MISSING: (
+        "pass --target-environment or pin context.target_environment in the policy"
+    ),
+    ReasonCode.ENVIRONMENT_CONTEXT_CONFLICT: (
+        "a CLI flag contradicts the policy's pinned context: drop the flag, or use a policy for "
+        "that context"
+    ),
+    ReasonCode.UNSUPPORTED_ENVIRONMENT: "use one of the documented environment values",
+    ReasonCode.STRICT_POLICY_REQUIRED: (
+        "this destination needs a strict policy: set settings.strict: true"
+    ),
+    ReasonCode.RESCAN_REQUIRED: (
+        "this destination needs the rescan gate: do not disable settings.rescan in the policy"
+    ),
+    ReasonCode.CREDENTIAL_DETECTION_REQUIRED: (
+        "this destination needs credential detection: remove secret_pattern and field_name from "
+        "detectors.disabled"
+    ),
+    ReasonCode.KEY_SCAN_REQUIRED: (
+        "this destination needs JSON key scanning: set settings.scan_json_keys: true"
+    ),
+    ReasonCode.RESIDUAL_FINDING: (
+        "the rescan still found gating categories in the output: add rules for them, then run again"
+    ),
+}
+
+_KEY_HINT = (
+    "set {env} to at least 32 random bytes in your environment (never on the command line); "
+    "see 'Pseudonymization key' in the README"
+)
+
+
+def next_steps(report: dict[str, Any]) -> list[str]:
+    """Hints for a run that ended with a non-zero exit code; empty otherwise."""
+    if not report.get("exit_code"):
+        return []
+    codes = [gate["reason_code"] for gate in report.get("gates", [])]
+    if report.get("command") != "rescan":
+        # A rescan's policy decisions describe the output, not what to fix in the input.
+        codes += list(report.get("summary", {}).get("by_reason_code", {}))
+    rescan = report.get("rescan")
+    if rescan and rescan.get("failed"):
+        codes.append(ReasonCode.RESIDUAL_FINDING)
+    hints: list[str] = []
+    for code in codes:
+        hint = _HINTS.get(code)
+        if hint and hint not in hints:
+            hints.append(hint)
+    for key in report.get("keys", []):
+        if key.get("status") != "available":
+            hint = _KEY_HINT.format(env=key["key_env"])
+            if hint not in hints:
+                hints.append(hint)
+    return hints

{ciphergate_cli-0.11.0 → ciphergate_cli-0.12.0}/src/ciphergate/reporting/terminal.py

@@ -7,6 +7,7 @@ from typing import Any
 from ciphergate.constants import DISCLAIMER, RESCAN_LIMIT
 from ciphergate.models.report import RunReport
 from ciphergate.pipeline.batch import BatchReport
+from ciphergate.reporting.next_steps import next_steps
 from ciphergate.reporting.safe_text import escape_control
 
 SUMMARY_ITEMS = 15
@@ -119,6 +120,8 @@ def render_summary(report: RunReport, *, verbose: bool = False) -> str:
             lines.append(f"  output:  not written ({out['withheld_reason']})")
     for warning in d["warnings"]:
         lines.append(f"  warning: {escape_control(warning)}")
+    for hint in next_steps(d):
+        lines.append(f"  next: {hint}")
     lines.append(f"  note: {DISCLAIMER}")
     return "\n".join(lines) + "\n"
 
@@ -158,6 +161,13 @@ def render_batch_summary(report: BatchReport, *, verbose: bool = False) -> str:
             lines.append(f"  output:  not written ({out.get('withheld_reason')})")
     for warning in d["warnings"]:
         lines.append(f"  warning: {escape_control(warning)}")
+    hints: list[str] = []
+    for entry in d["files"]:
+        for hint in next_steps(entry.get("report") or {}):
+            if hint not in hints:
+                hints.append(hint)
+    for hint in hints:
+        lines.append(f"  next: {hint}")
     lines.append("  note: per-file details are in the JSON report (--report).")
     lines.append(f"  note: {DISCLAIMER}")
     return "\n".join(lines) + "\n"

{ciphergate_cli-0.11.0 → ciphergate_cli-0.12.0}/tests/integration/test_batch.py

@@ -354,3 +354,54 @@ def test_entry_replaced_after_discovery_is_not_processed(
     )
     assert calls == []
     assert results[0].error_code == "input_changed_type" and results[0].exit_code != 0
+
+
+# --------------------------------------------------------------------------- coverage
+
+
+def test_out_and_err_files_are_read_as_text(tmp_path: Path) -> None:
+    root = tmp_path / "in"
+    root.mkdir()
+    (root / "app.out").write_text("started\n", encoding="utf-8")
+    (root / "app.err").write_text("failed\n", encoding="utf-8")
+    d = discover(root, recursive=False, fmt=None, max_files=10)
+    assert [p.as_posix() for p in d.files] == ["app.err", "app.out"] and not d.skipped
+
+
+def test_skipped_files_are_a_warning_and_fail_a_strict_rescan(tmp_path: Path, env) -> None:
+    root = tmp_path / "in"
+    root.mkdir()
+    (root / "clean.log").write_text("service started\n", encoding="utf-8")
+    (root / "notes.md").write_text("not scanned\n", encoding="utf-8")
+    r = invoke("inspect", root, *PRD_EXTERNAL, env=env)
+    assert r.exit_code == 0 and "1 file(s) were skipped and not scanned" in r.stdout
+    strict = invoke("rescan", root, *PRD_EXTERNAL, env=env)
+    assert strict.exit_code == 7 and "not scanned" in strict.stdout
+    assert invoke("rescan", root, *PRD_EXTERNAL, "--no-strict", env=env).exit_code == 0
+
+
+def test_sanitize_warns_that_skipped_files_are_not_in_the_output(tmp_path: Path, env) -> None:
+    root = tmp_path / "in"
+    root.mkdir()
+    (root / "clean.log").write_text("service started\n", encoding="utf-8")
+    (root / "notes.md").write_text("not scanned\n", encoding="utf-8")
+    out = tmp_path / "out"
+    r = invoke("sanitize", root, *PRD_EXTERNAL, "-o", out, "--apply", env=env)
+    assert r.exit_code == 0 and "they are not in the output" in r.stdout
+    assert sorted(p.name for p in out.iterdir()) == ["clean.log"]
+
+
+def test_forced_format_that_contradicts_an_extension_warns(tmp_path: Path, env) -> None:
+    root = _tree(tmp_path)
+    report = tmp_path / "report.json"
+    r = invoke("inspect", root, "--format", "text", *PRD_EXTERNAL, "--report", report, env=env)
+    assert "--format text was applied to 1 file(s)" in r.stdout
+    assert any("--format text" in w for w in _report(report)["warnings"])
+
+
+def test_directory_summary_carries_next_steps(tmp_path: Path) -> None:
+    root = tmp_path / "in"
+    root.mkdir()
+    (root / "app.log").write_text(SECRET_LINE, encoding="utf-8")
+    r = invoke("inspect", root, "--policy", POLICIES / "developer_logs.yml")
+    assert r.exit_code == 1 and "next: pass --environment" in r.stdout

{ciphergate_cli-0.11.0 → ciphergate_cli-0.12.0}/tests/integration/test_cli_e2e.py

@@ -197,6 +197,35 @@ def test_sanitize_missing_key_exit_6(tmp_path: Path, no_key_env: None) -> None:
     assert r.exit_code == 6 and not out.exists() and "missing" in r.stdout
 
 
+def test_blocked_run_says_what_to_do_next(tmp_path: Path) -> None:
+    src = tmp_path / "raw.csv"
+    shutil.copy(EXAMPLES / "sample.csv", src)
+    out = tmp_path / "out.csv"
+    r = invoke("sanitize", src, "--policy", POLICIES / "developer_logs.yml", "-o", out, "--apply")
+    assert r.exit_code == 1 and not out.exists()
+    assert "next: pass --environment" in r.stdout and "next: pass --destination" in r.stdout
+
+
+def test_successful_run_has_no_next_steps(tmp_path: Path) -> None:
+    clean = tmp_path / "clean.log"
+    clean.write_text("service started\n", encoding="utf-8")
+    out = tmp_path / "out.log"
+    r = invoke(
+        "sanitize",
+        clean,
+        "--policy",
+        POLICIES / "developer_logs.yml",
+        "--environment",
+        "dev",
+        "--destination",
+        "local_dev",
+        "-o",
+        out,
+        "--apply",
+    )
+    assert r.exit_code == 0 and "next:" not in r.stdout
+
+
 def test_rescan_summary_never_says_a_bare_pass(tmp_path: Path) -> None:
     policy = POLICIES / "prd_external_ai.yml"
     clean = tmp_path / "clean.log"

ciphergate_cli-0.12.0/tests/unit/test_next_steps.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ciphergate.constants import ReasonCode
+from ciphergate.reporting.next_steps import _HINTS, next_steps
+
+
+def report(**extra: Any) -> dict[str, Any]:
+    base: dict[str, Any] = {
+        "command": "sanitize",
+        "exit_code": 1,
+        "gates": [],
+        "summary": {"by_reason_code": {}},
+        "keys": [],
+        "rescan": None,
+    }
+    base.update(extra)
+    return base
+
+
+def test_successful_run_has_no_hints() -> None:
+    blocked = {"by_reason_code": {ReasonCode.EXPLICIT_HARD_BLOCK: 1}}
+    assert next_steps(report(exit_code=0, summary=blocked)) == []
+
+
+def test_gates_decisions_keys_and_rescan_each_give_a_hint() -> None:
+    hints = next_steps(
+        report(
+            gates=[{"reason_code": ReasonCode.DESTINATION_REQUIRED_BUT_MISSING}],
+            summary={"by_reason_code": {ReasonCode.CREDENTIAL_DETECTED_HARD_BLOCK: 2}},
+            keys=[{"key_env": "CIPHERGATE_HMAC_KEY", "status": "missing"}],
+            rescan={"failed": True},
+        )
+    )
+    assert len(hints) == 4
+    assert "--destination" in hints[0] and "rotate" in hints[1]
+    assert "rescan" in hints[2] and "CIPHERGATE_HMAC_KEY" in hints[3]
+
+
+def test_duplicate_hints_are_shown_once() -> None:
+    summary = {
+        "by_reason_code": {
+            ReasonCode.NO_APPLICABLE_RULE_REQUIRES_REVIEW: 1,
+            ReasonCode.NO_APPLICABLE_RULE_BLOCKS: 1,
+        }
+    }
+    assert len(next_steps(report(summary=summary))) == 1
+
+
+def test_rescan_hints_ignore_the_policy_decisions() -> None:
+    summary = {"by_reason_code": {ReasonCode.EXPLICIT_HARD_BLOCK: 1}}
+    hints = next_steps(
+        report(command="rescan", exit_code=7, summary=summary, rescan={"failed": True})
+    )
+    assert hints == [_HINTS[ReasonCode.RESIDUAL_FINDING]]
+
+
+def test_hints_are_fixed_text() -> None:
+    # Hints come from a fixed table, so they can never carry input values.
+    unknown = {"by_reason_code": {"explicit_policy_match": 3, "not_a_code": 1}}
+    assert next_steps(report(summary=unknown)) == []