@adamchanadam/agent-handoff-kit 0.3.38 → 0.3.40

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,17 +1,17 @@
1
- # Antigravity / Gemini Entry Bridge
2
-
3
- This file is a bridge only. It exists for Google Antigravity CLI, Gemini CLI during migration, and compatible tools that still read `GEMINI.md`.
4
-
5
- Authoritative operating rules remain in `AGENTS.md`.
6
-
7
- Do not expand, summarize, replace, or "improve" this file during onboarding, setup, or project documentation work. Do not add command lists, architecture summaries, project state, or handoff notes here.
8
-
9
- Antigravity CLI may read both `AGENTS.md` and `GEMINI.md` from the active workspace. If `AGENTS.md` has already been loaded, do not treat this bridge as a second rule source and do not repeat the same instructions.
10
-
11
- At session startup:
12
-
13
- 1. Confirm the current root is the intended project root.
14
- 2. Read `AGENTS.md`.
15
- 3. Follow the startup read order in `AGENTS.md`.
16
-
17
- If the current root does not match the intended project root, stop and ask the user to confirm the workspace before reading or editing project state.
1
+ # Antigravity / Gemini Entry Bridge
2
+
3
+ This file is a bridge only. It exists for Google Antigravity CLI, Gemini CLI during migration, and compatible tools that still read `GEMINI.md`.
4
+
5
+ Authoritative operating rules remain in `AGENTS.md`.
6
+
7
+ Do not expand, summarize, replace, or "improve" this file during onboarding, setup, or project documentation work. Do not add command lists, architecture summaries, project state, or handoff notes here.
8
+
9
+ Antigravity CLI may read both `AGENTS.md` and `GEMINI.md` from the active workspace. If `AGENTS.md` has already been loaded, do not treat this bridge as a second rule source and do not repeat the same instructions.
10
+
11
+ At session startup:
12
+
13
+ 1. Confirm the current root is the intended project root.
14
+ 2. Read `AGENTS.md`.
15
+ 3. Follow the startup read order in `AGENTS.md`.
16
+
17
+ If the current root does not match the intended project root, stop and ask the user to confirm the workspace before reading or editing project state.
@@ -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 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)
@@ -6,7 +6,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
6
6
 
7
7
  | Field | Value | Last verified |
8
8
  |---|---|---|
9
- | Agent Handoff Kit template version | 0.1.7 | package prototype |
9
+ | Agent Handoff Kit template version | 0.3.40 | implementation candidate; not yet published |
10
10
  | Runtime | TBD | TBD |
11
11
  | Framework | TBD | TBD |
12
12
  | Package manager | TBD | TBD |
@@ -21,11 +21,12 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
21
21
  | `AGENTS.md` | primary Agent Handoff Kit entry and startup contract | session startup |
22
22
  | `CLAUDE.md` | Claude Code bridge to the same startup path | Claude Code startup |
23
23
  | `GEMINI.md` | Google Antigravity CLI / Gemini CLI migration bridge to the same startup path | Antigravity / Gemini startup |
24
- | `START_NEXT_SESSION_PROMPT.txt` | auto-generated stateful startup prompt for the next local-agent session; `dev/SESSION_HANDOFF.md` remains authoritative | next session startup |
24
+ | `START_NEXT_SESSION_PROMPT.txt` | portable generated mirror of the handoff opening-message block; `dev/SESSION_HANDOFF.md` remains authoritative | fallback when the next agent is not yet operating in this root; not an additional local startup read |
25
25
  | `src/` | application source | coding task |
26
26
  | `tests/` | tests | coding/QC |
27
27
  | `docs/` | user or product docs | doc/public behavior change |
28
- | `dev/` | governance state | startup/closeout |
28
+ | `dev/` | governance state | read the handoff at startup; other files are task-routed or closeout-routed |
29
+ | `dev/rules/closeout.md` | full closeout contract | clear end-of-session or handoff intent only |
29
30
  | `TBD` | local source-of-truth files | before tasks that depend on project facts |
30
31
  | `TBD` | external-source indexes or mirrors | before research, writing, or knowledge-sync tasks |
31
32
 
