@roarpeng/graphflow
面向编码代理的本地优先记忆与上下文工具
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add @roarpeng/graphflow@1.25.1Graphflow 以 @roarpeng/graphflow 发布，当前版本为 1.25.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 中文
The memory & context harness for coding agents. Local-first code knowledge graph · bounded context compression (truly bounded responses: the package plus history echoes, which ship as short previews only; 95.6% vs a realistic top-K-files read, see both baseline arms) · cross-session learning flywheel.
The community is converging on an "agent harness" vocabulary: memory + hooks + skills are the harness primitives that turn a stateless model into a reliable long-running agent. GraphFlow implements all three for coding agents and ships them through a portable MCP surface (Cursor, Claude Code, 15+ agents):
| Harness primitive | GraphFlow implementation |
|---|---|
| Memory | 12-language AST code graph + Episodic / Skill / Decision nodes — project knowledge and project experience persist across sessions |
| Hooks | Outcome auto-capture (on by default) + Claude Code SessionEnd / Stop and DeepSeek Harness agent/disposed glue close the learning loop automatically — no manual outcome reporting required |
| Skills | A four-class flywheel (proven / correctable / anti-pattern / noise) with canary validation — skills are promoted by evidence, not by assertion |
Pure TypeScript/Node. CLI + MCP + VS Code extension. Fully offline, no API key required.
Most "memory" products are either static injection (load CLAUDE.md / rules files in full on every session) or plain RAG (retrieve chunks, no learning). Both fail in long-lived projects:
GraphFlow is a harness: memory is dynamic and typed. Each request retrieves only what the current decision needs — graph anchors, compressed summaries, similar past episodes, applicable skills — under an explicit token budget (L0–L3 layered compression; measured against a realistic top-K-files read, see benchmarks/RESULTS.md). What the agent learns (outcomes, lessons, skills) is written back through hooks, so the harness gets better with use.
It is also local-first and portable: everything runs offline with no API key, and the whole surface is exposed over MCP, so the same memory travels across agents instead of being locked into one vendor's format.
Third-party reproduction entry: npm run proof:flywheel — one command, offline, no API key. Guide: docs/flywheel-reproduction.md. Independent runs are welcome; open a GitHub issue titled [benchmark] Independent reproduction — <commit>.
All headline numbers come from a public, reproducible benchmark suite (benchmarks/README.md) with published methodology (docs/benchmark-standards.md) and machine-readable JSON dumps pinned to commits. Authoritative percentages live in the tracked RESULTS markdown; this package does not invent new scores.
gpt-tokenizer): 95.6% against the fair counterfactual (the same ranker's top-10 anchors resolved to real files and read in full: 136,265 → 6,044 tokens) and 98.5% against a naive term-frequency grep baseline (410,725 → 6,044), whose denominator is an upper bound by construction. The realistic arm cannot inflate itself: anchors pointing at fewer or smaller files make its savings smaller. Details: benchmarks/RESULTS.mdbenchmarks/datasets/retrieval-golden-v1.json — run npm run bench:retrievalResults are commit-anchored so any number above can be checked out and re-run. See ROADMAP.md for the open invitation.
Shared and synced memory is only useful if it cannot be silently corrupted. Skills merged from external sources (e.g. skill sync imports) are treated as unproven until validated locally: imported skills carry provenance markers, never enter the proven class directly, must pass canary validation on real tasks before promotion, and anti-pattern skills are isolated rather than deleted so they can be audited. Promotion is gated by the four-class lifecycle, not by trust in the source. See docs/team-memory-security.md.
No API key needed (offline AST indexing + graph compression):
# 1. Build the graph offline (AST indexing, no LLM)
npx @roarpeng/graphflow graph index .
# 2. Preview compressed context (anchors + summaries, 90%+ token savings)
npx @roarpeng/graphflow context preview "orchestrator" --json
Connect via MCP (Cursor / Claude Code / …):
{
"mcpServers": {
"graphflow": {
"command": "npx",
"args": ["-y", "--package=@roarpeng/graphflow", "graphflow-mcp"]
}
}
}
The agent calls graphflow_context for compressed context, then graphflow_plan to plan; without a provider API key GraphFlow automatically bridges the ATP thinking protocol to the host agent (agent-delegated mode). For symbol-precise edits, compose Serena as a second MCP server — GraphFlow + Serena (examples/graphflow-serena.mcp.json).
Single-purpose tools each do one thing well; GraphFlow combines graph + compression + planning protocol + learning memory in one place:
| Capability | GraphFlow | CodeGraph | Serena | Repomix |
|---|---|---|---|---|
| Code graph | 12-language AST index | more mature | LSP symbols | — |
| Context compression | layered + graph compression + vector recall | partial | partial | whole-repo dump |
| Planning protocol | ATP IR + DAG + agent bridge | — | — | — |
| Learning memory | Episodic / Skill / Decision flywheel | — | — | — |
| Local-first | ✅ | ✅ | ✅ | ✅ |
| Open protocol | ATP/IR public spec | — | — | — |
The differentiator is the learning flywheel: graph indexing and token compression are replicable; project-private experience (skills, lessons, decisions) accumulated across sessions is not — it compounds with use. Serena is a complement, not a competitor — see GraphFlow + Serena: better together (中文; comparison).
| Module | Capability |
|---|---|
| Planning protocol | ATP v1.1 (Intent / Requirement / Six Hats / 5-Why / First Principles / Decision Matrix / Planning / Reflection); simple / complex / insight modes; agent-delegated bridge without an LLM; skill-conditioned DAG (skillRefs / avoidPatterns on plan nodes); ATP/IR public spec v1.1 |
| Goal alignment | Goal anchor nodes (intent five-tuple as first-class citizen, original requirement auto-injected); low-confidence clarification gate (no plan below 0.6); runtime alignment-check; deviation classification (misread-requirement / scope-creep / tech-drift); goal version chain + diffs |
| Knowledge graph | 12-language AST indexing; File / Module / Symbol + Concept / Requirement; cross-layer edges documents / implements / derived_from; Office/PDF → Markdown via optional @firecrawl/anydoc (MIT). CLI/npm: optionalDependency. VSIX: not bundled; on activate the extension auto-downloads the current-OS binary into ~/.graphflow/optional-deps when graphflow.downloadAnydoc is true (default). Disable the setting to skip network; source indexing still works. |
| Context compression | L1/L2/L3 layered anchors; graph compression (edge weights + PageRank, LRU cache); stem-matching recall (orchestrate ↔ orchestration); vector recall + RRF; RepoMap overview; adaptive budget; post-packaging accounting (out-of-package payloads are honestly counted: dialogue recall hits and workbench/dialogue preview echoes land in unbudgetedTokens; accountedTokens = compressed + unbudgeted and estimatedSavingsPercent is computed on that true delivered total, with estimatedRawTokens floored at it; responses are bounded — history echoes are ~160-char message previews with a truncated flag, full text stays in the graph and expands via anchorId or the VS Code panel; recordDialogue: false disables echo and recording entirely) |
| Efficiency mechanisms (SoL-Pi borrow) | ObservationPack (oversized outputs → content-addressed handle + exact paged recall), (log → bounded receipt whose retained lines are re-verified verbatim), (observed-pressure budget + economic compaction signal), (fused edit+validate steps on the bridge descriptor). , individually switchable in ; rewrites over-budget tool results on the model surface ( to disable); paired ( + thresholds); (, held-out isolation). See |
GraphFlow is not an orchestrating executor — it is the memory & context harness for coding agents. Task execution is delegated to the host coding agent via bridge mode (honest semantics, no faked COMPLETED); GraphFlow's job is to make the agent see clearly and remember.
| Tool | Function |
|---|---|
graphflow_context | Compressed context package (query → anchors + summaries; topicId / assistantReply to resume a workbench node or fill the pending answer; anchorId → expand) |
graphflow_plan | Task planning (mode='simple' or 'insight'; seeds workbench.topics + workbench.outline; agent-delegated without an LLM) |
graphflow_run | Orchestration + bridge execution descriptor |
graphflow_report_outcome | Outcome backfill (incl. deviation classification), closes the learning flywheel |
graphflow_insight | ATP insight submit / merge (agent bridge protocol) |
graphflow_index | Incremental / full indexing; optional knowledgeExtract: true distills dialogue turns into Concept / Requirement nodes with provenance edges |
graphflow_skill_insights | Skill insights |
graphflow_diagnose | Diagnostics (provider + graph + token savings + flywheel + graph.workbenchOutline) |
graphflow_artifact | Graph artifact import / export |
graphflow_skill_guide | GraphFlow skill usage guide |
MCP workspace resolution: the workspace is discovered automatically from the MCP client cwd; override with GRAPHFLOW_WORKSPACE_ROOT.
Everyday chat stays a single thread. Complex work seeds a workbench of function-topic containers from graphflow_plan — one canvas node per plan step, not one node per turn. Click a node and pass topicId to graphflow_context to refine that function or return to the mainline. Drift auto-forks an isolated side branch (co_occurs); the trunk is not overwritten. After answering, call graphflow_context({ assistantReply }) so the original reply is stored. Outline titles are display labels only; next-turn context is Goal + ancestor titles + the node's original Q/A.
Wake the collapsed outline when you need it (still 10 MCP tools):
graphflow workbench tree --json # CLI
# VS Code / Cursor: GraphFlow: Workbench Tree (Activity Bar, default collapsed) or chat /tree
# MCP: graphflow_diagnose → graph.workbenchOutline
graphflow context preview --topic-id "<topic:...>" "continue from this node"
graphflow context preview --reply "original assistant answer"
graphflow graph index . # build the graph
graphflow context preview "orchestrator" # preview compressed context
graphflow plan "refactor planner" --json # plan (also seeds workbench topics)
graphflow workbench tree --json # on-demand function DAG + side branches
graphflow run "update readme" # orchestrate (bridge)
graphflow skill insights # skill insights
graphflow skill report # flywheel contribution report
graphflow mcp serve --http # stateless MCP Streamable HTTP (add --stateful for SSE sessions)
graphflow team serve # team graph JSON-RPC (tenant + RBAC; non-loopback requires auth)
graphflow outcome backfill --evidence evidence.jsonl # close pending episodes with evidence packages
graphflow governance release-gate # enforce proven-skill/fidelity/pending gates
graphflow skill sync export # export team skill pack + golden queries (share via git)
graphflow skill sync import # import team skill pack (MERGE; --force to overwrite) + golden merge into .graphflow/team-golden.json
graphflow challenge --files a.ts,b.ts # R8-2: graph-diff challenge list after edits (callers / requirements / deleted symbols)
graphflow audit # R9: closing audit — dangling deps / unwired files / unreferenced configs / doc drift
graphflow route diagnose # routing diagnostics
graphflow learn nightly # nightly learning
graphflow doctor # install self-check
Three-layer merge: global ~/.graphflow.config.json → project graphflow.config.json → project .graphflow/config.json. Copy graphflow.config.example.json to get started.
Key options:
| Option | Description |
|---|---|
graphPolicy.transport | file / memory / sqlite / auto (recommended: sqlite-first, falls back to file) / mcp-http |
graphPolicy.maxContextTokens | Context budget (default 1500) |
graphPolicy.autoIndexOnSave | Auto incremental index on save (default true) |
embeddingPolicy.provider | transformers (local default) / openai / hash |
embeddingPolicy.vectorStorePath | Vector index persistence path (.hnsw derived automatically) |
skillPolicy.enableSkillFlywheel | Learning flywheel switch |
Set graphPolicy.transport to mcp-http to host the graph on a remote Graphify service (shared by the team); requires graphPolicy.mcpEndpoint (http(s) URL, optional mcpApiKey bearer token):
{ "graphPolicy": { "transport": "mcp-http", "mcpEndpoint": "http://graphify.team.internal:8080" } }
A missing/malformed endpoint fails at config validation; connection or runtime request failures degrade transparently to local JSON storage (graphPolicy.graphStorePath, default graphflow-out/graphflow-graph.json) with a logger.warn, consistent with the sqlite→file fallback, never interrupting the agent. HTTP 401/403 (auth / RBAC deny) do not degrade — they throw. graphflow team serve implements graph.read_snapshot and team.health; third-party Graphify servers without those methods still fall back to the local mirror. See docs/team-memory-security.md.
Download graphflow-<version>.vsix from GitHub Releases (or Open VSX: roarpeng.graphflow).
Commands: Settings / Show Graph (graph visualization) / Preview Context / Plan & Brainstorm / Run Task / Skill Insights / Install MCP; chat agent @graphflow (/run /plan /graph /skills /diagnose /learn /history).
Primary install path for hosts that support Agent Plugins. GraphFlow ships as a portable package at the repository root:
plugin.json # Agent Plugins 1.0 manifest
mcp.json # stdio MCP (type required by the spec)
skills/graphflow/SKILL.md
Install in Cursor (local):
mkdir -p ~/.cursor/plugins/local
ln -s /absolute/path/to/GraphFlow ~/.cursor/plugins/local/graphflow
# then Restart Cursor / Developer: Reload Window
Install via Team Marketplace / Git: import this repository; clients discover plugin.json, then load skills/ and mcp.json.
Docs: Context Engineering contract · Experience memory
Uninstall: Removing the Agent Plugin in Cursor only drops the plugin package. Skills/Rules/MCP written by graphflow install remain and will keep steering the agent — run:
npx @roarpeng/graphflow uninstall
That removes user + workspace MCP entries, skills/graphflow folders, GraphFlow rules/instruction blocks, Claude Code hooks, and the DeepSeek Harness cordis.patch.yml overlay. Also delete any local symlink under ~/.cursor/plugins/local/graphflow if you used one.
GraphFlow 是 DeepSeek Harness 的 dsh-plugin。包内 dsh.bundle + cordis.patch.yml 会把 GraphFlow MCP 挂到内置 @deepseek-ai/dsh-mcp-client，并把 @roarpeng/graphflow/dsh glue 插入插件树。模型看到的工具名是 mcp__graphflow__graphflow_*。中文说明见 README.zh.md。
在 dsh 上能工作 vs 不能工作：
| 能力 | dsh |
|---|---|
10 个 MCP 工具（mcp__graphflow__graphflow_*），stdio cwd = 会话工作区 | 是 |
Skill（on-demand skill({name:"graphflow"})；bundle glue 注册，不必先 graphflow install） | 是 |
会话结束飞轮：仅 agent/disposed 关闭 pending episode（不是 live session/flush；GRAPHFLOW_AUTO_CAPTURE=0 可关） | 是 |
首轮短 hint：先调 graphflow_context（rootDir = cwd） | 是 |
Workbench 数据（topicId / outline）经 MCP graphflow_context / graphflow_diagnose | 是 |
VS Code/Cursor 图谱面板、Settings webview、Workbench Tree、@graphflow chat | 否（宿主 UI，不移植） |
| Cursor Agent Plugins 1.0 发现 | 否（dsh 用 dsh.bundle） |
Claude Code SessionStart/End/Stop 文件 hooks | 否（dsh analog 是上面的 glue） |
装进某个 profile（推荐）：
dsh plugin --profile web add @roarpeng/graphflow
npx @deepseek-ai/dsh web
从插件市场安装（一键）： GraphFlow 已按 dsh-plugin 收录规范 打标（dsh-plugin / cordis-plugin / deepseek-harness），市场每 2 小时自动扫描该 topic，可在 DSH 插件市场 或 DSH-Plugins-Marketplace 里搜 GraphFlow 一键安装。
从 GitHub 安装（跟随 main 分支）：
dsh plugin --profile web add github:Roarpeng/GraphFlow
⚠️ 只选一条注册路径：市场 /
dsh plugin … add会自动把dsh.bundle的cordis.patch.yml注册进 profile；此时不要再跑npx @roarpeng/graphflow install（它会写$DSH_HOME/cordis.patch.yml这层 overlay），两条注册叠加会导致重复加载。反之，用了 home overlay 就不必再 add。
市场收录类型： cordis-plugin（package.json 的 dsh.bundle.patch → cordis.patch.yml）。仓库不提交 dist/（源码型），市场安装时会先询问「安装依赖并执行构建」，确认后执行 npm install + npm run build（构建离线可用）。
披露（disclosure，STANDARD §9）： 本地优先——索引、压缩、召回、图存储全部离线（默认 resilient local 语义向量：优先本地 Xenova/bge-base-zh-v1.5，失败降级 FNV-1a hash，可用 embeddingProvider: "fnv" 强制纯离线），cloud: false 场景可用；仅当你为 graphflow_plan / graphflow_run 配置了 LLM provider 时才访问云端端点（api.deepseek.com / api.openai.com / api.anthropic.com / dashscope.aliyuncs.com / ark.cn-beijing.volces.com）。API Key 只从环境变量或全局配置读取，全局配置 ~/.graphflow.config.json 以 0600 权限写入，日志中脱敏。可执行核验：graphflow audit --privacy（见 docs/threat-model.md）。完整字段见 package.json 的 disclosure。
或在已有 ~/.dsh 时写 home 级 overlay（对所有 profile 生效）：
npx @roarpeng/graphflow install
会写入 $DSH_HOME/cordis.patch.yml（MCP + glue）与 $DSH_HOME/skills/graphflow/SKILL.md。卸载：npx @roarpeng/graphflow uninstall，或 dsh plugin --profile web remove @roarpeng/graphflow。graphflow doctor 会检查 overlay、glue、skill。
用法： 第一轮先 mcp__graphflow__graphflow_context（传入 rootDir = 仓库绝对路径），复杂任务再 graphflow_plan；改完代码后 graphflow_index；若走了 graphflow_run，结束后必须 graphflow_report_outcome。不要在 patch 里写死 GRAPHFLOW_WORKSPACE_ROOT。
npm install -g @roarpeng/graphflow # one command including the install: global postinstall registers, checks, and repairs automatically
npx @roarpeng/graphflow@latest doctor # self-check: list agents detected on this machine
npx @roarpeng/graphflow@latest install # register into every detected agent (idempotent, safe to re-run)
npx @roarpeng/graphflow@latest uninstall # remove the registration from every agent
install scans the detection markers of all 20 hosts (~/.zcode, ~/.cursor, ~/.claude, ~/.codex, ~/.config/opencode, …) and writes a three-piece set into every host it finds (paths shown for ZCode; every host is owned by the HostAdapter registry):
| Registered | Location | Content |
|---|---|---|
| MCP server | ~/.zcode/cli/config.json → mcp.servers.graphflow | stdio launch of graphflow-mcp (10 tools) |
| Skill | ~/.zcode/skills/graphflow/SKILL.md | on-demand graph-context skill |
| Global instructions | ~/.zcode/AGENTS.md (managed block) | GraphFlow context-first rule (append-with-markers, user content untouched) |
Notes:
onnxruntime-node, hundreds of MB on Windows) on first run and can exceed the connect timeout. Fix: npm install -g @roarpeng/graphflow, then re-run install — when a global install is detected the injector writes a direct node + server.js entry (sub-second launch, no network dependency); without one it falls back to the npx entry.npm install -g @roarpeng/graphflow, then plain graphflow install / graphflow doctor.dsh plugin --profile web add @roarpeng/graphflow — pick one registration path, never both (double loading).Use npx @roarpeng/graphflow install as the fallback when you need Rules, multi-agent wiring, or a host that does not load Agent Plugins:
npx @roarpeng/graphflow doctor # detect installed agents
npx @roarpeng/graphflow install # auto-install MCP + Skill + Rules
npx @roarpeng/graphflow uninstall # remove MCP + Skill + Rules + hooks
npx @roarpeng/graphflow init # write a minimal project config
Supported: Cursor, VS Code, Trae (incl. CN), Claude Code, Windsurf, Cline, Roo Code, Kilo Code, Gemini CLI, Codex, Antigravity, Opencode, Qoder, Amazon Q, Zed, Continue, DeepSeek Harness (dsh), Kimi Code CLI, ZCode, and more (15+). Every registered host goes through the HostAdapter registry (installViaHostAdapter); the legacy installers now only cover host-scoped extras (Trae user Skills, project-level rules).
| Path | When to use |
|---|---|
| Agent Plugins | Preferred single-host Skill + MCP discovery |
graphflow install | Rules / multi-agent / non-plugin hosts |
graphflow uninstall | After removing a plugin (or anytime) — clears leftover Skill/MCP/Rules |
ATP/IR — Agent Thinking Protocol public specification v1.0: work-item registry, submit/merge contract, compatibility rules. Third-party tools can implement compatible producers / consumers. Minimal Producer example: examples/atp-minimal-producer/. Dual-MCP compose snippet (GraphFlow + Serena, config only): examples/graphflow-serena.mcp.json.
GraphFlow is a single-maintainer project (bus factor = 1); community collaboration is the key to reducing single-point risk. Contributions welcome:
npm install
npm run ci # lint + build + tests + extension packaging + smoke
Requires Node.js ≥ 20, npm ≥ 10. Expected: lint clean, build succeeds, full vitest suite green.
GraphFlow/
├── plugin.json # Agent Plugins 1.0 manifest
├── mcp.json # Agent Plugins MCP (stdio)
├── cordis.patch.yml # DeepSeek Harness (dsh) bundle layer (MCP + glue)
├── dsh/plugin.mjs # dsh ESM glue: skill register + session-end capture
├── skills/graphflow/ # portable Agent Skill (canonical SKILL.md)
├── src/
│ ├── core/ # orchestration core: orchestrator, triage, dag-engine, agent-delegation
│ ├── graph/ # indexing, context slicing, graph compression, sqlite/auto storage, snapshot
│ ├── routing/ # model routing and health probes (5 providers)
│ ├── learning/ # embeddings, episodic, skill-flywheel, hnsw, nightly
│ ├── agents/ # ATP schema, planner, insight, brainstormer
│ └── surfaces/
│ ├── cli/ # CLI + runtime
│ └── mcp/ # MCP server (10 tools)
├── tests/ # vitest suite (unit + governance + MCP HTTP/stdio matrix)
├── benchmarks/ # comprehensive + independent + SWE-bench + token savings + skill A/B (reproducible)
├── docs/ # ATP spec + context contract + experience memory + flywheel reproduction + GraphFlow/Serena
├── examples/ # ATP producer + team-memory config + GraphFlow/Serena dual-MCP snippet
├── vscode-extension/ # VS Code panel and commands
└── CHANGELOG.md
Full history in CHANGELOG.md. License: Apache-2.0.
GRAPHFLOW_D_DSH_PROJECTION=0graphflow-out/efficiency.jsongovernance release-gategraphflow mechanism| Retrieval & fidelity | Golden-set regression gate (132 queries, Hit@5=100%, MRR=0.779, NDCG@5=0.638); separate anchor-recall and normalized body-coverage metrics persisted beside token savings |
| Vector index | In-process memoization + disk persistence (fingerprint-checked, seconds to restore after MCP restart) |
| Storage backends | file / memory / sqlite (FTS5, tokenizer-enhanced searchtext, camelCase searchable) / auto (sqlite-first with fallback) / mcp-http |
| Learning flywheel | Episodic memory, reflection, skill nodes (score ±1, bounded [-20,20]), nightly training, adaptive evidence-aware forgetting, auto-capture + Claude Code hooks (on by default), SkillOpt-lite bounded guidance edits, four-class lifecycle + canary gate for synced skills, portable SKILL.md import/export (agentskills.io spec layout: one dir per skill + progressive-disclosure references/), auditable efficiency evidence (graphflow efficiency export → graphflow-out/efficiency-evidence.json), npm run backfill:episodes, contribution reports (skill report / graphflow_diagnose / route diagnose) |
| Team sharing | graphflow team serve (tenant + RBAC) + skill sync export/import/push/pull; imports/pulls are a bidirectional MERGE; golden queries via .graphflow/team-golden.json; security model + ops runbook |
| Benchmarks | Comprehensive 92.9% · Independent-style 96.2% · context-readiness eval · token savings with two baseline arms — 95.6% realistic / 98.5% naive grep |
| Model routing | Smart / Economy tiers; multi-provider health probes and fallback (DeepSeek, OpenAI, Anthropic, Bailian, Doubao) |
| Workbench | Plan DAG seeds function-topic containers; collapsed outline; click topicId to resume; drift forks a side branch; original Q/A stored via assistantReply |
| Observability | graphflow_diagnose / route diagnose: provider health + graph stats + token savings + flywheel health (auto-capture, episodes, skills by class, session journal) + workbench outline |
| Agent surfaces | CLI --json; MCP stdio and Streamable HTTP (stateless JSON or stateful SSE, 10 tools); auto-install into 15+ agents (incl. Codex Windows NODE/NPX_CLI short-path MCP). HostAdapter registry owns install · uninstall · doctor for every registered host: 4 hand-written slices (Cursor / Claude Code / DeepSeek Harness / Kimi Code) + a generic profile-backed slice for the rest |
| Evidence & governance | Outcome evidence packages (commit/diff/tests), evidence backfill, tamper-evident audit chains, ADR/Invariant/APIContract/Test review states, artifact three-way merge/signing/encryption, retention/quarantine, release gates |
| Closing audit / promise ledger (R9) | Cures "干着干着就忘了": obligations derived from observable side effects — dependency-lock consistency (npm v1/v3, pip+poetry/Pipfile), orphan files with zero graph wiring, declarative graphflow.audit.json rules (driver loading / container injection: filePattern + mustBeReferencedBy globs), doc drift (CLI vs README, version badge). Baseline = uncommitted git working tree (--since <ref> to widen). Touchpoints: graphflow audit CLI; automatic pre-check before report_outcome success (advisory, or refusing via GRAPHFLOW_AUDIT_STRICT=1); cross-session reminder — the first graphflow_context of a session surfaces "上次会话有 N 项未收尾" from the on-graph promise ledger. See docs/closing-audit.md |
| Savings & reliability duo (R8) | working-set prefetch (kill exploration turns — each turn re-pays the whole history), challenge graph-diff questions (the graph knows every caller the agent does not), spawn-receipt (subagents inherit anchors, not copied context), facts ask temporal lookup (effective vs superseded at a point in time), quote honest task budget from paired-efficiency history |
| Engineering quality | TypeScript strict; vitest suite; npm run ci includes extension packaging and smoke tests |