@adamchanadam/agent-handoff-kit 0.3.37 → 0.3.39

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,190 +1,112 @@
1
- # Agent Handoff Kit Core Runtime
2
-
3
- This is the lightweight core. It is the always-read contract for AI sessions.
4
-
5
- ## 1. Startup Reads
6
-
7
- After this core is loaded, read in order:
8
-
9
- 1. `dev/SESSION_HANDOFF.md`
10
- 2. the latest entry in `dev/SESSION_LOG.md`
11
- 3. `dev/PROJECT_INDEX.md`
12
- 4. `dev/RULE_PACKS.md`
13
-
14
- Then classify the user's task and read only the required rule pack(s). State which pack(s) you loaded and why, using plain language so the user understands the working mode without needing to know pack names.
15
-
16
- Before classifying the task, detect first-time-user signals (R-029): if the user's first message in this session is short, vague, contains onboarding signal keywords such as "I'm new", "help me start", "first time", "I just installed", "how do I start", "show me how", or equivalent Chinese phrases such as "新手", "教我用", "我剛安裝", "點開始", or if the session is a fresh installation (HANDOFF Active Objective empty + Session count 1), load `dev/rules/onboarding.md` proactively before doing the regular task loop. The onboarding pack surfaces the AI's role and offers Scenario A-F selection instead of immediately diving into task execution. Onboarding is a transient pack: after the user completes the first-task walk-through, unload it and load the regular scenario pack (coding / research / writing / knowledge / etc.) for ongoing work.
17
-
18
- If the user did not paste the previous opening message but the current project root is clear, read `AGENTS.md` first as fallback entry, then use this read order. If the root is unclear or mismatched, stop and ask for the intended project root before reading or editing project state.
19
-
20
- Detect clear startup / handoff-start intent in natural language, such as "開工", "Start Agent Handoff", "開始接力", or "continue handoff". When that intent is clear and the current project root is clear, open `START_NEXT_SESSION_PROMPT.txt` and follow the opening message inside. If `START_NEXT_SESSION_PROMPT.txt` is missing or seems stale, read `dev/SESSION_HANDOFF.md` instead. Before changing anything, tell the user the current state and your recommended next step.
21
-
22
- Ambiguous startup phrases need one concise confirmation question before treating them as Agent Handoff Kit startup. In particular, if the user says "<something> 開工", "<something> start", or similar wording that may refer to a real-world shift, event, project phase, or another context, ask whether they mean to start Agent Handoff Kit continuity for this project.
23
-
24
- If a required file is missing, create the smallest useful version only after confirming the target project root.
25
-
26
- Before acting on a non-trivial task, identify required local source-of-truth files and external sources from the handoff, project index, user request, and sync registry. Read them or mark them blocked. Reachable is not the same as ingested. Do not treat unread sources as absent. If tool output is truncated, paginated, or only a search hit, continue reading the relevant source or mark coverage as partial; do not present a complete conclusion from partial output.
27
-
28
- When creating or materially changing Markdown files, generated documents, research outputs, specifications, runbooks, checklists, guides, or other durable artifacts, do not leave them as orphan files. Before claiming the task is complete, classify each new or materially changed artifact as one of: draft / one-time evidence, source of truth, reference, runbook, workflow, public document, generated output, or intentionally temporary. Then either register it in `dev/PROJECT_INDEX.md` with a role and read condition, register a sync obligation in `dev/DOC_SYNC_REGISTRY.md`, point to an existing authoritative home and mark the file as non-authoritative, or explicitly record why it is temporary / one-time evidence. If several files carry the same durable rule or requirement, consolidate or point to the single authoritative home instead of creating parallel truth.
29
-
30
- After reading `dev/PROJECT_INDEX.md`, if `## Installed Integrations` is non-empty, run startup availability probe (R-030 Integration governance discipline; see `dev/rules/integrations.md`):
31
-
32
- - For each declared Integration under Connectors / MCPs subsection, attempt a minimal capability probe using the active runtime's currently exposed tool name, description, and input schema. Do not invent `mcp__*` names or arguments from examples or memory.
33
- - If probe succeeds: update the corresponding `Last Verified` cell to today's date; proceed normally.
34
- - If probe fails (current AI tool lacks the Connector / auth expired / network issue): print warning in the startup card (`⚠️ Boundary` line) noting which Integration is declared-but-unavailable + that this session will fallback to paste flow when that external surface is touched. Do not attempt to auto-fix auth or credential issues; surface to the user to handle via the AI tool's own settings interface.
35
- - Credential separation: AI must never request, log, or persist credential values (API keys / OAuth tokens / app secrets / refresh tokens). Credentials live in OS-level secure storage or AI-tool-specific config, never in `dev/*` files. Recognize common credential prefixes (`sk-`, `sk-ant-`, `ntn_`, `secret_`, `ya29.`, `1//`, `xoxp-`, `xoxb-`, `ghp_`, `gho_`, `ghs_`, `github_pat_`, `sl.`, `AKIA`, `AIza`) and redact + warn the user to rotate the token if accidentally pasted.
36
-
37
- After startup reads are complete, show one short startup card. If onboarding is loaded, combine this card and the onboarding choice list into one first response. Do not print any standalone startup card before the onboarding rule has been read. Do not print a partial card. Do not print the cat banner twice. If you started drafting a card and then discovered onboarding applies, discard the draft and output only the final combined response.
38
-
39
- Display version rule: after reading `dev/PROJECT_INDEX.md`, take the card version from the `## Stack` row `Agent Handoff Kit template version`. Print it as `vX.Y.Z`. If that row is missing, unreadable, or not a version, print `version unverified`. Never print the literal placeholder `v<version>` in user-facing startup or closeout output.
40
-
41
- ```text
42
- /\_/\ Agent Handoff Kit v<version>
43
- ( o.o ) continuity ready
44
- > ^ <
45
-
1
+ # Agent Handoff Kit Core Runtime
2
+
3
+ This is the small always-read contract. Detailed task and closeout procedures live in routed packs.
4
+
5
+ ## 1. Intent And Startup
6
+
7
+ Classify the user's visible intent before loading project state. For explicit continuity, closeout, or a task whose next action depends on persisted project state, read `dev/SESSION_HANDOFF.md` first; it is the current-state authority. A direct ordinary or stateless task does not read the handoff merely because the project root is known. If the message is genuinely unresolved and the handoff can resolve it, read the handoff before asking the user.
8
+
9
+ Do not read `dev/SESSION_LOG.md` during ordinary startup; it is trace-back evidence only. Do not read `START_NEXT_SESSION_PROMPT.txt` in addition to the handoff when already operating in the project root; that file is a portable generated mirror for an agent that has not yet been pointed at the root.
10
+
11
+ Route intent in this order:
12
+
13
+ 1. Clear closeout intent routes directly to `dev/rules/closeout.md`.
14
+ 2. Clear continuity intent such as "開工", "Start Agent Handoff", "開始接力", or "continue handoff" resumes from the handoff. If the same message or loaded state contains a concrete objective, begin its first safe action in the same response.
15
+ 3. A direct ordinary task begins without a startup card or onboarding ceremony. Read only the sources and packs required by that task.
16
+ 4. Explicit guidance requests such as "I'm new", "teach me", "help me start", "新手", "教我用", or "點開始" may load `dev/rules/onboarding.md`. A fresh install or short message only makes guidance available; it never overrides a concrete objective. If no executable objective remains after state reading, ask one concise question or offer guided onboarding.
17
+
18
+ Treat a phrase as ambiguous only when its ordinary meaning may genuinely refer to a real-world shift, event, or unrelated context. `開工,繼續 <task>`, `<project> 開工`, and `Start Agent Handoff and continue <task>` are continuity commands, not ambiguous phrases.
19
+
20
+ Read `dev/PROJECT_INDEX.md` when the task needs its file, command, integration, workspace, or source map. Read `dev/RULE_PACKS.md` when a task pack must be selected. Read `dev/DOC_SYNC_REGISTRY.md` before durable cross-file or external synchronization and during closeout. Pack loading is normally silent; explain it only when it changes risk, requires a user decision, or materially affects the next action.
21
+
22
+ If the user supplies the portable startup prompt, use it to locate the root, then trust the handoff over the mirror. If the root is unclear or mismatched, stop and ask for the intended root before reading or editing project state. Missing required governance files are a repair condition, not permission to invent a parallel structure.
23
+
24
+ Before a non-trivial task, identify and read the required local and external truth sources or mark them blocked. Reachable is not the same as ingested. Search hits, truncated output, summaries, and status claims do not replace the relevant source content.
25
+
26
+ Probe an integration only immediately before a task uses it, when the handoff explicitly identifies it as a dependency for the current objective, or when the user requests an integration health check. `TBD`, examples, blank rows, and undeclared placeholders are not installed integrations. Record `Last Verified` only after a real probe and through the normal persistence gate. Never write integration status merely because a session started.
27
+
28
+ Show the startup card only for explicit continuity startup. Combine it with the first useful task action when the objective is clear; do not spend a separate response on the card. Direct ordinary tasks do not show the card. If onboarding is explicitly requested, combine any card and guidance in one response.
29
+
30
+ Use a verified version already present in loaded state. If obtaining it would require reading an otherwise unnecessary file, print `version unverified`; do not create a second version source merely to fill the card.
31
+
32
+ ```text
33
+ /\_/\ Agent Handoff Kit v<version>
34
+ ( o.o ) continuity ready
35
+ > ^ <
36
+
46
37
  🔎 交接狀態:<loaded / new install / resumed>
