@adamchanadam/agent-handoff-kit 0.3.67 → 0.4.1

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.
@@ -1,170 +1,180 @@
1
- # Session Handoff
2
-
3
- Last Updated: TBD
4
-
5
- <!-- ack:section:durable-anchors -->
6
- ## Durable Anchors
7
-
8
- Stable facts that should survive across sessions. Update only when they change, but verify they still match reality at closeout.
9
-
10
- 1. Project root and boundary: TBD
11
- 2. Product/system identity: TBD
12
- 3. Governance model: TBD
13
- 4. Source-of-truth ownership: TBD
14
- 5. Release / publish boundary: TBD
15
- 6. Installed Integrations registry: `dev/PROJECT_INDEX.md` `## Installed Integrations` is the declaration source. Probe only immediately before actual use, when the current objective names an integration dependency, or when the user asks for a health check. Credential values never appear in `dev/*`; record references only.
16
-
17
- <!-- ack:section:closeout-reconciled-state -->
1
+ # Session Handoff
2
+
3
+ Last Updated: TBD
4
+
5
+ <!-- ack:section:durable-anchors -->
6
+ ## Durable Anchors
7
+
8
+ Stable facts that should survive across sessions. Update only when they change, but verify they still match reality at closeout.
9
+
10
+ 1. Project root and boundary: TBD
11
+ 2. Product/system identity: TBD
12
+ 3. Governance model: TBD
13
+ 4. Source-of-truth ownership: TBD
14
+ 5. Release / publish boundary: TBD
15
+ 6. Installed Integrations registry: `dev/PROJECT_INDEX.md` `## Installed Integrations` is the declaration source. Probe only immediately before actual use, when the current objective names an integration dependency, or when the user asks for a health check. Credential values never appear in `dev/*`; record references only.
16
+
17
+ <!-- ack:section:closeout-reconciled-state -->
18
18
  ## Closeout-Reconciled State
19
19
 
20
20
  This is the current-state area. At every full closeout, update only sections whose current truth changed; leave already-current sections byte-stable where practical and record checked/no-op only when useful. Do not append a new state snapshot under an old one.
21
21
 
22
- Pre-closeout checkpoint edits, when explicitly authorized or required by the core Persistence Gate, update only the named hot current-state field(s) or one concise log entry. Historical evidence, old validation records, completed-work narratives, and unchanged durable anchors are cold zones: preserve them byte-for-byte where practical instead of rewording, reordering, or refreshing them because another AI might otherwise read stale context.
22
+ Pre-closeout checkpoint edits, when explicitly authorized or required by the core Persistence Gate, update only the named hot current-state field(s) or one concise log entry. Apply the core Persistence Gate's bounded opening-consistency rule when the changed current facts are repeated in the opening. Historical evidence, old validation records, completed-work narratives, and unchanged durable anchors are cold zones: preserve them byte-for-byte where practical instead of rewording, reordering, or refreshing them because another AI might otherwise read stale context.
23
23
 
24
24
  <!-- ack:section:current-baseline -->
25
25
  ## Current Baseline
26
-
27
- 1. Project root: TBD
28
- 2. Product/system state: TBD
29
- 3. Governance state: TBD
30
- 4. Source-of-truth notes: TBD
31
- <!-- ack:field:first-use-guidance-state -->
32
- 5. First-use guidance state: eligible
33
-
34
- <!-- ack:section:task-understanding-summary -->
35
- ## Task Understanding Summary
36
-
37
- <!-- ack:field:user-intent -->
38
- - User intent: TBD
39
- <!-- ack:field:task-essence -->
40
- - Task essence: TBD
26
+
27
+ 1. Project root: TBD
28
+ 2. Product/system state: TBD
29
+ 3. Governance state: TBD
30
+ 4. Source-of-truth notes: TBD
31
+ <!-- ack:field:first-use-guidance-state -->
32
+ 5. First-use guidance state: eligible
33
+
34
+ <!-- ack:section:task-understanding-summary -->
35
+ ## Task Understanding Summary
36
+
37
+ <!-- ack:field:user-intent -->
38
+ - User intent: TBD
39
+ <!-- ack:field:task-essence -->
40
+ - Task essence: TBD
41
41
  - User value: TBD
42
42
  - Parent outcome / consumer: TBD
43
43
  - Task position: TBD — parent -> current step and how this step advances it; use standalone when this is the whole task, unknown when not established.
