@adamchanadam/agent-handoff-kit 0.3.12 → 0.3.14

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.
@@ -0,0 +1,110 @@
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 copyMarker = "📋 Next session: copy and paste the whole block below";
7
+
8
+ export function assessPromptMirrorRoot(root) {
9
+ const handoffPath = path.join(root, "dev", "SESSION_HANDOFF.md");
10
+ const promptPath = path.join(root, "START_NEXT_SESSION_PROMPT.txt");
11
+ let handoffText = "";
12
+ let promptText = "";
13
+
14
+ try {
15
+ handoffText = readFileSync(handoffPath, "utf8");
16
+ } catch {
17
+ return { status: "missing", ok: false, reason: "handoff unreadable" };
18
+ }
19
+
20
+ try {
21
+ promptText = readFileSync(promptPath, "utf8");
22
+ } catch {
23
+ return { status: "missing", ok: false, reason: "prompt copy unreadable" };
24
+ }
25
+
26
+ return assessPromptMirrorTexts(handoffText, promptText);
27
+ }
28
+
29
+ export function assessPromptMirrorTexts(handoffText, promptText) {
30
+ const openingMessage = extractOpeningMessage(handoffText);
31
+ if (openingMessage == null) {
32
+ return {
33
+ status: "missing",
34
+ ok: false,
35
+ reason: "handoff opening message missing"
36
+ };
37
+ }
38
+
39
+ if (openingMessage === promptText) {
40
+ return {
41
+ status: "match",
42
+ ok: true,
43
+ reason: "",
44
+ openingMessage,
45
+ firstDiff: null
46
+ };
47
+ }
48
+
49
+ const normalizedOpening = normalizePrompt(openingMessage);
50
+ const normalizedPrompt = normalizePrompt(promptText);
51
+ if (normalizedOpening === normalizedPrompt) {
52
+ return {
53
+ status: "newline-only",
54
+ ok: true,
55
+ reason: "only newline style or final newline differs",
56
+ openingMessage,
57
+ firstDiff: null
58
+ };
59
+ }
60
+
61
+ return {
62
+ status: "mismatch",
63
+ ok: false,
64
+ reason: "convenience copy differs from dev/SESSION_HANDOFF.md",
65
+ openingMessage,
66
+ firstDiff: firstDiff(normalizedOpening, normalizedPrompt)
67
+ };
68
+ }
69
+
70
+ export function extractOpeningMessage(text) {
71
+ const sectionStart = findOpeningSectionStart(text);
72
+ if (sectionStart < 0) return null;
73
+
74
+ const sectionText = text.slice(sectionStart);
75
+ const markerIndex = sectionText.indexOf(copyMarker);
76
+ if (markerIndex < 0) return null;
77
+
78
+ const afterMarker = sectionText.slice(markerIndex + copyMarker.length);
79
+ const fenceMatch = /```text[^\r\n]*(?:\r\n?|\n)([\s\S]*?)(?:\r\n?|\n)```/.exec(afterMarker);
80
+ if (!fenceMatch) return null;
81
+ return fenceMatch[1];
82
+ }
83
+
84
+ export function normalizePrompt(text) {
85
+ return text.replace(/\r\n?/g, "\n").replace(/\n+$/g, "");
86
+ }
87
+
88
+ function findOpeningSectionStart(text) {
89
+ const markerIndex = text.indexOf(openingSectionMarker);
90
+ if (markerIndex >= 0) return markerIndex;
91
+
92
+ const headingMatch = openingHeadingPattern.exec(text);
93
+ return headingMatch ? headingMatch.index : -1;
94
+ }
95
+
96
+ function firstDiff(left, right) {
97
+ const leftLines = left.split("\n");
98
+ const rightLines = right.split("\n");
99
+ const count = Math.max(leftLines.length, rightLines.length);
100
+ for (let index = 0; index < count; index += 1) {
101
+ if ((leftLines[index] ?? "") !== (rightLines[index] ?? "")) {
102
+ return {
103
+ line: index + 1,
104
+ handoff: leftLines[index] ?? "",
105
+ prompt: rightLines[index] ?? ""
106
+ };
107
+ }
108
+ }
109
+ return null;
110
+ }
@@ -0,0 +1,23 @@
1
+ # v0.3.13
2
+
3
+ ## 本版新加了甚麼
4
+
5
+ 本版修正升級後自動檢查失敗時的下一步提示。若 `upgrade` 已經執行,但自動 `doctor` 發現某個保留檔案真的缺少必要段落,CLI 會列出缺失檔案、檢查名稱與缺少文字,並給出交給 AI 非破壞性修補的步驟;不再只叫新手回頭跑 `upgrade --dry-run`。
6
+
7
+ 同時,本版把可重用操作程序的歸位規則收斂到既有 `agent-governance` pack:長期操作方法應進入相關 rule pack 或已登記 reference,不應只寫入 handoff / log 當作完成。
8
+
9
+ ## 對你已有檔案的影響
10
+
11
+ 既有項目不用重裝。`START_NEXT_SESSION_PROMPT.txt` 仍只是 closeout 便利副本;若它只是落後於 `dev/SESSION_HANDOFF.md`,普通 `doctor` 只會提醒,不會把項目判定為失敗。
12
+
13
+ 若升級後看到 anchor 缺失,代表某個保留檔案缺少 Kit 需要的固定段落。工具不會覆寫你的內容;你應把完整 `doctor` 輸出交給 AI,請它按缺失文字補回對應段落。
14
+
15
+ ## 建議下一步
16
+
17
+ 升級前可先預演:
18
+
19
+ ```bash
20
+ npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
21
+ ```
22
+
23
+ 如果預演沒有 conflict,再執行正式升級。正式升級後若自動檢查失敗,請按 CLI 顯示的「怎樣修」步驟交給 AI 修補;不要把 `upgrade --dry-run` 當成修補動作。
@@ -0,0 +1,29 @@
1
+ # v0.3.14
2
+
3
+ ## 本版新加了甚麼
4
+
5
+ 本版修正舊版項目跨版本升級時的交接狀態誤判。部分由很早期版本升級的項目,`upgrade` 會補入新的 lifecycle 欄位;舊工具曾把欄位填成 `TBD`,然後同一次升級後自動 `doctor` 又把這個 `TBD` 判定為失敗。
6
+
7
+ 現在升級工具會把這類欄位明確標記為「由升級重新分類,下一次 closeout 再核對」,避免工具自己寫入一個會被自己拒絕的值。
8
+
9
+ 同時,本版把 rules / packs 路由與可重用程序入庫範圍加入發佈前全面檢,確認自然語言任務能導向相應 pack,而不是隨意新建治理文件或只寫在 handoff / log。
10
+
11
+ 另外,本版把 `START_NEXT_SESSION_PROMPT.txt` 與 handoff opening message 的比對方法收斂到固定檢查器。檢查器會先錨定真正的下一次開工訊息,再正規化 CRLF / LF 換行符,避免只因換行風格不同就誤報內容不一致。
12
+
13
+ ## 對你已有檔案的影響
14
+
15
+ 既有項目不用重裝。若你是由舊版 Kit 升級,工具可能會在 `dev/SESSION_HANDOFF.md` 補入 lifecycle consistency 欄位;這是為了讓下一次 closeout 能核對「已完成的事是否仍被帶成未解待辦」。
16
+
17
+ 工具仍會保留既有交接內容,不會用新版模板覆寫你的工作紀錄。若 `doctor` 指出其他真實缺失,仍應把完整輸出交給 AI 非破壞性修補。
18
+
19
+ 若只出現 prompt convenience copy 的換行符差異,這不是內容損壞;正常 `doctor` 不會因此阻擋你繼續工作。
20
+
21
+ ## 建議下一步
22
+
23
+ 已安裝舊版的項目可先預演:
24
+
25
+ ```bash
26
+ npx --yes @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
27
+ ```
28
+
29
+ 如果預演沒有 conflict,再執行正式升級。升級後若自動 `doctor` 通過,即可繼續使用;若仍有缺失,請把完整檢查輸出交給 AI 修補,不要用重裝覆寫既有內容。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.12",
3
+ "version": "0.3.14",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -18,10 +18,11 @@
18
18
  "doctor": "node bin/agent-handoff-kit.mjs doctor --root .",
