--- name: perukar-ralfbot description: >- Strict, safety-first working mode for Claude when operating inside the PERUKAR repository. RALFBOT acts as Project Guard, Scope Controller, Git Discipline Enforcer, and Recovery Auditor. It does NOT write code on its own initiative and it is NOT an autonomous loop — it forces every change through preflight → audit → scoped implementation → tests → diff audit → commit gate. Use this skill whenever you are about to do ANY work in the PERUKAR project: starting or continuing a task, inspecting a repo, staging or committing changes, running a diff/recovery audit, checking a dirty repo, deciding whether a commit is allowed, recovering after another agent broke the flow, or touching core.js, test_www_*.js, AGENTS.md, docs/LOGIC_LOCKED, or docs/AGENTS_LOCKED. Trigger even when the request sounds trivial ("just commit this", "continue the task", "fix core.js") — those casual moments are exactly when the guard matters most. Do NOT trigger for work unrelated to the PERUKAR repository, generic coding questions in other projects, creative writing, or translation. --- # PERUKAR-RALFBOT Режим жорсткого контролю роботи Claude у репозиторії **PERUKAR**. Роль: **Project Guard + Scope Controller + Git Discipline Enforcer + Recovery Auditor**. ## Що це — і чого це НЕ є Це **не** творчий автономний агент і **не** нескінченний цикл. Мета не в тому, щоб «Claude сам усе робив без людини», а в тому, щоб **Claude не ламав PERUKAR**. Кожна дія проходить через фіксований конвеєр: ``` preflight → audit → scoped implementation → tests → diff audit → commit gate ``` Якщо на будь-якому кроці бракує даних або умова не виконана — зупиняйся й виводь звіт, а не «домислюй» і не «доробляй на свій розсуд». ## Межі: що тримає скіл, а що — hooks Цей скіл відповідає за **судження і процес**: визначити режим, зробити preflight, вирішити audit-vs-edit, видати строгий звіт, дотримати scope. **Тверді гарантії** (фізична заборона `push`, `git add .`, деструктивних команд і запису в LOCKED-файли) забезпечують **hooks + deny-правила в налаштуваннях Claude Code** — окремий шар (блок C). Поводься так, **ніби тверді заборони діють завжди**, навіть якщо hooks ще не встановлені. ## Пріоритет джерел правди (PERUKAR source-of-truth priority) Це ядро безпеки режиму. Коли є розбіжність, рішення приймається строго за цим порядком: 1. **AGENTS.md** та **docs/LOGIC_LOCKED / docs/AGENTS_LOCKED** (якщо існують). 2. **Закомічені (committed) тести:** `test_www_business_scenarios.js`, `test_www_mass_model.js`, `test_www_render_runtime.js`, `test_www_mapping.js`. 3. **Production runtime:** `www/core.js`. 4. **Брудний / незакомічений diff — НЕ джерело правди**, поки не пройшов: scope audit, conflict audit, повну матрицю тестів і commit gate. Дефолтні рішення при конфлікті: - **AGENTS.md / LOCKED docs vs БРУДНІ тести** → виграють AGENTS.md / LOCKED docs. Брудні тести вважати **підозрілими**, поки їх явно не схвалено. - **AGENTS.md / LOCKED docs vs ЗАКОМІЧЕНІ тести** → це справжній конфлікт контракту → **STOP / PROCESS FAIL** і звіт. Жоден бік не послаблювати тихо. Чому: якщо сказати «тести завжди — джерело правди», агент може узаконити зламаний брудний diff — напр. dirty-тест послаблює `BRAND-MISSING-* NO-APPROVED` до `BRAND-GENERIC-* ADVISORY-APPROVED`. Брудні тести — це **запропонована зміна**, а не контракт, поки вони не пройшли audit і commit gate. ## Крок 1 — Визнач режим - **read-only audit** — перевірити стан/diff/історію; жодних змін. - **implementation** — зміни коду в межах дозволеного scope. - **recovery** — розбір наслідків збою попереднього агента/процесу. - **commit** — застейджити й закомітити готові, перевірені зміни. - **documentation** — зміни docs (але не LOCKED-доки без явного дозволу). - **unknown** — задача неясна. Якщо режим **unknown**: **не питай одразу**. Спершу зроби read-only preflight/audit, класифікуй те, що вже відомо, і постав **щонайбільше одне точне питання** — лише якщо лишається реальне рішення, яке без користувача не закрити. При сумніві між режимами — обирай менш руйнівний: **audit, не edit.** ## Крок 2 — Preflight (обов'язково перед будь-якою не-тривіальною дією) Read-only, **не потребує підтвердження**. Запусти й **прочитай вивід**: ``` git rev-parse --show-toplevel git status --short git log --oneline -15 git diff --name-only git diff --cached --name-only ``` Навіщо: без актуального стану планування — це здогадка. На Windows перевірку файлів роби через `Test-Path` / `Get-ChildItem` (теж read-only). Команди запускай **окремо**, не зчіплюй через `&&` чи `;` — інакше при збої незрозуміло, який крок упав. ## Крок 3 — Рішення (preflight → один із чотирьох виходів) - **A. READ-ONLY AUDIT PLAN** — repo dirty, root/HEAD mismatch або задача неясна. Жодних змін. - **B. IMPLEMENTATION PLAN** — repo clean, scope зрозумілий, allowed files визначені. Перелічи точні файли й чому кожен у scope. - **C. COMMIT PLAN** — лише якщо виконано весь Commit gate (нижче). Перелічи точні шляхи для `git add`. - **D. STOP / PROCESS FAIL** — спрацювала Hard STOP умова. Назви причину й що потрібно від людини. Деталі git-операцій: `references/locked-files-and-git-policy.md`. ## Мінімальна участь користувача Read-only перевірки (preflight, status, diff, log, grep, `node --check`, прогон тестів) — **без підтвердження**. Переривай користувача **ТІЛЬКИ** для: 1. схвалення commit; 2. конфлікту бізнес-логіки (див. пріоритет джерел правди); 3. зміни LOCKED-файлу, якої немає в Allowed files; 4. ручного видалення **stale** `index.lock`; 5. деструктивної git-дії (`reset`/`restore`/`checkout`/`switch`/`clean`/`stash`); 6. повторного провалу тестів після безпечних спроб (за замовчуванням **≤2** спроби в межах scope). Scoped implementation дозволених файлів — без окремого підтвердження на кожну правку (зміни ще не закомічені й оборотні). Підтвердження потрібне на **commit**. ## Commit gate (коли commit взагалі дозволений) Commit дозволений **тільки** коли одночасно: 1. recovery/diff audit = **PASS**; 2. повна матриця тестів = **PASS**; 3. `git diff --check` = **PASS** (без whitespace-помилок / conflict-маркерів; окрема команда); 4. усі змінені файли — **всередині scope**; 5. перед стейджингом `git diff --cached --name-only` **порожній**; 6. **Approved commit file list** — точний перелік файлів саме для цього commit; він має бути **підмножиною** Allowed files; 7. після стейджингу застейджені файли **точно дорівнюють Approved commit file list** (не обов'язково всьому списку Allowed files); 8. користувач **явно схвалив commit** (`Commit: yes`). **Не запускай `git add` до явного `Commit: yes`.** До `Commit: yes` максимальний вихід — `Ready for commit gate: yes`, і нічого більше (жодного стейджингу/коміту). Стейдж **тільки точні шляхи** з Approved list: `git add exact/path`. **Ніколи** `git add .` / `-A` / `--all`. **One task = one commit.** Push у цьому режимі **не робиться ніколи**. ## Гілки / main - **Push у main — заборонений завжди.** - **Автономне перемикання гілок — заборонено.** - Якщо поточна гілка = `main` і задача — implementation або commit: - продовжуй **тільки** якщо користувач явно дозволив працювати на поточній гілці; - інакше **STOP** з одним запитом: `Confirm working on current branch or provide branch policy.` - **Ніколи** не створюй/не перемикай гілки через `git checkout` / `git switch` без явного дозволу. ## LOCKED-файли LOCKED **не означає** «ніколи не редагувати». Означає: редагувати **лише** якщо файл явно є в Allowed files задачі, scope чітко називає навіщо, обов'язкові тести + diff audit, і діє commit gate. Будь-яка правка LOCKED поза цими умовами → **STOP**. Повний перелік і політика: `references/locked-files-and-git-policy.md`. ## Матриця тестів (read-only прогон, без підтвердження) Спершу syntax-check усіх JS, потім прогін. Кожна команда — **окремо**, без `&&` і без `;` для групування: ``` node --check www/core.js node --check test_www_business_scenarios.js node --check test_www_mass_model.js node --check test_www_mapping.js node --check test_www_render_runtime.js node test_www_business_scenarios.js node test_www_mass_model.js node test_www_mapping.js node test_www_render_runtime.js ``` Тести — контракт безпеки (business safety, mass model, render/runtime, mapping, regression). Ніколи не послаблюй логіку, щоб тест пройшов. Статус тестів інтерпретуй у межах пріоритету джерел правди (committed > dirty). Інваріанти color-logic — покажчики в `references/color-logic-safety.md`; визначення живе в тестах, не дублюй їх з пам'яті. ## Вихід: формат звіту Будь-який вихід (A/B/C/D) подавай цією структурою: ``` STATUS: PASS / FAIL / PARTIAL / BLOCKED Repo root: HEAD: Git status: Changed files: Staged files: Task scope: Allowed files: Files outside scope: Tests run: Tests PASS/FAIL: Process violations: Recommended next action: Risks: ``` Якщо даних бракує — впиши **точно, чого саме бракує**, а не вгадуй. ## Hard STOP умови (→ вихід D) - dirty repo перед новою implementation-задачею → спершу **DIRTY STATE SCOPE AUDIT** (read-only); - root mismatch (очікуваний root ≠ `git rev-parse --show-toplevel`); - HEAD mismatch (очікуваний HEAD ≠ `git rev-parse HEAD`); - `index.lock` за **активного** git-процесу → STOP; `index.lock` **без** активного процесу → stale-lock candidate (див. політику в reference, ручне рішення користувача); - застейджені файли вже присутні перед стартом задачі; - змінено файл поза дозволеним scope; - тести FAIL; - спроба `git add .` / `-A` / `--all`; - спроба `push`; - спроба `reset` / `restore` / `checkout` / `switch` / `clean` / `stash` без прямого дозволу; - спроба змінити LOCKED-файл поза умовами LOCKED-політики; - конфлікт між AGENTS.md / LOCKED docs і **закоміченими** тестами. На STOP — назви причину, перелічи відсутні/проблемні дані, запропонуй безпечну наступну дію (зазвичай read-only audit). ## Тон Строгий, скептичний, практичний. Без мотиваційних фраз. Без «виглядає добре» без доказів. Без прихованих припущень. Якщо даних бракує — кажи прямо, чого саме. ## Reference-файли - `references/locked-files-and-git-policy.md` — LOCKED-перелік, детальна git-політика, детектування dirty/index.lock/mismatch, recovery/diff audit. - `references/color-logic-safety.md` — покажчики на safety-інваріанти color-logic; джерело правди — закомічені тести + LOCKED docs.