Harden color contracts and repo legibility

Author: btfranklin

.github/workflows/python-package.yml

@@ -25,15 +25,22 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install PDM
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install pdm
+        uses: pdm-project/setup-pdm@v4
       - name: Install dependencies
         run: |
           pdm install --group dev
       - name: Lint with ruff
         run: |
           pdm run ruff check src tests --statistics
+      - name: Type check with mypy
+        run: |
+          pdm run mypy src tests
+      - name: Check repo legibility
+        run: |
+          pdm run check:repo
       - name: Test with pytest
         run: |
           pdm run pytest
+      - name: Build package
+        run: |
+          pdm build

AGENTS.md

@@ -0,0 +1,29 @@
+# Agent Map
+
+Start with [docs/index.md](docs/index.md). It is the map for architecture,
+API contracts, quality gates, release flow, and current legibility debt.
+
+## Working Rules
+
+- Use PDM for all Python environment and dependency work.
+- When adding package dependencies, resolve the latest available version and
+  keep constraints as `>=...` unless a precise pin is required for function.
+- Do not add tests that only prove removed functionality is gone. Removals
+  should delete and simplify unless a positive replacement contract needs tests.
+
+## Main Commands
+
+- `pdm run lint`
+- `pdm run typecheck`
+- `pdm run check:repo`
+- `pdm run test`
+- `pdm run check`
+- `pdm build`
+
+## Code Map
+
+- `src/paintcan/hsba_color.py`: immutable HSBA value object and component bounds.
+- `src/paintcan/color_scheme.py`: immutable sequence of generated colors.
+- `src/paintcan/__main__.py`: terminal demo only; keep library behavior in the
+  domain modules.
+- `tests/`: public contract tests plus repo-legibility checks.

README.md

@@ -9,11 +9,12 @@
 ## Features
 
 - **HSBAColor**: A value-type representation of color using Hue, Saturation, Brightness, and Alpha (0.0 - 1.0).
+  - Validates all components on construction.
   - Cyclic Hue adjustment (wrapping).
-  - Clamping and Overflow support for Saturation and Brightness.
+  - Clamping and full-interval Overflow support for Saturation and Brightness.
   - Pythonic unpacking: `h, s, b, a = color`.
 - **ColorScheme**: A collection of colors generated by color theory rules.
-  - Supports the Sequence protocol (`len(scheme)`, `scheme[0]`, iteration).
+  - Immutable and supports the Sequence protocol (`len(scheme)`, `scheme[0]`, slicing, iteration).
   - 8 factory methods for generating harmonious schemes:
     - Analogous
     - Accented Analogous
