| # Documentation Map |
|
|
| This repository separates current operating guidance from immutable acceptance and |
| empirical history. Start with the README, then use the focused document that matches |
| the task. |
|
|
| ## Current Guidance |
|
|
| | Document | Use it for | |
| |---|---| |
| | [`README.md`](../README.md) | Hugging Face-style overview, install, quick starts, model matrix, headline metrics | |
| | [`config.json`](../config.json) | Machine-readable project, schema, model, and evaluation manifest | |
| | [`ARCHITECTURE.md`](../ARCHITECTURE.md) | Current layers, modules, data flow, isolation, and evolution rules | |
| | [`CONFIGURATION.md`](CONFIGURATION.md) | Typed fields, defaults, invariants, CLI JSON, readiness catalogs | |
| | [`EVALUATION.md`](EVALUATION.md) | Compared configurations, metrics, results, limitations, artifacts | |
| | [`WORKFLOWS.md`](WORKFLOWS.md) | End-to-end annotation, benchmark, backend, and readiness flows | |
| | [`TESTING.md`](TESTING.md) | Quality commands, markers, coverage, and focused-test map | |
| | [`PROJECT_STATUS.md`](PROJECT_STATUS.md) | Accepted operational status and evidence boundary | |
| | [`W1_T_SEMANTIC_READINESS.md`](W1_T_SEMANTIC_READINESS.md) | Specialized offline semantic-boundary timing workflow | |
|
|
| ## Contracts |
|
|
| | Document | Authority | |
| |---|---| |
| | [`ALIGNER_ENGINEERING_CONTRACT.md`](ALIGNER_ENGINEERING_CONTRACT.md) | Data columns, first/last semantics, reference-text and timestamp invariants | |
| | [`MODULAR_ARCHITECTURE_CONTRACT.md`](MODULAR_ARCHITECTURE_CONTRACT.md) | Mandatory layering, dependency direction, reuse, isolation, and coverage | |
| | [`AGENTS.md`](../AGENTS.md) | Repository execution and acceptance rules for coding agents | |
| | [`SKILLS.md`](../SKILLS.md) | Reusable implementation and verification patterns | |
|
|
| Contracts change only when the implementation/API changes intentionally. Update the |
| contract and its focused tests together. |
|
|
| ## Decision and Empirical Evidence |
|
|
| | Document/artifact | Authority | |
| |---|---| |
| | [`FINAL_ALIGNER_SELECTION.md`](FINAL_ALIGNER_SELECTION.md) | Current operational selection and limitations | |
| | [`POSTFINAL_THREE_ALIGNER_COMPARISON.md`](POSTFINAL_THREE_ALIGNER_COMPARISON.md) | Symmetric three-backend full-36 comparison | |
| | `results/final/` | Canonical selection and MFA annotated output | |
| | `results/postfinal/` | Full-36 MFA extension and three-backend evidence | |
| | `results/w1t/` | Readiness timing, consensus, review, and receipt artifacts | |
|
|
| Evidence files are preserved as reviewed. Documentation may summarize and link them; |
| it must not rewrite hashes, source cells, timing, or historical conclusions. |
|
|
| ## Historical Reports |
|
|
| | Document | Historical scope | |
| |---|---| |
| | [`STAGE_0_REPORT.md`](STAGE_0_REPORT.md) | Research, dependency selection, and original architecture freeze | |
| | [`STAGE_1_REPORT.md`](STAGE_1_REPORT.md) | Shared framework implementation and closure repairs | |
| | [`STAGE_2_REPORT.md`](STAGE_2_REPORT.md) | NeMo adapter implementation and original empirical boundary | |
| | [`STAGE_3_REPORT.md`](STAGE_3_REPORT.md) | MFA adapter and original five-row evidence | |
| | [`STAGE_4_REPORT.md`](STAGE_4_REPORT.md) | WhisperX adapter and original five-row/full-run evidence | |
| | [`STAGE_5_FINAL_ACCEPTANCE_REPORT.md`](STAGE_5_FINAL_ACCEPTANCE_REPORT.md) | Original software/architecture acceptance snapshot | |
| | [`POST_STAGE5_DOCS_LICENSE_REPORT.md`](POST_STAGE5_DOCS_LICENSE_REPORT.md) | Documentation, headers, and licensing audit | |
|
|
| Stage reports are provenance snapshots. Their counts, paths, and selection statements |
| may be superseded by later evidence. Current instructions live in the documents above. |
|
|
| ## Maintenance Rules |
|
|
| When behavior or evidence changes: |
|
|
| 1. Update the current focused guide first. |
| 2. Update README/config only for user-facing identity, defaults, models, or headline |
| metrics. |
| 3. Add or update a result receipt/evidence artifact before citing a new empirical |
| claim. |
| 4. Keep historical reports unchanged unless correcting a factual link or marking a |
| superseding record. |
| 5. Validate all local Markdown links and repository paths. |
| 6. Run every documented syntax/help/quality command before finalizing. |
| 7. Update `.agents/plans`, `.agents/work_data`, and `.agents/logs` with decisions and |
| observed results. |
| 8. Review `AGENTS.md` and `SKILLS.md` at the end for durable process gaps. |
|
|
| ## Terminology |
|
|
| - **Authoritative transcript**: the original `en_transcript` cell. |
| - **Forced alignment**: locating supplied text in audio; not ASR transcription. |
| - **Manual gold**: human reference timing/text fields. |
| - **Pairwise disagreement**: difference between two backend outputs; not accuracy. |
| - **Structural success**: valid complete word/timing output; not empirical accuracy. |
| - **Observed runtime**: one run's measured time under its stated hardware/cache state. |
| - **Current guidance**: maintained operating documentation. |
| - **Historical report**: preserved stage/acceptance snapshot. |
|
|