44
- <!-- ack:field:success-criteria -->
45
- - Success criteria: TBD
46
- - Key background already read: TBD
47
- - Background still unread or blocked: TBD
48
- - Non-goals / boundaries: TBD
49
-
50
- <!-- ack:section:active-objective -->
44
+ <!-- ack:field:success-criteria -->
45
+ - Success criteria: TBD
46
+ - Key background already read: TBD
47
+ - Background still unread or blocked: TBD
48
+ - Decision-changing corrections / accepted or rejected approaches and reasons: TBD — preserve what would change the next agent's action, not the whole conversation.
49
+ - Non-goals / boundaries: TBD
50
+
51
+ <!-- ack:section:active-objective -->
51
52
  ## Active Objective
52
53
 
53
54
  - Current step: TBD
54
55
  - Resume point: TBD — next bounded action, target and last verified result; distinguish finished preparation from unfinished work.
55
56
  - Remaining acceptance: TBD — what still proves the current step and the parent outcome; if complete, cite evidence rather than infer from child completion.
56
-
57
- <!-- ack:section:completed-this-session -->
58
- ## Completed This Session
59
-
60
- Record only work actually completed in the current session.
61
-
62
- 1. TBD
63
-
64
- <!-- ack:section:next-priorities -->
65
- ## Next Priorities
66
-
67
- Recommended next step: TBD — reason: TBD
68
-
69
- 1. TBD
70
-
71
- <!-- ack:section:next-task-required-reading -->
72
- ## Next Task Required Reading
73
-
57
+ - Reusable work / remaining obligations: TBD — name actual artifacts, their evidence limits, remaining consequential work and its next consumer; preserve restrictions on reuse or retry.
58
+
59
+ <!-- ack:section:work-items -->
60
+ ## Work Items
61
+
62
+ Use concise human-readable titles and summaries for current meaningful work, not terminal microsteps. Keep stable IDs and explicit parent links; standalone work leaves Parent blank. Valid statuses: `planned`, `active`, `waiting`, `review`, `done`, `paused`, `dropped`. A child being done never completes its parent. Source is an optional existing project-relative result/reference path. Optional `Title zh-Hant` and `Summary zh-Hant` columns add short Chinese display text. Update changed rows during normal authorized state saving, not to refresh the dashboard; keep detailed evidence in its existing sections or log. Empty rows mean unknown, never completed. The dashboard validates this table and rejects invalid states, duplicate IDs, missing parents and cycles.
63
+
64
+ | ID | Title | Status | Parent | Summary | Source |
65
+ |---|---|---|---|---|---|
66
+
67
+ <!-- ack:section:completed-this-session -->
68
+ ## Completed This Session
69
+
70
+ Record only work actually completed in the current session.
71
+
72
+ 1. TBD
73
+
74
+ <!-- ack:section:next-priorities -->
75
+ ## Next Priorities
76
+
77
+ Recommended next step: TBD — reason: TBD
78
+
79
+ 1. TBD
80
+
81
+ <!-- ack:section:next-task-required-reading -->
82
+ ## Next Task Required Reading
83
+
74
84
  Before acting on the next task, read or mark blocked:
75
85
 
76
86
  In Source, identify the authoritative file/link, revision or unverified freshness, and relevant sections/range. In Why required, name the decision or acceptance it supports. In Status, record the previous session's actual depth (located / skimmed / relevant range read / verified), remaining unread scope, and what the next agent must read before acting. An old read claim is not a fresh read. For no required sources, state none with a reason; do not invent coverage.
