Reframe cpm_spec() around staged CPM helpers

.Rbuildignore

@@ -11,3 +11,7 @@
 ^CODE_OF_CONDUCT\.md$
 ^[.]?air[.]toml$
 ^\.vscode$
+^\.agents($|/)
+^doc$
+^Meta$
+^touchstone$

.agents/skills/cpmr-r-development/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: cpmr-r-development
+description: Work on the cpmr R package in this repository. Use when editing package code, tests, documentation, or repo-managed package workflow guidance, especially for the staged selection/construction/model architecture, AIR formatting, devtools::document()/devtools::test(), restoring package coverage to 100%, and finishing with devtools::check().
+---
+
+# CPMR R Development
+
+Use this skill for changes inside the `cpmr` package repo.
+Read the package surface before editing: start with `README.Rmd`, then open the
+relevant files in `R/` and matching tests in `tests/testthat/`.
+
+## Project Workflow
+
+1. Understand the affected stage before changing code.
+   In this repo, keep the public CPM stages visible as `selection`,
+   `construction`, and `model`.
+2. Preserve the staged API.
+   `cpm_spec()` should stay readable at the top level, while stage-specific
+   helpers carry their own arguments.
+3. Keep runtime paths straight.
+   Avoid helper layers that only forward arguments, avoid repeated
+   validation/normalization in internal spec-based paths, and prefer computing a
+   value once over recomputing it through wrappers.
+4. Keep the `model` layer extensible.
+   Even if `lm` is the only current model, preserve a clear model boundary so
+   future model types have an obvious integration point.
+5. Match tests to the layer you changed.
+   Update the closest `testthat` file first, then run broader tests when the
+   change crosses multiple stages.
+
+## Repo-Specific Guidance
+
+- `R/cpm-spec*.R`: public staged spec helpers and validation
+- `R/fit-selection.R`: edge-selection runtime
+- `R/fit-construction.R`: feature construction and cached summaries
+- `R/fit-pipeline.R`: train/test flow, construction, model fit, prediction
+- `R/fit-runner.R`: top-level fit orchestration
+- `tests/testthat/`: stage-aligned tests
+
+When simplifying code in this repo:
+
+- Prefer one real runtime function over `foo()` plus `foo_impl()` when there is
+  only one meaningful path.
+- Put validation and normalization at public constructors or convenience
+  wrappers, not deep in internal runtime helpers that already receive parsed
+  specs.
+- When a private helper is still worth keeping, place it after the main
+  function(s) it supports so the file reads top-down from public flow to
+  implementation detail.
+- Preserve training-time caches when prediction reuses training data.
+- Keep names literal and stage-based instead of introducing abstract temporary
+  state.
+
+## Quality Checks
+
+Use AIR for formatting.
+This repo already points VS Code at `Posit.air-vscode` and CI uses
+`posit-dev/setup-air`.
+
+```bash
+air format .
+air format R/file.R
+```
+
+After R code changes, run:
+
+```r
+devtools::document()
+devtools::test()
+cov <- covr::package_coverage()
+print(cov)
+if (covr::percent_coverage(cov) < 100) {
+  stop(
+    sprintf(
+      "Coverage must remain at 100%% (current: %.3f%%).",
+      covr::percent_coverage(cov)
+    )
+  )
+}
+devtools::check()
+```
+
+Do not stop at green tests alone. This repo expects package coverage to remain
+at `100%`; if coverage drops below `100%`, add or adjust tests before
+finishing, or report the blocker explicitly. Once coverage is back to `100%`,
+run `devtools::check()` as the final package gate, because it catches build,
+install, documentation, and example issues that unit tests alone can miss.
+When coverage is below `100%`, inspect `covr::zero_coverage(cov)` to locate the
+uncovered lines before adding tests.
+
+For narrower iteration loops, use:
+
+```r
+devtools::test(filter = "fit-model")
+testthat::test_file("tests/testthat/test-fit-model.R")
+```
+
+If roxygen examples, README examples, or pkgdown-facing docs changed, update the
+generated outputs that belong with those sources before finishing.

.agents/skills/cpmr-r-development/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "CPMR Package Development"
+  short_description: "cpmr workflow with staged specs and quality gates"
+  default_prompt: "Use $cpmr-r-development to work on the cpmr package with staged CPM specs, AIR formatting, 100% coverage, and a final devtools::check()."

