engram-branch-pr

使用するタイミング

次の場合に、このスキルを使用します：

• 変更を加えるプルリクエストを作成するとき
• 提出するブランチを準備するとき
• コントリビューターが PR を作成するのを支援するとき

---

重要なルール

1. すべての PR で、承認済みの issue へのリンクが必須です — 例外はありません
2. すべての PR に、type:* ラベルを必ず 1 つだけ付けてください
3. マージを可能にするには、必須の自動チェックにすべて合格する必要があります
4. issue にリンクしていない空の PR は、GitHub Actions によってブロックされます

---

ワークフロー

1. Verify issue has `status:approved` label
2. Create branch: feat/*, fix/*, docs/*, refactor/*, chore/*
3. Implement changes
4. For behavior changes, run a focused regression test and affected package tests locally; record commands and outcomes. For docs-only changes, record N/A for Go tests and verify the documentation.
5. Check every changed path against the [Transient Artifact Policy](../../CONTRIBUTING.md#transient-artifact-policy)
6. Open PR using the template
7. Add exactly one type:* label
8. After pushing/opening the PR, wait for GitHub CI's full unit/E2E/lint and applicable platform checks; report results only after they run

---

ブランチの命名（GitHub ルールセットによる強制）

ブランチ名は GitHub ルールセットによって検証されます。一致しないプッシュは拒否されます。

パターン： ^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$

種類	ブランチのパターン	例
機能	feat/<description>	feat/json-export-command
バグ修正	fix/<description>	fix/duplicate-observation-insert
雑務	chore/<description>	chore/bump-bubbletea-v0.26
ドキュメント	docs/<description>	docs/api-reference-update
スタイル	style/<description>	style/fix-tui-alignment
リファクタリング	refactor/<description>	refactor/extract-query-sanitizer
パフォーマンス	perf/<description>	perf/optimize-fts5-queries
テスト	test/<description>	test/add-sync-coverage
ビルド	build/<description>	build/update-go-toolchain
CI	ci/<description>	ci/split-e2e-job
リバート	revert/<description>	revert/broken-migration

ルール：

• 説明はすべて小文字にする必要があります
• 説明には a-z、0-9、.、_、- のみ使用できます
• 大文字、スペース、特殊文字は使用できません

---

PR 本文の形式

PR テンプレートは .github/PULL_REQUEST_TEMPLATE.md にあります。すべての PR 本文に、以下を含める必要があります：

1. リンクされた issue（必須）

Closes #<issue-number>

有効なキーワード：Closes #N、Fixes #N、Resolves #N（大文字と小文字は区別されません）。 リンク先の issue には status:approved ラベルが付いている必要があります。

2. PR の種類（必須）

テンプレートで該当する項目を 1 つだけ選択し、対応するラベルを追加します：

チェックボックス	追加するラベル
バグ修正	type:bug
新機能	type:feature
ドキュメントのみ	type:docs
コードのリファクタリング	type:refactor
メンテナンス／ツール	type:chore
破壊的変更	type:breaking-change

3. 概要

PR の内容を 1～3 個の箇条書きで説明します。

4. 変更点の表

| File | Change |
|------|--------|
| `path/to/file` | What changed |

5. テスト計画

- [ ] Focused regression (behavior change): `<actual command>` — `<actual outcome or N/A: documentation-only>`
- [ ] Affected package (behavior change): `<actual command>` — `<actual outcome or N/A: documentation-only>`
- [ ] GitHub CI full unit/E2E/lint and applicable platform checks — pending until they run

サンプルのコマンドと結果は、実際の証拠に置き換えてください。ドキュメントのみの変更の場合、ローカルの Go テストには N/A — documentation-only; no Go behavior changed と記録し、実際に実行したドキュメントのチェックを列挙してください。対象を絞ったカバレッジは、見落とした分岐の発見に役立ちます。モジュール全体のカバレッジや PR ごとの数値ゲートは適用されません。PR を作成していない場合（またはプッシュ前）、およびリスクの高い変更の場合は、該当する追加のローカルチェックを実行し、CI の証拠に不足があれば明記してください。

6. コントリビューターチェックリスト

すべての項目にチェックを付ける必要があります：

• 承認済みの issue にリンクした
• type:* ラベルをちょうど 1 つ追加した
• 動作に関わる変更では、実際に実行した対象を絞った回帰テストおよび影響を受けるパッケージのテストコマンドと結果を記録した。ドキュメントのみの変更では N/A とした
• PR を作成せずに、またはリスクの高い変更に対して、該当する追加のローカルチェックを実行し、不足している CI の証拠を明記した
• 動作を変更した場合、ドキュメントを更新した
• Conventional Commits の形式に従った
• Co-Authored-By トレーラーを含めていない
• 変更したすべてのパスが一時成果物ポリシーに準拠している

---

自動チェック

必須コンテキストの6項目はCONTRIBUTING.mdに記載されています。マージ前に6項目すべてに合格する必要があります。Lint、一時生成物チェック、Windows Setup Test、Cloud Sync Wrapper Tests (Windows)はPRでは実行されますが、マージグループでは実行されず、必須コンテキストの6項目には含まれません。保留中のチェックを合格扱いせず、実際の結果を報告してください。

チェック	ジョブ名	検証内容
PR 検証	Check Issue Reference	本文に Closes/Fixes/Resolves #N が含まれている
PR 検証	Check Issue Has status:approved	リンクされたIssueに status:approved が付いている
PR ラベルポリシー	Check PR Has type:* Label	PRに type:* ラベルが1つだけ付いている
一時生成物チェック	Check PR Has No Transient Artifacts	PRのファイルが一時生成物ポリシーに準拠している
CI	Unit Tests	go test ./... が合格する
CI	E2E Tests	go test -tags e2e ./internal/server/... が合格する
CI	Plugin Tests	plugin/piで npm test が合格する
CI	Lint	golangci-lintがGoの変更に新たな指摘がないと報告する
CI	Windows Setup Test	Windowsのセットアップで絶対パスが保持され、MCPのジョブオブジェクトに関する親プロセスの有効期間テストが合格する
CI	Cloud Sync Wrapper Tests (Windows)	Windowsでクラウド同期ラッパーとPowerShellが見つからない場合のEngramテストが合格する

---

Conventional Commits（GitHubルールセットで強制）

コミットメッセージはGitHubルールセットによって検証されます。パターンに一致しないコミットは拒否されます。

パターン： ^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+

形式：

<type>(<optional-scope>): <description>
<type>(<optional-scope>)!: <description>   ← breaking change

許可されるタイプ

タイプ	用途	PRラベル
feat	新機能	type:feature
fix	バグ修正	type:bug
docs	ドキュメントのみ	type:docs
refactor	コードのリファクタリング	type:refactor
chore	メンテナンス、依存関係	type:chore
style	書式、空白	type:chore
perf	パフォーマンスの改善	type:refactor
test	テストの追加・修正	type:chore
build	ビルドシステムの変更	type:chore
ci	CI/CDの変更	type:chore
revert	以前のコミットの取り消し	(元のタイプに合わせる)
feat! / fix!	破壊的変更	type:breaking-change

ルール

• タイプは、記載されている値のいずれかでなければなりません
• スコープは省略可能で、小文字を使用し、a-z、0-9、.、_、-を使用できます
• :の前にある!は、破壊的変更を示します
• 説明は : （コロンとスペース）の後に始めなければなりません

例

feat(cli): add --json flag to session list command
fix(store): prevent duplicate observation insert on retry
docs(contributing): update workflow documentation
refactor(internal): extract search query sanitizer
chore(deps): bump github.com/charmbracelet/bubbletea to v0.26
style(tui): fix alignment in session detail view
perf(store): optimize FTS5 query for large datasets
test(sync): add coverage for conflict resolution
ci(workflows): split e2e into separate job
fix!: change session ID format

無効な例（拒否されます）

Fix bug                          ← no type prefix
feat: Add login                  ← description should be lowercase
FEAT(cli): add flag              ← type must be lowercase
feat (cli): add flag             ← no space before scope
feat(CLI): add flag              ← scope must be lowercase
update docs                      ← no conventional commit format

---

コマンド

# Create branch
git checkout -b feat/my-feature main

# For behavior changes, run actual focused regression and affected package commands:
# go test ./internal/store -run '<actual regression test name>'
# go test ./internal/store
# Record actual commands and outcomes in the PR test plan.
# For docs-only changes, record N/A for Go tests and the documentation checks run.
# Without a PR or for high-risk changes, run additional applicable local checks.
# After pushing, GitHub CI runs broad unit/E2E/lint and applicable platform checks;
# do not claim their results until the checks actually pass.

# Push and create PR
git push -u origin feat/my-feature
gh pr create --title "feat(scope): description" --body "Closes #N"

# Add type label to PR
gh pr edit <pr-number> --add-label "type:feature"