@adamchanadam/agent-handoff-kit 0.4.2 → 0.4.4

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.
Files changed (46) hide show
  1. package/LICENSE +21 -21
  2. package/README.en.md +1 -1
  3. package/README.md +1 -1
  4. package/bin/agent-handoff-kit.mjs +7146 -7047
  5. package/bin/commands.mjs +134 -134
  6. package/bin/handoff-read.mjs +88 -88
  7. package/bin/installed-file-contract.mjs +154 -90
  8. package/bin/migration-baselines/official-origin-catalog.json +534 -1
  9. package/bin/official-origin-catalog.mjs +294 -294
  10. package/bin/progress/ICON-LICENSE.txt +21 -21
  11. package/bin/progress/assets.mjs +6 -6
  12. package/bin/progress/dashboard.mjs +134 -134
  13. package/bin/progress/icons.svg +36 -36
  14. package/bin/progress/index.html +31 -31
  15. package/bin/progress/launch.mjs +40 -40
  16. package/bin/progress/open.mjs +43 -43
  17. package/bin/progress/project-version.mjs +121 -121
  18. package/bin/progress/projection.mjs +144 -144
  19. package/bin/progress/renderer.js +152 -152
  20. package/bin/progress/server.mjs +78 -78
  21. package/bin/progress/styles.css +31 -31
  22. package/bin/prompt-mirror-core.mjs +84 -84
  23. package/bin/upgrade-inventory.mjs +243 -243
  24. package/bin/user-rules-router.mjs +4 -4
  25. package/docs/commands.md +2 -2
  26. package/docs/progress.md +73 -73
  27. package/package.json +22 -22
  28. package/packs/agent-governance.md +120 -120
  29. package/packs/closeout.md +91 -91
  30. package/packs/coding.md +28 -28
  31. package/packs/integrations.md +19 -19
  32. package/packs/knowledge.md +3 -3
  33. package/packs/onboarding.md +45 -45
  34. package/packs/research.md +30 -30
  35. package/packs/safety.md +2 -2
  36. package/runtime-core/AGENTS.core.md +161 -161
  37. package/runtime-core/CLAUDE.md +13 -13
  38. package/runtime-core/DOC_SYNC_REGISTRY.md +24 -24
  39. package/runtime-core/GEMINI.md +17 -17
  40. package/runtime-core/PROJECT_DECISIONS.md +43 -43
  41. package/runtime-core/PROJECT_INDEX.md +16 -16
  42. package/runtime-core/RULE_PACKS.md +1 -1
  43. package/runtime-core/SESSION_HANDOFF.md +180 -180
  44. package/runtime-core/SESSION_LOG.md +37 -37
  45. package/runtime-core/START_NEXT_SESSION_PROMPT.txt +1 -1
  46. package/runtime-core/USER_RULES_ENTRY.md +5 -5
