160 lines
6.1 KiB
Markdown
160 lines
6.1 KiB
Markdown
# 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-*`, `local_ccra_reviews/round-*`, `reports/Codex*.md`, `reports/GPT*.md`, `reports/Round*_round_conductor_*.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-*/`
|
|
- `local_ccra_reviews/round-*/`
|
|
- `reports/Codex*.md`
|
|
- `reports/GPT*.md`
|
|
- `reports/Round*_round_conductor_*.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.
|
|
- `local_ccra_reviews/` records local first-pass review runs and is not copied into Web CCRA bundles by default.
|
|
- `findings-confirmation.md` inside a Local CCRA run is a Chinese Owner decision aid and does not replace the full review report.
|
|
- Round Conductor reports under `reports/` are process records and do not override canonical model, selector, evidence, or regression files.
|
|
- `04_LOCAL_CCRA_REVIEW_REPORT.md` is excluded from Web CCRA bundles by default unless the Owner explicitly asks to include it.
|
|
|
|
## 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.
|