docs(examples): add batch multi-query example 08 and synchronize documentation (ticket-057)

CHANGELOG.md

@@ -34,6 +34,13 @@
 - Implement Batch Multi-Query comparison engine and CLI subcommand (ticket-054).
 - Implement Query Template Generator and CLI subcommand (ticket-055).
 - Implement Markdown report formatting for CLI and batch operations (ticket-056).
+- Create Batch Example 08 and synchronize root documentation (ticket-057).
+
+### Batch example 08 & root documentation sync (ticket-057)
+
+- Create `examples/08-batch-multi-query/` runnable example suite for multi-query batch comparison and Markdown report generation.
+- Update `examples/README.md` index table with Example 08.
+- Synchronize root `README.md` reflecting 10 implemented source adapters, CLI subcommands, and Subactor integration.
 
 ### Markdown report formatting (ticket-056)
 

README.md

@@ -184,17 +184,26 @@ repository require that repository's owner-approved workflow.
 
 ## Current state
 
-- Phases 0 through 4 are complete with governed ticket evidence (49 tickets).
-- Nine source adapters are implemented: GitHub/Diagit commit metrics,
+- Phases 0 through 5 are complete with governed ticket evidence (56 tickets).
+- Ten source adapters are implemented: GitHub/Diagit commit metrics,
   Markdown claim extraction (via `mdflow`), Code2Logic (CFG/DFG),
   Code2Schema (entity/CQRS), Curllm (browser-backed BQL sources),
   Planfile (SDLC task queues and ticket statuses), Deta (infrastructure
   topologies and services), IntentContract (Subactor DSL v1 contracts),
-  and OQL Telemetry (`oqlos.telemetry` hardware scenario & sensor logs).
+  OQL Telemetry (`oqlos.telemetry` hardware scenario & sensor logs), and
+  SUMD (Structured Unified Markdown tables & descriptor blocks).
 - The deterministic comparator supports `integer`, `string`, `string-set`,
   `float`, and `percentage` metrics, producing `MATCH`, `CONFLICT`, `MISSING_LEFT`,
   `MISSING_RIGHT` and `UNEVALUABLE` outcomes with typed deltas and SHA-256
   evidence chains.
+- Multi-query batch comparison engine (`src/data2dsl_batch.py`) aggregates
+  summary metrics (`clean_ratio`, `is_clean`, missing/conflict breakdowns) and
+  formats Markdown comparison reports.
+- Query template generator (`src/data2dsl_generator.py`) automates canonical
+  `query/v0` creation across all 10 source adapter kinds.
+- Full Subactor standard conformance is implemented (`src/data2dsl_subactor.py`)
+  with semantic delegation envelope validation (`COMM-*` error codes) and
+  closed-loop self-healing (`DETECT` $\to$ `PLAN` $\to$ `EXECUTE` $\to$ `VERIFY` $\to$ `HEAL`).
 - Dedicated autonomous agent feedback feeds are implemented:
   - `data2dsl_doctor.py` (`DiagnosticProfileFormatter`): Generates prioritized
     diagnostic profiles and symptom severity triage for `subactor/doctor-agent`.
@@ -204,20 +213,21 @@ repository require that repository's owner-approved workflow.
 - Pipeline integration includes `if-uri`/`urirun` connector manifest
   (`data2dsl://` routes) and Model Context Protocol (MCP) JSON-RPC 2.0 STDIO
   server endpoints.
-- Architecture decisions (ADR-001 through ADR-006) and capability maps document
+- Architecture decisions (ADR-001 through ADR-007) and capability maps document
   multi-source pipelines and ecosystem integration points.
 - The CLI provides `compare`, `compare-golden`, `validate`, `feed-consumer`,
