116 lines
3.5 KiB
Markdown
116 lines
3.5 KiB
Markdown
# Index Maintenance Protocol
|
|
|
|
## Purpose
|
|
|
|
`models/model_index.json` is the machine-readable registry for model discovery.
|
|
|
|
`cards/card_index.md` is the human-readable projection for review and handoff.
|
|
|
|
Neither file is the full source of model content. Full content remains in:
|
|
|
|
- `models/*.model.json`
|
|
- `cards/*.md`
|
|
- `sources/source_articles.json`
|
|
- `sources/source_excerpts.json`
|
|
- `tests/regression_cases.json`
|
|
|
|
## Maintenance Rule
|
|
|
|
Every asset change must keep indexes synchronized.
|
|
|
|
Key handoff and release points must run a full rebuild or full consistency check.
|
|
|
|
The operating rule is:
|
|
|
|
```text
|
|
incremental update on every model/card/source/test change
|
|
+
|
|
full rebuild or full reconciliation at release, handoff, schema migration, batch expansion, or validation drift
|
|
```
|
|
|
|
## Incremental Update Triggers
|
|
|
|
Update indexes in the same work session whenever any of these changes:
|
|
|
|
- Model added, deleted, renamed, or archived.
|
|
- `model_id`, `model_name`, `model_type`, or `pipeline_position`.
|
|
- `model_file` or `card_file` path.
|
|
- Source article or source evidence references.
|
|
- Regression cases for a model.
|
|
- `stability_profile.stability_level`.
|
|
- `regression_status`.
|
|
- `status`.
|
|
- Card file added, deleted, or renamed.
|
|
|
|
## Full Rebuild Or Full Check Triggers
|
|
|
|
Run `python scripts\rebuild_indexes.py --check` or `python scripts\rebuild_indexes.py --write` before:
|
|
|
|
- ChatGPT / CCRA / owner handoff.
|
|
- Writing `reports/validation_report.md`.
|
|
- Schema changes.
|
|
- Batch model expansion.
|
|
- Directory or naming-rule changes.
|
|
- Larger merges.
|
|
- Selector rules depending on model registry state.
|
|
- Any model status upgrade review.
|
|
- Any detected index drift or orphan file.
|
|
|
|
## Field Sources
|
|
|
|
| Index field | Source |
|
|
| --- | --- |
|
|
| `model_id` | `models/*.model.json.model_id` |
|
|
| `model_name` | `models/*.model.json.model_name` |
|
|
| `model_type` | `models/*.model.json.model_type` |
|
|
| `pipeline_position` | `models/*.model.json.pipeline_position` |
|
|
| `model_file` | Model JSON file path |
|
|
| `card_file` | `cards/{model_id}.md` in v0.2 |
|
|
| `source_article_count` | Length of `source_articles` |
|
|
| `source_evidence_count` | Length of `source_evidence` |
|
|
| `regression_case_count` | Cases in `tests/regression_cases.json` with the same `model_id` |
|
|
| `stability_level` | `stability_profile.stability_level` |
|
|
| `regression_status` | `regression_status` |
|
|
| `status` | `status` |
|
|
| `last_updated` | `last_updated` |
|
|
|
|
## Card Index Generation
|
|
|
|
`cards/card_index.md` is rendered from `models/model_index.json`.
|
|
|
|
Current v0.2 table columns:
|
|
|
|
- Model ID
|
|
- 模型名称
|
|
- 类型
|
|
- 流程位置
|
|
- Card
|
|
- Model JSON
|
|
- 稳固性
|
|
- 回归状态
|
|
- 状态
|
|
|
|
Do not treat `cards/card_index.md` as an independent content source.
|
|
|
|
## Drift Checks
|
|
|
|
Validation must detect:
|
|
|
|
- Missing `model_file` or `card_file`.
|
|
- Model JSON files missing from `model_index.json`.
|
|
- Card files missing from `card_index.md`.
|
|
- `card_index.md` entries missing from `model_index.json`.
|
|
- Count drift for source articles, source evidence, and regression cases.
|
|
- State drift for `stability_level`, `regression_status`, and `status`.
|
|
|
|
## Codex Checklist
|
|
|
|
When modifying model assets:
|
|
|
|
1. Update the source asset first.
|
|
2. Run `python scripts\rebuild_indexes.py --write`.
|
|
3. Run `python scripts\rebuild_indexes.py --check`.
|
|
4. Run `python scripts\validate_model_library.py`.
|
|
5. Confirm `reports/index_rebuild_report.md` and `reports/validation_report.md`.
|
|
6. Do not upgrade `status`, `stability_level`, or `regression_status` unless owner / ChatGPT / CCRA explicitly decided it.
|