77
-
78
- | Source | Why required | Status |
79
- |---|---|---|
80
- | TBD | TBD | pending |
81
-
82
- <!-- ack:section:risks-blockers -->
83
- ## Risks / Blockers
84
-
85
- 1. TBD
86
-
87
- <!-- ack:section:validation-qc -->
88
- ## Validation / QC
89
-
90
- - Checks run this session: TBD
91
- - Checks not run and why: TBD
92
- - Handoff evidence location: TBD
93
-
94
- <!-- ack:section:workspace-identity -->
95
- ## Workspace Identity
96
-
97
- Expected project root: TBD
98
- Git root: TBD
99
- Branch: TBD
100
- Commit: TBD
101
- Worktree / parallel workspace status: TBD
102
- Uncommitted changes summary: TBD
103
-
104
- <!-- ack:section:sync-status -->
105
- ## Sync Status
106
-
107
- Use statuses from `dev/DOC_SYNC_REGISTRY.md`: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.
108
-
109
- - Project index: TBD
110
- - Doc sync registry: TBD
111
- - Public docs / README: TBD
112
- - External knowledge tools: TBD
113
-
114
- <!-- ack:section:state-reconciliation-check -->
115
- ## State Reconciliation Check
116
-
117
- At full closeout, complete this check after updating the state sections above.
118
-
119
- - Reconciled at: TBD
120
- <!-- ack:field:state-sections-rewritten-or-confirmed -->
121
- - State sections rewritten or confirmed current: TBD
122
- <!-- ack:field:stale-snapshots-left -->
123
- - Stale snapshots left in this handoff: TBD
124
- <!-- ack:field:lifecycle-conflicts-resolved -->
125
- - Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD
126
- <!-- ack:field:persistence-routing-checked -->
127
- - Persistence routing checked: TBD
128
- <!-- ack:field:closeout-outcome -->
129
- - Closeout outcome: not_started — full closeout has not yet been assessed.
130
- <!-- ack:field:project-required-persistence -->
131
- - Project-required persistence: not_assessed — state whether this project's required Git or other persistence completed, is not required, or is blocked.
132
- <!-- ack:field:recommended-next-step-explicit -->
133
- - Recommended next step is explicit and reasoned: TBD
134
- <!-- ack:field:opening-message-matches-current-state -->
135
- - Opening message matches current state: TBD
136
- <!-- ack:field:next-ai-can-continue -->
137
- - Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD
138
-
139
- If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready. `Closeout outcome: complete` is allowed only when required writes, read-backs and project-required persistence are complete. If project-required persistence is blocked, use `Closeout outcome: blocked` and state the blocker; it is not a completed closeout.
140
-
141
- Lifecycle consistency rule: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message` as full content, including renamed or paraphrased work. 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. Doctor catches only mechanical contradictions and unresolved fields; its green result is not semantic proof. 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.
142
-
143
- Closeout-card rule: `closeout-status` reads only these existing handoff fields plus fresh doctor / mirror results; it does not create another persistence authority. Its `complete` card is the only permitted source for the user-facing `handoff saved` wording. A nonzero / `blocked` result must be shown as blocked, never summarized as completed.
144
-
145
- <!-- ack:section:handoff-sufficiency-check -->
146
- ## Handoff Sufficiency Check
147
-
148
- Can the next AI continue from `AGENTS.md`, this handoff, and only the project index / rule packs required by the next task, without searching old log history?
149
-
87
+
88
+ | Source | Why required | Status |
89
+ |---|---|---|
90
+ | TBD | TBD | pending |
91
+
92
+ <!-- ack:section:risks-blockers -->
93
+ ## Risks / Blockers
94
+
95
+ 1. TBD
96
+
97
+ <!-- ack:section:validation-qc -->
98
+ ## Validation / QC
99
+
100
+ - Checks run this session: TBD
101
+ - Checks not run and why: TBD
102
+ - Handoff evidence location: TBD
103
+
104
+ <!-- ack:section:workspace-identity -->
105
+ ## Workspace Identity
106
+
107
+ Expected project root: TBD
108
+ Git root: TBD
109
+ Branch: TBD
110
+ Commit: TBD
111
+ Worktree / parallel workspace status: TBD
112
+ Uncommitted changes summary: TBD
113
+
114
+ <!-- ack:section:sync-status -->
115
+ ## Sync Status
116
+
117
+ Use statuses from `dev/DOC_SYNC_REGISTRY.md`: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.
118
+
119
+ - Project index: TBD
120
+ - Doc sync registry: TBD
121
+ - Public docs / README: TBD
122
+ - External knowledge tools: TBD
123
+
124
+ <!-- ack:section:state-reconciliation-check -->
125
+ ## State Reconciliation Check
126
+
127
+ At full closeout, complete this check after updating the state sections above.
128
+
129
+ - Reconciled at: TBD
130
+ <!-- ack:field:state-sections-rewritten-or-confirmed -->
131
+ - State sections rewritten or confirmed current: TBD
132
+ <!-- ack:field:stale-snapshots-left -->
133
+ - Stale snapshots left in this handoff: TBD
134
+ <!-- ack:field:lifecycle-conflicts-resolved -->
135
+ - Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD
136
+ <!-- ack:field:persistence-routing-checked -->
137
+ - Persistence routing checked: TBD
138
+ <!-- ack:field:closeout-outcome -->
139
+ - Closeout outcome: not_started — full closeout has not yet been assessed.
140
+ <!-- ack:field:project-required-persistence -->
141
+ - Project-required persistence: not_assessed — state whether this project's required Git or other persistence completed, is not required, or is blocked.
142
+ <!-- ack:field:recommended-next-step-explicit -->
143
+ - Recommended next step is explicit and reasoned: TBD
144
+ <!-- ack:field:opening-message-matches-current-state -->
145
+ - Opening message matches current state: TBD
146
+ <!-- ack:field:next-ai-can-continue -->
147
+ - Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD
148
+
149
+ If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready. `Closeout outcome: complete` is allowed only when required writes, read-backs and project-required persistence are complete. If project-required persistence is blocked, use `Closeout outcome: blocked` and state the blocker; it is not a completed closeout.
150
+
151
+ Lifecycle consistency rule: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message` as full content, including renamed or paraphrased work. 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. Doctor catches only mechanical contradictions and unresolved fields; its green result is not semantic proof. 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.
152
+
153
+ Closeout-card rule: `closeout-status` reads only these existing handoff fields plus fresh doctor / mirror results; it does not create another persistence authority. Its `complete` card is the only permitted source for the user-facing `handoff saved` wording. A nonzero / `blocked` result must be shown as blocked, never summarized as completed.
154
+
155
+ <!-- ack:section:handoff-sufficiency-check -->
156
+ ## Handoff Sufficiency Check
157
+
158
+ Can the next AI continue from `AGENTS.md`, this handoff, and only the project index / rule packs required by the next task, without searching old log history?
159
+
150
160
  Answer: TBD
