Knowledge Graph Schema

Назначение: формальная схема knowledge graph (KG) для RENAR-проектов — узлы, грани, properties, query patterns. KG служит derived view от RENAR-артефактов для семантических запросов AI-агентов и reconciliation. Источник: research/16-req-graph-schema-draft.md.

KG — не источник правды. Source of Truth — артефакты (ADAPT / BR / SR / SPEC / TC) на substrate. Граф derived from frontmatter и не редактируется напрямую. Если граф противоречит артефактам → rebuild графа, не правка артефактов.

1. Зачем граф

1.1 Проблема без графа

Без KG AI-агент при генерации/анализе требования имеет flat поиск через:

FTS5 / RAG поиск по .md файлам.
Frontmatter parent/children (только direct hops).
Keyword grep по коду.

Это даёт синтаксический контекст. Но AI часто нужен семантический: «дай все BR, влияющие на KPI X», «какие SR верифицированы tests с устаревшей requirement-version», «какие SPEC depends-on SPEC-DATA-03».

1.2 Use cases

Запрос	Без графа	С графом
Все BR, влияющие на Sales Cycle KPI	Grep + парсить frontmatter	Один Cypher-запрос
При изменении SR-05 — какие задачи и SPEC затронуты	Сканировать все ссылки	Single graph traversal
Какие AIC / SPEC-AI требуют high-risk classification по AI Act	Вручную	One query
Stakeholder map для проекта	Несколько запросов	Single subgraph extraction
Cross-project dependencies через INT-SR (заменено SPEC-INT)	Federation API calls	Federated graph query
Стало ли требование SR-12 деградировать (achievement % падает)	Manual analysis	Trend analytic on node properties
Stale TC — TC verifies SR с обновлённой версией, last-run на старой	Manual check	One query

2. Node types (closed list)

Type	Источник	Identity
`Requirement`	BR / SR / TR артефакты	`<id>`
`Specification`	SPEC-* артефакты (9 типов)	`<spec-id>`
`ADAPT`	ADAPT-NNN артефакты	`<adapt-id>`
`BackwardFinding`	B-NNN записи внутри ADAPT	`<adapt-id>:B-NNN`
`TestCase`	TC и INT-TC артефакты	`<tc-id>`
`WorkOrder`	ТЗ и delta-ТЗ	`<tz-id>`
`Stakeholder`	Frontmatter `business-context.stakeholder`	`<stakeholder-id>`
`BusinessGoal`	Frontmatter `business-context.business-goal` (deduplicated)	`<goal-id>`
`KPI`	Frontmatter `business-outcome.kpi-name`	`<kpi-id>`
`Task`	TR / runtime task store	`<task-id>`
`CodeArtifact`	TC `automation.location`, code commits	`<repo>:<path>:<symbol>`
`Decision`	Architectural decision records	`<decision-id>`
`DeadEnd`	Failed approaches (опционально)	`<deadend-id>`
`RiskItem`	AI Risk Register entry	`AIR-NN`
`Compliance`	Compliance standard reference	`<std>:<control>`
`Template`	Requirements library template	`<template-id>`

Список закрыт; новые node types — только через изменение полного RENAR Standard.

3. Edge types (closed list)

3.1 Иерархия и derivation

Edge	From	To	Семантика
`parent`	Requirement	Requirement	A.parent = B → B is parent of A (BR → SR → TR)
`derived-from-adapt`	Requirement / Specification	ADAPT	Артефакт выведен из approved ADAPT section
`derived-from-template`	Requirement / Specification	Template	Шаблон (с version pin)
`replaces`	Requirement / Specification	Requirement / Specification	new replaces old (deprecated)
`supersedes`	Requirement / Specification	Requirement / Specification	strictly newer version (post-delta)
`parent-adapt`	ADAPT	ADAPT	delta-ADAPT → main ADAPT

3.2 ADAPT specifics

Edge	From	To	Семантика
`from-tz`	ADAPT	WorkOrder	source-tz pointer
`contains-backward`	ADAPT	BackwardFinding	B-NNN запись
`backward-asks-stakeholder`	BackwardFinding	Stakeholder	who answers
`resolved-by-answer`	BackwardFinding	(timestamp + author)	client-answer record

