@adamchanadam/agent-handoff-kit 0.3.38 → 0.3.40

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/packs/safety.md CHANGED
@@ -2,12 +2,12 @@
2
2
 
3
3
  ## Scope
4
4
 
5
- Use for file operations, shell commands, Git changes, package managers, installers, deploy tools, release tools, cloud tools, external APIs, browser profiles, desktop app sessions, notebook kernels, local tool servers, locked files, permission errors, sandbox restrictions, or any task that could affect data loss, credentials, public release state, user sessions, shared local resources, or external systems.
5
+ Use for file operations, shell commands, Git changes, package managers, installers, deploy tools, release tools, cloud tools, external APIs, browser profiles, desktop app sessions, notebook kernels, local tool servers, locked files, permission errors, sandbox restrictions, or any task that could affect data loss, credentials, public release state, user sessions, shared local resources, or external systems.
6
6
 
7
7
  ## Load When
8
8
 
9
9
  - User requests deletion, overwrite, move, rename, cleanup, Git history changes, package installation, publish, deploy, release, cloud writes, external API calls, or credential handling.
10
- - A task touches filesystem paths, shell commands, permissions, sandbox limits, locks, secrets, external systems, browser profiles, desktop app sessions, notebook kernels, local tool servers, shared caches, or public release state.
10
+ - A task touches filesystem paths, shell commands, permissions, sandbox limits, locks, secrets, external systems, browser profiles, desktop app sessions, notebook kernels, local tool servers, shared caches, or public release state.
11
11
  - Another pack is loaded but the task includes data-loss, credential, permission, external-system, or irreversible-operation risk.
12
12
 
13
13
  ## Rules
@@ -16,31 +16,33 @@ Use for file operations, shell commands, Git changes, package managers, installe
16
16
  2. Preserve user-provided source files by default. Create renamed outputs instead of in-place overwrites unless overwrite is explicitly requested.
17
17
  3. Never operate on a filesystem root, drive root, home directory root, repository parent root, system directory, or ambiguous path.
18
18
  4. Do not bypass permissions, file locks, sandbox limits, failed safety checks, or denied operations. Report the blocker and manual action needed.
19
- 5. Do not run recursive or bulk destructive commands such as `rm -rf`, `Remove-Item -Recurse -Force`, `git clean -fdx`, or equivalent cleanup operations unless the user explicitly requested the operation and resolved absolute targets are verified.
19
+ 5. Never run `rm -rf`, `sudo rm -rf`, `Remove-Item -Recurse -Force`, `git clean -fdx`, `git reset --hard`, or an obfuscated / wrapped equivalent. User request does not make these named commands permissible. Use a narrower reversible operation or provide a manual action list.
20
20
  6. On Windows, do not use `cmd /c rmdir`, `cmd /c rd`, or any `cmd.exe /c` variant combined with `rmdir` or `rd`. Prefer native PowerShell cmdlets when PowerShell is active, and do not compose filesystem modification commands across shells.
21
- 7. On macOS / Linux, do not run `rm -rf`, `sudo rm`, recursive `chmod`, recursive `chown`, or destructive wildcard operations unless the user explicitly requested the operation and target paths are listed and verified.
22
- 8. Do not run `git reset --hard`, branch deletion, tag deletion, force push, or history rewrite unless the user explicitly requested it and affected refs/files are listed.
21
+ 7. On macOS / Linux, never use destructive wildcards, recursive `chmod 777`, recursive `chown`, disk formatting, mount-point cleanup, or home/system-directory cleanup. Other destructive operations require explicit authorization plus resolved target verification and must use the narrowest safe tool.
22
+ 8. Branch deletion, tag deletion, force push, and history rewrite require separate explicit authorization and affected-ref verification. The absolute prohibitions in Rule 5 remain prohibited even when such authorization exists.
23
23
  9. Before staging or committing, inspect current status and avoid staging unrelated parent-repo, sibling-directory, generated, credential, or user-owned changes.
