@adamchanadam/agent-handoff-kit 0.3.31 → 0.3.33
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 +7 -5
- package/bin/agent-handoff-kit.mjs +276 -74
- package/package.json +31 -20
- package/packs/agent-governance.md +17 -0
- package/packs/integrations.md +47 -27
- package/packs/knowledge.md +5 -5
- package/packs/onboarding.md +4 -4
- package/packs/safety.md +5 -5
- package/packs/writing.md +4 -0
- package/runtime-core/AGENTS.core.md +14 -9
- package/runtime-core/DOC_SYNC_REGISTRY.md +1 -0
- package/runtime-core/PROJECT_INDEX.md +13 -11
- package/runtime-core/SESSION_HANDOFF.md +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:目前版本為 `v0.3.
|
|
3
|
+
狀態:目前版本為 `v0.3.33`。這是早期可用版本,仍在持續完善中。
|
|
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">
|
|
@@ -44,7 +44,9 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
|
|
|
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
|
-
|
|
47
|
+
repo 內的 `scripts/`、`test-fixtures/`、`docs/qa/` 和部分設計文件,是維護者用來測試升級、安全合併和發佈品質的材料。普通用戶不需要閱讀,也不會被 npm 安裝到你的項目;npm package 只包含實際執行需要的核心檔案。
|
|
48
|
+
|
|
49
|
+
維護者請看 [`MAINTAINERS.md`](MAINTAINERS.md)。
|
|
48
50
|
|
|
49
51
|
## 🔎 它解決甚麼問題
|
|
50
52
|
|
|
@@ -145,7 +147,7 @@ AI 會處理檢查,不會把「檢查通過」誤當成已理解你的專案
|
|
|
145
147
|
| 寫文章 / README / 社交帖文 | 先確認讀者、目的、語氣和發布位置。 |
|
|
146
148
|
| 查資料 / 比較工具 | 分清已驗證事實、來源摘要和 AI 推論。 |
|
|
147
149
|
| 刪檔 / Git / 發佈 / npm | 高風險操作必須先說明影響,並等你確認。 |
|
|
148
|
-
| Notion / Google Drive 等外部工具 |
|
|
150
|
+
| Notion / Google Drive 等外部工具 | 先核對目前工具 schema 或官方文件;機密不寫入項目文件。 |
|
|
149
151
|
|
|
150
152
|
你只要用日常話說目的,例如「幫我改 README」、「幫我查這個工具是否適合」、「把這份文件接入 Agent Handoff Kit」。AI 會自己判斷要用哪些規則。
|
|
151
153
|
|
|
@@ -183,7 +185,7 @@ AI 應先判斷這條規則應放在哪裡:是一次性備忘、下次交接
|
|
|
183
185
|
|
|
184
186
|
- 禁止破壞性指令:例如 `rm -rf`、`git reset --hard`、強制推送、系統根路徑操作。
|
|
185
187
|
- 機密保護:`.env`、API key、token 不可印出、不可提交、不可上傳。
|
|
186
|
-
-
|
|
188
|
+
- 查證不猜:使用第三方服務、Connector、MCP、CLI、API 或 plugin API 前,先核對目前工具 schema、官方文件或有版本日期的本地 runbook;查不到就標示未核實。
|
|
187
189
|
- 權限不足就停手:檔案被鎖或沒有權限時,輸出手動操作清單,不嘗試繞過。
|
|
188
190
|
- 發佈需明確批准:建立版本標籤、GitHub Release、npm publish、部署或上傳,都不能因「準備好了」而自動執行。
|
|
189
191
|
|
|
@@ -198,7 +200,7 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
|
|
|
198
200
|
|
|
199
201
|
## ⚠️ 目前限制
|
|
200
202
|
|
|
201
|
-
- 目前版本為 `v0.3.
|
|
203
|
+
- 目前版本為 `v0.3.33`;正式安裝請以 npm registry `latest` 顯示為準。
|
|
202
204
|
- 這是早期可用版本,仍在持續完善中。
|
|
203
205
|
- 升級合併屬窄範圍策略,不是完整的複雜合併工具。
|
|
204
206
|
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
@@ -57,10 +57,11 @@ const requiredAnchors = [
|
|
|
57
57
|
"Start Agent Handoff",
|
|
58
58
|
"Ambiguous startup phrases",
|
|
59
59
|
"Reachable is not the same as ingested",
|
|
60
|
-
"Do not treat unread sources as absent",
|
|
61
|
-
"Task contract changes are durable facts",
|
|
62
|
-
"External Impact Note",
|
|
63
|
-
|
|
60
|
+
"Do not treat unread sources as absent",
|
|
61
|
+
"Task contract changes are durable facts",
|
|
62
|
+
"External Impact Note",
|
|
63
|
+
"ARTIFACT GOVERNANCE GATE",
|
|
64
|
+
// R-030 v0.3.0+: forces managed-core merge on v0.2.x → v0.3.0 upgrade to propagate
|
|
64
65
|
// startup availability probe + integrations pack reference + credential separation discipline.
|
|
65
66
|
"startup availability probe",
|
|
66
67
|
"dev/rules/integrations.md",
|
|
@@ -87,9 +88,10 @@ const requiredAnchors = [
|
|
|
87
88
|
"Use the same display version rule as startup",
|
|
88
89
|
"Never print the literal placeholder `v<version>`",
|
|
89
90
|
"next-session startup entry",
|
|
90
|
-
"State Reconciliation Check",
|
|
91
|
-
"handoff lifecycle consistency",
|
|
92
|
-
"
|
|
91
|
+
"State Reconciliation Check",
|
|
92
|
+
"handoff lifecycle consistency",
|
|
93
|
+
"A final chat summary without updated handoff/log/prompt evidence is not closeout",
|
|
94
|
+
"Do not append a new state snapshot",
|
|
93
95
|
"START_NEXT_SESSION_PROMPT.txt"
|
|
94
96
|
]
|
|
95
97
|
},
|
|
@@ -231,12 +233,16 @@ const requiredAnchors = [
|
|
|
231
233
|
"Integrations Pack",
|
|
232
234
|
"Connectors",
|
|
233
235
|
"MCPs",
|
|
234
|
-
"Plugins",
|
|
235
|
-
"Skills",
|
|
236
|
-
"機密分離原則",
|
|
237
|
-
"
|
|
238
|
-
"
|
|
239
|
-
"
|
|
236
|
+
"Plugins",
|
|
237
|
+
"Skills",
|
|
238
|
+
"機密分離原則",
|
|
239
|
+
"External Tool Usage Verification Gate",
|
|
240
|
+
"do not invent",
|
|
241
|
+
"input schema",
|
|
242
|
+
"official documentation",
|
|
243
|
+
"Source-of-truth Architecture",
|
|
244
|
+
"Cross-session Lifecycle",
|
|
245
|
+
"Connector-first default",
|
|
240
246
|
"Anti-pattern"
|
|
241
247
|
]
|
|
242
248
|
}
|
|
@@ -346,8 +352,8 @@ const schemaChecks = [
|
|
|
346
352
|
tableHeader("Check", "Command", "Run before", "Last verified"),
|
|
347
353
|
tableHeader("Change type", "Likely files", "Required checks"),
|
|
348
354
|
// R-030 v0.3.0+: Installed Integrations subsection table headers
|
|
349
|
-
tableHeader("Tool", "Project Usage", "Access Scope", "Specific Instance", "Credential
|
|
350
|
-
tableHeader("Server", "Source", "Project Usage", "Credential
|
|
355
|
+
tableHeader("Tool", "Project Usage", "Access Scope", "Specific Instance", "Credential Reference(no value)", "Declared", "Last Verified"),
|
|
356
|
+
tableHeader("Server", "Source", "Project Usage", "Credential Reference(no value)", "Declared", "Last Verified"),
|
|
351
357
|
tableHeader("Name", "Bundle Content(Skills + MCP + hooks)", "When Triggered", "Last Verified"),
|
|
352
358
|
tableHeader("Name", "Source", "When Triggered", "Last Verified"),
|
|
353
359
|
tableHeader("Layer", "Surface(具體 instance)", "Role", "Write Direction")
|
|
@@ -797,10 +803,10 @@ async function runDoctor(root, version, options = {}) {
|
|
|
797
803
|
const temperatureResult = await checkHandoffTemperatureBoundary(root);
|
|
798
804
|
console.log(`\nhandoff temperature boundary checks: ${temperatureResult.checked}`);
|
|
799
805
|
console.log(`${temperatureResult.ok ? "ok" : "missing"} dev/SESSION_HANDOFF.md / START_NEXT_SESSION_PROMPT.txt (current-state evidence boundary)`);
|
|
800
|
-
if (!temperatureResult.ok) {
|
|
801
|
-
for (const finding of temperatureResult.findings) {
|
|
802
|
-
console.log(` missing: ${finding}`);
|
|
803
|
-
}
|
|
806
|
+
if (!temperatureResult.ok) {
|
|
807
|
+
for (const finding of temperatureResult.findings) {
|
|
808
|
+
console.log(` missing: ${finding}`);
|
|
809
|
+
}
|
|
804
810
|
printDoctorSummary(version, root, "needs-fix", {
|
|
805
811
|
checked: rows.length + anchorRows.length + schemaRows.length + researchTraceResult.checked + temperatureResult.checked,
|
|
806
812
|
failedKind: "handoff temperature boundary checks",
|
|
@@ -808,12 +814,29 @@ async function runDoctor(root, version, options = {}) {
|
|
|
808
814
|
nextStep: "把一次性驗收證據、舊版本狀態、source token 或 Evidence chain 從 Durable Anchors / Next Priorities / opening message 移回 SESSION_LOG、PROJECT_INDEX 或 PROJECT_DECISIONS。"
|
|
809
815
|
});
|
|
810
816
|
process.exitCode = 1;
|
|
811
|
-
return "failed";
|
|
812
|
-
}
|
|
813
|
-
|
|
814
|
-
const
|
|
815
|
-
|
|
816
|
-
|
|
817
|
+
return "failed";
|
|
818
|
+
}
|
|
819
|
+
|
|
820
|
+
const artifactResult = await checkGeneratedMarkdownGovernance(root);
|
|
821
|
+
console.log(`\ngenerated markdown governance checks: ${artifactResult.checked}`);
|
|
822
|
+
console.log(`${artifactResult.ok ? "ok" : "missing"} dev/PROJECT_INDEX.md (generated Markdown / durable artifact registration)`);
|
|
823
|
+
if (!artifactResult.ok) {
|
|
824
|
+
for (const finding of artifactResult.findings) {
|
|
825
|
+
console.log(` missing: ${finding}`);
|
|
826
|
+
}
|
|
827
|
+
printDoctorSummary(version, root, "needs-fix", {
|
|
828
|
+
checked: rows.length + anchorRows.length + schemaRows.length + researchTraceResult.checked + temperatureResult.checked + artifactResult.checked,
|
|
829
|
+
failedKind: "generated markdown governance checks",
|
|
830
|
+
failedCount: artifactResult.findings.length,
|
|
831
|
+
nextStep: "把新生成或新修改的 Markdown / durable artifact 登記到 dev/PROJECT_INDEX.md,或在 SESSION_LOG / task summary 明確標成 draft、temporary 或 one-time evidence;如內容重複,先合併到單一真源。"
|
|
832
|
+
});
|
|
833
|
+
process.exitCode = 1;
|
|
834
|
+
return "failed";
|
|
835
|
+
}
|
|
836
|
+
|
|
837
|
+
const mirrorRows = await checkPromptMirror(root);
|
|
838
|
+
const mirrorBlockingFailures = mirrorRows.filter((row) => !row.ok && row.reason !== "convenience copy differs from dev/SESSION_HANDOFF.md");
|
|
839
|
+
const mirrorWarnings = mirrorRows.filter((row) => !row.ok && row.reason === "convenience copy differs from dev/SESSION_HANDOFF.md");
|
|
817
840
|
console.log(`\nprompt mirror checks: ${mirrorRows.length}`);
|
|
818
841
|
for (const row of mirrorRows) {
|
|
819
842
|
const status = row.ok ? "ok" : row.reason === "convenience copy differs from dev/SESSION_HANDOFF.md" ? "warn" : "missing";
|
|
@@ -869,7 +892,7 @@ async function runDoctor(root, version, options = {}) {
|
|
|
869
892
|
|
|
870
893
|
const overallHealthy = credentialResult.ok;
|
|
871
894
|
printDoctorSummary(version, root, overallHealthy ? "healthy" : "needs-attention", {
|
|
872
|
-
|
|
895
|
+
checked: rows.length + anchorRows.length + schemaRows.length + researchTraceResult.checked + temperatureResult.checked + artifactResult.checked + mirrorRows.length + 2,
|
|
873
896
|
failedKind: !credentialResult.ok ? "credential leak" : null,
|
|
874
897
|
failedCount: !credentialResult.ok ? credentialResult.findings.length : 0,
|
|
875
898
|
warningKind: mirrorWarnings.length > 0 ? "prompt mirror warning" : null,
|
|
@@ -883,7 +906,7 @@ async function runDoctor(root, version, options = {}) {
|
|
|
883
906
|
return overallHealthy ? "passed" : "failed";
|
|
884
907
|
}
|
|
885
908
|
|
|
886
|
-
async function checkResearchDecisionTrace(root) {
|
|
909
|
+
async function checkResearchDecisionTrace(root) {
|
|
887
910
|
const decisionsPath = path.join(root, "dev/PROJECT_DECISIONS.md");
|
|
888
911
|
const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
|
|
889
912
|
let decisionsText = "";
|
|
@@ -916,12 +939,111 @@ async function checkResearchDecisionTrace(root) {
|
|
|
916
939
|
}
|
|
917
940
|
});
|
|
918
941
|
|
|
919
|
-
return { ok: findings.length === 0, checked: 1, findings };
|
|
920
|
-
}
|
|
921
|
-
|
|
922
|
-
function
|
|
923
|
-
|
|
924
|
-
|
|
942
|
+
return { ok: findings.length === 0, checked: 1, findings };
|
|
943
|
+
}
|
|
944
|
+
|
|
945
|
+
async function checkGeneratedMarkdownGovernance(root) {
|
|
946
|
+
let indexText = "";
|
|
947
|
+
let logText = "";
|
|
948
|
+
let handoffText = "";
|
|
949
|
+
try {
|
|
950
|
+
indexText = await readFile(path.join(root, "dev/PROJECT_INDEX.md"), "utf8");
|
|
951
|
+
} catch {
|
|
952
|
+
return { ok: false, checked: 1, findings: ["dev/PROJECT_INDEX.md unreadable; cannot verify generated Markdown governance"] };
|
|
953
|
+
}
|
|
954
|
+
try {
|
|
955
|
+
logText = await readFile(path.join(root, "dev/SESSION_LOG.md"), "utf8");
|
|
956
|
+
} catch {
|
|
957
|
+
logText = "";
|
|
958
|
+
}
|
|
959
|
+
try {
|
|
960
|
+
handoffText = await readFile(path.join(root, "dev/SESSION_HANDOFF.md"), "utf8");
|
|
961
|
+
} catch {
|
|
962
|
+
handoffText = "";
|
|
963
|
+
}
|
|
964
|
+
|
|
965
|
+
const markdownFiles = await listMarkdownFiles(root);
|
|
966
|
+
const findings = [];
|
|
967
|
+
for (const rel of markdownFiles) {
|
|
968
|
+
if (!isGeneratedArtifactCandidate(rel)) continue;
|
|
969
|
+
if (isArtifactGoverned(rel, { indexText, logText, handoffText })) continue;
|
|
970
|
+
findings.push(`${rel} is not registered in dev/PROJECT_INDEX.md and is not explicitly classified as draft / temporary / one-time evidence`);
|
|
971
|
+
}
|
|
972
|
+
|
|
973
|
+
return { ok: findings.length === 0, checked: 1, findings };
|
|
974
|
+
}
|
|
975
|
+
|
|
976
|
+
async function listMarkdownFiles(root) {
|
|
977
|
+
const results = [];
|
|
978
|
+
async function walk(dir) {
|
|
979
|
+
let entries = [];
|
|
980
|
+
try {
|
|
981
|
+
entries = await readdir(dir, { withFileTypes: true });
|
|
982
|
+
} catch {
|
|
983
|
+
return;
|
|
984
|
+
}
|
|
985
|
+
for (const entry of entries) {
|
|
986
|
+
if (entry.name === ".git" || entry.name === "node_modules") continue;
|
|
987
|
+
const full = path.join(dir, entry.name);
|
|
988
|
+
if (entry.isDirectory()) {
|
|
989
|
+
await walk(full);
|
|
990
|
+
continue;
|
|
991
|
+
}
|
|
992
|
+
if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".md")) continue;
|
|
993
|
+
results.push(path.relative(root, full).split(path.sep).join("/"));
|
|
994
|
+
}
|
|
995
|
+
}
|
|
996
|
+
await walk(root);
|
|
997
|
+
return results.sort();
|
|
998
|
+
}
|
|
999
|
+
|
|
1000
|
+
function isGeneratedArtifactCandidate(rel) {
|
|
1001
|
+
const normalized = rel.replaceAll("\\", "/");
|
|
1002
|
+
const lower = normalized.toLowerCase();
|
|
1003
|
+
const kitManaged = new Set([
|
|
1004
|
+
"agents.md",
|
|
1005
|
+
"claude.md",
|
|
1006
|
+
"gemini.md",
|
|
1007
|
+
"readme.md",
|
|
1008
|
+
"dev/session_handoff.md",
|
|
1009
|
+
"dev/session_log.md",
|
|
1010
|
+
"dev/project_index.md",
|
|
1011
|
+
"dev/doc_sync_registry.md",
|
|
1012
|
+
"dev/rule_packs.md",
|
|
1013
|
+
"dev/project_decisions.md"
|
|
1014
|
+
]);
|
|
1015
|
+
if (kitManaged.has(lower)) return false;
|
|
1016
|
+
if (lower.startsWith("dev/rules/")) return false;
|
|
1017
|
+
if (lower.startsWith("dev/governance_migrations/")) return false;
|
|
1018
|
+
if (lower.startsWith("dev/session_log_archive/")) return false;
|
|
1019
|
+
if (lower.startsWith("docs/")) return true;
|
|
1020
|
+
if (lower.startsWith("outputs/")) return true;
|
|
1021
|
+
if (lower.startsWith("output/")) return true;
|
|
1022
|
+
if (lower.startsWith("research/")) return true;
|
|
1023
|
+
if (lower.startsWith("references/")) return true;
|
|
1024
|
+
if (lower.startsWith("reference/")) return true;
|
|
1025
|
+
if (lower.startsWith("runbooks/")) return true;
|
|
1026
|
+
if (lower.startsWith("specs/")) return true;
|
|
1027
|
+
if (lower.startsWith("requirements/")) return true;
|
|
1028
|
+
return !normalized.includes("/");
|
|
1029
|
+
}
|
|
1030
|
+
|
|
1031
|
+
function isArtifactGoverned(rel, { indexText, logText, handoffText }) {
|
|
1032
|
+
const normalized = rel.replaceAll("\\", "/");
|
|
1033
|
+
if (indexText.includes(normalized)) return true;
|
|
1034
|
+
const escaped = normalized.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
1035
|
+
const labels = "(draft|temporary|one-time evidence|non-authoritative|not source of truth|草稿|臨時|暫存|一次性|非真源|非權威)";
|
|
1036
|
+
const afterPath = new RegExp(`${escaped}[\\s\\S]{0,240}${labels}`, "i");
|
|
1037
|
+
const beforePath = new RegExp(`${labels}[\\s\\S]{0,240}${escaped}`, "i");
|
|
1038
|
+
return afterPath.test(logText)
|
|
1039
|
+
|| beforePath.test(logText)
|
|
1040
|
+
|| afterPath.test(handoffText)
|
|
1041
|
+
|| beforePath.test(handoffText);
|
|
1042
|
+
}
|
|
1043
|
+
|
|
1044
|
+
function stripFencedCodeBlocks(text) {
|
|
1045
|
+
return text.replace(/```[\s\S]*?```/g, "");
|
|
1046
|
+
}
|
|
925
1047
|
|
|
926
1048
|
function markdownListBlocks(text) {
|
|
927
1049
|
const blocks = [];
|
|
@@ -1182,7 +1304,7 @@ function printDoctorSummary(version, root, mode, details) {
|
|
|
1182
1304
|
}
|
|
1183
1305
|
} else {
|
|
1184
1306
|
console.log(`status: failed (${details.failedCount} ${details.failedKind} failed)`);
|
|
1185
|
-
console.log(`⚠️ 檢查未通過:${details.failedKind === "missing files" ? "有必要檔案不存在。" : details.failedKind === "anchor checks" ? "有檔案存在,但內容缺少必要段落。" : details.failedKind === "schema checks" ? "交接或索引文件結構不完整。" : details.failedKind === "research decision trace checks" ? "研究導向決策缺少可追溯來源鏈。" : details.failedKind === "handoff temperature boundary checks" ? "當前交接內容混入一次性或歷史證據。" : "下次開工提示副本與 handoff 真源不同。"}`);
|
|
1307
|
+
console.log(`⚠️ 檢查未通過:${details.failedKind === "missing files" ? "有必要檔案不存在。" : details.failedKind === "anchor checks" ? "有檔案存在,但內容缺少必要段落。" : details.failedKind === "schema checks" ? "交接或索引文件結構不完整。" : details.failedKind === "research decision trace checks" ? "研究導向決策缺少可追溯來源鏈。" : details.failedKind === "handoff temperature boundary checks" ? "當前交接內容混入一次性或歷史證據。" : details.failedKind === "generated markdown governance checks" ? "有 Markdown 或 durable artifact 未完成入庫、同步或臨時分類。" : "下次開工提示副本與 handoff 真源不同。"}`);
|
|
1186
1308
|
}
|
|
1187
1309
|
console.log("");
|
|
1188
1310
|
console.log(`📦 版本:v${version}`);
|
|
@@ -1621,20 +1743,35 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
1621
1743
|
// ## Local QC Commands on upgrade if missing. NON-DESTRUCTIVE: existing ## External Sources content
|
|
1622
1744
|
// is fully preserved (including any user-filled rows). User can later manually add the `via` column
|
|
1623
1745
|
// to External Sources rows (or AI can guide that incremental migration during a later session).
|
|
1624
|
-
if (targetRel === "dev/PROJECT_INDEX.md" && command === "upgrade" && !targetText.includes("## Installed Integrations")) {
|
|
1625
|
-
// Extract just the ## Installed Integrations block from source (not touching External Sources).
|
|
1626
|
-
const sourceInstalledMatch = sourceText.match(/(## Installed Integrations[\s\S]*?)(?=## Local QC Commands)/);
|
|
1627
|
-
if (sourceInstalledMatch && targetText.includes("## Local QC Commands")) {
|
|
1746
|
+
if (targetRel === "dev/PROJECT_INDEX.md" && command === "upgrade" && !targetText.includes("## Installed Integrations")) {
|
|
1747
|
+
// Extract just the ## Installed Integrations block from source (not touching External Sources).
|
|
1748
|
+
const sourceInstalledMatch = sourceText.match(/(## Installed Integrations[\s\S]*?)(?=## Local QC Commands)/);
|
|
1749
|
+
if (sourceInstalledMatch && targetText.includes("## Local QC Commands")) {
|
|
1628
1750
|
const installedBlock = sourceInstalledMatch[1];
|
|
1629
1751
|
return {
|
|
1630
1752
|
...base,
|
|
1631
1753
|
action: "merge",
|
|
1632
1754
|
reason: "insert ## Installed Integrations section template before ## Local QC Commands (R-030 Integration governance migration; existing External Sources content preserved non-destructively)",
|
|
1633
1755
|
mergedText: targetText.replace("## Local QC Commands", installedBlock + "## Local QC Commands")
|
|
1634
|
-
};
|
|
1635
|
-
}
|
|
1636
|
-
}
|
|
1637
|
-
|
|
1756
|
+
};
|
|
1757
|
+
}
|
|
1758
|
+
}
|
|
1759
|
+
if (targetRel === "dev/PROJECT_INDEX.md" && command === "upgrade" && (
|
|
1760
|
+
targetText.includes("Credential Location")
|
|
1761
|
+
|| targetText.includes("Claude Code MCP config + env var")
|
|
1762
|
+
|| targetText.includes("Credential 應由 AI 工具自身 secure storage 管理(譬如 Claude Desktop Extensions")
|
|
1763
|
+
)) {
|
|
1764
|
+
const mergedProjectIndex = mergeProjectIndexCredentialReferences(targetText);
|
|
1765
|
+
if (mergedProjectIndex !== targetText) {
|
|
1766
|
+
return {
|
|
1767
|
+
...base,
|
|
1768
|
+
action: "merge",
|
|
1769
|
+
reason: "update PROJECT_INDEX credential reference wording without changing user integration rows",
|
|
1770
|
+
mergedText: mergedProjectIndex
|
|
1771
|
+
};
|
|
1772
|
+
}
|
|
1773
|
+
}
|
|
1774
|
+
// R-030 v0.3.0+: dev/rules/onboarding.md gets ### Scenario F block auto-inserted before
|
|
1638
1775
|
// ## Cross-reference to guide.html on upgrade if missing. NON-DESTRUCTIVE: existing Scenarios A-E
|
|
1639
1776
|
// content and any user customization preserved. Step 1 micro-question additions to Scenarios A-E
|
|
1640
1777
|
// are NOT auto-migrated (user-customizable inline sample wording, not anchor-enforced); users get
|
|
@@ -1982,10 +2119,10 @@ function onboardingAnchorPlacement(snippet, text) {
|
|
|
1982
2119
|
return true;
|
|
1983
2120
|
}
|
|
1984
2121
|
|
|
1985
|
-
function integrationsAnchorPlacement(snippet, text) {
|
|
1986
|
-
if (snippet === "機密分離原則" || snippet === "Source-of-truth Architecture" || snippet === "Cross-session Lifecycle") {
|
|
1987
|
-
return snippetAppearsBetweenHeadings(text, snippet, "## Discipline", "## Rules");
|
|
1988
|
-
}
|
|
2122
|
+
function integrationsAnchorPlacement(snippet, text) {
|
|
2123
|
+
if (snippet === "機密分離原則" || snippet === "External Tool Usage Verification Gate" || snippet === "do not invent" || snippet === "input schema" || snippet === "official documentation" || snippet === "Source-of-truth Architecture" || snippet === "Cross-session Lifecycle") {
|
|
2124
|
+
return snippetAppearsBetweenHeadings(text, snippet, "## Discipline", "## Rules");
|
|
2125
|
+
}
|
|
1989
2126
|
if (snippet === "Connector-first default") {
|
|
1990
2127
|
return snippetAppearsBetweenHeadings(text, snippet, "## Rules", "## Checks");
|
|
1991
2128
|
}
|
|
@@ -2056,14 +2193,14 @@ const semanticAnchorRepairStrategies = {
|
|
|
2056
2193
|
mergedText: mergedSafety
|
|
2057
2194
|
} : null;
|
|
2058
2195
|
},
|
|
2059
|
-
"dev/rules/integrations.md": (targetText, sourceText, missing) => {
|
|
2060
|
-
const mergedIntegrations =
|
|
2061
|
-
return mergedIntegrations ? {
|
|
2062
|
-
action: "merge",
|
|
2063
|
-
reason: "restore integrations credential
|
|
2064
|
-
mergedText: mergedIntegrations
|
|
2065
|
-
} : null;
|
|
2066
|
-
}
|
|
2196
|
+
"dev/rules/integrations.md": (targetText, sourceText, missing) => {
|
|
2197
|
+
const mergedIntegrations = mergeIntegrationsSectionsByMissingAnchors(targetText, sourceText, missing);
|
|
2198
|
+
return mergedIntegrations ? {
|
|
2199
|
+
action: "merge",
|
|
2200
|
+
reason: "restore integrations verification and credential sections in semantic position",
|
|
2201
|
+
mergedText: mergedIntegrations
|
|
2202
|
+
} : null;
|
|
2203
|
+
}
|
|
2067
2204
|
};
|
|
2068
2205
|
|
|
2069
2206
|
function mergeMissingRequiredAnchorsSemantically(targetRel, targetText, sourceText) {
|
|
@@ -2111,10 +2248,10 @@ function mergeProjectDecisionsPreamble(targetText, sourceText, missing) {
|
|
|
2111
2248
|
return insertSourcePreambleBeforeHeading(targetText, sourceText, "## Evolution Timeline");
|
|
2112
2249
|
}
|
|
2113
2250
|
|
|
2114
|
-
function mergeProjectIndexTemplateVersionRow(targetText, sourceText) {
|
|
2115
|
-
if (projectIndexTemplateVersion(targetText)) return targetText;
|
|
2116
|
-
const sourceRow = sourceText.match(/^\| Agent Handoff Kit template version \| [\d.]+ \| [^|\n]+ \|$/m)?.[0];
|
|
2117
|
-
if (!sourceRow) return null;
|
|
2251
|
+
function mergeProjectIndexTemplateVersionRow(targetText, sourceText) {
|
|
2252
|
+
if (projectIndexTemplateVersion(targetText)) return targetText;
|
|
2253
|
+
const sourceRow = sourceText.match(/^\| Agent Handoff Kit template version \| [\d.]+ \| [^|\n]+ \|$/m)?.[0];
|
|
2254
|
+
if (!sourceRow) return null;
|
|
2118
2255
|
const lines = targetText.split(/\r?\n/);
|
|
2119
2256
|
const stackIndex = lines.findIndex((line) => line.trim() === "## Stack");
|
|
2120
2257
|
if (stackIndex < 0) return null;
|
|
@@ -2122,11 +2259,31 @@ function mergeProjectIndexTemplateVersionRow(targetText, sourceText) {
|
|
|
2122
2259
|
if (tableHeaderIndex < 0) return null;
|
|
2123
2260
|
const separatorIndex = tableHeaderIndex + 1;
|
|
2124
2261
|
if (!lines[separatorIndex]?.startsWith("|---")) return null;
|
|
2125
|
-
lines.splice(separatorIndex + 1, 0, sourceRow);
|
|
2126
|
-
return lines.join("\n");
|
|
2127
|
-
}
|
|
2128
|
-
|
|
2129
|
-
function
|
|
2262
|
+
lines.splice(separatorIndex + 1, 0, sourceRow);
|
|
2263
|
+
return lines.join("\n");
|
|
2264
|
+
}
|
|
2265
|
+
|
|
2266
|
+
function mergeProjectIndexCredentialReferences(targetText) {
|
|
2267
|
+
return targetText
|
|
2268
|
+
.replace(
|
|
2269
|
+
"Credential 應由 AI 工具自身 secure storage 管理(譬如 Claude Desktop Extensions 嘅 OS Keychain / Claude Code MCP config)。",
|
|
2270
|
+
"Credential 應由 AI 工具自身 secure storage / OS credential store / tool config / user-managed secret store 管理;若使用 env,只可記錄 env var name,不可讀取、貼出或保存 value。"
|
|
2271
|
+
)
|
|
2272
|
+
.replaceAll(
|
|
2273
|
+
"Credential Location",
|
|
2274
|
+
"Credential Reference(no value)"
|
|
2275
|
+
)
|
|
2276
|
+
.replace(
|
|
2277
|
+
"`Claude Desktop Extensions`",
|
|
2278
|
+
"`AI tool secure storage` / `OS credential store`"
|
|
2279
|
+
)
|
|
2280
|
+
.replace(
|
|
2281
|
+
"`Claude Code MCP config + env var`",
|
|
2282
|
+
"`tool config + env var name only` / `user-managed secret store`"
|
|
2283
|
+
);
|
|
2284
|
+
}
|
|
2285
|
+
|
|
2286
|
+
function mergeSafetyRulesByMissingAnchors(targetText, sourceText, missing) {
|
|
2130
2287
|
if (!hasTrustedSafetyPackShape(targetText)) return null;
|
|
2131
2288
|
const targetBounds = sectionBounds(targetText, "## Rules", "## Checks");
|
|
2132
2289
|
const sourceBounds = sectionBounds(sourceText, "## Rules", "## Checks");
|
|
@@ -2162,17 +2319,62 @@ function mergeSafetyRulesByMissingAnchors(targetText, sourceText, missing) {
|
|
|
2162
2319
|
return changed ? targetLines.join("\n") : targetText;
|
|
2163
2320
|
}
|
|
2164
2321
|
|
|
2165
|
-
function
|
|
2166
|
-
|
|
2167
|
-
|
|
2168
|
-
|
|
2169
|
-
|
|
2170
|
-
|
|
2171
|
-
|
|
2172
|
-
|
|
2173
|
-
|
|
2174
|
-
|
|
2175
|
-
|
|
2322
|
+
function mergeIntegrationsSectionsByMissingAnchors(targetText, sourceText, missing) {
|
|
2323
|
+
let merged = targetText;
|
|
2324
|
+
let changed = false;
|
|
2325
|
+
|
|
2326
|
+
if (missing.some((snippet) => snippet === "機密分離原則")) {
|
|
2327
|
+
const withCredential = replaceSectionByHeadingWithinBounds(
|
|
2328
|
+
merged,
|
|
2329
|
+
sourceText,
|
|
2330
|
+
/^### 1\. (機密分離原則|credential-separation anchor removed from this stale local copy)/m,
|
|
2331
|
+
/^### 2\. /m,
|
|
2332
|
+
"## Discipline",
|
|
2333
|
+
"## Rules"
|
|
2334
|
+
);
|
|
2335
|
+
if (!withCredential) return null;
|
|
2336
|
+
merged = withCredential;
|
|
2337
|
+
changed = true;
|
|
2338
|
+
}
|
|
2339
|
+
|
|
2340
|
+
if (missing.some((snippet) => snippet === "External Tool Usage Verification Gate" || snippet === "do not invent" || snippet === "input schema" || snippet === "official documentation")) {
|
|
2341
|
+
const withVerificationGate = mergeIntegrationsVerificationGateSection(merged, sourceText);
|
|
2342
|
+
if (!withVerificationGate) return null;
|
|
2343
|
+
merged = withVerificationGate;
|
|
2344
|
+
changed = true;
|
|
2345
|
+
}
|
|
2346
|
+
|
|
2347
|
+
return changed ? merged : null;
|
|
2348
|
+
}
|
|
2349
|
+
|
|
2350
|
+
function mergeIntegrationsVerificationGateSection(targetText, sourceText) {
|
|
2351
|
+
if (countText(targetText, "## Discipline") !== 1 || countText(targetText, "## Rules") !== 1) return null;
|
|
2352
|
+
const targetBounds = textSectionBounds(targetText, "## Discipline", "## Rules");
|
|
2353
|
+
const sourceBounds = textSectionBounds(sourceText, "## Discipline", "## Rules");
|
|
2354
|
+
if (!targetBounds || !sourceBounds) return null;
|
|
2355
|
+
|
|
2356
|
+
const boundedTarget = targetText.slice(targetBounds.start, targetBounds.end);
|
|
2357
|
+
const boundedSource = sourceText.slice(sourceBounds.start, sourceBounds.end);
|
|
2358
|
+
const sourceSection = extractSection(boundedSource, /^### 2\. External Tool Usage Verification Gate/m, /^### 3\. /m);
|
|
2359
|
+
if (!sourceSection) return null;
|
|
2360
|
+
|
|
2361
|
+
const existingTargetSection = extractSection(boundedTarget, /^### 2\. External Tool Usage Verification Gate/m, /^### 3\. /m);
|
|
2362
|
+
if (existingTargetSection) {
|
|
2363
|
+
return `${targetText.slice(0, targetBounds.start + existingTargetSection.start)}${sourceSection.text}${targetText.slice(targetBounds.start + existingTargetSection.end)}`;
|
|
2364
|
+
}
|
|
2365
|
+
|
|
2366
|
+
const oldFourTypesHeading = /^### 2\. 四類整合嘅紀律差異/m.exec(boundedTarget);
|
|
2367
|
+
if (oldFourTypesHeading) {
|
|
2368
|
+
return `${targetText.slice(0, targetBounds.start + oldFourTypesHeading.index)}${sourceSection.text}${targetText.slice(targetBounds.start + oldFourTypesHeading.index)}`;
|
|
2369
|
+
}
|
|
2370
|
+
|
|
2371
|
+
const currentFourTypesHeading = /^### 3\. 四類整合嘅紀律差異/m.exec(boundedTarget);
|
|
2372
|
+
if (currentFourTypesHeading) {
|
|
2373
|
+
return `${targetText.slice(0, targetBounds.start + currentFourTypesHeading.index)}${sourceSection.text}${targetText.slice(targetBounds.start + currentFourTypesHeading.index)}`;
|
|
2374
|
+
}
|
|
2375
|
+
|
|
2376
|
+
return null;
|
|
2377
|
+
}
|
|
2176
2378
|
|
|
2177
2379
|
function hasTrustedSafetyPackShape(text) {
|
|
2178
2380
|
return text.includes("# Safety Pack")
|
package/package.json
CHANGED
|
@@ -1,20 +1,31 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@adamchanadam/agent-handoff-kit",
|
|
3
|
-
"version": "0.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
|
-
"LICENSE"
|
|
15
|
-
],
|
|
16
|
-
"
|
|
17
|
-
"
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "@adamchanadam/agent-handoff-kit",
|
|
3
|
+
"version": "0.3.33",
|
|
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
|
+
"LICENSE"
|
|
15
|
+
],
|
|
16
|
+
"scripts": {
|
|
17
|
+
"doctor": "node bin/agent-handoff-kit.mjs doctor --root .",
|
|
18
|
+
"dry-run": "node bin/agent-handoff-kit.mjs init --dry-run --root .",
|
|
19
|
+
"qa:prototype": "node scripts/check-public-prototype.mjs",
|
|
20
|
+
"qa:public-mirror": "node scripts/build-public-mirror.mjs",
|
|
21
|
+
"qa:packs": "node scripts/check-pack-scenarios.mjs",
|
|
22
|
+
"qa:upgrade": "node scripts/check-upgrade-safety.mjs",
|
|
23
|
+
"qa:release": "node scripts/check-release-readiness.mjs",
|
|
24
|
+
"qa:prompt-mirror": "node scripts/check-prompt-mirror.mjs",
|
|
25
|
+
"qa:fixtures": "node scripts/generate-upgrade-fixtures.mjs"
|
|
26
|
+
},
|
|
27
|
+
"engines": {
|
|
28
|
+
"node": ">=18"
|
|
29
|
+
},
|
|
30
|
+
"license": "MIT"
|
|
31
|
+
}
|
|
@@ -10,6 +10,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
10
10
|
- A change affects `AGENTS.md`, `dev/*`, rule packs, installer templates, or durable workflow docs.
|
|
11
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
12
|
- User asks to make something long-term, cross-session, reusable, "寫入長期治理", "轉成長期機制", "之後都要遵守", or says future sessions should remember an API / MCP / tool-use pattern.
|
|
13
|
+
- The task creates or materially changes Markdown documents, generated outputs, specifications, runbooks, checklists, guides, source-of-truth files, or research artifacts that future agents may need to discover.
|
|
13
14
|
|
|
14
15
|
## Rules
|
|
15
16
|
|
|
@@ -24,6 +25,8 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
24
25
|
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
26
|
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.
|
|
26
27
|
11. 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.
|
|
28
|
+
12. 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.
|
|
29
|
+
13. 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.
|
|
27
30
|
|
|
28
31
|
## Governance Bridge Workflow
|
|
29
32
|
|
|
@@ -40,6 +43,18 @@ Use this workflow when the user asks for governance bridge / 治理打通 / 把
|
|
|
40
43
|
|
|
41
44
|
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.
|
|
42
45
|
|
|
46
|
+
## Generated Artifact Governance Workflow
|
|
47
|
+
|
|
48
|
+
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.
|
|
49
|
+
|
|
50
|
+
1. List the artifacts created or materially changed in this task.
|
|
51
|
+
2. Classify each artifact: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary.
|
|
52
|
+
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.
|
|
53
|
+
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.
|
|
54
|
+
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.
|
|
55
|
+
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.
|
|
56
|
+
7. Before claiming completion, run the available project governance check or `agent-handoff-kit doctor`; if it reports orphan artifact candidates, register, consolidate, or explicitly classify them.
|
|
57
|
+
|
|
43
58
|
## Long-term Governance Routing
|
|
44
59
|
|
|
45
60
|
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.
|
|
@@ -73,6 +88,8 @@ Output format:
|
|
|
73
88
|
- Check `dev/DOC_SYNC_REGISTRY.md` for governance, closeout/startup, and README sync rows.
|
|
74
89
|
- Confirm old overlapping wording was retired or marked legacy.
|
|
75
90
|
- Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
|
|
91
|
+
- Confirm every Markdown document or generated artifact created in this task is indexed, synced, consolidated, or explicitly classified as draft / temporary / one-time evidence.
|
|
92
|
+
- Confirm no new file has become a parallel source for an existing rule, requirement, checklist, or process.
|
|
76
93
|
- 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.
|
|
77
94
|
- 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.
|
|
78
95
|
- 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.
|
package/packs/integrations.md
CHANGED
|
@@ -20,13 +20,14 @@
|
|
|
20
20
|
|
|
21
21
|
### 1. 機密分離原則(最高優先)
|
|
22
22
|
|
|
23
|
-
**Credential(API key / OAuth token / app secret / refresh token)由 AI 工具自身 secure storage 管理**,與本 Kit 完全分離:
|
|
23
|
+
**Credential(API key / OAuth token / app secret / refresh token)由 AI 工具自身 secure storage、OS credential store、tool config、或用戶自管 secret store 管理**,與本 Kit 完全分離:
|
|
24
24
|
|
|
25
|
-
| 儲存層 | 例子 |
|
|
25
|
+
| 儲存層 | 例子 | Kit 可記錄內容 |
|
|
26
26
|
|--------|------|----------|
|
|
27
|
-
|
|
|
28
|
-
|
|
|
29
|
-
| 其他 AI tool
|
|
27
|
+
| AI tool secure storage / Connector storage | Notion / Slack / Linear / Google Drive / Atlassian 等 | 只記 `AI tool secure storage` 或 connector 名稱,不記 value |
|
|
28
|
+
| OS credential store | macOS Keychain / Windows Credential Manager / Linux secret service 等 | 只記 `OS credential store`,不讀取、不導出 value |
|
|
29
|
+
| Tool config / env indirection | Claude Code MCP config / 其他 AI tool config / env var | 只記 config 位置或 env var name;不可讀取、貼出、保存 env value |
|
|
30
|
+
| User-managed secret store | 由用戶或團隊管理嘅 vault / secret manager | 只記 store 類型或 owner,具體 secret value 由用戶管理 |
|
|
30
31
|
|
|
31
32
|
Kit 嘅 `dev/` folder **任何檔都不 touch credential value**。三條硬性 enforcement:
|
|
32
33
|
|
|
@@ -34,27 +35,41 @@ Kit 嘅 `dev/` folder **任何檔都不 touch credential value**。三條硬性
|
|
|
34
35
|
2. AI 識別到 credential prefix(`sk-` / `sk-ant-` / `ntn_` / `secret_` / `ya29.` / `1//` / `xoxp-` / `xoxb-` / `ghp_` / `gho_` / `ghs_` / `github_pat_` / `sl.` / `AKIA` / `AIza` 等)會即時 redact + warn 用戶 rotate token
|
|
35
36
|
3. 寫入 `dev/PROJECT_INDEX.md` `## Installed Integrations` 前 self-check 確認無 credential leak;doctor `checkInstalledIntegrationsCredentialLeak()` 對 PROJECT_INDEX + SESSION_HANDOFF + SESSION_LOG 三個 surface 強制 grep
|
|
36
37
|
|
|
37
|
-
### 2.
|
|
38
|
+
### 2. External Tool Usage Verification Gate
|
|
38
39
|
|
|
39
|
-
|
|
40
|
+
AI must not use model memory, old session experience, copied examples, Connector marketing text, or guessed command shapes as the source for external-tool usage. Before first use of an external tool layer in the current task, and again before any write, destructive action, permission-sensitive action, raw API / SDK / CLI / URI call, plugin API change, or retry after `unknown tool`, `invalid arguments`, HTTP 400 / 404, permission, auth, or schema errors, verify the current usage source for that layer:
|
|
40
41
|
|
|
41
|
-
|
|
42
|
+
| Layer | Required current source before invocation |
|
|
43
|
+
|---|---|
|
|
44
|
+
| Connector / MCP tool | Current runtime-exposed tool name, description, and input schema. Use the tool list/schema exposed by the active AI runtime or MCP server; do not invent `mcp__*` names or arguments. |
|
|
45
|
+
| Plugin / Skill | Current plugin/skill instructions plus any registered MCP tool schema it exposes. |
|
|
46
|
+
| Raw API / SDK / CLI / URI | Current official documentation or a project-local runbook that states source, version/date, and scope. If the runbook lacks those, verify against official docs. |
|
|
47
|
+
| Local app plugin API | Official API documentation, official type definitions, official sample project, or local installed package types matching the project version. |
|
|
48
|
+
| Project-local runbook | Accept as a task source only when it records the upstream source, version/date, scope, and known limits. |
|
|
49
|
+
|
|
50
|
+
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.
|
|
51
|
+
|
|
52
|
+
### 3. 四類整合嘅紀律差異
|
|
53
|
+
|
|
54
|
+
#### 3.1 Connectors(Anthropic 官方 vetted)
|
|
55
|
+
|
|
56
|
+
Anthropic 官方 directory 嘅 ready-to-use MCP server(譬如 Notion / Slack / Linear / Google Drive / Atlassian / HubSpot / 等)。用戶經 Claude Desktop Settings → Extensions → Browse 一鍵安裝,credential 由 AI tool secure storage / OS credential store / connector storage 管理。
|
|
42
57
|
|
|
43
58
|
紀律:
|
|
44
|
-
- AI 可使用
|
|
59
|
+
- AI 可使用 active runtime 已暴露、且已讀取 tool description / input schema 嘅 Connector tool 直接 read / write
|
|
45
60
|
- Write operations 必 read-back verify 後才聲稱成功(沿用 `packs/knowledge.md` Rule 6 紀律)
|
|
46
61
|
- Auth 失敗(token expired / revoked)即 surface「請開 Claude Desktop Settings → Extensions → 重新 authenticate」+ 唔嘗試自動 fix
|
|
47
62
|
|
|
48
|
-
####
|
|
63
|
+
#### 3.2 MCPs(community / custom)
|
|
49
64
|
|
|
50
65
|
非 Anthropic 官方 vetted 嘅 MCP server,譬如 community 開發、用戶自建。需要 manual config(譬如 `~/.config/claude-code/mcp.json`)。
|
|
51
66
|
|
|
52
67
|
紀律:
|
|
53
|
-
- 用
|
|
68
|
+
- 用 active runtime 已暴露、且已讀取 tool description / input schema 嘅 MCP tool(同 Connectors 一樣遵守 schema-first)
|
|
54
69
|
- 因為非官方 vetted,AI 對 write operation 加倍小心:destructive writes 必先 dry-run + 用戶 confirm(沿用 `packs/safety.md` Rule 1)
|
|
55
70
|
- Server 失靈(process crash / config error)即 surface「請檢查 MCP config + 重啟 AI tool」+ 唔嘗試自動 fix
|
|
56
71
|
|
|
57
|
-
####
|
|
72
|
+
#### 3.3 Plugins(Claude Code plugin bundle)
|
|
58
73
|
|
|
59
74
|
distribution format,bundle = Skills + MCP server config + hooks。用戶經 `/plugin` command 安裝。
|
|
60
75
|
|
|
@@ -63,7 +78,7 @@ distribution format,bundle = Skills + MCP server config + hooks。用戶經 `/
|
|
|
63
78
|
- 若 plugin 提供 skill,AI 按 skill 觸發條件自動 invoke(同 system skill 紀律一致)
|
|
64
79
|
- 若 plugin 提供 MCP server,當 Connector / MCP 處理(見 2.1 / 2.2)
|
|
65
80
|
|
|
66
|
-
####
|
|
81
|
+
#### 3.4 Skills(SKILL.md instruction set)
|
|
67
82
|
|
|
68
83
|
content format,由 Plugin 攜帶或 user-level / project-level 直接安裝。
|
|
69
84
|
|
|
@@ -72,7 +87,7 @@ content format,由 Plugin 攜帶或 user-level / project-level 直接安裝。
|
|
|
72
87
|
- Skill 內容屬 instruction overlay,與 rule pack 紀律 layer 共存
|
|
73
88
|
- 若 skill 與 rule pack 紀律有 conflict,rule pack(safety / governance 等)優先
|
|
74
89
|
|
|
75
|
-
###
|
|
90
|
+
### 4. Source-of-truth Architecture(多層持久化組合)
|
|
76
91
|
|
|
77
92
|
當項目用多個整合構成 source-of-truth 架構(譬如 Notion DB Index + 本機真源 + Google Drive 參考檔),AI 必先讀 `dev/PROJECT_INDEX.md` `## Installed Integrations` `### Source-of-truth Architecture` sub-table,識別每層分工:
|
|
78
93
|
|
|
@@ -85,7 +100,7 @@ content format,由 Plugin 攜帶或 user-level / project-level 直接安裝。
|
|
|
85
100
|
|
|
86
101
|
每個 Layer 由邊個 Integration 承擔由 PROJECT_INDEX schema 明示。AI 唔可越層(譬如將 Index 當真源、將 Working draft 直接 push 上 mirror)。
|
|
87
102
|
|
|
88
|
-
###
|
|
103
|
+
### 5. Cross-session Lifecycle(6 階段)
|
|
89
104
|
|
|
90
105
|
#### 階段 0 — First-contact declaration(onboarding 階段)
|
|
91
106
|
|
|
@@ -101,10 +116,10 @@ content format,由 Plugin 攜帶或 user-level / project-level 直接安裝。
|
|
|
101
116
|
|
|
102
117
|
#### 階段 3 — Startup availability probe
|
|
103
118
|
|
|
104
|
-
新 AI session 開工讀 PROJECT_INDEX 後,對每個 declared Integration 跑 minimal capability probe
|
|
119
|
+
新 AI session 開工讀 PROJECT_INDEX 後,對每個 declared Integration 跑 minimal capability probe。Probe 必須使用 active runtime 目前暴露、且已讀取 description / input schema 嘅 tool;不可照抄舊例子或憑記憶猜 tool name / arguments。
|
|
105
120
|
|
|
106
121
|
- Probe success → update `Last Verified` cell + 進入正常 task loop
|
|
107
|
-
- Probe fail(current AI tool 冇裝 / auth expired / network 問題)→ startup card warn 一句「⚠️ Boundary:
|
|
122
|
+
- Probe fail(current AI tool 冇裝 / auth expired / network 問題)→ startup card warn 一句「⚠️ Boundary: <tool> declared but unavailable in this runtime; will fallback to paste flow when that surface is touched」;用戶決定點處理
|
|
108
123
|
|
|
109
124
|
#### 階段 4 — Task execution(knowledge pack Rule 5 配合)
|
|
110
125
|
|
|
@@ -130,19 +145,21 @@ content format,由 Plugin 攜帶或 user-level / project-level 直接安裝。
|
|
|
130
145
|
## Rules
|
|
131
146
|
|
|
132
147
|
1. **Credential 機密分離**:AI 不要求用戶喺對話貼 credential;識別 credential prefix 即 redact + warn rotate;寫 PROJECT_INDEX 前 self-check 無 credential leak。
|
|
133
|
-
2. **
|
|
134
|
-
3. **
|
|
135
|
-
4. **
|
|
136
|
-
5. **
|
|
137
|
-
6. **
|
|
138
|
-
7. **
|
|
139
|
-
8. **
|
|
140
|
-
9. **
|
|
148
|
+
2. **External Tool Usage Verification Gate**:任務涉及外部工具前,先分類工具層並核對 current runtime schema、官方文件、官方型別 / sample、或有版本日期嘅本地 runbook;不能核實即 blocked / unverified,唔用模型記憶試錯。
|
|
149
|
+
3. **Declaration before use**:任務涉及外部工具前,先讀 `dev/PROJECT_INDEX.md` `## Installed Integrations`;無 declaration 即 ask user about Integration status,唔自己假設未裝。
|
|
150
|
+
4. **Connector-first default**:當 declared Integration functional,優先使用 active runtime 已暴露且已讀 schema 嘅 direct tool call;paste fallback 只當 Integration unavailable 時。
|
|
151
|
+
5. **Write operations read-back verify**:所有外部 write(Notion create-page / Drive upload / Slack post 等)必 read-back 對齊後才聲稱 success。
|
|
152
|
+
6. **No auto-fix credential / auth issues**:Auth 失靈即 surface 俾用戶處理(指向 AI 工具設定界面),AI 唔嘗試自動 fix。
|
|
153
|
+
7. **Cross-tool capability awareness**:新 session 開工 verify availability;若 current AI tool 冇相應整合,startup card warn + fallback。
|
|
154
|
+
8. **Source-of-truth layer 唔越界**:真源層 AI 不直接寫;Index 層 AI 經 Connector 讀寫;Mirror 層用戶手動同步;Working draft 層 AI 直接 read/write 本機。
|
|
155
|
+
9. **Drift event mandatory recording**:任何整合失靈 / unavailable 即更新 PROJECT_INDEX `Last Verified` cell + SESSION_LOG drift narrative + handoff next-session prompt 提示。
|
|
156
|
+
10. **Plugin / Skill 紀律 subordinate**:若 Plugin 攜帶 Skill 觸發,與 rule pack 紀律 layer 共存;conflict 時 rule pack(safety / governance / closeout)優先。
|
|
141
157
|
|
|
142
158
|
## Checks
|
|
143
159
|
|
|
144
160
|
- 開工 verify `dev/PROJECT_INDEX.md` `## Installed Integrations` section 存在 + 4 subsection schema 完整
|
|
145
|
-
- 開工對每 declared Integration 跑 capability probe,update `Last Verified` cell
|
|
161
|
+
- 開工對每 declared Integration 跑 capability probe,probe 前先讀 current runtime tool description / input schema,update `Last Verified` cell
|
|
162
|
+
- 外部工具首次調用、寫入、不可逆操作、API / SDK / CLI / URI / plugin API 使用、或工具錯誤後重試前,確認已核對 current runtime schema / 官方文件 / 官方型別 / 官方 sample / 有版本日期嘅 runbook
|
|
146
163
|
- 任何 mid-session Integration drift 即 surface + 紀錄
|
|
147
164
|
- Closeout 前確認 `Last Verified` cell 已 update 為今次 session 結果
|
|
148
165
|
- Credential leak self-check 對 PROJECT_INDEX + SESSION_HANDOFF + SESSION_LOG 任何 write
|
|
@@ -163,7 +180,10 @@ content format,由 Plugin 攜帶或 user-level / project-level 直接安裝。
|
|
|
163
180
|
| Anti-pattern | 點解唔做 | 正確做法 |
|
|
164
181
|
|---|---|---|
|
|
165
182
|
| 用戶提到 Notion / Google Drive 即假設冇 Connector,直接列 paste packet | 違反 2026-05 reality:Connector ecosystem 已成熟,paste-only fallback 不應係 default | 先 read PROJECT_INDEX Installed Integrations;無 declaration 即 ask user about Integration status |
|
|
166
|
-
|
|
|
183
|
+
| 憑模型記憶猜 Notion / Google Drive / Obsidian / GitHub tool name、endpoint、CLI flag、URI param、plugin API | 會把過時訓練資料當現行指令,造成 unknown tool / invalid args / 400 / 404 / permission error 循環 | 先核對 active runtime tool schema、官方文件、官方型別 / sample、或有版本日期嘅本地 runbook;不能核實即 blocked / unverified |
|
|
184
|
+
| Connector 介紹頁或舊例子當成可執行 schema | 介紹頁通常唔等於 current runtime 實際暴露 tool name / input schema | 以 active runtime tool list / schema 為準;官方文件只作 raw API / SDK / CLI / URI 或故障排查真源 |
|
|
185
|
+
| unknown tool / invalid args 後連續改名或改參數試錯 | 同類盲試會製造新錯誤,掩蓋真正 schema / docs 缺口 | 停止同類重試,回到 External Tool Usage Verification Gate |
|
|
186
|
+
| 將 credential value 寫入 PROJECT_INDEX / SESSION_HANDOFF / SESSION_LOG | 違反機密分離原則 + git history 永久保留泄露 | Credential reference 只記指向(譬如「AI tool secure storage」/「env var name only」),永不記 value |
|
|
167
187
|
| 用戶喺對話貼 credential value,AI 直接 用 / 紀錄 | 違反 enforcement Rule 1 + 用戶可能誤泄露 | 即時 redact + warn 用戶 rotate token + 解釋機密分離原則 |
|
|
168
188
|
| Auth 失靈即嘗試自動 fix / re-auth flow | 越界(屬 AI tool + 用戶範圍)+ 可能引入 credential exposure | Surface 失敗 + 指向 AI 工具設定界面 + 唔自動 fix |
|
|
169
189
|
| Connector 寫入後唔 read-back verify | Write 可能 silently fail(rate limit / partial write)—— 用戶以為 success | 必 read-back verify 後才聲稱 success(沿用 knowledge Rule 6) |
|
package/packs/knowledge.md
CHANGED
|
@@ -15,11 +15,11 @@ Use for external notes, knowledge bases, Notion, Obsidian, Drive, docs repositor
|
|
|
15
15
|
2. Record access mode and sync expectation before relying on external content.
|
|
16
16
|
3. Prefer local durable files for installable runtime text unless the project declares otherwise.
|
|
17
17
|
4. Do not perform destructive external writes without explicit confirmation.
|
|
18
|
-
5. Connector-first default for external read/write (R-030 Integration governance discipline; works together with `dev/rules/integrations.md`):
|
|
19
|
-
(a) Before reading or writing external knowledge, check `dev/PROJECT_INDEX.md` `## Installed Integrations` for declared tool availability.
|
|
20
|
-
(b) If a declared Integration is functional in the current session (verified during startup probe per `runtime-core/AGENTS.core.md` Section 1): use the
|
|
21
|
-
(c) If a declared Integration is unavailable in the current session (different AI tool / Connector not configured / auth expired): degrade to manual paste packet workflow + flag drift in the mid-task summary + update `Last Verified` cell at closeout.
|
|
22
|
-
(d) If no declaration exists in `## Installed Integrations` but the task references an external tool: ask the user about Integration status before proceeding (do not silently assume paste fallback). Backward-compat: existing v0.2.x projects with no Installed Integrations section follow path (d) — the section template auto-appends on upgrade but content stays empty until user declares; AI behavior degrades gracefully to ask-user fallback.
|
|
18
|
+
5. Connector-first default for external read/write (R-030 Integration governance discipline; works together with `dev/rules/integrations.md`):
|
|
19
|
+
(a) Before reading or writing external knowledge, check `dev/PROJECT_INDEX.md` `## Installed Integrations` for declared tool availability.
|
|
20
|
+
(b) If a declared Integration is functional in the current session (verified during startup probe per `runtime-core/AGENTS.core.md` Section 1): use only the active runtime tool calls whose current name, description, and input schema have been inspected under the External Tool Usage Verification Gate. Do not invent `mcp__*` names or arguments from examples or memory.
|
|
21
|
+
(c) If a declared Integration is unavailable in the current session (different AI tool / Connector not configured / auth expired): degrade to manual paste packet workflow + flag drift in the mid-task summary + update `Last Verified` cell at closeout.
|
|
22
|
+
(d) If no declaration exists in `## Installed Integrations` but the task references an external tool: ask the user about Integration status before proceeding (do not silently assume paste fallback). Backward-compat: existing v0.2.x projects with no Installed Integrations section follow path (d) — the section template auto-appends on upgrade but content stays empty until user declares; AI behavior degrades gracefully to ask-user fallback.
|
|
23
23
|
6. When writing to an external mirror or index, read back the written record before claiming sync success.
|
|
24
24
|
7. Preserve local file paths as plain text, code, or structured rich text fields when the external tool parses Markdown links or escape characters.
|
|
25
25
|
|
package/packs/onboarding.md
CHANGED
|
@@ -291,7 +291,7 @@ Onboarding 第一個可見回覆只能有一張完整啟動卡,然後直接接
|
|
|
291
291
|
- AI sample wording:
|
|
292
292
|
> 「我會將你已聲明的工具寫入項目登記表:
|
|
293
293
|
>
|
|
294
|
-
> - `## Installed Integrations` `### Connectors` 表填 Notion / Google Drive 等 entries(每個含 Project Usage / Access Scope / Specific Instance / Credential
|
|
294
|
+
> - `## Installed Integrations` `### Connectors` 表填 Notion / Google Drive 等 entries(每個含 Project Usage / Access Scope / Specific Instance / Credential Reference(no value)/ Declared / Last Verified)
|
|
295
295
|
> - `## Installed Integrations` `### Source-of-truth Architecture` sub-table 填多層分工
|
|
296
296
|
> - 既有 `## External Sources` 表的 `via` column 引用對應 Connector entry
|
|
297
297
|
>
|
|
@@ -303,9 +303,9 @@ Onboarding 第一個可見回覆只能有一張完整啟動卡,然後直接接
|
|
|
303
303
|
- AI sample wording:
|
|
304
304
|
> 「聲明已寫好。我會檢查每個外部工具在本次對話是否可用:
|
|
305
305
|
>
|
|
306
|
-
> -
|
|
307
|
-
> -
|
|
308
|
-
> -
|
|
306
|
+
> - Connector / MCP:先讀本次 runtime 暴露的工具名稱、描述與輸入 schema,再做最小 probe
|
|
307
|
+
> - API / SDK / CLI / URI / plugin API:先查官方文件、官方型別 / sample,或有版本日期的本地 runbook
|
|
308
|
+
> - 不能核實的工具:標記 blocked / unverified,不憑記憶試錯
|
|
309
309
|
>
|
|
310
310
|
> 檢查結果會寫入每行 `Last Verified` 欄位。如果任何外部工具不可用(例如目前 AI 工具未配對應 MCP),我會直接說明,讓你決定如何處理。
|
|
311
311
|
>
|
package/packs/safety.md
CHANGED
|
@@ -21,13 +21,13 @@ Use for file operations, shell commands, Git changes, package managers, installe
|
|
|
21
21
|
7. On macOS / Linux, do not run `rm -rf`, `sudo rm`, recursive `chmod`, recursive `chown`, or destructive wildcard operations unless the user explicitly requested the operation and target paths are listed and verified.
|
|
22
22
|
8. Do not run `git reset --hard`, branch deletion, tag deletion, force push, or history rewrite unless the user explicitly requested it and affected refs/files are listed.
|
|
23
23
|
9. Before staging or committing, inspect current status and avoid staging unrelated parent-repo, sibling-directory, generated, credential, or user-owned changes.
|
|
24
|
-
10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools, or release tools, verify current official documentation or project-local runbooks.
|
|
25
|
-
(a) Anthropic-vetted Connectors (e.g. Notion / Google Drive / Slack via Claude Desktop Extensions): trust the vetted MCP server
|
|
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 project-local runbook if available.
|
|
27
|
-
(c) Raw external APIs / SDKs / CLIs (no MCP layer): full Rule 10 verification of official docs required; mark unverified if blocked.
|
|
24
|
+
10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools, or release tools, verify current official documentation or project-local runbooks. For external tools, first apply the External Tool Usage Verification Gate in `dev/rules/integrations.md`: inspect current runtime tool schema for Connector / MCP calls, and use current official docs, official type definitions, official samples, or versioned local runbooks for raw API / SDK / CLI / URI / plugin API work. Differentiate three layers of external access:
|
|
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
|
+
(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
|
+
(c) Raw external APIs / SDKs / CLIs (no MCP layer): full Rule 10 verification of official docs required; mark unverified if blocked.
|
|
28
28
|
11. Do not print, copy, log, commit, upload, or generate files containing secret values. Use redacted placeholders or line references.
|
|
29
29
|
12. Credential leak prevention (R-030 Integration governance):
|
|
30
|
-
(a) Never request, log, or persist credential values (API keys / OAuth tokens / app secrets / refresh tokens) in any project file. Credentials live exclusively in AI tool secure storage
|
|
30
|
+
(a) Never request, log, or persist credential values (API keys / OAuth tokens / app secrets / refresh tokens) in any project file. Credentials live exclusively in AI tool secure storage, OS credential stores, AI tool config, user-managed secret stores, or env indirection; if env is used, project files may record only the env var name, never the value.
|
|
31
31
|
(b) Recognize common credential prefixes (`sk-`, `sk-ant-`, `ntn_`, `secret_`, `ya29.`, `1//`, `xoxp-`, `xoxb-`, `ghp_`, `gho_`, `ghs_`, `github_pat_`, `sl.`, `AKIA`, `AIza`) — if a value matching any prefix appears in conversation, redact immediately and warn the user to rotate the token.
|
|
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).
|
package/packs/writing.md
CHANGED
|
@@ -18,12 +18,16 @@ Use for drafting, editing, style, structure, publication copy, documentation pro
|
|
|
18
18
|
5. Do not bury durable requirements only in prose; use project index, spec, runbook, or handoff when needed.
|
|
19
19
|
6. For public Traditional Chinese docs or HTML aimed at non-technical readers, use steady written Chinese. Keep English only for commands, paths, URLs, file names, product names, and unavoidable tool names. Avoid mixed half-English fragments, internal governance codes, and developer-only wording in reader-facing prose.
|
|
20
20
|
7. For public README, onboarding, and other user-facing docs, use the product-journey rule: the user states the goal, the AI handles technical work. Keep one primary user path. Do not make users choose between install, upgrade, doctor, dry-run, or terminal commands when an AI-assisted path exists. Put technical commands in the dedicated AI install page, CLI help, or advanced examples instead of duplicating them in the main README flow.
|
|
21
|
+
8. When writing or revising Markdown files, decide whether the output is a durable source, a reference, a runbook, a public document, a reusable generated artifact, a draft, or one-time evidence. Durable outputs must be indexed or tied to a registered source/sync home before completion; drafts and one-time evidence must be labeled so they do not become hidden current state.
|
|
22
|
+
9. If a new document repeats requirements, instructions, acceptance rules, or process already owned by another file, consolidate into the existing source or make the new file explicitly subordinate. Do not let writing work create parallel truth.
|
|
21
23
|
|
|
22
24
|
## Checks
|
|
23
25
|
|
|
24
26
|
- Verify requested format, language, and tone.
|
|
25
27
|
- Check links, commands, names, and version-sensitive claims when relevant.
|
|
26
28
|
- Check `dev/DOC_SYNC_REGISTRY.md` if public docs or user-facing instructions changed.
|
|
29
|
+
- For any Markdown file created or materially changed, check whether `dev/PROJECT_INDEX.md` needs a Directory Map, Fact Base, Entry Points, or read-condition update.
|
|
30
|
+
- Check duplicate-source risk before keeping a new requirement, checklist, process, or instruction document.
|
|
27
31
|
- For public Chinese docs, read the final text as a new user journey: the next action should be clear without technical background.
|
|
28
32
|
- For README-style docs, confirm the main path does not become parallel instructions: no repeated manual install section, no competing command table, and no requirement that the reader understand internal files before taking the first action.
|
|
29
33
|
|
|
@@ -23,11 +23,13 @@ Ambiguous startup phrases need one concise confirmation question before treating
|
|
|
23
23
|
|
|
24
24
|
If a required file is missing, create the smallest useful version only after confirming the target project root.
|
|
25
25
|
|
|
26
|
-
Before acting on a non-trivial task, identify required local source-of-truth files and external sources from the handoff, project index, user request, and sync registry. Read them or mark them blocked. Reachable is not the same as ingested. Do not treat unread sources as absent. If tool output is truncated, paginated, or only a search hit, continue reading the relevant source or mark coverage as partial; do not present a complete conclusion from partial output.
|
|
26
|
+
Before acting on a non-trivial task, identify required local source-of-truth files and external sources from the handoff, project index, user request, and sync registry. Read them or mark them blocked. Reachable is not the same as ingested. Do not treat unread sources as absent. If tool output is truncated, paginated, or only a search hit, continue reading the relevant source or mark coverage as partial; do not present a complete conclusion from partial output.
|
|
27
|
+
|
|
28
|
+
When creating or materially changing Markdown files, generated documents, research outputs, specifications, runbooks, checklists, guides, or other durable artifacts, do not leave them as orphan files. Before claiming the task is complete, classify each new or materially changed artifact as one of: draft / one-time evidence, source of truth, reference, runbook, workflow, public document, generated output, or intentionally temporary. Then either register it in `dev/PROJECT_INDEX.md` with a role and read condition, register a sync obligation in `dev/DOC_SYNC_REGISTRY.md`, point to an existing authoritative home and mark the file as non-authoritative, or explicitly record why it is temporary / one-time evidence. If several files carry the same durable rule or requirement, consolidate or point to the single authoritative home instead of creating parallel truth.
|
|
27
29
|
|
|
28
30
|
After reading `dev/PROJECT_INDEX.md`, if `## Installed Integrations` is non-empty, run startup availability probe (R-030 Integration governance discipline; see `dev/rules/integrations.md`):
|
|
29
31
|
|
|
30
|
-
- For each declared Integration under Connectors / MCPs subsection, attempt minimal capability probe
|
|
32
|
+
- For each declared Integration under Connectors / MCPs subsection, attempt a minimal capability probe using the active runtime's currently exposed tool name, description, and input schema. Do not invent `mcp__*` names or arguments from examples or memory.
|
|
31
33
|
- If probe succeeds: update the corresponding `Last Verified` cell to today's date; proceed normally.
|
|
32
34
|
- If probe fails (current AI tool lacks the Connector / auth expired / network issue): print warning in the startup card (`⚠️ Boundary` line) noting which Integration is declared-but-unavailable + that this session will fallback to paste flow when that external surface is touched. Do not attempt to auto-fix auth or credential issues; surface to the user to handle via the AI tool's own settings interface.
|
|
33
35
|
- Credential separation: AI must never request, log, or persist credential values (API keys / OAuth tokens / app secrets / refresh tokens). Credentials live in OS-level secure storage or AI-tool-specific config, never in `dev/*` files. Recognize common credential prefixes (`sk-`, `sk-ant-`, `ntn_`, `secret_`, `ya29.`, `1//`, `xoxp-`, `xoxb-`, `ghp_`, `gho_`, `ghs_`, `github_pat_`, `sl.`, `AKIA`, `AIza`) and redact + warn the user to rotate the token if accidentally pasted.
|
|
@@ -56,8 +58,9 @@ Use this loop for every task:
|
|
|
56
58
|
1. PLAN: restate the user's intent, scope, risk, and acceptance criteria.
|
|
57
59
|
2. READ: inspect relevant files from `PROJECT_INDEX.md` and search for related definitions before editing.
|
|
58
60
|
3. CHANGE: make focused changes only.
|
|
59
|
-
4. QC: run available checks or state why they cannot run.
|
|
60
|
-
5. PERSISTENCE GATE: decide whether this task produced a durable fact before writing governance files. A durable fact is information the next agent cannot reliably reconstruct and that affects future action.
|
|
61
|
+
4. QC: run available checks or state why they cannot run.
|
|
62
|
+
5. PERSISTENCE GATE: decide whether this task produced a durable fact before writing governance files. A durable fact is information the next agent cannot reliably reconstruct and that affects future action.
|
|
63
|
+
6. ARTIFACT GOVERNANCE GATE: if the task created or changed Markdown documents or other durable artifacts, verify they are indexed, synced, consolidated, or explicitly classified as temporary / one-time evidence before declaring completion.
|
|
61
64
|
|
|
62
65
|
External skill flows, subagents, task plans, or another tool's "finish" step do not replace this loop. If you use any of them, the PLAN must include a final Agent Handoff Kit persistence-gate check for the active project root, and completion cannot be claimed until that check is answered at the correct tier.
|
|
63
66
|
|
|
@@ -108,11 +111,13 @@ Do not claim completion without evidence from checks, inspection, or a clear exp
|
|
|
108
111
|
|
|
109
112
|
## 4. Closeout And Handoff
|
|
110
113
|
|
|
111
|
-
Detect end-of-session or handoff intent in natural language, such as "收工", "Wrap up Agent Handoff", "closeout", "wrap up", or "handoff". If intent is ambiguous, ask one concise confirmation question.
|
|
112
|
-
|
|
113
|
-
Ambiguous closeout phrases need one concise confirmation question before full closeout. In particular, if the user says "<something> 收工", "<something> close", or similar wording that may refer to a real-world shift, event, project phase, or another context, ask whether they mean to wrap up Agent Handoff Kit and write the project handoff.
|
|
114
|
-
|
|
115
|
-
|
|
114
|
+
Detect end-of-session or handoff intent in natural language, such as "收工", "Wrap up Agent Handoff", "closeout", "wrap up", or "handoff". If intent is ambiguous, ask one concise confirmation question.
|
|
115
|
+
|
|
116
|
+
Ambiguous closeout phrases need one concise confirmation question before full closeout. In particular, if the user says "<something> 收工", "<something> close", or similar wording that may refer to a real-world shift, event, project phase, or another context, ask whether they mean to wrap up Agent Handoff Kit and write the project handoff.
|
|
117
|
+
|
|
118
|
+
If the user sends only a clear closeout phrase such as "收工", "wrap up", "handoff", or "Wrap up Agent Handoff", do not answer with a summary-only message. Enter full closeout immediately: announce that Agent Handoff Kit closeout is starting, read the current handoff/log/index, reconcile state, write the required files, run the available checks, and only then show the closeout card. A final chat summary without updated handoff/log/prompt evidence is not closeout.
|
|
119
|
+
|
|
120
|
+
At full closeout:
|
|
116
121
|
|
|
117
122
|
Closeout Write Contract: before writing `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, or `START_NEXT_SESSION_PROMPT.txt`, classify each fact by role and write it to the matching structured area. Use one Agent Handoff Kit marker standard as the machine boundary: `ack:section:*` for sections, `ack:field:*` for fields, `ack:log-entry:start/end` for log entries, and managed-core BEGIN/END for the installed AGENTS core. Do not remove or translate these markers. New closeout writes must use this marker standard; natural-language headings are only human labels, and legacy heading fallback is only for migration / repair of older installs. Current state and next action go only in `dev/SESSION_HANDOFF.md`. Trace evidence, one-time tasks, old build / release / hash facts, and completed delivery details go only in `dev/SESSION_LOG.md` unless promoted to `dev/PROJECT_INDEX.md`, `dev/PROJECT_DECISIONS.md`, `dev/DOC_SYNC_REGISTRY.md`, or a rule pack. `START_NEXT_SESSION_PROMPT.txt` is regenerated from the handoff opening-message block; do not hand-write separate startup state there.
|
|
118
123
|
|
|
@@ -9,6 +9,7 @@ Use: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.
|
|
|
9
9
|
| Change type | Also check/update | Verification |
|
|
10
10
|
|---|---|---|
|
|
11
11
|
| New file or directory | `dev/PROJECT_INDEX.md` Directory Map | path listed |
|
|
12
|
+
| Generated Markdown or durable artifact | `dev/PROJECT_INDEX.md` Directory Map / Fact Base / Entry Points, and this registry when future updates need sync | artifact classified as indexed / synced / temporary / one-time evidence; duplicate source-of-truth risk checked |
|
|
12
13
|
| Stack or command change | `dev/PROJECT_INDEX.md` Stack / Entry Points | command verified or marked unverified |
|
|
13
14
|
| Public behavior change | README, public docs, changelog | docs mention current behavior |
|
|
14
15
|
| API or SDK behavior change | API docs, examples, tests | tests or documented reason |
|
|
@@ -35,9 +35,10 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
|
|
|
35
35
|
|---|---|---|
|
|
36
36
|
| App entry | TBD | TBD |
|
|
37
37
|
| Main config | TBD | TBD |
|
|
38
|
-
| Test suite | TBD | TBD |
|
|
39
|
-
| Runbook | TBD | TBD |
|
|
40
|
-
| Public docs | TBD | TBD |
|
|
38
|
+
| Test suite | TBD | TBD |
|
|
39
|
+
| Runbook | TBD | TBD |
|
|
40
|
+
| Public docs | TBD | TBD |
|
|
41
|
+
| Generated artifact review | `dev/PROJECT_INDEX.md` + `dev/DOC_SYNC_REGISTRY.md` | After creating Markdown docs, generated outputs, specs, runbooks, checklists, or research artifacts, classify each artifact as indexed / synced / temporary / one-time evidence before completion |
|
|
41
42
|
|
|
42
43
|
## Fact Base
|
|
43
44
|
|
|
@@ -57,21 +58,21 @@ Reachable means the source can be found. It does not mean the source has been re
|
|
|
57
58
|
|
|
58
59
|
## Installed Integrations
|
|
59
60
|
|
|
60
|
-
> ⚠️ **機密分離原則**:本 section 只記錄 **項目使用紀錄** + **公開參考座標**(Notion DB 名 / URL / folder path 等),**絕對不記錄 API key / OAuth token / 任何 credential value**。Credential 應由 AI 工具自身 secure storage
|
|
61
|
+
> ⚠️ **機密分離原則**:本 section 只記錄 **項目使用紀錄** + **公開參考座標**(Notion DB 名 / URL / folder path 等),**絕對不記錄 API key / OAuth token / 任何 credential value**。Credential 應由 AI 工具自身 secure storage / OS credential store / tool config / user-managed secret store 管理;若使用 env,只可記錄 env var name,不可讀取、貼出或保存 value。AI 寫入本 section 前必 self-check 確認無 credential leak;doctor 對本 section + SESSION_HANDOFF + SESSION_LOG 強制 grep credential prefix patterns(`sk-` / `ntn_` / `ya29.` / `xoxp-` / `ghp_` / `sl.` / `AKIA` / `AIza` 等)。
|
|
61
62
|
|
|
62
63
|
> 用途:新 AI session 開工讀本 section 知道項目可用嘅外部工具能力 + 各自分工。Declare 一次後跨 session AI 都會 leverage;每個 entry 必含 `Declared` + `Last Verified` 防漂移。
|
|
63
64
|
|
|
64
65
|
### Connectors(Anthropic 官方 vetted)
|
|
65
66
|
|
|
66
|
-
| Tool | Project Usage | Access Scope | Specific Instance | Credential
|
|
67
|
+
| Tool | Project Usage | Access Scope | Specific Instance | Credential Reference(no value) | Declared | Last Verified |
|
|
67
68
|
|------|---------------|--------------|-------------------|---------------------|----------|---------------|
|
|
68
|
-
| TBD | TBD(譬如 DB Index 記真源 path / 持久化參考檔儲存) | read / read+write | TBD(譬如 DB 名 + URL / folder path) | TBD(譬如 `
|
|
69
|
+
| TBD | TBD(譬如 DB Index 記真源 path / 持久化參考檔儲存) | read / read+write | TBD(譬如 DB 名 + URL / folder path) | TBD(譬如 `AI tool secure storage` / `OS credential store`) | TBD | TBD |
|
|
69
70
|
|
|
70
71
|
### MCPs(community / custom)
|
|
71
72
|
|
|
72
|
-
| Server | Source | Project Usage | Credential
|
|
73
|
+
| Server | Source | Project Usage | Credential Reference(no value) | Declared | Last Verified |
|
|
73
74
|
|--------|--------|---------------|---------------------|----------|---------------|
|
|
74
|
-
| TBD | TBD(譬如 GitHub repo URL) | TBD | TBD(譬如 `
|
|
75
|
+
| TBD | TBD(譬如 GitHub repo URL) | TBD | TBD(譬如 `tool config + env var name only` / `user-managed secret store`) | TBD | TBD |
|
|
75
76
|
|
|
76
77
|
### Plugins(Claude Code plugin bundle)
|
|
77
78
|
|
|
@@ -100,8 +101,8 @@ Reachable means the source can be found. It does not mean the source has been re
|
|
|
100
101
|
|
|
101
102
|
| Check | Command | Run before | Last verified |
|
|
102
103
|
|---|---|---|---|
|
|
103
|
-
| Agent Handoff Kit doctor |
|
|
104
|
-
| Project governance check |
|
|
104
|
+
| Agent Handoff Kit doctor | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .` | closeout / governance changes / generated Markdown artifact checks | package latest |
|
|
105
|
+
| 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 |
|
|
105
106
|
|
|
106
107
|
## Workspace Identity
|
|
107
108
|
|
|
@@ -122,7 +123,8 @@ Record this at closeout so the next AI can detect wrong-root or workspace drift.
|
|
|
122
123
|
| API behavior | TBD | tests + docs sync |
|
|
123
124
|
| UI behavior | TBD | build + visual/manual check |
|
|
124
125
|
| Data model | TBD | migration/checks |
|
|
125
|
-
| Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
|
|
126
|
+
| Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
|
|
127
|
+
| Generated Markdown or durable artifact | `docs/`, `outputs/`, root Markdown files, project-specific reference folders | classify as indexed / synced / temporary / one-time evidence; update `dev/PROJECT_INDEX.md` or `dev/DOC_SYNC_REGISTRY.md` when durable |
|
|
126
128
|
| Closeout/startup contract | `AGENTS.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | opening message present + workspace identity current + prompt file regenerated from handoff at closeout |
|
|
127
129
|
|
|
128
130
|
## External Services
|
|
@@ -12,7 +12,7 @@ Stable facts that should survive across sessions. Update only when they change,
|
|
|
12
12
|
3. Governance model: TBD
|
|
13
13
|
4. Source-of-truth ownership: TBD
|
|
14
14
|
5. Release / publish boundary: TBD
|
|
15
|
-
6. Installed Integrations registry: `dev/PROJECT_INDEX.md` `## Installed Integrations` section is the project's authoritative declaration of installed Connectors / MCPs / Plugins / Skills + Source-of-truth Architecture sub-table. New AI session must read it after governance reads and run availability probe per `runtime-core/AGENTS.core.md` Section 1. Credential values never appear here or in any `dev/*` file —
|
|
15
|
+
6. Installed Integrations registry: `dev/PROJECT_INDEX.md` `## Installed Integrations` section is the project's authoritative declaration of installed Connectors / MCPs / Plugins / Skills + Source-of-truth Architecture sub-table. New AI session must read it after governance reads and run availability probe per `runtime-core/AGENTS.core.md` Section 1. Credential values never appear here or in any `dev/*` file — only credential references such as AI tool secure storage, OS credential store, tool config, user-managed secret store, or env var name may be recorded.
|
|
16
16
|
|
|
17
17
|
<!-- ack:section:closeout-reconciled-state -->
|
|
18
18
|
## Closeout-Reconciled State
|