the-mindscape-of-bro-tsong/docs/DATA_CONTRACT.md

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:

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:

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.