Disputa
Автору курса

Формат папки курса

Справочник формата v1 — файлы курса, поля работы и критерия, способы проверки, разметка шагов и тестов, темы, настройки курса, правила проверки.

Курс как код — это папка: файлы Markdown с шапкой YAML, по файлу на работу, тест и тему. Её пишет человек в редакторе или его агент, она лежит в репозитории или на диске и приходит на платформу через «Источники». Здесь — сам формат: что где лежит и какие поля бывают.

Пометка «скоро»

Формат описан целиком, версия 1. Где стоит «скоро», платформа это пока не читает: формат уже такой, можно писать по нему заранее.

Папка

course.yaml                 настройки курса и откуда что берётся
disputa.yaml                где лежат файлы и уровни правил проверки
roles.md                    роли команды
works/03-brif-produkta.md   работа 3
works/03-brif-produkta/tests/  тесты курса к работе 3 (скоро)
quizzes/04-letuchka.md      тест 4
quizzes/04-letuchka.gift    или тот же тест в GIFT
quizzes/04-letuchka.yaml    шапка теста в GIFT
topics/rekomendacii.md      тема проекта на весь курс
topics/brif-produkta/a.md   вариант работы brif-produkta
lessons/01-vvedenie.md      лекция или семинар, слайды Marp
themes/sii.css              своя тема лекций, CSS Marp
materials/rpd.md            материал основы курса: ссылка или своя методичка
course.json                 или весь курс одним файлом

Чего в папке нет, то не меняется: нет roles.md — роли курса не трогаются. Файл, который не читается, пропускается с причиной, остальные приходят. Работа со сломанным файлом в разборе не пропадает: там видны путь к файлу и причина, а в курсе работа остаётся как была, пока файл не поправят.

Работа

Файл works/<номер>-<ключ>.md. Номер в имени задаёт порядок: 03-brif-produkta.md — работа 3. Поля и критерии — в шапке между ---, шаги — в теле.

---
# yaml-language-server: $schema=https://disputa.ru/schema/v1/work.json
version: 1
title: Бриф продукта
mission: Зачем эта работа и что участник поймёт
points: 10
criteria:
  - key: metric
    text: Описана метрика успеха и способ её подсчёта
    role: product
    check: { type: llm, find: метрика успеха, good: измерима, bad: общие слова }
    ask: Почему эта метрика?
    expect: Связь метрики с задачей пользователя
---
## Подготовка
### Соберите бриф {#brif}
Текст шага.

Ключ работы — остаток имени файла: brif-produkta. По нему работа сопоставляется с курсом, поэтому переставить работы — значит поменять номера в именах, а не завести их заново: в разборе у работ поменяется «номер», отметки «правлено здесь» и варианты останутся при своей работе. Задать явно — key в шапке. Переименовать файл можно: тот же номер и похожее содержимое (то же название или хотя бы половина общих критериев) — это та же работа под новым ключом. В разборе у неё изменится «ключ (имя файла)», строка курса останется прежней — со сдачами, вердиктами, вариантами и отметками «правлено здесь»; откат вернёт прежний ключ. У работ, которые завели до ключей, ключ взят из названия — первое чтение папки предложит ключ из имени файла. Непохожая работа под тем же номером — новая, а прежняя «нет в источнике»: иначе чужая работа легла бы на сдачи прежней.

Версия формата: version: 1 в шапке, нет — значит 1. Файл другой версии пропускается с причиной. Схема: строка yaml-language-server с адресом схемы — с ней VS Code (расширение YAML) и другие редакторы подсказывают поля и подчёркивают опечатку ещё до проверки. Схемы: work, quiz, lesson, topic, variant, course, roles, disputa — https://disputa.ru/schema/v1/<имя>.json. fmt ставит строку сам.

Поля работы

ПолеЧто этоПо умолчанию
numberномер работы, 1–99из имени файла
titleназвание; без него не опубликовать—
missionзачем работа, одной-двумя фразами—
briefзадание целиком—
hrefгде задание лежит у курса: страница сайта, файл—
weeksнедели курса, строкой—
pointsбаллы за работу, 0–100010
gradingModepoints — баллами, pass_fail — зачётомpoints
passShareдоля, с которой работа зачтена—
requiredбез неё итога нетfalse
categoryкатегория итога: строка ведомости со своим бюджетом—
assessmentcriteria — по критериям, holistic — по описанию результатаcriteria
reviewKindtalk — приёмка разговором, written — письменноtalk
submitKindpull_request, commit, file, url, nonepull_request
submitByperson — каждый сам, group — командаperson
submitFieldsполя сдачи рядом с PR: key, label, kind (url или text), required, hint—
sessionCardкарточка приёмки для ведущего: тайминг, на что смотреть—
linksдоп. ссылки участнику «почитать к работе»: title, url, about—
variantRuleкак раздаются варианты: list_number, random, choice—
criteriaкритерии, ниже—

