docs(cli): unify/clarify list-merge semantics (--paths-from union vs manifest replace)

[dekobon]

Decided (2026-06-05): semantic split — targets (paths/include) replace the manifest, excludes (exclude/check_exclude) accumulate; --x/--x-from union; --no-config escape hatch. Add --output/-o to strip-comments. Now a behavior change (2.0), not docs-only. See the resolved-decisions comment.

Summary

Two different list-merge mental models coexist in the CLI/manifest surface, and
they are not documented in one place. This is a behavior-contract clarification;
any change to the merge rule itself is breaking → 2.0.

Evidence

• --paths-from doc: "Combined as a union with any --paths values"
  (big-code-analysis-cli/src/lib.rs:243); --exclude-from likewise "unioned"
  (lib.rs:253).
• Manifest list keys are CLI-replaces-manifest: paths / include /
  exclude / check_exclude (manifest.rs:239, manifest.rs:313; "an explicit
  --check-exclude replaces the bca.toml list", lib.rs:706).

So -from files union with their sibling flag, but a manifest list is replaced
by any CLI value. A user reasonably expects --paths + bca.toml paths to also
union. (See memory: "Manifest keys are CLI-replaces-manifest, not union".)

Secondary

strip-comments has no --output/-o; its only sink toggle is --in-place
(lib.rs:447), a bespoke idiom vs the "--output, stdout if omitted" pattern
used everywhere else. Likely keep --in-place (correct verb for multi-file
rewrite) but document the routing exception.

Proposed change

1. Document the merge rule explicitly in one place: "-from flags union with
   their sibling flag; manifest list keys are replaced by any CLI value."
2. Decide at 2.0 whether to keep the split or make manifest list-keys union too
   (the behavior change is breaking).
3. Document strip-comments's --in-place-only routing as a deliberate
   exception.

Acceptance

• One authoritative description of list-merge semantics in the CLI docs /
  STABILITY.md.

Part of the pre-2.0 review (#505).

Resolution

Implemented on fix/issue-539 (commit 7592467), 2.0 line.

Semantic split by list meaning (#539):

• Positive scope keys (paths, include): explicit CLI value
  REPLACES the manifest (unchanged — if x.is_empty() fallback kept).
• Negative filter keys (exclude, [check] exclude): CLI values now
  UNION with the manifest list (changed; previously CLI replaced).
  Dedup preserves order, CLI patterns first.
• --x / --x-from continue to union with each other.
• --no-config still bypasses the manifest entirely.

strip-comments --output/-o added for single-file output
routing (stdout when omitted); --in-place still drives multi-file
rewrites; the two are mutually exclusive (clap conflicts_with).

Docs updated in one authoritative place: STABILITY.md (new
"CLI / manifest list-merge semantics" section), the book
(local-gates.md, check.md, exporting-data.md), and the
--exclude / --check-exclude / strip-comments flag help. Man
pages regenerated.

[dekobon]

Resolved decisions (2026-06-05)

Optimizing for UX over back-compat. This is now a behavior change, not a
docs-only clarification — reclassifying toward enhancement and keeping it on
the 2.0 milestone (the exclude-union change in particular alters current
behavior).

Merge model → semantic split by list meaning:

• Positive scope (paths, include): explicit CLI value REPLACES the
  manifest. Pointing bca at something means that thing — bca check one.rs
  with a configured paths=["src"] checks just one.rs, not src too.
• Negative filters (exclude, check_exclude): CLI values ADD to the
  manifest's (union). You never silently un-exclude a dir the project config
  deliberately skipped (e.g. vendor/).
• --x and --x-from always union with each other (same level).
• --no-config stays the escape hatch to ignore the manifest entirely.

This mirrors ruff/ESLint's exclude (replace) vs extend-exclude (add)
distinction, generalized to all four keys. Document the rule in one place
(CLI docs + STABILITY.md) once implemented.

strip-comments → add --output/-o, keep --in-place. Single-file
strip-comments gains the universal "-o or stdout" routing; --in-place stays
for multi-file rewrites. One consistent output-routing model across the CLI.

Supersedes the previous CLI-replaces-manifest-for-all-list-keys behavior for the
exclude keys; cross-reference the manifest loader (if args.x.is_empty()
fallback) — excludes change to a merge, targets keep the replace.

[dekobon]

Implemented on fix/issue-539 (commit 7592467).

Root cause / change. The manifest loader resolved every list key
with the same if x.is_empty() CLI-replaces-manifest fallback. That
is correct for positive scope keys but wrong for negative filter
keys: a CLI --exclude/--check-exclude silently discarded the
project's manifest exemptions, so a one-off command-line filter could
un-exclude a directory (vendor/) the project deliberately skipped.

Resolution splits the merge by list meaning:

• paths / include — REPLACE on any CLI value (unchanged).
• exclude / [check] exclude — UNION CLI + manifest, dedup
  preserving order (CLI first). New extend_dedup helper in
  manifest.rs; applied in merge_globals, merge_check,
  merge_exemptions.
• --no-config short-circuits (manifest never consulted).

strip-comments gained --output/-o (single-file sink; stdout
when omitted), threaded through Action::StripComments →
CommentRmCfg.output. Mutually exclusive with --in-place via clap
conflicts_with.

Tests.

• merge_globals_unions_exclude_with_manifest,
  merge_globals_exclude_union_dedups,
  merge_globals_include_replaces_not_unions (unit).
• cli_check_exclude_unions_with_manifest_table (rewritten from the
  old replace-asserting test — now fails under the old behaviour),
  no_config_drops_manifest_check_exclude_from_union (integration).
• strip_comments_output_flag_writes_to_file,
  strip_comments_output_conflicts_with_in_place (integration).

Docs: STABILITY.md, book (local-gates / check / exporting-data),
flag help. Man pages regenerated.

Validation: cargo fmt --check, clippy -D warnings,
test --workspace --all-features, and cargo xtask +
git diff --exit-code -- man/ all clean.