24
- 10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools, release tools, browser automation, DevTools, Playwright, crawlers, notebooks, desktop app automation, or local helper services, verify current official documentation or project-local runbooks. For external tools, first apply the External Tool Usage Verification Gate in `dev/rules/integrations.md`: inspect current runtime tool schema for Connector / MCP calls, and use current official docs, official type definitions, official samples, or registered tool operation references for raw API / SDK / CLI / URI / plugin API work. Differentiate three layers of external access:
25
- (a) Anthropic-vetted Connectors (e.g. Notion / Google Drive / Slack via Claude Desktop Extensions): trust the vetted MCP server boundary only after inspecting the active runtime tool name, description, and input schema; still verify destructive write parameters before invocation.
26
- (b) Community / custom MCP servers (user-installed via manual config): treat with extra caution — destructive writes require dry-run + user confirmation; verify server behavior against current tool schema and project-local runbook if available.
27
- (c) Raw external APIs / SDKs / CLIs (no MCP layer): full Rule 10 verification of official docs required; mark unverified if blocked.
24
+ 10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools, release tools, browser automation, DevTools, Playwright, crawlers, notebooks, desktop app automation, or local helper services, verify current official documentation or project-local runbooks. For external tools, first apply the External Tool Usage Verification Gate in `dev/rules/integrations.md`: inspect current runtime tool schema for Connector / MCP calls, and use current official docs, official type definitions, official samples, or registered tool operation references for raw API / SDK / CLI / URI / plugin API work. Differentiate three layers of external access:
25
+ (a) Anthropic-vetted Connectors (e.g. Notion / Google Drive / Slack via Claude Desktop Extensions): trust the vetted MCP server boundary only after inspecting the active runtime tool name, description, and input schema; still verify destructive write parameters before invocation.
26
+ (b) Community / custom MCP servers (user-installed via manual config): treat with extra caution — destructive writes require dry-run + user confirmation; verify server behavior against current tool schema and project-local runbook if available.
27
+ (c) Raw external APIs / SDKs / CLIs (no MCP layer): full Rule 10 verification of official docs required; mark unverified if blocked.
28
28
  11. Do not print, copy, log, commit, upload, or generate files containing secret values. Use redacted placeholders or line references.
