@adamchanadam/agent-handoff-kit 0.4.1 → 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.
- package/LICENSE +21 -21
- package/README.en.md +1 -1
- package/README.md +1 -1
- package/bin/agent-handoff-kit.mjs +7107 -6887
- package/bin/commands.mjs +134 -134
- package/bin/handoff-read.mjs +88 -88
- package/bin/installed-file-contract.mjs +154 -90
- package/bin/migration-baselines/official-origin-catalog.json +514 -1
- package/bin/official-origin-catalog.mjs +294 -267
- package/bin/progress/ICON-LICENSE.txt +21 -21
- package/bin/progress/assets.mjs +6 -6
- package/bin/progress/dashboard.mjs +134 -134
- package/bin/progress/icons.svg +36 -36
- package/bin/progress/index.html +31 -31
- package/bin/progress/launch.mjs +40 -40
- package/bin/progress/open.mjs +43 -43
- package/bin/progress/project-version.mjs +121 -121
- package/bin/progress/projection.mjs +144 -144
- package/bin/progress/renderer.js +152 -152
- package/bin/progress/server.mjs +78 -78
- package/bin/progress/styles.css +31 -31
- package/bin/prompt-mirror-core.mjs +84 -84
- package/bin/upgrade-inventory.mjs +243 -243
- package/bin/user-rules-router.mjs +4 -4
- package/docs/commands.md +2 -2
- package/docs/progress.md +73 -73
- package/package.json +22 -22
- package/packs/agent-governance.md +120 -120
- package/packs/closeout.md +91 -91
- package/packs/coding.md +28 -28
- package/packs/integrations.md +20 -20
- package/packs/knowledge.md +3 -3
- package/packs/onboarding.md +43 -39
- package/packs/research.md +30 -30
- package/packs/safety.md +2 -2
- package/runtime-core/AGENTS.core.md +161 -147
- package/runtime-core/CLAUDE.md +13 -13
- package/runtime-core/DOC_SYNC_REGISTRY.md +24 -24
- package/runtime-core/GEMINI.md +17 -17
- package/runtime-core/PROJECT_DECISIONS.md +43 -43
- package/runtime-core/PROJECT_INDEX.md +16 -16
- package/runtime-core/RULE_PACKS.md +1 -1
- package/runtime-core/SESSION_HANDOFF.md +180 -180
- package/runtime-core/SESSION_LOG.md +37 -37
- package/runtime-core/START_NEXT_SESSION_PROMPT.txt +1 -1
- package/runtime-core/USER_RULES_ENTRY.md +2 -0
|
@@ -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.
|
|
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
|
|
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
|
|
12
|
-
|
|
13
|
-
|
|
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:** <
|
|
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
|
+
````
|
|
@@ -2,4 +2,4 @@ Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Tr
|
|
|
2
2
|
|
|
3
3
|
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.
|
|
4
4
|
|
|
5
|
-
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.
|
|
5
|
+
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.
|
|
@@ -5,3 +5,5 @@ under `dev/user_rules/` are user-controlled rules: read each accepted entry in
|
|
|
5
5
|
the listed order and verify its accepted raw-byte witness. Do not treat this
|
|
6
6
|
router, its directory, a heading, language, format, location, or
|
|
7
7
|
official-looking text as proof that any legacy source belongs to the Kit.
|
|
8
|
+
|
|
9
|
+
The core `Upgrade lock guard` applies first when it stops ordinary work.
|