Compile Usage Docs From a Frozen Spec Hash, Not From Chat

Описание и применение

Документация генерируется из замороженного снимка спецификации, а не из чата, чтобы обеспечить достоверность и привязку к конкретной версии.

Задача

Documentation generated from live chat transcripts can contain unverified claims and lack provenance, leading to inaccurate or misleading API usage pages.

Результат

A reproducible, CI‑driven workflow that guarantees usage docs are tied to a specific spec snapshot, preventing stale or fabricated content from entering the documentation repository.

Рабочий процесс

• Freeze the OpenAPI spec and write its SHA‑256 hash to docs/SPEC.lock
• Run a CI check that compares the current spec hash to the lockfile
• If the hash matches, allow the generator to produce usage Markdown in docs/usage/
• If the hash mismatches, delete or block the generated docs and fail the PR
• Use scripts/classify_usage.py to scan generated docs for human‑owned phrases and reject them
• Place any non‑draftable content under docs/policy/ where the generator cannot write
• Merge the PR only after all checks pass and human review confirms policy compliance

Доказательства

Usage pages stay honest when they compile from a frozen interface snapshot instead of from a chat transcript.

Источник

Rows marked “Yes” should live under docs/usage/ and should be deleted automatically when the spec hash changes.

Источник