ContextualWisdomLab · seonghobae · Aug 9, 2026 · Aug 9, 2026 · Aug 9, 2026 · Aug 9, 2026
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -298,6 +298,19 @@
 
 - Replaced the NumPy reference/fallback EAP expression `(posterior * nodes[None, :]).sum(axis=1)` with the algebraically equivalent matrix-vector product `posterior @ nodes`. This avoids constructing the explicit posterior-shaped broadcast product; NumPy may use optimized BLAS for matrix multiplication when available, while realized runtime remains dependent on array shape, layout, hardware, and the linked numerical library.
 
+#### Canonical product and architecture documentation baseline
+
+- Replaced the stale MVP-only PRD/TRD authority with canonical `docs/PRD.md` and `docs/TRD.md` requirements covering the current measurement, scoring, rubric/item-generation, model-selection, scientific-evidence, interoperability, security, lifecycle, and release boundaries.
+- Added root `ARCHITECTURE.md`, a status-bearing ADR corpus, reviewable PlantUML component/sequence/state/deployment views, a logical reusable-domain ERD, and requirements/research traceability matrices.
+- Added a canonical documentation authority index, explicit implementation-maturity/completeness matrix, and machine-checkable documentation contract so missing or stale PRD/TRD/ADR/UML/ERD/traceability/security artifacts remain visible release-maintenance debt rather than silently drifting.
+- Added a reusable-core threat model covering provider/JSON replay, native/PyO3 input boundaries, resource and non-finite numerical failures, GPU evidence spoofing, supply-chain/self-modifying CI, credential separation, benchmark contamination, privacy/purpose limitation, and scientific-interpretation abuse while leaving hosted HTTP/session/tenant/database threats downstream.
+- Added durable ADRs for converging future Rust-backed features on one canonical PyO3/public-export registry and for preserving legitimate sensitive-data linkage through purpose limitation and minimization rather than blanket masking that changes the measurement design.
+- Extended requirements traceability with the conversation-wide invariants that human/LLM judges are fallible raters, correlation is not parameter recovery/absolute agreement, latent-space interaction follows substantive dimension/testlet/facet diagnosis, reference-free is not truth-free, and psychometric discrimination is not business or safety criticality.
+- Explicitly deprecated the original narrow `docs/prd_trd_summary.md` as an authoritative requirements source while retaining its historical MLS2PLM MVP context.
+- Defined the `fast-mlsirm-cjson-v1` fingerprint preimage, SHA-256 binding, null/ordering/Unicode/number rules, and cross-language normative vector instead of leaving canonical serialization as an interoperability assumption.
+- Added the persistence-neutral `docs/uml/domain-public-contract.puml` view, indexed every UML source including the compatibility alias, modeled versioned calibration-design inputs as a many-to-many association, and made corrected quarantined items new immutable revisions.
+- Added complete APA 7 research records and scope summaries for LLM-RUBRIC, AutoNuggetizer/TREC RAG, EvalGen, the 2025 AutoNuggetizer follow-up and 2026 reflective rubric research, plus NIST AI RMF governance inputs with explicit non-certification language.
+
 #### Release cut 0.7.0
 
 - Project version is bumped to 0.7.0 in `pyproject.toml`,
@@ -317,6 +330,12 @@
 
 ### Fixed
 
+#### Subgroup validation evidence fails closed
+
+- Automated-scoring subgroup SMD gates reject requested subgroups with fewer
+  than two paired cases or zero human variance instead of silently skipping
+  them and reporting a vacuous pass.
+
 #### Serving bundle export requires Rust core
 
 - `export_serving_bundle` fails closed when the compiled Rust core is unavailable
@@ -326,6 +345,11 @@
 
 - Restricted the public `FitConfig.estimator` vocabulary to the implemented `jmle` and `mmle` fitting paths, so unsupported `em` and `bayes` requests fail during configuration validation instead of entering a fitting path that later raises `NotImplementedError`.
 
+#### Strict JSON artifact interoperability
+
+- Governed JSON artifact writers now reject `NaN`, positive infinity, and negative infinity instead of emitting Python's non-standard JSON numeric extensions, preserving RFC 8259 interoperability and atomic publication failure.
+- Non-finite serialization errors use a bounded package-owned message without reflecting the rejected artifact payload.
+
 #### Node-rule fail-closed validation
 
 - Public polytomous and 2PL fitters reject non-string integration-rule controls

