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

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

@@ -6,6 +6,41 @@ 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
+`rescan` terminal output need updating; exit codes and the JSON report do not change.
+
+### Changed
+
+- The `rescan` terminal summary no longer prints `PASSED`. It says `NO GATING FINDINGS`, or
+  `NOT ENFORCED` when gating findings remain with strict off, and states what rescan cannot see.
+  Exit codes and the JSON report's `status` are unchanged.
+- `validate-policy` warns when a rule or default handles `credential.secret` with anything other
+  than `block` or `review` toward a possibly untrusted destination.
+
 ## [0.10.0] - 2026-10-30
 
 Fixes a password leak in nested values and detects more credentials and identifiers. A run that
@@ -315,7 +350,9 @@ 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.10.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
 [0.8.0]: https://github.com/aashishkumar-tech/ciphergate/compare/v0.7.1...v0.8.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ciphergate-cli
-Version: 0.10.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.10.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.
@@ -154,6 +154,7 @@ ciphergate sanitize examples/sample.csv --policy policies/prd_external_ai.yml \
   --output build/sample.sanitized.csv --report build/sample.report.json --apply
 
 # 5. Rescan the output (read-only). Exit 7 if gating residual findings remain.
+# A clean result only means no gating findings. It does not show the output is safe.
 ciphergate rescan build/sample.sanitized.csv --policy policies/prd_external_ai.yml
 ```
 
@@ -286,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.10.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.10.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.
@@ -115,6 +115,7 @@ ciphergate sanitize examples/sample.csv --policy policies/prd_external_ai.yml \
   --output build/sample.sanitized.csv --report build/sample.report.json --apply
 
 # 5. Rescan the output (read-only). Exit 7 if gating residual findings remain.
+# A clean result only means no gating findings. It does not show the output is safe.
 ciphergate rescan build/sample.sanitized.csv --policy policies/prd_external_ai.yml
 ```
 
@@ -247,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.10.0 → ciphergate_cli-0.12.0}/docs/limitations.md

@@ -5,7 +5,9 @@
 - Detection is incomplete. Names, addresses, government IDs and bank accounts are not detected by
   value in free text; secrets in custom formats or encoded forms are missed. See
   [detector-coverage.md](detector-coverage.md).
-- A clean rescan is a quality gate, not proof of safety. Rescan cannot verify date-shifted values
+- A clean rescan is a quality gate, not proof of safety. The terminal summary says "no gating
+  findings" for this reason, while the JSON report keeps `status: passed` for CI. Names and
+  addresses in free text are often missed. Rescan cannot verify date-shifted values
   (reported as `unverifiable`) and recognises CipherGate's own markers/pseudonyms/replacement
   constants as transformed output.
 - Confidence values are uncalibrated engineering estimates.

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

@@ -122,6 +122,12 @@ A context selector never matches missing context.
 | `review` | — | run needs human decision, nothing written |
 | `tokenize` | — | **rejected**: no token vault in this release |
 
