@adamchanadam/agent-handoff-kit 0.3.35 → 0.3.37

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Agent Handoff Kit
2
2
 
3
- 狀態:目前版本為 `v0.3.35`。這是早期可用版本,仍在持續完善中。
3
+ 狀態:目前版本為 `v0.3.37`。
4
4
 
5
5
  <p align="center">
6
6
  <img src="https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif" alt="Agent Handoff Kit 功能簡介動畫" width="720">
@@ -8,11 +8,11 @@
8
8
 
9
9
  Agent Handoff Kit 是 **AI 對話之間的接力棒**。
10
10
 
11
- 它只處理一件狹窄但重要的事:AI 跨對話失憶。每次開新對話,AI 往往不記得你上次做到哪裡,也認不出中途新建的文件、你引入的參考資料、哪些檔案是真源。這套工具把進度、下一步、風險、檔案登記與下次開工提示寫進固定文件,讓下一個 AI 工具能接得上上一棒。
11
+ 它只處理一件狹窄但重要的事:AI 跨對話失憶。每次開新對話,AI 往往不記得你上次做到哪裡,也認不出中途新建的文件、你引入的參考資料、哪份文件才是最新依據。這套工具把進度、下一步、風險、檔案登記與下次開工提示寫進固定文件,讓下一個 AI 工具能接得上上一棒。
12
12
 
13
- 📌 使用時,你只需要說明目的;確認資料夾、判斷安裝或升級、執行指令和檢查結果,交給能讀寫本機資料夾的 AI 處理。
14
-
15
- ## 🚀 三步上手
13
+ 📌 使用時,你只需要說明目的;確認資料夾、判斷安裝或升級、執行指令和檢查結果,交給能讀寫本機資料夾的 AI 處理。
14
+
15
+ ## 🚀 三步上手
16
16
 
17
17
  第一次用,不需要先讀完整 README,也不需要研究終端機指令。只做三件事:
18
18
 
@@ -39,27 +39,27 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
39
39
 
40
40
  | 入口 | 用途 |
41
41
  |---|---|
42
- | `README.md` | 正式用途、安裝路徑、限制與安全邊界。 |
42
+ | `README.md` | 正式用途、安裝路徑與安全邊界。 |
43
43
  | [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html) | 非技術版 60 秒入門與宣傳動畫。 |
44
44
  | [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html) | 三個實操情景,示範開工、工作、收工。 |
45
45
  | [`agent-handoff-kit-ai-install.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.html) | 給 AI 讀的安裝與升級指令頁。 |
46
46
 
47
- repo 內的 `scripts/`、`test-fixtures/`、`docs/qa/` 和部分設計文件,是維護者用來測試升級、安全合併和發佈品質的材料。普通用戶不需要閱讀,也不會被 npm 安裝到你的項目;npm package 只包含實際執行需要的核心檔案。
48
-
49
- 維護者請看 [`MAINTAINERS.md`](MAINTAINERS.md)。
47
+ 這個公開 repo 保留使用、安裝、入門、GitHub Pages 與 npm 執行所需內容。日常使用時,你只需要從上面四個入口開始。
50
48
 
51
49
  ## 🔎 它解決甚麼問題
52
50
 
53
- 用 AI 做長期項目,常見四個問題:
51
+ 用 AI 做長期項目,常見五個問題:
54
52
 
55
53
  | 問題 | Agent Handoff Kit 怎樣處理 |
56
54
  |---|---|
57
55
  | 新 AI 不知做到哪 | 用 `dev/SESSION_HANDOFF.md` 保存目前狀態、下一步、風險與驗收。 |
58
- | 新建檔案、參考資料變孤兒 | 你可以叫 AI 把文件接入 Agent Handoff Kit,用 `dev/PROJECT_INDEX.md` 與 `dev/DOC_SYNC_REGISTRY.md` 登記檔案角色、真源與同步責任。 |
59
- | 不同 AI 工具入口不同 | 同時安裝 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,全部指向同一套開工流程;Antigravity CLI 會讀工作資料夾內的 `AGENTS.md` 與 `GEMINI.md`。 |
60
- | AI 可能亂改、亂刪或誤發佈 | 內置安全規則;高風險操作必須先講計劃,破壞性指令與未批准發佈一律禁止。 |
61
-
62
- 它不是聊天機器人,也不是開發框架。它比較像一本固定放在專案內的交接簿。
56
+ | 新建檔案、參考資料變孤兒 | 你可以叫 AI 把文件接入 Agent Handoff Kit,記低每份文件的用途、哪份作準、何時要同步。 |
57
+ | 不同 AI 工具入口不同 | 同時安裝 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,全部指向同一套開工流程;Antigravity CLI 會讀工作資料夾內的 `AGENTS.md` 與 `GEMINI.md`。 |
58
+ | AI 可能亂改、亂刪或誤發佈 | 內置安全規則;高風險操作必須先講計劃,破壞性指令與未批准發佈一律禁止。 |
59
+ | 外部工具用完後殘留或亂清理 | 使用 MCP、browser、自動化工具、notebook 或 helper server 後,AI 會按 ownership 判斷:本任務資源可收口,不明或共享資源先回報證據並等你確認。 |
60
+
61
+
62
+ 它不是聊天機器人,也不是開發框架。它比較像一本固定放在專案內的交接簿。
63
63
 
64
64
  ## 🧰 適用工具
65
65
 
@@ -145,9 +145,9 @@ AI 會處理檢查,不會把「檢查通過」誤當成已理解你的專案
145
145
  |---|---|
146
146
  | 寫程式 / 修錯誤 | 先讀項目索引、相關檔案,再改動和測試。 |
147
147
  | 寫文章 / README / 社交帖文 | 先確認讀者、目的、語氣和發布位置。 |
148
- | 查資料 / 比較工具 | 分清已驗證事實、來源摘要和 AI 推論。 |
148
+ | 查資料 / 比較工具 | 分清已驗證事實、來源摘要和 AI 的判斷。 |
149
149
  | 刪檔 / Git / 發佈 / npm | 高風險操作必須先說明影響,並等你確認。 |
150
- | Notion / Google Drive 等外部工具 | 先核對目前工具 schema 或官方文件;機密不寫入項目文件。 |
150
+ | Notion / Google Drive 等外部工具 | 先核對目前工具說明或官方文件;用後按資源歸屬安全收口;機密不寫入項目文件。 |
151
151
 
152
152
  你只要用日常話說目的,例如「幫我改 README」、「幫我查這個工具是否適合」、「把這份文件接入 Agent Handoff Kit」。AI 會自己判斷要用哪些規則。
153
153
 
@@ -169,24 +169,26 @@ AI 應先判斷這條規則應放在哪裡:是一次性備忘、下次交接
169
169
  | 結束本輪工作 | 「收工」 |
170
170
  | 讓新文件不變成孤兒 | 「把這份文件接入 Agent Handoff Kit,讓下次 AI 知道何時要讀、何時要更新。」 |
171
171
  | 掃描可能被遺漏的重要文件 | 「掃描未接入 Agent Handoff Kit 的重要文件。」 |
172
- | 把錯誤經驗保存成日後機制 | 「把今次錯誤變成日後機制,寫入長期治理。」 |
173
- | 讓 API / 工具用法之後都生效 | 「以後都用這個 API 調用方式,跨 session 生效。」 |
174
- | 使用外部工具,例如 Notion、Google Drive、GitHub | 「這個項目會用到這些外部工具,請記住哪些能直接使用,機密不要寫入項目文件。」 |
175
-
176
- 這個掃描只列出候選與缺口,不會自動修改;是否接入、合併或退役由你確認。
172
+ | 讓 AI 下次避免同類錯誤 | 「把今次錯誤整理成日後工作規則,讓下次 AI 知道要怎樣避免。」 |
173
+ | 讓 API / 工具用法下次仍生效 | 「以後都用這個 API 調用方式,之後開新對話也要沿用。」 |
174
+ | 使用外部工具,例如 Notion、Google Drive、GitHub | 「這個項目會用到這些外部工具,請記住哪些能直接使用,機密不要寫入項目文件。」 |
175
+ | 長任務用了 MCP、browser 或自動化工具 | 「收工時請顯示外部工具資源收口結果:已關閉哪些本任務資源,哪些因歸屬不明而保留並列證據。」 |
177
176
 
178
- 長期機制不應只寫入 `dev/SESSION_LOG.md`,也不只留在 session log 或 handoff;AI 應放入合適的長期治理位置。
177
+ 掃描重要文件時,AI 只會先列出可能需要接入的文件與原因,不會自動修改;是否接入、合併或退役由你確認。
178
+
179
+ 需要長期保留的規則,AI 應寫入合適的項目文件,而不是只留在當次對話摘要。
179
180
 
180
- 如涉及刪除、改名、合併真源、發佈、上傳或權限變更,AI 應先說明影響並等你確認。
181
+ 如涉及刪除、改名、合併權威文件、發佈、上傳或權限變更,AI 應先說明影響並等你確認。
181
182
 
182
183
  ## 🛡️ 安全護欄
183
184
 
184
185
  就算你不懂代碼,這套工具也會要求 AI 在高風險操作前停下來講清楚。
185
186
 
186
- - 禁止破壞性指令:例如 `rm -rf`、`git reset --hard`、強制推送、系統根路徑操作。
187
- - 機密保護:`.env`、API key、token 不可印出、不可提交、不可上傳。
188
- - 查證不猜:使用第三方服務、Connector、MCP、CLI、API 或 plugin API 前,先核對目前工具 schema、官方文件或有版本日期的本地 runbook;查不到就標示未核實。
189
- - 權限不足就停手:檔案被鎖或沒有權限時,輸出手動操作清單,不嘗試繞過。
187
+ - 禁止破壞性指令:例如 `rm -rf`、`git reset --hard`、強制推送、系統根路徑操作。
188
+ - 機密保護:`.env`、API key、token 不可印出、不可提交、不可上傳。
189
+ - 查證不猜:使用第三方服務、Connector、MCP、CLI、API 或 plugin API 前,先核對目前工具說明、官方文件或已驗證的本地操作說明;查不到就標示未核實。
190
+ - 外部工具安全收口:用完 MCP、browser、自動化工具、notebook 或 helper server 後,AI 只可自動關閉能證明屬於本任務的資源;不明、共享、使用者或其他 AI agent 可能擁有的程序與暫存資料,必須先回報並等你確認。
191
+ - 權限不足就停手:檔案被鎖或沒有權限時,輸出手動操作清單,不嘗試繞過。
190
192
  - 發佈需明確批准:建立版本標籤、GitHub Release、npm publish、部署或上傳,都不能因「準備好了」而自動執行。
191
193
 
192
194
  ## 🔗 可選配合:Adam-AI-Instructions
@@ -196,13 +198,4 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
196
198
  - **Adam-AI-Instructions** 負責 AI 在**單一對話**內的做事規矩:語氣、做事優先序、回覆骨架、計算紀律、用語紀律、安全護欄、輸出層分工。屬「AI 應該怎樣答你」的持久基準。
197
199
  - **Agent Handoff Kit** 負責 AI 在**對話之間**的接力:當前狀態、下一步、檔案登記、收工同下次開工。屬「AI 在對話之間怎樣記住你的項目」的持久基準。
198
200
 
199
- 這是可選配合,不影響 Agent Handoff Kit 的安裝和日常使用。想使用時,到該倉庫選擇適合你 AI 工具的版本,貼入 AI 工具設定即可。
200
-
201
- ## ⚠️ 目前限制
202
-
203
- - 目前版本為 `v0.3.35`;正式安裝請以 npm registry `latest` 顯示為準。
204
- - 這是早期可用版本,仍在持續完善中。
205
- - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
206
- - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
207
- - 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
208
-
201
+ 這是可選配合,不影響 Agent Handoff Kit 的安裝和日常使用。想使用時,到該倉庫選擇適合你 AI 工具的版本,貼入 AI 工具設定即可。
@@ -52,9 +52,11 @@ const requiredAnchors = [
52
52
  "dev/RULE_PACKS.md",
53
53
  "Agent Handoff Kit v<version>",
54
54
  "Display version rule",
55
- "Agent Handoff Kit template version",
56
- "continuity ready",
57
- "Start Agent Handoff",
55
+ "Agent Handoff Kit template version",
56
+ "continuity ready",
57
+ "推薦下一步",
58
+ "recommended action",
59
+ "Start Agent Handoff",
58
60
  "Ambiguous startup phrases",
59
61
  "Reachable is not the same as ingested",
60
62
  "Do not treat unread sources as absent",
@@ -111,15 +113,27 @@ const requiredAnchors = [
111
113
  "ack:section:sync-status",
112
114
  "ack:section:next-task-required-reading",
113
115
  "ack:section:state-reconciliation-check",
114
- "ack:section:next-session-opening-message",
115
- "ack:field:lifecycle-conflicts-resolved",
116
+ "ack:section:next-session-opening-message",
117
+ "ack:field:recommended-next-step-explicit",
118
+ "ack:field:lifecycle-conflicts-resolved",
116
119
  "ack:field:persistence-routing-checked",
117
120
  "📋 Next session:",
118
121
  "```text",
119
122
  "Read in order:",
120
- "dev/DOC_SYNC_REGISTRY.md"
121
- ]
122
- },
123
+ "dev/DOC_SYNC_REGISTRY.md"
124
+ ]
125
+ },
126
+ {
127
+ target: "dev/rules/communication.md",
128
+ label: "communication recommended next-step discipline",
129
+ snippets: [
130
+ "Communication Pack",
131
+ "recommended next step",
132
+ "state it directly with a short reason",
133
+ "Offer two or three choices only when the user truly must decide",
134
+ "do not turn an already-made technical judgment into an open question"
135
+ ]
136
+ },
123
137
  {
124
138
  target: "dev/SESSION_LOG.md",
125
139
  label: "session log event and opening message schema",
@@ -166,17 +180,27 @@ const requiredAnchors = [
166
180
  "not current state"
167
181
  ]
168
182
  },
