# Data Contract

## 1. Machine-Readable Format

Use JSON for machine-readable data.

Model JSON files own the model asset state, including `status`, `regression_status`, and `stability_profile.stability_level`.

Main JSON objects:

- Model spec
- Source article
- Source excerpt
- Regression case
- Selector example
- Model index

## 2. Human-Readable Format

Use Markdown for:

- Model cards
- Project documentation
- Extraction notes
- Validation reports
- Handoff reports

## 3. Model Spec Contract

Every model JSON should include:

- `model_id`
- `model_name`
- `model_type`
- `pipeline_position`
- `one_sentence_definition`
- `core_question`
- `core_mechanism`
- `status`
- `source_articles`
- `source_evidence`
- `input_types`
- `output_types`
- `call_when`
- `do_not_call_when`
- `common_misuses`
- `failure_modes`
- `selection_priority`
- `confidence_level`
- `stability_profile`
- `regression_status`
- `output_contract`
- `structured_output_contract`
- `productization_notes`

`structured_output_contract` is model-specific. It must not turn QPI-only or Intellectual-Archaeology-only runtime fields into global top-level required fields for every model.

Model-specific required runtime output fields are checked by `scripts/validate_model_library.py`.

## 4. Source Article Contract

Every source article should include:

- `source_id`
- `title`
- `source_type`
- `related_models`
- `source_status`

Optional:

- `author`
- `date`
- `file_path`
- `notes`

## 5. Source Excerpt Contract

Every source excerpt should include:

- `excerpt_id`
- `source_id`
- `related_model_id`
- `excerpt_type`
- `summary`
- `used_for`

Optional:

- `raw_excerpt`
- `confidence`
- `notes`

## 6. Regression Case Contract

Every regression case should include:

- `case_id`
- `model_id`
- `case_type`
- `input`
- `expected_behavior`
- `failure_signal`

Optional:

- `expected_output_elements`
- `should_call_model`
- `expected_primary_model`
- `negative_expected_models`
- `expected_classification`
- `expected_dominant_scarcity`
- `expected_max_depth`
- `minimum_required_elements`
- `forbidden_elements`
- `evaluation_mode`
- `notes`

## 7. Reference Integrity

The following references must be valid:

- `model.source_articles` -> `sources/source_articles.json`
- `model.source_evidence` -> `sources/source_excerpts.json`
- `regression_case.model_id` -> `models/*.model.json`
- `source_excerpt.source_id` -> `sources/source_articles.json`
- `source_excerpt.related_model_id` -> `models/*.model.json`

## 8. Index Integrity

`models/model_index.json` is generated or checked from model JSON, card files, source references, and regression cases.

`cards/card_index.md` is the human-readable projection of `models/model_index.json`.

Indexes must not drift from model state, source/evidence counts, regression case counts, or card file existence.

## 9. Content Stabilization Integrity

Engineering validation does not imply content stability.

Before content stabilization review, every core model should have at least 15 regression cases and field-level evidence coverage.

Source excerpts must distinguish exact quotes from condensed or paraphrased excerpts with `quote_status`.

## 10. Local CCRA Review Run Contract

Local CCRA review runs are process records, not model assets.

They live under:

```text
local_ccra_reviews/<public-round>/<local-pass>/
```

Each local pass should contain:

- `run-notes.md`
- `review-metadata.json`
- `gate-manifest.yaml`
- `lifecycle-guard-config.yaml`
- `agent-invocation-packet.md`
- `prompt-to-send.md`
- `turn-prompts/`
- `review-context.md`
- `review-file-manifest.json`
- `helper-outputs/`
- `04_LOCAL_CCRA_REVIEW_REPORT.md`
- `next-review-requirements.md`
- `returned-output.md`
- `findings-confirmation.md`
- `owner-decision.md`

`review-metadata.json`, `review-file-manifest.json`, and helper JSON outputs are machine-readable process records.

Markdown files in the run directory are human-readable process records.

`04_LOCAL_CCRA_REVIEW_REPORT.md` is the `review_turn` judgment output.

`next-review-requirements.md` is the same-child `planning_turn` output and should not be treated as Owner approval or proof that a patch worked.

For Local CCRA v0.1.2 and later, `review-metadata.json` or `agent-invocation-packet.md` must declare:

- `bundle_audit_profile`: `ccra_mindscape_review_bundle`, `generic`, or `not_applicable`.
- `gate_execution_mode`: `dry_run`, `run`, `owner_waived`, or `not_applicable`.
- `routing_diff_policy`: `required`, `skipped_no_after_evidence`, `manual_equivalent_required`, or `not_applicable`.
- `lifecycle_scan_scope`: `current_review_bundle`, `changed_files`, `knowledge_assets`, `model_library_state`, or `whole_repo`.

`returned-output.md` should include the compact Owner-facing summary defined by CCPE v0.1.2, including evidence limitations for the four fields above.

`findings-confirmation.md` is a Chinese Owner-facing decision aid written by the Codex main session after Local CCRA outputs exist. It should extract only core confirmation items, proposed decision states, repair scope, impact, and evidence paths. It must not replace the full Local CCRA report or invent findings that are not grounded in `04_LOCAL_CCRA_REVIEW_REPORT.md`, `next-review-requirements.md`, or `returned-output.md`.

Allowed decision states in `findings-confirmation.md` and `owner-decision.md` are:

- `accept_for_codex_fix`
- `reject`
- `defer_to_future_round`
- `escalate_to_web_ccra`
- `owner_clarification_required`
- `accept_as_known_limit`

Codex may implement only findings recorded as `accept_for_codex_fix` in `owner-decision.md`.

Local CCRA review records must not become source of truth for model status, selector behavior, regression cases, or source evidence. Accepted actions must be applied back to the canonical project files and validated there.

Formal Web CCRA upload bundles exclude the Local CCRA report by default unless the owner explicitly asks to include it.

## 11. Round Conductor Process Records

Round automation process records are not model assets.

Round charters and conductor summaries should live under `reports/` and should reference the relevant Local CCRA pass directories rather than copying reviewer outputs wholesale.

Recommended round charter filename:

```text
reports/RoundNN_round_conductor_charter_YYYY-MM-DD.md
```

Round Conductor records may describe:

- public round label;
- Owner / Web CCRA guidance source;
- in-scope files or asset areas;
- non-goals;
- Local CCRA pass paths;
- Owner decision gates;
- accepted repair items;
- deferred or escalated items;
- validation and before/after behavior evidence;
- Web bundle readiness.

Round Conductor records must not override canonical project files. If a finding changes model state, selector behavior, regression cases, model cards, or evidence records, that change must be applied to the canonical file and validated there.