package/packs/closeout.md CHANGED
@@ -1,91 +1,91 @@
1
- # Closeout Pack
2
-
3
- ## Scope
4
-
5
- This pack is the single detailed contract for full Agent Handoff Kit closeout. Load it only for clear end-of-session or handoff intent. It does not authorize Git, release, publish, deployment, deletion, permission, or cleanup actions.
6
-
7
- ## Required Reads
8
-
9
- Read the current `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, and `dev/DOC_SYNC_REGISTRY.md`. Read `dev/PROJECT_DECISIONS.md`, integration rules, or another pack only when its closeout trigger or the session's actual work requires it.
10
-
11
- ## Write Contract
12
-
13
- Use Kit markers as machine boundaries: `ack:section:*`, `ack:field:*`, `ack:log-entry:start/end`, and managed-core BEGIN/END. Human headings may be localized; markers may not be removed or translated.
14
-
15
- - Current state, objective, recommended next action, active risk, blocker, required reading, workspace identity, and sync status belong in `dev/SESSION_HANDOFF.md`.
16
- - When saving meaningful work changes, maintain the handoff's concise `Work Items` table using its declared fields, and keep project-wide name/goal in `PROJECT_INDEX` `Project`. Add the table/section to older projects only at an authorized state save when useful. Reconcile changed statuses against the evidence; do not duplicate full reports, rewrite old history, or create per-terminal-step records for the dashboard. Read-only dashboard viewing never triggers these writes.
17
- - Chronological work and evidence disposition belong in `dev/SESSION_LOG.md`.
18
- - File / command / source / capability maps belong in `dev/PROJECT_INDEX.md`.
19
- - Recurring sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`.
20
- - Long-term evolution, architectural rationale, and accumulated learning belong in `dev/PROJECT_DECISIONS.md` when triggered.
21
- - Reusable procedures belong in the relevant pack, registered reference, or QA check.
22
- - `START_NEXT_SESSION_PROMPT.txt` is generated only from the handoff opening-message block.
23
-
24
- Do not copy the full opening message into `dev/SESSION_LOG.md` or any third current governance file. The log records whether the mirror was verified no-op or regenerated and verified, plus an evidence reference when useful.
25
-
26
- ## Full Closeout
27
-
28
- Full closeout is differential and write-minimal. Update only fields whose current truth changed. For unchanged state, preserve bytes where practical and record checked/no-op only when it helps the next agent. Reuse a completed task check only when its recorded root, task input, tool identity, commit / artifact identity, and required file hashes still match the current state. Do not rerun task QA that is already bound to unchanged identity. Do rerun checks affected by closeout writes, gates that are incomplete or indeterminate, closeout-specific checks, and the final `closeout-status` read-back. If a closeout attempt is interrupted, stopped, aborted, times out, or hits a spawn / transport error, resume at the first incomplete or indeterminate gate; do not restart from the beginning unless the root, input, tool identity, commit, artifact, or relevant hash changed.
29
-
30
- Handoff cold zones are historical / evidence sections, old validation records, completed-work narratives, and unchanged durable anchors. Stable anchors and decision-changing current facts stay in the packet. Do not rewrite, reword, reorder, or refresh cold zones for ceremony or style. When older detailed narrative no longer changes the next action, preserve it byte-for-byte in existing trace/archive storage and verify that copy before removing it from the current packet. Do not rewrite or archive unchanged material at every closeout, impose an arbitrary size cap, or weaken the required full reception of the current packet.
31
-
32
- 1. Reconcile `dev/SESSION_HANDOFF.md`; never append a new current-state snapshot beneath an old one. Verify durable anchors, then update only changed closeout-reconciled fields or sections; leave already-current sections unchanged instead of rewriting them for ceremony.
33
- 2. Reconcile lifecycle state across `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. Completed or verified work cannot remain unresolved unless explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with its missing evidence or trigger.
34
- The bundled doctor is a mechanical floor for required lifecycle markers and readable sections only. `agent-handoff-kit closeout-status` checks explicit lifecycle declarations and same-scope textual contradictions; it does not prove natural-language semantic consistency. When it blocks, inspect its first `Resolved [...]` / `Carry-forward [...]` pair against the actual evidence: completion of one action does not complete another acceptance scope, and a preserved limitation is not a completion claim. Repair a real contradiction in its owning handoff section. If truthful, distinct scopes are misclassified, preserve the facts, report the checker defect and stop wording retries; do not add a reclassification prefix, invent a trigger, erase a limitation or broaden governance just to pass. A blocked result remains blocked until verified repair. Read all five sections as a whole before marking the lifecycle field resolved. For governance, release, or another project-defined high-risk completion, use the project's independent semantic review gate in addition to `closeout-status`.
35
- 3. Make `Next Priorities` name one recommended next action and a short reason unless blocked or a real user decision is required.
36
- 4. Complete the persistence-routing, handoff-sufficiency, `Closeout outcome`, and `Project-required persistence` fields. Apply the packet-only reconstruction check below before answering handoff sufficiency. The next agent must be able to continue from `AGENTS.md`, the handoff, the project index when needed, and routed packs without searching old log history. `complete` is allowed only when all required writes/read-backs and any project-required persistence succeeded; use `not_required` only when that persistence is genuinely not required. If a required commit, push, release record, or equivalent persistence is blocked or not authorized, set both fields to `blocked` with the exact boundary.
37
- 5. Add one concise log entry for work actually performed. Record evidence disposition and the prompt-mirror verification result; omit the full opening message by design.
38
- 6. Update the project index and sync registry only when their owned maps or obligations changed. Record each applicable sync target as `confirmed`, `unverified`, `pending`, `blocked`, or `not_applicable`.
39
- 7. Run `agent-handoff-kit workspace-health --root <project root>` or equivalent read-only Git probes, then record only the last-verified root, Git root, branch, commit, worktrees / parallel workspaces, uncommitted changes, and unresolved drift. Do not clean or change them without separate authorization. Do not treat `dev/PROJECT_INDEX.md` or old handoff prose as the live worktree truth.
40
- 8. If the session used external tools or helper processes, apply the integrations and safety ownership rules. Close only task-owned resources. Retain shared, user-owned, other-agent-owned, system, or ambiguous resources unless separately authorized; state visibility limits.
41
- 9. Run the short maintenance trigger check below and record its result in the log.
42
- 10. Mark first-use guidance `consumed` after the first successfully completed task or first full closeout. Upgrade must never reset `consumed` or `not_applicable` to `eligible`.
43
- 11. Verify `START_NEXT_SESSION_PROMPT.txt` against the sole fenced handoff opening-message block first. Regenerate it only when normalized content differs, then run the project's fixed prompt-mirror checker or perform an equivalent anchored read-back that verifies marker, heading, fence, full-copy uniqueness, and normalized content equality.
44
- 12. Run available project-specific closeout checks. Do not run a separate bundled `doctor`: the `closeout-status` command below performs the one required fresh doctor read-back. Do not treat an external update-check failure as local closeout failure. Fix state or mirror failures before claiming handoff ready.
45
- 13. Run `agent-handoff-kit closeout-status --root <project root>` after the handoff and prompt read-back. It performs the one required fresh doctor read-back plus a read-only workspace-health comparison against the handoff snapshot, and its output is the only final card source. A nonzero result means the closeout is blocked; do not replace it with a success summary.
46
-
47
- ## Packet-Only Reconstruction Check
48
-
49
- Before closing out, reconstruct the next task using only the handoff, without chat memory, old logs or opening linked sources. Identify the parent outcome and consumer, the current step's relation to it, the exact resume point, remaining step/parent acceptance, and required sources with revision/freshness, reading scope/depth and unread gaps. Also recover decision-changing user corrections, reasons for accepted/rejected approaches, reusable artifacts with their evidence limits, every remaining consequential obligation and its downstream use, and permission/stop boundaries. Cite the owning handoff sections in `Reconstruction evidence`; do not create a second task summary. Then compare that reconstruction against the user's actual request and the relevant sources read this session. Missing, contradictory or assumed critical facts must be repaired in their existing handoff sections or explicitly recorded as blockers with the next clarification/read needed. Do not answer yes on labels or a successful CLI card alone: the CLI checks the recorded answer and evidence presence, not the truth of this reconstruction.
50
-
51
- Check whether a reader could repeat a rejected attempt, redo accepted work, omit an obligation, act on obsolete instructions, or choose a plausible but wrong next action while still agreeing with the packet's headline. If so, preserve the missing decision-changing fact in its existing owning section, not merely in a linked historical log. Keep the packet sufficient and proportionate; do not paste the whole chat or silently discard important facts to fit an output limit. Transport truncation is handled by the core reception checkpoint, not by weakening the task.
52
-
53
- Closeout verifies this session's saved packet. It cannot certify that a future reader received or understood it. Do not describe `closeout-status: complete` as successful future-session reception; the next agent must pass the core Handoff reception and recovery checkpoint independently.
54
-
55
- Keep one `Answer:` line (`yes`, `no` or `unknown`, with optional explanation) and one `Reconstruction evidence:` line inside the marked sufficiency section. An affirmative answer requires concrete section references; keep `next-ai-can-continue` consistent. For an older handoff, add missing facts to its existing sections at this authorized closeout; upgrade must preserve user state and must not invent reconstruction evidence. Missing or negative answers, placeholder evidence and duplicate fields block `closeout-status` without changing project files.
56
-
57
- Use only the depth needed to resume safely. A standalone task needs no invented parent tree; state that it is the whole task. Finishing a child does not complete its parent or authorize another step. Keep the next consequential action bounded by its input, output and acceptance; do not enumerate every future microstep. Keep decision-relevant terms and identifiers faithful; when a translation could change their meaning, retain the original term alongside it. Reading coverage is previous-session evidence, never permission for the next agent to skip required fresh source reads. Honest blocked-work handoff can be sufficient when the missing fact, impact and safe next action are explicit.
58
-
59
- ## Maintenance Trigger Check
60
-
61
- Every full closeout runs this short check; full maintenance runs only when triggered.
62
-
63
- - SESSION_LOG: trigger when the main log reaches at least 11 entries, exceeds 1500 lines, or the 10-closeout backstop is due. Keep recent safety-buffer entries; collapse only content already absorbed by an authoritative home. Archive older raw entries to `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` and maintain `INDEX.md`. Port unique narrative before collapsing it.
64
- - PROJECT_DECISIONS: trigger when a decisions-like handoff section has at least 30 entries; retain the newest 8–22 in the hot tier and move older decisions into the decisions archive. Also write substantive task evolution, a multi-option architectural choice with rationale, or a cross-session learning when observed.
65
- - Backstop: every 10 closeouts, run the full long-term maintenance pass even when no semantic trigger is obvious. If the count cannot be determined confidently at the boundary, treat the backstop as due.
66
-
67
- If no trigger applies, record one no-op reason. Handoff carries continuity; log and project decisions carry trace and long-term narrative.
68
-
69
- ## Opening Message And Card
70
-
71
- The handoff opening-message block is authoritative. It must name the absolute root, route the agent through `AGENTS.md` and the handoff, state the current objective and boundary, and avoid instructing the next agent to redo completed work. It must not require SESSION_LOG as an ordinary startup read.
72
-
73
- Use `agent-handoff-kit closeout-status --root <project root>` after the required read-backs. When it returns a card, copy the full card verbatim in a fenced `text` block before any explanation for both `status: complete` and `status: blocked`; never reduce it to selected status or blocker lines, print the literal placeholder `v<version>`, hand-compose a substitute success/blocked card, or use `handoff saved` unless the command reports `status: complete`. Only when no CLI card exists because the CLI could not be launched or returned no card may the final response show a fenced `closeout unavailable` card with no version and no `saved`/`complete` claim, followed by the actual missing condition. That presentation does not complete closeout and never replaces a returned complete or blocked CLI card.
74
-
75
- ```text
76
- /\_/\ Agent Handoff Kit v<version>
77
- ( -.- ) handoff saved
78
- > ^ <
79
-
80
- status: complete
81
- ✅ Done: <completed summary>
82
- 🔎 QC: <validation summary>
83
- 📌 Handoff: opening message ready
84
- ⚠️ Boundary: <important boundary or none>
85
- ```
86
-
87
- For `status: blocked`, the command instead says `handoff blocked`; retain that status, blocker reason, and human explanation: `這不是失敗;只是還有事未保存、未提交、未驗證或需要處理。先照 Blocker 行處理,不要把本輪當作已完成交接。` Then give the short local-root entry `Start Agent Handoff` / `開工` and the path-bearing fallback for an agent not yet pointed at the root. The narrow `closeout unavailable` presentation above is allowed only when there is no CLI card; do not use it to replace a returned blocked card or hand-compose a third stateful prompt.
88
-
89
- ## Stop Conditions
90
-
91
- Do not claim closeout complete when any required write or read-back failed, lifecycle state conflicts remain, the mirror is stale or duplicated, the root is uncertain, mandatory sync is unclassified, `closeout-status` is nonzero, or required Git persistence was explicitly part of the project's closeout contract but did not succeed. State the exact blocker and leave the project in an honest resumable state.
1
+ # Closeout Pack
2
+
3
+ ## Scope
4
+
5
+ This pack is the single detailed contract for full Agent Handoff Kit closeout. Load it only for clear end-of-session or handoff intent. It does not authorize Git, release, publish, deployment, deletion, permission, or cleanup actions.
6
+
7
+ ## Required Reads
8
+
9
+ Receive the current `dev/SESSION_HANDOFF.md` in full; in the same session, reuse only evidence already fully received from the unchanged file, and supplement every unread, truncated, or changed range. Read the current-session-relevant `dev/SESSION_LOG.md` entry, carry-forward risks, and any actual maintenance need. Read the affected complete command, route, rule, source, workspace mapping, and any required supplement in `dev/PROJECT_INDEX.md`; do not replace that reading with keyword hits. Classify every applicable `dev/DOC_SYNC_REGISTRY.md` obligation. Read `dev/PROJECT_DECISIONS.md`, integration rules, or another pack only when its closeout trigger or the session's actual work requires it.
10
+
11
+ ## Write Contract
12
+
13
+ Use Kit markers as machine boundaries: `ack:section:*`, `ack:field:*`, `ack:log-entry:start/end`, and managed-core BEGIN/END. Human headings may be localized; markers may not be removed or translated.
14
+
15
+ - Current state, objective, recommended next action, active risk, blocker, required reading, workspace identity, and sync status belong in `dev/SESSION_HANDOFF.md`.
16
+ - When saving meaningful work changes, maintain the handoff's concise `Work Items` table using its declared fields, and keep project-wide name/goal in `PROJECT_INDEX` `Project`. Add the table/section to older projects only at an authorized state save when useful. Reconcile changed statuses against the evidence; do not duplicate full reports, rewrite old history, or create per-terminal-step records for the dashboard. Read-only dashboard viewing never triggers these writes.
17
+ - Chronological work and evidence disposition belong in `dev/SESSION_LOG.md`.
18
+ - File / command / source / capability maps belong in `dev/PROJECT_INDEX.md`.
19
+ - Recurring sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`.
20
+ - Long-term evolution, architectural rationale, and accumulated learning belong in `dev/PROJECT_DECISIONS.md` when triggered.
21
+ - Reusable procedures belong in the relevant pack, registered reference, or QA check.
22
+ - `START_NEXT_SESSION_PROMPT.txt` is generated only from the handoff opening-message block.
23
+
24
+ Do not copy the full opening message into `dev/SESSION_LOG.md` or any third current governance file. The log records whether the mirror was verified no-op or regenerated and verified, plus an evidence reference when useful.
25
+
26
+ ## Full Closeout
27
+
28
+ Full closeout is differential and write-minimal. Update only fields whose current truth changed. For unchanged state, preserve bytes where practical and record checked/no-op only when it helps the next agent. A same-session fully received unchanged source may be reused; incomplete, truncated, or changed sources require supplementary reading before relying on them. Reuse a completed task check only when its recorded root, task input, tool identity, commit / artifact identity, and required file hashes still match the current state. Do not rerun task QA that is already bound to unchanged identity. Do rerun checks affected by closeout writes, gates that are incomplete or indeterminate, closeout-specific checks, and the final `closeout-status` read-back. If a closeout attempt is interrupted, stopped, aborted, times out, or hits a spawn / transport error, resume at the first incomplete or indeterminate gate; do not restart from the beginning unless the root, input, tool identity, commit, artifact, or relevant hash changed.
29
+
30
+ Handoff cold zones are historical / evidence sections, old validation records, completed-work narratives, and unchanged durable anchors. Stable anchors and decision-changing current facts stay in the packet. Do not rewrite, reword, reorder, or refresh cold zones for ceremony or style. When older detailed narrative no longer changes the next action, preserve it byte-for-byte in existing trace/archive storage and verify that copy before removing it from the current packet. Do not rewrite or archive unchanged material at every closeout, impose an arbitrary size cap, or weaken the required full reception of the current packet.
31
+
32
+ 1. Reconcile `dev/SESSION_HANDOFF.md`; never append a new current-state snapshot beneath an old one. Verify durable anchors, then update only changed closeout-reconciled fields or sections; leave already-current sections unchanged instead of rewriting them for ceremony.
33
+ 2. Reconcile lifecycle state across `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. Completed or verified work cannot remain unresolved unless explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with its missing evidence or trigger.
34
+ The bundled doctor is a mechanical floor for required lifecycle markers and readable sections only. `agent-handoff-kit closeout-status` checks explicit lifecycle declarations and same-scope textual contradictions; it does not prove natural-language semantic consistency. When it blocks, inspect its first `Resolved [...]` / `Carry-forward [...]` pair against the actual evidence: completion of one action does not complete another acceptance scope, and a preserved limitation is not a completion claim. Repair a real contradiction in its owning handoff section. If truthful, distinct scopes are misclassified, preserve the facts, report the checker defect and stop wording retries; do not add a reclassification prefix, invent a trigger, erase a limitation or broaden governance just to pass. A blocked result remains blocked until verified repair. Read all five sections as a whole before marking the lifecycle field resolved. For governance, release, or another project-defined high-risk completion, use the project's independent semantic review gate in addition to `closeout-status`.
35
+ 3. Make `Next Priorities` name one recommended next action and a short reason unless blocked or a real user decision is required.
36
+ 4. Complete the persistence-routing, handoff-sufficiency, `Closeout outcome`, and `Project-required persistence` fields. Apply the packet-only reconstruction check below before answering handoff sufficiency. The next agent must be able to continue from `AGENTS.md`, the handoff, the project index when needed, and routed packs without searching old log history. `complete` is allowed only when all required writes/read-backs and any project-required persistence succeeded; use `not_required` only when that persistence is genuinely not required. If a required commit, push, release record, or equivalent persistence is blocked or not authorized, set both fields to `blocked` with the exact boundary.
37
+ 5. Add one concise log entry only for current work, risk, actual maintenance, or another durable fact that a later agent needs. Record evidence disposition and the prompt-mirror verification result when an entry is needed; omit the full opening message by design. A no-op closeout must not create a false work record.
38
+ 6. Update the project index only when affected complete mappings, rules, or supplements changed. Classify every applicable sync-registry target as `confirmed`, `unverified`, `pending`, `blocked`, or `not_applicable`.
39
+ 7. Run `agent-handoff-kit workspace-health --root <project root>` or equivalent read-only Git probes, then record only the last-verified root, Git root, branch, commit, worktrees / parallel workspaces, uncommitted changes, and unresolved drift. Do not clean or change them without separate authorization. Do not treat `dev/PROJECT_INDEX.md` or old handoff prose as the live worktree truth.
40
+ 8. If the session used external tools or helper processes, apply the integrations and safety ownership rules. Close only task-owned resources. Retain shared, user-owned, other-agent-owned, system, or ambiguous resources unless separately authorized; state visibility limits.
41
+ 9. Run the short maintenance assessment below. Record only actual maintenance work or a current risk; do not create a log entry solely to report a size advisory.
42
+ 10. Mark first-use guidance `consumed` after the first successfully completed task or first full closeout. Upgrade must never reset `consumed` or `not_applicable` to `eligible`.
43
+ 11. Verify `START_NEXT_SESSION_PROMPT.txt` against the sole fenced handoff opening-message block first. Regenerate it only when normalized content differs, then run the project's fixed prompt-mirror checker or perform an equivalent anchored read-back that verifies marker, heading, fence, full-copy uniqueness, and normalized content equality.
44
+ 12. Run available project-specific closeout checks. Do not run a separate bundled `doctor`: the `closeout-status` command below performs the one required fresh doctor read-back. Do not treat an external update-check failure as local closeout failure. Fix state or mirror failures before claiming handoff ready.
45
+ 13. Run `agent-handoff-kit closeout-status --root <project root>` after the handoff and prompt read-back. It performs the one required fresh doctor read-back plus a read-only workspace-health comparison against the handoff snapshot, and its output is the only final card source. A nonzero result means the closeout is blocked; do not replace it with a success summary.
46
+
47
+ ## Packet-Only Reconstruction Check
48
+
49
+ Before closing out, reconstruct the next task using only the handoff, without chat memory, old logs or opening linked sources. Identify the parent outcome and consumer, the current step's relation to it, the exact resume point, remaining step/parent acceptance, and required sources with revision/freshness, reading scope/depth and unread gaps. Also recover decision-changing user corrections, reasons for accepted/rejected approaches, reusable artifacts with their evidence limits, every remaining consequential obligation and its downstream use, and permission/stop boundaries. Cite the owning handoff sections in `Reconstruction evidence`; do not create a second task summary. Then compare that reconstruction against the user's actual request and the relevant sources read this session. Missing, contradictory or assumed critical facts must be repaired in their existing handoff sections or explicitly recorded as blockers with the next clarification/read needed. Do not answer yes on labels or a successful CLI card alone: the CLI checks the recorded answer and evidence presence, not the truth of this reconstruction.
50
+
51
+ Check whether a reader could repeat a rejected attempt, redo accepted work, omit an obligation, act on obsolete instructions, or choose a plausible but wrong next action while still agreeing with the packet's headline. If so, preserve the missing decision-changing fact in its existing owning section, not merely in a linked historical log. Keep the packet sufficient and proportionate; do not paste the whole chat or silently discard important facts to fit an output limit. Transport truncation is handled by the core reception checkpoint, not by weakening the task.
52
+
53
+ Closeout verifies this session's saved packet. It cannot certify that a future reader received or understood it. Do not describe `closeout-status: complete` as successful future-session reception; the next agent must pass the core Handoff reception and recovery checkpoint independently.
54
+
55
+ Keep one `Answer:` line (`yes`, `no` or `unknown`, with optional explanation) and one `Reconstruction evidence:` line inside the marked sufficiency section. An affirmative answer requires concrete section references; keep `next-ai-can-continue` consistent. For an older handoff, add missing facts to its existing sections at this authorized closeout; upgrade must preserve user state and must not invent reconstruction evidence. Missing or negative answers, placeholder evidence and duplicate fields block `closeout-status` without changing project files.
56
+
57
+ Use only the depth needed to resume safely. A standalone task needs no invented parent tree; state that it is the whole task. Finishing a child does not complete its parent or authorize another step. Keep the next consequential action bounded by its input, output and acceptance; do not enumerate every future microstep. Keep decision-relevant terms and identifiers faithful; when a translation could change their meaning, retain the original term alongside it. Reading coverage is previous-session evidence, never permission for the next agent to skip required fresh source reads. Honest blocked-work handoff can be sufficient when the missing fact, impact and safe next action are explicit.
58
+
59
+ ## Maintenance Trigger Check
60
+
61
+ Every full closeout runs this short assessment. It reports potential maintenance, but a pure `SESSION_LOG` size advisory is not a `closeout-status` blocker.
62
+
63
+ - SESSION_LOG: at 11 or more entries, more than 1500 lines, or a due 10-closeout backstop, report the shared maintenance advisory. Do full maintenance only when the current work establishes an actual preservation or continuation need, or a project-specific contract requires it. Keep recent safety-buffer entries; collapse only content already absorbed by an authoritative home. Before shortening an active source, verify the preserved copy. Archive older raw entries to `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` and maintain `INDEX.md` only when archive work is actually performed. Unknown count alone does not force a historical sweep.
64
+ - PROJECT_DECISIONS: at 30 or more decisions-like handoff entries, assess whether actual long-term maintenance is needed; retain the newest 8–22 in the hot tier and move older decisions into the decisions archive only when that work is required. Write substantive task evolution, a multi-option architectural choice with rationale, or a cross-session learning when observed.
65
+ - Backstop: a known due 10-closeout count is an advisory to assess long-term maintenance. Do not infer a historical sweep from an unknown count; project-specific stricter requirements still apply.
66
+
67
+ If no actual maintenance applies, leave historical trace content unchanged. Handoff carries continuity; log and project decisions carry trace and long-term narrative.
68
+
69
+ ## Opening Message And Card
70
+
71
+ The handoff opening-message block is authoritative. It must name the absolute root, route the agent through `AGENTS.md` and the handoff, state the current objective and boundary, and avoid instructing the next agent to redo completed work. It must not require SESSION_LOG as an ordinary startup read.
72
+
73
+ Use `agent-handoff-kit closeout-status --root <project root>` after the required read-backs. When it returns a card, copy the full card verbatim in a fenced `text` block before any explanation for both `status: complete` and `status: blocked`; never reduce it to selected status or blocker lines, print the literal placeholder `v<version>`, hand-compose a substitute success/blocked card, or use `handoff saved` unless the command reports `status: complete`. Only when no CLI card exists because the CLI could not be launched or returned no card may the final response show a fenced `closeout unavailable` card with no version and no `saved`/`complete` claim, followed by the actual missing condition. That presentation does not complete closeout and never replaces a returned complete or blocked CLI card.
74
+
75
+ ```text
76
+ /\_/\ Agent Handoff Kit v<version>
77
+ ( -.- ) handoff saved
78
+ > ^ <
79
+
80
+ status: complete
81
+ ✅ Done: <completed summary>
82
+ 🔎 QC: <validation summary>
83
+ 📌 Handoff: opening message ready
84
+ ⚠️ Boundary: <important boundary or none>
85
+ ```
86
+
87
+ For `status: blocked`, the command instead says `handoff blocked`; retain that status, blocker reason, and human explanation: `這不是失敗;只是還有事未保存、未提交、未驗證或需要處理。先照 Blocker 行處理,不要把本輪當作已完成交接。` Then give the short local-root entry `Start Agent Handoff` / `開工` and the path-bearing fallback for an agent not yet pointed at the root. The narrow `closeout unavailable` presentation above is allowed only when there is no CLI card; do not use it to replace a returned blocked card or hand-compose a third stateful prompt.
88
+
89
+ ## Stop Conditions
90
+
91
+ Do not claim closeout complete when any required write or read-back failed, lifecycle state conflicts remain, the mirror is stale or duplicated, the root is uncertain, mandatory sync is unclassified, `closeout-status` is nonzero, or required Git persistence was explicitly part of the project's closeout contract but did not succeed. State the exact blocker and leave the project in an honest resumable state.
package/packs/coding.md CHANGED
@@ -1,28 +1,28 @@
1
- # Coding Pack
2
-
3
- ## Scope
4
-
5
- Use for code changes, tests, builds, package managers, SDKs, CLIs, APIs, or developer tooling.
6
-
7
- ## Load When
8
-
9
- - User asks to write, edit, debug, refactor, test, build, package, or integrate code.
10
- - The task depends on framework, runtime, dependency, or API behavior.
11
-
12
- ## Rules
13
-
14
- 1. Read `dev/PROJECT_INDEX.md` for stack, commands, entry points, and directory roles before editing.
15
- 2. Inspect relevant source, tests, configs, and docs before changing code.
16
- 3. Prefer project-local patterns and helpers over new abstractions.
17
- 4. Do not guess current SDK, CLI, package, API, or deployment behavior when docs or project files can verify it.
18
- 5. Preserve unrelated user changes.
19
-
20
- ## Checks
21
-
22
- - Run the narrowest relevant test, build, lint, or typecheck available.
23
- - If a check cannot run, record why and what remains unverified.
24
- - Check `dev/DOC_SYNC_REGISTRY.md` if behavior, commands, public docs, or runbooks changed.
25
-
26
- ## Closeout
27
-
28
- Record files changed, commands run, results, remaining risks, and any project index or doc sync updates.
1
+ # Coding Pack
2
+
3
+ ## Scope
4
+
5
+ Use for code changes, tests, builds, package managers, SDKs, CLIs, APIs, or developer tooling.
6
+
7
+ ## Load When
8
+
9
+ - User asks to write, edit, debug, refactor, test, build, package, or integrate code.
10
+ - The task depends on framework, runtime, dependency, or API behavior.
11
+
12
+ ## Rules
13
+
14
+ 1. Read `dev/PROJECT_INDEX.md` for stack, commands, entry points, and directory roles before editing.
15
+ 2. Inspect relevant source, tests, configs, and docs before changing code.
16
+ 3. Prefer project-local patterns and helpers over new abstractions.
17
+ 4. Do not guess current SDK, CLI, package, API, or deployment behavior when docs or project files can verify it.
18
+ 5. Preserve unrelated user changes.
19
+
20
+ ## Checks
21
+
22
+ - Run the narrowest relevant test, build, lint, or typecheck available.
23
+ - If a check cannot run, record why and what remains unverified.
24
+ - Check `dev/DOC_SYNC_REGISTRY.md` if behavior, commands, public docs, or runbooks changed.
25
+
26
+ ## Closeout
27
+
28
+ Record files changed, commands run, results, remaining risks, and any project index or doc sync updates.
@@ -48,7 +48,7 @@ Agents must not use model memory, old session experience, copied examples, Conne
48
48
  | Local app plugin API | Official API documentation, official type definitions, official sample project, or local installed package types matching the project version. |
49
49
  | Project-local runbook | Accept as a task source only when it records the upstream source, version/date, scope, and known limits. |
50
50
 
51
- If the required source cannot be inspected, first classify the actual failure and check an already-authorized capable source/channel plus any normal platform approval. Mark only the affected use `blocked` or `unverified` when none can establish the needed contract; ask the user only for docs, schema, access, or a decision the AI cannot obtain, and use a manual packet only when it preserves the needed evidence. Do not continue by trial and error or bypass a real refusal. Connector-first means schema-first for the active runtime, not memory-first.
51
+ If the required source cannot be inspected, first classify the actual failure and check an already-authorized capable source/channel plus any normal platform approval. Mark only the affected use `blocked` or `unverified` when none can establish the needed contract; ask the user only for docs, schema, access, or a decision the AI cannot obtain, and use a manual packet only when it preserves the needed evidence. Do not continue by trial and error or bypass a real refusal. Connector-first means schema-first for the active runtime, not memory-first.
52
52
 
53
53
  #### Runtime-Controlled Tool Operation Variants
54
54
 
@@ -110,7 +110,7 @@ MCP servers may be official, community, custom, or project-local. Custom MCPs of
110
110
  Discipline:
111
111
 
112
112
  - Use only the active runtime's exposed tool name, description, and input schema.
113
- - Treat non-vetted or custom MCP write operations with extra caution. Destructive writes require dry-run and user confirmation under `dev/rules/safety.md`.
113
+ - Treat non-vetted or custom MCP write operations with extra caution. Destructive writes require dry-run and user confirmation under `dev/rules/safety.md`.
114
114
  - If the server fails because of process crash, config error, or unavailable runtime state, surface the failure, recommend checking MCP config and restarting the host tool, and do not blindly retry.
115
115
 
116
116
  #### 3.3 Plugins
@@ -164,12 +164,12 @@ Record declared integrations in `PROJECT_INDEX` `## Installed Integrations`, usi
164
164
 
