v1.0.0 — Frozen surfaces, each with a holder

Summary: 1.0 states what the version number promises. docs/VERSIONING.md names five frozen surfaces — the CLI, the MCP tool schemas, the JSON output field sets, the guide frontmatter schema, and the PostToolUse hook stdout contract — and, for each, the test that holds it. Reaching that point meant repairing what the packaging had been claiming falsely: the Typing :: Typed classifier had shipped for 35 releases without its PEP 561 marker, no platform was declared anywhere, and four frequency: high guides reached no session at all because their only route was a catalog that measurement found unused. Nothing here changes the CLI or the MCP surface for existing callers; what changes is that those surfaces are now promises with something behind them.

Added

• docs/VERSIONING.md states what a version number promises. Five surfaces are frozen from 1.0 onward — the CLI surface, the MCP tool schemas, the JSON output field sets (additive only), the guide frontmatter schema, and the PostToolUse hook stdout contract — and each names what holds it in place, because a frozen surface nothing reads back is the failure this project already made with Typing :: Typed. Three were held already: by the design.md schema comparison, by the hook's stdout tests, and by the frontmatter parser refusing violations. The CLI surface and the MCP schemas were not, and each gained a test — command names, positionals and option names read back from build_parser(), and every tool's whole inputSchema compared against a snapshot, so a layer changing from integer to string or a limit.maximum cut from 50 to 5 fails rather than slipping past a comparison of parameter names. Three things are deliberately outside the freeze because nothing compares them today: check and detect-version JSON output, and exit-code semantics; naming them would have made the document's own claim false in its opening paragraph, and widening a freeze later is not a breaking change. maxItems is excluded for a different reason — derived from the catalog size, so freezing it would freeze the catalog — with a control test pinning the premise of that exclusion. The Python import API and the guide catalog are named as not frozen, ids included, since retrieve selects by them and a rename is a breaking change recorded here rather than made quietly. (closes #203)

Changed

• The Development Status classifier moved from 3 - Alpha to 4 - Beta, which 35 tagged releases, a four-version CI matrix and a 92% coverage gate already described; a release that self-describes as Alpha contradicts itself on its own PyPI page. A test now derives the required value from the version in pyproject.toml, so the eventual bump to 1.0 cannot land while the classifier still says Beta. Prereleases of 1.0 are exempt, since 1.0.0rc1 is where a project finds out whether it is stable and requiring the stable classifier there would force the claim ahead of the evidence. The issue asked for a line item in a v1.0 release checklist; no such checklist exists in this repository, and a test fires in the same commit as the version bump, which a checklist line can be skipped in. (closes #207)

Removed

• docs/superpowers/ and the two planning documents inside it. They were the plan and design used to file five issues on 2026-08-06; those issues were filed, implemented in #184–#189, and closed, and the spec's text is the issue bodies verbatim — #179 and its siblings carry it, so removing the drafts loses nothing the project relies on. No document in the repository referenced the directory, it never reached the wheel, and the plan opened with an instruction addressed to whatever agent read it next, which a public repository has no reason to keep offering. Recover with git log --all --full-history -- docs/superpowers/. (closes #217)

Fixed

• Four frequency: high guides now reach a session. dataclass-modern, pytest-parametrize, ruff-over-flake8, and uv-over-pip had no detector — so the hook could never surface them — and no entry in the embedded-patterns section, which left the MCP catalog as their only route, and #152 measured that route as unused. All four are now carried by the Rules file, which loads on Python files and on project config (pyproject.toml, requirements*.txt, setup.cfg, .python-version, Pipfile), so the two toolchain guides arrive exactly when their own trigger files are being edited. The always-loaded body grew from 674 to 771 tokens; that is paid on every matching edit, which is why the routes were recorded on the issue before implementation. Adding detectors was considered and rejected: the guides present frozen/slots/kw_only as decisions rather than corrections, so an automatic finding would fire on correct mutable dataclasses. Each embedded line is now checked against the wording of its own guide, after a draft recommended uv sync — a command uv-over-pip never mentions, and whose GOOD section keeps uv pip install -r requirements.txt rather than asking anyone to abandon requirements.txt. (closes #208)

• The README no longer leaves out the delivery path that actually works. Its first line offered "MCP, CLI, or Agent Skills" without naming the Rules file, and the Highlights entry said Rules auto-inject on .py file touch — both inaccurate, since Rules also load on project config and a scan of session logs found the MCP catalog essentially unused. The ordering now follows what reaches a session first, and a test ties the claim to RULE_FRONTMATTER so the prose cannot drift from the paths again. search_guides had its own version of the problem: its description told agents to search for anything outside "~5" embedded patterns and named pytest as an example, which this change made false in the same commit that moved pytest into the rules body. (closes #152)

• The Python versions the classifiers advertise are now checked, and against two different facts because they answer to two. The lowest must agree with requires-python in both directions — those two tell installers the same thing or one of them is wrong. The set must be a subset of what CI tests, in one direction only: Programming Language :: Python :: 3.14 has been in pyproject.toml since the initial scaffolding while CI gained 3.14 in #105, a PR that changed ci.yml alone, so equality would have made every commit before that one a violation and would forbid trying a Python in CI before committing to support it. Environment :: Console is checked in the same one direction: the claim requires a console script, a script does not require the claim. Reading the CI matrix needs no new dependency — the pattern is scoped to matrix: and to the test job, and it raises rather than comparing against an empty set when it cannot find the list, since that is the failure that reports agreement exactly when the check has lost its footing. The floor is derived by asking the specifier which minors it admits rather than by reading its written bounds, because >=3.11,>=3.12 has two and only the higher one is real. License classifiers are deliberately left alone: #213 proposes dropping them as deprecated under PEP 639, and a test defending something slated for removal points the wrong way. (closes #220)

• CONTRIBUTING no longer states a test count or a guide count. The suite count was stale by a factor of three, so a contributor checking their environment against it would read a third of the suite failing to collect as a healthy setup. Pinning the numbers with tests was the alternative and was rejected: the guide count already has three places checking it against the catalog, and a fourth would be the duplication #219 removed. The one number kept is the dependency audit's, which says "as of" and means it. (closes #216)

• The package ships the PEP 561 marker that its Typing :: Typed classifier has been promising since the first release. Without py.typed, mypy and pyright treat an installed package as untyped no matter how annotated its source is, so every consumer silently lost the type information the classifier advertised — and the published wheel, downloaded and inspected, contained no marker at any path. The wheel verification now asserts the marker against the installed package rather than against the checkout, since the source tree holding the file proves nothing about what was packaged; the check was falsified by hand, because it runs only in the build job where a green result would otherwise be its own first evidence. (closes #204)

• The supported platforms are stated, and mpg setup explains itself when Windows refuses to create a symlink. No platform was declared anywhere before: no Operating System classifier, no mention in README, and CI running Linux alone. Both classifiers and a README section now name the two platforms with evidence behind them — Linux from CI, macOS from development — and Windows is deliberately absent from the metadata while README states what fails there and why. os.symlink raises WinError 1314 on Windows without Developer Mode or elevation, and the bare error text read like a defect in mpg rather than a privilege the OS withholds, leaving two of the advertised delivery methods missing with no indication of what to change. The new hint is scoped to that error rather than to the platform, because Windows also raises OSError here for path lengths and read-only volumes, and answering those with a privileges setting would send the reader after a fix that does not apply. Whether to fall back to copying on Windows is left open. (closes #206)