driftseal 3.3.0 → 3.4.0

package/README.md

@@ -2,11 +2,14 @@
 
 > **Seal the outcome. Stop the drift.**
 
-DriftSeal is a repository-local protocol and toolchain for keeping coding agents
-anchored to a coherent delivery outcome. It records the outcome before durable
-work begins, permits append-only extensions toward that same outcome, binds
-verification to the accumulated contract, and preserves only the decisions that
-need durable rationale.
+![DriftSeal: a precision metal seal anchors engineering documents to one delivery outcome.](docs/images/driftseal-hero.png)
+
+DriftSeal is an engineering protocol and toolchain for coding agents executing
+long tasks independently, with state kept in the repository. It keeps work
+anchored to a coherent delivery outcome: record the outcome before durable work
+begins, append extensions toward that same outcome, bind verification to the
+accumulated contract and workspace, and preserve the decisions that need durable
+rationale.
 
 ```text
 begin an outcome → extend the same outcome → verify the cumulative contract → close
@@ -16,6 +19,19 @@ One worktree owns one open outcome. Git records what landed; DriftSeal records
 what the work was meant to achieve, how completion was proved, and why durable
 decisions were made.
 
+## When to use DriftSeal
+
+Use DriftSeal when an agent needs to carry a multi-step engineering task through
+to completion without continuous human guidance. Explicit acceptance criteria,
+cumulative verification, and decision reconciliation provide a structured way to
+track delivery and resume the same contract after context loss or handoff.
+
+That rigor adds process overhead. When a person is actively reviewing progress,
+clarifying scope, and guiding the agent, we recommend
+[Inkan](https://github.com/rowan-hiro/inkan) as the lighter option. It records
+delivery intent, changes, and declared results while leaving evaluation to the
+person and the repository's normal tests.
+
 ## What changed in v2
 
 DriftSeal v2 is an outcome log rather than an intent-per-step log.
@@ -30,8 +46,8 @@ DriftSeal v2 is an outcome log rather than an intent-per-step log.
   and MADR reconciliation.
 - Stored events use `logVersion: 2`. Compatible clients accept `schemaVersion`
   `1` or `2`; lane events and non-default `begin.lane` use `schemaVersion: 2`.
-- The generated `AGENTS.md` protocol series is `2.1`. `driftseal init` upgrades
-  recognized `2.0` blocks.
+- The generated `AGENTS.md` protocol series is `2.2`. `driftseal init` upgrades
+  recognized `2.0` and `2.1` blocks.
 - Named lanes partition outcome history on the same WAL. The default lane is
   `main`; `driftseal log` follows the current lane.
 - The public CLI, Node API, MCP tools, and MCP resources use outcome terminology.
@@ -75,6 +91,8 @@ may still write `.seal/outcomes/.gitignore` so derived sidecars stay untracked.
 
 ## Core workflow
 
+![One outcome progresses through begin, extend, verify, and end, accumulating changes before verification.](docs/images/driftseal-workflow.png)
+
 Open the coherent delivery outcome before changing durable project content:
 
 ```sh
@@ -98,6 +116,13 @@ verifier or replace it. Every extension invalidates previous machine evidence.
 If the delivery outcome itself changes, close the current outcome honestly and
 begin another one.
 
+When the agent is in plan mode, write every `driftseal` command this work will
+run into the plan file as an explicit command. Closing commands may leave
+status and note as placeholders. As soon as plan mode ends, re-anchor before
+any other action. End an unrelated open outcome before any lane switch. Switch
+lanes when this work belongs to another lane. Then `begin` or `extend` to
+match that re-anchored state.
+
 Before completion:
 
 ```sh
@@ -118,6 +143,8 @@ driftseal status
 driftseal log --last 3
 ```
 
+![Resume the same outcome across a context boundary by reading driftseal status and driftseal log --last 3.](docs/images/driftseal-continuity.png)
+
 ## What needs an outcome
 
 Record an outcome for durable project-content changes: code, configuration,

package/README.zh-CN.md

@@ -2,10 +2,12 @@
 
 > **Seal the outcome. Stop the drift.**
 
