@adamchanadam/agent-handoff-kit 0.3.52 → 0.3.53

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.
@@ -11151,6 +11151,181 @@
11151
11151
  "canonicalSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef"
11152
11152
  }
11153
11153
  }
11154
+ },
11155
+ "0.3.52": {
11156
+ "source": {
11157
+ "npm": {
11158
+ "spec": "@adamchanadam/agent-handoff-kit@0.3.52",
11159
+ "shasum": "6e4c39e5bb0b96681ab2e4da82cb05776b2fe430",
11160
+ "integrity": "sha512-b/p0A3VZ5YI2otrSh99e1iZbFDjty4f360mO46XyGoJMijlYpXro0Uz3jKZ9rJCKoqa9rfJQdQ40da5quQvjFw==",
11161
+ "entryCount": 35,
11162
+ "gitHead": null
11163
+ },
11164
+ "git": {
11165
+ "tag": "v0.3.52",
11166
+ "directObject": "ea80f8d2771f3562f54a841cf55b31a280a8553a",
11167
+ "peeledCommit": null,
11168
+ "commit": "ea80f8d2771f3562f54a841cf55b31a280a8553a"
11169
+ },
11170
+ "githubRelease": {
11171
+ "tag": "v0.3.52",
11172
+ "publishedAt": "2026-07-25T10:26:46Z"
11173
+ },
11174
+ "sourceDivergence": {
11175
+ "status": "npm-gitHead-unavailable",
11176
+ "npmGitHead": null,
11177
+ "remoteTagCommit": "ea80f8d2771f3562f54a841cf55b31a280a8553a"
11178
+ }
11179
+ },
11180
+ "manifest": {
11181
+ "AGENTS.md": {
11182
+ "state": "present",
11183
+ "contentId": "64c1f4e05963d0e59f1bc897afb65a0a2ca8e200d7ef89b10f786e4f784751d5",
11184
+ "rawSha256": "761c52726b1ff7802748ab4162e2396dcf1c725fa44f858792c4ba67377e2a58",
11185
+ "normalizedSha256": "761c52726b1ff7802748ab4162e2396dcf1c725fa44f858792c4ba67377e2a58",
11186
+ "canonicalSha256": "761c52726b1ff7802748ab4162e2396dcf1c725fa44f858792c4ba67377e2a58"
11187
+ },
11188
+ "CLAUDE.md": {
11189
+ "state": "present",
11190
+ "contentId": "7a2cf08a1171762ebcb53f43036a2170655379416945258b9c85d4b189ecaecf",
11191
+ "rawSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad",
11192
+ "normalizedSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad",
11193
+ "canonicalSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad"
11194
+ },
11195
+ "GEMINI.md": {
11196
+ "state": "present",
11197
+ "contentId": "36da47034bb2ce6c760ddbbbbd49dccc1d17665dbb18bec56ffa3b26bac1c135",
11198
+ "rawSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986",
11199
+ "normalizedSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986",
11200
+ "canonicalSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986"
11201
+ },
11202
+ "START_NEXT_SESSION_PROMPT.txt": {
11203
+ "state": "present",
11204
+ "contentId": "da0553e924739abac7af3cc7358d6f9d25d43ae922dc99cd85fcc711edb04c54",
11205
+ "rawSha256": "ae08dcadd2ee0f71df0a1266c8aaca5cc80d9be7a609a98b707bccf442031570",
11206
+ "normalizedSha256": "ae08dcadd2ee0f71df0a1266c8aaca5cc80d9be7a609a98b707bccf442031570",
11207
+ "canonicalSha256": "664ffa54ceee94c62c6975f8ead530916f2faee2a9757949806fb5d7f378f080"
11208
+ },
11209
+ "dev/SESSION_HANDOFF.md": {
11210
+ "state": "present",
11211
+ "contentId": "1fcd367087fd751bcd5c3cf81efb5956235a8092822e0fd8ed0b0248c6223ccf",
11212
+ "rawSha256": "e4ba38fca8eab51705786375bcae3d059301f88fe3dda8d0658145342f141f84",
11213
+ "normalizedSha256": "e4ba38fca8eab51705786375bcae3d059301f88fe3dda8d0658145342f141f84",
11214
+ "canonicalSha256": "45e8161c88c13988192042a386cadce59a39aa007406e6de3c076255a81f3e70"
11215
+ },
11216
+ "dev/SESSION_LOG.md": {
11217
+ "state": "present",
11218
+ "contentId": "7b6184ee4dabe89f504a894c3d4803f012d962c7af53c7f29801a8fb28d9d51c",
11219
+ "rawSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47",
11220
+ "normalizedSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47",
11221
+ "canonicalSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47"
11222
+ },
11223
+ "dev/PROJECT_INDEX.md": {
11224
+ "state": "present",
11225
+ "contentId": "cc6eb8c88f8b4f71b81ea010633450f3ee72e06a58b0513f2d35f048cc472f3a",
11226
+ "rawSha256": "968d1ae7242df656a63eac2faf0ab8e12cd46e9eafe62189cf99486a5f1379ae",
11227
+ "normalizedSha256": "968d1ae7242df656a63eac2faf0ab8e12cd46e9eafe62189cf99486a5f1379ae",
11228
+ "canonicalSha256": "1ff9d23d69aa723549047352302e8f6825cadc75494dd80c95721f2a1747f3bc"
11229
+ },
11230
+ "dev/DOC_SYNC_REGISTRY.md": {
11231
+ "state": "present",
11232
+ "contentId": "f6545b524dc440d3563041e04a05caff4229863f6cae2a39127f85a29a120249",
11233
+ "rawSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6",
11234
+ "normalizedSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6",
11235
+ "canonicalSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6"
11236
+ },
11237
+ "dev/RULE_PACKS.md": {
11238
+ "state": "present",
11239
+ "contentId": "a92986fcb4f7630e533bacf114d096e8e655973de297ff972a1bf1de5610af4b",
11240
+ "rawSha256": "a3e433884fc6bf26448acfa79ba106acaaafe5b4bdb212cb8ce6dc4aaea2faaf",
11241
+ "normalizedSha256": "a3e433884fc6bf26448acfa79ba106acaaafe5b4bdb212cb8ce6dc4aaea2faaf",
11242
+ "canonicalSha256": "a3e433884fc6bf26448acfa79ba106acaaafe5b4bdb212cb8ce6dc4aaea2faaf"
11243
+ },
11244
+ "dev/PROJECT_DECISIONS.md": {
11245
+ "state": "present",
11246
+ "contentId": "3aae993bd5b85bf6b1d1d458f1bcf82c7d3105c843f053ffa13553bb5931b8c4",
11247
+ "rawSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e",
11248
+ "normalizedSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e",
11249
+ "canonicalSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e"
11250
+ },
11251
+ "dev/rules/safety.md": {
11252
+ "state": "present",
11253
+ "contentId": "dd6bcf74722d038f76d202e2044a6583a6e6ad107fbb010520e513eec799ff4a",
11254
+ "rawSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0",
11255
+ "normalizedSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0",
11256
+ "canonicalSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0"
11257
+ },
11258
+ "dev/rules/coding.md": {
11259
+ "state": "present",
11260
+ "contentId": "1c6deb9a5a281c13e97b0ac96079e9e1beccbd1ff106186e7a6ac78c0eeb75c2",
11261
+ "rawSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4",
11262
+ "normalizedSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4",
11263
+ "canonicalSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4"
11264
+ },
11265
+ "dev/rules/writing.md": {
11266
+ "state": "present",
11267
+ "contentId": "ceee5412520ba860e6b40de46bb164e2ce3919d2197d5fadb926198eb7dddd3b",
11268
+ "rawSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593",
11269
+ "normalizedSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593",
11270
+ "canonicalSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593"
11271
+ },
11272
+ "dev/rules/research.md": {
11273
+ "state": "present",
11274
+ "contentId": "4414f9c82c6d04ad49d7446f4b0740055242f425ef5b00391d9c8c78c96c0f66",
11275
+ "rawSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104",
11276
+ "normalizedSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104",
11277
+ "canonicalSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104"
11278
+ },
11279
+ "dev/rules/agent-governance.md": {
11280
+ "state": "present",
11281
+ "contentId": "d3751dc9cb96774413fdd32895bc0c04fcf177346945dab52ffb3cc0ad3a6855",
11282
+ "rawSha256": "33baedd735ee7ec83583f37122a7bfea5c986536b4be6e3d14653f66acec0e77",
11283
+ "normalizedSha256": "33baedd735ee7ec83583f37122a7bfea5c986536b4be6e3d14653f66acec0e77",
11284
+ "canonicalSha256": "33baedd735ee7ec83583f37122a7bfea5c986536b4be6e3d14653f66acec0e77"
11285
+ },
11286
+ "dev/rules/release.md": {
11287
+ "state": "present",
11288
+ "contentId": "b0a0c9dea88016185f4093f9be4ce3c0e29904222e21dd1fa1735fcc1bb7e744",
11289
+ "rawSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7",
11290
+ "normalizedSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7",
11291
+ "canonicalSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7"
11292
+ },
11293
+ "dev/rules/knowledge.md": {
11294
+ "state": "present",
11295
+ "contentId": "e6f5795c7ebaba7b05f04d971b2942b5a0394a3babb44f64a1cc591c9a08cb86",
11296
+ "rawSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c",
11297
+ "normalizedSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c",
11298
+ "canonicalSha256": "efeed5a4eef59f2ce59852832dddcd0447b2308a76fd01dd7a44ee6a16abb74c"
11299
+ },
11300
+ "dev/rules/communication.md": {
11301
+ "state": "present",
11302
+ "contentId": "34fd0034cbc75dad43f789b86a414763f01916dda4d59876db9c4d8d92ae6a87",
11303
+ "rawSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591",
11304
+ "normalizedSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591",
11305
+ "canonicalSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591"
11306
+ },
11307
+ "dev/rules/closeout.md": {
11308
+ "state": "present",
11309
+ "contentId": "26945d466e140c8602742a07c3c8bc02b172ad65149ce62d3ed65e29c6d47c3a",
11310
+ "rawSha256": "b60b3625090cd5000834adef1586e60dcf33acb8a07bce931c533781eccf897c",
11311
+ "normalizedSha256": "b60b3625090cd5000834adef1586e60dcf33acb8a07bce931c533781eccf897c",
11312
+ "canonicalSha256": "b60b3625090cd5000834adef1586e60dcf33acb8a07bce931c533781eccf897c"
11313
+ },
11314
+ "dev/rules/onboarding.md": {
11315
+ "state": "present",
11316
+ "contentId": "e67b34ca3eb5e3aac6e36aa3a3929daae0c881e803badb6d22d5837fc37588ab",
11317
+ "rawSha256": "ae0ab942b86e216e29e8996f17947442d7568910b84899b6df2b836b1fcdbed3",
11318
+ "normalizedSha256": "ae0ab942b86e216e29e8996f17947442d7568910b84899b6df2b836b1fcdbed3",
11319
+ "canonicalSha256": "ae0ab942b86e216e29e8996f17947442d7568910b84899b6df2b836b1fcdbed3"
11320
+ },
11321
+ "dev/rules/integrations.md": {
11322
+ "state": "present",
11323
+ "contentId": "a8fc1099da28f511bf9fed5eaf629ca10fb409299b0aed4d233a45fc7701f284",
11324
+ "rawSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef",
11325
+ "normalizedSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef",
11326
+ "canonicalSha256": "7e51039d57c7c424dbb2c74f9c5ac022193346354593ffa4979008112a2bf8ef"
11327
+ }
11328
+ }
11154
11329
  }
