GOV-2a — Checked-in agent entry docs for the two-tree repository

[aacostadiaz]

Depends on: — · Blocks: GOV-2b (#1610)

Context: A stated v1 principle is that the codebase must be comprehensible to both human developers and AI coding assistants — LLM-readable docs, skill files, and structured metadata, so contributors (human or agent) can navigate the repo and file good issues/PRs. Today the repository ships none of it: git ls-tree -r develop matches no CLAUDE.md, no AGENTS.md, no .claude/, no skill manifest. Whatever agent tooling exists on a given machine is untracked personal scratch and stays out of the tree. So the starting point is zero, not "a legacy set that needs updating", and there are no legacy-era skills to retire later — they were never committed. That has a direct cost during the whole coexistence window: --engine=legacy is the default, the frozen mace/ tree is the numerical oracle every parity ticket reads, and an agent asked to work in this repo has nothing that tells it the two-tree layout exists, that mace/** must never be reformatted, or how the capability-marked test suite selects jobs. This ticket creates that surface, against the tree as it stands, and it is the must-keep core of the agent-navigation work: it depends on nothing and unblocks GOV-2b (#1610).

Interface & constraints:

Deliverable	Shape / invariant
Root CLAUDE.md (tracked)	The repo's agent entry doc. States: the installed distribution is mace-torch and the import name is mace; all 13 console entry points declared in setup.cfg [options.entry_points] and the mace.cli.* module each maps to; the tests/ layout and the capability contract — the ten capabilities probed in tests/conftest.py (gpu, cueq, oeq, polar, les, magnetic, torchsim, schedulefree, bin_lammps, network), each a marker registered in pyproject.toml, skipped locally when absent and failed in CI when the job exported it through MACE_REQUIRE_CAPS; and the rule that a job's with: block on the .github/actions/run-tests composite action is its local reproduction recipe, because the inputs map 1:1 to pytest flags.
Frozen-tree navigation section	mace/** is the byte-frozen behavioural oracle for the rewrite: read it, never reformat it, never "clean it up" — a reformat moves the oracle. Names the directory-derived markers applied in pytest_collection_modifyitems (workflows→slow, foundations→network, benchmarks→benchmark,slow, extensions/<x>→<x>) and the vendored, lint-exempt trees (mace/tools/torch_geometric/, mace/tools/scatter.py).
User-facing skill files for the shipped CLIs, at .claude/skills/<name>/SKILL.md	Authored against the frozen mace/ surface, because that is what users run for the whole coexistence window: train (mace_run_train), evaluate (mace_eval_configs), preprocess (mace_prepare_data), convert/export (mace_create_lammps_model, mace_select_head, mace_convert_device, mace_e3nn_cueq, mace_cueq_to_e3nn), and run the test suite. Each states its capability requirements so an agent knows what will skip. The location is .claude/skills/ and not a neutral skills/ because that is where an assistant working inside this checkout discovers them.
npx skills add https://github.com/ACEsuit/mace install layout	A top-level MACE skill manifest so a third party installs the MACE skill into their own agent with one command. The manifest points at the skill files in this repo and validates offline — no network in the validation path.
tests/architecture/test_agent_repo_layout.py	The check that keeps all of the above honest, in the directory INF-3 (#1552)/INF-4 (#1553)/INF-5 (#1554) later fill with the architecture-fitness suite. It must be collected from the day it lands, and a new top-level tests/ directory is run by no existing job — the ci-core unit job selects tests/unit, the workflows job tests/workflows. So this ticket extends the ci-core unit job's tests: input (.github/workflows/ci-core.yaml, via the run-tests composite action) from tests/unit to tests/unit tests/architecture, exactly as P0-1 does for tests/golden. INF-3 (#1552)'s dedicated architecture job later takes the directory over; the extra path in the unit job costs nothing in the meantime.

Constraints:

• Personal tooling stays personal. Nothing that references a private board, a personal cluster account, or a local planning directory goes into the tree. What is committed is what a stranger cloning the repo can use.
• git add may silently refuse these files. .gitignore does not mention .claude/ at all, so the paths look addable — but a maintainer checkout can carry .claude/skills/, .claude/commands/ or .claude/hooks/ in .git/info/exclude, which is per-clone, untracked, and invisible in git status. That is why the repository has no agent files today. Confirm with git check-ignore -v .claude/skills/<name>/SKILL.md before concluding the commit landed, and assert tracked-ness in the layout test rather than file existence.
• Terminology. These files describe the repository as it is today, so they say mace / mace-torch / e3nn freely. The v1 vocabulary (--engine {legacy,v1}, MACE_ENGINE=v1, packages/, mace_core/mace_torch/mace_jax/mace_launcher, tutorials/) enters with GOV-2b (GOV-2b — Agent-friendly layout for packages/, issue automation, and a PR-review bot #1610). Say Clebsch-Gordan in prose, never bare "CG".
• No merge gating beyond the layout test. The skill manifest and entry docs are navigation aids; only test_agent_repo_layout.py is a check, and it asserts structure (files present, manifest parses, skill front-matter valid, no reference to an untracked path), never content quality.

Task:

1. Write the root CLAUDE.md: package/import names, entry points, architecture summary, the tests/ layout, the capability contract and the run-tests-inputs-are-the-recipe rule.
2. Add the frozen-tree navigation section: the never-reformat rule for mace/**, the directory-derived markers, the vendored lint-exempt trees.
3. Author the user-facing skill files for the shipped CLIs and the test suite, each declaring its capability requirements.
4. Add the top-level skill manifest so npx skills add <repo> installs the MACE skill; verify it parses and resolves the skill files with no network.
5. Add tests/architecture/test_agent_repo_layout.py asserting the entry doc, the skill files and the manifest exist, parse, and reference only tracked paths; extend the ci-core unit job's tests: input to tests/unit tests/architecture so it is collected on every PR.

Out of scope: anything describing packages/ — the per-package entry docs, the new-stack dev skills, the issue-template LLM prompt, the issue automation and the PR-review bot are all GOV-2b (#1610). CONTRIBUTING.md and GOVERNANCE.md — GOV-1 (#1609). The v0.x→v1 migration skill file — REL-1 (#1603). The tutorials/ educational implementation — EDU-1 (#1607)/EDU-2 (#1608).

Acceptance criteria:

• A tracked root CLAUDE.md exists and states the import/distribution names, the entry points, the tests/ layout, all ten capabilities and the MACE_REQUIRE_CAPS skip-or-fail contract, and that a job's run-tests inputs are its local reproduction recipe.
• It carries the frozen-tree section: mace/** is read-only-for-shape (never reformatted), with the directory-derived markers and the vendored lint-exempt trees named.
• User-facing skill files exist at .claude/skills/<name>/SKILL.md for train / eval / preprocess / convert-export / test, each declaring its capability requirements, and git ls-files lists every one of them.
• npx skills add <repo> resolves the top-level manifest and installs the MACE skill; the manifest validates offline.
• tests/architecture/test_agent_repo_layout.py exists, is collected by the ci-core unit job (whose tests: input now reads tests/unit tests/architecture), and fails if an entry doc, skill file or manifest is missing, unparseable, or points at an untracked path.
• Nothing committed references a private board, a personal account, or an untracked directory.

Verify:

# the entry doc and every skill file are TRACKED, not merely present
git ls-files CLAUDE.md .claude/skills | grep -c 'SKILL.md\|CLAUDE.md'
git check-ignore -v CLAUDE.md .claude/skills || echo "not excluded: OK"
python -m pytest tests/architecture/test_agent_repo_layout.py -v
# every repo path a skill file or the entry doc names is tracked
python - <<'PY'
import re, subprocess, pathlib
tracked = set(subprocess.run(["git", "ls-files"], capture_output=True, text=True).stdout.split())
docs = [pathlib.Path("CLAUDE.md"), *pathlib.Path(".claude/skills").rglob("SKILL.md")]
bad = [
    (str(f), m)
    for f in docs
    for m in re.findall(r"`([\w./-]+\.(?:py|md|yaml|yml|cfg|toml|sh))`", f.read_text())
    if m not in tracked
]
assert not bad, bad
print("paths tracked: OK")
PY
pre-commit run --all-files

Review focus: that a stranger's agent could navigate this repo from these files alone, that the frozen-tree rule is stated strongly enough that an assistant will not "tidy" mace/**, and that no personal or untracked tooling leaked into the tree.

---