diff --git a/docs/PRD.md b/docs/PRD.md
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,51 @@
+# fast-mlsirm documentation authority
+
+This index distinguishes governing product/architecture documents from implementation history and method-local evidence.
+
+## Canonical architecture package
+
+| Document | Governing purpose |
+|---|---|
+| [`../ARCHITECTURE.md`](../ARCHITECTURE.md) | System of interest, bounded contexts, dependency direction, component/data/deployment/scientific views |
+| [`PRD.md`](PRD.md) | Product requirements, users, workflows, non-goals, acceptance boundaries |
+| [`TRD.md`](TRD.md) | Technical realization, numerical/runtime/security/resource/release requirements |
+| [`adr/README.md`](adr/README.md) | Durable architecture/scientific decision log and status history |
+| [`standards_watch.md`](standards_watch.md) | Published governing standards versus draft/revision watch items; no certification shortcut |
+| [`verification_validation_plan.md`](verification_validation_plan.md) | Software, numerical, scientific, scoring/RAG, recovery, security, packaging and exact-artifact V&V evidence |
+| [`uml/README.md`](uml/README.md) | PlantUML component, sequence, lifecycle, model-selection, deployment and reusable domain/public-contract views |
+| [`uml/domain-public-contract.puml`](uml/domain-public-contract.puml) | Persistence-neutral reusable domain/public-contract classes and construction rules |
+| [`erd/domain-model.puml`](erd/domain-model.puml) | Logical reusable-domain artifact relationships; **not** a hosted ORM schema |
+| [`traceability/requirements-matrix.md`](traceability/requirements-matrix.md) | PRD/TRD/ADR -> protected-main implementation/evidence maturity |
+| [`traceability/research-basis.md`](traceability/research-basis.md) | Scientific/standards evidence and APA 7 reference mapping |
+| [`documentation_coverage.md`](documentation_coverage.md) | Documentation completeness states, remaining P0/P1/P2 gaps and maintenance gate |
+| [`security/threat-model.md`](security/threat-model.md) | Reusable-core trust/threat model; hosted product threats remain downstream |
+| [`doctoring/`](doctoring/) | Method/security/interoperability evidence and conservative implementation boundaries |
+| [`../AGENTS.md`](../AGENTS.md), [`../CLAUDE.md`](../CLAUDE.md) | Agent/developer operating rules aligned to this architecture |
+| [`../CHANGELOG.md`](../CHANGELOG.md) | User-visible released/unreleased change history |
+
+`prd_trd_summary.md` is historical and must not compete with `PRD.md` and `TRD.md` as a requirements source.
+
+## Authority and status
+
+1. Protected-main source/tests define executable behavior.
+2. Accepted ADRs define governing architecture/scientific decisions.
+3. PRD/TRD define product/technical requirements and non-claims.
+4. `ARCHITECTURE.md`, UML/ERD and the threat model define coherent system views.
+5. The standards watch defines which published editions may govern claims and which drafts/revisions are only monitored.
+6. The V&V plan defines what evidence is needed to verify software behavior and validate scientific/product interpretations.
+7. Method-specific doctoring and primary literature justify local scientific/interoperability details.
+8. Proposed ADRs, open PRs/issues and plans describe future/active work and are not released capability merely because they exist.
+
+A conversation or PR body is discovery evidence until the durable decision is captured in the documents above.
+
+## Implementation history
+
+`docs/superpowers/specs/` and `docs/superpowers/plans/` preserve bounded design/implementation history. They do not automatically remain normative after implementation. If a plan creates a durable product/architecture/scientific decision, update the canonical PRD/TRD/ADR/traceability set.
+
+## Completeness gate
+
+A material change is incomplete if it creates a contradiction among code, accepted ADRs, PRD/TRD, architecture diagrams, security/threat model, standards status, V&V evidence, traceability, doctoring or release evidence. The documentation-contract test and `documentation_coverage.md` make these gaps visible; a missing or stale canonical artifact is release-maintenance debt rather than harmless prose drift.
+
+## Cross-repository boundary
+
+`fast-mlsirm` is the standalone reusable measurement/psychometric core. `ContextualWisdomLab/psychometrics-commons` or another owning downstream service is responsible for hosted HTTP/session/consent/tenant/RBAC/UI/database/deployment lifecycle. Architecture documents here may define interoperable reusable artifacts and versioned handoffs without creating a shared application database or reverse product dependency.