@kylecheng3146/agent-ops 0.2.7 → 0.3.0

package/docs/en/guides/configuration.md

@@ -132,6 +132,48 @@ agent-ops doctor --check-auth # one real print call per target
 reports what to do but never fixes it: every target authenticates through
 interactive OAuth, so there is no `--fix`. Run `<target> login` yourself.
 
+### Parallel sessions in worktrees
+
+Verification, review and the completion gate all fingerprint the whole Git
+change surface, so two conversations editing one checkout void each other's
+evidence. Give each editing conversation its own worktree instead:
+
+```json
+{
+  "worktree": {
+    "mode": "auto",
+    "setup": [{ "command": "pnpm", "args": ["install", "--frozen-lockfile"] }]
+  }
+}
+```
+
+- `mode: "auto"` routes every editing conversation through
+  `agent-ops worktree add <name> --session <id>`, run from the main checkout.
+  On Claude Code a direct Edit or Write of the main checkout outside
+  `.worktrees/` is denied (run `agent-ops update` once so the PreToolUse hook
+  matches the file tools). Absent or `"off"` keeps today's single checkout.
+- `add` creates `.worktrees/<name>` on branch `agent-ops/<name>` from the main
+  checkout's HEAD and excludes `/.worktrees/` through `.git/info/exclude`,
+  never `.gitignore`. It copies the ignored files agent-ops installed and any
+  file matched by a root `.worktreeinclude` (gitignore syntax, for example
+  `.env` or `local.properties`); a file Git already checked out is never
+  overwritten. Trust is inherited only when the main checkout is trusted and
+  the worktree's effective config is identical.
+- `setup` commands run in the new worktree (default timeout ten minutes) for
+  what Git does not carry, such as installed dependencies. They are part of
+  the trusted config, so they need no separate approval; a failing step
+  removes the worktree again.
+- The session's completion gate follows it: Claude Code enters the worktree
+  with EnterWorktree, and a host that cannot move a session (agy) is judged by
+  the worktree's gate through a redirect the main checkout records.
+- `agent-ops worktree finish <name>` merges by fast-forward only, one finish
+  at a time. If the target moved, it rebases; a clean rebase whose own patch
+  is unchanged is re-verified before merging, and a conflict is reported with
+  the `refs/notes/agent-ops` intent of the work that landed first.
+- `worktree list`, `resume <name> --session <id>` and `remove <name>` manage
+  what is left; `remove --force` discards work and asks the user first.
+  `doctor` reports worktrees idle for more than seven days.
+
 ### Project-local loop profile
 
 `--profile loop` is an opt-in project-scope profile. Select `codex`, `claude`,

package/docs/en/spec/delegation.md

@@ -29,3 +29,13 @@ Concurrent delegated writers MUST NOT share one working tree.
 - Evidence: `agent-ops verify` returns a status other than `UNKNOWN` for the run.
 - Positive: `Read-only scans run in parallel; the single edit runs in the coordinator worktree.`
 - Negative: `Two subagents edit the same files while verification runs.`
+
+## DELEGATE-ISOLATION-002
+
+Parallel editing conversations in one repository MUST each work in their own agent-ops worktree.
+
+- Trigger: `worktree.mode` is `auto`, or a second conversation will edit the repository while another is still open.
+- Action: Run `agent-ops worktree add <name> --session <id>` from the main checkout before the first edit, work only in the printed path, and merge with `agent-ops worktree finish <name>` after the task completes against the printed `--base`.
+- Evidence: `agent-ops worktree list` shows one worktree per editing session, and each finish reports a fast-forward merge.
+- Positive: `Two conversations edit .worktrees/login and .worktrees/cart; each verifies, reviews and finishes on its own.`
+- Negative: `Two conversations edit the main checkout at once, so each one's verification and review is voided by the other's writes.`

package/docs/zh-TW/guides/configuration.md

@@ -116,6 +116,46 @@ agent-ops doctor --check-auth # 每個目標一次真實 print 呼叫
 不會代為修復：所有目標都經由互動式 OAuth 認證，因此沒有 `--fix`。
 請自行執行 `<target> login`。
 