3.3 SPEC graph (parallel axis)

Edge	From	To	Семантика
`constrained-by`	Requirement	Specification	SR constrained by SPEC-* (typed edge)
`implements-spec`	Task	Specification	TR implements SPEC-*
`depends-on`	Specification	Specification	SPEC depends on another SPEC (DAG)
`referenced-by`	Specification	Requirement / Task	inverse (auto-derived)

3.4 Verification и реализация

Edge	From	To	Семантика
`verifies`	TestCase	Requirement / Specification	TC verifies artifact
`verified-by`	Requirement / Specification	TestCase	inverse (auto-derived)
`implements`	Task	Requirement	Task implements requirement
`realises-in`	TestCase	CodeArtifact	TC.automation.location
`linked-defect`	Requirement	Task (defect type)	Bug на этом требовании

3.5 Provenance

Edge	From	To	Семантика
`from-order`	ADAPT / Requirement	WorkOrder	source.tz-section reference
`delta-from`	WorkOrder	WorkOrder	delta-ТЗ → base ТЗ
`cited-in`	Assertion	WorkOrder	inline citation pointer (для validator)
`decided`	Requirement / Specification	Decision	Decision при декомпозиции
`deadend`	Requirement / Specification	DeadEnd	Failed approach

3.6 Business / governance

Edge	From	To	Семантика
`owned-by`	Requirement	Stakeholder	business-context.stakeholder
`goal`	Requirement	BusinessGoal	business-context.business-goal
`impacts-kpi`	BusinessGoal	KPI	KPI driven by goal
`compliance-with`	Requirement / Specification	Compliance	compliance entry
`risk-mitigates`	Requirement / Specification	RiskItem	mitigates AIR-NN
`risk-introduces`	Requirement / Specification	RiskItem	introduces new risk (warning trigger)

3.7 Cross-project / integration

Edge	From	To	Семантика
`participates-in`	Specification (SPEC-INT)	Specification (SPEC-INT)	INT-SR participants (cross-project)
`cross-deps-on`	Task (project A)	Task (project B)	Cross-project dependency
`integrates-via`	Requirement	Specification (SPEC-INT)	Через SPEC-INT contract

3.8 Edge properties

Edges имеют properties (Cypher-style):

(SR:Requirement)-[v:verifies {requirement-version: "1.2", confidence: "high"}]->(TC:TestCase)
(BR:Requirement)-[c:compliance-with {control: "A.5.34", rationale: "PII protection"}]->(GDPR:Compliance)
(WO:WorkOrder)-[d:delta-from {effective-date: "2026-05-15"}]->(WO-prev:WorkOrder)
(SR:Requirement)-[cb:constrained-by {since-version: "1.0"}]->(SPEC:Specification)

4. Cypher-style query examples

4.1 BR, влияющие на KPI X

MATCH (br:Requirement {type:"BR"})-[:goal]->(g:BusinessGoal)-[:impacts-kpi]->(k:KPI {name:"Sales Cycle Time"})
RETURN br.id, br.title, br.status

4.2 Затронутые задачи при изменении SR-05

MATCH (sr:Requirement {id:"SR-05"})<-[:implements]-(t:Task)
WHERE t.status NOT IN ["done", "cancelled"]
RETURN t.id, t.title, t.assignee

4.3 Все требования с PII в GDPR/ФЗ-152 scope

MATCH (r:Requirement)-[:compliance-with]->(c:Compliance)
WHERE c.standard IN ["GDPR", "ФЗ-152"] AND r.data-classification.contains-pii = true
RETURN r.id, r.title, collect(c.control) as controls

4.4 Stale TC (criteria-version drift)

MATCH (r:Requirement)<-[:verifies]-(tc:TestCase)
WHERE tc.last-run.requirement-version < r.version
RETURN r.id, tc.id, tc.last-run.requirement-version, r.version

4.5 Multi-hop: code → test → SR → BR → KPI

