Add review evidence pack and clarify draft milestone decisions

AGENTS.md

@@ -74,6 +74,15 @@ v0.1 (core concepts)
 5. Add validation test in `tests/`
 6. State maturity clearly in the document
 
+## Feature Completion Expectations
+
+- Every spec or schema behavior change must include tests or fixtures.
+- Normative or user-guiding changes must include or update realistic examples.
+- When a milestone item is completed or its status changes, update `README.md`
+  and `ROADMAP.md` in the same change.
+- When a change affects an earlier layer, also update dependent milestone
+  documents, schemas, fixtures, and tests before considering the work done.
+
 ## Pre-push Checklist
 
 Run `make check` before every push. It runs the schema validation tests.

CONTRIBUTING.md

@@ -15,6 +15,14 @@ AI Operations Specification contributions should improve interoperability for in
 
 A proposal SHOULD state the interoperability problem, affected concepts, compatibility impact, privacy implications, and at least one realistic example. Changes that affect an earlier layer MUST update dependent documents, schemas, fixtures, and tests in the same proposal.
 
+Feature completion expectations:
+
+- Every spec or schema behavior change must include tests or fixtures.
+- Normative or user-guiding changes should include or update realistic
+  examples in the same proposal.
+- If a roadmap or milestone item is completed or its status changes, update
+  `README.md` and `ROADMAP.md` in the same pull request.
+
 Do not mark an acceptance gate complete without recorded evidence. External review gates require evidence from an independent implementation or standard, not only internal agreement.
 
 ## Validation

MILESTONE_CLOSEOUT_PLAN.md

