[M0-R][DOCS] Establish the canonical source-of-truth documentation baseline

.github/workflows/docs.yml

@@ -1,8 +1,27 @@
-name: Deploy Docs (MkDocs)
+name: Docs Build and Deploy (MkDocs)
 
 on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "README.md"
+      - "CHANGELOG.md"
+      - "SECURITY.md"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/docs.yml"
   push:
     branches: [master, main]
+    paths:
+      - "docs/**"
+      - "README.md"
+      - "CHANGELOG.md"
+      - "SECURITY.md"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/docs.yml"
   workflow_dispatch:
 
 permissions:
@@ -11,12 +30,14 @@ permissions:
   id-token: write
 
 concurrency:
-  group: pages
-  cancel-in-progress: false
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
   build:
+    name: strict-build
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@v4
 
@@ -32,15 +53,17 @@ jobs:
       - name: Install docs dependencies
         run: uv sync --frozen --no-default-groups --group docs
 
-      - name: Build site
+      - name: Build site in strict mode
         run: uv run --frozen --no-default-groups --group docs mkdocs build --strict
 
       - name: Upload Pages artifact
+        if: github.event_name == 'push'
         uses: actions/upload-pages-artifact@v3
         with:
           path: site
 
   deploy:
+    if: github.event_name == 'push'
     runs-on: ubuntu-latest
     needs: build
     environment:

CHANGELOG.md

@@ -1,25 +1,45 @@
 # Changelog
 
-All current release claims are governed by
-[`docs/governance/CLAIMS_POLICY.md`](docs/governance/CLAIMS_POLICY.md).
+All current release claims are governed by [`docs/governance/CLAIMS_POLICY.md`](docs/governance/CLAIMS_POLICY.md). A changelog entry records implementation history; it does not establish scientific validity.
 
-## Unreleased — canonical E1 governance
+## Unreleased — M0-R Canonical Scientific Baseline
 
-- Declared `E1_research_prototype` as the intended-use level.
-- Declared clinical decision support, validated patient-specific prediction,
-  and identified causal effects as false.
-- Replaced prescriptive simulation interpretation with model-relative
-  diagnostic flags carrying epistemic and model-version context.
+### Documentation and planning
+
+- Added a canonical mission: virtual patients, current and experimental therapy hypotheses, falsification, reproducible protocols and an interdisciplinary Knowledge Commons.
+- Separated current verified architecture from the target virtual-laboratory architecture.
+- Added a current model-status catalog with formulas, units, examples, code mappings and falsification boundaries.
+- Added source-of-truth and documentation-governance policies plus a corpus inventory.
+- Reconciled GitHub roadmap/tracker state and Notion project state against canonical `master` `a33418fb...`.
+- Added strict MkDocs validation to documentation pull requests without deploying PR content.
+
+### Scientific identity and reproducibility
+
+- Added the Structured Research Dataset Contract v0.1 and generic idempotent importer.
+- Added content-addressed computational-input and Patient Twin lineage contracts.
+- Added immutable research run manifests and a governed model registry.
+- Added typed scientific payload contracts, artifact integrity checks, direct-comparability rules and append-only invalidation.
+- Locked the dependency graph with `uv.lock`, Python 3.11/3.12 support and numerical/repository/dependency checks.
+- Upgraded sqlparse to 0.6.0 and recorded exact dependency-audit decisions through merged PR `#71`.
+- Migrated the unsupported Django 4.2 baseline to Django 5.2.17 LTS through merged PR `#72`.
+- Removed all Django 4.2 advisory exceptions; ordinary/deploy checks, disposable migrations, authorization-sensitive regressions, dependency audit, numerical baseline and Docker evidence passed.
+- Added a stable protected `required` dependency/reproducibility result after detecting a mismatch between branch protection and workflow status names.
+
+### Intended use and language
+
+- Declared `E1_research_prototype` as the current intended-use level.
+- Declared clinical decision support, validated patient-specific prediction and identified causal effects as false.
+- Replaced prescriptive simulation interpretation with model-relative diagnostic flags carrying epistemic and model-version context.
 - Added machine-readable release claims and semantic regression tests.
-- Separated learning, research, and administration navigation.
-- Invalidated pre-policy chemistry efficacy, survival, toxicity/risk-benefit,
-  and patient-prognosis outputs for scientific interpretation; numerical model
-  equations and parameters are unchanged.
+- Separated learning, research and administration navigation.
+- Invalidated pre-policy chemistry efficacy, survival, toxicity/risk-benefit and patient-prognosis outputs for scientific interpretation; numerical equations and parameters were not changed by that language migration.
+
+### Operational identity
+
+- Added a governed temporary least-privilege M0 smoke-user command. It does not constitute a normal product login or reviewed RBAC contract.
 
-## 1.0.0 — 2024-11
+## Historical 1.0.0 claim — 2024-11
 
