Format Contracts

Overview

A format contract is the agreed shape of a file that flows between you and a command (or between two commands). Where a shape is enforced by a schema or a fixed template in the plugin, that schema or template is the source of truth — the examples below are grounded in it, not invented.

Quick spec

Consumed by: /gaia-quick-dev. Written by: /gaia-quick-spec. Canonical path: .gaia/artifacts/implementation-artifacts/quick-spec-{spec_name}.md.

A quick spec is a lightweight implementation plan with exactly five fixed sections, in this order: Summary, Files to change, Implementation steps, Acceptance criteria, and Risks. Do not add other sections — a developer (or /gaia-quick-dev) hands the file straight to implementation.

# Quick Spec: Add a --json flag to the report command

## Summary

Add a `--json` flag to `report` so it can emit machine-readable output for
CI consumption.

## Files to change

- src/cli.py — add the `--json` argument and branch the output formatter.
- tests/test_report.py — cover the JSON output path.

## Implementation steps

1. Add `--json` to the report argument parser.
2. Branch the formatter: JSON when the flag is set, table otherwise.
3. Add a test asserting valid JSON is emitted with `--json`.

## Acceptance criteria

- Running `report --json` prints valid JSON and exits 0.
- Running `report` without the flag prints the existing table output.

## Risks

- None known; the change is additive and the default path is unchanged.

The five-section template is defined in gaia-quick-spec/SKILL.md (Step 4 — Generate Quick Spec). The path convention is fixed; do not invent a different folder or filename.

Brownfield gap entry

Consumed by: the brownfield scan and consolidation flow. Canonical source: plugins/gaia/schemas/brownfield-gap-entry.schema.json (with a shipped example at plugins/gaia/tests/fixtures/brownfield-gap-entry-example.json).

A gap entry is a single JSON object describing one finding. The required fields are gap_id, category, severity, title, and evidence; the rest (claim_type, description, suggested_action, stack, aliases, confidence, metadata) are optional. Scan subagents emit an array of these objects, each validated per entry.

{
  "gap_id": "DC-001",
  "category": "doc-code-drift",
  "severity": "WARNING",
  "claim_type": "positive",
  "title": "README documents a --json flag the CLI no longer accepts",
  "description": "The README usage block lists `--json` as a supported flag, but the argument parser in cli.py has no such option.",
  "evidence": {
    "file": "README.md",
    "line_range": "57",
    "snippet": "Run `tool report --json` to emit machine-readable output.",
    "tool": "doc-code-scan"
  },
  "suggested_action": "Either restore the --json flag in cli.py or remove the stale README line.",
  "stack": "python"
}

Validate any candidate entry against the schema before relying on it. The schema is the source of truth for field names, allowed values, and which fields are required.

Execution evidence

Consumed by: test-execution review gates when the Test Execution Bridge is enabled. The execution-evidence file is a small JSON object the review gate inspects to decide whether a PASSED verdict is allowed:

{
  "exit_code": 0,
  "skipped": false,
  "suites": [
    { "name": "unit",        "fail_count": 0 },
    { "name": "integration", "fail_count": 0 }
  ]
}

The gate reads exit_code, suites[].fail_count (summed), and skipped, and refuses PASSED if the run was red or skipped. The full contract — every field, the refuse-conditions, and how to enable the bridge — is documented on the Test Execution Bridge page.

Related