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

File Taxonomy

Date: 2026-06-17

Status: accepted

1. Purpose

This document defines file identities for the model_library_mvp phase.

The goal is to prevent every generated report, review bundle, cache, and model asset from being treated as the same kind of artifact.

docs/KNOWLEDGE_ASSET_RULES.md governs one specific category: long-term reusable knowledge assets.

This document is broader. It governs the whole repository.

2. File Identity Classes

Every meaningful file should fit one of four classes:

Class	Meaning	Default retention	Examples
Canonical source of truth	Files that define model/library behavior or reviewed content	Keep and version	models/*.model.json, cards/*.md, sources/*.json, tests/*.regression.json, selector/*.json, schemas/*.json, operative docs/*.md
Generated / derived	Files rebuilt or checked from canonical assets	Keep when useful, rebuild at handoff/release	models/model_index.json, cards/card_index.md, reports/validation_report.md, reports/index_rebuild_report.md, reports/model_card_sync_report_v0.2.md, reports/selector_regression_report_v0.2.md
Review archive	Per-round evidence for Owner / CCRA / GPT review	Keep by round, do not treat as runtime truth	ccra_review_bundle/round-*, reports/Codex*.md, reports/GPT*.md, reports/model_case_preprocessing/*
Temporary / local runtime	Caches or local command byproducts	Do not commit	__pycache__/, *.pyc, temporary extraction folders, ad hoc local scratch files

3. Canonical Source Of Truth

Canonical files answer:

What is the current model/library behavior?
What is the reviewed source or contract?
What should code and future agents trust?

Canonical files include:

• model JSON specs under models/;
• human-readable cards under cards/;
• source records and evidence excerpts under sources/;
• regression source files under tests/*.regression.json;
• selector rules and calibration files under selector/;
• schemas under schemas/;
• operative rules and protocols under docs/;
• stable explanatory assets under knowledge_assets/.

Canonical files should be edited deliberately and validated after change.

4. Generated / Derived Files

Generated files answer:

What did the current canonical assets produce when checked or rebuilt?

They may be committed when they are part of the file-first workflow, but they are not independent truth.

Examples:

• models/model_index.json
• cards/card_index.md
• tests/regression_cases.json
• reports/validation_report.md
• reports/index_rebuild_report.md
• reports/model_card_sync_report_v0.2.md
• reports/selector_regression_report_v0.2.md
• reports/selector_calibration_smoke_report.md

Rules:

• Rebuild indexes after model/card/source/test changes.
• Regenerate reports after validation or selector checks.
• Do not manually edit generated reports to hide validation failure.
• If generated output disagrees with canonical source, fix the source or generator, then regenerate.

5. Review Archive Files

Review archives answer:

What was submitted, reviewed, or handed off in a specific round?

They preserve evidence and context, but they do not override canonical files.

Examples:

• ccra_review_bundle/round-*/
• reports/Codex*.md
• reports/GPT*.md
• reports/model_case_preprocessing/*

Rules:

• Keep review bundles under dated round directories.
• Do not place new review files directly under ccra_review_bundle/.
• optional_raw_changed_files.zip must preserve source-relative paths.
• Do not flatten zip contents, because duplicate filenames such as README.md can collide.
• knowledge_assets/ is excluded from review zips by default because the Owner manually syncs stable knowledge assets into GPT knowledge storage.

6. Temporary / Local Runtime Files

Temporary files answer no durable project question.

Examples:

• __pycache__/
• *.pyc
• local unpacked zip folders;
• scratch command outputs not referenced by a report;
• editor backups.

Rules:

• Do not commit these files.
• Add broad safe ignore rules in .gitignore.
• If a temporary command output becomes useful evidence, convert it into a deliberate report under reports/ or a review bundle.

7. Relationship To Knowledge Assets

knowledge_assets/ is a canonical long-term explanatory layer, but not every canonical file belongs there.

Put a document in knowledge_assets/ only when it answers:

What durable context, mechanism, rule, or map should ChatGPT / CCRA / Owner remember across sessions?

Do not put these in knowledge_assets/:

• concrete model cards that already live in cards/;
• machine-readable model JSON;
• validation reports;
• per-round review bundles;
• command logs;
• temporary handoffs.

See docs/KNOWLEDGE_ASSET_RULES.md for detailed knowledge-asset rules.

8. Commit Checklist

Before commit:

1. Confirm new files have the correct identity.
2. Confirm temporary files are not staged.
3. Rebuild or check indexes when canonical model/card/source/test files changed.
4. Regenerate validation reports after validation commands.
5. Keep review-bundle zips path-preserving.
6. Keep lifecycle status conservative; validation pass does not imply stable.