@@ -0,0 +1,194 @@
+# AIOS Milestone Close-Out Plan
+
+This document turns the current `v0.1` through `v0.4` draft milestones into a concrete path to reviewed completion.
+
+It does not change milestone status by itself. A milestone is complete only when its acceptance criteria, dependency gates, repo updates, and validation evidence are all closed.
+
+## Current baseline
+
+- Documented milestone chain:
+  - `v0.1` core concepts
+  - `v0.2` relationships
+  - `v0.3` semantic conventions
+  - `v0.4` JSON Schemas
+- Local validation baseline as of `2026-08-09`:
+  - `UV_CACHE_DIR=/tmp/uv-cache uv run pytest`
+  - `20 passed`
+- Immediate blocker pattern:
+  - most remaining work is review evidence, cross-document consistency, and independent implementation validation
+  - later milestones cannot freeze before earlier review gates close
+
+## Done criteria by milestone
+
+### v0.1
+
+Must close:
+
+- review definitions against at least two independent frameworks
+- record decisions and update all `v0.1` documents consistently
+- show that two independent implementers can classify the same runtime objects without package-specific knowledge
+
+Evidence package:
+
+- framework mapping notes for two independent frameworks
+- classification worksheet using shared runtime examples
+- maintainer decision log
+- consistency pass across `README.md`, `core-concepts.md`, `terminology.md`, `examples.md`, and `acceptance-criteria.md`
+
+### v0.2
+
+Must close:
+
+- validate the relationship vocabulary against at least two independent agent frameworks
+- confirm ordering and retry semantics
+- record decisions and update affected documents
+
+Evidence package:
+
+- graph reconstruction examples from the same scenario across two frameworks
+- explicit decisions for parent-child, causal order, retry attempt, branch, join, and loop semantics
+- updated examples and any test coverage needed for graph/document invariants
+
+### v0.3
+
+Must close:
+
+- validate conventions against OpenTelemetry design principles
+- validate event coverage against at least two reference implementations
+- decide whether transport mappings belong in separate implementation profiles
+- record decisions and update affected documents
+
+Evidence package:
+
+- event catalog review against OTel naming, cardinality, lifecycle, and extension principles
+- coverage matrix showing each runtime area is representable by canonical or extension events
+- written decision separating normative semantics from transport bindings
+
+### v0.4
+
+Must close:
+
+- resolve all open `v0.1` through `v0.3` review gates
+- validate artifacts produced by at least two independent implementations
+- review identifier, reference, extension, and unknown-value behavior
+- replace the draft version marker when the milestone freezes
+
+Evidence package:
+
+- artifact samples from at least two independent producers
+- validation outputs against current schemas
+- issue log for identifier/reference/extension edge cases
+- final schema/version marker update and fixture refresh
+
+## Workstreams
+
+## 1. Repo-internal work
+
+These items can be completed directly in `ai-operations-spec`.
+
+- normalize milestone language across `README.md`, `ROADMAP.md`, `SPECIFICATION.md`, and milestone READMEs
+- create or expand decision logs for unresolved reviewer questions
+- add scenario-based review worksheets for object classification, graph reconstruction, and semantic event coverage
+- add tests for any newly clarified document invariants or schema edge cases
+- add a review ledger documenting which acceptance gates are closed, by whom, and with what evidence
+
+## 2. Cross-project coordination
+
+These items need evidence from sibling repos in this workspace.
+
+- `agenticlens`
+  - export draft-conforming artifacts
+  - prove consumer and producer use of relationships, events, and schemas
+  - supply examples for findings, traces, and conformance-oriented validation
+- `agentic-chaos`
+  - exercise degraded, failed, retried, and recovered execution paths
+  - validate whether reliability and incident concepts are sufficient
+  - produce artifacts that stress event semantics and edge-case relationships
+- `mcp-server`
+  - validate consumer-side reading, transformation, and interoperability expectations
+  - verify artifact references and unknown-value handling in a control-plane style consumer
+
+## 3. Independent review work
+
+These items cannot honestly be self-certified inside this repo alone.
+
+- choose two non-DeepAgentLabs frameworks or implementers for external review
+- run the same scenario pack through both
+- compare concept classification results for `v0.1`
+- compare execution graph reconstruction results for `v0.2`
+- compare event semantics interpretation results for `v0.3`
+- compare schema artifact output and validation results for `v0.4`
+
+## Review sequence
+
+The fastest safe path is:
+
+1. Close `v0.1` first.
+2. Use the finalized `v0.1` vocabulary to tighten `v0.2`.
+3. Freeze `v0.3` only after `v0.2` ordering and retry semantics are explicit.
+4. Freeze `v0.4` last after artifact validation from independent producers.
+
+Doing `v0.2` through `v0.4` first would create churn because each later layer inherits names and boundaries from `v0.1`.
+
+## Proposed close-out checklist
+
+### Phase A: close the `v0.1` foundation
+
+- create a single review packet with:
+  - concept glossary
+  - boundary decisions
+  - three to five shared runtime scenarios
+- run the packet against two independent frameworks
+- capture disagreements and resolve naming or boundary ambiguity
+- update all `v0.1` docs together
+- mark `v0.1` review gates complete only after evidence is recorded
+
+### Phase B: lock `v0.2` execution semantics
+
+- derive graph examples from the same shared scenarios
+- write explicit rules for:
+  - ordering
+  - retries
+  - branches
+  - joins
+  - loops
+  - parent-child runs
+- validate equivalent graph reconstruction across two implementations
+- update relationship docs, examples, and any tests together
+
+### Phase C: lock `v0.3` semantics
+
+- produce a catalog review worksheet covering every runtime area
+- align event naming and extension guidance with OTel design principles
+- decide and document that transport mappings stay outside the core spec unless added as separate non-normative profiles
+- validate event coverage using artifacts from at least two implementations
+
+### Phase D: freeze `v0.4` schemas
+
+- generate artifacts from at least two independent producers
+- validate all artifacts against the schemas
+- add missing edge-case fixtures for identifiers, references, extensions, and unknown values
+- replace draft version markers only after `v0.1` through `v0.3` are closed
+
+## Recommended repo additions
+
+The repo would benefit from a small review infrastructure layer:
+
+- `reviews/decision-log.md`
+- `reviews/evidence-matrix.md`
+- `reviews/scenarios/`
+- `reviews/framework-mappings/`
+
+These would let the project prove why a milestone is reviewed instead of only claiming it.
+
+## Exit standard
+
+Do not mark `v0.1` through `v0.4` as done when only the prose looks complete.
+
+Mark them done only when:
+
+- the acceptance criteria are checked off
+- dependencies are closed in order
+- tests and fixtures pass
+- review evidence is committed in the repo
+- at least the required independent implementation validation is recorded

README.md

@@ -29,6 +29,27 @@ DeepAgentLabs stewards the specification today and is its sole editor. AgenticLe
 
 **Pre-release draft. Do not claim stable conformance.**
 
