T-FFHB-pin-moon-version-in-prototools

Status: closed/done · Impact: medium · Complexity: small

Goal

The workspace .moon/workspace.yml pins versionConstraint: '>=1.41.0', but the repo declares no moon version anywhere — no .prototools, mise, or .tool-versions file. The moon that resolves on PATH here is proto’s shim pointing at 2.0.0-rc.0, which fails the constraint, so moon run <project> aborts unless the operator has separately installed a 1.41.x and put it ahead on PATH. Pin moon to a 1.41.x in repo config so the default-resolved moon drives the workspace runner out of the box, removing a host-setup footgun every contributor hits.

Today

Location	Role today
.moon/workspace.yml	declares versionConstraint: '>=1.41.0' (line 25) but nothing in the repo pins a satisfying moon
.moon/toolchain.yml	declares the bun/rust toolchains moon manages; notes 1.41.x reads the singular filename — no moon version pin lives here
package.json	root workspace manifest; pins engines.bun but has no moon version handle

There is no .prototools, mise.toml, or .tool-versions at the repo root, so whichever moon is first on PATH wins. On the migration host that was proto’s shim at 2.0.0-rc.0, which fails the >=1.41.0 constraint; moon run site:build during T-F31Q only succeeded after an explicit 1.41.8 was installed and used.

Proposed

The repo pins moon to a 1.41.x version through proto’s .prototools at the root, so a fresh checkout resolves a constraint-satisfying moon via the proto shim with no per-host setup. moon run site:build (and any other workspace task) succeeds against the default-PATH moon. The pin and the .moon/workspace.yml#versionConstraint agree: a contributor who runs proto use (or proto install) lands on the exact moon the workspace was authored against.

Approach

1. Decide the pin mechanism. Proto is already the shim provider on the dev host (~/.tools/proto/shims/moon), so a root .prototools with moon = "1.41.x" is the lowest-friction fix; it slots beside any future proto-managed tools. (If the project later standardizes on mise, the same pin moves to mise.toml — call this out but don’t build both.)
2. Add a root .prototools pinning moon to the latest 1.41.x (e.g. moon = "1.41.8", the version T-F31Q verified against). Confirm the pinned version satisfies .moon/workspace.yml#versionConstraint.
3. Run proto install (or proto use) to materialize the pinned moon, then verify moon --version reports 1.41.x with the repo root on the resolution path and moon run site:build (or another workspace task) exits zero.
4. Document the one-liner contributors run to adopt the pin (proto use) in the monorepo tooling docs if a setup section exists; otherwise note it in the README quickstart near the moon/workspace instructions.

Files to touch

Location	Kind	Change
.prototools	new	pin moon = "1.41.x" at the repo root so the proto shim resolves a constraint-satisfying moon
.moon/workspace.yml	modify	(only if the pin route is rejected) bump versionConstraint to admit the installed major instead — mutually exclusive with the pin
README.md	modify	add the proto use adoption one-liner near the workspace/moon instructions

Acceptance criteria

• AC-1: A root .prototools (or equivalent repo-tracked pin) declares a moon version in the 1.41.x line that satisfies .moon/workspace.yml#versionConstraint.
• AC-2: With the pin materialized (proto install) and the repo root on the resolution path, moon --version reports the pinned 1.41.x — not the default-shim 2.0.0-rc.0.
• AC-3: moon run site:build (or another registered workspace task) exits zero driven by the default-resolved moon, with no manually pre-installed moon ahead on PATH.

Out of scope

• Bumping the whole workspace to a moon 2.x major (and the .moon/toolchain.yml singular-vs-plural filename change that entails) — a deliberate, separate upgrade tracked against T-RVMG-adopt-moon-workspace-runner’s line.
• Standardizing the repo on mise instead of proto — pick proto here because it is already the installed shim provider; revisit only if a broader tooling decision changes that.

Dependencies

• T-RVMG-adopt-moon-workspace-runner — landed the .moon/workspace.yml versionConstraint this task pins against. Soft dependency: that config already exists on the branch, so this task can proceed independently; recorded in related: rather than depends_on:.

Discovery context

Spawned on 2026-06-19 UTC from the T-F31Q-migrate-site-to-bun post-mortem (### Friction and automation gaps, bullet 4). During the site-to-Bun migration, moon run site:build failed against the default-PATH moon (proto shim, 2.0.0-rc.0) because it violates the workspace versionConstraint: '>=1.41.0'; the AC-4 build only passed once an explicit moon 1.41.8 was installed. The repo pins no moon version anywhere, so every contributor hits this until the pin lands. This is a Local friction — the fix touches this repo’s own root config (.prototools / .moon/), not the SDLC plugin — so per the caller’s direction it rides the T-F31Q PR rather than spawning its own.

Dedup search (spawn-from-post-mortem)

Bullet: The moon on PATH is 2.0.0-rc.0, which fails the workspace’s versionConstraint: ’>=1.41.0’ (.moon/workspace.yml); moon run site:build only works with an explicitly-installed 1.41.x. The repo pins no moon version in .prototools/mise — pin moon 1.41.x (or bump the constraint) so the default-PATH moon can drive the workspace runner. Keywords searched: explicitly-installed, versionconstraint, default-path, prototools, constraint, workspace, version, runner Excluded: T-F31Q-migrate-site-to-bun Top candidates (score / status / headline):

• 24 / closed/done / T-3A6G-implement-entities-migrate — Implement /sdlc:entities-migrate to apply mechanical schema-drift fixes
• 21 / in-progress / T-RVMG-adopt-moon-workspace-runner — Adopt moon as the monorepo workspace runner; create apps/ + packages/ trees
• 20 / closed/done / T-T5RB-consolidate-task-status-enum — Consolidate task status enum and migrate existing instances
• 15 / closed/superseded / T-NUSP-run-quality-checks-logs-cwd-and-forwards-project-root — run_quality_checks.py logs cwd at start and forwards —project-root to capable verbs
• 12 / closed/done / T-TZD2-task-work-spawn-fast-path-no-op — Inline fast-path for empty post-mortem friction lists in /sdlc:task-work Decision: SPAWNED Note: top candidates are keyword-noise (entities-migrate, status-enum) or the source of the friction itself (T-RVMG sets the constraint but pins no moon version — it is the cause, not a fix). No existing task tracks pinning a moon version; spawned as a new Local follow-up.

---

← Back to Tasks