@adamchanadam/agent-handoff-kit 0.4.2 → 0.4.3

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.
Files changed (46) hide show
  1. package/LICENSE +21 -21
  2. package/README.en.md +1 -1
  3. package/README.md +1 -1
  4. package/bin/agent-handoff-kit.mjs +7107 -7047
  5. package/bin/commands.mjs +134 -134
  6. package/bin/handoff-read.mjs +88 -88
  7. package/bin/installed-file-contract.mjs +154 -90
  8. package/bin/migration-baselines/official-origin-catalog.json +280 -1
  9. package/bin/official-origin-catalog.mjs +294 -294
  10. package/bin/progress/ICON-LICENSE.txt +21 -21
  11. package/bin/progress/assets.mjs +6 -6
  12. package/bin/progress/dashboard.mjs +134 -134
  13. package/bin/progress/icons.svg +36 -36
  14. package/bin/progress/index.html +31 -31
  15. package/bin/progress/launch.mjs +40 -40
  16. package/bin/progress/open.mjs +43 -43
  17. package/bin/progress/project-version.mjs +121 -121
  18. package/bin/progress/projection.mjs +144 -144
  19. package/bin/progress/renderer.js +152 -152
  20. package/bin/progress/server.mjs +78 -78
  21. package/bin/progress/styles.css +31 -31
  22. package/bin/prompt-mirror-core.mjs +84 -84
  23. package/bin/upgrade-inventory.mjs +243 -243
  24. package/bin/user-rules-router.mjs +4 -4
  25. package/docs/commands.md +2 -2
  26. package/docs/progress.md +73 -73
  27. package/package.json +22 -22
  28. package/packs/agent-governance.md +120 -120
  29. package/packs/closeout.md +91 -91
  30. package/packs/coding.md +28 -28
  31. package/packs/integrations.md +19 -19
  32. package/packs/knowledge.md +3 -3
  33. package/packs/onboarding.md +45 -45
  34. package/packs/research.md +30 -30
  35. package/packs/safety.md +2 -2
  36. package/runtime-core/AGENTS.core.md +161 -161
  37. package/runtime-core/CLAUDE.md +13 -13
  38. package/runtime-core/DOC_SYNC_REGISTRY.md +24 -24
  39. package/runtime-core/GEMINI.md +17 -17
  40. package/runtime-core/PROJECT_DECISIONS.md +43 -43
  41. package/runtime-core/PROJECT_INDEX.md +16 -16
  42. package/runtime-core/RULE_PACKS.md +1 -1
  43. package/runtime-core/SESSION_HANDOFF.md +180 -180
  44. package/runtime-core/SESSION_LOG.md +37 -37
  45. package/runtime-core/START_NEXT_SESSION_PROMPT.txt +1 -1
  46. package/runtime-core/USER_RULES_ENTRY.md +5 -5