29
- 12. Credential leak prevention (R-030 Integration governance):
30
- (a) Never request, log, or persist credential values (API keys / OAuth tokens / app secrets / refresh tokens) in any project file. Credentials live exclusively in AI tool secure storage, OS credential stores, AI tool config, user-managed secret stores, or env indirection; if env is used, project files may record only the env var name, never the value.
31
- (b) Recognize common credential prefixes (`sk-`, `sk-ant-`, `ntn_`, `secret_`, `ya29.`, `1//`, `xoxp-`, `xoxb-`, `ghp_`, `gho_`, `ghs_`, `github_pat_`, `sl.`, `AKIA`, `AIza`) — if a value matching any prefix appears in conversation, redact immediately and warn the user to rotate the token.
32
- (c) Before writing to `dev/PROJECT_INDEX.md` `## Installed Integrations`, `dev/SESSION_HANDOFF.md`, or `dev/SESSION_LOG.md`, self-check that no credential value is present; doctor `checkInstalledIntegrationsCredentialLeak()` enforces this at QC.
33
- (d) Auth failure (token expired / revoked / rate-limit) surfaces to the user with a pointer to the AI tool's own settings interface; do not attempt to auto-fix auth or re-auth flow (out of scope for Kit governance).
34
- 13. Shell / script parser failure discipline: after a shell, quoting, here-string, wrapper, temporary script, or parser failure, stop same-pattern retries and classify the failing layer before trying again: active shell, wrapper shell, runtime parser, package manager, or target CLI. Do not embed large JavaScript, JSON, Markdown, regex, patch, or path-heavy content inside shell strings when a direct tool, patch file, or real script file is safer. For temporary scripts, first make a minimal reproducible script, run a syntax-only check such as `node --check`, `python -m py_compile`, or an equivalent parser check where available, then execute. After any write script, read back the affected files or affected ranges before claiming success. If the same parser failure repeats, stop and return to root-cause classification instead of changing quoting again.
35
- 14. Process termination and cache cleanup boundary: agents may automatically close or clean up resources that are clearly task-owned or agent-managed, including task-created browser contexts, MCP child processes, helper servers, notebook kernels, temp directories, or bounded caches. Agents must not terminate shared, ambiguous, user-owned, system-level, or other-agent-owned processes; delete broad caches; disable tools; uninstall packages; mutate browser profiles, desktop app sessions, shared tool servers, notebook kernels, global package / browser / plugin caches, or change configuration without explicit user confirmation listing exact process IDs or paths, tool names, evidence, expected impact, and restart / rollback path. Generic process names such as `node`, `python`, or `chrome` are never enough ownership evidence by themselves. If a process, browser context, desktop app session, notebook kernel, MCP service, or helper server may belong to another AI agent running on the same machine, treat it as shared unless current-task ownership is proven.
36
-
37
- ## Checks
38
-
39
- - Report which safety-relevant command, path, API, install, deploy, release, or Git check was performed and the result.
40
- - If checks cannot run, state the reason and mark the result unverified.
41
- - For durable governance changes, update the project index, sync registry, and any human review map if they exist.
42
- - For external-tool resource cleanup, report the ownership class used: task-owned, agent-managed, shared / user-owned / other-agent-owned / system-level, or unknown.
43
-
44
- ## Closeout
45
-
46
- Record unresolved safety risks, blocked verification, pending manual actions, dirty worktrees, or external sync gaps in `dev/SESSION_HANDOFF.md`.
29
+ 12. Credential leak prevention (R-030 Integration governance):
30
+ (a) Never request, log, or persist credential values (API keys / OAuth tokens / app secrets / refresh tokens) in any project file. Credentials live exclusively in AI tool secure storage, OS credential stores, AI tool config, user-managed secret stores, or env indirection; if env is used, project files may record only the env var name, never the value.
31
+ (b) Recognize common credential prefixes (`sk-`, `sk-ant-`, `ntn_`, `secret_`, `ya29.`, `1//`, `xoxp-`, `xoxb-`, `ghp_`, `gho_`, `ghs_`, `github_pat_`, `sl.`, `AKIA`, `AIza`) — if a value matching any prefix appears in conversation, redact immediately and warn the user to rotate the token.
32
+ (c) Before writing to `dev/PROJECT_INDEX.md` `## Installed Integrations`, `dev/SESSION_HANDOFF.md`, or `dev/SESSION_LOG.md`, self-check that no credential value is present; doctor `checkInstalledIntegrationsCredentialLeak()` enforces this at QC.
33
+ (d) Auth failure (token expired / revoked / rate-limit) surfaces to the user with a pointer to the AI tool's own settings interface; do not attempt to auto-fix auth or re-auth flow (out of scope for Kit governance).
34
+ 13. Shell / script parser failure discipline: after a shell, quoting, here-string, wrapper, temporary script, or parser failure, stop same-pattern retries and classify the failing layer before trying again: active shell, wrapper shell, runtime parser, package manager, or target CLI. Do not embed large JavaScript, JSON, Markdown, regex, patch, or path-heavy content inside shell strings when a direct tool, patch file, or real script file is safer. For temporary scripts, first make a minimal reproducible script, run a syntax-only check such as `node --check`, `python -m py_compile`, or an equivalent parser check where available, then execute. After any write script, read back the affected files or affected ranges before claiming success. If the same parser failure repeats, stop and return to root-cause classification instead of changing quoting again.
35
+ 14. Process termination and cache cleanup boundary: agents may automatically close or clean up resources that are clearly task-owned or agent-managed, including task-created browser contexts, MCP child processes, helper servers, notebook kernels, temp directories, or bounded caches. Agents must not terminate shared, ambiguous, user-owned, system-level, or other-agent-owned processes; delete broad caches; disable tools; uninstall packages; mutate browser profiles, desktop app sessions, shared tool servers, notebook kernels, global package / browser / plugin caches, or change configuration without explicit user confirmation listing exact process IDs or paths, tool names, evidence, expected impact, and restart / rollback path. Generic process names such as `node`, `python`, or `chrome` are never enough ownership evidence by themselves. If a process, browser context, desktop app session, notebook kernel, MCP service, or helper server may belong to another AI agent running on the same machine, treat it as shared unless current-task ownership is proven.
36
+ 15. Short-lived localhost validation services: when local HTML / app validation needs a safer fallback after `file://` is blocked, a task-owned loopback static server is allowed only within a bounded project or temp path, bound to localhost / loopback, and used for the current validation task. Record the served root, URL, and evidence collected. Stop the server before completion and verify it is no longer reachable when the runtime allows. Do not leave helper servers running as a convenience, expose them beyond loopback, reuse another agent's server without confirmation, or mutate browser profiles / extension state to make the validation pass.
37
+
38
+ ## Checks
39
+
40
+ - Report which safety-relevant command, path, API, install, deploy, release, or Git check was performed and the result.
41
+ - If checks cannot run, state the reason and mark the result unverified.
42
+ - For durable governance changes, update the project index, sync registry, and any human review map if they exist.
43
+ - For external-tool resource cleanup, report the ownership class used: task-owned, agent-managed, shared / user-owned / other-agent-owned / system-level, or unknown.
44
+ - For short-lived localhost validation services, report the served root / URL, evidence collected, and cleanup result or cleanup blocker.
45
+
46
+ ## Closeout
47
+
48
+ Record unresolved safety risks, blocked verification, pending manual actions, dirty worktrees, or external sync gaps in `dev/SESSION_HANDOFF.md`.
package/packs/writing.md CHANGED
@@ -1,36 +1,36 @@
1
- # Writing Pack
2
-
3
- ## Scope
4
-
5
- Use for drafting, editing, style, structure, publication copy, documentation prose, and tone control.
6
-
7
- ## Load When
8
-
9
- - User asks to write, rewrite, summarize, translate, or edit text.
10
- - The task has a target audience, voice, format, or publication surface.
11
-
12
- ## Rules
13
-
14
- 1. Identify audience, purpose, and target surface before rewriting.
15
- 2. Preserve factual meaning unless the user asks for content changes.
16
- 3. Keep terminology consistent with project docs.
17
- 4. Mark uncertain claims instead of inventing support.
18
- 5. Do not bury durable requirements only in prose; use project index, spec, runbook, or handoff when needed.
19
- 6. For public Traditional Chinese docs or HTML aimed at non-technical readers, use steady written Chinese. Keep English only for commands, paths, URLs, file names, product names, and unavoidable tool names. Avoid mixed half-English fragments, internal governance codes, and developer-only wording in reader-facing prose.
20
- 7. For public README, onboarding, and other user-facing docs, use the product-journey rule: the user states the goal, the AI handles technical work. Keep one primary user path. Do not make users choose between install, upgrade, doctor, dry-run, or terminal commands when an AI-assisted path exists. Put technical commands in the dedicated AI install page, CLI help, or advanced examples instead of duplicating them in the main README flow.
21
- 8. When writing or revising Markdown files, decide whether the output is a durable source, a reference, a runbook, a public document, a reusable generated artifact, a draft, or one-time evidence. Durable outputs must be indexed or tied to a registered source/sync home before completion; drafts and one-time evidence must be labeled so they do not become hidden current state.
22
- 9. If a new document repeats requirements, instructions, acceptance rules, or process already owned by another file, consolidate into the existing source or make the new file explicitly subordinate. Do not let writing work create parallel truth.
23
-
24
- ## Checks
25
-
26
- - Verify requested format, language, and tone.
27
- - Check links, commands, names, and version-sensitive claims when relevant.
28
- - Check `dev/DOC_SYNC_REGISTRY.md` if public docs or user-facing instructions changed.
29
- - For any Markdown file created or materially changed, check whether `dev/PROJECT_INDEX.md` needs a Directory Map, Fact Base, Entry Points, or read-condition update.
30
- - Check duplicate-source risk before keeping a new requirement, checklist, process, or instruction document.
31
- - For public Chinese docs, read the final text as a new user journey: the next action should be clear without technical background.
32
- - For README-style docs, confirm the main path does not become parallel instructions: no repeated manual install section, no competing command table, and no requirement that the reader understand internal files before taking the first action.
33
-
34
- ## Closeout
35
-
36
- Record changed documents, unresolved content questions, and any sync or follow-up needed.
1
+ # Writing Pack
2
+
3
+ ## Scope
4
+
5
+ Use for drafting, editing, style, structure, publication copy, documentation prose, and tone control.
6
+
7
+ ## Load When
8
+
9
+ - User asks to write, rewrite, summarize, translate, or edit text.
10
+ - The task has a target audience, voice, format, or publication surface.
11
+
12
+ ## Rules
13
+
14
+ 1. Identify audience, purpose, and target surface before rewriting.
15
+ 2. Preserve factual meaning unless the user asks for content changes.
16
+ 3. Keep terminology consistent with project docs.
17
+ 4. Mark uncertain claims instead of inventing support.
18
+ 5. Do not bury durable requirements only in prose; use project index, spec, runbook, or handoff when needed.
19
+ 6. For public Traditional Chinese docs or HTML aimed at non-technical readers, use steady written Chinese. Keep English only for commands, paths, URLs, file names, product names, and unavoidable tool names. Avoid mixed half-English fragments, internal governance codes, and developer-only wording in reader-facing prose.
20
+ 7. For public README, onboarding, and other user-facing docs, use the product-journey rule: the user states the goal, the AI handles technical work. Keep one primary user path. Do not make users choose between install, upgrade, doctor, dry-run, or terminal commands when an AI-assisted path exists. Put technical commands in the dedicated AI install page, CLI help, or advanced examples instead of duplicating them in the main README flow.
21
+ 8. When writing or revising Markdown files, decide whether the output is a durable source, a reference, a runbook, a public document, a reusable generated artifact, a draft, or one-time evidence. Durable outputs must be indexed or tied to a registered source/sync home before completion; drafts and one-time evidence must be labeled so they do not become hidden current state.
22
+ 9. If a new document repeats requirements, instructions, acceptance rules, or process already owned by another file, consolidate into the existing source or make the new file explicitly subordinate. Do not let writing work create parallel truth.
23
+
24
+ ## Checks
25
+
26
+ - Verify requested format, language, and tone.
27
+ - Check links, commands, names, and version-sensitive claims when relevant.
28
+ - Check `dev/DOC_SYNC_REGISTRY.md` if public docs or user-facing instructions changed.
29
+ - For any Markdown file created or materially changed, check whether `dev/PROJECT_INDEX.md` needs a Directory Map, Fact Base, Entry Points, or read-condition update.
30
+ - Check duplicate-source risk before keeping a new requirement, checklist, process, or instruction document.
31
+ - For public Chinese docs, read the final text as a new user journey: the next action should be clear without technical background.
32
+ - For README-style docs, confirm the main path does not become parallel instructions: no repeated manual install section, no competing command table, and no requirement that the reader understand internal files before taking the first action.
33
+
34
+ ## Closeout
35
+
36
+ Record changed documents, unresolved content questions, and any sync or follow-up needed.
@@ -1,190 +1,112 @@
1
1
  # Agent Handoff Kit Core Runtime
