docs: establish approved TEPP planning baseline

.github/workflows/docs-quality.yml

@@ -0,0 +1,40 @@
+name: Documentation Quality
+
+on:
+  pull_request:
+    paths:
+      - "**/*.md"
+      - "**/*.json"
+      - ".github/workflows/**"
+      - "scripts/validate_documentation.py"
+  push:
+    branches:
+      - main
+    paths:
+      - "**/*.md"
+      - "**/*.json"
+      - ".github/workflows/**"
+      - "scripts/validate_documentation.py"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-quality-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: Validate planning and governance contracts
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout exact head
+        uses: actions/checkout@631c942040754b6e095e929c1677c07e10ed4f87
+        with:
+          persist-credentials: false
+      - name: Validate documentation
+        run: python3 scripts/validate_documentation.py
+      - name: Reject whitespace errors
+        run: git diff --check HEAD^ HEAD || git diff --check

.github/workflows/hourly-pr-maintenance.yml

@@ -0,0 +1,24 @@
+name: Hourly PR Maintenance
+
+on:
+  schedule:
+    - cron: "11 * * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: tepp-hourly-pr-maintenance
+  cancel-in-progress: false
+
+jobs:
+  maintain:
+    name: Review, repair, revalidate, and merge
+    permissions:
+      actions: write
+      checks: read
+      contents: write
+      id-token: write
+      pull-requests: write
+    uses: ContextualWisdomLab/.github/.github/workflows/pr-review-merge-scheduler.yml@f070c504c1cb06891b800d7ab0cf6ac7d3cf8eae

AGENTS.md

@@ -0,0 +1,44 @@
+# AGENTS.md
+
+## Mission
+
+TEPP is the Temporal Event Psychometrics Platform: a multilingual, temporal, relational measurement system that combines evidence-grounded language processing, event ontology, topic measurement, TDT/CHRONOS-style event reasoning, and longitudinal psychometrics.
+
+## Non-negotiable engineering contracts
+
+1. Production psychometric and mathematical arithmetic is implemented in Rust.
+2. Every estimator has a CPU `f64` reference path. Parallel CPU and GPU paths must demonstrate numerical parity against it.
+3. GPU execution is VRAM-budgeted, streamed, and able to fall back safely to CPU. OOM is an expected state, not an unhandled exception.
+4. Temporal modeling distinguishes event/valid time, assertion time, document time, system time, availability time, and knowledge cutoff. No analysis may use evidence whose availability time exceeds its cutoff.
+5. Forward state-transition and input-process-outcome edges never move backward in event time. Citation, revision, translation, and retrospective-reporting edges may point to the past but never become reverse state transitions.
+6. Models must support multilevel, cross-classified, and multiple-membership structures. Documents may simultaneously belong to authors, departments, customers, partners, competitors, projects, opportunity pools, templates, languages, and event episodes.
+7. Multilingual measurement uses one shared latent semantic space. Language-specific morphology and lexical emissions may vary, but equivalent meanings must be aligned and tested for measurement invariance.
+8. Production line and branch coverage are 100%. All public modules, traits, structs, enums, functions, methods, error variants, configuration fields, and safety contracts have complete docstrings.
+9. Scientific acceptance requires realistic synthetic truth: parameter recovery, RMSE, bias, interval coverage, temporal ordering, graph recovery, invariance, and CPU/GPU parity. Skipped or ignored GPU tests are not evidence.
+10. LLM live tests use `NVIDIA_NIM_API_KEY`. `COPILOT_GITHUB_TOKEN` is prohibited. Existing independent review-agent credentials must not be repurposed.
+11. LLM orchestration allocates test-time computation between direct routing and deeper multi-agent workflows. Workflow depth, decomposition, access lists, recursion, role-specific reasoning effort, and ablations are recorded.
+12. Database object names contain at least two words and use `snake_case` by default. CamelCase or PascalCase is permitted only where language conventions require it.
+13. Every scientific or standards claim is traced to an authoritative primary source and cited in APA 7th style in `docs/research/`.
+14. Changes that alter latent-variable meaning, temporal semantics, event ontology, multilingual invariance, or estimator targets require an ADR and PRD version change.
+
+## Repository architecture
+
+Use modular MSA boundaries. Each service or crate must work independently and through stable contracts when imported by CWL organization repositories, `naruon`, or `contextual-orchestrator`. Avoid hidden global state and repository-specific coupling.
+
+## Pull-request loop
+
+For every open PR:
+
+1. inspect unresolved reviews and exact-head checks;
+2. reproduce each actionable defect with a failing test;
+3. implement the smallest scientifically and architecturally valid fix;
+4. rerun focused and complete verification;
+5. update ADRs, architecture, references, CHANGELOG, and manifests;
+6. merge only after current-head required checks and independent approvals pass;
+7. re-enumerate the queue and continue.
+
+When the queue reaches zero, select one buyer-visible product gap, implement one bounded vertical slice, open a PR, and resume the same loop. Never bypass branch protection or claim queued checks have passed.
+
+## Release contract
+
+A release requires a clean PR queue, exact-head CI/security evidence, reproducible artifacts, SBOM and provenance, validated migrations, updated `CHANGELOG.md`, version consistency, rollback instructions, and no unresolved scientific or security blocker.

