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 ```json { "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>