feat(cli): add rooted paths-file scan selection

[mstykow]

Summary

• add --paths-file <FILE> for native scans under one explicit root, including stdin support, root-relative normalization, and structured warnings for missing entries
• tighten --include so it behaves as an explicit glob/path filter: recursive subtree selection now requires an explicit recursive pattern like src/**, while bare directory-like tokens no longer imply descendant selection
• document the split between pattern filtering and explicit rooted selection across the CLI guide, migration guide, and docs/improvements/cli-workflows.md

Issues

• Covers: cli: add --paths-file for selected-file scans under an explicit root #759; related upstream context in Allow the scans of multiple file paths and not only a single directory aboutcode-org/scancode-toolkit#1392, Combining more than 1 path in a scan does not work aboutcode-org/scancode-toolkit#1654, Allow scans from a list of file paths (likely in a file for the CLI) aboutcode-org/scancode-toolkit#2454, Allow to run scan on list of files with relative or absolute paths aboutcode-org/scancode-toolkit#3418, and Scanning multiple directories scans too much aboutcode-org/scancode-toolkit#3452
• Closes: cli: add --paths-file for selected-file scans under an explicit root #759

Scope and exclusions

• Included:
  • one explicit native scan root plus root-relative path-list input via --paths-file
  • --paths-file - stdin support
  • missing-entry warning propagation into terminal output and header warnings
  • explicit separation between --include pattern filtering and rooted path selection
  • CLI/help/docs/migration updates for the new workflow and include semantics
  • improvement-doc coverage for rooted selected-path scans and incremental rescans
• Explicit exclusions:
  • absolute paths inside --paths-file
  • true multi-root scans in one invocation
  • --paths-file support for --from-json
  • glob semantics inside --paths-file entries

Intentional differences from Python

• Provenant now has a first-class rooted path-list workflow for selected-file scans instead of relying on argv expansion or cwd-sensitive multi-input workarounds.
• Provenant now keeps a clearer split between pattern filtering and explicit rooted selection: --include is a glob/path filter, while --paths-file is the exact rooted-selection workflow.
• The current --paths-file contract is intentionally single-root and root-relative; broader absolute/multi-root support is deferred instead of being partially implemented.

Follow-up work

• Created or intentionally deferred:
  • defer absolute-entry and multi-root --paths-file support until there is evidence that single-root root-relative workflows are insufficient
  • keep replay-specific improvements such as multi-input --from-json merge semantics out of this PR because upstream already supports multi-input --from-json
  • continue tracking local contract verification for rooted selected-path scans, incremental reuse, and explicit recursive include semantics in the CLI workflow scorecard

Expected-output fixture changes

• Files changed: none
• Why the new expected output is correct: this change adds a new CLI selection mode, tightens include semantics, and updates docs only; no golden expected outputs needed to change

[mstykow]

Follow-up note on include semantics:

This branch now intentionally keeps a sharper split between pattern filtering and explicit path selection.

• --include is treated as a path/glob filter: recursion should be explicit in the pattern (for example src/foo/**), and bare directory-looking tokens like src/foo no longer imply "the whole subtree".
• --paths-file remains the explicit rooted-selection workflow: file entries mean one file, directory entries mean that subtree.

That differs from the previous Provenant behavior, where bare directory-style --include values were effectively treated as recursive subtree selectors. It also means Provenant now has a first-class rooted selected-path workflow (--paths-file) instead of forcing users to approximate that intent through --include/--ignore combinations alone.