agent-step-gate 0.3.0 → 0.3.1

package/README.md

@@ -13,6 +13,38 @@ It only maintains an external execution ledger and verifies that planned steps h
 
 ---
 
+## 🚀 Quick Start
+
+```bash
+# Install globally
+npm install -g agent-step-gate
+
+# Create a task with steps
+step-gate start-plan '{
+  "title":"Refactor auth module",
+  "steps":[
+    {"id":"extract","title":"Extract middleware","dependsOn":[]},
+    {"id":"jwt","title":"Add JWT validation","dependsOn":[]},
+    {"id":"routes","title":"Update routes","dependsOn":["extract","jwt"]},
+    {"id":"test","title":"Write tests","dependsOn":["routes"]}
+  ]
+}'
+# → Returns taskId + stepKeys for unlocked steps
+
+# Complete a step (unlocks downstream)
+step-gate checkpoint '{"taskId":"tsk_XXX","stepId":"tsk_XXX_extract","stepKey":"K8F2QZ"}'
+# → Returns nextSteps + nextStepKeys
+
+# Finalize when all steps are done
+step-gate finalize '{"taskId":"tsk_XXX","taskKey":"A1B2C3"}'
+```
+
+**One interaction = One Task.** Create a task, checkpoint each step, finalize. The external ledger ensures nothing is skipped.
+
+For multi-session projects, see [Program mode](#program-level-usage). For multi-agent orchestration, see [Weaver.md](Weaver.md).
+
+---
+
 ## ❓ Why
 
 Long-context agents are capable, but they often miss steps in long-running tasks.

package/SKILL.md

@@ -185,6 +185,3 @@ The CLI auto-discovers the session from binding files. No manual session managem
 - `Weaver.md` — Multi-agent orchestration: how a Main Agent spawns Sub Agents, injects
   taskId + stepKey, and verifies returned taskKeys. Read this before orchestrating
   parallel Sub Agents.
-- `ARCHITECTURE.md` — Full architecture: 4-layer model, 7 DB tables, 5 credential types,
-  12 CLI commands, 20+ core functions
-- `docs/security-stress-test-report.md` — Security audit: 9 issues, all resolved

package/Weaver.md

@@ -1,140 +1,145 @@
-# Weaver — Step Gate 编排引擎
+# Weaver — Multi-Agent Orchestration Protocol
 
-## 三层角色
+## Role model
 
 ```
-Main Agent (编排者)       ← 持有 Node/Program 全局视角
-  │                          只做三件事: 派发、校验、推进
-  │                          不写代码、不执行 Step
+Main Agent (orchestrator)
+  │  Only three jobs: dispatch, verify, advance
+  │  Never writes code, never executes steps
   │
-  ├── Sub Agent A            ← 只知道自己的 taskId + taskGoal
-  ├── Sub Agent B            ← 不知道其他 Task、不知道 DAG
-  └── Sub Agent C            ← 不知道 Node/Program 全局
+  ├── Sub Agent A   Knows: taskId + taskGoal + its stepKeys
+  ├── Sub Agent B   Does NOT know: full DAG, other tasks, Node/Program
+  └── Sub Agent C   Does NOT know: validation logic (the Gate handles it)
 ```
 
-Sub Agent 的上下文由 Main Agent 在 Spawn 时精确注入。看不到全局计划，不知道前后 Task，不持有验证逻辑。
+The Main Agent injects precisely what each Sub Agent needs. No more, no less.
+
+## Protocol: what gets passed
+
+### Main Agent → Sub Agent (dispatch)
+
+```json
+{
+  "taskId": "tsk_XXXXXX",
+  "taskGoal": "Extract auth middleware into a standalone module",
+  "stepKeys": {
+    "tsk_XXXXXX_extract": "K8F2QZ"
+  },
+  "constraints": [
+    "Only work on this task's scope",
+    "Run step-gate checkpoint after each step",
+    "Return the taskKey when all steps are done"
+  ]
+}
+```
+
+Critical: `stepKeys` contains the keys for currently-unlocked steps. The Sub Agent
+needs these to call `checkpoint`. Without them, it can't advance. The Main Agent
+gets them from the `start-plan` or `checkpoint` response.
 
-## 完整执行流程
+### Sub Agent → Main Agent (return)
 
+```json
+{
+  "taskId": "tsk_XXXXXX",
+  "taskKey": "A1B2C3",
+  "summary": "Extracted auth middleware to src/middleware/auth.ts",
+  "artifacts": ["src/middleware/auth.ts", "src/middleware/index.ts"]
+}
 ```
-═══════════════════════════════════════════════════════
-Phase 0 — 规划
-═══════════════════════════════════════════════════════
-Main Agent:
-  program init → 拆分 Node
-  reconcile → 日常诊断
 
-═══════════════════════════════════════════════════════
-Phase 1 — 启动 Node
-═══════════════════════════════════════════════════════
-Main Agent:
-  program start <node-id>        ← 绑定 session 到 node
-  start-plan → 创建 Task(DAG)    ← 一次交互 = 一个 Task
-  → 拿到 taskId + stepKeys
-
-═══════════════════════════════════════════════════════
-Phase 2 — 派发
-═══════════════════════════════════════════════════════
-Main Agent → Sub Agent:
-  {
-    "taskId": "tsk_XXX",
-    "taskGoal": "抽离认证中间件",
-    "constraints": ["只处理本Task范围", "完成后调checkpoint"]
-  }
-
-Sub Agent 在同一工作目录启动:
-  → ensureSession() 自动从 .step-gate/bindings/ 发现 session
-  → 无需手动传 sessionId
-
-═══════════════════════════════════════════════════════
-Phase 3 — Sub Agent 执行循环
-═══════════════════════════════════════════════════════
-Sub Agent:
-  current(taskId)
-    → { currentSteps, stepKeys }
-
-  for each step:
-    执行 step
-    checkpoint(taskId, stepId, stepKey)
-      → { nextSteps, nextStepKeys }
-      → 或 { allStepsCompleted: true, taskKey }
-
-═══════════════════════════════════════════════════════
-Phase 4 — 交回凭证
-═══════════════════════════════════════════════════════
-Sub Agent → Main Agent:
-  {
-    "taskId": "tsk_XXX",
-    "taskKey": "A1B2C3",
-    "summary": "完成认证中间件抽离",
-    "artifacts": ["src/middleware/auth.ts"]
-  }
-
-═══════════════════════════════════════════════════════
-Phase 5 — Main Agent 校验 + 自动推进
-═══════════════════════════════════════════════════════
+If the Sub Agent failed to complete all steps, it returns the current step it's
+stuck on — the Main Agent can re-dispatch or reassign.
+
+## Full lifecycle
+
+### Phase 1 — Plan and create
+
+```
 Main Agent:
-  finalize(taskId, taskKey)
-
-  ✅ 通过:
-    → 返回 { ok: true, level, ... }
-    → level="task":    Node 还有未完成的 Task，继续派发
-    → level="node":    Node 完成! nodeKey 返回，自动推进
-    → level="program": 全部 Node 完成! 收工
-    → Sub Agent 释放
-
-  ❌ 不通过:
-    → 返回 { actualStatus, completedSteps, missingSteps,
-             currentStepId, stepKey }
-    → Main Agent 把真实账本发回 Sub Agent:
-        "你的 TaskKey 未通过 Gate 校验。
-         已完成: step_001, step_002
-         缺失:   step_003, step_004
-         当前应继续 step_003，StepKey: SK_REAL33"
-    → Sub Agent 从 currentStepId 继续 checkpoint
-    → 修完重新 finalize
-
-═══════════════════════════════════════════════════════
-Phase 6 — 下一个 Node (自动)
-═══════════════════════════════════════════════════════
-finalize 返回 level="node" 时，Main Agent:
-  program status → 找下一个 ready node
-  program start <next-node>
-  → 创建新 Task → 派发 → 循环
+  start-plan → creates Task with DAG steps
+  Receives: taskId + currentSteps + stepKeys (for unlocked steps)
+```
 
-═══════════════════════════════════════════════════════
-收尾
-═══════════════════════════════════════════════════════
-最后一个 Node 完成:
-  finalize → level="program" → Program completed
-  收工
+### Phase 2 — Dispatch to Sub Agent
+
+```
+Main Agent spawns Sub Agent with the injection payload above.
+Sub Agent auto-discovers session from .step-gate/bindings/.
 ```
 
-## 关键设计点
+### Phase 3 — Sub Agent executes
 
-**Main Agent 只调一个命令**：`finalize(taskKey)`。剩下的系统自动从 Task → Node → Program 传播。
+```
+Sub Agent loop:
+  1. Read stepKey from the injected payload (or checkpoint response)
+  2. Execute the step
+  3. step-gate checkpoint '{"taskId":"...","stepId":"...","stepKey":"..."}'
+  4. Response gives nextSteps + nextStepKeys (if deps satisfied)
+     OR allStepsCompleted: true + taskKey (if this was the last step)
+```
 
-**TaskKey 校验即消费**：finalize 会消耗 taskKey 并推进 DAG，不存在"校验通过但不推进"的状态。
+If a merge point hasn't been reached yet (parallel branches), `nextSteps` is
+empty. The Sub Agent must wait for other branches to complete before the merge
+step unlocks.
 
-**Sub Agent 不需要知道**：
-- taskId 的结构含义
-- 完整的 DAG
-- 前后 Task 是什么
-- Node/Program 全局
-- 验证逻辑（系统自己校验）
+### Phase 4 — Sub Agent returns
 
-**中断恢复**：taskId + skipKey 重建，旧 step 凭证永久保留。
+```
+Sub Agent → Main Agent: { taskId, taskKey, summary, artifacts }
+Main Agent: step-gate finalize '{"taskId":"...","taskKey":"..."}'
+```
+
+### Phase 5 — Verify and propagate
 
-**纯 Task 模式**：不用 Program/Node 时，只需 `start-plan → checkpoint → finalize`。每个交互一个 Task，交互结束 Stop Hook 自动检查。
+```
+finalize returns:
+  { level: "task" }      → Node has more tasks, dispatch next Sub Agent
+  { level: "node" }      → Node complete, auto-generated nodeKey returned
+  { level: "program" }   → All nodes done, program complete
+
+If finalize REJECTS:
+  { accepted: false, pendingSteps: [...] }
+  → Sub Agent missed steps. Send it the pendingSteps list, continue checkpointing.
+```
 
-## 渐进式披露
+### Phase 6 — Next node
 
 ```
-SKILL.md (执行协议)         ← 所有 Agent 必读，基础 CLI 命令
-  └─ Weaver.md (编排引擎)   ← Main Agent 读，如何编排 Sub Agent
-       └─ CLI (状态机)       ← 底层实现
-            └─ SQLite (持久化)
+When level="node", Main Agent:
+  program status → find next ready node
+  program start <next-node>
+  → start-plan → dispatch → repeat
 ```
 
-Sub Agent 只需要 SKILL.md 中的 CLI 命令，不需要 Weaver.md。
-Main Agent 需要 SKILL.md + Weaver.md。
+## Key design rules
+
+1. **Sub Agent never sees the full DAG.** It only knows the steps it's been given
+   keys for. This prevents hallucinated dependencies and keeps context lean.
+
+2. **Main Agent only calls `finalize`.** It doesn't need to inspect execution
+   traces. The taskKey is a cryptographic proof — it either matches or it doesn't.
+
+3. **Keys are single-use and appear once.** The Sub Agent captures them from the
+   checkpoint response. The `current` command does NOT return keys. If a key is
+   lost, the task must be cancelled and rebuilt with skipKey.
+
+4. **SkipKey recovery.** If a Sub Agent dies mid-task, the Main Agent rebuilds:
+   ```
+   cancel-task → start-plan (with skipKey + skipTaskId for completed steps)
+   ```
+   Completed steps are marked `skipped`, remaining steps get fresh keys.
+
+5. **Pure Task mode.** When Program/Node layers aren't needed, just use:
+   ```
+   start-plan → checkpoint × N → finalize
+   ```
+   The Stop Hook checks for unfinalized tasks at session end.
+
+## Progressive disclosure
+
+```
+SKILL.md        → All agents. CLI commands + rules.
+Weaver.md       → Main Agent only. How to dispatch and verify Sub Agents.
+CLI + SQLite    → The Gate itself. Agents don't read this.
+```

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "agent-step-gate",
-  "version": "0.3.0",
-  "description": "CLI + Skill-based Step Ledger & Key Gate for long-running multi-agent orchestration",
+  "version": "0.3.1",
+  "description": "External cryptographic step ledger for long-running multi-agent orchestration",
   "type": "module",
-  "main": "dist/index.js",
   "bin": {
     "step-gate": "dist/cli.js"
   },
@@ -22,12 +21,10 @@
     "dist/",
     "scripts/",
     "SKILL.md",
-    "Weaver.md",
-    "ARCHITECTURE.md"
+    "Weaver.md"
   ],
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
     "better-sqlite3": "^11.0.0",
     "zod": "^4.0"
   },
