feat(module): pin module version (version field, ?ref=, --ref)

[rickliujh]

What

A git module previously always cloned its source's default branch, so a run tracked whatever was on main at the time. This adds a way to pin a module to an exact branch, tag, or commit so runs are reproducible.

Three ways to set it, one for each place a module is named:

• Child modules — a visible version: field alongside name/source/params (the preferred form), templatable:

  modules:
    - name: networking
      source: https://github.com/org/modules.git//networking
      version: v1.4.0            # or "{{ .modVersion }}"

• CLI / root module — a short --ref flag on loom run / loom diff:

  loom run https://github.com/org/modules.git//onboard --ref v1.4.0 -p serviceName=payments

• ?ref= suffix on any git source (Terraform convention), for the root or a child source:

  loom run 'https://github.com/org/modules.git//onboard?ref=v1.4.0'

Precedence: --ref flag → version field → ?ref= suffix. Pinning a local source is an error (already fixed on disk).

How

• config.ModuleRef gains a templatable Version field, validated like other templatable fields.
• module.ResolveSource(source, version, parentDir, logger) takes an explicit version and merges it with any ?ref= suffix (explicit wins), clones in full, then checks out the ref.
• New git.Checkout — go-git ResolveRevision + checkout, with a git checkout CLI fallback (resolves refs go-git can't, e.g. remote-tracking branches). No Repository interface change.
• The executor renders modules[].version with the parent's params and passes it down.
• --ref flag added to loom run and loom diff, threaded to ResolveSource (flag beats a ?ref= suffix).

Spec & docs

• New behavioral rule M5 (Version pinning) in specs/module.md, plus updates to the child-module inputs table, source-pattern table, the T4 templatable list, the run/diff flag tables, and the execution flow.
• Guide + reference docs updated (README, module-composition, loom-yaml, cli-run, cli-diff).

Tests

• git.Checkout tag checkout (go-git and CLI paths) + unknown-ref error.
• version-field resolution, field-overrides-?ref= precedence, and local-source rejection for both spellings.
• CLI --ref pins the root source (cmd test).
• Full suite + spectrace guard green; go vet clean.

Verified end-to-end against a real repo: child version: default → v1 content; -p modVersion=v2 → v2 content; --ref v1 on the root → v1 content; --ref overrides ?ref=; bogus version → pinning module "..." to version "v9": git checkout v9: exit status 1.

🤖 Generated with Claude Code