FN-7911: add workflow validate dry-run command, tool, and API route

Adds a non-mutating `fn workflow validate` dry-run path across CLI, agent tools, and dashboard API so custom workflow IR can be checked before create/update.

- Add `packages/cli/src/commands/workflow.ts` implementing `fn workflow validate <id> | --file <path>` with JSON/text output, wired into `bin.ts`.
- Add `fn_workflow_validate` agent tool (`agent-tools.ts`, `index.ts`) reusing the existing parseWorkflowIr/trait/code-node/column-agent validation used by create/update, performing no persistence.
- Add `POST /api/workflows/validate` route in `register-workflow-routes.ts` plus dashboard route test coverage.
- Extend heartbeat tool-gating/exposure tests and gating classifications to include `fn_workflow_validate` alongside the other workflow tools.
- Update CLI/agent extension docs (`docs/cli-reference.md`, `docs/agents.md`, `docs/workflow-steps.md`, fusion skill references) to document the new command/tool.
- Add changeset `.changeset/fn-7911-workflow-validate.md` (minor) describing the new capability.

Files changed:
 .changeset/fn-7911-workflow-validate.md            |   7 ++
 docs/agents.md                                     |   5 +-
 docs/cli-reference.md                              |  13 ++
 docs/workflow-steps.md                             |   3 +-
 packages/cli/skill/fusion/SKILL.md                 |   2 +-
 .../cli/skill/fusion/references/extension-tools.md |  10 ++
 .../skill/fusion/references/fusion-capabilities.md |   1 +
 .../src/__tests__/extension-workflow-tools.test.ts |   1 +
 packages/cli/src/__tests__/extension.test.ts       |   1 +
 .../src/__tests__/workflow-docs-current.test.ts    |   1 +
 packages/cli/src/bin.ts                            |  22 ++++
 packages/cli/src/commands/workflow.ts              |  80 ++++++++++++
 packages/cli/src/extension.ts                      |  10 ++
 .../dashboard/src/__tests__/chat-manager.test.ts   |   1 +
 .../dashboard/src/__tests__/chat.rooms.test.ts     |   1 +
 .../planning-document-tools-exposure.test.ts       |   1 +
 .../__tests__/workflow-validate-route.test.ts      | 101 +++++++++++++++
 .../src/routes/register-workflow-routes.ts         |  27 +++-
 .../engine/src/__tests__/agent-action-gate.test.ts |   2 +-
 .../agent-workflow-tools-exposure.test.ts          |  70 ++++++++++-
 .../src/__tests__/gating-classifications.test.ts   |   3 +-
 .../src/__tests__/heartbeat-executor.test.ts       |  37 +++---
 .../src/__tests__/heartbeat-session-prompt.test.ts |   5 +-
 .../src/__tests__/permanent-agent-gating.test.ts   |   2 +-
 packages/engine/src/agent-heartbeat.ts             |   5 +-
 packages/engine/src/agent-tools.ts                 | 140 ++++++++++++++++++++-
 packages/engine/src/executor.ts                    |   6 +
 packages/engine/src/gating-classifications.ts      |   2 +
 packages/engine/src/index.ts                       |   4 +
 29 files changed, 532 insertions(+), 31 deletions(-)

Fusion-Task-Id: FN-7911

Fusion-Task-Lineage: 903d15fe-a7ec-458f-aa34-8f2e895a9603

Co-authored-by: Fusion (runfusion.ai) <noreply@runfusion.ai>

docs/cli-reference.md

@@ -10,6 +10,9 @@ The published CLI/pi extension must document its agent-facing workflow authoring
 
 FNXC:AgentTools 2026-06-30-09:25:
 The extension docs must list workflow selection and task-creation forwarding alongside CRUD/settings tools so operators do not assume only discovery and selection exist or that agents may reroute arbitrary tasks.
+
+FNXC:WorkflowCli 2026-07-12-00:00:
+Workflow authors need a published CLI dry-run that validates the same IR contract as create/update while performing zero persistence, so scripts can fail before attempting a save.
 -->
 
 ## Published agent extension workflow tools
@@ -17,6 +20,7 @@ The extension docs must list workflow selection and task-creation forwarding alo
 The published `@runfusion/fusion` CLI bundle also exposes the pi extension tool surface used by external agents. Alongside task and coordination helpers, agents can now author and manage workflow definitions:
 
 - `fn_workflow_list` / `fn_workflow_get` — discover built-in and custom workflows and inspect a workflow's IR before editing.
+- `fn_workflow_validate` — dry-run validate a workflow IR without creating or mutating it. It accepts an existing workflow id or inline IR through the tool surface and returns the same typed validation errors that create/update would reject.
 - `fn_workflow_create` / `fn_workflow_update` — create or revise custom workflow definitions through Fusion's central workflow validator. Built-in definitions are read-only, and broader-than-default column permission bindings require explicit policy-escalation confirmation.
 - `fn_workflow_settings` — read and write typed per-project values for a workflow's declared settings. `get` returns stored and engine-effective values; `set` validates atomically and treats `null` as deleting a stored override.
 - `fn_workflow_delete` — delete custom workflows; built-in workflows remain protected.
@@ -26,6 +30,15 @@ The published `@runfusion/fusion` CLI bundle also exposes the pi extension tool
 
 Agents should still use `fn_workflow_select` only when the user explicitly requested that workflow or when assigning a workflow to a task they created; they must not reroute arbitrary existing tasks just because another workflow appears more suitable. Prompt-injectable lanes strip workflow approval-bypass flags during `fn_workflow_create` / `fn_workflow_update`; executor-owner paths are the only authoring path that may preserve those flags.
 
+## Workflow commands
+
+```bash
+fn workflow validate <id> [--json]
+fn workflow validate --file <path> [--json]
+```
+
+`fn workflow validate` runs the server-side workflow IR dry run without creating, updating, deleting, or emitting workflow events. The command exits `0` when the IR is valid, exits non-zero for invalid IR or usage errors, and `--json` prints `{ "valid": true }` or `{ "valid": false, "errors": [...] }` for automation.
+
 ## Global Usage
 
 ```bash