Вариант работы — отдельный файл в topics/<ключ работы>/, а в работе остаётся только variantRule, см. Темы проектов и варианты. Список variants в шапке (key, title, body, reference) тоже читается, пока в папке нет topics/.

Критерий

ПолеЧто это
keyстабильный ключ: по нему приходят вердикты и считается история
textчто должно быть сделано
roleк какой роли команды; нет — к каждому
appliesToeach, role или group — вся команда; обычно выводится сам
groupгруппа критериев в карточке
weightвес, 0–100, по умолчанию 1
checkспособ проверки, ниже
askвопрос к приёмке
expectчто засчитываем за ответ
redFlagпризнак, что артефакт есть, а понимания нет
visibilityкогда участник видит вердикт: visible, after_due, staff

Не пишите в критерии путь к файлу и нижнюю границу «не меньше N»: агент ищет артефакт по смыслу, а счёт подменяет суть. Верхняя граница («одна страница») допустима.

Способы проверки

checkПоляКто решает
commandrun, expect: exit_zero или output_matches с patternкод, по выводу команды в песочнице
filesfind: какой артефакт искать по смыслуагент
structurefind, count, schema: чего и сколько в артефактеагент
httpurlFrom: team.prodUrl, team.repoUrl или field с field; expect: status_2xxкод
llmfind, good, bad: что искать, закрыт если, не закрыт еслимодель по уликам
humanhow: как проверитьчеловек на приёмке

Автотесты (скоро)

Тесты курса — тот же command, только с отчётом: доля прошедших тестов даёт долю веса критерия.

criteria:
  - key: api-tests
    text: Эндпоинты отвечают по контракту
    check:
      type: command
      setup: pip install -r requirements.txt
      run: pytest tests/ --junitxml=report.xml
      report: junit           # junit, gradescope или prairielearn
      tests: "test_api_*"     # какие тесты отчёта относятся к критерию
    visibility: after_due

Тесты лежат рядом с работой, в works/<работа>/tests/, и кладутся в песочницу к копии работы. Скрытые тесты агент, который смотрит работу, не видит: их убирают из песочницы до разведки. Импорт из GitHub Classroom (autograding.json), затем из Gradescope и PrairieLearn.

Шаги

Тело работы — шаги, та же разметка, что в редакторе шагов:

