engram-branch-pr

适用场景

在以下情况下使用此技能：

• 为任何变更创建拉取请求
• 准备提交分支
• 帮助贡献者创建 PR

---

关键规则

1. 每个 PR 都必须关联一个已获批准的问题——没有例外
2. 每个 PR 都必须且只能有一个 type:* 标签
3. 所有必需的自动化检查都必须通过，才能合并
4. 没有关联问题的空白 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
Bug 修复	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. 关联的问题（必填）

Closes #<issue-number>

有效关键词：Closes #N、Fixes #N、Resolves #N（不区分大小写）。 关联的问题必须带有 status:approved 标签。

2. PR 类型（必填）

在模板中勾选且只能勾选一项，并添加对应标签：

复选框	要添加的标签
Bug 修复	type:bug
新功能	type:feature
仅文档	type:docs
代码重构	type:refactor
维护/工具	type:chore
破坏性变更	type:breaking-change

3. 摘要

用 1-3 个项目符号说明 PR 的内容。

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. 贡献者检查清单

所有项目都必须勾选：

• 已关联一个获批准的问题
• 已添加且只添加了一个 type:* 标签
• 对于行为变更，已记录实际执行的针对性回归测试和受影响软件包的测试命令/结果；仅涉及文档的变更则填写 N/A
• 没有 PR 或涉及高风险变更时，已运行其他适用的本地检查；已指出缺失的 CI 证据
• 行为有变更时，已更新文档
• 符合 Conventional Commits 格式
• 不含 Co-Authored-By 尾注
• 每个变更路径都符合临时产物政策

---

自动化检查

六个必需的检查上下文列在 CONTRIBUTING.md 中；合并前必须全部通过。Lint、临时制品检查、Windows Setup Test 和 Cloud Sync Wrapper Tests (Windows) 会在 PR 中运行，但不会在合并队列中运行，也不属于六个必需的检查上下文。请报告这些检查的实际结果，不要将待处理的检查视为已通过。

检查	Job 名称	验证内容
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:* 标签
临时制品检查	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	修复 Bug	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"