Специфікація DWP

Поточний стандарт: v7 (DWP 7.0.0). Це збережена основа специфікації v5 з розширеннями життєвого циклу v6 і поколінням контракту v7. Пакет 7.x за замовчуванням створює нові плани у форматі v7; явний запит v6 і далі матеріалізує план v6, а наявні плани зберігають зафіксоване покоління. Маніфест і контракт v7 опубліковані за адресами plan-manifest/v7.json та plan-contract/v7.json; поточний snapshot лишається за адресою plan-snapshot/v6.json.

Версія 5.0.0. Статус: стабільний. Цей документ є нормативною специфікацією методології Deep Work Plan (DWP). Ключові слова MUST, MUST NOT, SHOULD, SHOULD NOT та MAY тлумачаються згідно з RFC 2119.

Адитивно в 2.4.0, без руйнівних змін. (1) Секція Торкнута поверхня — контракт між тим, що завдання змінює, і тим, що мусить бути валідованим, із вибором gate за класом ризику (ізольована / шов / спільна-ядро / невідома); (2) повна валідація стає вимогою до кінцевого стану, що виконується в єдиному обовʼязковому Final Review плану, з явними правилами повторного використання доказів; (3) рішення щодо skills у межах завдань переходять у те завдання, що їх породило, а Executive Report стає опційним, на запит; (4) потік create, залежний від режиму — trust-режим матеріалізує план одразу, зберігаючи аналіз і перевірки якості; (5) матеріалізація у форматі Lite за замовчуванням — guided create одразу створює виконуваний Lite-план замість невиконуваної чернетки, який можна підвищити до Full-плану в будь-який момент (див. Lite-плани); та (6) явна матриця сумісності: плани й репозиторії з ранішніх версій залишаються відповідними.

Стандарт 4.0.0. Стрибок версії вирівнює номер стандарту з продуктовою лінійкою — 2.x історичний, стандарту 3.x не існує — і не змінює жодної вимоги відносно 2.4.0. Плани й репозиторії попередніх версій залишаються конформними.

Визначення

Deep Work Plan — це структурований, виключно markdown-артефакт, що описує складне інженерне завдання, розкладене на послідовні, придатні до рецензування одиниці роботи, призначений для створення, виконання та супроводу AI-агентами програмування, які працюють автономно.

DWP є spec-driven: план є специфікацією, і агенти MUST виконувати за його явними критеріями приймання та валідаційними gate, а не імпровізувати. Специфікація — а не транскрипт чату — є стійким джерелом істини, тож робота є перевірюваною та відновлюваною між сесіями й агентами. Це також harness-інженерія, зроблена портативною: контекст, керувальний цикл, запобіжники та відновлюваний стан, що роблять агента надійним, встановлюються в сам репозиторій як звичайний markdown, тож будь-який відповідний агент MAY пілотувати репозиторій без фреймворку під конкретний інструмент.

Потік create — один крок, залежний від режиму

Потік create збирає мету, контекст, обмеження та контур завдань один раз, виконує свій аналіз вимог (scope, порядок залежностей між завданнями, вибір валідації з Торкнутої поверхні, рівень пропорційної строгості), а потім матеріалізує відповідно до режиму, який обрав розробник:

