Skip to content

Remote includes: resolve git-source references/includes (cache-as-pin, offline) #26

Description

@no0dles

What to build

Implement resolution of a remote references/includes entry from a git repository (per the syntax settled in the naming slice #20), in addition to the existing local-path form (which resolves exactly as today — additive). A reference may use a mutable ref (branch or tag) or an immutable commit SHA, with an optional subpath. The first resolution fetches the repo at the ref and caches it locally; subsequent runs use the cached copy without re-fetching, including offline — the cache, not a lockfile or in-manifest SHA, is the pin. A remote file's own relative references/includes and paths resolve within that same repo at that same commit (git clone-at-ref makes this trivial). Resolution executes nothing — a remote file contributes task/service/cache/env definitions only; commands run only when a task is invoked. Credentials for private repos reuse standard git credential helpers (no new secret surface). There is no HTTP transport and no lockfile (ADR-0004). Errors clearly name the repo, ref, and failure cause; an unreachable repo/ref that is not cached is a clear error with no silent fallback, while an unreachable ref that is cached uses the cache (offline path). A commit-SHA ref pins exact content reproducibly across machines; a branch/tag is frozen only in the per-machine cache (documented drift trade-off). Integration tests exercise a real git repo.

References: specs/remote-includes/spec.md (US1, US2, US4, FR-001–003, 005–010); docs/adr/0004.

Acceptance criteria

  • A references entry pointing at a git repo + ref + subpath resolves and runs that file's task from the remote definition (SC-001).
  • An existing local-path references/includes entry resolves exactly as today (SC-005).
  • After one online resolution, the same build resolves and runs offline from cache with identical content (SC-002).
  • A remote file's own relative references/includes and paths resolve within the same repo at the same commit.
  • A commit-SHA ref yields identical content on two machines regardless of cache state (SC-004).
  • Resolution executes no task or command; private-repo credentials use standard git helpers.
  • An uncached, unreachable repo/ref is a clear error naming repo + ref; no HTTP transport and no lockfile exist.

Blocked by

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readyReady for an AFK agent to grab and implement

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions