Epic: Distill Across a Multi-Repo Workspace
Description
In a multi-repo Nexus workspace, code repos plan and close locally while a hub docs repo holds the
concept store and drains the queue. At close, each entry is migrated from its code repo to the hub
queue with its originating repo and landed SHA range stamped in. The distiller then runs from the
hub — but the code the entry describes lives in a member checkout, not beside the queue.
Today /nxs.distill still assumes the queue and the code share one repo. It derives the diff with
git in its own repo, writes anchors with a single source SHA, defaults provenance to the terse
#n home-repo form, and reports drain health for one repo only. Run from a hub, every one of those
assumptions is wrong: the diff comes out empty or wrong, anchors point at the hub instead of the
code, #n resolves to the wrong repo, and the drain report cannot see the workspace.
This epic makes the distiller workspace-aware. Each entry's diff is recomputed from its recorded
repo and range inside the correct member checkout; anchors qualify their paths by repo and stamp a
source SHA per repo; provenance defaults to the qualified <owner>/<repo>#n form; and a single hub
drain reports drain-SLO across every member repo represented in the queue. The judgment stays the
same — the distiller still maps a diff to concept deltas — only the what is now sourced correctly
across repos.
Success Metrics
- A hub drain of an entry recorded against member repo R derives a diff identical (same file/hunk
set) to git diff <base>...<head> run in R's checkout, for 100% of drainable entries.
- Every anchor file a hub drain writes carries a source SHA for each repo the concept's code is
attributed to; no listed path lacks a repo-qualified SHA.
- 100% of provenance references a hub drain emits use the qualified
<owner>/<repo>#n form; the
terse #n form never appears in a workspace drain's output.
- One hub drain's report accounts for every undrained hub-queue entry, attributed to its
originating repo, and flags each entry undrained past 30 days as a drain-SLO breach.
Personas
Per docs/product/context.md. The operator here is the Engineer adopting Nexus, running the drain
from the hub on behalf of the workspace.
Assumptions
- The workspace shape is resolved from workspace-resolution's own committed artifacts
(.nexus/config/workspace.yml = hub) — the distiller re-derives no workspace shape of its own,
matching the existing invocation-selection step in /nxs.distill.
- Each hub-queue entry carries its originating repo and SHA range in the close-record
range: list
(delivered by close-entry-migration); this epic consumes that stamp rather than recording it.
- Member checkouts are siblings resolvable via the workspace manifest; portable tooling already runs
in the hub (portable-nexus-tools).
- Drain-SLO is measured against the hub queue — the entries that have actually landed there.
Out of Scope
- Scanning member checkouts for closed-but-not-yet-migrated entries — that is migration-lag, owned
by close-entry-migration / workspace-status, not the drain-SLO report here.
- Single-repo distill behavior — diff derivation, anchors, provenance, and reporting stay unchanged
when no hub manifest is present.
- Recording the repo+range stamp at close time (close-entry-migration) and manifest/checkout
resolution itself (workspace-manifest); this epic depends on both and does not re-implement them.
Open Questions
Epic: Distill Across a Multi-Repo Workspace
Description
In a multi-repo Nexus workspace, code repos plan and close locally while a hub docs repo holds the
concept store and drains the queue. At close, each entry is migrated from its code repo to the hub
queue with its originating repo and landed SHA range stamped in. The distiller then runs from the
hub — but the code the entry describes lives in a member checkout, not beside the queue.
Today
/nxs.distillstill assumes the queue and the code share one repo. It derives the diff withgitin its own repo, writes anchors with a single source SHA, defaults provenance to the terse#nhome-repo form, and reports drain health for one repo only. Run from a hub, every one of thoseassumptions is wrong: the diff comes out empty or wrong, anchors point at the hub instead of the
code,
#nresolves to the wrong repo, and the drain report cannot see the workspace.This epic makes the distiller workspace-aware. Each entry's diff is recomputed from its recorded
repo and range inside the correct member checkout; anchors qualify their paths by repo and stamp a
source SHA per repo; provenance defaults to the qualified
<owner>/<repo>#nform; and a single hubdrain reports drain-SLO across every member repo represented in the queue. The judgment stays the
same — the distiller still maps a diff to concept deltas — only the what is now sourced correctly
across repos.
Success Metrics
set) to
git diff <base>...<head>run in R's checkout, for 100% of drainable entries.attributed to; no listed path lacks a repo-qualified SHA.
<owner>/<repo>#nform; theterse
#nform never appears in a workspace drain's output.originating repo, and flags each entry undrained past 30 days as a drain-SLO breach.
Personas
Per
docs/product/context.md. The operator here is the Engineer adopting Nexus, running the drainfrom the hub on behalf of the workspace.
Assumptions
(
.nexus/config/workspace.yml= hub) — the distiller re-derives no workspace shape of its own,matching the existing invocation-selection step in
/nxs.distill.range:list(delivered by close-entry-migration); this epic consumes that stamp rather than recording it.
in the hub (portable-nexus-tools).
Out of Scope
by close-entry-migration / workspace-status, not the drain-SLO report here.
when no hub manifest is present.
resolution itself (workspace-manifest); this epic depends on both and does not re-implement them.
Open Questions