-- Initial public research-prototype release.
+A 2024 document described the repository as ready for a public `1.0.0` release and incorrectly equated passing 30 of 32 tests with 94% code coverage. Those statements are historical and are not current release, coverage or security evidence.
 
-Pre-governance descriptions are preserved in Git history and summarized in
-[`docs/archive/LEGACY_PRESCRIPTIVE_OUTPUTS.md`](docs/archive/LEGACY_PRESCRIPTIVE_OUTPUTS.md).
-They are not current product capabilities or authorized claims.
+The archived record is retained at [`docs/archive/releases/RELEASE_PREPARATION_2024.md`](docs/archive/releases/RELEASE_PREPARATION_2024.md). Legacy prescriptive claims are summarized in [`docs/archive/LEGACY_PRESCRIPTIVE_OUTPUTS.md`](docs/archive/LEGACY_PRESCRIPTIVE_OUTPUTS.md).

README.md

@@ -1,7 +1,6 @@
 # bmyCure4MM
 
-bmyCure4MM is an **E1 research prototype** for reproducible Multiple Myeloma
-computational research.
+bmyCure4MM is an **E1 research prototype** whose north-star is a virtual and reproducible Multiple Myeloma research laboratory.
 
 ```yaml
 intended_use_level: E1_research_prototype
@@ -10,118 +9,104 @@ patient_specific_prediction_validated: false
 causal_effect_identified: false
 ```
 
-The platform supports mechanistic simulation, structured research data,
-lineage-bound patient-twin experiments, exploratory scenario comparison, and
-scientific QA. It does not choose treatment, issue patient-specific dose or
-schedule instructions, predict patient benefit, or identify causal treatment
-effects.
+The platform currently provides governed structured research data, lineage-bound Patient Twin infrastructure, mechanistic PK/PD and schedule-aware simulation, model-relative counterfactual research, immutable run identity, artifact integrity and scientific QA foundations.
 
-The canonical policy is [Canonical Intended Use](docs/governance/INTENDED_USE.md).
+It does **not** choose treatment, issue patient-specific dose or schedule instructions, predict validated patient benefit or identify causal treatment effects.
+
+## Start here
+
+- [Mission and north star](docs/product/MISSION_AND_NORTH_STAR.md)
+- [Current verified state](docs/product/CURRENT_STATE.md)
+- [Capabilities and limitations](docs/product/CAPABILITIES_AND_LIMITATIONS.md)
+- [Canonical intended use](docs/governance/INTENDED_USE.md)
+- [Source-of-truth policy](docs/governance/SOURCE_OF_TRUTH.md)
+- [Current architecture](docs/architecture/CURRENT_SYSTEM.md)
+- [Target virtual laboratory](docs/architecture/TARGET_VIRTUAL_LAB.md)
+- [Current model registry and formulas](docs/models/REGISTRY.md)
+- [Project roadmap](docs/product/ROADMAP.md)
+
+## Current verified baseline
+
+```text
+repository = andreazedda/bmyCure4MM
+branch = master
+verified_head = a33418fb8ae9cb9fd05832dd9bc1cb0778e08533
+```
+
+Current M0-R path:
+
+```text
+#14 documentation/source of truth
+→ #13 mandatory CI aggregate gate and PR governance
+→ #23 minimum scientific/privacy invariants
+→ #26 close M0-R
+```
+
+The canonical dependency baseline now uses Django 5.2.17 LTS and sqlparse 0.6.0. Dependency audit, Django compatibility/deploy checks, disposable migrations, Python 3.11/3.12 suites, numerical identity, Secret Scan, Docker build and the protected `required` gate passed in PRs #71 and #72.
 
 ## Current capabilities
 
-- versioned structured research-dataset import with content hashes;
-- mechanistic PK/PD and tumor/healthy-cell simulation;
-- lineage-bound research twin initialization and calibration infrastructure;
-- model-relative diagnostic flags with explicit epistemic labels;
-- time-respecting research diagnostics, uncertainty, sensitivity, robustness,
-  and backtesting prototypes;
-- molecular research utilities, with RDKit-dependent features optional;
-- separate educational (`/learn/`), research (`/research/`), and administrative
-  (`/admin/`) surfaces.
+- versioned Structured Research Dataset Contract and idempotent import infrastructure;
+- content-addressed computational-input and Twin lineage;
+- persistent Twin states, residuals and calibration infrastructure;
+- logistic tumour/healthy-cell and PK/PD research simulation;
+- day-resolved administered-dose profiles and schedule identity;
+- heuristic hepatic and neutropenia risk signals;
+- mechanistic baseline/alternative counterfactual runs;
+- immutable run manifests, model registry, artifact hashes, comparability and invalidation;
+- uncertainty, sensitivity, robustness and backtesting prototypes;
+- optional molecular research utilities;
+- separate learning, research and administration surfaces.
 
