@adamchanadam/agent-handoff-kit 0.3.27 → 0.3.29

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.27`。這是早期可用版本,仍在持續完善中。
3
+ 狀態:目前版本為 `v0.3.29`。這是早期可用版本,仍在持續完善中。
4
4
 
5
5
  ![Agent Handoff Kit 主視覺](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-main-visual2.png)
6
6
 
@@ -8,9 +8,17 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
8
8
 
9
9
  它只處理一件狹窄但重要的事:AI 跨對話失憶。每次開新對話,AI 往往不記得你上次做到哪裡,也認不出中途新建的文件、你引入的參考資料、哪些檔案是真源。這套工具把進度、下一步、風險、檔案登記與下次開工提示寫進固定文件,讓下一個 AI 工具能接得上上一棒。
10
10
 
11
- > 🚀 **第一次用?你不需要先讀本 README 或任何文件。**
12
- >
13
- > 安裝完成後,打開能讀寫本機專案資料夾的 AI agent。若 AI 已經在正確專案資料夾內,只需輸入:
11
+ > 🚀 **第一次用?你不需要先讀本 README 或任何文件。**
12
+ >
13
+ > 最簡單做法:在你要安裝或升級的資料夾打開能讀寫本機資料夾的 AI agent,貼上:
14
+ >
15
+ > ```text
16
+ > 請讀取 https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.html,並在這個資料夾安裝或升級 Agent Handoff Kit。
17
+ > ```
18
+ >
19
+ > AI 會先顯示目前資料夾並請你確認;未確認前不應安裝或升級。
20
+ >
21
+ > 安裝完成後,打開能讀寫本機專案資料夾的 AI agent。若 AI 已經在正確專案資料夾內,只需輸入:
14
22
  >
15
23
  > ```text
16
24
  > Start Agent Handoff
@@ -26,7 +34,7 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
26
34
  >
27
35
  > AI 會依 `AGENTS.md` 打開專案內的 `START_NEXT_SESSION_PROMPT.txt`。第一次安裝後,該檔會帶它載入新手引導;之後每次收工後,該檔會改成下一次接力需要的真實狀態。本 README 與下方介紹頁是參考對照,不是必讀。
28
36
 