2
2
 
3
- This is the lightweight core. It is the always-read contract for AI sessions.
3
+ This is the small always-read contract. Detailed task and closeout procedures live in routed packs.
4
4
 
5
- ## 1. Startup Reads
5
+ ## 1. Intent And Startup
6
6
 
7
- After this core is loaded, read in order:
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
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`
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.
13
10
 
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.
11
+ Route intent in this order:
15
12
 
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.
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
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.
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
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.
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
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.
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
23
 
24
- If a required file is missing, create the smallest useful version only after confirming the target project root.
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
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.
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.
29
27
 
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`):
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.
31
29
 
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.
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.
40
31
 
41
32
  ```text
42
33
  /\_/\ Agent Handoff Kit v<version>
43
34
  ( o.o ) continuity ready
44
35
  > ^ <
45
36
 
46
- 🔎 交接狀態:<loaded / new install / resumed>
47
- 📌 目前目標:<current objective>
48
- ⚠️ 注意事項:<important boundary or none>
49
- 🚀 推薦下一步:<one recommended next action + short reason>
50
- ```
51
-
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
37
+ 🔎 交接狀態:<loaded / new install / resumed>
38
+ 📌 目前目標:<current objective>
39
+ ⚠️ 注意事項:<important boundary or none>
40
+ 🚀 推薦下一步:<one action + reason>
41
+ ```
55
42
 
56
- Use this loop for every task:
43
+ Use the full product name, plain user language, and one recommended next action. Never print the literal placeholder `v<version>`.
57
44
 
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.
45
+ ## 2. Proportionate Work Loop
64
46
 
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.
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.
66
48
 
67
- For high-risk work, pause after PLAN. High-risk means destructive operations, ambiguous target, external systems, release/publish, or broad multi-file change.
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.
68
54
 
69
55
  ## 2.1 Persistence Gate
70
56
 
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
57
+ Choose exactly one tier after a task:
103
58
 
104
- Do not delete, reset, overwrite, bulk-move, or publish without explicit user approval.
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`.
105
62
 
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.
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.
107
64
 
