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