29
- 想先看非技術版介紹,可打開 GitHub Pages 上的 [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html) —— 新手 60 秒入門。看完想看實際操作示範,可開 [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html) —— 三個日常情境的完整流程示範。本 README 則保留安裝、日常使用與限制。
37
+ 想先看非技術版介紹,可打開 GitHub Pages 上的 [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html) —— 新手 60 秒入門。看完想看實際操作示範,可開 [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html) —— 三個日常情境的完整流程示範。若想讓 AI 代你判斷安裝或升級,給 AI 讀 [`agent-handoff-kit-ai-install.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.html)。本 README 則保留安裝、日常使用與限制。
30
38
 
31
39
  ## 它解決甚麼問題
32
40
 
@@ -35,7 +43,7 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
35
43
  | 問題 | Agent Handoff Kit 怎樣處理 |
36
44
  |---|---|
37
45
  | 新 AI 不知做到哪 | 用 `dev/SESSION_HANDOFF.md` 保存目前狀態、下一步、風險與驗收。 |
38
- | 新建檔案、參考資料變孤兒 | 你可以叫 AI 做「治理打通」,用 `dev/PROJECT_INDEX.md` 與 `dev/DOC_SYNC_REGISTRY.md` 登記檔案角色、真源與同步責任。 |
46
+ | 新建檔案、參考資料變孤兒 | 你可以叫 AI 把文件接入 Agent Handoff Kit,用 `dev/PROJECT_INDEX.md` 與 `dev/DOC_SYNC_REGISTRY.md` 登記檔案角色、真源與同步責任。 |
39
47
  | 不同 AI 工具入口不同 | 同時安裝 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,全部指向同一套開工流程;Antigravity CLI 會讀工作資料夾內的 `AGENTS.md` 與 `GEMINI.md`。 |
40
48
  | AI 可能亂改、亂刪或誤發佈 | 內置安全規則;高風險操作必須先講計劃,破壞性指令與未批准發佈一律禁止。 |
41
49
 
@@ -45,7 +53,7 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
45
53
 
46
54
  ![Agent Handoff Kit 新手流程](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-new-user-flow.png)
47
55
 
48
- 這張圖是給第一次使用的人看的流程摘要:先在專案資料夾安裝,然後在能讀寫本機資料夾的 AI 對話輸入 `Start Agent Handoff` 或「開工」;AI 會依 `AGENTS.md` 打開 `START_NEXT_SESSION_PROMPT.txt` 進入新手引導。準備結束本輪工作時說「收工」,讓 AI 留下下一次能接上的交接。
56
+ 這張圖是給第一次使用的人看的流程摘要:先在目標資料夾讓 AI 讀安裝指令頁,或手動執行 `npx --yes @adamchanadam/agent-handoff-kit@latest init`;安裝完成後,在能讀寫本機資料夾的 AI 對話輸入 `Start Agent Handoff` 或「開工」。AI 會依 `AGENTS.md` 打開 `START_NEXT_SESSION_PROMPT.txt` 進入新手引導。準備結束本輪工作時說「收工」,讓 AI 留下下一次能接上的交接。
49
57
 
50
58
  ### 適用工具
51
59
 
@@ -53,9 +61,19 @@ Agent Handoff Kit 適合能讀寫本機專案資料夾的 agentic AI 工具,
53
61
 
54
62
  它不適合普通 web chat AI,例如沒有本機檔案讀寫能力的 ChatGPT、Claude、Gemini 網頁版。上載檔案或貼上交接內容不能取代本工具需要的本機讀寫能力;這類工具不能可靠維護專案內的交接文件。
55
63
 
56
- ### 一、安裝
57
-
58
- 在你的專案資料夾打開終端機,執行:
64
+ ### 一、安裝
65
+
66
+ 最簡單做法,是在目標資料夾打開能讀寫本機資料夾的 AI agent,貼上:
67
+
68
+ ```text
69
+ 請讀取 https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.html,並在這個資料夾安裝或升級 Agent Handoff Kit。
70
+ ```
71
+
72
+ AI 應先顯示目前資料夾的絕對路徑,問你是否就是要安裝或升級的資料夾;確認後才判斷要執行 `init`、`upgrade --dry-run`、`upgrade` 或停在衝突狀態。
73
+
74
+ 如你想手動安裝,才用下面的終端機指令。
75
+
76
+ 在你的專案資料夾打開終端機,執行:
59
77
 
60
78
  ```bash
61
79
  npx --yes @adamchanadam/agent-handoff-kit@latest init
@@ -71,13 +89,15 @@ npx --yes @adamchanadam/agent-handoff-kit@latest init
71
89
 
72
90
  安裝成功後,先做 AI 對話,不必立刻跑 `doctor`。`doctor` 是之後不確定狀態、升級後驗收,或 AI 要排錯時才需要用的檢查工具。
73
91
 
74
- ### 常見入口
75
-
76
- | 你現在的狀態 | 建議指令 |
77
- |---|---|
78
- | 第一次在新資料夾使用 | `npx --yes @adamchanadam/agent-handoff-kit@latest init` |
79
- | 已安裝舊版,或已有 AI 記憶文件 | `npx --yes @adamchanadam/agent-handoff-kit@latest upgrade` |
80
- | 不確定是否安裝完整,或升級後想檢查 | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor` |
92
+ ### 手動入口
93
+
94
+ 如果你不用 AI 代判斷安裝或升級,才直接使用下表指令。
95
+
96
+ | 你現在的狀態 | 手動指令 |
97
+ |---|---|
98
+ | 第一次在新資料夾使用 | `npx --yes @adamchanadam/agent-handoff-kit@latest init` |
99
+ | 已安裝舊版,或已有 AI 記憶文件 | `npx --yes @adamchanadam/agent-handoff-kit@latest upgrade` |
100
+ | 不確定是否安裝完整,或升級後想檢查 | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor` |
81
101
 
82
102
  ### 已安裝舊版,或已有 AI 記憶文件?
83
103
 
@@ -227,13 +247,16 @@ dev/rules/*.md
227
247
 
228
248
  新手用戶完全不需要打開本檔,也不需要記任何結構 —— 一切由 AI 自動處理。
229
249
 
230
- ## 治理打通:讓重要文件不要變孤兒
250
+ ## 把重要文件接入 Agent Handoff Kit
231
251
 
232
252
  長期項目常會產生新文件,例如 stock list、production guide、runbook、workflow、checklist、研究真源或操作清單。文件本身做完,不代表下一個 AI 一定知道它存在,也不代表 AI 知道何時要讀、何時要更新、是否有另一份舊版真源。
233
253
 
234
- 這時可以在 AI 對話中直接說:
254
+ 常見有兩種用法。
255
+
256
+ 第一種是指定一份文件,讓 AI 審核這份文件是否已接入治理層:
235
257
 
236
258
  ```text
259
+ 把 docs/production-guide.md 接入 Agent Handoff Kit
237
260
  治理打通 docs/production-guide.md
238
261
  ```
239
262
 
@@ -246,14 +269,17 @@ connect this document to governance
246
269
 
247
270
  AI 會檢查這份文件是否已接入項目記憶:文件本身是否講清楚用途與更新時機、`dev/PROJECT_INDEX.md` 是否登記它、`dev/DOC_SYNC_REGISTRY.md` 是否記下同類變更要同步哪裡、相關 workflow 是否會提醒更新它,以及 handoff / log 是否各自放在正確角色。
248
271
 
249
- 如果你不確定整個 repo 有沒有漏接的文件,可以說:
272
+ 第二種是不指定單一文件,先掃描整個 repo 有沒有疑似未接合的重要文件:
250
273
 
251
274
  ```text
275
+ 掃描未接入 Agent Handoff Kit 的重要文件
252
276
  掃描 repo 有沒有未接合文件
253
277
  scan for unbridged governance documents
254
278
  ```
255
279
 
256
- 這個掃描只列出候選與缺口,不會自動刪除、改名或合併文件。若發現兩份文件像是同一個真源,AI 只會列出合併、引用或退役建議,等你確認。
280
+ 這個掃描只列出候選與缺口,不會一邊掃描一邊自動修改。若你同意其中某個建議,可以再叫 AI 按建議補丁更新索引、同步登記或相關流程。若涉及刪除、改名、合併真源,AI 只會列出合併、引用或退役建議,等你明確確認。
281
+
282
+ 這裡的「接入 Agent Handoff Kit」只指文件接合:避免重要文件變成下一個 AI 不知道要讀、不知道要更新的孤兒文件。若你想保存一條長期有效的做法,例如「以後都用這個 API 調用方式」、「把今次錯誤變成日後機制」、「這條工具使用方法要跨 session 生效」,請直接說「把這件事轉成長期機制」或「寫入長期治理」。AI 應把這類內容分流到規則包、項目索引、同步登記、決策紀錄或驗收檢查;不應只寫入 `dev/SESSION_LOG.md`、`dev/SESSION_HANDOFF.md` 或 `START_NEXT_SESSION_PROMPT.txt`。
257
283
 
258
284
  ## 外部工具治理
259
285
 
@@ -279,7 +305,8 @@ scan for unbridged governance documents
279
305
  | 整理 Notion、Google Drive 或知識庫 | 知識整理規則 |
280
306
  | 準備發佈說明 | 發佈規則;真正發佈、上傳或建立版本前必須再讀安全規則 |
281
307
  | 改規則、改流程、整理交接 | AI 治理規則;先找既有真源,不盲目新增規則 |
282
- | 新建重要文件後想避免變孤兒 | AI 治理規則;說「治理打通 <檔案>」,讓 AI 檢查索引、同步責任、相關流程與重複真源風險 |
308
+ | 新建重要文件後想避免變孤兒 | AI 治理規則;說「把 <檔案> 接入 Agent Handoff Kit」,讓 AI 檢查索引、同步責任、相關流程與重複真源風險 |
309
+ | 把錯誤經驗、API 用法或工具用法變成日後都有效的機制 | AI 治理規則;說「轉成長期機制」或「寫入長期治理」,讓 AI 找正確持久位置,不只留在 session log 或 handoff |
283
310
 
284
311
  原則是只讀當前任務需要的規則,不是每次讀全部文件。
285
312
 
@@ -310,11 +337,11 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
310
337
  - **Adam-AI-Instructions** 負責 AI 在**單一對話**內的做事規矩:語氣、做事優先序、回覆骨架、計算紀律、用語紀律、安全護欄、輸出層分工。屬「AI 應該怎樣答你」的持久基準。
311
338
  - **Agent Handoff Kit** 負責 AI 在**對話之間**的接力:當前狀態、下一步、檔案登記、收工同下次開工。屬「AI 在對話之間怎樣記住你的項目」的持久基準。
312
339
 
313
- 到該倉庫的「五、提示詞索引」選擇適合你 AI 工具的版本(Claude Cowork、Claude Code、OpenAI Codex、ChatGPT 等),複製對應子目錄的 `prompt.md` 全文,貼入 AI 工具設定。然後再在項目資料夾執行 `npx --yes @adamchanadam/agent-handoff-kit@latest init` 安裝本工具。兩者配合,就能同時照顧單次對話的做事規矩,以及不同對話之間的項目接力。
340
+ 到該倉庫的「五、提示詞索引」選擇適合你 AI 工具的版本(Claude Cowork、Claude Code、OpenAI Codex、ChatGPT 等),複製對應子目錄的 `prompt.md` 全文,貼入 AI 工具設定。然後在項目資料夾打開能讀寫本機資料夾的 AI agent,請它讀 `https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.html` 並在這個資料夾安裝或升級本工具;如你想手動處理,才執行 `npx --yes @adamchanadam/agent-handoff-kit@latest init`。兩者配合,就能同時照顧單次對話的做事規矩,以及不同對話之間的項目接力。
314
341
 
315
342
  ## 目前限制
316
343
 
317
- - 目前版本為 `v0.3.27`;正式安裝請以 npm registry `latest` 顯示為準。
344
+ - 目前版本為 `v0.3.29`;正式安裝請以 npm registry `latest` 顯示為準。
318
345
  - 這是早期可用版本,仍在持續完善中。
319
346
  - 升級合併屬窄範圍策略,不是完整的複雜合併工具。
320
347
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
@@ -382,6 +382,8 @@ const schemaChecks = [
382
382
  // R-030 v0.3.0+: routing table must include integrations pack row.
383
383
  includes("dev/rules/integrations.md"),
384
384
  includes("Governance bridge / 治理打通"),
385
+ includes("接入 Agent Handoff Kit"),
386
+ includes("掃描未接入 Agent Handoff Kit 的重要文件"),
385
387
  includes("scan for unbridged governance documents")
386
388
  ]
387
389
  },
@@ -396,6 +398,8 @@ const schemaChecks = [
396
398
  heading("Checks"),
397
399
  heading("Closeout"),
398
400
  includes("Governance bridge is a triggered review"),
401
+ includes("接入 Agent Handoff Kit"),
402
+ includes("掃描未接入 Agent Handoff Kit 的重要文件"),
399
403
  includes("Status: bridged / partially bridged / unbridged / blocked"),
400
404
  includes("duplicate source-of-truth risk")
401
405
  ]
@@ -1576,7 +1580,11 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1576
1580
  }
1577
1581
  // Governance bridge v0.3.27+: route durable document bridging requests to
1578
1582
  // agent-governance without replacing user-added routing rows.
1579
- if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("Governance bridge / 治理打通")) {
1583
+ if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && (
1584
+ !targetText.includes("Governance bridge / 治理打通")
1585
+ || !targetText.includes("接入 Agent Handoff Kit")
1586
+ || !targetText.includes("掃描未接入 Agent Handoff Kit 的重要文件")
1587
+ )) {
1580
1588
  const mergedRulePacks = mergeRulePacksRows(targetText, sourceText);
1581
1589
  if (!mergedRulePacks) {
1582
1590
  return { ...base, action: "conflict", reason: "RULE_PACKS.md routing table header was changed; manual merge required to preserve custom rows" };
@@ -1590,7 +1598,11 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1590
1598
  }
1591
1599
  // Governance bridge v0.3.27+: add the triggered review workflow to the
1592
1600
  // agent-governance pack only when the pack still has a trusted Checks section.
1593
- if (targetRel === "dev/rules/agent-governance.md" && command === "upgrade" && !targetText.includes("## Governance Bridge Workflow")) {
1601
+ if (targetRel === "dev/rules/agent-governance.md" && command === "upgrade" && (
1602
+ !targetText.includes("## Governance Bridge Workflow")
1603
+ || !targetText.includes("接入 Agent Handoff Kit")
1604
+ || !targetText.includes("掃描未接入 Agent Handoff Kit 的重要文件")
1605
+ )) {
1594
1606
  const mergedGovernancePack = mergeAgentGovernanceBridgeWorkflow(targetText, sourceText);
1595
1607
  if (!mergedGovernancePack) {
1596
1608
  return { ...base, action: "conflict", reason: "agent-governance pack structure was changed; manual merge required to add governance bridge workflow" };
@@ -1806,9 +1818,19 @@ function mergeOnboardingScenarioALabel(targetText) {
1806
1818
  function mergeAgentGovernanceBridgeWorkflow(targetText, sourceText) {
1807
1819
  const sourceMatch = sourceText.match(/9\. Governance bridge[\s\S]*?(?=\n## Checks)/);
1808
1820
  const workflowMatch = sourceText.match(/\n## Governance Bridge Workflow[\s\S]*?(?=\n## Checks)/);
1821
+ const sourceLoadWhenLine = sourceText.split(/\r?\n/).find((line) => line.startsWith("- User asks to \"治理打通\""));
1822
+ const sourceWorkflowIntroLine = sourceText.split(/\r?\n/).find((line) => line.startsWith("Use this workflow when"));
1809
1823
  if (!sourceMatch || !workflowMatch || !targetText.includes("\n## Checks")) return null;
1810
1824
 
1811
1825
  let merged = targetText;
1826
+ const targetLoadWhenLine = merged.split(/\r?\n/).find((line) => line.startsWith("- User asks to \"治理打通\""));
1827
+ if (sourceLoadWhenLine && (!targetLoadWhenLine || !targetLoadWhenLine.includes("接入 Agent Handoff Kit"))) {
1828
+ merged = merged.replace(/- User asks to "治理打通"[^\n]*\n/, `${sourceLoadWhenLine}\n`);
1829
+ }
1830
+ const targetWorkflowIntroLine = merged.match(/^Use this workflow when[^\n]*$/m)?.[0] ?? "";
1831
+ if (sourceWorkflowIntroLine && !targetWorkflowIntroLine.includes("掃描未接入 Agent Handoff Kit 的重要文件")) {
1832
+ merged = merged.replace(/^Use this workflow when[^\n]*$/m, sourceWorkflowIntroLine);
1833
+ }
1812
1834
  if (!merged.includes("Governance bridge is a triggered review")) {
1813
1835
  const rulePrefix = sourceMatch[0].trimEnd();
1814
1836
  merged = merged.replace(/\n## Checks/, `\n${rulePrefix}\n${workflowMatch[0]}\n## Checks`);
@@ -2452,8 +2474,19 @@ function mergeRulePacksRows(targetText, sourceText) {
2452
2474
 
2453
2475
  const before = lines.slice(0, tableStart);
2454
2476
  const table = lines.slice(tableStart, tableEnd);
2455
- const after = lines.slice(tableEnd);
2456
- const sourceRowsToApply = sourceRows.filter((row) => {
2477
+ const after = lines.slice(tableEnd);
2478
+ const governanceBridgeSourceRow = sourceRows.find((row) => row.includes("Governance bridge / 治理打通"));
2479
+ if (
2480
+ governanceBridgeSourceRow
2481
+ && targetText.includes("Governance bridge / 治理打通")
2482
+ && (!targetText.includes("接入 Agent Handoff Kit") || !targetText.includes("掃描未接入 Agent Handoff Kit 的重要文件"))
2483
+ ) {
2484
+ const replaced = lines.map((line) => (
2485
+ line.includes("Governance bridge / 治理打通") ? governanceBridgeSourceRow : line
2486
+ ));
2487
+ return replaced.join("\n");
2488
+ }
2489
+ const sourceRowsToApply = sourceRows.filter((row) => {
2457
2490
  if (row.includes("dev/rules/onboarding.md")) return !targetText.includes("First-time user signals");
2458
2491
  if (row.includes("dev/rules/integrations.md")) return !targetText.includes("External tool integrations");
2459
2492
  if (row.includes("Governance bridge / 治理打通")) return !targetText.includes("Governance bridge / 治理打通");
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.27",
3
+ "version": "0.3.29",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -8,7 +8,8 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
8
8
 
9
9
  - User asks to change AI behavior, project governance, prompts, handoff, startup, closeout, or tool-use rules.
10
10
  - A change affects `AGENTS.md`, `dev/*`, rule packs, installer templates, or durable workflow docs.
11
- - User asks to "治理打通", "bridge governance", "connect this document to governance", or scan for unbridged governance documents.
11
+ - User asks to "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", "掃描未接入 Agent Handoff Kit 的重要文件", "bridge governance", "connect this document to governance", or scan for unbridged governance documents.
12
+ - User asks to make something long-term, cross-session, reusable, "寫入長期治理", "轉成長期機制", "之後都要遵守", or says future sessions should remember an API / MCP / tool-use pattern.
12
13
 
13
14
  ## Rules
14
15
 
@@ -21,10 +22,11 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
21
22
  7. When a task uses external skills, subagents, demo workspaces, or another tool's closeout, treat those flows as subordinate to the active root's Agent Handoff Kit governance. The active root still needs the `runtime-core/AGENTS.core.md` persistence gate decision; do not duplicate the gate thresholds in this pack.
22
23
  8. For long-running projects, maintain `dev/PROJECT_DECISIONS.md` per R-028 closeout discipline (see `runtime-core/AGENTS.core.md` closeout maintenance trigger check): capture major decisions when they happen, run the short trigger check at every closeout, and do full long-term maintenance only when a hard trigger, semantic trigger, or 10-closeout backstop applies. Short single-task projects keep this as a no-op default; users are not expected to edit this file manually.
23
24
  9. Governance bridge is a triggered review, not a default startup scan. Use it when an important file, source-of-truth document, runbook, production guide, workflow, checklist, stock list, or similar durable document may need to be connected to project governance.
25
+ 10. Content-based trigger: long-term governance routing is content-based, not trigger-only. Even if the user does not say "轉成長期機制" or "寫入長期治理", treat a statement as durable governance when it says future sessions must follow it, when it corrects a recurring AI mistake, or when it defines a reusable API / MCP / tool-use pattern. Do not persist long-term governance knowledge only in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or `START_NEXT_SESSION_PROMPT.txt`; those surfaces may be compressed, archived, or regenerated.
24
26
 
25
27
  ## Governance Bridge Workflow
26
28
 
27
- Use this workflow when the user asks for governance bridge / 治理打通 / connect this document to governance, or asks to scan for unbridged governance documents.
29
+ Use this workflow when the user asks for governance bridge / 治理打通 / 把文件接入 Agent Handoff Kit / 接入 Agent Handoff Kit / connect this document to governance, or asks to scan for unbridged governance documents / 掃描未接入 Agent Handoff Kit 的重要文件.
28
30
 
29
31
  1. Identify the target. If the user named a file, inspect that file and its surrounding directory. If no file is named, run a bounded repo scan for likely durable documents such as source-of-truth files, runbooks, workflows, guides, checklists, stock lists, production guides, and rules.
30
32
  2. Check the target file itself: it should state its role, scope, update trigger, owner or responsible workflow when known, and what must not be inferred from it.
@@ -37,6 +39,23 @@ Use this workflow when the user asks for governance bridge / 治理打通 / conn
37
39
 
38
40
  For repo-wide scans, report candidates as candidates. Do not fail ordinary docs merely because they are not indexed; only durable files that future agents need to discover, update, or distinguish from drafts should be bridged.
39
41
 
42
+ ## Long-term Governance Routing
43
+
44
+ Use this workflow when the user asks to write something into long-term governance, turn an experience into a mechanism, make a rule apply across sessions, or when the content itself clearly has durable force.
45
+
46
+ 1. Classify the knowledge before writing:
47
+ - Current task state, next action, unresolved risk, or startup-needed fact -> `dev/SESSION_HANDOFF.md`.
48
+ - Chronological evidence or validation trace -> `dev/SESSION_LOG.md`.
49
+ - File maps, command maps, API reference locations, tool capability maps, and external source coordinates -> `dev/PROJECT_INDEX.md`.
50
+ - Sync obligations or external mirror duties -> `dev/DOC_SYNC_REGISTRY.md`.
51
+ - Durable decisions, architecture trade-offs, research-derived rationale, and long-term lessons -> `dev/PROJECT_DECISIONS.md`.
52
+ - Reusable procedures, recurring mistake prevention, API / MCP / tool-use rules -> the relevant rule pack, registered reference, or QA check.
53
+ - API / MCP / tool-use patterns -> project index / registered reference / integrations pack, depending on scope.
54
+ 2. If the knowledge is reusable but no existing home fits, propose the smallest new registered reference or rule-pack patch. New runbooks remain last resort.
55
+ 3. If the knowledge was first captured in `SESSION_LOG` or handoff for short-term continuity, promote it to the correct durable home before claiming it is long-term.
56
+ 4. Add or update a QA check when the same failure class could recur and can be tested.
57
+ 5. Keep governance bridge wording reserved for document orphan prevention. Do not relabel non-file governance as "file connected to Agent Handoff Kit".
58
+
40
59
  Output format:
41
60
 
42
61
  - Status: bridged / partially bridged / unbridged / blocked.
@@ -53,6 +72,7 @@ Output format:
53
72
  - Confirm old overlapping wording was retired or marked legacy.
54
73
  - Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
55
74
  - Confirm reusable operating procedure knowledge is not stored only in `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, or a decision narrative when it belongs in a pack or registered reference.
75
+ - Confirm long-term governance knowledge is promoted out of `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, and `START_NEXT_SESSION_PROMPT.txt` when it should survive log archive or prompt regeneration.
56
76
  - For governance bridge work, confirm the target file, project index, sync registry, related workflow, handoff/log role split, and duplicate-source risk were all checked or explicitly marked not applicable.
57
77
  - Before claiming completion, apply the active root's core persistence gate and record the result only when that gate selects a checkpoint or full closeout; do not assume child or demo workspaces cover the parent/root workspace.
58
78
  - For long-running projects, confirm `dev/PROJECT_DECISIONS.md` retains its four H2 sections in order (Evolution Timeline / Decisions Archive / Architecture Choices / Insights & Learnings) and that the closeout maintenance trigger check was recorded, with full maintenance applied where its trigger conditions were met.
@@ -10,8 +10,9 @@ Read only the packs needed for the current task.
10
10
  | Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
11
11
  | Sources, evidence, comparison, fact finding | `dev/rules/research.md` | source handling and uncertainty |
12
12
  | Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |
13
- | Governance bridge / 治理打通 / bridge governance / connect this document to governance / scan for unbridged governance documents | `dev/rules/agent-governance.md` | connect important files, source-of-truth documents, runbooks, workflows, checklists, and guides to the project index, sync registry, handoff/log roles, and related workflows without creating duplicate sources of truth |
14
- | Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
13
+ | Governance bridge / 治理打通 / 把文件接入 Agent Handoff Kit / 接入 Agent Handoff Kit / 掃描未接入 Agent Handoff Kit 的重要文件 / bridge governance / connect this document to governance / scan for unbridged governance documents | `dev/rules/agent-governance.md` | connect important files, source-of-truth documents, runbooks, workflows, checklists, and guides to the project index, sync registry, handoff/log roles, and related workflows without creating duplicate sources of truth |
14
+ | Long-term governance routing / 寫入長期治理 / 轉成長期機制 / 之後都要遵守 / 跨 session 有效 / future sessions should remember / always use this API or MCP pattern | `dev/rules/agent-governance.md` | classify durable non-file knowledge by role and store it in the right home: rule pack, registered reference, project index, sync registry, project decisions, or QA check; do not leave reusable governance only in session log or handoff |
15
+ | Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
15
16
  | External notes, knowledge base, Notion, Obsidian, Google Drive | `dev/rules/knowledge.md` | external knowledge source integration |
16
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 |
17
18
  | Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |