Adopt canonical knowledge rules registry

Author: dapi

.github/workflows/docs.yml

@@ -0,0 +1,19 @@
+name: Documentation
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  generated-readmes:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+      - name: Verify generated README files
+        run: ruby scripts/render_readmes.rb --check

README.md

@@ -1,96 +1,112 @@
+<!-- This file is generated from `rules.yaml`. Run `ruby scripts/render_readmes.rb` after changing the registry. -->
+
 # Knowledge as Code
 
 [Русская версия](README.ru.md)
 
-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 much more expensive: corporate knowledge has gained another fast and literal reader.
+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.
+
+> AI does not create corporate memory. It becomes useful when that memory distinguishes sources, assertions, evidence, inferences, decisions, and unknowns.
 
-> AI does not create corporate memory. It becomes useful when that memory can distinguish a source, a fact, an inference, a decision, and an unknown.
+## Working model
 
-## The model
+The arrow is a reading path, not a storage pipeline. In practice, knowledge forms an acyclic graph of typed relationships.
 
-`Source → fact → derivative → inference or hypothesis → decision → action`
+```text
+source ──evidence_for──▶ canonical assertion
+   │                         │
+   └────derived_from────────▶ report
+                             │
+assertions + constraints ───▶ decision ──implemented_by──▶ action or code
+```
 
-Every layer links to the preceding one; none silently replaces it.
+## Independent metadata axes
 
-## Knowledge-status notation
+Do not force epistemic state, document role, authorship, and lifecycle into one status. Apply each field only when it is meaningful.
 
-| Label | Meaning |
-| --- | --- |
-| `FACT` | Confirmed by a primary source. |
-| `DERIVED` | A reproducible calculation, extract, or transformation of facts. |
-| `CLAIM` | Somebody's statement that has not yet been verified. |
-| `HYPOTHESIS` | An assumption that can be tested. |
-| `DECISION` | An accepted choice, rule, or policy. |
-| `UNKNOWN` | An important, explicitly recorded gap. |
-| `SYNTHETIC` | AI-generated, illustrative, or test data; not evidence. |
+| Field | Axis | Values | What it describes |
+| --- | --- | --- | --- |
+| `epistemic_state` | Epistemic state | `verified`, `claim`, `hypothesis`, `unknown` | What is known and how strongly it is supported. `verified` always implies named verification criteria. |
+| `record_kind` | Record role | `source`, `assertion`, `decision`, `instruction`, `report` | What responsibility the record owns. Evidence is a typed relationship, not a competing record role. |
+| `generation_mode` | Generation mode | `captured`, `human_authored`, `machine_generated`, `mixed` | How the content came into existence. Derivation is recorded separately through `derived_from`. |
+| `lifecycle` | Lifecycle | document: `draft`, `active`, `archived`; decision: `proposed`, `accepted`, `superseded`, `rejected` | Publication state and entity state are separate. A draft cannot silently override active knowledge. |
 
 ## Rules
 
-### KAC-01 — One fact, one owner
+### KAC-01 — One scope, one canonical owner
 
-Every fact has one canonical source and a person responsible for its freshness. Other documents link to it or derive from it.
+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.
 
-### KAC-02 — Do not confuse a source with its processing
+### KAC-02 — Separate source, assertion, and derivative
 
-An email, meeting recording, contract, or export is a source. A transcript, summary, report, or presentation is a derivative. A derivative links to the source and its version.
+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.
 
-### KAC-03 — Preserve provenance
+### KAC-03 — Provenance is not truth
 
-Every material record identifies its `source`, `author`, `created_at`, `as_of`, and transformation. Readers should be able to see who produced a result, when, and from what.
+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.
 
-### KAC-04 — Mark the type of assertion
+### KAC-04 — One question, one metadata axis
 
-Use `FACT`, `DERIVED`, `CLAIM`, `HYPOTHESIS`, `DECISION`, `UNKNOWN`, or `SYNTHETIC`. A hypothesis, paraphrase, or AI-generated text must not masquerade as a fact.
+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.
 
-### KAC-05 — Links, not copies
+### KAC-05 — Typed links, not copies
 
-Projects, companies, meetings, decisions, and sources need stable addresses. Share a link to the canonical record, rather than another copy.
+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.
 
-### KAC-06 — Knowledge belongs in the repository, not the thread
+### KAC-06 — Durable owner, messages as transport
 
-Within a project or team, record knowledge in the repository: a card, meeting note, ADR, runbook, or task. Send a link in chat and email. Messages are for discussion and notification, not the sole storage for agreements.
+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.
 
-### KAC-07 — Make changes visible
+### KAC-07 — Upstream first, downstream in sync
 
-Do not rewrite history silently. Material changes have an intelligible diff, author, and date; superseded decisions are marked as such.
+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.
 
-### KAC-08 — Schema before prose
+### KAC-08 — Make schema and lifecycle explicit
 
-Use templates and required fields for recurring entities: `owner`, `status`, `source`, `as_of`, `access`, `supersedes`. Prose explains context; it does not replace structure.
+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.
 
-### KAC-09 — Keep knowledge units small and clear
+### KAC-09 — One artifact, one responsibility
 
-Do not combine a customer record, meeting minutes, plan, and report in one document. One entity or assertion deserves one clear record with explicit links.
+The useful atomic boundary is an independent owner, lifecycle, or change boundary—not every sentence. Split monoliths without creating a maze of fragments.
 
-### KAC-10 — Knowledge has freshness
+### KAC-10 — Index first, details on demand
 
-Name an owner, a verification date, and a review interval. Stale knowledge is not erased without a trace: mark it `superseded` or `archived`.
+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.
 
-### KAC-11 — AI answers from evidence
+### KAC-11 — Outputs trace back to evidence
 
-AI searches authorised sources, cites them, separates quotation from inference, and returns `UNKNOWN` when evidence is insufficient. Confidence is not a substitute for evidence.
+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.
 
 ### KAC-12 — Context and access follow the source
 
-A knowledge link carries its author, scope, version, and access rights. Search, catalogues, and AI must not turn a local record into context-free “common knowledge”.
+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.
+
+## Minimal record example
 
-## Minimal record template
+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.
 
 ```yaml
-id: DEC-042
-type: decision
-status: current
-owner: product-lead
-as_of: 2026-08-14
-source:
-  - repo://company/project/meetings/2026-08-14.md#decision-3
-supersedes: null
+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
 ```
 
-For a longer Russian explanation, see [«Корпоративная память, пригодная для AI»](article.md).
+For a longer Russian explanation derived from this registry, see [«Корпоративная память, пригодная для AI»](article.md).
 
 ## Foundations
 
 - [W3C PROV Primer](https://www.w3.org/TR/prov-primer/) — provenance through entities, activities, and agents.
-- [FAIR Guiding Principles](https://doi.org/10.1038/sdata.2016.18) — knowledge should be findable, accessible, interoperable, and reusable by people and machines.
-- [Pro Git: About Version Control](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control) — the history of change is part of the working object.
+- [FAIR Guiding Principles](https://doi.org/10.1038/sdata.2016.18) — findable, accessible, interoperable, and reusable data for people and machines.
+- [Pro Git: About Version Control](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control) — change history as part of the working object.