Atlas Alignment - April 2026 Update

.github/workflows/ci.yml

@@ -5,6 +5,10 @@ on:
   push:
     branches:
       - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
 
 jobs:
   ci:
@@ -22,7 +26,68 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
+          pip install --upgrade \
+            "design-research-analysis @ git+https://github.com/cmudrc/design-research-analysis.git@main" \
+            "design-research-agents @ git+https://github.com/cmudrc/design-research-agents.git@main" \
+            "design-research-problems @ git+https://github.com/cmudrc/design-research-problems.git@main" \
+            "design-research-experiments @ git+https://github.com/cmudrc/design-research-experiments.git@main"
           pip install -e ".[dev]"
 
       - name: Run local CI gate
         run: make ci
+
+  coverage-badge:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: [ci]
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    concurrency:
+      group: coverage-badge-${{ github.ref }}
+      cancel-in-progress: true
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref_name }}
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --upgrade \
+            "design-research-analysis @ git+https://github.com/cmudrc/design-research-analysis.git@main" \
+            "design-research-agents @ git+https://github.com/cmudrc/design-research-agents.git@main" \
+            "design-research-problems @ git+https://github.com/cmudrc/design-research-problems.git@main" \
+            "design-research-experiments @ git+https://github.com/cmudrc/design-research-experiments.git@main"
+          pip install -e ".[dev]"
+
+      - name: Generate coverage artifacts
+        run: make coverage
+
+      - name: Generate coverage badge
+        run: python scripts/generate_coverage_badge.py
+
+      - name: Generate example badges
+        run: make examples-metrics
+
+      - name: Commit and push badges if changed
+        env:
+          BRANCH_NAME: ${{ github.ref_name }}
+        run: |
+          if ! git status --porcelain -- .github/badges/coverage.svg .github/badges/examples-passing.svg .github/badges/examples-api-coverage.svg | grep -q .; then
+            echo "Badges unchanged."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add .github/badges/coverage.svg .github/badges/examples-passing.svg .github/badges/examples-api-coverage.svg
+          git commit -m "chore: update coverage and examples badges [skip ci]"
+          git push origin "HEAD:${BRANCH_NAME}"

.github/workflows/docs-pages.yml

@@ -36,12 +36,18 @@ jobs:
       - name: Build docs
         run: make docs
 
+      - name: Setup Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/configure-pages@v5
+
       - name: Upload Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         uses: actions/upload-pages-artifact@v3
         with:
           path: docs/_build/html
 
   deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     needs: build
     runs-on: ubuntu-latest
     environment:

.github/workflows/examples.yml

@@ -0,0 +1,40 @@
+name: Examples
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  deterministic-examples:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --upgrade \
+            "design-research-analysis @ git+https://github.com/cmudrc/design-research-analysis.git@main" \
+            "design-research-agents @ git+https://github.com/cmudrc/design-research-agents.git@main" \
+            "design-research-problems @ git+https://github.com/cmudrc/design-research-problems.git@main" \
+            "design-research-experiments @ git+https://github.com/cmudrc/design-research-experiments.git@main"
+          pip install -e ".[dev]"
+
+      - name: Run deterministic examples
+        run: make examples-test
+
+      - name: Check public API example coverage
+        run: make examples-coverage

.gitignore

@@ -98,7 +98,7 @@ ipython_config.py
 #   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
 #   This is especially recommended for binary packages to ensure reproducibility, and is more
 #   commonly ignored for libraries.
-#uv.lock
+uv.lock
 
 # poetry
 #   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.

AGENTS.md

@@ -29,7 +29,8 @@ merging.
   - `make docs-check`
   - `make docs`
 - If the example changed:
-  - `make run-example`
+  - `make run-example` (install `llama-cpp-python[server]`; also install `huggingface-hub` unless `LLAMA_CPP_MODEL` points at a local GGUF file)
+  - `make examples-test` (skips the live walkthrough unless `RUN_LIVE_EXAMPLE=1`)
 - Pre-merge baseline:
   - `make ci`
 - Pre-publish baseline:
@@ -41,14 +42,17 @@ merging.
   `src/design_research/__init__.py` and the wrapper submodules:
   `design_research.problems`, `design_research.agents`,
   `design_research.experiments`, and `design_research.analysis`.
-- Keep wrapper modules thin and explicit; prefer pass-through imports and curated
-  `__all__` lists.
+- Keep wrapper modules thin and trust the sibling libraries to define their own
+  public surfaces. Wrapper submodules should mirror each sibling package's
+  `__all__` by default rather than maintaining local allowlists.
 - If internal helper modules are added, prefix them with `_` and keep them out
   of top-level exports unless there is a deliberate API decision.
 
 ## Behavioral Guardrails
 
 - Keep tests deterministic and offline by default.
+- Let the canonical walkthrough fail fast when the `llama.cpp` runtime is missing rather than silently falling back.
+- Keep total line coverage at or above 90% in CI and local release work.
 - Update tests, docs, and examples alongside behavior changes.
 - Avoid broad dependency growth in the base install.
 - Treat this package as an umbrella wrapper; do not duplicate implementation
@@ -59,6 +63,8 @@ merging.
 - Theme: cartography and wayfinding.
 - Monthly release names are shared across milestone titles, release PR titles,
   and release branches.
+- Milestone due dates should land about one week after the start of the release
+  month so new versions of sibling libraries have time to land first.
   - Milestone title / PR title: `{base name} - {Month YYYY}`
   - Release branch: slugified full title, for example `meridian-map-may-2026`
 - Milestone descriptions must use:
@@ -74,16 +80,16 @@ merging.
 
 | Due date | Base name | Source subject |
 | --- | --- | --- |