@@ -38,7 +39,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
38
39
  | Test suite | TBD | TBD |
39
40
  | Runbook | TBD | TBD |
40
41
  | Public docs | TBD | TBD |
41
- | Generated artifact review | `dev/PROJECT_INDEX.md` + `dev/DOC_SYNC_REGISTRY.md` | After creating Markdown docs, generated outputs, specs, runbooks, checklists, or research artifacts, classify each artifact as indexed / synced / temporary / one-time evidence before completion |
42
+ | Generated Markdown review | `dev/PROJECT_INDEX.md` + `dev/DOC_SYNC_REGISTRY.md` | After creating Markdown docs, generated Markdown outputs, specs, runbooks, checklists, or research notes, classify each file as indexed / synced / temporary / one-time evidence before completion; other durable formats require human review because doctor scans Markdown only |
42
43
 
43
44
  ## Fact Base
44
45
 
@@ -60,7 +61,7 @@ Reachable means the source can be found. It does not mean the source has been re
60
61
 
61
62
  > **Credential Separation Principle**: this section records only project usage and public reference coordinates such as Notion database names, URLs, or folder paths. It must never record API keys, OAuth tokens, or credential values. Credentials belong in AI runtime secure storage, OS credential stores, tool configuration, or user-managed secret stores. If an environment variable is used, record only the variable name, never the value. Before writing this section, self-check that no credential value is being persisted. Doctor scans this section, `SESSION_HANDOFF`, and `SESSION_LOG` for common credential prefixes such as `sk-`, `ntn_`, `ya29.`, `xoxp-`, `ghp_`, `sl.`, `AKIA`, and `AIza`.
62
63
 
63
- > Purpose: a new AI session reads this section to understand declared external-tool capabilities and their project roles. Declarations persist across sessions. Every entry must include `Declared` and `Last Verified` fields so stale capability assumptions can be detected.
64
+ > Purpose: tasks that use external tools read this section to understand declared capabilities and project roles. Declarations persist across sessions. A new session does not probe this table merely because it exists. `TBD`, examples, blanks, and placeholder-only rows are not installed integrations. Every real entry includes `Declared` and `Last Verified` so capability assumptions can be checked immediately before use.
64
65
 
65
66
  ### Connectors
66
67
 
@@ -106,13 +107,14 @@ Do not store credential values or machine-private paths here. Local machine-only
106
107
  | Tool / operation | Reference path or URL | Required before | Source and version/date | Scope and known limits | Last verified |
107
108
  |---|---|---|---|---|---|
108
109
  | TBD | TBD | TBD | TBD | TBD | TBD |
110
+ | Local HTML / app browser validation | TBD, for example project runbook or official browser-tool docs | Before validating local HTML, static app, generated guide, screenshot, click flow, or visual QA | TBD, include source and date | Prefer short-lived loopback localhost service when `file://` is blocked; record click/text/screenshot evidence and cleanup result; do not mutate user browser profiles or extension state | TBD |
109
111
 
110
112
  ## Local QC Commands
111
113
 
112
114
  | Check | Command | Run before | Last verified |
113
115
  |---|---|---|---|
