Opt-in developer-controlled SwiftPM scratch root for conductor builds across worktrees

[baron]

Impact

App-managed worktrees currently accumulate independent SwiftPM .build directories. In a workflow with many worktrees, this multiplies disk usage and makes each new worktree feel cold even when the code change is small.

The build-storm mitigation work adds visibility into .build footprint, but developers still do not have a supported way to direct SwiftPM scratch/build output somewhere they control.

This issue tracks a deliberate, opt-in scratch-root policy for conductor/package/test flows.

Current behavior

• SwiftPM builds default to the checkout-local .build directory.
• Each worktree accumulates its own .build.
• Developers who want a different scratch location must hand-edit scripts or bypass conductor with raw swift build --scratch-path usage.
• RepoPrompt CE already has a partial precedent: some release/helper scripts use REPOPROMPT_SWIFTPM_SCRATCH_PATH and pass --scratch-path, but this is not a coherent developer-facing policy for normal conductor builds.
• Issue Modularize build targets so focused tests do not rebuild the monolithic RepoPrompt app target #416 tracks target modularization. That reduces what needs to build, but does not address where build products live.

Expected behavior

RepoPrompt CE should support an opt-in, developer-controlled SwiftPM scratch root for conductor-coordinated local builds.

The goal is developer control without surprising the repository or other contributors:

• no default behavior change until proven safe
• no surprise generated directories in the project root
• no requirement to edit the repository's committed .gitignore
• clear diagnostics showing which scratch path is active
• conservative keying so different branches/worktrees do not corrupt one another

Proposed model

Add or formalize an environment variable, working name:

REPOPROMPT_SWIFTPM_SCRATCH_ROOT=/path/to/cache/root

The final name should be reconciled with the existing REPOPROMPT_SWIFTPM_SCRATCH_PATH script precedent. The important distinction is:

• SCRATCH_ROOT would name a developer-controlled root directory.
• conductor would derive deterministic subdirectories under that root.
• existing exact-path behavior should either remain documented or be migrated carefully.

When unset, all flows should behave as they do today.

When set, conductor/scripts should derive scratch subdirectories keyed by at least:

• repository identity
• toolchain / Swift version
• SDK / destination
• build configuration
• checkout/worktree identity, unless testing proves broader sharing is safe

Do not blindly point divergent branches at one exact SwiftPM scratch directory unless validated.

Recommended cache placement

Documentation should recommend an off-repository user cache location, for example:

~/Library/Caches/RepoPromptCE/swiftpm-scratch/

or $XDG_CACHE_HOME on platforms where that convention applies.

This keeps project checkouts clean and avoids making developers negotiate committed ignore rules with the team.

In-repository cache placement

If a developer intentionally points the scratch root inside a Git worktree, tooling should:

1. warn clearly that the cache root is inside a Git repository
2. avoid modifying the repository's committed .gitignore
3. create or offer to create a self-contained .gitignore inside the chosen cache root, for example:

*

That makes the generated cache directory self-ignoring without polluting project-level ignore rules.

Known SwiftPM risks to validate

SwiftPM supports custom scratch/build/cache paths, but non-default scratch paths have edge cases. In particular, swiftlang/swift#59994 reports editable packages not being built correctly when --scratch-path is not .build.

RepoPrompt CE also has local/package-style dependencies, so this must be validated before recommending broad use.

This issue should explicitly test:

• local package dependencies
• editable package behavior if relevant
• package/app bundling scripts that assume .build/debug
• debug CLI installation paths
• generated workspace assumptions
• focused test flows through conductor

Non-goals

• Target modularization; see Modularize build targets so focused tests do not rebuild the monolithic RepoPrompt app target #416.
• Silent default relocation of .build.
• Sharing one exact build directory across divergent branches without proof.
• Deleting old build caches.
• Release packaging changes unless required to reconcile existing scratch-path behavior.
• Mutating the repository's committed .gitignore.

Acceptance criteria

• With no env var set, conductor/make/script build behavior is unchanged.
• With the env var set to an off-repo cache root, conductor-coordinated build/test/package flows write SwiftPM scratch output under deterministic subdirectories of that root.
• Subdirectory keying prevents accidental collisions between incompatible branches, toolchains, SDKs, or configurations.
• The effective scratch path and whether it came from default behavior or env override appears in conductor diagnostics/job summaries.
• If the configured root is inside a Git worktree, tooling warns and uses/offers a self-contained .gitignore inside the cache root rather than modifying repository-level ignore rules.
• Validation covers local/package dependencies and the known non-default --scratch-path editable-package risk.
• Existing REPOPROMPT_SWIFTPM_SCRATCH_PATH usage is documented, reconciled, or migrated so there are not two confusing scratch-path contracts.
• Developer docs explain recommended cache locations and cleanup expectations.

References

• SwiftPM custom scratch/cache path docs: https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/swiftbuild/
• Swift forum precedent for custom build paths to avoid overwriting .build: https://forums.swift.org/t/swiftpm-platform-specific-build-folders/6154
• Known --scratch-path caveat with editable packages: editable SPM packages are not built when using --scratch-path  swiftlang/swift#59994
• Git ignore behavior / local ignore rules: https://git-scm.com/docs/gitignore