@adamchanadam/agent-handoff-kit 0.1.7 → 0.1.8

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 CHANGED
@@ -1,6 +1,6 @@
1
1
  # Agent Handoff Kit
2
2
 
3
- 狀態:`v0.1.7` 已正式發佈到 GitHub 與 npm。這是早期可用版本,尚未宣稱所有需求已完成。
3
+ 狀態:`v0.1.8` 已正式發佈到 GitHub 與 npm。這是早期可用版本,尚未宣稱所有需求已完成。
4
4
 
5
5
  ![Agent Handoff Kit 主視覺](https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-main-visual2.png)
6
6
 
@@ -8,7 +8,7 @@ Agent Handoff Kit 是 **AI Session 之間的接力棒**。
8
8
 
9
9
  它只處理一件狹窄但重要的事:AI 跨對話失憶。每次開新對話,AI 往往不記得你上次做到哪裡,也認不出中途新建的文件、你引入的參考資料、哪些檔案是真源。這套工具把進度、下一步、風險、檔案登記與下次開工提示寫進固定文件,讓下一個 AI 工具能接得上上一棒。
10
10
 
11
- 想先看非技術版介紹,可打開 GitHub Pages 上的 [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html)。那一頁是新手 60 秒入門,README 則保留安裝、日常使用與限制。
11
+ 想先看非技術版介紹,可打開 GitHub Pages 上的 [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html) —— 新手 60 秒入門。看完想睇實際操作示範,可開 [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html) —— 兩個日常情景(整理電腦下載目錄、開咖啡店市場調查)嘅七步流程完整示範。README 則保留安裝、日常使用與限制。
12
12
 
13
13
  ## 它解決甚麼問題
14
14
 