@@ -88,6 +89,16 @@ pdm run python -m paintcan
 python -m paintcan
 ```
 
+## Development
+
+The maintainer and agent docs live in [`docs/index.md`](docs/index.md). For local validation:
+
+```bash
+pdm install --group dev
+pdm run check
+pdm build
+```
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

docs/api-contracts.md

@@ -0,0 +1,48 @@
+# API Contracts
+
+This document records behavior that should remain stable unless the package is
+intentionally changing its public contract.
+
+## `HSBAColor`
+
+`HSBAColor(hue, saturation, brightness, alpha)` is an immutable value object.
+Each component must be in `0.0 <= value <= 1.0`; invalid construction raises
+`ValueError`.
+
+### Adjustment Methods
+
+- `adjust_hue(change)` accepts `-1.0 <= change <= 1.0` and wraps the result.
+- `complement()` is equivalent to a half-turn hue adjustment.
+- `adjust_saturation(change, floor=0.0, ceiling=1.0, overflow=False)` clamps by
+  default and wraps by full intervals when `overflow=True`.
+- `adjust_brightness(change, floor=0.0, ceiling=1.0, overflow=False)` follows
+  the same bounds behavior as saturation.
+- `adjust_alpha(change, floor=0.0, ceiling=1.0)` clamps only.
+
+Custom floors and ceilings must also be inside `0.0..1.0`, and `floor` must be
+less than or equal to `ceiling`.
+
+### Random Colors
+
+`HSBAColor.random()` always creates a color with alpha `1.0`. Saturation and
+brightness ranges are validated before sampling.
+
+## `ColorScheme`
+
+`ColorScheme(colors)` is a read-only sequence of one or more `HSBAColor` values.
+The constructor normalizes iterable input to a tuple. Empty schemes raise
+`ValueError`.
+
+Every factory method returns five colors:
+
+- `from_analogous`
+- `from_accented_analogous`
+- `from_complementary`
+- `from_compound`
+- `from_monochromatic`
+- `from_shades`
+- `from_split_complementary`
+- `from_triadic`
+
+The first color is always the theme color and is also available through
+`scheme.theme_color`.

docs/architecture.md

@@ -0,0 +1,52 @@
+# Architecture
+
+PaintCan is a small, typed Python package for HSBA color values and deterministic
+color-scheme generation. The intended shape is deliberately simple:
+
+1. `HSBAColor` is the core immutable value object.
+2. `ColorScheme` is an immutable sequence wrapper around generated colors.
+3. The terminal demo renders colors for human inspection but does not own domain
+   behavior.
+
+## Layers
+
+### Domain Values
+
+`src/paintcan/hsba_color.py` owns all HSBA component invariants:
+
+- hue, saturation, brightness, and alpha are floats in `0.0 <= value <= 1.0`;
+- hue adjustment wraps cyclically;
+- saturation and brightness can clamp or overflow within caller-provided bounds;
+- alpha always clamps and never overflows;
+- random color ranges are validated before any color is constructed.
+
+Code outside this module should not reimplement component bounds. It should rely
+on `HSBAColor` construction and adjustment methods.
+
+### Scheme Generation
+
+`src/paintcan/color_scheme.py` owns all palette factory methods. Every factory:
+
+- returns exactly five colors;
+- preserves the first color as `theme_color`;
+- returns a read-only `ColorScheme`;
+- keeps every generated HSBA component inside `0.0..1.0`.
+
+Scheme generation is intentionally algorithmic and local. If more schemes are
+added, keep the scheme rules readable in this module until repeated operations
+make a small internal helper clearly worthwhile.
+
+### Demo Entrypoint
+
+`src/paintcan/__main__.py` is a visual terminal demo. It may convert HSBA to RGB
+for ANSI output, but library callers should import from `paintcan` instead of
+depending on demo helpers.
+
+## Dependency Direction
+
+- `paintcan.__init__` re-exports the public API.
+- `color_scheme` may depend on `hsba_color`.
+- `hsba_color` must not depend on scheme or demo code.
+- `__main__` may depend on both public domain modules.
+- Tests may import the public package and inspect internals only for repo
+  structure checks.

docs/index.md

@@ -0,0 +1,28 @@
+# PaintCan Docs
+
+This directory is the repo-local system of record for maintainers and coding
+agents. Keep the README focused on package users, and keep durable maintenance
+truth here.
+
+## Read By Task
+
+- Understand the library shape: [architecture.md](architecture.md)
+- Check exact public behavior: [api-contracts.md](api-contracts.md)
+- Run or update validation: [quality.md](quality.md)
+- Prepare a release: [releasing.md](releasing.md)
+- Improve repo legibility: [legibility-audit.md](legibility-audit.md)
+
+## Source Map
+
+- `src/paintcan/hsba_color.py` owns HSBA component validation and adjustments.
+- `src/paintcan/color_scheme.py` owns generated scheme collections.
+- `src/paintcan/__main__.py` owns the terminal demo.
+- `tests/test_hsba_color.py` and `tests/test_color_scheme.py` encode the public
+  behavior contracts.
+- `tests/test_repo_legibility.py` keeps the docs and validation surface wired.
+
+## Planning Policy
+
+Planning docs should stay forward-looking. Once work is implemented, move durable
+truth into the relevant current-state document instead of leaving completed task
+history in a plan.

docs/legibility-audit.md

@@ -0,0 +1,39 @@
+# Legibility Audit
+
+Last updated: 2026-05-08
+
+## Current Strengths
+
+- The package has a small public API with clear module ownership.
+- PDM owns dependency and build workflows.
+- CI already validates the package across the supported Python versions.
+- The code has focused pytest coverage for the two domain types.
+
+## Gaps Closed In This Pass
+
+- Added `AGENTS.md` as a short routing map instead of relying on chat-provided
+  instructions.
+- Added this indexed `docs/` spine so architecture, API contracts, quality, and
+  release flow are discoverable in the repo.
+- Added strict mypy type checking as a local and CI validation lane.
+- Added repo-legibility tests so docs routes and validation commands cannot drift
+  silently.
+- Tightened tests around HSBA invariants, overflow behavior, immutable schemes,
+  and generated scheme bounds.
+
+## Remaining Pressure Points
+
+- Scheme factory definitions are still hand-written chains. That is acceptable
+  at the current size, but the next family of schemes should revisit whether a
+  small internal operation helper would make the palette rules easier to audit.
+- There is no generated public API inventory. If the package grows beyond the two
+  current public classes, add a generated or test-enforced inventory under
+  `docs/generated/`.
+- The terminal demo is intentionally simple. If it grows into a richer CLI, split
+  CLI formatting from demo orchestration and document that boundary here.
+
+## Entropy Control
+
+Keep `tests/test_repo_legibility.py` cheap and focused. When a future review
+finds drift that can be expressed mechanically, prefer adding one targeted
+assertion there over expanding `AGENTS.md`.

docs/quality.md

@@ -0,0 +1,45 @@
+# Quality
+
+PaintCan is a tiny library, so quality gates should stay fast and contract
+oriented. The full local validation loop is:
+
+```bash
+pdm run lint
+pdm run typecheck
+pdm run check:repo
+pdm run test
+pdm build
+```
+
+For a single command before handing work back, run:
+
+```bash
+pdm run check
+```
+
+`pdm run check` covers linting, strict mypy type checking, repo-legibility
+checks, and the pytest suite. Run `pdm build` as well before release or packaging
+changes.
+
+## Test Contracts
+
+Tests should protect user-facing behavior rather than mirror implementation
+coincidence:
+
+- HSBA components stay inside `0.0..1.0`.
+- Invalid construction and invalid adjustment bounds raise clear `ValueError`s.
+- Overflow wraps by full intervals, not by a single correction step.
+- `ColorScheme` is immutable and sequence-like.
+- Every scheme factory returns five in-range colors with the theme first.
+- Documentation and CI keep pointing at the current validation surface.
+
+## Static Checks
+
+The package ships `py.typed`, so type checking is part of the public maintenance
+contract. Keep `pdm run typecheck` green when public signatures change.
+
+## Dependency Policy
+
+Use PDM for dependency management. When adding dependencies, resolve the latest
+available version and store constraints with `>=...` unless an exact pin is
+necessary for runtime correctness.

docs/releasing.md

@@ -0,0 +1,32 @@
+# Releasing
+
+PaintCan uses SCM-derived versions through PDM. Release work should preserve the
+local validation contract before publishing.
+
+## Local Release Checklist
+
+1. Run the full validation loop:
+
+   ```bash
+   pdm run lint
+   pdm run typecheck
+   pdm run check:repo
+   pdm run test
+   pdm build
+   ```
+
+2. Confirm the built artifacts under `dist/` have the expected version.
+3. Tag the release with a `vX.Y.Z` tag.
+4. Publish a GitHub release from that tag.
+
+## GitHub Automation
+
+- `.github/workflows/python-package.yml` validates pushes and pull requests
+  across supported Python versions.
+- `.github/workflows/draft-release-notes.yml` drafts release notes for
+  `v*.*.*` tags.
+- `.github/workflows/python-publish.yml` publishes to PyPI when a GitHub release
+  is published.
+
+The publish workflow uses PyPI trusted publishing. Keep package metadata in
+`pyproject.toml` aligned with the README and supported Python classifiers.