rules.yaml

schema_version: 1
id: knowledge-as-code-rules
status: active
canonical_for:
  - knowledge_as_code_principles
  - knowledge_metadata_vocabulary
steward: dapi
as_of: "2026-08-14"

locales:
  en:
    language_link: "[Русская версия](README.ru.md)"
    intro: >-
      A compact guide to organisational knowledge that remains understandable,
      verifiable, and reusable by a team. AI did not create these principles,
      but it makes their absence more expensive by becoming another fast and
      literal consumer of corporate knowledge.
    thesis: >-
      AI does not create corporate memory. It becomes useful when that memory
      distinguishes sources, assertions, evidence, inferences, decisions, and
      unknowns.
    model_title: Working model
    model_intro: >-
      The arrow is a reading path, not a storage pipeline. In practice,
      knowledge forms an acyclic graph of typed relationships.
    model: |-
      source ──evidence_for──▶ canonical assertion
         │                         │
         └────derived_from────────▶ report
                                   │
      assertions + constraints ───▶ decision ──implemented_by──▶ action or code
    axes_title: Independent metadata axes
    axes_intro: >-
      Do not force epistemic state, document role, authorship, and lifecycle
      into one status. Apply each field only when it is meaningful.
    rules_title: Rules
    template_title: Minimal record example
    template_intro: >-
      This example records exactly what the evidence proves: a customer made a
      statement. It does not silently promote that statement into proof that
      the money exists.
    article_text: >-
      For a longer Russian explanation derived from this registry, see
      [«Корпоративная память, пригодная для AI»](article.md).
    foundations_title: Foundations
    generated_notice: "This file is generated from `rules.yaml`. Run `ruby scripts/render_readmes.rb` after changing the registry."
  ru:
    language_link: "[English version](README.md)"
    intro: >-
      Краткий гайд по корпоративной памяти: как делать знания понятными,
      проверяемыми и пригодными для совместной работы. AI не создаёт эти
      принципы, но делает цену их отсутствия выше, становясь ещё одним быстрым и
      буквальным потребителем корпоративных знаний.
    thesis: >-
      AI не создаёт корпоративную память. Он становится полезным, когда память
      различает источники, утверждения, свидетельства, выводы, решения и
      неизвестное.
    model_title: Рабочая модель
    model_intro: >-
      Стрелка здесь — маршрут чтения, а не конвейер хранения. На практике знание
      образует ациклический граф типизированных связей.
    model: |-
      источник ──evidence_for──▶ каноническое утверждение
          │                              │
          └──────derived_from───────────▶ отчёт
                                         │
      утверждения + ограничения ────────▶ решение ──implemented_by──▶ действие или код
    axes_title: Независимые оси метаданных
    axes_intro: >-
      Не смешивайте достоверность, роль документа, авторство и lifecycle в одном
      статусе. Каждое поле применяется только там, где имеет смысл.
    rules_title: Правила
    template_title: Минимальный пример записи
    template_intro: >-
      Пример фиксирует ровно то, что доказывает свидетельство: клиент сделал
      заявление. Он не превращает это заявление в доказательство наличия денег.
    article_text: >-
      Более подробное объяснение, производное от этого реестра:
      [«Корпоративная память, пригодная для AI»](article.md).
    foundations_title: Основания
    generated_notice: "Этот файл сгенерирован из `rules.yaml`. После изменения реестра запустите `ruby scripts/render_readmes.rb`."

