Workspace Manifest & Resolution

[sameera]

Epic: Workspace Manifest & Resolution

Description

Nexus today assumes one repo plays every role at once: code repo, planning-queue host, and
knowledge store. Multi-repo products split those roles — code lives in member repos, knowledge
in a docs hub — and developers work in whichever repo their task lives in, not at a parent
folder. Before any pipeline stage can operate across that split, the workspace itself must be a
declared, discoverable thing: which repo is the hub, which repos are members, and where their
checkouts are expected to live.

This epic delivers that foundation. A single manifest in the hub declares the workspace. A small
pointer in each member repo locates the hub. Resolution behaves identically whether it starts
from the hub or from any member repo, reports exactly what is missing when it cannot resolve,
and falls back to today's single-repo behavior when no workspace is declared — existing
single-repo projects are untouched.

Every later multi-repo capability — close-entry migration, cross-repo distillation, Prime's
workspace state — consumes this resolution rather than re-deriving it. Getting it right once,
with sharp diagnostics, is what keeps the rest of the program frictionless for developers.

Success Metrics

• Resolution parity: from the hub or from any member checkout, workspace resolution reports
  an identical workspace description (same hub, same member set, same checkout locations).
• Diagnosability: every resolution failure mode — malformed manifest, missing hub checkout,
  missing member checkout, undeclared member — produces an error naming the artifact and the
  expected state; no generic failure messages.
• Zero regression: a repo with no workspace signals runs every nxs.* command with behavior
  unchanged from today.
• Setup cost: adding a member repo to an existing workspace touches at most two files — the
  hub manifest and the new member's pointer.

Personas

Per docs/product/context.md, with one epic-specific addition:

Persona	Role in this epic
Delivery lead (epic-specific)	Declares and maintains the workspace manifest in the hub repo

The canonical engineer persona appears here as the member-repo developer who must never need to
know the workspace's full shape to work in their own repo.

Assumptions

• The sibling-checkout convention is the only supported layout in v1: the hub and all member
  checkouts sit under one parent folder. Per-engineer checkout-path overrides are deferred.
• The manifest is committed in the hub repo; the hub pointer is committed in each member repo.
• Workspace membership changes are infrequent, lead-authored edits; no manifest-generation
  tooling is needed in this epic.
• Git is the only version-control system in scope.

Out of Scope

• Consuming workspace resolution in /nxs.close or /nxs.distill (the close-entry-migration
  and distill-multi-repo stubs).
• Prime's derived workspace state (the workspace-state-provider stub).
• Per-engineer checkout-path overrides for non-sibling layouts (re-triage via the feature
  backlog if the convention proves insufficient).
• Auto-cloning or fetching missing checkouts — resolution reports; it never mutates.

Open Questions

[sameera]

Close Record

Epic closed. Durable record below — the queue close-record.md drains post-merge.

Key Decisions

• Resolver landed as an Nx library @nexus/workspace (libs/workspace/), registered as a root devDependency. It gives the one shared resolver inferred test/typecheck/lint targets and a stable import name resolvable from skill scripts run at the repo root. Refuted: utils/workspace/ — lighter, but wired into no test project and a weaker "shared module" boundary than a named package.
• Package surface is subpath exports, no barrel (./manifest, ./remote, … direct to source; no src/index.ts), honoring the no-barrel rule. Refuted: a single . → src/index.ts entry — exactly the re-export barrel the rule forbids.
• Concrete filenames sharing one hub: block: manifest at <hub>/.nexus/config/workspace.yml, member pointer at <member>/.nexus/config/hub.yml, both reusing hub: {name, remote}. A member never also holds workspace.yml, so the two never collide. Refuted: workspace-manifest.yml / hub-pointer.yml — longer to author, no disambiguation benefit.
• Ship templates only; do NOT commit a live manifest in the Nexus repo. A live manifest would flip this single-repo tool into workspace mode once the resolver landed, breaking the zero-regression guarantee. Capability proven via tmp-dir fixtures + templates. Refuted: commit an example manifest as docs — read as real config, would break single-repo mode.
• Remote normalization sharpened to lowercase-host / preserve-path-case. DNS hosts are case-insensitive (safe to lower); some self-hosted forges are path-case-sensitive, so path case is preserved to avoid a false "same remote" match. Refuted: lowercase the whole string — risks a false duplicate on case-sensitive hosts.
• Invariant 9 (bare-name security boundary) enforced in a shared bare-name.ts. The decision record documented the guarantee but the first implementation did not enforce it — a name of ../x was joined onto the parent and followed. Fix (caught at /nxs.analyze) adds isBareSegment, imported by both manifest.ts and pointer.ts, plus an unsafe-name diagnostic; one module because the rule applies identically on both sides. Refuted: export it from manifest.ts — overloads that module with a generic path rule, weaker shared boundary.
• Parity realized as an entry-point-independent description. ResolvedWorkspace has no entry field, so hub and member results deep-equal (parity as a literal toEqual). Single-repo and a missing member checkout are both ok:true; only a missing hub, an undeclared member, or a malformed manifest are hard ok:false. A checkout holding both artifacts resolves as the hub. Refuted: an entry:"hub"|"member" field — breaks parity toEqual.

Deviation Rationale

• Member checkout identity is keyed on the expected sibling directory, not the declared git remote. The manifest declares each member's remote, but the resolver identifies a member checkout by basename / isDirectory(expectedPath) and never reads a member's git remote; only the hub's remote is verified (hub-remote-mismatch). Member remote is declared-but-unverified in v1. Why: there is no git subprocess anywhere in the tree yet — reading each member's remote would be the first, make the pure fs+YAML resolver impure, and require real git repos in fixtures instead of tmp-dirs. Over-built for an S story; the v1 layout already defines a member's name as its expected sibling directory.
• Generated coverage output is committed to the repo. libs/workspace/test-output/vitest/coverage/** (15 files, ~6,000 lines) is tracked and not gitignored — a repo-hygiene divergence that will travel to main. Recommendation: gitignore the vitest test-output/ directory and remove the tracked coverage files before the distill PR. (Flagged follow-up; close does not modify code.)

Pointers (durable)

• Deferred scope → docs/features/multi-repo-workspaces/backlog.md (no new scope deferred at close; out-of-scope items were stubbed during decomposition)
• Process lesson → docs/delivery/lessons/2026-07-12-workspace-manifest.md