jackyu66gitandCursor
ad45d17dff
将编号与 schema 完整性留在 Repository Governance，不扩 ESS/Loop；TRACEABILITY 锚定 Next ECR=041、Max Migration=000050。 Co-authored-by: Cursor <cursoragent@cursor.com>
95 lines
4.8 KiB
Markdown
95 lines
4.8 KiB
Markdown
# Project Rules — 愈心谷
|
||
|
||
Inherits: `$ESS_ROOT/product-governance/PROJECT_RULES.md`（流程）
|
||
Product/DoD 权威：`.ai/`（不在此复制长文）
|
||
|
||
## ESS Intake（本仓覆盖）
|
||
|
||
```yaml
|
||
ess_intake: strict
|
||
```
|
||
|
||
- **权威入口：** `$ESS_ROOT/governance/SESSION_BOOTSTRAP.md`（G0 Mode 块）
|
||
- **Solo multi-role：** `$ESS_ROOT/governance/AGENT_OPERATIONS.md`
|
||
- **Execution Context：** 同时只绑定 **一个** Active ECR（或一个 L1 TASK）；新主题 = OUT OF SCOPE，禁止顺手改码
|
||
- **retro-ecr：** 本仓 **FAIL**（须 `Retrospective: true` + Original drift + Scope freeze + Process debt；不得伪装正序路径）。通用 ESS 默认为 WARN；脚本强制见后续门禁 PR，**规则即时约束 Agent**
|
||
- **Loop / Adapter：** 不在本仓维护；已授权执行不扩展 ESS Intake 职责
|
||
- **ESS 0.2.0-intake / Loop / Adapter：** 本仓视为 **FROZEN**；仓库治理问题不塞进 ESS 内核或 Loop
|
||
|
||
## Repository governance（仓侧 · 非 Loop）
|
||
|
||
独立于 ESS Loop。Merge / 开 ECR / 写 migration 前执行：
|
||
|
||
```bash
|
||
python scripts/repo-governance-check.py
|
||
python scripts/repo-governance-check.py --print-anchors
|
||
```
|
||
|
||
权威锚点：`docs/TRACEABILITY.md` 顶部 **Next ECR** · **Max Migration**。
|
||
|
||
### ECR identity（硬规则）
|
||
|
||
- **`ECR-NNN`（及带字母/后缀的完整 identity）在仓库历史内全局唯一。**
|
||
即使已 Closed，也**禁止**把同一编号重新解释成另一件事。
|
||
- **禁止同号双义**（例如两个文件都自称 `# ECR-012`）。
|
||
- 分叉只允许：**`ECR-012-star`** · **`ECR-013A`** · **`ECR-013B`** 等形式；不得再开第二个裸 `ECR-012`。
|
||
- **预占：** 开新 ECR 前读 TRACEABILITY **Next ECR**；占用后立即更新该锚点（或跑 `--print-anchors` 核对后写回）。
|
||
- **Canonical-ID：** 仅作历史分叉过渡字段；长期以唯一 H1 / identity 为准，不发展成并行别名体系。
|
||
- Agent **Single ECR Context** 绑定的必须是上述唯一 identity（查 TRACEABILITY，勿猜）。
|
||
|
||
### Migration stem（硬规则）
|
||
|
||
- `apps/api/migrations/` 下 **6 位版本号唯一**（禁止 `000015_foo` 与 `000015_bar` 并存）。
|
||
- **禁止**凭记忆递增。Create 流程：
|
||
|
||
```text
|
||
Read repo state → Max Migration (TRACEABILITY / --print-anchors)
|
||
→ allocate next stem → write file → repo-governance-check PASS
|
||
```
|
||
|
||
- 并行 branch + merge 是已知攻击面；合入含 migration 的变更必须过 uniqueness 检查。
|
||
- 已发生撞号的修复说明：`docs/MIGRATION_RENUMBER.md`（playbook 保留，本阶段不扩展）。
|
||
|
||
### L0 / L1 UI（轻规则 · 不过度治理）
|
||
|
||
无 API / DB / Domain 新概念 / 权限 / 新业务状态、且不改既定 Acceptance → 可 L0/L1，**不必**为大 ECR。
|
||
若改变**用户可见主路径**语义 → 对照相关 Active Feature Spec 做 consistency check（不必因此自动升 L2）。
|
||
|
||
## Domain invariants
|
||
|
||
1. 语言契约：只用 `.ai/product/lexicon.md` 中的愈心谷用词；禁止竞品品牌词与恐吓/吉凶话术。
|
||
2. API 信封固定为 `{code,message,data}`；不发明表名、端点、领域同义词。
|
||
3. 调用链：UI → `@yuxingu/sdk` → Handler → Service → Repository → DB。
|
||
4. 新功能 / 扩行为：必须有 Active `.ai/product/feature-spec/<id>.md`；L2+ 另须 Approved `docs/ECR/`；**涉后台**另须 Approved `docs/BACKEND_DESIGN/`。
|
||
5. 本地默认：本机 `go run` + Vite；compose 只起 DB。
|
||
6. Done ≠ build 通过：须过 `.ai/definition-of-done.md` 并输出 Review Report。
|
||
|
||
## Change levels（映射）
|
||
|
||
| ESS | 本仓要求 |
|
||
|-----|----------|
|
||
| L0 | 文档/注释/无行为；可无 ECR |
|
||
| L1 | 明确 bugfix；可无新 Feature Spec，但不得扩行为 |
|
||
| L2 | 功能行为变更 → Feature Spec Active + ECR Approved + HANDOFF |
|
||
| L2-BLOCKED | 无 Approved ECR 时禁止改 `apps/` / `packages/` / `proto/` / `migrations/` |
|
||
| L3 | 栈/包边界/架构 → ADR（`.ai/adr/`）+ ECR + ENGINEERING_SPEC |
|
||
|
||
## Forbidden（extra）
|
||
|
||
- 猜需求继续写（ASK FIRST）
|
||
- Architect 角色改 `apps/` / `packages/` 生产实现
|
||
- 无 Human 批准把实验当 Live 行为推广
|
||
- 提交 `config.local.yaml`、`.env`、密钥
|
||
- 同一 review turn Approve + Modify
|
||
- 在已绑定 ECR 的 Execution Context 内「顺便」做第二功能
|
||
- 同号双义 ECR；凭记忆分配 migration 版本号
|
||
- Retro 批量追认已 merge 行为；把仓库治理机制扩进 ESS Loop
|
||
|
||
## Completion
|
||
|
||
1. 开场 ESS Mode 块（G0）通过且 `Action: CONTINUE`（或明确 L0）
|
||
2. 仓侧（改 ECR / migration / merge 前）：`python scripts/repo-governance-check.py` PASS
|
||
3. ESS gate（有 ECR 时）：`python scripts/ess-validate.py --phase <phase> --ecr ECR-xxx`
|
||
4. 本仓 DoD：`.ai/definition-of-done.md` + `.ai/review.md`
|
||
5. 有行为变更时更新/尊重 `.ai/product/p1-status.md` 标签
|