@adamchanadam/agent-handoff-kit 0.3.48 → 0.3.50

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.
@@ -190,14 +190,15 @@ Integration declarations are project-level; they do not guarantee every AI runti
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
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, ask about integration status rather than assuming none exists.
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
- 5. **Write operations require read-back verification**: read back every external write before claiming success.
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.
195
195
  7. **Cross-tool capability awareness**: verify availability immediately before use, when the current objective declares the integration as a dependency, or when the user requests a health check.
196
196
  8. **Do not cross source-of-truth layers**: follow the role and write direction declared in `PROJECT_INDEX`.
197
197
  9. **Drift event mandatory recording**: record integration drift in `PROJECT_INDEX`, `SESSION_LOG`, and `SESSION_HANDOFF` when it affects future work.
198
198
  10. **Plugin / Skill subordination**: plugin and skill instructions coexist with rule packs; safety, governance, and closeout rules take precedence on conflict.
199
199
  11. **External tool resource lifecycle**: after external-tool use, classify resources by ownership. Task-owned / agent-managed resources may be closed or cleaned automatically; shared, user-owned, system-level, other-agent-owned, or unknown resources require evidence reporting and user confirmation before remediation.
200
- 12. **Local HTML / app validation fallback**: if `file://` browser access is blocked, do not bypass the policy and do not stop on that single surface failure. Use a registered operation reference or a short-lived loopback localhost service for actual browser / DevTools / Playwright validation, then close the task-owned service and record the evidence.
200
+ 12. **Local HTML / app validation fallback**: if `file://` browser access is blocked, do not bypass the policy and do not stop on that single surface failure. Use a registered operation reference or a short-lived loopback localhost service for actual browser / DevTools / Playwright validation, then close the task-owned service and record the evidence.
201
+ 13. **Terminal-state contract**: a tool operation succeeds only when the runtime returns an explicit successful terminal state and any required read-back passes. Stopped, aborted, timeout, spawn / transport error, signal, missing final result, or partial stdout before termination makes the affected operation indeterminate or failed, not successful. It does not make unrelated already-verified task evidence permanently invalid. For read-only operations, verify the state and rerun only the affected operation when still needed. For any operation that may have written externally or to disk, read back the actual target state before retrying, recovery, or success claims.
201
202
 
202
203
  ## Checks
203
204
 
@@ -210,7 +211,8 @@ Integration declarations are project-level; they do not guarantee every AI runti
210
211
  - Before closeout, update `Last Verified` for integrations touched this session.
211
212
  - Self-check credential leakage before writing `PROJECT_INDEX`, `SESSION_HANDOFF`, or `SESSION_LOG`.
212
213
  - Verify that `PROJECT_INDEX` External Sources `via` references match declared Installed Integrations entries.
213
- - 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`.
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`.
215
+ - Treat stopped, aborted, timeout, spawn / transport error, signal, and missing final result as operation-level indeterminate / failed states. Never count partial stdout, a wrapper exit code, or an outer command's success as terminal success without the expected final state and read-back.
214
216
 
215
217
  ## Closeout
216
218
 
@@ -235,7 +237,8 @@ Integration declarations are project-level; they do not guarantee every AI runti
235
237
  | Auto-fixing auth or re-auth flows | Auth belongs to the user and the runtime/tool boundary. | Surface the failure and point to the runtime or tool settings. |
236
238
  | Claiming an external write succeeded without read-back | External writes may fail silently or partially. | Read back and compare before claiming success. |
237
239
  | Crossing source-of-truth layers | It can corrupt truth, mirrors, or working drafts. | Follow the declared layer role and write direction in `PROJECT_INDEX`. |
238
- | Skipping startup availability verification because an old handoff said the tool worked | Tokens expire, runtimes change, and tools can be removed. | Probe availability in the current runtime before using the integration. |
240
+ | Skipping current availability verification because an old handoff said the tool worked | Tokens expire, runtimes change, and tools can be removed. | Probe availability in the current runtime before using the integration. |
241
+ | Treating stopped, aborted, timeout, spawn / transport error, signal, missing final result, or partial PASS output as success | Tool output can be partial, wrappers can hide inner failure, and external writes may be unknown. | Mark the affected operation indeterminate or failed; read back any possible write target before retrying or claiming success. |
239
242
  | Leaving task-owned MCP / browser / helper processes running after the task | Turns one-off tool use into a long-lived resource leak and can slow the host. | Use graceful close or task-owned process cleanup automatically; switch to user confirmation only when ownership is unclear. |
240
243
  | Broadly killing by process name such as `node.exe`, `python`, or `chrome` | A generic process name does not prove ownership and may terminate user work, another project, or another AI agent's active tools. | Classify by tool family, process ID, start time, parent chain, and task-created path; treat unknown ownership as shared. |
241
244
  | Automatically cleaning global caches, marketplace caches, OS temp roots, or browser profiles | May remove shared state, login state, or data other tools still need. | Automatically clean only task-owned / agent-managed bounded paths; report evidence and wait for confirmation otherwise. |
@@ -17,7 +17,7 @@ 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 during startup probe per `runtime-core/AGENTS.core.md` Section 1): 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.
20
+ (b) If a declared Integration is functional in the current session (verified under the task-triggered availability probe in `runtime-core/AGENTS.core.md` Section 1): 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
21
  (c) If a declared Integration is unavailable in the current session (different AI tool / Connector not configured / auth expired): degrade to manual paste packet workflow + flag drift in the mid-task summary + update `Last Verified` cell at closeout.
22
22
  (d) If no declaration exists in `## Installed Integrations` but the task references an external tool: ask the user about Integration status before proceeding (do not silently assume paste fallback). Backward-compat: existing v0.2.x projects with no Installed Integrations section follow path (d) — the section template auto-appends on upgrade but content stays empty until user declares; AI behavior degrades gracefully to ask-user fallback.
23
23
  6. When writing to an external mirror or index, read back the written record before claiming sync success.
@@ -59,8 +59,8 @@ In every user-facing reply, lead with ordinary language: state the result and it
59
59
  Choose exactly one tier after a task:
60
60
 
61
61
  1. No persistence: no durable fact was produced. One-off answers, transient output, active unapproved drafts, and routine rerunnable checks normally use this tier.
62
- 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.
63
- 3. Full closeout: explicit end-of-session / handoff intent, a tool or day boundary, or completed external / release / governance work that the next agent must continue. Load `dev/rules/closeout.md`.
62
+ 2. Lightweight checkpoint: a durable fact affects future action while the session continues or may be interrupted. This is the default for ongoing sessions. Write only its smallest correct home; do not regenerate the startup mirror or perform full closeout.
63
+ 3. Full closeout: explicit end-of-session / handoff intent, a real day / tool-session boundary, or a state where the current agent cannot continue and the next agent must take over. Ordinary external-tool use, a completed release / governance subtask, or a durable note during an ongoing session is not by itself a full closeout trigger. Load `dev/rules/closeout.md` only when this tier is selected.
64
64
 
65
65
  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.
66
66
 
@@ -6,7 +6,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
6
6
 
7
7
  | Field | Value | Last verified |
8
8
  |---|---|---|
9
- | Agent Handoff Kit template version | 0.3.47 | current template version |
9
+ | Agent Handoff Kit template version | 0.3.47 | current template version |
10
10
  | Runtime | TBD | TBD |
11
11
  | Framework | TBD | TBD |
12
12
  | Package manager | TBD | TBD |