165
165
  Immediately before the current task uses a declared integration, run the smallest relevant availability probe when the runtime exposes the needed tool schema. Do not probe unrelated integrations at startup. `TBD`, examples, blank rows, and placeholder-only tables are not declarations.
166
166
 
167
- - Probe success: update `Last Verified` only through the normal Persistence Gate, then proceed.
168
- - Probe fail: record the actual unavailable/failed result where the Persistence Gate applies, then use this pack's fallback flow only for the affected surface.
167
+ - Probe success: update `Last Verified` only through the normal Persistence Gate, then proceed.
168
+ - Probe fail: record the actual unavailable/failed result where the Persistence Gate applies, then use this pack's fallback flow only for the affected surface.
169
169
 
170
170
  #### Phase 4 — Task execution
171
171
 
172
- Apply the knowledge pack's Connector-first discipline: check declaration, use the verified direct tool when available, then follow this pack's classified fallback. A manual packet or user question is a last resort only when an authorized capable channel cannot supply the needed evidence.
172
+ Apply the knowledge pack's Connector-first discipline: check declaration, use the verified direct tool when available, then follow this pack's classified fallback. A manual packet or user question is a last resort only when an authorized capable channel cannot supply the needed evidence.
173
173
 
174
174
  #### Phase 5 — Mid-session drift handling
