Drop-in 033: Unified psych-design companion v0.1 release candidate

.github/workflows/ci.yml

@@ -67,10 +67,11 @@ jobs:
         with:
           python-version: "3.10"
 
-      - name: Build wheel
+      - name: Build deterministic companion assets and wheel
         run: |
           python -m pip install -U pip
-          python -m pip install build
+          python -m pip install build pandas
+          python tools/build_psych_design_companion_asset.py
           python -m build --wheel
 
       - name: Install wheel + smoke test (posix)
@@ -85,6 +86,15 @@ jobs:
           python -c "from importlib import resources; p = resources.files('pystatsv1.assets') / 'workbook_starter.zip'; assert p.is_file(), p"
           python -c "from importlib import resources; p = resources.files('pystatsv1.assets') / 'psych_stats_with_python_companion_v0_2.zip'; assert p.is_file(), p"
           python -c "from importlib import resources; p = resources.files('pystatsv1.assets') / 'psych_stats_with_python_companion_v0_2_1.zip'; assert p.is_file(), p"
+          python -c "from importlib import resources; p = resources.files('pystatsv1.assets') / 'psychological_statistics_by_design_companion_v0_1.zip'; assert p.is_file(), p"
+          pystatsv1 psych-design info
+          pystatsv1 psych-design list-studies | grep SWL-S10
+          pystatsv1 psych-design init --dest /tmp/psych_design_smoke
+          pystatsv1 psych-design verify --dest /tmp/psych_design_smoke
+          pystatsv1 psych-design doctor --dest /tmp/psych_design_smoke
+          python /tmp/psych_design_smoke/scripts/python/design_audit.py --check-only
+          python /tmp/psych_design_smoke/scripts/python/swl_s02_independent_groups.py
+          test -f /tmp/psych_design_smoke/outputs/swl_s02/python_result.json
           pystatsv1 book1 init --dest /tmp/book1_smoke
           pystatsv1 book1 verify --dest /tmp/book1_smoke
           test -f /tmp/book1_smoke/scripts/python/generate_figures.py
@@ -114,6 +124,15 @@ jobs:
           .\wheeltest\Scripts\python -c "from importlib import resources; p = resources.files('pystatsv1.assets') / 'workbook_starter.zip'; assert p.is_file(), p"
           .\wheeltest\Scripts\python -c "from importlib import resources; p = resources.files('pystatsv1.assets') / 'psych_stats_with_python_companion_v0_2.zip'; assert p.is_file(), p"
           .\wheeltest\Scripts\python -c "from importlib import resources; p = resources.files('pystatsv1.assets') / 'psych_stats_with_python_companion_v0_2_1.zip'; assert p.is_file(), p"
+          .\wheeltest\Scripts\python -c "from importlib import resources; p = resources.files('pystatsv1.assets') / 'psychological_statistics_by_design_companion_v0_1.zip'; assert p.is_file(), p"
+          .\wheeltest\Scripts\pystatsv1.exe psych-design info
+          .\wheeltest\Scripts\pystatsv1.exe psych-design list-studies
+          .\wheeltest\Scripts\pystatsv1.exe psych-design init --dest psych_design_smoke
+          .\wheeltest\Scripts\pystatsv1.exe psych-design verify --dest psych_design_smoke
+          .\wheeltest\Scripts\pystatsv1.exe psych-design doctor --dest psych_design_smoke
+          .\wheeltest\Scripts\python psych_design_smoke\scripts\python\design_audit.py --check-only
+          .\wheeltest\Scripts\python psych_design_smoke\scripts\python\swl_s02_independent_groups.py
+          if (!(Test-Path psych_design_smoke\outputs\swl_s02\python_result.json)) { throw 'Missing psych-design SWL-S02 result' }
           .\wheeltest\Scripts\pystatsv1.exe book1 init --dest book1_smoke
           .\wheeltest\Scripts\pystatsv1.exe book1 verify --dest book1_smoke
           if (!(Test-Path book1_smoke\scripts\python\generate_figures.py)) { throw 'Missing Book 1 figure generator' }
@@ -133,6 +152,44 @@ jobs:
           .\wheeltest\Scripts\pystatsv1.exe workbook check ch10 --workdir wb_smoke
 
 
