Output formats¶
Commands print JSON (pretty-printed) or Markdown on stdout. Diagnostics, progress and model telemetry go to stderr, so stdout can always be parsed.
Draft documents¶
verlato draft json, the service's draft.get and the MCP verlato_get_draft_document return:
{
"version": "v1.1.0",
"generated_on": "2026-11-10",
"repository_url": null,
"base_ref": "v1.0.0",
"head_ref": "HEAD",
"targets": [
{"name": "changelog", "path": "CHANGELOG.md", "format": "changelog"},
{"name": "github-release", "path": ".github/release.md", "format": "github-release"}
],
"sections": [
{"kind": "added", "title": "Added", "items": [ "...draft items..." ]}
],
"rendered": {"changelog": "### v1.1.0 (2026-11-10)\n...", "github-release": "## v1.1.0 - 2026-11-10\n..."},
"item_count": 4
}
repository_url is the web URL of the origin remote, when it has one (the extension links
PRs, commits and files with it). Sections follow the order Breaking Changes, Added,
Changed, Deprecated, Removed, Fixed, Security, Documentation, Performance, Refactoring,
Tests, Build, Internal, Other.
Draft items¶
| Field | Meaning |
|---|---|
id |
stable item ID (ci_ + 12 hex digits) |
title, summary |
the entry; summary is the edited summary when there is one |
original_summary |
the generated summary |
summary_source, classification_source |
human-readable: where the summary and the classification came from |
evidence_summary |
one-line description of the changed-file evidence |
kind, area, audience, semver |
the classification (Concepts) |
confidence |
0 to 1 |
pr_number, commit_shas, base_ref, head_ref |
provenance |
files |
changed paths |
commit_signals |
signals behind the classification, such as conventional:fix, semantic:additive, semantic:api-break-candidate, diff-fallback |
derived_conventional_commits |
Conventional Commit metadata inferred for the item's commits |
grouping_reason |
why these commits form one changeset |
status, hidden |
the review status |
reviewed_by, reviewed_at, edited_summary |
the reviewer's decision |
summary_provenance |
for applied suggestions: provider, model, prompt hash, tone, style, response metadata and time |
diff_engine |
intentumdiff or git |
semantic |
the IntentumDiff review (below), or null with the git engine |
The semantic block¶
{
"engine": "intentumdiff",
"engine_version": "intentumdiff-core@1c4bdbc5dfbe",
"verdict": "additive",
"complete": true,
"files_reviewed": 1,
"files_unreviewed": 0,
"group_counts": {"MEANINGFUL_CHANGE": 4, "REFACTORING": 1, "NOISE_SUPPRESSED": 1},
"languages": ["python"],
"meaningful_files": ["src/taskboard/tasks.py"],
"style_only_files": [],
"refactor_only_files": [],
"added_symbols": ["overdue in src/taskboard/tasks.py"],
"removed_symbols": [],
"renamed_symbols": ["open_tasks -> pending in src/taskboard/tasks.py"],
"signature_changes": [],
"refactorings": ["RENAME_SYMBOL"],
"cross_file": [],
"guardrails": [],
"unreviewed": [],
"errors": [],
"notes": [],
"summary": "IntentumDiff semantic review: additive changes only; ...",
"extended_signatures": []
}
verdict is one of behavioral, additive, refactor-only, style-only and unreviewed
(see Semantic evidence).
Rendered Markdown¶
The github-release format (draft preview, render --format github-release):
## v1.1.0 - 2026-11-10
### Added
- Export a board as CSV. Added `export_csv` (PR #12).
### Fixed
- Rejected tasks with empty titles. Renamed `open_tasks` to `pending`; added `overdue` (possible breaking change).
Each entry is the item's summary followed by its PR. With summary_style: "evidence" an entry
reads - <title> (PR #12): <summary> instead, as in Verlato 0.1 (see
Summaries).
The changelog format uses ### v1.1.0 (2026-11-10) as the release heading. With
--include-confidence / --include-provenance, each entry ends with
[confidence 0.74; source v1.0.0..HEAD].
Other JSON documents¶
| Command | Shape |
|---|---|
scan, generate |
an array of change items as stored in state |
reconcile |
{"unpublished": [...items], "count": n} |
draft apply |
{"target", "path", "format", "action": "create" or "update", "bytes_written"} |
draft review |
the updated change item |
draft suggest --preview |
the run (provider, privacy, strategy, tone, performance, batch_count, ...) and per-item items with candidates, evidence and the audit record |
draft prompt |
the prompt, evidence, privacy record and audit (ai_request) for one item |
commit conventional |
header, body, message, type, scope, breaking, confidence, privacy, ai_request |
state show |
{"items": [...]}; the file itself (.verlato_state.json, schema_version: "v3") also holds feedback_events and area_release_lineage |
feedback export |
schema_version: "verlato.feedback.v1" and the events (or JSON lines) |
feedback recommend |
schema_version: "verlato.feedback_recommendations.v1" |
model-logs export |
schema_version: "verlato.model_logs.v1" |
doctor engine |
engine availability |
doctor ollama |
schema: "ollama_doctor.v1" |
doctor model |
schema: "model_doctor.v1" |
Stderr lines¶
These lines are a stable interface: the VS Code extension parses them.
[verlato:progress] json {"event":"progress","stage":"...","label":"...","current":1,"total":4,"unit":"item"}
[verlato:model] <message>
[verlato:model] json {"event":"prompt_built","attributes":{...},"message":"..."}
[verlato:suggestion] json {"event":"...", ...}
[verlato:progress] lines appear with VERLATO_TRACE_PROGRESS=1; [verlato:model] and
[verlato:suggestion] lines with VERLATO_TRACE_MODEL_CALLS=1. Event names and fields are
listed in Model telemetry.