175
175
 
@@ -177,18 +177,18 @@ If an integration fails mid-task because of expired auth, rate limit, network ti
177
177
 
178
178
  - Surface the failure and impact.
179
179
  - Do not auto-fix credentials or auth.
180
- - Update `PROJECT_INDEX` `Last Verified` only after a real successful probe and the normal Persistence Gate; record an actual failed probe as failure/drift without relabeling it available.
180
+ - Update `PROJECT_INDEX` `Last Verified` only after a real successful probe and the normal Persistence Gate; record an actual failed probe as failure/drift without relabeling it available.
181
181
  - Record the drift in `SESSION_LOG` and unresolved risk in `SESSION_HANDOFF` when it affects future work.
182
182
 
183
183
  #### Phase 6 — Cross-tool consistency
184
184
 
185
- Integration declarations are project-level; they do not guarantee every AI runtime has the same tools installed. A new runtime must verify availability, warn on capability differences, and use this pack's fallback flow for the affected surface; do not require the user to install or switch tools before checking an already-authorized capable channel.
185
+ Integration declarations are project-level; they do not guarantee every AI runtime has the same tools installed. A new runtime must verify availability, warn on capability differences, and use this pack's fallback flow for the affected surface; do not require the user to install or switch tools before checking an already-authorized capable channel.
186
186
 
