M13-P2.5: Source-summary policy and path-first UX

[shaypal5]

Planning notation

• Concrete PR sub-slice: M13-P2.5
• Parent milestone slice: M13-P2 Issue Agent experience report: repo scan footgun, value proposition gap, and improvement ideas #70/Initial user experience: useful direction, but source refresh and agent workflow need sharper primitives #72 agent-usefulness redesign
• Plan source: .agent-plan.md, README "What Comes Next", and docs/splendor_mvp_to_v1_roadmap.md

Summary

Implements the M13-P2.5 source-summary policy and path-first UX slice.

Changes:

• Make excerpt-mode generated source summaries prefer claim-bearing sections such as Core Claims, Design Implications, Product Experience Notes, and Summary before falling back to a bounded opening excerpt.
• Keep the configured generated-summary policy deterministic and read-only during ingest while preserving full extracts for copied/external/transformed sources.
• Render source-summary source sections path-first/source-file-first before canonical source IDs and include the extract policy used for the page.
• Make human CLI source displays more path-first/source-ref-first for add-source, source lookup/list, source refresh, ingest, wiki suggest/compile, and brief recent-source output.
• Allow splendor query --source, splendor wiki suggest, and splendor wiki compile to accept source IDs, titles, or readable paths while continuing to persist canonical source IDs.
• For query/suggest path aliases, exact readable paths now resolve across all known content-addressed source versions for that path until stable logical source identities exist.
• Clarify generated-state review policy in README, quickstart, schema/product docs, dogfooding guidance, and the Issue Agent experience report: repo scan footgun, value proposition gap, and improvement ideas #70 design response.
• Advance synchronized planning-state lines to M13-P2.5 with M13-P3.1 as the conservative next release-finalization/hardening sub-slice.

Validation

• /Users/shaypalachy/.local/bin/uv run pytest (500 passed)
• /Users/shaypalachy/.local/bin/uv run ruff format --check .
• /Users/shaypalachy/.local/bin/uv run ruff check .
• /Users/shaypalachy/.local/bin/uv run splendor lint

Note: uv was not on the shell PATH in this Codex session, so validation used the installed binary at /Users/shaypalachy/.local/bin/uv.

Follow-ups intentionally deferred

• Stable logical source identities
• Supersedes/superseded_by source lifecycle semantics
• Pruning old generated state
• Full workspace refresh command
• splendor pr-summary

Refs #70
Refs #72

[codecov]

Codecov Report

❌ Patch coverage is 80.57554% with 27 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/splendor/commands/ingest.py	75.51%	7 Missing and 5 partials ⚠️
src/splendor/commands/source.py	78.78%	6 Missing and 1 partial ⚠️
src/splendor/commands/query.py	66.66%	4 Missing and 2 partials ⚠️
src/splendor/cli.py	90.47%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[github-actions]

pr-agent-context report:

Repository focus:

- Splendor is a local-first, git-native, schema-driven knowledge compiler for code-and-research
  repositories.
- Prioritize correctness, deterministic filesystem contracts, schema integrity, and CLI behavior.
- Flag regressions in repository automation and contributor workflow quality, not just Python code.
- Do not flag the `shaypal5/pr-agent-context/.github/workflows/pr-agent-context.yml@v4`
  reusable workflow reference, or the matching `tool_ref: v4`, as a supply-chain or
  reproducibility finding. This repository intentionally uses the floating stable `v4` major ref
  for `pr-agent-context` so CI and refresh runs track upstream v4 patch releases.

# Pull request 76

No unresolved review comments, failing checks, or actionable patch coverage gaps were found on PR #76 in repository https://github.com/splendor-dev/splendor. Treat this PR as all clear unless new signals appear.

Run metadata:

Tool ref: v4
Tool version: 4.0.21
Trigger: commit pushed
Workflow run: 25288542342 attempt 1
Comment timestamp: 2026-05-03T19:29:01.395185+00:00
PR head commit: 50c0be491977b838848778dde8199fe1ff6838e3