maestro-guard

<purpose> Configure directory-level write boundaries enforced by the workflow-guard PreToolUse hook. Subcommands: on, off, status, allow `<path>`, deny `<path>`, remove `<path>`, clear. </purpose> <context> $ARGUMENTS — Parse subcommand and optional path argument.

Config location: .workflow/config.json → guard section

{
  "guard": {
    "enabled": false,
    "mode": "allow",
    "paths": []
  }
}

Enforcement: The workflow-guard hook (PreToolUse on Write/Edit) reads this config and blocks operations targeting files outside boundaries. Requires hooks level >= full.

Output boundary: ALL file writes MUST target .workflow/config.json (guard section) only. NEVER modify hook files, .claude/settings.json, or source code. </context>

<invariants> 1. **Config-only mutation** — guard MUST only modify the `guard` section of `.workflow/config.json`; NEVER touch other config sections or files 2. **Non-destructive** — `off` MUST preserve existing paths and mode; NEVER clear the path list when disabling 3. **Mode switch confirmation** — switching between allow/deny mode MUST require request_user_input confirmation when existing paths will be cleared 4. **Hook dependency** — guard MUST warn when enabled but `workflow-guard` hook is not active (hooks level < full) 5. **Path normalization** — all paths MUST use forward slashes with trailing slash for directories; NEVER store raw backslash paths </invariants> <execution>

Phase Gates (MANDATORY, BLOCKING)

GATE 1: Parse → Config Read

• REQUIRED: Subcommand parsed (on/off/status/allow/deny/remove/clear) or defaulted to status.
• BLOCKED if: invalid subcommand provided.

GATE 2: Config Read → Execute

• REQUIRED: .workflow/config.json read successfully or initialized with empty guard section.
• BLOCKED if: file unreadable and cannot be created (E001).

GATE 3: Execute → Confirm

• REQUIRED: Config mutation applied (for on/off/allow/deny) or status displayed (for status).
• REQUIRED: Mode-switch request_user_input answered (for allow↔deny transitions with existing paths).
• BLOCKED if: user declines mode switch.

Step 1: Parse subcommand

Extract from $ARGUMENTS:

• on / off / status / allow <path> / deny <path>
• If no subcommand, default to status

Step 2: Read config

Read .workflow/config.json. If file missing, initialize with empty guard section.

Step 3: Execute subcommand

status:

• Display: enabled/disabled, mode (allow/deny), paths list
• Check if workflow-guard hook is active (read .claude/settings.json for hook presence)
• If guard enabled but hook not active, warn: "⚠ PathGuard enabled but workflow-guard hook not installed. Run maestro hooks level full to activate."

on:

• Set guard.enabled = true
• If guard.paths is empty, set default: ["src/", "tests/", ".workflow/"]
• Check hook level, warn if < full
• Write config

off:

• Set guard.enabled = false
• Preserve existing paths and mode
• Write config

allow <path>:

• Normalize path to forward slashes, ensure trailing slash for directories
• If guard.mode is deny, request_user_input: "Switching from deny to allow mode will clear existing paths ({N} paths). Continue?" — abort if user declines. Clear guard.paths (mode switch invalidates previous path list).
• Set guard.mode = "allow"
• Add path to guard.paths (deduplicate)
• Set guard.enabled = true if not already
• Write config

deny <path>:

• Normalize path to forward slashes, ensure trailing slash for directories
• If guard.mode is allow, request_user_input: "Switching from allow to deny mode will clear existing paths ({N} paths). Continue?" — abort if user declines. Clear guard.paths (mode switch invalidates previous path list).
• Set guard.mode = "deny"
• Add path to guard.paths (deduplicate)
• Set guard.enabled = true if not already (symmetric with allow: adding a deny path auto-enables the guard)
• Write config

remove <path>:

• Normalize path
• Remove from guard.paths (if present)
• Write config

clear:

• Set guard.paths = []
• Write config

Step 4: Confirm

Display updated guard configuration.

</execution>

<error_codes>

• E001: .workflow/config.json not found and cannot be created (not a maestro project)
• W001: PathGuard enabled but workflow-guard hook not installed </error_codes>

<success_criteria>

• Config read/written correctly
• Hook level warning displayed when applicable
• Updated configuration shown after changes </success_criteria>

<completion> ### Next-step routing | Condition | Suggestion | |-----------|-----------| | Guard enabled, hook not installed | `maestro hooks level full` | | Want to verify guard works | Edit a file outside allowed paths | </completion>