@adamchanadam/agent-handoff-kit 0.3.39 → 0.3.40

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.
@@ -1,201 +1,201 @@
1
- # Onboarding Pack
2
-
3
- ## Scope
4
-
5
- Use this transient pack for first-time Agent Handoff Kit users, vague first messages, or fresh-install sessions where the user has not yet chosen a working scenario.
6
-
7
- The goal is to help the user complete a small first task without requiring them to read README, guide pages, `AGENTS.md`, or internal Kit rules first. After the onboarding walk-through finishes, unload this pack and continue with the regular scenario pack such as coding, research, writing, knowledge, or integrations.
8
-
9
- ## Load When
10
-
11
- ### Explicit onboarding signal keywords
12
-
13
- Load this pack when the user message contains an onboarding signal such as:
14
-
15
- - "I'm new" / "new user"
16
- - "teach me" / "help me start" / "help me get started"
17
- - "first time" / "first-time" / "I just installed"
18
- - "how do I start" / "show me how" / "getting started"
19
- - "what can agent handoff kit do"
20
- - vague project intent such as "I want to do a project"
21
- - equivalent Chinese user phrases such as "新手", "教我用", "我剛安裝", "點開始", "開工", "能力", or "能做甚麼"
22
-
23
- ### Implicit signals
24
-
25
- - The first user message is short and vague.
26
- - `SESSION_HANDOFF` Active Objective is empty and Session count is 1.
27
- - The user asks a generic capability question instead of giving a concrete task.
28
- - The user appears unfamiliar with the workflow, for example asking what the AI should do rather than giving an objective.
29
-
30
- ## Discipline
31
-
32
- ### 1. Do not assume prior reading
33
-
34
- The user may start directly from an AI conversation. Explain only the minimum needed for the current step. Do not teach internal file structure, pack names, release identifiers, maintenance rules, or implementation details unless the user asks.
35
-
36
- ### 2. Offer scenario choice before task execution
37
-
38
- When onboarding applies, the first visible response must combine the startup card and scenario chooser into one complete response. Do not print a partial startup card first. Do not repeat the status card, current objective, warnings, or next step.
39
-
40
- Offer six scenarios:
41
-
42
- - **A. Build systems, tools, platforms, websites, or apps**: the user wants AI help to create or maintain a working project.
43
- - **B. Organize research or write a report**: the user has sources, notes, articles, presentations, or a report goal.
44
- - **C. Organize local files, Notion, Google Drive, or a knowledge base**: the user wants source, reference, mirror, and draft material kept clear.
45
- - **D. Learn to code**: the user is a technical beginner and wants a small guided exercise.
46
- - **E. Custom scenario**: the user has another goal.
47
- - **F. Review installed external tools and design governance**: the user already has Connectors, MCPs, Plugins, Skills, or browser / notebook / crawler tools and wants a safe operating model.
48
-
49
- ### 3. 5-step walk-through pattern
50
-
51
- After the user picks a scenario, guide one small first task through five steps:
52
-
53
- 1. Confirm project context: folder, existing material, current tools, source locations, and whether external tools are already connected.
54
- 2. Explain in three plain points how Agent Handoff Kit helps this scenario.
55
- 3. Ask for the first concrete task scope, offering four to six practical options.
56
- 4. Suggest one minimum viable task that can usually be completed in 10-15 minutes.
57
- 5. Wait for user confirmation, then transition to the regular work loop.
58
-
59
- ### 4. Advance one step at a time
60
-
61
- Do not run all five steps in one message. At each step:
62
-
63
- - state what the AI will do,
64
- - state what the user needs to answer or confirm,
65
- - answer questions before continuing,
66
- - let the user skip or change the step.
67
-
68
- ### 5. Keep the first task small
69
-
70
- The first task should be a preview, a short draft, a small classification sample, a dry-run, or another bounded result. Do not begin with broad refactors, bulk file moves, publishing, deployment, or destructive operations.
71
-
72
- ### 6. Transition after onboarding
73
-
74
- After the walk-through:
75
-
76
- - load the regular pack(s) for the chosen task,
77
- - unload this transient onboarding pack,
78
- - enter the PLAN -> READ -> CHANGE -> QC -> PERSIST work loop,
79
- - record the first-task scope in `SESSION_HANDOFF` when the persistence gate requires it.
80
-
81
- ## Application Scenario Library
82
-
83
- Each scenario keeps the same five-step rhythm. The model may adapt wording, but must preserve the intent, tone, and safety boundaries.
84
-
85
- ### Scenario A. Build systems, tools, platforms, websites, or apps
86
-
87
- Step A.1: ask for the project folder, current stack if known, whether git exists, and whether GitHub, Linear, Slack, Notion, Google Drive, or other external tools are connected.
88
-
89
- Step A.2: explain that Kit helps the AI remember project state across sessions, avoid silent risky commands, and record what changed at closeout.
90
-
91
- Step A.3: offer task choices such as fix a bug, add a feature, organize code, add tests, write README, or prepare a first commit.
92
-
93
- Step A.4: suggest a small first task, such as a short README section, one failing test investigation, or a dry-run plan.
94
-
95
- Step A.5: after confirmation, load the relevant coding / writing / safety packs and begin the normal work loop.
96
-
97
- ### Scenario B. Organize research or write a report
98
-
99
- Step B.1: ask for the topic, existing source locations, intended reader, and whether Notion, Google Drive, or another source tool is connected.
100
-
101
- Step B.2: explain that Kit separates source evidence from inference, records source locations, and preserves progress across sessions.
102
-
103
- Step B.3: offer task choices such as outline sections, register sources, summarize one source, draft a subsection, or review an existing draft.
104
-
105
- Step B.4: suggest a small first task, such as a 5-7 heading outline with one sentence per section.
106
-
107
- Step B.5: after confirmation, load research / writing / knowledge packs and begin the normal work loop.
108
-
109
- ### Scenario C. Organize local files, Notion, Google Drive, or a knowledge base
110
-
111
- Step C.1: ask what needs organizing: local folder, Notion database, Google Drive folder, or mixed sources. Ask which external tools are connected or unknown.
112
-
113
- Step C.2: explain that Kit separates source of truth, references, mirrors, and drafts, and that risky file operations require dry-run and confirmation.
114
-
115
- Step C.3: offer task choices such as scan and classify files, design a folder structure, draft a Notion schema, write a dry-run script, or align local references with an external index.
116
-
117
- Step C.4: suggest a small first task, such as classifying a bounded sample without moving files.
118
-
119
- Step C.5: after confirmation, load knowledge / safety / integrations packs as needed.
120
-
121
- ### Scenario D. Learn to code
122
-
123
- Step D.1: ask which direction the user wants: small automation, web page, Python tool, Git / GitHub basics, or another beginner task. Ask whether any relevant tools are already installed.
124
-
125
- Step D.2: explain that Kit keeps learning progress across sessions, keeps risky operations explicit, and lets the user review each small change.
126
-
127
- Step D.3: offer one small exercise, such as a dry-run file renamer, a one-page HTML example, or a tiny Python script.
128
-
129
- Step D.4: keep the exercise small enough to explain line by line.
130
-
131
- Step D.5: after confirmation, load coding / safety packs and begin the normal work loop.
132
-
133
- ### Scenario E. Custom scenario
134
-
135
- Step E.1: ask for four facts: objective, existing material or tools, technical comfort level, and the first small result the user wants.
136
-
137
- Step E.2: explain how Kit helps the chosen scenario using continuity, safety, and source / artifact governance.
138
-
139
- Step E.3: offer task choices tailored to the user's answer.
140
-
141
- Step E.4: suggest one minimum viable first task.
142
-
143
- Step E.5: after confirmation, load the appropriate regular pack combination.
144
-
145
- ### Scenario F. External-tool governance
146
-
147
- Use this scenario when the user already has external tools installed or asks how to use them safely across sessions. This scenario does not teach installation. It records declarations, boundaries, verification, and safe use.
148
-
149
- Step F.1: collect installed external tools by category: Connectors, MCPs, Plugins, Skills, browser automation, crawlers, notebooks, or local helper services. If the user does not know the category, ask for names only and classify them.
150
-
151
- Step F.2: explain credential separation: Kit files record tool names, project usage, access scope, and credential reference location only. They must never store API keys, OAuth tokens, secrets, or credential values.
152
-
153
- Step F.3: map source-of-truth architecture: source of truth, index, persistent mirror, and working draft. Make each layer's write boundary explicit.
154
-
155
- Step F.4: when authorized, write the declaration into `PROJECT_INDEX` `## Installed Integrations` and cross-reference relevant External Sources `via` values.
156
-
157
- Step F.5: verify current availability using runtime-exposed tool schemas, official docs, or versioned local runbooks. Mark unavailable tools as blocked / unverified instead of guessing.
158
-
159
- ## Cross-reference to guide.html
160
-
161
- When the user asks for a fuller example, mention `agent-handoff-kit-guide.html` as an optional reference. The guide is not required reading.
162
-
163
- - Case A aligns with Scenario A plus parts of Scenario C.
164
- - Case B aligns with Scenario B plus Scenario F.
165
- - Case C aligns with long-running project evolution.
166
-
167
- ## Tone Discipline
168
-
169
- Use plain user-facing language. Avoid internal jargon in onboarding replies unless the user asks for implementation details.
170
-
171
- - Say "project registry" before exposing `PROJECT_INDEX`.
172
- - Say "wrap up" or the user's own closeout phrase before exposing closeout internals.
173
- - Say "next-session startup message" only when discussing the persisted handoff file.
174
- - Say "working mode" before exposing "rule pack".
175
- - Say "risky command" before exposing "destructive operation".
176
-
177
- Keep user-facing explanations self-contained. For the public product's Chinese surfaces, use steady written Traditional Chinese and avoid Cantonese spoken characters. Inside this AI-facing pack, keep instructions in English and use Chinese only as quoted user phrases that the runtime must recognize.
178
-
179
- ## Closeout
180
-
181
- After onboarding finishes:
182
-
183
- 1. Confirm that the user knows the next practical action, how to start a later session, and how to request closeout.
184
- 2. Update `SESSION_HANDOFF` only when the persistence gate says the first-task scope or next action is durable.
185
- 3. Record next priorities only when they affect a later session.
186
- 4. Do not paste a separate stateful opening message in chat. The persisted `SESSION_HANDOFF` opening-message block remains authoritative.
187
- 5. Unload this pack and continue with the relevant regular pack(s).
188
-
189
- In a later session, reload onboarding only when the user gives a fresh onboarding signal or asks to restart the walk-through. Otherwise enter the normal work loop.
190
-
191
- ## Anti-patterns
192
-
193
- | Anti-pattern | Why it is wrong | Correct approach |
194
- |---|---|---|
195
- | Treating a vague first message as a specific task | The user may be trying to learn the workflow or choose a scenario. | Offer the A-F scenario chooser first. |
196
- | Making the first task broad | A first-time user needs rhythm and confidence before large changes. | Suggest one 10-15 minute minimum viable task. |
197
- | Explaining Kit internals before the user needs them | Internal labels increase cognitive load. | Explain the visible effect in plain language. |
198
- | Assuming the user read README or guide pages | Many users start directly in an AI chat. | Surface only the concepts needed for the next step. |
199
- | Keeping onboarding loaded after the first task starts | Onboarding is transient and will distract from normal task work. | Unload onboarding and load the regular pack(s). |
200
- | Running all five steps without waiting | The user loses control of the walk-through. | Pause for confirmation at each step. |
201
- | Assuming no Connector, MCP, Plugin, or Skill exists | Paste-only fallback creates the wrong operating model for users who already connected tools. | Ask a lightweight external-tool question in step 1, or use Scenario F. |
1
+ # Onboarding Pack
2
+
3
+ ## Scope
4
+
5
+ Use this transient pack for first-time Agent Handoff Kit users, vague first messages, or fresh-install sessions where the user has not yet chosen a working scenario.
6
+
7
+ The goal is to help the user complete a small first task without requiring them to read README, guide pages, `AGENTS.md`, or internal Kit rules first. After the onboarding walk-through finishes, unload this pack and continue with the regular scenario pack such as coding, research, writing, knowledge, or integrations.
8
+
9
+ ## Load When
10
+
11
+ ### Explicit onboarding signal keywords
12
+
13
+ Load this pack when the user message contains an onboarding signal such as:
14
+
15
+ - "I'm new" / "new user"
16
+ - "teach me" / "help me start" / "help me get started"
17
+ - "first time" / "first-time" / "I just installed"
18
+ - "how do I start" / "show me how" / "getting started"
19
+ - "what can agent handoff kit do"
20
+ - vague project intent such as "I want to do a project"
21
+ - equivalent Chinese user phrases such as "新手", "教我用", "我剛安裝", "點開始", "開工", "能力", or "能做甚麼"
22
+
23
+ ### Implicit signals
24
+
25
+ - The first user message is short and vague.
26
+ - `SESSION_HANDOFF` Active Objective is empty and Session count is 1.
27
+ - The user asks a generic capability question instead of giving a concrete task.
28
+ - The user appears unfamiliar with the workflow, for example asking what the AI should do rather than giving an objective.
29
+
30
+ ## Discipline
31
+
32
+ ### 1. Do not assume prior reading
33
+
34
+ The user may start directly from an AI conversation. Explain only the minimum needed for the current step. Do not teach internal file structure, pack names, release identifiers, maintenance rules, or implementation details unless the user asks.
35
+
36
+ ### 2. Offer scenario choice before task execution
37
+
38
+ When onboarding applies, the first visible response must combine the startup card and scenario chooser into one complete response. Do not print a partial startup card first. Do not repeat the status card, current objective, warnings, or next step.
39
+
40
+ Offer six scenarios:
41
+
42
+ - **A. Build systems, tools, platforms, websites, or apps**: the user wants AI help to create or maintain a working project.
43
+ - **B. Organize research or write a report**: the user has sources, notes, articles, presentations, or a report goal.
44
+ - **C. Organize local files, Notion, Google Drive, or a knowledge base**: the user wants source, reference, mirror, and draft material kept clear.
45
+ - **D. Learn to code**: the user is a technical beginner and wants a small guided exercise.
46
+ - **E. Custom scenario**: the user has another goal.
47
+ - **F. Review installed external tools and design governance**: the user already has Connectors, MCPs, Plugins, Skills, or browser / notebook / crawler tools and wants a safe operating model.
48
+
49
+ ### 3. 5-step walk-through pattern
50
+
51
+ After the user picks a scenario, guide one small first task through five steps:
52
+
53
+ 1. Confirm project context: folder, existing material, current tools, source locations, and whether external tools are already connected.
54
+ 2. Explain in three plain points how Agent Handoff Kit helps this scenario.
55
+ 3. Ask for the first concrete task scope, offering four to six practical options.
56
+ 4. Suggest one minimum viable task that can usually be completed in 10-15 minutes.
57
+ 5. Wait for user confirmation, then transition to the regular work loop.
58
+
59
+ ### 4. Advance one step at a time
60
+
61
+ Do not run all five steps in one message. At each step:
62
+
63
+ - state what the AI will do,
64
+ - state what the user needs to answer or confirm,
65
+ - answer questions before continuing,
66
+ - let the user skip or change the step.
67
+
68
+ ### 5. Keep the first task small
69
+
70
+ The first task should be a preview, a short draft, a small classification sample, a dry-run, or another bounded result. Do not begin with broad refactors, bulk file moves, publishing, deployment, or destructive operations.
71
+
72
+ ### 6. Transition after onboarding
73
+
74
+ After the walk-through:
75
+
76
+ - load the regular pack(s) for the chosen task,
77
+ - unload this transient onboarding pack,
78
+ - enter the PLAN -> READ -> CHANGE -> QC -> PERSIST work loop,
79
+ - record the first-task scope in `SESSION_HANDOFF` when the persistence gate requires it.
80
+
81
+ ## Application Scenario Library
82
+
83
+ Each scenario keeps the same five-step rhythm. The model may adapt wording, but must preserve the intent, tone, and safety boundaries.
84
+
85
+ ### Scenario A. Build systems, tools, platforms, websites, or apps
86
+
87
+ Step A.1: ask for the project folder, current stack if known, whether git exists, and whether GitHub, Linear, Slack, Notion, Google Drive, or other external tools are connected.
88
+
89
+ Step A.2: explain that Kit helps the AI remember project state across sessions, avoid silent risky commands, and record what changed at closeout.
90
+
91
+ Step A.3: offer task choices such as fix a bug, add a feature, organize code, add tests, write README, or prepare a first commit.
92
+
93
+ Step A.4: suggest a small first task, such as a short README section, one failing test investigation, or a dry-run plan.
94
+
95
+ Step A.5: after confirmation, load the relevant coding / writing / safety packs and begin the normal work loop.
96
+
97
+ ### Scenario B. Organize research or write a report
98
+
99
+ Step B.1: ask for the topic, existing source locations, intended reader, and whether Notion, Google Drive, or another source tool is connected.
100
+
101
+ Step B.2: explain that Kit separates source evidence from inference, records source locations, and preserves progress across sessions.
102
+
103
+ Step B.3: offer task choices such as outline sections, register sources, summarize one source, draft a subsection, or review an existing draft.
104
+
105
+ Step B.4: suggest a small first task, such as a 5-7 heading outline with one sentence per section.
106
+
107
+ Step B.5: after confirmation, load research / writing / knowledge packs and begin the normal work loop.
108
+
109
+ ### Scenario C. Organize local files, Notion, Google Drive, or a knowledge base
110
+
111
+ Step C.1: ask what needs organizing: local folder, Notion database, Google Drive folder, or mixed sources. Ask which external tools are connected or unknown.
112
+
113
+ Step C.2: explain that Kit separates source of truth, references, mirrors, and drafts, and that risky file operations require dry-run and confirmation.
114
+
115
+ Step C.3: offer task choices such as scan and classify files, design a folder structure, draft a Notion schema, write a dry-run script, or align local references with an external index.
116
+
117
+ Step C.4: suggest a small first task, such as classifying a bounded sample without moving files.
118
+
119
+ Step C.5: after confirmation, load knowledge / safety / integrations packs as needed.
120
+
121
+ ### Scenario D. Learn to code
122
+
123
+ Step D.1: ask which direction the user wants: small automation, web page, Python tool, Git / GitHub basics, or another beginner task. Ask whether any relevant tools are already installed.
124
+
125
+ Step D.2: explain that Kit keeps learning progress across sessions, keeps risky operations explicit, and lets the user review each small change.
126
+
127
+ Step D.3: offer one small exercise, such as a dry-run file renamer, a one-page HTML example, or a tiny Python script.
128
+
129
+ Step D.4: keep the exercise small enough to explain line by line.
130
+
131
+ Step D.5: after confirmation, load coding / safety packs and begin the normal work loop.
132
+
133
+ ### Scenario E. Custom scenario
134
+
135
+ Step E.1: ask for four facts: objective, existing material or tools, technical comfort level, and the first small result the user wants.
136
+
137
+ Step E.2: explain how Kit helps the chosen scenario using continuity, safety, and source / artifact governance.
138
+
139
+ Step E.3: offer task choices tailored to the user's answer.
140
+
141
+ Step E.4: suggest one minimum viable first task.
142
+
143
+ Step E.5: after confirmation, load the appropriate regular pack combination.
144
+
145
+ ### Scenario F. External-tool governance
146
+
147
+ Use this scenario when the user already has external tools installed or asks how to use them safely across sessions. This scenario does not teach installation. It records declarations, boundaries, verification, and safe use.
148
+
149
+ Step F.1: collect installed external tools by category: Connectors, MCPs, Plugins, Skills, browser automation, crawlers, notebooks, or local helper services. If the user does not know the category, ask for names only and classify them.
150
+
151
+ Step F.2: explain credential separation: Kit files record tool names, project usage, access scope, and credential reference location only. They must never store API keys, OAuth tokens, secrets, or credential values.
152
+
153
+ Step F.3: map source-of-truth architecture: source of truth, index, persistent mirror, and working draft. Make each layer's write boundary explicit.
154
+
155
+ Step F.4: when authorized, write the declaration into `PROJECT_INDEX` `## Installed Integrations` and cross-reference relevant External Sources `via` values.
156
+
157
+ Step F.5: verify current availability using runtime-exposed tool schemas, official docs, or versioned local runbooks. Mark unavailable tools as blocked / unverified instead of guessing.
158
+
159
+ ## Cross-reference to guide.html
160
+
161
+ When the user asks for a fuller example, mention `agent-handoff-kit-guide.html` as an optional reference. The guide is not required reading.
162
+
163
+ - Case A aligns with Scenario A plus parts of Scenario C.
164
+ - Case B aligns with Scenario B plus Scenario F.
165
+ - Case C aligns with long-running project evolution.
166
+
167
+ ## Tone Discipline
168
+
169
+ Use plain user-facing language. Avoid internal jargon in onboarding replies unless the user asks for implementation details.
170
+
171
+ - Say "project registry" before exposing `PROJECT_INDEX`.
172
+ - Say "wrap up" or the user's own closeout phrase before exposing closeout internals.
173
+ - Say "next-session startup message" only when discussing the persisted handoff file.
174
+ - Say "working mode" before exposing "rule pack".
175
+ - Say "risky command" before exposing "destructive operation".
176
+
177
+ Keep user-facing explanations self-contained. For the public product's Chinese surfaces, use steady written Traditional Chinese and avoid Cantonese spoken characters. Inside this AI-facing pack, keep instructions in English and use Chinese only as quoted user phrases that the runtime must recognize.
178
+
179
+ ## Closeout
180
+
181
+ After onboarding finishes:
182
+
183
+ 1. Confirm that the user knows the next practical action, how to start a later session, and how to request closeout.
184
+ 2. Update `SESSION_HANDOFF` only when the persistence gate says the first-task scope or next action is durable.
185
+ 3. Record next priorities only when they affect a later session.
186
+ 4. Do not paste a separate stateful opening message in chat. The persisted `SESSION_HANDOFF` opening-message block remains authoritative.
187
+ 5. Unload this pack and continue with the relevant regular pack(s).
188
+
189
+ In a later session, reload onboarding only when the user gives a fresh onboarding signal or asks to restart the walk-through. Otherwise enter the normal work loop.
190
+
191
+ ## Anti-patterns
192
+
193
+ | Anti-pattern | Why it is wrong | Correct approach |
194
+ |---|---|---|
195
+ | Treating a vague first message as a specific task | The user may be trying to learn the workflow or choose a scenario. | Offer the A-F scenario chooser first. |
196
+ | Making the first task broad | A first-time user needs rhythm and confidence before large changes. | Suggest one 10-15 minute minimum viable task. |
197
+ | Explaining Kit internals before the user needs them | Internal labels increase cognitive load. | Explain the visible effect in plain language. |
198
+ | Assuming the user read README or guide pages | Many users start directly in an AI chat. | Surface only the concepts needed for the next step. |
199
+ | Keeping onboarding loaded after the first task starts | Onboarding is transient and will distract from normal task work. | Unload onboarding and load the regular pack(s). |
200
+ | Running all five steps without waiting | The user loses control of the walk-through. | Pause for confirmation at each step. |
201
+ | Assuming no Connector, MCP, Plugin, or Skill exists | Paste-only fallback creates the wrong operating model for users who already connected tools. | Ask a lightweight external-tool question in step 1, or use Scenario F. |
@@ -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
+ }