-  `feed-doctor`, and `feed-koru` subcommands.
+  `feed-doctor`, `feed-koru`, `validate-envelope`, `simulate-healing`, `batch`,
+  and `generate-query` subcommands with `--format markdown|json` support.
 - The consumer fact feed is integrated with `semcod/todo2code` while preserving
   strict separation of factual acquisition from reasoning.
 - The comparison contract `autogrammar.data2dsl.comparison` v`0.1.0` is stable
   and validated against `wellmanifest/dsl` profiles.
 - The `Data2DslSkill` agent tool interface conforms to `wellmanifest.skills/v1`
-  and exposes `data2dsl_compare`, `data2dsl_self_test`, and `data2dsl_feed_doctor`
-  for agent discovery.
-- Testing infrastructure includes `conftest.py`, 57 unit tests (100% passing),
+  and exposes `data2dsl_compare`, `data2dsl_self_test`, `data2dsl_feed_doctor`,
+  `data2dsl_validate_envelope`, and `data2dsl_simulate_healing` for agent discovery.
+- Testing infrastructure includes `conftest.py`, 84 unit tests (100% passing),
   and clean `ruff`/`mypy` baselines.
-- Runnable example suites are structured under [`examples/`](examples/README.md).
+- Eight runnable example suites are structured under [`examples/`](examples/README.md).
 - Docker bootstrap uses a pinned SHA-256 base image and the deterministic
   governance gate passes.
 

TODO.md

@@ -306,6 +306,12 @@ Analiza ekosystemu `semcod/*` (56 pakietów), `subactor/*` (75 modułów),
 - [x] **Flaga `--format` w CLI**: Dodanie opcji `markdown` / `json` do komend `compare` i `batch` w `src/data2dsl_cli.py`. — ticket-056
 - [x] **Zestaw testów jednostkowych i CLI**: Rozszerzenie `tests/test_batch_compare.py` (84/84 testów przechodzi). — ticket-056
 
+### Przykład wsadowy 08 i synchronizacja dokumentacji (workstream: `integration`, ticket-057)
+
+- [x] **Pakiet `examples/08-batch-multi-query/`**: Utworzenie gotowego pakietu demonstracyjnego z fixtures i instrukcją. — ticket-057
+- [x] **Aktualizacja `examples/README.md`**: Włączenie Przykładu 08 do indeksu przykładów. — ticket-057
+- [x] **Synchronizacja głównego `README.md`**: Uzupełnienie opisów 10 adapterów, subkomend CLI, generatora i Subactora. — ticket-057
+
 
 
 

examples/08-batch-multi-query/README.md

@@ -0,0 +1,36 @@
+# Example 08: Batch Multi-Query Evaluation and Markdown Reporting
+
+This example demonstrates how to evaluate a batch collection of formal queries against heterogeneous observation sets in a single deterministic execution using `data2dsl batch`.
+
+## Files in this example
+
+- `queries.json`: Array of query objects (`autogrammar.data2dsl/query/v0`) covering ticket completions and test coverage.
+- `left-observations.json`: Observed records from internal build sources (Planfile and CI).
+- `right-observations.json`: Observed records from authoritative external systems (GitHub Pull Requests and CI Audit).
+
+## CLI Execution
+
+### 1. JSON Report Output
+```bash
+python src/data2dsl_cli.py batch \
+  --queries examples/08-batch-multi-query/queries.json \
+  --left examples/08-batch-multi-query/left-observations.json \
+  --right examples/08-batch-multi-query/right-observations.json
+```
+
+### 2. Formatted Markdown Report
+```bash
+python src/data2dsl_cli.py batch \
+  --queries examples/08-batch-multi-query/queries.json \
+  --left examples/08-batch-multi-query/left-observations.json \
+  --right examples/08-batch-multi-query/right-observations.json \
+  --format markdown
+```
+
+## Expected Behavior
+
+- **Total Queries**: 2
+- **Matches**: 2
+- **Conflicts**: 0
+- **Clean Ratio**: 100.0% (`is_clean`: true)
+- **Exit code**: `0`

examples/08-batch-multi-query/left-observations.json

@@ -0,0 +1,70 @@
+[
+  {
+    "schema": "autogrammar.data2dsl/observation/v0",
+    "observation_id": "observation:planfile:tickets",
+    "query_id": "query:batch:tickets_completed",
+    "side": "left",
+    "subject": {
+      "repository": "https://github.com/autogrammar/data2dsl",
+      "actor": "antigravity"
+    },
+    "metric": {
+      "id": "tickets_completed",
+      "version": "1.0.0",
+      "value_kind": "integer",
+      "unit": "tickets"
+    },
+    "window": {
+      "start": "2026-08-01T00:00:00Z",
+      "end": "2026-08-27T00:00:00Z",
+      "semantics": "half-open-utc"
+    },
+    "state": "OBSERVED",
+    "value": {
+      "kind": "integer",
+      "value": "56"
+    },
+    "evidence": [
+      {
+        "evidence_id": "evidence:planfile:1",
+        "digest_sha256": "4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a",
+        "source_uri": "file:///project/TICKETS.md",
+        "source_revision": "sha256:4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a"
+      }
+    ]
+  },
+  {
+    "schema": "autogrammar.data2dsl/observation/v0",
+    "observation_id": "observation:ci:coverage",
+    "query_id": "query:batch:test_coverage",
+    "side": "left",
+    "subject": {
+      "repository": "https://github.com/autogrammar/data2dsl",
+      "actor": "antigravity"
+    },
+    "metric": {
+      "id": "test_coverage",
+      "version": "1.0.0",
+      "value_kind": "percentage",
+      "unit": "percent"
+    },
+    "window": {
+      "start": "2026-08-01T00:00:00Z",
+      "end": "2026-08-27T00:00:00Z",
+      "semantics": "half-open-utc"
+    },
+    "state": "OBSERVED",
+    "value": {
+      "kind": "percentage",
+      "value": "100.0%"
+    },
+    "evidence": [
+      {
+        "evidence_id": "evidence:ci:coverage:1",
+        "digest_sha256": "ef2d127de37b942baad06145e54b0c619a1f22327b2ebbcfbec78f5564afe39d",
+        "source_uri": "file:///coverage.xml",
+        "source_revision": "sha256:ef2d127de37b942baad06145e54b0c619a1f22327b2ebbcfbec78f5564afe39d"
+      }
+    ]
+  }
+]

examples/08-batch-multi-query/queries.json

@@ -0,0 +1,66 @@
+[
+  {
+    "schema": "autogrammar.data2dsl/query/v0",
+    "query_id": "query:batch:tickets_completed",
+    "subject": {
+      "repository": "https://github.com/autogrammar/data2dsl",
+      "actor": "antigravity"
+    },
+    "metric": {
+      "id": "tickets_completed",
+      "version": "1.0.0",
+      "value_kind": "integer",
+      "unit": "tickets"
+    },
+    "window": {
+      "start": "2026-08-01T00:00:00Z",
+      "end": "2026-08-27T00:00:00Z",
+      "semantics": "half-open-utc"
+    },
+    "left_source": {
+      "id": "source:planfile",
+      "kind": "planfile"
+    },
+    "right_source": {
+      "id": "source:github",
+      "kind": "github"
+    },
+    "comparison": {
+      "equality": "exact",
+      "delta_direction": "right-minus-left",
+      "missing_is_zero": false
+    }
+  },
+  {
+    "schema": "autogrammar.data2dsl/query/v0",
+    "query_id": "query:batch:test_coverage",
+    "subject": {
+      "repository": "https://github.com/autogrammar/data2dsl",
+      "actor": "antigravity"
+    },
+    "metric": {
+      "id": "test_coverage",
+      "version": "1.0.0",
+      "value_kind": "percentage",
+      "unit": "percent"
+    },
+    "window": {
+      "start": "2026-08-01T00:00:00Z",
+      "end": "2026-08-27T00:00:00Z",
+      "semantics": "half-open-utc"
+    },
+    "left_source": {
+      "id": "source:ci",
+      "kind": "ci"
+    },
+    "right_source": {
+      "id": "source:audit",
+      "kind": "audit"
+    },
+    "comparison": {
+      "equality": "percentage-exact",
+      "delta_direction": "right-minus-left",
+      "missing_is_zero": false
+    }
+  }
+]