108
- Do not modify unrelated files. If unexpected user changes appear, work with them or ask before touching them.
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.
109
66
 
110
- Do not claim completion without evidence from checks, inspection, or a clear explanation of what could not be verified.
67
+ ## 2.2 Upgrade Completion
111
68
 
112
- ## 4. Closeout And Handoff
69
+ The CLI owns upgrade truth. An upgrade is complete only when:
113
70
 
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:
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.
121
77
 
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.
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.
123
79
 
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`.
80
+ ## 3. Safety Baseline
136
81
 
137
- Hard triggers:
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.
138
83
 
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.
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.
140
85
 
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.
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.
142
87
 
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.
88
+ Do not modify unrelated files or erase unexpected user changes. Do not claim completion without read-back evidence and proportionate checks.
144
89
 
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.
90
+ ## 4. Closeout Trigger
146
91
 
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.
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.
148
93
 
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.
94
+ The always-enforced closeout invariants are:
150
95
 
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.
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.
175
101
 
176
102
  ## 5. Pack Loading
177
103
 
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.
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.
183
105
 
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.
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.
185
107
 
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.
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.
187
109
 
188
110
  ## Core Complexity Rule
189
111
 
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.
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.
@@ -1,13 +1,13 @@
1
- # Claude Code Entry Bridge
2
-
3
- @AGENTS.md
4
-
5
- This file is a bridge only. Claude Code reads `CLAUDE.md` automatically, so this bridge imports `AGENTS.md`, which remains the single authoritative startup file for Agent Handoff Kit.
6
-
7
- Do not expand, summarize, replace, or "improve" this file during onboarding, setup, `/init`, or project documentation work. Do not add command lists, architecture summaries, project state, or handoff notes here.
8
-
9
- If the user says `I just installed agent-handoff-kit`, `help me get started`, or similar first-use wording, do not run Claude Code `/init` and do not load an `init` skill. Agent Handoff Kit is already installed. Read `AGENTS.md`, load the onboarding rule when appropriate, and guide the user through the first task.
10
-
11
- Only edit this file when the user explicitly asks to edit `CLAUDE.md` itself, or when `agent-handoff-kit upgrade` reports a bridge conflict and asks for manual repair.
12
-
13
- After loading this bridge, follow `AGENTS.md` and the startup read order defined there.
1
+ # Claude Code Entry Bridge
2
+
3
+ @AGENTS.md
4
+
5
+ This file is a bridge only. Claude Code reads `CLAUDE.md` automatically, so this bridge imports `AGENTS.md`, which remains the single authoritative startup file for Agent Handoff Kit.
6
+
7
+ Do not expand, summarize, replace, or "improve" this file during onboarding, setup, `/init`, or project documentation work. Do not add command lists, architecture summaries, project state, or handoff notes here.
8
+
9
+ If the user says `I just installed agent-handoff-kit`, `help me get started`, or similar first-use wording, do not run Claude Code `/init` and do not load an `init` skill. Agent Handoff Kit is already installed. Read `AGENTS.md`, load the onboarding rule when appropriate, and guide the user through the first task.
10
+
11
+ Only edit this file when the user explicitly asks to edit `CLAUDE.md` itself, or when `agent-handoff-kit upgrade` reports a bridge conflict and asks for manual repair.
12
+
13
+ After loading this bridge, follow `AGENTS.md` and the startup read order defined there.
@@ -1,24 +1,24 @@
1
- # Doc Sync Registry
2
-
3
- Purpose: map change types to documents and checks. Keep this as rows, not long prose.
4
-
5
- ## Status Vocabulary
6
-
7
- Use: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.
8
-
9
- | Change type | Also check/update | Verification |
10
- |---|---|---|
11
- | New file or directory | `dev/PROJECT_INDEX.md` Directory Map | path listed |
12
- | Generated Markdown or durable artifact | `dev/PROJECT_INDEX.md` Directory Map / Fact Base / Entry Points, and this registry when future updates need sync | artifact classified as indexed / synced / temporary / one-time evidence; duplicate source-of-truth risk checked |
13
- | Stack or command change | `dev/PROJECT_INDEX.md` Stack / Entry Points | command verified or marked unverified |
14
- | Public behavior change | README, public docs, changelog | docs mention current behavior |
15
- | API or SDK behavior change | API docs, examples, tests | tests or documented reason |
16
- | Runbook change | runbook path in `PROJECT_INDEX.md` | procedure still executable |
17
- | Governance rule change | relevant pack/core, registry, README if public-facing | complexity budget checked |
18
- | Closeout/startup contract change | `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, README quick usage | opening message schema + workspace identity present |
19
- | Workspace identity change | `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md` | root/branch/commit/status recorded or marked unverified |
20
- | Release | release notes, README version, changelog | release pack checklist |
21
-
22
- ## Registry Rule
23
-
24
- If a change has no matching row, add a row before closeout or record why no durable sync rule is needed. At closeout, record sync status for every row touched by the session.
1
+ # Doc Sync Registry
2
+
3
+ Purpose: map change types to documents and checks. Keep this as rows, not long prose.
4
+
5
+ ## Status Vocabulary
6
+
7
+ Use: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.
8
+
9
+ | Change type | Also check/update | Verification |
10
+ |---|---|---|
11
+ | New file or directory | `dev/PROJECT_INDEX.md` Directory Map | path listed |
12
+ | Generated Markdown or durable artifact | `dev/PROJECT_INDEX.md` Directory Map / Fact Base / Entry Points, and this registry when future updates need sync | artifact classified as indexed / synced / temporary / one-time evidence; duplicate source-of-truth risk checked |
13
+ | Stack or command change | `dev/PROJECT_INDEX.md` Stack / Entry Points | command verified or marked unverified |
14
+ | Public behavior change | README, public docs, changelog | docs mention current behavior |
15
+ | API or SDK behavior change | API docs, examples, tests | tests or documented reason |
16
+ | Runbook change | runbook path in `PROJECT_INDEX.md` | procedure still executable |
17
+ | Governance rule change | relevant pack/core, registry, README if public-facing | complexity budget checked |
18
+ | Closeout/startup contract change | `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, README quick usage | opening message schema + workspace identity present |
19
+ | Workspace identity change | `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md` | root/branch/commit/status recorded or marked unverified |
20
+ | Release | release notes, README version, changelog | release pack checklist |
21
+
22
+ ## Registry Rule
23
+
24
+ If a change has no matching row, add a row before closeout or record why no durable sync rule is needed. At closeout, record sync status for every row touched by the session.