blast-scope: Instructions file for Claude Code

blast-scope

MCP tool that intercepts shell commands from AI agents, resolves target paths against a code dependency graph, and returns a structured risk score before execution.

The goal is contextual blast radius scoring — not pattern matching on syntax, but understanding structural consequence. rm -rf ./logs on an untracked folder is different from rm -rf ./config that 8 services import at runtime.

---

what this is not

• Not a blocklist tool. We don't block commands, we score them.
• Not a replacement for Shellfirm. Complementary to it.
• Not a runtime monitor. Static analysis + filesystem state, not syscall tracing (yet).

---

project structure

blast-scope/
├── CLAUDE.md
├── pyproject.toml
├── README.md
├── src/
│   └── blast_scope/
│       ├── __init__.py
│       ├── server.py          # MCP server entrypoint
│       ├── command_parser.py  # parse shell command → structured intent
│       ├── graph_resolver.py  # resolve paths → dependency graph nodes
│       └── risk_scorer.py     # combine signals → risk score + rationale
├── tests/
│   ├── fixtures/              # real command strings to test against
│   ├── test_command_parser.py
│   ├── test_graph_resolver.py
│   └── test_risk_scorer.py
└── docs/
    └── heuristics.md          # scoring logic, documented as it evolves

---

build order

1. command_parser.py — pure functions, no dependencies, fully testable in isolation
2. server.py — MCP skeleton, single tool that calls the parser
3. vendor parser.py + graph.py from code-review-graph into src/blast_scope/vendor/crg/
4. graph_resolver.py — thin wrapper over vendored code, adds path-to-node resolution
5. risk_scorer.py — combine parser + resolver output into a score

do not skip ahead. each module should be independently useful before wiring together.

---

command parser contract

input: raw shell command string output:

{
  "command": str,           # the base command (rm, mv, chmod...)
  "targets": list[str],     # resolved absolute paths
  "flags": list[str],       # parsed flags (-rf, --force...)
  "intent": str,            # "destructive" | "additive" | "read" | "unknown"
  "recursive": bool,
  "reversible": bool        # is there a git history? is target in project tree?
}