ADR-0025: Workspace root discovery

• Status: Amended
• Date: 2026-07-25
• Deciders: Michel Gillet
• Amended by: ADR-0026

Context

ADR-0024 defines product repo R, optional superbuild workspace W, method resolution under $W/.tools_local/esys/a2c/<ver>/, and the rule that agents must not treat $W/tools/ai-rules/ as the A2C method root.

$WORKSPACE / W is not an ambient environment variable. How to discover W from a path under R will evolve (new markers, nested superbuilds, esysrepo features). Baking the full algorithm into ADR-0024 would force churn on the write contract / path-binding ADR. Discovery therefore has its own ADR and lives in the a2c CLI (shared library), not in ad-hoc agent prompts.

Decision

1. Responsibility

• Authoritative discovery is implemented by a2c (e.g. a2c workspace path and any command that needs W).
• Agents and other tools call the CLI (or the same library API). They do not re-implement parent walks in prompts.
• This ADR defines the current algorithm. Expect amend or supersede when signals or nesting rules change (e.g. superbuild nested under another superbuild).

2. Committed vs local pointer files

Path	Role
$W/.tools/esys/a2c/workspace.yaml	Committed marker — this tree is workspace W. No workspace_root path field required.
$R/.tools_local/esys/a2c/workspace.yaml	Local pointer only — cache of the current nesting on this machine. Not committed: the same git repo R may participate in more than one superbuild.

Do not treat $W/.tools/esys/a2c/workspace.yaml as a full product adoption. kind: workspace is workspace metadata only. Write contract / adoption.yaml applies to product repos R (and to W only if W deliberately adopts A2C as a product).

Schema under $W (committed marker):

schema_version: 1
kind: workspace

Schema under $R (local pointer, gitignored):

schema_version: 1
kind: workspace_pointer
workspace_root: ../..   # relative to this file's directory → W (preferred)
# workspace_root: /abs/path/to/W   # absolute allowed (machine-local)

kind: workspace_pointer matches the “local pointer” role above (symmetry with kind: workspace at $W). Readers/writers should require the matching kind so a misplaced or copied YAML is not treated as the other role.

3. Discovery algorithm (current)

Given cwd or a path under product repo R:

1. Resolve R (git toplevel for the product being edited).
2. If $R/.tools_local/esys/a2c/workspace.yaml exists with kind: workspace_pointer → resolve workspace_root → candidate W. Validate that W still matches a first-class signal (step 3); if invalid (or wrong/missing kind), ignore the cache and continue.
3. Else walk parents of R (inclusive) and pick the nearest ancestor that matches any of these first-class workspace signals:

• .tools/esys/a2c/workspace.yaml with kind: workspace
• .repo/manifest.xml (Google repo multi-git workspace root)
• .esysrepo/ (LibESys / esysrepo workspace root)
• .tools_local/esys/repo/ (local esysrepo / repo tooling state under the workspace)

4. If a match is found → that ancestor is W.
5. Else → single-repo mode (W unset; only R installs and $R/tools/ai-rules apply — see ADR-0024 method resolution).

Nearest ancestor is the current rule for nested layouts. If esysrepo later supports superbuild-as-child-of-superbuild with a different “which W?” policy, amend or supersede this ADR — do not silently change behavior without a decision record.

4. Materialize local pointer

When discovery finds a W and $R/.tools_local/esys/a2c/workspace.yaml is missing (or was invalidated), a2c writes it with kind: workspace_pointer (prefer relative workspace_root from the pointer file’s directory to W). Superbuild sync may also write the same file; schema must match. Agents should not invent this file by hand.

5. Agent contract

Run a2c workspace path (or rely on commands that already resolve W). Do not duplicate this algorithm in prompts.

Consequences

Positive

• Discovery can evolve (nested workspaces, new markers) without reopening ADR-0024’s write-contract / path bindings.
• One implementation path keeps agents, CI, and humans aligned.
• Local $R pointer stays out of git so multi-superbuild reuse of R remains valid.

Negative

• Implementers must keep CLI behavior and this ADR in sync (amend when changing the algorithm).
• Nested-superbuild policy is intentionally deferred; “nearest” may need replacement later.

References

• ADR-0024 — R / W, method resolution, tool state roots
• ADR-0021 — Amends vs Supersede

Amends

• (none)

Amended by

• ADR-0026 — exclude user-global user_config.xml under .esysrepo/ and .tools_local/esys/repo/

Supersedes

• (none)

Superseded by

• (none)