meta docs <path> unions the ancestor config's sources with the explicit path argument, so a scoped docs tree absorbs unrelated metadata

[dmealing]

Found while evaluating 0.24.0-rc.3 in an adopter project. Same underlying change as the meta gen re-rooting problem, but a different command, a different failure mode, and a different correct behaviour — so filing separately.

Summary

meta docs <path> takes an explicit positional path. In 0.24.0-rc.3 that path no longer scopes the run: the sources declared in the nearest ancestor .metaobjects/config.json are unioned in on top of it.

The explicit argument is still honoured — everything it used to emit is still emitted — but unrelated metadata trees are now added silently. A command whose whole purpose is "document this subset" quietly documents the whole repo.

Unlike the gen case this fails open, not closed: no error, exit 0, just more pages than asked for.

Observed

An adopter generates two committed documentation trees from one repo:

• a data-model tree, generated from the app directory;
• a prompt/response-contract tree, generated from an explicitly-passed scoped root (a small directory holding a symlink to one module's metadata), with --layout package.

That second command is unchanged; only the CLI version differs.

meta docs <repo-root>/<scoped-root> --out <repo-root>/docs/prompts --layout package

CLI	ancestor .metaobjects/config.json	entity pages	template pages	total
0.23.1	present	445	15	461
0.24.0-rc.3	moved aside	445	50	496
0.24.0-rc.3	present	567	57	625

Reading the table:

• 445 → 445: the explicit path is still resolved correctly. Nothing was lost — a set-diff of the page lists shows zero pages present in 0.23.1 and missing in rc.3.
• 15 → 50 template pages: expected and correct. This is ADR-0052 — the inbound half is now documented too. The module declares 15 template.output and 35 template.prompt nodes, and 15 + 35 = 50. 0.23.1 only ever documented the outbound 15.
• +122 entity / +7 template pages: the regression. These come from the other sources entries in the ancestor config — packages belonging to unrelated trees (data-model packages for identity, email, admin, and so on) appearing inside a tree that is supposed to contain only prompt contracts.

Consequence

Adopters who drift-gate their committed docs (regenerate in CI, fail on a diff) get a gate failure whose diff is 164 new files, of which ~35 are a legitimate ADR-0052 improvement and ~129 are leakage. The two are only separable by moving the ancestor config aside and regenerating — which is not something a gate can do.

There is no scoping flag to opt out: meta docs --help exposes --out, --layout, --site, but nothing that says "sources = exactly this path".

Suggested fix

An explicit positional path should define the source set, not extend it. Ancestor-config sources are the right default for a bare meta docs with no path, and the wrong thing to union into an explicitly-scoped one.

If unioning is deliberate, it needs to be opt-in (--include-config-sources) or at minimum announced on stderr — the current behaviour is invisible until someone counts pages.

Related

Same ancestor-config discovery introduced the meta gen re-rooting failure filed alongside this one (#326). A fix that makes discovery respect the invocation scope would likely address both, but the two commands need different answers: gen currently fails closed, docs fails open.

[dmealing]

Fixed on main — an explicit positional now defines the source set rather than seeding an upward walk, which is what this issue asked for. resolveCollection already had the pin ({ explicitDir }); meta docs <path> now passes it, and a bare meta docs still discovers, since that is the right default for "document the project I am standing in".

Both help blocks say so now. The old text described the argument as a project root without saying anything about what it does to the source set, which is why the union was invisible until someone counted pages.

Gated by an integration test with both arms — an explicitly-scoped run must not absorb the ancestor config's other sources, and a bare run must still discover them.