Agent Memento v0.2 — Complete Skill Specification

---
name: agent-memento
description: Tick-Driven Autonomous Production Factory for LLMs. A framework for long-running agents using Cron/Heartbeats and physical Markdown checklists to prevent OOM and context decay.
metadata: {"clawdbot":{"emoji":"🧠","requires":{"bins":["bash","openclaw"],"env":[]}}}
---

# Agent Memento v0.2 (Tick-Driven Autonomous Execution)

> "Don't build AI that tries to remember everything. Build systems that make AI read the blueprint anew every 5 minutes."

当我们在聊天框里让大模型"写一个游戏"时，开头总是美好的。但随着代码超过 2000 行，模型开始：
- **失忆症 (Amnesia)**：忘记了自己定义的接口，开始凭空捏造。
- **幻觉重构 (Hallucination)**：自信满满地输出一堆根本没有跑过的"完美"代码。
- **上下文核爆 (Resource Overload)**：为了修一个小 Bug，强行覆盖整个大文件，导致内存耗尽 (OOM)。

**核心原则：把"全知全能的超级 Agent"降级为无数个"只有 5 分钟记忆的、无情的 Tick 机器"。**

---


## Quick Start (30 秒上手)

1. 初始化项目：
   ```bash
   bash skills/agent-memento/scripts/init_memento.sh MyProject

在主对话中让 Architect 填写 MASTER_PLAN.md 和 PROJECT_MAP.md

启动自动执行：

crontab -e
# 添加：*/5 * * * * /path/to/MyProject/scripts/memento_tick.sh

（可选）启动 Dashboard 看板监控：
```
bash scripts/dashboard.sh
```
去刷手机。回来看 Dashboard 或 docs/TICK_STATUS.md 查看进度。

一、系统架构总览

┌─────────────────────────────────────────────────────────┐
│                    Human (You)                          │
│         Discord / 飞书 / Dashboard Panel                │
└──────────────┬──────────────────────────┬───────────────┘
               │ 自然语言交互              │ 面板批注/干预
               ▼                          ▼
┌─────────────────────────────────────────────────────────┐
│              Main Agent (Architect)                      │
│         LLM 本体 · 长对话 Session                        │
│                                                         │
│  职责：                                                  │
│  - 与人类讨论需求，翻译为结构化任务                         │
│  - 编辑 MASTER_PLAN.md（增/删/改/重排任务）                │
│  - 编辑 PROJECT_MAP.md（维护项目认知地图）                  │
│  - 读取 TICK_STATUS.md 和 Dashboard 批注                  │
│  - 根据反馈调整计划（自主决策 or 请示人类）                  │
└──────────────┬──────────────────────────────────────────┘
               │ 写入物理文件
               ▼
┌─────────────────────────────────────────────────────────┐
│              Physical State Layer (磁盘)                 │
│                                                         │
│  docs/MASTER_PLAN.md    ← 唯一真相源，结构化任务清单       │
│  docs/PROJECT_MAP.md    ← 项目认知地图 / 文件索引          │
│  docs/TICK_STATUS.md    ← Tick 执行状态流水账              │
│  docs/HUMAN_NOTES.md    ← 人类批注通道（面板写入）          │
│  logs/tick_*.log        ← 每个 Tick 的完整执行日志         │
└──────────────┬──────────────────────────────────────────┘
               │ 读取（每次从零开始）
               ▼
┌─────────────────────────────────────────────────────────┐
│           Tick Worker (Bricklayer)                       │
│      Cron 唤醒 · 短命进程 · 无状态 · 无情                 │
│                                                         │
│  生命周期：                                               │
│  1. 醒来 → 读 MASTER_PLAN.md                             │
│  2. 找到当前可执行任务                                     │
│  3. 读 PROJECT_MAP.md 确定上下文范围                       │
│  4. 读 HUMAN_NOTES.md 检查人类批注                        │
│  5. 执行任务 → 物理验证                                    │
│  6. 写结果到 TICK_STATUS.md                               │
│  7. 成功则标 [x]，失败则记录 → 死亡                        │
│  8. 自动 git commit                                      │
└─────────────────────────────────────────────────────────┘

二、The Methodology：三层智能分工

Layer 1：人类（方向盘）

在 Discord/飞书/Dashboard 中用自然语言描述需求和反馈
通过 Dashboard 面板随时插入批注、暂停/恢复流水线
不需要逐条审核——只在 Agent 请求帮助或自己想介入时参与

Layer 2：Architect（主 Agent / 翻译官）

与人类的主对话 Session
将模糊需求翻译为 MASTER_PLAN.md 中的结构化任务
持续维护 PROJECT_MAP.md（项目认知地图）
监控 TICK_STATUS.md，根据执行情况自主调整计划
遇到阻塞性决策时才请示人类

Layer 3：Tick Worker（子 Agent / 泥瓦匠）

Cron 唤醒的短命进程，每次从零启动
绝对服从 MASTER_PLAN.md，不做创造性决策
执行 → 验证 → 汇报 → 死亡

三、物理状态文件规范

3.1 MASTER_PLAN.md — 唯一真相源

# MASTER_PLAN: <ProjectName>

## Meta
- created: 2025-01-15
- last_architect_edit: 2025-01-15T14:30:00
- tick_mode: auto          <!-- auto | paused | stopped -->
- max_retries: 3           <!-- 单任务最大重试次数 -->
- max_tasks_per_tick: 2    <!-- 快任务时允许单 Tick 连续处理上限 -->
- max_diff_lines: 200      <!-- diff size guard 阈值 -->
- stale_lock_timeout: 15min <!-- [~] 僵尸锁重置阈值 -->
- circuit_breaker_threshold: 5 <!-- 连续失败多少次触发熔断 -->
- clean_strategy: git-clean <!-- 三阶段防爆清理机制 -->
- clean_ignore: .memento_cleanignore
- status_max_entries: 50    <!-- TICK_STATUS.md 最大条目数，超出自动归档 -->
- status_archive_dir: logs/status_archive/
- total_ticks: 0           <!-- 自动递增的 Tick 计数器 -->
- total_tasks: 15          <!-- 自动维护 -->
- completed_tasks: 0       <!-- 自动维护 -->

---

## Phase 1: Foundation
<!-- parallel: true -->
<!-- depends: none -->

- [ ] `T-101` [MODULE:database] Setup PostgreSQL schema
  - verify: `cd src && npm test -- --grep "db-schema" && echo PASS`
  - context_files: [src/db/schema.ts, src/db/migrations/]
  - guard_files: [src/auth/*]
  - estimate: 5min
  - retries: 0

- [ ] `T-102` [MODULE:auth] Implement JWT token generation
  - verify: `cd src && npm test -- --grep "jwt" && echo PASS`
  - context_files: [src/auth/jwt.ts, tests/auth/jwt.test.ts]
  - guard_files: [src/db/*]
  - estimate: 5min
  - retries: 0

## Phase 2: Integration
<!-- parallel: false -->
<!-- depends: Phase 1 -->

- [ ] `T-201` [MODULE:auth] Connect auth middleware to database
  - verify: `cd src && npm run test:integration && echo PASS`
  - context_files: [src/auth/middleware.ts, src/db/queries.ts]
  - guard_files: [src/db/schema.ts]
  - estimate: 10min
  - retries: 0

## Phase 3: Polish
<!-- parallel: true -->
<!-- depends: Phase 2 -->

- [ ] `T-301` [MODULE:docs] Generate API documentation
  - verify: `test -f docs/api.md && echo PASS`
  - context_files: [src/routes/*.ts]
  - guard_files: []
  - estimate: 3min
  - retries: 0

任务字段说明：

字段	必须	说明
`T-XXX`	✅	任务唯一 ID，用于日志追踪和跨文件引用
`[MODULE:xxx]`	✅	模块标签，帮助 Worker 理解领域边界
`verify`	✅	验收命令，Exit Code 0 = 通过。没有这个字段，任务不合法
`context_files`	✅	Worker 允许加载的文件白名单，防止上下文爆炸
`guard_files`	推荐	禁止修改的文件列表，硬约束
`estimate`	推荐	预估耗时，用于 Tick 调度决策
`retries`	自动	由 Tick Worker 自动递增，Architect 可重置

任务状态标记：

标记	含义
`[ ]`	待执行
`[x]`	已完成（verify 通过）
`[!]`	已阻塞（超过 max_retries）
`[~]`	执行中（Tick Worker 正在处理，防止并发冲突）
`[-]`	已跳过（Architect 主动标记为不需要）

Phase 级元数据：

字段	说明
`parallel: true/false`	该 Phase 内的任务是否可并发执行
`depends: Phase X` / `none`	Phase 级前置依赖

3.2 PROJECT_MAP.md — 项目认知地图

Worker 的 GPS。不读全部源码，先读地图，再按 context_files 精准加载。

# PROJECT MAP: <ProjectName>

## Architecture Overview
Single-page game using Canvas API. No framework. Vanilla TypeScript.

## Module Registry

### [MODULE:database]
- Purpose: PostgreSQL connection and schema management
- Entry: src/db/index.ts
- Key interfaces: `DbConnection`, `UserRecord`, `SessionRecord`
- Notes: Uses connection pooling via pg-pool

### [MODULE:auth]
- Purpose: JWT-based authentication
- Entry: src/auth/index.ts
- Key interfaces: `AuthToken`, `AuthMiddleware`
- Dependencies: [MODULE:database]
- Notes: Tokens expire in 24h, refresh flow not yet implemented

### [MODULE:routes]
- Purpose: Express route handlers
- Entry: src/routes/index.ts
- Dependencies: [MODULE:auth], [MODULE:database]

## File Tree (auto-maintained)
<!-- Architect 应在项目结构变动时更新此区块 -->

src/
├── db/
│   ├── index.ts          # DB connection pool
│   ├── schema.ts         # Table definitions
│   └── migrations/       # SQL migration files
├── auth/
│   ├── index.ts          # Auth module entry
│   ├── jwt.ts            # Token generation/validation
│   └── middleware.ts      # Express middleware
└── routes/
    ├── index.ts          # Route registry
    └── users.ts          # User CRUD endpoints

## Conventions
- All tests in `tests/` mirror `src/` structure
- Config via environment variables (see .env.example)
- Error handling: all async handlers wrapped in try/catch, errors go to src/utils/errors.ts

维护规则：

Architect 在创建/调整计划时同步更新
Tick Worker 只读不写 PROJECT_MAP.md
如果 Worker 发现 MAP 与实际不符，在 TICK_STATUS.md 中报告，由 Architect 修正

3.3 TICK_STATUS.md — 执行状态流水账

# TICK STATUS LOG

---

## [2025-01-15T14:35:00] Tick #012
- **Task**: T-101 [MODULE:database] Setup PostgreSQL schema
- **Status**: ✅ SUCCESS
- **Verify Output**: `PASS` (exit code 0)
- **Duration**: 2m18s
- **Files Modified**: src/db/schema.ts (+45 -0), src/db/migrations/001_init.sql (+23 -0)
- **Diff Size**: 68 lines
- **Git Commit**: `a3f7b2c` — "memento: complete T-101 database schema setup"

---

## [2025-01-15T14:35:00] Tick #012 (continued, tasks_this_tick: 2/2)
- **Task**: T-102 [MODULE:auth] Implement JWT token generation
- **Status**: ✅ SUCCESS
- **Verify Output**: `PASS` (exit code 0)
- **Duration**: 3m41s
- **Files Modified**: src/auth/jwt.ts (+67 -0), tests/auth/jwt.test.ts (+34 -0)
- **Diff Size**: 101 lines
- **Git Commit**: `b8e2d1f` — "memento: complete T-102 JWT token generation"

---

## [2025-01-15T14:40:00] Tick #013
- **Task**: T-201 [MODULE:auth] Connect auth middleware to database
- **Status**: ❌ FAILED (retry 2/3)
- **Verify Output**: `TypeError: pool.query is not a function` (exit code 1)
- **Duration**: 4m52s
- **Error Analysis**: DB module exports `pool` but middleware imports `connection`. Interface mismatch.
- **Files Modified**: (rolled back)
- **Git Commit**: (none — rollback)

---

## [2025-01-15T14:45:00] Tick #014
- **Task**: T-201 [MODULE:auth] Connect auth middleware to database
- **Status**: 🚫 BLOCKED (retry 3/3 — max_retries exceeded)
- **Verify Output**: Same error as Tick #013
- **Error Analysis**: Recurring interface mismatch. Likely needs Architect to update MODULE:database exports or redefine task scope.
- **Escalation**: ⚠️ NEEDS ARCHITECT ATTENTION
- **Files Modified**: (rolled back)

---

3.4 HUMAN_NOTES.md — 人类批注通道

Dashboard 面板写入此文件。Tick Worker 每次启动时检查。Architect 也会读取。

# HUMAN NOTES

<!-- 格式：每条批注带时间戳和目标（global / 具体 Task ID） -->
<!-- Worker 执行完相关批注后，将 [NOTE] 改为 [NOTE:READ] -->
<!-- Architect 处理完后可归档到底部的 Archive 区 -->

## Active Notes

### [NOTE] 2025-01-15T15:00:00 → T-201
改用 Redis 做 session 存储而不是 PostgreSQL。连接配置参考项目根目录的 redis.conf。

### [NOTE] 2025-01-15T15:10:00 → global
暂停 Phase 3 的所有任务，等 Phase 2 全部稳定再说。

### [NOTE:READ] 2025-01-15T14:00:00 → T-102
JWT secret 从环境变量 `JWT_SECRET` 读取，别硬编码。

---

## Archive
<!-- Architect 把已处理的批注移到这里 -->

四、Tick 调度引擎规范

4.1 任务拾取算法

Tick Worker 醒来后执行以下逻辑：

1. 读取 MASTER_PLAN.md 的 Meta 区
   - 如果 tick_mode != "auto"，写一行 "Tick skipped: mode={mode}" 到 TICK_STATUS.md，退出

2. 读取 HUMAN_NOTES.md
   - 缓存所有 [NOTE]（非 [NOTE:READ]）条目，按 target 分组备用

3. 按 Phase 顺序扫描：
   FOR each Phase:
     a. 检查 depends 条件
        - 依赖的 Phase 内是否所有任务都是 [x] 或 [-]？
        - 如果有 [ ] 或 [~] 或 [!]，则该 Phase 不可进入，跳过
     
     b. 在当前 Phase 内扫描任务：
        - 跳过 [x] [!] [-] [~]
        - 对于 [ ]：检查 retries < max_retries
        - 如果 parallel: false，只取第一个符合条件的 [ ]
        - 如果 parallel: true，取第一个符合条件的 [ ]（单 Worker 场景）
        
     c. 找到目标任务后，break

4. 如果没有找到任何可执行任务：
   - 检查是否所有任务都是 [x] 或 [-] → 写 "🎉 ALL TASKS COMPLETE" 到 TICK_STATUS.md
   - 检查是否存在 [!] 阻塞 → 写 "⚠️ PIPELINE BLOCKED" 到 TICK_STATUS.md
   - 退出

5. 将目标任务标记为 [~]（执行中）

6. 执行任务（详见 4.2）

7. tasks_completed_this_tick++
   如果 tasks_completed_this_tick < max_tasks_per_tick 且剩余任务 estimate 合理：
     回到步骤 3 继续拾取
   否则退出

4.2 单任务执行流程

1. 读取任务的 context_files 列表
   - 通过 PROJECT_MAP.md 理解模块上下文
   - 加载 context_files 中声明的文件内容
   - 检查是否有针对该 Task ID 的 HUMAN_NOTES，如有，纳入上下文

2. 执行实际工作
   - 遵循铁血纪律（见第五节）
   - 生成精确 diff，不做全文件覆写

3. 运行 guard_files 检查
   - diff 中是否触及了 guard_files 列表中的文件？
   - 如果是 → 自动回滚 → 标记失败 → 原因写 "guard file violation"

4. 运行 diff size 检查
   - 单次修改是否超过 200 行？（可配置）
   - 如果是 → 自动回滚 → 标记失败 → 原因写 "diff too large, possible full-file rewrite"

5. 运行 verify 命令
   - 捕获 stdout/stderr 和 exit code
   - Exit Code 0 → SUCCESS
   - Exit Code != 0 → FAILED

6. 写结果到 TICK_STATUS.md

7. 如果 SUCCESS：
   - 任务标记 [ ] → [x]
   - retries 保持不变
   - git add + git commit（message 格式：`memento: complete {TASK_ID} {简述}`）

8. 如果 FAILED：
   - 回滚所有文件修改（git checkout 或备份恢复）
   - retries += 1
   - 任务保持 [ ]，清除 [~]
   - 如果 retries >= max_retries：
     - 标记 [!]
     - TICK_STATUS 中添加 "⚠️ NEEDS ARCHITECT ATTENTION"

4.3 并发安全

当 parallel Phase 中可能有多个 Worker 并行时（高级场景）：

[~] 标记充当简易锁 —— Worker 拾取任务时先标 [~]，其他 Worker 看到 [~] 就跳过
如果检测到 [~] 标记超过 15 分钟未更新（Worker 可能崩溃），将其重置为 [ ]
在 MVP 阶段，建议单 Worker 串行执行，并发作为未来扩展

五、铁血纪律 (Execution Sandbox)

作为一个被 Memento 唤醒的 Tick Worker，你必须遵循：

纪律 1：防爆底线 (Surgical Edits Only)

❌ 严禁输出完整文件内容要求覆写
✅ 必须通过精准定位工具进行增量修改
硬约束：diff size guard 会物理阻断超大修改

纪律 2：拒绝脑内验算 (Evidence-Based Audit)

❌ 不许在脑中模拟运行然后宣称"应该没问题"
✅ 跑 verify 命令看真实退出码
没有 Exit Code 0，不许标 [x]

纪律 3：不要静默空转 (No Silent Ghosting)

❌ 遇到问题不许沉默退出
✅ 把死亡原因、错误日志、分析完整写入 TICK_STATUS.md
卡死了就大声喊出来，让 Architect 看到

纪律 4：恪守边界 (Stay in Your Lane)

❌ 不许修改 guard_files 中的文件
❌ 不许修改 MASTER_PLAN.md 的任务定义（只能改 checkbox 状态和 retries）
❌ 不许修改 PROJECT_MAP.md
✅ 只能读写 context_files 中声明的文件 + TICK_STATUS.md

纪律 5：原子提交 (Atomic Commits)

每完成一个任务，立即 git commit
每失败一个任务，立即 git checkout 回滚
确保任意时刻 git log 都是干净的、可追溯的

六、Dashboard 面板设计

6.1 设计理念

Dashboard 是人类与 Memento 流水线之间的异步交互界面。不是实时聊天，而是留言板 + 监控台。人类不需要一直盯着，但打开就能在 5 秒内知道一切。

6.2 面板布局

┌─────────────────────────────────────────────────────────────┐
│  🧠 Agent Memento Dashboard        [ProjectName]           │
│  Status: ● RUNNING    Uptime: 2h 35m    Next tick: 2m 14s  │
│  ┌──────────────────┐ ┌──────────────────────────────────┐  │
│  │ Controls         │ │ Progress                         │  │
│  │                  │ │                                  │  │
│  │ [▶ Resume]       │ │ ████████████░░░░░░░░░ 23/47     │  │
│  │ [⏸ Pause ]       │ │ Phase 1 ████████████ 100%       │  │
│  │ [⏹ Stop  ]       │ │ Phase 2 ████████░░░░  67%       │  │
│  │                  │ │ Phase 3 ░░░░░░░░░░░░   0%       │  │
│  │ Tick interval:   │ │                                  │  │
│  │ [5] min ▼        │ │ Blocked: 2 ⚠️                    │  │
│  │                  │ │ Est. remaining: ~1h 20m          │  │
│  └──────────────────┘ └──────────────────────────────────┘  │
│                                                             │
│  ┌──────────────────────────────────────────────────────────┤
│  │ Task List                                    Filter: All │
│  │                                                          │
│  │  ✅ T-101 [database] Setup PostgreSQL schema    2m18s    │
│  │  ✅ T-102 [auth] JWT token generation           3m41s    │
│  │  🚫 T-201 [auth] Connect auth to DB            BLOCKED   │
│  │     └─ retries: 3/3 · "Interface mismatch"              │
│  │     └─ 💬 [Add Note]                                    │
│  │  ⬜ T-202 [auth] Password hashing              waiting   │
│  │  ⬜ T-301 [docs] Generate API docs             Phase 3   │
│  │                                                          │
│  └──────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────────────────────────────────────────────────┤
│  │ Tick Timeline                              Latest first  │
│  │                                                          │
│  │  14:45 Tick #014 · T-201 · 🚫 BLOCKED                  │
│  │  │  "Interface mismatch — needs Architect attention"     │
│  │  │  [View Full Log]                                      │
│  │  │                                                       │
│  │  14:40 Tick #013 · T-201 · ❌ FAILED (retry 2/3)        │
│  │  │  "TypeError: pool.query is not a function"            │
│  │  │  [View Full Log]                                      │
│  │  │                                                       │
│  │  14:35 Tick #012 · T-101 + T-102 · ✅✅                  │
│  │  │  2 tasks completed in 5m59s                           │
│  │  │  [View Full Log] [View Diff]                          │
│  │                                                          │
│  └──────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────────────────────────────────────────────────┤
│  │ 📝 Notes                                                │
│  │                                                          │
│  │  ┌─────────────────────────────────────────────────────┐ │
│  │  │ Target: [T-201 ▼]  or  [global ▼]                  │ │
│  │  │                                                     │ │
│  │  │ 改用 Redis 做 session 存储，连接配置见 redis.conf    │ │
│  │  │                                                     │ │
│  │  │                              [Send Note 📤]         │ │
│  │  └─────────────────────────────────────────────────────┘ │
│  │                                                          │
│  │  Active Notes:                                           │
│  │  • 15:10 → global: "暂停 Phase 3..." ⏳ pending         │
│  │  • 15:00 → T-201: "改用 Redis..." ⏳ pending            │
│  │  • 14:00 → T-102: "JWT_SECRET 环境变量..." ✅ read      │
│  │                                                          │
│  └──────────────────────────────────────────────────────────┘
└─────────────────────────────────────────────────────────────┘

6.3 面板功能规范

控制区 (Controls)

操作	行为
Resume	将 `MASTER_PLAN.md` 的 `tick_mode` 改为 `auto`
Pause	将 `tick_mode` 改为 `paused`（当前 Tick 执行完后停止）
Stop	将 `tick_mode` 改为 `stopped`（建议同时移除 crontab）
Tick interval	修改 crontab 的执行频率

进度区 (Progress)

数据源：解析 MASTER_PLAN.md 的所有 checkbox 状态
实时计算各 Phase 完成百分比
基于已完成任务的平均耗时 × 剩余任务数，估算剩余时间

任务列表 (Task List)

数据源：MASTER_PLAN.md
每个任务可展开查看：最近一次执行结果、错误信息、重试次数
支持过滤：All / Pending / Completed / Blocked
每个任务旁有 [Add Note] 按钮，快速针对该任务添加批注
支持手动操作：
- 对 [!] 任务点击 [Reset Retries] → 将 retries 重置为 0，状态改回 [ ]
- 对任务点击 [Skip] → 标记为 [-]

时间线 (Tick Timeline)

数据源：TICK_STATUS.md
倒序展示每个 Tick 的执行摘要
可展开查看完整日志（链接到 logs/tick_*.log）
可查看该 Tick 的 Git diff

批注区 (Notes)

写入目标：HUMAN_NOTES.md
支持选择 target（global 或具体 Task ID）
显示所有 Active Notes 及其状态（pending / read）
Read 后的 notes 自动折叠但不删除

6.4 面板技术建议

轻量优先：纯静态页面 + 文件系统轮询（每 5~10s 读取 Markdown 文件）即可
数据层：直接 parse Markdown 文件，不需要数据库
可选方案 A：本地 HTTP server（Python/Node），serve 一个 SPA，通过 API 读写 Markdown 文件
可选方案 B：Terminal UI（blessed/ink），不离开终端

七、错误恢复与自愈机制

7.1 单任务失败 → 自动重试

失败 → retries++ → 保持 [ ] → 下个 Tick 重试
              ↓
       retries >= max_retries
              ↓
       标记 [!] → 写入 TICK_STATUS "NEEDS ARCHITECT ATTENTION"
              ↓
       跳过该任务，继续执行后续可执行任务

7.2 Phase 阻塞 → 智能跳转

Phase 2 中 T-201 被标记 [!]
              ↓
Phase 2 depends 未完全满足（存在非 [x]/[-] 的任务）
              ↓
Phase 3 无法启动
              ↓
如果 Phase 2 中还有其他 [ ] 任务 → 继续执行它们
如果 Phase 2 所有任务都是 [x]/[-]/[!] → 整条流水线 BLOCKED
              ↓
TICK_STATUS: "⚠️ PIPELINE BLOCKED — Phase 2 has unresolved [!] tasks"

7.3 Worker 崩溃 → 防腐检测

如果 [~] 标记存在超过 15 分钟（可配置），下一个 Tick Worker 将：
- 重置该任务为 [ ]
- 在 TICK_STATUS 中记录 "Stale [~] detected on {TASK_ID}, reset to [ ]"
- 如果存在未提交的文件修改，执行 git checkout 清理

7.4 全局熔断

在以下情况下自动暂停流水线（tick_mode → paused）：

连续 5 个 Tick 全部失败（无一次 SUCCESS）
阻塞任务数超过总任务数的 30%
磁盘空间不足 / git 操作异常

在 TICK_STATUS 中写入：🔴 CIRCUIT BREAKER TRIGGERED — reason: {reason}

八、Architect 工作规范

当 Main Agent 处于 Architect 态时（与人类直接对话的 Session 中），遵循以下规范：

8.1 创建计划

与人类讨论项目需求，理解全貌
设计模块划分，写入 PROJECT_MAP.md
将需求分解为原子任务，写入 MASTER_PLAN.md
每个任务必须有 verify 命令 —— 没有验证命令的任务不配存在
合理划分 Phase，声明 parallel 和 depends

8.2 监控与调整

定期读取 TICK_STATUS.md（可由人类触发，或在对话中主动查看）
对于 [!] 阻塞任务：
- 分析失败原因
- 修改任务定义（调整 verify、context_files、拆分子任务）
- 或修改 PROJECT_MAP（更新接口定义）
- 重置 retries 为 0，状态改回 [ ]
对于 HUMAN_NOTES.md 中的批注：
- 读取并理解
- 将批注转化为 MASTER_PLAN 的具体修改
- 处理完后归档

8.3 计划变更原则

新增任务：追加到合适的 Phase，保持 ID 唯一
删除任务：标记 [-] 并注释原因，不要真的删掉行
拆分任务：将原任务标记 [-] (拆分为 T-XXX, T-XXY)，新增子任务
重排 Phase：更新 depends 关系，确保 DAG 无环

九、初始化与部署

9.1 初始化命令

bash skills/agent-memento/scripts/init_memento.sh <ProjectName>

该脚本执行：

在项目目录下创建 docs/ 目录
生成 MASTER_PLAN.md 模板（含 Meta 区和示例 Phase）
生成 PROJECT_MAP.md 模板
生成 TICK_STATUS.md（空）
生成 HUMAN_NOTES.md（空）
创建 logs/ 目录
生成 scripts/memento_tick.sh —— Tick Worker 的入口脚本
生成 .memento_ignore（排除 node_modules/, .git/, logs/ 等）
生成 scripts/tick_worker_system_prompt.md —— 注入给 Worker 的全套纪律法则和 Output 规范。
生成 .memento_cleanignore（保护 node_modules/, .env, vendor/ 等）
输出提示：“请将以下行添加到 crontab 以启动自动执行”

9.1.1 Tick Worker System Prompt 模板 (tick_worker_system_prompt.md)

以下是 init_memento.sh 应生成的 scripts/tick_worker_system_prompt.md 的完整内容：

# Memento Tick Worker — System Prompt

You are a Memento Tick Worker: a short-lived, stateless, disciplined execution agent.
You have no memory of previous ticks. You start fresh every time.

## Your Lifecycle (execute in this exact order)

1. Read `docs/MASTER_PLAN.md`. Parse the Meta section for configuration.
2. Read `docs/HUMAN_NOTES.md`. Note any `[NOTE]` entries (ignore `[NOTE:READ]`).
3. Scan Phases in order. For each Phase:
   - Check `depends`: all tasks in depended Phase must be `[x]` or `[-]`.
   - Find the first task marked `[ ]` with `retries < max_retries`.
4. If no executable task found:
   - If all tasks are `[x]`/`[-]`: write "🎉 ALL TASKS COMPLETE" to TICK_STATUS.md.
   - If any `[!]` exists: write "⚠️ PIPELINE BLOCKED" to TICK_STATUS.md.
   - Exit.
5. Mark the target task `[~]` in MASTER_PLAN.md.
6. Read `docs/PROJECT_MAP.md` for module context.
7. Load ONLY the files listed in the task's `context_files`.
8. If there are `[NOTE]` entries targeting this task ID or `global`, incorporate them.
9. Perform the work using surgical, targeted edits. NEVER output a full file.
10. Verify:
    - Check: did you modify any file listed in `guard_files`? If yes → rollback → fail.
    - Check: is your total diff > `max_diff_lines`? If yes → rollback → fail.
    - Run the task's `verify` command. Capture exit code, stdout, stderr.
11. Write a TICK_STATUS.md entry (format below).
12. If verify exit code == 0:
    - Mark task `[x]`. Run `git add -A && git commit -m "memento: complete {TASK_ID} {description}"`.
    - If `tasks_completed_this_tick < max_tasks_per_tick`, go to step 3 for next task.
13. If verify exit code != 0:
    - Rollback: `git checkout -- .`
    - Increment `retries` in MASTER_PLAN.md.
    - If `retries >= max_retries`: mark task `[!]`, add "⚠️ NEEDS ARCHITECT ATTENTION" to status.
    - Clear `[~]` back to `[ ]` (or `[!]`).
14. Exit.

## TICK_STATUS.md Entry Format

## [{timestamp}] Tick #{tick_number}
- **Task**: {TASK_ID} [MODULE:{module}] {description}
- **Status**: ✅ SUCCESS | ❌ FAILED (retry {n}/{max}) | 🚫 BLOCKED
- **Verify Output**: {first 5 lines of stdout/stderr} (exit code {n})
- **Duration**: {time}
- **Error Analysis**: {your diagnosis of what went wrong — FAILED/BLOCKED only}
- **Files Modified**: {file (+lines -lines)} | (rolled back)
- **Diff Size**: {total lines changed}
- **Git Commit**: {hash} — "{message}" | (none — rollback)
- **Outputs**: {key interfaces/exports created — SUCCESS only, optional but encouraged}

## Iron Disciplines (violation = immediate failure)

1. **SURGICAL EDITS ONLY**: Never output a complete file. Use precise, targeted modifications.
2. **EVIDENCE-BASED**: Run `verify`. No exit code 0 = no `[x]`. No exceptions.
3. **NO SILENT GHOSTING**: If stuck, write full error + analysis to TICK_STATUS.md. Never exit silently.
4. **STAY IN YOUR LANE**: Only modify files in `context_files`. Never touch `guard_files`. Never edit task definitions in MASTER_PLAN.md (only checkbox state + retries). Never edit PROJECT_MAP.md.
5. **ATOMIC COMMITS**: `git commit` on success. `git checkout` on failure. Always.

## What You Are NOT

- You are NOT an architect. Do not redesign, re-plan, or question the task definition.
- You are NOT creative. Execute exactly what is specified.
- You are NOT persistent. After this tick, you will cease to exist.

9.2 Tick 入口脚本模板 (memento_tick.sh)

#!/usr/bin/env bash
set -euo pipefail

PROJECT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
PLAN="$PROJECT_DIR/docs/MASTER_PLAN.md"
STATUS="$PROJECT_DIR/docs/TICK_STATUS.md"
LOG_DIR="$PROJECT_DIR/logs"
TIMESTAMP=$(date +%Y-%m-%dT%H:%M:%S)
TICK_LOG="$LOG_DIR/tick_${TIMESTAMP}.log"

# 防撞车：确保同一时间只有一个 Tick Worker 运行
LOCK_FILE="$PROJECT_DIR/.memento.lock"
exec 200>"$LOCK_FILE"
if ! flock -n 200; then
  echo "[$TIMESTAMP] Tick skipped: previous tick still running" >> "$STATUS"
  exit 0
fi

# 检查 tick_mode
TICK_MODE=$(grep -oP 'tick_mode:\s*\K\w+' "$PLAN" || echo "stopped")
if [[ "$TICK_MODE" != "auto" ]]; then
  echo "[$TIMESTAMP] Tick skipped: mode=$TICK_MODE" >> "$STATUS"
  exit 0
fi

# 调用 LLM Agent 执行 Tick
SYSTEM_PROMPT="$(cat "$PROJECT_DIR/scripts/tick_worker_system_prompt.md")"

openclaw agent \
  --system-prompt "$SYSTEM_PROMPT" \
  --prompt "Read $PLAN, find the first executable task, complete it following the Memento Tick Worker protocol. Write results to $STATUS." \
  --context-files "$PLAN" "$PROJECT_DIR/docs/PROJECT_MAP.md" "$PROJECT_DIR/docs/HUMAN_NOTES.md" \
  2>&1 | tee "$TICK_LOG"

# 后处理：三阶段防爆清理
cd "$PROJECT_DIR"
if [[ -n $(git status --porcelain) ]]; then
  echo "[$TIMESTAMP] WARNING: Dirty workspace detected. Running 3-phase cleanup." >> "$STATUS"

  # Phase 1: 恢复已追踪文件
  git checkout -- .

  # Phase 2: 清理未追踪文件（排除保护列表）
  if [[ -f ".memento_cleanignore" ]]; then
    git clean -fd --exclude-from=.memento_cleanignore
  else
    git clean -fd
  fi

  # Phase 3: 兜底——如果还是脏的，紧急 stash
  if [[ -n $(git status --porcelain) ]]; then
    git stash --include-untracked -m "memento-emergency-stash-$TIMESTAMP"
    echo "[$TIMESTAMP] CRITICAL: Emergency stash created. Manual inspection required." >> "$STATUS"
  fi
fi

# 日志轮转
MAX_ENTRIES=$(grep -oP 'status_max_entries:\s*\K\d+' "$PLAN" || echo "50")
CURRENT_ENTRIES=$(grep -c '^\## \[' "$STATUS" || true)
if [[ $CURRENT_ENTRIES -gt $MAX_ENTRIES ]]; then
  ARCHIVE_DIR="$PROJECT_DIR/logs/status_archive"
  mkdir -p "$ARCHIVE_DIR"
  mv "$STATUS" "$ARCHIVE_DIR/TICK_STATUS_$(date +%Y%m%d_%H%M%S).md"
  echo "# TICK STATUS LOG" > "$STATUS"
  echo "" >> "$STATUS"
  echo "<!-- Rotated at $TIMESTAMP. Previous entries archived. -->" >> "$STATUS"
fi

# 告警检测
BLOCKED_COUNT=$(grep -c '\[!\]' "$PLAN" || true)
CIRCUIT_BROKEN=$(grep -c 'CIRCUIT BREAKER' "$STATUS" || true)

if [[ $BLOCKED_COUNT -gt 0 || $CIRCUIT_BROKEN -gt 0 ]]; then
  cat > "$PROJECT_DIR/.memento_alert" << EOF_INNER
timestamp: $TIMESTAMP
blocked_tasks: $BLOCKED_COUNT
circuit_breaker: $([[ $CIRCUIT_BROKEN -gt 0 ]] && echo "TRIGGERED" || echo "OK")
message: Pipeline needs attention. $BLOCKED_COUNT task(s) blocked.
EOF_INNER
fi

# 如果一切正常且之前有告警，清除告警
if [[ $BLOCKED_COUNT -eq 0 && $CIRCUIT_BROKEN -eq 0 && -f "$PROJECT_DIR/.memento_alert" ]]; then
  rm -f "$PROJECT_DIR/.memento_alert"
fi

9.3 Cron 配置

# 每 5 分钟执行一次
*/5 * * * * /path/to/project/scripts/memento_tick.sh >> /path/to/project/logs/cron.log 2>&1

十、完整工作流示例

人类："我想做一个带用户系统的 REST API"
  │
  ▼
Architect（主 Session）：
  ├─ 与人类讨论确认：PostgreSQL + JWT + Express
  ├─ 写入 PROJECT_MAP.md（模块划分）
  ├─ 写入 MASTER_PLAN.md（15 个任务，3 个 Phase）
  └─ "计划已就绪，运行 init 脚本后添加 crontab 即可启动"
  │
  ▼
人类：添加 crontab，开始刷手机
  │
  ▼
Tick #001 → T-101 数据库初始化 → ✅
Tick #001 → T-102 JWT 模块 → ✅ （同一 Tick 内连续完成 2 个快任务）
Tick #002 → T-103 密码哈希 → ✅
Tick #003 → T-201 连接中间件 → ❌ (retry 1/3)
Tick #004 → T-201 → ❌ (retry 2/3)
Tick #005 → T-201 → 🚫 BLOCKED
  │
  ▼
人类打开 Dashboard，看到 T-201 阻塞
  ├─ 在 Notes 区写："别用 pg-pool 了，直接用 prisma"
  └─ 继续刷手机
  │
  ▼
Architect（读取 HUMAN_NOTES + TICK_STATUS）：
  ├─ 更新 PROJECT_MAP.md（MODULE:database 改为 Prisma）
  ├─ 修改 T-201 的 context_files 和 verify
  ├─ 新增 T-105 "安装并配置 Prisma"（插入 Phase 1）
  ├─ 重置 T-201 retries → 0，状态 [!] → [ ]
  └─ 归档 HUMAN_NOTES 中的批注
  │
  ▼
Tick #006 → T-105 安装 Prisma → ✅
Tick #007 → T-201 连接中间件（Prisma 版）→ ✅
Tick #008 → T-202 ... → ✅
  │
  ... 持续推进 ...
  │
  ▼
Tick #031 → 🎉 ALL TASKS COMPLETE
  │
  ▼
人类打开 Dashboard："哦，做完了。" 移除 crontab。

Security & Transparency

Data Access — Exactly What Is Read

Reads <project-dir>/docs/MASTER_PLAN.md to determine the current task
Reads <project-dir>/docs/PROJECT_MAP.md for project structure awareness
Reads <project-dir>/docs/HUMAN_NOTES.md for human annotations
Reads source code files listed in each task's context_files only

Data Written

Creates project scaffolding (MASTER_PLAN.md, PROJECT_MAP.md, TICK_STATUS.md, HUMAN_NOTES.md, memento_tick.sh)
Updates checkbox states in MASTER_PLAN.md (Tick Worker: only [ ]↔[x]/[!]/[~])
Edits source files within the target project directory, limited to declared context_files
Writes execution logs to logs/tick_*.log
Creates git commits for successful task completions

Hard Safety Guards

Diff size limit: Rejects changes > 200 lines per task (configurable)
Guard files: Physically prevents modification of declared protected files
Auto-rollback: Failed tasks are rolled back via git checkout
Circuit breaker: Auto-pauses pipeline on sustained failures

Persistence & Autonomous Scheduling

The init_memento.sh script generates a bash script intended to be run via cron
The user must manually add this to their crontab to enable autonomous execution
Stop at any time by removing the crontab entry or setting tick_mode: stopped

Credentials

Operates entirely locally
Relies on openclaw agent with the system's existing LLM configurations
No new keys are requested or stored

Network Access

No outbound network access by framework scripts
Network access may occur only when user-defined verify commands require it (e.g., npm install)


---

## 附录：文件结构总览

<project>/ ├── docs/ │ ├── MASTER_PLAN.md # 唯一真相源 │ ├── PROJECT_MAP.md # 项目认知地图 │ ├── TICK_STATUS.md # 执行状态流水账 │ └── HUMAN_NOTES.md # 人类批注通道 ├── logs/ │ ├── cron.log # cron 调度日志 │ ├── tick_2025-01-15T14:35:00.log │ └── tick_2025-01-15T14:40:00.log ├── scripts/ │ └── memento_tick.sh # Tick Worker 入口 ├── .memento_ignore # 上下文排除规则 └── src/ # 实际项目代码 └── ...