## Подготовка                       этап, держится до следующего
Зачем этот этап.
### Поставьте Python {#python}      шаг: заголовок и ключ
Текст шага, `код`, [ссылка](https://example.com), списки.
? Вопрос «Проверь себя»
- [x] верный вариант → почему
- [ ] неверный
> проверка: README.md
[Готово]
---
### Следующий шаг

Шаг опознаётся по ключу {#ключ}, а без него — по заголовку ###. Ставьте ключ, если заголовок будут править: отметки участников держатся за ключ.

Тест

Файл quizzes/<номер>-<ключ>.md: шапка как у работы, вопросы — в теле. Номер и ключ — из имени, как у работы; нумерация у работ и тестов общая.

---
title: Летучка 4
category: mini-tests
lesson: evaluation
quiz: { open: button, minutes: 10, attempts: 1 }
---
Код или картинка перед вопросом видны вместе с ним.
? (2) Какая метрика подходит? {#metric}
- [x] Recall@k → ищем, нашлось ли нужное
- [ ] BLEU {#bleu}
> разбор: почему так
---
? Столица Франции
= Париж
  • ? (2) — баллы вопроса, по умолчанию 1; {#ключ} — ключ вопроса или варианта. Ответы держатся за ключи, поэтому варианты можно переставлять.
  • - [x] — верный, - [ ] — неверный, после → — почему. Несколько [x] — выбор нескольких.
  • = ответ — короткий ответ: принимаемые варианты, без учёта регистра и «ё».
  • > разбор: — виден вместе с ответами. --- — следующая страница.

Настройки теста — поле quiz:

ПолеЧто этоПо умолчанию
openbutton — открывает преподаватель, schedule — по окну, due — до срокаbutton
minutesминут на попыткубез лимита
attemptsсколько попыток1
countкакая в зачёт: best или lastbest
revealкогда видны ответы: closed, submitted, manualclosed
shuffleсвой порядок у каждогоtrue
sampleN случайных вопросов из наборавсе
partialнесколько верных: all — всё или ничего, partial — частичноall
codeвход по коду с экранаfalse
graceзапас на сеть после конца времени, секунд30

По какой лекции — lesson. Ключ занятия, по которому тест: lesson: evaluation для lessons/03-evaluation.md. У участника тест стоит сразу после этой лекции и её работы. Без lesson тест встанет по номеру, и проверка курса это отметит, если в курсе есть занятия.

Порядок у участника

У участника лекции, работы и тесты идут одним списком в сайдбаре:

  • занятия — по своим номерам;
  • работа — после последнего занятия, которое к ней готовит (work у занятия);
  • тест — сразу после лекции, по которой он (lesson у теста), после её работ: лекция, её чекпоинт, летучка по ней.

Номер работы только называет её и задаёт место в ведомости. Связи — по ключам, поэтому лекции можно переставлять и перенумеровывать: тест и работа уходят за своей лекцией. Поменяли ключ занятия (имя файла после номера) — поправьте lesson у тестов и work-связи, иначе проверка покажет «тест ссылается на лекцию, которой нет». В курсе без занятий порядок — по номерам.

Тест в GIFT

Тест можно положить файлом quizzes/04-letuchka.gift в формате Moodle GIFT, и он так и останется в GIFT. Номер и ключ — из имени, как у .md. Шапки у GIFT нет: она в quizzes/04-letuchka.yaml рядом, с теми же полями, что шапка .md (title, points, category, quiz). Без .yaml у теста нет названия, и проверка курса об этом скажет. Настройки теста без .yaml — умолчания летучки.

// летучка 4
Код перед вопросом виден вместе с ним.

::metric::Какая метрика подходит для поиска? {
	=Recall@k#ищем, нашлось ли нужное
	~BLEU#это про перевод
	####Считаем по нужным
}

::golden::Набор эталонных ответов называется? {=golden set =эталонный набор}

::tf::Recall@k зависит от k {TRUE#Подумайте, что такое k#Да}
  • ::имя:: — ключ вопроса, без него ключ — номер вопроса (q3). Ключ варианта — его текст.
  • = — верный, ~ — неверный, # после варианта — «почему», #### — разбор.
  • Несколько верных — веса без =: ~%50%. Верные — варианты с весом больше нуля; сами веса не переносятся, частичный балл задаёт partial. Несколько = в вопросе с вариантами ~ — ошибка: в Moodle так верен любой из них, у нас верный один. Без ~ это короткий ответ, и все = принимаются.
  • Верно-неверно — {T} или {FALSE}, у нас это вопрос с вариантами «Верно» и «Неверно». Отзывы как в Moodle: первый # — при неверном ответе, второй — при верном.
  • Короткий ответ — {=Париж =Paris}. Отзыв # у такого ответа не переносится: общий разбор пишут после ####.
  • Описание — текст без {} — становится текстом перед следующим вопросом. Описание в конце файла, без вопроса после, — ошибка.
  • Пустая строка разделяет вопросы, // — комментарий, $CATEGORY пропускается. Буквальные ~ = # { } : пишутся через \, перенос строки внутри вопроса — \n.
  • Выгрузку из Moodle можно класть как есть: [html] переводится в текст, пустой # у коротких ответов пропускается. Картинки и оформление блоков кода из [html] не переносятся: разбор называет их замечанием у вопроса.

Соответствие, числовой вопрос, пропущенное слово и эссе платформа не читает. Файл с таким вопросом пропускается с причиной и номером вопроса, тест в курсе остаётся как был.

Когда платформа будет записывать курс в репозиторий (скоро), тест останется в GIFT. Чего в GIFT нет — баллы вопроса не 1, страница, ключ варианта не из текста, — платформа пишет служебным комментарием перед вопросом, как сам Moodle пишет // question: при выгрузке:

// disputa: points 2, page 2, keys 2=recall 3=mrr
::metric::Какая метрика подходит для поиска? {…}

page — с этого вопроса и дальше, пока строка не сменит страницу. keys — ключи вариантов по их номеру в вопросе, с 1: 2=recall — у второго варианта ключ recall; пишутся только ключи, которые не выводятся из текста варианта. Номера, которого в вопросе нет, или повтор — ошибка на месте вопроса. Moodle такой комментарий пропускает, платформа читает. Вопросы, которые не правили, и ваши комментарии запись не трогает.

Занятие

Файл lessons/<номер>-<ключ>.md: лекция или семинар. Номер и ключ — из имени, как у работы; занятие сверяется по ключу. В шапке — title, kind (lecture или seminar, по умолчанию lecture), about, plan, outcome, links (доп. ссылки участнику, как у работы), materials (прежнее текстовое поле), work (ключ работы, к которой занятие готовит: у участника работа встанет после него), minutes (минут речи) и hidden (занятие курса, которое участникам не показывают). Тело — слайды Marp, между слайдами ---. Слайды файлом PDF пока загружаются не из репозитория, а на странице занятия, см. Слайды PDF.

---
title: Замер качества
kind: lecture
work: model-i-zamer
minutes: 40
marp: true
paginate: true
---

# Замер качества

---

## Эталонный набор

Директивы Marp пишутся в ту же шапку: Marp берёт их только из первой шапки, а поля занятия пропускает, поэтому файл открывается в Marp как есть. Директивы — из списка Marp: marp, theme, style, size, math, lang, headingDivider, paginate, header, footer, class, color, background…, transition и поля метаданных description, author, keywords, url, image. title у Marp и у занятия одно и то же. Незнакомое поле проверка назовёт замечанием: так опечатка в поле занятия не станет молча «директивой». Число слайдов платформа считает сама. Работа в work ищется по ключу в той же версии курса; нет такой — занятие без работы.

Занятия приходят на разбор строкой на занятие, если у источника отмечены «Занятия». Занятие, которого нет в источнике, остаётся в курсе: к нему могли быть привязаны занятия потока.

Какие критерии разбирает слайд

Слайд отмечает критерии работы из work, которые он разбирает, меткой <!-- criteria: ключ, ключ -->. Это как > критерии: у шага работы и как метки покрытия требований в коде. Ключи — у критериев этой работы.

## Эталонный набор

- Вопросы с заранее известными ответами
- Кто писал ответы и кто их проверял

<!-- criteria: golden -->

<!-- Главная ошибка: мерить на тех же примерах, на которых подбирали промпт. -->

На слайде и в речи докладчика метки нет. Руками её писать не обязательно: в виде «Слайды» на странице занятия она ставится галочкой у критерия. По меткам считается «критерии 4 из 6»: критерий, который разбирает другое занятие к той же работе, тоже разобран.

Поменялась формулировка критерия после отметки, и отметка «устарела», пока вы не подтвердите «Разбирает новую». Разбор источника узнал переименование критерия, и метки слайдов идут за новым ключом сами. Метку с ключом, которого у работы нет, или у занятия без work проверка назовёт замечанием lesson-criterion-unknown.

Тема лекций

Файл themes/<имя>.css: своя тема слайдов, CSS темы Marp. Имя файла и есть имя темы, его пишут в шапке занятия строкой theme: sii. Название для людей лежит в первом комментарии строкой @title. Своих тем на курс до пяти, встроенные (disputa, default, gaia, uncover) в предел не входят, и с них удобно начинать через @import.

/*
 * @theme sii
 * @title Тема курса
 */
@import 'default';

section { background-color: #fcfbfa; color: #26211f; }
section a, section strong { color: #1069da; }
section.invert { background-color: #26211f; color: #fcfbfa; }

Внешних адресов в теме нет: @import только встроенной темы, url() только строкой data:. Иначе лекция ходила бы за шрифтами и картинками на чужие серверы у каждого участника. Такой файл не читается, проверка покажет его ошибкой. Шрифт 'Golos Text' платформа вшивает сама. Контраст текста и акцента ниже 4,5:1 проверка отмечает предупреждением theme-contrast.

Тема висит на курсе, а не на версии, как темы проектов: приходит сразу, без разбора, и правка меняет оформление у всех занятий с ней. Есть в папке хоть один файл в themes/, значит папка и есть список тем: удалённый файл снимает тему, а опубликованные версии рисуются ею дальше. Нет themes/, и темы курса не трогаются, их ведут на платформе в «Курс → Темы лекций». Темы идут вместе с разделом «Занятия». Занятие с темой, которой нет ни в themes/, ни среди встроенных, проверка отметит lesson-theme-missing: Marp покажет его стандартной темой.

Основа курса

Файл materials/<ключ>.md: из чего строятся лекции. Это своя методичка, ключевая статья, документация, РПД. В шапке название, ссылка (url: адрес http(s) или путь файла в репозитории курса), строка «зачем» (about), занятия и работы ключами (lessons, works) и show, если участникам его надо показать. Тело файла — своя методичка в Markdown, участник читает её в Disputa. Нужна ссылка или текст, можно и то и другое.

---
title: Эталонный набор
about: что включить и что отложить до конца
lessons: [ zamer ]
works: [ model ]
show: true
---

# Эталонный набор

Вопросы с известными ответами, отложенная выборка…

По умолчанию основу видят только автор и помощник. С show: true участник видит материал у связанных работ («К работе N» в «Материалах») и занятий. Основа висит на курсе, а не на версии, как темы лекций: приходит сразу, без разбора. Есть в папке хоть один файл в materials/, значит папка и есть вся основа: удалённый файл снимает материал. Нет materials/, и основу ведут на платформе в «Курс → Материалы». Основа идёт вместе с разделом «Занятия».

Поправили материал после того, как сверяли с ним лекцию, и у лекции появится «лекция отстаёт», пока автор не нажмёт «Лекция сверена». Связку с занятием или работой, которых в курсе нет, проверка назовёт замечанием material-link-unknown.

Доп. ссылки «почитать» к одному занятию или работе в основу не кладут: это поле links в шапке самого занятия или работы.

links:
  - { title: Recall@k простыми словами, url: "https://example.com/recall", about: перед семинаром }

Роли

roles.md — роли команды строками или списком в шапке:

- product: Продукт
- ml: ML-инженер

За что роль отвечает и можно ли занять её вдвоём — списком в шапке:

---
roles:
  - key: product
    title: Продукт
    about: Бриф, метрика успеха и голос пользователя
  - key: ml
    title: ML-инженер
    duplicable: true
---

about видят участник и проверяющий; duplicable: true — роль можно занять двоим, состав команды это не нарушит. Не указано — описания нет, роль на одного.

Критерий с role должен ссылаться на объявленную роль.

Темы проектов и варианты

Раздел topics/: topics/<адрес>.md — тема на весь курс, topics/<ключ работы>/<ключ варианта>.md — вариант работы. Имя файла — адрес темы или ключ варианта. Темы и варианты идут по имени файла, и variantRule: list_number раздаёт варианты в этом порядке. У варианта в шапке title и reference, описание — тело.

---
version: 1
title: Рекомендации для книжного магазина
code: T-07
details: { difficulty: 2, data: открытый датасет }
reference: |               # эталон: видят только агент и штаб
  …
---
Описание темы для студентов.

Темы курса не ждут новой версии курса и разбора: если у источника отмечены «Темы проектов», правка приходит в каталог сразу. По умолчанию этот раздел не берётся. Варианты идут с работой: они на разборе вместе с ней.

Есть в папке хоть один файл в topics/ — папка и есть каталог: удалённый файл убирает тему, у работы ровно те варианты, что лежат в её папке. Команда, которая тему уже взяла, сохраняет свою копию. Нет topics/ — темы и варианты курса не трогаются.

У раздела один источник: пока «Темы проектов» берутся из репозитория, адрес каталога тем на сайте не читается. Задали адрес снова — раздел вернётся к нему. Эталон в открытом репозитории проверка назовёт ошибкой (скоро).

Настройки курса

course.yaml в корне — настройки курса, которые поток берёт по умолчанию, и откуда какой раздел приходит.

# yaml-language-server: $schema=https://disputa.ru/schema/v1/course.json
version: 1
title: Системы ИИ
team: { size: 4, min: 3 }               # team: false — курс без команд
topics: { kinds: [catalog, own, partner], seats: 2 }
grading:
  aggregation: sum
  extras: [{ key: exam, title: Экзамен, max: 40 }]   # строки итога от человека
  admitPoints: 35                         # допуск: столько за семестр
  requireAll: true                        # и все обязательные работы
  latePenalty: true                       # считать штраф за опоздание
late: { kind: steps, steps: [...] }
sources:
  works: this                             # этот репозиторий
  quizzes: this
  lessons: https://site.example/course    # адрес
  roles: here                             # ведётся на платформе
  • team — размер команды «от и до», false — курс без команд; topics — виды тем (kinds), сколько команд берут одну тему каталога (seats), правила (rules) и поля заявки своей темы (brief).
  • grading — как складывается итог: aggregation (sum, weighted, bundles), категории (categories), строки итога с баллом от человека (extras, bonus: true — поверх шкалы), допуск по баллам за семестр без экзамена (admitPoints), все ли обязательные работы нужны (requireAll, по умолчанию да), посещаемость (attendance) и считать ли штраф (latePenalty). Форма контроля и перевод в отметку вуза задаются на потоке.
  • late — штраф за опоздание.
  • sources — у каждого раздела свой источник: this — этот репозиторий, here — ведётся на платформе, адрес — сайт курса. Нет sources — весь курс из этой папки. Разделы — course, works, quizzes, lessons, roles, topics.

Настройки приходят на разбор одной строкой «Настройки курса», если у источника отмечено «Оценивание и команды». Есть course.yaml в папке — раздел при подключении отмечен сам, снять можно; нет файла — не отмечен. Если файл есть, а раздел ведётся здесь, проверка и разбор об этом говорят: «course.yaml не применяется». Чего в course.yaml нет, то по умолчанию: команда из 4 человек, итог — сумма без категорий, без штрафа. Название курса, если оно есть, меняется сразу, а не с публикацией: оно у курса, а не у версии. Раздел, который sources отдал другому источнику или платформе, из этой папки не берётся, даже если файлы в ней есть. Показ sources в «Источниках» — скоро.

Поток может переопределить размер команды, виды тем и схему итога у себя: сроки, модули и люди ведутся на платформе, а не в файлах. Токены и подключения в файл не пишутся.

Раскладка файлов и уровни правил

disputa.yaml в корне папки курса задаёт уровни правил проверки (rules) и, если файлы лежат не там, где по умолчанию, говорит, где их искать: раздел → маска с одной * на месте имени работы. labs/03-model/README.md по маске labs/*/README.md — это работа 3 с ключом model; остальное в labs/ — материалы работ, их платформа не читает. Раздел с маской из своей папки по умолчанию не читается. Маски есть у works, quizzes (шапка теста в GIFT — .yaml рядом) и lessons; check, fmt, diff, push и чтение репозитория идут по ним:

version: 1
works: { files: "labs/*/README.md" }
lessons: { files: "slides/*.md" }
rules: { no-lower-bound: off, ask-missing: error }

Весь курс одним файлом

Вместо файлов можно положить course.json — документ курса с теми же полями.

Проверка курса

Курс проверяется на платформе — disputa version check --course <курс> или кнопка в редакторе — и у вас без сети: disputa content check [папка]. Правила одни и те же. Ошибка не даёт опубликовать, предупреждение подсказывает.

ПравилоУровеньЧто ловит
file-invalidошибкафайл не читается: YAML, шапка, шаги, вопросы или поля
file-skippedпредупреждениефайл без номера в имени или шапка теста без теста рядом
field-unknownпредупреждениенезнакомое поле в шапке работы, критерия или занятия, чаще всего опечатка
gift-html-cutпредупреждениеиз [html] в GIFT срезаны картинка или оформление кода
section-elsewhereпредупреждениефайл раздела, который sources: в course.yaml отдал платформе или другому источнику: правка в нём не применится
course-emptyошибкав курсе нет ни одной работы
work-no-titleошибкаработа без названия
work-no-criteriaошибкаработа по критериям без критериев
role-unknownошибкакритерий ссылается на роль, которой нет
quiz-emptyошибкатест без вопросов
ask-missingпредупреждениеу критерия нет вопроса к приёмке
quiz-no-explainпредупреждениеу вопроса нет разбора
llm-no-signsпредупреждениеу оценки моделью нет признаков
no-hard-pathпредупреждениепуть к файлу в критерии
no-lower-boundпредупреждение«не меньше N» в критерии
link-brokenошибкабитая относительная ссылка или якорь; только check по папке: файл ищется на диске, внешние адреса не проверяются
public-repo-answersошибкав открытом репозитории то, что видят только проверяющие: признаки проверки, expect, redFlag, скрытые критерии, sessionCard, ответы тестов, эталоны, solutions/; одна находка на файл

Проверка папки без сети — disputa content check [папка]: без входа, у вас, в агенте и в CI на каждом PR. Находка — строкой, как у ESLint:

works/03-model.md:4:5  warn   no-hard-path  путь к файлу в критерии: работа 3, metric
works/04-bad.md:2:16  error  file-invalid  шапка не читается: …

--json — то же конвертом со schemaVersion: 1, --sarif — для пометок прямо в PR на GitHub. Код выхода 1 — есть ошибки, 0 — ошибок нет (предупреждения не роняют CI), 2 — не прочитать саму папку или disputa.yaml. Уровни правил меняются в disputa.yaml в папке курса — rules: { ask-missing: error, no-lower-bound: off }; file-invalid и role-unknown не выключаются. Открыт ли репозиторий, check без сети не знает: это говорит public: true в disputa.yaml или флаг --public (--no-public — закрыт), флаг главнее — видимость меняют в настройках репозитория без коммита. В GitHub Actions флаг берётся из события: disputa content check --sarif ${{ github.event.repository.private && '--no-public' || '--public' }}. Ни поля, ни флага — public-repo-answers молчит. Курс, открытый нарочно, выключает правило: rules: { public-repo-answers: off }. Новое правило приходит предупреждением: ошибкой оно станет только с новой версией формата. Почему правило есть, с плохим и хорошим примером, — disputa content rule explain no-hard-path, все правила с уровнями этой папки — disputa content rule list.

Один вид папки — disputa content fmt [папка]: тот же курс, записанный так, как его пишет платформа: поля шапки в постоянном порядке, без значений по умолчанию, короткие наборы в строку (check: { type: llm }), имена файлов 03-ключ.md. fmt --check ничего не меняет и отвечает кодом 1, если папка не в одном виде, — для CI. Не трогает файлы, которые не читаются, файлы с незнакомыми полями (их поправит check) и шапки с комментариями: шапку fmt пишет заново и комментарий потерял бы. GIFT пишется поверх себя: нетронутые вопросы и комментарии остаются.

Что изменит папка — disputa content diff [папка] --course sii-2026: тот же разбор, что после отправки, но без снимка, курс не меняется — как terraform plan. ~ — изменится, + — новое, - — нет в папке, ! — спор с правкой на платформе. Опасная правка — ⚠ под строкой: убран критерий, по которому уже есть вердикты, или сменился способ его проверки; у работы, которую уже сдают, меняются баллы или способ сдачи и оценки. Опубликованная версия заморожена, но это заденет потоки, которые переведёте на новую; разбор на платформе показывает то же «Осторожно». Код 2 — есть изменения, 0 — нет, 1 — сбой (папка не читается — сначала check).

Курс папкой и обратно — в «Источниках» есть «Скачать папкой» (zip того же вида), а из терминала — disputa content clone sii-2026 выгружает курс папкой sii-2026/ в том виде, в каком её пишет fmt, и кладёт отметку базы .disputa/base.json (курс, версия, последний принятый снимок, хэш каждого раздела и файла; токена в ней нет; .disputa/ — в .gitignore). Поправили — disputa content diff показывает, что изменится, disputa content push из папки присылает её на разбор; курс берётся из отметки базы или --course. С --data команда работает как раньше: disputa content push sii-2026 --data @course.json.

С чего начать — disputa content init [папка]: course.yaml и disputa.yaml со строкой схемы, папки разделов, .disputa/ в .gitignore, в корне репозитория — проверка курса на каждом PR (.github/workflows/disputa-course.yml) и .pre-commit-config.yaml с check и fmt --check. Версия CLI в них закреплена: новое правило не уронит проверку, пока вы её не обновите. Что уже есть, init не трогает. Что поменялось — disputa content status: свои правки после выгрузки по отметке базы (без сети) и разделы, которые за это время поменялись на платформе.

Токен для CI — в «Источниках», «Настроить» у источника: умеет только прислать снимок этого курса на разбор, применить или опубликовать им нельзя. Кладут в секреты репозитория как DISPUTA_TOKEN, в CI — npx disputa content push course/ --course <курс>. Личный токен в CI не нужен: он ломается с уходом человека, а пока не сломался, действует всеми его правами. Отозвать — там же.

Следом появятся:

disputa course test           # прогнать проверку на эталонных решениях (скоро)

На этой странице