From c3efae6a3069745f43c213f5630e12d707d2a4eb Mon Sep 17 00:00:00 2001 From: Sergey <93754860+slaid098@users.noreply.github.com> Date: Wed, 29 Jul 2026 18:29:41 +0300 Subject: [PATCH] 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 --- .opencode/agents/docs-reviewer.md | 4 ++++ .opencode/agents/memory-syncer.md | 4 ++++ .opencode/agents/reviewer.md | 6 +++++- .opencode/skills/bug-discovery/SKILL.md | 2 +- .opencode/skills/run-pipeline/SKILL.md | 11 +++++++--- AGENTS.md | 10 ++++++++-- ...7-pr-128-enforce-bug-discovery-protocol.md | 18 +++++++++++++++++ .../pr-128-enforce-bug-discovery-protocol.md | 20 +++++++++++++++++++ 8 files changed, 68 insertions(+), 7 deletions(-) create mode 100644 docs/decisions/057-pr-128-enforce-bug-discovery-protocol.md create mode 100644 docs/handoff/pr-128-enforce-bug-discovery-protocol.md diff --git a/.opencode/agents/docs-reviewer.md b/.opencode/agents/docs-reviewer.md index 1fdff90..28382cb 100644 --- a/.opencode/agents/docs-reviewer.md +++ b/.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: ...". diff --git a/.opencode/agents/memory-syncer.md b/.opencode/agents/memory-syncer.md index 6a19b90..b1eb928 100644 --- a/.opencode/agents/memory-syncer.md +++ b/.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 ` — работай в текущем 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: ...". diff --git a/.opencode/agents/reviewer.md b/.opencode/agents/reviewer.md index 702ad3b..d5d4558 100644 --- a/.opencode/agents/reviewer.md +++ b/.opencode/agents/reviewer.md @@ -311,4 +311,8 @@ If `post-review` returns a string starting with `⚠️ ...failed` (e.g. `⚠️ Main agent merges via run-pipeline. 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). \ No newline at end of file +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: ...". \ No newline at end of file diff --git a/.opencode/skills/bug-discovery/SKILL.md b/.opencode/skills/bug-discovery/SKILL.md index 570dc43..3933c93 100644 --- a/.opencode/skills/bug-discovery/SKILL.md +++ b/.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 diff --git a/.opencode/skills/run-pipeline/SKILL.md b/.opencode/skills/run-pipeline/SKILL.md index 380fdcd..fa2cd9f 100644 --- a/.opencode/skills/run-pipeline/SKILL.md +++ b/.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 --log-failed` output: `commit({ message: "fix(ci): " })` 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 --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) diff --git a/AGENTS.md b/AGENTS.md index 3dd735b..576548f 100644 --- a/AGENTS.md +++ b/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 diff --git a/docs/decisions/057-pr-128-enforce-bug-discovery-protocol.md b/docs/decisions/057-pr-128-enforce-bug-discovery-protocol.md new file mode 100644 index 0000000..65c0ef3 --- /dev/null +++ b/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-команда). diff --git a/docs/handoff/pr-128-enforce-bug-discovery-protocol.md b/docs/handoff/pr-128-enforce-bug-discovery-protocol.md new file mode 100644 index 0000000..e71d1a3 --- /dev/null +++ b/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 +—