@@ -40,9 +37,6 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "start": "node dist/index.js",
-    "cli": "node dist/cli.js",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "cli": "node dist/cli.js"
   }
 }

package/ARCHITECTURE.md

@@ -1,393 +0,0 @@
-# Agent Step Gate — 完整架构文档
-
-**版本**: 0.3.0 | **日期**: 2026-05-30 | **测试**: 116/116
-
----
-
-## 1. 四层架构
-
-```
-Program (pgm_XXXXXX)              ← 跨 Session 大计划
-  └─ Node (pg-xxx)                ← 一个 Session 的工作单元
-       └─ Task (tsk_XXXXXX)       ← 一个 DAG 计划
-            └─ Step               ← 最小执行单元
-```
-
-每层都有对应的完成凭证：
-```
-stepKey ──→ taskKey ──→ nodeKey ──→ program (自检)
- (出示)      (出示)      (收据)       (自动)
-```
-
-### 自底向上传播
-
-`finalize` 命令一次调用，自动逐层上浮：
-
-```
-finalize(taskKey)
-  → task completed
-  → 检查: 同 node 全部 task completed?
-    → 是 → 生成 nodeKey → node completed
-    → 检查: 同 program 全部 node completed?
-      → 是 → program completed
-```
-
-Agent 不需要判断层级——系统自己知道该传播到哪。
-
----
-
-## 2. 数据库 — 7 张表
-
-### programs
-```sql
-program_id    TEXT PK   -- pgm_XXXXXX
-title         TEXT
-status        TEXT     -- active | completed
-total_nodes   INTEGER
-created_at / updated_at
-```
-
-### program_nodes
-```sql
-node_id       TEXT PK   -- user-defined or pg_xxx_N
-program_id    TEXT FK
-title / description / order_index
-status        TEXT     -- pending | in_progress | completed
-session_id    TEXT
-node_key_hash TEXT     -- SHA-256(6-char nodeKey), system-generated
-completed_at / created_at
-```
-
-### sessions
-```sql
-session_id          TEXT PK   -- ses_XXXXXX
-session_secret_hash TEXT     -- SHA-256(6-char)
-recovery_token_hash TEXT     -- SHA-256(6-char)
-title / workspace
-program_id / program_node_id
-status              TEXT     -- active | completed | abandoned
-created_by_cli / created_at / updated_at
-```
-
-### cli_instances
-```sql
-cli_instance_id   TEXT PK   -- cli_XXXXXX
-session_id / hostname / pid / workspace
-status            TEXT     -- active | dead | detached
-created_at / last_seen_at
-```
-
-### tasks
-```sql
-id              TEXT PK   -- tsk_XXXXXX
-title / status            -- active | completed | cancelled
-current_index / total_steps
-final_key_hash  TEXT     -- SHA-256(taskKey)
-session_id      TEXT FK
-created_at / updated_at
-```
-
-### steps
-```sql
-id              TEXT PK   -- {taskId}_{nodeId}
-task_id / parent_path / title / path
-order_index / depends_on (JSON)
-status          TEXT     -- pending | current | completed | skipped
-step_key_hash   TEXT     -- SHA-256(stepKey), 完成后保留为永久凭证
-completed_at / created_at
-```
-
-### events
-```sql
-id / task_id / step_id
-event_type      TEXT     -- plan_created | step_activated | step_completed
-                         -- all_steps_completed | task_finalized | task_cancelled
-                         -- skip_key_consumed
-payload / created_at
-```
-
----
-
-## 3. 安全模型 — 5 种凭证
-
-| 凭证 | 长度 | 用途 | 生成者 | 验证方式 | 生命周期 |
-|------|------|------|--------|---------|---------|
-| **stepKey** | 6位 | 证明单个 step 完成 | 系统(plan/checkpoint) | SHA-256 hash 匹配 | 一次性，checkpoint 后消耗 |
-| **taskKey** | 6位 | 证明全部 step 完成 | 系统(最后一步 checkpoint) | SHA-256 hash 匹配 | 一次性，finalize 后消耗 |
-| **nodeKey** | 6位 | Node 完成凭证(收据) | 系统(finalize 自动传播) | SHA-256 hash 存 DB | 作为完成凭证返回给 Agent |
-| **sessionSecret** | 6位 | Session 身份认证 | 系统(createSession) | SHA-256 hash 匹配 | Session 生命周期 |
-| **recoveryToken** | 6位 | 崩溃恢复 + 管理操作 | 系统(createSession) | SHA-256 hash 匹配 | Session 生命周期 |
-
-### 隔离规则
-- Task 写操作：session_id 列强制过滤
-- cancel-task：必须同 session，或出示 recoveryToken (--admin)
-- checkpoint 原子性：`WHERE status='current' + affected rows` 防双消费
-- stepKey 一次性：key_hash 保留作永久凭证，但 step 只能 checkpoint 一次
-
-### skipKey 验证 (中断恢复)
-- 旧 task 的 completed step 可作 skipKey 跳过新 task 的重复步骤
-- `verifySkipKey()` 检查：hash 匹配 + status='completed' + events 表无 `skip_key_consumed`
-- 验证通过后立即写入 `skip_key_consumed` 事件——确保一次性使用
-- 跳过步骤标记为 `skipped`（非 `completed`），保留溯源
-
----
-
-## 4. DAG 引擎
-
-### 输入格式
-```json
-{
-  "title": "Plan",
-  "steps": [
-    {"id":"a","title":"A","dependsOn":[]},
-    {"id":"b","title":"B","dependsOn":["a"]},
-    {"id":"c","title":"C","dependsOn":[],"skipKey":"OLD","skipTaskId":"tsk_OLD"}
-  ]
-}
-```
-
-### 展开规则
-1. `dependsOn: []` → 并行起点，初始即激活
-2. `dependsOn: undefined` → 自动串行，依赖前一个叶子
-3. `dependsOn: ["b","c"]` → b 和 c 都完成后才解锁
-4. `skipKey + skipTaskId` → 验证通过后标记 `skipped`
-5. 嵌套 children → 递归展开为叶子节点
-
-### 解锁算法
-```
-checkpoint(stepX):
-  1. 标记 stepX = completed (保留 key_hash)
-  2. 扫描 pending steps：
-     dependsOn 全部 completed/skipped → 标记 current，生成 key
-  3. 无新解锁 + 全部 completed/skipped → 生成 taskKey
-```
-
----
-
-## 5. CLI 命令全集 (12 个)
-
-### Task 级
-| 命令 | 输入 | 输出 |
-|------|------|------|
-| `start-plan '<json>'` | title + steps[] | taskId, session, totalSteps, currentSteps, stepKeys |
-| `checkpoint '<json>'` | taskId + stepId + stepKey | completedStep, nextSteps, nextStepKeys, taskKey |
-| `current '<json>'` | taskId | status, totalSteps, completedSteps, currentSteps |
-| `finalize '<json>'` | taskId + taskKey | level(task/node/program), nodeKey(if), program(if) |
-| `cancel-task '<json>'` | taskId | ok / error(NO_SESSION) |
-| `active-task` | — | activeTasks[] (session-filtered) |
-| `active-task --all` | — | activeTasks[] (跨 session) |
-
-### Program 级
-| 命令 | 输入 | 输出 |
-|------|------|------|
-| `program init '<json>'` | title + nodes[] | programId, totalNodes, nodes |
-| `program status '<json>'` | programId | programId, title, nodes[] |
-| `program ready '<json>'` | programId | readyNodes[] |
-| `program start '<json>'` | programId + nodeId | ok, nodeId, sessionId |
-| `program finalize '<json>'` | programId | ok, pending[] |
-
-### Session 绑定方式
-- `--session-file <path>` — 显式指定 session 文件
-- `--binding-file <path>` — 通过 binding 文件间接指定
-- `STEP_GATE_SESSION_FILE` / `STEP_GATE_BINDING_FILE` 环境变量
-- 自动发现 `.step-gate/bindings/` 中最新的 binding（回退）
-
-### Admin 模式
-- `cancel-task --admin --recovery-token <token>` — 跨 session 取消
-
----
-
-## 6. 核心函数 (20+)
-
-### src/core/plan.ts
-| 函数 | 作用 |
-|------|------|
-| `flattenPlan(nodes, taskId) → LeafStep[]` | 嵌套展开 + DAG 依赖解析 |
-
-### src/core/keys.ts
-| 函数 | 作用 |
-|------|------|
-| `randomCode(length) → string` | [A-Z0-9] 随机码 |
-| `generateStepKey() → {plaintext, hash}` | 6位 step key |
-| `generateTaskKey() → {plaintext, hash}` | 6位 task key |
-| `generateNodeKey() → {plaintext, hash}` | 6位 node key |
-| `hashKey(plaintext) → string` | SHA-256 |
-
-### src/core/gate.ts
-| 函数 | 作用 |
-|------|------|
-| `validateCheckpoint(repo, taskId, stepId, stepKey)` | 5步校验（task存在/active/current匹配/key匹配） |
-| `advanceSteps(repo, task, completedStepId)` | 解锁后继步骤或生成 taskKey |
-| `GateRepository` (interface) | 仓库抽象：getTask/getCurrentSteps/getTaskSteps/completeAndAdvance/updateTaskStatus/verifyTaskKey |
-
-### src/core/session.ts
-| 函数 | 作用 |
-|------|------|
-| `createSession(workspace) → SessionInfo` | 创建 session + 写入文件 |
-| `verifySessionSecret(sessionId, secret)` | 校验 session 凭据 |
-| `verifyRecoveryToken(sessionId, token)` | 校验恢复凭据 |
-| `isSessionActive(sessionId)` | 检查状态 |
-| `getCurrentSessionId()` | 进程内共享 sessionId |
-
-### src/core/program.ts
-| 函数 | 作用 |
-|------|------|
-| `createProgram(title, nodes[]) → ProgramInfo` | 创建 Program |
-| `getProgramStatus(programId) → ProgramInfo` | 查询状态 |
-| `getReadyNodes(programId) → ProgramNodeInfo[]` | 可开始的 node |
-| `startProgramNode(programId, nodeId, sessionId)` | 绑定 session |
-| `commitProgramNode(sessionId)` | 自动生成 nodeKey + 标记 node 完成 |
-| `finalizeProgram(programId)` | 全局完整性检查 |
-
-### src/storage/repository.ts
-| 函数 | 作用 |
-|------|------|
-| `createTask(task, steps[])` | 原子写入 task + steps |
-| `getTask(taskId)` | 查询 task |
-| `getCurrentSteps(taskId)` | 查询活跃步骤 |
-| `getTaskSteps(taskId)` | 查询所有步骤 |
-| `getActiveTasks(sessionId?)` | 活跃 task（可选 session 过滤） |
-| `completeAndAdvance(...)` | 原子完成+推进（事务保护） |
-| `verifyStepKey(taskId, stepId, key)` | 严格校验（status='current'） |
-| `verifyTaskKey(taskId, key)` | 校验 taskKey |
-| `verifySkipKey(oldTaskId, stepId, oldKey)` | 验证 skip 凭证 + 检查消费事件 |
-| `recordSkipConsumed(taskId, stepId)` | 写入 skip_key_consumed 事件 |
-| `cancelTask(taskId, sessionId)` | 取消（session 门控） |
-| `updateTaskStatus(taskId, status)` | 更新状态 |
-| `addEvent(taskId, stepId, type, payload?)` | 事件记录 |
-| `getEvents(taskId)` | 查询事件 |
-
----
-
-## 7. Hook 系统
-
-### SessionStart (`scripts/session-start-hook.sh`)
-```
-触发: 每次终端启动
-策略: 轻量优先 — 读 data/state.json (1ms)，无结果才调 CLI
-行为:
-  1. 读 state.json → 有活跃 task → 警告 + 列出进度
-  2. state 为空 → active-task --all → 跨 session 检查
-  3. 无未完成 → 提醒可用命令
-```
-
-### Stop (`.claude/settings.local.json`)
-```
-触发: Session 结束前
-行为:
-  调用 finalize(taskKey) → 系统自动传播到 node/program
-  如无 taskKey → 拦截提醒
-```
-
-### State File (`data/state.json`)
-```
-写入时机: start-plan / checkpoint / finalize / cancel-task 后
-内容: { hasActiveTask, activeTasks: [{taskId, title, completed, total, current}] }
-用途: SessionStart 1ms 快照，跨互动提醒
-```
-
----
-
-## 8. 文件布局
-
-```
-project/
-  src/
-    cli.ts                       ← CLI 入口 (504行, 12命令)
-    index.ts                     ← MCP Server 入口 (备用)
-    core/
-      plan.ts                    ← DAG 展开
-      keys.ts                    ← 三层密钥生成
-      gate.ts                    ← 校验 + 解锁状态机
-      session.ts                 ← Session 管理
-      program.ts                 ← Program 层
-      errors.ts                  ← GateError
-    storage/
-      db.ts                      ← SQLite (WAL, busy_timeout=5000)
-      repository.ts              ← 数据层 (20+ 函数)
-    tools/                        ← MCP 工具 (备用)
-      startPlan.ts / checkpoint.ts / current.ts
-      finalize.ts / cancelTask.ts / activeTask.ts / index.ts
-    types/
-      index.ts                   ← 全部类型定义
-  tests/
-    core.test.ts                 ← 36 tests
-    storage.test.ts              ← 34 tests
-    tools.test.ts                ← 29 tests (含 A1/B1)
-    ci-blackbox.test.ts          ← 15 tests (MCP 协议级)
-    e2e-smoking-app.test.ts      ← E2E 强制回退
-    e2e-multi-agent.test.ts      ← E2E 多Agent协作
-  scripts/
-    session-start-hook.sh
-    prompt-check-hook.sh
-  mcp-backup/                    ← MCP 完整备份
-  data/
-    gate.db                      ← SQLite 数据库
-    state.json                   ← 轻量快照
-  .step-gate/
-    sessions/                    ← Session 凭据文件
-    bindings/                    ← CLI 绑定文件
-  openspec/changes/              ← 变更文档
-  SKILL.md                       ← Skill 定义
-  ARCHITECTURE.md                ← 本文档
-```
-
----
-
-## 9. 错误码
-
-| 错误码 | 含义 |
-|--------|------|
-| TASK_NOT_FOUND | taskId 不存在 |
-| TASK_ALREADY_COMPLETED | 任务已完成 |
-| NO_STEPS | 计划无步骤 |
-| INVALID_CURRENT_STEP | 步骤不在当前状态 |
-| INVALID_STEP_KEY | stepKey 校验失败 |
-| INVALID_FINAL_KEY | taskKey 校验失败 |
-| INVALID_RECOVERY_TOKEN | recoveryToken 校验失败 |
-| PLAN_SCHEMA_INVALID | 计划格式错误 |
-| SKIP_VERIFY_FAILED | skip 凭证验证失败或已消费 |
-| NO_SESSION | 无 session 绑定 |
-| INTERNAL_ERROR | 数据库/内部错误 |
-
----
-
-## 10. 典型流程
-
-### 单 Session
-```bash
-start-plan → checkpoint × N → finalize taskKey
-# → 自底向上: task → node → program (如有)
-```
-
-### 中断恢复
-```bash
-start-plan → checkpoint auth ✅
-  → current (查状态) → cancel-task
-  → start-plan (skipKey+skipTaskId 重建，旧 key 被消费)
-  → checkpoint → finalize taskKey
-```
-
-### 跨 Session Program
-```bash
-program init → program start pg-1
-  → start-plan → checkpoint × N → finalize taskKey
-# ↑ 自动标记 pg-1 completed + nodeKey 生成
-
-program start pg-2
-  → start-plan → checkpoint × N → finalize taskKey
-# ↑ 自动标记 pg-2 completed，program completed
-```
-
----
-
-## 11. 技术栈
-
-- **Runtime**: Node.js 20+
-- **Language**: TypeScript ESM
-- **Storage**: better-sqlite3 (WAL, synchronous=NORMAL, busy_timeout=5000)
-- **Validation**: Zod v4 (MCP tools)
-- **Test**: vitest (116 tests, 6 suites)
-- **Key**: crypto.randomBytes → [A-Z0-9]{6} → SHA-256
-- **IDs**: 6位 [A-Z0-9] (36^6 ≈ 21亿熵)
-- **MCP SDK**: @modelcontextprotocol/sdk v1.x (备用)