ARCHITECTURE.md

@@ -0,0 +1,74 @@
+# TEPP Architecture
+
+## Product definition
+
+TEPP is a Temporal Event Psychometrics Platform. It measures multilingual semantic evidence, links documents and event mentions through typed temporal relations, estimates shared latent topic and higher-order psychometric structures, and renders the resulting evidence, uncertainty, trajectories, and networks.
+
+```mermaid
+flowchart LR
+    A[Immutable documents and metadata] --> B[Evidence ingestion]
+    B --> C[Temporal and event normalization]
+    C --> D[Multilingual semantic units]
+    D --> E[Shared-latent temporal topic measurement]
+    C --> F[Typed document-event-entity graph]
+    E --> G[Posterior topic coordinates]
+    F --> G
+    G --> H[Longitudinal ESEM and DSEM]
+    G --> I[Topic and event networks]
+    H --> J[Evidence-grounded interpretation]
+    I --> J
+    J --> K[Accessible visual analytics and exports]
+```
+
+## Bounded services and Rust crates
+
+| Boundary | Primary responsibility |
+|---|---|
+| `evidence_ingestion` | immutable source bytes, hashes, layout, exact spans, metadata, provenance |
+| `temporal_core` | instants, intervals, uncertain dates, partial orders, bitemporal availability and leakage gates |
+| `event_ontology` | event mentions, event instances, roles, subevents, products, factors, places, and evidence links |
+| `relation_graph` | typed document, segment, event, entity, revision, translation, evidence, and transition edges |
+| `membership_model` | time-varying cross-classified and multiple-membership assignments |
+| `semantic_preprocessor` | Unicode, segmentation, morphology, dependency phrases, LLM span contracts, validation |
+| `concept_dictionary` | versioned multilingual concept alignment and unknown-concept review |
+| `topic_measurement` | shared-latent temporal/relational topic estimation and uncertainty |
+| `compute_backend` | CPU `f64`, fixed-pool multithreading, CUDA/WGPU, sparse streaming, VRAM budgeting |
+| `model_selection` | candidate K, predictive fit, coherence, exclusivity, stability, alignment, fairness, blinded LLM review |
+| `psychometric_core` | posterior-plausible-value ESEM, longitudinal invariance, DSEM, continuous-time paths |
+| `event_intelligence` | TDT segmentation/link/detection/first-story/tracking and CHRONOS schema reasoning |
+| `network_analysis` | log-ratio topic correlation, conditional networks, uncertainty, Leiden consensus clusters |
+| `interpretation_gateway` | evidence-bounded LLM interpretation, independent verification, routing and ablations |
+| `artifact_service` | model registry, manifests, JSON-LD, GraphML, Arrow/Parquet, tables, SVG/PDF exports |
+| `visual_analytics` | bitemporal lens, event graph, topic river, drift, ESEM/DSEM builder, invariance and leakage audit |
+
+Every boundary must be independently usable and expose versioned contracts for integration with organization repositories, `naruon`, and `contextual-orchestrator`.
+
+## Temporal invariants
+
+TEPP stores event/valid time, assertion time, document time, system time, available time, and knowledge cutoff independently. A historical analysis may include a document only when:
+
+\[
+\operatorname{available\_time}(d) \leq \operatorname{knowledge\_cutoff}.
+\]
+
+Forward transition edges require a temporally valid partial order. Retrospective, revision, translation, citation, support, and contradiction relations retain their direction and provenance but do not create reverse state transitions.
+
+## Measurement invariants
+
+All languages share global topic identities and latent document coordinates. Language-specific lexical emissions, morphology, script, and content deviations are modeled rather than forced to be identical. Validated, calibrated, provisional, and unresolved language profiles are reported separately.
+
+Repeated report vocabulary is modeled through corpus-background, template, section, style, copied-text, prompt, modality, and substantive-topic sources. It is not silently removed by stopword lists, TF-IDF, or BM25.
+
+Topic proportions are compositional. ESEM and network analysis consume logistic-normal latent coordinates or orthonormal log-ratio coordinates, with posterior uncertainty propagated through plausible values or a joint model.
+
+## Compute architecture
+
+The CPU `f64` implementation is the numerical reference. Rayon-style fixed worker pools and thread-local sufficient statistics minimize context switching and oversubscription. GPU work is streamed; temporary responsibilities are never retained for the full corpus. The VRAM controller estimates peak allocation, reserves a safety margin, autotunes micro-batches, records telemetry, reduces batches after OOM, and falls back to CPU safely.
+
+## Persistence
+
+PostgreSQL is the reference relational store. Database objects use two-or-more-word `snake_case` names, including `document_record`, `temporal_interval`, `event_instance`, `event_mention`, `document_relation`, `segment_relation`, `entity_role_assignment`, `model_run`, `topic_definition`, `topic_correlation`, `topic_cluster`, `factor_solution`, `validation_metric`, and `audit_event`.
+
+## Security and trust boundaries
+
+Documents and LLM outputs are untrusted. Exact spans, JSON Schema, size/depth limits, Unicode validity, prompt-injection isolation, provider allowlists, no-tool execution, tenant isolation, immutable audit events, dependency pinning, SBOM, provenance, and reproducible releases are mandatory. LLM live tests use `NVIDIA_NIM_API_KEY`; `COPILOT_GITHUB_TOKEN` is forbidden.

CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to TEPP are documented here. The format follows Keep a Changelog and semantic versioning once the first implementation release is cut.
+
+## [Unreleased]
+
+### Added
+
+- Approved Temporal Event Psychometrics Platform PRD v0.4 baseline.
+- Eight-phase delivery roadmap and Temporal/Event Foundation implementation plan.
+- Immutable evidence, six-clock temporal semantics, interval reasoning, event ontology, typed relation graph, and time-varying multiple-membership contracts.
+- Shared-latent multilingual topic measurement architecture with native lexical channels and language-profile validation.
+- Longitudinal ESEM/DSEM and continuous-time structural modeling requirements.
+- Rust-first CPU `f64`, multithreaded CPU, GPU, VRAM-adaptive streaming, and CPU/GPU parity requirements.
+- Topic correlation, consensus clustering, TDT, CHRONOS, and evidence-grounded LLM interpretation requirements.
+- APA 7th research traceability, source archive manifests, ADRs, governance, security, and contribution contracts.
+- Hourly centralized PR-maintenance workflow and a documented requirement for a future credential-separated NVIDIA NIM/OpenCode product-development loop.
+
+### Security
+
+- Prohibited `COPILOT_GITHUB_TOKEN` and reserved `NVIDIA_NIM_API_KEY` for approved LLM test and development workflows.
+- Removed the bootstrap branch's credential-co-resident OpenCode workflow: no model process may receive repository-write authority, and scheduled product development remains disabled until proposal, independent verification, and late publication authority are separated across fresh jobs.
+- Removed completed bootstrap materializers, encoded payload fragments, readiness sentinels, and push probes from the reviewable tree.
+- Required full-commit GitHub Action pins, minimum permissions, concurrency controls, immutable audit evidence, SBOM, and provenance.
+
+### Quality
+
+- Required 100% production line and branch coverage and complete public API docstrings.
+- Required true-parameter recovery, RMSE, bias, interval coverage, temporal leakage, graph recovery, invariance, and CPU/GPU parity evidence.
+
+[Unreleased]: https://github.com/ContextualWisdomLab/TEPP/compare/HEAD...HEAD

