@adamchanadam/agent-handoff-kit 0.3.38 → 0.3.40
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -21
- package/README.md +5 -5
- package/bin/agent-handoff-kit.mjs +1570 -752
- package/bin/migration-baselines/v0.3.38/integrations.md +235 -0
- package/bin/migration-baselines/v0.3.38/onboarding.md +201 -0
- package/bin/migration-baselines/v0.3.38/safety.md +46 -0
- package/bin/prompt-mirror-core.mjs +187 -114
- package/package.json +20 -31
- package/packs/agent-governance.md +103 -103
- package/packs/closeout.md +72 -0
- package/packs/coding.md +28 -28
- package/packs/communication.md +30 -30
- package/packs/integrations.md +251 -235
- package/packs/knowledge.md +5 -5
- package/packs/onboarding.md +214 -201
- package/packs/release.md +28 -28
- package/packs/research.md +30 -30
- package/packs/safety.md +29 -27
- package/packs/writing.md +36 -36
- package/runtime-core/AGENTS.core.md +61 -139
- package/runtime-core/CLAUDE.md +13 -13
- package/runtime-core/DOC_SYNC_REGISTRY.md +24 -24
- package/runtime-core/GEMINI.md +17 -17
- package/runtime-core/PROJECT_DECISIONS.md +43 -43
- package/runtime-core/PROJECT_INDEX.md +10 -8
- package/runtime-core/RULE_PACKS.md +12 -11
- package/runtime-core/SESSION_HANDOFF.md +35 -44
- package/runtime-core/SESSION_LOG.md +35 -57
- package/runtime-core/START_NEXT_SESSION_PROMPT.txt +5 -16
|
@@ -1,114 +1,187 @@
|
|
|
1
|
-
import { readFileSync } from "node:fs";
|
|
2
|
-
import path from "node:path";
|
|
3
|
-
|
|
4
|
-
const openingSectionMarker = "<!-- ack:section:next-session-opening-message -->";
|
|
5
|
-
const openingHeadingPattern = /^##\s+Next Session Opening Message\s*$/m;
|
|
6
|
-
const openingContentMarkers = [
|
|
7
|
-
"📋 Next session: agent-managed startup content below",
|
|
8
|
-
"📋 Next session: copy and paste the whole block below"
|
|
9
|
-
];
|
|
10
|
-
|
|
11
|
-
export function assessPromptMirrorRoot(root) {
|
|
12
|
-
const handoffPath = path.join(root, "dev", "SESSION_HANDOFF.md");
|
|
13
|
-
const promptPath = path.join(root, "START_NEXT_SESSION_PROMPT.txt");
|
|
14
|
-
let handoffText = "";
|
|
15
|
-
let promptText = "";
|
|
16
|
-
|
|
17
|
-
try {
|
|
18
|
-
handoffText = readFileSync(handoffPath, "utf8");
|
|
19
|
-
} catch {
|
|
20
|
-
return { status: "missing", ok: false, reason: "handoff unreadable" };
|
|
21
|
-
}
|
|
22
|
-
|
|
23
|
-
try {
|
|
24
|
-
promptText = readFileSync(promptPath, "utf8");
|
|
25
|
-
} catch {
|
|
26
|
-
return { status: "missing", ok: false, reason: "prompt copy unreadable" };
|
|
27
|
-
}
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
if (
|
|
43
|
-
return {
|
|
44
|
-
status: "
|
|
45
|
-
ok:
|
|
46
|
-
reason:
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
const
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
}
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
}
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
const
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
return
|
|
114
|
-
}
|
|
1
|
+
import { lstatSync, readFileSync, readdirSync } from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
|
|
4
|
+
const openingSectionMarker = "<!-- ack:section:next-session-opening-message -->";
|
|
5
|
+
const openingHeadingPattern = /^##\s+Next Session Opening Message\s*$/m;
|
|
6
|
+
const openingContentMarkers = [
|
|
7
|
+
"📋 Next session: agent-managed startup content below",
|
|
8
|
+
"📋 Next session: copy and paste the whole block below"
|
|
9
|
+
];
|
|
10
|
+
|
|
11
|
+
export function assessPromptMirrorRoot(root) {
|
|
12
|
+
const handoffPath = path.join(root, "dev", "SESSION_HANDOFF.md");
|
|
13
|
+
const promptPath = path.join(root, "START_NEXT_SESSION_PROMPT.txt");
|
|
14
|
+
let handoffText = "";
|
|
15
|
+
let promptText = "";
|
|
16
|
+
|
|
17
|
+
try {
|
|
18
|
+
handoffText = readFileSync(handoffPath, "utf8");
|
|
19
|
+
} catch {
|
|
20
|
+
return { status: "missing", ok: false, reason: "handoff unreadable" };
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
try {
|
|
24
|
+
promptText = readFileSync(promptPath, "utf8");
|
|
25
|
+
} catch {
|
|
26
|
+
return { status: "missing", ok: false, reason: "prompt copy unreadable" };
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
const otherTexts = collectCurrentGovernanceTexts(root, new Set([
|
|
30
|
+
path.resolve(handoffPath),
|
|
31
|
+
path.resolve(promptPath)
|
|
32
|
+
]));
|
|
33
|
+
return assessPromptMirrorTexts(handoffText, promptText, otherTexts);
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export function assessPromptMirrorTexts(handoffText, promptText, otherTexts = []) {
|
|
37
|
+
const markerCount = countLiteral(handoffText, openingSectionMarker);
|
|
38
|
+
const headingCount = (handoffText.match(new RegExp(openingHeadingPattern.source, "gm")) ?? []).length;
|
|
39
|
+
const contentMarkerCount = openingContentMarkers.reduce((sum, marker) => sum + countLiteral(handoffText, marker), 0);
|
|
40
|
+
const openingSection = markerCount === 1 ? handoffText.slice(handoffText.indexOf(openingSectionMarker)) : "";
|
|
41
|
+
const fenceCount = (openingSection.match(/```text[^\r\n]*(?:\r\n?|\n)[\s\S]*?(?:\r\n?|\n)```/g) ?? []).length;
|
|
42
|
+
if (markerCount !== 1 || headingCount > 1 || contentMarkerCount !== 1 || fenceCount !== 1) {
|
|
43
|
+
return {
|
|
44
|
+
status: "structure-invalid",
|
|
45
|
+
ok: false,
|
|
46
|
+
reason: `opening structure must be unique (section marker=${markerCount}, heading=${headingCount}, copy marker=${contentMarkerCount}, fenced text=${fenceCount})`
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const openingMessage = extractOpeningMessage(handoffText);
|
|
51
|
+
if (openingMessage == null) {
|
|
52
|
+
return {
|
|
53
|
+
status: "missing",
|
|
54
|
+
ok: false,
|
|
55
|
+
reason: "handoff opening message missing"
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
const normalizedOpening = normalizePrompt(openingMessage);
|
|
60
|
+
const thirdCopies = otherTexts.filter(({ text }) => normalizePrompt(text).includes(normalizedOpening));
|
|
61
|
+
if (thirdCopies.length > 0) {
|
|
62
|
+
return {
|
|
63
|
+
status: "third-copy",
|
|
64
|
+
ok: false,
|
|
65
|
+
reason: `full opening message also appears in: ${thirdCopies.map(({ relative }) => relative).join(", ")}`,
|
|
66
|
+
openingMessage,
|
|
67
|
+
thirdCopies: thirdCopies.map(({ relative }) => relative)
|
|
68
|
+
};
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
if (openingMessage === promptText) {
|
|
72
|
+
return {
|
|
73
|
+
status: "match",
|
|
74
|
+
ok: true,
|
|
75
|
+
reason: "",
|
|
76
|
+
openingMessage,
|
|
77
|
+
firstDiff: null
|
|
78
|
+
};
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
const normalizedPrompt = normalizePrompt(promptText);
|
|
82
|
+
if (normalizedOpening === normalizedPrompt) {
|
|
83
|
+
return {
|
|
84
|
+
status: "newline-only",
|
|
85
|
+
ok: true,
|
|
86
|
+
reason: "only newline style or final newline differs",
|
|
87
|
+
openingMessage,
|
|
88
|
+
firstDiff: null
|
|
89
|
+
};
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
return {
|
|
93
|
+
status: "mismatch",
|
|
94
|
+
ok: false,
|
|
95
|
+
reason: "convenience copy differs from dev/SESSION_HANDOFF.md",
|
|
96
|
+
openingMessage,
|
|
97
|
+
firstDiff: firstDiff(normalizedOpening, normalizedPrompt)
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
export function extractOpeningMessage(text) {
|
|
102
|
+
const sectionStart = findOpeningSectionStart(text);
|
|
103
|
+
if (sectionStart < 0) return null;
|
|
104
|
+
|
|
105
|
+
const sectionText = text.slice(sectionStart);
|
|
106
|
+
const marker = openingContentMarkers.find((candidate) => sectionText.includes(candidate));
|
|
107
|
+
if (!marker) return null;
|
|
108
|
+
|
|
109
|
+
const markerIndex = sectionText.indexOf(marker);
|
|
110
|
+
const afterMarker = sectionText.slice(markerIndex + marker.length);
|
|
111
|
+
const fenceMatch = /```text[^\r\n]*(?:\r\n?|\n)([\s\S]*?)(?:\r\n?|\n)```/.exec(afterMarker);
|
|
112
|
+
if (!fenceMatch) return null;
|
|
113
|
+
return fenceMatch[1];
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
export function normalizePrompt(text) {
|
|
117
|
+
return text.replace(/\r\n?/g, "\n").replace(/\n+$/g, "");
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
function findOpeningSectionStart(text) {
|
|
121
|
+
const markerIndex = text.indexOf(openingSectionMarker);
|
|
122
|
+
if (markerIndex >= 0) return markerIndex;
|
|
123
|
+
|
|
124
|
+
const headingMatch = openingHeadingPattern.exec(text);
|
|
125
|
+
return headingMatch ? headingMatch.index : -1;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
function firstDiff(left, right) {
|
|
129
|
+
const leftLines = left.split("\n");
|
|
130
|
+
const rightLines = right.split("\n");
|
|
131
|
+
const count = Math.max(leftLines.length, rightLines.length);
|
|
132
|
+
for (let index = 0; index < count; index += 1) {
|
|
133
|
+
if ((leftLines[index] ?? "") !== (rightLines[index] ?? "")) {
|
|
134
|
+
return {
|
|
135
|
+
line: index + 1,
|
|
136
|
+
handoff: leftLines[index] ?? "",
|
|
137
|
+
prompt: rightLines[index] ?? ""
|
|
138
|
+
};
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
return null;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
function countLiteral(text, token) {
|
|
145
|
+
if (!token) return 0;
|
|
146
|
+
let count = 0;
|
|
147
|
+
let offset = 0;
|
|
148
|
+
while ((offset = text.indexOf(token, offset)) >= 0) {
|
|
149
|
+
count += 1;
|
|
150
|
+
offset += token.length;
|
|
151
|
+
}
|
|
152
|
+
return count;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
function collectCurrentGovernanceTexts(root, excluded) {
|
|
156
|
+
const candidates = [
|
|
157
|
+
"AGENTS.md",
|
|
158
|
+
"CLAUDE.md",
|
|
159
|
+
"GEMINI.md",
|
|
160
|
+
"dev/SESSION_LOG.md",
|
|
161
|
+
"dev/PROJECT_INDEX.md",
|
|
162
|
+
"dev/DOC_SYNC_REGISTRY.md",
|
|
163
|
+
"dev/RULE_PACKS.md",
|
|
164
|
+
"dev/PROJECT_DECISIONS.md"
|
|
165
|
+
];
|
|
166
|
+
const rulesDir = path.join(root, "dev", "rules");
|
|
167
|
+
try {
|
|
168
|
+
for (const entry of readdirSync(rulesDir, { withFileTypes: true })) {
|
|
169
|
+
if (entry.isFile() && entry.name.endsWith(".md")) candidates.push(`dev/rules/${entry.name}`);
|
|
170
|
+
}
|
|
171
|
+
} catch {
|
|
172
|
+
// Missing rules are reported by normal doctor checks.
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
const results = [];
|
|
176
|
+
for (const relative of candidates) {
|
|
177
|
+
const absolute = path.resolve(root, relative);
|
|
178
|
+
if (excluded.has(absolute)) continue;
|
|
179
|
+
try {
|
|
180
|
+
if (lstatSync(absolute).isSymbolicLink()) continue;
|
|
181
|
+
results.push({ relative, text: readFileSync(absolute, "utf8") });
|
|
182
|
+
} catch {
|
|
183
|
+
// Missing or unreadable files are handled by their owning checks.
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
return results;
|
|
187
|
+
}
|
package/package.json
CHANGED
|
@@ -1,31 +1,20 @@
|
|
|
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
|
-
|
|
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
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@adamchanadam/agent-handoff-kit",
|
|
3
|
+
"version": "0.3.40",
|
|
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
|
+
"engines": {
|
|
17
|
+
"node": ">=18"
|
|
18
|
+
},
|
|
19
|
+
"license": "MIT"
|
|
20
|
+
}
|
|
@@ -1,103 +1,103 @@
|
|
|
1
|
-
# Agent Governance Pack
|
|
2
|
-
|
|
3
|
-
## Scope
|
|
4
|
-
|
|
5
|
-
Use for governance rules, prompts, agent instructions, handoff systems, startup/closeout behavior, skills, and rule packs.
|
|
6
|
-
|
|
7
|
-
## Load When
|
|
8
|
-
|
|
9
|
-
- User asks to change AI behavior, project governance, prompts, handoff, startup, closeout, or tool-use rules.
|
|
10
|
-
- A change affects `AGENTS.md`, `dev/*`, rule packs, installer templates, or durable workflow docs.
|
|
11
|
-
- User asks to bridge governance, connect a document to governance, scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
|
|
12
|
-
- User asks to make something long-term, cross-session, reusable, future sessions should remember an API / MCP / tool-use pattern, or uses equivalent Chinese phrases such as "寫入長期治理", "轉成長期機制", or "之後都要遵守".
|
|
13
|
-
- The task creates or materially changes Markdown documents, generated outputs, specifications, runbooks, checklists, guides, source-of-truth files, or research artifacts that future agents may need to discover.
|
|
14
|
-
|
|
15
|
-
## Rules
|
|
16
|
-
|
|
17
|
-
1. Locate the existing source of truth before adding a rule.
|
|
18
|
-
2. Prefer merge, replace, or registry rows over append-only rule growth.
|
|
19
|
-
3. Keep public runtime rules generic; project-specific incidents belong in logs, runbooks, or project index.
|
|
20
|
-
4. Do not let development-only workspace rules enter public runtime.
|
|
21
|
-
5. Check complexity budget before adding default-core behavior.
|
|
22
|
-
6. Before creating durable workflow, runbook, or instruction files, first classify the knowledge type and verify whether an existing home can carry it without a new file: current state belongs in `dev/SESSION_HANDOFF.md`; trace evidence belongs in `dev/SESSION_LOG.md`; file / command / reference maps belong in `dev/PROJECT_INDEX.md`; sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`; reusable operating procedures belong in the relevant rule pack or registered reference. New runbooks are last resort only.
|
|
23
|
-
7. When a task uses external skills, subagents, demo workspaces, or another tool's closeout, treat those flows as subordinate to the active root's Agent Handoff Kit governance. The active root still needs the `runtime-core/AGENTS.core.md` persistence gate decision; do not duplicate the gate thresholds in this pack.
|
|
24
|
-
8. For long-running projects, maintain `dev/PROJECT_DECISIONS.md` per R-028 closeout discipline (see `runtime-core/AGENTS.core.md` closeout maintenance trigger check): capture major decisions when they happen, run the short trigger check at every closeout, and do full long-term maintenance only when a hard trigger, semantic trigger, or 10-closeout backstop applies. Short single-task projects keep this as a no-op default; users are not expected to edit this file manually.
|
|
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.
|
|
26
|
-
10. Content-based trigger: long-term governance routing is content-based, not trigger-only. Even if the user does not use explicit governance-routing phrases, treat a statement as durable governance when it says future sessions must follow it, when it corrects a recurring AI mistake, or when it defines a reusable API / MCP / tool-use pattern. Do not persist long-term governance knowledge only in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or `START_NEXT_SESSION_PROMPT.txt`; those surfaces may be compressed, archived, or regenerated.
|
|
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.
|
|
30
|
-
|
|
31
|
-
## Governance Bridge Workflow
|
|
32
|
-
|
|
33
|
-
Use this workflow when the user asks for governance bridge, connect this document to governance, asks to scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
|
|
34
|
-
|
|
35
|
-
1. Identify the target. If the user named a file, inspect that file and its surrounding directory. If no file is named, run a bounded repo scan for likely durable documents such as source-of-truth files, runbooks, workflows, guides, checklists, stock lists, production guides, and rules.
|
|
36
|
-
2. Check the target file itself: it should state its role, scope, update trigger, owner or responsible workflow when known, and what must not be inferred from it.
|
|
37
|
-
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
|
-
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
|
-
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, 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
|
-
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
|
-
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
|
-
|
|
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.
|
|
45
|
-
|
|
46
|
-
Output format:
|
|
47
|
-
|
|
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.
|
|
50
|
-
- Already bridged: list the governance links that are present.
|
|
51
|
-
- Gaps: list missing links and why they matter for the next agent.
|
|
52
|
-
- Not applicable: list skipped layers with a reason.
|
|
53
|
-
- Suggested patches: list exact files and sections to update.
|
|
54
|
-
- Manual decisions: list duplicates, naming choices, deletion, renaming, external sync, or ownership questions requiring user confirmation.
|
|
55
|
-
- Acceptance: give one concrete check that proves the bridge is complete.
|
|
56
|
-
|
|
57
|
-
## Generated Artifact Governance Workflow
|
|
58
|
-
|
|
59
|
-
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.
|
|
60
|
-
|
|
61
|
-
1. List the artifacts created or materially changed in this task.
|
|
62
|
-
2. Classify each artifact: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary.
|
|
63
|
-
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.
|
|
64
|
-
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.
|
|
65
|
-
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.
|
|
66
|
-
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.
|
|
67
|
-
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.
|
|
68
|
-
|
|
69
|
-
## Long-term Governance Routing
|
|
70
|
-
|
|
71
|
-
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.
|
|
72
|
-
|
|
73
|
-
1. Classify the knowledge before writing:
|
|
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.
|
|
75
|
-
- Current task state, recommended next action with reason, unresolved risk, or startup-needed fact -> `dev/SESSION_HANDOFF.md`.
|
|
76
|
-
- Chronological evidence or validation trace -> `dev/SESSION_LOG.md`.
|
|
77
|
-
- File maps, command maps, API reference locations, tool capability maps, and external source coordinates -> `dev/PROJECT_INDEX.md`.
|
|
78
|
-
- Sync obligations or external mirror duties -> `dev/DOC_SYNC_REGISTRY.md`.
|
|
79
|
-
- Durable decisions, architecture trade-offs, research-derived rationale, and long-term lessons -> `dev/PROJECT_DECISIONS.md`.
|
|
80
|
-
- Reusable procedures, recurring mistake prevention, API / MCP / tool-use rules -> the relevant rule pack, registered reference, or QA check.
|
|
81
|
-
- API / MCP / tool-use patterns -> project index / registered reference / integrations pack, depending on scope.
|
|
82
|
-
2. If the knowledge is reusable but no existing home fits, propose the smallest new registered reference or rule-pack patch. New runbooks remain last resort.
|
|
83
|
-
3. If the knowledge was first captured in `SESSION_LOG` or handoff for short-term continuity, promote it to the correct durable home before claiming it is long-term.
|
|
84
|
-
4. Add or update a QA check when the same failure class could recur and can be tested.
|
|
85
|
-
5. Keep governance bridge wording reserved for document orphan prevention. Do not relabel non-file governance as "file connected to Agent Handoff Kit".
|
|
86
|
-
|
|
87
|
-
## Checks
|
|
88
|
-
|
|
89
|
-
- Verify affected files are indexed or intentionally installed templates.
|
|
90
|
-
- Check `dev/DOC_SYNC_REGISTRY.md` for governance, closeout/startup, and README sync rows.
|
|
91
|
-
- Confirm old overlapping wording was retired or marked legacy.
|
|
92
|
-
- Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
|
|
93
|
-
- Confirm every Markdown document or generated artifact created in this task is indexed, synced, consolidated, or explicitly classified as draft / temporary / one-time evidence.
|
|
94
|
-
- Confirm no new file has become a parallel source for an existing rule, requirement, checklist, or process.
|
|
95
|
-
- 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.
|
|
96
|
-
- 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.
|
|
97
|
-
- 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.
|
|
98
|
-
- Before claiming completion, apply the active root's core persistence gate and record the result only when that gate selects a checkpoint or full closeout; do not assume child or demo workspaces cover the parent/root workspace.
|
|
99
|
-
- For long-running projects, confirm `dev/PROJECT_DECISIONS.md` retains its four H2 sections in order (Evolution Timeline / Decisions Archive / Architecture Choices / Insights & Learnings) and that the closeout maintenance trigger check was recorded, with full maintenance applied where its trigger conditions were met.
|
|
100
|
-
|
|
101
|
-
## Closeout
|
|
102
|
-
|
|
103
|
-
Record the changed rule home, reason, complexity impact, retired wording, and follow-up checks.
|
|
1
|
+
# Agent Governance Pack
|
|
2
|
+
|
|
3
|
+
## Scope
|
|
4
|
+
|
|
5
|
+
Use for governance rules, prompts, agent instructions, handoff systems, startup/closeout behavior, skills, and rule packs.
|
|
6
|
+
|
|
7
|
+
## Load When
|
|
8
|
+
|
|
9
|
+
- User asks to change AI behavior, project governance, prompts, handoff, startup, closeout, or tool-use rules.
|
|
10
|
+
- A change affects `AGENTS.md`, `dev/*`, rule packs, installer templates, or durable workflow docs.
|
|
11
|
+
- User asks to bridge governance, connect a document to governance, scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
|
|
12
|
+
- User asks to make something long-term, cross-session, reusable, future sessions should remember an API / MCP / tool-use pattern, or uses equivalent Chinese phrases such as "寫入長期治理", "轉成長期機制", or "之後都要遵守".
|
|
13
|
+
- The task creates or materially changes Markdown documents, generated outputs, specifications, runbooks, checklists, guides, source-of-truth files, or research artifacts that future agents may need to discover.
|
|
14
|
+
|
|
15
|
+
## Rules
|
|
16
|
+
|
|
17
|
+
1. Locate the existing source of truth before adding a rule.
|
|
18
|
+
2. Prefer merge, replace, or registry rows over append-only rule growth.
|
|
19
|
+
3. Keep public runtime rules generic; project-specific incidents belong in logs, runbooks, or project index.
|
|
20
|
+
4. Do not let development-only workspace rules enter public runtime.
|
|
21
|
+
5. Check complexity budget before adding default-core behavior.
|
|
22
|
+
6. Before creating durable workflow, runbook, or instruction files, first classify the knowledge type and verify whether an existing home can carry it without a new file: current state belongs in `dev/SESSION_HANDOFF.md`; trace evidence belongs in `dev/SESSION_LOG.md`; file / command / reference maps belong in `dev/PROJECT_INDEX.md`; sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`; reusable operating procedures belong in the relevant rule pack or registered reference. New runbooks are last resort only.
|
|
23
|
+
7. When a task uses external skills, subagents, demo workspaces, or another tool's closeout, treat those flows as subordinate to the active root's Agent Handoff Kit governance. The active root still needs the `runtime-core/AGENTS.core.md` persistence gate decision; do not duplicate the gate thresholds in this pack.
|
|
24
|
+
8. For long-running projects, maintain `dev/PROJECT_DECISIONS.md` per R-028 closeout discipline (see `runtime-core/AGENTS.core.md` closeout maintenance trigger check): capture major decisions when they happen, run the short trigger check at every closeout, and do full long-term maintenance only when a hard trigger, semantic trigger, or 10-closeout backstop applies. Short single-task projects keep this as a no-op default; users are not expected to edit this file manually.
|
|
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.
|
|
26
|
+
10. Content-based trigger: long-term governance routing is content-based, not trigger-only. Even if the user does not use explicit governance-routing phrases, treat a statement as durable governance when it says future sessions must follow it, when it corrects a recurring AI mistake, or when it defines a reusable API / MCP / tool-use pattern. Do not persist long-term governance knowledge only in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or `START_NEXT_SESSION_PROMPT.txt`; those surfaces may be compressed, archived, or regenerated.
|
|
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.
|
|
30
|
+
|
|
31
|
+
## Governance Bridge Workflow
|
|
32
|
+
|
|
33
|
+
Use this workflow when the user asks for governance bridge, connect this document to governance, asks to scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
|
|
34
|
+
|
|
35
|
+
1. Identify the target. If the user named a file, inspect that file and its surrounding directory. If no file is named, run a bounded repo scan for likely durable documents such as source-of-truth files, runbooks, workflows, guides, checklists, stock lists, production guides, and rules.
|
|
36
|
+
2. Check the target file itself: it should state its role, scope, update trigger, owner or responsible workflow when known, and what must not be inferred from it.
|
|
37
|
+
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
|
+
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
|
+
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, 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
|
+
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
|
+
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
|
+
|
|
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.
|
|
45
|
+
|
|
46
|
+
Output format:
|
|
47
|
+
|
|
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.
|
|
50
|
+
- Already bridged: list the governance links that are present.
|
|
51
|
+
- Gaps: list missing links and why they matter for the next agent.
|
|
52
|
+
- Not applicable: list skipped layers with a reason.
|
|
53
|
+
- Suggested patches: list exact files and sections to update.
|
|
54
|
+
- Manual decisions: list duplicates, naming choices, deletion, renaming, external sync, or ownership questions requiring user confirmation.
|
|
55
|
+
- Acceptance: give one concrete check that proves the bridge is complete.
|
|
56
|
+
|
|
57
|
+
## Generated Artifact Governance Workflow
|
|
58
|
+
|
|
59
|
+
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.
|
|
60
|
+
|
|
61
|
+
1. List the artifacts created or materially changed in this task.
|
|
62
|
+
2. Classify each artifact: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary.
|
|
63
|
+
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.
|
|
64
|
+
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.
|
|
65
|
+
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.
|
|
66
|
+
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.
|
|
67
|
+
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.
|
|
68
|
+
|
|
69
|
+
## Long-term Governance Routing
|
|
70
|
+
|
|
71
|
+
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.
|
|
72
|
+
|
|
73
|
+
1. Classify the knowledge before writing:
|
|
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.
|
|
75
|
+
- Current task state, recommended next action with reason, unresolved risk, or startup-needed fact -> `dev/SESSION_HANDOFF.md`.
|
|
76
|
+
- Chronological evidence or validation trace -> `dev/SESSION_LOG.md`.
|
|
77
|
+
- File maps, command maps, API reference locations, tool capability maps, and external source coordinates -> `dev/PROJECT_INDEX.md`.
|
|
78
|
+
- Sync obligations or external mirror duties -> `dev/DOC_SYNC_REGISTRY.md`.
|
|
79
|
+
- Durable decisions, architecture trade-offs, research-derived rationale, and long-term lessons -> `dev/PROJECT_DECISIONS.md`.
|
|
80
|
+
- Reusable procedures, recurring mistake prevention, API / MCP / tool-use rules -> the relevant rule pack, registered reference, or QA check.
|
|
81
|
+
- API / MCP / tool-use patterns -> project index / registered reference / integrations pack, depending on scope.
|
|
82
|
+
2. If the knowledge is reusable but no existing home fits, propose the smallest new registered reference or rule-pack patch. New runbooks remain last resort.
|
|
83
|
+
3. If the knowledge was first captured in `SESSION_LOG` or handoff for short-term continuity, promote it to the correct durable home before claiming it is long-term.
|
|
84
|
+
4. Add or update a QA check when the same failure class could recur and can be tested.
|
|
85
|
+
5. Keep governance bridge wording reserved for document orphan prevention. Do not relabel non-file governance as "file connected to Agent Handoff Kit".
|
|
86
|
+
|
|
87
|
+
## Checks
|
|
88
|
+
|
|
89
|
+
- Verify affected files are indexed or intentionally installed templates.
|
|
90
|
+
- Check `dev/DOC_SYNC_REGISTRY.md` for governance, closeout/startup, and README sync rows.
|
|
91
|
+
- Confirm old overlapping wording was retired or marked legacy.
|
|
92
|
+
- Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
|
|
93
|
+
- Confirm every Markdown document or generated artifact created in this task is indexed, synced, consolidated, or explicitly classified as draft / temporary / one-time evidence.
|
|
94
|
+
- Confirm no new file has become a parallel source for an existing rule, requirement, checklist, or process.
|
|
95
|
+
- 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.
|
|
96
|
+
- 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.
|
|
97
|
+
- 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.
|
|
98
|
+
- Before claiming completion, apply the active root's core persistence gate and record the result only when that gate selects a checkpoint or full closeout; do not assume child or demo workspaces cover the parent/root workspace.
|
|
99
|
+
- For long-running projects, confirm `dev/PROJECT_DECISIONS.md` retains its four H2 sections in order (Evolution Timeline / Decisions Archive / Architecture Choices / Insights & Learnings) and that the closeout maintenance trigger check was recorded, with full maintenance applied where its trigger conditions were met.
|
|
100
|
+
|
|
101
|
+
## Closeout
|
|
102
|
+
|
|
103
|
+
Record the changed rule home, reason, complexity impact, retired wording, and follow-up checks.
|