114
116
  | Agent Handoff Kit doctor | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .` | closeout / governance changes / generated Markdown artifact checks | package latest |
115
- | Project governance check | Check newly created Markdown / durable artifacts against `dev/PROJECT_INDEX.md` and `dev/DOC_SYNC_REGISTRY.md`; register, sync, consolidate, or explicitly classify as temporary / one-time evidence | closeout / durable file changes | unverified until project-specific command exists |
117
+ | Project governance check | Check newly created Markdown against `dev/PROJECT_INDEX.md` and `dev/DOC_SYNC_REGISTRY.md`; register, sync, consolidate, or explicitly classify as temporary / one-time evidence. Review non-Markdown durable outputs manually. | closeout / durable file changes | unverified until project-specific command exists |
116
118
 
117
119
  ## Workspace Identity
118
120
 
@@ -134,8 +136,8 @@ Record this at closeout so the next AI can detect wrong-root or workspace drift.
134
136
  | UI behavior | TBD | build + visual/manual check |
135
137
  | Data model | TBD | migration/checks |
136
138
  | Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
137
- | Generated Markdown or durable artifact | `docs/`, `outputs/`, root Markdown files, project-specific reference folders | classify as indexed / synced / temporary / one-time evidence; update `dev/PROJECT_INDEX.md` or `dev/DOC_SYNC_REGISTRY.md` when durable |
138
- | 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 + workspace identity current + prompt file regenerated from handoff at closeout |
139
+ | Generated Markdown | `docs/`, `outputs/`, root Markdown files, project-specific reference folders | classify as indexed / synced / temporary / one-time evidence; update `dev/PROJECT_INDEX.md` or `dev/DOC_SYNC_REGISTRY.md` when durable; review other formats manually |
140
+ | 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 |
139
141
 
140
142
  ## External Services
141
143
 
@@ -4,21 +4,22 @@ Read only the packs needed for the current task.
4
4
 
5
5
  | Task signal | Pack | Purpose |
6
6
  |---|---|---|
7
- | First-time user signals: "I'm new" / "new user" / "teach me" / "help me start" / "first time" / "I just installed" / "how do I start" / "show me how" / "getting started" / "what can agent handoff kit do" / vague first message <= 30 chars / HANDOFF Active Objective empty + Session count 1 (fresh installation context). Also recognize equivalent Chinese user phrases such as "新手", "教我用", "我剛安裝", "點開始", "開工", and "能力". | `dev/rules/onboarding.md` | first-time user walk-through with 6 scenarios (A build / B research report / C knowledge base / D learning to code / E custom / F external-tool governance) x 5-step pattern (confirm context / explain fit / ask task scope / suggest minimum viable task / confirm + transition); load proactively when signal present; transient pack, unload after onboarding completion |
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 or "I just installed" is eligibility context, not a forced route. `Start Agent Handoff` / "開工" is continuity. | `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 no executable objective remains |
8
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 |
9
10
  | Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
10
11
  | Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
11
12
  | 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
