AIFC-012: Metadata and Markdown

Status: Draft 0.1 Standard: AI-First Community Standard Zkráceně: AIFC Navazuje na:

AIFC-000 Manifest AI-first komunity
AIFC-001 Core Concepts
AIFC-002 Community Model
AIFC-010 Knowledge Structure
AIFC-011 Operational DNA

Účel dokumentu: Definovat principy pro zapisování AIFC knowledge base v lidsky čitelné, agenticky použitelné a softwarově validovatelné podobě. Popsat roli Markdownu, metadat, standardizované struktury, lifecycle, ownerů, citlivosti, AI přístupu a údržby.

1. Purpose of this document

Tento dokument popisuje, jak má být knowledge base AIFC komunity zapisována.

AIFC knowledge base má být současně:

human-readable
agent-actionable
software-verifiable

To znamená, že jeden zdroj znalosti musí být použitelný pro tři typy čtenářů:

člověka,
AI agenta,
software nebo validátor.

Markdown je přirozený kandidát, protože je čitelný, jednoduchý, verzovatelný a široce podporovaný. Sám o sobě však nestačí.

AIFC proto kombinuje:

Markdown
+ metadata
+ standardizovanou strukturu
+ validační pravidla
+ Human Cockpit Layer

2. Core principle

Základní princip tohoto dokumentu je:

Markdown gives knowledge a readable body.
Metadata gives knowledge a manageable structure.
Validation gives knowledge operational reliability.

Česky:

Markdown dává znalosti čitelné tělo.
Metadata dávají znalosti řiditelnou strukturu.
Validace dává znalosti provozní spolehlivost.

AIFC nesmí vytvořit systém, kterému rozumí pouze AI nebo pouze vývojáři.

Knowledge base musí zůstat čitelná člověkem.

Zároveň ale nesmí zůstat pouze volným textem bez struktury, protože taková dokumentace se špatně validuje, špatně udržuje a obtížně používá agenticky.

3. Why Markdown

Markdown je vhodný pro AIFC, protože podporuje několik klíčových principů:

je čitelný bez speciální aplikace,
lze ho verzovat v Gitu,
dobře se porovnávají změny,
je dobře čitelný pro AI,
je přenosný mezi nástroji,
umožňuje kombinovat text a strukturu,
podporuje dlouhodobou udržitelnost,
snižuje vendor lock-in.

Markdown není povinná technologie AIFC.

Je to referenční textový formát.

AIFC může být implementováno i jinak, pokud implementace zachová:

lidskou čitelnost,
exportovatelnost,
verzování,
metadata,
auditovatelnost,
agentickou použitelnost,
validovatelnost.

Minimum requirement

AIFC knowledge artefakty musí být exportovatelné do lidsky čitelné a strojově zpracovatelné podoby.

4. Markdown alone is not enough

Samotný Markdown nestačí.

Volný text sice člověk přečte, ale software z něj obtížně pozná:

kdo je owner,
zda je obsah schválený,
zda je zastaralý,
jaká je citlivost,
zda jej smí číst AI,
k jakým hodnotám se vztahuje,
jaký má lifecycle,
kdy má být revidován,
zda je to pravidlo, návrh, rozhodnutí nebo poznámka.

Bez metadat se knowledge base postupně mění v dokumentační chaos.

Minimum requirement

Kritické knowledge artefakty musí mít metadata.

5. Metadata

Metadata jsou strukturované informace o znalostním artefaktu.

Popisují například:

typ artefaktu,
status,
ownera,
citlivost,
AI access,
lifecycle,
vazby na hodnoty,
vazby na rozhodnutí,
review datum,
affected communities,
confidence,
source,
validaci.

Metadata nejsou dekorace.

Jsou provozní vrstva, která umožňuje:

navigaci,
audit,
validaci,
workflow,
Human Cockpit Layer,
AI agentické chování,
security,
cleanup,
maintenance,
reporting,
compliance.

Minimum requirement

Metadata musí být dostatečně jednoduchá, aby je lidé a AI mohli udržovat, ale dostatečně strukturovaná, aby umožnila validaci.

