# 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:

```text
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:

```text
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:

```text
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_<round-version>.zip` must preserve source-relative paths.
- GPT / CCRA upload files inside review bundles must include the round version in the filename, for example `_03.2`, to avoid same-name ambiguity when multiple rounds are uploaded in one Web ChatGPT conversation.
- 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:

```text
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.