@adamchanadam/agent-handoff-kit 0.4.1 → 0.4.2
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/README.en.md +1 -1
- package/README.md +1 -1
- package/bin/agent-handoff-kit.mjs +181 -21
- package/bin/commands.mjs +2 -2
- package/bin/installed-file-contract.mjs +2 -2
- package/bin/migration-baselines/official-origin-catalog.json +235 -1
- package/bin/official-origin-catalog.mjs +27 -0
- package/package.json +1 -1
- package/packs/agent-governance.md +3 -3
- package/packs/closeout.md +4 -4
- package/packs/integrations.md +20 -20
- package/packs/knowledge.md +3 -3
- package/packs/onboarding.md +16 -12
- package/packs/safety.md +2 -2
- package/runtime-core/AGENTS.core.md +15 -1
- package/runtime-core/DOC_SYNC_REGISTRY.md +1 -1
- package/runtime-core/SESSION_HANDOFF.md +1 -1
- package/runtime-core/SESSION_LOG.md +1 -1
- package/runtime-core/USER_RULES_ENTRY.md +5 -3
package/packs/knowledge.md
CHANGED
|
@@ -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 `
|
|
21
|
-
(c) If a declared Integration is unavailable in the current session
|
|
22
|
-
(d) If no declaration exists in `## Installed Integrations` but the task references an external tool:
|
|
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
|
|
package/packs/onboarding.md
CHANGED
|
@@ -33,17 +33,11 @@ Load this pack when the user message contains an onboarding signal such as:
|
|
|
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. Do not assume prior reading
|
|
39
|
-
|
|
40
|
-
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.
|
|
36
|
+
## Discipline
|
|
41
37
|
|
|
42
|
-
### 1.
|
|
38
|
+
### 1. Onboarding brand card
|
|
43
39
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
Start broad help / capability answers with this display-only onboarding card in a fenced `text` block:
|
|
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:
|
|
47
41
|
|
|
48
42
|
```text
|
|
49
43
|
/\_/\ Agent Handoff Kit
|
|
@@ -51,7 +45,17 @@ Start broad help / capability answers with this display-only onboarding card in
|
|
|
51
45
|
> ^ <
|
|
52
46
|
```
|
|
53
47
|
|
|
54
|
-
The card is
|
|
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.
|
|
55
59
|
|
|
56
60
|
Cover these public command categories:
|
|
57
61
|
|
|
@@ -184,7 +188,7 @@ Step E.5: after confirmation, load the appropriate regular pack combination.
|
|
|
184
188
|
|
|
185
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.
|
|
186
190
|
|
|
187
|
-
Step F.1:
|
|
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.
|
|
188
192
|
|
|
189
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.
|
|
190
194
|
|
|
@@ -192,7 +196,7 @@ Step F.3: map source-of-truth architecture: source of truth, index, persistent m
|
|
|
192
196
|
|
|
193
197
|
Step F.4: when authorized, write the declaration into `PROJECT_INDEX` `## Installed Integrations` and cross-reference relevant External Sources `via` values.
|
|
194
198
|
|
|
195
|
-
Step F.5: verify current availability using runtime-exposed tool schemas, official docs, or versioned local runbooks.
|
|
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.
|
|
196
200
|
|
|
197
201
|
## Cross-reference to guide.html
|
|
198
202
|
|
package/packs/safety.md
CHANGED
|
@@ -15,7 +15,7 @@ Use for file operations, shell commands, Git changes, package managers, installe
|
|
|
15
15
|
1. Before deleting, overwriting, moving, renaming, cleaning, resetting, publishing, or running destructive tool operations, list the exact target paths, expected scope, impact, and required confirmation.
|
|
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
|
-
4. Do not bypass permissions, file locks, sandbox limits, failed safety checks, or denied operations.
|
|
18
|
+
4. Do not bypass permissions, file locks, sandbox limits, failed safety checks, or denied operations. First classify the actual failure and use normal platform approval or another already-authorized safe method only when its scope is verified; a true unresolved denial remains an affected-operation blocker. Ask for manual action only when the user alone can supply the missing condition.
|
|
19
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
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.
|
|
@@ -30,7 +30,7 @@ Use for file operations, shell commands, Git changes, package managers, installe
|
|
|
30
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
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
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
|
|
33
|
+
(d) Auth failure (token expired / revoked) 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). A rate limit is a capacity constraint, not proof of an auth failure: respect its limit and use only an authorized safe path without demanding re-login unless an actual auth failure is verified.
|
|
34
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
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
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.
|
|
@@ -4,6 +4,18 @@ This is the small always-read contract. Detailed task and closeout procedures li
|
|
|
4
4
|
|
|
5
5
|
## 1. Intent And Startup
|
|
6
6
|
|
|
7
|
+
### Upgrade lock guard
|
|
8
|
+
|
|
9
|
+
Before any handoff, user-rule router, pack, or other project-state read, use the verified project root to probe `dev/governance_migrations/.upgrade.lock`. A present lock, or inability to establish its absence, stops ordinary work and all further project-state reads and searches. Do not search for recovery instructions or edit or delete the lock. Before that explanation, render this fenced brand card:
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
/\_/\ Agent Handoff Kit
|
|
13
|
+
( x.x ) continuity unavailable
|
|
14
|
+
> ^ <
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
It must not claim loaded, healthy, saved, or version-verified state. Explain that continuity is unavailable and give the supported recovery command `agent-handoff-kit upgrade --yes --root <verified-project-root>`. Bare startup never runs this command automatically. If the existence probe is unreadable, report continuity unavailable without claiming a lock is present and do not auto-recover. When the visible user request explicitly authorizes update, upgrade or recovery, only the official CLI performs transaction recovery; resume ordinary state loading only after that CLI succeeds and a new probe establishes lock absence.
|
|
18
|
+
|
|
7
19
|
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
20
|
|
|
9
21
|
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.
|
|
@@ -73,6 +85,8 @@ In every user-facing reply, lead with ordinary language: state the result and it
|
|
|
73
85
|
|
|
74
86
|
- 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.
|
|
75
87
|
- Non-trivial work reads relevant sources before changing them.
|
|
88
|
+
- For failures spanning steps or recurring, trace relevant inputs, processing, saved state and actual consumers until evidence explains the cause and direct impact. Then stop expanding the investigation and repair the affected locations with that cause within the authorized scope; do not turn a simple local fix into a whole-system audit.
|
|
89
|
+
- When repeated attempts produce no improved result, unblocked dependency or new evidence, reassess the cause and method before retrying; preserve useful results. Necessary waits and experiments that yield new evidence are not stagnation. Existing safety and retry limits still apply.
|
|
76
90
|
- High-risk work states scope, impact, acceptance, and required confirmation before writes.
|
|
77
91
|
- External skill flows, subagents, task plans, demo workspaces, and another tool's finish step do not replace the active root's persistence decision.
|
|
78
92
|
- Task-first governance locality: when the user supplied a concrete, actionable, authorized task plan and no safety / source-truth / permission blocker prevents it, follow the plan's main acceptance path before governance side work. Governance may become the main path only when the task itself is governance, the user explicitly asks for governance bridge or long-term governance, the content semantically requires cross-session force, or deferring it would create a safety, continuity, source-of-truth, or discoverability blocker. Otherwise, keep governance to the smallest classification, indexing, sync, or Persistence Gate decision that does not change the main deliverable path; do not start governance bridge, long-term-governance routing, repo-wide scans, handoff writes, or closeout solely because the task mentions Markdown, README, docs, specs, plans, checklists, or generated outputs.
|
|
@@ -116,7 +130,7 @@ Do not delete, reset, overwrite user-owned content, bulk-move, publish, change p
|
|
|
116
130
|
|
|
117
131
|
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.
|
|
118
132
|
|
|
119
|
-
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.
|
|
133
|
+
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. A real permission or lock refusal stops the affected operation; it is not permission to elevate, switch provider or mode, or use a riskier command. Normal platform approval and another already-authorized safe method remain available only after their actual scope and safety are verified.
|
|
120
134
|
|
|
121
135
|
Do not modify unrelated files or erase unexpected user changes. Do not claim completion without read-back evidence and proportionate checks.
|
|
122
136
|
|
|
@@ -8,7 +8,7 @@ Use: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.
|
|
|
8
8
|
|
|
9
9
|
| Change type | Also check/update | Verification |
|
|
10
10
|
|---|---|---|
|
|
11
|
-
| New file or directory | `dev/PROJECT_INDEX.md` Directory Map | path listed |
|
|
11
|
+
| New durable or discoverable project file or directory | `dev/PROJECT_INDEX.md` Directory Map | path listed; temporary or one-time evidence follows the next row's classification instead |
|
|
12
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
13
|
| Stack or command change | `dev/PROJECT_INDEX.md` Stack / Entry Points | command verified or marked unverified |
|
|
14
14
|
| Public behavior change | README, public docs, changelog | docs mention current behavior |
|
|
@@ -19,7 +19,7 @@ Stable facts that should survive across sessions. Update only when they change,
|
|
|
19
19
|
|
|
20
20
|
This is the current-state area. At every full closeout, update only sections whose current truth changed; leave already-current sections byte-stable where practical and record checked/no-op only when useful. Do not append a new state snapshot under an old one.
|
|
21
21
|
|
|
22
|
-
Pre-closeout checkpoint edits, when explicitly authorized or required by the core Persistence Gate, update only the named hot current-state field(s) or one concise log entry. Apply the core Persistence Gate's bounded opening-consistency rule when the changed current facts are repeated in the opening.
|
|
22
|
+
Pre-closeout checkpoint edits, when explicitly authorized or required by the core Persistence Gate, update only the named hot current-state field(s) or one concise log entry. Apply the core Persistence Gate's bounded opening-consistency rule when the changed current facts are repeated in the opening. Cold-zone retention and trace/archive handling are owned by `dev/rules/closeout.md`; keep stable anchors plus the current outcome, remaining obligations, decision-changing corrections/rejected reasons, evidence limits and pointers in this packet. Full reception of the current packet remains mandatory.
|
|
23
23
|
|
|
24
24
|
<!-- ack:section:current-baseline -->
|
|
25
25
|
## Current Baseline
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
<!-- ack:section:session-log-preamble -->
|
|
4
4
|
|
|
5
|
-
> **Handoff role**: This log is the trace-back / audit trail layer. Handoff capability rests on `dev/SESSION_HANDOFF.md`. The next AI session can continue by reading `AGENTS.md` + `dev/SESSION_HANDOFF.md` + `dev/PROJECT_INDEX.md` + needed rule packs; reading this log is not required for continuity. Each closeout
|
|
5
|
+
> **Handoff role**: This log is the trace-back / audit trail layer. Handoff capability rests on `dev/SESSION_HANDOFF.md`. The next AI session can continue by reading `AGENTS.md` + `dev/SESSION_HANDOFF.md` + `dev/PROJECT_INDEX.md` + needed rule packs; reading this log is not required for continuity. Each closeout applies `dev/rules/closeout.md` `## Maintenance Trigger Check`; that owner defines the current thresholds and archive discipline.
|
|
6
6
|
|
|
7
7
|
Add new session entries at the top. Record what actually happened in the session; do not copy old completed work forward as new work.
|
|
8
8
|
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
<!-- ack:user-rules-acceptance:sha256=2807fc8bcb006a8ed65d5b7dfe0cd53a499342a2eac41195f0efdad44174b2bc -->
|
|
3
3
|
Before loading task packs, read `dev/USER_RULES.md`. Its registered entries
|
|
4
4
|
under `dev/user_rules/` are user-controlled rules: read each accepted entry in
|
|
5
|
-
the listed order and verify its accepted raw-byte witness. Do not treat this
|
|
6
|
-
router, its directory, a heading, language, format, location, or
|
|
7
|
-
official-looking text as proof that any legacy source belongs to the Kit.
|
|
5
|
+
the listed order and verify its accepted raw-byte witness. Do not treat this
|
|
6
|
+
router, its directory, a heading, language, format, location, or
|
|
7
|
+
official-looking text as proof that any legacy source belongs to the Kit.
|
|
8
|
+
|
|
9
|
+
The core `Upgrade lock guard` applies first when it stops ordinary work.
|