axes:
  - field: epistemic_state
    name:
      en: Epistemic state
      ru: Эпистемический статус
    values:
      en: "`verified`, `claim`, `hypothesis`, `unknown`"
      ru: "`verified`, `claim`, `hypothesis`, `unknown`"
    description:
      en: What is known and how strongly it is supported. `verified` always implies named verification criteria.
      ru: Что известно и насколько это подтверждено. `verified` всегда подразумевает названный критерий проверки.
  - field: record_kind
    name:
      en: Record role
      ru: Роль записи
    values:
      en: "`source`, `assertion`, `decision`, `instruction`, `report`"
      ru: "`source`, `assertion`, `decision`, `instruction`, `report`"
    description:
      en: What responsibility the record owns. Evidence is a typed relationship, not a competing record role.
      ru: Какой ответственностью владеет запись. Evidence — типизированная связь, а не конкурирующая роль записи.
  - field: generation_mode
    name:
      en: Generation mode
      ru: Способ создания
    values:
      en: "`captured`, `human_authored`, `machine_generated`, `mixed`"
      ru: "`captured`, `human_authored`, `machine_generated`, `mixed`"
    description:
      en: How the content came into existence. Derivation is recorded separately through `derived_from`.
      ru: Как появилось содержимое. Производность отдельно фиксируется через `derived_from`.
  - field: lifecycle
    name:
      en: Lifecycle
      ru: Lifecycle
    values:
      en: "document: `draft`, `active`, `archived`; decision: `proposed`, `accepted`, `superseded`, `rejected`"
      ru: "документ: `draft`, `active`, `archived`; решение: `proposed`, `accepted`, `superseded`, `rejected`"
    description:
      en: Publication state and entity state are separate. A draft cannot silently override active knowledge.
      ru: Статус документа и состояние сущности разделены. Черновик не может молча переопределить действующее знание.