+### 在 worktree 中並行 session
+
+Verification、review 與 completion gate 都對整個 Git change surface 計算
+fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方的 evidence。
+請讓每個修改中的對話使用自己的 worktree：
+
+```json
+{
+  "worktree": {
+    "mode": "auto",
+    "setup": [{ "command": "pnpm", "args": ["install", "--frozen-lockfile"] }]
+  }
+}
+```
+
+- `mode: "auto"` 讓每個修改中的對話都先在主 checkout 執行
+  `agent-ops worktree add <name> --session <id>`。Claude Code 直接以 Edit 或
+  Write 修改主 checkout 中 `.worktrees/` 以外的檔案會被拒絕（需先執行一次
+  `agent-ops update`，讓 PreToolUse hook 比對檔案工具）。未設定或 `"off"` 則維持
+  目前的單一 checkout。
+- `add` 從主 checkout 的 HEAD 建立 `.worktrees/<name>` 與 branch
+  `agent-ops/<name>`，並透過 `.git/info/exclude`（而非 `.gitignore`）排除
+  `/.worktrees/`。它會複製 agent-ops 安裝的 ignored 檔案，以及根目錄
+  `.worktreeinclude`（gitignore 語法，例如 `.env` 或 `local.properties`）比對到
+  的檔案；Git 已 checkout 的檔案一律不覆寫。只有主 checkout 已 trusted 且
+  worktree 的 effective config 完全相同時才繼承 trust。
+- `setup` 指令在新 worktree 中執行（預設 timeout 十分鐘），處理 Git 不會帶過去
+  的東西，例如已安裝的相依套件。它屬於 trusted config 的一部分，不需另外核准；
+  任一步驟失敗會移除該 worktree。
+- Session 的 completion gate 會跟著它：Claude Code 以 EnterWorktree 進入
+  worktree；無法移動 session 的 host（agy）則透過主 checkout 記錄的 redirect，
+  由 worktree 的 gate 判定。
+- `agent-ops worktree finish <name>` 只以 fast-forward 合併，一次只執行一個
+  finish。Target 若已前進會先 rebase；沒有衝突且自身 patch 不變的 rebase 會先
+  重新驗證再合併；衝突則連同先合併那份工作在 `refs/notes/agent-ops` 的意圖一起
+  回報。
+- `worktree list`、`resume <name> --session <id>` 與 `remove <name>` 管理剩下的
+  worktree；`remove --force` 會丟棄工作，執行前會先詢問使用者。`doctor` 會回報
+  閒置超過七天的 worktree。
+
 ### Project-local loop profile
 
 `--profile loop` 是明確 opt-in 的 project-scope profile。請選擇 `codex`、

package/docs/zh-TW/spec/delegation.md

@@ -1,6 +1,6 @@
 # 委派
 
-English source version: 2026-07-23. Revalidate: when the English specification changes.
+English source version: 2026-09-24. Revalidate: when the English specification changes.
 
 ## DELEGATE-SCOPE-001
 
@@ -31,3 +31,13 @@ English source version: 2026-07-23. Revalidate: when the English specification c
 - Evidence: `agent-ops verify` 該次執行回傳非 `UNKNOWN` 的狀態。
 - Positive: `唯讀掃描並行執行；唯一的修改在協調者工作區進行。`
 - Negative: `兩個 subagent 在驗證執行期間修改相同檔案。`
+
+## DELEGATE-ISOLATION-002
+
+同一個 repository 中並行修改檔案的對話 MUST 各自在自己的 agent-ops worktree 中工作。
+
+- Trigger: `worktree.mode` 為 `auto`，或另一個對話仍開著時，第二個對話也要修改這個 repository。
+- Action: 第一次修改前，在主 checkout 執行 `agent-ops worktree add <name> --session <id>`，只在印出的路徑中工作；task 以印出的 `--base` 完成後，用 `agent-ops worktree finish <name>` 合併。
+- Evidence: `agent-ops worktree list` 顯示每個修改中的 session 各有一個 worktree，且每次 finish 都回報 fast-forward 合併。
+- Positive: `兩個對話分別修改 .worktrees/login 與 .worktrees/cart；各自驗證、review 並 finish。`
+- Negative: `兩個對話同時修改主 checkout，彼此的寫入讓對方的驗證與 review 全部作廢。`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "MIT",

package/schemas/config.schema.json

@@ -119,6 +119,41 @@
         }
       }
     },
+    "worktree": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode"],
+      "properties": {
+        "mode": {
+          "enum": ["auto", "off"]
+        },
+        "setup": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["command", "args"],
+            "properties": {
+              "command": {
+                "$ref": "#/$defs/nonEmptyString"
+              },
+              "args": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^[^\\u0000]*$"
+                }
+              },
+              "timeoutMs": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 2147483647
+              }
+            }
+          }
+        }
+      }
+    },
     "securityExceptions": {
       "type": "array",
       "items": {