fix(pipeline-docs): unify N/M placeholder notation in agents and skills #78

New issue

Closed

opened 2026-08-16 18:06:57 +03:00 by slaid098 · 0 comments

slaid098 commented

2026-08-16 18:06:57 +03:00

Owner

Контекст

Конвенция run-pipeline SKILL.md: N=issue, M=PR. Она нарушается в смежных файлах, что вносит путаницу номеров:

.opencode/agents/memory-syncer.md: «Get the PR number», curl pulls/<N>, receipt - [YYYY-MM-DD, PR#N] — здесь N = PR.
.opencode/agents/reviewer.md: failure-пример ⚠️ post-review failed for PR #N — N = PR; правила используют pulls/<N>.
issue SKILL.md (~строка 187): merge-pr({ pr_number: N }) — N = PR, хотя в том же файле N = issue.
reviewer.md: git diff main...HEAD — хардкод main, тогда как run-pipeline Template C уже использует origin/HEAD (ADR-076).
.opencode/scripts/check-permissions.py: подсказки «use pipeline_status tool, not bash» — snake_case вместо kebab-case.
memory-syncer.md: устаревшая ссылка на строки («## Setup» line 38, правило на строках 47–48).

Задача

Принять единую конвенцию в agent-facing документах: плейсхолдер номера PR = <PR_NUMBER>, номера issue = <ISSUE_NUMBER> (самодокументируемо, устраняет буквенные коллизии). Применить в memory-syncer.md, reviewer.md, issue SKILL.md. Receipt-формат memory: пример записи привести как - [YYYY-MM-DD, PR#<PR_NUMBER>] с пояснением, что подставляется реальный номер.
run-pipeline SKILL.md не трогать — его нотация чинится отдельным issue; после обоих мержей конвенции не должны конфликтовать (там N=issue, M=PR с явной легендой; здесь самодокументируемые плейсхолдеры).
reviewer.md: git diff main...HEAD → git diff origin/HEAD...HEAD.
check-permissions.py: snake_case → kebab-case в текстах подсказок (pipeline-status, spec-status, merge-pr...).
memory-syncer.md: поправить устаревшую ссылку на строки.
Копии агентов/скриптов в .opencode и ~/.config/opencode — байт-идеальный синк.

Контракты

Поведение агентов не меняется — правки только документационные/текстовые (prompt-файлы, help-строки check-permissions).
Формат receipts - [YYYY-MM-DD, PR#N] как регулярное выражение в pipeline-status.py НЕ меняется — меняется только пример-плейсхолдер в документации агента.

Инварианты

check-permissions.py остаётся функционально идентичным (меняются только строки сообщений).
Нумерация правил/шагов в агентах не сдвигается.

Граничные случаи

Все места, где N осознанно означает issue (например issues/<issue_N> в memory-syncer.md), привести к <ISSUE_NUMBER>.

Влияние на связанные компоненты

run-pipeline SKILL.md (отдельный issue) — согласованность конвенций проверить при мерже.
Тестов на строки check-permissions.py нет — grep-чеки достаточно.

Вне scope

Изменения оракула и run-pipeline/issue/bug-discovery скиллов — отдельные issues.

Критерии приемки

grep: в .opencode/agents/*.md и issue SKILL.md нет PR#N / «PR #N» / pulls/<N>; вместо них <PR_NUMBER>/<ISSUE_NUMBER>.
reviewer.md содержит git diff origin/HEAD...HEAD, не содержит main...HEAD.
check-permissions.py: подсказки в kebab-case.
diff копий файлов между .opencode и ~/.config/opencode пуст.

## Контекст Конвенция run-pipeline SKILL.md: N=issue, M=PR. Она нарушается в смежных файлах, что вносит путаницу номеров: - `.opencode/agents/memory-syncer.md`: «Get the PR number», curl `pulls/<N>`, receipt `- [YYYY-MM-DD, PR#N]` — здесь N = PR. - `.opencode/agents/reviewer.md`: failure-пример `⚠️ post-review failed for PR #N` — N = PR; правила используют `pulls/<N>`. - `issue` SKILL.md (~строка 187): `merge-pr({ pr_number: N })` — N = PR, хотя в том же файле N = issue. - `reviewer.md`: `git diff main...HEAD` — хардкод main, тогда как run-pipeline Template C уже использует `origin/HEAD` (ADR-076). - `.opencode/scripts/check-permissions.py`: подсказки «use pipeline_status tool, not bash» — snake_case вместо kebab-case. - memory-syncer.md: устаревшая ссылка на строки («## Setup» line 38, правило на строках 47–48). ## Задача 1. Принять единую конвенцию в agent-facing документах: плейсхолдер номера PR = `<PR_NUMBER>`, номера issue = `<ISSUE_NUMBER>` (самодокументируемо, устраняет буквенные коллизии). Применить в memory-syncer.md, reviewer.md, issue SKILL.md. Receipt-формат memory: пример записи привести как `- [YYYY-MM-DD, PR#<PR_NUMBER>]` с пояснением, что подставляется реальный номер. 2. run-pipeline SKILL.md не трогать — его нотация чинится отдельным issue; после обоих мержей конвенции не должны конфликтовать (там N=issue, M=PR с явной легендой; здесь самодокументируемые плейсхолдеры). 3. reviewer.md: `git diff main...HEAD` → `git diff origin/HEAD...HEAD`. 4. check-permissions.py: snake_case → kebab-case в текстах подсказок (`pipeline-status`, `spec-status`, `merge-pr`...). 5. memory-syncer.md: поправить устаревшую ссылку на строки. 6. Копии агентов/скриптов в .opencode и ~/.config/opencode — байт-идеальный синк. ## Контракты - Поведение агентов не меняется — правки только документационные/текстовые (prompt-файлы, help-строки check-permissions). - Формат receipts `- [YYYY-MM-DD, PR#N]` как регулярное выражение в pipeline-status.py НЕ меняется — меняется только пример-плейсхолдер в документации агента. ## Инварианты - check-permissions.py остаётся функционально идентичным (меняются только строки сообщений). - Нумерация правил/шагов в агентах не сдвигается. ## Граничные случаи - Все места, где N осознанно означает issue (например `issues/<issue_N>` в memory-syncer.md), привести к `<ISSUE_NUMBER>`. ## Влияние на связанные компоненты - run-pipeline SKILL.md (отдельный issue) — согласованность конвенций проверить при мерже. - Тестов на строки check-permissions.py нет — grep-чеки достаточно. ## Вне scope - Изменения оракула и run-pipeline/issue/bug-discovery скиллов — отдельные issues. ## Критерии приемки - grep: в `.opencode/agents/*.md` и issue SKILL.md нет `PR#N` / «PR #N» / `pulls/<N>`; вместо них `<PR_NUMBER>`/`<ISSUE_NUMBER>`. - reviewer.md содержит `git diff origin/HEAD...HEAD`, не содержит `main...HEAD`. - check-permissions.py: подсказки в kebab-case. - diff копий файлов между .opencode и ~/.config/opencode пуст.

slaid098 added the

bug

label

2026-08-16 18:06:57 +03:00

slaid098 referenced this issue from a pull request that will close it,

2026-08-16 19:34:00 +03:00

fix(pipeline-docs): unify N/M placeholder notation in agents and skills #84

slaid098 referenced this issue

2026-08-16 19:38:29 +03:00

fix(pipeline-docs): unify N/M placeholder notation in agents and skills #84

slaid098 closed this issue

2026-08-16 19:38:40 +03:00