rules:
  - id: KAC-01
    title:
      en: One scope, one canonical owner
      ru: Один scope — один canonical owner
    body:
      en: >-
        Every material assertion has exactly one canonical owner within a
        declared scope. The owner is the record or system that maintains the
        current assertion; source evidence and the human steward are separate.
      ru: >-
        У каждого существенного утверждения есть ровно один canonical owner в
        объявленном scope. Owner — запись или система, которая поддерживает
        актуальное утверждение; источники-свидетельства и steward-человек
        фиксируются отдельно.
  - id: KAC-02
    title:
      en: Separate source, assertion, and derivative
      ru: Разделяйте источник, утверждение и производное
    body:
      en: >-
        A source preserves what happened or was said. A canonical assertion
        records what the organisation currently accepts. A derivative
        transforms upstream material. None silently substitutes for another.
      ru: >-
        Источник сохраняет то, что произошло или было сказано. Каноническое
        утверждение фиксирует то, что организация сейчас принимает. Производное
        преобразует upstream-материал. Они не подменяют друг друга.
  - id: KAC-03
    title:
      en: Provenance is not truth
      ru: Происхождение не равно истинности
    body:
      en: >-
        Provenance answers who produced a record, when, from what, and through
        which transformation. Verification separately states what the evidence
        proves, under which criteria, scope, and date.
      ru: >-
        Provenance отвечает, кто, когда, из чего и каким преобразованием создал
        запись. Проверка отдельно указывает, что именно доказывает свидетельство,
        по какому критерию, в каком scope и на какую дату.
  - id: KAC-04
    title:
      en: One question, one metadata axis
      ru: Один вопрос — одна ось метаданных
    body:
      en: >-
        Do not encode truth, role, authorship, and lifecycle in one label. Use
        independent fields so a machine-generated report can also be derived,
        active, and based on claims without contradiction.
      ru: >-
        Не кодируйте достоверность, роль, авторство и lifecycle одной меткой.
        Независимые поля позволяют машинно-сгенерированному отчёту одновременно
        быть производным, active и основанным на claims без противоречия.
  - id: KAC-05
    title:
      en: Typed links, not copies
      ru: Типизированные ссылки вместо копий
    body:
      en: >-
        Link to the canonical record using an explicit relationship such as
        `evidence_for`, `derived_from`, `implements`, or `supersedes`. A useful
        link explains what is there and why it should be followed.
      ru: >-
        Ссылайтесь на каноническую запись с явным типом связи: `evidence_for`,
        `derived_from`, `implements` или `supersedes`. Полезная ссылка объясняет,
        что находится по адресу и зачем туда переходить.
  - id: KAC-06
    title:
      en: Durable owner, messages as transport
      ru: Устойчивый owner, переписка как транспорт
    body:
      en: >-
        Decisions, agreements, and instructions belong with the correct
        canonical owner; chat and email carry links and notifications. Code owns
        implementation, operational systems own transactional state, and
        documentation owns intent, rationale, and contracts.
      ru: >-
        Решения, договорённости и инструкции живут у правильного canonical
        owner; чат и почта передают ссылки и уведомления. Код владеет
        реализацией, операционные системы — транзакционным состоянием,
        документация — intent, rationale и contracts.
  - id: KAC-07
    title:
      en: Upstream first, downstream in sync
      ru: Сначала upstream, затем синхронизация downstream
    body:
      en: >-
        Change meaning at the canonical owner first. Then inspect direct
        dependants and update, invalidate, or explicitly leave them unchanged.
        Conflicting active knowledge is a defect, not an alternative truth.
      ru: >-
        Сначала меняйте смысл у canonical owner. Затем проверяйте прямые
        зависимости и обновляйте, инвалидируйте либо явно оставляйте их без
        изменений. Конфликтующее active-знание — дефект, а не альтернативная
        истина.
  - id: KAC-08
    title:
      en: Make schema and lifecycle explicit
      ru: Явно задавайте схему и lifecycle
    body:
      en: >-
        Repeating record kinds use a small schema with conditional fields.
        Separate document status from decision or delivery status; record
        `as_of`, review dates, and `supersedes` only where time or replacement is
        meaningful.
      ru: >-
        Повторяющиеся типы записей используют небольшую схему с условными
        полями. Отделяйте статус документа от статуса решения или delivery;
        фиксируйте `as_of`, дату пересмотра и `supersedes` там, где время или
        замена действительно имеют значение.
  - id: KAC-09
    title:
      en: One artifact, one responsibility
      ru: Один артефакт — одна ответственность
    body:
      en: >-
        The useful atomic boundary is an independent owner, lifecycle, or change
        boundary—not every sentence. Split monoliths without creating a maze of
        fragments.
      ru: >-
        Полезная граница атомарности — независимый owner, lifecycle или граница
        изменения, а не каждое предложение. Разделяйте монолиты, не создавая
        лабиринт из фрагментов.
  - id: KAC-10
    title:
      en: Index first, details on demand
      ru: Сначала индекс, детали по необходимости
    body:
      en: >-
        Every durable record is reachable from a relevant index. Start readers
        with a compact map and annotated links, then disclose deeper context only
        when the task requires it.
      ru: >-
        Каждая устойчивая запись достижима из подходящего индекса. Сначала дайте
        читателю компактную карту и аннотированные ссылки, затем раскрывайте
        подробности по мере необходимости задачи.
  - id: KAC-11
    title:
      en: Outputs trace back to evidence
      ru: Результат ведёт обратно к свидетельствам
    body:
      en: >-
        A human or AI answer, report, and decision identifies supporting
        evidence, separates quotation from inference, and preserves unknowns.
        Confident language is not a substitute for verification.
      ru: >-
        Ответ человека или AI, отчёт и решение называют поддерживающие
        свидетельства, отделяют цитату от вывода и сохраняют неизвестное.
        Уверенный тон не заменяет проверку.
  - id: KAC-12
    title:
      en: Context and access follow the source
      ru: Контекст и доступ следуют за источником
    body:
      en: >-
        Scope, effective date, provenance, and access restrictions survive
        indexing, summarisation, and retrieval. Search and AI must not turn a
        local record into context-free common knowledge.
      ru: >-
        Scope, дата действия, provenance и ограничения доступа сохраняются при
        индексации, суммаризации и поиске. Поиск и AI не должны превращать
        локальную запись в бесконтекстное общее знание.

record_example: |-
  id: AST-042
  record_kind: assertion
  status: active
  canonical_for:
    - customer_budget_status
  steward: sales-lead
  as_of: "2026-08-14"
  epistemic_state: claim
  generation_mode: human_authored
  evidence:
    - path: correspondence/client-message.md
      supports: customer_stated_that_budget_is_approved
  derived_from: []
  supersedes: AST-037
  access: internal

foundations:
  - url: https://www.w3.org/TR/prov-primer/
    label:
      en: W3C PROV Primer
      ru: W3C PROV Primer
    note:
      en: provenance through entities, activities, and agents
      ru: происхождение через сущности, действия и агентов
  - url: https://doi.org/10.1038/sdata.2016.18
    label:
      en: FAIR Guiding Principles
      ru: FAIR Guiding Principles
    note:
      en: findable, accessible, interoperable, and reusable data for people and machines
      ru: находимые, доступные, совместимые и повторно используемые данные для людей и машин
  - url: https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control
    label:
      en: "Pro Git: About Version Control"
      ru: "Pro Git: About Version Control"
    note:
      en: change history as part of the working object
      ru: история изменений как часть рабочего объекта