driftseal 2.0.0 → 2.1.0

package/README.md

@@ -28,9 +28,12 @@ DriftSeal v2 is an outcome log rather than an intent-per-step log.
   decision link to the currently open outcome.
 - Every extension changes the contract hash and invalidates earlier verification
   and MADR reconciliation.
-- Stored events use `logVersion: 2` and `schemaVersion: 1`.
-- The generated `AGENTS.md` protocol series is `2.0`; compatible protocol
-  refinements use `2.1`, `2.2`, and so on.
+- 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.
+- 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.
   v1 names and storage paths are not runtime aliases.
 
@@ -121,6 +124,45 @@ The scope belongs to the worktree, not to the agent process. Agents and subagent
 working in the same worktree resume its matching open outcome. Separate worktrees
 hold separate outcomes.
 
+## Lanes
+
+Orthogonal long-lived capabilities can share one append-only log without sharing
+narrative context. Each outcome belongs to one named lane. Untagged history lives
+on `main`. `status` and `log --last 3` follow the current lane, which is local to
+the worktree.
+
+```sh
+driftseal lane add index --desc "On-disk inverted index"
+driftseal lane switch index
+driftseal begin "Ship the inverted index" --accept "lookups return stored postings" --verify "npm test"
+```
+
+Close the open outcome before switching. Later work on the same capability
+switches back and begins a new outcome on that lane; it does not reopen a closed
+record. `driftseal lane assign <id> <name>` moves a closed outcome. Cross-cutting
+work stays on `main`. An open outcome stays visible in `log` even when it belongs
+to another lane; `status` prints that lane when it differs from the current one.
+
+Lanes cannot be renamed or removed. A typo in `lane add` stays in `driftseal lane`
+output; add the intended name and stop using the old one.
+
+If a `begin` names a lane whose `lane_add` is missing, DriftSeal infers the lane
+so `status`, `log`, and `lane` still work, and `lane add` can write the missing
+event. Duplicate `lane_add` records last-write the description instead of failing
+the fold. A `lane_assign` that names an unknown lane infers it the same way.
+If the worktree's current-lane pointer names a lane the WAL no longer
+has, `status`, `log`, and `lane` fall back to `main` with a warning; `begin`
+still refuses until you `lane switch main` or add the lane. `log --last N` can
+return more than N records when an open outcome sits on another lane.
+
+A derived lane index caches fold state in Git metadata (or beside a custom
+seal). Incremental rebuilds follow `indexedThrough` and `indexedLines`; a full
+rebuild happens when the log identity changes. Per-lane heads, reverse links,
+and WAL byte ranges are stored for a seek path that is not consumed yet. The
+index is reconstructable and is not committed with the log. Custom-home
+sidecars sit next to `events.jsonl`. When that directory is inside a Git
+worktree, they are listed in its `.gitignore`.
+
 ## Decisions and MADR
 
 Use a MADR only for context that the outcome log and Git cannot recover: a
@@ -152,8 +194,9 @@ driftseal decision update 1 --status accepted --note "Confirmed by the final imp
 | `driftseal extend "<addition>" [--accept "..."] [--verify "..."] [--decision id]` | Append scope to the same outcome and invalidate earlier verification. |
 | `driftseal verify [--allow-tracked-command]` | Execute the declared cumulative verifier and bind evidence. |
 | `driftseal end [id] [-s status] [-n note] [-r verify-result]` | Close an outcome honestly. |
-| `driftseal status` | Show the outcome in progress. |
-| `driftseal log [--last N] [--all]` | Review outcome history. |
+| `driftseal status` | Show the outcome in progress and the current lane. |
+| `driftseal log [--last N] [--all] [--all-lanes]` | Review outcome history (current lane unless `--all-lanes`). |
+| `driftseal lane add\|switch\|assign\|show` | Partition history by long-lived capability. |
 | `driftseal reclaim [id ...] --reason "..." [--force]` | Hide meaningless closed records with append-only markers. |
 | `driftseal unreclaim <id> --reason "..."` | Restore a reclaimed record. |
 | `driftseal absorb [other-events.jsonl] [--decisions dir] [--abandon-theirs\|--abandon-ours]` | Merge another lineage and remap colliding outcome or MADR ids. |
