@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
|
@@ -14126,6 +14126,181 @@
|
|
|
14126
14126
|
"canonicalSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef"
|
|
14127
14127
|
}
|
|
14128
14128
|
}
|
|
14129
|
+
},
|
|
14130
|
+
"0.4.1": {
|
|
14131
|
+
"source": {
|
|
14132
|
+
"npm": {
|
|
14133
|
+
"spec": "@adamchanadam/agent-handoff-kit@0.4.1",
|
|
14134
|
+
"shasum": "5e094750d21fdd7b583a8acda4e527f9c0894daf",
|
|
14135
|
+
"integrity": "sha512-bOJ2FCMH91IdyvfPKo/Eq/BBYauRl+zbXv3lvWcRHfCME76D/oVuInTm480FBPtVqjXS8ynlj/WNT0IIa5grUA==",
|
|
14136
|
+
"entryCount": 52,
|
|
14137
|
+
"gitHead": null
|
|
14138
|
+
},
|
|
14139
|
+
"git": {
|
|
14140
|
+
"tag": "v0.4.1",
|
|
14141
|
+
"directObject": "1f1738a3caa0fe6323dfe4a3280b5946d10b5eb2",
|
|
14142
|
+
"peeledCommit": "58683c34855d179a5fa86b2d99ff435b529aa4c9",
|
|
14143
|
+
"commit": "58683c34855d179a5fa86b2d99ff435b529aa4c9"
|
|
14144
|
+
},
|
|
14145
|
+
"githubRelease": {
|
|
14146
|
+
"tag": "v0.4.1",
|
|
14147
|
+
"publishedAt": "2026-10-03T13:23:24Z"
|
|
14148
|
+
},
|
|
14149
|
+
"sourceDivergence": {
|
|
14150
|
+
"status": "npm-gitHead-unavailable",
|
|
14151
|
+
"npmGitHead": null,
|
|
14152
|
+
"remoteTagCommit": "58683c34855d179a5fa86b2d99ff435b529aa4c9"
|
|
14153
|
+
}
|
|
14154
|
+
},
|
|
14155
|
+
"manifest": {
|
|
14156
|
+
"AGENTS.md": {
|
|
14157
|
+
"state": "present",
|
|
14158
|
+
"contentId": "b5d9456c0df9a07ece1de510ae86cd49ddc17cee890c72db614d8cb4d05811ea",
|
|
14159
|
+
"rawSha256": "debb0ff0ec7798380d7e6cea86283bbea5b1e35d90ab8e2e5646a00b10b9d9ef",
|
|
14160
|
+
"normalizedSha256": "65af6bda8d1bceb78702e9c9f71131ff96bccd29e0311432e2376721da36755f",
|
|
14161
|
+
"canonicalSha256": "65af6bda8d1bceb78702e9c9f71131ff96bccd29e0311432e2376721da36755f"
|
|
14162
|
+
},
|
|
14163
|
+
"CLAUDE.md": {
|
|
14164
|
+
"state": "present",
|
|
14165
|
+
"contentId": "7a2cf08a1171762ebcb53f43036a2170655379416945258b9c85d4b189ecaecf",
|
|
14166
|
+
"rawSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad",
|
|
14167
|
+
"normalizedSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad",
|
|
14168
|
+
"canonicalSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad"
|
|
14169
|
+
},
|
|
14170
|
+
"GEMINI.md": {
|
|
14171
|
+
"state": "present",
|
|
14172
|
+
"contentId": "36da47034bb2ce6c760ddbbbbd49dccc1d17665dbb18bec56ffa3b26bac1c135",
|
|
14173
|
+
"rawSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986",
|
|
14174
|
+
"normalizedSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986",
|
|
14175
|
+
"canonicalSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986"
|
|
14176
|
+
},
|
|
14177
|
+
"START_NEXT_SESSION_PROMPT.txt": {
|
|
14178
|
+
"state": "present",
|
|
14179
|
+
"contentId": "9902b70a395688d6602b34f9e8085b32b5538e72c9009e28b4258e1fd30b77cc",
|
|
14180
|
+
"rawSha256": "c985898d57b7095d9f4626eebbf6c02495b7b19e8ec9c2cf7c4570cbc0d8d828",
|
|
14181
|
+
"normalizedSha256": "c985898d57b7095d9f4626eebbf6c02495b7b19e8ec9c2cf7c4570cbc0d8d828",
|
|
14182
|
+
"canonicalSha256": "9896feb18fe71a4f3500e2d89cea6991ca1788aebc6c6ead9848f5551750a1c0"
|
|
14183
|
+
},
|
|
14184
|
+
"dev/SESSION_HANDOFF.md": {
|
|
14185
|
+
"state": "present",
|
|
14186
|
+
"contentId": "dcb8900b5c4a5a136be2cc786cfff929cc7669ea51dc2e1af9f5996b12222678",
|
|
14187
|
+
"rawSha256": "283479f3dc0422130abf2a9fabd6ce6934c30395100669bdc78aa7a2c76d7b1a",
|
|
14188
|
+
"normalizedSha256": "283479f3dc0422130abf2a9fabd6ce6934c30395100669bdc78aa7a2c76d7b1a",
|
|
14189
|
+
"canonicalSha256": "7ceb3efb4e3b12ead32af121eeb6dc2c800a4677f028121966368beb26ea4424"
|
|
14190
|
+
},
|
|
14191
|
+
"dev/SESSION_LOG.md": {
|
|
14192
|
+
"state": "present",
|
|
14193
|
+
"contentId": "43d31885fda4f399b8b8c78badb70cda4baffd4749316a2c14444d8bd97acd08",
|
|
14194
|
+
"rawSha256": "e60f41c7a5ab350877ee400fcbdad879f15f3b34d920ff37ce1bd26934912973",
|
|
14195
|
+
"normalizedSha256": "e60f41c7a5ab350877ee400fcbdad879f15f3b34d920ff37ce1bd26934912973",
|
|
14196
|
+
"canonicalSha256": "e60f41c7a5ab350877ee400fcbdad879f15f3b34d920ff37ce1bd26934912973"
|
|
14197
|
+
},
|
|
14198
|
+
"dev/PROJECT_INDEX.md": {
|
|
14199
|
+
"state": "present",
|
|
14200
|
+
"contentId": "c4c0db7c6e7a19796cd7ca1ed2a666461aa49a0b0d087a99deca43853ffdb468",
|
|
14201
|
+
"rawSha256": "8a64665d19ee9b4bf33b073507ddecc1afd31eafdb88b53536a4b13f9028dd3f",
|
|
14202
|
+
"normalizedSha256": "f8599dddc2f38ac28ab35c0b05f67c246279ed29817bae544515b648b9741f28",
|
|
14203
|
+
"canonicalSha256": "d13af58d29f15710e54469e929847a611a066f286198feeebada13192404141c"
|
|
14204
|
+
},
|
|
14205
|
+
"dev/DOC_SYNC_REGISTRY.md": {
|
|
14206
|
+
"state": "present",
|
|
14207
|
+
"contentId": "f6545b524dc440d3563041e04a05caff4229863f6cae2a39127f85a29a120249",
|
|
14208
|
+
"rawSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6",
|
|
14209
|
+
"normalizedSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6",
|
|
14210
|
+
"canonicalSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6"
|
|
14211
|
+
},
|
|
14212
|
+
"dev/RULE_PACKS.md": {
|
|
14213
|
+
"state": "present",
|
|
14214
|
+
"contentId": "1b91985b9c6460b7bf4293cc6119097df9b426c3a46199a0a4f1de1712d02faa",
|
|
14215
|
+
"rawSha256": "383842f3d2f995a6f0917bb4a7bc6bfa5fd6e3c33ec8aa2cd073ce1695812df4",
|
|
14216
|
+
"normalizedSha256": "383842f3d2f995a6f0917bb4a7bc6bfa5fd6e3c33ec8aa2cd073ce1695812df4",
|
|
14217
|
+
"canonicalSha256": "383842f3d2f995a6f0917bb4a7bc6bfa5fd6e3c33ec8aa2cd073ce1695812df4"
|
|
14218
|
+
},
|
|
14219
|
+
"dev/PROJECT_DECISIONS.md": {
|
|
14220
|
+
"state": "present",
|
|
14221
|
+
"contentId": "3aae993bd5b85bf6b1d1d458f1bcf82c7d3105c843f053ffa13553bb5931b8c4",
|
|
14222
|
+
"rawSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e",
|
|
14223
|
+
"normalizedSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e",
|
|
14224
|
+
"canonicalSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e"
|
|
14225
|
+
},
|
|
14226
|
+
"dev/rules/safety.md": {
|
|
14227
|
+
"state": "present",
|
|
14228
|
+
"contentId": "dd6bcf74722d038f76d202e2044a6583a6e6ad107fbb010520e513eec799ff4a",
|
|
14229
|
+
"rawSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0",
|
|
14230
|
+
"normalizedSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0",
|
|
14231
|
+
"canonicalSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0"
|
|
14232
|
+
},
|
|
14233
|
+
"dev/rules/coding.md": {
|
|
14234
|
+
"state": "present",
|
|
14235
|
+
"contentId": "1c6deb9a5a281c13e97b0ac96079e9e1beccbd1ff106186e7a6ac78c0eeb75c2",
|
|
14236
|
+
"rawSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4",
|
|
14237
|
+
"normalizedSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4",
|
|
14238
|
+
"canonicalSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4"
|
|
14239
|
+
},
|
|
14240
|
+
"dev/rules/writing.md": {
|
|
14241
|
+
"state": "present",
|
|
14242
|
+
"contentId": "ceee5412520ba860e6b40de46bb164e2ce3919d2197d5fadb926198eb7dddd3b",
|
|
14243
|
+
"rawSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593",
|
|
14244
|
+
"normalizedSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593",
|
|
14245
|
+
"canonicalSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593"
|
|
14246
|
+
},
|
|
14247
|
+
"dev/rules/research.md": {
|
|
14248
|
+
"state": "present",
|
|
14249
|
+
"contentId": "4414f9c82c6d04ad49d7446f4b0740055242f425ef5b00391d9c8c78c96c0f66",
|
|
14250
|
+
"rawSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104",
|
|
14251
|
+
"normalizedSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104",
|
|
14252
|
+
"canonicalSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104"
|
|
14253
|
+
},
|
|
14254
|
+
"dev/rules/agent-governance.md": {
|
|
14255
|
+
"state": "present",
|
|
14256
|
+
"contentId": "5dcd857a4b7e3416bc1c454ba42d0683afa87d414232ec4bd9ebc4665f55d4a1",
|
|
14257
|
+
"rawSha256": "b36a1782d81476545769727e002248e2e6bbfd507e6a66941cc6c3d16ee60a16",
|
|
14258
|
+
"normalizedSha256": "b36a1782d81476545769727e002248e2e6bbfd507e6a66941cc6c3d16ee60a16",
|
|
14259
|
+
"canonicalSha256": "b36a1782d81476545769727e002248e2e6bbfd507e6a66941cc6c3d16ee60a16"
|
|
14260
|
+
},
|
|
14261
|
+
"dev/rules/release.md": {
|
|
14262
|
+
"state": "present",
|
|
14263
|
+
"contentId": "b0a0c9dea88016185f4093f9be4ce3c0e29904222e21dd1fa1735fcc1bb7e744",
|
|
14264
|
+
"rawSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7",
|
|
14265
|
+
"normalizedSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7",
|
|
14266
|
+
"canonicalSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7"
|
|
14267
|
+
},
|
|
14268
|
+
"dev/rules/knowledge.md": {
|
|
14269
|
+
"state": "present",
|
|
14270
|
+
"contentId": "e6f5795c7ebaba7b05f04d971b2942b5a0394a3babb44f64a1cc591c9a08cb86",
|
|
14271
|
+
"rawSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c",
|
|
14272
|
+
"normalizedSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c",
|
|
14273
|
+
"canonicalSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c"
|
|
14274
|
+
},
|
|
14275
|
+
"dev/rules/communication.md": {
|
|
14276
|
+
"state": "present",
|
|
14277
|
+
"contentId": "34fd0034cbc75dad43f789b86a414763f01916dda4d59876db9c4d8d92ae6a87",
|
|
14278
|
+
"rawSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591",
|
|
14279
|
+
"normalizedSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591",
|
|
14280
|
+
"canonicalSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591"
|
|
14281
|
+
},
|
|
14282
|
+
"dev/rules/closeout.md": {
|
|
14283
|
+
"state": "present",
|
|
14284
|
+
"contentId": "6d79f54352feaf21315cbdf329566d05b5c52117cf330d4dc611acf5ad0ae363",
|
|
14285
|
+
"rawSha256": "434f3365e2f31ee9d0a639d50017763354bbdd834af757b2da7351eaed55ef5c",
|
|
14286
|
+
"normalizedSha256": "434f3365e2f31ee9d0a639d50017763354bbdd834af757b2da7351eaed55ef5c",
|
|
14287
|
+
"canonicalSha256": "434f3365e2f31ee9d0a639d50017763354bbdd834af757b2da7351eaed55ef5c"
|
|
14288
|
+
},
|
|
14289
|
+
"dev/rules/onboarding.md": {
|
|
14290
|
+
"state": "present",
|
|
14291
|
+
"contentId": "6967a95f2256bc7962cd7f0b2b63249a2537979fe0d8bafd49ef620db873cae4",
|
|
14292
|
+
"rawSha256": "0c416732ae67c7dd3bfd2f27fbb763a940e6248ce8a23e42d8b897db8380d9ce",
|
|
14293
|
+
"normalizedSha256": "0c416732ae67c7dd3bfd2f27fbb763a940e6248ce8a23e42d8b897db8380d9ce",
|
|
14294
|
+
"canonicalSha256": "0c416732ae67c7dd3bfd2f27fbb763a940e6248ce8a23e42d8b897db8380d9ce"
|
|
14295
|
+
},
|
|
14296
|
+
"dev/rules/integrations.md": {
|
|
14297
|
+
"state": "present",
|
|
14298
|
+
"contentId": "a8fc1099da28f511bf9fed5eaf629ca10fb409299b0aed4d233a45fc7701f284",
|
|
14299
|
+
"rawSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef",
|
|
14300
|
+
"normalizedSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef",
|
|
14301
|
+
"canonicalSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef"
|
|
14302
|
+
}
|
|
14303
|
+
}
|
|
14129
14304
|
}
|
|
14130
14305
|
},
|
|
14131
14306
|
"contents": {
|
|
@@ -15123,6 +15298,11 @@
|
|
|
15123
15298
|
"targetRel": "dev/rules/closeout.md",
|
|
15124
15299
|
"canonicalSha256": "434f3365e2f31ee9d0a639d50017763354bbdd834af757b2da7351eaed55ef5c",
|
|
15125
15300
|
"text": "# Closeout Pack\n\n## Scope\n\nThis pack is the single detailed contract for full Agent Handoff Kit closeout. Load it only for clear end-of-session or handoff intent. It does not authorize Git, release, publish, deployment, deletion, permission, or cleanup actions.\n\n## Required Reads\n\nRead the current `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, and `dev/DOC_SYNC_REGISTRY.md`. Read `dev/PROJECT_DECISIONS.md`, integration rules, or another pack only when its closeout trigger or the session's actual work requires it.\n\n## Write Contract\n\nUse Kit markers as machine boundaries: `ack:section:*`, `ack:field:*`, `ack:log-entry:start/end`, and managed-core BEGIN/END. Human headings may be localized; markers may not be removed or translated.\n\n- Current state, objective, recommended next action, active risk, blocker, required reading, workspace identity, and sync status belong in `dev/SESSION_HANDOFF.md`.\n- When saving meaningful work changes, maintain the handoff's concise `Work Items` table using its declared fields, and keep project-wide name/goal in `PROJECT_INDEX` `Project`. Add the table/section to older projects only at an authorized state save when useful. Reconcile changed statuses against the evidence; do not duplicate full reports, rewrite old history, or create per-terminal-step records for the dashboard. Read-only dashboard viewing never triggers these writes.\n- Chronological work and evidence disposition belong in `dev/SESSION_LOG.md`.\n- File / command / source / capability maps belong in `dev/PROJECT_INDEX.md`.\n- Recurring sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`.\n- Long-term evolution, architectural rationale, and accumulated learning belong in `dev/PROJECT_DECISIONS.md` when triggered.\n- Reusable procedures belong in the relevant pack, registered reference, or QA check.\n- `START_NEXT_SESSION_PROMPT.txt` is generated only from the handoff opening-message block.\n\nDo not copy the full opening message into `dev/SESSION_LOG.md` or any third current governance file. The log records whether the mirror was verified no-op or regenerated and verified, plus an evidence reference when useful.\n\n## Full Closeout\n\nFull closeout is differential and write-minimal. Update only fields whose current truth changed. For unchanged state, preserve bytes where practical and record checked/no-op only when it helps the next agent. Reuse a completed task check only when its recorded root, task input, tool identity, commit / artifact identity, and required file hashes still match the current state. Do not rerun task QA that is already bound to unchanged identity. Do rerun checks affected by closeout writes, gates that are incomplete or indeterminate, closeout-specific checks, and the final `closeout-status` read-back. If a closeout attempt is interrupted, stopped, aborted, times out, or hits a spawn / transport error, resume at the first incomplete or indeterminate gate; do not restart from the beginning unless the root, input, tool identity, commit, artifact, or relevant hash changed.\n\nHandoff cold zones are historical / evidence sections, old validation records, completed-work narratives, and unchanged durable anchors. Do not rewrite, reword, reorder, or refresh cold zones for ceremony or style. Change them only when the closeout directly proves their current meaning is false or the section itself is the named target of the reconciliation; otherwise preserve cold-zone bytes where practical and update only hot current-state fields.\n\n1. Reconcile `dev/SESSION_HANDOFF.md`; never append a new current-state snapshot beneath an old one. Verify durable anchors, then update only changed closeout-reconciled fields or sections; leave already-current sections unchanged instead of rewriting them for ceremony.\n2. Reconcile lifecycle state across `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. Completed or verified work cannot remain unresolved unless explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with its missing evidence or trigger.\n The bundled doctor is a mechanical floor for required lifecycle markers and readable sections only. `agent-handoff-kit closeout-status` checks explicit lifecycle declarations and same-scope textual contradictions; it does not prove natural-language semantic consistency. When it blocks, inspect its first `Resolved [...]` / `Carry-forward [...]` pair against the actual evidence: completion of one action does not complete another acceptance scope, and a preserved limitation is not a completion claim. Repair a real contradiction in its owning handoff section. If truthful, distinct scopes are misclassified, preserve the facts, report the checker defect and stop wording retries; do not add a reclassification prefix, invent a trigger, erase a limitation or broaden governance just to pass. A blocked result remains blocked until verified repair. Read all five sections as a whole before marking the lifecycle field resolved. For governance, release, or another project-defined high-risk completion, use the project's independent semantic review gate in addition to `closeout-status`.\n3. Make `Next Priorities` name one recommended next action and a short reason unless blocked or a real user decision is required.\n4. Complete the persistence-routing, handoff-sufficiency, `Closeout outcome`, and `Project-required persistence` fields. Apply the packet-only reconstruction check below before answering handoff sufficiency. The next agent must be able to continue from `AGENTS.md`, the handoff, the project index when needed, and routed packs without searching old log history. `complete` is allowed only when all required writes/read-backs and any project-required persistence succeeded; use `not_required` only when that persistence is genuinely not required. If a required commit, push, release record, or equivalent persistence is blocked or not authorized, set both fields to `blocked` with the exact boundary.\n5. Add one concise log entry for work actually performed. Record evidence disposition and the prompt-mirror verification result; omit the full opening message by design.\n6. Update the project index and sync registry only when their owned maps or obligations changed. Record each applicable sync target as `confirmed`, `unverified`, `pending`, `blocked`, or `not_applicable`.\n7. Run `agent-handoff-kit workspace-health --root <project root>` or equivalent read-only Git probes, then record only the last-verified root, Git root, branch, commit, worktrees / parallel workspaces, uncommitted changes, and unresolved drift. Do not clean or change them without separate authorization. Do not treat `dev/PROJECT_INDEX.md` or old handoff prose as the live worktree truth.\n8. If the session used external tools or helper processes, apply the integrations and safety ownership rules. Close only task-owned resources. Retain shared, user-owned, other-agent-owned, system, or ambiguous resources unless separately authorized; state visibility limits.\n9. Run the short maintenance trigger check below and record its result in the log.\n10. Mark first-use guidance `consumed` after the first successfully completed task or first full closeout. Upgrade must never reset `consumed` or `not_applicable` to `eligible`.\n11. Verify `START_NEXT_SESSION_PROMPT.txt` against the sole fenced handoff opening-message block first. Regenerate it only when normalized content differs, then run the project's fixed prompt-mirror checker or perform an equivalent anchored read-back that verifies marker, heading, fence, full-copy uniqueness, and normalized content equality.\n12. Run available project-specific closeout checks. Do not run a separate bundled `doctor`: the `closeout-status` command below performs the one required fresh doctor read-back. Do not treat an external update-check failure as local closeout failure. Fix state or mirror failures before claiming handoff ready.\n13. Run `agent-handoff-kit closeout-status --root <project root>` after the handoff and prompt read-back. It performs the one required fresh doctor read-back plus a read-only workspace-health comparison against the handoff snapshot, and its output is the only final card source: copy its status faithfully. A nonzero result means the closeout is blocked; do not replace it with a success summary.\n\n## Packet-Only Reconstruction Check\n\nBefore closing out, reconstruct the next task using only the handoff, without chat memory, old logs or opening linked sources. Identify the parent outcome and consumer, the current step's relation to it, the exact resume point, remaining step/parent acceptance, and required sources with revision/freshness, reading scope/depth and unread gaps. Also recover decision-changing user corrections, reasons for accepted/rejected approaches, reusable artifacts with their evidence limits, every remaining consequential obligation and its downstream use, and permission/stop boundaries. Cite the owning handoff sections in `Reconstruction evidence`; do not create a second task summary. Then compare that reconstruction against the user's actual request and the relevant sources read this session. Missing, contradictory or assumed critical facts must be repaired in their existing handoff sections or explicitly recorded as blockers with the next clarification/read needed. Do not answer yes on labels or a successful CLI card alone: the CLI checks the recorded answer and evidence presence, not the truth of this reconstruction.\n\nCheck whether a reader could repeat a rejected attempt, redo accepted work, omit an obligation, act on obsolete instructions, or choose a plausible but wrong next action while still agreeing with the packet's headline. If so, preserve the missing decision-changing fact in its existing owning section, not merely in a linked historical log. Keep the packet sufficient and proportionate; do not paste the whole chat or silently discard important facts to fit an output limit. Transport truncation is handled by the core reception checkpoint, not by weakening the task.\n\nCloseout verifies this session's saved packet. It cannot certify that a future reader received or understood it. Do not describe `closeout-status: complete` as successful future-session reception; the next agent must pass the core Handoff reception and recovery checkpoint independently.\n\nKeep one `Answer:` line (`yes`, `no` or `unknown`, with optional explanation) and one `Reconstruction evidence:` line inside the marked sufficiency section. An affirmative answer requires concrete section references; keep `next-ai-can-continue` consistent. For an older handoff, add missing facts to its existing sections at this authorized closeout; upgrade must preserve user state and must not invent reconstruction evidence. Missing or negative answers, placeholder evidence and duplicate fields block `closeout-status` without changing project files.\n\nUse only the depth needed to resume safely. A standalone task needs no invented parent tree; state that it is the whole task. Finishing a child does not complete its parent or authorize another step. Keep the next consequential action bounded by its input, output and acceptance; do not enumerate every future microstep. Keep decision-relevant terms and identifiers faithful; when a translation could change their meaning, retain the original term alongside it. Reading coverage is previous-session evidence, never permission for the next agent to skip required fresh source reads. Honest blocked-work handoff can be sufficient when the missing fact, impact and safe next action are explicit.\n\n## Maintenance Trigger Check\n\nEvery full closeout runs this short check; full maintenance runs only when triggered.\n\n- SESSION_LOG: trigger when the main log reaches at least 11 entries, exceeds 1500 lines, or the 10-closeout backstop is due. Keep recent safety-buffer entries; collapse only content already absorbed by an authoritative home. Archive older raw entries to `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` and maintain `INDEX.md`. Port unique narrative before collapsing it.\n- PROJECT_DECISIONS: trigger when a decisions-like handoff section has at least 30 entries; retain the newest 8–22 in the hot tier and move older decisions into the decisions archive. Also write substantive task evolution, a multi-option architectural choice with rationale, or a cross-session learning when observed.\n- Backstop: every 10 closeouts, run the full long-term maintenance pass even when no semantic trigger is obvious. If the count cannot be determined confidently at the boundary, treat the backstop as due.\n\nIf no trigger applies, record one no-op reason. Handoff carries continuity; log and project decisions carry trace and long-term narrative.\n\n## Opening Message And Card\n\nThe handoff opening-message block is authoritative. It must name the absolute root, route the agent through `AGENTS.md` and the handoff, state the current objective and boundary, and avoid instructing the next agent to redo completed work. It must not require SESSION_LOG as an ordinary startup read.\n\nUse `agent-handoff-kit closeout-status --root <project root>` after the required read-backs. It renders the verified version when available and otherwise `version unverified`; never print the literal placeholder `v<version>`, hand-compose a substitute card, or use `handoff saved` unless the command reports `status: complete`.\n\n```text\n /\\_/\\ Agent Handoff Kit v<version>\n ( -.- ) handoff saved\n > ^ <\n\nstatus: complete\n✅ Done: <completed summary>\n🔎 QC: <validation summary>\n📌 Handoff: opening message ready\n⚠️ Boundary: <important boundary or none>\n```\n\nFor `status: blocked`, the command instead says `handoff blocked`; retain that status, blocker reason, and human explanation: `這不是失敗;只是還有事未保存、未提交、未驗證或需要處理。先照 Blocker 行處理,不要把本輪當作已完成交接。` Then give the short local-root entry `Start Agent Handoff` / `開工` and the path-bearing fallback for an agent not yet pointed at the root. Do not hand-compose a third stateful prompt in the final response.\n\n## Stop Conditions\n\nDo not claim closeout complete when any required write or read-back failed, lifecycle state conflicts remain, the mirror is stale or duplicated, the root is uncertain, mandatory sync is unclassified, `closeout-status` is nonzero, or required Git persistence was explicitly part of the project's closeout contract but did not succeed. State the exact blocker and leave the project in an honest resumable state.\n"
|
|
15301
|
+
},
|
|
15302
|
+
"b5d9456c0df9a07ece1de510ae86cd49ddc17cee890c72db614d8cb4d05811ea": {
|
|
15303
|
+
"targetRel": "AGENTS.md",
|
|
15304
|
+
"canonicalSha256": "65af6bda8d1bceb78702e9c9f71131ff96bccd29e0311432e2376721da36755f",
|
|
15305
|
+
"text": "<!-- BEGIN Agent Handoff Kit managed core -->\n# Agent Handoff Kit Core Runtime\n\nThis is the small always-read contract. Detailed task and closeout procedures live in routed packs.\n\n## 1. Intent And Startup\n\nClassify 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.\n\nDo 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.\n\nWhen resuming, recover the parent outcome, current step, resume point, remaining acceptance and source coverage from the fully received handoff under the checkpoint below. Preserve decision-changing user corrections, rejected approaches and their reasons, reusable work and permission boundaries. Surface missing critical context in the startup warning and recommend the specific clarification/read; do not infer parent completion from a finished child or treat previous-session reading as your own. Bare startup remains status-only, with no extra source reads or writes.\n\nRoute intent in this order:\n\n1. Clear closeout intent routes directly to `dev/rules/closeout.md`.\n2. Clear continuity intent such as \"開工\", \"Start Agent Handoff\", \"開始接力\", or \"continue handoff\" resumes the minimum current state from the handoff. A plain continuity message with no same-message task or explicit long-run instruction authorizes only that recovery, the display-only current-thread naming checkpoint when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out wording such as \"unless you object I will start\". First-use exception: when `dev/SESSION_HANDOFF.md` says `First-use guidance state: eligible`, the active objective is empty / `TBD`, and there is no same-message concrete task, load `dev/rules/onboarding.md` and include a short first-use welcome plus the most relevant guided choices in the same response instead of ending status-only. A concrete objective found only in loaded state is not authority to complete it. A same-message task may begin normally. An explicit instruction such as \"開工,繼續做到下一個 blocker\" or \"開工,繼續完成目前目標\" may continue under the normal task and safety rules.\n3. A direct ordinary task begins without a startup card or onboarding ceremony. Read only the sources and packs required by that task.\n4. Explicit guidance requests such as \"I'm new\", \"teach me\", \"help me start\", \"新手\", \"教我用\", or \"點開始\" may load `dev/rules/onboarding.md`. A fresh install marks first-use guidance as `eligible`, so the first unresolved startup must enter onboarding; upgrade must not reset `consumed` or `not_applicable` back to `eligible`. A short message in a non-eligible root 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.\n\nTreat 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.\n\n### Handoff reception and recovery checkpoint\n\nBefore claiming `loaded`, `resumed` or `continuity ready`, complete both gates below. A successful closeout, read command, exit code, digest, section list or summary does not establish reception or understanding.\n\n1. **Receive the whole packet.** Read all of `dev/SESSION_HANDOFF.md`, including its middle and end, from one unchanged file version. A full-file command is only a request: inspect the actual tool result. If output is truncated, omitted, paginated or uncertain, use smaller bounded reads and track contiguous ranges from the start through EOF, with no gaps or mixed versions. Check the entire returned body, not just its header/footer; a tool can retain both ends while omitting the middle. Reread any uncertain range. If the file changes during reading, restart coverage for the new version. Native file tools are valid; compare file identity before/after the read sequence. When an already-available local Kit CLI supports it, `handoff-read --root <root>` offers bounded Unicode ranges; continue with its `nextOffset` as `--offset` and the same `--sha256`, reducing `--max-chars` on truncation. Verify its canonical `root` matches the intended workspace; a root alias is not permission to read an unexpected location. Links below that root are rejected. This helper serves content only. Do not download, install, probe integrations or write a receipt for bare startup. Missing/unreadable content stays incomplete.\n2. **Recover the work.** From that packet, reconcile the user's outcome and consumer, current task's relation to it, completed work and reusable evidence, decision reasons and rejected approaches, remaining obligations/acceptance, exact bounded next action, required fresh sources, and authorization/stop boundaries. Preserve corrections and distinguish historical state from current truth. Use existing section locations as internal evidence; do not create another summary file or dump the packet into the reply. Missing or contradictory facts that prevent safe recovery make the checkpoint incomplete; identify their effect and the smallest clarification/read. A packet that honestly describes blocked work can still be sufficient: show its dependency blocker without inventing completion or requiring every linked source at startup. Eligible first-use TBD state still routes to onboarding; it is not a failed task handoff.\n\nUntil both gates pass, replace the card's `continuity ready` with `continuity incomplete`, use `incomplete` for its handoff status, and name the unread/conflicting scope. Do not begin dependent task work. Complete safe same-file supplementary reads before giving up; elapsed time or a green CLI is not acceptance. Full reception does not prove every historical fact or linked source; follow the normal required-reading gate before an authorized action. Bare startup still ends after its card. With explicit continuation, check the recovered input, output, downstream use and acceptance against the current request, read the necessary sources, and continue within the authorized scope, including multiple steps when completion or the next blocker was explicitly requested; neither the packet nor this checkpoint grants new permissions. These gates also apply after interrupted reads or context compaction when coverage cannot be recovered from actual evidence.\n\n### Current-thread naming checkpoint\n\nDuring explicit continuity startup, naming is a required presentation checkpoint when safe current-thread title control is available, not an optional task. After the minimum authorized startup reads, derive the current objective, boundary and recommended next action; resolve this checkpoint before emitting the final startup card or beginning any same-message authorized task work. Do not defer the tool call until after the final response or until the task is finished. If interrupted before the checkpoint resolves, handle it on the next user-authorized turn using current facts; do not schedule a background rename.\n\nUse `<project name>|<primary action>` from already-loaded facts: the concrete current user task first, then an unresolved current objective, then a concrete recommended action. Do not revive a completed child task from historical handoff text. When the project is known but no concrete action remains, use the project name alone; do not leave a new task named `開工` merely because the previous work is complete. If the project name is unknown, skip without guessing or extra source reads. `Start Agent Handoff`, `開工`, `開始交接工作` and `開始工作交接` are not primary actions. Titles must not contain progress, completion, status, task/session IDs, absolute paths, secrets or unverified facts.\n\nUse the current runtime's exposed tool schema. If a safe current-thread title tool is already available, call it directly; otherwise use a bounded runtime tool-discovery mechanism once with a narrow title/rename/current-thread query, when available. Never invent a tool name or require discovery when the tool is already exposed. Current-title readback is useful when available, but is not required when the tool safely targets the calling/current thread. Replace a generic or stale title; keep an informative title when readback proves it is already relevant, and preserve an explicitly user-chosen title unless the user asks to change it. When the current title cannot be read, use one safe current-thread set call with the derived title. Omit the target identifier only when the schema documents current-thread targeting; otherwise require a verified current-thread identifier. Do not list or inspect unrelated threads solely for naming, and do not create, fork, navigate, message, archive, pin or otherwise manage tasks for this checkpoint.\n\nBefore the final response, resolve the checkpoint as applied (successful tool result confirms the title), kept (relevant or user-chosen title), unavailable (no safe capability), skipped (project unknown), or failed/unverified (error or no confirmation). Use a targeted current-thread readback when available; an ambiguous write requires readback before any retry. Only a verified mismatch permits one safe corrective call; never loop or overwrite a later user rename. Do not assume a universal timing window or automatic-title overwrite across AI apps. An unavailable capability does not block startup; skip silently. A failed/unverified attempted rename gets a brief startup warning, not a success claim. Once resolved, return the card and stop for bare startup. On a later user-authorized turn, revisit naming when the primary task becomes concrete or changes, or a generic/stale title is observed; do not rename for tests, reviews or small substeps.\n\nThe title is display-only; it is not project state, permission, progress, completion evidence, a health result, or a source of truth. This checkpoint permits only the bounded title calls above; it does not authorize project/file writes, network research, external task work, extra startup reads or continuation beyond the startup boundary.\n\nRead `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.\n\nIf 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.\n\nBefore 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.\n\nProbe 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.\n\nShow the startup card only for explicit continuity startup. For a plain continuity message, show the card after the minimum state recovery and end the turn; its recommended next action is advice, not permission to act. Render the startup card in a fenced `text` block and preserve spacing so the ASCII status marker remains aligned. The first-use exception above replaces that status-only stop with onboarding only when the handoff state is `eligible`, the objective is empty / `TBD`, and there is no same-message concrete task. An explicit same-message task or long-run continuation may combine the card with its first useful action. Direct ordinary tasks do not show the card. If onboarding is explicitly requested or first-use onboarding is triggered, combine any card and guidance in one response.\n\nFor explicit bare continuity startup, after the handoff is read, the startup card may read only the bounded version evidence from `dev/PROJECT_INDEX.md`: the unique stable-semver `| Agent Handoff Kit template version | X.Y.Z | ... |` row inside the unique real `## Stack` section. Do not route on, summarize, or load any other Project Index content for startup, title, permissions, packs, health, or task work. Missing, unreadable, malformed, duplicate, prerelease, or out-of-Stack-only version evidence prints `version unverified`; the turn remains status-only with zero writes. A direct ordinary or stateless task does not read the handoff or Project Index merely to fill a card or version.\n\n```text\n /\\_/\\ Agent Handoff Kit v<version>\n ( o.o ) continuity ready\n > ^ <\n\n🔎 交接狀態:<loaded / new install / resumed / incomplete>\n📌 目前目標:<current objective>\n⚠️ 注意事項:<important boundary or none>\n🚀 推薦下一步:<one action + reason>\n```\n\nUse the full product name, plain user language, and one recommended next action. Never print the literal placeholder `v<version>`.\n\n## 2. Proportionate Work Loop\n\nApply 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.\n\nIn every user-facing reply, lead with ordinary language: state the result and its practical effect, then the next action when one helps. Put exact commands, errors, hashes, and detailed evidence after that; brevity must not hide uncertainty or safety risk.\n\n- 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.\n- Non-trivial work reads relevant sources before changing them.\n- High-risk work states scope, impact, acceptance, and required confirmation before writes.\n- External skill flows, subagents, task plans, demo workspaces, and another tool's finish step do not replace the active root's persistence decision.\n- 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.\n- 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.\n- Ordinary document edits normally use local read-back and task-specific checks only. If the edited document itself is the target authority and the task does not touch Kit-managed files, migrations, release / closeout gates, external effects, cross-source conflicts, or blockers for safe continuation, do not run `agent-handoff-kit doctor`, write handoff / log state, or regenerate the startup mirror solely because a document changed.\n\n## 2.1 Persistence Gate\n\nChoose exactly one tier after a task:\n\n1. No persistence: no durable fact was produced. One-off answers, transient output, active unapproved drafts, and routine rerunnable checks normally use this tier.\n2. 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 perform full closeout. Apply the bounded opening/mirror consistency rule below only when this checkpoint changes actionable state repeated there.\n3. 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.\n\nPre-closeout checkpoint guard: before writing `dev/SESSION_HANDOFF.md` or `dev/SESSION_LOG.md` without explicit closeout / checkpoint intent, identify the durable fact, why the edited target authority or user-visible answer is insufficient, and why that file is the smallest correct home. Do not write either file merely because the next AI might misread stale state, because a target-authority document changed, or to make the handoff mirror every intermediate step. If the gate selects a checkpoint, update only the named current-state field(s) or one concise log entry; preserve unrelated / historical handoff sections byte-stable where practical. Without the opening-consistency condition below, do not regenerate `START_NEXT_SESSION_PROMPT.txt`.\n\nCheckpoint opening consistency: when an authorized checkpoint changes actionable facts repeated in the `Next Session Opening Message`, reconcile only those affected current facts in that same checkpoint. Derive `START_NEXT_SESSION_PROMPT.txt` from the sole marked opening block only if normalized content differs, then verify the block/mirror and the changed objective, next action and completion boundary agree. Do not merely label an authoritative opening historical while leaving instructions to redo completed work. Preserve unrelated opening text and cold evidence; this condition does not authorize full closeout, new task work, extra source scans or persistence after an ordinary document edit.\n\nDuring an ongoing task, between Persistence Gate decisions, `dev/SESSION_HANDOFF.md` may legitimately trail the read-back target authority. Treat that as expected lag, not drift, and do not update handoff merely to mirror each intermediate step. Still apply the gate when a durable or startup-needed fact must survive interruption, the handoff is the smallest correct home, Kit-managed / release / closeout / external-effect state changed, or full closeout is selected.\n\nRoute 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.\n\nExternal 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.\n\n## 2.2 Upgrade Completion\n\nThe CLI owns upgrade truth. An upgrade is complete only when:\n\n1. The root is not newer than the CLI and every target passes read-only classification.\n2. Conflict produces zero governance-target and version writes.\n3. Staged outputs pass the offline migration acceptance gate: root boundary, structure, cross-file invariants, preservation hashes, and version transition.\n4. The recoverable transaction commits without an unresolved journal; only a failure caused by this transaction triggers rollback.\n5. 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.\n6. The migration report records attempted version, committed version, transaction state, actions, redacted reasons, and backup locations without credential values.\n\nDo 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.\n\n## 3. Safety Baseline\n\nDo not delete, reset, overwrite user-owned content, bulk-move, publish, change permissions, or perform another irreversible or external action without the required explicit authorization.\n\nNamed 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.\n\nVerify 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.\n\nDo not modify unrelated files or erase unexpected user changes. Do not claim completion without read-back evidence and proportionate checks.\n\n## 4. Closeout Trigger\n\nClear 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.\n\nThe always-enforced closeout invariants are:\n\n1. Current state lives in `dev/SESSION_HANDOFF.md`; trace evidence lives in `dev/SESSION_LOG.md`.\n2. Completed, pending, risk, validation, and opening-message lifecycle states agree.\n3. `START_NEXT_SESSION_PROMPT.txt` is regenerated from the sole authoritative handoff block and no third full copy is retained.\n4. Workspace identity is a last-verified snapshot. Live root / Git / worktree truth belongs to `agent-handoff-kit workspace-health --root <project root>` or equivalent read-only Git probes, not to stale prose.\n5. Closeout is not complete until required files are written, read back, and the available closeout checks pass.\n6. After those checks, render the final card with `agent-handoff-kit closeout-status --root <project root>`; only its `status: complete` output may say `handoff saved`. A nonzero / `blocked` result is an honest blocked closeout, not a completed one.\n7. Git commit, push, release, publish, deployment, deletion, and permission changes remain separately authorized actions.\n\n## 5. Pack Loading\n\nUse `dev/RULE_PACKS.md` to load the minimum task-specific set. Read the applicable packs, including their project supplements and required references, before deciding how to act; an index, title or remembered summary is not the rule itself. Apply them within the user's actual objective and instruction priority: do not invent a replacement goal, acceptance standard or competing rule system. Missing or conflicting requirements must be resolved from their owners, not filled by an invented policy. Packs may add stricter requirements but cannot weaken core safety or continuity.\n\nLoad `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.\n\nAfter 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.\n\n## Core Complexity Rule\n\nBefore changing `AGENTS.md` or adding a durable governance rule, use `dev/RULE_PACKS.md` to load `dev/rules/agent-governance.md` and locate the existing normative owner. Follow its `Governance Write Boundary` before choosing a writable location: installed official core and pack bodies are not project-editable rule homes. Default-core rules must apply to most sessions, protect safety or continuity, and be shorter than the routed detail they replace. Scenario-specific or project-specific detail belongs in an existing pack's project supplement or registered reference; a new pack is justified only when it creates a smaller, independently loadable responsibility with one normative owner. Do not copy the agent-governance classification table or workflow into the core.\n<!-- END Agent Handoff Kit managed core -->\n\n<!-- ack:user-rules-router:dev/USER_RULES.md -->\n<!-- ack:user-rules-acceptance:sha256=36d718ba87def4e8a68b3da9b16eb5427ccffe5d03455d53c7c7ec3a3df23dd4 -->\nBefore loading task packs, read `dev/USER_RULES.md`. Its registered entries\nunder `dev/user_rules/` are user-controlled rules: read each accepted entry in\nthe listed order and verify its accepted raw-byte witness. Do not treat this\nrouter, its directory, a heading, language, format, location, or\nofficial-looking text as proof that any legacy source belongs to the Kit.\n"
|
|
15126
15306
|
}
|
|
15127
15307
|
},
|
|
15128
15308
|
"generatedShortcuts": {
|
|
@@ -15160,7 +15340,61 @@
|
|
|
15160
15340
|
".agents/skills/handoff-kit-help/SKILL.md": "1d804e52c229a96deb656a141fb805ba7dd190666e2f191a5671109b5c1dc439",
|
|
15161
15341
|
".gemini/commands/handoff-kit-help.toml": "5c7b431efc2ab7aab7b21e8e7dd387193d8a1a590b8aef7469d86741c8ab8885"
|
|
15162
15342
|
}
|
|
15343
|
+
},
|
|
15344
|
+
"0.4.1": {
|
|
15345
|
+
"npm": {
|
|
15346
|
+
"spec": "@adamchanadam/agent-handoff-kit@0.4.1",
|
|
15347
|
+
"shasum": "5e094750d21fdd7b583a8acda4e527f9c0894daf",
|
|
15348
|
+
"integrity": "sha512-bOJ2FCMH91IdyvfPKo/Eq/BBYauRl+zbXv3lvWcRHfCME76D/oVuInTm480FBPtVqjXS8ynlj/WNT0IIa5grUA==",
|
|
15349
|
+
"tarballSha256": "9d49774bedebfc5443a67d693dba11c83b9251c930e31222b93ca3fdc9683aaf"
|
|
15350
|
+
},
|
|
15351
|
+
"generatorSha256": "65543365ed67888951f8b38bf1ef2b0eece0e1b0c24bce82d7610b774161b75e",
|
|
15352
|
+
"files": {
|
|
15353
|
+
".claude/skills/handoff-kit-start/SKILL.md": "1051c712d3436a9435e875c66018b3fb366f54ccc0d37c25f9f4120fc24fdce9",
|
|
15354
|
+
".agents/skills/handoff-kit-start/SKILL.md": "1051c712d3436a9435e875c66018b3fb366f54ccc0d37c25f9f4120fc24fdce9",
|
|
15355
|
+
".agents/skills/handoff-kit-start/agents/openai.yaml": "a294dd1815bef68434d4fbf93261d5192abdc6f3570e6b6030d19f2bf657a984",
|
|
15356
|
+
".gemini/commands/handoff-kit-start.toml": "1bfa5ceb9601e52120c30998398c3c844f723aea2c720806f8d952156f0725d6",
|
|
15357
|
+
".claude/skills/handoff-kit-close/SKILL.md": "83eb6ceb5c5be6a9eed5532daea61ad2fa49c9cff51a5152545c53b69bf123c7",
|
|
15358
|
+
".agents/skills/handoff-kit-close/SKILL.md": "83eb6ceb5c5be6a9eed5532daea61ad2fa49c9cff51a5152545c53b69bf123c7",
|
|
15359
|
+
".agents/skills/handoff-kit-close/agents/openai.yaml": "7ff3064232dfa62d9b0a75c5cc743afb77a1c6986e8c423618cc37cf0031501d",
|
|
15360
|
+
".gemini/commands/handoff-kit-close.toml": "b6d5c01ffc52de91976739df95ac100f7c4564fab261967714be0669430bd77b",
|
|
15361
|
+
".claude/skills/handoff-kit-progress/SKILL.md": "0e01790b02127f29def9289fa6065680922b57b039cd005c0103306e9eadbc69",
|
|
15362
|
+
".agents/skills/handoff-kit-progress/SKILL.md": "0e01790b02127f29def9289fa6065680922b57b039cd005c0103306e9eadbc69",
|
|
15363
|
+
".agents/skills/handoff-kit-progress/agents/openai.yaml": "cbb31a137fe249e7ec563ea70759c7bd7792d0b72dd912d38ef25226667902c4",
|
|
15364
|
+
".gemini/commands/handoff-kit-progress.toml": "621d7bd36559cef8726f9fbd9335b04b8bd51ef87c26191c0376536fc3e73436",
|
|
15365
|
+
".claude/skills/handoff-kit-align/SKILL.md": "bdd159f7b9409cd996dee3eae0f60e1f3f91542e7300bae9c6f551a5df2eeff5",
|
|
15366
|
+
".agents/skills/handoff-kit-align/SKILL.md": "bdd159f7b9409cd996dee3eae0f60e1f3f91542e7300bae9c6f551a5df2eeff5",
|
|
15367
|
+
".agents/skills/handoff-kit-align/agents/openai.yaml": "4001a19fc73b01be44de48b44db2d5c361e38c637a1b4ffa1b215dd5615bca5d",
|
|
15368
|
+
".gemini/commands/handoff-kit-align.toml": "7dc105f92a8259715ce115a651982d72ae9a411ca082b6a6ba4f71658417d772",
|
|
15369
|
+
".claude/skills/handoff-kit-onboard/SKILL.md": "947bfab49687be1dc62c1484e6d143700762af01103d0fbece30dc1123f93035",
|
|
15370
|
+
".agents/skills/handoff-kit-onboard/SKILL.md": "947bfab49687be1dc62c1484e6d143700762af01103d0fbece30dc1123f93035",
|
|
15371
|
+
".agents/skills/handoff-kit-onboard/agents/openai.yaml": "5ef6ac65e96d20a71287c5f44abad14dc4f7b91d4fefd5b4ec7f672273917265",
|
|
15372
|
+
".gemini/commands/handoff-kit-onboard.toml": "ba9d618cc55646b04d10d35814329054b7069166e515e1b3346d953606bbf8bf",
|
|
15373
|
+
".claude/skills/handoff-kit-remember/SKILL.md": "155cddc9ced4b309d448b2e9111073eeaa73a05c004f9fde4d6b3db7dd978c1f",
|
|
15374
|
+
".agents/skills/handoff-kit-remember/SKILL.md": "155cddc9ced4b309d448b2e9111073eeaa73a05c004f9fde4d6b3db7dd978c1f",
|
|
15375
|
+
".agents/skills/handoff-kit-remember/agents/openai.yaml": "9bed15e27ee9725e2a31b57d10687349a5754dcfcae55aca167c763f6f1e0e80",
|
|
15376
|
+
".gemini/commands/handoff-kit-remember.toml": "b6a648e2532db26a287ebfbd57adcce320400fc837b48dfd5b07785890e84f40",
|
|
15377
|
+
".claude/skills/handoff-kit-check/SKILL.md": "d8052a0748cd21d8b20d829c1fff79659f0dbb9a25be502a029a1b481801c826",
|
|
15378
|
+
".agents/skills/handoff-kit-check/SKILL.md": "d8052a0748cd21d8b20d829c1fff79659f0dbb9a25be502a029a1b481801c826",
|
|
15379
|
+
".agents/skills/handoff-kit-check/agents/openai.yaml": "666d4b602e019e06a7dd70742fc459cd2afab2a442bce038c87dfce09d429bb2",
|
|
15380
|
+
".gemini/commands/handoff-kit-check.toml": "250463183ba5567f9f5ff938521bb4bded6349ec3e82fe0a84a93607b6082423",
|
|
15381
|
+
".claude/skills/handoff-kit-update/SKILL.md": "b49ec97880383d6789e62d7aea0cbd49ba63b9588cae6ebc0025817bbf8e0127",
|
|
15382
|
+
".agents/skills/handoff-kit-update/SKILL.md": "b49ec97880383d6789e62d7aea0cbd49ba63b9588cae6ebc0025817bbf8e0127",
|
|
15383
|
+
".agents/skills/handoff-kit-update/agents/openai.yaml": "12177a56d5a3573cb079506de78375f83ccb06f8fa7e1828a3d7c237de82e7bf",
|
|
15384
|
+
".gemini/commands/handoff-kit-update.toml": "7845f7b6bea3ec55c73eb8a6a1e8ed3e44ddf17f0c75ca4268175cf5902b026c",
|
|
15385
|
+
".claude/skills/handoff-kit-help/SKILL.md": "6fd2f07abf54727d76524614200c90b0836edf1118a08bfb3b89f2d0c5bb9530",
|
|
15386
|
+
".agents/skills/handoff-kit-help/SKILL.md": "6fd2f07abf54727d76524614200c90b0836edf1118a08bfb3b89f2d0c5bb9530",
|
|
15387
|
+
".agents/skills/handoff-kit-help/agents/openai.yaml": "a87a82d80551abfe32588d6b66b44b21c45aa636ef0392cc886dfb5cc65a609a",
|
|
15388
|
+
".gemini/commands/handoff-kit-help.toml": "2bbdca26e35469d4330324ed89f9bcb73d30bd645fdf0c28865dddda03011b56",
|
|
15389
|
+
"dev/handoff-kit/launch.mjs": "0a4b0f7263e3dd48e686b3fa6d99e2d000c9c54eede849f9b719fe57e173e63e",
|
|
15390
|
+
"dev/handoff-kit/open.mjs": "f060618c69ac30373121d72a0fdafc6d592d61aad342a92b17cca2bea87e2255",
|
|
15391
|
+
"dev/handoff-kit/server.mjs": "536b32ae27e16852c3cbb80c1124125d3f7a50f7fc2870a7d46d6b8ece112d37",
|
|
15392
|
+
"dev/handoff-kit/projection.mjs": "733cfdc66b3228ff9ad1280409c003612ac77a3cc12169fe7d3d015fa632b18c",
|
|
15393
|
+
"dev/handoff-kit/dashboard.mjs": "b9ea752f00e5b0b92027f5cbfe8e14a4f5cd3af5c076e2d71ded8db58dcddb48",
|
|
15394
|
+
"dev/handoff-kit/project-version.mjs": "9fdee8c290e8fb8a8621430957b484676c6fb2d8ab198576b49b132d48a4e262",
|
|
15395
|
+
"dev/handoff-kit/assets.mjs": "3c4557156b93b04fb4cebb2cb5b70c167cdcab5a58625b8a1b67654331691f4e"
|
|
15396
|
+
}
|
|
15163
15397
|
}
|
|
15164
15398
|
},
|
|
15165
|
-
"catalogDigestSha256": "
|
|
15399
|
+
"catalogDigestSha256": "2effd584542e87a477ff5bd971082dc82819b3267f3d2b09f22482a02fe9fe10"
|
|
15166
15400
|
}
|
|
@@ -11,6 +11,7 @@ const requiredArtifactBoundManagedSegments = Object.freeze([
|
|
|
11
11
|
]);
|
|
12
12
|
|
|
13
13
|
export const OFFICIAL_ORIGIN_CATALOG_SCHEMA = 1;
|
|
14
|
+
export const RECENT_PUBLISHED_UPGRADE_VERSION_LIMIT = 30;
|
|
14
15
|
|
|
15
16
|
export async function loadOfficialOriginCatalog(catalogPath = defaultCatalogPath) {
|
|
16
17
|
const catalog = JSON.parse(await readFile(catalogPath, "utf8"));
|
|
@@ -18,6 +19,25 @@ export async function loadOfficialOriginCatalog(catalogPath = defaultCatalogPath
|
|
|
18
19
|
return catalog;
|
|
19
20
|
}
|
|
20
21
|
|
|
22
|
+
// This selection limits WORK upgrade acceptance exercises. It does not alter
|
|
23
|
+
// catalog validation or runtime recognition of any older official release.
|
|
24
|
+
export function selectRecentPublishedStableVersions(catalog, limit = RECENT_PUBLISHED_UPGRADE_VERSION_LIMIT) {
|
|
25
|
+
if (!Number.isInteger(limit) || limit < 1) throw new Error("recent published upgrade limit must be a positive integer");
|
|
26
|
+
return Object.entries(catalog?.releases ?? {})
|
|
27
|
+
.filter(([version, release]) => (
|
|
28
|
+
/^\d+\.\d+\.\d+$/.test(version)
|
|
29
|
+
&& typeof release?.source?.npm?.spec === "string"
|
|
30
|
+
&& typeof release?.source?.githubRelease?.publishedAt === "string"
|
|
31
|
+
&& Number.isFinite(Date.parse(release.source.githubRelease.publishedAt))
|
|
32
|
+
))
|
|
33
|
+
.sort(([leftVersion, left], [rightVersion, right]) => (
|
|
34
|
+
Date.parse(left.source.githubRelease.publishedAt) - Date.parse(right.source.githubRelease.publishedAt)
|
|
35
|
+
|| compareStableVersions(leftVersion, rightVersion)
|
|
36
|
+
))
|
|
37
|
+
.slice(-limit)
|
|
38
|
+
.map(([version]) => version);
|
|
39
|
+
}
|
|
40
|
+
|
|
21
41
|
export function validateOfficialOriginCatalog(catalog) {
|
|
22
42
|
assertCatalogShape(catalog);
|
|
23
43
|
const digestCopy = { ...catalog };
|
|
@@ -251,6 +271,13 @@ function stripVersionPrefix(version) {
|
|
|
251
271
|
return String(version ?? "").replace(/^v/, "");
|
|
252
272
|
}
|
|
253
273
|
|
|
274
|
+
function compareStableVersions(left, right) {
|
|
275
|
+
const a = left.split(".").map(Number);
|
|
276
|
+
const b = right.split(".").map(Number);
|
|
277
|
+
for (let index = 0; index < 3; index += 1) if (a[index] !== b[index]) return a[index] - b[index];
|
|
278
|
+
return 0;
|
|
279
|
+
}
|
|
280
|
+
|
|
254
281
|
function validSegmentByteIdentity(value) {
|
|
255
282
|
return Boolean(value && typeof value === "object" && !Array.isArray(value)
|
|
256
283
|
&& /^[a-f0-9]{64}$/.test(value.sha256)
|
package/package.json
CHANGED
|
@@ -20,9 +20,9 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
20
20
|
4. Do not let development-only workspace rules enter public runtime.
|
|
21
21
|
5. Check complexity budget before adding default-core behavior.
|
|
22
22
|
6. Before creating durable workflow, runbook, or instruction files, first classify the knowledge type and verify whether an existing home can carry it without a new file: current state belongs in `dev/SESSION_HANDOFF.md`; trace evidence belongs in `dev/SESSION_LOG.md`; file / command / reference maps belong in `dev/PROJECT_INDEX.md`; sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`; reusable operating procedures belong in the relevant rule pack or registered reference. New runbooks are last resort only.
|
|
23
|
-
7. When a task uses external skills, subagents, demo workspaces, or another tool's closeout, treat those flows as subordinate to the active root's Agent Handoff Kit governance. The active root still needs the `
|
|
23
|
+
7. When a task uses external skills, subagents, demo workspaces, or another tool's closeout, treat those flows as subordinate to the active root's Agent Handoff Kit governance. The active root still needs the installed `AGENTS.md` Persistence Gate decision; do not duplicate the gate thresholds in this pack.
|
|
24
24
|
8. Before any pre-closeout handoff / log write for governance work, apply the core Persistence Gate explicitly. A concern that future agents may read stale handoff is not enough when the changed rule, spec, runbook, or document is itself the target authority; leave handoff lag expected unless checkpoint conditions are met. When the gate does select a checkpoint, write only the smallest current-state field or concise log entry and leave historical evidence sections byte-stable where practical.
|
|
25
|
-
9. For long-running projects, maintain `dev/PROJECT_DECISIONS.md`
|
|
25
|
+
9. For long-running projects, maintain `dev/PROJECT_DECISIONS.md` under `dev/rules/closeout.md` `## Maintenance Trigger Check`: capture major decisions when they happen, run the short trigger check at every closeout, and do full long-term maintenance only when a hard trigger, semantic trigger, or 10-closeout backstop applies. Short single-task projects keep this as a no-op default; users are not expected to edit this file manually.
|
|
26
26
|
10. Governance bridge is a triggered review, not a default startup scan. Use it when an important file, source-of-truth document, runbook, production guide, workflow, checklist, stock list, or similar durable document may need to be connected to project governance.
|
|
27
27
|
11. Content-based trigger: long-term governance routing is content-based, not trigger-only. Even if the user does not use explicit governance-routing phrases, treat a statement as durable governance when it says future sessions must follow it, when it corrects a recurring AI mistake, or when it defines a reusable API / MCP / tool-use pattern. Do not persist long-term governance knowledge only in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or `START_NEXT_SESSION_PROMPT.txt`; those surfaces may be compressed, archived, or regenerated.
|
|
28
28
|
12. Mid-task changes to product goals, requirements, development checklists, acceptance rules, exclusions, priorities, or scope are task contract changes. Before writing them, check whether the same contract already lives in a spec, backlog, issue list, README, runbook, project index entry, or handoff section. Merge into the existing authoritative home, then leave only a pointer or current-state summary elsewhere.
|
|
@@ -37,7 +37,7 @@ This is the single write-location contract for installed projects, not for autho
|
|
|
37
37
|
2. Treat the `AGENTS.md` managed-core region and complete official `dev/rules/*` pack bodies as protected. Daily project edits must not insert, translate, reformat, reorder or remove their contents or delimiters. Verify the installed version's official content before identifying the boundary; a heading, marker or version row alone is not ownership proof. Formal upgrade or an explicitly scoped repair owns official changes. If local rules are already interleaved, preserve them and report the required bounded reconciliation; do not guess which lines to delete or bless the mixed body as official.
|
|
38
38
|
3. Reuse the matching pack's existing project supplement when it owns the rule. Otherwise place a short local rule after the entire verified official body under `## Project Rules`; preserve the official trailing newline. This heading labels the writable appendix, not the end of official ownership. For substantial or shared procedures, reuse a registered project reference; create a new reference only if no suitable owner exists. If `dev/USER_RULES.md` formally owns the rule, use its accepted update procedure rather than editing witnessed bytes or creating a competing copy. Always-needed project entry rules may live outside the managed core only after checking their existing owner.
|
|
39
39
|
4. Preserve project-state schemas separately: edit handoff fields, actual log entries, index data or registry rows in their existing writable sections; do not insert policy into template instructions or alter machine markers. Preserve official routing rows in `dev/RULE_PACKS.md`; add a project row only when a project reference needs a task trigger, naming both the relevant pack and reference. A same-pack appendix uses that pack's existing route. Do not add a route or load a pack merely for bare startup.
|
|
40
|
-
5. Before and after an edit touching core or pack files, compare the complete protected region against the verified input; every protected byte must remain unchanged. Use the installed-version CLI's read-only `upgrade --dry-run --root <project root>`
|
|
40
|
+
5. Before and after an ordinary project-rule edit touching core or pack files, compare the complete protected region against the verified input; every protected byte must remain unchanged. For a formal upgrade or explicitly scoped repair, verify the approved official diff against the verified input and perform its required readback instead; preserve interleaved or unknown user content and do not guess which bytes to remove. Use the installed-version CLI's read-only `upgrade --dry-run --root <project root>` where that lifecycle applies; record the CLI version and any existing conflict separately. A pre-existing conflict requires reconciliation before claiming the write boundary is verified. A new conflict or a change outside the approved scope prevents completion; restore only your own scoped change from its verified input without discarding concurrent or pre-existing user work. For ordinary project-state edits, use schema/marker and local readback checks instead of an upgrade preview.
|
|
41
41
|
6. Read back the rule from its normal consumer path: task signal -> router -> relevant pack including the project supplement and required reference -> requested action. Verify its exact requirement, scope and precedence, and that unrelated packs stay unloaded. An indexed file that no applicable route reads is not connected. Evidence must show both correct application and preserved upgrade compatibility; a successful preview alone does not prove an AI followed the rule.
|
|
42
42
|
|
|
43
43
|
## Governance Bridge Workflow
|
package/packs/closeout.md
CHANGED
|
@@ -27,7 +27,7 @@ Do not copy the full opening message into `dev/SESSION_LOG.md` or any third curr
|
|
|
27
27
|
|
|
28
28
|
Full closeout is differential and write-minimal. Update only fields whose current truth changed. For unchanged state, preserve bytes where practical and record checked/no-op only when it helps the next agent. Reuse a completed task check only when its recorded root, task input, tool identity, commit / artifact identity, and required file hashes still match the current state. Do not rerun task QA that is already bound to unchanged identity. Do rerun checks affected by closeout writes, gates that are incomplete or indeterminate, closeout-specific checks, and the final `closeout-status` read-back. If a closeout attempt is interrupted, stopped, aborted, times out, or hits a spawn / transport error, resume at the first incomplete or indeterminate gate; do not restart from the beginning unless the root, input, tool identity, commit, artifact, or relevant hash changed.
|
|
29
29
|
|
|
30
|
-
Handoff cold zones are historical / evidence sections, old validation records, completed-work narratives, and unchanged durable anchors. Do not rewrite, reword, reorder, or refresh cold zones for ceremony or style.
|
|
30
|
+
Handoff cold zones are historical / evidence sections, old validation records, completed-work narratives, and unchanged durable anchors. Stable anchors and decision-changing current facts stay in the packet. Do not rewrite, reword, reorder, or refresh cold zones for ceremony or style. When older detailed narrative no longer changes the next action, preserve it byte-for-byte in existing trace/archive storage and verify that copy before removing it from the current packet. Do not rewrite or archive unchanged material at every closeout, impose an arbitrary size cap, or weaken the required full reception of the current packet.
|
|
31
31
|
|
|
32
32
|
1. Reconcile `dev/SESSION_HANDOFF.md`; never append a new current-state snapshot beneath an old one. Verify durable anchors, then update only changed closeout-reconciled fields or sections; leave already-current sections unchanged instead of rewriting them for ceremony.
|
|
33
33
|
2. Reconcile lifecycle state across `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. Completed or verified work cannot remain unresolved unless explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with its missing evidence or trigger.
|
|
@@ -42,7 +42,7 @@ Handoff cold zones are historical / evidence sections, old validation records, c
|
|
|
42
42
|
10. Mark first-use guidance `consumed` after the first successfully completed task or first full closeout. Upgrade must never reset `consumed` or `not_applicable` to `eligible`.
|
|
43
43
|
11. Verify `START_NEXT_SESSION_PROMPT.txt` against the sole fenced handoff opening-message block first. Regenerate it only when normalized content differs, then run the project's fixed prompt-mirror checker or perform an equivalent anchored read-back that verifies marker, heading, fence, full-copy uniqueness, and normalized content equality.
|
|
44
44
|
12. Run available project-specific closeout checks. Do not run a separate bundled `doctor`: the `closeout-status` command below performs the one required fresh doctor read-back. Do not treat an external update-check failure as local closeout failure. Fix state or mirror failures before claiming handoff ready.
|
|
45
|
-
13. Run `agent-handoff-kit closeout-status --root <project root>` after the handoff and prompt read-back. It performs the one required fresh doctor read-back plus a read-only workspace-health comparison against the handoff snapshot, and its output is the only final card source
|
|
45
|
+
13. Run `agent-handoff-kit closeout-status --root <project root>` after the handoff and prompt read-back. It performs the one required fresh doctor read-back plus a read-only workspace-health comparison against the handoff snapshot, and its output is the only final card source. A nonzero result means the closeout is blocked; do not replace it with a success summary.
|
|
46
46
|
|
|
47
47
|
## Packet-Only Reconstruction Check
|
|
48
48
|
|
|
@@ -70,7 +70,7 @@ If no trigger applies, record one no-op reason. Handoff carries continuity; log
|
|
|
70
70
|
|
|
71
71
|
The handoff opening-message block is authoritative. It must name the absolute root, route the agent through `AGENTS.md` and the handoff, state the current objective and boundary, and avoid instructing the next agent to redo completed work. It must not require SESSION_LOG as an ordinary startup read.
|
|
72
72
|
|
|
73
|
-
Use `agent-handoff-kit closeout-status --root <project root>` after the required read-backs.
|
|
73
|
+
Use `agent-handoff-kit closeout-status --root <project root>` after the required read-backs. When it returns a card, copy the full card verbatim in a fenced `text` block before any explanation for both `status: complete` and `status: blocked`; never reduce it to selected status or blocker lines, print the literal placeholder `v<version>`, hand-compose a substitute success/blocked card, or use `handoff saved` unless the command reports `status: complete`. Only when no CLI card exists because the CLI could not be launched or returned no card may the final response show a fenced `closeout unavailable` card with no version and no `saved`/`complete` claim, followed by the actual missing condition. That presentation does not complete closeout and never replaces a returned complete or blocked CLI card.
|
|
74
74
|
|
|
75
75
|
```text
|
|
76
76
|
/\_/\ Agent Handoff Kit v<version>
|
|
@@ -84,7 +84,7 @@ status: complete
|
|
|
84
84
|
⚠️ Boundary: <important boundary or none>
|
|
85
85
|
```
|
|
86
86
|
|
|
87
|
-
For `status: blocked`, the command instead says `handoff blocked`; retain that status, blocker reason, and human explanation: `這不是失敗;只是還有事未保存、未提交、未驗證或需要處理。先照 Blocker 行處理,不要把本輪當作已完成交接。` Then give the short local-root entry `Start Agent Handoff` / `開工` and the path-bearing fallback for an agent not yet pointed at the root.
|
|
87
|
+
For `status: blocked`, the command instead says `handoff blocked`; retain that status, blocker reason, and human explanation: `這不是失敗;只是還有事未保存、未提交、未驗證或需要處理。先照 Blocker 行處理,不要把本輪當作已完成交接。` Then give the short local-root entry `Start Agent Handoff` / `開工` and the path-bearing fallback for an agent not yet pointed at the root. The narrow `closeout unavailable` presentation above is allowed only when there is no CLI card; do not use it to replace a returned blocked card or hand-compose a third stateful prompt.
|
|
88
88
|
|
|
89
89
|
## Stop Conditions
|
|
90
90
|
|
package/packs/integrations.md
CHANGED
|
@@ -48,7 +48,7 @@ Agents must not use model memory, old session experience, copied examples, Conne
|
|
|
48
48
|
| Local app plugin API | Official API documentation, official type definitions, official sample project, or local installed package types matching the project version. |
|
|
49
49
|
| Project-local runbook | Accept as a task source only when it records the upstream source, version/date, scope, and known limits. |
|
|
50
50
|
|
|
51
|
-
If the required source cannot be inspected,
|
|
51
|
+
If the required source cannot be inspected, first classify the actual failure and check an already-authorized capable source/channel plus any normal platform approval. Mark only the affected use `blocked` or `unverified` when none can establish the needed contract; ask the user only for docs, schema, access, or a decision the AI cannot obtain, and use a manual packet only when it preserves the needed evidence. Do not continue by trial and error or bypass a real refusal. Connector-first means schema-first for the active runtime, not memory-first.
|
|
52
52
|
|
|
53
53
|
#### Runtime-Controlled Tool Operation Variants
|
|
54
54
|
|
|
@@ -110,7 +110,7 @@ MCP servers may be official, community, custom, or project-local. Custom MCPs of
|
|
|
110
110
|
Discipline:
|
|
111
111
|
|
|
112
112
|
- Use only the active runtime's exposed tool name, description, and input schema.
|
|
113
|
-
- Treat non-vetted or custom MCP write operations with extra caution. Destructive writes require dry-run and user confirmation under `
|
|
113
|
+
- Treat non-vetted or custom MCP write operations with extra caution. Destructive writes require dry-run and user confirmation under `dev/rules/safety.md`.
|
|
114
114
|
- If the server fails because of process crash, config error, or unavailable runtime state, surface the failure, recommend checking MCP config and restarting the host tool, and do not blindly retry.
|
|
115
115
|
|
|
116
116
|
#### 3.3 Plugins
|
|
@@ -158,18 +158,18 @@ Record declared integrations in `PROJECT_INDEX` `## Installed Integrations`, usi
|
|
|
158
158
|
|
|
159
159
|
#### Phase 2 — Cross-session handoff
|
|
160
160
|
|
|
161
|
-
`SESSION_HANDOFF` durable anchors should point future agents to `PROJECT_INDEX` `## Installed Integrations`.
|
|
161
|
+
`SESSION_HANDOFF` durable anchors should point future agents to `PROJECT_INDEX` `## Installed Integrations`. Follow the core Intent And Startup contract for when to read that section; a durable anchor does not add it to every next-session opening read order.
|
|
162
162
|
|
|
163
163
|
#### Phase 3 — Before-use availability probe
|
|
164
164
|
|
|
165
165
|
Immediately before the current task uses a declared integration, run the smallest relevant availability probe when the runtime exposes the needed tool schema. Do not probe unrelated integrations at startup. `TBD`, examples, blank rows, and placeholder-only tables are not declarations.
|
|
166
166
|
|
|
167
|
-
- Probe success: update `Last Verified`
|
|
168
|
-
- Probe fail:
|
|
167
|
+
- Probe success: update `Last Verified` only through the normal Persistence Gate, then proceed.
|
|
168
|
+
- Probe fail: record the actual unavailable/failed result where the Persistence Gate applies, then use this pack's fallback flow only for the affected surface.
|
|
169
169
|
|
|
170
170
|
#### Phase 4 — Task execution
|
|
171
171
|
|
|
172
|
-
Apply the knowledge pack's Connector-first discipline: check declaration, use the verified direct tool when available,
|
|
172
|
+
Apply the knowledge pack's Connector-first discipline: check declaration, use the verified direct tool when available, then follow this pack's classified fallback. A manual packet or user question is a last resort only when an authorized capable channel cannot supply the needed evidence.
|
|
173
173
|
|
|
174
174
|
#### Phase 5 — Mid-session drift handling
|
|
175
175
|
|
|
@@ -177,18 +177,18 @@ If an integration fails mid-task because of expired auth, rate limit, network ti
|
|
|
177
177
|
|
|
178
178
|
- Surface the failure and impact.
|
|
179
179
|
- Do not auto-fix credentials or auth.
|
|
180
|
-
- Update `PROJECT_INDEX` `Last Verified` /
|
|
180
|
+
- Update `PROJECT_INDEX` `Last Verified` only after a real successful probe and the normal Persistence Gate; record an actual failed probe as failure/drift without relabeling it available.
|
|
181
181
|
- Record the drift in `SESSION_LOG` and unresolved risk in `SESSION_HANDOFF` when it affects future work.
|
|
182
182
|
|
|
183
183
|
#### Phase 6 — Cross-tool consistency
|
|
184
184
|
|
|
185
|
-
Integration declarations are project-level; they do not guarantee every AI runtime has the same tools installed. A new runtime must verify availability, warn on capability differences, and use fallback flow
|
|
185
|
+
Integration declarations are project-level; they do not guarantee every AI runtime has the same tools installed. A new runtime must verify availability, warn on capability differences, and use this pack's fallback flow for the affected surface; do not require the user to install or switch tools before checking an already-authorized capable channel.
|
|
186
186
|
|
|
187
187
|
## Rules
|
|
188
188
|
|
|
189
189
|
1. **Credential separation**: never ask for, log, or persist credential values. Redact credential-like values and warn about rotation when appropriate.
|
|
190
190
|
2. **External Tool Usage Verification Gate**: verify current runtime schema, official docs, official types/samples, or registered tool operation references before invoking or retrying external tools.
|
|
191
|
-
3. **Declaration before use**: read `dev/PROJECT_INDEX.md` `## Installed Integrations` and `## Tool Operation References` before external-tool or runtime-controlled tool-operation work. If absent,
|
|
191
|
+
3. **Declaration before use**: read `dev/PROJECT_INDEX.md` `## Installed Integrations` and `## Tool Operation References` before external-tool or runtime-controlled tool-operation work. If absent, inspect the active runtime for an authorized capable tool/schema before asking the user about access or source information.
|
|
192
192
|
4. **Connector-first default**: when a declared integration is functional, prefer the verified direct tool call. Manual paste is fallback, not default.
|
|
193
193
|
5. **Write operations require read-back verification**: read back every external write before claiming success.
|
|
194
194
|
6. **No auto-fix credential / auth issues**: surface auth failures to the user and point to the runtime settings or tool owner.
|
|
@@ -208,7 +208,7 @@ Integration declarations are project-level; they do not guarantee every AI runti
|
|
|
208
208
|
- Before external-tool first use, write, destructive operation, raw API / SDK / CLI / URI / plugin API call, or retry after tool error, confirm the current usage source.
|
|
209
209
|
- Surface and record mid-session integration drift.
|
|
210
210
|
- After external-tool use, perform ownership-based resource closeout. For long-running, multi-tool, MCP, browser automation, repeated-error, or slowdown scenarios, report grouped residual processes or services when observable.
|
|
211
|
-
- Before closeout, update `Last Verified` for integrations
|
|
211
|
+
- Before closeout, update `Last Verified` only for integrations with a real successful probe and when the normal Persistence Gate selects the write; retain actual failed-probe drift separately.
|
|
212
212
|
- Self-check credential leakage before writing `PROJECT_INDEX`, `SESSION_HANDOFF`, or `SESSION_LOG`.
|
|
213
213
|
- Verify that `PROJECT_INDEX` External Sources `via` references match declared Installed Integrations entries.
|
|
214
214
|
- For local HTML / app validation, verify that a rejected `file://` attempt is followed by a registered operation reference or short-lived localhost fallback before declaring `blocked`.
|
|
@@ -216,7 +216,7 @@ Integration declarations are project-level; they do not guarantee every AI runti
|
|
|
216
216
|
|
|
217
217
|
## Closeout
|
|
218
218
|
|
|
219
|
-
1. Update `PROJECT_INDEX` `## Installed Integrations` `Last Verified` cells
|
|
219
|
+
1. Update `PROJECT_INDEX` `## Installed Integrations` `Last Verified` cells only after real successful probes and when the normal Persistence Gate selects the write; record actual failed drift without claiming availability.
|
|
220
220
|
2. If drift happened, record the drift narrative, impact, and suggested next handling in `SESSION_LOG`.
|
|
221
221
|
3. Add unresolved integration failures to `SESSION_HANDOFF` `## Risks / Blockers`.
|
|
222
222
|
4. If unresolved drift affects startup, mention the next-session verification need in the opening message.
|
|
@@ -227,9 +227,9 @@ Integration declarations are project-level; they do not guarantee every AI runti
|
|
|
227
227
|
|
|
228
228
|
| Anti-pattern | Why it is wrong | Correct approach |
|
|
229
229
|
|---|---|---|
|
|
230
|
-
| Assuming no Connector or MCP exists whenever the user mentions Notion, Google Drive, or another external source | Mature connector ecosystems make paste-only fallback an unreliable default. | Read `PROJECT_INDEX` Installed Integrations
|
|
230
|
+
| Assuming no Connector or MCP exists whenever the user mentions Notion, Google Drive, or another external source | Mature connector ecosystems make paste-only fallback an unreliable default. | Read `PROJECT_INDEX` Installed Integrations, then inspect the active runtime for an authorized capable tool/schema; ask only for missing user-held access or source information. |
|
|
231
231
|
| Guessing tool names, endpoints, CLI flags, URI parameters, or plugin APIs from memory | Stale examples cause unknown tool, invalid args, 400 / 404, permission, or auth loops. | Verify active runtime schema, official docs, official types/samples, or versioned local runbooks. |
|
|
232
|
-
| Treating browser validation as ordinary coding and guessing Chrome, Playwright, or DevTools commands | Browser and tool-control surfaces differ across runtimes, profiles, plugins, and installed packages. | Verify the active runtime schema, official docs, or a registered tool operation reference;
|
|
232
|
+
| Treating browser validation as ordinary coding and guessing Chrome, Playwright, or DevTools commands | Browser and tool-control surfaces differ across runtimes, profiles, plugins, and installed packages. | Verify the active runtime schema, official docs, or a registered tool operation reference; use the classified fallback only for the affected surface when unavailable. |
|
|
233
233
|
| Treating a Connector marketing page or old example as executable schema | Marketing pages do not prove the active runtime's current tool name or input schema. | Use active runtime tool list/schema as the invocation source. |
|
|
234
234
|
| Retrying unknown tool / invalid args by changing names or parameters repeatedly | Trial-and-error hides the real schema or docs gap. | Stop same-pattern retries and return to the External Tool Usage Verification Gate. |
|
|
235
235
|
| Writing credential values into `PROJECT_INDEX`, `SESSION_HANDOFF`, or `SESSION_LOG` | Project files and git history are persistent; leaked credentials remain exposed. | Record credential references only, never values. |
|
|
@@ -245,10 +245,10 @@ Integration declarations are project-level; they do not guarantee every AI runti
|
|
|
245
245
|
|
|
246
246
|
## Cross-reference
|
|
247
247
|
|
|
248
|
-
- `
|
|
249
|
-
- `
|
|
250
|
-
- `
|
|
251
|
-
- `
|
|
252
|
-
- `
|
|
253
|
-
- `
|
|
254
|
-
- `
|
|
248
|
+
- `dev/rules/knowledge.md` Rule 5: Connector-first source access discipline.
|
|
249
|
+
- `dev/rules/safety.md` Rule 10: external API / SDK / CLI / tool verification boundary.
|
|
250
|
+
- `dev/rules/safety.md` Rule 12: credential leak prevention.
|
|
251
|
+
- `dev/rules/safety.md` Rule 14: process termination and cache cleanup boundary for external-tool resources.
|
|
252
|
+
- `dev/rules/onboarding.md` Scenario F: first-contact declaration entry point.
|
|
253
|
+
- installed `AGENTS.md`: task-triggered availability probe discipline.
|
|
254
|
+
- `dev/PROJECT_INDEX.md` `## Installed Integrations` and `## External Sources` `via` column: declaration registry.
|