driftseal 1.3.2 → 1.4.0

package/README.md

@@ -251,15 +251,32 @@ driftseal end \
 
 If the scope changes, close the current intent as `partial` or `abandoned`, then start a new one. After context loss, use `driftseal status` and `driftseal log --last 3` to re-anchor.
 
-Git operations are entirely outside the intent log because Git maintains their
-history. Inspection, branch and worktree management, staging, commits, merges,
-rebases, cherry-picks, tags, and pushes never need an intent of their own. They
-still require normal authorization and safety checks. A command whose result
-can be reconstructed from Git state, such as a patch file regenerated from a
-commit range or a scratch harness that re-runs, needs no intent either; content
-that will be committed and cannot be reconstructed, such as a `.gitignore`
-edit, does. Single-step builds and checks, such as compiling or running tests,
-also need no intent. Any other non-Git content change starts a new work round.
+Record an intent for changes intended to persist in the project: edits to code,
+configuration, documentation, dependencies, and equivalent project files. The
+boundary does not depend on Git: inside a worktree it includes content intended
+for commit, while outside Git it includes durable project files. Everything else
+is exempt. Git operations are entirely outside the intent log because Git
+maintains their history; inspection, branch and worktree management, staging,
+commits, merges, rebases, cherry-picks, tags, and pushes never need an intent of
+their own, though they still require normal authorization and safety checks.
+Single-step builds and checks, such as compiling or running tests, need no
+intent. Auxiliary file or shell operations whose results remain outside durable
+project content — an `rsync` scratch copy, temp scaffolding — need none either.
+State changes to a remote machine or the local environment are also exempt when
+they do not write durable project content into this workspace. When an external
+operation does bring durable content into the project, record the intent for
+that project-content change, not for the external operation itself.
+
+In multi-agent work the scope belongs to the worktree, not the writer. One
+worktree holds one open intent; every agent or subagent changing durable project
+content there re-anchors and continues that matching intent. Agents in separate
+worktrees hold separate intents. A configured project root outside Git follows
+the same single-intent rule. An agent that only receives another agent's changes
+through Git or into a shared worktree records no receiving intent and lets
+`verify` expose misalignment. Handoff files are exempt while ignored or
+otherwise kept outside durable project content and require an intent when
+promoted into it. Taking over work in the same root is a re-anchor, not a
+boundary: resume the open intent when its objective still matches the task.
 
 ## Commands
 

package/README.zh-CN.md

@@ -235,12 +235,23 @@ driftseal end \
 
 如果范围发生变化，先把当前 intent 以 `partial` 或 `abandoned` 关闭，再开启新的 intent。发生 context loss 后，用 `driftseal status` 和 `driftseal log --last 3` 重新锚定当前目标。
 
-Git 操作完全不计入 intent log，因为 Git 会自行维护历史。查看状态、管理 branch
-或 worktree、stage、commit、merge、rebase、cherry-pick、tag 和 push 都不需要
-单独开启 intent，但仍须遵守正常的授权与安全要求。结果能从 Git 状态重建的命令
-——比如从 commit range 重新生成的 patch 文件、可以重跑的临时 harness——也不需要
-intent；会被提交且无法重建的内容改动（比如编辑 `.gitignore`）则需要。编译、跑测试
-等单步构建或检查同样不需要 intent；除此之外的非 Git 内容改动，都要开启新一轮。
+需要记录 intent 的是准备作为项目内容长期保留的改动，包括代码、配置、文档、依赖及同类
+项目文件。这个边界不取决于 Git：在 worktree 中，它包括准备提交的内容；在非 Git 项目中，
+它包括要长期保留的项目文件。其余操作一律免记。Git 会自行维护操作历史，因此查看状态、
+管理 branch 或 worktree、stage、commit、merge、rebase、cherry-pick、tag 和 push 都
+不需要单独开启 intent，但仍须遵守正常的授权与安全要求。编译、跑测试等单步构建或检查也
+不需要 intent。结果不会成为持久项目内容的辅助文件或 shell 操作——比如 `rsync` 临时拷贝、
+临时脚手架——同样免记。远程机器或本机环境的状态变更，只要不把持久项目内容写入当前
+workspace，也不属于 intent log；如果外部操作确实把持久内容带进项目，记录的是落入项目的
+内容改动，而不是外部操作本身。
+
+多 agent 协作时，intent 的作用域属于 worktree，而不是写入者。一个 worktree 只能有一个
+open intent；在那里改动持久项目内容的所有 agent 和 subagent 都要先重新锚定，再继续同一个
+匹配的 intent。不同 worktree 各自持有 intent；非 Git 项目的 configured root 同样只持有
+一个。只通过 Git 或共享 worktree 接收其他 agent 变更的一方不另记 receiving intent，交给
+`verify` 暴露不一致。handoff 文件在被 ignore 或以其他方式排除在持久项目内容之外时免记，
+一旦转为正式项目内容就需要 intent。在同一个 root 中途接手工作属于重新锚定而非边界：目标
+仍然匹配就继续沿用 open intent。
 
 ## 命令速览
 