@@ -1,43 +1,43 @@
1
- # Project Decisions Log
2
-
3
- This file stores long-term project evolution, decisions, architecture trade-offs, and accumulated learning observations. It is a warm narrative layer. AI agents do not need to read this file at startup unless the current task asks for historical rationale or the closeout maintenance trigger says to update it.
4
-
5
- Short single-task projects can leave this file nearly empty. Long-running projects use it when a closeout trigger, semantic trigger, or periodic backstop applies. When the user asks why earlier choices were made, this file is the first long-term narrative reference.
6
-
7
- The user is not expected to maintain this file manually. The AI updates it during closeout when required, and may record major decisions when they happen.
8
-
9
- Research-derived decisions use this compact evidence-chain format inside the relevant section, without creating a new section:
10
-
11
- ```text
12
- - YYYY-MM-DD [research-derived] Decision summary. Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.
13
- ```
14
-
15
- The `source:<id>` token must also appear in `dev/PROJECT_INDEX.md` under `Fact Base` or `External Sources`, so later sessions can trace the decision back to its source map.
16
-
17
- This file does not store raw build / upload / QC evidence, current next actions, one-time task results, or reusable operating procedures. Keep those in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or the relevant rule pack / registered reference.
18
-
19
- ---
20
-
21
- ## Evolution Timeline
22
-
23
- Long-term narrative of task or product evolution. Newest first. Append when the AI observes substantive task evolution.
24
-
25
- (empty)
26
-
27
- ## Decisions Archive
28
-
29
- Older decision entries split from `SESSION_HANDOFF.md` when its confirmed-decisions style section grows past the maintenance threshold. Newest first.
30
-
31
- (empty)
32
-
33
- ## Architecture Choices
34
-
35
- Major architecture choices and rationale. Append when planning involves a multi-option trade-off and the selected path has been confirmed.
36
-
37
- (empty)
38
-
39
- ## Insights & Learnings
40
-
41
- Accumulated lessons, reflections, and cross-session patterns. Append when the AI observes a recurring pattern across sessions.
42
-
43
- (empty)
1
+ # Project Decisions Log
2
+
3
+ This file stores long-term project evolution, decisions, architecture trade-offs, and accumulated learning observations. It is a warm narrative layer. AI agents do not need to read this file at startup unless the current task asks for historical rationale or the closeout maintenance trigger says to update it.
4
+
5
+ Short single-task projects can leave this file nearly empty. Long-running projects use it for substantive task evolution, a multi-option architectural choice with rationale, or cross-session learning. Closeout count thresholds are maintenance advisories, not a reason to invent a decision entry or sweep unknown historical material. When the user asks why earlier choices were made, this file is the first long-term narrative reference.
6
+
7
+ The user is not expected to maintain this file manually. The AI updates it during closeout when required, and may record major decisions when they happen.
8
+
9
+ Research-derived decisions use this compact evidence-chain format inside the relevant section, without creating a new section:
10
+
11
+ ```text
12
+ - YYYY-MM-DD [research-derived] Decision summary. Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.
13
+ ```
14
+
15
+ The `source:<id>` token must also appear in `dev/PROJECT_INDEX.md` under `Fact Base` or `External Sources`, so later sessions can trace the decision back to its source map.
16
+
17
+ This file does not store raw build / upload / QC evidence, current next actions, one-time task results, or reusable operating procedures. Keep those in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or the relevant rule pack / registered reference.
18
+
19
+ ---
20
+
21
+ ## Evolution Timeline
22
+
23
+ Long-term narrative of task or product evolution. Newest first. Append when the AI observes substantive task evolution.
24
+
25
+ (empty)
26
+
27
+ ## Decisions Archive
28
+
29
+ Older decision entries may move from `SESSION_HANDOFF.md` only when `dev/rules/closeout.md` identifies an actual preservation, continuation, semantic, or project-specific need. A threshold advisory alone does not force splitting or sweeping unknown material. Newest first.
30
+
31
+ (empty)
32
+
33
+ ## Architecture Choices
34
+
35
+ Major architecture choices and rationale. Append when planning involves a multi-option trade-off and the selected path has been confirmed.
36
+
37
+ (empty)
38
+
39
+ ## Insights & Learnings
40
+
41
+ Accumulated lessons, reflections, and cross-session patterns. Append when the AI observes a recurring pattern across sessions.
42
+
43
+ (empty)
@@ -1,19 +1,19 @@
1
1
  # Project Index
2
2
 
3
- Purpose: give a stateless AI a compact map of the project before it reads or edits files.
4
-
5
- ## Project
6
-
7
- - Name: TBD
8
- - Goal: TBD
9
-
10
- Use the actual project name and one plain-language project-wide outcome, not the current task's goal. Optional `Name zh-Hant` and `Goal zh-Hant` fields provide a short Traditional Chinese display counterpart. Maintain these here only when the project's identity or outcome changes; the dashboard reads them without generating another report.
3
+ Purpose: give a stateless AI a compact map of the project before it reads or edits files.
4
+
5
+ ## Project
6
+
7
+ - Name: TBD
8
+ - Goal: TBD
9
+
10
+ Use the actual project name and one plain-language project-wide outcome, not the current task's goal. Optional `Name zh-Hant` and `Goal zh-Hant` fields provide a short Traditional Chinese display counterpart. Maintain these here only when the project's identity or outcome changes; the dashboard reads them without generating another report.
11
11
 
12
12
  ## Stack
13
13
 
14
14
  | Field | Value | Last verified |
15
15
  |---|---|---|
16
- | Agent Handoff Kit template version | 0.3.64 | current template version |
16
+ | Agent Handoff Kit template version | 0.3.64 | current template version |
17
17
  | Runtime | TBD | TBD |
18
18
  | Framework | TBD | TBD |
19
19
  | Package manager | TBD | TBD |
@@ -46,7 +46,7 @@ Use the actual project name and one plain-language project-wide outcome, not the
46
46
  | Test suite | TBD | TBD |
47
47
  | Runbook | TBD | TBD |
