@adamchanadam/agent-handoff-kit 0.2.3 → 0.3.0

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,93 +1,136 @@
1
- # Project Index
2
-
3
- Purpose: give a stateless AI a compact map of the project before it reads or edits files.
4
-
5
- ## Stack
6
-
7
- | Field | Value | Last verified |
8
- |---|---|---|
9
- | Agent Handoff Kit template version | 0.1.7 | package prototype |
10
- | Runtime | TBD | TBD |
11
- | Framework | TBD | TBD |
12
- | Package manager | TBD | TBD |
13
- | Test command | TBD | TBD |
14
- | Build command | TBD | TBD |
15
- | Deploy command | TBD | TBD |
16
-
17
- ## Directory Map
18
-
19
- | Path | Role | Read when |
20
- |---|---|---|
21
- | `AGENTS.md` | primary Agent Handoff Kit entry and startup contract | session startup |
22
- | `CLAUDE.md` | Claude Code bridge to the same startup path | Claude Code startup |
23
- | `GEMINI.md` | Gemini CLI bridge to the same startup path | Gemini CLI startup |
24
- | `START_NEXT_SESSION_PROMPT.txt` | auto-generated convenience copy of the next-session startup prompt; `dev/SESSION_HANDOFF.md` remains authoritative | next session startup copy/paste |
25
- | `src/` | application source | coding task |
26
- | `tests/` | tests | coding/QC |
27
- | `docs/` | user or product docs | doc/public behavior change |
28
- | `dev/` | governance state | startup/closeout |
29
- | `TBD` | local source-of-truth files | before tasks that depend on project facts |
30
- | `TBD` | external-source indexes or mirrors | before research, writing, or knowledge-sync tasks |
31
-
32
- ## Entry Points
33
-
34
- | Entry | Path | Notes |
35
- |---|---|---|
36
- | App entry | TBD | TBD |
37
- | Main config | TBD | TBD |
38
- | Test suite | TBD | TBD |
39
- | Runbook | TBD | TBD |
40
- | Public docs | TBD | TBD |
41
-
42
- ## Fact Base
43
-
44
- Reachable means the source can be found. It does not mean the source has been read in this session.
45
-
46
- | Source | Role | Required before | Access method | Last verified |
47
- |---|---|---|---|---|
48
- | TBD | local source of truth / reference / draft / archive | TBD | path or instruction | TBD |
49
-
50
- ## External Sources
51
-
52
- | Source | Role | Required before | Access method | Write-back rule | Last verified |
53
- |---|---|---|---|---|---|
54
- | TBD | source of truth / mirror / index / attachment store | TBD | URL, connector, or manual packet | read-back required / manual only / no write | TBD |
55
-
56
- ## Local QC Commands
57
-
58
- | Check | Command | Run before | Last verified |
59
- |---|---|---|---|
60
- | Agent Handoff Kit doctor | TBD | closeout / governance changes | TBD |
61
- | Project governance check | TBD | closeout / durable file changes | TBD |
62
-
63
- ## Workspace Identity
64
-
65
- Record this at closeout so the next AI can detect wrong-root or workspace drift.
66
-
67
- | Field | Value | Last verified |
68
- |---|---|---|
69
- | Expected project root | TBD | TBD |
70
- | Git root | TBD | TBD |
71
- | Branch / commit | TBD | TBD |
72
- | Worktree or parallel workspace | TBD | TBD |
73
- | Uncommitted change summary | TBD | TBD |
74
-
75
- ## Change Hotspots
76
-
77
- | Change type | Likely files | Required checks |
78
- |---|---|---|
79
- | API behavior | TBD | tests + docs sync |
80
- | UI behavior | TBD | build + visual/manual check |
81
- | Data model | TBD | migration/checks |
82
- | Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
83
- | Closeout/startup contract | `AGENTS.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | opening message present + prompt convenience copy matches handoff + workspace identity current |
84
-
85
- ## External Services
86
-
87
- | Service | Scope | Verification source | Last verified |
88
- |---|---|---|---|
89
- | TBD | TBD | TBD | TBD |
90
-
91
- ## Maintenance Rule
92
-
93
- Update this file when stack, commands, directory roles, entry points, external services, workspace identity, durable runbooks, or governance file map changes.
1
+ # Project Index
2
+
3
+ Purpose: give a stateless AI a compact map of the project before it reads or edits files.
4
+
5
+ ## Stack
6
+
7
+ | Field | Value | Last verified |
8
+ |---|---|---|
9
+ | Agent Handoff Kit template version | 0.1.7 | package prototype |
10
+ | Runtime | TBD | TBD |
11
+ | Framework | TBD | TBD |
12
+ | Package manager | TBD | TBD |
13
+ | Test command | TBD | TBD |
14
+ | Build command | TBD | TBD |
15
+ | Deploy command | TBD | TBD |
16
+
17
+ ## Directory Map
18
+
19
+ | Path | Role | Read when |
20
+ |---|---|---|
21
+ | `AGENTS.md` | primary Agent Handoff Kit entry and startup contract | session startup |
22
+ | `CLAUDE.md` | Claude Code bridge to the same startup path | Claude Code startup |
23
+ | `GEMINI.md` | Gemini CLI bridge to the same startup path | Gemini CLI startup |
24
+ | `START_NEXT_SESSION_PROMPT.txt` | auto-generated convenience copy of the next-session startup prompt; `dev/SESSION_HANDOFF.md` remains authoritative | next session startup copy/paste |
25
+ | `src/` | application source | coding task |
26
+ | `tests/` | tests | coding/QC |
27
+ | `docs/` | user or product docs | doc/public behavior change |
28
+ | `dev/` | governance state | startup/closeout |
29
+ | `TBD` | local source-of-truth files | before tasks that depend on project facts |
30
+ | `TBD` | external-source indexes or mirrors | before research, writing, or knowledge-sync tasks |
31
+
32
+ ## Entry Points
33
+
34
+ | Entry | Path | Notes |
35
+ |---|---|---|
36
+ | App entry | TBD | TBD |
37
+ | Main config | TBD | TBD |
38
+ | Test suite | TBD | TBD |
39
+ | Runbook | TBD | TBD |
40
+ | Public docs | TBD | TBD |
41
+
42
+ ## Fact Base
43
+
44
+ Reachable means the source can be found. It does not mean the source has been read in this session.
45
+
46
+ | Source | Role | Required before | Access method | Last verified |
47
+ |---|---|---|---|---|
48
+ | TBD | local source of truth / reference / draft / archive | TBD | path or instruction | TBD |
49
+
50
+ ## External Sources
51
+
52
+ | Source | Role | Required before | Access method | `via` | Write-back rule | Last verified |
53
+ |---|---|---|---|---|---|---|
54
+ | TBD | source of truth / mirror / index / attachment store | TBD | URL, connector, or manual packet | `Notion Connector` / `Drive Connector` / `manual paste` / etc — must match an entry under `## Installed Integrations` | read-back required / manual only / no write | TBD |
55
+
56
+ > `via` column 紀律:每行 External Sources 必引用 `## Installed Integrations` 嘅 entry 名稱(譬如 `Notion Connector`、`Drive Connector`),確認該 source 經邊個 integration 訪問;無 declared Integration 嘅 source 用 `manual paste`。Cross-section consistency 由 doctor + qa:release 強制 enforce。
57
+
58
+ ## Installed Integrations
59
+
60
+ > ⚠️ **機密分離原則**:本 section 只記錄 **項目使用紀錄** + **公開參考座標**(Notion DB 名 / URL / folder path 等),**絕對不記錄 API key / OAuth token / 任何 credential value**。Credential 應由 AI 工具自身 secure storage 管理(譬如 Claude Desktop Extensions 嘅 OS Keychain / Claude Code MCP config)。AI 寫入本 section 前必 self-check 確認無 credential leak;doctor 對本 section + SESSION_HANDOFF + SESSION_LOG 強制 grep credential prefix patterns(`sk-` / `ntn_` / `ya29.` / `xoxp-` / `ghp_` / `sl.` / `AKIA` / `AIza` 等)。
61
+
62
+ > 用途:新 AI session 開工讀本 section 知道項目可用嘅外部工具能力 + 各自分工。Declare 一次後跨 session AI 都會 leverage;每個 entry 必含 `Declared` + `Last Verified` 防漂移。
63
+
64
+ ### Connectors(Anthropic 官方 vetted)
65
+
66
+ | Tool | Project Usage | Access Scope | Specific Instance | Credential Location | Declared | Last Verified |
67
+ |------|---------------|--------------|-------------------|---------------------|----------|---------------|
68
+ | TBD | TBD(譬如 DB Index 記真源 path / 持久化參考檔儲存) | read / read+write | TBD(譬如 DB 名 + URL / folder path) | TBD(譬如 `Claude Desktop Extensions`) | TBD | TBD |
69
+
70
+ ### MCPs(community / custom)
71
+
72
+ | Server | Source | Project Usage | Credential Location | Declared | Last Verified |
73
+ |--------|--------|---------------|---------------------|----------|---------------|
74
+ | TBD | TBD(譬如 GitHub repo URL) | TBD | TBD(譬如 `Claude Code MCP config + env var`) | TBD | TBD |
75
+
76
+ ### Plugins(Claude Code plugin bundle)
77
+
78
+ | Name | Bundle Content(Skills + MCP + hooks) | When Triggered | Last Verified |
79
+ |------|----------------------------------------|----------------|---------------|
80
+ | TBD | TBD | TBD | TBD |
81
+
82
+ ### Skills(SKILL.md instruction set)
83
+
84
+ | Name | Source | When Triggered | Last Verified |
85
+ |------|--------|----------------|---------------|
86
+ | TBD | TBD(譬如 plugin bundle / user-level install) | TBD | TBD |
87
+
88
+ ### Source-of-truth Architecture(多層持久化組合)
89
+
90
+ > 當項目用多個整合構成 source-of-truth 架構(譬如 Notion DB Index + 本機真源 + Drive 參考檔),本表描述每層分工,避免 AI 跨層越界。
91
+
92
+ | Layer | Surface(具體 instance) | Role | Write Direction |
93
+ |-------|--------------------------|------|-----------------|
94
+ | 真源(source of truth) | TBD(譬如 本機 `~/project/reference/`) | 原始可審計 reference 內容 | 用戶手動置入;AI 不直接寫入 |
95
+ | Index | TBD(譬如 Notion DB「Project Index」) | 登記每份真源檔 metadata + 摘要 + tag | AI 經 Connector 直接讀寫 |
96
+ | 持久化參考檔(mirror) | TBD(譬如 Drive folder「Project Reference/」) | 防本機 disk failure / 跨裝置 access | 用戶手動同步;AI 唔自動 push |
97
+ | Working draft | TBD(譬如 本機 `~/project/output/`) | AI 寫 task output | AI 直接 read + write 本機 |
98
+
99
+ ## Local QC Commands
100
+
101
+ | Check | Command | Run before | Last verified |
102
+ |---|---|---|---|
103
+ | Agent Handoff Kit doctor | TBD | closeout / governance changes | TBD |
104
+ | Project governance check | TBD | closeout / durable file changes | TBD |
105
+
106
+ ## Workspace Identity
107
+
108
+ Record this at closeout so the next AI can detect wrong-root or workspace drift.
109
+
110
+ | Field | Value | Last verified |
111
+ |---|---|---|
112
+ | Expected project root | TBD | TBD |
113
+ | Git root | TBD | TBD |
114
+ | Branch / commit | TBD | TBD |
115
+ | Worktree or parallel workspace | TBD | TBD |
116
+ | Uncommitted change summary | TBD | TBD |
117
+
118
+ ## Change Hotspots
119
+
120
+ | Change type | Likely files | Required checks |
121
+ |---|---|---|
122
+ | API behavior | TBD | tests + docs sync |
123
+ | UI behavior | TBD | build + visual/manual check |
124
+ | Data model | TBD | migration/checks |
125
+ | Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
126
+ | Closeout/startup contract | `AGENTS.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | opening message present + prompt convenience copy matches handoff + workspace identity current |
127
+
128
+ ## External Services
129
+
130
+ | Service | Scope | Verification source | Last verified |
131
+ |---|---|---|---|
132
+ | TBD | TBD | TBD | TBD |
133
+
134
+ ## Maintenance Rule
135
+
136
+ Update this file when stack, commands, directory roles, entry points, external services, workspace identity, durable runbooks, or governance file map changes.
@@ -1,19 +1,20 @@
1
- # Rule Packs Router
2
-
3
- Read only the packs needed for the current task.
4
-
5
- | Task signal | Pack | Purpose |
6
- |---|---|---|
7
- | First-time user signals (任一即可): "I'm new" / "新手" / "教我用" / "help me start" / "first time" / "我啱啱安裝" / "點開始" / "show me how" / "getting started" / "agent handoff kit 可幫我做甚麼" / "我想做 [type] project" / "點用" / "能力" / vague first message ≤ 30 chars / HANDOFF Active Objective 空白 + Session count 1 (fresh installation context) | `dev/rules/onboarding.md` | first-time user walk-through with 5 scenarios (A 寫代碼 / B 研究報告 / C 知識庫 / D 學寫代碼 / E 其他) × 5-step pattern (PLAN-style: confirm context / explain v2 fit / ask task scope / suggest minimum viable / confirm + transition); load proactively when signal present; transient pack, unload after onboarding completion |
8
- | 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 |
9
- | Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
10
- | Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
11
- | Sources, evidence, comparison, fact finding | `dev/rules/research.md` | source handling and uncertainty |
12
- | Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |
13
- | Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
14
- | External notes, knowledge base, Notion, Obsidian, Drive | `dev/rules/knowledge.md` | external knowledge source integration |
15
- | Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |
16
-
17
- ## Routing Rule
18
-
19
- Load the minimum set. If uncertain, load the narrower pack first. If a task clearly involves safety risk plus another domain, load `dev/rules/safety.md` with the relevant domain pack and state why. Packs can add stricter rules, but cannot weaken core safety or closeout requirements.
1
+ # Rule Packs Router
2
+
3
+ Read only the packs needed for the current task.
4
+
5
+ | Task signal | Pack | Purpose |
6
+ |---|---|---|
7
+ | First-time user signals (任一即可): "I'm new" / "新手" / "教我用" / "help me start" / "first time" / "我啱啱安裝" / "點開始" / "show me how" / "getting started" / "agent handoff kit 可幫我做甚麼" / "我想做 [type] project" / "點用" / "能力" / vague first message ≤ 30 chars / HANDOFF Active Objective 空白 + Session count 1 (fresh installation context) | `dev/rules/onboarding.md` | first-time user walk-through with 5 scenarios (A 寫代碼 / B 研究報告 / C 知識庫 / D 學寫代碼 / E 其他) × 5-step pattern (PLAN-style: confirm context / explain v2 fit / ask task scope / suggest minimum viable / confirm + transition); load proactively when signal present; transient pack, unload after onboarding completion |
8
+ | 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 |
9
+ | Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
10
+ | Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
11
+ | Sources, evidence, comparison, fact finding | `dev/rules/research.md` | source handling and uncertainty |
12
+ | Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |
13
+ | Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
14
+ | External notes, knowledge base, Notion, Obsidian, Drive | `dev/rules/knowledge.md` | external knowledge source integration |
15
+ | External tool integrations (Connector / MCP / Plugin / Skill) — declared in `## Installed Integrations`; tasks involving Notion / Drive / Slack / Linear / Dropbox / HubSpot / GitHub / etc. external read-write | `dev/rules/integrations.md` | Connector-first default + credential separation + multi-layer source-of-truth + cross-session resilience |
16
+ | Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |
17
+
18
+ ## Routing Rule
19
+
20
+ Load the minimum set. If uncertain, load the narrower pack first. If a task clearly involves safety risk plus another domain, load `dev/rules/safety.md` with the relevant domain pack and state why. Packs can add stricter rules, but cannot weaken core safety or closeout requirements.
@@ -1,150 +1,151 @@
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
-
16
- <!-- ack:section:closeout-reconciled-state -->
17
- ## Closeout-Reconciled State
18
-
19
- This is the current-state area. At every full closeout, rewrite or explicitly confirm every section below. Do not append a new state snapshot under an old one.
20
-
21
- <!-- ack:section:current-baseline -->
22
- ## Current Baseline
23
-
24
- 1. Project root: TBD
25
- 2. Product/system state: TBD
26
- 3. Governance state: TBD
27
- 4. Source-of-truth notes: TBD
28
-
29
- <!-- ack:section:task-understanding-summary -->
30
- ## Task Understanding Summary
31
-
32
- <!-- ack:field:user-intent -->
33
- - User intent: TBD
34
- <!-- ack:field:task-essence -->
35
- - Task essence: TBD
36
- - User value: TBD
37
- <!-- ack:field:success-criteria -->
38
- - Success criteria: TBD
39
- - Key background already read: TBD
40
- - Background still unread or blocked: TBD
41
- - Non-goals / boundaries: TBD
42
-
43
- <!-- ack:section:active-objective -->
44
- ## Active Objective
45
-
46
- TBD
47
-
48
- <!-- ack:section:completed-this-session -->
49
- ## Completed This Session
50
-
51
- Record only work actually completed in the current session.
52
-
53
- 1. TBD
54
-
55
- <!-- ack:section:next-priorities -->
56
- ## Next Priorities
57
-
58
- 1. TBD
59
-
60
- <!-- ack:section:next-task-required-reading -->
61
- ## Next Task Required Reading
62
-
63
- Before acting on the next task, read or mark blocked:
64
-
65
- | Source | Why required | Status |
66
- |---|---|---|
67
- | TBD | TBD | pending |
68
-
69
- <!-- ack:section:risks-blockers -->
70
- ## Risks / Blockers
71
-
72
- 1. TBD
73
-
74
- <!-- ack:section:validation-qc -->
75
- ## Validation / QC
76
-
77
- - Checks run this session: TBD
78
- - Checks not run and why: TBD
79
- - Handoff evidence location: TBD
80
-
81
- <!-- ack:section:workspace-identity -->
82
- ## Workspace Identity
83
-
84
- Expected project root: TBD
85
- Git root: TBD
86
- Branch: TBD
87
- Commit: TBD
88
- Worktree / parallel workspace status: TBD
89
- Uncommitted changes summary: TBD
90
-
91
- <!-- ack:section:sync-status -->
92
- ## Sync Status
93
-
94
- Use statuses from `dev/DOC_SYNC_REGISTRY.md`: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.
95
-
96
- - Project index: TBD
97
- - Doc sync registry: TBD
98
- - Public docs / README: TBD
99
- - External knowledge tools: TBD
100
-
101
- <!-- ack:section:state-reconciliation-check -->
102
- ## State Reconciliation Check
103
-
104
- At full closeout, complete this check after updating the state sections above.
105
-
106
- - Reconciled at: TBD
107
- <!-- ack:field:state-sections-rewritten-or-confirmed -->
108
- - State sections rewritten or confirmed current: TBD
109
- <!-- ack:field:stale-snapshots-left -->
110
- - Stale snapshots left in this handoff: TBD
111
- <!-- ack:field:opening-message-matches-current-state -->
112
- - Opening message matches current state: TBD
113
- <!-- ack:field:next-ai-can-continue -->
114
- - Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD
115
-
116
- If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready.
117
-
118
- <!-- ack:section:handoff-sufficiency-check -->
119
- ## Handoff Sufficiency Check
120
-
121
- Can the next AI continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history?
122
-
123
- Answer: TBD
124
- If no, update this handoff before closeout.
125
-
126
- 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.
127
-
128
- <!-- ack:section:next-session-opening-message -->
129
- ## Next Session Opening Message
130
-
131
- This fenced block is the authoritative startup prompt. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. If the two differ, trust this block and rewrite the convenience copy.
132
-
133
- 📋 Next session: copy and paste the whole block below
134
-
135
- ```text
136
- Work in <absolute project root>.
137
-
138
- Read in order:
139
- 1. AGENTS.md
140
- 2. dev/SESSION_HANDOFF.md
141
- 3. dev/SESSION_LOG.md
142
- 4. dev/PROJECT_INDEX.md
143
- 5. dev/RULE_PACKS.md
144
-
145
- Read dev/DOC_SYNC_REGISTRY.md before file changes or closeout.
146
-
147
- If this root does not match the expected project root, stop and ask for confirmation.
148
-
149
- After reading, summarize current objective, task understanding, confirmed decisions, pending work, risks, and the next recommended action.
150
- ```
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` section is the project's authoritative declaration of installed Connectors / MCPs / Plugins / Skills + Source-of-truth Architecture sub-table. New AI session must read it after governance reads and run availability probe per `runtime-core/AGENTS.core.md` Section 1. Credential values never appear here or in any `dev/*` file — they live in AI tool secure storage only.
16
+
17
+ <!-- ack:section:closeout-reconciled-state -->
18
+ ## Closeout-Reconciled State
19
+
20
+ This is the current-state area. At every full closeout, rewrite or explicitly confirm every section below. Do not append a new state snapshot under an old one.
21
+
22
+ <!-- ack:section:current-baseline -->
23
+ ## Current Baseline
24
+
25
+ 1. Project root: TBD
26
+ 2. Product/system state: TBD
27
+ 3. Governance state: TBD
28
+ 4. Source-of-truth notes: TBD
29
+
30
+ <!-- ack:section:task-understanding-summary -->
31
+ ## Task Understanding Summary
32
+
33
+ <!-- ack:field:user-intent -->
34
+ - User intent: TBD
35
+ <!-- ack:field:task-essence -->
36
+ - Task essence: TBD
37
+ - User value: TBD
38
+ <!-- ack:field:success-criteria -->
39
+ - Success criteria: TBD
40
+ - Key background already read: TBD
41
+ - Background still unread or blocked: TBD
42
+ - Non-goals / boundaries: TBD
43
+
44
+ <!-- ack:section:active-objective -->
45
+ ## Active Objective
46
+
47
+ TBD
48
+
49
+ <!-- ack:section:completed-this-session -->
50
+ ## Completed This Session
51
+
52
+ Record only work actually completed in the current session.
53
+
54
+ 1. TBD
55
+
56
+ <!-- ack:section:next-priorities -->
57
+ ## Next Priorities
58
+
59
+ 1. TBD
60
+
61
+ <!-- ack:section:next-task-required-reading -->
62
+ ## Next Task Required Reading
63
+
64
+ Before acting on the next task, read or mark blocked:
65
+
66
+ | Source | Why required | Status |
67
+ |---|---|---|
68
+ | TBD | TBD | pending |
69
+
70
+ <!-- ack:section:risks-blockers -->
71
+ ## Risks / Blockers
72
+
73
+ 1. TBD
74
+
75
+ <!-- ack:section:validation-qc -->
76
+ ## Validation / QC
77
+
78
+ - Checks run this session: TBD
79
+ - Checks not run and why: TBD
80
+ - Handoff evidence location: TBD
81
+
82
+ <!-- ack:section:workspace-identity -->
83
+ ## Workspace Identity
84
+
85
+ Expected project root: TBD
86
+ Git root: TBD
87
+ Branch: TBD
88
+ Commit: TBD
89
+ Worktree / parallel workspace status: TBD
90
+ Uncommitted changes summary: TBD
91
+
92
+ <!-- ack:section:sync-status -->
93
+ ## Sync Status
94
+
95
+ Use statuses from `dev/DOC_SYNC_REGISTRY.md`: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.
96
+
97
+ - Project index: TBD
98
+ - Doc sync registry: TBD
99
+ - Public docs / README: TBD
100
+ - External knowledge tools: TBD
101
+
102
+ <!-- ack:section:state-reconciliation-check -->
103
+ ## State Reconciliation Check
104
+
105
+ At full closeout, complete this check after updating the state sections above.
106
+
107
+ - Reconciled at: TBD
108
+ <!-- ack:field:state-sections-rewritten-or-confirmed -->
109
+ - State sections rewritten or confirmed current: TBD
110
+ <!-- ack:field:stale-snapshots-left -->
111
+ - Stale snapshots left in this handoff: TBD
112
+ <!-- ack:field:opening-message-matches-current-state -->
113
+ - Opening message matches current state: TBD
114
+ <!-- ack:field:next-ai-can-continue -->
115
+ - Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD
116
+
117
+ If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready.
118
+
119
+ <!-- ack:section:handoff-sufficiency-check -->
120
+ ## Handoff Sufficiency Check
121
+
122
+ Can the next AI continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history?
123
+
124
+ Answer: TBD
125
+ If no, update this handoff before closeout.
126
+
127
+ 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.
128
+
129
+ <!-- ack:section:next-session-opening-message -->
130
+ ## Next Session Opening Message
131
+
132
+ This fenced block is the authoritative startup prompt. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. If the two differ, trust this block and rewrite the convenience copy.
133
+
134
+ 📋 Next session: copy and paste the whole block below
135
+
136
+ ```text
137
+ Work in <absolute project root>.
138
+
139
+ Read in order:
140
+ 1. AGENTS.md
141
+ 2. dev/SESSION_HANDOFF.md
142
+ 3. dev/SESSION_LOG.md
143
+ 4. dev/PROJECT_INDEX.md
144
+ 5. dev/RULE_PACKS.md
145
+
146
+ Read dev/DOC_SYNC_REGISTRY.md before file changes or closeout.
147
+
148
+ If this root does not match the expected project root, stop and ask for confirmation.
149
+
150
+ After reading, summarize current objective, task understanding, confirmed decisions, pending work, risks, and the next recommended action.
151
+ ```