How the Case-Guard Script Prevents Premature ACT Before Scope Readiness

The case-guard script prevents premature ACT execution by enforcing four hard requirements—authorization status, network profile, in-scope assets, and explicit sign-off—on the scope.md file, exiting with status 2 if any validation fails.

The case-guard utility in the zhaoxuya520/reverse-skill repository acts as a mandatory pre-flight gate that validates case scope configuration before any action (ACT) code executes. By centralizing these checks in skills/scripts/case-guard.ps1 and skills/scripts/case-guard.sh, the workflow ensures that potentially dangerous or misconfigured operations cannot launch until the case is fully authorized and explicitly marked ready.

The Four Hard Gates Enforced by Case-Guard

The script parses the scope.md file and validates four specific contract fields. If any check fails, the script collects the issues and terminates with exit code 2, blocking all downstream ACT steps.

1. Authorization Status Must Be Granted

The script inspects the auth section and requires status: granted. If the field is missing or contains any other value, case-guard appends the issue "auth.status is not granted" to the error list.

In skills/scripts/case-guard.ps1, this validation occurs at lines 52–54, while the Bash implementation at skills/scripts/case-guard.sh handles the same logic at lines 66–71.

2. Network Profile Validation

The script extracts network_profile.mode and validates it against an enumerated whitelist: offline, lab_only, authorized_target_only, and unrestricted_lab.

For offline mode, the script performs an additional safety check—the scope must mention an offline sample cue (e.g., "sample" or ".apk"). Invalid or missing modes generate "network_profile.mode missing" or "network_profile.mode is unsupported" errors.

This validation logic resides at lines 55–62 in the PowerShell version and lines 73–86 in the Bash version.

3. In-Scope Assets Presence

The script scans only the ## in_scope section, parsing properly indented list items under - assets:. If no asset entries are detected—and the network mode is not offline—the script adds "in_scope.assets appears empty" to the issue list.

This check appears at lines 69–82 in case-guard.ps1 and lines 88–106 in case-guard.sh.

4. Sign-Off Readiness Confirmation

Final validation requires signoff.ready_for_act to be explicitly set to true. Missing or false values trigger the issue "ready_for_act is not true".

The PowerShell implementation checks this at lines 85–87, while the Bash script handles it at lines 108–112.

Exit Codes and Workflow Integration

The case-guard script uses specific exit codes to communicate state to CI pipelines and wrapper scripts like skills/scripts/smoke.ps1:

• 0 – All checks passed; the case scope is ready and ACT may proceed.
• 2 – Scope not ready; the workflow must abort any further ACT steps.
• 1 – Usage error (e.g., missing required arguments).

By invoking case-guard early in the execution chain—before scripts like master-route.ps1 or verify-routing-coherence.ps1 run—the repository guarantees that action code never executes against an unauthorized or incomplete scope.

The Force Flag Limitation

Both implementations provide a --force (Bash) or -Force (PowerShell) flag for compatibility, but the script explicitly states that it never bypasses the hard gates. Even when forced, the validation logic executes completely and will still exit with code 2 if requirements are not met.

This safety mechanism is documented at lines 96–99 in case-guard.ps1 and lines 22–27 in case-guard.sh.

Implementation Examples

Integrate the guard into your CI pipeline or local workflow by calling the appropriate script before any ACT execution:

# PowerShell: Validate scope before ACT

powershell -File skills/scripts/case-guard.ps1 -CaseRoot work\my-case

# Bash: Validate scope before ACT  

bash skills/scripts/case-guard.sh --case-root work/my-case

Both commands return exit code 2 and print specific issues if the scope.md file lacks the required fields defined in skills/ops/scope-contract.md.

Summary

• Hard gates cannot be bypassed—even with --force, the script validates all four requirements before allowing ACT execution.
• Exit code 2 specifically indicates unreadiness, enabling CI systems to catch scope violations before action code runs.
• Dual implementation ensures consistent behavior across Windows (PowerShell) and Unix (Bash) environments.
• Centralized validation in skills/scripts/smoke.ps1 and similar entry points prevents fragmented safety checks.
• Explicit contract defined in skills/ops/scope-contract.md dictates the required scope.md structure for authorization, network profile, assets, and sign-off.

Frequently Asked Questions

What happens if I run case-guard with the --force flag?

The --force or -Force flag does not bypass validation. According to the source code in case-guard.ps1 (lines 96–99) and case-guard.sh (lines 22–27), the flag is acknowledged for compatibility but the script explicitly states it never bypasses the hard gates. All four requirements are still enforced, and the script exits with code 2 if any check fails.

Can case-guard pass if no assets are defined in offline mode?

Yes. The asset presence check at lines 69–82 (PowerShell) and lines 88–106 (Bash) is skipped when network_profile.mode is set to offline. However, the offline mode requires the scope to mention a sample cue such as ".apk" or "sample" to ensure the analyst is working with isolated artifacts rather than live targets.

Which exit code indicates the scope is not ready?

Exit code 2 specifically signals that the scope is not ready. Code 0 indicates success, while code 1 indicates a usage error such as missing command-line arguments. CI pipelines should trap exit code 2 to abort ACT execution while distinguishing it from script crashes or syntax errors.

Where should case-guard be invoked in the workflow?

The script should be invoked as the first validation step in entry-point scripts like skills/scripts/smoke.ps1 or directly in CI pipeline steps before any ACT scripts (e.g., master-route.ps1, verify-routing-coherence.ps1) execute. This placement ensures no action code runs until the scope.md contract is fully satisfied.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}