feat: add specify workflow definition for run-scoped definitions

[markuswondrak]

Description

Closes #4792.

Adds specify workflow definition <run_id> --json, a read-only command that
returns the workflow definition a run was started with. It reads only the
persisted run snapshot and frozen definitions for workflow calls that were
actually bound during execution, so output does not drift after installed
workflows are edited, overlaid, or removed.

• definition is the persisted, overlay-composed root definition, passed
  through without filling defaults or restructuring fields.
• workflow_scopes is always present and contains each bound workflow call's
  scope_path, workflow ID, and frozen definition. Its paths and workflow IDs
  match workflow status --json.
• RunState.definition_path, load_definition(), and
  load_workflow_scopes() make the snapshot read surface explicit; resume and
  definition share the same persisted snapshot path.
• --json is required. Successful output is one JSON object on stdout; errors
  are one {"error": ...} object on stderr.
• Strict JSON output stringifies YAML-native values, non-string mapping keys,
  and non-finite floats, and rejects recursive YAML aliases with the same
  strict JSON error contract.

Decisions that diverge from the original issue

• Output mirrors the persisted workflow structure rather than defining a new,
  normalized definition model. schema_version therefore versions the exposed
  definition shape; the JSON envelope is additive-only. This avoids partially
  applying engine defaults and preserves the definition that was executed.
• The command is JSON-only for now. It requires --json and exits 2 without it;
  a human text renderer is intentionally deferred rather than introducing a
  second output contract.
• A composed run includes only definitions that are already bound in its
  execution tree. Unreached calls are not resolved from current installed
  workflows, because doing so would reintroduce definition drift.
• The root definition remains authored: call steps are not expanded inline.
  Frozen callees appear separately in workflow_scopes, which also supports a
  call invoked more than once through loops or fan-out.
• Errors follow the established artifact strict-JSON contract, including
  project-resolution and unsafe-workflow-storage failures. workflow status --json intentionally retains its existing Rich error rendering.

Follow-ups

• [Bug]: Harden persisted workflow run artifact access against symlinks #4914 will harden persisted workflow-run artifact access at the shared
  storage boundary. The symlink concern predates this command: resume already
  reads the same persisted snapshot and run-state loading reads sibling files.
  A command-local check would leave those consumers inconsistent.
• [Feature]: Add explicit MCP inventory parity for workflow CLI commands #4913 will establish a complete workflow-hierarchy MCP inventory and parity
  coverage. A workflow.definition-only disposition would leave every existing
  workflow leaf unaccounted for.

Testing

• Ran focused workflow, overlay, preset, extension, and engine tests:
  1996 passed, 1 skipped.
• Ran uvx ruff@0.15.0 check src tests.
• Ran git diff --check.
• Ran the primary workflow suites again: 850 passed.
• Ran tests/specify_cli/workflows/test_command_definition.py: 36 passed,
  including recursive YAML alias rejection.
• Manually tested the working-tree CLI in /tmp/test-workflow-run-definition:
  initialized a project, ran root and composed paused workflows, verified the
  persisted snapshot and JSON envelope, checked workflow_scopes parity with
  status --json, exercised required-flag and unknown-run errors, and confirmed
  unchanged output after editing then removing the installed child workflow.

The full suite was attempted twice. Both runs showed the known pre-existing
failure tests/integration/test_preset_update_workflow.py::test_preset_update_cli_contract,
which expects an older Typer missing-argument string; the isolated test still
fails unchanged. The second full run continued cleanly through 83% before the
available execution timeout.

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (fill in the disclosure below)

AI disclosure: Implemented and updated with OpenCode using gpt-5.6-terra
(github-copilot/gpt-5.6-terra) in autonomous mode with default reasoning.
The agent generated implementation, tests, documentation, follow-up issues, and
review responses from the reviewed issue plan and review decisions, and ran the
listed automated and manual checks. No claim of human line-by-line review is
made.

[Copilot]

🟡 Changes recommended

Symlink traversal, recursive YAML handling, and missing MCP inventory coverage remain unresolved.

3 open findings

