fix(agents): enforce bug-discovery protocol across all subagent layers (#128)

* fix(agents): strengthen bug-discovery protocol in AGENTS.md to MANDATORY

* fix(skills): add bug-discovery triggers to run-pipeline templates A-E

* fix(agents): add bug-discovery section to subagent bodies

* fix(skill): strengthen bug-discovery description for semantic matching

* docs(handoff): scaffold handoff and ADR for bug-discovery protocol

* docs(handoff): set PR number

---------

Co-authored-by: opencode-agent <agent@opencode.local>

.opencode/agents/docs-reviewer.md

@@ -245,3 +245,7 @@ If `post-docs-review` returns a string starting with `⚠️ ...failed` (e.g. `
 7. If `docs/project-map/` doesn't exist → create initial map with `README.md` and one file per top-level module.
 8. Для debug-вывода используй `pwd`/`ls`/`cat` — НЕ `echo` (не в allow-list).
 9. НЕ переключайся на master и НЕ делай `git pull` — работай только на PR branch (checkout уже сделан в Setup).
+
+## Bug Discovery
+
+If you find a bug outside the current PR/task scope — you MUST load skill `bug-discovery` via `skill("bug-discovery")` tool and follow its protocol. Do NOT fix the bug yourself. Report to orchestrator: "Created issue #N: ...".

.opencode/agents/memory-syncer.md

@@ -96,3 +96,7 @@ If a fact is already recorded — update the entry (bump `updated` in frontmatte
 8. Для статуса PR используй нативный tool `pipeline-status` (НЕ bash `python3 .../pipeline-status.py` — детерминированный deny-rule, см. ADR-019).
 9. НЕ используй `git -C <path>` — работай в текущем cwd (memory-syncer читает уже смерженный default branch).
 10. НЕ делай `git checkout`/`git pull` — работаешь на уже смерженном default branch, переключаться не нужно.
+
+## Bug Discovery
+
+If you find a bug outside the current PR/task scope — you MUST load skill `bug-discovery` via `skill("bug-discovery")` tool and follow its protocol. Do NOT fix the bug yourself. Report to orchestrator: "Created issue #N: ...".

.opencode/agents/reviewer.md

@@ -312,3 +312,7 @@ If `post-review` returns a string starting with `⚠️ ...failed` (e.g. `⚠️
 8. After `post-review` with REQUEST_CHANGES, STOP. Do not merge.
 9. Для получения login автора PR используй `gh pr view --json author` (НЕ `gh api user` — broad API call, не в allow-list, вызывает doom-loop).
 10. Для debug-вывода используй `pwd`/`ls`/`cat` — НЕ `echo` (не в allow-list).
+
+## Bug Discovery
+
+If you find a bug outside the current PR/task scope — you MUST load skill `bug-discovery` via `skill("bug-discovery")` tool and follow its protocol. Do NOT fix the bug yourself. Report to orchestrator: "Created issue #N: ...".

.opencode/skills/bug-discovery/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bug-discovery
-description: Use when a bug is found outside the current task scope. Covers duplicate check, issue creation via create-issue tool, and continuation protocol. Also when user says "нашёл баг", "bug found", "создай issue для бага", "bug outside scope".
+description: Use when a bug is found outside the current task scope — MANDATORY for ALL subagents. Covers duplicate check, issue creation via create-issue tool, and continuation protocol. Also when user says "нашёл баг", "bug found", "создай issue для бага", "bug outside scope", "заметил проблему", "code smell", "unexpected behavior not related to current task".
 ---
 
 # Bug Discovery Protocol

.opencode/skills/run-pipeline/SKILL.md

@@ -62,6 +62,7 @@ description: Autonomous PR pipeline executor. Delegates 7 phases to subagents, d
    frontmatter, отдельный коммит `docs(handoff): set PR number` через
    `commit` tool, push.
 7. Верни PR номер M.
+Если найдёшь баг вне scope текущей задачи — загрузи skill `bug-discovery` через `skill("bug-discovery")` и следуй протоколу. НЕ чини баг сам. Сообщи оркестратору: "Created issue #N: ...".
 ```
 
 ### Template B (docs-review)
@@ -91,7 +92,8 @@ Review PR#M в текущем репо (pre-merge, режим docs).
    Heading `## Docs Review Summary` — обязательно (regex `Docs Review`),
    tool добавляет его автоматически — НЕ форматируй heading/verdict вручную.
    Если tool вернул строку начинающуюся с `⚠️ ...failed` — СООБЩИ оркестратору
-   о сбое и STOP (не fallback на raw bash).
+    о сбое и STOP (не fallback на raw bash).
+Если найдёшь баг вне scope текущей задачи — загрузи skill `bug-discovery` через `skill("bug-discovery")` и следуй протоколу. НЕ чини баг сам. Сообщи оркестратору: "Created issue #N: ...".
 ```
 
 ### Template C (code_review)
@@ -112,7 +114,8 @@ Review PR#M в текущем репо.
    Tool добавляет heading + verdict line автоматически — НЕ форматируй их
    вручную. Если tool вернул строку начинающуюся с `⚠️ ...failed` — СООБЩИ
    оркестратору о сбое и STOP (не fallback на raw bash).
-   6. НЕ МЕРДЖИТЬ — merge делает основной агент через run-pipeline.
+    6. НЕ МЕРДЖИТЬ — merge делает основной агент через run-pipeline.
+Если найдёшь баг вне scope текущей задачи — загрузи skill `bug-discovery` через `skill("bug-discovery")` и следуй протоколу. НЕ чини баг сам. Сообщи оркестратору: "Created issue #N: ...".
 ```
 
 ### Template D (fix_ci)
@@ -130,6 +133,7 @@ Log: `gh run view <run-id> --log-failed` output:
    `commit({ message: "fix(ci): <description>" })` tool (НЕ raw
    `git commit`), push.
 5. Не трогай логику unrelated файлов.
+Если найдёшь баг вне scope текущей задачи — загрузи skill `bug-discovery` через `skill("bug-discovery")` и следуй протоколу. НЕ чини баг сам. Сообщи оркестратору: "Created issue #N: ...".
 ```
 
 ### Template E (memory_sync)
@@ -149,7 +153,8 @@ Log: `gh run view <run-id> --log-failed` output:
 4. Квитанция ВСЕГДА (даже если durable нет): `- [date, PR#M] — (нет durable-записей)`.
 5. `memory-save` для commit + reindex + push.
 6. Проверь `git status` основного репо — если staged что-то в memory dir,
-   репорт пользователю (guard от случайного коммита в master).
+    репорт пользователю (guard от случайного коммита в master).
+Если найдёшь баг вне scope текущей задачи — загрузи skill `bug-discovery` через `skill("bug-discovery")` и следуй протоколу. НЕ чини баг сам. Сообщи оркестратору: "Created issue #N: ...".
 ```
 
 ### Template F (merge)

AGENTS.md

@@ -13,9 +13,15 @@
 Pipeline: ISSUE → IMPLEMENT → DOCS → CI → REVIEW → MERGE → MEMORY.
 `pipeline-status` = read-only oracle (NEXT action). `merge-pr` = orchestrator-safe merge wrapper. Execution via `/run-pipeline` skill.
 
-## Bug Discovery Protocol
+## Bug Discovery Protocol (MANDATORY)
 
-If a bug is found outside current task scope — load skill `bug-discovery`.
+If you find a bug outside current task scope — you MUST:
+1. Load skill `bug-discovery` via `skill("bug-discovery")` tool.
+2. Follow its protocol (check duplicates → create issue → continue task).
+3. Do NOT fix the bug yourself.
+4. Report to orchestrator: "Created issue #N: ...".
+
+This applies to ALL subagents (general, reviewer, docs-reviewer, memory-syncer).
 
 ## Linear Execution
 

docs/decisions/057-pr-128-enforce-bug-discovery-protocol.md

@@ -0,0 +1,18 @@
+# ADR-057: Enforce bug-discovery protocol across all subagent layers
+
+## Статус
+Accepted (2026-07-29)
+
+## Контекст
+Bug-discovery protocol в AGENTS.md состоял из одной строки и не срабатывал у subagents. Subagents (reviewer, docs-reviewer, memory-syncer) не загружали skill `bug-discovery` при обнаружении багов вне scope текущей задачи — баги либо игнорировались, либо фиксировались напрямую (нарушение протокола).
+
+## Решение
+Усилить протокол в 4 слоях (defense-in-depth):
+1. AGENTS.md — секция помечена MANDATORY, добавлен нумерованный протокол и список применимых subagents.
+2. run-pipeline templates A-E — каждый template содержит явный reminder загружать skill.
+3. Agent definition bodies (reviewer, docs-reviewer, memory-syncer) — секция "## Bug Discovery" в конце body.
+4. bug-discovery SKILL.md description — расширена триггерными фразами для лучшего semantic matching.
+
+## Альтернативы
+— Одиночное усиление в AGENTS.md (отвергнуто: уже не работал).
+— Permission-level enforcement через bash deny-rules (отвергнуто: bug-discovery — поведенческий паттерн, не bash-команда).

docs/handoff/pr-128-enforce-bug-discovery-protocol.md

@@ -0,0 +1,20 @@
+---
+pr: 128
+title: fix(agents): enforce bug-discovery protocol across all subagent layers
+---
+
+## Что сделано
+Усилён Bug Discovery Protocol в 4 слоях:
+- AGENTS.md: секция "Bug Discovery Protocol" → "Bug Discovery Protocol (MANDATORY)" с нумерованным протоколом (load skill → follow protocol → do NOT fix → report to orchestrator) и явным списком применимых subagents (general, reviewer, docs-reviewer, memory-syncer).
+- .opencode/skills/bug-discovery/SKILL.md: description расширена триггерами "заметил проблему", "code smell", "unexpected behavior not related to current task" + "MANDATORY for ALL subagents".
+- .opencode/skills/run-pipeline/SKILL.md: в каждый из 5 templates (A-E) добавлена строка-reminder: "Если найдёшь баг вне scope — загрузи skill bug-discovery ... НЕ чини баг сам".
+- .opencode/agents/reviewer.md, docs-reviewer.md, memory-syncer.md: в body каждого добавлена секция "## Bug Discovery" с обязательным протоколом.
+
+## Почему
+Bug-discovery protocol не срабатывал у subagents — одна строка в AGENTS.md была слишком слабым сигналом. Subagents не загружали skill `bug-discovery` при обнаружении багов вне scope. Усиление в 4 слоях (AGENTS.md → run-pipeline templates → agent bodies → SKILL description) обеспечивает множественные точки напоминания на разных уровнях вызова.
+
+## Pending
+—
+
+## Watch out
+—