- | Governance bridge / bridge governance / connect this document to governance / scan for unbridged governance documents. Also recognize equivalent Chinese user phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", and "掃描未接入 Agent Handoff Kit 的重要文件". | `dev/rules/agent-governance.md` | connect important files, source-of-truth documents, runbooks, workflows, checklists, and guides to the project index, sync registry, handoff/log roles, and related workflows without creating duplicate sources of truth |
14
- | Long-term governance routing / future sessions should remember / always use this API or MCP pattern. Also recognize equivalent Chinese user phrases such as "寫入長期治理", "轉成長期機制", "之後都要遵守", and "跨 session 有效". | `dev/rules/agent-governance.md` | classify durable non-file knowledge by role and store it in the right home: rule pack, registered reference, project index, sync registry, project decisions, or QA check; do not leave reusable governance only in session log or handoff |
15
- | Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
16
- | External notes, knowledge base, Notion, Obsidian, Google Drive | `dev/rules/knowledge.md` | external knowledge source integration |
17
- | External tool integrations (Connector / MCP / Plugin / Skill) — declared in `## Installed Integrations`; tasks involving Notion / Google 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 |
18
- | Runtime-controlled tool operation / browser UI validation / visual QA / screenshot / Chrome / Playwright / DevTools / desktop app automation / crawler or scraper / notebook or data runtime / raw CLI, SDK, tool server, MCP, plugin, or local helper operation | `dev/rules/integrations.md` + `dev/rules/safety.md` (add `dev/rules/coding.md` only when changing code, tests, or project scripts) | verify the active runtime capability, current schema, official docs, or registered tool operation reference before invocation; block or use a manual packet when unavailable; preserve ownership and cleanup boundaries |
19
- | External tool resource pressure / stale MCP process / plugin service leak / browser automation left running / cache growth after external tools / slowdown after MCP, plugin, browser, crawler, notebook, or local helper services | `dev/rules/integrations.md` + `dev/rules/safety.md` | ownership-based external-tool resource closeout; task-owned cleanup allowed; shared or ambiguous remediation requires exact evidence and confirmation |
20
- | Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |
13
+ | Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |
14
+ | Governance bridge / bridge governance / connect this document to governance / scan for unbridged governance documents. Also recognize equivalent Chinese user phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", and "掃描未接入 Agent Handoff Kit 的重要文件". | `dev/rules/agent-governance.md` | <!-- ack:route:governance-bridge --> connect important files, source-of-truth documents, runbooks, workflows, checklists, and guides to the project index, sync registry, handoff/log roles, and related workflows without creating duplicate sources of truth |
15
+ | Long-term governance routing / future sessions should remember / always use this API or MCP pattern. Also recognize equivalent Chinese user phrases such as "寫入長期治理", "轉成長期機制", "之後都要遵守", and "跨 session 有效". | `dev/rules/agent-governance.md` | <!-- ack:route:long-term-governance --> classify durable non-file knowledge by role and store it in the right home: rule pack, registered reference, project index, sync registry, project decisions, or QA check; do not leave reusable governance only in session log or handoff |
16
+ | Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
17
+ | External notes, knowledge base, Notion, Obsidian, Google Drive | `dev/rules/knowledge.md` | external knowledge source integration |
18
+ | A task that actually uses an external Connector / MCP / Plugin / Skill; a handoff that declares one as a current-task dependency; or an explicit integration health check | `dev/rules/integrations.md` | <!-- ack:route:integration-use --> capability verification immediately before use, credential separation, source-of-truth boundaries, fallback, and cross-session resilience; registry placeholders alone do not load or probe |
19
+ | Runtime-controlled tool operation / browser UI validation / visual QA / screenshot / local HTML validation / file:// blocked / `file://` blocked / localhost fallback / Chrome / Playwright / DevTools / desktop app automation / crawler or scraper / notebook or data runtime / raw CLI, SDK, tool server, MCP, plugin, or local helper operation | `dev/rules/integrations.md` + `dev/rules/safety.md` (add `dev/rules/coding.md` only when changing code, tests, or project scripts) | <!-- ack:route:runtime-tool --> verify the active runtime capability, current schema, official docs, or registered tool operation reference before invocation; for local HTML / app validation, a blocked `file://` surface must route to a registered operation reference or short-lived localhost fallback before declaring blocked; preserve ownership and cleanup boundaries |
20
+ | External tool resource pressure / stale MCP process / plugin service leak / browser automation left running / cache growth after external tools / slowdown after MCP, plugin, browser, crawler, notebook, or local helper services | `dev/rules/integrations.md` + `dev/rules/safety.md` | <!-- ack:route:resource-closeout --> ownership-based external-tool resource closeout; task-owned cleanup allowed; shared or ambiguous remediation requires exact evidence and confirmation |
21
+ | Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |
21
22
 
22
23
  ## Routing Rule
23
24
 
24
- 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.
25
+ Load the minimum set. If uncertain, load the narrower pack first. Pack selection is normally silent; state it only when it changes risk or user action. If a task clearly involves safety risk plus another domain, load `dev/rules/safety.md` with the relevant domain pack. Packs can add stricter rules, but cannot weaken core safety or continuity.
@@ -12,7 +12,7 @@ Stable facts that should survive across sessions. Update only when they change,
12
12
  3. Governance model: TBD
13
13
  4. Source-of-truth ownership: TBD
14
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 — only credential references such as AI tool secure storage, OS credential store, tool config, user-managed secret store, or env var name may be recorded.
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
16
 
17
17
  <!-- ack:section:closeout-reconciled-state -->
18
18
  ## Closeout-Reconciled State
@@ -26,6 +26,8 @@ This is the current-state area. At every full closeout, rewrite or explicitly co
26
26
  2. Product/system state: TBD
27
27
  3. Governance state: TBD
28
28
  4. Source-of-truth notes: TBD
29
+ <!-- ack:field:first-use-guidance-state -->
30
+ 5. First-use guidance state: eligible
29
31
 
30
32
  <!-- ack:section:task-understanding-summary -->
31
33
  ## Task Understanding Summary
@@ -53,12 +55,12 @@ Record only work actually completed in the current session.
53
55
 
54
56
  1. TBD
55
57
 