+A rule or default that applies `redact`, `replace`, or any other non-`block`, non-`review` action
+to `credential.secret` toward a possibly untrusted destination validates with a warning, because
+a detector can match only part of a secret. A destination that is not pinned counts as possibly
+untrusted. A `hard: true` block that covers every untrusted destination, with no selectors other
+than `categories` and `destinations`, removes the warning.
+
 ## Precedence (deterministic)
 
 1. Engine hard constraints: missing/invalid context gates; credential never allowed (forced
@@ -144,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.10.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.10.0"
+__version__ = "0.12.0"
 
 from ciphergate.config import RuntimeSettings
 from ciphergate.constants import (

{ciphergate_cli-0.10.0 → ciphergate_cli-0.12.0}/src/ciphergate/cli.py

@@ -749,7 +749,10 @@ def rescan_command(
     no_color: NoColorOpt = False,
     debug: DebugOpt = False,
 ) -> None:
-    """Report residual findings in an existing output. Read-only; never alters the file."""
+    """Report residual findings in an existing output. Read-only; never alters the file.
+
+    No gating findings does not mean the output is safe: rescan only sees what detectors match.
+    """
     _configure_logging(verbose, debug)
     _guard(
         debug,

{ciphergate_cli-0.10.0 → ciphergate_cli-0.12.0}/src/ciphergate/constants.py

@@ -272,3 +272,7 @@ DISCLAIMER = (
     "It does not prove that the output contains no sensitive information; "
     "detectors can miss values."
 )
+RESCAN_LIMIT = (
+    "rescan only sees what the enabled detectors match. No gating findings does not mean the "
+    "output is safe; names and addresses in free text are often missed."
+)

{ciphergate_cli-0.10.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.10.0 → ciphergate_cli-0.12.0}/src/ciphergate/policy/validator.py

@@ -225,6 +225,34 @@ def _effective_destinations(doc: PolicyDocument, rule_dests: list[Destination] |
     return {str(d) for d in Destination}
 
 
+def _hard_blocked_destinations(doc: PolicyDocument, categories: frozenset[str]) -> set[str]:
+    """Destinations where a hard rule blocks every credential finding, whatever its field."""
+    blocked: set[str] = set()
+    for rule in doc.rules:
+        m = rule.match
+        if (
+            rule.hard
+            and rule.action == Action.BLOCK
+            and m.categories is not None
+            and CREDENTIAL_CATEGORY in _selector_can_cover(m.categories, categories)
+            and set(m.model_dump(exclude_none=True)) <= {"categories", "destinations"}
+        ):
+            blocked |= _effective_destinations(doc, m.destinations)
+    return blocked
+
+
+def _relaxes_credentials(
+    doc: PolicyDocument,
+    action: Action,
+    rule_dests: list[Destination] | None,
+    hard_blocked: set[str],
+) -> bool:
+    if action in (Action.BLOCK, Action.REVIEW):
+        return False
+    reachable = _effective_destinations(doc, rule_dests) - hard_blocked
+    return bool(reachable & {str(d) for d in UNTRUSTED_DESTINATIONS})
+
+
 def _selector_can_cover(selectors: list[str] | None, categories: frozenset[str]) -> set[str]:
     if selectors is None:
         return set(categories)
@@ -335,6 +363,7 @@ def compile_policy(raw: dict[str, Any], *, digest: str, source_name: str | None
     required_keys: set[str] = set()
     replacement_values: set[str] = set()
     seen_rules: set[str] = set()
+    hard_blocked = _hard_blocked_destinations(doc, categories)
     for i, rule in enumerate(doc.rules):
         where = f"rules[{i}]"
         if rule.id in seen_rules:
@@ -394,6 +423,15 @@ def compile_policy(raw: dict[str, Any], *, digest: str, source_name: str | None
                     "credential_unsafe_action",
                 )
             )
+        if (
+            CREDENTIAL_CATEGORY in covered
+            and m.categories is not None
+            and _relaxes_credentials(doc, rule.action, m.destinations, hard_blocked)
+        ):
+            warnings.append(
+                f"rule '{rule.id}' applies '{rule.action}' to credential.secret toward a possibly "
+                "untrusted destination instead of blocking; detection can miss part of a secret"
+            )
         if rule.action == Action.ALLOW:
             dests = _effective_destinations(doc, m.destinations)
             untrusted = dests & {str(d) for d in UNTRUSTED_DESTINATIONS}
@@ -492,6 +530,13 @@ def compile_policy(raw: dict[str, Any], *, digest: str, source_name: str | None
                     "credential_unsafe_action",
                 )
             )
+        if CREDENTIAL_CATEGORY in covered and _relaxes_credentials(
+            doc, spec.action, None, hard_blocked
+        ):
+            warnings.append(
+                f"default '{sel}' applies '{spec.action}' to credential.secret toward a possibly "
+                "untrusted destination instead of blocking; detection can miss part of a secret"
+            )
         if isinstance(params, PseudonymizeParams | DateShiftParams):
             required_keys.add(params.key_env)
         if isinstance(params, ReplaceParams) and params.value is not None:

{ciphergate_cli-0.10.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.10.0 → ciphergate_cli-0.12.0}/src/ciphergate/reporting/terminal.py

@@ -4,9 +4,10 @@ from __future__ import annotations
 
 from typing import Any
 
-from ciphergate.constants import DISCLAIMER
+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
@@ -31,9 +32,24 @@ def _location(loc: dict[str, Any]) -> str:
     return ", ".join(parts)
 
 
+def _rescan_verdict(rescan: dict[str, Any]) -> str:
+    if rescan["failed"]:
+        return "FAILED, gating findings remain"
+    if rescan["gating_by_category"]:
+        return "NOT ENFORCED, gating findings remain but strict is off"
+    return "no gating findings"
+
+
+def _headline(d: dict[str, Any]) -> str:
+    # Never print a bare PASSED for rescan: it reads as "this output is safe".
+    if d["command"] == "rescan" and d["rescan"] and not d["rescan"]["failed"]:
+        return _rescan_verdict(d["rescan"]).split(",")[0].upper()
+    return str(d["status"]).upper()
+
+
 def render_summary(report: RunReport, *, verbose: bool = False) -> str:
     d = report.to_dict()
-    lines = [f"CipherGate {d['command']}: {d['status'].upper()} (exit {d['exit_code']})"]
+    lines = [f"CipherGate {d['command']}: {_headline(d)} (exit {d['exit_code']})"]
     inp = d["input"]
     lines.append(
         f"  input:   {escape_control(str(inp['path']))} [{inp['format']}, "
@@ -89,12 +105,13 @@ def render_summary(report: RunReport, *, verbose: bool = False) -> str:
         )
     if d["rescan"]:
         r = d["rescan"]
-        verdict = "FAILED" if r["failed"] else "passed"
         lines.append(
-            f"  rescan: {verdict} (strict={r['strict']}) residuals: {_counts(r['counts'])}"
+            f"  rescan: {_rescan_verdict(r)} (strict={r['strict']}) "
+            f"residuals: {_counts(r['counts'])}"
         )
         if r["gating_by_category"]:
             lines.append(f"    gating residuals: {_counts(r['gating_by_category'])}")
+        lines.append(f"  rescan limit: {RESCAN_LIMIT}")
     out = d["output"]
     if out:
         if out.get("written"):
@@ -103,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"
 
@@ -142,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.10.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