• Reject symlinked run directories and workflow files · New
• Guard plain_json against recursive YAML structures · New
• Add MCP inventory disposition for workflow.definition · New

What changed in this PR

Adds run-scoped workflow definition retrieval using persisted snapshots and frozen called-workflow definitions.

Changes:

• Adds the JSON-only workflow definition command and documentation.
• Exposes persisted definitions and bound workflow scopes through RunState.
• Adds extensive command, persistence, composition, and error tests.

File	Description
src/​specify_cli/​workflows/​command_definition.py	Implements the new command.
src/​specify_cli/​workflows/​engine.py	Adds snapshot and scope-loading APIs.
src/​specify_cli/​workflows/​_execution.py	Shares bound-scope traversal.
src/​specify_cli/​workflows/​_commands.py	Adds registration and JSON conversion.
src/​specify_cli/​workflows/​command_status.py	Reuses run-state loading.
src/​specify_cli/​_installed_list_json.py	Generalizes strict JSON helpers.
tests/​specify_cli/​workflows/​test_command_definition.py	Tests the command contract.
tests/​test_workflows.py	Tests snapshot persistence APIs.
docs/​reference/​workflows.md	Documents usage and output.

🧠 Review effort: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[markuswondrak]

Manual validation completed after opening this PR. Using the working-tree CLI in a disposable initialized project, I verified root and composed paused runs, persisted snapshots, definition/status scope parity, required-flag and unknown-run errors, and stable definition output after editing and removing the installed child workflow.

AI disclosure: Posted by Markus Wondrak with OpenCode (github-copilot/gpt-5.6-terra), default reasoning, autonomous mode; the agent performed and summarized the manual CLI validation.

[markuswondrak]

Review update for commit 57b4136:

• Fixed the recursive YAML-alias finding. Strict workflow JSON conversion now rejects cyclic mappings, lists, and tuples, while allowing non-recursive aliases reused across separate branches. workflow definition --json reports this through its single JSON stderr error envelope.
• Added a command-level regression test covering snapshot persistence of a recursive YAML alias and the strict error contract.
• Deferred the broader persisted-run symlink hardening to [Bug]: Harden persisted workflow run artifact access against symlinks #4914 and the complete workflow MCP inventory/parity work to [Feature]: Add explicit MCP inventory parity for workflow CLI commands #4913; the PR description and relevant review threads link both.

Validation: 36 passed for tests/specify_cli/workflows/test_command_definition.py; 133 passed across definition, run, resume, and status command suites; Ruff and git diff --check passed.

AI disclosure: Posted by Markus Wondrak with OpenCode (github-copilot/gpt-5.6-terra), default reasoning, autonomous mode. The agent implemented the fix, tests, follow-up issues, and this review summary, and ran the stated automated checks; no claim of human line-by-line review is made.

[Copilot]

🔵 Needs a closer look

Mapping-key normalization can silently discard persisted definition data, and scope rendering introduces avoidable traversal overhead.

0 open findings

3 resolved since last review

• Reject symlinked run directories and workflow files
• Guard plain_json against recursive YAML structures
• Add MCP inventory disposition for workflow.definition

Previously missed (2)

In code that hasn't changed since last review

Stringified mapping keys can silently overwrite existing keys

src/​specify_cli/​workflows/​_commands.py:1082

Stringifying a non-string mapping key inside this comprehension can silently overwrite an existing string key. For example, YAML containing both an unquoted 2026-01-01 key (loaded as date) and a quoted "2026-01-01" key has two entries before this code and only the latter afterward, so the advertised persisted definition is returned with data missing. Normalize keys explicitly and reject collisions (with a negative test) rather than allowing the comprehension to drop an entry.

Scope rendering adds avoidable traversal and per-node memory

src/​specify_cli/​workflows/​_execution.py:368

This refactor turns scope rendering from one tree walk into two and retains an additional entry for every execution node in nodes_by_path. Since workflow trees grow with loop iterations and fan-out items and status is commonly polled, this adds avoidable O(nodes) memory and a full traversal even when there are few or no bound scopes. Iterate the nodes directly (as before), or make the shared iterator yield the node together with the path and binding.

🧠 Review effort: Balanced