56
- <!-- ack:section:next-priorities -->
57
- ## Next Priorities
58
-
59
- Recommended next step: TBD — reason: TBD
60
-
61
- 1. TBD
58
+ <!-- ack:section:next-priorities -->
59
+ ## Next Priorities
60
+
61
+ Recommended next step: TBD — reason: TBD
62
+
63
+ 1. TBD
62
64
 
63
65
  <!-- ack:section:next-task-required-reading -->
64
66
  ## Next Task Required Reading
@@ -109,27 +111,27 @@ At full closeout, complete this check after updating the state sections above.
109
111
  - Reconciled at: TBD
110
112
  <!-- ack:field:state-sections-rewritten-or-confirmed -->
111
113
  - State sections rewritten or confirmed current: TBD
112
- <!-- ack:field:stale-snapshots-left -->
113
- - Stale snapshots left in this handoff: TBD
114
- <!-- ack:field:lifecycle-conflicts-resolved -->
115
- - Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD
116
- <!-- ack:field:persistence-routing-checked -->
117
- - Persistence routing checked: TBD
118
- <!-- ack:field:recommended-next-step-explicit -->
119
- - Recommended next step is explicit and reasoned: TBD
120
- <!-- ack:field:opening-message-matches-current-state -->
121
- - Opening message matches current state: TBD
122
- <!-- ack:field:next-ai-can-continue -->
123
- - Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD
124
-
125
- If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready.
126
-
127
- Lifecycle consistency rule: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. 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. 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.
114
+ <!-- ack:field:stale-snapshots-left -->
115
+ - Stale snapshots left in this handoff: TBD
116
+ <!-- ack:field:lifecycle-conflicts-resolved -->
117
+ - Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD
118
+ <!-- ack:field:persistence-routing-checked -->
119
+ - Persistence routing checked: TBD
120
+ <!-- ack:field:recommended-next-step-explicit -->
121
+ - Recommended next step is explicit and reasoned: TBD
122
+ <!-- ack:field:opening-message-matches-current-state -->
123
+ - Opening message matches current state: TBD
124
+ <!-- ack:field:next-ai-can-continue -->
125
+ - Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD
126
+
127
+ If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready.
128
+
129
+ 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.
128
130
 
129
131
  <!-- ack:section:handoff-sufficiency-check -->
130
132
  ## Handoff Sufficiency Check
131
133
 
132
- Can the next AI continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history?
134
+ 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?
133
135
 
134
136
  Answer: TBD
135
137
  If no, update this handoff before closeout.
@@ -139,25 +141,14 @@ Continuity rule: this file carries current state and next action. `dev/SESSION_L
139
141
  <!-- ack:section:next-session-opening-message -->
140
142
  ## Next Session Opening Message
141
143
 
142
- This fenced block is the authoritative agent-managed startup content. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. 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.
143
-
144
- 📋 Next session: agent-managed startup content below
144
+ This fenced block is the authoritative agent-managed startup content. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. 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.
145
+
146
+ 📋 Next session: agent-managed startup content below
145
147
 
146
148
  ```text
