--- description: Єдина documentation surface: file-level CRC docs як evidence та trigger, package-level CI4 knowledge для AI-assisted планування змін, protected zones, traceability, Changeability Test і Gap Test alwaysApply: true version: '5.0' --- # Doc-files: file evidence → package knowledge documentation `doc-files` тримає файлове evidence та CI4-архітектурне знання versioned разом із кодом у portable Markdown. Source file є джерелом evidence й trigger інвалідації, але одиницею package-level генерації є package, crate або module. Головний читач — AI coding agent, який готує зміну; людина також має без широкої code archaeology зрозуміти призначення package, поведінку, boundaries і рішення. Це правило описує documentation contract. Deterministic discovery, graph construction, generation і validation живуть у `package_knowledge` engine, а не дублюються в policy text. ## Scoped sources of truth Для всіх тверджень немає одного універсального source of truth: - **Code** є source of truth для `Implemented AS-IS` behavior. - **Protected `EXPECTED` zones**, accepted ADR, formal specifications і executable assertions є source of truth для intended behavior. - **Knowledge graph** є derived comparison model, а не окремим authoring source. - Generated Markdown views і traceability manifest є versioned projections цієї моделі. Агент не описує current implementation за ADR, specification або manual narrative, якщо їм суперечить code evidence. І навпаки, implementation не стирає мовчки explicit expectation: різниця стає visible gap. ## Documentation domain Одиниця architecture documentation — один **package, crate або module**, а не source file і не весь monorepo. Language plugin визначає domain root за native manifest: `package.json`, `Cargo.toml`, `pyproject.toml` або `composer.json`. Nested workspace package є окремим domain. Parent domain не розгортає його implementation, навіть коли import резолвиться через local workspace link; він зберігає лише opaque external contract. Stable domain identity базується на ecosystem і canonical package name, а не на filesystem location. Identity collision є blocking diagnostic, а не приводом для path-based fallback. Repository-root `docs/` може давати лише navigation між domains. Business, process, architecture і contract content належать локальному `docs/` owning domain. Це не documentation scattering: кожен domain має одну self-contained knowledge boundary. ## Implemented behavior, expectations і gaps `Implemented AS-IS` — evidence-backed behavior, виведена зі source structure, entry points, state changes, integrations, configuration, contracts і tests. Private implementation може підтримувати evidence chain, але private symbol names не потрапляють у human Markdown. `Expected` behavior є explicit. `MANUAL` prose дає context, але не створює expectation. Відсутня expectation не є defect і не створює gap. Коли expectation можна безпечно зіставити з implemented evidence, вона має один зі status: - `satisfied` — implementation підтверджує expectation; - `missing` — expected behavior не має implementation evidence; - `diverged` — implementation суперечить expectation; - `unresolved` — evidence недостатньо для безпечного висновку. `unresolved` не можна вгадувати як `missing` або `diverged`. Parser, coverage, identity, entailment, privacy, projection або atomic-publication failure блокує publication, а не створює переконливу, але неперевірену prose. ## Package documentation views Кожен domain тримає thin arc42/Diátaxis navigation skeleton і публікує тільки meaningful views; порожні capability, process або contract pages не створюються. ```text docs/ ├── index.md ├── explanation/ │ ├── architecture.md │ ├── capabilities/.md │ └── processes/.md ├── reference/ │ ├── contracts/.md │ └── glossary.md ├── implementation-gaps.md └── .docgen/manifest.json ``` `index.md` і `.docgen/manifest.json` є required. `architecture.md` публікується, коли domain має більше однієї responsibility або external boundary. Business-critical process fragment є self-contained і описує purpose, actors і trigger, preconditions, main та alternative flows, rules, state/effects, outcomes, architecture responsibilities, explicit expectations і local gaps. Topics відкриваються зі stable evidence, зокрема public entry points, routes, commands, events, jobs, state transitions і verified scenarios. Title може змінитися без зміни topic ID. Ambiguous topic split, merge або protected-zone migration блокує publication до explicit migration plan. ## Protected і generated zones Markdown підтримує лише такі zone kinds: - **`AUTOGEN`** — generated projection; її hash захищає від silent manual edits. - **`MANUAL`** — preserved narrative context, який не є expectation source. - **`EXPECTED`** — preserved narrative зі stable identity, яка є expectation source. Generated content ніколи не переписує protected zone. `MERGED` zones не підтримуються в першій версії. Manual claim, що доказово суперечить graph, є blocking `manual-conflict`: автор виправляє його або робить intended difference explicit через `EXPECTED`. ## Traceability manifest і slices Committed manifest є compact AI-facing index, а не копією повного AST graph. Він зберігає domains і stable topic identities, aliases, fingerprints, claims із compact evidence references, reverse evidence links, gaps і zone hashes. Це дає агенту перейти від process step або rule до affected files, symbols, tests, configuration і contracts без repo-wide searching. Full parsed graph є reproducible cache і не зберігається в Git. CLI дає small read surfaces замість того, щоб змушувати агента завантажувати всі documents: ```text n-rules docs domains n-rules docs index --domain n-rules docs slice --domain --topic n-rules docs validate --domain ``` Unchanged domain не виконує LLM work. Full та incremental rebuild мають давати однакові committed generated artifacts. Candidate output проходить validation перед atomic publication; partial analysis може бути cached, але не публікується як domain documentation. ## Changeability Test Former Rebuild Test видалено. Doc-files не вимагає відтворювати всю codebase лише з Markdown, бо implementation detail залишається у code. Binary Changeability Test дає fresh agent self-contained `Implemented AS-IS` fragment, TO-BE description, repository і manifest. Агент має знайти correct domain, affected topics, files, symbols, tests, contracts і configuration та побудувати complete implementation plan без broad searching поза domain. Golden fixtures вимагають complete recall required impact set; extra impact не може вийти за domain boundary. ## Gap Test Golden fixtures перевіряють gap model: без expectation gap не виникає; matching expectation є `satisfied`; absent implementation — `missing`; contradictory implementation — `diverged`; insufficient mapping evidence — `unresolved`. Parse або coverage failure блокує publication, а не створює gap verdict. ## ADR compatibility і migration Accepted ADR лишаються canonical architecture decisions та expectation evidence. До ADR vNext вони живуть лише в repository-root `docs/adr/`, який зберігає current MADR v4 minimal layout, capture/normalize flow і accepted-status rules з `adr`. Package-local `docs/adr/` не створюється. Existing ADR-derived root projections лишаються compatible під час migration. ADR більше не є єдиним autogen input: implemented views походять із code evidence, а ADR, protected expectations, specifications і assertions дають expected evidence. File-level CRC docs і package knowledge є двома проєкціями однієї `doc-files` surface: перші дають локальне evidence та швидкий drift gate, друга формує business/architecture views на рівні domain. Жодна проєкція не видаляє іншу автоматично. ## Portable Docs-as-Code Documentation review, versioning і validation відбуваються разом із code. Використовуй лише CommonMark, GFM, Mermaid і semantic `
` blocks; не додавай site generator або presentation HTML на кшталт `
` і ``. Кожен fragment має бути зрозумілий окремо: не пиши context-dependent references на кшталт «як вище» або «попередній компонент». arc42 і Diátaxis залишаються navigation aids, а не вимогою порожніх pages. C4, Context Maps і EventModeling — optional diagrams, коли вони пояснюють реальний boundary або flow. Architecture documents посилаються на relevant tests і, для nondeterministic components, на trace storage або dashboard, що пояснює observed decisions. ## Working with a change Перед implementation change прочитай relevant domain index, topic slice, contracts, local gaps і accepted ADR. Зміна, що зачіпає architecture, contracts, boundaries або explicit intent, оновлює expectation evidence і generated projections у тому самому review. Не дублюй operational Cursor rules в architecture documentation; посилайся на owning rule. ## Tooling - `marksman` лишається Markdown navigation і link-validation layer; `doc_files.vscode_extensions` вимагає `arr.marksman`. - Mermaid рендерить C4 і process diagrams без site generator. - `package_knowledge` validator володіє deterministic graph, zone, manifest, privacy і publication checks. Це policy навмисно не дублює його algorithm.