diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..80f43f2 --- /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 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..69646c8 --- /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, probabilistic semantic 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..251c629 --- /dev/null +++ b/docs/project_source.md @@ -0,0 +1,102 @@ +# Project Source: CompText V7 + +## 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 + +## 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. + +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 +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. + +## 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.