blakemere-wraptools 0.1.0__tar.gz

blakemere_wraptools-0.1.0/.external-links-ignore

@@ -0,0 +1,9 @@
+# External HTTP(S) links intentionally skipped by scripts/check_external_links.py.
+#
+# Use one fnmatch-style URL pattern per line, for example:
+# https://status.example.com/*
+#
+# Keep this file small and explain any real ignores in the commit that adds them.
+# Every real ignore pattern must be preceded by a reason comment.
+# Ignore patterns must use http:// or https:// and include a host.
+# Ignore patterns must match at least one current external docs link.

blakemere_wraptools-0.1.0/.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,30 @@
+name: Bug report
+description: Report behavior that looks incorrect.
+title: "[bug]: "
+labels: [bug]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened, and what did you expect instead?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Minimal reproduction
+      description: Include a small code sample or command sequence.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Package version
+      placeholder: pydecorators 0.1.0
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: Python 3.12

blakemere_wraptools-0.1.0/.github/ISSUE_TEMPLATE/docs-or-release-question.yml

@@ -0,0 +1,26 @@
+name: Docs or release question
+description: Ask about documentation, examples, packaging, or release checks.
+title: "[docs/release]: "
+labels: [documentation]
+body:
+  - type: textarea
+    id: question
+    attributes:
+      label: Question
+      description: What are you trying to understand or verify?
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: Link the page, command, package version, or release step involved.
+    validations:
+      required: true
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before filing
+      options:
+        - label: I checked README.md and docs/index.md.
+        - label: I included the command output or page link when relevant.

blakemere_wraptools-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,22 @@
+## Summary
+
+- 
+
+## Checks
+
+- [ ] Ran the smallest meaningful local verification gate, or explained why not.
+- [ ] Updated `TODO.md` for completed or newly discovered work.
+- [ ] Added or updated tests for behavior changes.
+
+## Documentation checks
+
+- [ ] Updated `docs/index.md` if a top-level docs page or executable example was added, removed, or renamed.
+- [ ] Updated executable docs examples and `tests/test_docs_examples.py` together when examples changed.
+- [ ] Used the `docs_policy` pytest marker for documentation policy tests.
+- [ ] Ran `./scripts/docs-policy.sh` when documentation structure, links, release docs, or examples changed.
+- [ ] Confirmed root docs that help users navigate still link to `docs/index.md`.
+
+## Release-impact checks
+
+- [ ] Updated `RELEASE.md` if release gates, publishing flow, package metadata, or persistent cache compatibility changed.
+- [ ] Confirmed no secrets, tokens, built distributions, local virtualenvs, or cache databases are included.

blakemere_wraptools-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  docs-policy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install package
+        run: python -m pip install -e '.[dev]'
+      - name: Documentation policy tests
+        run: ./scripts/docs-policy.sh
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: python -m pip install -e '.[dev]'
+      - name: Pre-commit hooks
+        run: pre-commit run --all-files --show-diff-on-failure
+      - name: Ruff lint
+        run: ruff check .
+      - name: Ruff format check
+        run: ruff format --check .
+      - name: Mypy
+        run: mypy
+      - name: Import smoke test
+        run: python scripts/smoke_imports.py
+      - name: Examples smoke test
+        run: python scripts/smoke_examples.py
+      - name: Tests
+        run: pytest
+      - name: Coverage summary
+        run: python scripts/coverage_summary.py >> "$GITHUB_STEP_SUMMARY"
+      - name: Upload coverage XML
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: coverage.xml
+          if-no-files-found: error
+      - name: Build package
+        run: python -m build
+      - name: Wheel install smoke test
+        run: python scripts/smoke_wheel_install.py
+      - name: Dogfood wheel scenarios
+        run: python scripts/dogfood_local_wheel.py
+      - name: External project dogfood
+        run: python scripts/dogfood_external_project.py