6. Recommended metadata placement

AIFC doporučuje používat metadata buď:

na úrovni souboru,
na úrovni sekce,
na úrovni bloku,
nebo kombinovaně.

6.1 File-level metadata

Vhodné pro dokumenty, které mají jeden jasný účel.

Příklad:

---
aifc_type: values
status: active
owner: community-owner
sensitivity: internal
ai_access: allowed
review_cycle: quarterly
last_reviewed: 2026-06-15
---

6.2 Section-level metadata

Vhodné pro dlouhé dokumenty, kde různé části mají různý status, ownera nebo citlivost.

Příklad:

## AI-NDA Boundary

metadata:
  status: approved
  owner: security-owner
  sensitivity: restricted
  ai_access: limited

6.3 Block-level metadata

Vhodné tam, kde jednotlivé bloky mají samostatný význam, lifecycle nebo schvalování.

Například:

jednotlivé návrhy změn,
jednotlivá pravidla,
jednotlivá rozhodnutí,
jednotlivé skills,
jednotlivé risks,
jednotlivé assumptions.

Block-level metadata umožňují Human Cockpit Layer zobrazovat a spravovat obsah po menších částech.

Minimum requirement

AIFC implementace musí definovat, na jaké úrovni se metadata používají a jak se dědí mezi složkou, souborem, sekcí a blokem.

7. Metadata inheritance

Metadata se mohou dědit z vyšší struktury.

Například složka může určovat:

/work/maintenance/high-priority/

a tím předávat výchozí hodnoty:

work_type: maintenance
priority: high

Soubor nebo blok může tyto hodnoty zpřesnit nebo dočasně změnit.

Dědičnost metadat pomáhá omezit opakování.

Zároveň však může vytvářet riziko nesouladu.

Například soubor je ve složce maintenance, ale blok uvnitř má metadata work_type: change.

To nemusí být chyba. Může to být signál, že blok má být přesunut nebo přeřazen.

Minimum requirement

AIFC implementace musí definovat pravidla dědičnosti a pravidla řešení konfliktu mezi inherited metadata a explicit metadata.

8. Reclassification and cleanup

Knowledge base se vyvíjí.

Artefakt může změnit:

typ,
prioritu,
ownera,
citlivost,
status,
AI access,
lifecycle,
rozhodovací úroveň.

AIFC proto musí podporovat reclassification.

Reclassification může proběhnout:

ručně člověkem,
přes Human Cockpit Layer,
návrhem AI agenta,
nebo cleanup agentem.

Cleanup agent může pravidelně kontrolovat, zda metadata odpovídají umístění, struktuře a pravidlům.

Například:

task je ve špatné složce,
block má prioritu high, ale je v low-priority souboru,
dokument je active, ale obsahuje deprecated sekce,
AI access je allowed, ale sensitivity je restricted,
artefakt nemá ownera,
workflow je critical, ale nemá fallback.

Minimum requirement

AIFC knowledge base musí mít mechanismus pro detekci a řešení metadata conflicts.

9. Avoid fragile sequential IDs

AIFC nedoporučuje používat lidsky viditelné sekvenční ID jako hlavní identitu bloků.

Například:

TASK-001
TASK-002
TASK-003

Taková ID mohou být křehká, pokud se obsah vkládá mezi existující položky, přesouvá nebo slučuje.

Může vznikat:

nutnost přečíslování,
mezery,
duplicitní ID,
zavádějící pořadí,
konflikt mezi identitou a pozicí.

AIFC proto doporučuje oddělit:

identity
order
display order
priority

Identita artefaktu má být stabilní. Pořadí a priorita se mohou měnit.

Minimum requirement

Pokud implementace používá ID, musí rozlišovat stabilní identitu artefaktu od jeho pořadí v dokumentu nebo backlogu.

10. Stable identity

Stabilní identita artefaktu může být založena například na:

UUID,
krátkém náhodném ID,
hash-based ID,
system-generated ID,
kombinaci namespace a ID,
nebo identitě uložené v metadatech.

Příklad:

id: cp_8f3a91
type: change_proposal

Stabilní ID nemusí být krásné pro člověka.