187
187
  ## Rules
188
188
 
189
189
  1. **Credential separation**: never ask for, log, or persist credential values. Redact credential-like values and warn about rotation when appropriate.
190
190
  2. **External Tool Usage Verification Gate**: verify current runtime schema, official docs, official types/samples, or registered tool operation references before invoking or retrying external tools.
191
- 3. **Declaration before use**: read `dev/PROJECT_INDEX.md` `## Installed Integrations` and `## Tool Operation References` before external-tool or runtime-controlled tool-operation work. If absent, inspect the active runtime for an authorized capable tool/schema before asking the user about access or source information.
191
+ 3. **Declaration before use**: read `dev/PROJECT_INDEX.md` `## Installed Integrations` and `## Tool Operation References` before external-tool or runtime-controlled tool-operation work. If absent, inspect the active runtime for an authorized capable tool/schema before asking the user about access or source information.
192
192
  4. **Connector-first default**: when a declared integration is functional, prefer the verified direct tool call. Manual paste is fallback, not default.
193
193
  5. **Write operations require read-back verification**: read back every external write before claiming success.
194
194
  6. **No auto-fix credential / auth issues**: surface auth failures to the user and point to the runtime settings or tool owner.
@@ -208,7 +208,7 @@ Integration declarations are project-level; they do not guarantee every AI runti
208
208
  - Before external-tool first use, write, destructive operation, raw API / SDK / CLI / URI / plugin API call, or retry after tool error, confirm the current usage source.
