# Pulse Engine 目录规范

> `~/.upulse/engine/` — Pulse 的"用户态"代码空间，独立 git 仓库。

## 架构

```
~/.upulse/engine/           # 独立 git repo
├── package.json            # @upulse/engine, 依赖 @uncaged/pulse
├── tsconfig.json
├── templates/              # Scaffold 模板（meta coder 参考）
│   ├── workflow.ts.tmpl
│   └── workflow.test.ts.tmpl
├── src/
│   └── workflows/
│       ├── ping-pong.ts        # 示例 workflow
│       ├── ping-pong.test.ts
│       ├── werewolf.ts         # 业务 workflow
│       ├── werewolf.test.ts
│       └── roles/
│           ├── meta-gate.ts        # Gate: 准入检查（无 LLM）
│           ├── meta-gate.test.ts
│           ├── meta-coder-cursor.ts  # Coder: Cursor Agent 写代码
│           ├── meta-checker.ts       # Checker: 验证 scope + build + unit test
│           ├── meta-tester.ts        # Tester: E2E lifecycle 验证
│           └── meta-promoter.ts      # Promoter: commit + push + code_rev
└── docs/
```

## 核心概念

### Engine vs 核心包

| | Engine (`~/.upulse/engine/`) | 核心包 (`packages/pulse/`) |
|---|---|---|
| 谁改 | Meta workflow（agent 自主改） | 人工 / subagent |
| 内容 | 业务 workflow + meta roles | 框架代码 |
| 版本控制 | engine repo git hash = `code_rev` | pulse repo |
| 部署 | promote event → daemon 热加载 | npm publish |

### code_rev

Engine repo 的 **git commit hash** 就是 `code_rev`。

- 每次 promoter commit 后，commit hash 成为新的 `code_rev`
- Guard state 按 `code_rev` 隔离（同一 guard + 同一 key，不同版本有独立 state）
- 回滚 = 切回旧 `code_rev`，旧 state 还在

### Meta Workflow 流程

```
START → gate → coder → checker → tester → promoter → END
                ↑          |          |
                └── fail ──┘── fail ──┘
```

| Role | 职责 | LLM |
|------|------|-----|
| **gate** | 准入检查：任务描述够不够详细、是否在 engine scope | ❌ |
| **coder** | 用 Cursor Agent 写代码，参考 templates/ | ✅ Agent |
| **checker** | 验证文件 scope + `bun run build` + `bun test` | ❌ |
| **tester** | E2E lifecycle 验证：import → temp store → tick → quiescence | ❌ |
| **promoter** | `git commit` + `git push` + 输出 `codeRev` | ❌ |

### Daemon 加载机制

1. Daemon 启动时 `tryLoadFromEngine`，优先加载 engine 目录下的 workflow/role
2. Engine 文件 import 用 `@uncaged/pulse`（npm link 到核心包）
3. Promote event 触发 daemon 重新加载

## 开发新 Workflow

1. 参考 `templates/workflow.ts.tmpl` 创建 `src/workflows/{name}.ts`
2. 参考 `templates/workflow.test.ts.tmpl` 创建配套测试
3. `bun test` 确认通过
4. Git commit + push

或者通过 meta workflow 自动生成：向 daemon 提交任务 → gate → coder → checker → tester → promoter → 自动完成。

## 约束

- Workflow 文件只放 `src/workflows/` 下
- Meta role 文件只放 `src/workflows/roles/` 下
- Import 用 `@uncaged/pulse`，不用相对路径到核心包
- Commit author: `小橘 <xiaoju@shazhou.work>`