-All scientific results require interpretation in model and data context.
-Negative and inconclusive results are valid research outcomes.
+See [Capabilities and limitations](docs/product/CAPABILITIES_AND_LIMITATIONS.md) before interpreting any result.
 
 ## Local setup
 
-Python 3.11 and 3.12 are supported. `uv.lock` is the sole dependency lock;
-`uv` 0.12.3 is required and refuses a stale lock.
+Python 3.11 and 3.12 are supported. `uv.lock` is the sole dependency lock and `uv` 0.12.3 is required.
 
 ```bash
 git clone https://github.com/andreazedda/bmyCure4MM.git
 cd bmyCure4MM
-python3.11 -m pip install uv==0.12.3  # one-time bootstrap
+python3.11 -m pip install uv==0.12.3
 uv sync --frozen --extra chemistry
 uv run python manage.py migrate
 uv run python manage.py check
 uv run python manage.py runserver
 ```
 
-Omit `--extra chemistry` for core work that does not use RDKit or the molecular
-pipelines. Dependency groups, lock updates, audits, and deterministic numerical
-checks are documented in [Dependency Operations](docs/operations/DEPENDENCIES.md).
-
-Do not use production secrets or private patient payloads in development
-commands, fixtures, tests, or Git.
+Omit `--extra chemistry` for core work that does not require RDKit. Dependency operations are documented in [Dependency Operations](docs/operations/DEPENDENCIES.md).
 
-## Tests and safety gate
+## Verification and safety
 
 ```bash
+uv lock --check
+uv sync --frozen --extra chemistry
 uv run python manage.py check
 uv run python manage.py makemigrations --check --dry-run
 uv run python manage.py test
 uv run ruff check .
 uv run ruff format --check .
 uv run mypy
+uv run python -m scripts.check_repository_hygiene
 uv run python -m scripts.check_numerical_baseline
 uv run python -m scripts.audit_dependencies
-scripts/pre_push_research_safety_check.sh
+bash scripts/pre_push_research_safety_check.sh
 ```
 
-The safety script checks ignored private paths, staged sensitive files,
-PHI-like markers, Django configuration, twin-engine tests, and selected
-authorization/simulation tests.
-
-## Scientific identity
-
-The current research model identifier is `research-twin-v1`. Twin states may
-bind model/config/Git identity, dataset identity, and a content-addressed
-computational-input hash. Historical states without lineage remain explicitly
-unbound; they are not silently reinterpreted.
-
-Every persisted scientific execution now creates an immutable run manifest
-containing the mandatory model/data/code/configuration version vector and
-artifact hashes. The governed model registry, direct-comparison rules, and
-append-only invalidation semantics are documented in
-[Research run manifests](docs/research/RUN_MANIFESTS.md). A successful process
-exit still does not imply calibration, validation, or scientific success.
-
-## Epistemic labels
-
-Current canonical labels are:
-
-`OBSERVED`, `DERIVED`, `USER_PROVIDED`, `SIMULATED`, `HEURISTIC`,
-`LITERATURE_INFORMED`, `HYPOTHETICAL`, and `VALIDATED_EXTERNAL`.
-
-Definitions and restrictions are in
-[Epistemic Labels](docs/governance/EPISTEMIC_LABELS.md) and
-[Model Output Language](docs/governance/MODEL_OUTPUT_LANGUAGE.md).
-
-## Repository areas
-
-```text
-clinic/         structured clinical-record workspace and data navigation
-simulator/      mechanistic simulation and synthetic learning scenarios
-twin_engine/    research twin, lineage, diagnostics, and artifacts
-chemtools/      molecular research utilities
-docs/           current and archived documentation
-governance/     machine-readable release claims
-local_private/  ignored private research material (never commit)
-```
+Current test boundaries and CI limitations are documented in [Testing](docs/operations/TESTING.md) and [Dependency Audit Triage](docs/operations/DEPENDENCY_AUDIT_TRIAGE.md).
 
 ## Privacy
 
-Names, medical-record numbers, dates of birth, clinical PDFs, source excerpts,
-direct identifiers, private dataset payloads, and private artifacts must never
-enter Git. Keep private research material under ignored `local_private/` paths
-and export only explicitly validated, de-identified research artifacts.
+Names, medical-record numbers, dates of birth, clinical PDFs, source excerpts, direct identifiers, private dataset payloads and private artifacts must never enter Git. Keep private research material under ignored `local_private/` paths and export only explicitly validated, de-identified research artifacts.
 
 ## Documentation status
 
-Current governance documents are authoritative. Historical feature narratives
-live under `docs/archive/` and must not be interpreted as current behavior. A
-full documentation source-of-truth rebuild is tracked in GitHub issue #14.
+The documentation corpus is governed by:
+
+- [Documentation policy](docs/governance/DOCUMENTATION_POLICY.md)
+- [Documentation inventory](docs/DOCUMENTATION_INVENTORY.yaml)
+
+Historical feature and release narratives are retained only as archives and are not current product claims.
 
 ## License and security