-| April 1, 2026 | Atlas Alignment | Atlas |
-| May 1, 2026 | Meridian Map | Meridian |
-| June 1, 2026 | Compass Course | Compass |
-| July 1, 2026 | Legend Line | Map legend |
-| August 1, 2026 | Bearing Bridge | Bearing |
-| September 1, 2026 | Surveyor Signal | Surveying |
-| October 1, 2026 | Cartographer Circuit | Cartography |
-| November 1, 2026 | Wayfinder Weave | Wayfinding |
-| December 1, 2026 | Transit Trace | Transit |
-| January 1, 2027 | North Star Nexus | Pole star |
+| April 8, 2026 | Atlas Alignment | Atlas |
+| May 8, 2026 | Meridian Map | Meridian |
+| June 8, 2026 | Compass Course | Compass |
+| July 8, 2026 | Legend Line | Map legend |
+| August 8, 2026 | Bearing Bridge | Bearing |
+| September 8, 2026 | Surveyor Signal | Surveying |
+| October 8, 2026 | Cartographer Circuit | Cartography |
+| November 8, 2026 | Wayfinder Weave | Wayfinding |
+| December 8, 2026 | Transit Trace | Transit |
+| January 8, 2027 | North Star Nexus | Pole star |
 
 ## Keep This File Up To Date
 

CONTRIBUTING.md

@@ -30,6 +30,31 @@ make docs-check
 make docs
 ```
 
+If the example or walkthrough docs changed, also run:
+
+```bash
+make run-example
+make examples-test
+```
+
+`make run-example` is the live walkthrough path and uses a managed
+`llama.cpp` client. Install `llama-cpp-python[server]` before running it. If
+you want to use the default GGUF download path, also install
+`huggingface-hub`; otherwise set `LLAMA_CPP_MODEL` to point at a specific local
+GGUF file. `make examples-test` skips that walkthrough unless
+`RUN_LIVE_EXAMPLE=1`, which keeps the default local and CI loop offline-safe.
+
+## Coverage Policy
+
+`design-research` follows the family-wide baseline of at least 90% total line
+coverage in CI.
+
+- Treat 90% as a strict floor for this repository, not a soft target.
+- Keep new family repositories at the same baseline unless the shared policy is
+  intentionally changed across the ecosystem.
+- `make ci` enforces this floor through the coverage gate, so coverage-impacting
+  changes should be validated there before merge.
+
 Optional but useful:
 
 ```bash

Makefile

@@ -6,18 +6,23 @@ MYPY ?= $(PYTHON) -m mypy
 SPHINX ?= $(PYTHON) -m sphinx
 BUILD ?= $(PYTHON) -m build
 TWINE ?= $(PYTHON) -m twine
+COVERAGE_MIN ?= 90
 
 .PHONY: help check-python dev install-dev \
 	lint fmt fmt-check type test qa coverage docstrings-check \
-	run-example docs docs-build docs-check docs-linkcheck \
+	run-example examples-test examples-coverage examples-metrics \
+	docs docs-build docs-check docs-linkcheck \
 	release-check ci clean
 
 help:
 	@echo "Common targets:"
 	@echo "  dev              Install the project in editable mode with dev dependencies."
 	@echo "  test             Run the pytest suite."
 	@echo "  qa               Run lint, fmt-check, type, and test."
-	@echo "  run-example      Execute the bundled example script."
+	@echo "  run-example      Execute the live llama.cpp strategy-comparison study example."
+	@echo "  examples-test    Execute all bundled example scripts."
+	@echo "  examples-coverage Check public API coverage across examples."
+	@echo "  examples-metrics Generate example and public-API badge artifacts."
 	@echo "  docs             Build the HTML docs."
 	@echo "  ci               Run the main local CI checks."
 
@@ -49,14 +54,24 @@ qa: lint fmt-check type test
 
 coverage: check-python
 	mkdir -p artifacts/coverage
-	PYTHONPATH=src $(PYTEST) --cov=src/design_research --cov-report=term --cov-report=json:artifacts/coverage/coverage.json -q
-	$(PYTHON) scripts/check_coverage_thresholds.py --coverage-json artifacts/coverage/coverage.json
+	PYTHONPATH=src $(PYTEST) --cov=src/design_research --cov-fail-under=$(COVERAGE_MIN) --cov-report=term --cov-report=json:artifacts/coverage/coverage.json -q
+	$(PYTHON) scripts/check_coverage_thresholds.py --coverage-json artifacts/coverage/coverage.json --minimum $(COVERAGE_MIN)
 
 docstrings-check: check-python
 	$(PYTHON) scripts/check_google_docstrings.py
 
 run-example: check-python
-	PYTHONPATH=src $(PYTHON) examples/basic_usage.py
+	PYTHONPATH=src $(PYTHON) examples/prompt_framing_study.py
+
+examples-test: check-python
+	$(PYTHON) scripts/run_examples.py
+
+examples-coverage: check-python
+	$(PYTHON) scripts/check_example_api_coverage.py --minimum 90
+
+examples-metrics: check-python examples-test
+	$(PYTHON) scripts/generate_examples_metrics.py
+	$(PYTHON) scripts/generate_examples_badges.py
 
 docs-build: check-python
 	PYTHONPATH=src $(SPHINX) -b html docs docs/_build/html -n -W --keep-going -E
@@ -74,7 +89,7 @@ release-check: check-python
 	$(BUILD)
 	$(TWINE) check dist/*
 
-ci: qa coverage docstrings-check docs-check run-example release-check
+ci: qa coverage docstrings-check docs-check examples-test examples-coverage release-check
 
 clean:
 	rm -rf .coverage .mypy_cache .pytest_cache .ruff_cache artifacts build dist docs/_build