+## Release Status
+
+- **v0.1** 🏗️ In review — Core runtime concepts and boundaries
+- **v0.2** 🚧 Exploratory draft — Relationships and execution graphs
+- **v0.3** 🚧 Exploratory draft — Transport-neutral semantic events
+- **v0.4** 🚧 Exploratory draft — JSON Schema artifacts
+- **v0.5** 🚧 Planned — Versioning and compatibility rules
+- **v0.6** 🚧 Planned — Canonical examples and extension model
+- **v0.6.x** 🚧 Planned — Provenance, evidence, and operational artifacts
+- **v1.0** 🚧 Planned — Stable specification
+
+## Next Steps
+
+- Close the remaining v0.1 external review gate so later layers can move
+  toward freeze.
+- Validate the v0.4 draft artifacts against at least two independent
+  implementations.
+- Formalize versioning/compatibility rules and the extension model.
+- Standardize provenance/evidence concepts and publish producer-independent
+  conformance fixtures and rules.
+
 The work is cumulative, not four competing formats:
 
 | Layer | Defines | Status |

ROADMAP.md

@@ -1,5 +1,67 @@
 # AI Operations Specification Roadmap
 
+## Release Status
+
+- **v0.1** 🏗️ In review — Core runtime concepts and boundaries
+- **v0.2** 🚧 Exploratory draft — Relationships and execution graphs
+- **v0.3** 🚧 Exploratory draft — Transport-neutral semantic events
+- **v0.4** 🚧 Exploratory draft — JSON Schema artifacts
+- **v0.5** 🚧 Planned — Versioning and compatibility rules
+- **v0.6** 🚧 Planned — Canonical examples and extension model
+- **v0.6.x** 🚧 Planned — Provenance, evidence, and operational artifacts
+- **v1.0** 🚧 Planned — Stable specification
+
+## Next Steps
+
+- Resolve the remaining v0.1 review gate and keep later milestones clearly
+  labeled as draft until those dependencies close.
+- Prove the v0.4 draft against at least two independent producers and
+  consumers.
+- Define compatibility/versioning policy before claiming stable consumption
+  guarantees.
+- Promote provenance, evidence, and conformance fixtures from implementation
+  practice into spec-standard artifacts once the underlying model settles.
+
+## Cross-Project Dependencies
+
+AIOS is the normative specification, not an implementation package, but its
+roadmap still depends on evidence from sibling projects and independent
+implementers.
+
+- `agenticlens`
+  Provides real producer/consumer evidence for traces, findings, conformance
+  tooling, and schema usage.
+- `agentic-chaos`
+  Provides resilience and fault evidence that tests whether the model can
+  represent degraded, failed, and recovered behavior.
+- `deep-agentic-core-mcp`
+  Provides a consumer/control-plane view that exercises artifact validation and
+  interoperability across tools.
+
+For roadmap planning, distinguish:
+
+- `Depends on`: an earlier AIOS layer that must freeze first.
+- `Evidence from`: sibling repos or independent implementers that should
+  validate the design in practice.
+- `Coordinate with`: implementation repos that may need doc, fixture, or
+  terminology updates when the spec changes.
+
+## Definition of Done
+
+A roadmap item is done only when all applicable work is complete:
+
+- normative text is written with scope, boundaries, and maturity clearly
+  stated
+- examples, fixtures, and schema changes are added or updated together
+- tests validate the intended structure or document invariants
+- `README.md` and this roadmap are updated when milestone status or user
+  guidance changes
+- dependent milestone documents are updated when an earlier layer changes
+- implementation evidence or independent review is recorded for any acceptance
+  gate that requires it
+- draft, reviewed, and stable claims remain consistent across all milestone
+  documents
+
 ## Direction
 
 DeepAgentLabs builds the AI Operations Specification **specification-first**. The standard defines meaning before SDK ergonomics, exporter fields, dashboards, or integrations.
@@ -123,6 +185,15 @@ Formalize concepts proven in implementation repositories.
   document from canonical `aiops.*` events and common attributes to OTel
   spans, span events, and resource attributes, so producers already emitting
   OTel do not need to invent their own bridge independently
+- verification-signal schema — a standard shape for second-opinion/judge
+  results (verdict, confidence, evidence-grounding, safety concerns) as a
+  first-class signal object, once judge-output shapes stabilize across
+  implementation repos; candidate prior art: `devops-open-agent`'s
+  LLM-as-a-Judge verifier output
+- audit-event schema — a standard shape for who-did-what operational events
+  (actor, action, target artifact reference, timestamp, no secret values),
+  feeding the incident-context/operator-facing summary semantics above;
+  candidate prior art: `devops-open-agent`'s structured audit log
 
 Success means implementations can attach provenance to findings using
 spec-standard objects, and producers can run conformance checks independently.