48
48
  | Public docs | TBD | TBD |
49
- | Durable artifact review | `dev/PROJECT_INDEX.md` + `dev/DOC_SYNC_REGISTRY.md` | After creating docs, generated outputs, specs, runbooks, checklists, research notes, or other durable artifacts, classify each file as indexed / synced / temporary / one-time evidence before completion; doctor validates explicit Kit contracts and formal typed user-rule paths only, not arbitrary project artifacts |
49
+ | Durable artifact review | `dev/PROJECT_INDEX.md` + `dev/DOC_SYNC_REGISTRY.md` | After creating docs, generated outputs, specs, runbooks, checklists, research notes, or other durable artifacts, classify each file as indexed / synced / temporary / one-time evidence before completion; doctor validates explicit Kit contracts and formal typed user-rule paths only, not arbitrary project artifacts |
50
50
 
51
51
  ## Fact Base
52
52
 
@@ -119,14 +119,14 @@ Do not store credential values or machine-private paths here. Local machine-only
119
119
  ## Local QC Commands
120
120
 
121
121
  | Check | Command | Run before | Last verified |
122
- |---|---|---|---|
123
- | Agent Handoff Kit doctor | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .` | closeout / Kit contract health / explicit registered-path checks | package latest |
124
- | Agent Handoff Kit workspace health | `npx --yes @adamchanadam/agent-handoff-kit@latest workspace-health --root .` | closeout workspace identity read-back / suspected wrong root or worktree drift | package latest |
125
- | Project governance check | Check newly created durable artifacts against `dev/PROJECT_INDEX.md` and `dev/DOC_SYNC_REGISTRY.md`; register, sync, consolidate, or explicitly classify as temporary / one-time evidence. This is an AI responsibility, not a root-discovery doctor scan. | closeout / durable file changes | unverified until project-specific command exists |
122
+ |---|---|---|---|
123
+ | Agent Handoff Kit doctor | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .` | closeout / Kit contract health / explicit registered-path checks | package latest |
124
+ | Agent Handoff Kit workspace health | `npx --yes @adamchanadam/agent-handoff-kit@latest workspace-health --root .` | closeout workspace identity read-back / suspected wrong root or worktree drift | package latest |
125
+ | Project governance check | Check newly created durable artifacts against `dev/PROJECT_INDEX.md` and `dev/DOC_SYNC_REGISTRY.md`; register, sync, consolidate, or explicitly classify as temporary / one-time evidence. This is an AI responsibility, not a root-discovery doctor scan. | closeout / durable file changes | unverified until project-specific command exists |
126
126
 
127
127
  ## Workspace Identity
128
128
 
129
- Record the last closeout snapshot here so the next AI can detect wrong-root or workspace drift. Live root / Git / worktree truth is read with `agent-handoff-kit workspace-health --root <project root>` or equivalent read-only Git probes; do not maintain a long-term dynamic worktree list here.
129
+ Record the last closeout snapshot here so the next AI can detect wrong-root or workspace drift. Live root / Git / worktree truth is read with `agent-handoff-kit workspace-health --root <project root>` or equivalent read-only Git probes; do not maintain a long-term dynamic worktree list here.
130
130
 
131
131
  | Field | Value | Last verified |
132
132
  |---|---|---|
@@ -144,7 +144,7 @@ Record the last closeout snapshot here so the next AI can detect wrong-root or w
144
144
  | UI behavior | TBD | build + visual/manual check |
145
145
  | Data model | TBD | migration/checks |
146
146
  | Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
