[M0-R][DOCUMENTATION] Establish the versioned documentation source of truth #14

Verified current state — 2026-08-24

Canonical repository:

repository: andreazedda/bmyCure4MM
branch: master
verified_head: bf097810b337dc6b766cda04497005670cd96513
intended_use: E1_research_prototype

The intended-use contradiction was resolved by #12, dependency identity by #15, Twin/input lineage by #11, and immutable run/model identity by #19. Documentation is therefore no longer blocked by those decisions.

The repository already contains strong current contracts under docs/governance/, docs/research/, and docs/operations/, but they coexist with older architecture guides, implementation logs, release claims, and security statements that describe incompatible generations of the product.

Objective

Create a single versioned documentation system that distinguishes without ambiguity:

CURRENT_VERIFIED
CURRENT_PARTIAL
TARGET_APPROVED
RESEARCH_HYPOTHESIS
DEFERRED
HISTORICAL_ARCHIVE

The documentation must explain both:

1. what bmyCure4MM implements now at the verified Git SHA; and
2. the approved target architecture: a virtual Multiple Myeloma research laboratory for virtual patients, established and experimental therapy hypotheses, falsification, reproducible research protocols, and an interdisciplinary Knowledge Commons.

Target architecture must never be presented as current implementation.

Canonical source-of-truth hierarchy

1. code, schemas, migrations, registries, machine-readable governance
2. current GitHub documentation verified against a Git SHA
3. GitHub issues, PRs, test and validation evidence
4. Notion current project dashboard and decision records
5. external architecture documents / DOCX proposals
6. historical archives

If two layers disagree, the higher layer wins until the lower layer is reconciled.

Phase A — current-state and inventory baseline

Create and make canonical:

docs/product/MISSION_AND_NORTH_STAR.md
docs/product/CURRENT_STATE.md
docs/product/CAPABILITIES_AND_LIMITATIONS.md
docs/product/ROADMAP.md
docs/architecture/CURRENT_SYSTEM.md
docs/architecture/TARGET_VIRTUAL_LAB.md
docs/models/REGISTRY.md
docs/governance/SOURCE_OF_TRUTH.md
docs/governance/DOCUMENTATION_POLICY.md
docs/DOCUMENTATION_INVENTORY.yaml

The inventory must classify every documentation artifact as:

CANONICAL
CURRENT_SUPPORTING
TARGET_SUPPORTING
HISTORICAL_ARCHIVE
DUPLICATE
DELETE_CANDIDATE
UNCLASSIFIED_REQUIRES_REVIEW

For each artifact record:

path
classification
owner
audience
last_verified_git_sha
replacement_or_canonical_parent
reason

No unclassified document may be exposed as a current authoritative page.

Phase B — architecture, models, research contracts, and operations

Document current components:

• clinic;
• simulator;
• twin_engine;
• chemtools;
• docs_viewer;
• structured dataset contracts/importers;
• Twin lineage and calibration lineage;
• model registry and immutable run manifests;
• artifact comparability/invalidation;
• Redis/Celery and asynchronous chemistry jobs;
• current authentication boundary and authorization gaps;
• privacy/safety controls.

Separate current executable models from target candidates using this status taxonomy:

CURRENT_EXECUTABLE
CURRENT_HEURISTIC_PROTOTYPE
CURRENT_HYPOTHETICAL_PROTOTYPE
TARGET_APPROVED
CANDIDATE_COMPARATOR
RESEARCH_HYPOTHESIS
DEFERRED
REJECTED

Every model/formula page must include:

scientific question
formula and variable definitions
units
source-code entry point
model version
parameter provenance/evidence status
worked numerical example
valid domain
limitations
validation/falsification tests
allowed and forbidden conclusions

Phase C — repair existing public documents

Required repairs:

• rewrite the MkDocs navigation around Product, Architecture, Models, Research Contracts, Operations, Governance, and Archive;
• update README.md to link the new canonical documents without expanding current claims;
• update CHANGELOG.md through the current 2026 M0-R work;
• replace the obsolete SECURITY.md placeholder contact/version claims and accurately state current authentication/authorization maturity;
• move RELEASE_PREPARATION.md to a historical archive with a superseded banner;
• archive or reclassify root implementation/debug summaries;
• retain historical evidence without exposing it as current behavior.

Diagram and equation rules

• every diagram declares CURRENT or TARGET;
• source is versioned;
• diagrams are split before labels or arrows overlap;
• no unreadably small text;
• Mermaid rendering is validated;
• every formula has definitions, units, example, code mapping, model version, and falsification condition;
• the DOCX architecture proposal must identify its verified Git SHA and current-vs-target status.

Automated consistency gates

Add deterministic checks for:

• internal links and MkDocs strict build;
• referenced repository files;
• named routes/endpoints;
• environment variables;
• management commands;
• dependency/tool versions;
• migration names;
• intended-use wording;
• documentation status metadata;
• current-vs-target labels;
• archived-document banners.

Acceptance criteria

• Mission and project intention are canonical and derive the proposed architecture.
• Current implementation and target virtual laboratory are documented separately.
• Every current model in twin_engine/model_registry.json has a status and documentation mapping.
• No two current documents contradict intended use, architecture, model status, or current Git identity.
• twin_engine, dataset lineage, run manifests, model registry, comparability, and invalidation are documented.
• README and MkDocs home match runtime behavior and E1 maturity.
• Historical documents have explicit archive banners and are outside the current navigation.
• SECURITY.md has a real reporting path and accurate supported-state language.
• All documentation links and strict builds pass in CI.
• Documentation has an owner, review cadence, and last_verified_git_sha policy.
• Notion current-state pages point to the canonical GitHub documents and do not duplicate technical truth.

Dependencies and execution order

Completed prerequisites:

#11 #12 #15 #19

Current execution order:

#14 documentation/source-of-truth baseline
→ #13 consolidate mandatory CI and PR governance around the canonical paths
→ #23 enforce the minimum scientific QA subset
→ M0-R close

Non-goals

This issue does not change scientific equations, numerical outputs, database semantics, private patient data, clinical claims, or production runtime architecture.