209
209
  - Surface and record mid-session integration drift.
210
210
  - After external-tool use, perform ownership-based resource closeout. For long-running, multi-tool, MCP, browser automation, repeated-error, or slowdown scenarios, report grouped residual processes or services when observable.
211
- - Before closeout, update `Last Verified` only for integrations with a real successful probe and when the normal Persistence Gate selects the write; retain actual failed-probe drift separately.
211
+ - Before closeout, update `Last Verified` only for integrations with a real successful probe and when the normal Persistence Gate selects the write; retain actual failed-probe drift separately.
212
212
  - Self-check credential leakage before writing `PROJECT_INDEX`, `SESSION_HANDOFF`, or `SESSION_LOG`.
213
213
  - Verify that `PROJECT_INDEX` External Sources `via` references match declared Installed Integrations entries.
214
214
  - For local HTML / app validation, verify that a rejected `file://` attempt is followed by a registered operation reference or short-lived localhost fallback before declaring `blocked`.
@@ -216,7 +216,7 @@ Integration declarations are project-level; they do not guarantee every AI runti
216
216
 
217
217
  ## Closeout
218
218
 
219
- 1. Update `PROJECT_INDEX` `## Installed Integrations` `Last Verified` cells only after real successful probes and when the normal Persistence Gate selects the write; record actual failed drift without claiming availability.
219
+ 1. Update `PROJECT_INDEX` `## Installed Integrations` `Last Verified` cells only after real successful probes and when the normal Persistence Gate selects the write; record actual failed drift without claiming availability.
220
220
  2. If drift happened, record the drift narrative, impact, and suggested next handling in `SESSION_LOG`.
221
221
  3. Add unresolved integration failures to `SESSION_HANDOFF` `## Risks / Blockers`.
222
222
  4. If unresolved drift affects startup, mention the next-session verification need in the opening message.
@@ -227,9 +227,9 @@ Integration declarations are project-level; they do not guarantee every AI runti
227
227
 
228
228
  | Anti-pattern | Why it is wrong | Correct approach |
229
229
  |---|---|---|
230
- | Assuming no Connector or MCP exists whenever the user mentions Notion, Google Drive, or another external source | Mature connector ecosystems make paste-only fallback an unreliable default. | Read `PROJECT_INDEX` Installed Integrations, then inspect the active runtime for an authorized capable tool/schema; ask only for missing user-held access or source information. |
230
+ | Assuming no Connector or MCP exists whenever the user mentions Notion, Google Drive, or another external source | Mature connector ecosystems make paste-only fallback an unreliable default. | Read `PROJECT_INDEX` Installed Integrations, then inspect the active runtime for an authorized capable tool/schema; ask only for missing user-held access or source information. |
231
231
  | Guessing tool names, endpoints, CLI flags, URI parameters, or plugin APIs from memory | Stale examples cause unknown tool, invalid args, 400 / 404, permission, or auth loops. | Verify active runtime schema, official docs, official types/samples, or versioned local runbooks. |
232
- | Treating browser validation as ordinary coding and guessing Chrome, Playwright, or DevTools commands | Browser and tool-control surfaces differ across runtimes, profiles, plugins, and installed packages. | Verify the active runtime schema, official docs, or a registered tool operation reference; use the classified fallback only for the affected surface when unavailable. |
232
+ | Treating browser validation as ordinary coding and guessing Chrome, Playwright, or DevTools commands | Browser and tool-control surfaces differ across runtimes, profiles, plugins, and installed packages. | Verify the active runtime schema, official docs, or a registered tool operation reference; use the classified fallback only for the affected surface when unavailable. |
233
233
  | Treating a Connector marketing page or old example as executable schema | Marketing pages do not prove the active runtime's current tool name or input schema. | Use active runtime tool list/schema as the invocation source. |
234
234
  | Retrying unknown tool / invalid args by changing names or parameters repeatedly | Trial-and-error hides the real schema or docs gap. | Stop same-pattern retries and return to the External Tool Usage Verification Gate. |
235
235
  | Writing credential values into `PROJECT_INDEX`, `SESSION_HANDOFF`, or `SESSION_LOG` | Project files and git history are persistent; leaked credentials remain exposed. | Record credential references only, never values. |
@@ -245,10 +245,10 @@ Integration declarations are project-level; they do not guarantee every AI runti
245
245
 
246
246
  ## Cross-reference
247
247
 
248
- - `dev/rules/knowledge.md` Rule 5: Connector-first source access discipline.
249
- - `dev/rules/safety.md` Rule 10: external API / SDK / CLI / tool verification boundary.
250
- - `dev/rules/safety.md` Rule 12: credential leak prevention.
251
- - `dev/rules/safety.md` Rule 14: process termination and cache cleanup boundary for external-tool resources.
252
- - `dev/rules/onboarding.md` Scenario F: first-contact declaration entry point.
253
- - installed `AGENTS.md`: task-triggered availability probe discipline.
254
- - `dev/PROJECT_INDEX.md` `## Installed Integrations` and `## External Sources` `via` column: declaration registry.
248
+ - `dev/rules/knowledge.md` Rule 5: Connector-first source access discipline.
249
+ - `dev/rules/safety.md` Rule 10: external API / SDK / CLI / tool verification boundary.
250
+ - `dev/rules/safety.md` Rule 12: credential leak prevention.
251
+ - `dev/rules/safety.md` Rule 14: process termination and cache cleanup boundary for external-tool resources.
252
+ - `dev/rules/onboarding.md` Scenario F: first-contact declaration entry point.
253
+ - installed `AGENTS.md`: task-triggered availability probe discipline.
254
+ - `dev/PROJECT_INDEX.md` `## Installed Integrations` and `## External Sources` `via` column: declaration registry.
@@ -17,9 +17,9 @@ Use for external notes, knowledge bases, Notion, Obsidian, Drive, docs repositor
17
17
  4. Do not perform destructive external writes without explicit confirmation.
