From 29fa0faa1c39fecdd6bb3e514b18af1a06cb56fc Mon Sep 17 00:00:00 2001 From: PRAMOD B N Date: Fri, 7 Aug 2026 22:58:41 -0500 Subject: [PATCH] clarify conformance ownership --- README.md | 17 ++++++++++++++++- ROADMAP.md | 11 ++++++++++- 2 files changed, 26 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b2adb35..21e7199 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,9 @@ The **AI Operations Specification (AIOS)** is a vendor-neutral contract for desc It gives instrumentation, observability, evaluation, safety, and reliability tools a shared vocabulary and portable JSON artifacts for Runs, Steps, model interactions, tool calls, retrieval, memory, evaluations, signals, and incidents. This repository defines the contract. It does **not** run agents, collect telemetry, host dashboards, or provide an SDK. +It also does **not** own the primary end-user CLI for conformance checks; +implementation repositories may provide that convenience on top of the +normative rules defined here. ## Why it exists @@ -37,6 +40,13 @@ The work is cumulative, not four competing formats: Later layers depend on earlier ones. They are available for design feedback and prototype implementations; acceptance of a later layer does not bypass open review gates in an earlier layer. +Conformance should be understood in two layers: + +- **AIOS defines the normative rules**: schemas, conformance requirements, + canonical fixtures, and expected validation behavior +- **implementations may provide tooling**: for example, AgenticLens can expose + a practical `conformance` CLI over those rules without owning the standard + ## Choose a path - **Understand the model:** read the [v0.1 overview](specification/v0.1/README.md), [core concepts](specification/v0.1/core-concepts.md), and [conceptual examples](specification/v0.1/examples.md). @@ -94,6 +104,10 @@ uv run pytest AIOS defines shared meaning, relationships, events, and exchange artifacts. SDK behavior, dashboards, provider catalogs, recommendation logic, storage, and transport exporters belong in implementation repositories. +That same boundary applies to conformance: the specification owns the rules +and expected behavior, while implementation repositories may offer user-facing +commands that execute those checks. + See [SPECIFICATION.md](SPECIFICATION.md) for the complete reading order and maturity rules, or [CONTRIBUTING.md](CONTRIBUTING.md) to propose a change. ## What's Next @@ -103,7 +117,8 @@ Upcoming specification work (see [ROADMAP.md](ROADMAP.md)): - **Provenance and evidence concepts** — standardize source references, evidence lineage, and derived findings as first-class spec objects - **Conformance test suite** — producers can validate artifacts against the - spec independently + spec independently, while implementation repositories can expose convenient + CLIs on top - **Naming conventions** — lock down field naming rules, casing, and abbreviation policy - **Migration guides** — clear upgrade paths between spec versions diff --git a/ROADMAP.md b/ROADMAP.md index a604b18..04a64e1 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -91,6 +91,11 @@ Success means implementers can determine whether they may safely consume an arti Publish minimal and advanced canonical artifacts, namespace rules, third-party extension guidance, and conformance expectations. +The specification should define what conformance means, but it should not +require the specification repository itself to be the primary end-user entry +point for running those checks. Implementation repositories may expose +convenient CLIs as long as they follow the normative rules defined here. + ### Phase 6.x — Provenance, Evidence & Operational Artifacts Formalize concepts proven in implementation repositories. @@ -101,6 +106,9 @@ Formalize concepts proven in implementation repositories. lineage, and derived findings as first-class spec objects - conformance test suite — so producers can validate their artifacts against the spec without importing a DeepAgentLabs package +- conformance requirements, canonical fixtures, and expected validation + behavior — so implementations such as AgenticLens can offer user-facing + `conformance` commands without owning the standard - naming conventions document — lock down field naming rules, casing, singular/plural, abbreviation policy @@ -142,7 +150,8 @@ Specification milestone documents live under `specification/` and clearly state ## Package roles - `ai-operations-spec` defines the standard. -- `agenticlens` instruments and exports the standard. +- `agenticlens` instruments and exports the standard, and may provide + user-facing conformance tooling over AIOS-defined rules. - `agentic-chaos` adds resilience and fault-testing evidence using the same model. - `deep-agentic-core-mcp` reads, exposes, and transforms conforming artifacts.