Платформа — Документная Система

ЧТО?     → содержание — о чём документ
ЧЕМ?     → формат    — в каком виде записан (.md, .yaml, .csv)
КАК?     → структура — как организован внутри
ГДЕ?     → путь      — где физически находится
СКОЛЬКО? → объём     — размер, количество разделов

ЗАЧЕМ?  → назначение — для чего создан
КТО?    → аудитория  — кто читает
КОГДА?  → версия     — когда создан / изменён

$WORKSPACE = исходники (source)
$DATASPACE = результат обработки (output / binary / data)

✅ Код:          .py .js .ts .tsx .jsx .php .go .sh
✅ Документация: .md .ai.md .fx.md .txt .rst
✅ Конфигурация: .yaml .json .toml .ini .xml
✅ Web-код:      .html .css .scss .less
✅ Шаблоны:      .twig .tpl .j2
✅ SQL:          .sql
✅ Специальные:  .gitignore .gitkeep Dockerfile Makefile LICENSE

❌ Графика:    .svg .ico .jpg .jpeg .png .gif .webp
❌ Шрифты:     .woff2 .ttf .otf .eot
❌ Медиа:      .mp4 .avi .mov .mp3 .wav
❌ Документы:  .pdf .docx .doc .rtf
❌ Данные:     .xlsx .xls .ods .csv
❌ Базы:       .db .sqlite

.credentials.md   — секреты (НЕ в git)

chmod 600 .credentials.md    # только владелец может читать

*.credentials.md

У0  ТЕОРИЯ        Универсальные законы. Не зависят от платформы.
                  Меняется: НИКОГДА (LOCKED)

У0  КОНЦЕПЦИЯ     Как МЫ видим нашу платформу.
                  Меняется: редко, только большие решения

У1  СТАНДАРТЫ     Наши правила — как делать конкретные вещи.
                  Меняется: при эволюции платформы

У2  ПАТТЕРНЫ      Рецепты — типовые решения типовых задач.
                  Меняется: по мере накопления опыта

У3  ШАБЛОНЫ       Заготовки — готовые формы для заполнения.
                  Меняется: постоянно растёт

У4  РЕАЛИЗАЦИЯ    Конкретный код / конфиг / данные.
                  Меняется: часто

У0 ТЕОРИЯ → У0 КОНЦЕПЦИЯ → У1 СТАНДАРТЫ → У2 ПАТТЕРНЫ → У3 ШАБЛОНЫ → У4 РЕАЛИЗАЦИЯ

ПЛАТФОРМА
  ├── АРХ          architect/        — методология, стандарты, теория
  ├── ПРО          projects/         — проекты
  │     └── ПРОЕКТ     projects/org/{name}/
  │           └── КОМПОНЕНТ    @name.type/
  │                 └── ПОДКОМПОНЕНТ
  ├── SYS ⏸        system/           — агенты, планировщик, мониторинг
  └── ИНФРА ⏸      infra/            — серверы, деплой

                  АРХ   ПРО   ПРОЕКТ   КОМПОНЕНТ
У0 ТЕОРИЯ          ✅    —      —          —
У0 КОНЦЕПЦИЯ       ✅    —      —          —
У1 СТАНДАРТ        ✅    —      —          —
У2 ПАТТЕРН         ✅    ✅     —          —
У3 ШАБЛОН          ✅    ✅     ✅         —
У4 РЕАЛИЗАЦИЯ      —     —     ✅         ✅

## ЗАЧЕМ          — проблема / цель
## ПРАВИЛА        — жёсткие требования
## ПРИМЕРЫ        — как применять
## ИСКЛЮЧЕНИЯ     — когда можно нарушить

## Контекст       — какая проблема, почему возникла
## Решение        — что решили делать
## Альтернативы   — что рассматривали, почему отказались
## Последствия    — что изменится, плюсы / минусы

## Цель           — чего хотим достичь
## Scope          — границы: что входит, что нет
## Фазы           — последовательность шагов
## Риски          — что может пойти не так

## Описание           — что не так / что нужно сделать
## Критерии готовности — когда считать выполненным
## Откат              — как вернуть назад если сломалось

У4 РЕАЛИЗАЦИЯ → ВОПЛОЩЕНИЕ → АРТЕФАКТ
                               (работающий сервис / данные / продукт)

