Normalize workspace directory handling for generated DevTools artifacts

[coisa]

Context

DevTools now has a global --working-dir option that changes the project root used by commands. That solves command execution from another checkout, but it does not give users a separate way to control where generated DevTools artifacts live.

Today most generated outputs still assume the default .dev-tools workspace through ManagedWorkspace constants and command defaults. That affects generated documentation, wiki output, coverage, metrics, reports, cache directories, and nested orchestrators such as standards and reports.

We should normalize this before more commands start carrying local path workarounds.

Goal

Add a single workspace-directory concept for generated DevTools artifacts, likely exposed as a global --workspace-dir option and an optional environment variable such as FAST_FORWARD_WORKSPACE_DIR.

The workspace directory should control default generated-output and cache locations without changing the project root selected by --working-dir.

Expected behavior

• --working-dir continues to define the project root where commands run.
• --workspace-dir controls DevTools-generated artifact defaults currently rooted under .dev-tools.
• Explicit command options keep precedence over the workspace directory. Examples:
  • --target
  • --coverage
  • --metrics
  • --cache-dir
  • any command-specific output path already provided by the user
• When no explicit output/cache path is provided, commands resolve defaults from the selected workspace directory.
• Nested orchestrators pass or inherit the same workspace policy consistently.
• The behavior is documented for standalone bin/dev-tools, Composer plugin usage, CI workflows, and consumer repositories.

Candidate implementation notes

• Avoid spreading string concatenation or repeated .dev-tools logic across commands.
• Prefer extending the existing ManagedWorkspace/path-resolution surface or introducing a small dedicated resolver for generated workspace paths.
• Keep command layers as orchestration. Path policy should live in a shared resolver/service.
• Preserve Composer decoupling direction: do not introduce new dependencies on composer/composer for this.
• Audit commands and configs that currently rely on .dev-tools, including:
  • docs
  • wiki
  • tests
  • metrics
  • reports
  • phpdoc
  • standards
  • Rector/ECS config helpers
  • any cache option helpers

Acceptance criteria

• A global workspace directory option is available in the DevTools Symfony application.
• Generated artifacts and cache defaults consistently honor the selected workspace directory.
• Explicit command-level paths continue to override workspace defaults.
• --working-dir and --workspace-dir are independently testable and do not conflate project-root and artifact-root behavior.
• Nested commands launched by orchestrators use the same workspace policy.
• README and Sphinx docs explain the difference between project root and workspace artifact root.
• Tests cover at least:
  • default .dev-tools behavior
  • custom workspace directory behavior
  • explicit command option precedence
  • nested/orchestrated command propagation

Non-goals

• Do not change repository source/resource lookup semantics.
• Do not move managed files such as synchronized workflows, skills, agents, or root project metadata into the workspace directory.
• Do not replace command-specific output options that users already rely on.

Metadata

No labels, milestone, project, or assignee were applied because the current repository metadata was not inspected in this session.