@adamchanadam/agent-handoff-kit 0.3.62 → 0.3.64

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 CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [繁體中文](README.md) · [Getting started](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.en.html) · [Practical guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html) · [AI install page](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.en.html)
4
4
 
5
- Source package version: `v0.3.62`. npm `@latest` and GitHub Release are verified by post-publish readback.
5
+ Source package version: `v0.3.64`. npm `@latest` and GitHub Release are verified by post-publish readback.
6
6
 
7
7
  <p align="center">
8
8
  <img src="https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif" alt="Agent Handoff Kit overview animation" width="720">
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  English: [README.en.md](README.en.md) · [Getting started](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.en.html) · [Practical guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html) · [AI install page](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.en.html)
4
4
 
5
- 原始碼套件版本:`v0.3.62`。npm `@latest` 與 GitHub Release 以發佈後讀回為準。
5
+ 原始碼套件版本:`v0.3.64`。npm `@latest` 與 GitHub Release 以發佈後讀回為準。
6
6
 
7
7
  <p align="center">
8
8
  <img src="https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif" alt="Agent Handoff Kit 功能簡介動畫" width="720">
@@ -12901,6 +12901,356 @@
12901
12901
  "canonicalSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef"
12902
12902
  }
12903
12903
  }
12904
+ },
12905
+ "0.3.62": {
12906
+ "source": {
12907
+ "npm": {
12908
+ "spec": "@adamchanadam/agent-handoff-kit@0.3.62",
12909
+ "shasum": "635fe28ea138e7b29393649b8e02dbcb0d1286fa",
12910
+ "integrity": "sha512-e7IHTzeQovGvbfJp8h8PnS+DgFTWlh3IcWGDUn5d8iGCvk7rSFZ7+8fL5P4BZQQNTqy09XWL92N99jO0VADmkw==",
12911
+ "entryCount": 34,
12912
+ "gitHead": "ce4300c0e834ff8dc8765edc6168e128e3f3a996"
12913
+ },
12914
+ "git": {
12915
+ "tag": "v0.3.62",
12916
+ "directObject": "ce4300c0e834ff8dc8765edc6168e128e3f3a996",
12917
+ "peeledCommit": null,
12918
+ "commit": "ce4300c0e834ff8dc8765edc6168e128e3f3a996"
12919
+ },
12920
+ "githubRelease": {
12921
+ "tag": "v0.3.62",
12922
+ "publishedAt": "2026-08-23T14:48:07Z"
12923
+ },
12924
+ "sourceDivergence": {
12925
+ "status": "same-commit",
12926
+ "npmGitHead": "ce4300c0e834ff8dc8765edc6168e128e3f3a996",
12927
+ "remoteTagCommit": "ce4300c0e834ff8dc8765edc6168e128e3f3a996"
12928
+ }
12929
+ },
12930
+ "manifest": {
12931
+ "AGENTS.md": {
12932
+ "state": "present",
12933
+ "contentId": "5b237785d450112d8b3d58cd6363a7b4d9885d3d25da62285c8f11724b5a2a0e",
12934
+ "rawSha256": "7f57c38458c779cfa4450930a05af99efdffb9f7f29d6975bdf036530c1a6af7",
12935
+ "normalizedSha256": "7f57c38458c779cfa4450930a05af99efdffb9f7f29d6975bdf036530c1a6af7",
12936
+ "canonicalSha256": "7f57c38458c779cfa4450930a05af99efdffb9f7f29d6975bdf036530c1a6af7"
12937
+ },
12938
+ "CLAUDE.md": {
12939
+ "state": "present",
12940
+ "contentId": "7a2cf08a1171762ebcb53f43036a2170655379416945258b9c85d4b189ecaecf",
12941
+ "rawSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad",
12942
+ "normalizedSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad",
12943
+ "canonicalSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad"
12944
+ },
12945
+ "GEMINI.md": {
12946
+ "state": "present",
12947
+ "contentId": "36da47034bb2ce6c760ddbbbbd49dccc1d17665dbb18bec56ffa3b26bac1c135",
12948
+ "rawSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986",
12949
+ "normalizedSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986",
12950
+ "canonicalSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986"
12951
+ },
12952
+ "START_NEXT_SESSION_PROMPT.txt": {
12953
+ "state": "present",
12954
+ "contentId": "de01669f2989762269e57b8f71decc55d58effa649a245136efa6dc1434b78a9",
12955
+ "rawSha256": "20f0b17dbd56b1f69b8eec186cf6419128a15573f98d3b817a8236cbb0321eed",
12956
+ "normalizedSha256": "20f0b17dbd56b1f69b8eec186cf6419128a15573f98d3b817a8236cbb0321eed",
12957
+ "canonicalSha256": "b1b9ad0cb5f3a374542a43b6c2c938e1e5d39dd42b91d12a4a74206f5f187113"
12958
+ },
12959
+ "dev/SESSION_HANDOFF.md": {
12960
+ "state": "present",
12961
+ "contentId": "54e20421bf99c389617d6cca9d3c8182bb836ed087a01c0ae98e55012ac393ea",
12962
+ "rawSha256": "28e99e21303a70b18a0b55c973020363a6b8285cd8fc1cb405896237734c9f38",
12963
+ "normalizedSha256": "28e99e21303a70b18a0b55c973020363a6b8285cd8fc1cb405896237734c9f38",
12964
+ "canonicalSha256": "fc4bf3ddddfa198a13d0ca610ad375a80fb79ec9ef9a7284da75f011969d1d94"
12965
+ },
12966
+ "dev/SESSION_LOG.md": {
12967
+ "state": "present",
12968
+ "contentId": "7b6184ee4dabe89f504a894c3d4803f012d962c7af53c7f29801a8fb28d9d51c",
12969
+ "rawSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47",
12970
+ "normalizedSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47",
12971
+ "canonicalSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47"
12972
+ },
12973
+ "dev/PROJECT_INDEX.md": {
12974
+ "state": "present",
12975
+ "contentId": "c7e652f64d5418bce302c5c96ef4afe56199d4ffa604b3db2283d26ba76d40dd",
12976
+ "rawSha256": "1c8e6526d4658a745b1efcbf9e77837a45640f36f928f379351ad96eaee9fe66",
12977
+ "normalizedSha256": "a914fd6fd8460dc4f83eac771becd333956beebf3fa71aeda3f43e481b5aefcf",
12978
+ "canonicalSha256": "3e80b5332e0c2527bd653cb049ac0d40db651e1cdfa1fcb0900f23739e745266"
12979
+ },
12980
+ "dev/DOC_SYNC_REGISTRY.md": {
12981
+ "state": "present",
12982
+ "contentId": "f6545b524dc440d3563041e04a05caff4229863f6cae2a39127f85a29a120249",
12983
+ "rawSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6",
12984
+ "normalizedSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6",
12985
+ "canonicalSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6"
12986
+ },
12987
+ "dev/RULE_PACKS.md": {
12988
+ "state": "present",
12989
+ "contentId": "9e9643115e4abef66f2c52510c0c63ce0f4a978ceb0ed5655b7c9c07a4f98c39",
12990
+ "rawSha256": "5715644cf26aa64fa42bf2173e02cadeff1731d6ea1647cfcde4bbf0915f4230",
12991
+ "normalizedSha256": "5715644cf26aa64fa42bf2173e02cadeff1731d6ea1647cfcde4bbf0915f4230",
12992
+ "canonicalSha256": "5715644cf26aa64fa42bf2173e02cadeff1731d6ea1647cfcde4bbf0915f4230"
12993
+ },
12994
+ "dev/PROJECT_DECISIONS.md": {
12995
+ "state": "present",
12996
+ "contentId": "3aae993bd5b85bf6b1d1d458f1bcf82c7d3105c843f053ffa13553bb5931b8c4",
12997
+ "rawSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e",
12998
+ "normalizedSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e",
12999
+ "canonicalSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e"
13000
+ },
13001
+ "dev/rules/safety.md": {
13002
+ "state": "present",
13003
+ "contentId": "dd6bcf74722d038f76d202e2044a6583a6e6ad107fbb010520e513eec799ff4a",
13004
+ "rawSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0",
13005
+ "normalizedSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0",
13006
+ "canonicalSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0"
13007
+ },
13008
+ "dev/rules/coding.md": {
13009
+ "state": "present",
13010
+ "contentId": "1c6deb9a5a281c13e97b0ac96079e9e1beccbd1ff106186e7a6ac78c0eeb75c2",
13011
+ "rawSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4",
13012
+ "normalizedSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4",
13013
+ "canonicalSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4"
13014
+ },
13015
+ "dev/rules/writing.md": {
13016
+ "state": "present",
13017
+ "contentId": "ceee5412520ba860e6b40de46bb164e2ce3919d2197d5fadb926198eb7dddd3b",
13018
+ "rawSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593",
13019
+ "normalizedSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593",
13020
+ "canonicalSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593"
13021
+ },
13022
+ "dev/rules/research.md": {
13023
+ "state": "present",
13024
+ "contentId": "4414f9c82c6d04ad49d7446f4b0740055242f425ef5b00391d9c8c78c96c0f66",
13025
+ "rawSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104",
13026
+ "normalizedSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104",
13027
+ "canonicalSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104"
13028
+ },
13029
+ "dev/rules/agent-governance.md": {
13030
+ "state": "present",
13031
+ "contentId": "5a0d043130825f68dc53329450c5101c3b595bd2675e70b731a29309b4394415",
13032
+ "rawSha256": "98a7f5805783bf98b446c3ef29f019d53a9b9d51fd15f401ea91daab2f708860",
13033
+ "normalizedSha256": "98a7f5805783bf98b446c3ef29f019d53a9b9d51fd15f401ea91daab2f708860",
13034
+ "canonicalSha256": "98a7f5805783bf98b446c3ef29f019d53a9b9d51fd15f401ea91daab2f708860"
13035
+ },
13036
+ "dev/rules/release.md": {
13037
+ "state": "present",
13038
+ "contentId": "b0a0c9dea88016185f4093f9be4ce3c0e29904222e21dd1fa1735fcc1bb7e744",
13039
+ "rawSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7",
13040
+ "normalizedSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7",
13041
+ "canonicalSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7"
13042
+ },
13043
+ "dev/rules/knowledge.md": {
13044
+ "state": "present",
13045
+ "contentId": "e6f5795c7ebaba7b05f04d971b2942b5a0394a3babb44f64a1cc591c9a08cb86",
13046
+ "rawSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c",
13047
+ "normalizedSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c",
13048
+ "canonicalSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c"
13049
+ },
13050
+ "dev/rules/communication.md": {
13051
+ "state": "present",
13052
+ "contentId": "34fd0034cbc75dad43f789b86a414763f01916dda4d59876db9c4d8d92ae6a87",
13053
+ "rawSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591",
13054
+ "normalizedSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591",
13055
+ "canonicalSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591"
13056
+ },
13057
+ "dev/rules/closeout.md": {
13058
+ "state": "present",
13059
+ "contentId": "96e4faa5480f016a9e94f197004b2dd5ed5f0308f3e0b4a75cda53bff8fe1c6d",
13060
+ "rawSha256": "41881eea9bb9071f01b5c27e7b725c0c2fb7a60efe2cb9dfc5f234a66288ff05",
13061
+ "normalizedSha256": "41881eea9bb9071f01b5c27e7b725c0c2fb7a60efe2cb9dfc5f234a66288ff05",
13062
+ "canonicalSha256": "41881eea9bb9071f01b5c27e7b725c0c2fb7a60efe2cb9dfc5f234a66288ff05"
13063
+ },
13064
+ "dev/rules/onboarding.md": {
13065
+ "state": "present",
13066
+ "contentId": "3989b14439cd64894d9cad444e73e35d0a5c1c67e85991819111483d1df67124",
13067
+ "rawSha256": "ffd0f2337cf1f5998d94ede375af920a0f14e9662ee6b50ca8b568511ac9d5d8",
13068
+ "normalizedSha256": "ffd0f2337cf1f5998d94ede375af920a0f14e9662ee6b50ca8b568511ac9d5d8",
13069
+ "canonicalSha256": "ffd0f2337cf1f5998d94ede375af920a0f14e9662ee6b50ca8b568511ac9d5d8"
13070
+ },
13071
+ "dev/rules/integrations.md": {
13072
+ "state": "present",
13073
+ "contentId": "a8fc1099da28f511bf9fed5eaf629ca10fb409299b0aed4d233a45fc7701f284",
13074
+ "rawSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef",
13075
+ "normalizedSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef",
13076
+ "canonicalSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef"
13077
+ }
13078
+ }
13079
+ },
13080
+ "0.3.63": {
13081
+ "source": {
13082
+ "npm": {
13083
+ "spec": "@adamchanadam/agent-handoff-kit@0.3.63",
13084
+ "shasum": "80eed187e6595ada8b21cf960ec1063327a60598",
13085
+ "integrity": "sha512-nfH9C3g/MOkfkR3h7KwUKoLCR/+Dgutq0FqROphWa+b/H9wRq55hlfjOuhy3JBqp77BqaqxUTwYn2Srx70oYeA==",
13086
+ "entryCount": 34,
13087
+ "gitHead": "615bb98d3e2592226cabfb56aef29cff23a71707"
13088
+ },
13089
+ "git": {
13090
+ "tag": "v0.3.63",
13091
+ "directObject": "615bb98d3e2592226cabfb56aef29cff23a71707",
13092
+ "peeledCommit": null,
13093
+ "commit": "615bb98d3e2592226cabfb56aef29cff23a71707"
13094
+ },
13095
+ "githubRelease": {
13096
+ "tag": "v0.3.63",
13097
+ "publishedAt": "2026-08-24T07:46:06Z"
13098
+ },
13099
+ "sourceDivergence": {
13100
+ "status": "same-commit",
13101
+ "npmGitHead": "615bb98d3e2592226cabfb56aef29cff23a71707",
13102
+ "remoteTagCommit": "615bb98d3e2592226cabfb56aef29cff23a71707"
13103
+ }
13104
+ },
13105
+ "manifest": {
13106
+ "AGENTS.md": {
13107
+ "state": "present",
13108
+ "contentId": "acfc72978b5cda82d2cb4a34f63fa12dbf7024512215af5d33da3fdef72b0109",
13109
+ "rawSha256": "925d947e20b265f4d1e8514772e3da522cf7df18435f72ddcd591dd30c0faf8e",
13110
+ "normalizedSha256": "925d947e20b265f4d1e8514772e3da522cf7df18435f72ddcd591dd30c0faf8e",
13111
+ "canonicalSha256": "925d947e20b265f4d1e8514772e3da522cf7df18435f72ddcd591dd30c0faf8e"
13112
+ },
13113
+ "CLAUDE.md": {
13114
+ "state": "present",
13115
+ "contentId": "7a2cf08a1171762ebcb53f43036a2170655379416945258b9c85d4b189ecaecf",
13116
+ "rawSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad",
13117
+ "normalizedSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad",
13118
+ "canonicalSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad"
13119
+ },
13120
+ "GEMINI.md": {
13121
+ "state": "present",
13122
+ "contentId": "36da47034bb2ce6c760ddbbbbd49dccc1d17665dbb18bec56ffa3b26bac1c135",
13123
+ "rawSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986",
13124
+ "normalizedSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986",
13125
+ "canonicalSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986"
13126
+ },
13127
+ "START_NEXT_SESSION_PROMPT.txt": {
13128
+ "state": "present",
13129
+ "contentId": "de01669f2989762269e57b8f71decc55d58effa649a245136efa6dc1434b78a9",
13130
+ "rawSha256": "9918ce76f1a8c21554784c74190c5dadca0b2ddac0a4d58b67ca64465b2138c8",
13131
+ "normalizedSha256": "9918ce76f1a8c21554784c74190c5dadca0b2ddac0a4d58b67ca64465b2138c8",
13132
+ "canonicalSha256": "b1b9ad0cb5f3a374542a43b6c2c938e1e5d39dd42b91d12a4a74206f5f187113"
13133
+ },
13134
+ "dev/SESSION_HANDOFF.md": {
13135
+ "state": "present",
13136
+ "contentId": "54e20421bf99c389617d6cca9d3c8182bb836ed087a01c0ae98e55012ac393ea",
13137
+ "rawSha256": "edecac7162e12eb85d2a195a4a91eb3fee582ff1577d60c1fa9c0d8417de0ab0",
13138
+ "normalizedSha256": "edecac7162e12eb85d2a195a4a91eb3fee582ff1577d60c1fa9c0d8417de0ab0",
13139
+ "canonicalSha256": "fc4bf3ddddfa198a13d0ca610ad375a80fb79ec9ef9a7284da75f011969d1d94"
13140
+ },
13141
+ "dev/SESSION_LOG.md": {
13142
+ "state": "present",
13143
+ "contentId": "7b6184ee4dabe89f504a894c3d4803f012d962c7af53c7f29801a8fb28d9d51c",
13144
+ "rawSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47",
13145
+ "normalizedSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47",
13146
+ "canonicalSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47"
13147
+ },
13148
+ "dev/PROJECT_INDEX.md": {
13149
+ "state": "present",
13150
+ "contentId": "c7e652f64d5418bce302c5c96ef4afe56199d4ffa604b3db2283d26ba76d40dd",
13151
+ "rawSha256": "ad4c8da8a15190c750125f381bd9b4b1441e92f9fabc91048986c8fe3fb925a8",
13152
+ "normalizedSha256": "05f4a34e128d8e29accfebae256ab398b8ea574c59a755e3443d01229d0ab0ff",
13153
+ "canonicalSha256": "3e80b5332e0c2527bd653cb049ac0d40db651e1cdfa1fcb0900f23739e745266"
13154
+ },
13155
+ "dev/DOC_SYNC_REGISTRY.md": {
13156
+ "state": "present",
13157
+ "contentId": "f6545b524dc440d3563041e04a05caff4229863f6cae2a39127f85a29a120249",
13158
+ "rawSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6",
13159
+ "normalizedSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6",
13160
+ "canonicalSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6"
13161
+ },
13162
+ "dev/RULE_PACKS.md": {
13163
+ "state": "present",
13164
+ "contentId": "1b91985b9c6460b7bf4293cc6119097df9b426c3a46199a0a4f1de1712d02faa",
13165
+ "rawSha256": "383842f3d2f995a6f0917bb4a7bc6bfa5fd6e3c33ec8aa2cd073ce1695812df4",
13166
+ "normalizedSha256": "383842f3d2f995a6f0917bb4a7bc6bfa5fd6e3c33ec8aa2cd073ce1695812df4",
13167
+ "canonicalSha256": "383842f3d2f995a6f0917bb4a7bc6bfa5fd6e3c33ec8aa2cd073ce1695812df4"
13168
+ },
13169
+ "dev/PROJECT_DECISIONS.md": {
13170
+ "state": "present",
13171
+ "contentId": "3aae993bd5b85bf6b1d1d458f1bcf82c7d3105c843f053ffa13553bb5931b8c4",
13172
+ "rawSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e",
13173
+ "normalizedSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e",
13174
+ "canonicalSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e"
13175
+ },
13176
+ "dev/rules/safety.md": {
13177
+ "state": "present",
13178
+ "contentId": "dd6bcf74722d038f76d202e2044a6583a6e6ad107fbb010520e513eec799ff4a",
13179
+ "rawSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0",
13180
+ "normalizedSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0",
13181
+ "canonicalSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0"
13182
+ },
13183
+ "dev/rules/coding.md": {
13184
+ "state": "present",
13185
+ "contentId": "1c6deb9a5a281c13e97b0ac96079e9e1beccbd1ff106186e7a6ac78c0eeb75c2",
13186
+ "rawSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4",
13187
+ "normalizedSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4",
13188
+ "canonicalSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4"
13189
+ },
13190
+ "dev/rules/writing.md": {
13191
+ "state": "present",
13192
+ "contentId": "ceee5412520ba860e6b40de46bb164e2ce3919d2197d5fadb926198eb7dddd3b",
13193
+ "rawSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593",
13194
+ "normalizedSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593",
13195
+ "canonicalSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593"
13196
+ },
13197
+ "dev/rules/research.md": {
13198
+ "state": "present",
13199
+ "contentId": "4414f9c82c6d04ad49d7446f4b0740055242f425ef5b00391d9c8c78c96c0f66",
13200
+ "rawSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104",
13201
+ "normalizedSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104",
13202
+ "canonicalSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104"
13203
+ },
13204
+ "dev/rules/agent-governance.md": {
13205
+ "state": "present",
13206
+ "contentId": "9fa50a5d18ebc762d239db85524a70b83f501aead4adff6c2fd38c7cb17caa72",
13207
+ "rawSha256": "84eee255e885726e540c105cb83287f9a661a1611e9264f08e5d803020eddd82",
13208
+ "normalizedSha256": "84eee255e885726e540c105cb83287f9a661a1611e9264f08e5d803020eddd82",
13209
+ "canonicalSha256": "84eee255e885726e540c105cb83287f9a661a1611e9264f08e5d803020eddd82"
13210
+ },
13211
+ "dev/rules/release.md": {
13212
+ "state": "present",
13213
+ "contentId": "b0a0c9dea88016185f4093f9be4ce3c0e29904222e21dd1fa1735fcc1bb7e744",
13214
+ "rawSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7",
13215
+ "normalizedSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7",
13216
+ "canonicalSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7"
13217
+ },
13218
+ "dev/rules/knowledge.md": {
13219
+ "state": "present",
13220
+ "contentId": "e6f5795c7ebaba7b05f04d971b2942b5a0394a3babb44f64a1cc591c9a08cb86",
13221
+ "rawSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c",
13222
+ "normalizedSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c",
13223
+ "canonicalSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c"
13224
+ },
13225
+ "dev/rules/communication.md": {
13226
+ "state": "present",
13227
+ "contentId": "34fd0034cbc75dad43f789b86a414763f01916dda4d59876db9c4d8d92ae6a87",
13228
+ "rawSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591",
13229
+ "normalizedSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591",
13230
+ "canonicalSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591"
13231
+ },
13232
+ "dev/rules/closeout.md": {
13233
+ "state": "present",
13234
+ "contentId": "96e4faa5480f016a9e94f197004b2dd5ed5f0308f3e0b4a75cda53bff8fe1c6d",
13235
+ "rawSha256": "41881eea9bb9071f01b5c27e7b725c0c2fb7a60efe2cb9dfc5f234a66288ff05",
13236
+ "normalizedSha256": "41881eea9bb9071f01b5c27e7b725c0c2fb7a60efe2cb9dfc5f234a66288ff05",
13237
+ "canonicalSha256": "41881eea9bb9071f01b5c27e7b725c0c2fb7a60efe2cb9dfc5f234a66288ff05"
13238
+ },
13239
+ "dev/rules/onboarding.md": {
13240
+ "state": "present",
13241
+ "contentId": "6967a95f2256bc7962cd7f0b2b63249a2537979fe0d8bafd49ef620db873cae4",
13242
+ "rawSha256": "0c416732ae67c7dd3bfd2f27fbb763a940e6248ce8a23e42d8b897db8380d9ce",
13243
+ "normalizedSha256": "0c416732ae67c7dd3bfd2f27fbb763a940e6248ce8a23e42d8b897db8380d9ce",
13244
+ "canonicalSha256": "0c416732ae67c7dd3bfd2f27fbb763a940e6248ce8a23e42d8b897db8380d9ce"
13245
+ },
13246
+ "dev/rules/integrations.md": {
13247
+ "state": "present",
13248
+ "contentId": "a8fc1099da28f511bf9fed5eaf629ca10fb409299b0aed4d233a45fc7701f284",
13249
+ "rawSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef",
13250
+ "normalizedSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef",
13251
+ "canonicalSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef"
13252
+ }
13253
+ }
12904
13254
  }