18
18
  5. Connector-first default for external read/write (R-030 Integration governance discipline; works together with `dev/rules/integrations.md`):
19
19
  (a) Before reading or writing external knowledge, check `dev/PROJECT_INDEX.md` `## Installed Integrations` for declared tool availability.
20
- (b) If a declared Integration is functional in the current session (verified under the task-triggered availability probe in installed `AGENTS.md`): use only the active runtime tool calls whose current name, description, and input schema have been inspected under the External Tool Usage Verification Gate. Do not invent `mcp__*` names or arguments from examples or memory.
21
- (c) If a declared Integration is unavailable in the current session, follow `dev/rules/integrations.md` fallback: classify the actual failure, check a task-authorized capable channel and normal platform approval, and use a manual packet only when it preserves the needed evidence. Record drift honestly; update `Last Verified` only after a real successful probe and the normal Persistence Gate.
22
- (d) If no declaration exists in `## Installed Integrations` but the task references an external tool: first inspect the active runtime for an authorized capable tool/schema. Ask the user only for access, source information, or a decision that the AI cannot obtain; do not silently assume paste fallback. Backward-compat: existing v0.2.x projects with no Installed Integrations section follow the same bounded capability check before any necessary user question.
20
+ (b) If a declared Integration is functional in the current session (verified under the task-triggered availability probe in installed `AGENTS.md`): use only the active runtime tool calls whose current name, description, and input schema have been inspected under the External Tool Usage Verification Gate. Do not invent `mcp__*` names or arguments from examples or memory.
21
+ (c) If a declared Integration is unavailable in the current session, follow `dev/rules/integrations.md` fallback: classify the actual failure, check a task-authorized capable channel and normal platform approval, and use a manual packet only when it preserves the needed evidence. Record drift honestly; update `Last Verified` only after a real successful probe and the normal Persistence Gate.
22
+ (d) If no declaration exists in `## Installed Integrations` but the task references an external tool: first inspect the active runtime for an authorized capable tool/schema. Ask the user only for access, source information, or a decision that the AI cannot obtain; do not silently assume paste fallback. Backward-compat: existing v0.2.x projects with no Installed Integrations section follow the same bounded capability check before any necessary user question.
23
23
  6. When writing to an external mirror or index, read back the written record before claiming sync success.
24
24
  7. Preserve local file paths as plain text, code, or structured rich text fields when the external tool parses Markdown links or escape characters.
25
25
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## Scope
4
4
 
5
- Use this transient pack for first-time Agent Handoff Kit users after a fresh install, users who request guidance, or when the user's first-task intent remains genuinely unresolved after reading the available project state.
5
+ Use this transient pack for first-time Agent Handoff Kit users after a fresh install, users who request guidance, or when the user's first-task intent remains genuinely unresolved after reading the available project state.
6
6
 
7
7
  The goal is to help the user complete a small first task without requiring them to read README, guide pages, `AGENTS.md`, or internal Kit rules first. After the onboarding walk-through finishes, unload this pack and continue with the regular scenario pack such as coding, research, writing, knowledge, or integrations.
8
8
 
@@ -20,58 +20,58 @@ Load this pack when the user message contains an onboarding signal such as:
20
20
  - vague project intent such as "I want to do a project"
21
21
  - equivalent Chinese user phrases such as "新手", "教我用", "點開始", "能力", or "能做甚麼"
22
22
 
23
- `I just installed` / "我剛安裝" is a first-use signal. When `SESSION_HANDOFF` says `First-use guidance state: eligible` and no executable objective remains, load this pack and give the first-use welcome. It does not override a same-message concrete task with enough material facts.
23
+ `I just installed` / "我剛安裝" is a first-use signal. When `SESSION_HANDOFF` says `First-use guidance state: eligible` and no executable objective remains, load this pack and give the first-use welcome. It does not override a same-message concrete task with enough material facts.
24
24
 
25
25
  ### Continuity startup boundary
26
26
 
27
- `Start Agent Handoff` / "開工" starts continuity and reads the minimum current handoff state; it is not an onboarding signal by itself. A plain startup normally stops after its status card and recommended next action; a loaded objective alone does not authorize work. First-use eligible plain startup is the exception: when the handoff says `First-use guidance state: eligible`, the active objective is empty / `TBD`, and the user did not provide a same-message concrete task, enter onboarding instead of ending status-only. A same-message concrete task may begin normally. Only when no executable objective remains after state reading should the AI ask one concise question or offer the guided onboarding path. Explicit requests such as "新手,教我用" enter onboarding directly.
27
+ `Start Agent Handoff` / "開工" starts continuity and reads the minimum current handoff state; it is not an onboarding signal by itself. A plain startup normally stops after its status card and recommended next action; a loaded objective alone does not authorize work. First-use eligible plain startup is the exception: when the handoff says `First-use guidance state: eligible`, the active objective is empty / `TBD`, and the user did not provide a same-message concrete task, enter onboarding instead of ending status-only. A same-message concrete task may begin normally. Only when no executable objective remains after state reading should the AI ask one concise question or offer the guided onboarding path. Explicit requests such as "新手,教我用" enter onboarding directly.
28
28
 
29
29
  ### Implicit signals
30
30
 
31
31
  - The first user message is short and still genuinely vague after available project state is read.
32
- - `SESSION_HANDOFF` first-use guidance state is `eligible`, Active Objective is empty / `TBD`, and the user has not supplied a concrete objective with enough material facts. This is the fresh-install welcome path and should not be skipped as an ordinary status-only startup.
32
+ - `SESSION_HANDOFF` first-use guidance state is `eligible`, Active Objective is empty / `TBD`, and the user has not supplied a concrete objective with enough material facts. This is the fresh-install welcome path and should not be skipped as an ordinary status-only startup.
33
33
  - The user asks a generic capability question instead of giving a concrete task.
34
34
  - The user appears unfamiliar with the workflow, for example asking what the AI should do rather than giving an objective.
35
35
 