11155
11330
  },
11156
11331
  "contents": {
@@ -11898,7 +12073,22 @@
11898
12073
  "targetRel": "AGENTS.md",
11899
12074
  "canonicalSha256": "fda865042c27be44b86030a7cbfef16c8f2a1dc1f41e77bff73f3242f7e099e7",
11900
12075
  "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, 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, writes, network access, or opt-out wording such as \"unless you object I will start\". 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 or short message only makes guidance available; it never overrides a concrete objective. If no executable objective remains after state reading, ask one concise question or offer guided onboarding.\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\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. 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, combine any card and guidance in one response.\n\nUse a verified version already present in loaded state. If obtaining it would require reading an otherwise unnecessary file, print `version unverified`; do not create a second version source merely to fill the card.\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\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\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. Closeout is not complete until required files are written, read back, and the available closeout checks pass.\n5. 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.\n6. 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\nDefault-core rules must apply to most sessions, protect safety or continuity, and be shorter than the routed detail they replace. New scenario detail belongs in an existing pack or registered reference; a new pack is justified only when it creates a smaller, independently loadable responsibility with one normative owner.\n<!-- END Agent Handoff Kit managed core -->\n\n<!-- ack:user-rules-router:dev/USER_RULES.md -->\n<!-- ack:user-rules-acceptance:sha256=d5169d70e9d930efd9e4e5feefaadab1dc67e99e748307f6946e7a279c9d4f3b -->\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"
12076
+ },
12077
+ "64c1f4e05963d0e59f1bc897afb65a0a2ca8e200d7ef89b10f786e4f784751d5": {
12078
+ "targetRel": "AGENTS.md",
12079
+ "canonicalSha256": "761c52726b1ff7802748ab4162e2396dcf1c725fa44f858792c4ba67377e2a58",
12080
+ "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 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\". 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 or short message only makes guidance available; it never overrides a concrete objective. If no executable objective remains after state reading, ask one concise question or offer guided onboarding.\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-title readback and title control. Replace only a generic or stale title, or update once when the main objective clearly changes; keep an informative title 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. 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 title control/readback is unavailable, 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. 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, combine any card and guidance in one response.\n\nUse a verified version already present in loaded state. If obtaining it would require reading an otherwise unnecessary file, print `version unverified`; do not create a second version source merely to fill the card.\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\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\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. Closeout is not complete until required files are written, read back, and the available closeout checks pass.\n5. 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.\n6. 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\nDefault-core rules must apply to most sessions, protect safety or continuity, and be shorter than the routed detail they replace. New scenario detail belongs in an existing pack or registered reference; a new pack is justified only when it creates a smaller, independently loadable responsibility with one normative owner.\n<!-- END Agent Handoff Kit managed core -->\n\n<!-- ack:user-rules-router:dev/USER_RULES.md -->\n<!-- ack:user-rules-acceptance:sha256=2d480f8f64963a37b5af0754d9643c5dd781f02adc0246aef0a8c2ae706dd24f -->\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"
12081
+ },
12082
+ "da0553e924739abac7af3cc7358d6f9d25d43ae922dc99cd85fcc711edb04c54": {
12083
+ "targetRel": "START_NEXT_SESSION_PROMPT.txt",
12084
+ "canonicalSha256": "664ffa54ceee94c62c6975f8ead530916f2faee2a9757949806fb5d7f378f080",
12085
+ "text": "Work in <ROOT>.\n\nIf the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.\n\nResume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, one optional display-only 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 execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading."
12086
+ },
12087
+ "1fcd367087fd751bcd5c3cf81efb5956235a8092822e0fd8ed0b0248c6223ccf": {
12088
+ "targetRel": "dev/SESSION_HANDOFF.md",
12089
+ "canonicalSha256": "45e8161c88c13988192042a386cadce59a39aa007406e6de3c076255a81f3e70",
12090
+ "text": "# Session Handoff\n\nLast Updated: TBD\n\n<!-- ack:section:durable-anchors -->\n## Durable Anchors\n\nStable facts that should survive across sessions. Update only when they change, but verify they still match reality at closeout.\n\n1. Project root and boundary: TBD\n2. Product/system identity: TBD\n3. Governance model: TBD\n4. Source-of-truth ownership: TBD\n5. Release / publish boundary: TBD\n6. 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.\n\n<!-- ack:section:closeout-reconciled-state -->\n## Closeout-Reconciled State\n\nThis is the current-state area. At every full closeout, rewrite or explicitly confirm every section below. Do not append a new state snapshot under an old one.\n\n<!-- ack:section:current-baseline -->\n## Current Baseline\n\n1. Project root: TBD\n2. Product/system state: TBD\n3. Governance state: TBD\n4. Source-of-truth notes: TBD\n<!-- ack:field:first-use-guidance-state -->\n5. First-use guidance state: eligible\n\n<!-- ack:section:task-understanding-summary -->\n## Task Understanding Summary\n\n<!-- ack:field:user-intent -->\n- User intent: TBD\n<!-- ack:field:task-essence -->\n- Task essence: TBD\n- User value: TBD\n<!-- ack:field:success-criteria -->\n- Success criteria: TBD\n- Key background already read: TBD\n- Background still unread or blocked: TBD\n- Non-goals / boundaries: TBD\n\n<!-- ack:section:active-objective -->\n## Active Objective\n\nTBD\n\n<!-- ack:section:completed-this-session -->\n## Completed This Session\n\nRecord only work actually completed in the current session.\n\n1. TBD\n\n<!-- ack:section:next-priorities -->\n## Next Priorities\n\nRecommended next step: TBD — reason: TBD\n\n1. TBD\n\n<!-- ack:section:next-task-required-reading -->\n## Next Task Required Reading\n\nBefore acting on the next task, read or mark blocked:\n\n| Source | Why required | Status |\n|---|---|---|\n| TBD | TBD | pending |\n\n<!-- ack:section:risks-blockers -->\n## Risks / Blockers\n\n1. TBD\n\n<!-- ack:section:validation-qc -->\n## Validation / QC\n\n- Checks run this session: TBD\n- Checks not run and why: TBD\n- Handoff evidence location: TBD\n\n<!-- ack:section:workspace-identity -->\n## Workspace Identity\n\nExpected project root: TBD\nGit root: TBD\nBranch: TBD\nCommit: TBD\nWorktree / parallel workspace status: TBD\nUncommitted changes summary: TBD\n\n<!-- ack:section:sync-status -->\n## Sync Status\n\nUse statuses from `dev/DOC_SYNC_REGISTRY.md`: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.\n\n- Project index: TBD\n- Doc sync registry: TBD\n- Public docs / README: TBD\n- External knowledge tools: TBD\n\n<!-- ack:section:state-reconciliation-check -->\n## State Reconciliation Check\n\nAt full closeout, complete this check after updating the state sections above.\n\n- Reconciled at: TBD\n<!-- ack:field:state-sections-rewritten-or-confirmed -->\n- State sections rewritten or confirmed current: TBD\n<!-- ack:field:stale-snapshots-left -->\n- Stale snapshots left in this handoff: TBD\n<!-- ack:field:lifecycle-conflicts-resolved -->\n- Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD\n<!-- ack:field:persistence-routing-checked -->\n- Persistence routing checked: TBD\n<!-- ack:field:closeout-outcome -->\n- Closeout outcome: not_started — full closeout has not yet been assessed.\n<!-- ack:field:project-required-persistence -->\n- Project-required persistence: not_assessed — state whether this project's required Git or other persistence completed, is not required, or is blocked.\n<!-- ack:field:recommended-next-step-explicit -->\n- Recommended next step is explicit and reasoned: TBD\n<!-- ack:field:opening-message-matches-current-state -->\n- Opening message matches current state: TBD\n<!-- ack:field:next-ai-can-continue -->\n- Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD\n\nIf any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready. `Closeout outcome: complete` is allowed only when required writes, read-backs and project-required persistence are complete. If project-required persistence is blocked, use `Closeout outcome: blocked` and state the blocker; it is not a completed closeout.\n\nLifecycle consistency rule: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message` as full content, including renamed or paraphrased work. A completed or verified item must not remain as an unresolved next priority, active risk, or startup instruction unless it is explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with the missing evidence or trigger condition stated. Doctor catches only mechanical contradictions and unresolved fields; its green result is not semantic proof. Recommended next-step rule: `Next Priorities` must name the single recommended next action and a short reason before listing additional options, unless the next action is blocked or genuinely requires a user decision. Persistence routing rule: one-time delivery instructions, historical validation evidence, old hashes, old version facts, and incident notes must stay in trace evidence unless they still affect the next action.\n\nCloseout-card rule: `closeout-status` reads only these existing handoff fields plus fresh doctor / mirror results; it does not create another persistence authority. Its `complete` card is the only permitted source for the user-facing `handoff saved` wording. A nonzero / `blocked` result must be shown as blocked, never summarized as completed.\n\n<!-- ack:section:handoff-sufficiency-check -->\n## Handoff Sufficiency Check\n\nCan the next AI continue from `AGENTS.md`, this handoff, and only the project index / rule packs required by the next task, without searching old log history?\n\nAnswer: TBD\nIf no, update this handoff before closeout.\n\nContinuity rule: this file carries current state and next action. `dev/SESSION_LOG.md` carries recent evidence only. Archive old detail only when needed; do not create an archive directory by default.\n\n<!-- ack:section:next-session-opening-message -->\n## Next Session Opening Message\n\nThis fenced block is the authoritative agent-managed startup content. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. If the two differ, trust this block and rewrite the convenience copy. User-facing closeout output should show `Start Agent Handoff` / `開工` as the primary next-session entry, plus the path-bearing fallback when the next AI is not yet pointed at this project root; do not hand-write a separate stateful prompt in the final response.\n\n📋 Next session: agent-managed startup content below\n\n```text\nWork in <ROOT>.\n\nIf the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.\n\nResume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, one optional display-only 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 execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.\n```\n"
11901
12091
  }