MATCH (code:CodeArtifact {path:"src/auth/registration.py"})
      <-[:realises-in]-(tc:TestCase)
      -[:verifies]->(sr:Requirement {type:"SR"})
      -[:parent*1..2]->(br:Requirement {type:"BR"})
      -[:goal]->(g:BusinessGoal)
      -[:impacts-kpi]->(k:KPI)
RETURN code.path, sr.id, br.id, g.name, k.name

«Какие KPI зависят от этого файла кода?» — за один query.

4.6 SPEC dependency cycle detection

MATCH path=(s1:Specification)-[:depends-on*]->(s1)
RETURN path

Returning rows → нарушение DAG invariant (см. 02-schemas.md §9).

4.7 ADAPT с open backward findings

MATCH (a:ADAPT {status:"draft"})-[:contains-backward]->(b:BackwardFinding {status:"open"})
RETURN a.id, count(b) as open_count
ORDER BY open_count DESC

5. Derivation rules

KG — derived от frontmatter артефактов. Не существует «прямого редактирования графа».

5.1 Node derivation

Node type	Источник в frontmatter
`Requirement`	`id`, `type ∈ {BR,SR,TR}`
`Specification`	`id`, `type ∈ {SPEC-ARCH..SPEC-OPS}`
`ADAPT`	`id`, `type: ADAPT`
`BackwardFinding`	ADAPT body parsing
`TestCase`	`id`, `level: TC`
`WorkOrder`	TZ-NNN frontmatter
`Stakeholder`	`business-context.stakeholder` deduplicated
`BusinessGoal`	`business-context.business-goal` deduplicated
`KPI`	`business-outcome.kpi-name` deduplicated
`Compliance`	`compliance.standard` + `compliance.control`

5.2 Edge derivation

Edge	Источник
`parent`	`parent.id` field
`verifies`	`verifies[].id` в TC
`constrained-by`	`constrained-by[]` в SR
`depends-on`	`depends-on[]` в SPEC
`implements-spec`	`implements-spec[]` в TR
`owned-by`	`business-context.stakeholder` → Stakeholder node
`compliance-with`	`compliance[]` массив
`derived-from-adapt`	`source.adapt`
`from-order`	`source.tz-section`
`delta-from`	`parent-adapt` (для ADAPT) или TZ delta

5.3 Refresh policy

Граф rebuilt при:

Любое изменение в .req репозитории / collection (post-commit / post-save hook).
Import TC last-run от CI бота.
Создание/обновление task в task store.

Rebuild — incremental (только затронутые узлы и грани), не full rebuild каждый раз. Full rebuild — раз в неделю reconciliation-агентом.

6. Validation queries (для reconciliation)

Reconciliation-агент запускает graph queries для finding inconsistency:

6.1 Orphan approved requirements

MATCH (r:Requirement {status:"approved"})
WHERE NOT (r)-[:verified-by]->()
RETURN r.id  // approved без TC — warning

6.2 Broken citations

MATCH (r:Requirement)-[:from-order]->(wo:WorkOrder)
WHERE wo.status = "obsolete"
RETURN r.id, wo.id  // citation указывает на obsolete TZ

6.3 Circular parent chain

MATCH path=(r1:Requirement)-[:parent*]->(r1)
RETURN path

6.4 Stakeholder без owned BR

MATCH (s:Stakeholder)
WHERE NOT (s)<-[:owned-by]-()
RETURN s.id  // stakeholder в графе, но nothing assigned

6.5 Test fitting suspicious (AIR-06 signal)

MATCH (tc:TestCase)
WHERE tc.last_modified < tc.criteria_changed_at
  AND tc.last-run.result = "pass"
RETURN tc.id  // criteria недавно меняли, тут же passing — подозрительно

6.6 SR без constrained-by (missing SPEC links)

MATCH (sr:Requirement {type:"SR", status:"approved"})
WHERE NOT (sr)-[:constrained-by]->(:Specification)
RETURN sr.id  // SR approved, но не привязан ни к одному SPEC — warning

6.7 SPEC без referenced-by (orphan SPEC)

MATCH (s:Specification {status:"approved"})
WHERE NOT (s)<-[:referenced-by]-()
  AND NOT (s)<-[:depends-on]-()
RETURN s.id  // возможный мёртвый SPEC