36
- ## Discipline
37
-
38
- ### 1. Onboarding brand card
39
-
40
- Every onboarding reply, including a blocked/safe-stop reply, starts with a fenced cat brand card. Use the normal guidance card when help can continue:
41
-
42
- ```text
43
- /\_/\ Agent Handoff Kit
44
- ( o.o ) quick guide
45
- > ^ <
46
- ```
47
-
48
- When a required condition blocks onboarding, keep the same card and replace only its middle line with ` ( x.x ) onboarding paused`, then state the exact blocker and next safe action. The normal guidance card is the display-only onboarding card. The card is presentation only: it must not claim `continuity ready`, `handoff saved`, a version, loaded state, doctor health, or that `SESSION_HANDOFF.md` has been read.
49
-
50
- ### 1.1 Do not assume prior reading
51
-
52
- The user may start directly from an AI conversation. Explain only the minimum needed for the current step. Do not teach internal file structure, pack names, release identifiers, maintenance rules, or implementation details unless the user asks.
53
-
54
- ### 1.2 Public capability answer
55
-
56
- When the user asks "教我用", "能力", "能做甚麼", "what can agent handoff kit do", or an equivalent broad help question, answer in normal user language first. The main answer is what the user can say to an AI, not a CLI command list.
57
-
58
- For broad help / capability answers, use the normal `quick guide` card above. Do not perform extra reads, `doctor`, version checks, or handoff loading merely to fill the card.
59
-
60
- Cover these public command categories:
61
-
62
- - Daily continuity: say "開工" / "Start Agent Handoff" to resume, and "收工" / "wrap up" to save a handoff.
63
- - Keep important files connected: say "把這份文件接入 Agent Handoff Kit,讓下次 AI 知道何時要讀、何時要更新。" / "Connect this document to Agent Handoff Kit so the next AI knows when to read and update it."
64
- - Find missing governance links: say "掃描未接入 Agent Handoff Kit 的重要文件。" / "Scan for important documents not yet connected to Agent Handoff Kit."
65
- - Turn a recurring mistake into future practice: say "把今次錯誤整理成日後工作規則,讓下次 AI 知道要怎樣避免。" / "Turn this mistake into a durable work rule for future sessions."
66
- - Keep an API / MCP / tool-use practice reusable: say "以後都用這個 API 調用方式,之後開新對話也要沿用。" / "Use this API approach in future sessions too."
67
- - Declare external tools safely: say "這個項目會用到這些外部工具,請記住哪些能直接使用,機密不要寫入項目文件。" / "Record what external tools can be used directly and keep secrets out of project files."
68
- - Finish a long external-tool task cleanly: say "收工時請顯示外部工具資源收口結果:已關閉哪些本任務資源,哪些因歸屬不明而保留並列證據。" / "At wrap up, show the external-tool resource closeout."
69
-
70
- Do not make CLI maintenance commands the main onboarding answer. Mention `init`, `upgrade`, `doctor`, `workspace-health`, or `closeout-status` only when the user asks about installation, upgrade, repair, health checks, manual terminal use, or when the current task needs those checks. For a zero-background user, phrase maintenance as "the AI can install, upgrade, or check the Kit when needed" before exposing exact commands.
71
-
72
- ### 2. Infer first; offer scenario choice only when needed
73
-
74
- Infer when sufficient; ask only when unresolved. Read the user's message together with the available handoff and project state before deciding whether a chooser is needed.
36
+ ## Discipline
37
+
38
+ ### 1. Onboarding brand card
39
+
40
+ Every onboarding reply, including a blocked/safe-stop reply, starts with a fenced cat brand card. Use the normal guidance card when help can continue:
41
+
42
+ ```text
43
+ /\_/\ Agent Handoff Kit
44
+ ( o.o ) quick guide
45
+ > ^ <
46
+ ```
47
+
48
+ When a required condition blocks onboarding, keep the same card and replace only its middle line with ` ( x.x ) onboarding paused`, then state the exact blocker and next safe action. The normal guidance card is the display-only onboarding card. The card is presentation only: it must not claim `continuity ready`, `handoff saved`, a version, loaded state, doctor health, or that `SESSION_HANDOFF.md` has been read.
49
+
50
+ ### 1.1 Do not assume prior reading
51
+
52
+ The user may start directly from an AI conversation. Explain only the minimum needed for the current step. Do not teach internal file structure, pack names, release identifiers, maintenance rules, or implementation details unless the user asks.
53
+
54
+ ### 1.2 Public capability answer
55
+
56
+ When the user asks "教我用", "能力", "能做甚麼", "what can agent handoff kit do", or an equivalent broad help question, answer in normal user language first. The main answer is what the user can say to an AI, not a CLI command list.
57
+
58
+ For broad help / capability answers, use the normal `quick guide` card above. Do not perform extra reads, `doctor`, version checks, or handoff loading merely to fill the card.
59
+
60
+ Cover these public command categories:
61
+
62
+ - Daily continuity: say "開工" / "Start Agent Handoff" to resume, and "收工" / "wrap up" to save a handoff.
63
+ - Keep important files connected: say "把這份文件接入 Agent Handoff Kit,讓下次 AI 知道何時要讀、何時要更新。" / "Connect this document to Agent Handoff Kit so the next AI knows when to read and update it."
64
+ - Find missing governance links: say "掃描未接入 Agent Handoff Kit 的重要文件。" / "Scan for important documents not yet connected to Agent Handoff Kit."
65
+ - Turn a recurring mistake into future practice: say "把今次錯誤整理成日後工作規則,讓下次 AI 知道要怎樣避免。" / "Turn this mistake into a durable work rule for future sessions."
66
+ - Keep an API / MCP / tool-use practice reusable: say "以後都用這個 API 調用方式,之後開新對話也要沿用。" / "Use this API approach in future sessions too."
67
+ - Declare external tools safely: say "這個項目會用到這些外部工具,請記住哪些能直接使用,機密不要寫入項目文件。" / "Record what external tools can be used directly and keep secrets out of project files."
68
+ - Finish a long external-tool task cleanly: say "收工時請顯示外部工具資源收口結果:已關閉哪些本任務資源,哪些因歸屬不明而保留並列證據。" / "At wrap up, show the external-tool resource closeout."
69
+
70
+ Do not make CLI maintenance commands the main onboarding answer. Mention `init`, `upgrade`, `doctor`, `workspace-health`, or `closeout-status` only when the user asks about installation, upgrade, repair, health checks, manual terminal use, or when the current task needs those checks. For a zero-background user, phrase maintenance as "the AI can install, upgrade, or check the Kit when needed" before exposing exact commands.
71
+
72
+ ### 2. Infer first; offer scenario choice only when needed
73
+
74
+ Infer when sufficient; ask only when unresolved. Read the user's message together with the available handoff and project state before deciding whether a chooser is needed.
75
75
 
76
76
  When the user has already supplied a concrete, actionable objective and enough material facts, infer the closest working scenario, state the assumption briefly, load the regular task pack(s), and begin the first safe action. Do not require an A-F reply, repeat questions whose answers are already available, or reduce a concrete request to a generic minimum task.
77
77
 
@@ -188,7 +188,7 @@ Step E.5: after confirmation, load the appropriate regular pack combination.
188
188
 
189
189
  Use this scenario when the user already has external tools installed or asks how to use them safely across sessions. This scenario does not teach installation. It records declarations, boundaries, verification, and safe use.
190
190
 
191
- Step F.1: inspect runtime-exposed external tools by category first: Connectors, MCPs, Plugins, Skills, browser automation, crawlers, notebooks, or local helper services. Ask the user only for names, access, or source details the runtime cannot reveal, then classify them.
191
+ Step F.1: inspect runtime-exposed external tools by category first: Connectors, MCPs, Plugins, Skills, browser automation, crawlers, notebooks, or local helper services. Ask the user only for names, access, or source details the runtime cannot reveal, then classify them.
192
192
 
193
193
  Step F.2: explain credential separation: Kit files record tool names, project usage, access scope, and credential reference location only. They must never store API keys, OAuth tokens, secrets, or credential values.
194
194
 
@@ -196,7 +196,7 @@ Step F.3: map source-of-truth architecture: source of truth, index, persistent m
196
196
 
197
197
  Step F.4: when authorized, write the declaration into `PROJECT_INDEX` `## Installed Integrations` and cross-reference relevant External Sources `via` values.
198
198
 
199
- Step F.5: verify current availability using runtime-exposed tool schemas, official docs, or versioned local runbooks. For an unavailable tool, follow `dev/rules/integrations.md` classified fallback for the affected surface; mark blocked / unverified only when no authorized capable route can establish the needed contract.
199
+ Step F.5: verify current availability using runtime-exposed tool schemas, official docs, or versioned local runbooks. For an unavailable tool, follow `dev/rules/integrations.md` classified fallback for the affected surface; mark blocked / unverified only when no authorized capable route can establish the needed contract.
200
200
 
201
201
  ## Cross-reference to guide.html
202
202