@adamchanadam/agent-handoff-kit 0.4.1 → 0.4.3
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/LICENSE +21 -21
- package/README.en.md +1 -1
- package/README.md +1 -1
- package/bin/agent-handoff-kit.mjs +7107 -6887
- package/bin/commands.mjs +134 -134
- package/bin/handoff-read.mjs +88 -88
- package/bin/installed-file-contract.mjs +154 -90
- package/bin/migration-baselines/official-origin-catalog.json +514 -1
- package/bin/official-origin-catalog.mjs +294 -267
- package/bin/progress/ICON-LICENSE.txt +21 -21
- package/bin/progress/assets.mjs +6 -6
- package/bin/progress/dashboard.mjs +134 -134
- package/bin/progress/icons.svg +36 -36
- package/bin/progress/index.html +31 -31
- package/bin/progress/launch.mjs +40 -40
- package/bin/progress/open.mjs +43 -43
- package/bin/progress/project-version.mjs +121 -121
- package/bin/progress/projection.mjs +144 -144
- package/bin/progress/renderer.js +152 -152
- package/bin/progress/server.mjs +78 -78
- package/bin/progress/styles.css +31 -31
- package/bin/prompt-mirror-core.mjs +84 -84
- package/bin/upgrade-inventory.mjs +243 -243
- package/bin/user-rules-router.mjs +4 -4
- package/docs/commands.md +2 -2
- package/docs/progress.md +73 -73
- package/package.json +22 -22
- package/packs/agent-governance.md +120 -120
- package/packs/closeout.md +91 -91
- package/packs/coding.md +28 -28
- package/packs/integrations.md +20 -20
- package/packs/knowledge.md +3 -3
- package/packs/onboarding.md +43 -39
- package/packs/research.md +30 -30
- package/packs/safety.md +2 -2
- package/runtime-core/AGENTS.core.md +161 -147
- package/runtime-core/CLAUDE.md +13 -13
- package/runtime-core/DOC_SYNC_REGISTRY.md +24 -24
- package/runtime-core/GEMINI.md +17 -17
- package/runtime-core/PROJECT_DECISIONS.md +43 -43
- package/runtime-core/PROJECT_INDEX.md +16 -16
- package/runtime-core/RULE_PACKS.md +1 -1
- package/runtime-core/SESSION_HANDOFF.md +180 -180
- package/runtime-core/SESSION_LOG.md +37 -37
- package/runtime-core/START_NEXT_SESSION_PROMPT.txt +1 -1
- package/runtime-core/USER_RULES_ENTRY.md +2 -0
package/docs/progress.md
CHANGED
|
@@ -1,73 +1,73 @@
|
|
|
1
|
-
# Agent Handoff Kit 進度頁
|
|
2
|
-
|
|
3
|
-
[English](#dashboard)
|
|
4
|
-
|
|
5
|
-
在專案的 AI 對話輸入 `/handoff-kit-progress`;Codex 用 `$handoff-kit-progress`,或從 `/skills` 選取。AI 會開啟或重用這個專案的頁面。先看頁面上的專案名稱,避免認錯專案。
|
|
6
|
-
|
|
7
|
-
## 可以看到甚麼
|
|
8
|
-
|
|
9
|
-
- **總覽**:目前工作、成果、未完成、等待和待驗收事項。「正在查看」只是你選中的工作,不會改動紀錄。工作排列不是完成順序,完成子項也不代表整項完成。
|
|
10
|
-
- **歷程**:用近 7 日、近 30 日、自選日期、關鍵字和工作篩選,找回已保存的改變。日期篩選不會隱藏目前未完事項。長期紀錄分批讀取,還有內容時可繼續載入;日期排序只包括已載入結果。
|
|
11
|
-
- **文件地圖**:看重要文件的用途、關係及原文。這裏只列已登記文件,不是整個資料夾的所有檔案;沒有記錄的關係不會自行猜補。
|
|
12
|
-
|
|
13
|
-
## 何時更新,會用多少 token
|
|
14
|
-
|
|
15
|
-
AI 正常保存工作紀錄後,頁面自行更新,不用刷新,也不用重新設計。AI 只維護有變的進度和必要紀錄,不必記下每一步操作或再寫一份報告。
|
|
16
|
-
|
|
17
|
-
叫 AI 開頁面和保存紀錄會使用一些 token;之後瀏覽、篩選、動畫和畫面更新不呼叫 AI。沿用安裝時已有的 Node.js 和瀏覽器,不需另外安裝資料庫、Python 或購買金鑰。進度頁程式會隨正常安裝/升級一併準備好;開頁不需下載工具或連接 npm。
|
|
18
|
-
|
|
19
|
-
頁面可切換繁體中文和英文。若紀錄本身沒有翻譯,就保留原文。動畫只提示選取或資料變更,不表示 AI 正在思考或工作已驗收。
|
|
20
|
-
|
|
21
|
-
## 看到缺漏或舊資料時
|
|
22
|
-
|
|
23
|
-
| 情況 | 意思與做法 |
|
|
24
|
-
|---|---|
|
|
25
|
-
| 未記錄/尚未分類 | 原有紀錄沒有這項資料。AI 不會猜進度百分比或完成狀態;可查看原文,或請 AI 在正常保存時補清楚。 |
|
|
26
|
-
| 紀錄只顯示一部分 | 首頁先顯示摘要,其餘可看完整工作或原文。歷史資料太多、缺檔或格式有問題時,頁面會提示未讀齊;縮窄日期或請 AI 查明原因。 |
|
|
27
|
-
| 斷線/更新失敗 | 畫面保留上次資料並提示,會自動重試。可按「立即重連」;仍失敗就再用進度頁指令。 |
|
|
28
|
-
| 升級中 | 暫停讀取,等升級完成後再看,避免把更新到一半的內容當作最新。 |
|
|
29
|
-
| 版本未核實/版本不同 | 頁面從專案讀取這套工具的版本;讀不到不會猜。「資料依據」另列開啟頁面的工具版本。有疑問用 `handoff-kit-check`;查最新正式版用 `handoff-kit-update`。 |
|
|
30
|
-
|
|
31
|
-
「交接保存」是交接文件的保存時間,不是所有專案檔案最後修改的時間。未保存的聊天內容不會出現。頁面只整理已保存的內容,不能證明 AI 已讀齊交接或成果已經驗收。
|
|
32
|
-
|
|
33
|
-
## 關掉後怎樣重開
|
|
34
|
-
|
|
35
|
-
頁面開着時會持續連線。全部頁面關閉後,本機服務保留八小時;閒置時不反覆讀檔。超過時間、電腦重啟或服務停止後,再用同一個進度頁指令即可。舊網址不能自己啟動已停止的程式。
|
|
36
|
-
|
|
37
|
-
這是你電腦上的檢視頁,不會公開上網。查看、篩選和點選文件不會改檔;它只讀取專案內已登記、允許顯示的文件,原文以文字顯示。請勿把密碼等秘密寫進專案紀錄。
|
|
38
|
-
|
|
39
|
-
## Dashboard
|
|
40
|
-
|
|
41
|
-
In your project’s AI conversation, enter `/handoff-kit-progress`. In Codex, use `$handoff-kit-progress` or select it through `/skills`. The AI opens or reuses that project’s page. Check the displayed project name so you know which project you are viewing.
|
|
42
|
-
|
|
43
|
-
### What you can see
|
|
44
|
-
|
|
45
|
-
- **Overview**: current work, results, unfinished items, things waiting and work awaiting checks. “Viewing” identifies your selection without changing records. The order of work items is not a completion sequence, and completing a child does not complete its parent.
|
|
46
|
-
- **History**: find saved changes using the last 7 days, last 30 days, custom dates, keywords and work filters. Date filters do not hide current outstanding items. Long histories load in batches; load more when available. Date sorting covers only loaded results.
|
|
47
|
-
- **Documents**: see important files, their purpose, connections and source text. Only registered files appear, not every file in the folder. Unrecorded connections are not invented.
|
|
48
|
-
|
|
49
|
-
### Updates and token use
|
|
50
|
-
|
|
51
|
-
The page updates when the AI saves normal work records, without a refresh or redesign. The AI maintains changed progress and necessary records, rather than logging every action or writing a second report.
|
|
52
|
-
|
|
53
|
-
Asking the AI to open the page and saving records use some tokens. After that, browsing, filters, animation and page updates make no AI calls. It uses the tool’s existing Node.js and your browser; no database, Python or purchased key is needed. Normal installation or upgrade supplies the progress program; opening it requires no tool download or npm connection.
|
|
54
|
-
|
|
55
|
-
The interface switches between Traditional Chinese and English. Records without a translation keep their original language. Animation indicates a selection or changed data, not AI thinking or accepted work.
|
|
56
|
-
|
|
57
|
-
### Missing or older information
|
|
58
|
-
|
|
59
|
-
| What you see | What it means and what to do |
|
|
60
|
-
|---|---|
|
|
61
|
-
| Unrecorded / unclassified | The records lack that information. No progress percentages or completion states are guessed. Read the source or ask the AI to clarify it during a normal save. |
|
|
62
|
-
| Only part of the history | Home shows summaries with links to full work or sources. Large histories, missing files or formatting problems produce an incomplete-coverage notice. Narrow the dates or ask the AI to investigate. |
|
|
63
|
-
| Disconnected / update failed | The page keeps the last data with a warning and retries. Select “Reconnect now”, or use the Progress shortcut again if it still fails. |
|
|
64
|
-
| Upgrade in progress | Reading pauses until the upgrade finishes, so partly updated files are not treated as current. |
|
|
65
|
-
| Version unverified / versions differ | The page reads the version recorded in this project and does not guess if it is unavailable. Sources also lists the tool version that opened the page. Use `handoff-kit-check` for concerns or `handoff-kit-update` to check the latest release. |
|
|
66
|
-
|
|
67
|
-
“Handoff saved” is the handoff file’s save time, not the last change to every project file. Unsaved chat content does not appear. The page organizes saved records; it does not prove that the AI has read the full handoff or that the work has passed its checks.
|
|
68
|
-
|
|
69
|
-
### Reopening the page
|
|
70
|
-
|
|
71
|
-
The service stays connected while a page is open. After all pages close, it remains available for eight hours without repeatedly reading files while idle. After that, a computer restart or a stopped service, use the same Progress shortcut again. An old browser address cannot start a stopped program by itself.
|
|
72
|
-
|
|
73
|
-
This is a view on your computer, not a public website. Browsing, filtering and selecting files do not edit them. Only registered files within the project that are allowed for display are read, and their contents are shown as text. Do not put passwords or other secrets into project records.
|
|
1
|
+
# Agent Handoff Kit 進度頁
|
|
2
|
+
|
|
3
|
+
[English](#dashboard)
|
|
4
|
+
|
|
5
|
+
在專案的 AI 對話輸入 `/handoff-kit-progress`;Codex 用 `$handoff-kit-progress`,或從 `/skills` 選取。AI 會開啟或重用這個專案的頁面。先看頁面上的專案名稱,避免認錯專案。
|
|
6
|
+
|
|
7
|
+
## 可以看到甚麼
|
|
8
|
+
|
|
9
|
+
- **總覽**:目前工作、成果、未完成、等待和待驗收事項。「正在查看」只是你選中的工作,不會改動紀錄。工作排列不是完成順序,完成子項也不代表整項完成。
|
|
10
|
+
- **歷程**:用近 7 日、近 30 日、自選日期、關鍵字和工作篩選,找回已保存的改變。日期篩選不會隱藏目前未完事項。長期紀錄分批讀取,還有內容時可繼續載入;日期排序只包括已載入結果。
|
|
11
|
+
- **文件地圖**:看重要文件的用途、關係及原文。這裏只列已登記文件,不是整個資料夾的所有檔案;沒有記錄的關係不會自行猜補。
|
|
12
|
+
|
|
13
|
+
## 何時更新,會用多少 token
|
|
14
|
+
|
|
15
|
+
AI 正常保存工作紀錄後,頁面自行更新,不用刷新,也不用重新設計。AI 只維護有變的進度和必要紀錄,不必記下每一步操作或再寫一份報告。
|
|
16
|
+
|
|
17
|
+
叫 AI 開頁面和保存紀錄會使用一些 token;之後瀏覽、篩選、動畫和畫面更新不呼叫 AI。沿用安裝時已有的 Node.js 和瀏覽器,不需另外安裝資料庫、Python 或購買金鑰。進度頁程式會隨正常安裝/升級一併準備好;開頁不需下載工具或連接 npm。
|
|
18
|
+
|
|
19
|
+
頁面可切換繁體中文和英文。若紀錄本身沒有翻譯,就保留原文。動畫只提示選取或資料變更,不表示 AI 正在思考或工作已驗收。
|
|
20
|
+
|
|
21
|
+
## 看到缺漏或舊資料時
|
|
22
|
+
|
|
23
|
+
| 情況 | 意思與做法 |
|
|
24
|
+
|---|---|
|
|
25
|
+
| 未記錄/尚未分類 | 原有紀錄沒有這項資料。AI 不會猜進度百分比或完成狀態;可查看原文,或請 AI 在正常保存時補清楚。 |
|
|
26
|
+
| 紀錄只顯示一部分 | 首頁先顯示摘要,其餘可看完整工作或原文。歷史資料太多、缺檔或格式有問題時,頁面會提示未讀齊;縮窄日期或請 AI 查明原因。 |
|
|
27
|
+
| 斷線/更新失敗 | 畫面保留上次資料並提示,會自動重試。可按「立即重連」;仍失敗就再用進度頁指令。 |
|
|
28
|
+
| 升級中 | 暫停讀取,等升級完成後再看,避免把更新到一半的內容當作最新。 |
|
|
29
|
+
| 版本未核實/版本不同 | 頁面從專案讀取這套工具的版本;讀不到不會猜。「資料依據」另列開啟頁面的工具版本。有疑問用 `handoff-kit-check`;查最新正式版用 `handoff-kit-update`。候選版實測須在執行 `npx` 的工作目錄選擇受控的一般 `registry=`,不是只以 Node 讀取專案 `.npmrc`。 |
|
|
30
|
+
|
|
31
|
+
「交接保存」是交接文件的保存時間,不是所有專案檔案最後修改的時間。未保存的聊天內容不會出現。頁面只整理已保存的內容,不能證明 AI 已讀齊交接或成果已經驗收。
|
|
32
|
+
|
|
33
|
+
## 關掉後怎樣重開
|
|
34
|
+
|
|
35
|
+
頁面開着時會持續連線。全部頁面關閉後,本機服務保留八小時;閒置時不反覆讀檔。超過時間、電腦重啟或服務停止後,再用同一個進度頁指令即可。舊網址不能自己啟動已停止的程式。
|
|
36
|
+
|
|
37
|
+
這是你電腦上的檢視頁,不會公開上網。查看、篩選和點選文件不會改檔;它只讀取專案內已登記、允許顯示的文件,原文以文字顯示。請勿把密碼等秘密寫進專案紀錄。
|
|
38
|
+
|
|
39
|
+
## Dashboard
|
|
40
|
+
|
|
41
|
+
In your project’s AI conversation, enter `/handoff-kit-progress`. In Codex, use `$handoff-kit-progress` or select it through `/skills`. The AI opens or reuses that project’s page. Check the displayed project name so you know which project you are viewing.
|
|
42
|
+
|
|
43
|
+
### What you can see
|
|
44
|
+
|
|
45
|
+
- **Overview**: current work, results, unfinished items, things waiting and work awaiting checks. “Viewing” identifies your selection without changing records. The order of work items is not a completion sequence, and completing a child does not complete its parent.
|
|
46
|
+
- **History**: find saved changes using the last 7 days, last 30 days, custom dates, keywords and work filters. Date filters do not hide current outstanding items. Long histories load in batches; load more when available. Date sorting covers only loaded results.
|
|
47
|
+
- **Documents**: see important files, their purpose, connections and source text. Only registered files appear, not every file in the folder. Unrecorded connections are not invented.
|
|
48
|
+
|
|
49
|
+
### Updates and token use
|
|
50
|
+
|
|
51
|
+
The page updates when the AI saves normal work records, without a refresh or redesign. The AI maintains changed progress and necessary records, rather than logging every action or writing a second report.
|
|
52
|
+
|
|
53
|
+
Asking the AI to open the page and saving records use some tokens. After that, browsing, filters, animation and page updates make no AI calls. It uses the tool’s existing Node.js and your browser; no database, Python or purchased key is needed. Normal installation or upgrade supplies the progress program; opening it requires no tool download or npm connection.
|
|
54
|
+
|
|
55
|
+
The interface switches between Traditional Chinese and English. Records without a translation keep their original language. Animation indicates a selection or changed data, not AI thinking or accepted work.
|
|
56
|
+
|
|
57
|
+
### Missing or older information
|
|
58
|
+
|
|
59
|
+
| What you see | What it means and what to do |
|
|
60
|
+
|---|---|
|
|
61
|
+
| Unrecorded / unclassified | The records lack that information. No progress percentages or completion states are guessed. Read the source or ask the AI to clarify it during a normal save. |
|
|
62
|
+
| Only part of the history | Home shows summaries with links to full work or sources. Large histories, missing files or formatting problems produce an incomplete-coverage notice. Narrow the dates or ask the AI to investigate. |
|
|
63
|
+
| Disconnected / update failed | The page keeps the last data with a warning and retries. Select “Reconnect now”, or use the Progress shortcut again if it still fails. |
|
|
64
|
+
| Upgrade in progress | Reading pauses until the upgrade finishes, so partly updated files are not treated as current. |
|
|
65
|
+
| Version unverified / versions differ | The page reads the version recorded in this project and does not guess if it is unavailable. Sources also lists the tool version that opened the page. Use `handoff-kit-check` for concerns or `handoff-kit-update` to check the latest release. Candidate testing selects the controlled general `registry=` in the working directory that invokes `npx`; a direct Node read of a project `.npmrc` alone is not that route. |
|
|
66
|
+
|
|
67
|
+
“Handoff saved” is the handoff file’s save time, not the last change to every project file. Unsaved chat content does not appear. The page organizes saved records; it does not prove that the AI has read the full handoff or that the work has passed its checks.
|
|
68
|
+
|
|
69
|
+
### Reopening the page
|
|
70
|
+
|
|
71
|
+
The service stays connected while a page is open. After all pages close, it remains available for eight hours without repeatedly reading files while idle. After that, a computer restart or a stopped service, use the same Progress shortcut again. An old browser address cannot start a stopped program by itself.
|
|
72
|
+
|
|
73
|
+
This is a view on your computer, not a public website. Browsing, filtering and selecting files do not edit them. Only registered files within the project that are allowed for display are read, and their contents are shown as text. Do not put passwords or other secrets into project records.
|
package/package.json
CHANGED
|
@@ -1,22 +1,22 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@adamchanadam/agent-handoff-kit",
|
|
3
|
-
"version": "0.4.
|
|
4
|
-
"description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"bin": {
|
|
7
|
-
"agent-handoff-kit": "bin/agent-handoff-kit.mjs"
|
|
8
|
-
},
|
|
9
|
-
"files": [
|
|
10
|
-
"bin/",
|
|
11
|
-
"runtime-core/",
|
|
12
|
-
"packs/",
|
|
13
|
-
"README.md",
|
|
14
|
-
"docs/progress.md",
|
|
15
|
-
"docs/commands.md",
|
|
16
|
-
"LICENSE"
|
|
17
|
-
],
|
|
18
|
-
"engines": {
|
|
19
|
-
"node": ">=18"
|
|
20
|
-
},
|
|
21
|
-
"license": "MIT"
|
|
22
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@adamchanadam/agent-handoff-kit",
|
|
3
|
+
"version": "0.4.3",
|
|
4
|
+
"description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"agent-handoff-kit": "bin/agent-handoff-kit.mjs"
|
|
8
|
+
},
|
|
9
|
+
"files": [
|
|
10
|
+
"bin/",
|
|
11
|
+
"runtime-core/",
|
|
12
|
+
"packs/",
|
|
13
|
+
"README.md",
|
|
14
|
+
"docs/progress.md",
|
|
15
|
+
"docs/commands.md",
|
|
16
|
+
"LICENSE"
|
|
17
|
+
],
|
|
18
|
+
"engines": {
|
|
19
|
+
"node": ">=18"
|
|
20
|
+
},
|
|
21
|
+
"license": "MIT"
|
|
22
|
+
}
|
|
@@ -1,120 +1,120 @@
|
|
|
1
|
-
# Agent Governance Pack
|
|
2
|
-
|
|
3
|
-
## Scope
|
|
4
|
-
|
|
5
|
-
Use for governance rules, prompts, agent instructions, handoff systems, startup/closeout behavior, skills, and rule packs.
|
|
6
|
-
|
|
7
|
-
## Load When
|
|
8
|
-
|
|
9
|
-
- User asks to change AI behavior, project governance, prompts, handoff, startup, closeout, or tool-use rules.
|
|
10
|
-
- A change affects `AGENTS.md`, `dev/*`, rule packs, installer templates, or durable workflow docs.
|
|
11
|
-
- User asks to bridge governance, connect a document to governance, scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
|
|
12
|
-
- User asks to make something long-term, cross-session, reusable, future sessions should remember an API / MCP / tool-use pattern, or uses equivalent Chinese phrases such as "寫入長期治理", "轉成長期機制", or "之後都要遵守".
|
|
13
|
-
- The task creates or materially changes Markdown governance artifacts, source-of-truth files, durable workflow docs, or durable artifacts that future agents may need to discover. Ordinary target-authority documents, drafts, and user-task deliverables do not load this pack solely because they are Markdown or generated.
|
|
14
|
-
|
|
15
|
-
## Rules
|
|
16
|
-
|
|
17
|
-
1. Locate the existing source of truth before adding a rule. Read the matching categories in `dev/RULE_PACKS.md`, their applicable packs, project supplements and required references first; then apply `Governance Write Boundary` below. A matching topic does not make official prose writable.
|
|
18
|
-
2. Prefer merge, replace, or registry rows over append-only rule growth, within the verified project-owned location. Change an existing project rule in place rather than duplicating it in another file or appending an override.
|
|
19
|
-
3. Keep public runtime rules generic; project-specific incidents belong in logs, runbooks, or project index.
|
|
20
|
-
4. Do not let development-only workspace rules enter public runtime.
|
|
21
|
-
5. Check complexity budget before adding default-core behavior.
|
|
22
|
-
6. Before creating durable workflow, runbook, or instruction files, first classify the knowledge type and verify whether an existing home can carry it without a new file: current state belongs in `dev/SESSION_HANDOFF.md`; trace evidence belongs in `dev/SESSION_LOG.md`; file / command / reference maps belong in `dev/PROJECT_INDEX.md`; sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`; reusable operating procedures belong in the relevant rule pack or registered reference. New runbooks are last resort only.
|
|
23
|
-
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 `
|
|
24
|
-
8. Before any pre-closeout handoff / log write for governance work, apply the core Persistence Gate explicitly. A concern that future agents may read stale handoff is not enough when the changed rule, spec, runbook, or document is itself the target authority; leave handoff lag expected unless checkpoint conditions are met. When the gate does select a checkpoint, write only the smallest current-state field or concise log entry and leave historical evidence sections byte-stable where practical.
|
|
25
|
-
9. For long-running projects, maintain `dev/PROJECT_DECISIONS.md`
|
|
26
|
-
10. 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.
|
|
27
|
-
11. Content-based trigger: long-term governance routing is content-based, not trigger-only. Even if the user does not use explicit governance-routing phrases, 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.
|
|
28
|
-
12. Mid-task changes to product goals, requirements, development checklists, acceptance rules, exclusions, priorities, or scope are task contract changes. Before writing them, check whether the same contract already lives in a spec, backlog, issue list, README, runbook, project index entry, or handoff section. Merge into the existing authoritative home, then leave only a pointer or current-state summary elsewhere.
|
|
29
|
-
13. New Markdown or generated documents are not automatically harmless. After creating or materially changing them, classify each artifact before completion: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary. Durable artifacts must be discoverable from `dev/PROJECT_INDEX.md` or intentionally tied to a registered sync / source-of-truth row. Temporary or one-time evidence must be labeled as such in the task record or closeout so future agents do not treat it as hidden current state.
|
|
30
|
-
14. Do not create a new document to hold a rule, requirement, checklist, or process if an existing authoritative document can carry it. Merge into the existing home or make the new document explicitly subordinate. If two files now carry the same durable instruction, resolve the duplicate by choosing one authoritative home and pointing the other to it.
|
|
31
|
-
|
|
32
|
-
## Governance Write Boundary
|
|
33
|
-
|
|
34
|
-
This is the single write-location contract for installed projects, not for authorized Kit source development. It guides agent edits; it cannot intercept arbitrary editor writes.
|
|
35
|
-
|
|
36
|
-
1. Classify the change before writing. Use the existing task category and normative owner; read the full relevant rule and its project supplements. A current task instruction is not automatically a durable rule. Do not create a new goal, acceptance threshold or balancing policy merely to reconcile your preferences with the user's request. Follow instruction priority; surface a material unresolved conflict instead of silently inventing an override.
|
|
37
|
-
2. Treat the `AGENTS.md` managed-core region and complete official `dev/rules/*` pack bodies as protected. Daily project edits must not insert, translate, reformat, reorder or remove their contents or delimiters. Verify the installed version's official content before identifying the boundary; a heading, marker or version row alone is not ownership proof. Formal upgrade or an explicitly scoped repair owns official changes. If local rules are already interleaved, preserve them and report the required bounded reconciliation; do not guess which lines to delete or bless the mixed body as official.
|
|
38
|
-
3. Reuse the matching pack's existing project supplement when it owns the rule. Otherwise place a short local rule after the entire verified official body under `## Project Rules`; preserve the official trailing newline. This heading labels the writable appendix, not the end of official ownership. For substantial or shared procedures, reuse a registered project reference; create a new reference only if no suitable owner exists. If `dev/USER_RULES.md` formally owns the rule, use its accepted update procedure rather than editing witnessed bytes or creating a competing copy. Always-needed project entry rules may live outside the managed core only after checking their existing owner.
|
|
39
|
-
4. Preserve project-state schemas separately: edit handoff fields, actual log entries, index data or registry rows in their existing writable sections; do not insert policy into template instructions or alter machine markers. Preserve official routing rows in `dev/RULE_PACKS.md`; add a project row only when a project reference needs a task trigger, naming both the relevant pack and reference. A same-pack appendix uses that pack's existing route. Do not add a route or load a pack merely for bare startup.
|
|
40
|
-
5. Before and after an edit touching core or pack files, compare the complete protected region against the verified input; every protected byte must remain unchanged. Use the installed-version CLI's read-only `upgrade --dry-run --root <project root>`
|
|
41
|
-
6. Read back the rule from its normal consumer path: task signal -> router -> relevant pack including the project supplement and required reference -> requested action. Verify its exact requirement, scope and precedence, and that unrelated packs stay unloaded. An indexed file that no applicable route reads is not connected. Evidence must show both correct application and preserved upgrade compatibility; a successful preview alone does not prove an AI followed the rule.
|
|
42
|
-
|
|
43
|
-
## Governance Bridge Workflow
|
|
44
|
-
|
|
45
|
-
Use this workflow when the user asks for governance bridge, connect this document to governance, asks to scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
|
|
46
|
-
|
|
47
|
-
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.
|
|
48
|
-
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.
|
|
49
|
-
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.
|
|
50
|
-
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.
|
|
51
|
-
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.
|
|
52
|
-
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.
|
|
53
|
-
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.
|
|
54
|
-
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.
|
|
55
|
-
|
|
56
|
-
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.
|
|
57
|
-
|
|
58
|
-
Output format:
|
|
59
|
-
|
|
60
|
-
- Status: bridged / partially bridged / unbridged / blocked.
|
|
61
|
-
- 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.
|
|
62
|
-
- Already bridged: list the governance links that are present.
|
|
63
|
-
- Gaps: list missing links and why they matter for the next agent.
|
|
64
|
-
- Not applicable: list skipped layers with a reason.
|
|
65
|
-
- Suggested patches: list exact files and sections to update.
|
|
66
|
-
- Manual decisions: list duplicates, naming choices, deletion, renaming, external sync, or ownership questions requiring user confirmation.
|
|
67
|
-
- Acceptance: give one concrete check that proves the bridge is complete.
|
|
68
|
-
|
|
69
|
-
## Generated Artifact Governance Workflow
|
|
70
|
-
|
|
71
|
-
Use this workflow whenever the current task creates or materially changes Markdown documents or other durable artifacts, even if the user did not explicitly ask for governance bridge.
|
|
72
|
-
|
|
73
|
-
This workflow is subordinate to the core task-first governance locality rule. Use it as a proportionate classification / routing check, not as permission to interrupt an explicit user task plan, start a repo-wide governance scan, or turn an ordinary user-task deliverable into governance work.
|
|
74
|
-
|
|
75
|
-
1. List the artifacts created or materially changed in this task.
|
|
76
|
-
2. Classify each artifact: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary.
|
|
77
|
-
3. For source-of-truth, reference, runbook, workflow, checklist, public document, and reusable generated output, update `dev/PROJECT_INDEX.md` so the file is discoverable with a role and read condition.
|
|
78
|
-
4. For artifacts that require future mirror, external index, publication, or repeated sync, update `dev/DOC_SYNC_REGISTRY.md` or record why no durable sync rule applies.
|
|
79
|
-
5. For one-time evidence, draft, or temporary files, record that classification in `dev/SESSION_LOG.md` or the task summary, and do not promote it to current handoff unless it affects the next action.
|
|
80
|
-
6. Search for duplicate source-of-truth risk before keeping a new document. If another file already owns the same rule, requirement, checklist, or process, merge into that file or make the new document explicitly subordinate.
|
|
81
|
-
7. Before claiming completion, explicitly confirm the artifacts created or materially changed in this task have been classified, indexed, synchronized, consolidated, or marked temporary through the steps above. Existing target-authority documents that only received a local content edit normally need read-back and task-specific validation, not a handoff / log write or a bundled doctor run. You may run the available project governance check and `agent-handoff-kit doctor` only for scoped Kit / typed registered-surface checks; doctor does not discover unregistered ordinary workspace files and cannot replace explicit changed-artifact review.
|
|
82
|
-
|
|
83
|
-
## Long-term Governance Routing
|
|
84
|
-
|
|
85
|
-
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.
|
|
86
|
-
|
|
87
|
-
1. Classify the knowledge before writing:
|
|
88
|
-
- 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.
|
|
89
|
-
- Current task state, recommended next action with reason, unresolved risk, or startup-needed fact -> `dev/SESSION_HANDOFF.md`.
|
|
90
|
-
- Chronological evidence or validation trace -> `dev/SESSION_LOG.md`.
|
|
91
|
-
- File maps, command maps, API reference locations, tool capability maps, and external source coordinates -> `dev/PROJECT_INDEX.md`.
|
|
92
|
-
- Sync obligations or external mirror duties -> `dev/DOC_SYNC_REGISTRY.md`.
|
|
93
|
-
- Durable decisions, architecture trade-offs, research-derived rationale, and long-term lessons -> `dev/PROJECT_DECISIONS.md`.
|
|
94
|
-
- Reusable procedures, recurring mistake prevention, API / MCP / tool-use rules -> the relevant rule pack, registered reference, or QA check.
|
|
95
|
-
- API / MCP / tool-use patterns -> project index / registered reference / integrations pack, depending on scope.
|
|
96
|
-
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.
|
|
97
|
-
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.
|
|
98
|
-
4. Add or update a QA check when the same failure class could recur and can be tested.
|
|
99
|
-
5. Repeat-failure escalation: when the same failure class recurs after an AI has already claimed a durable fix for that class, do not continue with another same-pattern patch as ordinary work. Limit the escalation to the affected domain: identify the authoritative owner, correct or remove the failed method there, add a counterexample or replay check that would have failed before the fix when feasible, and state the temporary constraint. If the failure recurs again after that root-fix validation, separate the change and validation roles where the runtime provides an independent reviewer, subagent, or fresh-context pass; when none is available, perform a fresh read-back pass against the replay check and mark independent review unavailable instead of blocking unrelated work. Restore normal flow as soon as the replay and review / read-back pass. Do not create a central penalty database, cross-project blacklist, permanent role split, or public rule carrying project-specific incident details.
|
|
100
|
-
6. Keep governance bridge wording reserved for document orphan prevention. Do not relabel non-file governance as "file connected to Agent Handoff Kit".
|
|
101
|
-
|
|
102
|
-
## Checks
|
|
103
|
-
|
|
104
|
-
- Verify affected files are indexed or intentionally installed templates.
|
|
105
|
-
- Check `dev/DOC_SYNC_REGISTRY.md` for governance, closeout/startup, and README sync rows.
|
|
106
|
-
- Confirm old overlapping wording was retired or marked legacy.
|
|
107
|
-
- Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
|
|
108
|
-
- Confirm every Markdown document or generated artifact created in this task is indexed, synced, consolidated, or explicitly classified as draft / temporary / one-time evidence.
|
|
109
|
-
- Confirm no new file has become a parallel source for an existing rule, requirement, checklist, or process.
|
|
110
|
-
- 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.
|
|
111
|
-
- 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.
|
|
112
|
-
- Confirm repeat-failure escalation, when triggered, is limited to the affected domain, tied to the authoritative owner, backed by a counterexample or replay check when feasible, and does not create a central penalty store, cross-project blacklist, or permanent role split.
|
|
113
|
-
- 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.
|
|
114
|
-
- For governance bridge work, run bounded searches for the target path/name and the relevant artifact class or sync-change type across the project index, sync registry, related workflows, and current rule owners. If the target is tied to generated outputs, also inspect the workflow or production guide that creates those outputs. Search evidence is a check, not a second source of truth.
|
|
115
|
-
- 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.
|
|
116
|
-
- 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
|
|
117
|
-
|
|
118
|
-
## Closeout
|
|
119
|
-
|
|
120
|
-
Record the changed rule home, reason, complexity impact, retired wording, and follow-up checks.
|
|
1
|
+
# Agent Governance Pack
|
|
2
|
+
|
|
3
|
+
## Scope
|
|
4
|
+
|
|
5
|
+
Use for governance rules, prompts, agent instructions, handoff systems, startup/closeout behavior, skills, and rule packs.
|
|
6
|
+
|
|
7
|
+
## Load When
|
|
8
|
+
|
|
9
|
+
- User asks to change AI behavior, project governance, prompts, handoff, startup, closeout, or tool-use rules.
|
|
10
|
+
- A change affects `AGENTS.md`, `dev/*`, rule packs, installer templates, or durable workflow docs.
|
|
11
|
+
- User asks to bridge governance, connect a document to governance, scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
|
|
12
|
+
- User asks to make something long-term, cross-session, reusable, future sessions should remember an API / MCP / tool-use pattern, or uses equivalent Chinese phrases such as "寫入長期治理", "轉成長期機制", or "之後都要遵守".
|
|
13
|
+
- The task creates or materially changes Markdown governance artifacts, source-of-truth files, durable workflow docs, or durable artifacts that future agents may need to discover. Ordinary target-authority documents, drafts, and user-task deliverables do not load this pack solely because they are Markdown or generated.
|
|
14
|
+
|
|
15
|
+
## Rules
|
|
16
|
+
|
|
17
|
+
1. Locate the existing source of truth before adding a rule. Read the matching categories in `dev/RULE_PACKS.md`, their applicable packs, project supplements and required references first; then apply `Governance Write Boundary` below. A matching topic does not make official prose writable.
|
|
18
|
+
2. Prefer merge, replace, or registry rows over append-only rule growth, within the verified project-owned location. Change an existing project rule in place rather than duplicating it in another file or appending an override.
|
|
19
|
+
3. Keep public runtime rules generic; project-specific incidents belong in logs, runbooks, or project index.
|
|
20
|
+
4. Do not let development-only workspace rules enter public runtime.
|
|
21
|
+
5. Check complexity budget before adding default-core behavior.
|
|
22
|
+
6. Before creating durable workflow, runbook, or instruction files, first classify the knowledge type and verify whether an existing home can carry it without a new file: current state belongs in `dev/SESSION_HANDOFF.md`; trace evidence belongs in `dev/SESSION_LOG.md`; file / command / reference maps belong in `dev/PROJECT_INDEX.md`; sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`; reusable operating procedures belong in the relevant rule pack or registered reference. New runbooks are last resort only.
|
|
23
|
+
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 installed `AGENTS.md` Persistence Gate decision; do not duplicate the gate thresholds in this pack.
|
|
24
|
+
8. Before any pre-closeout handoff / log write for governance work, apply the core Persistence Gate explicitly. A concern that future agents may read stale handoff is not enough when the changed rule, spec, runbook, or document is itself the target authority; leave handoff lag expected unless checkpoint conditions are met. When the gate does select a checkpoint, write only the smallest current-state field or concise log entry and leave historical evidence sections byte-stable where practical.
|
|
25
|
+
9. For long-running projects, maintain `dev/PROJECT_DECISIONS.md` under `dev/rules/closeout.md` `## Maintenance Trigger Check`: capture major decisions when they happen and run the short assessment at every closeout. Counts may prompt review, but do not force a historical sweep or create a no-op log record without an actual preservation, continuation, semantic, or project-specific requirement. Short single-task projects keep this as a no-op default; users are not expected to edit this file manually.
|
|
26
|
+
10. 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.
|
|
27
|
+
11. Content-based trigger: long-term governance routing is content-based, not trigger-only. Even if the user does not use explicit governance-routing phrases, 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.
|
|
28
|
+
12. Mid-task changes to product goals, requirements, development checklists, acceptance rules, exclusions, priorities, or scope are task contract changes. Before writing them, check whether the same contract already lives in a spec, backlog, issue list, README, runbook, project index entry, or handoff section. Merge into the existing authoritative home, then leave only a pointer or current-state summary elsewhere.
|
|
29
|
+
13. New Markdown or generated documents are not automatically harmless. After creating or materially changing them, classify each artifact before completion: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary. Durable artifacts must be discoverable from `dev/PROJECT_INDEX.md` or intentionally tied to a registered sync / source-of-truth row. Temporary or one-time evidence must be labeled as such in the task record or closeout so future agents do not treat it as hidden current state.
|
|
30
|
+
14. Do not create a new document to hold a rule, requirement, checklist, or process if an existing authoritative document can carry it. Merge into the existing home or make the new document explicitly subordinate. If two files now carry the same durable instruction, resolve the duplicate by choosing one authoritative home and pointing the other to it.
|
|
31
|
+
|
|
32
|
+
## Governance Write Boundary
|
|
33
|
+
|
|
34
|
+
This is the single write-location contract for installed projects, not for authorized Kit source development. It guides agent edits; it cannot intercept arbitrary editor writes.
|
|
35
|
+
|
|
36
|
+
1. Classify the change before writing. Use the existing task category and normative owner; read the full relevant rule and its project supplements. A current task instruction is not automatically a durable rule. Do not create a new goal, acceptance threshold or balancing policy merely to reconcile your preferences with the user's request. Follow instruction priority; surface a material unresolved conflict instead of silently inventing an override.
|
|
37
|
+
2. Treat the `AGENTS.md` managed-core region and complete official `dev/rules/*` pack bodies as protected. Daily project edits must not insert, translate, reformat, reorder or remove their contents or delimiters. Verify the installed version's official content before identifying the boundary; a heading, marker or version row alone is not ownership proof. Formal upgrade or an explicitly scoped repair owns official changes. If local rules are already interleaved, preserve them and report the required bounded reconciliation; do not guess which lines to delete or bless the mixed body as official.
|
|
38
|
+
3. Reuse the matching pack's existing project supplement when it owns the rule. Otherwise place a short local rule after the entire verified official body under `## Project Rules`; preserve the official trailing newline. This heading labels the writable appendix, not the end of official ownership. For substantial or shared procedures, reuse a registered project reference; create a new reference only if no suitable owner exists. If `dev/USER_RULES.md` formally owns the rule, use its accepted update procedure rather than editing witnessed bytes or creating a competing copy. Always-needed project entry rules may live outside the managed core only after checking their existing owner.
|
|
39
|
+
4. Preserve project-state schemas separately: edit handoff fields, actual log entries, index data or registry rows in their existing writable sections; do not insert policy into template instructions or alter machine markers. Preserve official routing rows in `dev/RULE_PACKS.md`; add a project row only when a project reference needs a task trigger, naming both the relevant pack and reference. A same-pack appendix uses that pack's existing route. Do not add a route or load a pack merely for bare startup.
|
|
40
|
+
5. Before and after an ordinary project-rule edit touching core or pack files, compare the complete protected region against the verified input; every protected byte must remain unchanged. For a formal upgrade or explicitly scoped repair, verify the approved official diff against the verified input and perform its required readback instead; preserve interleaved or unknown user content and do not guess which bytes to remove. Use the installed-version CLI's read-only `upgrade --dry-run --root <project root>` where that lifecycle applies; record the CLI version and any existing conflict separately. A pre-existing conflict requires reconciliation before claiming the write boundary is verified. A new conflict or a change outside the approved scope prevents completion; restore only your own scoped change from its verified input without discarding concurrent or pre-existing user work. For ordinary project-state edits, use schema/marker and local readback checks instead of an upgrade preview.
|
|
41
|
+
6. Read back the rule from its normal consumer path: task signal -> router -> relevant pack including the project supplement and required reference -> requested action. Verify its exact requirement, scope and precedence, and that unrelated packs stay unloaded. An indexed file that no applicable route reads is not connected. Evidence must show both correct application and preserved upgrade compatibility; a successful preview alone does not prove an AI followed the rule.
|
|
42
|
+
|
|
43
|
+
## Governance Bridge Workflow
|
|
44
|
+
|
|
45
|
+
Use this workflow when the user asks for governance bridge, connect this document to governance, asks to scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
|
|
46
|
+
|
|
47
|
+
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.
|
|
48
|
+
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.
|
|
49
|
+
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.
|
|
50
|
+
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.
|
|
51
|
+
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.
|
|
52
|
+
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.
|
|
53
|
+
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.
|
|
54
|
+
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.
|
|
55
|
+
|
|
56
|
+
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.
|
|
57
|
+
|
|
58
|
+
Output format:
|
|
59
|
+
|
|
60
|
+
- Status: bridged / partially bridged / unbridged / blocked.
|
|
61
|
+
- 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.
|
|
62
|
+
- Already bridged: list the governance links that are present.
|
|
63
|
+
- Gaps: list missing links and why they matter for the next agent.
|
|
64
|
+
- Not applicable: list skipped layers with a reason.
|
|
65
|
+
- Suggested patches: list exact files and sections to update.
|
|
66
|
+
- Manual decisions: list duplicates, naming choices, deletion, renaming, external sync, or ownership questions requiring user confirmation.
|
|
67
|
+
- Acceptance: give one concrete check that proves the bridge is complete.
|
|
68
|
+
|
|
69
|
+
## Generated Artifact Governance Workflow
|
|
70
|
+
|
|
71
|
+
Use this workflow whenever the current task creates or materially changes Markdown documents or other durable artifacts, even if the user did not explicitly ask for governance bridge.
|
|
72
|
+
|
|
73
|
+
This workflow is subordinate to the core task-first governance locality rule. Use it as a proportionate classification / routing check, not as permission to interrupt an explicit user task plan, start a repo-wide governance scan, or turn an ordinary user-task deliverable into governance work.
|
|
74
|
+
|
|
75
|
+
1. List the artifacts created or materially changed in this task.
|
|
76
|
+
2. Classify each artifact: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary.
|
|
77
|
+
3. For source-of-truth, reference, runbook, workflow, checklist, public document, and reusable generated output, update `dev/PROJECT_INDEX.md` so the file is discoverable with a role and read condition.
|
|
78
|
+
4. For artifacts that require future mirror, external index, publication, or repeated sync, update `dev/DOC_SYNC_REGISTRY.md` or record why no durable sync rule applies.
|
|
79
|
+
5. For one-time evidence, draft, or temporary files, record that classification in `dev/SESSION_LOG.md` or the task summary, and do not promote it to current handoff unless it affects the next action.
|
|
80
|
+
6. Search for duplicate source-of-truth risk before keeping a new document. If another file already owns the same rule, requirement, checklist, or process, merge into that file or make the new document explicitly subordinate.
|
|
81
|
+
7. Before claiming completion, explicitly confirm the artifacts created or materially changed in this task have been classified, indexed, synchronized, consolidated, or marked temporary through the steps above. Existing target-authority documents that only received a local content edit normally need read-back and task-specific validation, not a handoff / log write or a bundled doctor run. You may run the available project governance check and `agent-handoff-kit doctor` only for scoped Kit / typed registered-surface checks; doctor does not discover unregistered ordinary workspace files and cannot replace explicit changed-artifact review.
|
|
82
|
+
|
|
83
|
+
## Long-term Governance Routing
|
|
84
|
+
|
|
85
|
+
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.
|
|
86
|
+
|
|
87
|
+
1. Classify the knowledge before writing:
|
|
88
|
+
- 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.
|
|
89
|
+
- Current task state, recommended next action with reason, unresolved risk, or startup-needed fact -> `dev/SESSION_HANDOFF.md`.
|
|
90
|
+
- Chronological evidence or validation trace -> `dev/SESSION_LOG.md`.
|
|
91
|
+
- File maps, command maps, API reference locations, tool capability maps, and external source coordinates -> `dev/PROJECT_INDEX.md`.
|
|
92
|
+
- Sync obligations or external mirror duties -> `dev/DOC_SYNC_REGISTRY.md`.
|
|
93
|
+
- Durable decisions, architecture trade-offs, research-derived rationale, and long-term lessons -> `dev/PROJECT_DECISIONS.md`.
|
|
94
|
+
- Reusable procedures, recurring mistake prevention, API / MCP / tool-use rules -> the relevant rule pack, registered reference, or QA check.
|
|
95
|
+
- API / MCP / tool-use patterns -> project index / registered reference / integrations pack, depending on scope.
|
|
96
|
+
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.
|
|
97
|
+
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.
|
|
98
|
+
4. Add or update a QA check when the same failure class could recur and can be tested.
|
|
99
|
+
5. Repeat-failure escalation: when the same failure class recurs after an AI has already claimed a durable fix for that class, do not continue with another same-pattern patch as ordinary work. Limit the escalation to the affected domain: identify the authoritative owner, correct or remove the failed method there, add a counterexample or replay check that would have failed before the fix when feasible, and state the temporary constraint. If the failure recurs again after that root-fix validation, separate the change and validation roles where the runtime provides an independent reviewer, subagent, or fresh-context pass; when none is available, perform a fresh read-back pass against the replay check and mark independent review unavailable instead of blocking unrelated work. Restore normal flow as soon as the replay and review / read-back pass. Do not create a central penalty database, cross-project blacklist, permanent role split, or public rule carrying project-specific incident details.
|
|
100
|
+
6. Keep governance bridge wording reserved for document orphan prevention. Do not relabel non-file governance as "file connected to Agent Handoff Kit".
|
|
101
|
+
|
|
102
|
+
## Checks
|
|
103
|
+
|
|
104
|
+
- Verify affected files are indexed or intentionally installed templates.
|
|
105
|
+
- Check `dev/DOC_SYNC_REGISTRY.md` for governance, closeout/startup, and README sync rows.
|
|
106
|
+
- Confirm old overlapping wording was retired or marked legacy.
|
|
107
|
+
- Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
|
|
108
|
+
- Confirm every Markdown document or generated artifact created in this task is indexed, synced, consolidated, or explicitly classified as draft / temporary / one-time evidence.
|
|
109
|
+
- Confirm no new file has become a parallel source for an existing rule, requirement, checklist, or process.
|
|
110
|
+
- 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.
|
|
111
|
+
- 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.
|
|
112
|
+
- Confirm repeat-failure escalation, when triggered, is limited to the affected domain, tied to the authoritative owner, backed by a counterexample or replay check when feasible, and does not create a central penalty store, cross-project blacklist, or permanent role split.
|
|
113
|
+
- 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.
|
|
114
|
+
- For governance bridge work, run bounded searches for the target path/name and the relevant artifact class or sync-change type across the project index, sync registry, related workflows, and current rule owners. If the target is tied to generated outputs, also inspect the workflow or production guide that creates those outputs. Search evidence is a check, not a second source of truth.
|
|
115
|
+
- 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.
|
|
116
|
+
- 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 apply the closeout maintenance assessment. Record only actual maintenance or a current risk; do full work only for an actual preservation, continuation, semantic, or project-specific requirement. A count alone does not force a historical sweep or no-op record.
|
|
117
|
+
|
|
118
|
+
## Closeout
|
|
119
|
+
|
|
120
|
+
Record the changed rule home, reason, complexity impact, retired wording, and follow-up checks.
|