examples/08-batch-multi-query/right-observations.json

@@ -0,0 +1,70 @@
+[
+  {
+    "schema": "autogrammar.data2dsl/observation/v0",
+    "observation_id": "observation:github:tickets",
+    "query_id": "query:batch:tickets_completed",
+    "side": "right",
+    "subject": {
+      "repository": "https://github.com/autogrammar/data2dsl",
+      "actor": "antigravity"
+    },
+    "metric": {
+      "id": "tickets_completed",
+      "version": "1.0.0",
+      "value_kind": "integer",
+      "unit": "tickets"
+    },
+    "window": {
+      "start": "2026-08-01T00:00:00Z",
+      "end": "2026-08-27T00:00:00Z",
+      "semantics": "half-open-utc"
+    },
+    "state": "OBSERVED",
+    "value": {
+      "kind": "integer",
+      "value": "56"
+    },
+    "evidence": [
+      {
+        "evidence_id": "evidence:github:api:1",
+        "digest_sha256": "8f3b232ce9a3d4626154b5dfd4f6ef1e47f7d1b3e6e8e89fbc07e265c02b3df4",
+        "source_uri": "https://api.github.com/repos/autogrammar/data2dsl/pulls?state=closed",
+        "source_revision": "sha256:8f3b232ce9a3d4626154b5dfd4f6ef1e47f7d1b3e6e8e89fbc07e265c02b3df4"
+      }
+    ]
+  },
+  {
+    "schema": "autogrammar.data2dsl/observation/v0",
+    "observation_id": "observation:audit:coverage",
+    "query_id": "query:batch:test_coverage",
+    "side": "right",
+    "subject": {
+      "repository": "https://github.com/autogrammar/data2dsl",
+      "actor": "antigravity"
+    },
+    "metric": {
+      "id": "test_coverage",
+      "version": "1.0.0",
+      "value_kind": "percentage",
+      "unit": "percent"
+    },
+    "window": {
+      "start": "2026-08-01T00:00:00Z",
+      "end": "2026-08-27T00:00:00Z",
+      "semantics": "half-open-utc"
+    },
+    "state": "OBSERVED",
+    "value": {
+      "kind": "percentage",
+      "value": "100.0%"
+    },
+    "evidence": [
+      {
+        "evidence_id": "evidence:audit:report:1",
+        "digest_sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
+        "source_uri": "https://audit.ci/reports/latest",
+        "source_revision": "sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"
+      }
+    ]
+  }
+]

examples/README.md

@@ -13,6 +13,7 @@ This directory provides simple, runnable examples demonstrating the multi-source
 | **05** | [`05-mcp-tool-dispatch`](05-mcp-tool-dispatch/) | JSON-RPC 2.0 / MCP | Invoking `data2dsl_compare` over Model Context Protocol (MCP). |
 | **06** | [`06-closed-loop-self-healing`](06-closed-loop-self-healing/) | Subactor Envelope & Closed Loop | Complete 5-stage closed loop (`DETECT` -> `PLAN` -> `EXECUTE` -> `VERIFY` -> `HEAL`) with envelope validation. |
 | **07** | [`07-sumd-table-comparison`](07-sumd-table-comparison/) | SUMD Tables vs Telemetry | Factual extraction from Structured Unified Markdown Document tables and deterministic comparison. |
