Every conformant assessment MUST produce a report in the format described below. Assessors MAY produce richer output, but the minimum fields MUST be present, well-formed, and accurately describe the assessment.

Required fields

The minimum report schema in YAML:

standard_version: '1.0' # The CARL Standard version referenced.
subject:
  type: repository # repository | application | organization
  identifier: your-org/your-repo # Stable identifier for the subject.
  commit_hash: 5581990 # Git SHA of the state assessed.
assessed_at: 2026-04-22T14:03:11Z # ISO-8601 timestamp.
assessor:
  name: 'CARL Scan (claude-opus-4-7)' # Human-readable assessor identifier.
  type: ai-assisted # deterministic | ai-assisted | human | mixed
  version: '1.0.0' # Assessor version. Model ID included for AI.
level_achieved: 3 # 1-5 per §4 of the standard.
pillar_scores: # Floats in [0, 1] per pillar.
  documentation: 0.86
  codeQuality: 0.92
  testing: 0.73
  buildEnvironment: 0.80
  observability: 0.67
  security: 0.81
  taskIntakeRouting: 0.58
  deliveryMeasurement: 0.64
criteria: # Per-criterion result.
  - id: DOC-030 # Criterion ID from the catalog.
    pillar: documentation
    level: 2
    result: pass # pass | fail | not_applicable
    rationale: AGENTS.md present with Stack, Conventions, and Commands sections.
    evidence_summary: Found AGENTS.md at repo root with 7 headings.
  # ... remaining criteria ...
ai_assisted_variance: 0.015 # Optional; SHOULD be < 0.02 per §6.2.
remediation: # Prioritized remediation suggestions.
  - criterion_id: TST-040
    text:
      Raise coverage thresholds in vitest.config.ts to 80% across branches,
      functions, lines, statements.
    severity: high
    effort_estimate: S # S < 1hr, M 1-4hr, L 4-8hr, XL > 1 day.

Field requirements

standard_version

The CARL Standard version the report claims conformance against. MUST be a version that is currently Ratified or Superseded at the time of the report. A report against a Candidate or Working Draft version is NOT a conformance claim; it is a preview.

subject

• type — the subject granularity per §4.3.
• identifier — a stable identifier for the subject, e.g. vercel/next.js for a GitHub repository, or vercel/next.js:packages/next for an application scope.
• commit_hash — the Git SHA (7-40 hex chars) of the state assessed. This is the most important single field for reproducibility.

assessed_at

ISO-8601 timestamp. Assessors SHOULD use UTC (Z suffix) to avoid timezone ambiguity.

assessor

• name — human-readable identifier. Include the model name for AI-assisted assessors so the report's provenance is clear.
• type — one of deterministic, ai-assisted, human, mixed. See assessment methodology.
• version — the assessor's own version string. Include the model identifier for AI-assisted assessors.

level_achieved

An integer from 1 to 5. MUST be computed from the 80% gating rule in §4.2, not asserted independently.

pillar_scores

Per-pillar pass rate as a float in [0, 1]. Eight keys, one per pillar, in the JSON naming above (documentation, codeQuality, testing, buildEnvironment, observability, security, taskIntakeRouting, deliveryMeasurement).

criteria

An array of per-criterion results. Every criterion evaluated MUST appear. Each entry MUST have a stable id, a pillar, a level, a result, a rationale, and an evidence_summary.

ai_assisted_variance

Optional but SHOULD be present for ai-assisted and mixed assessors. A float in [0, 1] representing the fraction of AI-assisted criteria whose result differs across repeated evaluations on a fixed fixture. The standard recommends variance below 0.02.

remediation

An array of prioritized remediation suggestions produced from failing or weak criteria. Each entry MUST reference a criterion_id from the criteria array, a user-facing text, a severity (critical | high | medium | low | info), and an effort_estimate (S | M | L | XL).

JSON Schemas (normative)

The minimum field set is expressed formally as JSON Schema in the monorepo at prompts/schemas/. The reference implementations validate against these schemas:

• carl-scan.schema.json
• carl-review-team.schema.json
• carl-review-solo.schema.json

Assessors MUST produce output that validates against the appropriate schema. Consumers MAY reject non-conformant reports.

Reproducibility

A CARL report is designed to be reproducible in the sense that the same commit, assessed by the same assessor version against the same catalog version, should produce the same level and same pillar scores. AI-assisted assessments carry variance; that variance is disclosed in ai_assisted_variance.

A report that cannot be reproduced is not a useful conformance claim; consumers SHOULD treat a report whose commit hash no longer exists in the subject with caution, and MUST treat a report against a withdrawn standard version as not currently conformant.

Related

• JSON Schema reference — the per-field schema with prose explanation.
• Conformance claims — what a published claim looks like.