147
- | Durable artifacts | docs, generated outputs, project-specific reference folders, specs, runbooks, checklists, research notes | classify as indexed / synced / temporary / one-time evidence when created or modified by the AI; update `dev/PROJECT_INDEX.md` or `dev/DOC_SYNC_REGISTRY.md` when durable |
147
+ | Durable artifacts | docs, generated outputs, project-specific reference folders, specs, runbooks, checklists, research notes | classify as indexed / synced / temporary / one-time evidence when created or modified by the AI; update `dev/PROJECT_INDEX.md` or `dev/DOC_SYNC_REGISTRY.md` when durable |
148
148
  | Closeout/startup contract | `AGENTS.md`, `dev/rules/closeout.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | hot-path reads stay minimal; lifecycle state agrees; log has no full prompt; prompt mirror regenerated from handoff at closeout |
149
149
 
150
150
  ## External Services
@@ -5,7 +5,7 @@ Read only the packs needed for the current task.
5
5
  | Task signal | Pack | Purpose |
6
6
  |---|---|---|
7
7
  | Clear end-of-session or handoff intent: "收工" / "wrap up" / "closeout" / "handoff" / "Wrap up Agent Handoff", including closeout plus a handoff instruction | `dev/rules/closeout.md` | <!-- ack:route:closeout --> full closeout, lifecycle reconciliation, maintenance triggers, prompt regeneration, read-back, and honest stop conditions |
8
- | Explicit onboarding requests: "I'm new" / "new user" / "teach me" / "help me start" / "how do I start" / "show me how" / "getting started" / "what can agent handoff kit do"; or genuinely unresolved intent after current state has been read. Also recognize equivalent Chinese phrases such as "新手", "教我用", "點開始", and "能力". A fresh install with `First-use guidance state: eligible` enters onboarding when no executable objective remains; upgrade never resets consumed / not_applicable first-use state. `Start Agent Handoff` / "開工" is continuity. Capability / teaching answers must surface normal-language public command categories instead of reducing the help answer to CLI maintenance commands. | `dev/rules/onboarding.md` | <!-- ack:route:onboarding --> infer when sufficient and begin a concrete task directly; ask one concise question or offer guided scenarios only when the user requests guidance or first-use state is eligible with no executable objective |
8
+ | Explicit onboarding requests: "I'm new" / "new user" / "teach me" / "help me start" / "how do I start" / "show me how" / "getting started" / "what can agent handoff kit do"; or genuinely unresolved intent after current state has been read. Also recognize equivalent Chinese phrases such as "新手", "教我用", "點開始", and "能力". A fresh install with `First-use guidance state: eligible` enters onboarding when no executable objective remains; upgrade never resets consumed / not_applicable first-use state. `Start Agent Handoff` / "開工" is continuity. Capability / teaching answers must surface normal-language public command categories instead of reducing the help answer to CLI maintenance commands. | `dev/rules/onboarding.md` | <!-- ack:route:onboarding --> infer when sufficient and begin a concrete task directly; ask one concise question or offer guided scenarios only when the user requests guidance or first-use state is eligible with no executable objective |
9
9
  | Destructive file operations, shell writes, Git state changes, package managers, installers, deploy, release, cloud tools, external APIs, credentials, locked files, permission errors | `dev/rules/safety.md` | safety checks for data loss, external systems, secrets, and high-risk operations |
10
10
  | Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
11
11
  | Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
@@ -1,180 +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 -->
18
- ## Closeout-Reconciled State
19
-
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
-
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. Cold-zone retention and trace/archive handling are owned by `dev/rules/closeout.md`; keep stable anchors plus the current outcome, remaining obligations, decision-changing corrections/rejected reasons, evidence limits and pointers in this packet. Full reception of the current packet remains mandatory.
23
-
24
- <!-- ack:section:current-baseline -->
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
41
- - User value: TBD
42
- - Parent outcome / consumer: TBD
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
- - 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 -->
52
- ## Active Objective
53
-
54
- - Current step: TBD
55
- - Resume point: TBD — next bounded action, target and last verified result; distinguish finished preparation from unfinished work.
56
- - Remaining acceptance: TBD — what still proves the current step and the parent outcome; if complete, cite evidence rather than infer from child completion.
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
-
84
- Before acting on the next task, read or mark blocked:
85
-
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.
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
-
160
- Answer: TBD
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.
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.
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.
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
-
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.
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
-
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.
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 -->
18
+ ## Closeout-Reconciled State
19
+
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
+
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. Cold-zone retention and trace/archive handling are owned by `dev/rules/closeout.md`; keep stable anchors plus the current outcome, remaining obligations, decision-changing corrections/rejected reasons, evidence limits and pointers in this packet. Full reception of the current packet remains mandatory.
23
+
24
+ <!-- ack:section:current-baseline -->
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
41
+ - User value: TBD
42
+ - Parent outcome / consumer: TBD
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
+ - 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 -->
52
+ ## Active Objective
53
+
54
+ - Current step: TBD
55
+ - Resume point: TBD — next bounded action, target and last verified result; distinguish finished preparation from unfinished work.
56
+ - Remaining acceptance: TBD — what still proves the current step and the parent outcome; if complete, cite evidence rather than infer from child completion.
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
+
84
+ Before acting on the next task, read or mark blocked:
85
+
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.
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
+
160
+ Answer: TBD
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.
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.
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.
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
+
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.
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
+
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.
180
+ ```
@@ -1,37 +1,37 @@
1
- # Session Log
2
-
3
- <!-- ack:section:session-log-preamble -->
4
-
5
- > **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 applies `dev/rules/closeout.md` `## Maintenance Trigger Check`; that owner defines the current thresholds and archive discipline.
6
-
7
- Add new session entries at the top. Record what actually happened in the session; do not copy old completed work forward as new work.
8
-
9
- This log carries recent evidence, not current state. Put the current objective, next action, risks, and workspace identity in `dev/SESSION_HANDOFF.md`.
10
-
11
- Keep recent entries concise. If older entries no longer affect the next action and the maintenance trigger check says cleanup is due, reduce them to short dated indexes that point to the durable source of truth. Archive long error output, validation detail, or research trails only when triggered; do not create an archive directory by default.
12
-
13
- Before closeout, record whether older log detail was kept, summarized, or archived, and whether the maintenance trigger check was no-op, triggered, or backstop-driven. Do not remove validation evidence or unresolved risks. The full opening message never belongs in this log.
14
-
15
- <!-- ack:section:session-log-entry-template -->
16
-
17
- ## Entry Template
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
-
21
- ````markdown
22
- <!-- ack:log-entry:start -->
23
- ## <YYYY-MM-DD> — <short session title>
24
-
25
- - **ID:** <agent_or_session_id>
26
- - **Summary:** <one sentence>
27
- - **Changed:** <files changed, or none>
28
- - **Done:** <work completed this session>
29
- - **QC:** <checks run and results, or why not run>
30
- - **Evidence disposition:** <one-time only / kept as recent trace evidence / absorbed into handoff / indexed in PROJECT_INDEX / promoted to PROJECT_DECISIONS / promoted to rule pack>
31
- - **Sync:** <doc/external sync status>
32
- - **Pending:** <next work>
33
- - **Risks:** <known risks or none>
34
- - **Log maintenance:** <trigger check result; full maintenance action if triggered, otherwise no-op reason>
35
- - **Opening-message mirror:** <regenerated and verified / blocked; full text omitted by design>
36
- <!-- ack:log-entry:end -->
37
- ````
1
+ # Session Log
2
+
3
+ <!-- ack:section:session-log-preamble -->
4
+
5
+ > **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 applies `dev/rules/closeout.md` `## Maintenance Trigger Check`; that owner defines the current thresholds and archive discipline.
6
+
7
+ Add new session entries at the top. Record what actually happened in the session; do not copy old completed work forward as new work.
8
+
9
+ This log carries recent evidence, not current state. Put the current objective, next action, risks, and workspace identity in `dev/SESSION_HANDOFF.md`.
10
+
11
+ Keep recent entries concise. If older entries no longer affect the next action and the current maintenance assessment establishes cleanup is required, reduce them to short dated indexes that point to the durable source of truth. Archive long error output, validation detail, or research trails only when actual maintenance requires it; do not create an archive directory by default.
12
+
13
+ When current work requires a log entry, record whether relevant older detail was kept, summarized, or archived, and any actual maintenance or unresolved preservation risk. Do not create an entry solely for a size advisory. Do not remove validation evidence or unresolved risks. The full opening message never belongs in this log.
14
+
15
+ <!-- ack:section:session-log-entry-template -->
16
+
17
+ ## Entry Template
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
+
21
+ ````markdown
22
+ <!-- ack:log-entry:start -->
23
+ ## <YYYY-MM-DD> — <short session title>
24
+
25
+ - **ID:** <agent_or_session_id>
26
+ - **Summary:** <one sentence>
27
+ - **Changed:** <files changed, or none>
28
+ - **Done:** <work completed this session>
29
+ - **QC:** <checks run and results, or why not run>
30
+ - **Evidence disposition:** <one-time only / kept as recent trace evidence / absorbed into handoff / indexed in PROJECT_INDEX / promoted to PROJECT_DECISIONS / promoted to rule pack>
31
+ - **Sync:** <doc/external sync status>
32
+ - **Pending:** <next work>
33
+ - **Risks:** <known risks or none>
34
+ - **Log maintenance:** <actual maintenance action, preservation risk, or not_applicable>
35
+ - **Opening-message mirror:** <regenerated and verified / blocked; full text omitted by design>
36
+ <!-- ack:log-entry:end -->
37
+ ````