From 326868bb651702e38f0321ca1989ef03c72e20eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6lnberger?= <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 20 May 2026 12:16:36 -0700 Subject: [PATCH 1/4] docs: add central project source and scope governance --- CONTRIBUTING.md | 48 ++++++++++++++++++ NON_GOALS.md | 25 ++++++++++ docs/project_source.md | 109 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 182 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 NON_GOALS.md create mode 100644 docs/project_source.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c2dedea --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,48 @@ +# Contributing to CompTextv7 + +CompTextv7 accepts focused changes that preserve deterministic replay-integrity validation boundaries. + +## PR Scope Checklist +- [ ] This improves deterministic replay-integrity validation or is strictly maintenance-only. +- [ ] No runtime orchestration added. +- [ ] No LLM judge added. +- [ ] No embeddings/vector search added. +- [ ] No fuzzy semantic matching added. +- [ ] No cloud dependency added to validation logic. +- [ ] No dashboard/SaaS behavior added. +- [ ] No hidden platform expansion. +- [ ] Artifacts were regenerated if fixture or validator semantics changed. +- [ ] The evidence index was updated or confirmed unchanged if committed evidence artifacts changed. +- [ ] Tests were added or updated for new artifact or contract behavior. +- [ ] Taxonomy labels were reused, or new labels are explicitly justified. +- [ ] The change preserves offline reproducibility. +- [ ] The change does not require an RFC, or an RFC is linked. + +## Non-Goals Checklist +Before requesting review, confirm the change does **not** introduce: +- agent framework behavior +- runtime orchestration behavior +- tool routing platform behavior +- LLM judging +- embeddings/vector retrieval +- probabilistic semantic-vibes evaluation +- cloud-only validation dependencies +- dashboard/SaaS product scope + +## Artifact Regeneration Expectations +If fixture semantics, validator logic, or artifact-producing contracts change, regenerate required artifacts and include the resulting deterministic outputs in the PR. + +## Determinism Requirements +All validation behavior in core must remain deterministic, offline-capable, and reproducible from committed inputs and scripts. + +## Taxonomy / Failure-Label Rules +Reuse existing registered failure labels whenever possible. New labels require explicit justification, narrow definitions, and matching tests/docs updates. + +## RFC Requirement for Scope-Changing Proposals +Any proposal that expands scope beyond deterministic replay-integrity validation requires an accepted RFC before implementation. + +## Merge Policy Summary +Keep PRs small, focused, and auditable. Separate governance/docs updates from core logic changes. Core logic updates require tests and green CI before merge readiness. + +## Evidence-Index Reminder +If committed evidence artifacts change, the evidence index must be updated or explicitly confirmed unchanged with rationale in the PR. diff --git a/NON_GOALS.md b/NON_GOALS.md new file mode 100644 index 0000000..94dc3d2 --- /dev/null +++ b/NON_GOALS.md @@ -0,0 +1,25 @@ +# NON_GOALS + +CompTextv7 must not become: +- an agent framework +- a runtime orchestrator +- a tool router +- a memory platform +- a vector database layer +- a semantic summary evaluator +- an LLM judge +- a cloud observability dashboard +- a live monitoring SaaS +- an autonomous repair system +- a prompt optimization framework +- a generic AI governance platform + +Hard scope test: + +“Does this improve deterministic replay-integrity validation for compressed operational traces without adding probabilistic judgment, orchestration behavior, runtime dependency, cloud dependency, semantic-vibes evaluation, or platform expansion?” + +The default answer to scope-expanding proposals is rejection. + +Integrations belong outside core unless proven necessary through the RFC process. + +Runtime adapters, dashboards, and cloud services are not core project goals. diff --git a/docs/project_source.md b/docs/project_source.md new file mode 100644 index 0000000..bec7272 --- /dev/null +++ b/docs/project_source.md @@ -0,0 +1,109 @@ +# Project Source: CompTextv7 + +## Canonical Positioning +“CompTextv7 is the deterministic replay-integrity layer for compressed operational agent traces.” + +## Strategic Category +CompTextv7 is a deterministic replay-integrity validation research prototype. + +## Core Thesis +The core project question is: + +“Can a compressed agent state still reproduce a safe operational trajectory?” + +The governing research direction is: + +“Deterministic Replay Integrity Validation for Compressed Operational Agent Traces” + +## Research Alignment Principle +Every accepted change must strengthen deterministic, offline, reproducible replay-integrity validation for compressed operational traces, or be strictly maintenance-only. + +## Current Strategic State +The project remains: +- offline +- deterministic +- artifact-first +- trace-native +- reproducible +- narrowly scoped +- audit-oriented + +## State After PR #155 and PR #156 +After PR #155, the existing `mcp_trace_replay` fixture family was hardened via explicit capability-boundary structures, deterministic degraded variants, `failure_label_on_violation` handling, regenerated artifacts, and preserved scope by avoiding runtime/orchestration/LLM/embedding/fuzzy behavior. + +After PR #156, a deterministic artifact evidence index was added to map committed evidence artifacts to their generators, evidence categories, fixture-family coverage, manifest alignment, deterministic evaluation status, LLM-free status, and external-API-free status. + +## Non-Goals +CompTextv7 does not pursue: +- runtime agent orchestration +- autonomous runtime tool routing +- probabilistic semantic judging +- LLM judging +- embeddings or vector retrieval layers +- cloud-first observability platforms +- generalized AI governance platform expansion + +## 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. + +## Scope Evolution & RFC Process +Scope-expanding proposals require an RFC before implementation. RFCs must: +1. define the exact replay-integrity gain, +2. prove deterministic and offline reproducibility, +3. show no hidden orchestration/platform expansion, +4. describe artifact and failure-taxonomy implications, +5. include rollback/de-scope criteria. + +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. + +## Preferred Terminology +Prefer: +- deterministic replay-integrity validation +- compressed operational traces +- artifact evidence +- failure taxonomy and labels +- capability boundary +- offline reproducibility + +Avoid vague or marketing abstractions that hide deterministic constraints. + +## Roadmap From Here +1. Expand deterministic replay-integrity 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. + +## Merge Policy +- 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. + +## PR Template Additions +PR descriptions should explicitly confirm: +- deterministic replay-integrity alignment, +- non-goals preserved, +- artifact regeneration expectations, +- evidence-index impact (updated or unchanged), +- RFC status when scope is touched. + +## Strategic Risk Register +1. **Platform drift risk**: accidental expansion into orchestration/platform scope. +2. **Determinism erosion risk**: introduction of probabilistic evaluation paths. +3. **Evidence integrity risk**: artifact changes without corresponding evidence/governance updates. +4. **Terminology drift risk**: ambiguous framing that weakens enforceable boundaries. + +## Governance Stance +Governance is conservative, boundary-enforcing, and evidence-led. CompTextv7 accepts incremental improvements over broad platform ambitions. + +## Current Priority Stack +1. Deterministic replay-integrity 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. From 95051f34efc7c96b441639f4bfa3153da89a61a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6lnberger?= <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 20 May 2026 12:28:04 -0700 Subject: [PATCH 2/4] docs: address governance review comments --- docs/project_source.md | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/docs/project_source.md b/docs/project_source.md index bec7272..251c629 100644 --- a/docs/project_source.md +++ b/docs/project_source.md @@ -1,4 +1,4 @@ -# Project Source: CompTextv7 +# Project Source: CompText V7 ## Canonical Positioning “CompTextv7 is the deterministic replay-integrity layer for compressed operational agent traces.” @@ -28,20 +28,13 @@ The project remains: - narrowly scoped - audit-oriented -## State After PR #155 and PR #156 -After PR #155, the existing `mcp_trace_replay` fixture family was hardened via explicit capability-boundary structures, deterministic degraded variants, `failure_label_on_violation` handling, regenerated artifacts, and preserved scope by avoiding runtime/orchestration/LLM/embedding/fuzzy behavior. +## Current Implementation State +The `mcp_trace_replay` fixture family is hardened via explicit capability-boundary structures, deterministic degraded variants, and `failure_label_on_violation` handling. -After PR #156, a deterministic artifact evidence index was added to map committed evidence artifacts to their generators, evidence categories, fixture-family coverage, manifest alignment, deterministic evaluation status, LLM-free status, and external-API-free status. +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. ## Non-Goals -CompTextv7 does not pursue: -- runtime agent orchestration -- autonomous runtime tool routing -- probabilistic semantic judging -- LLM judging -- embeddings or vector retrieval layers -- cloud-first observability platforms -- generalized AI governance platform expansion +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. From a6987f3df1a07e34a0da3f70b87ec4a11e2c8f3f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6lnberger?= <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 20 May 2026 12:28:15 -0700 Subject: [PATCH 3/4] docs: replace informal scope terminology --- NON_GOALS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/NON_GOALS.md b/NON_GOALS.md index 94dc3d2..69646c8 100644 --- a/NON_GOALS.md +++ b/NON_GOALS.md @@ -16,7 +16,7 @@ CompTextv7 must not become: Hard scope test: -“Does this improve deterministic replay-integrity validation for compressed operational traces without adding probabilistic judgment, orchestration behavior, runtime dependency, cloud dependency, semantic-vibes evaluation, or platform expansion?” +“Does this improve deterministic replay-integrity validation for compressed operational traces without adding probabilistic judgment, orchestration behavior, runtime dependency, cloud dependency, probabilistic semantic evaluation, or platform expansion?” The default answer to scope-expanding proposals is rejection. From f8e6465925e64a6e7154c164d1be72868e132b77 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6lnberger?= <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 20 May 2026 12:28:29 -0700 Subject: [PATCH 4/4] docs: replace informal contributing terminology --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c2dedea..80f43f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,7 +25,7 @@ Before requesting review, confirm the change does **not** introduce: - tool routing platform behavior - LLM judging - embeddings/vector retrieval -- probabilistic semantic-vibes evaluation +- probabilistic semantic evaluation - cloud-only validation dependencies - dashboard/SaaS product scope