47
38
  📌 目前目標:<current objective>
48
39
  ⚠️ 注意事項:<important boundary or none>
49
- 🚀 推薦下一步:<one recommended next action + short reason>
40
+ 🚀 推薦下一步:<one action + reason>
50
41
  ```
51
42
 
52
- Keep the card short. Use plain Traditional Chinese labels in user-facing output. Use the full product name, not an abbreviation. The next-step line must name the recommended action, not only list possible work. If there are several valid paths, state the best first action and the reason; offer choices only when the user must decide.
53
-
54
- ## 2. Work Loop
55
-
56
- Use this loop for every task:
57
-
58
- 1. PLAN: restate the user's intent, scope, risk, and acceptance criteria.
59
- 2. READ: inspect relevant files from `PROJECT_INDEX.md` and search for related definitions before editing.
60
- 3. CHANGE: make focused changes only.
61
- 4. QC: run available checks or state why they cannot run.
62
- 5. PERSISTENCE GATE: decide whether this task produced a durable fact before writing governance files. A durable fact is information the next agent cannot reliably reconstruct and that affects future action.
63
- 6. ARTIFACT GOVERNANCE GATE: if the task created or changed Markdown documents or other durable artifacts, verify they are indexed, synced, consolidated, or explicitly classified as temporary / one-time evidence before declaring completion.
64
-
65
- External skill flows, subagents, task plans, or another tool's "finish" step do not replace this loop. If you use any of them, the PLAN must include a final Agent Handoff Kit persistence-gate check for the active project root, and completion cannot be claimed until that check is answered at the correct tier.
66
-
67
- For high-risk work, pause after PLAN. High-risk means destructive operations, ambiguous target, external systems, release/publish, or broad multi-file change.
68
-
69
- ## 2.1 Persistence Gate
70
-
71
- Use exactly one of these tiers after each task:
72
-
73
- 1. No persistence: choose this when the task produced no durable fact. Examples: one-off answers, active draft / image iterations not approved as final, routine successful checks that can be rerun, transient tool output, and ordinary progress that remains visible in the current chat.
74
- 2. Lightweight checkpoint: choose this when a durable fact exists and the session continues, when the agent may be interrupted before full closeout, or when uncertain whether the fact is durable. Write only the smallest correct home. Lightweight checkpoint is not full closeout: do not regenerate `START_NEXT_SESSION_PROMPT.txt`, do not show a closeout card, do not run full closeout maintenance, and do not reconcile every handoff section unless the fact itself requires it.
75
- 3. Full closeout: choose this only for explicit end-of-session / handoff intent, tool or day boundary, user-requested handoff, agent about to stop, or completed release / external sync / governance change that needs the next agent to continue from persisted state.
76
-
77
- Task contract changes are durable facts when they affect future action. If the user adds or changes the product goal, requirements, development checklist, acceptance rules, exclusions, priority, or task scope during a long-running task, first reconcile those changes into one current task contract before continuing. If a dedicated spec, backlog, issue, runbook, or project document is already the authoritative home, update that home and cite it from `dev/SESSION_HANDOFF.md`; otherwise merge the current contract into `dev/SESSION_HANDOFF.md` under `Task Understanding Summary`, `Active Objective`, `Next Priorities`, and `Next Task Required Reading`. Do not scatter the same task contract across chat memory, log entries, draft docs, and startup prompts.
78
-
79
- Route durable facts by file role:
80
-
81
- - Current objective, recommended next action with reason, unresolved risk, blocker, or a fact needed at startup belongs in `dev/SESSION_HANDOFF.md`.
82
- - Chronological evidence, command output, validation result, and research trace belongs in `dev/SESSION_LOG.md` when it affects future action or cannot be cheaply rerun. Routine successful checks that can be rerun are not durable facts.
83
- - File maps, command maps, reference maps, source locations, and installed capability maps belong in `dev/PROJECT_INDEX.md`.
84
- - Sync obligations across repositories, docs, mirrors, or external surfaces belong in `dev/DOC_SYNC_REGISTRY.md`.
85
- - Long-term decisions, architecture trade-offs, durable rationale, and research-derived decisions belong in `dev/PROJECT_DECISIONS.md`. Use project decisions for long-term decisions that future agents may need to explain or revisit.
86
- - Reusable operating procedures and practice-to-mechanism lessons belong in the relevant rule pack, registered reference, or QA check. Do not store reusable procedure knowledge only in handoff or log.
87
-
88
- External Impact Note: if a task reads from, writes to, generates artifacts for, pushes, publishes, or updates anything outside the expected project root confirmed at startup, record one concise note per external target as soon as the external effect is complete; full closeout later reconciles the note. The note must state the target, action, status, read-back verification, what the next AI must not assume, and a safe evidence reference. Status must describe verified facts only: read-only, local impact, external sync with sync type, or unverified known impact. Do not scan sibling folders, infer unscanned targets are clean, write another workspace's handoff without explicit authorization, or use the note as permission to clean, stash, commit, push, publish, or release. If the target handoff was not updated, say so; if read-only material was summarized or persisted, say so without leaking secrets or private content.
89
-
90
- Do not persist one-time delivery instructions, old hashes, old version facts, incident notes, routine green validation, or unapproved draft status as current state, next priorities, durable anchors, or startup instructions. If an involuntary stop is likely and a durable fact has not yet been written, make a lightweight checkpoint before stopping. If uncertain whether a fact is durable, choose lightweight checkpoint.
91
-
92
- ## 2.2 Upgrade Done Contract
93
-
94
- `agent-handoff-kit upgrade` is considered complete only when all of the following hold. The CLI enforces this contract; do not declare upgrade success without it.
95
-
96
- 1. `AGENTS.md` health state is `clean`: exactly one `# Agent Handoff Kit Core Runtime` heading, exactly one paired managed-core marker block, and no unmarked stale core ranges. Sandwich states (managed marker plus an unmarked stale core) are not clean; the installer must replace the stale ranges, not skip.
97
- 2. The CLI runs `doctor` automatically against the upgraded root after writes complete. `doctor` must report `status: passed` across required files, anchors, schema checks, handoff lifecycle checks, and credential separation checks. A `START_NEXT_SESSION_PROMPT.txt` convenience-copy warning does not block upgrade health; that file is regenerated at full closeout.
98
- 3. The migration report records every action taken, with backup paths for merged files.
99
-
100
- If any check fails, the upgrade did not finish; resolve the failure (or hand the failure output to the user) before reporting completion. This contract is the single source of truth for upgrade success; downstream QA scripts and release-grade QA derive their assertions from it.
101
-
102
- ## 3. Safety Boundaries
103
-
104
- Do not delete, reset, overwrite, bulk-move, or publish without explicit user approval.
105
-
106
- Do not guess commands, APIs, SDK behavior, deployment steps, or file ownership when project docs or official docs are needed. Mark unverified facts as unverified.
107
-
108
- Do not modify unrelated files. If unexpected user changes appear, work with them or ask before touching them.
109
-
110
- Do not claim completion without evidence from checks, inspection, or a clear explanation of what could not be verified.
111
-
112
- ## 4. Closeout And Handoff
113
-
114
- Detect end-of-session or handoff intent in natural language, such as "收工", "Wrap up Agent Handoff", "closeout", "wrap up", or "handoff". If intent is ambiguous, ask one concise confirmation question.
115
-
116
- Ambiguous closeout phrases need one concise confirmation question before full closeout. In particular, if the user says "<something> 收工", "<something> close", or similar wording that may refer to a real-world shift, event, project phase, or another context, ask whether they mean to wrap up Agent Handoff Kit and write the project handoff.
117
-
118
- If the user sends only a clear closeout phrase such as "收工", "wrap up", "handoff", or "Wrap up Agent Handoff", do not answer with a summary-only message. Enter full closeout immediately: announce that Agent Handoff Kit closeout is starting, read the current handoff/log/index, reconcile state, write the required files, run the available checks, and only then show the closeout card. A final chat summary without updated handoff/log/prompt evidence is not closeout.
119
-
120
- At full closeout:
121
-
122
- Closeout Write Contract: before writing `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, or `START_NEXT_SESSION_PROMPT.txt`, classify each fact by role and write it to the matching structured area. Use one Agent Handoff Kit marker standard as the machine boundary: `ack:section:*` for sections, `ack:field:*` for fields, `ack:log-entry:start/end` for log entries, and managed-core BEGIN/END for the installed AGENTS core. Do not remove or translate these markers. New closeout writes must use this marker standard; natural-language headings are only human labels, and legacy heading fallback is only for migration / repair of older installs. Current state and next action go only in `dev/SESSION_HANDOFF.md`. Trace evidence, one-time tasks, old build / release / hash facts, and completed delivery details go only in `dev/SESSION_LOG.md` unless promoted to `dev/PROJECT_INDEX.md`, `dev/PROJECT_DECISIONS.md`, `dev/DOC_SYNC_REGISTRY.md`, or a rule pack. `START_NEXT_SESSION_PROMPT.txt` is regenerated from the handoff opening-message block; do not hand-write separate startup state there.
123
-
124
- 1. Reconcile `dev/SESSION_HANDOFF.md`. Do not append a new state snapshot under old state. Verify `Durable Anchors`, then rewrite or explicitly confirm every section under `Closeout-Reconciled State`.
125
- 2. Add a concise entry to `dev/SESSION_LOG.md` with work actually completed this session and the exact next-session opening message.
126
- 3. Update `dev/PROJECT_INDEX.md` if files, stack, commands, entry points, workspace identity, or durable document map changed.
127
- 4. Check `dev/DOC_SYNC_REGISTRY.md` and record required sync status.
128
- 5. Record unresolved drift risk, active worktree, parallel workspace, uncommitted changes, or blocked verification.
129
- 6. If this session used external tools such as Connectors, MCPs, plugins, browser automation, DevTools, Playwright, crawlers, notebooks, local helper services, or task-created helper processes, run an ownership-based external-tool resource closeout check before declaring closeout ready. Report task-owned or agent-managed resources that were closed or cleaned, observable resources released when the runtime exposes counts / memory / temp size, retained shared / user-owned / other-agent-owned / system-level / unknown resources with redacted evidence, and any runtime visibility limits. Do not terminate, delete, disable, or reconfigure shared or ambiguous resources without explicit user confirmation under `dev/rules/integrations.md` and `dev/rules/safety.md`.
130
- 7. Complete the `State Reconciliation Check`: it must state when reconciliation happened, which state sections were rewritten or confirmed current, whether stale snapshots remain, whether the `Persistence routing checked` field is complete, whether completed / pending / risk / opening-message lifecycle conflicts were resolved, whether the recommended next step is explicit and reasoned, and whether the opening message matches current state. In the same step, run the handoff lifecycle consistency check before declaring handoff ready: 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.
131
- 8. Run the handoff sufficiency check: the next AI should be able to continue from `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history.
132
- 9. If either check fails, fix `dev/SESSION_HANDOFF.md` first; do not push current-state responsibility into `dev/SESSION_LOG.md`.
133
- 10. Regenerate `START_NEXT_SESSION_PROMPT.txt` from the fenced opening message in `dev/SESSION_HANDOFF.md`, then read it back or run the project's prompt mirror check before declaring closeout ready. `dev/SESSION_HANDOFF.md` is authoritative; `START_NEXT_SESSION_PROMPT.txt` is the stateful startup prompt that the next local agent must read. During an active session, do not regenerate it just to silence `doctor`; normal `doctor` may warn about drift, but closeout must make the copy match before handoff is declared ready.
134
- 11. Show a short closeout card, then provide the next-session startup entry in a fenced `text` code block. Primary entry, when the next local AI agent is already opened at this project root: `Start Agent Handoff` / `開工`. Fallback entry, when the next AI agent is not yet pointed at the project root: `Work in <project root>. Read AGENTS.md first, then Start Agent Handoff. Before changing anything, tell me the current state and your recommended next step.` Do not compose a separate stateful final-response prompt; the final response points to the persisted prompt file, not a third source of truth.
135
- 12. Run the closeout maintenance trigger check. This is a short required check, not a full maintenance pass every time. Record the result in the new `dev/SESSION_LOG.md` entry under `Log maintenance`.
136
-
137
- Hard triggers:
138
-
139
- (a) Advance the SESSION_LOG N-rule (R-010 SESSION_LOG handoff-role discipline) when `dev/SESSION_LOG.md` reaches N ≥ 11 entries, or when the main log exceeds 1500 lines. If triggered, move N ≥ 11 entries into `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` with raw content preserved, maintain `dev/SESSION_LOG_archive/INDEX.md`, collapse absorbed N=4–10 entries to short-index lines, and port any unique narrative into the relevant durable source before collapsing it. If a research trail affected a long-term decision, public claim, strategy, governance rule, or material selection, port its evidence chain into `dev/PROJECT_DECISIONS.md` using that file's research-derived decision format before collapsing the log. Handoff capability rests on `dev/SESSION_HANDOFF.md`; `dev/SESSION_LOG.md` is trace-back / audit trail and does not carry handoff responsibility.
140
-
141
- (b) Maintain `dev/PROJECT_DECISIONS.md` per R-028 project narrative discipline when `dev/SESSION_HANDOFF.md` contains a decisions-like H2 section, for example `## Confirmed Decisions`, `## Decisions`, or a localized equivalent, with a numbered list of at least 30 entries. If triggered, split the oldest entries, retaining the most recent 8-22 in the handoff hot tier, into `dev/PROJECT_DECISIONS.md` `## Decisions Archive`, newest first.
142
-
143
- (c) Append to `dev/PROJECT_DECISIONS.md` immediately, or at closeout, when the current session includes substantive task evolution, a multi-option architectural trade-off with recorded rationale, a cross-session accumulated pattern, or a user retrospective question. Use `## Evolution Timeline`, `## Architecture Choices`, or `## Insights & Learnings` as appropriate. If the decision is research-derived, use that file's evidence-chain format so the source, summary, inference, decision impact, and uncertainty survive future compression.
144
-
145
- (d) Run a full long-term maintenance pass every 10 closeouts as a backstop, even if no trigger seems obvious. Count closeouts from the main `dev/SESSION_LOG.md` entries plus archive index entry counts when an archive exists; if the count cannot be determined confidently, treat the current N=10 boundary as the backstop trigger.
146
-
147
- If none of the hard triggers, semantic triggers, or 10-closeout backstop applies, write a one-line no-op reason and do not perform full long-term maintenance. This keeps routine closeout fast while still preventing silent drift.
148
-
149
- Installed handoff templates use English headings by default for cross-tool stability, but project teams may translate `dev/SESSION_HANDOFF.md` section headings and visible field labels into the project's working language. Keep the `ack:section:*` and `ack:field:*` semantic markers intact; `doctor` validates those markers so localized handoff notes remain supported.
150
-
151
- Use this closeout card:
152
-
153
- Use the same display version rule as startup: take the version from `dev/PROJECT_INDEX.md` `## Stack` row `Agent Handoff Kit template version`, print it as `vX.Y.Z`, and fall back to `version unverified` only when it cannot be verified. Never print the literal placeholder `v<version>`.
154
-
155
- ```text
156
- /\_/\ Agent Handoff Kit v<version>
157
- ( -.- ) handoff saved
158
- > ^ <
159
-
160
- ✅ Done: <completed summary>
161
- 🔎 QC: <validation summary>
162
- 📌 Handoff: opening message ready
163
- ⚠️ Boundary: <important boundary or none>
164
- ```
165
-
166
- In `dev/SESSION_HANDOFF.md`, immediately before the fenced `Next Session Opening Message` content, write:
167
-
168
- ```text
169
- 📋 Next session: agent-managed startup content below
170
- ```
171
-
172
- Record only work actually performed in the current session. Do not copy old completed work forward as new work.
173
- `dev/SESSION_HANDOFF.md` carries continuity. `dev/SESSION_LOG.md` carries recent evidence. Archive old detail only when needed; do not create an archive directory by default.
174
- Do not declare handoff ready if `dev/SESSION_HANDOFF.md` still contains stale state, unreconciled placeholders in current-state sections, or an opening message that no longer matches the reconciled state.
175
-
176
- ## 5. Pack Loading
177
-
178
- Use `dev/RULE_PACKS.md` to decide which pack to read.
179
-
180
- A pack may add task-specific requirements. A pack cannot weaken core safety. If two packs conflict, choose the safer and more verifiable path, then record the conflict in closeout.
181
-
182
- When a task references external tools (Notion / Google Drive / Slack / Linear / GitHub / Dropbox / HubSpot / Atlassian / etc.) or `dev/PROJECT_INDEX.md` `## Installed Integrations` is non-empty, load `dev/rules/integrations.md` together with the relevant domain pack. The integrations pack covers Connector-first defaults, credential separation, multi-layer source-of-truth architecture, and cross-session resilience for declared integrations.
183
-
184
- After the task, apply the Persistence Gate in Section 2.1. Do not assume the next session remembers pack context unless it is recorded, and do not treat handoff/log persistence as sufficient for reusable procedure knowledge.
185
-
186
- If a pack, skill, subagent plan, demo workspace, or external workflow produces its own closeout, treat it as subordinate evidence. The active project root still needs the Section 2.1 persistence-gate decision before the task is complete.
187
-
188
- ## Core Complexity Rule
189
-
190
- New default-core rules are allowed only when they apply to most sessions, protect safety or continuity, cannot live in a pack or registry, and keep the core within budget.
43
+ Use the full product name, plain user language, and one recommended next action. Never print the literal placeholder `v<version>`.
44
+
45
+ ## 2. Proportionate Work Loop
46
+
47
+ Apply PLAN → READ → CHANGE → QC internally and in proportion to task state and risk. Do not make the user watch governance ceremony that does not help the task.
48
+
49
+ - Simple answers, pure conversation or creation with no durable state, and low-risk tasks with an obvious target may proceed directly with proportionate reading and checking.
50
+ - Non-trivial work reads relevant sources before changing them.
51
+ - High-risk work states scope, impact, acceptance, and required confirmation before writes.
52
+ - External skill flows, subagents, task plans, demo workspaces, and another tool's finish step do not replace the active root's persistence decision.
53
+ - Materially changed Markdown governance artifacts must be indexed, synchronized, consolidated into their authoritative home, or explicitly classified as temporary / one-time evidence. Other durable formats follow the same human governance rule, but the bundled doctor does not claim to scan them.
54
+
55
+ ## 2.1 Persistence Gate
56
+
57
+ Choose exactly one tier after a task:
58
+
59
+ 1. No persistence: no durable fact was produced. One-off answers, transient output, active unapproved drafts, and routine rerunnable checks normally use this tier.
60
+ 2. Lightweight checkpoint: a durable fact affects future action while the session continues or may be interrupted. Write only its smallest correct home; do not regenerate the startup mirror or perform full closeout.
61
+ 3. Full closeout: explicit end-of-session / handoff intent, a tool or day boundary, or completed external / release / governance work that the next agent must continue. Load `dev/rules/closeout.md`.
62
+
63
+ Route current objective, next action, active risk, blocker, and startup-needed facts to `dev/SESSION_HANDOFF.md`; chronological evidence to `dev/SESSION_LOG.md`; maps to `dev/PROJECT_INDEX.md`; sync obligations to `dev/DOC_SYNC_REGISTRY.md`; long-term rationale to `dev/PROJECT_DECISIONS.md`; and reusable procedures to the relevant pack, registered reference, or QA check. Do not store the same task contract or reusable rule in several homes.
64
+
65
+ External effects are never implied permission for commit, push, publish, release, deployment, cleanup, or another workspace write. Record verified external impact through the relevant integrations, release, safety, and closeout contracts without exposing private content or secrets.
66
+
67
+ ## 2.2 Upgrade Completion
68
+
69
+ The CLI owns upgrade truth. An upgrade is complete only when:
70
+
71
+ 1. The root is not newer than the CLI and every target passes read-only classification.
72
+ 2. Conflict produces zero governance-target and version writes.
73
+ 3. Staged outputs pass the offline migration acceptance gate: root boundary, structure, cross-file invariants, preservation hashes, and version transition.
74
+ 4. The recoverable transaction commits without an unresolved journal; only a failure caused by this transaction triggers rollback.
75
+ 5. Whole-project `doctor` reports project health separately. Pre-existing or unrelated health failures do not convert a correct migration into a destructive rollback; new migration-caused blockers do.
76
+ 6. The migration report records attempted version, committed version, transaction state, actions, redacted reasons, and backup locations without credential values.
77
+
78
+ Do not use "upgrade completed" to mean "the entire project is healthy". Report `migration committed` and `project health` separately. Conflict, incomplete recovery, failed migration acceptance, and future-version roots are not completed upgrades.
79
+
80
+ ## 3. Safety Baseline
81
+
82
+ Do not delete, reset, overwrite user-owned content, bulk-move, publish, change permissions, or perform another irreversible or external action without the required explicit authorization.
83
+
84
+ Named prohibited destructive commands in `dev/rules/safety.md` remain prohibited even when requested. Never use a weaker pack or local instruction to bypass core safety.
85
+
86
+ Verify the selected root and real target boundaries before writes. Do not follow a link, junction, mount, or computed path outside the confirmed root. Do not expose credential values in output, reports, backups, tests, or logs. Permission or lock failure is a stop condition, not permission to elevate or switch to a riskier command.
87
+
88
+ Do not modify unrelated files or erase unexpected user changes. Do not claim completion without read-back evidence and proportionate checks.
89
+
90
+ ## 4. Closeout Trigger
91
+
92
+ Clear end-of-session or handoff intent such as "收工", "Wrap up Agent Handoff", "closeout", "wrap up", or "handoff" triggers full closeout, not a chat-only summary. Load `dev/rules/closeout.md` and follow its complete contract. `收工,記得 <handoff requirement>` and equivalent closeout-plus-instruction phrases are clear closeout intent. Ask one concise confirmation only when the phrase genuinely refers to an unrelated real-world closing or shift.
93
+
94
+ The always-enforced closeout invariants are:
95
+
96
+ 1. Current state lives in `dev/SESSION_HANDOFF.md`; trace evidence lives in `dev/SESSION_LOG.md`.
97
+ 2. Completed, pending, risk, validation, and opening-message lifecycle states agree.
98
+ 3. `START_NEXT_SESSION_PROMPT.txt` is regenerated from the sole authoritative handoff block and no third full copy is retained.
99
+ 4. Closeout is not complete until required files are written, read back, and the available closeout checks pass.
100
+ 5. Git commit, push, release, publish, deployment, deletion, and permission changes remain separately authorized actions.
101
+
102
+ ## 5. Pack Loading
103
+
104
+ Use `dev/RULE_PACKS.md` to load the minimum task-specific set. Packs may add stricter requirements but cannot weaken core safety or continuity.
105
+
106
+ Load `dev/rules/integrations.md` when the current task actually uses an external tool, not merely because a registry or placeholder table exists. Load `dev/rules/closeout.md` only for full closeout. If two packs conflict, use the safer and more verifiable path and record the unresolved conflict at closeout.
107
+
108
+ After the task, apply the Persistence Gate. Do not assume the next session remembers pack context, and do not use handoff or log as the only home for reusable procedures.
109
+
110
+ ## Core Complexity Rule
111
+
112
+ Default-core rules must apply to most sessions, protect safety or continuity, and be shorter than the routed detail they replace. New scenario detail belongs in an existing pack or registered reference; a new pack is justified only when it creates a smaller, independently loadable responsibility with one normative owner.
@@ -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.39 | 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
 