package/bin/driftseal.js

@@ -41,7 +41,7 @@ const DECISION_STATUSES = [
   'superseded',
 ];
 const EVENT_SCHEMA_VERSION = 4;
-const PROTOCOL_VERSION = 13;
+const PROTOCOL_VERSION = 14;
 const DEFAULT_LOG_LANGUAGE = 'en';
 const IN_PROGRESS_GIT_PATH = 'driftseal-in-progress.jsonl';
 const LOCK_STALE_MS = 30 * 60 * 1000;
@@ -1874,20 +1874,31 @@ MCP and lifecycle hooks are optional adapters.
 
 ${intentLogLanguageParagraph(language)}
 
-1. **Write intent first**, before modifying, creating, or deleting files, or
-   making any other non-Git change that may need a rollback:
+1. **Write intent first**, before changing durable project content:
    \`driftseal begin "<what this round will accomplish>" --accept "<observable outcome>" --verify "<exact command that proves it>"\`.
    Repeat \`--accept\` when completion has multiple independently observable criteria.
    Add one \`--decision <id>\` for each existing decision this round may change.
-   Git operations never need an intent and are not included in the intent log;
-   Git maintains their history. This includes inspection, branch and worktree
-   management, staging, commits, merges, rebases, cherry-picks, tags, and pushes.
-   A command whose result can be reconstructed from Git state (for example a
-   patch file regenerated from a commit range, or a scratch harness that
-   re-runs) needs no intent; content that will be committed and cannot be
-   reconstructed (for example a .gitignore edit) does.
-   Single-step commands that only build or check work already done, such as
-   compiling or running tests, also need no intent.
+   Record intents for changes intended to persist in the project: edits to code,
+   configuration, documentation, dependencies, and equivalent project files,
+   whether or not the project is inside a Git worktree. Everything else is
+   exempt: Git operations (Git maintains their history — inspection, branch
+   and worktree management, staging, commits, merges, rebases, cherry-picks,
+   tags, and pushes); single-step commands that only build or check work
+   already done, such as compiling or running tests; auxiliary file or shell
+   operations whose results remain outside durable project content (for example
+   an rsync scratch copy or temp scaffolding); and state changes to a remote
+   machine or the local environment that do not write durable project content
+   into this workspace. When an external operation does bring durable content
+   into the project, record an intent for that project-content change, not for
+   the external operation itself.
+   In multi-agent work, one open intent belongs to one worktree, or to one
+   configured project root outside Git. Every agent or subagent that changes
+   durable project content in the same root first re-anchors and continues its
+   matching open intent; agents working in separate worktrees hold separate
+   intents. An agent that only receives another agent's changes through Git or
+   into a shared worktree records no receiving intent and lets \`verify\` expose
+   misalignment; handoff files are exempt while ignored or otherwise kept
+   outside durable project content and require an intent when promoted into it.
    Size an intent to the smallest unit that leaves the tree self-consistent
    and can be verified on its own.
 2. **Execute only the intent.** Scope change? Close the current intent
@@ -1914,12 +1925,15 @@ ${intentLogLanguageParagraph(language)}
    by the next linked \`decision update\` or successful \`end\`. Closing as
    \`failed\` or \`abandoned\` cancels pending recovery for that intent.
    Git operations remain subject to normal authorization and safety requirements
-   even though they do not require an intent. Any non-Git content change made while
-   preparing a Git operation does require a new intent, per the step 1 test.
+   even though they do not require an intent. Any content change made while
+   preparing a Git operation still requires an intent when it meets the
+   durable-project-content rule in step 1.
 4. **Re-anchor after context loss**: run \`driftseal status\` and \`driftseal log --last 3\` before
    doing anything else. The open intent is the source of truth: resume it when its
    objective still matches the current task; otherwise close it (\`partial\` or
-   \`abandoned\`, with a note) and \`begin\` a new one.
+   \`abandoned\`, with a note) and \`begin\` a new one. Taking over work in the
+   same root from another agent is the same re-anchor: resume the open intent
+   when its objective still matches.
 
 **Log access goes only through DriftSeal.** Never read, edit, move, or delete
 \`.intent-log/events.jsonl\` (or anything under \`$DRIFTSEAL_HOME\`) directly; use
@@ -1935,7 +1949,75 @@ ${INTENT_PROTOCOL_END}`;
 }
 
 function previousIntentProtocolBlock(version, language = DEFAULT_LOG_LANGUAGE, localLog = false) {
-  const v12 = intentProtocolBlock(version, language, localLog)
+  const v13 = intentProtocolBlock(version, language, localLog)
+    .replace(
+      '1. **Write intent first**, before changing durable project content:\n' +
+        '   `driftseal begin "<what this round will accomplish>" --accept "<observable outcome>" --verify "<exact command that proves it>"`.\n' +
+        '   Repeat `--accept` when completion has multiple independently observable criteria.\n' +
+        '   Add one `--decision <id>` for each existing decision this round may change.\n' +
+        '   Record intents for changes intended to persist in the project: edits to code,\n' +
+        '   configuration, documentation, dependencies, and equivalent project files,\n' +
+        '   whether or not the project is inside a Git worktree. Everything else is\n' +
+        '   exempt: Git operations (Git maintains their history — inspection, branch\n' +
+        '   and worktree management, staging, commits, merges, rebases, cherry-picks,\n' +
+        '   tags, and pushes); single-step commands that only build or check work\n' +
+        '   already done, such as compiling or running tests; auxiliary file or shell\n' +
+        '   operations whose results remain outside durable project content (for example\n' +
+        '   an rsync scratch copy or temp scaffolding); and state changes to a remote\n' +
+        '   machine or the local environment that do not write durable project content\n' +
+        '   into this workspace. When an external operation does bring durable content\n' +
+        '   into the project, record an intent for that project-content change, not for\n' +
+        '   the external operation itself.\n' +
+        '   In multi-agent work, one open intent belongs to one worktree, or to one\n' +
+        '   configured project root outside Git. Every agent or subagent that changes\n' +
+        '   durable project content in the same root first re-anchors and continues its\n' +
+        '   matching open intent; agents working in separate worktrees hold separate\n' +
+        "   intents. An agent that only receives another agent's changes through Git or\n" +
+        '   into a shared worktree records no receiving intent and lets `verify` expose\n' +
+        '   misalignment; handoff files are exempt while ignored or otherwise kept\n' +
+        '   outside durable project content and require an intent when promoted into it.\n' +
+        '   Size an intent to the smallest unit that leaves the tree self-consistent\n' +
+        '   and can be verified on its own.',
+      '1. **Write intent first**, before modifying, creating, or deleting files, or\n' +
+        '   making any other non-Git change that may need a rollback:\n' +
+        '   `driftseal begin "<what this round will accomplish>" --accept "<observable outcome>" --verify "<exact command that proves it>"`.\n' +
+        '   Repeat `--accept` when completion has multiple independently observable criteria.\n' +
+        '   Add one `--decision <id>` for each existing decision this round may change.\n' +
+        '   Git operations never need an intent and are not included in the intent log;\n' +
+        '   Git maintains their history. This includes inspection, branch and worktree\n' +
+        '   management, staging, commits, merges, rebases, cherry-picks, tags, and pushes.\n' +
+        '   A command whose result can be reconstructed from Git state (for example a\n' +
+        '   patch file regenerated from a commit range, or a scratch harness that\n' +
+        '   re-runs) needs no intent; content that will be committed and cannot be\n' +
+        '   reconstructed (for example a .gitignore edit) does.\n' +
+        '   Single-step commands that only build or check work already done, such as\n' +
+        '   compiling or running tests, also need no intent.\n' +
+        '   Size an intent to the smallest unit that leaves the tree self-consistent\n' +
+        '   and can be verified on its own.'
+    )
+    .replace(
+      '   Git operations remain subject to normal authorization and safety requirements\n' +
+        '   even though they do not require an intent. Any content change made while\n' +
+        '   preparing a Git operation still requires an intent when it meets the\n' +
+        '   durable-project-content rule in step 1.',
+      '   Git operations remain subject to normal authorization and safety requirements\n' +
+        '   even though they do not require an intent. Any non-Git content change made while\n' +
+        '   preparing a Git operation does require a new intent, per the step 1 test.'
+    )
+    .replace(
+      '4. **Re-anchor after context loss**: run `driftseal status` and `driftseal log --last 3` before\n' +
+        '   doing anything else. The open intent is the source of truth: resume it when its\n' +
+        '   objective still matches the current task; otherwise close it (`partial` or\n' +
+        '   `abandoned`, with a note) and `begin` a new one. Taking over work in the\n' +
+        '   same root from another agent is the same re-anchor: resume the open intent\n' +
+        '   when its objective still matches.',
+      '4. **Re-anchor after context loss**: run `driftseal status` and `driftseal log --last 3` before\n' +
+        '   doing anything else. The open intent is the source of truth: resume it when its\n' +
+        '   objective still matches the current task; otherwise close it (`partial` or\n' +
+        '   `abandoned`, with a note) and `begin` a new one.'
+    );
+  if (version >= 13) return v13;
+  const v12 = v13
     .replace(
       '   `driftseal begin "<what this round will accomplish>" --accept "<observable outcome>" --verify "<exact command that proves it>"`.\n' +
         '   Repeat `--accept` when completion has multiple independently observable criteria.',
@@ -2900,11 +2982,13 @@ function hookReminder(event, { readOnly = false } = {}) {
   if (!file) return null;
   if (event === 'prompt') {
     return (
-      'DriftSeal reminder: if this round will modify files or anything else that may need a ' +
-      'rollback, begin an intent first: driftseal begin "<intent>" --accept "<observable outcome>" ' +
+      'DriftSeal reminder: if this round will change durable project content in this workspace ' +
+      '(code, configuration, documentation, dependencies), ' +
+      'begin an intent first: driftseal begin "<intent>" --accept "<observable outcome>" ' +
       '--verify "<command>". ' +
-      'Questions, read-only exploration, and single-step checks need no intent — skip this ' +
-      'reminder when it does not apply.'
+      'Questions, read-only exploration, single-step checks, temporary work outside durable ' +
+      'project content, and external state changes that do not write project content here need ' +
+      'no intent — skip this reminder when it does not apply.'
     );
   }
   const open = openIntent(fold(readEvents({ file, readOnly })));
@@ -4607,6 +4691,8 @@ const commands = {
       knownManagedBlocks: [
         ...sourceLanguages.flatMap((source) => [
           protocolEol(intentProtocolBlock(PROTOCOL_VERSION, source), eol),
+          protocolEol(previousIntentProtocolBlock(13, source), eol),
+          protocolEol(previousIntentProtocolBlock(13, source, true), eol),
           protocolEol(previousIntentProtocolBlock(12, source), eol),
           protocolEol(previousIntentProtocolBlock(12, source, true), eol),
           protocolEol(previousIntentProtocolBlock(11, source), eol),
@@ -4634,6 +4720,8 @@ const commands = {
       knownManagedBlocks: [
         ...sourceLanguages.flatMap((source) => [
           protocolEol(decisionProtocolBlock(PROTOCOL_VERSION, source), eol),
+          protocolEol(previousDecisionProtocolBlock(13, source), eol),
+          protocolEol(previousDecisionProtocolBlock(13, source, true), eol),
           protocolEol(previousDecisionProtocolBlock(12, source), eol),
           protocolEol(previousDecisionProtocolBlock(12, source, true), eol),
           protocolEol(previousDecisionProtocolBlock(11, source), eol),

package/package.json

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