12905
13255
  },
12906
13256
  "contents": {
@@ -13773,7 +14123,42 @@
13773
14123
  "targetRel": "dev/rules/closeout.md",
13774
14124
  "canonicalSha256": "e21b0885f3a9b971bd05bdb54e07966ab72eff33bd84242a7c218f9cf6da1f6f",
13775
14125
  "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- 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\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. The semantic lifecycle gate is `agent-handoff-kit closeout-status`; when it blocks, use its first `Resolved [...]` / `Carry-forward [...]` pair to repair the handoff, not a separate project workaround, repeated doctor runs, or a broader governance rewrite. 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. 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. Record the actual root, Git root, branch, commit, worktrees / parallel workspaces, uncommitted changes, and unresolved drift. Do not clean or change them without separate authorization.\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 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## 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"
14126
+ },
14127
+ "5b237785d450112d8b3d58cd6363a7b4d9885d3d25da62285c8f11724b5a2a0e": {
14128
+ "targetRel": "AGENTS.md",
14129
+ "canonicalSha256": "7f57c38458c779cfa4450930a05af99efdffb9f7f29d6975bdf036530c1a6af7",
14130
+ "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\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, one optional display-only current-thread title update 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\nDuring explicit continuity startup, the only optional presentation effect beyond state recovery and card/status is a user-visible task/conversation title update, when the active runtime safely supports current-thread title control. Current-title readback is useful when available to avoid overwriting an already informative title, but it is not required when the tool safely targets the calling/current thread. If title control is exposed only through a bounded runtime tool-discovery mechanism, use that discovery once with a narrow title/rename/current-thread query before deciding the control is unavailable; then call only the discovered safe current-thread title tool. Do not list or inspect unrelated threads solely for naming, and do not create, fork, navigate, message, archive, pin, or otherwise manage tasks as part of startup title naming. Do not title from the raw continuity trigger or before handoff-derived startup facts are final. First derive the startup card's current objective, risk/boundary, and recommended next action; then choose and apply any title update as the last presentation side effect before returning the startup response. Replace only a generic or stale title, or update once when the main objective clearly changes; keep an informative title when readback proves it is already relevant, and do not rename for tests, reviews, or small substeps. Use `<project name>|<primary action>` from facts already loaded for startup: a concrete same-message task first, otherwise the loaded current objective plus recommended next action. Within those facts, select one concrete primary action in this order: the same-message task; the loaded current objective; the recommended next action. The continuity trigger itself and generic phrases such as `Start Agent Handoff`, `開工`, `開始交接工作`, or `開始工作交接` are not primary actions. If the loaded facts do not provide both a concrete project name and a concrete primary action, skip the title update. Do not read `dev/PROJECT_INDEX.md`, files, network, or other state solely to name the title. The title must not contain progress, completion, status, task/session IDs, absolute paths, secrets, or unverified facts. If safe current-thread title control is unavailable after the bounded discovery above, skip silently. The title is display-only; it is not project state, permission, progress, completion evidence, a health result, or a source of truth, and it does not authorize project/file writes, network activity, external task work, 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>\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- 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 regenerate the startup mirror or perform full closeout.\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\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. 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. 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 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=78b6aecdca148876697ca31eb5eeafa19141dec960f35a25ade6b55449e02e2d -->\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"
14131
+ },
14132
+ "c7e652f64d5418bce302c5c96ef4afe56199d4ffa604b3db2283d26ba76d40dd": {
14133
+ "targetRel": "dev/PROJECT_INDEX.md",
14134
+ "canonicalSha256": "3e80b5332e0c2527bd653cb049ac0d40db651e1cdfa1fcb0900f23739e745266",
14135
+ "text": "# Project Index\n\nPurpose: give a stateless AI a compact map of the project before it reads or edits files.\n\n## Stack\n\n| Field | Value | Last verified |\n|---|---|---|\n| Agent Handoff Kit template version | <VERSION> | current template version |\n| Runtime | TBD | TBD |\n| Framework | TBD | TBD |\n| Package manager | TBD | TBD |\n| Test command | TBD | TBD |\n| Build command | TBD | TBD |\n| Deploy command | TBD | TBD |\n\n## Directory Map\n\n| Path | Role | Read when |\n|---|---|---|\n| `AGENTS.md` | primary Agent Handoff Kit entry and startup contract | session startup |\n| `CLAUDE.md` | Claude Code bridge to the same startup path | Claude Code startup |\n| `GEMINI.md` | Google Antigravity CLI / Gemini CLI migration bridge to the same startup path | Antigravity / Gemini startup |\n| `START_NEXT_SESSION_PROMPT.txt` | portable generated mirror of the handoff opening-message block; `dev/SESSION_HANDOFF.md` remains authoritative | fallback when the next agent is not yet operating in this root; not an additional local startup read |\n| `src/` | application source | coding task |\n| `tests/` | tests | coding/QC |\n| `docs/` | user or product docs | doc/public behavior change |\n| `dev/` | governance state | read the handoff at startup; other files are task-routed or closeout-routed |\n| `dev/rules/closeout.md` | full closeout contract | clear end-of-session or handoff intent only |\n| `TBD` | local source-of-truth files | before tasks that depend on project facts |\n| `TBD` | external-source indexes or mirrors | before research, writing, or knowledge-sync tasks |\n\n## Entry Points\n\n| Entry | Path | Notes |\n|---|---|---|\n| App entry | TBD | TBD |\n| Main config | TBD | TBD |\n| Test suite | TBD | TBD |\n| Runbook | TBD | TBD |\n| Public docs | TBD | TBD |\n| Durable artifact review | `dev/PROJECT_INDEX.md` + `dev/DOC_SYNC_REGISTRY.md` | After creating docs, generated outputs, specs, runbooks, checklists, research notes, or other durable artifacts, classify each file as indexed / synced / temporary / one-time evidence before completion; doctor validates explicit Kit contracts and formal typed user-rule paths only, not arbitrary project artifacts |\n\n## Fact Base\n\nReachable means the source can be found. It does not mean the source has been read in this session.\n\n| Source | Role | Required before | Access method | Last verified |\n|---|---|---|---|---|\n| TBD | local source of truth / reference / draft / archive | TBD | path or instruction | TBD |\n\n## External Sources\n\n| Source | Role | Required before | Access method | `via` | Write-back rule | Last verified |\n|---|---|---|---|---|---|---|\n| TBD | source of truth / mirror / index / attachment store | TBD | URL, connector, or manual packet | `Notion Connector` / `Google Drive Connector` / `manual paste` / etc — must match an entry under `## Installed Integrations` | read-back required / manual only / no write | TBD |\n\n> `via` column discipline: every External Sources row must reference an entry name under `## Installed Integrations`, such as `Notion Connector` or `Google Drive Connector`, so the access path is explicit. Sources without a declared integration use `manual paste`. Doctor and release QA enforce cross-section consistency.\n\n## Installed Integrations\n\n> **Credential Separation Principle**: this section records only project usage and public reference coordinates such as Notion database names, URLs, or folder paths. It must never record API keys, OAuth tokens, or credential values. Credentials belong in AI runtime secure storage, OS credential stores, tool configuration, or user-managed secret stores. If an environment variable is used, record only the variable name, never the value. Before writing this section, self-check that no credential value is being persisted. Doctor scans this section, `SESSION_HANDOFF`, and `SESSION_LOG` for common credential prefixes such as `sk-`, `ntn_`, `ya29.`, `xoxp-`, `ghp_`, `sl.`, `AKIA`, and `AIza`.\n\n> Purpose: tasks that use external tools read this section to understand declared capabilities and project roles. Declarations persist across sessions. A new session does not probe this table merely because it exists. `TBD`, examples, blanks, and placeholder-only rows are not installed integrations. Every real entry includes `Declared` and `Last Verified` so capability assumptions can be checked immediately before use.\n\n### Connectors\n\n| Tool | Project Usage | Access Scope | Specific Instance | Credential Reference (no value) | Declared | Last Verified |\n|------|---------------|--------------|-------------------|---------------------|----------|---------------|\n| TBD | TBD, for example an index of source paths or persistent reference storage | read / read+write | TBD, for example database name + URL or folder path | TBD, for example `AI tool secure storage` / `OS credential store` | TBD | TBD |\n\n### MCPs\n\n| Server | Source | Project Usage | Credential Reference (no value) | Declared | Last Verified |\n|--------|--------|---------------|---------------------|----------|---------------|\n| TBD | TBD, for example GitHub repository URL | TBD | TBD, for example `tool config + env var name only` / `user-managed secret store` | TBD | TBD |\n\n### Plugins\n\n| Name | Bundle Content (Skills + MCP + hooks) | When Triggered | Last Verified |\n|------|----------------------------------------|----------------|---------------|\n| TBD | TBD | TBD | TBD |\n\n### Skills\n\n| Name | Source | When Triggered | Last Verified |\n|------|--------|----------------|---------------|\n| TBD | TBD, for example plugin bundle or user-level install | TBD | TBD |\n\n### Source-of-truth Architecture\n\n> When a project uses several integrations as a source-of-truth system, for example Notion index + local primary sources + Google Drive reference mirror, this table records each layer's role so agents do not cross write boundaries.\n\n| Layer | Surface (specific instance) | Role | Write Direction |\n|-------|--------------------------|------|-----------------|\n| Source of truth | TBD, for example local `~/project/reference/` | Original auditable reference content | User-controlled placement; agent does not write directly unless explicitly authorized |\n| Index | TBD, for example Notion database `Project Index` | Metadata, summaries, and tags for each source file | Agent may read/write through a verified Connector |\n| Persistent mirror | TBD, for example Drive folder `Project Reference/` | Backup or cross-device reference mirror | User-controlled sync by default; agent does not push automatically |\n| Working draft | TBD, for example local `~/project/output/` | Agent task output | Agent may read and write local files under normal safety rules |\n\n## Tool Operation References\n\nUse this section for project-local runbooks or verified procedures for runtime-controlled tools such as browser validation, screenshots, DevTools, Playwright, crawlers, notebooks, desktop app automation, MCP/plugin helpers, or raw CLI/SDK operations.\n\nDo not store credential values or machine-private paths here. Local machine-only references may be listed only when the project explicitly depends on them, and the scope / limits must say they are not portable.\n\n| Tool / operation | Reference path or URL | Required before | Source and version/date | Scope and known limits | Last verified |\n|---|---|---|---|---|---|\n| TBD | TBD | TBD | TBD | TBD | TBD |\n| Local HTML / app browser validation | TBD, for example project runbook or official browser-tool docs | Before validating local HTML, static app, generated guide, screenshot, click flow, or visual QA | TBD, include source and date | Prefer short-lived loopback localhost service when `file://` is blocked; record click/text/screenshot evidence and cleanup result; do not mutate user browser profiles or extension state | TBD |\n\n## Local QC Commands\n\n| Check | Command | Run before | Last verified |\n|---|---|---|---|\n| Agent Handoff Kit doctor | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .` | closeout / Kit contract health / explicit registered-path checks | package latest |\n| Agent Handoff Kit workspace health | `npx --yes @adamchanadam/agent-handoff-kit@latest workspace-health --root .` | closeout workspace identity read-back / suspected wrong root or worktree drift | package latest |\n| Project governance check | Check newly created durable artifacts against `dev/PROJECT_INDEX.md` and `dev/DOC_SYNC_REGISTRY.md`; register, sync, consolidate, or explicitly classify as temporary / one-time evidence. This is an AI responsibility, not a root-discovery doctor scan. | closeout / durable file changes | unverified until project-specific command exists |\n\n## Workspace Identity\n\nRecord the last closeout snapshot here so the next AI can detect wrong-root or workspace drift. Live root / Git / worktree truth is read with `agent-handoff-kit workspace-health --root <project root>` or equivalent read-only Git probes; do not maintain a long-term dynamic worktree list here.\n\n| Field | Value | Last verified |\n|---|---|---|\n| Expected project root | TBD | TBD |\n| Git root | TBD | TBD |\n| Branch / commit | TBD | TBD |\n| Worktree or parallel workspace | TBD | TBD |\n| Uncommitted change summary | TBD | TBD |\n\n## Change Hotspots\n\n| Change type | Likely files | Required checks |\n|---|---|---|\n| API behavior | TBD | tests + docs sync |\n| UI behavior | TBD | build + visual/manual check |\n| Data model | TBD | migration/checks |\n| Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |\n| Durable artifacts | docs, generated outputs, project-specific reference folders, specs, runbooks, checklists, research notes | classify as indexed / synced / temporary / one-time evidence when created or modified by the AI; update `dev/PROJECT_INDEX.md` or `dev/DOC_SYNC_REGISTRY.md` when durable |\n| Closeout/startup contract | `AGENTS.md`, `dev/rules/closeout.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | hot-path reads stay minimal; lifecycle state agrees; log has no full prompt; prompt mirror regenerated from handoff at closeout |\n\n## External Services\n\n| Service | Scope | Verification source | Last verified |\n|---|---|---|---|\n| TBD | TBD | TBD | TBD |\n\n## Maintenance Rule\n\nUpdate this file when stack, commands, directory roles, entry points, external services, runtime-controlled tool operation references, workspace identity, durable runbooks, or governance file map changes.\n"
14136
+ },
14137
+ "96e4faa5480f016a9e94f197004b2dd5ed5f0308f3e0b4a75cda53bff8fe1c6d": {
14138
+ "targetRel": "dev/rules/closeout.md",
14139
+ "canonicalSha256": "41881eea9bb9071f01b5c27e7b725c0c2fb7a60efe2cb9dfc5f234a66288ff05",
14140
+ "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- 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\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. The semantic lifecycle gate is `agent-handoff-kit closeout-status`; when it blocks, use its first `Resolved [...]` / `Carry-forward [...]` pair to repair the handoff, not a separate project workaround, repeated doctor runs, or a broader governance rewrite. 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. 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## 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"
14141
+ },
14142
+ "acfc72978b5cda82d2cb4a34f63fa12dbf7024512215af5d33da3fdef72b0109": {
14143
+ "targetRel": "AGENTS.md",
14144
+ "canonicalSha256": "925d947e20b265f4d1e8514772e3da522cf7df18435f72ddcd591dd30c0faf8e",
14145
+ "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\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, one optional display-only current-thread title update 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\nDuring explicit continuity startup, the only optional presentation effect beyond state recovery and card/status is a user-visible task/conversation title update, when the active runtime safely supports current-thread title control. Current-title readback is useful when available to avoid overwriting an already informative title, but it is not required when the tool safely targets the calling/current thread. If title control is exposed only through a bounded runtime tool-discovery mechanism, use that discovery once with a narrow title/rename/current-thread query before deciding the control is unavailable; then call only the discovered safe current-thread title tool. Do not list or inspect unrelated threads solely for naming, and do not create, fork, navigate, message, archive, pin, or otherwise manage tasks as part of startup title naming. Do not title from the raw continuity trigger or before handoff-derived startup facts are final. First derive the startup card's current objective, risk/boundary, and recommended next action; then choose and apply any title update as the last presentation side effect before returning the startup response. Replace only a generic or stale title, or update once when the main objective clearly changes; keep an informative title when readback proves it is already relevant, and do not rename for tests, reviews, or small substeps. Use `<project name>|<primary action>` from facts already loaded for startup: a concrete same-message task first, otherwise the loaded current objective plus recommended next action. Within those facts, select one concrete primary action in this order: the same-message task; the loaded current objective; the recommended next action. The continuity trigger itself and generic phrases such as `Start Agent Handoff`, `開工`, `開始交接工作`, or `開始工作交接` are not primary actions. If the loaded facts do not provide both a concrete project name and a concrete primary action, skip the title update. Do not read `dev/PROJECT_INDEX.md`, files, network, or other state solely to name the title. The title must not contain progress, completion, status, task/session IDs, absolute paths, secrets, or unverified facts. If safe current-thread title control is unavailable after the bounded discovery above, skip silently. The title is display-only; it is not project state, permission, progress, completion evidence, a health result, or a source of truth, and it does not authorize project/file writes, network activity, external task work, 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>\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- 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 regenerate the startup mirror or perform full closeout.\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\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. 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. 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 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=85e53d73f3080c03010ca68bf166173b1024445811851785a752668097ec6cb4 -->\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"
14146
+ },
14147
+ "1b91985b9c6460b7bf4293cc6119097df9b426c3a46199a0a4f1de1712d02faa": {
14148
+ "targetRel": "dev/RULE_PACKS.md",
14149
+ "canonicalSha256": "383842f3d2f995a6f0917bb4a7bc6bfa5fd6e3c33ec8aa2cd073ce1695812df4",
14150
+ "text": "# Rule Packs Router\n\nRead only the packs needed for the current task.\n\n| Task signal | Pack | Purpose |\n|---|---|---|\n| Clear end-of-session or handoff intent: \"收工\" / \"wrap up\" / \"closeout\" / \"handoff\" / \"Wrap up Agent Handoff\", including closeout plus a handoff instruction | `dev/rules/closeout.md` | <!-- ack:route:closeout --> full closeout, lifecycle reconciliation, maintenance triggers, prompt regeneration, read-back, and honest stop conditions |\n| Explicit onboarding requests: \"I'm new\" / \"new user\" / \"teach me\" / \"help me start\" / \"how do I start\" / \"show me how\" / \"getting started\" / \"what can agent handoff kit do\"; or genuinely unresolved intent after current state has been read. Also recognize equivalent Chinese phrases such as \"新手\", \"教我用\", \"點開始\", and \"能力\". A fresh install with `First-use guidance state: eligible` enters onboarding when no executable objective remains; upgrade never resets consumed / not_applicable first-use state. `Start Agent Handoff` / \"開工\" is continuity. Capability / teaching answers must surface normal-language public command categories instead of reducing the help answer to CLI maintenance commands. | `dev/rules/onboarding.md` | <!-- ack:route:onboarding --> infer when sufficient and begin a concrete task directly; ask one concise question or offer guided scenarios only when the user requests guidance or first-use state is eligible with no executable objective |\n| Destructive file operations, shell writes, Git state changes, package managers, installers, deploy, release, cloud tools, external APIs, credentials, locked files, permission errors | `dev/rules/safety.md` | safety checks for data loss, external systems, secrets, and high-risk operations |\n| Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |\n| Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |\n| Sources, evidence, comparison, fact finding | `dev/rules/research.md` | source handling and uncertainty |\n| Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |\n| Governance bridge / bridge governance / connect this document to governance / scan for unbridged governance documents. Also recognize equivalent Chinese user phrases such as \"治理打通\", \"把文件接入 Agent Handoff Kit\", \"接入 Agent Handoff Kit\", and \"掃描未接入 Agent Handoff Kit 的重要文件\". | `dev/rules/agent-governance.md` | <!-- ack:route:governance-bridge --> connect important files, source-of-truth documents, runbooks, workflows, checklists, and guides to the project index, sync registry, handoff/log roles, and related workflows without creating duplicate sources of truth |\n| Long-term governance routing / future sessions should remember / always use this API or MCP pattern. Also recognize equivalent Chinese user phrases such as \"寫入長期治理\", \"轉成長期機制\", \"之後都要遵守\", and \"跨 session 有效\". | `dev/rules/agent-governance.md` | <!-- ack:route:long-term-governance --> classify durable non-file knowledge by role and store it in the right home: rule pack, registered reference, project index, sync registry, project decisions, or QA check; do not leave reusable governance only in session log or handoff |\n| Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |\n| External notes, knowledge base, Notion, Obsidian, Google Drive | `dev/rules/knowledge.md` | external knowledge source integration |\n| A task that actually uses an external Connector / MCP / Plugin / Skill; a handoff that declares one as a current-task dependency; or an explicit integration health check | `dev/rules/integrations.md` | <!-- ack:route:integration-use --> capability verification immediately before use, credential separation, source-of-truth boundaries, fallback, and cross-session resilience; registry placeholders alone do not load or probe |\n| Runtime-controlled tool operation / browser UI validation / visual QA / screenshot / local HTML validation / file:// blocked / `file://` blocked / localhost fallback / Chrome / Playwright / DevTools / desktop app automation / crawler or scraper / notebook or data runtime / raw CLI, SDK, tool server, MCP, plugin, or local helper operation | `dev/rules/integrations.md` + `dev/rules/safety.md` (add `dev/rules/coding.md` only when changing code, tests, or project scripts) | <!-- ack:route:runtime-tool --> verify the active runtime capability, current schema, official docs, or registered tool operation reference before invocation; for local HTML / app validation, a blocked `file://` surface must route to a registered operation reference or short-lived localhost fallback before declaring blocked; preserve ownership and cleanup boundaries |\n| External tool resource pressure / stale MCP process / plugin service leak / browser automation left running / cache growth after external tools / slowdown after MCP, plugin, browser, crawler, notebook, or local helper services | `dev/rules/integrations.md` + `dev/rules/safety.md` | <!-- ack:route:resource-closeout --> ownership-based external-tool resource closeout; task-owned cleanup allowed; shared or ambiguous remediation requires exact evidence and confirmation |\n| Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |\n\n## Routing Rule\n\nLoad the minimum set. If uncertain, load the narrower pack first. Pack selection is normally silent; state it only when it changes risk or user action. If a task clearly involves safety risk plus another domain, load `dev/rules/safety.md` with the relevant domain pack. Packs can add stricter rules, but cannot weaken core safety or continuity.\n"
14151
+ },
14152
+ "9fa50a5d18ebc762d239db85524a70b83f501aead4adff6c2fd38c7cb17caa72": {
14153
+ "targetRel": "dev/rules/agent-governance.md",
14154
+ "canonicalSha256": "84eee255e885726e540c105cb83287f9a661a1611e9264f08e5d803020eddd82",
14155
+ "text": "# Agent Governance Pack\n\n## Scope\n\nUse for governance rules, prompts, agent instructions, handoff systems, startup/closeout behavior, skills, and rule packs.\n\n## Load When\n\n- User asks to change AI behavior, project governance, prompts, handoff, startup, closeout, or tool-use rules.\n- A change affects `AGENTS.md`, `dev/*`, rule packs, installer templates, or durable workflow docs.\n- User asks to bridge governance, connect a document to governance, scan for unbridged governance documents, or uses equivalent Chinese phrases such as \"治理打通\", \"把文件接入 Agent Handoff Kit\", \"接入 Agent Handoff Kit\", or \"掃描未接入 Agent Handoff Kit 的重要文件\".\n- User asks to make something long-term, cross-session, reusable, future sessions should remember an API / MCP / tool-use pattern, or uses equivalent Chinese phrases such as \"寫入長期治理\", \"轉成長期機制\", or \"之後都要遵守\".\n- The task creates or materially changes Markdown documents, generated outputs, specifications, runbooks, checklists, guides, source-of-truth files, or research artifacts that future agents may need to discover.\n\n## Rules\n\n1. Locate the existing source of truth before adding a rule.\n2. Prefer merge, replace, or registry rows over append-only rule growth.\n3. Keep public runtime rules generic; project-specific incidents belong in logs, runbooks, or project index.\n4. Do not let development-only workspace rules enter public runtime.\n5. Check complexity budget before adding default-core behavior.\n6. 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.\n7. 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 `runtime-core/AGENTS.core.md` persistence gate decision; do not duplicate the gate thresholds in this pack.\n8. For long-running projects, maintain `dev/PROJECT_DECISIONS.md` per R-028 closeout discipline (see `runtime-core/AGENTS.core.md` closeout 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.\n9. 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.\n10. 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.\n11. 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.\n12. New Markdown or generated documents are not automatically harmless. After creating or materially changing them, classify each artifact before completion: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary. Durable artifacts must be discoverable from `dev/PROJECT_INDEX.md` or intentionally tied to a registered sync / source-of-truth row. Temporary or one-time evidence must be labeled as such in the task record or closeout so future agents do not treat it as hidden current state.\n13. Do not create a new document to hold a rule, requirement, checklist, or process if an existing authoritative document can carry it. Merge into the existing home or make the new document explicitly subordinate. If two files now carry the same durable instruction, resolve the duplicate by choosing one authoritative home and pointing the other to it.\n\n## Governance Bridge Workflow\n\nUse this workflow when the user asks for governance bridge, connect this document to governance, asks to scan for unbridged governance documents, or uses equivalent Chinese phrases such as \"治理打通\", \"把文件接入 Agent Handoff Kit\", \"接入 Agent Handoff Kit\", or \"掃描未接入 Agent Handoff Kit 的重要文件\".\n\n1. Identify the target. If the user named a file, inspect that file and its surrounding directory. If no file is named, run a bounded repo scan for likely durable documents such as source-of-truth files, runbooks, workflows, guides, checklists, stock lists, production guides, and rules.\n2. Check the target file itself: it should state its role, scope, update trigger, owner or responsible workflow when known, and what must not be inferred from it.\n3. Check `dev/PROJECT_INDEX.md`: the file should be discoverable with its role and \"read when\" condition. Source-of-truth or reference files should appear in Fact Base, External Sources, Directory Map, Entry Points, or another existing indexed home that fits the project.\n4. Check `dev/DOC_SYNC_REGISTRY.md`: future same-type changes should have a matching change type or an explicit reason no durable sync rule is needed.\n5. Check related workflows, guides, runbooks, or rule packs: if a process creates or updates the file, that process should say when to update the file or its index row.\n6. Check `dev/SESSION_HANDOFF.md`: only current state, recommended next action with reason, unresolved risk, blocker, or a startup-needed fact should be in handoff. Do not copy whole documents or old evidence into handoff.\n7. Check `dev/SESSION_LOG.md`: this session's bridge review, validation, and evidence can be logged when it affects future action, but log entries must not become current state.\n8. Search for duplicate source-of-truth risk. If another file has the same durable role, recommend merge, reference, or retire options; do not delete, rename, or move files without explicit approval.\n\nFor repo-wide scans, report candidates as candidates. Do not fail ordinary docs merely because they are not indexed; only durable files that future agents need to discover, update, or distinguish from drafts should be bridged.\n\nOutput format:\n\n- Status: bridged / partially bridged / unbridged / blocked.\n- Use bridged only when every applicable governance link is present. If only `dev/PROJECT_INDEX.md` or `dev/SESSION_LOG.md` was updated, report partially bridged.\n- Already bridged: list the governance links that are present.\n- Gaps: list missing links and why they matter for the next agent.\n- Not applicable: list skipped layers with a reason.\n- Suggested patches: list exact files and sections to update.\n- Manual decisions: list duplicates, naming choices, deletion, renaming, external sync, or ownership questions requiring user confirmation.\n- Acceptance: give one concrete check that proves the bridge is complete.\n\n## Generated Artifact Governance Workflow\n\nUse this workflow whenever the current task creates or materially changes Markdown documents or other durable artifacts, even if the user did not explicitly ask for governance bridge.\n\n1. List the artifacts created or materially changed in this task.\n2. Classify each artifact: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary.\n3. For source-of-truth, reference, runbook, workflow, checklist, public document, and reusable generated output, update `dev/PROJECT_INDEX.md` so the file is discoverable with a role and read condition.\n4. For artifacts that require future mirror, external index, publication, or repeated sync, update `dev/DOC_SYNC_REGISTRY.md` or record why no durable sync rule applies.\n5. For one-time evidence, draft, or temporary files, record that classification in `dev/SESSION_LOG.md` or the task summary, and do not promote it to current handoff unless it affects the next action.\n6. Search for duplicate source-of-truth risk before keeping a new document. If another file already owns the same rule, requirement, checklist, or process, merge into that file or make the new document explicitly subordinate.\n7. Before claiming completion, explicitly confirm the artifacts created or materially changed in this task have been classified, indexed, synchronized, consolidated, or marked temporary through the steps above. Existing target-authority documents that only received a local content edit normally need read-back and task-specific validation, not a handoff / log write or a bundled doctor run. You may run the available project governance check and `agent-handoff-kit doctor` only for scoped Kit / typed registered-surface checks; doctor does not discover unregistered ordinary workspace files and cannot replace explicit changed-artifact review.\n\n## Long-term Governance Routing\n\nUse this workflow when the user asks to write something into long-term governance, turn an experience into a mechanism, make a rule apply across sessions, or when the content itself clearly has durable force.\n\n1. Classify the knowledge before writing:\n - Current task contract changes, including product goals, requirements, development checklists, acceptance rules, exclusions, priorities, or scope -> the existing authoritative spec / backlog / issue / runbook when one exists; otherwise `dev/SESSION_HANDOFF.md` current-state sections.\n - Current task state, recommended next action with reason, unresolved risk, or startup-needed fact -> `dev/SESSION_HANDOFF.md`.\n - Chronological evidence or validation trace -> `dev/SESSION_LOG.md`.\n - File maps, command maps, API reference locations, tool capability maps, and external source coordinates -> `dev/PROJECT_INDEX.md`.\n - Sync obligations or external mirror duties -> `dev/DOC_SYNC_REGISTRY.md`.\n - Durable decisions, architecture trade-offs, research-derived rationale, and long-term lessons -> `dev/PROJECT_DECISIONS.md`.\n - Reusable procedures, recurring mistake prevention, API / MCP / tool-use rules -> the relevant rule pack, registered reference, or QA check.\n - API / MCP / tool-use patterns -> project index / registered reference / integrations pack, depending on scope.\n2. If the knowledge is reusable but no existing home fits, propose the smallest new registered reference or rule-pack patch. New runbooks remain last resort.\n3. If the knowledge was first captured in `SESSION_LOG` or handoff for short-term continuity, promote it to the correct durable home before claiming it is long-term.\n4. Add or update a QA check when the same failure class could recur and can be tested.\n5. Repeat-failure escalation: when the same failure class recurs after an AI has already claimed a durable fix for that class, do not continue with another same-pattern patch as ordinary work. Limit the escalation to the affected domain: identify the authoritative owner, correct or remove the failed method there, add a counterexample or replay check that would have failed before the fix when feasible, and state the temporary constraint. If the failure recurs again after that root-fix validation, separate the change and validation roles where the runtime provides an independent reviewer, subagent, or fresh-context pass; when none is available, perform a fresh read-back pass against the replay check and mark independent review unavailable instead of blocking unrelated work. Restore normal flow as soon as the replay and review / read-back pass. Do not create a central penalty database, cross-project blacklist, permanent role split, or public rule carrying project-specific incident details.\n6. Keep governance bridge wording reserved for document orphan prevention. Do not relabel non-file governance as \"file connected to Agent Handoff Kit\".\n\n## Checks\n\n- Verify affected files are indexed or intentionally installed templates.\n- Check `dev/DOC_SYNC_REGISTRY.md` for governance, closeout/startup, and README sync rows.\n- Confirm old overlapping wording was retired or marked legacy.\n- Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.\n- Confirm every Markdown document or generated artifact created in this task is indexed, synced, consolidated, or explicitly classified as draft / temporary / one-time evidence.\n- Confirm no new file has become a parallel source for an existing rule, requirement, checklist, or process.\n- Confirm reusable operating procedure knowledge is not stored only in `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, or a decision narrative when it belongs in a pack or registered reference.\n- Confirm long-term governance knowledge is promoted out of `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, and `START_NEXT_SESSION_PROMPT.txt` when it should survive log archive or prompt regeneration.\n- Confirm repeat-failure escalation, when triggered, is limited to the affected domain, tied to the authoritative owner, backed by a counterexample or replay check when feasible, and does not create a central penalty store, cross-project blacklist, or permanent role split.\n- For governance bridge work, confirm the target file, project index, sync registry, related workflow, handoff/log role split, and duplicate-source risk were all checked or explicitly marked not applicable.\n- For governance bridge work, run bounded searches for the target path/name and the relevant artifact class or sync-change type across the project index, sync registry, related workflows, and current rule owners. If the target is tied to generated outputs, also inspect the workflow or production guide that creates those outputs. Search evidence is a check, not a second source of truth.\n- Before claiming completion, apply the active root's core persistence gate and record the result only when that gate selects a checkpoint or full closeout; do not assume child or demo workspaces cover the parent/root workspace.\n- For long-running projects, confirm `dev/PROJECT_DECISIONS.md` retains its four H2 sections in order (Evolution Timeline / Decisions Archive / Architecture Choices / Insights & Learnings) and that the closeout maintenance trigger check was recorded, with full maintenance applied where its trigger conditions were met.\n\n## Closeout\n\nRecord the changed rule home, reason, complexity impact, retired wording, and follow-up checks.\n"
14156
+ },
14157
+ "6967a95f2256bc7962cd7f0b2b63249a2537979fe0d8bafd49ef620db873cae4": {
14158
+ "targetRel": "dev/rules/onboarding.md",
14159
+ "canonicalSha256": "0c416732ae67c7dd3bfd2f27fbb763a940e6248ce8a23e42d8b897db8380d9ce",
14160
+ "text": "# Onboarding Pack\n\n## Scope\n\nUse this transient pack for first-time Agent Handoff Kit users after a fresh install, users who request guidance, or when the user's first-task intent remains genuinely unresolved after reading the available project state.\n\nThe goal is to help the user complete a small first task without requiring them to read README, guide pages, `AGENTS.md`, or internal Kit rules first. After the onboarding walk-through finishes, unload this pack and continue with the regular scenario pack such as coding, research, writing, knowledge, or integrations.\n\n## Load When\n\n### Explicit onboarding signal keywords\n\nLoad this pack when the user message contains an onboarding signal such as:\n\n- \"I'm new\" / \"new user\"\n- \"teach me\" / \"help me start\" / \"help me get started\"\n- \"first time\" / \"first-time\" when the user also asks for guidance\n- \"how do I start\" / \"show me how\" / \"getting started\"\n- \"what can agent handoff kit do\"\n- vague project intent such as \"I want to do a project\"\n- equivalent Chinese user phrases such as \"新手\", \"教我用\", \"點開始\", \"能力\", or \"能做甚麼\"\n\n`I just installed` / \"我剛安裝\" is a first-use signal. When `SESSION_HANDOFF` says `First-use guidance state: eligible` and no executable objective remains, load this pack and give the first-use welcome. It does not override a same-message concrete task with enough material facts.\n\n### Continuity startup boundary\n\n`Start Agent Handoff` / \"開工\" starts continuity and reads the minimum current handoff state; it is not an onboarding signal by itself. A plain startup normally stops after its status card and recommended next action; a loaded objective alone does not authorize work. First-use eligible plain startup is the exception: when the handoff says `First-use guidance state: eligible`, the active objective is empty / `TBD`, and the user did not provide a same-message concrete task, enter onboarding instead of ending status-only. A same-message concrete task may begin normally. Only when no executable objective remains after state reading should the AI ask one concise question or offer the guided onboarding path. Explicit requests such as \"新手,教我用\" enter onboarding directly.\n\n### Implicit signals\n\n- The first user message is short and still genuinely vague after available project state is read.\n- `SESSION_HANDOFF` first-use guidance state is `eligible`, Active Objective is empty / `TBD`, and the user has not supplied a concrete objective with enough material facts. This is the fresh-install welcome path and should not be skipped as an ordinary status-only startup.\n- The user asks a generic capability question instead of giving a concrete task.\n- The user appears unfamiliar with the workflow, for example asking what the AI should do rather than giving an objective.\n\n## Discipline\n\n### 1. Do not assume prior reading\n\nThe user may start directly from an AI conversation. Explain only the minimum needed for the current step. Do not teach internal file structure, pack names, release identifiers, maintenance rules, or implementation details unless the user asks.\n\n### 1.1 Public capability answer\n\nWhen the user asks \"教我用\", \"能力\", \"能做甚麼\", \"what can agent handoff kit do\", or an equivalent broad help question, answer in normal user language first. The main answer is what the user can say to an AI, not a CLI command list.\n\nStart broad help / capability answers with this display-only onboarding card in a fenced `text` block:\n\n```text\n /\\_/\\ Agent Handoff Kit\n ( o.o ) quick guide\n > ^ <\n```\n\nThe card is a brand affordance only. It must not claim `continuity ready`, `handoff saved`, a version, loaded state, doctor health, or that `SESSION_HANDOFF.md` has been read. Do not perform extra reads, `doctor`, version checks, or handoff loading merely to fill the card.\n\nCover these public command categories:\n\n- Daily continuity: say \"開工\" / \"Start Agent Handoff\" to resume, and \"收工\" / \"wrap up\" to save a handoff.\n- Keep important files connected: say \"把這份文件接入 Agent Handoff Kit,讓下次 AI 知道何時要讀、何時要更新。\" / \"Connect this document to Agent Handoff Kit so the next AI knows when to read and update it.\"\n- Find missing governance links: say \"掃描未接入 Agent Handoff Kit 的重要文件。\" / \"Scan for important documents not yet connected to Agent Handoff Kit.\"\n- Turn a recurring mistake into future practice: say \"把今次錯誤整理成日後工作規則,讓下次 AI 知道要怎樣避免。\" / \"Turn this mistake into a durable work rule for future sessions.\"\n- Keep an API / MCP / tool-use practice reusable: say \"以後都用這個 API 調用方式,之後開新對話也要沿用。\" / \"Use this API approach in future sessions too.\"\n- Declare external tools safely: say \"這個項目會用到這些外部工具,請記住哪些能直接使用,機密不要寫入項目文件。\" / \"Record what external tools can be used directly and keep secrets out of project files.\"\n- Finish a long external-tool task cleanly: say \"收工時請顯示外部工具資源收口結果:已關閉哪些本任務資源,哪些因歸屬不明而保留並列證據。\" / \"At wrap up, show the external-tool resource closeout.\"\n\nDo not make CLI maintenance commands the main onboarding answer. Mention `init`, `upgrade`, `doctor`, `workspace-health`, or `closeout-status` only when the user asks about installation, upgrade, repair, health checks, manual terminal use, or when the current task needs those checks. For a zero-background user, phrase maintenance as \"the AI can install, upgrade, or check the Kit when needed\" before exposing exact commands.\n\n### 2. Infer first; offer scenario choice only when needed\n\nInfer when sufficient; ask only when unresolved. Read the user's message together with the available handoff and project state before deciding whether a chooser is needed.\n\nWhen the user has already supplied a concrete, actionable objective and enough material facts, infer the closest working scenario, state the assumption briefly, load the regular task pack(s), and begin the first safe action. Do not require an A-F reply, repeat questions whose answers are already available, or reduce a concrete request to a generic minimum task.\n\nOnly show the scenario chooser when the user's intent remains genuinely unresolved or the user asks for guided onboarding. In that case, combine the startup card and chooser into one complete response. Do not print a partial startup card first or repeat the card.\n\nThis routing decision never removes a safety gate. High-risk, external, permission, cost, publishing, and irreversible actions still require the normal plan and explicit confirmation before execution.\n\nThe library contains six scenarios. Treat them as an internal inference library. When choices are genuinely required, show only the two or three most relevant options; use a short open question when no responsible shortlist can be inferred. Do not display all six merely because the library contains them.\n\n- **A. Build systems, tools, platforms, websites, or apps**: the user wants AI help to create or maintain a working project.\n- **B. Organize research or write a report**: the user has sources, notes, articles, presentations, or a report goal.\n- **C. Organize local files, Notion, Google Drive, or a knowledge base**: the user wants source, reference, mirror, and draft material kept clear.\n- **D. Learn to code**: the user is a technical beginner and wants a small guided exercise.\n- **E. Custom scenario**: the user has another goal.\n- **F. Review installed external tools and design governance**: the user already has Connectors, MCPs, Plugins, Skills, or browser / notebook / crawler tools and wants a safe operating model.\n\n### 3. Guided 5-step walk-through pattern\n\nUse this five-step path only after the user selects guided onboarding or when clarification is genuinely needed:\n\n1. Confirm project context: folder, existing material, current tools, source locations, and whether external tools are already connected.\n2. Explain in three plain points how Agent Handoff Kit helps this scenario.\n3. Ask for the first concrete task scope, offering at most two or three genuinely relevant options.\n4. Suggest one minimum viable task that can usually be completed in 10-15 minutes.\n5. Wait for user confirmation, then transition to the regular work loop.\n\n### 4. Ask only for missing information\n\nSkip any guided step already answered by the user or available project state. When a step is still needed, advance one step at a time and:\n\n- state what the AI will do,\n- state what the user needs to answer or confirm,\n- answer questions before continuing,\n- let the user skip or change the step.\n\n### 5. Keep the first task small\n\nThe first task should be a preview, a short draft, a small classification sample, a dry-run, or another bounded result. Do not begin with broad refactors, bulk file moves, publishing, deployment, or destructive operations.\n\n### 6. Transition after onboarding\n\nAfter the walk-through:\n\n- load the regular pack(s) for the chosen task,\n- unload this transient onboarding pack,\n- enter the PLAN -> READ -> CHANGE -> QC -> PERSIST work loop,\n- record the first-task scope in `SESSION_HANDOFF` when the persistence gate requires it.\n\n## Application Scenario Library\n\nEach scenario is a fallback guidance template, not a mandatory questionnaire. The model may skip answered steps, infer the route when evidence is sufficient, and adapt wording while preserving intent, tone, and safety boundaries.\n\n### Scenario A. Build systems, tools, platforms, websites, or apps\n\nStep A.1: ask for the project folder, current stack if known, whether git exists, and whether GitHub, Linear, Slack, Notion, Google Drive, or other external tools are connected.\n\nStep A.2: explain that Kit helps the AI remember project state across sessions, avoid silent risky commands, and record what changed at closeout.\n\nStep A.3: offer task choices such as fix a bug, add a feature, organize code, add tests, write README, or prepare a first commit.\n\nStep A.4: suggest a small first task, such as a short README section, one failing test investigation, or a dry-run plan.\n\nStep A.5: after confirmation, load the relevant coding / writing / safety packs and begin the normal work loop.\n\n### Scenario B. Organize research or write a report\n\nStep B.1: ask for the topic, existing source locations, intended reader, and whether Notion, Google Drive, or another source tool is connected.\n\nStep B.2: explain that Kit separates source evidence from inference, records source locations, and preserves progress across sessions.\n\nStep B.3: offer task choices such as outline sections, register sources, summarize one source, draft a subsection, or review an existing draft.\n\nStep B.4: suggest a small first task, such as a 5-7 heading outline with one sentence per section.\n\nStep B.5: after confirmation, load research / writing / knowledge packs and begin the normal work loop.\n\n### Scenario C. Organize local files, Notion, Google Drive, or a knowledge base\n\nStep C.1: ask what needs organizing: local folder, Notion database, Google Drive folder, or mixed sources. Ask which external tools are connected or unknown.\n\nStep C.2: explain that Kit separates source of truth, references, mirrors, and drafts, and that risky file operations require dry-run and confirmation.\n\nStep C.3: offer task choices such as scan and classify files, design a folder structure, draft a Notion schema, write a dry-run script, or align local references with an external index.\n\nStep C.4: suggest a small first task, such as classifying a bounded sample without moving files.\n\nStep C.5: after confirmation, load knowledge / safety / integrations packs as needed.\n\n### Scenario D. Learn to code\n\nStep D.1: ask which direction the user wants: small automation, web page, Python tool, Git / GitHub basics, or another beginner task. Ask whether any relevant tools are already installed.\n\nStep D.2: explain that Kit keeps learning progress across sessions, keeps risky operations explicit, and lets the user review each small change.\n\nStep D.3: offer one small exercise, such as a dry-run file renamer, a one-page HTML example, or a tiny Python script.\n\nStep D.4: keep the exercise small enough to explain line by line.\n\nStep D.5: after confirmation, load coding / safety packs and begin the normal work loop.\n\n### Scenario E. Custom scenario\n\nStep E.1: use any facts already provided, then ask only for missing information that materially affects the first safe action. Do not ask about technical comfort unless it changes the delivery approach.\n\nStep E.2: explain how Kit helps the chosen scenario using continuity, safety, and source / artifact governance.\n\nStep E.3: offer task choices tailored to the user's answer.\n\nStep E.4: suggest one minimum viable first task.\n\nStep E.5: after confirmation, load the appropriate regular pack combination.\n\n### Scenario F. External-tool governance\n\nUse this scenario when the user already has external tools installed or asks how to use them safely across sessions. This scenario does not teach installation. It records declarations, boundaries, verification, and safe use.\n\nStep F.1: collect installed external tools by category: Connectors, MCPs, Plugins, Skills, browser automation, crawlers, notebooks, or local helper services. If the user does not know the category, ask for names only and classify them.\n\nStep F.2: explain credential separation: Kit files record tool names, project usage, access scope, and credential reference location only. They must never store API keys, OAuth tokens, secrets, or credential values.\n\nStep F.3: map source-of-truth architecture: source of truth, index, persistent mirror, and working draft. Make each layer's write boundary explicit.\n\nStep F.4: when authorized, write the declaration into `PROJECT_INDEX` `## Installed Integrations` and cross-reference relevant External Sources `via` values.\n\nStep F.5: verify current availability using runtime-exposed tool schemas, official docs, or versioned local runbooks. Mark unavailable tools as blocked / unverified instead of guessing.\n\n## Cross-reference to guide.html\n\nWhen the user asks for a fuller example, mention `agent-handoff-kit-guide.html` as an optional reference. The guide is not required reading.\n\n- Case A aligns with Scenario A plus parts of Scenario C.\n- Case B aligns with Scenario B plus Scenario F.\n- Case C aligns with long-running project evolution.\n\n## Tone Discipline\n\nUse plain user-facing language. Avoid internal jargon in onboarding replies unless the user asks for implementation details.\n\n- Say \"project registry\" before exposing `PROJECT_INDEX`.\n- Say \"wrap up\" or the user's own closeout phrase before exposing closeout internals.\n- Say \"next-session startup message\" only when discussing the persisted handoff file.\n- Say \"working mode\" before exposing \"rule pack\".\n- Say \"risky command\" before exposing \"destructive operation\".\n\nKeep user-facing explanations self-contained. For the public product's Chinese surfaces, use steady written Traditional Chinese and avoid Cantonese spoken characters. Inside this AI-facing pack, keep instructions in English and use Chinese only as quoted user phrases that the runtime must recognize.\n\n## Closeout\n\nAfter onboarding finishes:\n\n1. Confirm that the user knows the next practical action, how to start a later session, and how to request closeout.\n2. Update `SESSION_HANDOFF` only when the persistence gate says the first-task scope or next action is durable.\n3. Record next priorities only when they affect a later session.\n4. Do not paste a separate stateful opening message in chat. The persisted `SESSION_HANDOFF` opening-message block remains authoritative.\n5. Unload this pack and continue with the relevant regular pack(s).\n6. Mark `ack:field:first-use-guidance-state` as `consumed` after the first guided task begins or the first full closeout completes. Never reset `consumed` or `not_applicable` to `eligible` during upgrade.\n\nIn a later session, reload onboarding only when the user gives a fresh onboarding signal or asks to restart the walk-through. Otherwise enter the normal work loop.\n\n## Anti-patterns\n\n| Anti-pattern | Why it is wrong | Correct approach |\n|---|---|---|\n| Treating a genuinely vague first message as a specific task | The user may be trying to learn the workflow or choose a scenario. | Ask one concise question or show the two or three most relevant scenarios only when intent remains unresolved. |\n| Making the first task broad | A first-time user needs rhythm and confidence before large changes. | Suggest one 10-15 minute minimum viable task. |\n| Explaining Kit internals before the user needs them | Internal labels increase cognitive load. | Explain the visible effect in plain language. |\n| Assuming the user read README or guide pages | Many users start directly in an AI chat. | Surface only the concepts needed for the next step. |\n| Keeping onboarding loaded after the first task starts | Onboarding is transient and will distract from normal task work. | Unload onboarding and load the regular pack(s). |\n| Forcing the chooser or all five guided steps after the objective is already concrete | The user must repeat known information and the AI shifts technical work back to the user. | Infer the scenario, state the assumption, and begin the first safe action; ask only for missing facts or required risk approval. |\n| Assuming no Connector, MCP, Plugin, or Skill exists | Paste-only fallback creates the wrong operating model for users who already connected tools. | Ask a lightweight external-tool question in step 1, or use Scenario F. |\n"
13776
14161
  }