Člověk může pracovat s názvem, stavem, prioritou a kontextem.

Systém potřebuje stabilní ID pro:

odkazy,
historii,
vazby,
audit,
přesuny,
slučování,
validaci.

Minimum requirement

Kritické artefakty, které mají lifecycle nebo vazby, musí mít stabilní identitu.

11. Standardized structure

AIFC knowledge base nesmí mít kreativní strukturu podle toho, který člověk nebo AI agent ji zrovna vytvářel.

Nekonzistentní struktura vytváří attention debt.

Člověk se musí znovu učit každý projekt, každé repo a každou složku.

AI agent také ztrácí spolehlivost, pokud každý workspace vypadá jinak.

AIFC proto doporučuje standardizovanou strukturu:

jednotné názvy domén,
jednotné typy artefaktů,
jednotné metadata keys,
jednotné lifecycle states,
jednotné decision records,
jednotné change proposal schema,
jednotné skill schema,
jednotné AI governance schema.

Minimum requirement

AIFC komunita musí mít dokumentovaná pravidla struktury a pojmenování.

AI agent nesmí svévolně vytvářet nové složky, názvy a šablony mimo pravidla komunity.

12. Minimal metadata fields

Kritické artefakty by měly mít minimálně:

id:
title:
aifc_type:
status:
owner:
sensitivity:
ai_access:
created_at:
updated_at:
review_cycle:
related_values:
related_decisions:

Ne každý artefakt musí mít všechna metadata.

Ale čím kritičtější artefakt, tím více struktury potřebuje.

Recommended minimum by criticality

Low criticality:
title, type, status

Medium criticality:
title, type, status, owner, updated_at

High criticality:
id, title, type, status, owner, sensitivity, ai_access, review_cycle, related_decisions

Operational DNA:
id, title, type, status, owner, sensitivity, ai_access, review_cycle, access_roles, exit_strategy, fallback, audit

13. Common metadata keys

Doporučené obecné metadata keys:

id:
title:
aifc_type:
status:
owner:
sensitivity:
ai_access:
human_access_roles:
created_at:
updated_at:
last_reviewed:
review_cycle:
source:
confidence:
related_values:
related_purpose:
related_strategy:
related_decisions:
related_workflows:
related_skills:
related_risks:
affected_communities:

aifc_type

Určuje typ artefaktu.

Příklady:

purpose
value
strategy
decision_record
workflow
human_skill
ai_skill
observed_signal
change_proposal
risk
ai_workflow
security_rule
community_interface
operational_dna

status

Určuje lifecycle.

Příklady:

draft
proposed
under_review
approved
active
deprecated
archived
rejected

sensitivity

Určuje citlivost.

Příklady:

public
internal
restricted
operational_dna

ai_access

Určuje AI přístup.

Příklady:

allowed
limited
forbidden
requires_approval

14. Lifecycle states

AIFC doporučuje jednotné lifecycle states:

draft
proposed
under_review
approved
active
deprecated
archived
rejected

Pro Operational DNA může být doplněno:

restricted
compromised

Why it matters

Bez lifecycle komunita neví, čemu má věřit.

AI agent nesmí používat deprecated nebo rejected artefakty jako aktuální pravidlo.

Human Cockpit Layer musí umět zobrazit, co je draft, co čeká na review a co je schválené.

Minimum requirement

Kritické artefakty musí mít lifecycle status.

15. Sensitivity and AI access

Sensitivity a AI access nejsou totéž.

Sensitivity

Říká, jak citlivý je obsah.

Příklad:

sensitivity: restricted

AI access

Říká, zda a jak s ním smí pracovat AI.

Příklad:

ai_access: limited

Restricted obsah může být pro některé AI nástroje zakázán, pro jiné povolen v rámci AI-NDA boundary.

Public obsah může být pro AI povolen, ale stále může vyžadovat kontrolu, pokud AI generuje veřejný výstup.

Minimum requirement

Kritické artefakty musí mít odděleně definovanou citlivost a pravidlo AI přístupu.

16. Metadata for AI workflows

AI workflow musí mít metadata, která umožní governance.