• Guided-режим (за замовчуванням). Потік матеріалізує Lite-план одразу — компактну, вже виконувану пропозицію з інлайн-записами завдань {#task-N}, придатну для рецензування за один прохід — і просить розробника залишити його як Lite, підвищити до Full-плану, запросити правки або зупинитися. Проміжна невиконувана чернетка не створюється.
• Trust-режим (trust / auto). Потік матеріалізує обране представлення (Lite, або Lite з негайним підвищенням до Full) одразу, без етапу рецензування — розробник відмовився від нього. Аналіз вимог, порядок залежностей та перевірка якості плану все одно виконуються: trust відмовляється від рецензування, а не від аналізу. План у trust-режимі фіксується як попередньо схвалений для автономного виконання.

Обидва режими визначають формат плану (Lite чи Full) у межах того самого аналізу вимог, а не заднім числом. Див. Lite-плани — повний опис представлень, створення-і-вибору та життєвого циклу підвищення.

Структура плану

Новий план MUST використовувати нумерований каталог у .dwp/plans/, наприклад PLAN_001_<slug>/, в одному з двох представлень. Наявні каталоги без номера PLAN_<slug>/ залишаються допустимими й не перейменовуються:

• Full. Каталог MUST містити README.md (огляд плану, мета, таблиця завдань та статус), по одному файлу на завдання з назвою <n>.task_<slug>.md, та PROGRESS.md (поточний журнал виконання).
• Lite. Компактні, повністю виконувані записи завдань живуть інлайн у README.md за стабільними якорями {#task-N} замість окремих файлів завдань — кожен запис все одно несе мету, Торкнуту поверхню, критерії приймання, валідацію та журнал завершення. PROGRESS.md все одно REQUIRED. Lite-план MAY бути підвищений до Full у будь-який момент. Див. Lite-плани — повний життєвий цикл, не дублюючи його тут.

План MAY додатково нести машиночитаний рівень стану: manifest.json (статична ідентичність, записується один раз при матеріалізації) та state.json (живий стан виконання по завданнях). Рівень стану RECOMMENDED для планів v5 і REQUIRED для автономного виконання та для робочих просторів агентів без git. Див. Стан плану.

Нові плани отримують монотонно зростаючі числові ID завдовжки щонайменше три цифри (наприклад, PLAN_001_add_payment_webhooks/). Заморожені схеми v5 рахують числовий ID як одне слово, тому slug v5 містить 2–4 слова, а slug v6 і v7 — 2–5. Наявні папки без номера PLAN_<slug>/ залишаються доступними для читання й ніколи не перейменовуються. Якщо є нумеровані плани, latest вказує на план із найбільшим числовим ID.

Анатомія завдання

Файл завдання

1. 01 Заголовок
2. 02 Контекст
3. 03 Прочитати перед початком
4. 04 Мета
5. 05 Торкнута поверхня
6. 06 Інструкції
7. 07 Критерії прийнятності
8. 08 Результати
9. 09 Валідація
10. 10 Чек-лист виконання та Журнал завершення

Кожен файл завдання MUST містити ці десять секцій по порядку:

1. Goal — один абзац, що окреслює, чого досягає завдання.
2. Context — передумови, посилання та чому це завдання існує.
3. Торкнута поверхня — контракт між тим, що завдання змінює, і тим, що мусить бути валідованим.
4. Steps — упорядковані, конкретні дії, які треба виконати.
5. Acceptance criteria — контрольний список умов, що визначають завершення.
6. Validation — команди чи тести, які треба запустити для перевірки, обрані з Торкнутої поверхні.
7. Files — шляхи, які очікувано буде створено чи змінено.
8. Dependencies — інші завдання чи зовнішні передумови.
9. Risks — що може піти не так і як це помʼякшити.
10. Completion & Log — маркер статусу плюс хронологічні нотатки.

Завдання MAY додатково містити секцію Delta (RECOMMENDED для змін поведінки в brownfield — див. нижче) та секцію Rollback (RECOMMENDED для міграцій, змін інфраструктури або розгортань).

У плані v7 контракт результату також може позначити завдання як parallel_safe: це твердження, встановлене під час створення, що завдання може виконуватися в делегата без перемежування з роботою сусідніх завдань. Маркер нічого не авторизує без дозволу контракту agent_delegation (Делегування).

Торкнута поверхня

Торкнута поверхня — це контракт між тим, що завдання змінює, і тим, що мусить бути валідованим. Вона існує, щоб валідація обиралася за ефектом, а не за звичкою, і щоб пізніший читач бачив, чому обрано той чи інший gate. Завдання, що змінює поведінку, MUST записати:

• Запланована поверхня — шляхи, модулі, пакети чи конфігурація, які завдання має намір змінити, записані до редагування.
• Фактична поверхня — узгоджений після редагування список, узятий із реального diff. Агент MUST узгодити заплановану та фактичну поверхні перед вибором gate.
• Зачеплені споживачі — модулі, пакети чи сервіси, що залежать від фактичної поверхні, настільки, наскільки може встановити задокументоване відображення репозиторію. Де воно не може, запис MUST це сказати.
• Клас ризику — один із: ізольована (обмежена одним модулем і його тестами); шов (змінює контракт, персистентність, маршрутизацію, серіалізацію, auth чи фреймворкове зʼєднання між колаборантами); спільна/ядро (широко імпортується, або зміна залежності, міграції, конфігурації збірки/тестів, схеми чи інструментарію); невідома (відображення відсутнє, застаріле або неперевірене).
• Використане тестове відображення — яке задокументоване відображення чи інструмент породив вибір.
• Обраний gate і причина — точні команди й те, чому вони покривають фактичну поверхню.

Конфігураційні файли, схеми, манифести залежностей, шаблони, фікстури, міграції та файли інструкцій агентів можуть змінювати поведінку і MUST класифікуватися за своїм ефектом, а ніколи не за розширенням файла. Завдання, що змінює лише прозу, коментарі чи артефакти дослідження, MAY оголосити поверхню непридатною та все одно запускає нон-рантайм перевірки репозиторію.

Секція Delta (зміни brownfield)

Більшість реальної роботи змінює наявну поведінку, а не створює нову. Завдання, що змінює поведінку наявної системи, SHOULD містити секцію Delta, що описує зміну як явний контракт «до/після», використовуючи три заголовки списку:

• ADDED — поведінка, що існує після завдання і не існувала раніше.
• MODIFIED — поведінка, що існує в обох станах, сформульована як was: … → now: ….
• REMOVED — поведінка, що існувала раніше і навмисно відсутня після.

Кожен запис MUST бути спостережуваною поведінкою — відповідь ендпоінта, прапорець CLI, стан UI, значення за замовчуванням, — а не деталлю реалізації. Секція Delta є дифом рецензента на рівні поведінки: критерії приймання перевіряють записи ADDED/MODIFIED, а записи REMOVED є явним дозволом на видалення. Все, що не перелічено як REMOVED, MUST продовжувати працювати.

Валідаційні gate — вибір за класом ризику

Валідація — це gate, що перетворює заяву про завершення на доказ завершення: завдання MUST NOT позначатися завершеним, доки кожна команда з його секції Validation не буде запущена й не пройде успішно. Gate завдання, що змінює поведінку, обирається з його узгодженої Торкнутої поверхні, за класом ризику:

Зміна поведінки MUST породжувати непорожній, релевантний вибір тестів — недійсний селектор чи раннер, що обрав нуль тестів, не є покриттям. Де тестове відображення репозиторію застаріле, правильний виклик виводиться, а оновлення відображення фіксується; невелика відсутня команда ніколи не потребує повного онбордингового прогону. Де не існує обмеженого виклику, застосовується повний придатний набір — застаріла поведінка, а ніколи не помилка.

Коли завдання додає нову основну функціональність або суттєво змінює наявну поведінку, його критерії приймання MUST включати автоматизоване тестове покриття нової чи зміненої поведінки, а його валідація запускає тести репозиторію разом із перевірками lint, типів і форматування — а не лише збірку. Наявні тести MUST залишатися зеленими.

Валідація кінцевого стану

Gate окремих завдань валідують те, що кожне завдання торкнулося; вони не замінюють валідацію плану як цілого. Перед завершенням плану повний придатний набір валідації репозиторію MUST бути запущений і пройти на кінцевому релевантному стані, після останньої суттєвої зміни — у Final Review. Ширші запуски раніше відбуваються на межах інтеграції або після спільних/ядрових змін, а не за розкладом на кількість завдань. Пройдений результат MAY бути повторно використаний лише з доказом, що релевантні входи еквівалентні; інакше він перезапускається. Кожен запуск gate лишає стислий запис: команда, scope, ревізія, результат та шлях до доказів.

Дисципліна безпеки

Безпека є першокласною так само, як і тести, і дотримується тієї самої дворівневої моделі: подисциплінна робота над кожним завданням, поки воно виконується, плюс перевірка безпеки Final Review над усім набором змін наприкінці. Щоразу, коли завдання торкається автентифікації чи авторизації, обробки вводу, секретів чи конфігурації, мережевої поверхні, файлів чи shell, або залежностей:

• Його критерії приймання MUST окреслювати безпекові очікування щодо зміни — ввід валідовано та екрановано, жодного секретного матеріалу в коді чи фікстурах, перевірки auth збережено або посилено — узгоджені з docs/SECURITY.md.
• Кожен коміт MUST бути підтверджено як вільний від секретів чи облікових даних, перш ніж він потрапить у репозиторій, включно з тестовими фікстурами та прикладами в документації. Секрет у запушеному коміті MUST вважатися витоком і бути ротованим, а не просто видаленим.
• Там, де безпекочутлива робота є суттєвою, окреме завдання з посилення захисту SHOULD бути розміщене одразу після завдань реалізації та перед завданням всеохопних тестів, щоб знахідки виправлялися до того, як тести закодують поведінку, і кожна знахідка ставала регресійним випадком, а не переробкою.

Ця подисциплінна робота над кожним завданням не замінює перевірку безпеки Final Review: подисциплінні перевірки ловлять проблеми в тому коміті, де вони народжуються, тоді як фінальний gate проводить аудит усього плану — включно із самими завданнями тестів і документації.

Планка якості — перевірено, а не заявлено

Суть DWP — перевірена якість: коректність, ясність, простота, безпека, продуктивність і масштабованість, доведені, а не заявлені. Ці правила застосовуються до кожного плану й кожного агента, який його продовжує (§5.1.4 файлу DWP_SPECIFICATION.md із пакета DWP):

1. Gate — це гіпотези. Новий чи змінений gate MUST показати збій на внесеному дефекті (або на дереві до зміни), перш ніж йому довіряють, і цей невдалий прогін записується. Порожній прохід — відсутній бінарний файл, порожній вхід, нуль збіглих файлів чи тестів, порожній лог, || true на фінальному gate — це збій. Конвеєри виконуються з pipefail (або код виходу зберігається інакше). Gate, що лише шукає текст, написаний самим агентом, — це структурний запобіжник, а не спостережений доказ поведінки. Завдання з контрактом введення називає у своїх критеріях приймання граничні вхідні дані (порожні, багаторядкові, із пробільними символами на початку чи в кінці) — проходження кожного прикладу не доводить правило. Тест точного виводу перевіряє його за допомогою сигнального значення ([ "$(f x; printf s)" = $'y\ns' ]): $(…) відкидає завершальні переведення рядка, тож вивід, який губить або подвоює своє останнє переведення рядка, інакше пройшов би.
2. Порівнюйте з базою. Продуктивність, покриття й розмір порівнюються з базовою гілкою (або початковою ревізією плану), а не лише з порогом; про регресію відносно бази повідомляють, навіть якщо поріг і далі дотримано.
3. Спершу вимірюйте. Завдання 1 виправлення, аудиту чи оптимізації перевіряє своє припущення й вимірювальний інструмент до будь-яких змін.
4. Проєктування до збирання. Нетривіальна зміна записує свої інтерфейси, режими відмов, позицію безпеки й план тестування до написання коду.
5. Чесність середовища. Gate виконується в оголошеному середовищі — клас команди-обгортки для контейнерів, явний робочий каталог, фіксована локаль там, де порівнюється вивід. Збій середовища — це блокер, який треба усунути або про який треба повідомити, — ніколи не прохід і ніколи не провина зміни.
6. Рецензія до незворотного кроку. Локальний AI Diff Review із Final Review запускається до будь-якого злиття, тегу чи публікації, які виконує план, відносно базової лінії плану. Завершення плану зберігає контракт рецензії «ніколи не блокувати» (відсутній рецензент — це записана знахідка local reviewer not installed); сам крок злиття, тегу чи публікації залишається заблокованим цією знахідкою, доки рецензент не запуститься або розробник явно від нього не відмовиться, — ніколи не тихий пропуск. Зміни методології, протоколу й зміни, значущі для безпеки, SHOULD також отримувати рецензента іншого постачальника чи агента.
7. Ощадні докази. analysis_results/ містить звіти, логи, дайджести й покажчики — ніколи продукти, дерева залежностей чи вендорні копії; продукт отримує власний репозиторій або оголошену торкнуту поверхню.
8. Неперервність ніколи не знижує планку. Агент-наступник успадковує ті самі gate; пакет передавання не закриває жодного критерію, не послаблює жодного gate і не пропускає жодної рецензії (Автономія рою).

Життєвий цикл плану — Final Review

Кожен відповідний план, створений за цією версією, завершується рівно одним обовʼязковим завданням: Final Review (завдання N). Дві відповідальності, які раніші версії клали в окремі завершальні завдання, переміщено: рішення щодо skills переходять у те завдання, що породило патерн, а Executive Report стає опційним артефактом на запит. Ніщо в перевірці безпеки не послаблюється.

Final Review MUST, по порядку:

(a) Перевірка безпеки — ревʼю повного накопиченого набору змін плану на захаровані секрети, ризики інʼєкцій, нову поверхню атаки, послаблений auth і чутливі дані в журналах чи документації; аудит уведених залежностей; перевірка, що docs/SECURITY.md досі відображає реальність; написання звіту перевірки безпеки навіть коли все чисто. Критична знахідка виправляється — або явно приймається користувачем — перш ніж план завершується. Перевірка включає обовʼязкове локальне ревʼю AI Diff Reviewer повного діапазону плану; відсутній рецензент — це зафіксована знахідка local reviewer not installed, а не тихий пропуск.

(b) Валідація кінцевого стану — повний придатний набір валідації репозиторію запускається й проходить на кінцевому релевантному стані.

(c) Узгодження skills — кожне завдання несе диспозицію skills, і кожен зафіксований кандидат має диспозицію; без другого звіту про виявлення.

(d) Узгодження документації — торкнута поверхня кожного завдання, що змінює поведінку, звіряється з документами, які її реєструють (спершу реєстр gate, потім документація архітектури й модулів, потім індекс AGENTS.md); пропуски виправляються в межах рецензії, а зачеплені валідації перезапускаються.

(e) Завершення — записи плану узгоджені (список завдань, журнал прогресу, а в планах v6 і v7 — похідний від журналу знімок і квитанція); відзвітувати про завершення з результатами, доказами валідації та обмеженнями; запропонувати Executive Report один раз. План є завершеним незалежно від того, чи отримано відповідь на пропозицію.

Final Review виконується послідовно після всіх інших завдань і ніколи не розміщується в паралельній групі.

Рішення щодо skills у межах завдань

На запитання «чи породила ця робота патерн, придатний для повторного використання, вартий скіла чи агента?» відповідається всередині завдання, що породило патерн, поки його докази в контексті. Completion & Log кожного завдання несе диспозицію skills: жодної, оновлення наявного скіла, створення іменованого артефакта або відкладення з причиною. Виправдане авторство відбувається всередині цього завдання, перед його валідаційним gate і комітом, після перевірки наявного каталогу на дублікати.

Executive report — опційний, на запит

Executive Report більше не є обовʼязковим завданням. При завершенні агент пропонує його один раз; він генерується лише за явним запитом, на основі довговічних доказів без відтворення плану. Відсутня відповідь або автономний прогін лишає план завершеним без згенерованого звіту.

Протокол завершення завдання

Після проходження валідації та перед переходом до наступного завдання агент MUST виконати по порядку: (1) позначити завдання [x] у README плану; (2) збільшити лічильник статусу плану; (3) заповнити секцію Completion & Log завдання без жодних значень-заповнювачів; (4) додати запис із 3–5 пунктів до PROGRESS.md; (5) зробити коміт (де план комітить) у форматі {type}({scope}): {description} — Task {N} of PLAN_{name}; (6) де план несе рівень стану, атомарно перезаписати state.json — завдання completed, записи gate, запис результату, хеш коміту.

Шість кроків утворюють одну логічну транзакцію. Агент, перерваний посеред протоколу, MUST NOT починати наступне завдання — він повинен завершити або скасувати часткове завершення спочатку.

Протокол відновлення DWP

Відновлення MUST бути можливим лише з файлів плану та журналу git, без зовнішнього стану. У робочому просторі без git — див. Архетипи §3 — state.json плану є REQUIRED і замінює журнал git.

Агент, що відновлює роботу, — нова сесія, інший агент, запланований поворот демона або хмарна сесія, що прокидається, — MUST виконати цей ритуал по порядку:

1. Переорієнтація. Прочитати README плану: мета, глобальні настанови, список завдань.
2. Знайти checkpoint. Знайти перше непозначене завдання в README; прочитати журнал git і git status (або checkpoint у state.json, де git відсутній).
3. Узгодити стан. Де state.json існує, порівняти його з прапорцями README; у разі десинхронізації перегенерувати його з markdown перед продовженням.
4. Оглянути шов. Прочитати Completion & Log завдання точки відновлення та останній запис PROGRESS.md — остання перевірена основа попередньої сесії.
5. Запустити дим-тест. Запустити найдешевшу наявну валідацію репозиторію, щоб підтвердити, що світ досі працює, перш ніж будувати на ньому. Дим-тест, що не проходить, досліджується спочатку, а не ігнорується.
6. Продовжити атомарно. Виконати рівно наступне завдання; не батчити наперед.

Агент MUST довіряти позначкам завершення ([x]) і MUST NOT повторно валідувати завершені завдання, якщо лише користувач явно не попросить про це або дим-тест не зазнав невдачі у спосіб, що стосується завершеного завдання.

Цикл виконання

DWP визначає шість операцій плану:

• create — Згенерувати новий план із мети.
• execute — Виконати план завдання за завданням.
• refine — Змінити наявний план.
• resume — Відновити перерваний план.
• status — Відзвітувати про статус плану без виконання.
• verify — Перевірити відповідність репозиторію й плану, лише читання.

Ще три sub-skills доповнюють встановлений пакет: onboard (зробити репозиторій AI-first), author (створювати чи оновлювати власні skills, агентів і команди репозиторію) та upgrade (перевести встановлений скіл на новіший реліз за згодою, ніколи не мігруючи наявні плани). Маршрутизатор і ці девʼять sub-skills постачаються як один пакет скілів.

Робочий простір виводу

Робочий простір виводу

• .dwp/ ігнорується git · одноразове
• config.json
• plans/
• PLAN_001_<slug>/
• README.md
• PROGRESS.md
• <n>.task_<slug>.md
• manifest.json
• contract.json
• journal.ndjson
• state.json
• analysis_results/ звіти
• SECURITY_REVIEW.md огляд безпеки
• EXECUTIVE_REPORT.md підсумковий звіт

Усі артефакти DWP MUST жити під каталогом .dwp/ у gitignore в корені репозиторію.

Машиночитаний стан плану

План MAY нести машиночитаний рівень стану — manifest.json (статична ідентичність) та state.json (живий стан по завданнях, записи валідаційних gate, записи результатів, checkpoint, заблокований стан). Markdown-план залишається джерелом істини; JSON-рівень є похідною проєкцією, що перегенеровується у точках протоколу та узгоджується при відновленні.

Рівень стану RECOMMENDED для планів v5, REQUIRED для автономного виконання та REQUIRED для робочих просторів агентів без git. Повне нормативне визначення — у Стані плану.

Пропорційна строгість

Строгість MUST бути пропорційною роботі. Церемонія над тривіальними змінами є невдачею методології, а не додатковою безпекою. Кожен обсяг роботи належить рівно до одного рівня:

Агент, якому доручено створити план для роботи рівня micro, MUST сказати, що план є непропорційним, та запропонувати замість нього вбудовану форму. Папка плану MUST NOT створюватися для тривіальної зміни одного файлу.

Робота рівня micro все одно зберігає обовʼязкові елементи: явну мету, валідаційний gate, що запускається й проходить, та дисципліну тестування для змін поведінки. Рівень змінює пакування, але ніколи не gate.

Коли scope зростає в середині виконання — micro-завдання виявляє реальний scope, стандартний план породжує суб-репозиторії, — агент MUST зупинитися та підвищити роботу до наступного рівня, а не розтягувати поточний.

Сумісність

Плани й репозиторії з ранішніх версій залишаються відповідними, і перевірник відповідності MUST розрізняти відомий застарілий артефакт (приймається) та артефакт, що заявляє цю версію й обʼєктивно недійсний за нею (відхиляється):

Версіонування

Ця специфікація дотримується семантичного версіонування.