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