УРОВЕНЬ        АВТОР              ДОСТУП
────────────────────────────────────────────────────
У0 ТЕОРИЯ      Архитектор         Архитектор
У0 КОНЦЕПЦИЯ   Архитектор         Архитектор, Проектор
У1 СТАНДАРТ    Архитектор         Все роли
У2 ПАТТЕРН     Арх + Кодер        Проектор, Кодер
У3 ШАБЛОН      Кодер              Проектор, Кодер, Инфра
У4 РЕАЛИЗАЦИЯ  Кодер + Инфра      Кодер, Инфра, AI

---
type: standard|concept|decision|pattern|template|analysis|research|practice|plan|instruction|ticket
title: "Название документа"
status: draft|development|testing|active|archived|deprecated
date: YYYY-MM-DD
---

version: X.Y.Z      # для версионируемых документов (стандарты, концепции)
owner: architect     # для документов с явным владельцем

id: ADR-001                  # для decisions / tickets
priority: HIGH               # для tickets
knowledge_level: У1          # У0|У1|У2|У3|У4
fractal_level: arch          # arch|pro|project|component|subcomponent
parent: path/to.md           # ссылка вверх по каскаду
derived_from: path/to.md     # деривация: от какого документа
part_of: path/to.md          # декомпозиция: частью чего является
spawns: [a.md, b.md]         # что породил
phase: 3                     # фаза Проектора (0–15), только для проектных документов
tags: [api, security]
audience: [architect, coder]

standards/format/
  ├── format-file-types.md        ← родитель
  └── format-file-types-web.md   ← дочерний

standards/
  ├── naming.md                   ← было
  └── naming/                     ← стало (декомпозиция)
        ├── naming.md             ← родитель (теперь индекс)
        ├── naming-files.md
        └── naming-folders.md

projects/org/
  └── pirotehnika/
        ├── CLAUDE.md             ← обязательно
        └── ...

# .git/hooks/pre-commit
LOCKED=$(git diff --cached --name-only | grep "\.fx\.md$")
if [ -n "$LOCKED" ]; then
  echo "❌ Защищённый файл: $LOCKED"
  echo "Требуется согласование с Архитектором."
  exit 1
fi

GFM (GitHub Flavored Markdown)  — база
  ↓
Pandoc extensions               — расширения
  ↓
Custom transclusion             — компиляция

::: warning
**Внимание:** Это важное предупреждение.
:::

::: note
Примечание для читателя.
:::

::: example
Пример использования.
:::

✅ [Стандарт](./format-file-types.md)
✅ [Секция](#название-раздела)
✅ [Родитель](../MASTER.md)

❌ [Стандарт](/opt/claude-workspace/architect/standards/file.md)
❌ [Файл](C:\Users\...\file.md)

MASTER.md                    ← Верхний уровень (обзор)
  ↓ ссылка
  DETAIL_1.md               ← Средний уровень (детали)
    ↓ ссылка
    SUBDETAIL_1.1.md        ← Нижний уровень (реализация)

---
type: detail
title: "Архитектура платформы"
parent: ../MASTER.md
---

## Детали структуры

[→ Читать отдельно](./details/STRUCTURE_DETAILS.md)

<!-- INCLUDE: ./details/STRUCTURE_DETAILS.md -->

python3 architect/tools/md-compile.py INPUT.md OUTPUT.md

DRAFT → DEV → TEST → PROD → ARCHIVE

❌ DRAFT → PROD (без DEV и TEST)
✅ DRAFT → DEV → TEST → PROD

❌ PROD → DRAFT (слишком далеко)
✅ PROD → TEST → DEV (постепенно)

❌ ARCHIVE → PROD
✅ ARCHIVE → (создать новый документ/проект)

ANY → SUSPENDED     # Приостановка из любой стадии
SUSPENDED → ANY     # Возобновление в ту же стадию
ANY → CANCELLED     # Отмена из любой стадии
TEST → FAILED       # Провал тестирования
PROD → DEPRECATED   # Устаревание перед архивацией

ДРОБИТЬ   — если части используются раздельно
ДЕРЖАТЬ   — если используются вместе
МАКСИМУМ  — 5000 строк (~100 страниц)

MAJOR.MINOR.PATCH

PATCH  — опечатки, форматирование       1.0.0 → 1.0.1
MINOR  — новая секция, уточнения        1.0.1 → 1.1.0
MAJOR  — изменение структуры, breaking  1.1.0 → 2.0.0