KeiSeiKit-1.0/skills/spawn-agent/phase-3-scope.md

Phase 3 — Scope (files whitelist + optional denylist)

Goal: produce a concrete WHITELIST (glob patterns the agent may touch) and optionally an explicit DENYLIST. For read-only / explorer roles the whitelist is advisory; for edit-* roles it is ENFORCED by kei-spawn. Verify criterion: WHITELIST non-empty list of glob strings.

---

3.a — First AskUserQuestion: scope preset

Send ONE AskUserQuestion call. Presets cover ≥80% of real invocations; pick "Custom" only if none fit.

{
  "questions": [
    {
      "question": "Scope preset?",
      "header": "Scope",
      "multiSelect": false,
      "options": [
        {
          "label": "Single crate (Rust)",
          "description": "crates/<name>/** — typical edit-local scope. Also includes that crate's tests/ and Cargo.toml."
        },
        {
          "label": "Single skill (Markdown)",
          "description": "skills/<name>/** — pure-markdown skill authoring. No code compilation."
        },
        {
          "label": "Single agent manifest",
          "description": "agents/_manifests/<name>.toml + agents/_blocks/*.md — agent fleet authoring."
        },
        {
          "label": "Docs / rules only",
          "description": "**/*.md — read-only or explorer roles that only touch documentation."
        },
        {
          "label": "Whole project (read-only)",
          "description": "** — read-only or explorer roles. Not valid for edit-* (too broad; use edit-shared with explicit globs)."
        },
        {
          "label": "Custom",
          "description": "Enter glob patterns as one free-text line (comma- or newline-separated)."
        }
      ]
    }
  ]
}

Store the clicked label as SCOPE_PRESET.

---

3.b — Resolve preset to WHITELIST

• Single crate (Rust) → follow up with ONE free-text prompt: Crate name? Validate [a-z0-9-]+. Build: [ "crates/<name>/**", "Cargo.toml" ].
• Single skill (Markdown) → follow up: Skill name? Validate [a-z0-9-]+. Build: [ "skills/<name>/**" ].
• Single agent manifest → follow up: Agent name? Validate [a-z0-9-]+. Build: [ "agents/_manifests/<name>.toml", "agents/_blocks/*.md" ].
• Docs / rules only → Build: [ "**/*.md" ]. Warn if ROLE is edit-* — docs-only edits rarely need worktree isolation; suggest explorer or read-only instead.
• Whole project (read-only) → BLOCK if ROLE is edit-local or edit-shared. Print: "Whole-project scope is not allowed for edit roles. Use edit-shared with explicit globs naming the ≥2 modules you will touch." Loop back to 3.a. Otherwise build: [ "**" ].
• Custom → follow up: Enter glob patterns (comma- or newline-separated). Parse, trim, validate each glob against the rules in 3.c. Build the list.

---

3.c — Glob validation rules

Apply to every pattern in WHITELIST:

1. No absolute paths. Must not start with / or ~/. globs are repo-relative.
2. No parent traversal. Reject any pattern containing ...
3. No leading dot-dir unless explicit. .git/**, .claude/** must be typed in full; reject accidental .**.
4. At least one literal char. Reject ** alone without a scoping prefix unless ROLE is read-only or explorer AND SCOPE_PRESET was "Whole project".
5. Max count. ≤20 globs. If the user pastes more, ask them to consolidate.

On any failure, print the offending pattern and the rule that tripped; re-prompt for that one line; do NOT fall through.

---

3.d — Second AskUserQuestion: explicit denylist?

Send the second AskUserQuestion call:

{
  "questions": [
    {
      "question": "Denylist?",
      "header": "Deny",
      "multiSelect": false,
      "options": [
        {
          "label": "Auto (recommended)",
          "description": "kei-spawn applies the role-default denylist: secrets/**, **/*.env, target/**, node_modules/**, .git/**, dist/**, .keisei/** — covers 95% of cases."
        },
        {
          "label": "Explicit",
          "description": "Enter additional deny globs on top of the auto default. Use when the task whitelist accidentally includes sensitive subpaths."
        },
        {
          "label": "None (override auto)",
          "description": "Override the auto defaults and pass an empty denylist. BLOCKED for edit-* roles — read-only / explorer only."
        }
      ]
    }
  ]
}

Resolve:

• Auto → DENYLIST = [], let kei-spawn apply its role defaults. Most common path.
• Explicit → follow up: Enter deny globs (comma- or newline-separated). Validate via 3.c rules. DENYLIST = [ "<user globs>" ]. kei-spawn will UNION these with the role defaults (not replace).
• None (override auto) → if ROLE ∈ {edit-local, edit-shared} BLOCK and loop back. Otherwise set a marker DENYLIST_OVERRIDE = true; Phase 4 will pass --no-default-deny to kei-spawn. Warn the user that this disables the secrets/** and .env safety nets.

---

3.e — Verify criterion

• WHITELIST is a non-empty list (length ≥ 1).
• Every pattern passes 3.c validation.
• DENYLIST resolved (may be empty list — Auto path).
• If ROLE is edit-* and WHITELIST == [ "**" ], REJECT and loop to 3.a.

Emit confirmation:

Scope locked: <N> whitelist globs, deny=<auto|explicit:N|override>

Proceed to Phase 4.

---

3.f — Failure paths (NO DOWNGRADE)

If the user cannot choose a preset and Custom produces invalid globs twice:

• (A) Offer to inspect the current repo with rg --files | head -50 and propose 2-3 concrete whitelists based on what's actually there.
• (B) Suggest downgrading ROLE from edit-shared to explorer — explorer accepts [ "**" ] and still reads everything, without write risk.
• (C) Abort this invocation and ask the user to run /spawn-agent again once the target files are clearer.