169
- {
170
- target: "dev/PROJECT_INDEX.md",
171
- label: "template version metadata",
172
- placement: projectIndexAnchorPlacement,
173
- snippets: [
174
- "Agent Handoff Kit template version"
175
- ]
176
- },
177
- {
178
- target: "dev/rules/safety.md",
179
- label: "safety pack high-risk anchors",
183
+ {
184
+ target: "dev/PROJECT_INDEX.md",
185
+ label: "template version metadata",
186
+ placement: projectIndexAnchorPlacement,
187
+ snippets: [
188
+ "Agent Handoff Kit template version"
189
+ ]
190
+ },
191
+ {
192
+ target: "dev/PROJECT_INDEX.md",
193
+ label: "tool operation references",
194
+ snippets: [
195
+ "Tool Operation References",
196
+ "runtime-controlled tools",
197
+ "Source and version/date",
198
+ "Scope and known limits"
199
+ ]
200
+ },
201
+ {
202
+ target: "dev/rules/safety.md",
203
+ label: "safety pack high-risk anchors",
180
204
  placement: safetyAnchorPlacement,
181
205
  snippets: [
182
206
  "deleting, overwriting, moving, renaming",
@@ -187,7 +211,11 @@ const requiredAnchors = [
187
211
  "parser failure",
188
212
  "secret values",
189
213
  "task-owned or agent-managed",
190
- "other-agent-owned"
214
+ "other-agent-owned",
215
+ "browser profiles",
216
+ "desktop app sessions",
217
+ "shared tool servers",
218
+ "notebook kernels"
191
219
  ]
192
220
  },
193
221
  {
@@ -246,9 +274,12 @@ const requiredAnchors = [
246
274
  "Source-of-truth Architecture",
247
275
  "Cross-session Lifecycle",
248
276
  "Connector-first default",
249
- "Anti-pattern"
250
- ]
251
- }
277
+ "Runtime-Controlled Tool Operation Variants",
278
+ "Tool Operation References",
279
+ "Do not guess Chrome, Playwright, or DevTools commands",
280
+ "Anti-pattern"
281
+ ]
282
+ }
252
283
  ];
253
284
 
