wantsong
/
the-mindscape-of-bro-tsong
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
the-mindscape-of-bro-tsong/docs/DATA_CONTRACT.md

4.4 KiB
Raw Blame History

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
  • 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.

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.