.agents/skills/r-api-design/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: r-api-design
+description: Design or refactor R function APIs with tidyverse-inspired principles. Use when choosing function names, argument order, defaults, enums vs booleans, options/helper objects, output contracts, side effects, or error structure in R packages.
+---
+
+# R API Design
+
+Use this skill when shaping an R API, not just when polishing style.
+Optimize for humans reading code, consistency across related functions, and
+small composable pieces.
+
+Before editing, read the public function signature, its closest tests, and the
+callers directly above and below it in the stack.
+
+## Design Priorities
+
+1. Keep layers distinct.
+   Do not force one naming pattern across different abstraction levels. Public
+   entry points, orchestration helpers, and low-level transforms can use
+   different name families if the boundary becomes clearer.
+2. Prefer interfaces that are obvious at a glance.
+   The function signature should reveal what is required, what is optional, and
+   which arguments matter most.
+3. Optimize for consistency and composition.
+   Reuse the same API pattern across related functions, and make outputs easy to
+   feed into the next step.
+4. Prefer explicit behavior.
+   Avoid hidden dependence on options, locale, or internal state when it affects
+   computation.
+
+## Naming
+
+- Use `snake_case`.
+- Prefer verbs for actions and nouns for object builders.
+- Err toward names that are a bit long but obvious.
+- Reserve very short names for very frequent calls.
+- Use prefixes for families and suffixes for variations.
+- Keep related names parallel within a layer, but do not flatten different
+  layers into one naming scheme just for symmetry.
+
+## Function Signatures
+
+- Put the most important arguments first.
+- Give defaults only to optional arguments.
+- Put `...` after required arguments.
+- Keep defaults short and simple.
+  If the real default is non-trivial, prefer `NULL` plus in-body resolution, or
+  a documented helper object.
+- Make inputs explicit.
+  If an option, locale, or external setting changes results, surface it as an
+  argument.
+- Keep argument meanings independent whenever possible.
+  Avoid signatures where one argument silently changes the meaning of another.
+
+## Options And Strategies
+
+- Use small string enums for a finite set of choices.
+  Prefer `c("a", "b")` with `rlang::arg_match()` or `match.arg()` over ad hoc
+  checking.
+- Prefer enums over booleans when `TRUE`/`FALSE` would be ambiguous, or when
+  the choice may grow beyond two strategies.
+- If different strategies need different arguments, extract them into helper
+  objects instead of piling mutually dependent arguments into one function.
+- If low-importance tuning arguments clutter a signature, group them in an
+  options object created by a helper.
+
+## Helpers
+
+- Delete helpers that only forward arguments or rename values without adding a
+  clear boundary.
+- Keep a private helper when it collapses truly identical repetition or enforces
+  one stable invariant.
+- Extract an error helper only after the same error pattern appears in three or
+  more places.
+- Place private helpers after the main function(s) they support so the file
+  reads top-down from public flow to implementation detail.
+
+## Outputs, Side Effects, And Errors
+
+- Keep outputs type-stable whenever possible.
+- If a function returns multiple values, give them stable names and a stable
+  container shape.
+- Partition side effects away from computation where possible.
+- If a function exists mainly for side effects, return invisibly.
+- Suppress noisy raw calls in user-facing errors with `call. = FALSE` or
+  `rlang::abort()`.
+- Use custom error constructors only for repeated, structured failure modes.
+
+## Review Loop
+
+When reviewing or refactoring an R API:
+
+1. Identify the abstraction layer of the function before judging its name.
+2. Check whether the signature is scannable without reading documentation.
+3. Replace boolean switches or tangled arguments with clearer strategy choices
+   only when that actually reduces complexity.
+4. Remove helpers that exist only because of prior refactors, not because they
+   carry meaning now.
+5. Re-check callers and tests after renaming so the new boundary is still
+   obvious in use.
+
+For deeper source-backed notes, read
+[references/tidyverse-design-map.md](references/tidyverse-design-map.md).

.agents/skills/r-api-design/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "R API Design"
+  short_description: "Tidyverse-inspired R API and function design guidance"
+  default_prompt: "Use $r-api-design to refine R function names, arguments, defaults, helper layers, outputs, side effects, and errors with tidyverse-inspired design principles."

.agents/skills/r-api-design/references/tidyverse-design-map.md