@@ -2,23 +2,24 @@
2
2
 
3
3
  Read only the packs needed for the current task.
4
4
 
5
- | Task signal | Pack | Purpose |
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 |
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 |
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
13
  | 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 |
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 |
15
16
  | Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
16
17
  | 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 |
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 |
20
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
@@ -25,7 +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
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
@@ -124,12 +126,12 @@ At full closeout, complete this check after updating the state sections above.
124
126
 
125
127
  If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready.
126
128
 
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.
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.
@@ -144,20 +146,9 @@ This fenced block is the authoritative agent-managed startup content. At closeou
144
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.
149
+ Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Trust the handoff over this generated mirror.
159
150
 
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.
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.
161
152
 
162
- Before changing anything, tell me the current state and your recommended next step.
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.
163
154
  ```
@@ -10,7 +10,7 @@ This log carries recent evidence, not current state. Put the current objective,
10
10
 
11
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
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.
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
14
 
15
15
  <!-- ack:section:session-log-entry-template -->
16
16
 
@@ -30,28 +30,6 @@ Before closeout, record whether older log detail was kept, summarized, or archiv
30
30
  - **Pending:** <next work>
31
31
  - **Risks:** <known risks or none>
32
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
- ```
33
+ - **Opening-message mirror:** <regenerated and verified / blocked; full text omitted by design>
56
34
  <!-- ack:log-entry:end -->
57
35
  ````