147
- Work in <absolute project root>.
148
-
149
- Read in order:
150
- 1. AGENTS.md
151
- 2. dev/SESSION_HANDOFF.md
152
- 3. dev/SESSION_LOG.md
153
- 4. dev/PROJECT_INDEX.md
154
- 5. dev/RULE_PACKS.md
155
-
156
- Read dev/DOC_SYNC_REGISTRY.md before file changes or closeout.
157
-
158
- If this root does not match the expected project root, stop and ask for confirmation.
159
-
160
- This is the first startup after installing Agent Handoff Kit. Load the onboarding guidance from dev/RULE_PACKS.md when appropriate. Help me choose the right working scenario, then guide me through the first task step by step.
161
-
162
- Before changing anything, tell me the current state and your recommended next step.
163
- ```
149
+ Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Trust the handoff over this generated mirror.
150
+
151
+ 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.
152
+
153
+ Resume the current objective. If my message or the handoff already gives an executable task, begin its first safe action in this response. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.
154
+ ```
@@ -1,57 +1,35 @@
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 must run the maintenance trigger check per `AGENTS.md` `## Closeout And Handoff` step 11 (R-010 SESSION_LOG handoff-role discipline): N=1–3 keep full, N=4–10 may short-index after absorbed-source check when triggered, N=11+ archive into `dev/SESSION_LOG_archive/`.
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, unresolved risks, or the latest opening message.
14
-
15
- <!-- ack:section:session-log-entry-template -->
16
-
17
- ## Entry Template
18
-
19
- ````markdown
20
- <!-- ack:log-entry:start -->
21
- ## <YYYY-MM-DD> — <short session title>
22
-
23
- - **ID:** <agent_or_session_id>
24
- - **Summary:** <one sentence>
25
- - **Changed:** <files changed, or none>
26
- - **Done:** <work completed this session>
27
- - **QC:** <checks run and results, or why not run>
28
- - **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>
29
- - **Sync:** <doc/external sync status>
30
- - **Pending:** <next work>
31
- - **Risks:** <known risks or none>
32
- - **Log maintenance:** <trigger check result; full maintenance action if triggered, otherwise no-op reason>
33
-
34
- ### Next Session Opening Message
35
-
36
- 📋 Next session: agent-managed startup content below
37
-
38
- ```text
39
- Work in <absolute project root>.
40
-
41
- Read in order:
42
- 1. AGENTS.md
43
- 2. dev/SESSION_HANDOFF.md
44
- 3. dev/SESSION_LOG.md
45
- 4. dev/PROJECT_INDEX.md
46
- 5. dev/RULE_PACKS.md
47
-
48
- Read dev/DOC_SYNC_REGISTRY.md before file changes or closeout.
49
-
50
- If this root does not match the expected project root, stop and ask for confirmation.
51
-
52
- This is the first startup after installing Agent Handoff Kit. Load the onboarding guidance from dev/RULE_PACKS.md when appropriate. Help me choose the right working scenario, then guide me through the first task step by step.
53
-
54
- Before changing anything, tell me the current state and your recommended next step.
55
- ```
56
- <!-- ack:log-entry:end -->
57
- ````
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 must run the maintenance trigger check per `AGENTS.md` `## Closeout And Handoff` step 11 (R-010 SESSION_LOG handoff-role discipline): N=1–3 keep full, N=4–10 may short-index after absorbed-source check when triggered, N=11+ archive into `dev/SESSION_LOG_archive/`.
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
+ ````markdown
20
+ <!-- ack:log-entry:start -->
21
+ ## <YYYY-MM-DD> — <short session title>
22
+
23
+ - **ID:** <agent_or_session_id>
24
+ - **Summary:** <one sentence>
25
+ - **Changed:** <files changed, or none>
26
+ - **Done:** <work completed this session>
27
+ - **QC:** <checks run and results, or why not run>
28
+ - **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>
29
+ - **Sync:** <doc/external sync status>
30
+ - **Pending:** <next work>
31
+ - **Risks:** <known risks or none>
32
+ - **Log maintenance:** <trigger check result; full maintenance action if triggered, otherwise no-op reason>
33
+ - **Opening-message mirror:** <regenerated and verified / blocked; full text omitted by design>
34
+ <!-- ack:log-entry:end -->
35
+ ````
@@ -1,16 +1,5 @@
1
- Work in <absolute project root>.
2
-
3
- Read in order:
4
- 1. AGENTS.md
5
- 2. dev/SESSION_HANDOFF.md
6
- 3. dev/SESSION_LOG.md
7
- 4. dev/PROJECT_INDEX.md
8
- 5. dev/RULE_PACKS.md
9
-
10
- Read dev/DOC_SYNC_REGISTRY.md before file changes or closeout.
11
-
12
- If this root does not match the expected project root, stop and ask for confirmation.
13
-
14
- This is the first startup after installing Agent Handoff Kit. Load the onboarding guidance from dev/RULE_PACKS.md when appropriate. Help me choose the right working scenario, then guide me through the first task step by step.
15
-
16
- Before changing anything, tell me the current state and your recommended next step.
1
+ Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Trust the handoff over this generated mirror.
2
+
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
+
5
+ Resume the current objective. If my message or the handoff already gives an executable task, begin its first safe action in this response. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.