From 3dde3e90014f8cb1c86fe56944683799927b7303 Mon Sep 17 00:00:00 2001 From: ProfRandom92 Date: Sun, 24 May 2026 22:16:55 +0200 Subject: [PATCH 1/2] Align project docs with replay validation scope --- docs/project_source.md | 34 ++++++++++++++++++---------------- docs/validation.md | 15 ++++++++++----- pyproject.toml | 2 +- 3 files changed, 29 insertions(+), 22 deletions(-) diff --git a/docs/project_source.md b/docs/project_source.md index 251c629..c630fa0 100644 --- a/docs/project_source.md +++ b/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 traces, or be strictly maintenance-only. ## Current Strategic State The project remains: @@ -29,6 +29,8 @@ The project remains: - audit-oriented ## Current Implementation State +Current implemented surfaces include curated agent trace fixtures in `tests/fixtures/agent_traces/`, the deterministic replay runner in `tests/utils/agent_trace_replay_runner.py`, the 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`, and the 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 +39,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 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 +52,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 +75,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 +95,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 traces, it should not merge into core. diff --git a/docs/validation.md b/docs/validation.md index 4a71b57..3f97b6a 100644 --- a/docs/validation.md +++ b/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. diff --git a/pyproject.toml b/pyproject.toml index 5079de7..9dbe1fc 100644 --- a/pyproject.toml +++ b/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"] From d00c54d1677abdb49322ab6fc8352231d1eefc38 Mon Sep 17 00:00:00 2001 From: ProfRandom92 Date: Sun, 24 May 2026 22:41:06 +0200 Subject: [PATCH 2/2] Address PR review comments on project source docs --- docs/project_source.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/project_source.md b/docs/project_source.md index c630fa0..55df856 100644 --- a/docs/project_source.md +++ b/docs/project_source.md @@ -16,7 +16,7 @@ The governing research direction is: “Deterministic replay validation for compact operational agent/MCP traces” ## Research Alignment Principle -Every accepted change must strengthen deterministic, offline, reproducible replay validation for compact 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,7 +29,14 @@ The project remains: - audit-oriented ## Current Implementation State -Current implemented surfaces include curated agent trace fixtures in `tests/fixtures/agent_traces/`, the deterministic replay runner in `tests/utils/agent_trace_replay_runner.py`, the 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`, and the KVTC-V7 technical-log compression prototype in `src/core/kvtc_v7.py`. +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. @@ -39,7 +46,7 @@ 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 validation for compact 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: @@ -101,4 +108,4 @@ Governance is conservative, boundary-enforcing, and evidence-led. CompTextv7 acc 4. Scope-bound documentation and review discipline. ## One-Sentence Rule -If a change does not directly improve deterministic replay validation for compact 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.