+| **08** | [`08-batch-multi-query`](08-batch-multi-query/) | Multi-Query Batch & Markdown | Batch evaluation of multiple queries against observation pools with clean ratio aggregation and Markdown report formatting. |
 
 ## Running Examples with CLI
 

project/TICKETS.md

@@ -61,4 +61,5 @@ analysis-generated `project/README.md`.
 | **ticket-054** | [`README.md`](./ticket-054/README.md) | [`preprompt.md`](./ticket-054/preprompt.md) | - |  [`ai-antigravity.md`](./ticket-054/ai-antigravity.md) |  [`ai-antigravity-logs.txt`](./ticket-054/ai-antigravity-logs.txt) | [`changelog.md`](./ticket-054/changelog.md) |
 | **ticket-055** | [`README.md`](./ticket-055/README.md) | [`preprompt.md`](./ticket-055/preprompt.md) | - |  [`ai-antigravity.md`](./ticket-055/ai-antigravity.md) |  [`ai-antigravity-logs.txt`](./ticket-055/ai-antigravity-logs.txt) | [`changelog.md`](./ticket-055/changelog.md) |
 | **ticket-056** | [`README.md`](./ticket-056/README.md) | [`preprompt.md`](./ticket-056/preprompt.md) | - |  [`ai-antigravity.md`](./ticket-056/ai-antigravity.md) |  [`ai-antigravity-logs.txt`](./ticket-056/ai-antigravity-logs.txt) | [`changelog.md`](./ticket-056/changelog.md) |
+| **ticket-057** | [`README.md`](./ticket-057/README.md) | [`preprompt.md`](./ticket-057/preprompt.md) | - |  [`ai-antigravity.md`](./ticket-057/ai-antigravity.md) |  [`ai-antigravity-logs.txt`](./ticket-057/ai-antigravity-logs.txt) | [`changelog.md`](./ticket-057/changelog.md) |
 <!-- AUTO:TICKET_INDEX:END -->

project/ticket-056/README.md

@@ -2,7 +2,7 @@
 
 - **ID**: ticket-056
 - **Owner**: unresolved:human
-- **Status**: IN_PROGRESS
+- **Status**: PLAN
 - **Workflow state**: PUBLICATION
 - **Created**: 2026-08-27
 - **Receipt**: Implemented format_markdown_report and added --format flag to compare and batch CLI subcommands; 84/84 pytest tests passing and GOV-PASS.

project/ticket-057/README.md

@@ -0,0 +1,27 @@
+# Ticket 057: Batch Example 08 and Root Documentation Synchronization
+
+- **ID**: ticket-057
+- **Owner**: unresolved:human
+- **Status**: PLAN
+- **Workflow state**: PUBLICATION
+- **Created**: 2026-08-27
+- **Receipt**: Created examples/08-batch-multi-query, updated examples/README.md and root README.md; 84/84 pytest tests passing and GOV-PASS.
+
+## Goal and scope
+
+Synchronize examples and documentation:
+1. Create `examples/08-batch-multi-query/` featuring complete runnable fixtures (`queries.json`, `left-observations.json`, `right-observations.json`, `README.md`).
+2. Update `examples/README.md` with index of all 8 example suites.
+3. Update root `README.md` with comprehensive documentation of CLI commands (`compare`, `batch`, `generate-query`, `validate-envelope`, `simulate-healing`), 10 source adapters, and Subactor integration.
+4. Verify all tests pass cleanly and deterministic governance gate passes (`GOV-PASS`).
+
+## Acceptance criteria
+
+- [x] AC-01: `examples/08-batch-multi-query/` contains runnable test fixtures and execution instructions.
+- [x] AC-02: `examples/README.md` and root `README.md` document all current features, CLI options, and architecture.
+- [x] AC-03: Full pytest test suite and governance check pass (`GOV-PASS`).
+
+## Participants
+
+- Human participant: unresolved; no user-* file was created by this script.
+- Agent participant: [ai-antigravity.md](ai-antigravity.md)