CLAUDE.md

@@ -0,0 +1,19 @@
+# CLAUDE.md
+
+Read and follow `AGENTS.md` before changing this repository. The repository-wide contracts in that file are normative.
+
+## Working method
+
+- Use test-driven development for every behavior change.
+- Keep changes bounded to one independently reviewable product or scientific slice.
+- Prefer explicit types and small modules with stable interfaces.
+- Preserve source spans, temporal provenance, uncertainty, and model-version metadata end to end.
+- Do not replace statistical estimation with an LLM judgment.
+- Do not convert association, temporal precedence, or document links into causal language without identification evidence.
+- Do not remove repeated report language with global stopword lists or use TF-IDF/BM25 as inferential weights. Model template, section, copied-text, style, modality, and corpus-background sources explicitly.
+- Do not treat raw topic proportions as ordinary Euclidean indicators. Use logistic-normal coordinates or valid log-ratio coordinates and propagate posterior uncertainty into ESEM/DSEM.
+- Never use future-available evidence in historical model fits.
+
+## Verification before completion
+
+Before stating that a task is complete, run the exact focused tests, complete test suite, line/branch coverage gate, docstring gate, formatter, linter, dependency/security checks, build/package checks, and any required CPU/GPU parity or true-parameter study. Report actual evidence and unresolved external gates.

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to TEPP
+
+## Before starting
+
+Read `AGENTS.md`, `ARCHITECTURE.md`, the approved PRD, relevant ADRs, and research references. A change is not ready merely because it compiles.
+
+## Change workflow
+
+1. Choose one bounded, buyer-visible or scientifically necessary vertical slice.
+2. Create an isolated branch or worktree.
+3. Write the failing unit, property, integration, simulation, or recovery test first.
+4. Confirm that the test fails for the intended reason.
+5. Implement the smallest valid change.
+6. Run focused tests, then complete verification.
+7. Update documentation, APA 7th references, ADRs, model manifests, schemas, migrations, and `CHANGELOG.md`.
+8. Open a pull request with source, assumptions, numerical tolerances, risks, rollback, and verification evidence.
+9. Address every actionable review thread and rerun checks on the resulting head.
+10. Merge only when required current-head checks and independent approvals pass.
+
+## Required verification
+
+As applicable, a PR must provide fresh evidence for:
+
+- Rust formatting, linting with warnings denied, compilation, and complete tests;
+- production line and branch coverage at 100%;
+- complete public API and safety-contract docstrings;
+- deterministic seeds and reproducibility manifest;
+- true-parameter RMSE, bias, interval coverage, convergence, and failure-rate studies;
+- temporal leakage and partial-order invariants;
+- multilevel/multiple-membership recovery and atomistic-fallacy safeguards;
+- multilingual alignment and measurement-invariance checks;
+- CPU `f64` versus parallel CPU/GPU numerical parity;
+- GPU execution without skipped tests and measured peak VRAM/fallback behavior;
+- database migrations, constraints, rollback, and two-word object naming;
+- dependency licenses, advisories, action pins, SBOM, provenance, and package/install smoke tests;
+- accessibility, exact-value tables, no-JavaScript/print exports, and visual regression where relevant.
+
+Monte Carlo acceptance thresholds must include Monte Carlo uncertainty rather than comparing a finite observed rate directly with its nominal target.
+
+## Research and documentation
+
+Use primary papers, international standards, official specifications, and official library documentation. Record APA 7th references in `docs/research/standards-and-literature.md` and link methodological claims to the exact section, equation, or requirement they support. Clearly distinguish replicated published methods, adaptations, and novel TEPP methods.
+
+## LLM development
+
+- Treat all model output as untrusted structured input.
+- Preserve exact source spans and evidence identifiers.
+- Use `NVIDIA_NIM_API_KEY` for approved live tests.
+- Never use or introduce `COPILOT_GITHUB_TOKEN`.
+- Record provider, model, prompt hash, reasoning effort, workflow depth, tools/access list, seed where supported, latency, token usage, and cost.
+- Include direct-routing versus orchestrated and reasoning-effort ablations.
+
+## Database naming
+
+Database objects use at least two words and `snake_case` by default, such as `document_record`, `event_instance`, `topic_definition`, and `audit_event`. Single-word object names are rejected.