@adamchanadam/agent-handoff-kit 0.3.34 → 0.3.35

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.
@@ -183,24 +183,25 @@ const requiredAnchors = [
183
183
  "filesystem root, drive root",
184
184
  "cmd /c rmdir",
185
185
  "git reset --hard",
186
- "external APIs, SDKs, CLIs",
187
- "parser failure",
188
- "secret values"
186
+ "external APIs, SDKs, CLIs",
187
+ "parser failure",
188
+ "secret values",
189
+ "task-owned or agent-managed",
190
+ "other-agent-owned"
189
191
  ]
190
192
  },
191
193
  {
192
- target: "dev/PROJECT_DECISIONS.md",
193
- label: "project decisions narrative anchors",
194
- placement: projectDecisionsAnchorPlacement,
195
- snippets: [
196
- "Project Decisions Log",
197
- "warm 資料層",
198
- "AI 開工",
199
- "不需要讀",
200
- "AI 在收工時自動 update",
201
- "Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.",
202
- "This file does not store raw build / upload / QC evidence",
203
- "Evolution Timeline",
194
+ target: "dev/PROJECT_DECISIONS.md",
195
+ label: "project decisions narrative anchors",
196
+ placement: projectDecisionsAnchorPlacement,
197
+ snippets: [
198
+ "Project Decisions Log",
199
+ "warm narrative layer",
200
+ "do not need to read this file at startup",
201
+ "The AI updates it during closeout",
202
+ "Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.",
203
+ "This file does not store raw build / upload / QC evidence",
204
+ "Evolution Timeline",
204
205
  "Decisions Archive",
205
206
  "Architecture Choices",
206
207
  "Insights & Learnings"
@@ -209,22 +210,22 @@ const requiredAnchors = [
209
210
  {
210
211
  target: "dev/rules/onboarding.md",
211
212
  label: "onboarding pack core anchors",
212
- placement: onboardingAnchorPlacement,
213
- snippets: [
214
- "Onboarding Pack",
215
- "transient pack",
216
- "明確 onboarding signal keywords",
217
- "5-step walk-through pattern",
218
- "Application Scenario Library",
219
- "Scenario A. 建構系統 / 工具 / 平台 / 網站或應用",
220
- "Scenario B. 整理研究資料",
221
- "Scenario C. 整理電腦檔案",
222
- "Scenario D. 學寫代碼",
223
- "Scenario E. 其他",
224
- "Scenario F. 審視已裝外部工具",
225
- "Tone Discipline"
226
- ]
227
- },
213
+ placement: onboardingAnchorPlacement,
214
+ snippets: [
215
+ "Onboarding Pack",
216
+ "transient pack",
217
+ "Explicit onboarding signal keywords",
218
+ "5-step walk-through pattern",
219
+ "Application Scenario Library",
220
+ "Scenario A. Build systems, tools, platforms, websites, or apps",
221
+ "Scenario B. Organize research or write a report",
222
+ "Scenario C. Organize local files, Notion, Google Drive, or a knowledge base",
223
+ "Scenario D. Learn to code",
224
+ "Scenario E. Custom scenario",
225
+ "Scenario F. External-tool governance",
226
+ "Tone Discipline"
227
+ ]
228
+ },
228
229
  {
229
230
  target: "dev/rules/integrations.md",
230
231
  label: "integrations pack core anchors",
@@ -235,8 +236,10 @@ const requiredAnchors = [
235
236
  "MCPs",
236
237
  "Plugins",
237
238
  "Skills",
238
- "機密分離原則",
239
+ "Credential Separation Principle",
239
240
  "External Tool Usage Verification Gate",
241
+ "External Tool Resource Lifecycle",
242
+ "other-agent-owned",
240
243
  "do not invent",
241
244
  "input schema",
242
245
  "official documentation",
@@ -352,11 +355,11 @@ const schemaChecks = [
352
355
  tableHeader("Check", "Command", "Run before", "Last verified"),
353
356
  tableHeader("Change type", "Likely files", "Required checks"),
354
357
  // R-030 v0.3.0+: Installed Integrations subsection table headers
355
- tableHeader("Tool", "Project Usage", "Access Scope", "Specific Instance", "Credential Reference(no value)", "Declared", "Last Verified"),
356
- tableHeader("Server", "Source", "Project Usage", "Credential Reference(no value)", "Declared", "Last Verified"),
357
- tableHeader("Name", "Bundle Content(Skills + MCP + hooks)", "When Triggered", "Last Verified"),
358
- tableHeader("Name", "Source", "When Triggered", "Last Verified"),
359
- tableHeader("Layer", "Surface(具體 instance)", "Role", "Write Direction")
358
+ tableHeader("Tool", "Project Usage", "Access Scope", "Specific Instance", "Credential Reference (no value)", "Declared", "Last Verified"),
359
+ tableHeader("Server", "Source", "Project Usage", "Credential Reference (no value)", "Declared", "Last Verified"),
360
+ tableHeader("Name", "Bundle Content (Skills + MCP + hooks)", "When Triggered", "Last Verified"),
361
+ tableHeader("Name", "Source", "When Triggered", "Last Verified"),
362
+ tableHeader("Layer", "Surface (specific instance)", "Role", "Write Direction")
360
363
  ]
361
364
  },
362
365
  {
@@ -388,14 +391,16 @@ const schemaChecks = [
388
391
  // stale routing table that does not route onboarding signals.
389
392
  includes("First-time user signals"),
390
393
  includes("dev/rules/onboarding.md"),
391
- // R-030 v0.3.0+: routing table must include integrations pack row.
392
- includes("dev/rules/integrations.md"),
393
- includes("Governance bridge / 治理打通"),
394
- includes("接入 Agent Handoff Kit"),
395
- includes("掃描未接入 Agent Handoff Kit 的重要文件"),
396
- includes("scan for unbridged governance documents")
397
- ]
398
- },
394
+ // R-030 v0.3.0+: routing table must include integrations pack row.
395
+ includes("dev/rules/integrations.md"),
396
+ includes("External tool resource pressure"),
397
+ includes("ownership-based external-tool resource closeout"),
398
+ includes("Governance bridge / bridge governance"),
399
+ includes("equivalent Chinese user phrases"),
400
+ includes("scan for unbridged governance documents"),
401
+ includes("scan for unbridged governance documents")
402
+ ]
403
+ },
399
404
  {
400
405
  target: "dev/rules/agent-governance.md",
401
406
  label: "agent governance pack structure",
@@ -407,11 +412,11 @@ const schemaChecks = [
407
412
  heading("Checks"),
408
413
  heading("Closeout"),
409
414
  includes("Governance bridge is a triggered review"),
410
- includes("接入 Agent Handoff Kit"),
411
- includes("掃描未接入 Agent Handoff Kit 的重要文件"),
412
- includes("Status: bridged / partially bridged / unbridged / blocked"),
413
- includes("duplicate source-of-truth risk")
414
- ]
415
+ includes("equivalent Chinese phrases"),
416
+ includes("scan for unbridged governance documents"),
417
+ includes("Status: bridged / partially bridged / unbridged / blocked"),
418
+ includes("duplicate source-of-truth risk")
419
+ ]
415
420
  },
416
421
  {
417
422
  target: "dev/PROJECT_DECISIONS.md",
@@ -427,7 +432,7 @@ const schemaChecks = [
427
432
  },
428
433
  {
429
434
  target: "dev/rules/onboarding.md",
430
- label: "onboarding pack structure (新手引導包)",
435
+ label: "onboarding pack structure",
431
436
  checks: [
432
437
  heading("Scope"),
433
438
  heading("Load When"),
@@ -440,15 +445,17 @@ const schemaChecks = [
440
445
  },
441
446
  {
442
447
  target: "dev/rules/integrations.md",
443
- label: "integrations pack structure (外部工具治理)",
444
- checks: [
445
- heading("Scope"),
446
- heading("Load When"),
447
- heading("Discipline"),
448
- heading("Rules"),
448
+ label: "integrations pack structure",
449
+ checks: [
450
+ heading("Scope"),
451
+ heading("Load When"),
452
+ heading("Discipline"),
453
+ includes("External Tool Resource Lifecycle"),
454
+ includes("other-agent-owned"),
455
+ heading("Rules"),
449
456
  heading("Checks"),
450
457
  heading("Closeout"),
451
- heading("Anti-pattern(不要做的事)"),
458
+ heading("Anti-patterns"),
452
459
  heading("Cross-reference")
453
460
  ]
454
461
  }
@@ -866,7 +873,7 @@ async function runDoctor(root, version, options = {}) {
866
873
 
867
874
  // R-030 v0.3.0+: credential leak prevention sweep over governance files.
868
875
  const credentialResult = await checkInstalledIntegrationsCredentialLeak(root);
869
- console.log(`Credential 機密分離 sweep: ${credentialResult.ok ? "ok" : "FAILED"}`);
876
+ console.log(`Credential separation sweep: ${credentialResult.ok ? "ok" : "FAILED"}`);
870
877
  if (!credentialResult.ok) {
871
878
  for (const finding of credentialResult.findings) {
872
879
  console.log(` CRITICAL: ${finding}`);
@@ -1691,25 +1698,39 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1691
1698
  };
1692
1699
  }
1693
1700
  // R-030 v0.3.0+: dev/RULE_PACKS.md must also include integrations pack routing row.
1694
- if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("External tool integrations")) {
1695
- const mergedRulePacks = mergeRulePacksRows(targetText, sourceText);
1696
- if (!mergedRulePacks) {
1697
- return { ...base, action: "conflict", reason: "RULE_PACKS.md routing table header was changed; manual merge required to preserve custom rows" };
1701
+ if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("External tool integrations")) {
1702
+ const mergedRulePacks = mergeRulePacksRows(targetText, sourceText);
1703
+ if (!mergedRulePacks) {
1704
+ return { ...base, action: "conflict", reason: "RULE_PACKS.md routing table header was changed; manual merge required to preserve custom rows" };
1698
1705
  }
1699
1706
  return {
1700
1707
  ...base,
1701
1708
  action: "merge",
1702
1709
  reason: "merge missing v0.3.0+ routing rows while preserving existing custom rows (Integration governance routing)",
1703
- mergedText: mergedRulePacks
1704
- };
1705
- }
1710
+ mergedText: mergedRulePacks
1711
+ };
1712
+ }
1713
+ // External-tool resource lifecycle extension: old v0.3.x installs may already
1714
+ // have the integrations row, but still lack the resource-pressure routing row.
1715
+ if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && !targetText.includes("External tool resource pressure")) {
1716
+ const mergedRulePacks = mergeRulePacksRows(targetText, sourceText);
1717
+ if (!mergedRulePacks) {
1718
+ return { ...base, action: "conflict", reason: "RULE_PACKS.md routing table header was changed; manual merge required to preserve custom rows" };
1719
+ }
1720
+ return {
1721
+ ...base,
1722
+ action: "merge",
1723
+ reason: "merge missing external-tool resource lifecycle routing row while preserving existing custom rows",
1724
+ mergedText: mergedRulePacks
1725
+ };
1726
+ }
1706
1727
  // Governance bridge v0.3.27+: route durable document bridging requests to
1707
1728
  // agent-governance without replacing user-added routing rows.
1708
- if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && (
1709
- !targetText.includes("Governance bridge / 治理打通")
1710
- || !targetText.includes("接入 Agent Handoff Kit")
1711
- || !targetText.includes("掃描未接入 Agent Handoff Kit 的重要文件")
1712
- )) {
1729
+ if (targetRel === "dev/RULE_PACKS.md" && command === "upgrade" && (
1730
+ !targetText.includes("Governance bridge / bridge governance")
1731
+ || !targetText.includes("equivalent Chinese user phrases")
1732
+ || !targetText.includes("scan for unbridged governance documents")
1733
+ )) {
1713
1734
  const mergedRulePacks = mergeRulePacksRows(targetText, sourceText);
1714
1735
  if (!mergedRulePacks) {
1715
1736
  return { ...base, action: "conflict", reason: "RULE_PACKS.md routing table header was changed; manual merge required to preserve custom rows" };
@@ -1718,16 +1739,29 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1718
1739
  ...base,
1719
1740
  action: "merge",
1720
1741
  reason: "merge missing governance bridge routing row while preserving existing custom rows",
1721
- mergedText: mergedRulePacks
1722
- };
1723
- }
1724
- // Governance bridge v0.3.27+: add the triggered review workflow to the
1725
- // agent-governance pack only when the pack still has a trusted Checks section.
1726
- if (targetRel === "dev/rules/agent-governance.md" && command === "upgrade" && (
1727
- !targetText.includes("## Governance Bridge Workflow")
1728
- || !targetText.includes("接入 Agent Handoff Kit")
1729
- || !targetText.includes("掃描未接入 Agent Handoff Kit 的重要文件")
1730
- )) {
1742
+ mergedText: mergedRulePacks
1743
+ };
1744
+ }
1745
+ // Language migration: older integrations packs were AI-facing rules written
1746
+ // partly in Chinese/Cantonese. If the file still has the trusted legacy Kit
1747
+ // shape, replace it with the current English maintainer pack. If the shape is
1748
+ // ambiguous or locally restructured, stop as a conflict instead of doing a
1749
+ // partial merge that could create a half-English, half-legacy pack.
1750
+ if (targetRel === "dev/rules/integrations.md" && command === "upgrade" && isLegacyChineseIntegrationsPack(targetText)) {
1751
+ return {
1752
+ ...base,
1753
+ action: "merge",
1754
+ reason: "replace legacy Chinese integrations pack with current English maintainer pack",
1755
+ mergedText: sourceText
1756
+ };
1757
+ }
1758
+ // Governance bridge v0.3.27+: add the triggered review workflow to the
1759
+ // agent-governance pack only when the pack still has a trusted Checks section.
1760
+ if (targetRel === "dev/rules/agent-governance.md" && command === "upgrade" && (
1761
+ !targetText.includes("## Governance Bridge Workflow")
1762
+ || !targetText.includes("equivalent Chinese phrases")
1763
+ || !targetText.includes("scan for unbridged governance documents")
1764
+ )) {
1731
1765
  const mergedGovernancePack = mergeAgentGovernanceBridgeWorkflow(targetText, sourceText);
1732
1766
  if (!mergedGovernancePack) {
1733
1767
  return { ...base, action: "conflict", reason: "agent-governance pack structure was changed; manual merge required to add governance bridge workflow" };
@@ -1758,8 +1792,10 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1758
1792
  }
1759
1793
  if (targetRel === "dev/PROJECT_INDEX.md" && command === "upgrade" && (
1760
1794
  targetText.includes("Credential Location")
1795
+ || targetText.includes("Credential Reference(no value)")
1761
1796
  || targetText.includes("Claude Code MCP config + env var")
1762
1797
  || targetText.includes("Credential 應由 AI 工具自身 secure storage 管理(譬如 Claude Desktop Extensions")
1798
+ || targetText.includes("機密分離原則")
1763
1799
  )) {
1764
1800
  const mergedProjectIndex = mergeProjectIndexCredentialReferences(targetText);
1765
1801
  if (mergedProjectIndex !== targetText) {
@@ -1771,14 +1807,25 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1771
1807
  };
1772
1808
  }
1773
1809
  }
1774
- // R-030 v0.3.0+: dev/rules/onboarding.md gets ### Scenario F block auto-inserted before
1775
- // ## Cross-reference to guide.html on upgrade if missing. NON-DESTRUCTIVE: existing Scenarios A-E
1776
- // content and any user customization preserved. Step 1 micro-question additions to Scenarios A-E
1777
- // are NOT auto-migrated (user-customizable inline sample wording, not anchor-enforced); users get
1778
- // those on fresh install only or can manually patch following CHANGELOG migration guidance.
1779
- if (targetRel === "dev/rules/onboarding.md" && command === "upgrade" && !targetText.includes("Scenario F. 審視已裝外部工具")) {
1780
- const sourceScenarioFMatch = sourceText.match(/(### Scenario F\. 審視已裝外部工具[\s\S]*?)(?=## Cross-reference to guide\.html)/);
1781
- if (sourceScenarioFMatch && hasTrustedOnboardingScenarioLibrary(targetText)) {
1810
+ // Language migration: older onboarding packs were AI-facing rules written
1811
+ // mostly in Chinese. If the file still has the trusted legacy Kit shape,
1812
+ // replace it with the current concise English maintainer pack. If the shape
1813
+ // is ambiguous or locally restructured, stop as a conflict instead of
1814
+ // producing a half-English, half-legacy pack.
1815
+ if (targetRel === "dev/rules/onboarding.md" && command === "upgrade" && isLegacyChineseOnboardingPack(targetText)) {
1816
+ return {
1817
+ ...base,
1818
+ action: "merge",
1819
+ reason: "replace legacy Chinese onboarding pack with current English maintainer pack",
1820
+ mergedText: sourceText
1821
+ };
1822
+ }
1823
+ // R-030 v0.3.0+: dev/rules/onboarding.md gets Scenario F auto-inserted before
1824
+ // ## Cross-reference to guide.html on upgrade if missing and the pack is not
1825
+ // a legacy Chinese pack that should be replaced wholesale.
1826
+ if (targetRel === "dev/rules/onboarding.md" && command === "upgrade" && !targetText.includes("Scenario F. External-tool governance")) {
1827
+ const sourceScenarioFMatch = sourceText.match(/(### Scenario F\. External-tool governance[\s\S]*?)(?=## Cross-reference to guide\.html)/);
1828
+ if (sourceScenarioFMatch && hasTrustedOnboardingScenarioLibrary(targetText)) {
1782
1829
  const scenarioFBlock = sourceScenarioFMatch[1];
1783
1830
  return {
1784
1831
  ...base,
@@ -1788,7 +1835,7 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
1788
1835
  };
1789
1836
  }
1790
1837
  }
1791
- if (targetRel === "dev/rules/onboarding.md" && command === "upgrade" && !targetText.includes("Scenario A. 建構系統 / 工具 / 平台 / 網站或應用")) {
1838
+ if (targetRel === "dev/rules/onboarding.md" && command === "upgrade" && !targetText.includes("Scenario A. Build systems, tools, platforms, websites, or apps")) {
1792
1839
  const mergedOnboarding = mergeOnboardingScenarioALabel(targetText);
1793
1840
  if (mergedOnboarding !== targetText) {
1794
1841
  return {
@@ -1942,47 +1989,69 @@ function looksLikeExpandedKitBridge(targetRel, text) {
1942
1989
  return false;
1943
1990
  }
1944
1991
 
1945
- function mergeOnboardingScenarioALabel(targetText) {
1946
- let merged = targetText;
1947
- merged = merged.replace(
1948
- /\*\*A\. 寫 \/ 改代碼項目\*\* —— 你有一個(?: project 的 codebase|程式項目)想長期維護/g,
1949
- "**A. 建構系統 / 工具 / 平台 / 網站或應用** —— 你想由 AI 協助建立或長期維護一個可運作的項目"
1950
- );
1951
- merged = merged.replace(
1952
- /### Scenario A\. 寫 \/ 改代碼項目/g,
1953
- "### Scenario A. 建構系統 / 工具 / 平台 / 網站或應用"
1954
- );
1955
- return merged;
1956
- }
1957
-
1958
- function mergeAgentGovernanceBridgeWorkflow(targetText, sourceText) {
1959
- const sourceMatch = sourceText.match(/9\. Governance bridge[\s\S]*?(?=\n## Checks)/);
1960
- const workflowMatch = sourceText.match(/\n## Governance Bridge Workflow[\s\S]*?(?=\n## Checks)/);
1961
- const sourceLoadWhenLine = sourceText.split(/\r?\n/).find((line) => line.startsWith("- User asks to \"治理打通\""));
1962
- const sourceWorkflowIntroLine = sourceText.split(/\r?\n/).find((line) => line.startsWith("Use this workflow when"));
1963
- if (!sourceMatch || !workflowMatch || !targetText.includes("\n## Checks")) return null;
1992
+ function mergeOnboardingScenarioALabel(targetText) {
1993
+ let merged = targetText;
1994
+ merged = merged.replace(
1995
+ /\*\*A\. 寫 \/ 改代碼項目\*\* —— 你有一個(?: project 的 codebase|程式項目)想長期維護/g,
1996
+ "**A. Build systems, tools, platforms, websites, or apps**: the user wants AI help to create or maintain a working project."
1997
+ );
1998
+ merged = merged.replace(
1999
+ /### Scenario A\. 寫 \/ 改代碼項目/g,
2000
+ "### Scenario A. Build systems, tools, platforms, websites, or apps"
2001
+ );
2002
+ merged = merged.replace(
2003
+ /### Scenario A\. 建構系統 \/ 工具 \/ 平台 \/ 網站或應用/g,
2004
+ "### Scenario A. Build systems, tools, platforms, websites, or apps"
2005
+ );
2006
+ return merged;
2007
+ }
1964
2008
 
1965
- let merged = targetText;
1966
- const targetLoadWhenLine = merged.split(/\r?\n/).find((line) => line.startsWith("- User asks to \"治理打通\""));
1967
- if (sourceLoadWhenLine && (!targetLoadWhenLine || !targetLoadWhenLine.includes("接入 Agent Handoff Kit"))) {
1968
- merged = merged.replace(/- User asks to "治理打通"[^\n]*\n/, `${sourceLoadWhenLine}\n`);
1969
- }
1970
- const targetWorkflowIntroLine = merged.match(/^Use this workflow when[^\n]*$/m)?.[0] ?? "";
1971
- if (sourceWorkflowIntroLine && !targetWorkflowIntroLine.includes("掃描未接入 Agent Handoff Kit 的重要文件")) {
1972
- merged = merged.replace(/^Use this workflow when[^\n]*$/m, sourceWorkflowIntroLine);
1973
- }
1974
- if (!merged.includes("Governance bridge is a triggered review")) {
1975
- const rulePrefix = sourceMatch[0].trimEnd();
1976
- merged = merged.replace(/\n## Checks/, `\n${rulePrefix}\n${workflowMatch[0]}\n## Checks`);
1977
- }
1978
- if (!merged.includes("For governance bridge work, confirm the target file")) {
2009
+ function mergeAgentGovernanceBridgeWorkflow(targetText, sourceText) {
2010
+ const sourceRuleLine = sourceText.split(/\r?\n/).find((line) => line.startsWith("9. Governance bridge"));
2011
+ const workflowMatch = sourceText.match(/\n## Governance Bridge Workflow[\s\S]*?(?=\n## Generated Artifact Governance Workflow|\n## Checks)/);
2012
+ const sourceLoadWhenLine = sourceText.split(/\r?\n/).find((line) => line.startsWith("- User asks to bridge governance"));
2013
+ if (!sourceRuleLine || !workflowMatch || !targetText.includes("\n## Checks")) return null;
2014
+
2015
+ let merged = targetText;
2016
+ const targetLoadWhenLine = merged.split(/\r?\n/).find((line) => line.startsWith("- User asks to bridge governance") || line.startsWith("- User asks to \"治理打通\""));
2017
+ if (sourceLoadWhenLine && targetLoadWhenLine && !targetLoadWhenLine.includes("scan for unbridged governance documents")) {
2018
+ merged = merged.replace(/- User asks to (?:bridge governance|"治理打通")[^\n]*\n/, `${sourceLoadWhenLine}\n`);
2019
+ }
2020
+ if (sourceLoadWhenLine && !targetLoadWhenLine && !merged.includes("equivalent Chinese phrases")) {
2021
+ const loadWhenMarker = "- A change affects `AGENTS.md`, `dev/*`, rule packs, installer templates, or durable workflow docs.";
2022
+ if (merged.includes(loadWhenMarker)) {
2023
+ merged = merged.replace(loadWhenMarker, `${loadWhenMarker}\n${sourceLoadWhenLine}`);
2024
+ }
2025
+ }
2026
+ if (/^9\. Governance bridge/m.test(merged)) {
2027
+ merged = merged.replace(/^9\. Governance bridge[^\n]*$/m, sourceRuleLine);
2028
+ } else if (!merged.includes(sourceRuleLine)) {
2029
+ merged = merged.replace(/\n## Governance Bridge Workflow|\n## Checks/, `\n${sourceRuleLine}$&`);
2030
+ }
2031
+ merged = removeAllSectionsByHeading(merged, "## Governance Bridge Workflow");
2032
+ merged = merged.replace(/\n## Checks/, `${workflowMatch[0]}\n## Checks`);
2033
+ if (!merged.includes("Governance bridge is a triggered review")) {
2034
+ return null;
2035
+ }
2036
+ if (!merged.includes("For governance bridge work, confirm the target file")) {
1979
2037
  merged = merged.replace(
1980
2038
  "- 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.",
1981
2039
  "- 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- 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."
1982
2040
  );
1983
2041
  }
1984
- return merged;
1985
- }
2042
+ return merged;
2043
+ }
2044
+
2045
+ function removeAllSectionsByHeading(text, heading) {
2046
+ let result = text;
2047
+ while (true) {
2048
+ const start = result.indexOf(`\n${heading}`);
2049
+ if (start < 0) return result;
2050
+ const next = result.indexOf("\n## ", start + heading.length + 1);
2051
+ if (next < 0) return result.slice(0, start).trimEnd() + "\n";
2052
+ result = result.slice(0, start) + result.slice(next);
2053
+ }
2054
+ }
1986
2055
 
1987
2056
  function hasTrustedOnboardingScenarioLibrary(text) {
1988
2057
  const bounds = textSectionBounds(text, "## Application Scenario Library", "## Cross-reference to guide.html");
@@ -2095,16 +2164,15 @@ function safetyAnchorPlacement(snippet, text) {
2095
2164
  return safetyAnchorHasTrustedRuleShape(text, snippet);
2096
2165
  }
2097
2166
 
2098
- function projectDecisionsAnchorPlacement(snippet, text) {
2099
- const preamble = [
2100
- "Project Decisions Log",
2101
- "warm 資料層",
2102
- "AI 開工",
2103
- "不需要讀",
2104
- "AI 在收工時自動 update",
2105
- "Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.",
2106
- "This file does not store raw build / upload / QC evidence"
2107
- ];
2167
+ function projectDecisionsAnchorPlacement(snippet, text) {
2168
+ const preamble = [
2169
+ "Project Decisions Log",
2170
+ "warm narrative layer",
2171
+ "do not need to read this file at startup",
2172
+ "The AI updates it during closeout",
2173
+ "Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.",
2174
+ "This file does not store raw build / upload / QC evidence"
2175
+ ];
2108
2176
  if (preamble.includes(snippet)) return snippetAppearsBeforeHeading(text, snippet, "## Evolution Timeline");
2109
2177
  return true;
2110
2178
  }
@@ -2120,13 +2188,13 @@ function onboardingAnchorPlacement(snippet, text) {
2120
2188
  }
2121
2189
 
2122
2190
  function integrationsAnchorPlacement(snippet, text) {
2123
- if (snippet === "機密分離原則" || snippet === "External Tool Usage Verification Gate" || snippet === "do not invent" || snippet === "input schema" || snippet === "official documentation" || snippet === "Source-of-truth Architecture" || snippet === "Cross-session Lifecycle") {
2191
+ if (snippet === "Credential Separation Principle" || snippet === "External Tool Usage Verification Gate" || snippet === "External Tool Resource Lifecycle" || snippet === "do not invent" || snippet === "input schema" || snippet === "official documentation" || snippet === "Source-of-truth Architecture" || snippet === "Cross-session Lifecycle") {
2124
2192
  return snippetAppearsBetweenHeadings(text, snippet, "## Discipline", "## Rules");
2125
2193
  }
2126
2194
  if (snippet === "Connector-first default") {
2127
2195
  return snippetAppearsBetweenHeadings(text, snippet, "## Rules", "## Checks");
2128
2196
  }
2129
- if (snippet === "Anti-pattern") return text.includes("## Anti-pattern(不要做的事)");
2197
+ if (snippet === "Anti-pattern") return text.includes("## Anti-patterns") || text.includes("## Anti-pattern(不要做的事)");
2130
2198
  return true;
2131
2199
  }
2132
2200
 
@@ -2265,6 +2333,55 @@ function mergeProjectIndexTemplateVersionRow(targetText, sourceText) {
2265
2333
 
2266
2334
  function mergeProjectIndexCredentialReferences(targetText) {
2267
2335
  return targetText
2336
+ .replace(
2337
+ /`via` column 紀律:每行 External Sources 必引用 `## Installed Integrations`[^\r\n]*/,
2338
+ "`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."
2339
+ )
2340
+ .replace(
2341
+ /⚠️ \*\*機密分離原則\*\*:本 section 只記錄[^\r\n]*/,
2342
+ "**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`."
2343
+ )
2344
+ .replace(
2345
+ /用途:新 AI session 開工讀本 section 知道[^\r\n]*/,
2346
+ "Purpose: a new AI session reads this section to understand declared external-tool capabilities and their project roles. Declarations persist across sessions. Every entry must include `Declared` and `Last Verified` fields so stale capability assumptions can be detected."
2347
+ )
2348
+ .replace("### Connectors(Anthropic 官方 vetted)", "### Connectors")
2349
+ .replace("### MCPs(community / custom)", "### MCPs")
2350
+ .replace("### Plugins(Claude Code plugin bundle)", "### Plugins")
2351
+ .replace("### Skills(SKILL.md instruction set)", "### Skills")
2352
+ .replace("### Source-of-truth Architecture(多層持久化組合)", "### Source-of-truth Architecture")
2353
+ .replace(
2354
+ /當項目用多個整合構成 source-of-truth 架構[^\r\n]*/,
2355
+ "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."
2356
+ )
2357
+ .replace(
2358
+ "| TBD | TBD(譬如 DB Index 記真源 path / 持久化參考檔儲存) | read / read+write | TBD(譬如 DB 名 + URL / folder path) | TBD(譬如 `AI tool secure storage` / `OS credential store`) | TBD | TBD |",
2359
+ "| 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 |"
2360
+ )
2361
+ .replace(
2362
+ "| TBD | TBD(譬如 GitHub repo URL) | TBD | TBD(譬如 `tool config + env var name only` / `user-managed secret store`) | TBD | TBD |",
2363
+ "| TBD | TBD, for example GitHub repository URL | TBD | TBD, for example `tool config + env var name only` / `user-managed secret store` | TBD | TBD |"
2364
+ )
2365
+ .replace(
2366
+ "| TBD | TBD(譬如 plugin bundle / user-level install) | TBD | TBD |",
2367
+ "| TBD | TBD, for example plugin bundle or user-level install | TBD | TBD |"
2368
+ )
2369
+ .replace(
2370
+ "| 真源(source of truth) | TBD(譬如 本機 `~/project/reference/`) | 原始可審計 reference 內容 | 用戶手動置入;AI 不直接寫入 |",
2371
+ "| Source of truth | TBD, for example local `~/project/reference/` | Original auditable reference content | User-controlled placement; agent does not write directly unless explicitly authorized |"
2372
+ )
2373
+ .replace(
2374
+ "| Index | TBD(譬如 Notion DB「Project Index」) | 登記每份真源檔 metadata + 摘要 + tag | AI 經 Connector 直接讀寫 |",
2375
+ "| Index | TBD, for example Notion database `Project Index` | Metadata, summaries, and tags for each source file | Agent may read/write through a verified Connector |"
2376
+ )
2377
+ .replace(
2378
+ "| 持久化參考檔(mirror) | TBD(譬如 Drive folder「Project Reference/」) | 防本機 disk failure / 跨裝置 access | 用戶手動同步;AI 唔自動 push |",
2379
+ "| 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 |"
2380
+ )
2381
+ .replace(
2382
+ "| Working draft | TBD(譬如 本機 `~/project/output/`) | AI 寫 task output | AI 直接 read + write 本機 |",
2383
+ "| Working draft | TBD, for example local `~/project/output/` | Agent task output | Agent may read and write local files under normal safety rules |"
2384
+ )
2268
2385
  .replace(
2269
2386
  "Credential 應由 AI 工具自身 secure storage 管理(譬如 Claude Desktop Extensions 嘅 OS Keychain / Claude Code MCP config)。",
2270
2387
  "Credential 應由 AI 工具自身 secure storage / OS credential store / tool config / user-managed secret store 管理;若使用 env,只可記錄 env var name,不可讀取、貼出或保存 value。"
@@ -2273,6 +2390,18 @@ function mergeProjectIndexCredentialReferences(targetText) {
2273
2390
  "Credential Location",
2274
2391
  "Credential Reference(no value)"
2275
2392
  )
2393
+ .replaceAll(
2394
+ "Credential Reference(no value)",
2395
+ "Credential Reference (no value)"
2396
+ )
2397
+ .replaceAll(
2398
+ "Bundle Content(Skills + MCP + hooks)",
2399
+ "Bundle Content (Skills + MCP + hooks)"
2400
+ )
2401
+ .replaceAll(
2402
+ "Surface(具體 instance)",
2403
+ "Surface (specific instance)"
2404
+ )
2276
2405
  .replace(
2277
2406
  "`Claude Desktop Extensions`",
2278
2407
  "`AI tool secure storage` / `OS credential store`"
@@ -2296,13 +2425,32 @@ function mergeSafetyRulesByMissingAnchors(targetText, sourceText, missing) {
2296
2425
 
2297
2426
  let changed = false;
2298
2427
  const remainingMissing = [...missing];
2299
- if (remainingMissing.includes("parser failure") && !targetText.includes("parser failure")) {
2300
- const parserFailureRule = sourceRuleLines.find((line) => line.includes("parser failure"));
2301
- if (!parserFailureRule || !parserFailureRule.startsWith("13. ")) return null;
2302
- targetLines.splice(targetRuleEnd, 0, parserFailureRule);
2303
- changed = true;
2304
- remainingMissing.splice(remainingMissing.indexOf("parser failure"), 1);
2305
- }
2428
+ const appendableRules = [
2429
+ { snippet: "parser failure", number: "13" },
2430
+ { snippet: "Process termination and cache cleanup boundary", number: "14" },
2431
+ { snippet: "task-owned or agent-managed", number: "14" },
2432
+ { snippet: "other-agent-owned", number: "14" }
2433
+ ];
2434
+ for (const { snippet, number } of appendableRules) {
2435
+ if (!remainingMissing.includes(snippet) || targetText.includes(snippet)) continue;
2436
+ const sourceRule = sourceRuleLines.find((line) => line.includes(snippet));
2437
+ if (!sourceRule || !sourceRule.startsWith(`${number}. `)) return null;
2438
+ if (!targetLines.some((line, index) => index >= targetRuleStart && index < targetRuleEnd && line.startsWith(`${number}. `))) {
2439
+ targetLines.splice(targetRuleEnd, 0, sourceRule);
2440
+ changed = true;
2441
+ remainingMissing.splice(remainingMissing.indexOf(snippet), 1);
2442
+ continue;
2443
+ }
2444
+ // If the numbered rule already exists, leave it for the same-shape replacement path below.
2445
+ }
2446
+
2447
+ if (remainingMissing.includes("parser failure") && !targetText.includes("parser failure")) {
2448
+ const parserFailureRule = sourceRuleLines.find((line) => line.includes("parser failure"));
2449
+ if (!parserFailureRule || !parserFailureRule.startsWith("13. ")) return null;
2450
+ targetLines.splice(targetRuleEnd, 0, parserFailureRule);
2451
+ changed = true;
2452
+ remainingMissing.splice(remainingMissing.indexOf("parser failure"), 1);
2453
+ }
2306
2454
 
2307
2455
  for (const snippet of remainingMissing) {
2308
2456
  const sourceLine = sourceRuleLines.find((line) => line.includes(snippet));
@@ -2323,11 +2471,11 @@ function mergeIntegrationsSectionsByMissingAnchors(targetText, sourceText, missi
2323
2471
  let merged = targetText;
2324
2472
  let changed = false;
2325
2473
 
2326
- if (missing.some((snippet) => snippet === "機密分離原則")) {
2474
+ if (missing.some((snippet) => snippet === "Credential Separation Principle" || snippet === "機密分離原則")) {
2327
2475
  const withCredential = replaceSectionByHeadingWithinBounds(
2328
2476
  merged,
2329
2477
  sourceText,
2330
- /^### 1\. (機密分離原則|credential-separation anchor removed from this stale local copy)/m,
2478
+ /^### 1\. (Credential Separation Principle|機密分離原則|credential-separation anchor removed from this stale local copy)/m,
2331
2479
  /^### 2\. /m,
2332
2480
  "## Discipline",
2333
2481
  "## Rules"
@@ -2337,7 +2485,7 @@ function mergeIntegrationsSectionsByMissingAnchors(targetText, sourceText, missi
2337
2485
  changed = true;
2338
2486
  }
2339
2487
 
2340
- if (missing.some((snippet) => snippet === "External Tool Usage Verification Gate" || snippet === "do not invent" || snippet === "input schema" || snippet === "official documentation")) {
2488
+ if (missing.some((snippet) => snippet === "External Tool Usage Verification Gate" || snippet === "External Tool Resource Lifecycle" || snippet === "other-agent-owned" || snippet === "do not invent" || snippet === "input schema" || snippet === "official documentation")) {
2341
2489
  const withVerificationGate = mergeIntegrationsVerificationGateSection(merged, sourceText);
2342
2490
  if (!withVerificationGate) return null;
2343
2491
  merged = withVerificationGate;
@@ -2373,10 +2521,47 @@ function mergeIntegrationsVerificationGateSection(targetText, sourceText) {
2373
2521
  return `${targetText.slice(0, targetBounds.start + currentFourTypesHeading.index)}${sourceSection.text}${targetText.slice(targetBounds.start + currentFourTypesHeading.index)}`;
2374
2522
  }
2375
2523
 
2524
+ const englishTypeHeading = /^### 3\. Integration Type Discipline/m.exec(boundedTarget);
2525
+ if (englishTypeHeading) {
2526
+ return `${targetText.slice(0, targetBounds.start + englishTypeHeading.index)}${sourceSection.text}${targetText.slice(targetBounds.start + englishTypeHeading.index)}`;
2527
+ }
2528
+
2376
2529
  return null;
2377
2530
  }
2378
-
2379
- function hasTrustedSafetyPackShape(text) {
2531
+
2532
+ function isLegacyChineseIntegrationsPack(text) {
2533
+ return text.includes("# Integrations Pack")
2534
+ && countText(text, "## Scope") === 1
2535
+ && countText(text, "## Load When") === 1
2536
+ && countText(text, "## Discipline") === 1
2537
+ && countText(text, "## Rules") === 1
2538
+ && countText(text, "## Checks") === 1
2539
+ && countText(text, "## Closeout") === 1
2540
+ && countText(text, "## Cross-reference") === 1
2541
+ && (text.includes("機密分離原則") || text.includes("四類整合"))
2542
+ && !text.includes("## Local Discipline")
2543
+ && !text.includes("Duplicate ambiguous local heading")
2544
+ && countText(text, "四類整合") <= 2;
2545
+ }
2546
+
2547
+ function isLegacyChineseOnboardingPack(text) {
2548
+ return text.includes("# Onboarding Pack")
2549
+ && countText(text, "## Scope") === 1
2550
+ && countText(text, "## Load When") === 1
2551
+ && countText(text, "## Discipline") === 1
2552
+ && countText(text, "## Application Scenario Library") === 1
2553
+ && countText(text, "## Cross-reference to guide.html") === 1
2554
+ && countText(text, "## Tone Discipline") === 1
2555
+ && countText(text, "## Closeout") === 1
2556
+ && text.includes("### Scenario A.")
2557
+ && text.includes("### Scenario E.")
2558
+ && (text.includes("明確 onboarding signal keywords") || text.includes("Scenario F. 審視已裝外部工具") || text.includes("Anti-pattern(不要做的事)"))
2559
+ && !text.includes("### Local Scenario A")
2560
+ && !text.includes("structurally ambiguous onboarding")
2561
+ && !text.includes("## Local Discipline");
2562
+ }
2563
+
2564
+ function hasTrustedSafetyPackShape(text) {
2380
2565
  return text.includes("# Safety Pack")
2381
2566
  && text.includes("## Scope")
2382
2567
  && Boolean(sectionBounds(text, "## Rules", "## Checks"))
@@ -2690,28 +2875,24 @@ function mergeRulePacksRows(targetText, sourceText) {
2690
2875
 
2691
2876
  let tableEnd = tableStart;
2692
2877
  while (tableEnd < lines.length && lines[tableEnd].startsWith("|")) tableEnd++;
2693
-
2694
- const before = lines.slice(0, tableStart);
2695
- const table = lines.slice(tableStart, tableEnd);
2696
- const after = lines.slice(tableEnd);
2697
- const governanceBridgeSourceRow = sourceRows.find((row) => row.includes("Governance bridge / 治理打通"));
2698
- if (
2699
- governanceBridgeSourceRow
2700
- && targetText.includes("Governance bridge / 治理打通")
2701
- && (!targetText.includes("接入 Agent Handoff Kit") || !targetText.includes("掃描未接入 Agent Handoff Kit 的重要文件"))
2702
- ) {
2703
- const replaced = lines.map((line) => (
2704
- line.includes("Governance bridge / 治理打通") ? governanceBridgeSourceRow : line
2705
- ));
2706
- return replaced.join("\n");
2707
- }
2708
- const sourceRowsToApply = sourceRows.filter((row) => {
2709
- if (row.includes("dev/rules/onboarding.md")) return !targetText.includes("First-time user signals");
2710
- if (row.includes("dev/rules/integrations.md")) return !targetText.includes("External tool integrations");
2711
- if (row.includes("Governance bridge / 治理打通")) return !targetText.includes("Governance bridge / 治理打通");
2712
- return false;
2713
- });
2714
- if (sourceRowsToApply.length === 0) return targetText;
2878
+
2879
+ const before = lines.slice(0, tableStart);
2880
+ const governanceBridgeSourceRow = sourceRows.find((row) => row.includes("Governance bridge / bridge governance"));
2881
+ const hasAnyGovernanceRow = targetText.includes("Governance bridge / 治理打通") || targetText.includes("Governance bridge / bridge governance");
2882
+ const table = lines.slice(tableStart, tableEnd).map((line) => (
2883
+ governanceBridgeSourceRow && (line.includes("Governance bridge / 治理打通") || line.includes("Governance bridge / bridge governance"))
2884
+ ? governanceBridgeSourceRow
2885
+ : line
2886
+ ));
2887
+ const after = lines.slice(tableEnd);
2888
+ const sourceRowsToApply = sourceRows.filter((row) => {
2889
+ if (row.includes("dev/rules/onboarding.md")) return !targetText.includes("First-time user signals");
2890
+ if (row.includes("External tool resource pressure")) return !targetText.includes("External tool resource pressure");
2891
+ if (row.includes("dev/rules/integrations.md")) return !targetText.includes("External tool integrations");
2892
+ if (row.includes("Governance bridge / bridge governance")) return !hasAnyGovernanceRow;
2893
+ return false;
2894
+ });
2895
+ if (sourceRowsToApply.length === 0 && table.join("\n") === lines.slice(tableStart, tableEnd).join("\n")) return targetText;
2715
2896
 
2716
2897
  const merged = [
2717
2898
  ...before,