13777
14162
  },
13778
- "catalogDigestSha256": "f71b0577d2489e5436a1780272091022d71c91e806dfed8537da26e0dfc54b2d"
14163
+ "catalogDigestSha256": "f23de405793876e68af1c05412757c27e91ccaea274c6532dc056b6abb8abeef"
13779
14164
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.62",
3
+ "version": "0.3.64",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -10,7 +10,7 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
10
10
  - A change affects `AGENTS.md`, `dev/*`, rule packs, installer templates, or durable workflow docs.
11
11
  - User asks to bridge governance, connect a document to governance, scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
12
12
  - User asks to make something long-term, cross-session, reusable, future sessions should remember an API / MCP / tool-use pattern, or uses equivalent Chinese phrases such as "寫入長期治理", "轉成長期機制", or "之後都要遵守".
13
- - The task creates or materially changes Markdown documents, generated outputs, specifications, runbooks, checklists, guides, source-of-truth files, or research artifacts that future agents may need to discover.
13
+ - The task creates or materially changes Markdown governance artifacts, source-of-truth files, durable workflow docs, or durable artifacts that future agents may need to discover. Ordinary target-authority documents, drafts, and user-task deliverables do not load this pack solely because they are Markdown or generated.
14
14
 
15
15
  ## Rules