@@ -0,0 +1,64 @@
+# Tidyverse Design Source Map
+
+This note distills the parts of [Tidy design principles](https://design.tidyverse.org/)
+that are most useful when designing or refactoring R package APIs.
+Use it as a map back to the official source, not as a substitute for the book.
+
+## Core frame
+
+- [Unifying principles](https://design.tidyverse.org/unifying.html)
+  Optimize for humans, consistency, composition, and inclusive interfaces.
+- [Function names](https://design.tidyverse.org/function-names.html)
+  Prefer clear `snake_case` names, usually verbs, with prefixes for families and
+  suffixes for variations.
+
+## Signatures
+
+- [Put the most important arguments first](https://design.tidyverse.org/important-args-first.html)
+  Order arguments by importance and typical use, not by implementation details.
+- [Required args shouldn’t have defaults](https://design.tidyverse.org/required-no-defaults.html)
+  Make requiredness visible from the signature.
+- [Put ... after required arguments](https://design.tidyverse.org/dots-after-required.html)
+  Keep the structure of the call readable.
+- [Keep defaults short and sweet](https://design.tidyverse.org/defaults-short-and-sweet.html)
+  Prefer simple defaults; move complex resolution into the body or a helper.
+- [Avoid magical defaults](https://design.tidyverse.org/def-magical.html)
+  Do not make an explicitly supplied default behave differently from an omitted
+  argument.
+- [Make inputs explicit](https://design.tidyverse.org/inputs-explicit.html)
+  Avoid hidden dependence on global options, locale, or other ambient state.
+
+## Choices and helper objects
+
+- [Enumerate possible options](https://design.tidyverse.org/enumerate-options.html)
+  Use small string enums for finite choices and validate them centrally.
+- [Prefer a enum, even if only two choices](https://design.tidyverse.org/boolean-strategies.html)
+  Avoid booleans when `TRUE`/`FALSE` would not be self-explanatory or the design
+  may grow.
+- [Reduce argument clutter with an options object](https://design.tidyverse.org/argument-clutter.html)
+  Move low-importance tuning knobs into a helper-built object when the main
+  signature gets noisy.
+- [Extract strategies into objects](https://design.tidyverse.org/strategy-objects.html)
+  When different strategies need different arguments, use helper objects rather
+  than one oversized signature.
+
+## Outputs and side effects
+
+- [Type-stability](https://design.tidyverse.org/out-type-stability.html)
+  Make output type predictable from input types, not surprising value-dependent
+  branches.
+- [Side-effect functions should return invisibly](https://design.tidyverse.org/out-invisible.html)
+  Let side-effect helpers stay pipe-friendly without pretending they compute a
+  primary value.
+- [Side-effect soup](https://design.tidyverse.org/side-effects.html)
+  Partition side effects deliberately; mixing them with transformation logic
+  raises cognitive load fast.
+
+## Errors
+
+- [Error call](https://design.tidyverse.org/err-call.html)
+  Hide noisy raw calls from user-facing errors unless the call is genuinely
+  helpful.
+- [Error constructors](https://design.tidyverse.org/err-constructor.html)
+  Extract structured error helpers only when the same failure pattern repeats
+  enough to justify the machinery.

.gitattributes

@@ -0,0 +1,11 @@
+# Keep repository text files on LF across platforms.
+* text=auto eol=lf
+
+# Treat common package artifacts as binary.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.pdf binary
+*.rds binary
+*.RData binary

.github/workflows/document.yaml

@@ -0,0 +1,46 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    paths: ["R/**"]
+
+name: document.yaml
+
+permissions: read-all
+
+jobs:
+  document:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup R
+        uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - name: Install dependencies
+        uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::roxygen2
+          needs: roxygen2
+
+      - name: Document
+        run: roxygen2::roxygenise()
+        shell: Rscript {0}
+
+      - name: Commit and push changes
+        run: |
+          git config --local user.name "$GITHUB_ACTOR"
+          git config --local user.email "$GITHUB_ACTOR@users.noreply.github.com"
+          git add man/\* NAMESPACE DESCRIPTION
+          git commit -m "Update documentation" || echo "No changes to commit"
+          git pull --ff-only
+          git push origin

.github/workflows/pkgdown.yaml

@@ -44,6 +44,5 @@ jobs:
         if: github.event_name != 'pull_request'
         uses: JamesIves/github-pages-deploy-action@v4.5.0
         with:
-          clean: false
           branch: gh-pages
           folder: docs

.github/workflows/touchstone-comment.yaml

@@ -0,0 +1,26 @@
+name: Continuous Benchmarks (Comment)
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.workflow_run.id }}
+  cancel-in-progress: true
+
+on:
+  workflow_run:
+    workflows: ["Continuous Benchmarks (Receive)"]
+    types:
+      - completed
+
+permissions:
+  contents: read
+  statuses: write
+  pull-requests: write
+
+jobs:
+  upload:
+    runs-on: ubuntu-latest
+    if: >
+      ${{ github.event.workflow_run.conclusion == 'success' }}
+    steps:
+      - uses: lorenzwalthert/touchstone/actions/comment@7e6072a25d1f8d72649188bc711113039ef94b75
+        with: 
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}