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 <agent@opencode.local>
2026-07-31 18:47:32 +03:00 · 2026-07-31 18:47:32 +03:00 · 27db3851b6
commit 27db3851b6
parent 746bb7438e
7 changed files with 83 additions and 13 deletions
--- 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 <PR_NUMBER> --json headRefName,title,body` to get branch name and PR context.
 2. Run `gh pr checkout <PR_NUMBER>` 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/<NN>-<title>.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
--- 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, переключаться не нужно.
--- 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).
--- 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>",
    )


--- 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>` в конец файла
--- a/docs/decisions/069-pr-163-resolve-prompt-contradictions.md
+++ 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/`.
+
+## Альтернативы
+—
--- a/docs/handoff/pr-163-resolve-prompt-contradictions.md
+++ 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
+—