feat(cli): opt-in discovery of an author-shipped baseline (#278)

[rodboev]

Summary

A skill distributed with a vetted .skillspector-baseline.yaml gets no benefit from it today: skillspector scan <skill> ignores the file unless every consumer finds it and passes --baseline by hand, so consumers of distributed skills see the author's known false positives raw. Loading it automatically would be worse: a baseline shipped by the skill author is third-party configuration from the party being audited, and applying it silently would let it suppress findings, lower the risk score, and flip the non-zero-exit install gate in a consumer's scan.

This makes discovery explicit-trust: scan detects a co-located baseline and reports it, applies it only when the consumer opts in with --use-shipped-baseline, and prints provenance when it does.

Closes #278

Behavior

• No flags: a .skillspector-baseline.yaml at the top level of the scanned directory produces a stderr notice naming the file and the opt-in flag. Findings, risk score, and exit code are unchanged, and the file is never parsed; discovery is a pure existence check.
• --use-shipped-baseline: the discovered baseline goes through the same loading and validation as --baseline and is applied; a stderr provenance line records that an author-shipped baseline at that path was applied. --show-suppressed lists what it suppressed and why through the existing rendering. A malformed shipped baseline exits 2, same as an explicit one; it is never silently skipped.
• --baseline PATH always wins: discovery is skipped entirely when an explicit baseline is given, including the missing-file exit-2 path.
• All notices go to stderr, so --format json and --format sarif stdout stays machine-parseable.

Discovery is limited to the canonical .skillspector-baseline.yaml, the name skillspector baseline writes by default. .yml and .json baselines stay usable through explicit --baseline; keeping auto-discovery to one filename keeps the author-controlled trust surface small and avoids any precedence question.

Diff Notes

• src/skillspector/suppression.py: new discover_baseline() that returns the co-located .skillspector-baseline.yaml path or None without reading the file. Top level of the scanned directory only.
• src/skillspector/cli.py: --use-shipped-baseline flag on scan, a discovery gate in the single-directory path, and a stderr console for the detection notice, provenance line, and a note when opt-in is given but nothing is shipped. The discovered path flows through the existing baseline plumbing, so suppression semantics and report rendering are unchanged.
• tests/unit/test_suppression.py: discovery unit tests (canonical file, absence, non-directory input, directory-named-like-the-baseline, noncanonical .yml/.json siblings ignored, nested files ignored).
• tests/unit/test_cli.py: end-to-end tests (all --no-llm) for detect-without-apply, opt-in apply with provenance and suppressed: true entries, explicit --baseline precedence over a shipped suppress-all baseline, JSON and SARIF stdout parseability with a discovered baseline in a directory whose name has a space and a non-ASCII character, no-op opt-in when nothing canonical is shipped, --show-suppressed reason rendering, exit 2 on a malformed shipped baseline under opt-in, and an untouched recursive path.

Scope

• No load-by-default and no opt-out flag; applying third-party suppressions stays an explicit consumer decision.
• No auto-discovery of alternate filenames or repository-root traversal; only the canonical name at the scanned directory's top level.
• No change to the recursive/multi-skill path; --baseline threading there is tracked separately ([BUG] Recursive multi-skill scans silently ignore --baseline and --show-suppressed #201/fix(cli): baseline suppression in recursive multi-skill scans (#201) #205).
• No baseline schema change, no SKILL.md front-matter suppression, no report-format or MCP changes.

Verification

• uv run pytest tests/unit/test_cli.py tests/unit/test_suppression.py -q → 89 passed
• uv run ruff check src/ tests/ → All checks passed.
• uv run ruff format --check src/ tests/ → 165 files already formatted

[rng1995]

[Automated SkillSpector Review]

Approved. Shipped suppressions remain inert and unparsed by default, require explicit consumer opt-in, preserve explicit --baseline precedence, and keep machine-readable stdout clean. Provenance, malformed input, recursive behavior, and suppression semantics have adequate focused coverage.

[rng1995]

@rodboev - Please address review comments and resolve merge conflicts.

[rodboev]

Addressed the requested maintenance on this PR.

• Rebasing pr/shipped-baseline-optin onto the current main resolved the merge conflict in tests/unit/test_suppression.py while preserving both the current baseline coverage and shipped-baseline discovery coverage.
• The two control comparisons now ignore only the run-unique finding_id introduced on current main; they continue to compare the finding payload, risk score, and exit status.
• The PR body now reflects the current focused validation results.

[rng1995]

Re-review approved at the current head. The previously reviewed opt-in shipped-baseline behavior remains acceptable and there are no unresolved review threads. CI is green except for the mechanical DCO failure on the unsigned merge commit.