blakemere_wraptools-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,112 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Package index target"
+        required: true
+        default: "testpypi"
+        type: choice
+        options:
+          - testpypi
+          - pypi
+      version:
+        description: "Expected package version, for example 0.1.0"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and verify distributions
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install package
+        run: python -m pip install -e '.[dev]'
+      - name: Verify requested version matches package metadata
+        id: version
+        shell: bash
+        run: |
+          actual="$(python -c "import tomllib; from pathlib import Path; print(tomllib.loads(Path('pyproject.toml').read_text())['project']['version'])")"
+          echo "version=${actual}" >> "$GITHUB_OUTPUT"
+          if [ "$actual" != "${{ inputs.version }}" ]; then
+            echo "Requested version ${{ inputs.version }} does not match pyproject.toml version ${actual}" >&2
+            exit 1
+          fi
+      - name: Docs policy
+        run: ./scripts/docs-policy.sh
+      - name: Ruff lint
+        run: ruff check .
+      - name: Ruff format check
+        run: ruff format --check .
+      - name: Mypy
+        run: mypy
+      - name: Import smoke test
+        run: python scripts/smoke_imports.py
+      - name: Examples smoke test
+        run: python scripts/smoke_examples.py
+      - name: Tests
+        run: pytest
+      - name: Build package
+        run: python -m build
+      - name: Twine check
+        run: python -m twine check dist/*
+      - name: Wheel install smoke test
+        run: python scripts/smoke_wheel_install.py
+      - name: Dogfood wheel scenarios
+        run: python scripts/dogfood_local_wheel.py
+      - name: External project dogfood
+        run: python scripts/dogfood_external_project.py
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/*
+          if-no-files-found: error
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    if: ${{ inputs.target == 'testpypi' }}
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    if: ${{ inputs.target == 'pypi' }}
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

blakemere_wraptools-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Virtual environments
+.venv/
+venv/
+
+# Editors and OS junk
+.DS_Store
+.idea/
+.vscode/

blakemere_wraptools-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.10
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.14.1
+    hooks:
+      - id: mypy
+        pass_filenames: false
+        additional_dependencies:
+          - pytest>=8.3
+          - pytest-asyncio>=0.25
+          - pytest-cov>=6.0

blakemere_wraptools-0.1.0/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project intends to follow semantic versioning once public releases begin.
+
+## [Unreleased]
+
+### Added
+
+- Aggregate timestamp diagnostic guidance for future disk-cache inspection reports.
+- Inspection report retention/deletion guidance for future disk-cache support artifacts.
+- Inspection sensitivity-warning design guidance for future disk-cache support tooling.
+- Inspection CLI safe-default design guidance for future disk-cache tooling.
+- Aggregate-only disk-cache inspection report design guidance for future support bundles.
+- Support-bundle metadata sensitivity guidance for no-preview disk-cache inspection reports.
+- No-preview support bundle/CI guidance for future disk-cache inspection tooling.
+- `preview_redactor` callback design guidance for future disk-cache inspection previews.
+- Payload preview redaction guidance for future disk-cache inspection tooling.
+- Bounded payload preview policy guidance for future disk-cache inspection APIs.
+- Disk-cache schema metadata table design guidance for future file-compatibility promises.
+- Supported cache-inspection API design guidance for future disk-cache tooling.
+- SQLite column-stability guidance for disk-cache debugging versus internal implementation details.
+- SQLite inspection example for JSON disk-cache rows.
+- Executable datetime/bytes JSON serializer adapter recipe for disk cache payloads.
+- Opt-in `coalesce_misses=True` request coalescing for duplicate concurrent cache misses.
+- Request coalescing design guidance for duplicate concurrent cache misses.
+- Opt-in `refresh_ttl_on_hit` sliding TTL behavior for memory and disk cache backends.
+- Disk cache integrity-check and maintenance helper design guidance.
+- `DiskCacheBackend(on_drop=...)` diagnostics for rows dropped because of serializer mismatches or corrupt payloads.
+- `JsonCacheSerializer` for simple JSON-compatible persistent cache payloads.
+- README Python code-block extraction and sync policy tests.
+- Release checklist guidance for persistent disk-cache migration and clearing.
+- `DiskCacheBackend` cache versioning and schema-change guidance.
+- `DiskCacheBackend` namespace/key stability documentation.
+- `DiskCacheBackend` persistence documentation example coverage.
+- Stale ignore-pattern validation for the optional external documentation link checker.
+- HTTP(S) URL-shape validation for external link ignore patterns.
+- Reason-comment validation for external link ignore patterns.
+- Verbose reporting for checked and ignored external documentation links.
+- Ignore-file support for the optional external documentation link checker.
+- Retry/backoff support for the optional external documentation link checker.
+- Opt-in external documentation link checker.
+- External HTTP(S) documentation link syntax policy.
+- Duplicate Markdown heading anchor handling.
+- Contributor guidance for documentation index inclusion.
+- README core documentation link policy.
+- Shared documentation policy helper module.
+- Contributor checklist for documentation file updates.
+- Contributor guidance for documentation policy test markers.
+- Pytest marker for documentation policy checks.
+- Dedicated documentation policy test module.
+- Pre-release docs policy script.
+- Release documentation maintenance checklist section.
+- Root documentation index-linking policy documentation.
+- Root docs documentation-index mention policy test.
+- Root documentation local Markdown link validation.
+- All-docs local Markdown link and anchor validation.
+- Local Markdown anchor validation for docs index links.
+- Docs index executable example conventions link policy test.
+- Docs example filename convention policy test.
+- Executable docs example naming conventions.
+- Docs example public-function assertion policy test.
+- Docs example execution coverage policy test.
+- Docs examples index coverage policy test.
+- Docs index coverage policy test for top-level documentation pages.
+- Docs index link validation policy test.
+- Documentation index page linking core API, exception, cache, backend, and example docs.
+- Centralized public exceptions reference page.
+- Public exception executable examples for configuration, key, and serialization errors.
+- Public exception inheritance documentation policy test.
+- Public exception docs policy test.
+- `CacheBackendClosedError` public docs and executable example coverage.
+- `CacheBackendClosedError` README warning for context-managed decorator-bound disk backends.
+- Regression coverage for decorator-bound closed `DiskCacheBackend` usage.
+- `DiskCacheBackend` context-manager documentation example and executable coverage.
+- Executable `DiskCacheBackend` documentation example coverage.
+- `DiskCacheBackend` README lifecycle guidance showing explicit `close()` cleanup.
+- `DiskCacheBackend` README usage example.
+- README guidance for `DiskCacheBackend` concurrency and single-host expectations.
+- `DiskCacheBackend` SQLite WAL/busy-timeout tuning options and tests.
+- `DiskCacheBackend` treats corrupt disk cache payloads as misses and drops the bad row.
+- Reusable cache backend conformance tests for memory and disk backend behavior.
+- `DiskCacheBackend` cache operations, persistence, TTL/LRU behavior, serializer mismatch handling, and closed-backend errors.
+- `DiskCacheBackend` key and payload serialization helpers.
+- `DiskCacheBackend` SQLite schema initialization and constructor tests.
+- `DiskCacheBackend` SQLite storage strategy design.
+- `CacheSerializer` protocol and `PickleCacheSerializer` default implementation.
+- `@cache_result` backend sharing semantics and `namespace=` isolation.
+- `CacheBackend` protocol and `backend=` parameter for `@cache_result`.
+- `MemoryCacheBackend` refactor as the default storage backend for `@cache_result`.
+- `@cache_result` TTL expiry, LRU maxsize eviction, and sync mutation thread-safety coverage.
+- `@cache_result` hardening tests for exception caching, lock behavior, and key canonicalization policy.
+- Sync-core `@cache_result` implementation with key generation, stats, clear, and async rejection.
+- `CacheInfo` and `CacheKeyError` support types for planned `@cache_result`.
+- `@cache_result` API design and implementation strategy.
+- Release checklist for repeatable package publishing.
+- Public API policy, contributor checklist, version consistency check, and executable docs examples.
+- `@deprecated` decorator with sync and async support.
+- Initial project packaging foundation.
+- Empty typed `pydecorators` package.
+- Import smoke test.
+- API design notes and shared internal decorator helpers.
+- Public exception hierarchy.

blakemere_wraptools-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,163 @@
+# Contributing
+
+## Documentation style
+
+Use `/home/skippy/.openclaw/workspace/WRITING_STYLE.md` as the project writing style when adding or revising documentation.
+
+The short version: write like a capable human who understands the system and is trying to be useful. Start with the point. Define fuzzy terms. Name the trade-off. Explain the practical consequence. Prefer concrete examples over vague reassurance.
+
+Good documentation for this project should be:
+
+- direct, specific, and edited
+- technically credible without sounding academic for sport
+- honest about limits, failure modes, and operating constraints
+- willing to say what not to do
+- dry when the joke helps, not when the reader needs sober warning
+
+Avoid vendor fog and AI filler. If a sentence could survive unchanged in a generic product whitepaper, make it confess what it actually means or delete it.
+
+## Adding a new decorator
+
+Use this checklist when adding a decorator. Yes, it is mildly bossy. That is the point.
+
+1. Update `TODO.md` or the relevant design document with the intended behavior.
+2. Decide whether the decorator supports bare usage, configured usage, or both.
+3. Add implementation under `src/pydecorators/`.
+4. Use shared helpers from `pydecorators._core` where applicable:
+   - `is_async_callable`
+   - `mirror_metadata`
+   - `monotonic`
+   - `sync_sleep`
+   - `async_sleep`
+   - configuration validators
+5. Preserve wrapped function metadata.
+6. Support async functions where practical, or document why not.
+7. Export the decorator from `pydecorators.__init__` and `__all__` only when it is ready to be public.
+8. Add tests for:
+   - normal behavior
+   - invalid configuration
+   - metadata preservation
+   - sync and async paths, if supported
+   - composition or edge cases when relevant
+9. Add README and per-decorator documentation examples.
+10. Add executable examples under `docs/examples/` when useful.
+11. Run the full verification gate:
+
+```bash
+ruff check .
+ruff format --check .
+mypy
+python scripts/smoke_imports.py
+python scripts/smoke_examples.py
+pytest
+python -m build
+python scripts/smoke_wheel_install.py
+python scripts/dogfood_local_wheel.py
+python scripts/dogfood_external_project.py
+```
+
+See [Quality Gates](docs/quality_gates.md) for what each command checks.
+
+The project also ships optional pre-commit hooks. Install them with `pre-commit install` if you want local lint/format/type checks before commits. This is optional because surprise Git hooks are how productivity gets mugged in an alley.
+
+## Public API rule
+
+If a name is in `pydecorators.__all__`, it is public. Public names need tests and documentation.
+
+If a helper is not meant for users, keep it in an underscore-prefixed module.
+
+## Executable documentation examples
+
+When adding runnable docs examples, put them under `docs/examples/` and use the naming pattern `<topic>_examples.py`, for example `deprecated_examples.py` or `disk_cache_backend_examples.py`.
+
+Keep example modules importable without side effects beyond defining small functions/classes. Public top-level example functions should be directly asserted in `tests/test_docs_examples.py`; if a file is intentionally not executable, document why and exempt it explicitly in the relevant policy test.
+
+After adding a new example file:
+
+1. Link it from `docs/index.md`.
+2. Load it through `load_docs_example(...)` in `tests/test_docs_examples.py`.
+3. Add at least one assertion for each public top-level example function.
+4. Run the full verification gate.
+
+## Adding or changing documentation files
+
+When adding or changing docs files, use this checklist before calling the slice done:
+
+1. Link new top-level `docs/*.md` pages from `docs/index.md`, unless the file is intentionally exempt and the docs policy test says why.
+2. Link new executable examples under `docs/examples/` from `docs/index.md`.
+3. Add or update assertions in `tests/test_docs_examples.py` for public top-level example functions.
+4. Add `pytest.mark.docs_policy` coverage when the change introduces a new documentation rule.
+5. Run `./scripts/docs-policy.sh` before the full verification gate.
+
+README Python code blocks are extracted by docs policy tests. Keep them syntactically valid and synchronized with the executable examples/policy expectations when changing documented decorator usage.
+
+The README is also expected to link the core documentation path for new users and reviewers:
+
+- `docs/index.md`
+- `docs/PUBLIC_API.md`
+- `docs/API_DESIGN.md`
+- `docs/exceptions.md`
+- `docs/deprecated.md`
+- `docs/cache_result.md`
+- `docs/disk_cache_backend.md`
+
+If that required set changes, update the README and the matching docs policy test in the same branch.
+
+External HTTP(S) links are syntax-checked only. The docs policy tests verify that they have an `http://` or `https://` scheme, a host, and no whitespace, but they do not fetch the network or fail builds because somebody else's server hiccuped. Local links and local Markdown anchors are checked for actual existence.
+
+If a planning/backlog file such as `GOAL.md`, `PLAN.md`, or `TODO.md` becomes user-facing navigation, update the root documentation link policy at the same time.
+
+## Documentation index inclusion rule
+
+Keep `docs/index.md` grouped by purpose: core project docs, decorator docs, cache backend docs, and executable examples. Add new links to the narrowest matching section rather than using the index as a junk drawer with Markdown syntax.
+
+
+Add a page to `docs/index.md` when it is intended to help users or contributors understand, use, extend, release, or maintain the package. In practice, that includes:
+
+- public API, compatibility, exception, or design policy pages
+- per-decorator behavior docs
+- cache backend, serializer, lifecycle, or trust-boundary docs
+- executable documentation examples under `docs/examples/`
+- release, contribution, or documentation-maintenance guidance linked from the docs flow
+
+Do not add raw planning/backlog files such as `GOAL.md`, `PLAN.md`, or `TODO.md` to the docs index unless they are deliberately promoted to user-facing documentation. If a docs file is intentionally not indexed, document the exemption in the relevant `docs_policy` test.
+
+## Documentation policy tests
+
+Use the `docs_policy` pytest marker for tests that guard documentation maintenance rather than runtime behavior. Mark tests with `@pytest.mark.docs_policy` or a module-level `pytestmark = pytest.mark.docs_policy` when they check things like:
+
+- `docs/index.md` coverage and navigation rules
+- executable documentation example indexing, naming, loading, or assertion coverage
+- Markdown local-link or heading-anchor validation
+- root documentation link policy
+- release-checklist documentation maintenance rules
+
+Do not use `docs_policy` for normal decorator behavior, backend behavior, public API exports, or version checks unless the test is specifically about documentation upkeep.
+
+Run documentation policy checks with:
+
+```bash
+./scripts/docs-policy.sh
+# or, when using Hatch locally:
+hatch run docs-policy
+```
+
+The Hatch alias intentionally delegates to the same script so local and CI documentation checks do not drift.
+
+For the full local release-prep gate, run:
+
+```bash
+hatch run full-gate
+```
+
+That alias chains docs policy, Ruff, formatting checks, mypy, smoke imports, smoke examples, pytest, package build, wheel install smoke, and both dogfood harnesses. It is intentionally boring. Boring gates are how we avoid exciting releases.
+
+## Root documentation links
+
+Root docs that help users or contributors navigate the project should link to `docs/index.md`. Today that means:
+
+- `README.md`
+- `CONTRIBUTING.md`
+- `RELEASE.md`
+
+Planning/backlog docs such as `GOAL.md`, `PLAN.md`, and `TODO.md` are not required to link the docs index unless they grow into user-facing navigation docs.

blakemere_wraptools-0.1.0/DOGFOOD.md

@@ -0,0 +1,51 @@
+# Dogfood Plan
+
+Public publishing is intentionally paused until the package has been used locally enough to expose awkward APIs, decorator-composition problems, documentation gaps, and release-process surprises.
+
+The current distribution name is `blakemere-wraptools`; the import package remains `pydecorators`.
+
+## Goals
+
+- Install the built wheel in a clean virtual environment.
+- Run realistic scripts from outside the source checkout.
+- Exercise decorator composition instead of only single-decorator happy paths.
+- Record findings before TestPyPI/PyPI release.
+
+## Dogfood harness
+
+Run:
+
+```bash
+python scripts/dogfood_local_wheel.py
+python scripts/dogfood_external_project.py
+```
+
+The harness:
+
+1. Builds a local wheel.
+2. Creates a clean virtual environment.
+3. Installs the wheel.
+4. Runs dogfood scripts from `dogfood/` with `PYTHONPATH` cleared.
+
+## Dogfood scenarios
+
+- `dogfood/service_client.py`: combines `@require_env`, `@rate_limit`, `@retry`, `@timeout`, `@log_calls`, `@measure_time`, and `@circuit_breaker` in service-client-like sync and async flows.
+- `scripts/dogfood_external_project.py`: runs decorators from the installed wheel against `projects/model-gateway-reliability-mini-lab/gateway_sim.py` without modifying that project.
+
+## Findings log
+
+Add findings here as dogfood scripts expose sharp edges.
+
+- 2026-05-12: Initial harness added. No API changes required yet; first goal is keeping composition behavior executable from an installed wheel.
+- 2026-05-12: External local-project dogfood against `model-gateway-reliability-mini-lab/gateway_sim.py` passed without API changes. Dynamic wrapping worked, but it reinforced that composition docs should eventually explain decorator order for wrappers that log/retry/measure.
+- 2026-05-12: Resolved the wrapper-order documentation finding by adding `docs/composition.md` and linking it from the docs index and README. No API changes required.
+
+## Release gate
+
+Before publishing:
+
+- [ ] Run `python scripts/dogfood_local_wheel.py`.
+- [ ] Run `python scripts/dogfood_external_project.py`.
+- [ ] Review this findings log.
+- [x] Resolve or explicitly defer any API/documentation issues found during dogfood use.
+- [ ] Re-check `pydecorators` availability on PyPI/TestPyPI.