+  psych-design-companion-release-candidate-smoke:
+    name: psych-design-companion-release-candidate-smoke (ubuntu)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Build wheel and run clean Python release-candidate proof
+        run: |
+          set -euo pipefail
+          python -m pip install -U pip build pandas
+          python tools/build_psych_design_companion_asset.py
+          python tools/check_psych_design_release_contract.py
+          python tools/check_psych_design_release_candidate.py
+          python -m build --wheel
+          python -m venv /tmp/psych-design-release-smoke
+          source /tmp/psych-design-release-smoke/bin/activate
+          python -m pip install -U pip
+          WHEEL=$(ls dist/*.whl)
+          python -m pip install "${WHEEL}[psych-design]"
+          pystatsv1 psych-design info
+          pystatsv1 psych-design init --dest /tmp/psych-design-public
+          pystatsv1 psych-design verify --dest /tmp/psych-design-public
+          pystatsv1 psych-design list-studies | grep SWL-S10
+          pystatsv1 psych-design doctor --dest /tmp/psych-design-public
+          make -C /tmp/psych-design-public design-audit
+          make -C /tmp/psych-design-public all-python
+          make -C /tmp/psych-design-public figures
+          test -f /tmp/psych-design-public/outputs/swl_s02/python_result.json
+          test -f /tmp/psych-design-public/outputs/swl_s08/python_result.json
+          test -f /tmp/psych-design-public/outputs/swl_s10/python_result.json
+          test -f /tmp/psych-design-public/outputs/swl_s02/figures/FIGURE_MANIFEST.json
+          pystatsv1 psych-design verify --dest /tmp/psych-design-public
+
   book1-companion-release-smoke:
     name: book1-companion-release-smoke (ubuntu)
     runs-on: ubuntu-latest

Makefile

@@ -510,6 +510,28 @@ business-ch23:
 	$(PYTHON) -m scripts.business_ch23_communicating_results_governance --datadir $(OUT_NSO_V1) --outdir $(OUT_TRACK_D) --seed $(SEED)
 
 
+
+# --- Psychological Statistics by Design companion release candidate ---
+PSYCH_DESIGN_SOURCE := psych_design_companion/psychological_statistics_by_design_companion_v0_1
+PSYCH_DESIGN_ASSET := src/pystatsv1/assets/psychological_statistics_by_design_companion_v0_1.zip
+
+.PHONY: psych-design-companion-build
+psych-design-companion-build:
+	$(PYTHON) tools/build_psych_design_companion_asset.py
+
+.PHONY: psych-design-companion-check
+psych-design-companion-check: psych-design-companion-build
+	$(PYTHON) tools/check_psych_design_release_contract.py
+	$(PYTHON) tools/check_psych_design_release_candidate.py
+
+.PHONY: psych-design-companion-python-proof
+psych-design-companion-python-proof: psych-design-companion-build
+	$(PYTHON) $(PSYCH_DESIGN_SOURCE)/scripts/python/design_audit.py --check-only
+	$(PYTHON) $(PSYCH_DESIGN_SOURCE)/scripts/python/run_all.py
+	$(PYTHON) $(PSYCH_DESIGN_SOURCE)/scripts/python/generate_figures.py
+	$(PYTHON) -m pytest -q $(PSYCH_DESIGN_SOURCE)/tests/test_companion_contract.py
+	rm -rf $(PSYCH_DESIGN_SOURCE)/outputs
+
 # --- Quality gates ---
 .PHONY: lint
 lint:

README.md

@@ -38,6 +38,34 @@ python scripts/psych_ch10_problem_set.py
 pytest -q
 ```
 
+## Psychological Statistics by Design companion — v0.26.0 release candidate
+
+The source tree now contains a **non-public release candidate** for
+*Psychological Statistics by Design — Executable Companion v0.1*. It unifies
+ten synthetic Student Well-Being and Learning studies behind one registry, ten
+visible Python entry scripts, independent R implementations, verification
+receipts, figure specifications, reviewer packets, and synthetic-safe adaptation
+templates. PyStatsV1 remains the versioned bridge and launcher; it does not
+choose a method, validate an instrument, authorize data, or establish causality.
+
+The candidate interface is implemented for local and CI proof:
+
+```bash
+python -m pip install -e '.[psych-design]'
+python tools/build_psych_design_companion_asset.py
+pystatsv1 psych-design info
+pystatsv1 psych-design init
+cd psychological_statistics_by_design_companion_v0_1
+pystatsv1 psych-design verify --dest .
+python -m pip install -r requirements-psych-design-companion.txt
+make first-result  # complete SWL-S02 Python/R V2 chain; requires Rscript
+```
+
+This is **not yet a PyPI or portal reader route**. Public release, portal
+deployment, book binding, and real-data use remain unauthorized. The current
+public foundations companion continues to use the separately pinned Book 1
+route below.
+
 ## Psych Stats with Python — Book 1 companion
 
 PyStatsV1 v0.25.2 packages Companion v0.2.1, the corrected synthetic-only

docs/PYSTATSV1_DROPIN_033_UNIFIED_PSYCH_DESIGN_COMPANION_RELEASE_CANDIDATE.md

@@ -0,0 +1,96 @@
+# PyStatsV1 Drop-in 033 — Unified Psych-Design Companion v0.1 Release Candidate
+
+## Boundary
+
+This unit changes only the PyStatsV1 repository. It does not edit the
+*Psychological Statistics by Design* book repository or the LearnToProgram.ca
+portal. It does not publish to PyPI, deploy a website, bind manuscript commands,
+authorize real data, or create a final public release tag.
+
+## Baseline and candidate identity
+
+- Baseline main: `e88ff0f6f1aa1c4a946c72b97387f47b3c5311ae`
+- Baseline contract tag: `psych-design-companion-release-contract-v0-1`
+- Feature branch: `feat/psych-design-companion-v0-1-release-candidate`
+- Candidate package version: `0.26.0`
+- Companion version: `v0.1`
+- Candidate tag: `psych-design-companion-v0-1-candidate`
+- Final release tag `v0.26.0`: reserved and not created by this unit
+
+## Implemented reader surface
+
+The candidate implements the frozen command family:
+
+```text
+pystatsv1 psych-design info
+pystatsv1 psych-design init
+pystatsv1 psych-design verify --dest .
+pystatsv1 psych-design list-studies
+pystatsv1 psych-design doctor --dest .
+```
+
+The extracted companion supports:
+
+```text
+make first-result
+make list-studies
+make design-audit
+make all-python
+make all-r
+make parity
+make figures
+make reviewer-packets
+make all
+make study STUDY=SWL-S02
+make verify-study STUDY=SWL-S02
+make packet STUDY=SWL-S02
+```
+
+Make orchestrates visible scripts; it does not contain statistical methods or
+select a method from data. Python is the primary workflow. The copied and
+path-normalized base-R scripts remain independently implemented verification
+paths.
+
+## Unified source architecture
+
+`psych_design_companion/psychological_statistics_by_design_companion_v0_1/`
+contains a no-placeholder central `STUDY_INDEX.json`, all ten synthetic datasets,
+design contracts, dedicated measurement maps, visible Python entry scripts, R
+launchers, verification policies, reference receipts, figure specifications,
+APA source maps, matched limitations, reviewer-packet generation, and nine
+synthetic-safe adaptation templates.
+
+`SOURCE_LINEAGE.json` binds each unified artifact to one of the three preserved
+source batches. The Drop-in 032 preservation manifest continues to verify all
+136 governed source-batch files byte for byte.
+
+## First-result proof
+
+SWL-S02 is the first-result study. `make first-result` verifies the source and
+data layout, runs the transparent Python analysis, runs the independent R path,
+compares the registered V2 fields, regenerates the source-bound figure, and
+constructs a bounded reviewer packet with its own manifest. Each packet includes the study registry record, a source-lineage manifest record, design and measurement contracts, the data-layout audit, Python and R results, the verification receipt, figure specifications and generated-figure manifest, the APA source map, and the matched limitation. The registered
+contrast is always `structured_routine - standard_routine`; mutation coverage
+rejects reversed or stale bindings.
+
+## Source verification boundary
+
+`pystatsv1 psych-design verify` checks only immutable source files listed in the
+packaged manifest. Reader-generated `outputs/` are intentionally outside that
+manifest. Output receipts contain hashes of their inputs and are regenerated by
+the study commands. `make clean` deletes outputs without touching governed
+source.
+
+## Release gates
+
+The release candidate records all of the following as false:
+
+- public companion released
+- PyPI publication authorized
+- portal deployment authorized
+- book binding authorized
+- real data authorized
+
+A later clean-reader unit must prove an installed wheel in fresh Ubuntu and WSL
+environments before the owner considers the final release tag or PyPI
+publication.

docs/source/release_notes.rst

@@ -1,6 +1,37 @@
 Release notes
 =============
 
+v0.26.0 release candidate — Psychological Statistics by Design companion v0.1
+---------------------------------------------------------------------------------
+
+PyStatsV1 v0.26.0 is prepared as a non-public release candidate for the
+synthetic-only *Psychological Statistics by Design* executable companion.
+Publication to PyPI, portal deployment, and book binding remain separate,
+explicitly unauthorized actions.
+
+Highlights
+~~~~~~~~~~
+
+* Adds ``pystatsv1 psych-design info``, ``init``, ``verify``,
+  ``list-studies``, and ``doctor`` behind the release-candidate source tree.
+* Packages all ten SWL studies in one deterministic companion with a central
+  ``STUDY_INDEX.json``, ten visible Python entry scripts, independent base-R
+  paths, V2/V3/V4 comparison policies, figures, APA source maps, matched
+  limitations, and bounded reviewer packets.
+* Makes SWL-S02 the first-result vertical slice from source identity and row
+  audit through Python, R, parity receipt, figure, source map, limitation, and
+  packet.
+* Preserves the three governed source batches byte for byte and records their
+  lineage in the unified companion.
+* Keeps immutable source verification separate from generated ``outputs/`` so
+  readers can clean and regenerate results without invalidating the released
+  source bundle.
+* Includes synthetic-safe adaptation templates and states that adaptation is a
+  new research project rather than replacement of a CSV.
+* Retains all public-release, PyPI, portal, book-binding, and real-data
+  authorization gates as false pending clean Ubuntu and WSL installed-wheel
+  proofs.
+
 v0.25.2 — Book 1 Companion v0.2.1 identity correction
 ----------------------------------------------------------------
 

psych_design_companion/psych_design_release_contract_v0_1/COMMAND_INTERFACE_CONTRACT.json

@@ -2,27 +2,27 @@
   "commands": [
     {
       "command": "pystatsv1 psych-design info",
-      "implemented": false,
+      "implemented": true,
       "purpose": "show packaged companion identity"
     },
     {
       "command": "pystatsv1 psych-design init",
-      "implemented": false,
+      "implemented": true,
       "purpose": "create a new local synthetic companion folder"
     },
     {
       "command": "pystatsv1 psych-design verify --dest .",
-      "implemented": false,
+      "implemented": true,
       "purpose": "verify immutable source files against the packaged manifest"
     },
     {
       "command": "pystatsv1 psych-design list-studies",
-      "implemented": false,
+      "implemented": true,
       "purpose": "list all ten studies and chapter mappings"
     },
     {
       "command": "pystatsv1 psych-design doctor --dest .",
-      "implemented": false,
+      "implemented": true,
       "purpose": "report environment, companion, manifest, dependency, R, and platform facts"
     }
   ],
@@ -41,8 +41,8 @@
     "packet STUDY=SWL-S02"
   ],
   "package_install": "python -m pip install \"pystatsv1[psych-design]==0.26.0\"",
-  "release_boundary": "No command in this contract may be printed as a live reader route until PyPI, asset, portal, and clean-reader proofs are complete.",
+  "release_boundary": "Commands are implemented and tested in the 0.26.0 release candidate but are not a live PyPI or portal reader route until explicit release authorization and clean-reader proofs pass.",
   "schema_version": "psych-design-command-interface-contract-v0.1",
-  "status": "frozen_proposed_not_implemented_not_public",
+  "status": "release_candidate_implemented_not_public",
   "visible_script_rule": "Make targets orchestrate visible scripts and may not hide statistical calculations."
 }

psych_design_companion/psych_design_release_contract_v0_1/COMPANION_RELEASE_CONTRACT.json

@@ -4,18 +4,19 @@
     "package_version": "0.25.2",
     "repository": "PyStatsV1"
   },
-  "expected_branch": "feat/psych-design-companion-release-contract",
-  "expected_tag": "psych-design-companion-release-contract-v0-1",
+  "expected_branch": "feat/psych-design-companion-v0-1-release-candidate",
+  "expected_tag": "psych-design-companion-v0-1-candidate",
   "first_result_study": "SWL-S02",
   "lifecycle": {
     "book_binding_authorized": false,
     "contract_frozen": true,
     "portal_release_authorized": false,
     "public_companion_released": false,
     "pypi_release_authorized": false,
-    "real_data_authorized": false
+    "real_data_authorized": false,
+    "release_candidate_implemented": true
   },
-  "next_unit": "Build the unified synthetic companion asset, launcher implementation, per-study visible scripts, reviewer packets, and release-candidate tests without publishing.",
+  "next_unit": "Run clean Ubuntu and WSL installed-wheel release proofs; do not publish, edit the portal, or bind the book without explicit authorization.",
   "planned_release": {
     "asset_name": "psychological_statistics_by_design_companion_v0_1.zip",
     "cli_namespace": "psych-design",
@@ -44,6 +45,9 @@
   ],
   "python_primary": true,
   "r_independent_verification": true,
+  "release_candidate_asset": "src/pystatsv1/assets/psychological_statistics_by_design_companion_v0_1.zip",
+  "release_candidate_baseline_main": "e88ff0f6f1aa1c4a946c72b97387f47b3c5311ae",
+  "release_candidate_source": "psych_design_companion/psychological_statistics_by_design_companion_v0_1",
   "schema_version": "psych-design-companion-release-contract-v0.1",
   "source_batches": [
     "psych_design_companion/swl_s02_s05_v0_1",
@@ -63,5 +67,6 @@
     "SWL-S10"
   ],
   "unit": "PyStatsV1 Drop-in 032 - Psychological Statistics by Design Companion Release Contract and Unified Study Registry",
+  "unit_033": "PyStatsV1 Drop-in 033 - Unified Psych-Design Companion v0.1 Release Candidate",
   "verification_marker": "PYSTATSV1_PSYCH_DESIGN_RELEASE_CONTRACT_VERIFY_OK"
 }