Normalize path-helper naming, namespace boundaries, and segment typing

[coisa]

Objective

Normalize the naming and namespace structure of path-related helpers so their intent is obvious to humans, deterministic for automation, and easier to evolve without spreading ambiguous utility classes.

Current Limitation

We currently have path-oriented helpers whose responsibilities are becoming clearer, but their naming and placement still carry structural debt:

• class names such as ProjectPaths / ProjectPathResolver are easy to understand only after reading the implementation;
• some helpers conceptually model managed workspace segments while others model repository-root paths, but that distinction is not yet consistently reflected across naming, namespace boundaries, and supporting types;
• multiple areas of the codebase still use namespace/class combinations that are "good enough" but not especially clear to humans or agents trying to infer responsibility from imports alone;
• we have started discussing whether path segments should remain constants or move to dedicated enums, but that decision has not yet been made consistently.

The result is workable code, but not yet a normalized path architecture that clearly signals:

• what belongs to managed generated workspace paths,
• what belongs to repository-root path resolution,
• and where future path-related helpers should live.

Related context: #151 is already reorganizing managed artifact paths, and #162 is extending option and path-contract consistency. This issue should capture the structural follow-up so the naming and namespace model does not remain half-evolved.

Proposed Work

Perform a focused architectural cleanup for path-related helpers and closely related utility classes.

The work should:

• settle the canonical namespace for path-resolution concerns;
• choose stable, responsibility-driven class names;
• decide whether path segments should stay as constants or move to one or more enums;
• define when a helper is a "workspace" concern versus a "project/repository path" concern;
• identify nearby classes that also suffer from namespace drift and should be regrouped when that produces a clear benefit.

Scope

• Review the path helper classes introduced or expanded during the .dev-tools path work.
• Normalize naming and namespace placement for managed-workspace vs repository-root path helpers.
• Evaluate whether path-segment constants should become enums, with a clear decision and rationale.
• Review adjacent classes that currently sit in namespaces that do not communicate responsibility well, when those cases are materially related to the same structural problem.
• Update tests, imports, docs, and any generated references affected by the rename or regrouping.

Non-goals

• Do not redesign unrelated domain layers that are not materially affected by the path-organization problem.
• Do not force a repo-wide namespace migration in one pass when the ambiguity is weak or only cosmetic.
• Do not introduce additional abstraction layers unless they materially reduce ambiguity or duplication.

Acceptance Criteria

Delivery Criteria

• Path-related helpers have a stable namespace and naming scheme that makes managed-workspace concerns and repository-root concerns easy to distinguish from imports alone.
• The implementation makes an explicit decision on constants vs enums for path segments, and applies that decision consistently in the affected path helpers.
• Any renamed or moved classes update all imports, tests, and path-related call sites.
• Documentation or agent-facing guidance is updated if the new naming/namespace scheme changes how contributors should navigate these helpers.

Architectural / Isolation Criteria

• Path resolution remains simple and discoverable instead of growing into a generic dumping ground for unrelated filesystem concerns.
• Helper classes expose responsibilities that are legible to human maintainers and to AI agents reading imports and method names without deep repository context.
• Namespace regrouping is performed only where it improves clarity, and avoids introducing extra layers that do not pay for themselves.
• Any related regrouping beyond the immediate path helpers is justified by a clear responsibility boundary rather than aesthetic preference alone.

Related Work

• Follow-up to Migrate repository-local tmp artifacts into .dev-tools #151.
• Related to Add a consistent negatable cache contract and audit other default-assumed CLI behaviors #162 because option/path contracts become easier to reason about when path helpers have stable names and boundaries.