Align project docs with replay validation scope (#216)

* Align project docs with replay validation scope

* Address PR review comments on project source docs

---------

Co-authored-by: ProfRandom92 <akoelnberger92@gmail.com>

Author: ProfRandom92

docs/project_source.md

@@ -1,22 +1,22 @@
 # Project Source: CompText V7
 
 ## Canonical Positioning
-“CompTextv7 is the deterministic replay-integrity layer for compressed operational agent traces.”
+“CompText V7 is a deterministic replay-validation prototype for compact operational agent/MCP traces, with a KVTC-V7 technical-log compression prototype.”
 
 ## Strategic Category
-CompTextv7 is a deterministic replay-integrity validation research prototype.
+CompText V7 is a deterministic replay-validation research prototype.
 
 ## Core Thesis
 The core project question is:
 
-“Can a compressed agent state still reproduce a safe operational trajectory?”
+“Can compact operational trace state still reproduce a safe replay trajectory?”
 
 The governing research direction is:
 
-“Deterministic Replay Integrity Validation for Compressed Operational Agent Traces”
+“Deterministic replay validation for compact operational agent/MCP traces”
 
 ## Research Alignment Principle
-Every accepted change must strengthen deterministic, offline, reproducible replay-integrity validation for compressed operational traces, or be strictly maintenance-only.
+Every accepted change must strengthen deterministic, offline, reproducible replay validation for compact operational agent/MCP traces, or be strictly maintenance-only.
 
 ## Current Strategic State
 The project remains:
@@ -29,6 +29,15 @@ The project remains:
 - audit-oriented
 
 ## Current Implementation State
+Current implemented surfaces:
+- curated agent trace fixtures in `tests/fixtures/agent_traces/`
+- deterministic replay runner in `tests/utils/agent_trace_replay_runner.py`
+- MCP replay payload layer in `src/comptext_v7/mcp/`
+- evidence survival helpers in `src/validation/evidence.py`
+- replay failure labels in `src/validation/replay_failure_classifier.py`
+- committed artifacts such as `artifacts/agent_trace_replay_results.json`
+- KVTC-V7 technical-log compression prototype in `src/core/kvtc_v7.py`
+
 The `mcp_trace_replay` fixture family is hardened via explicit capability-boundary structures, deterministic degraded variants, and `failure_label_on_violation` handling.
 
 A deterministic artifact evidence index maps committed evidence artifacts to their generators, evidence categories, fixture-family coverage, manifest alignment, deterministic evaluation status, LLM-free status, and external-API-free status.
@@ -37,11 +46,11 @@ A deterministic artifact evidence index maps committed evidence artifacts to the
 See `NON_GOALS.md` in the repository root for the full list of prohibited expansion paths and the hard scope test.
 
 ## Hard Scope Rule
-A proposal is out of scope unless it directly improves deterministic replay-integrity validation for compressed operational traces without introducing probabilistic or platform-expansion behavior.
+A proposal is out of scope unless it directly improves deterministic replay validation for compact operational agent/MCP traces without introducing probabilistic or platform-expansion behavior.
 
 ## Scope Evolution & RFC Process
 Scope-expanding proposals require an RFC before implementation. RFCs must:
-1. define the exact replay-integrity gain,
+1. define the exact replay-validation gain,
 2. prove deterministic and offline reproducibility,
 3. show no hidden orchestration/platform expansion,
 4. describe artifact and failure-taxonomy implications,
@@ -50,21 +59,21 @@ Scope-expanding proposals require an RFC before implementation. RFCs must:
 Default decision for scope-expanding proposals is rejection until the RFC is accepted.
 
 ## Correct Abstraction Level
-CompTextv7 focuses on replay-integrity contracts, trace-derived artifacts, fixture families, deterministic validators, and auditable evidence outputs. It does not absorb adjacent runtime or product-platform responsibilities.
+CompText V7 focuses on replay contracts, trace-derived artifacts, fixture families, deterministic validators, and auditable evidence outputs. It does not absorb adjacent runtime or product-platform responsibilities.
 
 ## Preferred Terminology
 Prefer:
-- deterministic replay-integrity validation
-- compressed operational traces
+- deterministic replay validation
+- compact operational agent/MCP traces
 - artifact evidence
 - failure taxonomy and labels
 - capability boundary
 - offline reproducibility
 
-Avoid vague or marketing abstractions that hide deterministic constraints.
+Avoid vague or marketing abstractions that hide deterministic constraints. Do not frame the repository as industrial, enterprise-ready, production-ready, certification-grade, showcase-first, or a cognitive fabric.
 
 ## Roadmap From Here
-1. Expand deterministic replay-integrity fixture coverage.
+1. Expand deterministic replay-validation fixture coverage.
 2. Strengthen artifact-evidence traceability and reproducibility checks.
 3. Improve contract-level validation clarity and failure classification precision.
 4. Add narrowly scoped capabilities only via approved RFC.
@@ -73,11 +82,11 @@ Avoid vague or marketing abstractions that hide deterministic constraints.
 - Documentation-only governance changes should stay small and focused.
 - Core logic changes must include targeted tests.
 - No merge-ready state until CI is green and review threads are resolved/outdated.
-- Keep docs, showcase, and core refactors separated.
+- Keep unrelated docs, demos, and core refactors separated.
 
 ## PR Template Additions
 PR descriptions should explicitly confirm:
-- deterministic replay-integrity alignment,
+- deterministic replay-validation alignment,
 - non-goals preserved,
 - artifact regeneration expectations,
 - evidence-index impact (updated or unchanged),
@@ -93,10 +102,10 @@ PR descriptions should explicitly confirm:
 Governance is conservative, boundary-enforcing, and evidence-led. CompTextv7 accepts incremental improvements over broad platform ambitions.
 
 ## Current Priority Stack
-1. Deterministic replay-integrity correctness.
+1. Deterministic replay-validation correctness.
 2. Artifact evidence traceability.
 3. Failure-label clarity and consistency.
 4. Scope-bound documentation and review discipline.
 
 ## One-Sentence Rule
-If a change does not directly improve deterministic replay-integrity validation for compressed operational traces, it should not merge into core.
+If a change does not directly improve deterministic replay validation for compact operational agent/MCP traces, it should not merge into core.

docs/validation.md

@@ -21,10 +21,6 @@ convenience. It does not define workspaces, dependencies, or a root Node app.
 The dashboard remains the only Node application in this repository, with its
 dependency management in `dashboard/app`.
 
-The embedded showcase was removed from Comptextv7 and is maintained separately
-in `ProfRandom92/comptext-v7-monaco-showcase`. Historical Comptextv7 showcase
-files are preserved on the `archive/showcase-before-extraction` branch.
-
 Root npm scripts use `npm --prefix` to delegate to the dashboard directory and
 use `pytest` for Python validation. No root `node_modules` directory or root npm
 dependencies are required for the wrapper itself.
@@ -67,7 +63,7 @@ npm run smoke:release-health
 Use these commands for dashboard TypeScript changes, release-health UI changes,
 and `dashboard/app/src/core/foundation/` modules.
 
-## Python validation from the repository root
+## Python replay validation from the repository root
 
 Run Python tests from the repository root:
 
@@ -80,6 +76,12 @@ pytest tests/test_paper_replay_bench.py tests/test_agent_trace_replay.py tests/t
 The focused replay command validates the deterministic paper replay, agent trace
 replay, and replay continuity surfaces without changing benchmark logic.
 
+Agent trace replay is fixture-bound: curated traces live in
+`tests/fixtures/agent_traces/`, the deterministic runner is
+`tests/utils/agent_trace_replay_runner.py`, and committed replay output is stored
+in `artifacts/agent_trace_replay_results.json`. Validation is local and does not
+use embeddings, vector databases, LLM judges, or external APIs.
+
 Install the Python test dependency set:
 
 ```bash
@@ -93,3 +95,6 @@ python tests/utils/paper_replay_runner.py
 python tests/utils/agent_trace_replay_runner.py
 python benchmarks/run_replay_continuity.py --iterations 250 --output-dir reports/replay_continuity
 ```
+
+The KVTC-V7 technical-log compressor in `src/core/kvtc_v7.py` is a deterministic
+prototype, not a production-readiness or certification claim.

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "comptextv7"
 version = "0.1.0"
-description = "CompText V7 Cognitive Fabric prototype"
+description = "Deterministic replay-validation prototype for compact operational agent/MCP traces"
 requires-python = ">=3.11"
 license = "Apache-2.0"
 license-files = ["LICENSE"]