[markshust]

Summary

• #[Command] takes a new destructive: bool = false argument (picked over a separate #[Destructive] attribute so the command's whole contract lives in one attribute and flows through the existing CommandDefinition/discovery pipeline). It is exposed as CommandDefinition::$destructive and stored in the discovery cache.
• Every shipped state-changing command is marked: db:migrate, db:reset, db:rollback, db:rebuild, db:seed, cache:clear, page-cache:clear, page-cache:purge, queue:clear, log:clear, session:gc, auth:clear-tokens, discovery:clear, indexer:rebuild, admin-auth:permissions:sync, devai:install. (db:migrate, devai:install and admin-auth:permissions:sync were already treated as destructive by MCP because they declare force; marking them keeps that.)
• MCP run_console_command reads $definition->destructive instead of looking for a force flag, so cache:clear, queue:clear, log:clear, page-cache:clear... now also need mcp.console.allow_destructive.
• --force stays the CLI confirmation mechanism. DestructiveCommandGuard itself never inferred anything from option names (it is called explicitly by each command), so its runtime behaviour is unchanged. Its docblock now requires guarded commands to carry the marker, and the repo test enforces that for shipped commands.
• New repo-level test tests/DestructiveCommandMarkerTest.php reflects every #[Command] class under packages/*/src and fails when a command named *:clear, *:reset, *:rollback, *:rebuild, *:fresh, *:seed, *:truncate, *:purge or *:clear-tokens, or one that depends on DestructiveCommandGuard, lacks the marker.
• Docs: cli (new "Destructive Commands" section), core, mcp, database.

Breaking

• MCP: an app that allowlisted a state-changing command without a force flag (e.g. cache:clear) in mcp.console.allowed_commands now gets it refused. Escape hatch: set mcp.console.allow_destructive to true (MCP_ALLOW_DESTRUCTIVE=true). That enables only destructive commands that are also allowlisted.
• Discovery cache: DiscoveryCache::CACHE_VERSION goes from 3 to 4 because command records gain a destructive field. A cache compiled by an older version fails boot with the usual version-mismatch DiscoveryCacheException. Run marko discovery:cache on deploy (already the documented step).

Test plan

• tests/DestructiveCommandMarkerTest.php: suffix rule, guard-dependency rule, and read-only commands stay unmarked (red before the commands were marked)
• RunConsoleCommandToolTest: refuses a destructive command with no force flag (cache:clear), refuses one reached through an alias, runs a force-flag command that is not marked destructive, existing allow_destructive cases
• core: attribute/definition defaults, discovery reads the marker, cache round-trips it and rejects records missing it or with a non-bool value
• composer test, composer cs:check, composer phpstan green locally

Fixes #516

🤖 Generated with Claude Code

https://claude.ai/code/session_01KyjR4cJTfro54iFZ9CWkv1