@adamchanadam/agent-handoff-kit 0.3.39 → 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,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.3.39 | implementation candidate; not yet published |
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 |
@@ -2,24 +2,24 @@
2
2
 
3
3
  Read only the packs needed for the current task.
4
4
 
5
- | Task signal | Pack | Purpose |
6
- |---|---|---|
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 |
5
+ | Task signal | Pack | Purpose |
6
+ |---|---|---|
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 |
9
9
  | Destructive file operations, shell writes, Git state changes, package managers, installers, deploy, release, cloud tools, external APIs, credentials, locked files, permission errors | `dev/rules/safety.md` | safety checks for data loss, external systems, secrets, and high-risk operations |
10
10
  | Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
11
11
  | Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
12
12
  | Sources, evidence, comparison, fact finding | `dev/rules/research.md` | source handling and uncertainty |
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 |
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 |
22
22
 
23
23
  ## Routing Rule
24
24
 
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.
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` 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.
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
@@ -25,9 +25,9 @@ This is the current-state area. At every full closeout, rewrite or explicitly co
25
25
  1. Project root: TBD
26
26
  2. Product/system state: TBD
27
27
  3. Governance state: TBD
28
- 4. Source-of-truth notes: TBD
29
- <!-- ack:field:first-use-guidance-state -->
30
- 5. First-use guidance state: eligible
28
+ 4. Source-of-truth notes: TBD
29
+ <!-- ack:field:first-use-guidance-state -->
30
+ 5. First-use guidance state: eligible
31
31
 
32
32
  <!-- ack:section:task-understanding-summary -->
33
33
  ## Task Understanding Summary
@@ -55,12 +55,12 @@ Record only work actually completed in the current session.
55
55
 
56
56
  1. TBD
57
57
 
58
- <!-- ack:section:next-priorities -->
59
- ## Next Priorities
60
-
61
- Recommended next step: TBD — reason: TBD
62
-
63
- 1. TBD
58
+ <!-- ack:section:next-priorities -->
59
+ ## Next Priorities
60
+
61
+ Recommended next step: TBD — reason: TBD
62
+
63
+ 1. TBD
64
64
 
65
65
  <!-- ack:section:next-task-required-reading -->
66
66
  ## Next Task Required Reading
@@ -111,27 +111,27 @@ At full closeout, complete this check after updating the state sections above.
111
111
  - Reconciled at: TBD
112
112
  <!-- ack:field:state-sections-rewritten-or-confirmed -->
113
113
  - State sections rewritten or confirmed current: TBD
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.
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.
130
130
 
131
131
  <!-- ack:section:handoff-sufficiency-check -->
132
132
  ## Handoff Sufficiency Check
133
133
 
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?
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?
135
135
 
136
136
  Answer: TBD
137
137
  If no, update this handoff before closeout.
@@ -141,14 +141,14 @@ Continuity rule: this file carries current state and next action. `dev/SESSION_L
141
141
  <!-- ack:section:next-session-opening-message -->
142
142
  ## Next Session Opening Message
143
143
 
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
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
147
147
 
148
148
  ```text
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
- ```
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,35 +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 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
+ # 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,5 +1,5 @@
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.
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.