7. Federated queries (cross-project)

Multi-project координация через KG federation. Пример:

MATCH (s1:Specification {project:"princess", type:"SPEC-INT"})
      -[:participates-in]->(int:Specification)
      <-[:participates-in]-(s2:Specification {project:"gerda"})
WHERE int.contract-version <> s1.implemented-version
RETURN s1.id, s2.id, int.id, int.contract-version, s1.implemented-version

Отвечает на «какие cross-team integrations имеют version drift».

Federation — substrate-зависимая операция; реализуется через convention (cross-substrate query layer) или native multi-tenant graph.

8. AI prompt access pattern

8.1 Без графа

Промпт AI содержит:

Контекст: [полное содержимое нескольких .md файлов]
Задача: ...

Проблемы: токены, релевантность, hallucinations (см. AIR-01).

8.2 С графом

Промпт AI содержит structured context:

target-br: BR-05
parent:
  id: BR-05
  business-goal: "Reduce sales cycle"
  stakeholder: "Sales Director"
  data-classification: { contains-pii: true, residency: ["RU"] }
  compliance: ["ФЗ-152 ст.13.1"]
sibling-srs:
  - { id: SR-12, status: verified, scope: "lead intake" }
  - { id: SR-13, status: approved, scope: "lead qualification" }
related-specs:
  - SPEC-API-03 (auth contract, version 1.2)
  - SPEC-SEC-01 (auth model, RBAC)
related-decisions:
  - DEC-2026-04-15: "В этом проекте RLS на уровне БД, не applevel"
related-risks:
  - AIR-09 (privacy leakage) — mitigations active

AI генерирует SR с этим контекстом — больше шансов consistency, меньше hallucinations.

9. Substrate-native реализации

9.1 git substrate (recommended for MVR)

Граф derived от frontmatter всех .md в <project>.req/ + task store.

Пример реализации: embedded SQLite с graph schema:

CREATE TABLE nodes (
    id TEXT PRIMARY KEY,
    type TEXT NOT NULL,
    properties JSON,
    last_modified TIMESTAMP
);

CREATE TABLE edges (
    from_id TEXT,
    to_id TEXT,
    edge_type TEXT,
    properties JSON,
    PRIMARY KEY (from_id, to_id, edge_type)
);

CREATE INDEX idx_edges_from ON edges(from_id);
CREATE INDEX idx_edges_to ON edges(to_id);
CREATE INDEX idx_edges_type ON edges(edge_type);

Альтернатива для больших проектов: embedded graph DB (Kuzu, RedisGraph local).

9.2 Document substrate (Raven и аналоги)

Документные БД с поддержкой графа имеют native graph queries через design views / Cypher-like языки. Не требуют separate infrastructure.

9.3 Schema invariants (independent of substrate)

Node types и edge types — fixed (closed list).
Properties могут эволюционировать (minor schema bump).
Удаление node / edge type — major schema bump + migration.

10. Implementation roadmap

Уровень зрелости	Покрытие графа
RENAR-1 / Core	KG опционален; парсинг frontmatter достаточно.
RENAR-2 / Foundation	Базовый граф: Requirement, TestCase, WorkOrder, Task; edges parent, verifies, verified-by, implements. Простые pre-built queries.
RENAR-3 / Team	Добавить: SPEC, ADAPT, BackwardFinding, Stakeholder, BusinessGoal, KPI, Decision. Edges: constrained-by, depends-on, derived-from-adapt, owned-by, goal, impacts-kpi. AI prompts с graph context.
RENAR-4 / Enterprise	Полная схема + reconciliation queries + federation. Visualization в UI.
RENAR-5	Trend analytics, cross-substrate federation, embedded graph DB для больших репо.

11. Cross-references

Каноничные termini узлов и граней — 01-glossary.md.
Формальные frontmatter schemas (источник derivation) — 02-schemas.md.
AI Risk Register (AIR-10 KG poisoning) — 03-ai-risk-register.md.
Style guide (validator использует KG для cross-reference checks) — 04-ai-style-guide.md.

Knowledge Graph Schema RENAR 1.0-draft — renar.tech