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
Blocked by
What to build
Implement resolution of a remote
references/includesentry 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 relativereferences/includesand 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
referencesentry pointing at a git repo + ref + subpath resolves and runs that file's task from the remote definition (SC-001).references/includesentry resolves exactly as today (SC-005).references/includesand paths resolve within the same repo at the same commit.Blocked by