> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joystream.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Reading the flag report

> How to read jstm agent conform output — lanes, severity, flag anatomy, JSON schema, and exit codes.

`jstm agent conform` prints one merged report. This page explains every part of it.

## Human output

```text theme={null}
Conformance: spec v05@84aa360f0d40ad5a68f56130cd0f431f397ac0203792b56a49afe6cff22d39ee
lanes: schema=ran spec_conflict=ran
  [error] SCHEMA_NAME_REQUIRED  (manifest.name)  id=a1edffb898bc138e7cbd8b41025af29e705519e8d05a31f6ecf0b7bb4d3ca10c
      name is missing
  [error] SPEC_CONFLICT_LIFECYCLE_DECLARED  (manifest.lifecycle)  id=7c2f…
      manifest declares the platform-managed deployment lifecycle state; lifecycle lives in .runtime/state/lifecycle.yaml, not the manifest
FAIL: schema=1 judge=0 spec_conflict=1 ignored=0 (exit 1)
```

Line by line:

* `Conformance: spec <id>` — the spec pack you were checked against, as `v05@<hash>`. The hash pins the exact spec content.
* `lanes: …` — which lanes ran. `ran` means it completed. `did_not_run` means it was filtered out or failed.
* One block per flag: `[severity] RULE_ID (target) id=…` followed by an indented rationale. The full `id` is printed so you can copy it into `--ignore <id>`.
* The verdict line: `PASS` or `FAIL`, a per-lane count, how many flags were ignored, and the exit code.

## Anatomy of a flag

Every flag, human or JSON, has the same fields.

| Field             | Meaning                                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `id`              | Stable structural identity: `sha256(rule_id + artifact_target + violation_class)`. Same across runs, so an ignore sticks. |
| `source`          | The lane that raised it: `schema`, `judge`, or `spec_conflict`.                                                           |
| `severity`        | `error` or `warning`. Drives the exit code.                                                                               |
| `rule_id`         | The catalog rule this flag instances, such as `SCHEMA_NAME_REQUIRED`.                                                     |
| `artifact_target` | The specific thing flagged, such as `manifest.name` or `purpose.md`.                                                      |
| `spec_anchor`     | The cited spec clause: `<file>.md#<heading-slug>`.                                                                        |
| `violation_class` | A machine code for the kind of violation.                                                                                 |
| `rationale`       | Plain-English explanation.                                                                                                |
| `related_targets` | Other targets the flag relates to.                                                                                        |

The `id` is deliberately keyed on stable structure, not wording. A semantic judge may rephrase its rationale run to run, but the rule, target, and violation class stay put — so the id stays put, and so does any acknowledgement you've made.

## Severity

Severity comes from the lane's default, which a spec rule can override:

* `schema` defaults to `error`, because it is authoritative.
* `judge` and `spec_conflict` default to `warning`, because they are advisory, unless the rule sets an override. The lifecycle spec conflict is one such override, at `error`.

Only flags at or above the `--fail-on` threshold, which defaults to `error`, affect the exit code. Warnings are always visible but non-fatal by default.

## JSON output

`--json` emits the full report as a single JSON line, for CI and tooling.

```json theme={null}
{
  "spec_pack": "v05@84aa360f…",
  "lanes_run": { "schema": "ran", "spec_conflict": "ran" },
  "flags": [
    {
      "id": "a1edffb8…",
      "source": "schema",
      "severity": "error",
      "rule_id": "SCHEMA_NAME_REQUIRED",
      "artifact_target": "manifest.name",
      "spec_anchor": "field-reference.md#identity",
      "violation_class": "missing_required_field",
      "rationale": "name is missing",
      "related_targets": []
    }
  ],
  "ignored": [],
  "summary": { "schema": 1, "judge": 0, "spec_conflict": 0, "ignored": 0 },
  "exit_code": 1,
  "lane_errors": {}
}
```

* `flags` — the active, un-ignored flags that count toward the verdict.
* `ignored` — flags suppressed by an acknowledgement. Only populated when you pass `--show-ignored`. Excluded from `summary` counts and the exit code.
* `summary` — per-lane active counts plus `ignored`.
* `lane_errors` — if a lane crashed, its error type is recorded here and the lane shows `did_not_run` in `lanes_run`.

## Exit codes

| Exit | Meaning                                                                                                                                                                                                                   |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`  | Pass. No un-ignored flag at or above `--fail-on`, and every required lane ran.                                                                                                                                            |
| `1`  | Fail. At least one blocking flag, or a required lane (`schema` or `spec_conflict`) was degraded so conformance can't be certified.                                                                                        |
| `2`  | Usage or input error. Package directory not found, an invalid flag value, an unknown `--source` lane, an unreadable allowlist, or a package the engine refused to read because it was oversized, symlinked, or malformed. |

<Warning>
  A required lane that doesn't run fails closed. If you filter the `schema` or `spec_conflict` lane out with `--source`, or it errors, the run cannot certify and exits `1` even with zero flags. "We didn't check" is never a pass.
</Warning>

With `--fail-on none`, flags become purely advisory: the run exits `0` regardless of severity, and only a degraded required lane still forces `1`.

## See also

* [Acknowledging flags](/features/conformance/ignores) — suppressing flags you've decided about.
* [`jstm agent conform`](/cli/agent-conform) — every flag.