-DriftSeal 是一套跟随 repo 保存的协议与工具，用来让 coding agent 始终围绕一个
-完整的交付 outcome 工作。它要求在持久改动开始前记录 outcome，允许以 append-only
-方式补充同一 outcome 的后续步骤，把验证结果绑定到累计 contract，并只为确实需要
-长期保留理由的选择建立 MADR。
+![DriftSeal：精密金属封印将工程文档锚定在同一个交付目标上。](docs/images/driftseal-hero.png)
+
+DriftSeal 是一套面向 Agent 独立执行长任务的工程化协议与工具链，状态随 repo 保存。
+它让 coding agent 始终围绕一个完整的交付 outcome 工作：在持久改动开始前记录
+outcome，以 append-only 方式补充同一 outcome 的后续步骤，把验证结果绑定到累计
+contract 和工作区，并只为确实需要长期保留理由的选择建立 MADR。
 
 ```text
 开启 outcome → 扩展同一 outcome → 验证累计 contract → 关闭
@@ -14,6 +16,16 @@ DriftSeal 是一套跟随 repo 保存的协议与工具，用来让 coding agent
 一个 worktree 只持有一个 open outcome。Git 记录最终落地了什么；DriftSeal 记录这轮
 工作想交付什么、如何证明完成，以及长期 decision 背后的理由。
 
+## 什么时候使用 DriftSeal
+
+当 Agent 需要在缺少人持续引导的情况下，独立推进并完成多步骤工程任务时，适合使用
+DriftSeal。明确的验收标准、累计验证和 decision reconciliation 为交付提供结构化
+约束，也让 Agent 在上下文丢失或交接后，可以回到同一份交付约定继续执行。
+
+这些工程化约束也会增加流程成本。如果有人持续审阅进展、澄清范围并引导 Agent，
+推荐使用更轻量的 [Inkan](https://github.com/rowan-hiro/inkan)。它记录交付意图、
+过程中的变更和结束时声明的结果，把结果判断留给人和仓库原有的测试流程。
+
 ## v2 的变化
 
 DriftSeal v2 从“按步骤记录 intent”改为“按交付记录 outcome”。
@@ -25,7 +37,7 @@ DriftSeal v2 从“按步骤记录 intent”改为“按交付记录 outcome”
 - 每次 extend 都会改变 contract hash，并让之前的 verification 与 MADR reconciliation 失效。
 - event 使用 `logVersion: 2`。兼容客户端接受 `schemaVersion` `1` 或 `2`；lane
   事件以及非默认的 `begin.lane` 使用 `schemaVersion: 2`。
-- `AGENTS.md` 的新协议版本是 `2.1`。`driftseal init` 会升级可识别的 `2.0` block。
+- `AGENTS.md` 的新协议版本是 `2.2`。`driftseal init` 会升级可识别的 `2.0` 和 `2.1` block。
 - 具名 lane 在同一条 WAL 上切分 outcome 历史。默认 lane 是 `main`；`driftseal log`
   跟随当前 lane。
 - CLI、Node API、MCP tool 与 resource 全部使用 outcome 命名；v1 名称和路径不会作为
@@ -68,6 +80,8 @@ attribute，并配置本地 Git merge driver。Git config 不会随 clone 传播
 
 ## 基本工作流
 
+![同一个 outcome 依次经过 begin、extend、verify 和 end，累积变更后统一验证。](docs/images/driftseal-workflow.png)
+
 在修改持久项目内容前，先开启完整的交付 outcome：
 
 ```sh
@@ -89,6 +103,11 @@ driftseal extend "Document recovery-link expiry" \
 acceptance 的 extend 可以沿用原 verifier，也可以替换它。任何 extend 都会让之前的
 machine evidence 失效。如果交付目标本身变了，应诚实关闭当前 outcome，再开启新的。
 
+Agent 处于 plan 模式时，要把这次工作将要运行的每条 `driftseal` 命令作为显式命令
+写进计划文件。结束命令的 status 和 note 可以写成占位符。plan 模式一结束，先重新
+锚定，再做其他动作。若已有无关的 open outcome，在切换 lane 之前结束它。工作属于
+另一条 lane 时再切换。然后按重新锚定后的状态执行 `begin` 或 `extend`。
+
 完成前依次执行：
 
 ```sh
@@ -109,6 +128,8 @@ driftseal status
 driftseal log --last 3
 ```
 
+![通过 driftseal status 和 driftseal log --last 3 读取持久记录，在上下文中断后继续同一个交付目标。](docs/images/driftseal-continuity.png)
+
 ## 哪些工作需要 outcome
 
 准备长期留在项目中的代码、配置、文档、依赖及同类文件改动需要 outcome。Git 操作、

package/bin/driftseal.js

@@ -56,7 +56,7 @@ const LOG_VERSION = 2;
 const EVENT_SCHEMA_VERSION = 2;
 const DEFAULT_WRITE_SCHEMA_VERSION = 1;
 const LEGACY_EVENT_SCHEMA_VERSION = 4;
