From 27db3851b6049a2527b559d17b29843158106162 Mon Sep 17 00:00:00 2001 From: Sergey <93754860+slaid098@users.noreply.github.com> Date: Fri, 31 Jul 2026 18:47:32 +0300 Subject: [PATCH] fix(agents): resolve prompt contradictions and path mismatches (#163) * fix(agents): allow echo and fix paths in docs-reviewer * fix(agents): allow echo and load memory skill in memory-syncer * fix(agents): fix skills path and load code-standards in reviewer * fix(pipeline): remove checkout master from template E * fix(scripts): update scaffold path in pipeline-status error * docs(handoff): add handoff and ADR for prompt contradictions fix * docs(handoff): set PR number --------- Co-authored-by: opencode-agent --- .opencode/agents/docs-reviewer.md | 11 +++++-- .opencode/agents/memory-syncer.md | 13 ++++---- .opencode/agents/reviewer.md | 3 +- .opencode/scripts/pipeline-status.py | 2 +- .opencode/skills/run-pipeline/SKILL.md | 5 +-- ...69-pr-163-resolve-prompt-contradictions.md | 30 +++++++++++++++++ .../pr-163-resolve-prompt-contradictions.md | 32 +++++++++++++++++++ 7 files changed, 83 insertions(+), 13 deletions(-) create mode 100644 docs/decisions/069-pr-163-resolve-prompt-contradictions.md create mode 100644 docs/handoff/pr-163-resolve-prompt-contradictions.md diff --git a/.opencode/agents/docs-reviewer.md b/.opencode/agents/docs-reviewer.md index 28382cb..22888c5 100644 --- a/.opencode/agents/docs-reviewer.md +++ b/.opencode/agents/docs-reviewer.md @@ -78,7 +78,7 @@ You are a project map reviewer. Your job: analyze structural changes in a PR, up 1. Run `gh pr view --json headRefName,title,body` to get branch name and PR context. 2. Run `gh pr checkout ` to switch to the PR branch. 3. Run `git fetch origin` to ensure you have the latest default branch. -4. Run `git diff origin/master...HEAD --stat` (or origin/main...HEAD) to see what files changed. +4. Run `git diff origin/HEAD...HEAD --stat` to see what files changed. 5. Run `repomix --no-files --stdout` to get the current directory tree. 6. Check if `docs/project-map/` exists: - Run `ls docs/project-map/ 2>/dev/null` @@ -108,7 +108,7 @@ After updating project map, validate handoff and ADR files: ### ADR (`docs/decisions/-.md`) — mandatory per ADR-002 1. ADR is **mandatory** in every PR (per ADR-002). Never bypass. -2. If ADR file `docs/decisions/*-pr-<PR#>-*.md` does not exist → create it via `bash config/scripts/scaffold-handoff.sh <PR#> <slug>` (creates both handoff + ADR templates). +2. If ADR file `docs/decisions/*-pr-<PR#>-*.md` does not exist → create it via `bash .opencode/scripts/scaffold-handoff.sh <PR#> <slug>` (creates both handoff + ADR templates). 3. Check ADR sections: Статус, Контекст, Решение, Альтернативы. 4. If sections incomplete (empty placeholders like `<заполни>`) → **fix them** based on PR diff. 5. If PR has NO architectural decisions → fill all sections (Контекст/Решение/Альтернативы) with `—` (em-dash). This is valid per ADR-002. @@ -116,6 +116,11 @@ After updating project map, validate handoff and ADR files: ## Spec cleanup (post-merge, опционально) +**GUARD: НЕ выполнять spec cleanup pre-merge — это post-merge операция.** +Spec cleanup выполняется ТОЛЬКО post-merge (в MEMORY фазе), НЕ pre-merge. +Если ты docs-reviewer (pre-merge), пропусти эту секцию — spec cleanup +выполняет memory-syncer post-merge. + Если `docs/spec/roadmap.md` существует в репо (spec был запущен): 1. Извлеки все `#N` номера issues из `docs/spec/roadmap.md` (regex `#(\d+)`). 2. Для каждого `#N`: `gh issue view N --json state --jq .state`. @@ -243,7 +248,7 @@ If `post-docs-review` returns a string starting with `⚠️ ...failed` (e.g. ` 5. Keep map files concise — structure and purpose, not implementation. 6. Update `last_updated` field in frontmatter when modifying a file. 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). +8. Для debug-вывода используй `pwd`/`ls`/`cat`/`echo` (все в allow-list). 9. НЕ переключайся на master и НЕ делай `git pull` — работай только на PR branch (checkout уже сделан в Setup). ## Bug Discovery diff --git a/.opencode/agents/memory-syncer.md b/.opencode/agents/memory-syncer.md index b1eb928..3ed1fcc 100644 --- a/.opencode/agents/memory-syncer.md +++ b/.opencode/agents/memory-syncer.md @@ -39,11 +39,12 @@ You are **read-only on the repository** and **write-only on memory**. You CANNOT ## Setup -1. Get the PR number from the invocation prompt. -2. Find the merged handoff file: `ls docs/handoff/pr-<N>-*` to discover the slug, then `cat docs/handoff/pr-<N>-<slug>.md` to read it (read-only — agent does not check out branches). -3. Determine the repo: `git remote get-url origin` → parse `{host}/{org}/{repo}` (e.g. `github.com/slaid098/opencode-config`). -4. Resolve memory path: read `OPENCODE_MEMORY_DIR` env var (set globally via docker-compose; fallback `~/.local/share/opencode/opencode-memory/`) → `<memory_dir>/repos/{host}/{org}/{repo}.md`. Use `printenv OPENCODE_MEMORY_DIR` to inspect it. -5. Open the memory file (create if missing) via the `edit`/`write` tool — `edit: allow` permits this. The memory dir is an isolated git repo (post-commit hook auto-pushes), separate from the main repo. +1. Load the memory skill via `skill("memory")` to get distillation rules and format conventions. +2. Get the PR number from the invocation prompt. +3. Find the merged handoff file: `ls docs/handoff/pr-<N>-*` to discover the slug, then `cat docs/handoff/pr-<N>-<slug>.md` to read it (read-only — agent does not check out branches). +4. Determine the repo: `git remote get-url origin` → parse `{host}/{org}/{repo}` (e.g. `github.com/slaid098/opencode-config`). +5. Resolve memory path: read `OPENCODE_MEMORY_DIR` env var (set globally via docker-compose; fallback `~/.local/share/opencode/opencode-memory/`) → `<memory_dir>/repos/{host}/{org}/{repo}.md`. Use `printenv OPENCODE_MEMORY_DIR` to inspect it. +6. Open the memory file (create if missing) via the `edit`/`write` tool — `edit: allow` permits this. The memory dir is an isolated git repo (post-commit hook auto-pushes), separate from the main repo. ## Distillation @@ -92,7 +93,7 @@ If a fact is already recorded — update the entry (bump `updated` in frontmatte 4. ONLY read files under `docs/handoff/` and `docs/decisions/`. 5. Receipt is mandatory even if no durable records found. 6. If memory file doesn't exist — create it with proper frontmatter (title, tags, summary, created, updated, importance). -7. Для debug-вывода используй `pwd`/`ls`/`cat`/`printenv` — НЕ `echo` (не в allow-list). +7. Для debug-вывода используй `pwd`/`ls`/`cat`/`printenv`/`echo` (все в allow-list). 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, переключаться не нужно. diff --git a/.opencode/agents/reviewer.md b/.opencode/agents/reviewer.md index d5d4558..149b36d 100644 --- a/.opencode/agents/reviewer.md +++ b/.opencode/agents/reviewer.md @@ -93,8 +93,9 @@ You are a global code reviewer. Your job: review PRs against project skills and 2. Run `git diff main...HEAD --stat` to see what files changed. 3. Run `git diff main...HEAD` to see the actual changes. 4. Check if the repo has project-specific skills: - - Run `find skills/ -name "SKILL.md" -o -name "skill.md" 2>/dev/null` + - Run `find .opencode/skills/ -name "SKILL.md" -o -name "skill.md" 2>/dev/null` - If skills exist, load each via `skill("<name>")` to get project-specific rules. + - Load `skill("code-standards")` for universal code review standards. 5. Check CI status: use `pipeline-status({pr_number: <PR_NUMBER>})` tool. If unavailable, use `gh run list --branch <headRefName> --limit 3`. Do NOT use `gh pr checks` (403) or bash `python3 .../pipeline-status.py` (denied). diff --git a/.opencode/scripts/pipeline-status.py b/.opencode/scripts/pipeline-status.py index 6b518d4..b3e925e 100644 --- a/.opencode/scripts/pipeline-status.py +++ b/.opencode/scripts/pipeline-status.py @@ -327,7 +327,7 @@ def check_adr(pr_number: int) -> PhaseResult: return PhaseResult( PhaseStatus.NOT_DONE, f"ADR *-pr-{pr_number}-*.md не найден. " - f"Создай через bash config/scripts/scaffold-handoff.sh {pr_number} <slug>", + f"Создай через bash .opencode/scripts/scaffold-handoff.sh {pr_number} <slug>", ) diff --git a/.opencode/skills/run-pipeline/SKILL.md b/.opencode/skills/run-pipeline/SKILL.md index fa2cd9f..fd5da36 100644 --- a/.opencode/skills/run-pipeline/SKILL.md +++ b/.opencode/skills/run-pipeline/SKILL.md @@ -144,8 +144,9 @@ Log: `gh run view <run-id> --log-failed` output: (default `~/.local/share/opencode/opencode-memory`, override через `OPENCODE_MEMORY_DIR`; `{host}/{org}/{repo}` вычисли через `git remote get-url origin` — см. `memory-syncer.md:38`). -1. Прочитай `docs/handoff/pr-M-*.md` и `docs/decisions/*-pr-M-*.md` с master - (`git checkout master && git pull`). +1. Прочитай `docs/handoff/pr-M-*.md` и `docs/decisions/*-pr-M-*.md` с текущего + состояния (уже смерженный default branch — checkout/pull НЕ нужны, запрещены + permission set'ом memory-syncer'а). 2. Найди durable gotchas (не статусы, не "сейчас делаем"). Паттерны, указатели, non-obvious API quirks. 3. Добавь записи формата `- [YYYY-MM-DD, PR#M] <summary>` в конец файла diff --git a/docs/decisions/069-pr-163-resolve-prompt-contradictions.md b/docs/decisions/069-pr-163-resolve-prompt-contradictions.md new file mode 100644 index 0000000..0de5607 --- /dev/null +++ b/docs/decisions/069-pr-163-resolve-prompt-contradictions.md @@ -0,0 +1,30 @@ +# ADR-069: Resolve prompt contradictions and path mismatches + +## Статус +Accepted (2026-07-31) + +## Контекст +В prompt-инструкциях агентов (docs-reviewer.md, memory-syncer.md, reviewer.md), run-pipeline/SKILL.md и pipeline-status.py накопилось 8 противоречий между декларированными правилами и фактическими permission set'ами / структурой репозитория. Это приводило к doom-loop'ам, невозможности выполнить инструкции и несоответствию путей. + +Конкретные противоречия: +1. `echo` запрещён в Rules, но разрешён в allow-list. +2. Путь `config/scripts/scaffold-handoff.sh` устарел — скрипт переехал в `.opencode/scripts/`. +3. `origin/master...HEAD` ломается на репо с default branch `main`. +4. `find skills/` не находит skills (реальный путь `.opencode/skills/`). +5. reviewer не загружает `code-standards` скилл. +6. Template E требует `git checkout master && git pull` — отсутствует в allow-list memory-syncer'а. +7. memory-syncer не загружает `memory` скилл перед дистилляцией. +8. Spec cleanup (post-merge операция) описан в docs-reviewer (pre-merge агент). + +## Решение +Устранить все 8 противоречий точечными правками: +- Привести Rules в соответствие с allow-list (echo разрешён). +- Обновить пути: `config/scripts/` → `.opencode/scripts/`, `skills/` → `.opencode/skills/`. +- Унифицировать default-branch через `origin/HEAD...HEAD`. +- Добавить загрузку скиллов (`code-standards` для reviewer, `memory` для memory-syncer). +- Убрать `git checkout master && git pull` из Template E (memory-syncer работает на текущем состоянии). +- Добавить явный guard: spec cleanup — post-merge only. +- Синхронизировать зеркало `~/.config/opencode/` с repo-local `.opencode/`. + +## Альтернативы +— \ No newline at end of file diff --git a/docs/handoff/pr-163-resolve-prompt-contradictions.md b/docs/handoff/pr-163-resolve-prompt-contradictions.md new file mode 100644 index 0000000..88634f6 --- /dev/null +++ b/docs/handoff/pr-163-resolve-prompt-contradictions.md @@ -0,0 +1,32 @@ +--- +pr: 163 +title: fix(agents): resolve prompt contradictions and path mismatches +--- + +## Что сделано +Устранены 8 противоречий в prompt-инструкциях агентов и скриптах пайплайна: +- Убран запрет `echo` из Rule 8 docs-reviewer.md и Rule 7 memory-syncer.md (echo уже в allow-list). +- Заменён устаревший путь `config/scripts/scaffold-handoff.sh` → `.opencode/scripts/scaffold-handoff.sh` в docs-reviewer.md (ADR секция) и pipeline-status.py (сообщение об ошибке check_adr). +- Заменён `origin/master...HEAD` → `origin/HEAD...HEAD` в docs-reviewer.md (Setup шаг 4) для унификации default-branch. +- Заменён `find skills/` → `find .opencode/skills/` в reviewer.md (Setup шаг 4). +- Добавлена загрузка `skill("code-standards")` в Setup reviewer.md после загрузки project skills. +- Убран `git checkout master && git pull` из Template E в run-pipeline/SKILL.md (memory-syncer работает на уже смерженном default branch — checkout/pull запрещены его permission set). +- Добавлена загрузка `skill("memory")` в Setup memory-syncer.md перед дистилляцией. +- Добавлен явный guard в Spec cleanup секцию docs-reviewer.md: «НЕ выполнять spec cleanup pre-merge — это post-merge операция». + +Зеркало `~/.config/opencode/` синхронизировано с repo-local `.opencode/` (agents/, skills/, scripts/). + +## Почему +Противоречия между permission set'ами и prompt-инструкциями приводили к: +- Невозможности использовать `echo` для debug, хотя он разрешён в allow-list. +- Несоответствию путей скриптов (scaffold-handoff.sh переехал из `config/scripts/` в `.opencode/scripts/`, но prompts и сообщения об ошибках не обновились). +- Поломке на main-репо из-за хардкода `origin/master` вместо `origin/HEAD`. +- Неспособности reviewer найти project skills (путь `skills/` вместо `.opencode/skills/`). +- Violation permission set'а memory-syncer'а (Template E требовал `git checkout master && git pull`, которые отсутствуют в allow-list). +- Выполнению post-merge операций (spec cleanup) на pre-merge стадии. + +## Pending +— + +## Watch out +— \ No newline at end of file