16
16
 
@@ -21,12 +21,13 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
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
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 `runtime-core/AGENTS.core.md` persistence gate decision; do not duplicate the gate thresholds in this pack.
24
- 8. For long-running projects, maintain `dev/PROJECT_DECISIONS.md` per R-028 closeout discipline (see `runtime-core/AGENTS.core.md` closeout 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.
25
- 9. 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.
26
- 10. 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.
27
- 11. 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.
28
- 12. New Markdown or generated documents are not automatically harmless. After creating or materially changing them, classify each artifact before completion: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary. Durable artifacts must be discoverable from `dev/PROJECT_INDEX.md` or intentionally tied to a registered sync / source-of-truth row. Temporary or one-time evidence must be labeled as such in the task record or closeout so future agents do not treat it as hidden current state.
29
- 13. Do not create a new document to hold a rule, requirement, checklist, or process if an existing authoritative document can carry it. Merge into the existing home or make the new document explicitly subordinate. If two files now carry the same durable instruction, resolve the duplicate by choosing one authoritative home and pointing the other to it.
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` per R-028 closeout discipline (see `runtime-core/AGENTS.core.md` closeout 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
+ 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
+ 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
+ 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.
29
+ 13. New Markdown or generated documents are not automatically harmless. After creating or materially changing them, classify each artifact before completion: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary. Durable artifacts must be discoverable from `dev/PROJECT_INDEX.md` or intentionally tied to a registered sync / source-of-truth row. Temporary or one-time evidence must be labeled as such in the task record or closeout so future agents do not treat it as hidden current state.
30
+ 14. Do not create a new document to hold a rule, requirement, checklist, or process if an existing authoritative document can carry it. Merge into the existing home or make the new document explicitly subordinate. If two files now carry the same durable instruction, resolve the duplicate by choosing one authoritative home and pointing the other to it.
30
31
 
31
32
  ## Governance Bridge Workflow
32
33
 
@@ -58,6 +59,8 @@ Output format:
58
59
 
59
60
  Use this workflow whenever the current task creates or materially changes Markdown documents or other durable artifacts, even if the user did not explicitly ask for governance bridge.
60
61
 
62
+ This workflow is subordinate to the core task-first governance locality rule. Use it as a proportionate classification / routing check, not as permission to interrupt an explicit user task plan, start a repo-wide governance scan, or turn an ordinary user-task deliverable into governance work.
63
+
61
64
  1. List the artifacts created or materially changed in this task.
62
65
  2. Classify each artifact: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary.
63
66
  3. For source-of-truth, reference, runbook, workflow, checklist, public document, and reusable generated output, update `dev/PROJECT_INDEX.md` so the file is discoverable with a role and read condition.
@@ -82,7 +85,8 @@ Use this workflow when the user asks to write something into long-term governanc
82
85
  2. If the knowledge is reusable but no existing home fits, propose the smallest new registered reference or rule-pack patch. New runbooks remain last resort.
83
86
  3. If the knowledge was first captured in `SESSION_LOG` or handoff for short-term continuity, promote it to the correct durable home before claiming it is long-term.
84
87
  4. Add or update a QA check when the same failure class could recur and can be tested.
85
- 5. Keep governance bridge wording reserved for document orphan prevention. Do not relabel non-file governance as "file connected to Agent Handoff Kit".
88
+ 5. Repeat-failure escalation: when the same failure class recurs after an AI has already claimed a durable fix for that class, do not continue with another same-pattern patch as ordinary work. Limit the escalation to the affected domain: identify the authoritative owner, correct or remove the failed method there, add a counterexample or replay check that would have failed before the fix when feasible, and state the temporary constraint. If the failure recurs again after that root-fix validation, separate the change and validation roles where the runtime provides an independent reviewer, subagent, or fresh-context pass; when none is available, perform a fresh read-back pass against the replay check and mark independent review unavailable instead of blocking unrelated work. Restore normal flow as soon as the replay and review / read-back pass. Do not create a central penalty database, cross-project blacklist, permanent role split, or public rule carrying project-specific incident details.
89
+ 6. Keep governance bridge wording reserved for document orphan prevention. Do not relabel non-file governance as "file connected to Agent Handoff Kit".
86
90
 
87
91
  ## Checks
88
92
 
@@ -94,6 +98,7 @@ Use this workflow when the user asks to write something into long-term governanc
94
98
  - Confirm no new file has become a parallel source for an existing rule, requirement, checklist, or process.
95
99
  - Confirm reusable operating procedure knowledge is not stored only in `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, or a decision narrative when it belongs in a pack or registered reference.
96
100
  - Confirm long-term governance knowledge is promoted out of `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, and `START_NEXT_SESSION_PROMPT.txt` when it should survive log archive or prompt regeneration.
101
+ - Confirm repeat-failure escalation, when triggered, is limited to the affected domain, tied to the authoritative owner, backed by a counterexample or replay check when feasible, and does not create a central penalty store, cross-project blacklist, or permanent role split.
97
102
  - For governance bridge work, confirm the target file, project index, sync registry, related workflow, handoff/log role split, and duplicate-source risk were all checked or explicitly marked not applicable.
98
103
  - For governance bridge work, run bounded searches for the target path/name and the relevant artifact class or sync-change type across the project index, sync registry, related workflows, and current rule owners. If the target is tied to generated outputs, also inspect the workflow or production guide that creates those outputs. Search evidence is a check, not a second source of truth.
99
104
  - Before claiming completion, apply the active root's core persistence gate and record the result only when that gate selects a checkpoint or full closeout; do not assume child or demo workspaces cover the parent/root workspace.
package/packs/closeout.md CHANGED
@@ -26,6 +26,8 @@ Do not copy the full opening message into `dev/SESSION_LOG.md` or any third curr
26
26
 
27
27
  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.
28
28
 
29
+ 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. 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.
30
+
29
31
  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.
30
32
  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.
31
33
  The bundled doctor is a mechanical floor for required lifecycle markers and readable sections only. The semantic lifecycle gate is `agent-handoff-kit closeout-status`; when it blocks, use its first `Resolved [...]` / `Carry-forward [...]` pair to repair the handoff, not a separate project workaround, repeated doctor runs, or a broader governance rewrite. Read all five sections as a whole before marking the lifecycle field resolved. For governance, release, or another project-defined high-risk completion, use the project's independent semantic review gate in addition to `closeout-status`.
@@ -35,13 +35,39 @@ Load this pack when the user message contains an onboarding signal such as:
35
35
 
36
36
  ## Discipline
37
37
 
38
- ### 1. Do not assume prior reading
39
-
40
- The user may start directly from an AI conversation. Explain only the minimum needed for the current step. Do not teach internal file structure, pack names, release identifiers, maintenance rules, or implementation details unless the user asks.
41
-
42
- ### 2. Infer first; offer scenario choice only when needed
43
-
44
- Infer when sufficient; ask only when unresolved. Read the user's message together with the available handoff and project state before deciding whether a chooser is needed.
38
+ ### 1. Do not assume prior reading
39
+
40
+ The user may start directly from an AI conversation. Explain only the minimum needed for the current step. Do not teach internal file structure, pack names, release identifiers, maintenance rules, or implementation details unless the user asks.
41
+
42
+ ### 1.1 Public capability answer
43
+
44
+ When the user asks "教我用", "能力", "能做甚麼", "what can agent handoff kit do", or an equivalent broad help question, answer in normal user language first. The main answer is what the user can say to an AI, not a CLI command list.
45
+
46
+ Start broad help / capability answers with this display-only onboarding card in a fenced `text` block:
47
+
48
+ ```text
49
+ /\_/\ Agent Handoff Kit
50
+ ( o.o ) quick guide
51
+ > ^ <
52
+ ```
53
+
54
+ The card is a brand affordance only. It must not claim `continuity ready`, `handoff saved`, a version, loaded state, doctor health, or that `SESSION_HANDOFF.md` has been read. Do not perform extra reads, `doctor`, version checks, or handoff loading merely to fill the card.
55
+
56
+ Cover these public command categories:
57
+
58
+ - Daily continuity: say "開工" / "Start Agent Handoff" to resume, and "收工" / "wrap up" to save a handoff.
59
+ - Keep important files connected: say "把這份文件接入 Agent Handoff Kit,讓下次 AI 知道何時要讀、何時要更新。" / "Connect this document to Agent Handoff Kit so the next AI knows when to read and update it."
60
+ - Find missing governance links: say "掃描未接入 Agent Handoff Kit 的重要文件。" / "Scan for important documents not yet connected to Agent Handoff Kit."
61
+ - Turn a recurring mistake into future practice: say "把今次錯誤整理成日後工作規則,讓下次 AI 知道要怎樣避免。" / "Turn this mistake into a durable work rule for future sessions."
62
+ - Keep an API / MCP / tool-use practice reusable: say "以後都用這個 API 調用方式,之後開新對話也要沿用。" / "Use this API approach in future sessions too."
63
+ - Declare external tools safely: say "這個項目會用到這些外部工具,請記住哪些能直接使用,機密不要寫入項目文件。" / "Record what external tools can be used directly and keep secrets out of project files."
64
+ - Finish a long external-tool task cleanly: say "收工時請顯示外部工具資源收口結果:已關閉哪些本任務資源,哪些因歸屬不明而保留並列證據。" / "At wrap up, show the external-tool resource closeout."
65
+
66
+ Do not make CLI maintenance commands the main onboarding answer. Mention `init`, `upgrade`, `doctor`, `workspace-health`, or `closeout-status` only when the user asks about installation, upgrade, repair, health checks, manual terminal use, or when the current task needs those checks. For a zero-background user, phrase maintenance as "the AI can install, upgrade, or check the Kit when needed" before exposing exact commands.
67
+
68
+ ### 2. Infer first; offer scenario choice only when needed
69
+
70
+ Infer when sufficient; ask only when unresolved. Read the user's message together with the available handoff and project state before deciding whether a chooser is needed.
45
71
 
46
72
  When the user has already supplied a concrete, actionable objective and enough material facts, infer the closest working scenario, state the assumption briefly, load the regular task pack(s), and begin the first safe action. Do not require an A-F reply, repeat questions whose answers are already available, or reduce a concrete request to a generic minimum task.
47
73
 
@@ -54,6 +54,7 @@ In every user-facing reply, lead with ordinary language: state the result and it
54
54
  - Non-trivial work reads relevant sources before changing them.
55
55
  - High-risk work states scope, impact, acceptance, and required confirmation before writes.
56
56
  - External skill flows, subagents, task plans, demo workspaces, and another tool's finish step do not replace the active root's persistence decision.
57
+ - 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.
57
58
  - 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.
58
59
  - 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.
59
60
 
@@ -65,6 +66,8 @@ Choose exactly one tier after a task:
65
66
  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.
66
67
  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.
67
68
 
69
+ Pre-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, and do not regenerate `START_NEXT_SESSION_PROMPT.txt`.
70
+
68
71
  During 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.
69
72
 
70
73
  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.
@@ -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.59 | current template version |
9
+ | Agent Handoff Kit template version | 0.3.64 | current template version |
10
10
  | Runtime | TBD | TBD |
11
11
  | Framework | TBD | TBD |
12
12
  | Package manager | TBD | TBD |
@@ -5,7 +5,7 @@ Read only the packs needed for the current task.
5
5
  | Task signal | Pack | Purpose |
6
6
  |---|---|---|
7
7
  | Clear end-of-session or handoff intent: "收工" / "wrap up" / "closeout" / "handoff" / "Wrap up Agent Handoff", including closeout plus a handoff instruction | `dev/rules/closeout.md` | <!-- ack:route:closeout --> full closeout, lifecycle reconciliation, maintenance triggers, prompt regeneration, read-back, and honest stop conditions |
8
- | Explicit onboarding requests: "I'm new" / "new user" / "teach me" / "help me start" / "how do I start" / "show me how" / "getting started" / "what can agent handoff kit do"; or genuinely unresolved intent after current state has been read. Also recognize equivalent Chinese phrases such as "新手", "教我用", "點開始", and "能力". A fresh install with `First-use guidance state: eligible` enters onboarding when no executable objective remains; upgrade never resets consumed / not_applicable first-use state. `Start Agent Handoff` / "開工" is continuity. | `dev/rules/onboarding.md` | <!-- ack:route:onboarding --> infer when sufficient and begin a concrete task directly; ask one concise question or offer guided scenarios only when the user requests guidance or first-use state is eligible with no executable objective |
8
+ | Explicit onboarding requests: "I'm new" / "new user" / "teach me" / "help me start" / "how do I start" / "show me how" / "getting started" / "what can agent handoff kit do"; or genuinely unresolved intent after current state has been read. Also recognize equivalent Chinese phrases such as "新手", "教我用", "點開始", and "能力". A fresh install with `First-use guidance state: eligible` enters onboarding when no executable objective remains; upgrade never resets consumed / not_applicable first-use state. `Start Agent Handoff` / "開工" is continuity. Capability / teaching answers must surface normal-language public command categories instead of reducing the help answer to CLI maintenance commands. | `dev/rules/onboarding.md` | <!-- ack:route:onboarding --> infer when sufficient and begin a concrete task directly; ask one concise question or offer guided scenarios only when the user requests guidance or first-use state is eligible with no executable objective |
9
9
  | Destructive file operations, shell writes, Git state changes, package managers, installers, deploy, release, cloud tools, external APIs, credentials, locked files, permission errors | `dev/rules/safety.md` | safety checks for data loss, external systems, secrets, and high-risk operations |
10
10
  | Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
11
11
  | Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
@@ -15,12 +15,14 @@ Stable facts that should survive across sessions. Update only when they change,
15
15
  6. Installed Integrations registry: `dev/PROJECT_INDEX.md` `## Installed Integrations` is the declaration source. Probe only immediately before actual use, when the current objective names an integration dependency, or when the user asks for a health check. Credential values never appear in `dev/*`; record references only.
16
16
 
17
17
  <!-- ack:section:closeout-reconciled-state -->
18
- ## Closeout-Reconciled State
19
-
18
+ ## Closeout-Reconciled State
19
+
20
20
  This is the current-state area. At every full closeout, update only sections whose current truth changed; leave already-current sections byte-stable where practical and record checked/no-op only when useful. Do not append a new state snapshot under an old one.
21
-
22
- <!-- ack:section:current-baseline -->
23
- ## Current Baseline
21
+
22
+ Pre-closeout checkpoint edits, when explicitly authorized or required by the core Persistence Gate, update only the named hot current-state field(s) or one concise log entry. Historical evidence, old validation records, completed-work narratives, and unchanged durable anchors are cold zones: preserve them byte-for-byte where practical instead of rewording, reordering, or refreshing them because another AI might otherwise read stale context.
23
+
24
+ <!-- ack:section:current-baseline -->
25
+ ## Current Baseline
24
26
 
25
27
  1. Project root: TBD
26
28
  2. Product/system state: TBD