Příklad:

id: aiw_7c91ab
title: Draft Jira ticket from change proposal
aifc_type: ai_workflow
status: active
owner: ai-governance-owner
sensitivity: internal
ai_access: allowed
model_dependency: replaceable
human_approval_required: true
fallback_required: true
fallback_defined: true
exit_strategy_required: true
related_values:
  - resilience
  - accountability

Minimum requirement

Kritické AI workflow musí mít metadata pro:

ownera,
scope,
data sensitivity,
AI access,
approval,
fallback,
exit strategy,
audit,
related values.

17. Metadata for change proposals

Change proposal metadata musí umožnit řízený feedback loop.

Příklad:

id: cp_8f3a91
title: Add non-AI fallback for routine implementation tasks
aifc_type: change_proposal
status: submitted
proposer_type: human
source_signal: ai_dependency_observed
proposal_type: ai_dependency
decision_level: ai_governance_owner
affected_values:
  - resilience
  - human_capability
affected_communities:
  - development_team

Minimum requirement

Change proposal musí mít metadata pro:

status,
proposer,
proposal type,
decision level,
affected values,
affected communities,
source signal.

18. Metadata for skills

Human skills a AI skills musí být odlišitelné.

Human skill

id: hskill_2d41aa
title: Write clear dashboard requirements
aifc_type: human_skill
status: active
owner: ux-lead
sensitivity: internal
review_cycle: yearly
related_values:
  - clarity
  - attention_protection

AI skill

id: askill_94c7f1
title: Generate dashboard UX review
aifc_type: ai_skill
status: active
owner: ux-lead
sensitivity: internal
ai_access: allowed
human_approval_required: true
related_human_skill: hskill_2d41aa

Minimum requirement

Kritické AI skills musí být navázané na lidsky čitelnou znalost nebo human skill.

AI skill nesmí být jediným nositelem know-how.

19. Metadata for decisions

Decision records musí být dohledatelné a propojené.

Příklad:

id: dr_3b72e4
title: Use Human Cockpit Layer as AIFC concept
aifc_type: decision_record
status: approved
owner: standard-owner
decision_date: 2026-06-15
related_values:
  - human_control
  - attention_protection
related_documents:
  - AIFC-001
  - AIFC-002

Decision record by měl propojit:

kontext,
rozhodnutí,
důvod,
alternativy,
dopady,
review date,
affected artefacts.

Minimum requirement

Významná rozhodnutí musí mít stabilní ID a vazby na dotčené artefakty.

20. Metadata for review

Review metadata pomáhají bránit degradaci znalostí.

Příklad:

last_reviewed: 2026-06-15
review_cycle: quarterly
next_review_due: 2026-09-15
review_owner: knowledge-owner

Neudržovaná knowledge base časem degraduje.

To, co není revidováno, se postupně mění z aktivní znalosti na riziko.

Minimum requirement

Kritické artefakty musí mít review mechanismus.

21. Markdown block structure

AIFC může používat blokový přístup.

Blok je samostatná část knowledge base, která má vlastní význam, metadata nebo lifecycle.

Příklady bloků:

pravidlo,
rozhodnutí,
návrh změny,
risk,
assumption,
task,
skill step,
anti-pattern,
observed signal.

Blokový přístup pomáhá Human Cockpit Layer zobrazovat obsah po menších jednotkách.

Člověk nemusí číst dlouhý dokument najednou. AI agent může pracovat s konkrétním blokem. Validátor může ověřit konkrétní pravidlo.

Minimum requirement

Pokud implementace používá block-level metadata, musí definovat stabilní identitu bloku a pravidla přesunu bloku mezi soubory.

22. Folder and file naming

AIFC doporučuje, aby názvy složek a souborů byly:

stabilní,
předvídatelné,
nekreativní,
dokumentované,
validovatelné,
použitelné pro lidi i AI.

Názvy nemají být generovány libovolně podle stylu konkrétního agenta.

Příklad špatného vzoru:

/Important Stuff
/AI Ideas
/New Docs
/Final FINAL
/Maybe useful

Příklad lepšího vzoru:

/purpose
/values
/strategy
/decisions
/workflows
/skills/human
/skills/ai
/feedback/change-proposals
/security
/ai-governance

Minimum requirement

AIFC workspace musí mít jednotná pravidla pro názvy složek a souborů.

23. Root README

AIFC workspace by měl mít jeden standardizovaný root README.

Root README má říkat:

že jde o AIFC workspace,
jaká je jeho struktura,
jak se v něm orientovat,
kde jsou must rules,
kde je source of truth,
jak se vytváří nové artefakty,
co AI agenti smí a nesmí,
jak se pracuje s Human Cockpit Layer,
jak se provádí validace.

Root README nemá být kreativní úvodní text.

Má být stabilní navigační a governance dokument.

Minimum requirement

AIFC workspace musí mít lidsky čitelný vstupní bod.

24. AI agent rules for structure

AI agenti nesmí svévolně měnit strukturu knowledge base.

Agent musí:

respektovat existující folder structure,
používat schválené templates,
dodržovat metadata schema,
nevytvářet nové typy artefaktů bez schválení,
nepřejmenovávat složky bez change proposal,
označit nejistotu,
navrhovat změny struktury jako change proposal.

Minimum requirement

Každý AI agent s právem zapisovat do knowledge base musí mít pravidla pro práci se strukturou.

25. Human editing

AIFC musí respektovat, že lidé mohou editovat text přímo.

Přímá editace je síla textového source of truth.

Zároveň ale vytváří rizika:

chybějící metadata,
porušení struktury,
přesun bloků bez aktualizace vazeb,
změna statusu bez decision record,
vložení restricted obsahu do public části,
neúmyslné vytvoření konfliktu.

Proto má být přímá editace podporována validátory a cleanup agentem.

Minimum requirement

AIFC workspace musí mít mechanismus, který pomáhá lidem najít a opravit strukturální chyby po ruční editaci.

26. Validation

Validace ověřuje, zda knowledge base dodržuje pravidla.

Může kontrolovat například:

chybějící owner,
chybějící status,
chybějící sensitivity,
restricted obsah s povoleným AI access,
AI workflow bez fallbacku,
critical workflow bez ownera,
deprecated artefakt používaný jako active,
change proposal bez decision level,
decision record bez vazby,
skill bez review,
Operational DNA bez ochrany.

Validace nemá být trestající mechanismus.

Má chránit komunitu před degradací knowledge base.

Minimum requirement

Kritické AIFC workspaces musí mít validační pravidla pro minimální metadata a bezpečnostní konflikty.

27. Cleanup agent

Cleanup agent je AI nebo software agent, který pomáhá udržovat knowledge base.

Může:

hledat metadata conflicts,
navrhovat přesuny bloků,
označovat deprecated obsah,
hledat duplicity,
hledat artefakty bez ownera,
detekovat missing review,
upozorňovat na AI access conflicts,
vytvářet maintenance tasks,
navrhovat change proposals.

Cleanup agent nesmí svévolně měnit kritický obsah bez oprávnění.

Minimum requirement

Cleanup agent musí mít scope, oprávnění, audit a pravidla schvalování.

28. Human Cockpit Layer and metadata

Human Cockpit Layer používá metadata k tomu, aby chránil lidskou pozornost.

Metadata umožňují zobrazit například:

co je důležité,
co čeká na review,
co je deprecated,
co je restricted,
co vyžaduje schválení,
co navrhla AI,
co je Operational DNA,
co nemá ownera,
co má blížící se review,
co je v konfliktu se strukturou.

Bez metadat by Human Cockpit Layer musel pouze zobrazovat dokumenty.

S metadaty může zobrazovat stav systému.

Minimum requirement

Metadata musí být navržena tak, aby podporovala nejen AI a validaci, ale i lidskou orientaci.

29. Portability

AIFC metadata a Markdown struktura musí být přenositelná.

Portabilita znamená, že komunita může:

exportovat knowledge base,
přenést ji do jiného nástroje,
nahradit AI vendora,
spustit jiný Human Cockpit Layer,
auditovat obsah mimo původní systém,
obnovit provoz ze zálohy.