11902
12092
  },
11903
- "catalogDigestSha256": "1b21a256e8fea678e07f04fd97796a36b495d857733c892a184fc9709b5a6f5b"
12093
+ "catalogDigestSha256": "087f91c9b75da89e9125f9b0734f2b0d08e25fb0c829c19a2bc722518f35c123"
11904
12094
  }
@@ -1,4 +1,4 @@
1
- import { lstatSync, readFileSync, readdirSync } from "node:fs";
1
+ import { lstatSync, readFileSync, readdirSync } from "node:fs";
2
2
  import path from "node:path";
3
3
 
4
4
  const openingSectionMarker = "<!-- ack:section:next-session-opening-message -->";
@@ -26,28 +26,28 @@ export function assessPromptMirrorRoot(root) {
26
26
  return { status: "missing", ok: false, reason: "prompt copy unreadable" };
27
27
  }
28
28
 
29
- const otherTexts = collectCurrentGovernanceTexts(root, new Set([
30
- path.resolve(handoffPath),
31
- path.resolve(promptPath)
32
- ]));
33
- return assessPromptMirrorTexts(handoffText, promptText, otherTexts);
34
- }
35
-
36
- export function assessPromptMirrorTexts(handoffText, promptText, otherTexts = []) {
37
- const markerCount = countLiteral(handoffText, openingSectionMarker);
38
- const headingCount = (handoffText.match(new RegExp(openingHeadingPattern.source, "gm")) ?? []).length;
39
- const contentMarkerCount = openingContentMarkers.reduce((sum, marker) => sum + countLiteral(handoffText, marker), 0);
40
- const openingSection = markerCount === 1 ? handoffText.slice(handoffText.indexOf(openingSectionMarker)) : "";
41
- const fenceCount = (openingSection.match(/```text[^\r\n]*(?:\r\n?|\n)[\s\S]*?(?:\r\n?|\n)```/g) ?? []).length;
42
- if (markerCount !== 1 || headingCount > 1 || contentMarkerCount !== 1 || fenceCount !== 1) {
43
- return {
44
- status: "structure-invalid",
45
- ok: false,
46
- reason: `opening structure must be unique (section marker=${markerCount}, heading=${headingCount}, copy marker=${contentMarkerCount}, fenced text=${fenceCount})`
47
- };
48
- }
49
-
50
- const openingMessage = extractOpeningMessage(handoffText);
29
+ const otherTexts = collectCurrentGovernanceTexts(root, new Set([
30
+ path.resolve(handoffPath),
31
+ path.resolve(promptPath)
32
+ ]));
33
+ return assessPromptMirrorTexts(handoffText, promptText, otherTexts);
34
+ }
35
+
36
+ export function assessPromptMirrorTexts(handoffText, promptText, otherTexts = []) {
37
+ const markerCount = countLiteral(handoffText, openingSectionMarker);
38
+ const headingCount = (handoffText.match(new RegExp(openingHeadingPattern.source, "gm")) ?? []).length;
39
+ const contentMarkerCount = openingContentMarkers.reduce((sum, marker) => sum + countLiteral(handoffText, marker), 0);
40
+ const openingSection = markerCount === 1 ? handoffText.slice(handoffText.indexOf(openingSectionMarker)) : "";
41
+ const fenceCount = (openingSection.match(/```text[^\r\n]*(?:\r\n?|\n)[\s\S]*?(?:\r\n?|\n)```/g) ?? []).length;
42
+ if (markerCount !== 1 || headingCount > 1 || contentMarkerCount !== 1 || fenceCount !== 1) {
43
+ return {
44
+ status: "structure-invalid",
45
+ ok: false,
46
+ reason: `opening structure must be unique (section marker=${markerCount}, heading=${headingCount}, copy marker=${contentMarkerCount}, fenced text=${fenceCount})`
47
+ };
48
+ }
49
+
50
+ const openingMessage = extractOpeningMessage(handoffText);
51
51
  if (openingMessage == null) {
52
52
  return {
53
53
  status: "missing",
@@ -56,19 +56,19 @@ export function assessPromptMirrorTexts(handoffText, promptText, otherTexts = []
56
56
  };
57
57
  }
58
58
 
59
- const normalizedOpening = normalizePrompt(openingMessage);
60
- const thirdCopies = otherTexts.filter(({ text }) => normalizePrompt(text).includes(normalizedOpening));
61
- if (thirdCopies.length > 0) {
62
- return {
63
- status: "third-copy",
64
- ok: false,
65
- reason: `full opening message also appears in: ${thirdCopies.map(({ relative }) => relative).join(", ")}`,
66
- openingMessage,
67
- thirdCopies: thirdCopies.map(({ relative }) => relative)
68
- };
69
- }
70
-
71
- if (openingMessage === promptText) {
59
+ const normalizedOpening = normalizePrompt(openingMessage);
60
+ const thirdCopies = otherTexts.filter(({ text }) => normalizePrompt(text).includes(normalizedOpening));
61
+ if (thirdCopies.length > 0) {
62
+ return {
63
+ status: "third-copy",
64
+ ok: false,
65
+ reason: `full opening message also appears in: ${thirdCopies.map(({ relative }) => relative).join(", ")}`,
66
+ openingMessage,
67
+ thirdCopies: thirdCopies.map(({ relative }) => relative)
68
+ };
69
+ }
70
+
71
+ if (openingMessage === promptText) {
72
72
  return {
73
73
  status: "match",
74
74
  ok: true,
@@ -78,7 +78,7 @@ export function assessPromptMirrorTexts(handoffText, promptText, otherTexts = []
78
78
  };
79
79
  }
80
80
 
81
- const normalizedPrompt = normalizePrompt(promptText);
81
+ const normalizedPrompt = normalizePrompt(promptText);
82
82
  if (normalizedOpening === normalizedPrompt) {
83
83
  return {
84
84
  status: "newline-only",
@@ -125,7 +125,7 @@ function findOpeningSectionStart(text) {
125
125
  return headingMatch ? headingMatch.index : -1;
126
126
  }
127
127
 
128
- function firstDiff(left, right) {
128
+ function firstDiff(left, right) {
129
129
  const leftLines = left.split("\n");
130
130
  const rightLines = right.split("\n");
131
131
  const count = Math.max(leftLines.length, rightLines.length);
@@ -139,49 +139,49 @@ function firstDiff(left, right) {
139
139
  }
140
140
  }
141
141
  return null;
142
- }
143
-
144
- function countLiteral(text, token) {
145
- if (!token) return 0;
146
- let count = 0;
147
- let offset = 0;
148
- while ((offset = text.indexOf(token, offset)) >= 0) {
149
- count += 1;
150
- offset += token.length;
151
- }
152
- return count;
153
- }
154
-
155
- function collectCurrentGovernanceTexts(root, excluded) {
156
- const candidates = [
157
- "AGENTS.md",
158
- "CLAUDE.md",
159
- "GEMINI.md",
160
- "dev/SESSION_LOG.md",
161
- "dev/PROJECT_INDEX.md",
162
- "dev/DOC_SYNC_REGISTRY.md",
163
- "dev/RULE_PACKS.md",
164
- "dev/PROJECT_DECISIONS.md"
165
- ];
166
- const rulesDir = path.join(root, "dev", "rules");
167
- try {
168
- for (const entry of readdirSync(rulesDir, { withFileTypes: true })) {
169
- if (entry.isFile() && entry.name.endsWith(".md")) candidates.push(`dev/rules/${entry.name}`);
170
- }
171
- } catch {
172
- // Missing rules are reported by normal doctor checks.
173
- }
174
-
175
- const results = [];
176
- for (const relative of candidates) {
177
- const absolute = path.resolve(root, relative);
178
- if (excluded.has(absolute)) continue;
179
- try {
180
- if (lstatSync(absolute).isSymbolicLink()) continue;
181
- results.push({ relative, text: readFileSync(absolute, "utf8") });
182
- } catch {
183
- // Missing or unreadable files are handled by their owning checks.
184
- }
185
- }
186
- return results;
187
- }
142
+ }
143
+
144
+ function countLiteral(text, token) {
145
+ if (!token) return 0;
146
+ let count = 0;
147
+ let offset = 0;
148
+ while ((offset = text.indexOf(token, offset)) >= 0) {
149
+ count += 1;
150
+ offset += token.length;
151
+ }
152
+ return count;
153
+ }
154
+
155
+ function collectCurrentGovernanceTexts(root, excluded) {
156
+ const candidates = [
157
+ "AGENTS.md",
158
+ "CLAUDE.md",
159
+ "GEMINI.md",
160
+ "dev/SESSION_LOG.md",
161
+ "dev/PROJECT_INDEX.md",
162
+ "dev/DOC_SYNC_REGISTRY.md",
163
+ "dev/RULE_PACKS.md",
164
+ "dev/PROJECT_DECISIONS.md"
165
+ ];
166
+ const rulesDir = path.join(root, "dev", "rules");
167
+ try {
168
+ for (const entry of readdirSync(rulesDir, { withFileTypes: true })) {
169
+ if (entry.isFile() && entry.name.endsWith(".md")) candidates.push(`dev/rules/${entry.name}`);
170
+ }
171
+ } catch {
172
+ // Missing rules are reported by normal doctor checks.
173
+ }
174
+
175
+ const results = [];
176
+ for (const relative of candidates) {
177
+ const absolute = path.resolve(root, relative);
178
+ if (excluded.has(absolute)) continue;
179
+ try {
180
+ if (lstatSync(absolute).isSymbolicLink()) continue;
181
+ results.push({ relative, text: readFileSync(absolute, "utf8") });
182
+ } catch {
183
+ // Missing or unreadable files are handled by their owning checks.
184
+ }
185
+ }
186
+ return results;
187
+ }