@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 +31 -38
- package/bin/agent-handoff-kit.mjs +229 -81
- package/package.json +1 -1
- package/packs/agent-governance.md +4 -2
- package/packs/communication.md +2 -0
- package/packs/integrations.md +18 -4
- package/packs/safety.md +4 -4
- package/runtime-core/AGENTS.core.md +20 -19
- package/runtime-core/PROJECT_INDEX.md +18 -8
- package/runtime-core/RULE_PACKS.md +1 -0
- package/runtime-core/SESSION_HANDOFF.md +9 -5
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:目前版本為 `v0.3.
|
|
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
|
|
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
|
|
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
|
|
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 等外部工具 |
|
|
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 /
|
|
174
|
-
| 使用外部工具,例如 Notion、Google Drive、GitHub | 「這個項目會用到這些外部工具,請記住哪些能直接使用,機密不要寫入項目文件。」 |
|
|
175
|
-
|
|
176
|
-
這個掃描只列出候選與缺口,不會自動修改;是否接入、合併或退役由你確認。
|
|
172
|
+
| 讓 AI 下次避免同類錯誤 | 「把今次錯誤整理成日後工作規則,讓下次 AI 知道要怎樣避免。」 |
|
|
173
|
+
| 讓 API / 工具用法下次仍生效 | 「以後都用這個 API 調用方式,之後開新對話也要沿用。」 |
|
|
174
|
+
| 使用外部工具,例如 Notion、Google Drive、GitHub | 「這個項目會用到這些外部工具,請記住哪些能直接使用,機密不要寫入項目文件。」 |
|
|
175
|
+
| 長任務用了 MCP、browser 或自動化工具 | 「收工時請顯示外部工具資源收口結果:已關閉哪些本任務資源,哪些因歸屬不明而保留並列證據。」 |
|
|
177
176
|
|
|
178
|
-
|
|
177
|
+
掃描重要文件時,AI 只會先列出可能需要接入的文件與原因,不會自動修改;是否接入、合併或退役由你確認。
|
|
178
|
+
|
|
179
|
+
需要長期保留的規則,AI 應寫入合適的項目文件,而不是只留在當次對話摘要。
|
|
179
180
|
|
|
180
|
-
|
|
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
|
|
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
|
-
"
|
|
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:
|
|
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/
|
|
179
|
-
label: "
|
|
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
|
-
"
|
|
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", "
|
|
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("
|
|
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" &&
|
|
1877
|
-
const
|
|
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 &&
|
|
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
|
-
|
|
2456
|
-
|
|
2457
|
-
|
|
2458
|
-
const
|
|
2459
|
-
if (!
|
|
2460
|
-
|
|
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
|
|
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 =
|
|
2715
|
-
if (!merged || merged === targetText) return null;
|
|
2716
|
-
return
|
|
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
|
@@ -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`.
|
package/packs/communication.md
CHANGED
|
@@ -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
|
|
package/packs/integrations.md
CHANGED
|
@@ -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
|
|
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,
|
|
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
|
-
🚀
|
|
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.
|
|
130
|
-
7.
|
|
131
|
-
8.
|
|
132
|
-
9.
|
|
133
|
-
10.
|
|
134
|
-
11.
|
|
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
|
-
##
|
|
101
|
-
|
|
102
|
-
|
|
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
|
-
|
|
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
|