254
285
  const schemaChecks = [
@@ -281,9 +312,10 @@ const schemaChecks = [
281
312
  section("handoff-sufficiency-check", "Handoff Sufficiency Check"),
282
313
  section("next-session-opening-message", "Next Session Opening Message"),
283
314
  marker("field", "stale-snapshots-left", "Stale snapshots left in this handoff"),
284
- marker("field", "lifecycle-conflicts-resolved", "Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified"),
285
- marker("field", "persistence-routing-checked", "Persistence routing checked"),
286
- marker("field", "opening-message-matches-current-state", "Opening message matches current state"),
315
+ marker("field", "lifecycle-conflicts-resolved", "Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified"),
316
+ marker("field", "persistence-routing-checked", "Persistence routing checked"),
317
+ marker("field", "recommended-next-step-explicit", "Recommended next step is explicit and reasoned"),
318
+ marker("field", "opening-message-matches-current-state", "Opening message matches current state"),
287
319
  marker("field", "state-sections-rewritten-or-confirmed", "State sections rewritten or confirmed current"),
288
320
  marker("field", "user-intent", "User intent:"),
289
321
  marker("field", "task-essence", "Task essence:"),
@@ -340,9 +372,10 @@ const schemaChecks = [
340
372
  heading("Directory Map"),
341
373
  heading("Entry Points"),
342
374
  heading("Fact Base"),
343
- heading("External Sources"),
344
- heading("Installed Integrations"),
345
- heading("Local QC Commands"),
375
+ heading("External Sources"),
376
+ heading("Installed Integrations"),
377
+ heading("Tool Operation References"),
378
+ heading("Local QC Commands"),
346
379
  heading("Workspace Identity"),
347
380
  heading("Change Hotspots"),
348
381
  heading("Maintenance Rule"),
@@ -359,9 +392,10 @@ const schemaChecks = [
359
392
  tableHeader("Server", "Source", "Project Usage", "Credential Reference (no value)", "Declared", "Last Verified"),
360
393
  tableHeader("Name", "Bundle Content (Skills + MCP + hooks)", "When Triggered", "Last Verified"),
361
394
  tableHeader("Name", "Source", "When Triggered", "Last Verified"),
362
- tableHeader("Layer", "Surface (specific instance)", "Role", "Write Direction")
363
- ]
364
- },
395
+ tableHeader("Layer", "Surface (specific instance)", "Role", "Write Direction"),
396
+ tableHeader("Tool / operation", "Reference path or URL", "Required before", "Source and version/date", "Scope and known limits", "Last verified")
397
+ ]
398
+ },
365
399
  {
366
400
  target: "dev/DOC_SYNC_REGISTRY.md",
367
401
  label: "doc sync registry status vocabulary",
@@ -1781,7 +1815,7 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1781
1815
  // Extract just the ## Installed Integrations block from source (not touching External Sources).
1782
1816
  const sourceInstalledMatch = sourceText.match(/(## Installed Integrations[\s\S]*?)(?=## Local QC Commands)/);
1783
1817
  if (sourceInstalledMatch && targetText.includes("## Local QC Commands")) {
1784
- const installedBlock = sourceInstalledMatch[1];
1818
+ const installedBlock = sourceInstalledMatch[1];
1785
1819
  return {
1786
1820
  ...base,
1787
1821
  action: "merge",
@@ -1790,6 +1824,19 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1790
1824
  };
1791
1825
  }
1792
1826
  }
1827
+ if (targetRel === "dev/PROJECT_INDEX.md" && command === "upgrade" && !targetText.includes("## Tool Operation References")) {
1828
+ const sourceToolRefsMatch = sourceText.match(/(## Tool Operation References[\s\S]*?)(?=## Local QC Commands)/);
1829
+ if (sourceToolRefsMatch && targetText.includes("## Local QC Commands")) {
1830
+ const toolRefsBlock = sourceToolRefsMatch[1];
1831
+ const normalizedTarget = mergeProjectIndexCredentialReferences(targetText);
1832
+ return {
1833
+ ...base,
1834
+ action: "merge",
1835
+ reason: "insert ## Tool Operation References section template before ## Local QC Commands and normalize integration reference wording (runtime-controlled tool operation governance)",
1836
+ mergedText: normalizedTarget.replace("## Local QC Commands", toolRefsBlock + "## Local QC Commands")
1837
+ };
1838
+ }
1839
+ }
1793
1840
  if (targetRel === "dev/PROJECT_INDEX.md" && command === "upgrade" && (
1794
1841
  targetText.includes("Credential Location")
1795
1842
  || targetText.includes("Credential Reference(no value)")
@@ -1861,20 +1908,32 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1861
1908
  mergedText: mergedHandoff
1862
1909
  };
1863
1910
  }
1864
- if (targetRel === "dev/SESSION_HANDOFF.md" && command === "upgrade" && !targetText.includes("ack:field:persistence-routing-checked")) {
1865
- const mergedHandoff = mergeHandoffPersistenceRoutingField(targetText);
1866
- if (!mergedHandoff) {
1867
- return { ...base, action: "conflict", reason: "SESSION_HANDOFF.md state reconciliation markers were changed; manual merge required to add persistence routing field" };
1868
- }
1911
+ if (targetRel === "dev/SESSION_HANDOFF.md" && command === "upgrade" && !targetText.includes("ack:field:persistence-routing-checked")) {
1912
+ const mergedHandoff = mergeHandoffPersistenceRoutingField(targetText);
1913
+ if (!mergedHandoff) {
1914
+ return { ...base, action: "conflict", reason: "SESSION_HANDOFF.md state reconciliation markers were changed; manual merge required to add persistence routing field" };
1915
+ }
1869
1916
  return {
1870
1917
  ...base,
1871
1918
  action: "merge",
1872
1919
  reason: "insert persistence routing field into State Reconciliation Check (one-time evidence must not drive next-session state)",
1873
- mergedText: mergedHandoff
1874
- };
1875
- }
1876
- if (targetRel === "dev/SESSION_HANDOFF.md" && command === "upgrade" && isUpgradeFromOlderTemplate(context)) {
1877
- const lifecycleValue = fieldValueAfterMarker(targetText, "lifecycle-conflicts-resolved");
1920
+ mergedText: mergedHandoff
1921
+ };
1922
+ }
1923
+ if (targetRel === "dev/SESSION_HANDOFF.md" && command === "upgrade" && !targetText.includes("ack:field:recommended-next-step-explicit")) {
1924
+ const mergedHandoff = mergeHandoffRecommendedNextStepDiscipline(targetText);
1925
+ if (!mergedHandoff) {
1926
+ return { ...base, action: "conflict", reason: "SESSION_HANDOFF.md state reconciliation markers were changed; manual merge required to add recommended next-step field" };
1927
+ }
1928
+ return {
1929
+ ...base,
1930
+ action: "merge",
1931
+ reason: "insert recommended next-step field and preserve existing next-priority items",
1932
+ mergedText: mergedHandoff
1933
+ };
1934
+ }
1935
+ if (targetRel === "dev/SESSION_HANDOFF.md" && command === "upgrade" && isUpgradeFromOlderTemplate(context)) {
1936
+ const lifecycleValue = fieldValueAfterMarker(targetText, "lifecycle-conflicts-resolved");
1878
1937
  if (isPlaceholderLifecycleFieldValue(lifecycleValue) && hasSubstantiveHandoffState(targetText)) {
1879
1938
  const mergedHandoff = reclassifyExistingHandoffLifecyclePlaceholder(targetText);
1880
1939
  if (!mergedHandoff) {
@@ -2188,7 +2247,7 @@ function onboardingAnchorPlacement(snippet, text) {
2188
2247
  }
2189
2248
 
2190
2249
  function integrationsAnchorPlacement(snippet, text) {
2191
- if (snippet === "Credential Separation Principle" || snippet === "External Tool Usage Verification Gate" || snippet === "External Tool Resource Lifecycle" || snippet === "do not invent" || snippet === "input schema" || snippet === "official documentation" || snippet === "Source-of-truth Architecture" || snippet === "Cross-session Lifecycle") {
2250
+ if (snippet === "Credential Separation Principle" || snippet === "External Tool Usage Verification Gate" || snippet === "External Tool Resource Lifecycle" || snippet === "do not invent" || snippet === "input schema" || snippet === "official documentation" || snippet === "Source-of-truth Architecture" || snippet === "Cross-session Lifecycle" || snippet === "Runtime-Controlled Tool Operation Variants" || snippet === "Tool Operation References" || snippet === "Do not guess Chrome, Playwright, or DevTools commands") {
2192
2251
  return snippetAppearsBetweenHeadings(text, snippet, "## Discipline", "## Rules");
2193
2252
  }
2194
2253
  if (snippet === "Connector-first default") {
@@ -2253,14 +2312,22 @@ const semanticAnchorRepairStrategies = {
2253
2312
  mergedText: mergedDecisions
2254
2313
  } : null;
2255
2314
  },
2256
- "dev/rules/safety.md": (targetText, sourceText, missing) => {
2257
- const mergedSafety = mergeSafetyRulesByMissingAnchors(targetText, sourceText, missing);
2258
- return mergedSafety ? {
2259
- action: "merge",
2260
- reason: "restore safety pack high-risk rules in ## Rules section",
2261
- mergedText: mergedSafety
2262
- } : null;
2263
- },
2315
+ "dev/rules/safety.md": (targetText, sourceText, missing) => {
2316
+ const mergedSafety = mergeSafetyRulesByMissingAnchors(targetText, sourceText, missing);
2317
+ return mergedSafety ? {
2318
+ action: "merge",
2319
+ reason: "restore safety pack high-risk rules in ## Rules section",
2320
+ mergedText: mergedSafety
2321
+ } : null;
2322
+ },
2323
+ "dev/rules/communication.md": (targetText, sourceText, missing) => {
2324
+ const mergedCommunication = mergeCommunicationNextStepDiscipline(targetText, sourceText, missing);
2325
+ return mergedCommunication ? {
2326
+ action: "merge",
2327
+ reason: "insert communication pack recommended next-step discipline without replacing local prose",
2328
+ mergedText: mergedCommunication
2329
+ } : null;
2330
+ },
2264
2331
  "dev/rules/integrations.md": (targetText, sourceText, missing) => {
2265
2332
  const mergedIntegrations = mergeIntegrationsSectionsByMissingAnchors(targetText, sourceText, missing);
2266
2333
  return mergedIntegrations ? {
@@ -2271,7 +2338,7 @@ const semanticAnchorRepairStrategies = {
2271
2338
  }
2272
2339
  };
2273
2340
 
2274
- function mergeMissingRequiredAnchorsSemantically(targetRel, targetText, sourceText) {
2341
+ function mergeMissingRequiredAnchorsSemantically(targetRel, targetText, sourceText) {
2275
2342
  const missing = missingRequiredAnchorSnippets(targetRel, targetText);
2276
2343
  if (missing.length === 0) return null;
2277
2344
 
@@ -2331,6 +2398,33 @@ function mergeProjectIndexTemplateVersionRow(targetText, sourceText) {
2331
2398
  return lines.join("\n");
2332
2399
  }
2333
2400
 
2401
+ function mergeCommunicationNextStepDiscipline(targetText, sourceText, missing) {
2402
+ if (!missing.some((snippet) => snippet === "recommended next step" || snippet === "state it directly with a short reason" || snippet === "do not turn an already-made technical judgment into an open question")) return null;
2403
+ if (!targetText.includes("# Communication Pack")) return null;
2404
+ if (countText(targetText, "## Rules") !== 1 || countText(targetText, "## Checks") !== 1 || countText(targetText, "## Closeout") !== 1) return null;
2405
+
2406
+ const sourceRule = sourceText.split(/\r?\n/).find((line) => line.includes("Give a clear recommended next step"));
2407
+ const sourceCheck = sourceText.split(/\r?\n/).find((line) => line.includes("Confirm user-facing next-step wording names the recommended action"));
2408
+ if (!sourceRule || !sourceCheck) return null;
2409
+
2410
+ let merged = targetText;
2411
+ if (!merged.includes("Give a clear recommended next step")) {
2412
+ const rulesBounds = textSectionBounds(merged, "## Rules", "## Checks");
2413
+ if (!rulesBounds) return null;
2414
+ const rulesBlock = merged.slice(rulesBounds.start, rulesBounds.end);
2415
+ if (/^6\. /m.test(rulesBlock)) return null;
2416
+ merged = `${merged.slice(0, rulesBounds.end).trimEnd()}\n${sourceRule}\n\n${merged.slice(rulesBounds.end).trimStart()}`;
2417
+ }
2418
+
2419
+ if (!merged.includes("Confirm user-facing next-step wording names the recommended action")) {
2420
+ const checksBounds = textSectionBounds(merged, "## Checks", "## Closeout");
2421
+ if (!checksBounds) return null;
2422
+ merged = `${merged.slice(0, checksBounds.end).trimEnd()}\n${sourceCheck}\n\n${merged.slice(checksBounds.end).trimStart()}`;
2423
+ }
2424
+
2425
+ return merged === targetText ? null : merged;
2426
+ }
2427
+
2334
2428
  function mergeProjectIndexCredentialReferences(targetText) {
2335
2429
  return targetText
2336
2430
  .replace(
@@ -2435,7 +2529,7 @@ function mergeSafetyRulesByMissingAnchors(targetText, sourceText, missing) {
2435
2529
  if (!remainingMissing.includes(snippet) || targetText.includes(snippet)) continue;
2436
2530
  const sourceRule = sourceRuleLines.find((line) => line.includes(snippet));
2437
2531
  if (!sourceRule || !sourceRule.startsWith(`${number}. `)) return null;
2438
- if (!targetLines.some((line, index) => index >= targetRuleStart && index < targetRuleEnd && line.startsWith(`${number}. `))) {
2532
+ if (!targetLines.some((line, index) => index >= targetRuleStart && line.startsWith(`${number}. `))) {
2439
2533
  targetLines.splice(targetRuleEnd, 0, sourceRule);
2440
2534
  changed = true;
2441
2535
  remainingMissing.splice(remainingMissing.indexOf(snippet), 1);
@@ -2451,13 +2545,26 @@ function mergeSafetyRulesByMissingAnchors(targetText, sourceText, missing) {
2451
2545
  changed = true;
2452
2546
  remainingMissing.splice(remainingMissing.indexOf("parser failure"), 1);
2453
2547
  }
2454
-
2455
- for (const snippet of remainingMissing) {
2456
- const sourceLine = sourceRuleLines.find((line) => line.includes(snippet));
2457
- if (!sourceLine) return null;
2458
- const ruleNumber = sourceLine.match(/^(\d+)\. /)?.[1];
2459
- if (!ruleNumber) return null;
2460
- const targetIndex = targetLines.findIndex((line, index) => index >= targetRuleStart && index < targetRuleEnd && line.startsWith(`${ruleNumber}. `));
2548
+
2549
+ const rule14Snippets = ["browser profiles", "desktop app sessions", "shared tool servers", "notebook kernels"];
2550
+ if (remainingMissing.some((snippet) => rule14Snippets.includes(snippet))) {
2551
+ const sourceRule14 = sourceRuleLines.find((line) => line.startsWith("14. ") && line.includes("Process termination and cache cleanup boundary"));
2552
+ const targetRule14Index = targetLines.findIndex((line, index) => index >= targetRuleStart && line.startsWith("14. "));
2553
+ if (!sourceRule14 || targetRule14Index < 0) return null;
2554
+ targetLines[targetRule14Index] = sourceRule14;
2555
+ changed = true;
2556
+ for (const snippet of rule14Snippets) {
2557
+ const index = remainingMissing.indexOf(snippet);
2558
+ if (index >= 0) remainingMissing.splice(index, 1);
2559
+ }
2560
+ }
2561
+
2562
+ for (const snippet of remainingMissing) {
2563
+ const sourceLine = sourceRuleLines.find((line) => line.includes(snippet));
2564
+ if (!sourceLine) return null;
2565
+ const ruleNumber = sourceLine.match(/^(\d+)\. /)?.[1];
2566
+ if (!ruleNumber) return null;
2567
+ const targetIndex = targetLines.findIndex((line, index) => index >= targetRuleStart && line.startsWith(`${ruleNumber}. `));
2461
2568
  if (targetIndex < 0) return null;
2462
2569
  if (!sameRuleShape(targetLines[targetIndex], sourceLine, snippet)) return null;
2463
2570
  targetLines[targetIndex] = sourceLine;
@@ -2485,7 +2592,7 @@ function mergeIntegrationsSectionsByMissingAnchors(targetText, sourceText, missi
2485
2592
  changed = true;
2486
2593
  }
2487
2594
 
2488
- if (missing.some((snippet) => snippet === "External Tool Usage Verification Gate" || snippet === "External Tool Resource Lifecycle" || snippet === "other-agent-owned" || snippet === "do not invent" || snippet === "input schema" || snippet === "official documentation")) {
2595
+ if (missing.some((snippet) => snippet === "External Tool Usage Verification Gate" || snippet === "External Tool Resource Lifecycle" || snippet === "other-agent-owned" || snippet === "do not invent" || snippet === "input schema" || snippet === "official documentation" || snippet === "Runtime-Controlled Tool Operation Variants" || snippet === "Tool Operation References" || snippet === "Do not guess Chrome, Playwright, or DevTools commands")) {
2489
2596
  const withVerificationGate = mergeIntegrationsVerificationGateSection(merged, sourceText);
2490
2597
  if (!withVerificationGate) return null;
2491
2598
  merged = withVerificationGate;
@@ -2687,10 +2794,10 @@ function mergeHandoffLifecycleField(targetText) {
2687
2794
  const openingMarker = "<!-- ack:field:opening-message-matches-current-state -->";
2688
2795
  if (!targetText.includes(openingMarker)) return null;
2689
2796
 
2690
- const fieldBlock = "<!-- ack:field:lifecycle-conflicts-resolved -->\n- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: Reclassified at upgrade: field added by v0.3.6+ migration; pre-existing handoff state predates it; reconcile at next closeout.\n";
2691
- let merged = targetText.replace(openingMarker, `${fieldBlock}${openingMarker}`);
2692
- return ensureHandoffStateReconciliationRules(ensureHandoffPersistenceRoutingField(merged));
2693
- }
2797
+ const fieldBlock = "<!-- ack:field:lifecycle-conflicts-resolved -->\n- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: Reclassified at upgrade: field added by v0.3.6+ migration; pre-existing handoff state predates it; reconcile at next closeout.\n";
2798
+ let merged = targetText.replace(openingMarker, `${fieldBlock}${openingMarker}`);
2799
+ return ensureCurrentHandoffMigrationFields(merged);
2800
+ }
2694
2801
 
2695
2802
  function reclassifyExistingHandoffLifecyclePlaceholder(targetText) {
2696
2803
  const marker = "ack:field:lifecycle-conflicts-resolved";
@@ -2710,19 +2817,57 @@ function reclassifyExistingHandoffLifecyclePlaceholder(targetText) {
2710
2817
  return ensureHandoffStateReconciliationRules(lines.join("\n"));
2711
2818
  }
2712
2819
 
2713
- function mergeHandoffPersistenceRoutingField(targetText) {
2714
- const merged = ensureHandoffPersistenceRoutingField(targetText);
2715
- if (!merged || merged === targetText) return null;
2716
- return ensureHandoffStateReconciliationRules(merged);
2717
- }
2820
+ function mergeHandoffPersistenceRoutingField(targetText) {
2821
+ const merged = ensureCurrentHandoffMigrationFields(targetText);
2822
+ if (!merged || merged === targetText) return null;
2823
+ return merged;
2824
+ }
2825
+
2826
+ function mergeHandoffRecommendedNextStepDiscipline(targetText) {
2827
+ const merged = ensureCurrentHandoffMigrationFields(targetText);
2828
+ if (!merged || merged === targetText) return null;
2829
+ return merged;
2830
+ }
2831
+
2832
+ function ensureCurrentHandoffMigrationFields(targetText) {
2833
+ let merged = ensureHandoffPersistenceRoutingField(targetText);
2834
+ if (!merged) return null;
2835
+ merged = ensureHandoffRecommendedNextStepField(merged);
2836
+ if (!merged) return null;
2837
+ merged = ensureHandoffRecommendedNextPriorityLine(merged);
2838
+ if (!merged) return null;
2839
+ return ensureHandoffStateReconciliationRules(merged);
2840
+ }
2718
2841
 
2719
- function ensureHandoffPersistenceRoutingField(targetText) {
2720
- if (targetText.includes("ack:field:persistence-routing-checked")) return targetText;
2721
- const openingMarker = "<!-- ack:field:opening-message-matches-current-state -->";
2722
- if (!targetText.includes(openingMarker)) return null;
2723
- const fieldBlock = "<!-- ack:field:persistence-routing-checked -->\n- Persistence routing checked: Reclassified at upgrade: field added by template migration; pre-existing handoff state predates it; reconcile at next closeout.\n";
2724
- return targetText.replace(openingMarker, `${fieldBlock}${openingMarker}`);
2725
- }
2842
+ function ensureHandoffPersistenceRoutingField(targetText) {
2843
+ if (targetText.includes("ack:field:persistence-routing-checked")) return targetText;
2844
+ const openingMarker = "<!-- ack:field:opening-message-matches-current-state -->";
2845
+ if (!targetText.includes(openingMarker)) return null;
2846
+ const fieldBlock = "<!-- ack:field:persistence-routing-checked -->\n- Persistence routing checked: Reclassified at upgrade: field added by template migration; pre-existing handoff state predates it; reconcile at next closeout.\n";
2847
+ return targetText.replace(openingMarker, `${fieldBlock}${openingMarker}`);
2848
+ }
2849
+
2850
+ function ensureHandoffRecommendedNextStepField(targetText) {
2851
+ if (targetText.includes("ack:field:recommended-next-step-explicit")) return targetText;
2852
+ const openingMarker = "<!-- ack:field:opening-message-matches-current-state -->";
2853
+ if (!targetText.includes(openingMarker)) return null;
2854
+ const fieldBlock = "<!-- ack:field:recommended-next-step-explicit -->\n- Recommended next step is explicit and reasoned: Reclassified at upgrade: field added by template migration; confirm at next closeout.\n";
2855
+ return targetText.replace(openingMarker, `${fieldBlock}${openingMarker}`);
2856
+ }
2857
+
2858
+ function ensureHandoffRecommendedNextPriorityLine(targetText) {
2859
+ if (/^Recommended next step:/m.test(targetText)) return targetText;
2860
+ const marker = "<!-- ack:section:next-priorities -->";
2861
+ const markerIndex = targetText.indexOf(marker);
2862
+ if (markerIndex < 0) return null;
2863
+ const afterMarker = targetText.slice(markerIndex);
2864
+ const headingMatch = /^##\s+.+$/m.exec(afterMarker);
2865
+ if (!headingMatch) return null;
2866
+ const headingIndex = markerIndex + headingMatch.index;
2867
+ const headingEnd = targetText.indexOf("\n", headingIndex);
2868
+ if (headingEnd < 0) return null;
2869
+ return `${targetText.slice(0, headingEnd + 1)}\nRecommended next step: Reclassified at upgrade — reason: confirm at next closeout.\n${targetText.slice(headingEnd + 1)}`;
2870
+ }
2726
2871
 
2727
2872
  function ensureHandoffStateReconciliationRules(targetText) {
2728
2873
  if (!targetText) return null;
@@ -2730,9 +2875,12 @@ function ensureHandoffStateReconciliationRules(targetText) {
2730
2875
  if (!targetText.includes("Lifecycle consistency rule: compare `Completed This Session`")) {
2731
2876
  rules.push("Lifecycle consistency rule: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. A completed or verified item must not remain as an unresolved next priority, active risk, or startup instruction unless it is explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with the missing evidence or trigger condition stated.");
2732
2877
  }
2733
- if (!targetText.includes("Persistence routing rule: one-time delivery instructions")) {
2734
- rules.push("Persistence routing rule: one-time delivery instructions, historical validation evidence, old hashes, old version facts, and incident notes must stay in trace evidence unless they still affect the next action.");
2735
- }
2878
+ if (!targetText.includes("Persistence routing rule: one-time delivery instructions")) {
2879
+ rules.push("Persistence routing rule: one-time delivery instructions, historical validation evidence, old hashes, old version facts, and incident notes must stay in trace evidence unless they still affect the next action.");
2880
+ }
2881
+ if (!targetText.includes("Recommended next-step rule:")) {
2882
+ rules.push("Recommended next-step rule: `Next Priorities` must name the single recommended next action and a short reason before listing additional options, unless the next action is blocked or genuinely requires a user decision.");
2883
+ }
2736
2884
  if (rules.length === 0) return targetText;
2737
2885
  const ruleBlock = `${rules.join("\n")}\n\n`;
2738
2886
  const sufficiencyMarker = "<!-- ack:section:handoff-sufficiency-check -->";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.35",
3
+ "version": "0.3.37",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -37,7 +37,7 @@ Use this workflow when the user asks for governance bridge, connect this documen
37
37
  3. Check `dev/PROJECT_INDEX.md`: the file should be discoverable with its role and "read when" condition. Source-of-truth or reference files should appear in Fact Base, External Sources, Directory Map, Entry Points, or another existing indexed home that fits the project.
38
38
  4. Check `dev/DOC_SYNC_REGISTRY.md`: future same-type changes should have a matching change type or an explicit reason no durable sync rule is needed.
39
39
  5. Check related workflows, guides, runbooks, or rule packs: if a process creates or updates the file, that process should say when to update the file or its index row.
40
- 6. Check `dev/SESSION_HANDOFF.md`: only current state, next action, unresolved risk, blocker, or a startup-needed fact should be in handoff. Do not copy whole documents or old evidence into handoff.
40
+ 6. Check `dev/SESSION_HANDOFF.md`: only current state, recommended next action with reason, unresolved risk, blocker, or a startup-needed fact should be in handoff. Do not copy whole documents or old evidence into handoff.
41
41
  7. Check `dev/SESSION_LOG.md`: this session's bridge review, validation, and evidence can be logged when it affects future action, but log entries must not become current state.
42
42
  8. Search for duplicate source-of-truth risk. If another file has the same durable role, recommend merge, reference, or retire options; do not delete, rename, or move files without explicit approval.
43
43
 
@@ -46,8 +46,10 @@ For repo-wide scans, report candidates as candidates. Do not fail ordinary docs
46
46
  Output format:
47
47
 
48
48
  - Status: bridged / partially bridged / unbridged / blocked.
49
+ - Use bridged only when every applicable governance link is present. If only `dev/PROJECT_INDEX.md` or `dev/SESSION_LOG.md` was updated, report partially bridged.
49
50
  - Already bridged: list the governance links that are present.
50
51
  - Gaps: list missing links and why they matter for the next agent.
52
+ - Not applicable: list skipped layers with a reason.
51
53
  - Suggested patches: list exact files and sections to update.
52
54
  - Manual decisions: list duplicates, naming choices, deletion, renaming, external sync, or ownership questions requiring user confirmation.
53
55
  - Acceptance: give one concrete check that proves the bridge is complete.
@@ -70,7 +72,7 @@ Use this workflow when the user asks to write something into long-term governanc
70
72
 
71
73
  1. Classify the knowledge before writing:
72
74
  - Current task contract changes, including product goals, requirements, development checklists, acceptance rules, exclusions, priorities, or scope -> the existing authoritative spec / backlog / issue / runbook when one exists; otherwise `dev/SESSION_HANDOFF.md` current-state sections.
73
- - Current task state, next action, unresolved risk, or startup-needed fact -> `dev/SESSION_HANDOFF.md`.
75
+ - Current task state, recommended next action with reason, unresolved risk, or startup-needed fact -> `dev/SESSION_HANDOFF.md`.
74
76
  - Chronological evidence or validation trace -> `dev/SESSION_LOG.md`.
75
77
  - File maps, command maps, API reference locations, tool capability maps, and external source coordinates -> `dev/PROJECT_INDEX.md`.
76
78
  - Sync obligations or external mirror duties -> `dev/DOC_SYNC_REGISTRY.md`.
@@ -16,12 +16,14 @@ Use for reply format, language behavior, output schema, user-facing explanation,
16
16
  3. Mark assumptions and unverified facts.
17
17
  4. Keep operational instructions copy-paste-ready when they are meant for future sessions.
18
18
  5. Avoid exposing internal process unless it helps the user act.
19
+ 6. Give a clear recommended next step whenever the user needs to continue. If there is one best path, state it directly with a short reason. Offer two or three choices only when the user truly must decide; mark the recommended choice and do not turn an already-made technical judgment into an open question.
19
20
 
20
21
  ## Checks
21
22
 
22
23
  - Verify required headings, schema fields, or language split.
23
24
  - Check public README or docs if user-facing behavior changed.
24
25
  - Confirm handoff/opening messages are complete and root-specific when needed.
26
+ - Confirm user-facing next-step wording names the recommended action and reason when a continuation is needed.
25
27
 
26
28
  ## Closeout
27
29
 
@@ -4,13 +4,13 @@
4
4
 
5
5
  Use this pack for governance of already-installed external tool integrations: **Connectors** (official or platform-vetted MCP servers), **MCPs** (community or custom MCP servers), **Plugins** (bundles that may register skills, MCP servers, hooks, or apps), and **Skills** (`SKILL.md` instruction sets).
6
6
 
7
- When a task touches external sources or external write surfaces such as Notion, Google Drive, Dropbox, Slack, Linear, GitHub, HubSpot, browsers, crawlers, notebooks, or local helper services, this pack makes the agent check declared integrations first, prefer direct runtime access when available, and fall back to manual packets only when the integration is unavailable.
7
+ When a task touches external sources or external write surfaces such as Notion, Google Drive, Dropbox, Slack, Linear, GitHub, HubSpot, browsers, screenshots, DevTools, Playwright, desktop app automation, crawlers, notebooks, or local helper services, this pack makes the agent check declared integrations and tool operation references first, prefer direct runtime access when available, and fall back to manual packets only when the integration is unavailable.
8
8
 
9
9
  This pack does not teach users how to install tools. Installation is handled by the user's AI runtime, tool vendor, or official documentation. This pack governs what happens after a tool is already installed: declaration, verification, safe use, resource lifecycle, drift handling, and cross-session continuity.
10
10
 
11
11
  ## Load When
12
12
 
13
- - The task mentions Notion, Google Drive, Slack, Linear, Dropbox, HubSpot, GitHub, browser automation, crawlers, notebooks, local helper services, or other external tools.
13
+ - The task mentions Notion, Google Drive, Slack, Linear, Dropbox, HubSpot, GitHub, browser automation, UI validation, screenshot capture, Chrome, Playwright, DevTools, desktop app automation, crawlers, notebooks, local helper services, or other external tools.
14
14
  - The user asks whether the agent can directly read or write an external system.
15
15
  - `dev/PROJECT_INDEX.md` has a non-empty `## Installed Integrations` section.
16
16
  - First-time onboarding asks the user to declare installed external tools.
@@ -50,6 +50,18 @@ Agents must not use model memory, old session experience, copied examples, Conne
50
50
 
51
51
  If the required source cannot be inspected, mark the tool use `blocked` or `unverified`, ask the user for the current docs/schema/runbook, or fall back to a manual packet. Do not continue by trial and error. Connector-first means schema-first for the active runtime, not memory-first.
52
52
 
53
+ #### Runtime-Controlled Tool Operation Variants
54
+
55
+ For browser and tool-operation work, first check `dev/PROJECT_INDEX.md` `## Tool Operation References` when present. A successful method from a previous session is reusable only when it is registered there with source, version/date, scope, known limits, and last verification.
56
+
57
+ | Variant | Examples | Required source before use |
58
+ |---|---|---|
59
+ | Browser / UI validation | Browser tool, screenshot, Chrome, DevTools, Playwright smoke test, visual QA | Active runtime browser/tool schema; registered tool operation reference; or current official docs for raw CLI/SDK use. Do not guess Chrome, Playwright, or DevTools commands. |
60
+ | Desktop or local app automation | Desktop app session, app plugin, local browser profile, extension-dependent workflow | Active app/plugin/tool schema or official automation API docs. Do not mutate user sessions, profiles, or extension state without confirmation. |
61
+ | Crawler / scraper / local helper | Firecrawl-like tools, crawler services, local helper server | Active tool schema, registered operation reference, or official docs. Respect source permissions, rate limits, and cleanup boundaries. |
62
+ | Notebook / data runtime | Notebook kernel, data runtime, long-lived analysis server | Active runtime/kernel schema or registered operation reference. Classify kernels and servers by ownership before cleanup. |
63
+ | Raw CLI / SDK / tool server | Direct command invocation, SDK script, MCP/tool server operation | Current official docs, installed package types, or registered operation reference. Mark blocked or unverified if unavailable. |
64
+
53
65
  ### 2.1 External Tool Resource Lifecycle
54
66
 
55
67
  External tools must be treated as resources with ownership, not just capabilities. After using Connector, MCP, plugin, browser automation, local server, crawler, notebook, or similar external tool services, classify any opened session, process, browser context, temporary directory, cache, or helper service into one of these ownership classes:
@@ -161,8 +173,8 @@ Integration declarations are project-level; they do not guarantee every AI runti
161
173
  ## Rules
162
174
 
163
175
  1. **Credential separation**: never ask for, log, or persist credential values. Redact credential-like values and warn about rotation when appropriate.
164
- 2. **External Tool Usage Verification Gate**: verify current runtime schema, official docs, official types/samples, or versioned local runbooks before invoking or retrying external tools.
165
- 3. **Declaration before use**: read `dev/PROJECT_INDEX.md` `## Installed Integrations` before external-tool work. If absent, ask about integration status rather than assuming none exists.
176
+ 2. **External Tool Usage Verification Gate**: verify current runtime schema, official docs, official types/samples, or registered tool operation references before invoking or retrying external tools.
177
+ 3. **Declaration before use**: read `dev/PROJECT_INDEX.md` `## Installed Integrations` and `## Tool Operation References` before external-tool or runtime-controlled tool-operation work. If absent, ask about integration status rather than assuming none exists.
166
178
  4. **Connector-first default**: when a declared integration is functional, prefer the verified direct tool call. Manual paste is fallback, not default.
167
179
  5. **Write operations require read-back verification**: read back every external write before claiming success.
168
180
  6. **No auto-fix credential / auth issues**: surface auth failures to the user and point to the runtime settings or tool owner.
@@ -176,6 +188,7 @@ Integration declarations are project-level; they do not guarantee every AI runti
176
188
 
177
189
  - Verify `dev/PROJECT_INDEX.md` `## Installed Integrations` exists and has the expected subsections when the project declares integrations.
178
190
  - Before probing or invoking a declared integration, inspect current runtime tool description and input schema.
191
+ - Before browser validation, screenshots, Chrome, Playwright, DevTools, desktop automation, crawler, notebook, or raw CLI/SDK/tool-server work, verify the current source from runtime schema, official docs, or `PROJECT_INDEX` `## Tool Operation References`.
179
192
  - Before external-tool first use, write, destructive operation, raw API / SDK / CLI / URI / plugin API call, or retry after tool error, confirm the current usage source.
180
193
  - Surface and record mid-session integration drift.
181
194
  - After external-tool use, perform ownership-based resource closeout. For long-running, multi-tool, MCP, browser automation, repeated-error, or slowdown scenarios, report grouped residual processes or services when observable.
@@ -198,6 +211,7 @@ Integration declarations are project-level; they do not guarantee every AI runti
198
211
  |---|---|---|
199
212
  | Assuming no Connector or MCP exists whenever the user mentions Notion, Google Drive, or another external source | Mature connector ecosystems make paste-only fallback an unreliable default. | Read `PROJECT_INDEX` Installed Integrations first; ask about integration status if undeclared. |
200
213
  | Guessing tool names, endpoints, CLI flags, URI parameters, or plugin APIs from memory | Stale examples cause unknown tool, invalid args, 400 / 404, permission, or auth loops. | Verify active runtime schema, official docs, official types/samples, or versioned local runbooks. |
214
+ | Treating browser validation as ordinary coding and guessing Chrome, Playwright, or DevTools commands | Browser and tool-control surfaces differ across runtimes, profiles, plugins, and installed packages. | Verify the active runtime schema, official docs, or a registered tool operation reference; mark blocked or use a manual packet when unavailable. |
201
215
  | Treating a Connector marketing page or old example as executable schema | Marketing pages do not prove the active runtime's current tool name or input schema. | Use active runtime tool list/schema as the invocation source. |
202
216
  | Retrying unknown tool / invalid args by changing names or parameters repeatedly | Trial-and-error hides the real schema or docs gap. | Stop same-pattern retries and return to the External Tool Usage Verification Gate. |
203
217
  | Writing credential values into `PROJECT_INDEX`, `SESSION_HANDOFF`, or `SESSION_LOG` | Project files and git history are persistent; leaked credentials remain exposed. | Record credential references only, never values. |
package/packs/safety.md CHANGED
@@ -2,12 +2,12 @@
2
2
 
3
3
  ## Scope
4
4
 
5
- Use for file operations, shell commands, Git changes, package managers, installers, deploy tools, release tools, cloud tools, external APIs, locked files, permission errors, sandbox restrictions, or any task that could affect data loss, credentials, public release state, or external systems.
5
+ Use for file operations, shell commands, Git changes, package managers, installers, deploy tools, release tools, cloud tools, external APIs, browser profiles, desktop app sessions, notebook kernels, local tool servers, locked files, permission errors, sandbox restrictions, or any task that could affect data loss, credentials, public release state, user sessions, shared local resources, or external systems.
6
6
 
7
7
  ## Load When
8
8
 
9
9
  - User requests deletion, overwrite, move, rename, cleanup, Git history changes, package installation, publish, deploy, release, cloud writes, external API calls, or credential handling.
10
- - A task touches filesystem paths, shell commands, permissions, sandbox limits, locks, secrets, external systems, or public release state.
10
+ - A task touches filesystem paths, shell commands, permissions, sandbox limits, locks, secrets, external systems, browser profiles, desktop app sessions, notebook kernels, local tool servers, shared caches, or public release state.
11
11
  - Another pack is loaded but the task includes data-loss, credential, permission, external-system, or irreversible-operation risk.
12
12
 
13
13
  ## Rules
@@ -21,7 +21,7 @@ Use for file operations, shell commands, Git changes, package managers, installe
21
21
  7. On macOS / Linux, do not run `rm -rf`, `sudo rm`, recursive `chmod`, recursive `chown`, or destructive wildcard operations unless the user explicitly requested the operation and target paths are listed and verified.
22
22
  8. Do not run `git reset --hard`, branch deletion, tag deletion, force push, or history rewrite unless the user explicitly requested it and affected refs/files are listed.
23
23
  9. Before staging or committing, inspect current status and avoid staging unrelated parent-repo, sibling-directory, generated, credential, or user-owned changes.
24
- 10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools, or release tools, verify current official documentation or project-local runbooks. For external tools, first apply the External Tool Usage Verification Gate in `dev/rules/integrations.md`: inspect current runtime tool schema for Connector / MCP calls, and use current official docs, official type definitions, official samples, or versioned local runbooks for raw API / SDK / CLI / URI / plugin API work. Differentiate three layers of external access:
24
+ 10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools, release tools, browser automation, DevTools, Playwright, crawlers, notebooks, desktop app automation, or local helper services, verify current official documentation or project-local runbooks. For external tools, first apply the External Tool Usage Verification Gate in `dev/rules/integrations.md`: inspect current runtime tool schema for Connector / MCP calls, and use current official docs, official type definitions, official samples, or registered tool operation references for raw API / SDK / CLI / URI / plugin API work. Differentiate three layers of external access:
25
25
  (a) Anthropic-vetted Connectors (e.g. Notion / Google Drive / Slack via Claude Desktop Extensions): trust the vetted MCP server boundary only after inspecting the active runtime tool name, description, and input schema; still verify destructive write parameters before invocation.
26
26
  (b) Community / custom MCP servers (user-installed via manual config): treat with extra caution — destructive writes require dry-run + user confirmation; verify server behavior against current tool schema and project-local runbook if available.
27
27
  (c) Raw external APIs / SDKs / CLIs (no MCP layer): full Rule 10 verification of official docs required; mark unverified if blocked.
@@ -32,7 +32,7 @@ Use for file operations, shell commands, Git changes, package managers, installe
32
32
  (c) Before writing to `dev/PROJECT_INDEX.md` `## Installed Integrations`, `dev/SESSION_HANDOFF.md`, or `dev/SESSION_LOG.md`, self-check that no credential value is present; doctor `checkInstalledIntegrationsCredentialLeak()` enforces this at QC.
33
33
  (d) Auth failure (token expired / revoked / rate-limit) surfaces to the user with a pointer to the AI tool's own settings interface; do not attempt to auto-fix auth or re-auth flow (out of scope for Kit governance).
34
34
  13. Shell / script parser failure discipline: after a shell, quoting, here-string, wrapper, temporary script, or parser failure, stop same-pattern retries and classify the failing layer before trying again: active shell, wrapper shell, runtime parser, package manager, or target CLI. Do not embed large JavaScript, JSON, Markdown, regex, patch, or path-heavy content inside shell strings when a direct tool, patch file, or real script file is safer. For temporary scripts, first make a minimal reproducible script, run a syntax-only check such as `node --check`, `python -m py_compile`, or an equivalent parser check where available, then execute. After any write script, read back the affected files or affected ranges before claiming success. If the same parser failure repeats, stop and return to root-cause classification instead of changing quoting again.
35
- 14. Process termination and cache cleanup boundary: agents may automatically close or clean up resources that are clearly task-owned or agent-managed, including task-created browser contexts, MCP child processes, helper servers, temp directories, or bounded caches. Agents must not terminate shared, ambiguous, user-owned, system-level, or other-agent-owned processes; delete broad caches; disable tools; uninstall packages; or change configuration without explicit user confirmation listing exact process IDs or paths, tool names, evidence, expected impact, and restart / rollback path. Generic process names such as `node`, `python`, or `chrome` are never enough ownership evidence by themselves. If a process, browser context, MCP service, or helper server may belong to another AI agent running on the same machine, treat it as shared unless current-task ownership is proven.
35
+ 14. Process termination and cache cleanup boundary: agents may automatically close or clean up resources that are clearly task-owned or agent-managed, including task-created browser contexts, MCP child processes, helper servers, notebook kernels, temp directories, or bounded caches. Agents must not terminate shared, ambiguous, user-owned, system-level, or other-agent-owned processes; delete broad caches; disable tools; uninstall packages; mutate browser profiles, desktop app sessions, shared tool servers, notebook kernels, global package / browser / plugin caches, or change configuration without explicit user confirmation listing exact process IDs or paths, tool names, evidence, expected impact, and restart / rollback path. Generic process names such as `node`, `python`, or `chrome` are never enough ownership evidence by themselves. If a process, browser context, desktop app session, notebook kernel, MCP service, or helper server may belong to another AI agent running on the same machine, treat it as shared unless current-task ownership is proven.
36
36
 
37
37
  ## Checks
38
38
 
@@ -43,13 +43,13 @@ Display version rule: after reading `dev/PROJECT_INDEX.md`, take the card versio
43
43
  ( o.o ) continuity ready
44
44
  > ^ <
45
45
 
46
- 🔎 交接狀態:<loaded / new install / resumed>
47
- 📌 目前目標:<current objective>
48
- ⚠️ 注意事項:<important boundary or none>
49
- 🚀 下一步:<next action>
50
- ```
51
-
52
- Keep the card short. Use plain Traditional Chinese labels in user-facing output. Use the full product name, not an abbreviation.
46
+ 🔎 交接狀態:<loaded / new install / resumed>
47
+ 📌 目前目標:<current objective>
48
+ ⚠️ 注意事項:<important boundary or none>
49
+ 🚀 推薦下一步:<one recommended next action + short reason>
50
+ ```
51
+
52
+ Keep the card short. Use plain Traditional Chinese labels in user-facing output. Use the full product name, not an abbreviation. The next-step line must name the recommended action, not only list possible work. If there are several valid paths, state the best first action and the reason; offer choices only when the user must decide.
53
53
 
54
54
  ## 2. Work Loop
55
55
 
@@ -76,9 +76,9 @@ Use exactly one of these tiers after each task:
76
76
 
77
77
  Task contract changes are durable facts when they affect future action. If the user adds or changes the product goal, requirements, development checklist, acceptance rules, exclusions, priority, or task scope during a long-running task, first reconcile those changes into one current task contract before continuing. If a dedicated spec, backlog, issue, runbook, or project document is already the authoritative home, update that home and cite it from `dev/SESSION_HANDOFF.md`; otherwise merge the current contract into `dev/SESSION_HANDOFF.md` under `Task Understanding Summary`, `Active Objective`, `Next Priorities`, and `Next Task Required Reading`. Do not scatter the same task contract across chat memory, log entries, draft docs, and startup prompts.
78
78
 
79
- Route durable facts by file role:
80
-
81
- - Current objective, next action, unresolved risk, blocker, or a fact needed at startup belongs in `dev/SESSION_HANDOFF.md`.
79
+ Route durable facts by file role:
80
+
81
+ - Current objective, recommended next action with reason, unresolved risk, blocker, or a fact needed at startup belongs in `dev/SESSION_HANDOFF.md`.
82
82
  - Chronological evidence, command output, validation result, and research trace belongs in `dev/SESSION_LOG.md` when it affects future action or cannot be cheaply rerun. Routine successful checks that can be rerun are not durable facts.
83
83
  - File maps, command maps, reference maps, source locations, and installed capability maps belong in `dev/PROJECT_INDEX.md`.
84
84
  - Sync obligations across repositories, docs, mirrors, or external surfaces belong in `dev/DOC_SYNC_REGISTRY.md`.
@@ -123,15 +123,16 @@ Closeout Write Contract: before writing `dev/SESSION_HANDOFF.md`, `dev/SESSION_L
123
123
 
124
124
  1. Reconcile `dev/SESSION_HANDOFF.md`. Do not append a new state snapshot under old state. Verify `Durable Anchors`, then rewrite or explicitly confirm every section under `Closeout-Reconciled State`.
125
125
  2. Add a concise entry to `dev/SESSION_LOG.md` with work actually completed this session and the exact next-session opening message.
126
- 3. Update `dev/PROJECT_INDEX.md` if files, stack, commands, entry points, workspace identity, or durable document map changed.
127
- 4. Check `dev/DOC_SYNC_REGISTRY.md` and record required sync status.
128
- 5. Record unresolved drift risk, active worktree, parallel workspace, uncommitted changes, or blocked verification.
129
- 6. Complete the `State Reconciliation Check`: it must state when reconciliation happened, which state sections were rewritten or confirmed current, whether stale snapshots remain, whether the `Persistence routing checked` field is complete, whether completed / pending / risk / opening-message lifecycle conflicts were resolved, and whether the opening message matches current state. In the same step, run the handoff lifecycle consistency check before declaring handoff ready: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. A completed or verified item must not remain as an unresolved next priority, active risk, or startup instruction unless it is explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with the missing evidence or trigger condition stated.
130
- 7. Run the handoff sufficiency check: the next AI should be able to continue from `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history.
131
- 8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
132
- 9. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the fenced opening message in `dev/SESSION_HANDOFF.md`, then read it back or run the project's prompt mirror check before declaring closeout ready. `dev/SESSION_HANDOFF.md` is authoritative; `START_NEXT_SESSION_PROMPT.txt` is the stateful startup prompt that the next local agent must read. During an active session, do not regenerate it just to silence `doctor`; normal `doctor` may warn about drift, but closeout must make the copy match before handoff is declared ready.
133
- 10. Show a short closeout card, then provide the next-session startup entry in a fenced `text` code block. Primary entry, when the next local AI agent is already opened at this project root: `Start Agent Handoff` / `開工`. Fallback entry, when the next AI agent is not yet pointed at the project root: `Work in <project root>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.` Do not compose a separate stateful final-response prompt; the final response points to the persisted prompt file, not a third source of truth.
134
- 11. Run the closeout maintenance trigger check. This is a short required check, not a full maintenance pass every time. Record the result in the new `dev/SESSION_LOG.md` entry under `Log maintenance`.
126
+ 3. Update `dev/PROJECT_INDEX.md` if files, stack, commands, entry points, workspace identity, or durable document map changed.
127
+ 4. Check `dev/DOC_SYNC_REGISTRY.md` and record required sync status.
128
+ 5. Record unresolved drift risk, active worktree, parallel workspace, uncommitted changes, or blocked verification.
129
+ 6. If this session used external tools such as Connectors, MCPs, plugins, browser automation, DevTools, Playwright, crawlers, notebooks, local helper services, or task-created helper processes, run an ownership-based external-tool resource closeout check before declaring closeout ready. Report task-owned or agent-managed resources that were closed or cleaned, observable resources released when the runtime exposes counts / memory / temp size, retained shared / user-owned / other-agent-owned / system-level / unknown resources with redacted evidence, and any runtime visibility limits. Do not terminate, delete, disable, or reconfigure shared or ambiguous resources without explicit user confirmation under `dev/rules/integrations.md` and `dev/rules/safety.md`.
130
+ 7. Complete the `State Reconciliation Check`: it must state when reconciliation happened, which state sections were rewritten or confirmed current, whether stale snapshots remain, whether the `Persistence routing checked` field is complete, whether completed / pending / risk / opening-message lifecycle conflicts were resolved, whether the recommended next step is explicit and reasoned, and whether the opening message matches current state. In the same step, run the handoff lifecycle consistency check before declaring handoff ready: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. A completed or verified item must not remain as an unresolved next priority, active risk, or startup instruction unless it is explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with the missing evidence or trigger condition stated.
131
+ 8. Run the handoff sufficiency check: the next AI should be able to continue from `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history.
132
+ 9. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
133
+ 10. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the fenced opening message in `dev/SESSION_HANDOFF.md`, then read it back or run the project's prompt mirror check before declaring closeout ready. `dev/SESSION_HANDOFF.md` is authoritative; `START_NEXT_SESSION_PROMPT.txt` is the stateful startup prompt that the next local agent must read. During an active session, do not regenerate it just to silence `doctor`; normal `doctor` may warn about drift, but closeout must make the copy match before handoff is declared ready.
134
+ 11. Show a short closeout card, then provide the next-session startup entry in a fenced `text` code block. Primary entry, when the next local AI agent is already opened at this project root: `Start Agent Handoff` / `開工`. Fallback entry, when the next AI agent is not yet pointed at the project root: `Work in <project root>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.` Do not compose a separate stateful final-response prompt; the final response points to the persisted prompt file, not a third source of truth.
135
+ 12. Run the closeout maintenance trigger check. This is a short required check, not a full maintenance pass every time. Record the result in the new `dev/SESSION_LOG.md` entry under `Log maintenance`.
135
136
 
136
137
  Hard triggers:
137
138
 
@@ -96,11 +96,21 @@ Reachable means the source can be found. It does not mean the source has been re
96
96
  | Index | TBD, for example Notion database `Project Index` | Metadata, summaries, and tags for each source file | Agent may read/write through a verified Connector |
97
97
  | Persistent mirror | TBD, for example Drive folder `Project Reference/` | Backup or cross-device reference mirror | User-controlled sync by default; agent does not push automatically |
98
98
  | Working draft | TBD, for example local `~/project/output/` | Agent task output | Agent may read and write local files under normal safety rules |
99
-
100
- ## Local QC Commands
101
-
102
- | Check | Command | Run before | Last verified |
103
- |---|---|---|---|
99
+
100
+ ## Tool Operation References
101
+
102
+ Use this section for project-local runbooks or verified procedures for runtime-controlled tools such as browser validation, screenshots, DevTools, Playwright, crawlers, notebooks, desktop app automation, MCP/plugin helpers, or raw CLI/SDK operations.
103
+
104
+ Do not store credential values or machine-private paths here. Local machine-only references may be listed only when the project explicitly depends on them, and the scope / limits must say they are not portable.
105
+
106
+ | Tool / operation | Reference path or URL | Required before | Source and version/date | Scope and known limits | Last verified |
107
+ |---|---|---|---|---|---|
108
+ | TBD | TBD | TBD | TBD | TBD | TBD |
109
+
110
+ ## Local QC Commands
111
+
112
+ | Check | Command | Run before | Last verified |
113
+ |---|---|---|---|
104
114
  | Agent Handoff Kit doctor | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .` | closeout / governance changes / generated Markdown artifact checks | package latest |
105
115
  | Project governance check | Check newly created Markdown / durable artifacts against `dev/PROJECT_INDEX.md` and `dev/DOC_SYNC_REGISTRY.md`; register, sync, consolidate, or explicitly classify as temporary / one-time evidence | closeout / durable file changes | unverified until project-specific command exists |
106
116
 
@@ -133,6 +143,6 @@ Record this at closeout so the next AI can detect wrong-root or workspace drift.
133
143
  |---|---|---|---|
134
144
  | TBD | TBD | TBD | TBD |
135
145
 
136
- ## Maintenance Rule
137
-
138
- Update this file when stack, commands, directory roles, entry points, external services, workspace identity, durable runbooks, or governance file map changes.
146
+ ## Maintenance Rule
147
+
148
+ Update this file when stack, commands, directory roles, entry points, external services, runtime-controlled tool operation references, workspace identity, durable runbooks, or governance file map changes.
@@ -15,6 +15,7 @@ Read only the packs needed for the current task.
15
15
  | Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
16
16
  | External notes, knowledge base, Notion, Obsidian, Google Drive | `dev/rules/knowledge.md` | external knowledge source integration |
17
17
  | External tool integrations (Connector / MCP / Plugin / Skill) — declared in `## Installed Integrations`; tasks involving Notion / Google Drive / Slack / Linear / Dropbox / HubSpot / GitHub / etc. external read-write | `dev/rules/integrations.md` | Connector-first default + credential separation + multi-layer source-of-truth + cross-session resilience |
18
+ | Runtime-controlled tool operation / browser UI validation / visual QA / screenshot / Chrome / Playwright / DevTools / desktop app automation / crawler or scraper / notebook or data runtime / raw CLI, SDK, tool server, MCP, plugin, or local helper operation | `dev/rules/integrations.md` + `dev/rules/safety.md` (add `dev/rules/coding.md` only when changing code, tests, or project scripts) | verify the active runtime capability, current schema, official docs, or registered tool operation reference before invocation; block or use a manual packet when unavailable; preserve ownership and cleanup boundaries |
18
19
  | External tool resource pressure / stale MCP process / plugin service leak / browser automation left running / cache growth after external tools / slowdown after MCP, plugin, browser, crawler, notebook, or local helper services | `dev/rules/integrations.md` + `dev/rules/safety.md` | ownership-based external-tool resource closeout; task-owned cleanup allowed; shared or ambiguous remediation requires exact evidence and confirmation |
19
20
  | Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |
20
21
 
@@ -53,10 +53,12 @@ Record only work actually completed in the current session.
53
53
 
54
54
  1. TBD
55
55
 
56
- <!-- ack:section:next-priorities -->
57
- ## Next Priorities
58
-
59
- 1. TBD
56
+ <!-- ack:section:next-priorities -->
57
+ ## Next Priorities
58
+
59
+ Recommended next step: TBD — reason: TBD
60
+
61
+ 1. TBD
60
62
 
61
63
  <!-- ack:section:next-task-required-reading -->
62
64
  ## Next Task Required Reading
@@ -113,6 +115,8 @@ At full closeout, complete this check after updating the state sections above.
113
115
  - Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD
114
116
  <!-- ack:field:persistence-routing-checked -->
115
117
  - Persistence routing checked: TBD
118
+ <!-- ack:field:recommended-next-step-explicit -->
119
+ - Recommended next step is explicit and reasoned: TBD
116
120
  <!-- ack:field:opening-message-matches-current-state -->
117
121
  - Opening message matches current state: TBD
118
122
  <!-- ack:field:next-ai-can-continue -->
@@ -120,7 +124,7 @@ At full closeout, complete this check after updating the state sections above.
120
124
 
121
125
  If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready.
122
126
 
123
- Lifecycle consistency rule: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. A completed or verified item must not remain as an unresolved next priority, active risk, or startup instruction unless it is explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with the missing evidence or trigger condition stated. Persistence routing rule: one-time delivery instructions, historical validation evidence, old hashes, old version facts, and incident notes must stay in trace evidence unless they still affect the next action.
127
+ Lifecycle consistency rule: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. A completed or verified item must not remain as an unresolved next priority, active risk, or startup instruction unless it is explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with the missing evidence or trigger condition stated. Recommended next-step rule: `Next Priorities` must name the single recommended next action and a short reason before listing additional options, unless the next action is blocked or genuinely requires a user decision. Persistence routing rule: one-time delivery instructions, historical validation evidence, old hashes, old version facts, and incident notes must stay in trace evidence unless they still affect the next action.
124
128
 
125
129
  <!-- ack:section:handoff-sufficiency-check -->
126
130
  ## Handoff Sufficiency Check