@@ -106,7 +106,7 @@ dev/rules/*.md
106
106
  | `GEMINI.md` | 讓 Gemini CLI 找到同一套入口。 |
107
107
  | `START_NEXT_SESSION_PROMPT.txt` | 下次開工時可直接貼上的便利副本;由 handoff 產生。 |
108
108
  | `dev/SESSION_HANDOFF.md` | 保存目前狀態、下一步、風險、驗收結果與下一次開工文字。 |
109
- | `dev/SESSION_LOG.md` | 保存近期實際做過的事與檢查結果。 |
109
+ | `dev/SESSION_LOG.md` | 保存近期實際做過的事與檢查結果。主檔長期保持短小;N=11+ 嘅舊條目自動 archive 至 `dev/SESSION_LOG_archive/`,trace-back 用。接力靠 `SESSION_HANDOFF.md`,本檔屬冷資料層。 |
110
110
  | `dev/PROJECT_INDEX.md` | 記錄專案檔案、必讀資料、外部來源與常用檢查。 |
111
111
  | `dev/DOC_SYNC_REGISTRY.md` | 記錄哪些文件改動後需要同步。 |
112
112
  | `dev/RULE_PACKS.md` | 告訴 AI 不同任務應讀哪些工作規則。 |
@@ -197,11 +197,11 @@ npm package 只包含安裝所需內容:
197
197
  - `LICENSE`
198
198
  - `package.json`
199
199
 
200
- GitHub Pages 上的新手介紹頁 `agent-handoff-kit-intro.html` 由原始碼倉庫根目錄發佈;`agent-handoff-kit-intro.html` 與 `images/` 是原始碼倉庫資產,不會安裝到你的專案。
200
+ GitHub Pages 上的兩個 onboarding 頁 —— [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html)(60 秒入門)與 [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html)(實操指南)—— 由原始碼倉庫根目錄發佈;兩個 HTML 與 `images/` 是原始碼倉庫資產,不會安裝到你的專案。
201
201
 
202
202
  ## 目前限制
203
203
 
204
- - `v0.1.7` 是 GitHub 與 npm 同步發佈版本。
204
+ - `v0.1.8` 是 GitHub 與 npm 同步發佈版本。
205
205
  - 這是早期可用版本,尚未宣稱完整穩定。
206
206
  - 升級合併仍是窄範圍策略,不是完整的複雜合併工具。
207
207
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
@@ -479,11 +479,22 @@ async function runDoctor(root, version, options = {}) {
479
479
  return "failed";
480
480
  }
481
481
 
482
+ // R-010 SESSION_LOG handoff-role discipline check (warn-only; does not change mode or exit).
483
+ const disciplineResult = await assessSessionLogDiscipline(root);
484
+ console.log(`\nSESSION_LOG discipline (R-010): ${disciplineResult.ok ? "ok" : "warn"}`);
485
+ if (!disciplineResult.ok) {
486
+ for (const warning of disciplineResult.warnings) {
487
+ console.log(` warn: ${warning}`);
488
+ }
489
+ }
490
+
482
491
  printDoctorSummary(version, root, "healthy", {
483
- checked: rows.length + anchorRows.length + schemaRows.length + mirrorRows.length,
492
+ checked: rows.length + anchorRows.length + schemaRows.length + mirrorRows.length + 1,
484
493
  failedKind: null,
485
494
  failedCount: 0,
486
- nextStep: "繼續日常使用;如要升級到較新版,執行 npx @adamchanadam/agent-handoff-kit@latest upgrade。"
495
+ nextStep: disciplineResult.ok
496
+ ? "繼續日常使用;如要升級到較新版,執行 npx @adamchanadam/agent-handoff-kit@latest upgrade。"
497
+ : "繼續使用;下次 closeout 時 AI 應自動執行 R-010 N 規則推進(見上面 warn 行)。如未動請要求 AI 重做 closeout。"
487
498
  });
488
499
  return "passed";
489
500
  }
@@ -699,6 +710,41 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
699
710
  return { ...base, action: "skip", reason: "preserve existing file" };
700
711
  }
701
712
 
713
+ // R-010 SESSION_LOG handoff-role discipline (warn-only doctor check).
714
+ // Returns { ok, warnings } where:
715
+ // - ok: true if no warnings triggered
716
+ // - warnings: array of Chinese, actionable warning strings
717
+ // Thresholds (all warn-only; doctor exit unaffected):
718
+ // - H2 entry count ≥ 11 → warn (archive boundary; AI closeout flow should auto-advance)
719
+ // - H2 entry count ≥ 25 → warn (severe drift; suggest AI re-do closeout)
720
+ // - line count ≥ 1500 → warn (anomalous entry size; safety net)
721
+ async function assessSessionLogDiscipline(root) {
722
+ const logPath = path.join(root, "dev/SESSION_LOG.md");
723
+ let text = "";
724
+ try {
725
+ text = await readFile(logPath, "utf8");
726
+ } catch {
727
+ return { ok: false, warnings: ["dev/SESSION_LOG.md unreadable; discipline check skipped"] };
728
+ }
729
+
730
+ const warnings = [];
731
+ const entryMatches = text.match(/^## \d{4}-\d{2}-\d{2}/gm) || [];
732
+ const entryCount = entryMatches.length;
733
+ const lineCount = text.split("\n").length;
734
+
735
+ if (entryCount >= 25) {
736
+ warnings.push(`SESSION_LOG entry count = ${entryCount}(嚴重超過 N=11+ archive 邊界;R-010 嘅 AI closeout flow 應該已自動推進,如未動請要求 AI 跟 R-010 重做 closeout)`);
737
+ } else if (entryCount >= 11) {
738
+ warnings.push(`SESSION_LOG entry count = ${entryCount}(達 N=11+ archive 邊界;下次 closeout 時 AI 應自動執行 N 規則推進,如未動請提醒)`);
739
+ }
740
+
741
+ if (lineCount >= 1500) {
742
+ warnings.push(`SESSION_LOG line count = ${lineCount}(超過 1500 安全網閾值;可能 entry 異常長)`);
743
+ }
744
+
745
+ return { ok: warnings.length === 0, warnings };
746
+ }
747
+
702
748
  // R-024 唯一真源:AGENTS.md 健康判斷合三為一函數。
703
749
  // Returns { state, evidence } where state ∈ { clean, needs-merge, conflict }.
704
750
  // - clean: structurally healthy
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.1.7",
3
+ "version": "0.1.8",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -84,6 +84,7 @@ At full closeout:
84
84
  8. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
85
85
  9. Show a short closeout card, then provide a copy-paste-ready next-session opening message inside a fenced `text` code block, so the user can clearly copy and paste it into the next session.
86
86
  10. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the fenced opening message in `dev/SESSION_HANDOFF.md`. `dev/SESSION_HANDOFF.md` is authoritative; `START_NEXT_SESSION_PROMPT.txt` is only a convenience copy for the user to paste at the next startup.
87
+ 11. Advance the SESSION_LOG N-rule (R-010 SESSION_LOG handoff-role discipline). After prepending the new closeout entry, count `## YYYY-MM-DD` H2 entries in `dev/SESSION_LOG.md`. Any entry now at position N ≥ 11 (oldest end) must be moved into `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` with raw content preserved. Maintain `dev/SESSION_LOG_archive/INDEX.md` (master index of all archive batches; create on first archive). Entries at N=4–10 whose core facts are already absorbed into HANDOFF / PROJECT_INDEX / requirements / decision records collapse to a short-index line using structural anchors, not line numbers. Entries with unique narrative not yet absorbed must first be ported into the relevant durable source, then collapsed. This is mandatory; do not skip. Handoff capability rests on `dev/SESSION_HANDOFF.md`; `dev/SESSION_LOG.md` is trace-back / audit trail and does not carry handoff responsibility.
87
88
 
88
89
  Installed handoff templates use English headings by default for cross-tool stability, but project teams may translate `dev/SESSION_HANDOFF.md` section headings and visible field labels into the project's working language. Keep the `ack:section:*` and `ack:field:*` semantic markers intact; `doctor` validates those markers so localized handoff notes remain supported.
89
90
 
@@ -1,5 +1,7 @@
1
1
  # Session Log
2
2
 
3
+ > **Handoff role**: This log is the trace-back / audit trail layer. Handoff capability rests on `dev/SESSION_HANDOFF.md`. The next AI session can continue by reading `AGENTS.md` + `dev/SESSION_HANDOFF.md` + `dev/PROJECT_INDEX.md` + needed rule packs; reading this log is not required for continuity. Each closeout must advance the N-rule per `AGENTS.md` `## Closeout And Handoff` step 11 (R-010 SESSION_LOG handoff-role discipline): N=1–3 keep full, N=4–10 short-index after absorbed-source check, N=11+ archive into `dev/SESSION_LOG_archive/`.
4
+
3
5
  Add new session entries at the top. Record what actually happened in the session; do not copy old completed work forward as new work.
4
6
 
5
7
  This log carries recent evidence, not current state. Put the current objective, next action, risks, and workspace identity in `dev/SESSION_HANDOFF.md`.