19
19
  "dry-run": "node bin/agent-handoff-kit.mjs init --dry-run --root .",
20
20
  "qa:prototype": "node scripts/check-public-prototype.mjs",
21
- "qa:packs": "node scripts/check-pack-scenarios.mjs",
22
- "qa:upgrade": "node scripts/check-upgrade-safety.mjs",
23
- "qa:release": "node scripts/check-release-readiness.mjs",
24
- "qa:fixtures": "node scripts/generate-upgrade-fixtures.mjs"
21
+ "qa:packs": "node scripts/check-pack-scenarios.mjs",
22
+ "qa:upgrade": "node scripts/check-upgrade-safety.mjs",
23
+ "qa:release": "node scripts/check-release-readiness.mjs",
24
+ "qa:prompt-mirror": "node scripts/check-prompt-mirror.mjs",
25
+ "qa:fixtures": "node scripts/generate-upgrade-fixtures.mjs"
25
26
  },
26
27
  "engines": {
27
28
  "node": ">=18"
@@ -16,7 +16,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
16
16
  3. Keep public runtime rules generic; project-specific incidents belong in logs, runbooks, or project index.
17
17
  4. Do not let development-only workspace rules enter public runtime.
18
18
  5. Check complexity budget before adding default-core behavior.
19
- 6. Before creating durable workflow, runbook, or instruction files, first verify whether `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md`, `dev/DOC_SYNC_REGISTRY.md`, or existing rule packs can carry the need without a new file.
19
+ 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.
20
20
  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 its own handoff/log/index/registry persistence.
21
21
  8. For long-running projects, maintain `dev/PROJECT_DECISIONS.md` per R-028 closeout discipline (see `runtime-core/AGENTS.core.md` step 12): smart-detect substantive task evolution, multi-option architectural trade-offs, and cross-session patterns, then append entries to the appropriate H2 section. Short single-task projects keep this as a no-op default; users are not expected to edit this file manually.
22
22
 
@@ -26,6 +26,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
26
26
  - Check `dev/DOC_SYNC_REGISTRY.md` for governance, closeout/startup, and README sync rows.
27
27
  - Confirm old overlapping wording was retired or marked legacy.
28
28
  - Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
29
+ - 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.
29
30
  - Before claiming completion, inspect the active root's `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, and `dev/DOC_SYNC_REGISTRY.md`; do not assume child or demo workspaces cover the parent/root workspace.
30
31
  - 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 closeout step 12 was applied where its trigger conditions were met.
31
32
 
package/packs/safety.md CHANGED
@@ -1,10 +1,16 @@
1
1
  # Safety Pack
2
2
 
3
- ## Scope
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.
6
-
7
- ## Rules
3
+ ## Scope
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.
6
+
7
+ ## Load When
8
+
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.
11
+ - Another pack is loaded but the task includes data-loss, credential, permission, external-system, or irreversible-operation risk.
12
+
13
+ ## Rules
8
14
 
9
15
  1. Before deleting, overwriting, moving, renaming, cleaning, resetting, publishing, or running destructive tool operations, list the exact target paths, expected scope, impact, and required confirmation.
10
16
  2. Preserve user-provided source files by default. Create renamed outputs instead of in-place overwrites unless overwrite is explicitly requested.
@@ -51,7 +51,7 @@ Use this loop for every task:
51
51
  2. READ: inspect relevant files from `PROJECT_INDEX.md` and search for related definitions before editing.
52
52
  3. CHANGE: make focused changes only.
53
53
  4. QC: run available checks or state why they cannot run.
54
- 5. PERSIST: update handoff/log and any affected project index or sync registry.
54
+ 5. PERSIST: classify durable facts before writing them. Current state belongs in handoff, chronological evidence in log, file / command / reference maps in project index, sync obligations in doc sync registry, and reusable operating procedure in the relevant rule pack or registered reference. Do not store reusable procedure knowledge only in handoff or log.
55
55
 
56
56
  External skill flows, subagents, task plans, or another tool's "finish" step do not replace this loop. If you use any of them, the PLAN must include a final Agent Handoff Kit persistence step for the active project root, and completion cannot be claimed until that root's `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, and `dev/DOC_SYNC_REGISTRY.md` have been inspected and updated or explicitly marked not applicable.
57
57
 
@@ -144,7 +144,7 @@ A pack may add task-specific requirements. A pack cannot weaken core safety. If
144
144
 
145
145
  When a task references external tools (Notion / Google Drive / Slack / Linear / GitHub / Dropbox / HubSpot / Atlassian / etc.) or `dev/PROJECT_INDEX.md` `## Installed Integrations` is non-empty, load `dev/rules/integrations.md` together with the relevant domain pack. The integrations pack covers Connector-first defaults, credential separation, multi-layer source-of-truth architecture, and cross-session resilience for declared integrations.
146
146
 
147
- After the task, persist durable facts into handoff/log/index/registry. Do not assume the next session remembers pack context unless it is recorded.
147
+ After the task, persist durable facts into the correct home: handoff for current state, log for trace evidence, project index for file / command / reference maps, doc sync registry for sync obligations, and rule packs or registered references for reusable operating procedures. Do not assume the next session remembers pack context unless it is recorded, and do not treat handoff/log persistence as sufficient for reusable procedure knowledge.
148
148
 
149
149
  If a pack, skill, subagent plan, demo workspace, or external workflow produces its own closeout, treat it as subordinate evidence. The active project root still needs Agent Handoff Kit persistence before the task is complete.
150
150