# Session Metadata Schema in Council of High Intelligence: Complete Field Reference

> Explore the Session Metadata schema in the Council of High Intelligence. Learn about execution mode, token estimates, fallback triggers, and more appended to every verdict.

- Repository: [nyk/council-of-high-intelligence](https://github.com/0xNyk/council-of-high-intelligence)
- Tags: api-reference
- Published: 2026-06-30

---

**The Session Metadata schema tracks eleven telemetry fields—including execution mode, panel composition, token estimates, and fallback triggers—that the coordinator appends to every verdict in a grep-friendly YAML front-matter block.**

The Council of High Intelligence coordinator appends a standardized Session Metadata block to every verdict generated by the council. This schema version 1 implementation, defined in [`SKILL.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/SKILL.md), provides a fixed telemetry contract that downstream tooling, log aggregators, and validation pipelines can reliably parse from markdown output.

## Core Telemetry Fields

The Session Metadata schema captures operational data across three categories: session configuration, runtime behavior, and resource consumption. According to the specification in [`SKILL.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/SKILL.md) (lines 41-51), the coordinator populates the following fields:

### Session Configuration

- **`schema_version`** – Identifies the metadata format revision. Currently locked to `1` to ensure parser compatibility.
- **`mode`** – Indicates the execution mode employed: `full`, `quick`, `duo`, or `triad`. This determines the deliberation depth and consensus requirements.
- **`panel_size`** – The integer count of council members that participated in the deliberation round.
- **`rounds_run`** – The actual number of deliberation iterations executed before reaching a verdict.

### Operational Behavior

- **`chairman_failed_fallback`** – Boolean indicator (`yes`/`no`) showing whether the Chairman fallback logic triggered due to primary model failures.
- **`tools_used`** – Flag (`yes`/`no`) indicating whether auxiliary tools such as file read, grep, or URL fetch were invoked during the session.
- **`fallbacks_triggered`** – Comma-separated list of provider or model substitutions required during execution, or the string `"none"` if all primary models responded successfully.

### Resource Utilization

- **`input_tokens_estimate`** – Approximate token count processed as input (e.g., `~12k`), useful for cost estimation and capacity planning.
- **`output_tokens_estimate`** – Approximate token count generated in the response.
- **`duration_seconds`** – Rough wall-clock runtime of the session (e.g., `~30`).
- **`provider_count`** – Integer derived from [`detect-providers.sh`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/detect-providers.sh) representing the number of distinct model providers participating in the council.

## Schema Format and Validation

The Session Metadata block follows a strict markdown-native format. As documented in [`SKILL.codex.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/SKILL.codex.md) (lines 42-44), the block uses YAML front-matter delimited by `---` to enable easy redirection to log files and straightforward extraction via standard Unix tools.

The validation script [`scripts/council-simulation-checklist.sh`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/scripts/council-simulation-checklist.sh) enforces this contract. Lines 106-109 assert the presence of the metadata block and validate that `schema_version: 1` appears exactly as specified, failing the CI check if the coordinator omits or malforms the telemetry.

## Extracting Session Metadata

Because the schema uses standard YAML front-matter syntax, you can extract metadata from any verdict file without specialized parsers.

To isolate the block from a verdict:

```bash
grep -A12 '^schema_version:' verdict.md

```

To append metadata to a structured log:

```bash
grep -A12 '^schema_version:' verdict.md >> session-telemetry.log

```

### Example Metadata Block

When the coordinator emits a verdict, it appends a block matching this structure:

```markdown
---
schema_version: 1
mode: quick
panel_size: 3
rounds_run: 2
chairman_failed_fallback: no
tools_used: yes
input_tokens_estimate: ~8k
output_tokens_estimate: ~5k
duration_seconds: ~12
provider_count: 2
fallbacks_triggered: none
---

```

In a full verdict context, this appears after the deliberation content:

```markdown

## Full Council Verdict

### Problem

Should we add caching to the authentication layer?

### Vote Tally

...
---

schema_version: 1
mode: full
panel_size: 5
rounds_run: 3
chairman_failed_fallback: yes
tools_used: yes
input_tokens_estimate: ~15k
output_tokens_estimate: ~10k
duration_seconds: ~30
provider_count: 3
fallbacks_triggered: member→anthropic/claude-2, member→openai/gpt-4

```

## Summary

- The Session Metadata schema defines eleven standardized fields tracking configuration, operations, and resource usage.
- Schema version 1 is enforced by [`scripts/council-simulation-checklist.sh`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/scripts/council-simulation-checklist.sh) (lines 106-109) to guarantee parser compatibility.
- The format uses YAML front-matter delimiters for grep-ability and log aggregation.
- Key source files include [`SKILL.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/SKILL.md) (primary specification), [`SKILL.codex.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/SKILL.codex.md) (Codex mode variant), and the validation shell script.

## Frequently Asked Questions

### How do I extract Session Metadata from generated verdicts?

Use standard grep with context lines to capture the YAML block. The command `grep -A12 '^schema_version:' verdict.md` reliably extracts the entire metadata section because the schema mandates the `schema_version` field appear first in the block.

### What happens if the schema_version field is missing?

The validation script [`scripts/council-simulation-checklist.sh`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/scripts/council-simulation-checklist.sh) will fail the session check. Lines 106-109 explicitly assert the presence of `schema_version: 1`, ensuring that any coordinator output missing this marker gets rejected in CI pipelines.

### Which values are valid for the mode field?

The specification recognizes four execution modes: `full` (complete deliberation), `quick` (abbreviated consensus), `duo` (two-member panel), and `triad` (three-member panel). These values are documented in [`SKILL.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/SKILL.md) line 42 and affect how `panel_size` and `rounds_run` are interpreted.

### How is the provider_count field calculated?

The coordinator derives this value from the output of [`detect-providers.sh`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/detect-providers.sh), counting the number of distinct model providers (e.g., OpenAI, Anthropic, local inference) that successfully participated in the session, as specified in [`SKILL.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/SKILL.md) line 50.