151
- Reconstruction evidence: TBD — apply the packet-only reconstruction check in `dev/rules/closeout.md`; cite the sections supporting the outcome, task position, resume point, remaining acceptance and source coverage. Record gaps explicitly; a bare yes is insufficient.
161
+ Reconstruction evidence: TBD — apply the packet-only reconstruction check in `dev/rules/closeout.md`; cite the sections supporting the outcome, task position, resume point, decisions/rejected approaches, reusable work, remaining obligations/acceptance, source coverage and permission boundaries. Record gaps explicitly; a bare yes is insufficient. This verifies the saved packet, not a future reader's reception or understanding.
152
162
  Keep the `Answer:` and `Reconstruction evidence:` labels. Use `yes`, `no` or `unknown` for Answer, followed by an explanation if needed. Narrative and section headings may use the project's language.
153
163
  If no, update this handoff before closeout. Unknown critical context blocks dependent work and is not permission to guess. A saved packet may honestly describe blocked work.
154
-
155
- Continuity rule: this file carries current state and next action. `dev/SESSION_LOG.md` carries recent evidence only. Archive old detail only when needed; do not create an archive directory by default.
156
-
157
- <!-- ack:section:next-session-opening-message -->
158
- ## Next Session Opening Message
159
-
164
+
165
+ Continuity rule: this file carries current state and next action. `dev/SESSION_LOG.md` carries recent evidence only. Archive old detail only when needed; do not create an archive directory by default.
166
+
167
+ <!-- ack:section:next-session-opening-message -->
168
+ ## Next Session Opening Message
169
+
160
170
  This fenced block is the authoritative agent-managed startup content. At closeout, verify `START_NEXT_SESSION_PROMPT.txt` against this block. Regenerate only if normalized content differs; if the two differ, trust this block and rewrite the convenience copy. User-facing closeout output should show `Start Agent Handoff` / `開工` as the primary next-session entry, plus the path-bearing fallback when the next AI is not yet pointed at this project root; do not hand-write a separate stateful prompt in the final response.
161
-
162
- 📋 Next session: agent-managed startup content below
163
-
164
- ```text
165
- Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Trust the handoff over this generated mirror.
166
-
167
- If the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.
168
-
171
+
172
+ 📋 Next session: agent-managed startup content below
173
+
174
+ ```text
175
+ Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Trust the handoff over this generated mirror.
176
+
177
+ If the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.
178
+
169
179
  Resume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, the display-only current-thread naming checkpoint when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out execution wording. First-use exception: when this handoff says `First-use guidance state: eligible`, the current objective is empty / `TBD`, and there is no same-message concrete task, load onboarding and include a short first-use welcome plus the most relevant guided choices in the same response instead of ending status-only. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. Upgrade never resets consumed / not_applicable first-use state back to eligible.
170
- ```
180
+ ```
@@ -16,6 +16,8 @@ Before closeout, record whether older log detail was kept, summarized, or archiv
16
16
 
17
17
  ## Entry Template
18
18
 
19
+ Optional concise fields at normal authorized saves: `Work` identifies a related handoff Work Items ID; `Title zh-Hant` and `Summary zh-Hant` provide Chinese display text. An optional `Event ID` uniquely identifies an event across a move or correction; the existing `ID` identifies the agent/session and is not an event identity. Omit unknown or unnecessary fields. Do not rewrite old history or create extra entries to refresh a dashboard.
20
+
19
21
  ````markdown
20
22
  <!-- ack:log-entry:start -->
21
23
  ## <YYYY-MM-DD> — <short session title>