docs/DOCUMENTATION.md

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	Hugging Face-style overview, install, quick starts, model matrix, headline metrics
config.json	Machine-readable project, schema, model, and evaluation manifest
ARCHITECTURE.md	Current layers, modules, data flow, isolation, and evolution rules
CONFIGURATION.md	Typed fields, defaults, invariants, CLI JSON, readiness catalogs
EVALUATION.md	Compared configurations, metrics, results, limitations, artifacts
WORKFLOWS.md	End-to-end annotation, benchmark, backend, and readiness flows
TESTING.md	Quality commands, markers, coverage, and focused-test map
PROJECT_STATUS.md	Accepted operational status and evidence boundary
W1_T_SEMANTIC_READINESS.md	Specialized offline semantic-boundary timing workflow

Contracts

Document	Authority
ALIGNER_ENGINEERING_CONTRACT.md	Data columns, first/last semantics, reference-text and timestamp invariants
MODULAR_ARCHITECTURE_CONTRACT.md	Mandatory layering, dependency direction, reuse, isolation, and coverage
AGENTS.md	Repository execution and acceptance rules for coding agents
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	Current operational selection and limitations
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	Research, dependency selection, and original architecture freeze
STAGE_1_REPORT.md	Shared framework implementation and closure repairs
STAGE_2_REPORT.md	NeMo adapter implementation and original empirical boundary
STAGE_3_REPORT.md	MFA adapter and original five-row evidence
STAGE_4_REPORT.md	WhisperX adapter and original five-row/full-run evidence
STAGE_5_FINAL_ACCEPTANCE_REPORT.md	Original software/architecture acceptance snapshot
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.