-const PROTOCOL_VERSION = '2.1';
+const PROTOCOL_VERSION = '2.2';
 const DEFAULT_LOG_LANGUAGE = 'en';
 const DEFAULT_LANE = 'main';
 const LANE_NAME_RE = /^[a-z][a-z0-9-]{0,62}$/;
@@ -2698,17 +2698,40 @@ Seal root: \`.seal/\` (override with \`$DRIFTSEAL_HOME\`); outcome log:
 ${INTENT_PROTOCOL_END}`;
 }
 
-function intentProtocolBlockV21(version = PROTOCOL_VERSION, language = DEFAULT_LOG_LANGUAGE, localLog = false) {
-  return intentProtocolBlockV21Text(version, language, localLog, { historyRepair: true });
+function intentProtocolBlockV21(version = '2.1', language = DEFAULT_LOG_LANGUAGE, localLog = false) {
+  if (String(version) !== '2.1') fail(`protocol block 2.1 cannot be stamped as version ${version}`);
+  return intentProtocolBlockV21Text('2.1', language, localLog, { historyRepair: true });
 }
 
-function intentProtocolBlockV21AbsorbCollisions(version = PROTOCOL_VERSION, language = DEFAULT_LOG_LANGUAGE, localLog = false) {
-  return intentProtocolBlockV21Text(version, language, localLog, { historyRepair: false });
+function intentProtocolBlockV21AbsorbCollisions(version = '2.1', language = DEFAULT_LOG_LANGUAGE, localLog = false) {
+  if (String(version) !== '2.1') fail(`protocol block 2.1 cannot be stamped as version ${version}`);
+  return intentProtocolBlockV21Text('2.1', language, localLog, { historyRepair: false });
+}
+
+const PLAN_MODE_PROTOCOL_STEP = `5. **Plan mode writes the commands, then runs them first.** When the agent is
+   in plan mode, write every \`driftseal\` command this work will run into the
+   plan file as an explicit command. Closing commands may leave status and note
+   as placeholders. As soon as plan mode ends, re-anchor before any other
+   action. End an unrelated open outcome before any lane switch. Switch lanes
+   when this work belongs to another lane. Then \`begin\` or \`extend\` to match
+   that re-anchored state.`;
+
+function intentProtocolBlockV22(version = PROTOCOL_VERSION, language = DEFAULT_LOG_LANGUAGE, localLog = false) {
+  if (String(version) !== String(PROTOCOL_VERSION)) {
+    fail(`protocol block ${PROTOCOL_VERSION} cannot be stamped as version ${version}`);
+  }
+  return intentProtocolBlockV21Text(PROTOCOL_VERSION, language, localLog, { historyRepair: true }).replace(
+    '\n\n**Log access goes only through DriftSeal.**',
+    `\n${PLAN_MODE_PROTOCOL_STEP}\n\n**Log access goes only through DriftSeal.**`
+  );
 }
 
 function intentProtocolBlock(version = PROTOCOL_VERSION, language = DEFAULT_LOG_LANGUAGE, localLog = false) {
-  if (String(version) === '2.0') return intentProtocolBlockV20(language, localLog);
-  return intentProtocolBlockV21(version, language, localLog);
+  const requested = String(version);
+  if (requested === '2.0') return intentProtocolBlockV20(language, localLog);
+  if (requested === '2.1') return intentProtocolBlockV21('2.1', language, localLog);
+  if (requested === String(PROTOCOL_VERSION)) return intentProtocolBlockV22(PROTOCOL_VERSION, language, localLog);
+  fail(`unsupported outcome protocol version "${version}"`);
 }
 
 function v1IntentProtocolBlock(version = 14, language = DEFAULT_LOG_LANGUAGE, localLog = false) {
@@ -3002,13 +3025,22 @@ function protocolEol(content, eol) {
   return eol === '\n' ? content : content.replace(/\n/g, eol);
 }
 
-function decisionProtocolBlockAbsorbCollisions(version = PROTOCOL_VERSION, language = DEFAULT_LOG_LANGUAGE, localLog = false) {
-  return decisionProtocolBlockText(version, language, localLog, { historyRepair: false });
+function decisionProtocolBlockAbsorbCollisions(version = '2.1', language = DEFAULT_LOG_LANGUAGE, localLog = false) {
+  const requested = String(version);
+  if (requested !== '2.0' && requested !== '2.1') {
+    fail(`absorb-collisions decision protocol cannot be stamped as version ${version}`);
+  }
+  return decisionProtocolBlockText(requested, language, localLog, { historyRepair: false });
 }
 
 function decisionProtocolBlock(version = PROTOCOL_VERSION, language = DEFAULT_LOG_LANGUAGE, localLog = false) {
-  if (String(version) === '2.0') return decisionProtocolBlockAbsorbCollisions(version, language, localLog);
-  return decisionProtocolBlockText(version, language, localLog, { historyRepair: true });
+  const requested = String(version);
+  if (requested === '2.0') return decisionProtocolBlockAbsorbCollisions('2.0', language, localLog);
+  if (requested === '2.1') return decisionProtocolBlockText('2.1', language, localLog, { historyRepair: true });
+  if (requested === String(PROTOCOL_VERSION)) {
+    return decisionProtocolBlockText(PROTOCOL_VERSION, language, localLog, { historyRepair: true });
+  }
+  fail(`unsupported decision protocol version "${version}"`);
 }
 
 function decisionProtocolBlockText(version = PROTOCOL_VERSION, language = DEFAULT_LOG_LANGUAGE, localLog = false, { historyRepair = true } = {}) {
@@ -3132,6 +3164,14 @@ function previousDecisionProtocolBlock(version, language = DEFAULT_LOG_LANGUAGE,
   return v8.replace(' --driver "<decision driver>"', '');
 }
 
+function customizedProtocolBlockError(marker) {
+  return (
+    `cannot safely upgrade customized protocol block beginning with ${marker}; ` +
+    'the block may come from a newer DriftSeal release even when its protocol version matches ' +
+    `(current client: ${PACKAGE_VERSION}); upgrade DriftSeal and retry`
+  );
+}
+
 function upgradeManagedBlock({
   content,
   marker,
@@ -3182,7 +3222,7 @@ function upgradeManagedBlock({
       key === protocolBlockKey(replacement) ||
       knownManagedBlocks.some((known) => key === protocolBlockKey(known));
     if (!recognized) {
-      fail(`cannot safely upgrade customized protocol block beginning with ${marker}`);
+      fail(customizedProtocolBlockError(marker));
     }
     return {
       content: content.slice(0, start) + replacement + content.slice(after),
@@ -3197,7 +3237,7 @@ function upgradeManagedBlock({
       found: true,
     };
   }
-  fail(`cannot safely upgrade customized protocol block beginning with ${marker}`);
+  fail(customizedProtocolBlockError(marker));
 }
 
 const MCP_TARGETS = ['codex', 'kimi-code', 'opencode', 'claude-code', 'cursor'];
@@ -6845,8 +6885,10 @@ const commands = {
         ...sourceLanguages.flatMap((source) => [
           protocolEol(intentProtocolBlock(PROTOCOL_VERSION, source), eol),
           protocolEol(intentProtocolBlock(PROTOCOL_VERSION, source, true), eol),
-          protocolEol(intentProtocolBlockV21AbsorbCollisions(PROTOCOL_VERSION, source), eol),
-          protocolEol(intentProtocolBlockV21AbsorbCollisions(PROTOCOL_VERSION, source, true), eol),
+          protocolEol(intentProtocolBlock('2.1', source), eol),
+          protocolEol(intentProtocolBlock('2.1', source, true), eol),
+          protocolEol(intentProtocolBlockV21AbsorbCollisions('2.1', source), eol),
+          protocolEol(intentProtocolBlockV21AbsorbCollisions('2.1', source, true), eol),
           protocolEol(intentProtocolBlockV20(source), eol),
           protocolEol(intentProtocolBlockV20(source, true), eol),
           protocolEol(v1IntentProtocolBlock(14, source), eol),
@@ -6881,8 +6923,10 @@ const commands = {
         ...sourceLanguages.flatMap((source) => [
           protocolEol(decisionProtocolBlock(PROTOCOL_VERSION, source), eol),
           protocolEol(decisionProtocolBlock(PROTOCOL_VERSION, source, true), eol),
-          protocolEol(decisionProtocolBlockAbsorbCollisions(PROTOCOL_VERSION, source), eol),
-          protocolEol(decisionProtocolBlockAbsorbCollisions(PROTOCOL_VERSION, source, true), eol),
+          protocolEol(decisionProtocolBlock('2.1', source), eol),
+          protocolEol(decisionProtocolBlock('2.1', source, true), eol),
+          protocolEol(decisionProtocolBlockAbsorbCollisions('2.1', source), eol),
+          protocolEol(decisionProtocolBlockAbsorbCollisions('2.1', source, true), eol),
           protocolEol(decisionProtocolBlock('2.0', source), eol),
           protocolEol(decisionProtocolBlock('2.0', source, true), eol),
           protocolEol(v1DecisionProtocolBlock(14, source), eol),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftseal",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Seal outcomes, verification, and decisions into an auditable workflow for agentic coding",
   "keywords": [
     "driftseal",