agent-step-gate 0.3.0

package/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: Step Gate
+description: >
+  Use this skill whenever working on multi-step tasks, large refactors, cross-session
+  development, or multi-agent orchestration — any situation where skipping a planned step
+  would be costly. This skill enforces an external cryptographic ledger: every planned step
+  must be checkpointed with a valid key before the task can be finalized. Triggers on
+  phrases like "multi-step plan", "refactor in phases", "orchestrate agents", "long task",
+  "don't skip steps", "checkpoint my work", "gate my steps", or any mention of Step Gate.
+---
+
+# Step Gate — External Execution Ledger
+
+An external cryptographic gate for agent task execution. It does not control *how* you
+work — it only verifies *that you did* what you planned. Think of it as a
+proof-of-work chain for agent steps: every completed step produces a cryptographic key,
+and you cannot finalize a task without the final chain key.
+
+## Why this exists
+
+Long-context agents lose track of plans. A 15-step refactor becomes 12 steps in the
+agent's memory by the time it reaches step 9. Context compression drops the original
+plan. A Sub Agent claims "all done" when it skipped step 7.
+
+The Gate solves this by moving the plan ledger **outside** the agent's context. The plan
+lives in SQLite. Each step is locked behind a 6-character key. The key appears only once
+in the checkpoint response — if the agent loses it, the step cannot be faked.
+
+## Core rule
+
+**One interaction = One Task.** At the start of each interaction, create a Task with the
+steps you plan to do. Before the interaction ends, checkpoint every step and finalize
+the Task. The Stop Hook will block exit if a Task is left unfinalized.
+
+```
+Interaction start → start-plan → checkpoint × N → finalize(taskKey) → done
+```
+
+Node and Program layers are optional — most work only needs the Task level.
+
+## CLI reference
+
+All commands return JSON. The CLI binary is at `node dist/cli.js` from the project root.
+
+### Task commands
+
+**start-plan** — Create a task for this interaction
+```bash
+node dist/cli.js start-plan '{"title":"What this task does","steps":[...]}'
+```
+Each step: `id` (optional), `title` (required), `dependsOn` (string array or omit for
+auto-serial), `children` (nested container). First call auto-creates session files.
+Returns `taskId`, `currentSteps`, and `stepKeys`.
+
+**checkpoint** — Complete a step and unlock its dependents
+```bash
+node dist/cli.js checkpoint '{"taskId":"tsk_XXX","stepId":"tsk_XXX_yy","stepKey":"KEY"}'
+```
+The key is consumed on use — it cannot be reused. Returns `nextSteps` + `nextStepKeys`
+for newly unlocked steps. When all steps are done, returns `allStepsCompleted: true` and
+a `taskKey`.
+
+**current** — Read current progress (does NOT return keys)
+```bash
+node dist/cli.js current '{"taskId":"tsk_XXX"}'
+```
+
+**finalize** — Complete the task and auto-propagate upward
+```bash
+node dist/cli.js finalize '{"taskId":"tsk_XXX","taskKey":"KEY"}'
+```
+Verifies the taskKey, marks the task completed, then automatically checks whether the
+parent Node (if any) and Program are also complete. Returns a `level` field: `task`,
+`node`, or `program`.
+
+**cancel-task** — Cancel the current session's task
+```bash
+node dist/cli.js cancel-task '{"taskId":"tsk_XXX"}'
+```
+Session-gated — you can only cancel your own tasks. Cross-session cancel requires
+`--admin --recovery-token <token>`.
+
+**active-task** — List active tasks
+```bash
+node dist/cli.js active-task          # current session only
+node dist/cli.js active-task --all    # all sessions
+```
+
+### Program commands (cross-session projects)
+
+```bash
+node dist/cli.js program init '{"title":"Big project","nodes":[...]}'
+node dist/cli.js program start '{"programId":"pgm_XXX","nodeId":"phase-1"}'
+node dist/cli.js program status '{"programId":"pgm_XXX"}'
+```
+
+Program finalization is automatic — when the last Task in the last Node is finalized,
+the system propagates completion all the way up. No manual `program finalize` needed.
+
+**program rebuild** — Rebuild node/program after plan changes (dry-run first, then `--confirm`)
+```bash
+node dist/cli.js program rebuild '{"programId":"pgm_XXX"}'          # dry-run
+node dist/cli.js program rebuild '{"programId":"pgm_XXX"}' --confirm
+```
+
+Always show the user the dry-run output and get confirmation before running `--confirm`.
+
+### Diagnostics
+
+```bash
+node dist/cli.js gate reconcile                   # full read-only health check
+node dist/cli.js gate reconcile '{"programId":"pgm_XXX"}'  # scoped to one program
+```
+
+## DAG rules
+
+**Example — parallel branches + merge point:**
+```bash
+node dist/cli.js start-plan '{
+  "title":"Backend refactor",
+  "steps":[
+    {"id":"auth","title":"Auth module","dependsOn":[]},
+    {"id":"api","title":"API layer","dependsOn":[]},
+    {"id":"db","title":"DB migration","dependsOn":["auth"]},
+    {"id":"test","title":"Integration tests","dependsOn":["api","db"]}
+  ]
+}'
+# auth + api activate immediately; db waits for auth; test waits for api + db
+```
+
+| dependsOn | Behavior |
+|-----------|----------|
+| `[]` (explicit empty) | Parallel entry — activated immediately |
+| omitted / undefined | Auto-serial — depends on previous leaf |
+| `["a", "b"]` | Merge point — unlocks after both a and b complete |
+| Container with children | Children inherit the container's dependsOn |
+| `skipKey` + `skipTaskId` | Skip a previously completed step (one-time use) |
+
+Cycle detection runs at plan creation time — circular dependencies are rejected before
+any step starts.
+
+## Interruption recovery
+
+When a session is interrupted, completed steps are permanent cryptographic proofs:
+
+```bash
+# Rebuild with skipKey to jump past already-completed steps
+node dist/cli.js start-plan '{
+  "title":"Resume wave 2",
+  "steps":[
+    {"id":"auth","title":"Auth module","dependsOn":[],"skipKey":"OLD_KEY","skipTaskId":"tsk_OLD"},
+    {"id":"ci","title":"CI tests","dependsOn":["auth"]}
+  ]
+}'
+```
+
+A skipKey can only be consumed once — the system writes a `skip_key_consumed` event on
+first use and rejects subsequent attempts. Skipped steps are marked `skipped` (not
+`completed`) to preserve traceability.
+
+## Key rules
+
+1. Keys appear exactly once — in the checkpoint or start-plan response. If lost, they
+   cannot be recovered. The `current` command never returns keys.
+2. Step double-consumption is impossible — the DB transaction uses `WHERE status='current'`
+   with an affected-rows guard.
+3. Cancel-task is session-gated — agents cannot cancel tasks they don't own.
+4. SkipKey is one-time — the `events` table records every consumption.
+5. Cycle detection runs at plan creation — dead DAGs are rejected before execution.
+
+The Gate is a proof-of-completion system, not a security product. It protects against
+agent hallucination, context loss, and accidental step-skipping. It does not protect
+against deliberate external attack.
+
+## Session files
+
+The first `start-plan` call creates:
+- `.step-gate/sessions/ses_XXXXXX.json` — session credentials
+- `.step-gate/bindings/bind_cli_XXXXXX.json` — hook binding
+
+The CLI auto-discovers the session from binding files. No manual session management needed.
+
+## Further reading
+
+- `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

@@ -0,0 +1,140 @@
+# Weaver — Step Gate 编排引擎
+
+## 三层角色
+
+```
+Main Agent (编排者)       ← 持有 Node/Program 全局视角
+  │                          只做三件事: 派发、校验、推进
+  │                          不写代码、不执行 Step
+  │
+  ├── Sub Agent A            ← 只知道自己的 taskId + taskGoal
+  ├── Sub Agent B            ← 不知道其他 Task、不知道 DAG
+  └── Sub Agent C            ← 不知道 Node/Program 全局
+```
+
+Sub Agent 的上下文由 Main Agent 在 Spawn 时精确注入。看不到全局计划，不知道前后 Task，不持有验证逻辑。
+
+## 完整执行流程
+
+```
+═══════════════════════════════════════════════════════
+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 校验 + 自动推进
+═══════════════════════════════════════════════════════
+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 → 派发 → 循环
+
+═══════════════════════════════════════════════════════
+收尾
+═══════════════════════════════════════════════════════
+最后一个 Node 完成:
+  finalize → level="program" → Program completed
+  收工
+```
+
+## 关键设计点
+
+**Main Agent 只调一个命令**：`finalize(taskKey)`。剩下的系统自动从 Task → Node → Program 传播。
+
+**TaskKey 校验即消费**：finalize 会消耗 taskKey 并推进 DAG，不存在"校验通过但不推进"的状态。
+
+**Sub Agent 不需要知道**：
+- taskId 的结构含义
+- 完整的 DAG
+- 前后 Task 是什么
+- Node/Program 全局
+- 验证逻辑（系统自己校验）
+
+**中断恢复**：taskId + skipKey 重建，旧 step 凭证永久保留。
+
+**纯 Task 模式**：不用 Program/Node 时，只需 `start-plan → checkpoint → finalize`。每个交互一个 Task，交互结束 Stop Hook 自动检查。
+
+## 渐进式披露
+
+```
+SKILL.md (执行协议)         ← 所有 Agent 必读，基础 CLI 命令
+  └─ Weaver.md (编排引擎)   ← Main Agent 读，如何编排 Sub Agent
+       └─ CLI (状态机)       ← 底层实现
+            └─ SQLite (持久化)
+```
+
+Sub Agent 只需要 SKILL.md 中的 CLI 命令，不需要 Weaver.md。
+Main Agent 需要 SKILL.md + Weaver.md。

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};