Stale-surface cleanup: remove Notation/as_list/Capability.version + align pyproject/CI/CONTRIBUTING

[azaharizaman]

Summary

Implements docs/development/plans/2026-08-17-stale-surface-cleanup.md — the FIRST of the four 2026-08-17 near-term plans. Closes every stale/dead surface named by architecture-review §9 item 3, which unblocks the capability-scaffolder plan (its templates assume no as_list, no Capability.version, and [dependency-groups]-only dev deps).

Scope: 0.x-budgeted breaking changes (public-API removals) plus packaging/CI/docs alignment. No pipeline behavior changes.

Changes by sub-item

1. Notation alias + as_list() bridging removed — paxman/core/domain.py, paxman/core/__init__.py, all ten capabilities/<Name>/notation.py modules, URL/notation.py docstring, and 11 test files. Test doubles in tests/unit/test_capability.py were retyped to list[str] (not redesigned — Trap 2). ARCHITECTURE.md "Notation Bridging" rewritten to the typed-dataclass model; CONTEXT.md / HOW_TO_ADD_NEW_CAPABILITY.md as_list snippets removed.
2. Capability.version removed — ABC annotation + version = "1.0.0" on all ten capability.py modules + the matching test assertions (D4: removed, not consumed — VersionStamp.paxman_version already owns versioning).
3. ContractFactory docstring — "the five capability classes satisfy it" → "every shipped capability class satisfies it" (no hardcoded count that drifts again; review W1/W2).
4. pyproject.toml — declared readme = "README.md", PEP 639 license = "MIT" + license-files = ["LICENSE.md"] (no License :: classifier), [project.urls] (Homepage/Repository/Issues), and consolidated dev deps into [dependency-groups] dev (PEP 735) at the max floors. [project.optional-dependencies] deleted. uv.lock regenerated and committed in the same commit (D5/D6).
5. .github/workflows/ci.yml — push.branches now [main, "feature/**", "refactor/**"]; pull_request untouched, no workflow_dispatch added (D7).
6. CONTRIBUTING.md — fixed stale repo name (paxman-alternative → paxman-python), aligned setup to CI's uv sync --all-extras, removed the duplicated install block, and linked the three contributor guides under a new "Before You Write Code" section.

Guard tests (architecture-as-law)

New tests/unit/test_removed_surfaces.py locks every removal:

• Notation alias gone from paxman.core.domain and paxman.core
• no def as_list anywhere under paxman/
• Capability ABC carries no version surface (__annotations__ and vars)
• none of the ten shipped capabilities declare version (vars(cls) — Trap 8, not hasattr)

tests/unit/test_package_install.py gains a pyproject-declaration guard (license / urls / readme / dependency-groups-only dev deps).

Notes

• Pre-approved follow-up commits (approved before the plan started, so the branch carries 8 commits rather than the plan's nominal 6, and docs/development/AGENTS.md does not require the plan to be rewritten post-implementation): e783d03 (wrap a pre-existing 95-char SIUnit docstring line) and 85223f9 (drop version from two test doubles that escaped the Task 2 enumeration). End state is fully correct.
• D3 preserved: RecognizedRep.__hash__ list-defense stays — defensive core code, not part of the removed alias.
• Verification run locally: D8 residual sweeps return zero hits in source/tests/living docs; uv run pytest tests/unit/test_removed_surfaces.py tests/unit/test_package_install.py → 8 passed.

Test plan

• CI runs green on push to refactor/** (this also proves Task 5's trigger)
• uv run pytest full suite green
• uv build wheel METADATA shows license / urls / readme

[coderabbitai]

Caution

Review failed

An error occurred during the review process. Please try again later.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}