Minimum requirement

Kritické artefakty, metadata a skills nesmí být uzamčené pouze v proprietárním nástroji bez exportu.

30. Minimal example of an AIFC Markdown artefact

Příklad jednoduchého artefaktu:

---
id: wf_4a92c1
title: Change Proposal Review Workflow
aifc_type: workflow
status: active
owner: governance-owner
sensitivity: internal
ai_access: allowed
review_cycle: quarterly
related_values:
  - accountability
  - human_control
related_decisions:
  - dr_3b72e4
---

# Change Proposal Review Workflow

## Purpose

This workflow defines how submitted change proposals are reviewed, decided and written back to the source of truth.

## Inputs

- submitted change proposal
- observed signal
- affected values
- proposed decision level

## Outputs

- accepted, rejected or deferred proposal
- decision record
- source of truth update

## Rules

AI may summarize and analyze the proposal.

AI must not approve significant changes.

Human or community governance owns the decision.

## Fallback

If AI tools are unavailable, the workflow can be executed manually using the same checklist.

31. Anti-patterns

AIFC odmítá následující anti-patterny.

31.1 Markdown without metadata

Obsah je čitelný, ale neříditelný.

31.2 Metadata without readability

Obsah je strukturovaný, ale lidé mu nerozumí.

31.3 Creative folder structure

Každý projekt má jiné názvy, jiný layout a jiná pravidla.

31.4 AI-created structure without approval

AI agent vytvoří nové složky, šablony nebo typy artefaktů bez governance.

31.5 Sequential IDs as primary identity

Identita artefaktu je založená na pořadí, které se při změnách rozpadá.

31.6 Deprecated content used as truth

Zastaralý obsah je stále používán lidmi nebo AI agenty.

31.7 No owner

Artefakt existuje, ale nikdo za něj neodpovídá.

31.8 No sensitivity

Není jasné, zda obsah smí vidět AI, člověk nebo externí nástroj.

31.9 Human Cockpit without source of truth

Lidské rozhraní zobrazuje informace, které nejsou napojené na autoritativní knowledge base.

31.10 Source of truth without human access

Knowledge base je formálně správná, ale lidé ji neumí používat.

32. Minimal requirements

AIFC komunita musí v oblasti Metadata and Markdown minimálně splnit:

Knowledge artefakty jsou lidsky čitelné.
Kritické artefakty mají metadata.
Kritické artefakty mají ownera.
Kritické artefakty mají lifecycle status.
Kritické artefakty mají sensitivity classification.
AI access je oddělený od sensitivity.
AI workflow mají metadata pro approval, fallback a exit strategy.
Change proposals mají metadata pro lifecycle a decision level.
Decision records mají stabilní identitu.
Skills rozlišují human skill a AI skill.
Deprecated artefakty nejsou používány jako aktuální source of truth.
Folder and file structure je standardizovaná.
AI agenti nesmí svévolně měnit strukturu.
Root README nebo jiný vstupní bod vysvětluje strukturu workspace.
Ruční editace je podporována validací nebo cleanup procesem.
Metadata podporují Human Cockpit Layer.
Knowledge base je exportovatelná a přenositelná.
Operational DNA má zvláštní metadata a ochranu.

33. Summary

AIFC knowledge base musí být čitelná, řiditelná a ověřitelná.

Markdown pomáhá zachovat lidskou čitelnost.

Metadata pomáhají řídit lifecycle, vlastnictví, citlivost, AI přístup a vazby.

Validace chrání knowledge base před degradací.

Human Cockpit Layer používá metadata k tomu, aby člověk nemusel číst celý repozitář, ale viděl stav systému.

AI agenti používají metadata k tomu, aby jednali podle pravidel, nikoli podle dojmu.

AIFC proto říká:

Readable text is not enough.
Structured data is not enough.
AIFC knowledge must be readable, actionable and verifiable.

Česky:

Čitelný text nestačí.
Strukturovaná data nestačí.
AIFC znalost musí být čitelná, použitelná a ověřitelná.

Metadata and Markdown turn community knowledge into a maintainable operating system.