@@ -266,24 +309,31 @@ seal.begin({
 seal.extend({ extension: 'Document token expiry' });
 ```
 
-The API also exposes `status`, `verify`, `end`, `log`, `absorb`, reclaim,
-decision, init, and migration methods.
+The API also exposes `status`, `verify`, `end`, `log`, `lane`, `laneAdd`,
+`laneSwitch`, `laneAssign`, `absorb`, reclaim, decision, init, and migration
+methods.
 
 The stdio MCP server fixes all operations to one repository root. Its v2 tools
 include `driftseal_status`, `driftseal_begin`, `driftseal_extend`,
-`driftseal_verify`, `driftseal_end`, outcome history and absorb tools, MADR
-tools, and the three migration tools. Resources are:
+`driftseal_verify`, `driftseal_end`, outcome history, lane, and absorb tools,
+MADR tools, and the three migration tools. Resources are:
 
 - `driftseal://outcome/current`
 - `driftseal://outcomes/recent`
+- `driftseal://lanes`
 - `driftseal://madr`
 
 ## Storage and trust boundary
 
 - `.seal/outcomes/events.jsonl` is the append-only outcome log. Access it through
-  DriftSeal; use `reclaim`, `unreclaim`, and `absorb` instead of manual edits.
+  DriftSeal; use `reclaim`, `unreclaim`, `lane`, and `absorb` instead of manual edits.
 - `.seal/madr/` stores numbered MADR documents.
 - `$DRIFTSEAL_HOME` replaces the `.seal` root.
+- The current lane and derived lane index live in Git metadata for a default
+  repository seal, or beside a custom seal (`outcomes/.current-lane` and
+  `outcomes/.lane-index.json`). When the custom seal sits inside a Git
+  worktree, those sidecars are gitignored. They are reconstructable and are not
+  part of the committed WAL.
 - Advisory hooks remind agents about lifecycle state but never broaden the
   repository's `AGENTS.md` policy.
 

package/README.zh-CN.md

@@ -23,8 +23,11 @@ DriftSeal v2 从“按步骤记录 intent”改为“按交付记录 outcome”
   目录；migration 时需要显式传入旧位置，之后再 unset 或替换这个变量。
 - `driftseal extend` 可以向当前 outcome 追加步骤、acceptance、verifier 或 decision link。
 - 每次 extend 都会改变 contract hash，并让之前的 verification 与 MADR reconciliation 失效。
-- event 使用 `logVersion: 2`、`schemaVersion: 1`。
-- `AGENTS.md` 的新协议版本从 `2.0` 开始，兼容改进依次使用 `2.1`、`2.2`。
+- event 使用 `logVersion: 2`。兼容客户端接受 `schemaVersion` `1` 或 `2`；lane
+  事件以及非默认的 `begin.lane` 使用 `schemaVersion: 2`。
+- `AGENTS.md` 的新协议版本是 `2.1`。`driftseal init` 会升级可识别的 `2.0` block。
+- 具名 lane 在同一条 WAL 上切分 outcome 历史。默认 lane 是 `main`；`driftseal log`
+  跟随当前 lane。
 - CLI、Node API、MCP tool 与 resource 全部使用 outcome 命名；v1 名称和路径不会作为
   runtime alias 保留。
 
@@ -109,6 +112,40 @@ driftseal log --last 3
 作用域属于 worktree，而不是某一个 agent process。同一 worktree 内的 agent 与
 subagent 重新锚定并继续匹配的 open outcome；不同 worktree 各自持有 outcome。
 
+## Lane
+
+彼此正交、会长期回来接着做的能力，可以共用一条 append-only log，而不共用叙事上下文。
+每个 outcome 只属于一条具名 lane。未打标签的历史在 `main` 上。`status` 与
+`log --last 3` 跟随当前 lane，指针是 worktree 本地的。
+
+```sh
+driftseal lane add index --desc "On-disk inverted index"
+driftseal lane switch index
+driftseal begin "Ship the inverted index" --accept "lookups return stored postings" --verify "npm test"
+```
+
+有 open outcome 时不能切 lane。以后回到同一能力，是切回去再 `begin` 新的 outcome，
+而不是重开已关闭的记录。`driftseal lane assign <id> <name>` 可以把已关闭的 outcome
+移过去。跨切工作留在 `main`。open outcome 即使属于别的 lane，也会出现在 `log` 里；
+若它和当前 lane 不同，`status` 会写出它的 lane。
+
+lane 不能改名或删除。`lane add` 打错的名字会一直出现在 `driftseal lane` 输出里；
+补上正确名字，旧名字不要再用。
+
+如果 `begin` 引用了 WAL 里没有 `lane_add` 的 lane，DriftSeal 会推断这条 lane，
+让 `status` / `log` / `lane` 仍可读，也允许再用 `lane add` 补上缺失事件。重复的
+`lane_add` 只更新 description，不会让 fold 失败；没有前置 `lane_add` 的
+`lane_assign` 同样会推断该 lane。若 worktree 的 current-lane 指针指向 WAL 里已
+不存在的 lane，`status` / `log` / `lane` 会警告并回落到 `main`；`begin` 仍会拒绝，
+直到 `lane switch main` 或把该 lane 加回来。`log --last N` 在 open outcome 属于
+别的 lane 时，返回条数可以多于 N。
+
+派生的 lane index 缓存 fold 状态，放在 Git metadata（或自定义 seal 旁边）。
+增量重建跟随 `indexedThrough` 和 `indexedLines`；log 身份变化时全量重建。每条
+lane 的 head、反向链接和 WAL byte range 会写入 index，供尚未接入的 seek 路径使用。
+它可以重建，不会随 log 一起提交。自定义 home 下的 sidecar 放在 `events.jsonl`
+旁边；该目录在 Git worktree 内时，由目录里的 `.gitignore` 忽略。
+
 ## Decision 与 MADR
 
 只有当 outcome log 与 Git 无法还原重要上下文时才建立 MADR，例如值得以后重访的
@@ -139,8 +176,9 @@ driftseal decision update 1 --status accepted --note "Confirmed by the final imp
 | `driftseal extend "<addition>" [--accept "..."] [--verify "..."] [--decision id]` | 向同一 outcome 追加内容，并让旧 verification 失效。 |
 | `driftseal verify [--allow-tracked-command]` | 执行累计 verifier 并绑定证据。 |
 | `driftseal end [id] [-s status] [-n note] [-r verify-result]` | 诚实关闭 outcome。 |
-| `driftseal status` | 查看进行中的 outcome。 |
-| `driftseal log [--last N] [--all]` | 查看 outcome 历史。 |
+| `driftseal status` | 查看进行中的 outcome 和当前 lane。 |
+| `driftseal log [--last N] [--all] [--all-lanes]` | 查看 outcome 历史（默认当前 lane）。 |
+| `driftseal lane add\|switch\|assign\|show` | 按长期能力切分历史。 |
 | `driftseal reclaim [id ...] --reason "..." [--force]` | 通过 append-only marker 隐藏无意义的已关闭记录。 |
 | `driftseal unreclaim <id> --reason "..."` | 恢复 reclaimed record。 |
 | `driftseal absorb [other-events.jsonl] [--decisions dir] [--abandon-theirs\|--abandon-ours]` | 合并另一条 lineage 并处理撞号。 |
@@ -243,23 +281,30 @@ seal.begin({
 seal.extend({ extension: 'Document token expiry' });
 ```
 
-API 还提供 `status`、`verify`、`end`、`log`、`absorb`、reclaim、decision、init 与
-migration 方法。
+API 还提供 `status`、`verify`、`end`、`log`、`lane`、`laneAdd`、`laneSwitch`、
+`laneAssign`、`absorb`、reclaim、decision、init 与 migration 方法。
 
 stdio MCP server 会把所有操作固定在一个 repo root。v2 tools 包括
 `driftseal_status`、`driftseal_begin`、`driftseal_extend`、`driftseal_verify`、
-`driftseal_end`、outcome history/absorb、MADR，以及三个 migration tools。resources 为：
+`driftseal_end`、outcome history、lane、absorb、MADR，以及三个 migration tools。
+resources 为：
 
 - `driftseal://outcome/current`
 - `driftseal://outcomes/recent`
+- `driftseal://lanes`
 - `driftseal://madr`
 
 ## 存储与信任边界
 
 - `.seal/outcomes/events.jsonl` 是 append-only outcome log。通过 DriftSeal 访问它；
-  需要调整可见性或处理 merge 时使用 `reclaim`、`unreclaim`、`absorb`，不要手改。
+  需要调整可见性、切分 lane 或处理 merge 时使用 `reclaim`、`unreclaim`、`lane`、
+  `absorb`，不要手改。
 - `.seal/madr/` 保存编号化 MADR。
 - `$DRIFTSEAL_HOME` 替换整个 `.seal` root。
+- 当前 lane 与派生 lane index 对默认 repo seal 存在 Git metadata 里，对自定义 seal
+  则放在旁边（`outcomes/.current-lane` 与 `outcomes/.lane-index.json`）。自定义
+  seal 在 Git worktree 内时，这些 sidecar 会被 gitignore。它们可以重建，不是
+  committed WAL 的一部分。
 - advisory hook 只提示 lifecycle 状态，不会扩大 repo 中 `AGENTS.md` 的政策边界。
 
 DriftSeal 不会替你判断 verification command 是否安全，也不会判断测试本身是否充分。

package/bin/driftseal-mcp.js

@@ -94,6 +94,7 @@ function registerTools(server, api, z) {
   const outcomeRecord = z.object({
     id: z.string(),
     outcome: z.string(),
+    lane: z.string().optional(),
     extensions: z.array(extensionRecord),
     acceptance: z.array(z.string()),
     verify: z.string().nullable(),
@@ -281,10 +282,14 @@ function registerTools(server, api, z) {
     {
       title: 'List DriftSeal outcome history',
       description:
-        'Review recent or complete DriftSeal outcome history. Reclaimed records are hidden unless includeReclaimed is set.',
+        'Review recent or complete DriftSeal outcome history. Defaults to the current lane. Reclaimed records are hidden unless includeReclaimed is set.',
       inputSchema: {
         last: z.number().int().positive().max(100).optional(),
         includeReclaimed: z.boolean().default(false),
+        allLanes: z
+          .boolean()
+          .default(false)
+          .describe('Show outcomes from every lane instead of the current lane.'),
       },
       outputSchema: {
         root: z.string(),
@@ -295,7 +300,11 @@ function registerTools(server, api, z) {
     },
     async (input) =>
       guarded(() => {
-        const outcomes = api.log({ last: input.last, all: input.includeReclaimed });
+        const outcomes = api.log({
+          last: input.last,
+          all: input.includeReclaimed,
+          allLanes: input.allLanes,
+        });
         const readOnly = api.readOnly;
         const summary = `Found ${outcomes.length} DriftSeal outcome records.`;
         return success(
@@ -305,6 +314,103 @@ function registerTools(server, api, z) {
       })
   );
 
+  const laneRecord = z.object({
+    name: z.string(),
+    description: z.string().nullable(),
+    addedAt: z.string().nullable(),
+    inferred: z.boolean().optional(),
+    visible: z.number().int().nonnegative(),
+    count: z.number().int().nonnegative(),
+    current: z.boolean().optional(),
+  });
+
+  server.registerTool(
+    'driftseal_lane',
+    {
+      title: 'Show DriftSeal lanes',
+      description:
+        'List named outcome lanes and the current lane. Re-anchoring and log history follow the current lane.',
+      inputSchema: {},
+      outputSchema: {
+        root: z.string(),
+        current: z.string(),
+        missingCurrentLane: z.string().nullable().optional(),
+        lanes: z.array(laneRecord),
+        total: z.number().int().nonnegative(),
+        readOnly: z.boolean().optional(),
+      },
+      annotations: readOnly,
+    },
+    async () =>
+      guarded(() => {
+        const snapshot = api.lane();
+        const readOnly = api.readOnly;
+        return success(
+          { root: api.root, ...snapshot, ...(readOnly ? { readOnly: true } : {}) },
+          `Current DriftSeal lane is ${snapshot.current}.`
+        );
+      })
+  );
+
+  server.registerTool(
+    'driftseal_lane_add',
+    {
+      title: 'Add a DriftSeal lane',
+      description:
+        'Create a named lane for a long-lived capability. The default lane main always exists.',
+      inputSchema: {
+        name: nonEmpty.describe('Lane name: a lowercase letter, then letters, digits, or hyphens.'),
+        description: nonEmpty.optional(),
+      },
+      outputSchema: { root: z.string(), name: z.string(), description: z.string().nullable() },
+      annotations: localWrite,
+    },
+    async (input) =>
+      guarded(() => {
+        const lane = api.laneAdd({ name: input.name, description: input.description });
+        return success({ root: api.root, ...lane }, `Added DriftSeal lane ${lane.name}.`);
+      })
+  );
+
+  server.registerTool(
+    'driftseal_lane_switch',
+    {
+      title: 'Switch the current DriftSeal lane',
+      description:
+        'Move this worktree onto an existing lane. Refused while an outcome is open.',
+      inputSchema: { name: nonEmpty },
+      outputSchema: { root: z.string(), current: z.string() },
+      annotations: localWrite,
+    },
+    async (input) =>
+      guarded(() => {
+        const result = api.laneSwitch({ name: input.name });
+        return success({ root: api.root, ...result }, `Switched to DriftSeal lane ${result.current}.`);
+      })
+  );
+
+  server.registerTool(
+    'driftseal_lane_assign',
+    {
+      title: 'Assign a closed outcome to a lane',
+      description: 'Move a closed outcome onto an existing lane with an append-only assign event.',
+      inputSchema: {
+        id: nonEmpty.describe('Closed outcome id.'),
+        lane: nonEmpty,
+      },
+      outputSchema: { root: z.string(), outcome: outcomeRecord },
+      annotations: localWrite,
+    },
+    async (input) =>
+      guarded(() => {
+        const outcome = api.laneAssign({ id: input.id, lane: input.lane });
+        return success(
+          { root: api.root, outcome },
+          `Assigned outcome ${outcome.id} to lane ${outcome.lane}.`
+        );
+      })
+  );
+
   server.registerTool(
     'driftseal_absorb',
     {
@@ -568,9 +674,16 @@ function registerResources(server, api) {
     'recent-outcomes',
     'driftseal://outcomes/recent',
     'Recent DriftSeal outcomes',
-    'The ten most recent outcome records for the fixed repository.',
+    'The ten most recent outcome records on the current lane.',
     () => ({ root: api.root, outcomes: api.log({ last: 10 }) })
   );
+  registerJson(
+    'outcome-lanes',
+    'driftseal://lanes',
+    'DriftSeal outcome lanes',
+    'Named lanes that partition outcome history, including the current lane.',
+    () => ({ root: api.root, ...api.lane() })
+  );
   registerJson(
     'decision-catalog',
     'driftseal://madr',
@@ -592,7 +705,7 @@ async function createServer({ root }) {
     { name: SERVER_NAME, version: SERVER_VERSION },
     {
       instructions:
-        'Use driftseal_status before durable project changes or after context loss. Open one coherent outcome with driftseal_begin and append same-outcome steps with driftseal_extend. Reconcile linked decisions after the final extension, inspect the cumulative verifier, use driftseal_verify for fresh contract-bound evidence, and close honestly with driftseal_end.',
+        'Use driftseal_status before durable project changes or after context loss. Open one coherent outcome with driftseal_begin and append same-outcome steps with driftseal_extend. Reconcile linked decisions after the final extension, inspect the cumulative verifier, use driftseal_verify for fresh contract-bound evidence, and close honestly with driftseal_end. Named lanes isolate orthogonal capability history; driftseal_log follows the current lane.',
     }
   );
   registerTools(server, api, z);