@venizia/vulcan 0.4.8 → 0.4.9-1

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.
Files changed (179) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +4 -3
  3. package/base/hooks/codex-guards.ts +17 -6
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +5 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +6 -6
  8. package/base/hooks/guard-remote-hosts.ts +14 -9
  9. package/base/hooks/guard-scripting.ts +6 -6
  10. package/base/hooks/guard-writes.ts +20 -11
  11. package/base/hooks/post-tool.ts +4 -3
  12. package/base/hooks/prompt-submit.ts +4 -3
  13. package/base/hooks/session-start.ts +5 -3
  14. package/base/hooks/stop.ts +4 -3
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/make/vulcan.mk +1 -4
  17. package/base/skills/build-a-feature/SKILL.md +1 -1
  18. package/base/skills/docs-update/SKILL.md +11 -5
  19. package/base/skills/docs-update/evals/evals.json +1 -1
  20. package/base/skills/docs-writing/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  22. package/base/skills/ship/SKILL.md +1 -1
  23. package/base/skills/visualize-work/SKILL.md +29 -6
  24. package/base/skills/visualize-work/references/spec.md +16 -5
  25. package/package.json +5 -6
  26. package/src/agents/atlas-block.ts +43 -43
  27. package/src/agents/codex-hooks.ts +55 -52
  28. package/src/agents/common/types.ts +1 -1
  29. package/src/agents/detect.ts +19 -16
  30. package/src/agents/exclude.ts +97 -98
  31. package/src/agents/hooks-json.ts +41 -43
  32. package/src/agents/local.ts +46 -43
  33. package/src/agents/prompt.ts +45 -42
  34. package/src/agents/render.ts +203 -201
  35. package/src/agents/resolve.ts +133 -134
  36. package/src/agents/table.ts +12 -8
  37. package/src/cli.ts +3 -1
  38. package/src/commands/add.command.ts +2 -2
  39. package/src/commands/agents.command.ts +11 -17
  40. package/src/commands/clean.command.ts +6 -6
  41. package/src/commands/doctor.command.ts +6 -4
  42. package/src/commands/help.command.ts +11 -9
  43. package/src/commands/init.command.ts +14 -8
  44. package/src/commands/preset.command.ts +2 -2
  45. package/src/commands/profile.command.ts +43 -50
  46. package/src/commands/sync.command.ts +109 -111
  47. package/src/commands/upgrade.command.ts +85 -78
  48. package/src/commands/visualize.command.ts +20 -5
  49. package/src/commands/x.command.ts +55 -50
  50. package/src/common/format.ts +23 -21
  51. package/src/common/index.ts +2 -0
  52. package/src/common/json.ts +8 -5
  53. package/src/common/layout-folder.ts +96 -111
  54. package/src/common/paths.ts +14 -12
  55. package/src/common/record.ts +7 -0
  56. package/src/common/text.ts +7 -0
  57. package/src/config/common/constants.ts +13 -1
  58. package/src/config/common/types.ts +8 -1
  59. package/src/config/loader.ts +53 -48
  60. package/src/config/packages.ts +17 -11
  61. package/src/config/schema.ts +54 -7
  62. package/src/create/add-app.ts +604 -493
  63. package/src/create/add-lib.ts +249 -242
  64. package/src/create/bunfig.ts +26 -23
  65. package/src/create/checks.ts +36 -34
  66. package/src/create/common/constants.ts +1 -0
  67. package/src/create/common/failure.ts +10 -0
  68. package/src/create/common/index.ts +2 -0
  69. package/src/create/common/preset-path.ts +11 -0
  70. package/src/create/common/types.ts +7 -2
  71. package/src/create/diff.ts +21 -23
  72. package/src/create/dockerignore.ts +26 -24
  73. package/src/create/files.ts +7 -5
  74. package/src/create/init-monorepo.ts +78 -80
  75. package/src/create/lib-preset.ts +62 -61
  76. package/src/create/manifest-json.ts +10 -4
  77. package/src/create/names.ts +217 -210
  78. package/src/create/next.ts +27 -24
  79. package/src/create/plan.ts +15 -12
  80. package/src/create/preset-diff.ts +415 -240
  81. package/src/create/preset-menu.ts +40 -34
  82. package/src/create/preset.ts +207 -194
  83. package/src/create/process.ts +80 -71
  84. package/src/create/scratch.ts +49 -48
  85. package/src/create/workspace.ts +423 -398
  86. package/src/doctor/checks.ts +1069 -998
  87. package/src/doctor/makefile.ts +17 -13
  88. package/src/doctor/runner.ts +88 -116
  89. package/src/doctor/skills.ts +97 -95
  90. package/src/doctor/tags.ts +44 -41
  91. package/src/hooks/codex-patch.ts +27 -24
  92. package/src/hooks/command-view.ts +44 -39
  93. package/src/hooks/common/constants.ts +0 -3
  94. package/src/hooks/common/types.ts +15 -1
  95. package/src/hooks/decision.ts +38 -42
  96. package/src/hooks/guard-git.ts +52 -50
  97. package/src/hooks/guard-manifest.ts +58 -55
  98. package/src/hooks/guard-outside.ts +109 -88
  99. package/src/hooks/guard-package.ts +86 -77
  100. package/src/hooks/guard-scripting.ts +20 -15
  101. package/src/hooks/guard-writes.ts +169 -111
  102. package/src/hooks/owner-reply.ts +128 -128
  103. package/src/hooks/post-tool.ts +94 -93
  104. package/src/hooks/project-guards.ts +93 -55
  105. package/src/hooks/project-tmp.ts +27 -24
  106. package/src/hooks/remote-hosts.ts +157 -149
  107. package/src/hooks/session-digest.ts +99 -95
  108. package/src/hooks/shell.ts +519 -500
  109. package/src/hooks/subagent-card.ts +11 -7
  110. package/src/hooks/trusted-scripts.ts +158 -80
  111. package/src/init/common/types.ts +1 -1
  112. package/src/init/scaffold.ts +137 -134
  113. package/src/local/clean.ts +39 -37
  114. package/src/local/format.ts +21 -17
  115. package/src/local/scan.ts +146 -140
  116. package/src/manifest/render.ts +127 -112
  117. package/src/owner/card.ts +51 -46
  118. package/src/owner/profile.ts +100 -96
  119. package/src/owner/reply-switch.ts +9 -6
  120. package/src/owner/shape.ts +72 -70
  121. package/src/owner/survey.ts +175 -164
  122. package/src/owner/view.ts +62 -59
  123. package/src/owner/violations.ts +119 -123
  124. package/src/router.ts +4 -1
  125. package/src/rules/base.ts +15 -11
  126. package/src/rules/common/types.ts +1 -1
  127. package/src/rules/parser.ts +39 -32
  128. package/src/rules/slots.ts +8 -6
  129. package/src/signals/claims.ts +30 -28
  130. package/src/signals/classify.ts +36 -33
  131. package/src/signals/loop.ts +39 -37
  132. package/src/signals/state.ts +80 -85
  133. package/src/skills/frontmatter.ts +28 -28
  134. package/src/sync/agent-files.ts +217 -199
  135. package/src/sync/agent-removal.ts +62 -68
  136. package/src/sync/atlas-block.ts +45 -43
  137. package/src/sync/base-rules.ts +32 -30
  138. package/src/sync/claude-launch.ts +74 -37
  139. package/src/sync/common/constants.ts +4 -0
  140. package/src/sync/common/index.ts +1 -0
  141. package/src/sync/common/symlink.ts +9 -0
  142. package/src/sync/common/types.ts +2 -2
  143. package/src/sync/exclude.ts +77 -69
  144. package/src/sync/local-choice.ts +50 -47
  145. package/src/sync/planner.ts +64 -68
  146. package/src/sync/prune.ts +52 -48
  147. package/src/sync/settings.ts +167 -168
  148. package/src/ui/capability.ts +12 -7
  149. package/src/ui/keyboard.ts +35 -33
  150. package/src/ui/prompt.ts +81 -77
  151. package/src/visualize/assets.ts +379 -195
  152. package/src/visualize/charts.ts +188 -176
  153. package/src/visualize/compare-css.ts +31 -0
  154. package/src/visualize/compare-render.ts +196 -0
  155. package/src/visualize/compare-schema.ts +81 -0
  156. package/src/visualize/compare-validate.ts +126 -0
  157. package/src/visualize/constants.ts +29 -3
  158. package/src/visualize/diagrams.ts +189 -174
  159. package/src/visualize/gate.ts +136 -0
  160. package/src/visualize/grid-span.ts +34 -0
  161. package/src/visualize/icons.ts +9 -4
  162. package/src/visualize/index.ts +2 -0
  163. package/src/visualize/kinds-css.ts +54 -0
  164. package/src/visualize/kinds-render.ts +698 -0
  165. package/src/visualize/kinds-schema.ts +148 -0
  166. package/src/visualize/kinds-validate.ts +186 -0
  167. package/src/visualize/labels-vi.ts +109 -0
  168. package/src/visualize/labels.ts +53 -0
  169. package/src/visualize/layout.ts +112 -92
  170. package/src/visualize/page.ts +140 -114
  171. package/src/visualize/render.ts +158 -114
  172. package/src/visualize/schema.ts +21 -1
  173. package/src/visualize/sections.ts +401 -309
  174. package/src/visualize/sources.ts +270 -0
  175. package/src/visualize/theme.ts +474 -0
  176. package/src/visualize/validate.ts +15 -5
  177. package/src/wiki/anchors.ts +39 -37
  178. package/src/wiki/command.ts +4 -4
  179. package/src/wiki/source-links.ts +49 -49
@@ -1,61 +1,37 @@
1
1
  import { Glob } from 'bun';
2
2
  import { spawnSync } from 'node:child_process';
3
- import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
3
+ import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
4
4
  import { basename, dirname, join, relative, sep } from 'node:path';
5
- import { BASE_DIRECTORY, ProjectLayout } from '../common/index.ts';
6
- import { LayoutKeys, layoutFoldersOf } from '../common/layout-folder.ts';
7
- import {
8
- coversFolder,
9
- declaresWorkspaces,
10
- MCP_SERVER_HINT,
11
- readWorkspaceGlobs,
12
- } from '../init/index.ts';
13
- import { resolvePackages } from '../config/index.ts';
5
+ import { BASE_DIRECTORY, ProjectLayout, RecordValue } from '../common/index.ts';
6
+ import { LayoutKeys, LayoutFolder } from '../common/layout-folder.ts';
7
+ import { MCP_SERVER_HINT, ProjectScaffold } from '../init/index.ts';
8
+ import { ProjectPackages } from '../config/index.ts';
14
9
  import type { TResolvedConfig } from '../config/index.ts';
10
+ import { BaseRules, RuleConstants, RuleParser, RuleSlots } from '../rules/index.ts';
11
+ import { ManifestConstants, ProjectManifest } from '../manifest/index.ts';
12
+ import { AgentScopes, AgentSelection, AgentTable, LocalChoice } from '../agents/index.ts';
15
13
  import {
16
- parseBaseReferences,
17
- readBaseRules,
18
- readRetiredRuleIds,
19
- readSlots,
20
- RuleConstants,
21
- } from '../rules/index.ts';
22
- import {
23
- isManifestCurrent,
24
- ManifestConstants,
25
- projectNameOf,
26
- renderManifest,
27
- } from '../manifest/index.ts';
28
- import {
29
- AgentScopes,
30
- readAgentTable,
31
- readLocalChoice,
32
- resolveAgentsQuietly,
33
- } from '../agents/index.ts';
34
- import {
35
- isTracked,
36
- mergedAtlasBlock,
37
- planLocalWorkspace,
38
- planManifest,
39
- planPrune,
40
- planSync,
14
+ AgentFiles,
15
+ AtlasBlockPlan,
16
+ LocalPlan,
17
+ PrunePlan,
18
+ SyncPlanner,
41
19
  SyncStatuses,
42
20
  } from '../sync/index.ts';
43
- import { formatAge, formatBytes, LocalConstants, LocalStates, scanLocal } from '../local/index.ts';
21
+ import { LocalConstants, LocalFormat, LocalScan, LocalStates } from '../local/index.ts';
44
22
  import {
45
- isOwnerReplyOff,
23
+ ReplySwitch,
46
24
  OwnerConstants,
47
25
  OwnerReplySwitch,
48
- profileIsIgnored,
49
- readProfile,
50
- readViolationCounts,
51
- violationLogBytes,
26
+ OwnerProfile,
27
+ ViolationLog,
52
28
  ViolationConstants,
53
29
  } from '../owner/index.ts';
54
- import { skillCatalogOf, triggerOf } from '@venizia/vulcan-atlas';
55
- import { trustOf, TrustStates } from '../hooks/index.ts';
30
+ import { SkillCatalog } from '@venizia/vulcan-atlas';
31
+ import { ScriptTrust, TrustStates } from '../hooks/index.ts';
56
32
  import { AppScripts, DoctorChecks, DoctorConstants } from './common/index.ts';
57
33
  import type { IViolation, TDoctorCheck } from './common/index.ts';
58
- import { parseMakeIncludes, parseMakeTargets } from './makefile.ts';
34
+ import { Makefile } from './makefile.ts';
59
35
 
60
36
  export interface ICheckContext {
61
37
  root: string;
@@ -83,102 +59,6 @@ const listDirectories = (opts: { directory: string }): string[] =>
83
59
  .map((entry) => entry.name)
84
60
  : [];
85
61
 
86
- export const checkLayout = (opts: ICheckContext): IViolation[] =>
87
- ['AGENTS.md', '.agents/rules.md', opts.config.knowledge.bundle]
88
- .filter((path) => !existsSync(join(opts.root, path)))
89
- .map((path) =>
90
- createViolation({
91
- check: DoctorChecks.LAYOUT,
92
- file: path,
93
- message: `missing - run '${ProjectLayout.VULCAN_COMMAND} init'`,
94
- }),
95
- );
96
-
97
- /**
98
- * The base owns the `V-` namespace: a project defines its rules with bare IDs, and a `V-` ID in its
99
- * rules points at a base rule - one the base does not carry, or has retired, dangles.
100
- */
101
- export const checkRuleIds = (opts: ICheckContext): IViolation[] => {
102
- const base = readBaseRules();
103
- const retired = new Set(readRetiredRuleIds());
104
-
105
- return parseBaseReferences({
106
- markdown: readText({ file: join(opts.root, '.agents', 'rules.md') }),
107
- })
108
- .filter((id) => base[id] === undefined)
109
- .map((id) =>
110
- createViolation({
111
- check: DoctorChecks.RULE_IDS,
112
- file: '.agents/rules.md',
113
- message: retired.has(id)
114
- ? `${id} is retired in the base - drop the reference`
115
- : `${id} is not a base rule - give the extension a bare ID`,
116
- }),
117
- );
118
- };
119
-
120
- export const checkRuleSlots = (opts: ICheckContext): IViolation[] => {
121
- const slots = readSlots();
122
- const violations: IViolation[] = [];
123
-
124
- for (const [id, slot] of Object.entries(slots)) {
125
- const choice = opts.config.rules[id];
126
- const options = Object.keys(slot.options).join(' | ');
127
-
128
- if (choice === undefined) {
129
- violations.push(
130
- createViolation({
131
- check: DoctorChecks.RULE_SLOTS,
132
- file: opts.configFile,
133
- message: `${id} needs a choice: rules: { '${id}': ${options} }`,
134
- }),
135
- );
136
- continue;
137
- }
138
-
139
- if (slot.options[choice] === undefined) {
140
- violations.push(
141
- createViolation({
142
- check: DoctorChecks.RULE_SLOTS,
143
- file: opts.configFile,
144
- message: `${id}: '${choice}' is not an option (${options})`,
145
- }),
146
- );
147
- }
148
- }
149
-
150
- for (const id of Object.keys(opts.config.rules).filter((ruleId) => slots[ruleId] === undefined)) {
151
- const namespaced = `${RuleConstants.BASE_NAMESPACE}${id}`;
152
-
153
- violations.push(
154
- createViolation({
155
- check: DoctorChecks.RULE_SLOTS,
156
- file: opts.configFile,
157
- message:
158
- slots[namespaced] === undefined
159
- ? `${id} is not a slot - only ${Object.keys(slots).join(', ')} take a choice`
160
- : `'${id}' is not a slot - the base rule is now '${namespaced}'`,
161
- }),
162
- );
163
- }
164
-
165
- return violations;
166
- };
167
-
168
- export const checkSkills = (opts: ICheckContext): IViolation[] => {
169
- const shipped = new Set(listDirectories({ directory: join(BASE_DIRECTORY, 'skills') }));
170
-
171
- return listDirectories({ directory: join(opts.root, '.agents', 'skills') })
172
- .filter((name) => shipped.has(name))
173
- .map((name) =>
174
- createViolation({
175
- check: DoctorChecks.SKILLS,
176
- file: `.agents/skills/${name}`,
177
- message: `'${name}' is a shipped skill - rename the project skill, for example to '${projectNameOf({ root: opts.root, config: opts.config })}-${name}'`,
178
- }),
179
- );
180
- };
181
-
182
62
  /**
183
63
  * The project's Makefile and every file it includes, recursively, relative to the root. Includes
184
64
  * under node_modules are shipped (vulcan.mk), never project targets.
@@ -196,7 +76,7 @@ const findProjectMakefiles = (opts: { root: string }): string[] => {
196
76
 
197
77
  found.push(file);
198
78
 
199
- for (const pattern of parseMakeIncludes({
79
+ for (const pattern of Makefile.parseMakeIncludes({
200
80
  makefile: readText({ file: join(opts.root, file) }),
201
81
  })) {
202
82
  const matches = [...new Glob(pattern).scanSync({ cwd: opts.root, onlyFiles: true })].sort();
@@ -208,132 +88,6 @@ const findProjectMakefiles = (opts: { root: string }): string[] => {
208
88
  return found;
209
89
  };
210
90
 
211
- export const checkMake = (opts: ICheckContext): IViolation[] => {
212
- const makefile = readText({ file: join(opts.root, 'Makefile') });
213
- const violations: IViolation[] = [];
214
-
215
- if (!DoctorConstants.MAKE_INCLUDE_PATTERN.test(makefile)) {
216
- violations.push(
217
- createViolation({
218
- check: DoctorChecks.MAKE,
219
- file: 'Makefile',
220
- message: `add: ${ProjectLayout.MAKE_INCLUDE_LINE}`,
221
- }),
222
- );
223
- }
224
-
225
- const shipped = new Set(
226
- parseMakeTargets({ makefile: readText({ file: join(BASE_DIRECTORY, 'make', 'vulcan.mk') }) }),
227
- );
228
-
229
- for (const file of findProjectMakefiles({ root: opts.root })) {
230
- const targets = parseMakeTargets({ makefile: readText({ file: join(opts.root, file) }) });
231
-
232
- for (const target of targets.filter((name) => shipped.has(name))) {
233
- violations.push(
234
- createViolation({
235
- check: DoctorChecks.MAKE,
236
- file,
237
- message: `'${target}' is a shipped target - give the project target another name`,
238
- }),
239
- );
240
- }
241
- }
242
-
243
- return violations;
244
- };
245
-
246
- export const checkHooks = (opts: ICheckContext): IViolation[] =>
247
- opts.config.hooks
248
- .filter((hook) => hook.command.includes(DoctorConstants.SHIPPED_HOOKS_PATH))
249
- .map((hook) =>
250
- createViolation({
251
- check: DoctorChecks.HOOKS,
252
- file: opts.configFile,
253
- message: `the ${hook.event} hook runs a shipped hook - sync registers those, never the project`,
254
- }),
255
- );
256
-
257
- export const checkAdapters = (opts: ICheckContext): IViolation[] => {
258
- const pending = planSync({
259
- root: opts.root,
260
- config: opts.config,
261
- agents: resolveAgentsQuietly({ root: opts.root, configAgents: opts.config.agents }),
262
- })
263
- .filter((action) => action.status !== SyncStatuses.UNCHANGED)
264
- .filter((action) => action.path !== join(opts.root, ManifestConstants.FILE));
265
- const absent = pending.filter((action) => action.status === SyncStatuses.CREATED);
266
- const differing = pending.filter((action) => action.status !== SyncStatuses.CREATED);
267
-
268
- // A clean checkout has none of the gitignored adapters: say so once, with the fix, not once per file.
269
- const violations =
270
- absent.length === 0
271
- ? []
272
- : [
273
- createViolation({
274
- check: DoctorChecks.ADAPTERS,
275
- file: relative(opts.root, absent[0].path),
276
- message: `not synced yet - run '${ProjectLayout.VULCAN_COMMAND} sync' (make agent-setup) first`,
277
- }),
278
- ];
279
-
280
- return [
281
- ...violations,
282
- ...differing.map((action) =>
283
- createViolation({
284
- check: DoctorChecks.ADAPTERS,
285
- file: relative(opts.root, action.path),
286
- message:
287
- action.status === SyncStatuses.SKIPPED
288
- ? (action.note ?? 'skipped by sync')
289
- : `stale (${action.status}) - run '${ProjectLayout.VULCAN_COMMAND} sync'`,
290
- }),
291
- ),
292
- ];
293
- };
294
-
295
- /** What `sync --prune` would remove: an old VULCAN or plugin-era hook command, a dead skill link. */
296
- export const checkPrune = (opts: ICheckContext): IViolation[] =>
297
- planPrune({ root: opts.root }).map((action) =>
298
- createViolation({
299
- check: DoctorChecks.PRUNE,
300
- file: relative(opts.root, action.path),
301
- message: `${action.note ?? 'stale'} - run '${ProjectLayout.VULCAN_COMMAND} sync --prune'`,
302
- }),
303
- );
304
-
305
- /**
306
- * C1: the committed manifest is what the config renders - atlas reads the file, never the config.
307
- * A file written before the `$generated` note existed is current; a hand-edited one is not.
308
- */
309
- export const checkManifest = (opts: ICheckContext): IViolation[] => {
310
- const action = planManifest({ root: opts.root, config: opts.config });
311
-
312
- if (
313
- action.status === SyncStatuses.UNCHANGED ||
314
- (action.status === SyncStatuses.REPLACED &&
315
- isManifestCurrent({
316
- committed: readFileSync(join(opts.root, ManifestConstants.FILE), 'utf8'),
317
- rendered: renderManifest({ root: opts.root, config: opts.config }),
318
- }))
319
- ) {
320
- return [];
321
- }
322
-
323
- const fix = `run '${ProjectLayout.VULCAN_COMMAND} sync' and commit it`;
324
-
325
- return [
326
- createViolation({
327
- check: DoctorChecks.MANIFEST,
328
- file: ManifestConstants.FILE,
329
- message:
330
- action.status === SyncStatuses.CREATED
331
- ? `missing - ${fix}`
332
- : `stale against the config, or edited by hand - the manifest is generated, never edit it: edit .configs/vulcan.config.* and ${fix}`,
333
- }),
334
- ];
335
- };
336
-
337
91
  const hasStylePackage = (opts: { directory: string }): boolean => {
338
92
  const file = join(opts.directory, 'package.json');
339
93
 
@@ -349,198 +103,6 @@ const hasStylePackage = (opts: { directory: string }): boolean => {
349
103
  return ProjectLayout.STYLE_PACKAGE in { ...manifest.dependencies, ...manifest.devDependencies };
350
104
  };
351
105
 
352
- /**
353
- * D9: the shared coding style - every lint config builds on it, and the package whose `.configs/`
354
- * holds the config declares it, or the root does. A project with no lint config declares it at the
355
- * root. Owners are `packages/*` and every configured package's `path`, such as `umbras/kit`.
356
- */
357
- export const checkStyle = (opts: ICheckContext): IViolation[] => {
358
- const violations: IViolation[] = [];
359
- const owners = [
360
- ...new Set([
361
- '.',
362
- ...listDirectories({ directory: join(opts.root, 'packages') }).map((name) =>
363
- join('packages', name),
364
- ),
365
- ...resolvePackages({ config: opts.config }).map(
366
- (entry) => relative(opts.root, join(opts.root, entry.path)) || '.',
367
- ),
368
- ]),
369
- ];
370
- const isRootDeclared = hasStylePackage({ directory: opts.root });
371
- let lintConfigs = 0;
372
-
373
- for (const owner of owners) {
374
- const configs = join(owner, '.configs');
375
- const found = ['.', ...new Set(Object.values(DoctorConstants.LINT_CONFIG_FOLDERS))].flatMap(
376
- (folder) => {
377
- const directory = join(configs, folder);
378
-
379
- return existsSync(join(opts.root, directory))
380
- ? readdirSync(join(opts.root, directory))
381
- .filter((file) => DoctorConstants.LINT_CONFIG_FILE.test(file))
382
- .map((file) => ({ file: join(directory, file), name: file, legacy: folder === '.' }))
383
- : [];
384
- },
385
- );
386
- const names = found.map((item) => item.file);
387
-
388
- lintConfigs += names.length;
389
-
390
- if (
391
- names.length > 0 &&
392
- !isRootDeclared &&
393
- !hasStylePackage({ directory: join(opts.root, owner) })
394
- ) {
395
- violations.push(
396
- createViolation({
397
- check: DoctorChecks.STYLE,
398
- file: join(owner, 'package.json'),
399
- message: `add ${ProjectLayout.STYLE_PACKAGE} as a devDependency - here, or at the root`,
400
- }),
401
- );
402
- }
403
-
404
- for (const item of found) {
405
- const { file } = item;
406
-
407
- if (item.legacy) {
408
- const tool = item.name.split('.')[0];
409
-
410
- violations.push(
411
- createViolation({
412
- check: DoctorChecks.STYLE,
413
- file,
414
- message: `move it to .configs/${DoctorConstants.LINT_CONFIG_FOLDERS[tool]}/${item.name}`,
415
- }),
416
- );
417
- }
418
-
419
- if (!readText({ file: join(opts.root, file) }).includes(ProjectLayout.STYLE_PACKAGE)) {
420
- violations.push(
421
- createViolation({
422
- check: DoctorChecks.STYLE,
423
- file,
424
- message: `build on the shared style: import from ${ProjectLayout.STYLE_PACKAGE}`,
425
- }),
426
- );
427
- }
428
- }
429
- }
430
-
431
- if (lintConfigs === 0 && !isRootDeclared) {
432
- violations.push(
433
- createViolation({
434
- check: DoctorChecks.STYLE,
435
- file: 'package.json',
436
- message: `add ${ProjectLayout.STYLE_PACKAGE} as a devDependency`,
437
- }),
438
- );
439
- }
440
-
441
- return violations;
442
- };
443
-
444
- /**
445
- * The scaffold is filled in: `init` writes a config and a knowledge index to be edited, and a
446
- * project that never did would otherwise pass. A workspaces project declares its packages, and the
447
- * knowledge index drops the scaffold marker once it describes the project.
448
- */
449
- export const checkScaffold = (opts: ICheckContext): IViolation[] => {
450
- const violations: IViolation[] = [];
451
-
452
- if (
453
- declaresWorkspaces({ root: opts.root }) &&
454
- resolvePackages({ config: opts.config }).length === 0
455
- ) {
456
- violations.push(
457
- createViolation({
458
- check: DoctorChecks.SCAFFOLD,
459
- file: opts.configFile,
460
- message:
461
- 'package.json declares workspaces but the config lists no packages - add packages: [{ dir, name, path }] in release order',
462
- }),
463
- );
464
- }
465
-
466
- const index = join(opts.config.knowledge.bundle, 'index.md');
467
-
468
- if (readText({ file: join(opts.root, index) }).includes(ProjectLayout.SCAFFOLD_MARKER)) {
469
- violations.push(
470
- createViolation({
471
- check: DoctorChecks.SCAFFOLD,
472
- file: index,
473
- message: `still the scaffold - describe the project, then delete the ${ProjectLayout.SCAFFOLD_MARKER} line`,
474
- }),
475
- );
476
- }
477
-
478
- return violations;
479
- };
480
-
481
- /** Apps sit in the folders the user named, and every named folder is a workspace. */
482
- export const checkApps = (opts: ICheckContext): IViolation[] => {
483
- const layout = opts.config.layout;
484
-
485
- if (layout === undefined) {
486
- return [];
487
- }
488
-
489
- const globs = readWorkspaceGlobs({ root: opts.root });
490
- const folders = LayoutKeys.ALL.flatMap((key) =>
491
- layoutFoldersOf({ value: layout[key] }).map((folder) => ({ side: key, folder })),
492
- );
493
- // A folder under `other` is deliberately not managed: it need not be a workspace, only a package in it is allowed.
494
- const violations = folders
495
- .filter(({ side, folder }) => side !== LayoutKeys.OTHER && !coversFolder({ globs, folder }))
496
- .map(({ side, folder }) =>
497
- createViolation({
498
- check: DoctorChecks.APPS,
499
- file: 'package.json',
500
- message: `layout.${side} '${folder}' is not in package.json workspaces - add '${folder}/*'`,
501
- }),
502
- );
503
- const names = folders.map(({ folder }) => folder);
504
- // A package may be an `other` folder itself (a docs site at `docs`); a side folder only holds packages.
505
- const otherNames = folders
506
- .filter(({ side }) => side === LayoutKeys.OTHER)
507
- .map(({ folder }) => folder);
508
-
509
- for (const entry of resolvePackages({ config: opts.config }).filter((item) => !item.retired)) {
510
- if (entry.kind === 'lib') {
511
- const parent = dirname(entry.path);
512
-
513
- // A library lives where the project keeps libraries; it only has to be a workspace.
514
- if (!coversFolder({ globs, folder: parent })) {
515
- violations.push(
516
- createViolation({
517
- check: DoctorChecks.APPS,
518
- file: opts.configFile,
519
- message: `package ${entry.dir} lives at ${entry.path}, which no workspace glob covers - add '${parent}/*' to workspaces`,
520
- }),
521
- );
522
- }
523
-
524
- continue;
525
- }
526
-
527
- if (
528
- !names.some((folder) => entry.path.startsWith(`${folder}/`)) &&
529
- !otherNames.includes(entry.path)
530
- ) {
531
- violations.push(
532
- createViolation({
533
- check: DoctorChecks.APPS,
534
- file: opts.configFile,
535
- message: `package ${entry.dir} lives at ${entry.path}, outside every layout folder (${names.join(', ')})`,
536
- }),
537
- );
538
- }
539
- }
540
-
541
- return violations;
542
- };
543
-
544
106
  const readScriptNames = (opts: { file: string }): string[] | undefined => {
545
107
  if (!existsSync(opts.file)) {
546
108
  return undefined;
@@ -561,75 +123,13 @@ const readScriptNames = (opts: { file: string }): string[] | undefined => {
561
123
  }
562
124
  };
563
125
 
564
- /**
565
- * Info only, never a failure: an app that lacks a standard script or carries a legacy one gets one
566
- * line naming them. Apps are the live packages inside the backend and frontend folders.
567
- */
568
- export const checkAppScripts = (opts: ICheckContext): IViolation[] => {
569
- const layout = opts.config.layout;
570
-
571
- if (layout === undefined) {
572
- return [];
573
- }
574
-
575
- const appFolders = [
576
- ...layoutFoldersOf({ value: layout.backend }),
577
- ...layoutFoldersOf({ value: layout.frontend }),
578
- ];
579
- const notes: IViolation[] = [];
580
-
581
- for (const entry of resolvePackages({ config: opts.config }).filter((item) => !item.retired)) {
582
- if (!appFolders.some((folder) => entry.path.startsWith(`${folder}/`))) {
583
- continue;
584
- }
585
-
586
- const file = `${entry.path}/package.json`;
587
- const names = readScriptNames({ file: join(opts.root, file) });
588
-
589
- if (names === undefined) {
590
- continue;
591
- }
592
-
593
- const missing = AppScripts.STANDARD.filter((name) => !names.includes(name));
594
- const legacy = AppScripts.LEGACY.filter((name) => names.includes(name));
595
- const parts = [
596
- ...(missing.length === 0 ? [] : [`missing ${missing.join(', ')}`]),
597
- ...(legacy.length === 0 ? [] : [`legacy ${legacy.join(', ')} (use the standard names)`]),
598
- ];
599
-
600
- if (parts.length > 0) {
601
- notes.push(
602
- createViolation({
603
- check: DoctorChecks.SCRIPTS,
604
- file,
605
- message: `app ${entry.dir}: ${parts.join('; ')}`,
606
- }),
607
- );
608
- }
609
- }
610
-
611
- return notes;
612
- };
613
-
614
- /** The developer's stored agents must parse and name known agents; a broken file would otherwise hide as a default. */
615
- export const checkAgents = (opts: ICheckContext): IViolation[] => {
616
- const stored = readLocalChoice({ root: opts.root });
617
-
618
- return stored.ok
619
- ? []
620
- : [
621
- createViolation({
622
- check: DoctorChecks.AGENTS,
623
- file: '.agents/vulcan.local.json',
624
- message: stored.error,
625
- }),
626
- ];
627
- };
628
-
629
126
  /** Info only: the Atlas block of AGENTS.md is missing or no longer matches the config. */
630
127
  const CANONICAL_ATLAS_ARGS = ['x', '--no-install', 'vulcan', 'x', 'atlas', 'mcp', '--root', '.'];
128
+
631
129
  const MCP_FILE = '.mcp.json';
130
+
632
131
  const CLAUDE_SETTINGS_FILE = '.claude/settings.json';
132
+
633
133
  const ATLAS_SERVER = 'atlas';
634
134
 
635
135
  const readJsonObject = (opts: { file: string }): Record<string, unknown> | undefined => {
@@ -644,9 +144,6 @@ const readJsonObject = (opts: { file: string }): Record<string, unknown> | undef
644
144
  }
645
145
  };
646
146
 
647
- const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unknown> } =>
648
- typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
649
-
650
147
  /** Whether git lists the file as untracked and not ignored: what a clean-tree check, such as a release, refuses on. */
651
148
  const isUntrackedAndVisible = (opts: { root: string; path: string }): boolean => {
652
149
  const listed = spawnSync('git', ['status', '--porcelain', '--', opts.path], {
@@ -661,601 +158,1175 @@ const isUntrackedAndVisible = (opts: { root: string; path: string }): boolean =>
661
158
  const mcpWarning = (opts: { file: string; message: string }): IViolation =>
662
159
  createViolation({ check: DoctorChecks.MCP, file: opts.file, message: opts.message });
663
160
 
664
- /**
665
- * The atlas server is registered the one way every project does: the root `.mcp.json` (a per-machine
666
- * file `sync` writes for the agents that read it) holds an `atlas` entry that runs the project's own
667
- * atlas (`--root .`), and the managed Claude settings enable `atlas` by that name. A server under
668
- * another name, or one that serves another folder, is never enabled automatically or serves the wrong
669
- * knowledge. A `.mcp.json` git still tracks is told how to hand over to `sync`; one that is untracked and not ignored is told how to hide it. Warnings, not violations.
670
- */
671
- export const checkMcpAtlas = (opts: ICheckContext): IViolation[] => {
672
- const warnings: IViolation[] = [];
673
- const file = join(opts.root, MCP_FILE);
674
- const chosen = resolveAgentsQuietly({ root: opts.root, configAgents: opts.config.agents });
675
- const readsMcpFile = readAgentTable().some(
676
- (entry) => chosen.includes(entry.id) && entry.mcp.scope === AgentScopes.SHARED,
161
+ const DOCKERFILE = '.configs/builders/Dockerfile';
162
+
163
+ const SECRET_LINES = ['**/.env', '**/.env.*', '!**/.env.example'];
164
+
165
+ const ADD_SECRET_LINES = `add ${SECRET_LINES[0]}, ${SECRET_LINES[1]} and ${SECRET_LINES[2]} (in that order) to the root .dockerignore`;
166
+
167
+ /** Whether a `.dockerignore` pattern, as Docker reads it, names the file `opts.file` at any depth. */
168
+ const patternNames = (opts: { pattern: string; file: string }): boolean => {
169
+ const bare = opts.pattern.replace(/^\*\*\//, '').replace(/^\//, '');
170
+
171
+ return (
172
+ bare === opts.file ||
173
+ (bare.endsWith('*') && opts.file.startsWith(bare.slice(0, -1)) && bare.startsWith('.env'))
677
174
  );
175
+ };
678
176
 
679
- // The root `.mcp.json` is a per-machine file of the agents that read it; a missing one is the
680
- // `adapters` check's (not synced yet), so only an existing file is looked at.
681
- if (readsMcpFile && existsSync(file)) {
682
- if (isTracked({ root: opts.root, path: MCP_FILE })) {
683
- warnings.push(
684
- mcpWarning({
685
- file: MCP_FILE,
686
- message:
687
- 'tracked by git; VULCAN now writes it per machine. Run `git rm --cached .mcp.json` and let sync manage it.',
688
- }),
689
- );
690
- } else if (isUntrackedAndVisible({ root: opts.root, path: MCP_FILE })) {
691
- warnings.push(
692
- mcpWarning({
693
- file: MCP_FILE,
694
- message:
695
- 'untracked and not ignored, so a clean-tree check (a release) refuses to run. Add `/.mcp.json` to .gitignore, or run `vulcan sync` at the top level of the repository, which lists it in .git/info/exclude.',
696
- }),
697
- );
177
+ /** Whether the last pattern that names `opts.file` excludes it: a later `!` line brings it back. */
178
+ const excludes = (opts: { lines: string[]; file: string }): boolean => {
179
+ let excluded = false;
180
+
181
+ for (const line of opts.lines) {
182
+ const negated = line.startsWith('!');
183
+
184
+ if (patternNames({ pattern: negated ? line.slice(1) : line, file: opts.file })) {
185
+ excluded = !negated;
698
186
  }
187
+ }
699
188
 
700
- const parsed = readJsonObject({ file });
189
+ return excluded;
190
+ };
701
191
 
702
- if (parsed === undefined) {
703
- warnings.push(
704
- mcpWarning({
705
- file: MCP_FILE,
706
- message: `not valid JSON - it must hold ${MCP_SERVER_HINT} under mcpServers`,
192
+ const FMT_SECTION_ADVICE =
193
+ 'add a [fmt] section (printWidth = 100, singleQuote = true, arrowParens = "always", flavor = "oxfmt"): without it bun fmt formats with Bun\'s defaults, not the shared style';
194
+
195
+ const FMT_FLAVOR_ADVICE =
196
+ 'without it bun fmt uses its default style when oxfmt is not a dependency, and the output changes';
197
+
198
+ const OXFMT_LOADED_ADVICE =
199
+ 'bun fmt loads it and it overrides the [fmt] section of bunfig.toml - delete it, or move its settings to [fmt]';
200
+
201
+ /** The folders that can hold a package.json and an oxfmt config: the root, `packages/*` and every configured package. */
202
+ const formatOwners = (opts: ICheckContext): string[] => [
203
+ ...new Set([
204
+ '.',
205
+ ...listDirectories({ directory: join(opts.root, 'packages') }).map((name) =>
206
+ join('packages', name),
207
+ ),
208
+ ...ProjectPackages.resolve({ config: opts.config })
209
+ .filter((entry) => !entry.retired)
210
+ .map((entry) => relative(opts.root, join(opts.root, entry.path)) || '.'),
211
+ ]),
212
+ ];
213
+
214
+ /** The size of `.agents/local/` once it is large: where the space went, and the command that gives it back. */
215
+ /** The states of a listed script worth a warning: a typo or a script nobody committed. A modified one is normal work, so it is only a note. */
216
+ const STALE_TRUST_STATES = new Set<string>([
217
+ TrustStates.MISSING,
218
+ TrustStates.UNTRACKED,
219
+ TrustStates.UNCOMMITTED,
220
+ TrustStates.SYMLINK,
221
+ TrustStates.UNKNOWN,
222
+ ]);
223
+
224
+ /** The path of a `guard.writes.trustedScripts` entry, and the subcommands when it is the object form. */
225
+ const trustedScriptOf = (opts: {
226
+ entry: TResolvedConfig['guard']['writes']['trustedScripts'][number];
227
+ }): { script: string; readOnly: string[] | undefined } =>
228
+ typeof opts.entry === 'string'
229
+ ? { script: opts.entry, readOnly: undefined }
230
+ : { script: opts.entry.script, readOnly: opts.entry.readOnly };
231
+
232
+ export class ProjectContract {
233
+ static checkLayout(opts: ICheckContext): IViolation[] {
234
+ return ['AGENTS.md', '.agents/rules.md', opts.config.knowledge.bundle]
235
+ .filter((path) => !existsSync(join(opts.root, path)))
236
+ .map((path) =>
237
+ createViolation({
238
+ check: DoctorChecks.LAYOUT,
239
+ file: path,
240
+ message: `missing - run '${ProjectLayout.VULCAN_COMMAND} init'`,
707
241
  }),
708
242
  );
709
- } else {
710
- const holder = { value: parsed['mcpServers'] };
711
- const servers = isRecord(holder) ? holder.value : {};
712
- const entry = { value: servers[ATLAS_SERVER] };
713
- const args = isRecord(entry) ? entry.value['args'] : undefined;
714
- const isCanonical =
715
- isRecord(entry) &&
716
- entry.value['command'] === 'bun' &&
717
- Array.isArray(args) &&
718
- args.length === CANONICAL_ATLAS_ARGS.length &&
719
- args.every((arg, index) => arg === CANONICAL_ATLAS_ARGS[index]);
720
-
721
- if (!isRecord(entry)) {
722
- warnings.push(
723
- mcpWarning({
724
- file: MCP_FILE,
725
- message: `no server named atlas (found: ${Object.keys(servers).join(', ') || 'none'}): a differently named server is not enabled automatically - use ${MCP_SERVER_HINT}`,
243
+ }
244
+
245
+ /**
246
+ * The base owns the `V-` namespace: a project defines its rules with bare IDs, and a `V-` ID in its
247
+ * rules points at a base rule - one the base does not carry, or has retired, dangles.
248
+ */
249
+ static checkRuleIds(opts: ICheckContext): IViolation[] {
250
+ const base = BaseRules.read();
251
+ const retired = new Set(BaseRules.readRetiredIds());
252
+
253
+ return RuleParser.parseBaseReferences({
254
+ markdown: readText({ file: join(opts.root, '.agents', 'rules.md') }),
255
+ })
256
+ .filter((id) => base[id] === undefined)
257
+ .map((id) =>
258
+ createViolation({
259
+ check: DoctorChecks.RULE_IDS,
260
+ file: '.agents/rules.md',
261
+ message: retired.has(id)
262
+ ? `${id} is retired in the base - drop the reference`
263
+ : `${id} is not a base rule - give the extension a bare ID`,
264
+ }),
265
+ );
266
+ }
267
+
268
+ static checkRuleSlots(opts: ICheckContext): IViolation[] {
269
+ const slots = RuleSlots.read();
270
+ const violations: IViolation[] = [];
271
+
272
+ for (const [id, slot] of Object.entries(slots)) {
273
+ const choice = opts.config.rules[id];
274
+ const options = Object.keys(slot.options).join(' | ');
275
+
276
+ if (choice === undefined) {
277
+ violations.push(
278
+ createViolation({
279
+ check: DoctorChecks.RULE_SLOTS,
280
+ file: opts.configFile,
281
+ message: `${id} needs a choice: rules: { '${id}': ${options} }`,
726
282
  }),
727
283
  );
728
- } else if (!isCanonical) {
729
- const shown = JSON.stringify(entry.value)
730
- .replace('{"command":', '{ "command": ')
731
- .replace(',"args":[', ', "args": [')
732
- .replaceAll('","', '", "')
733
- .replace(/\]\}$/, '] }');
284
+ continue;
285
+ }
734
286
 
735
- warnings.push(
736
- mcpWarning({
737
- file: MCP_FILE,
738
- message: `the atlas entry is ${shown}, expected ${MCP_SERVER_HINT}`,
287
+ if (slot.options[choice] === undefined) {
288
+ violations.push(
289
+ createViolation({
290
+ check: DoctorChecks.RULE_SLOTS,
291
+ file: opts.configFile,
292
+ message: `${id}: '${choice}' is not an option (${options})`,
739
293
  }),
740
294
  );
741
295
  }
742
296
  }
297
+
298
+ for (const id of Object.keys(opts.config.rules).filter(
299
+ (ruleId) => slots[ruleId] === undefined,
300
+ )) {
301
+ const namespaced = `${RuleConstants.BASE_NAMESPACE}${id}`;
302
+
303
+ violations.push(
304
+ createViolation({
305
+ check: DoctorChecks.RULE_SLOTS,
306
+ file: opts.configFile,
307
+ message:
308
+ slots[namespaced] === undefined
309
+ ? `${id} is not a slot - only ${Object.keys(slots).join(', ')} take a choice`
310
+ : `'${id}' is not a slot - the base rule is now '${namespaced}'`,
311
+ }),
312
+ );
313
+ }
314
+
315
+ return violations;
743
316
  }
744
317
 
745
- const settings = join(opts.root, CLAUDE_SETTINGS_FILE);
746
- const enabled = existsSync(settings)
747
- ? readJsonObject({ file: settings })?.['enabledMcpjsonServers']
748
- : undefined;
318
+ static checkSkills(opts: ICheckContext): IViolation[] {
319
+ const shipped = new Set(listDirectories({ directory: join(BASE_DIRECTORY, 'skills') }));
749
320
 
750
- if (existsSync(settings) && !(Array.isArray(enabled) && enabled.includes(ATLAS_SERVER))) {
751
- const has = Array.isArray(enabled) ? enabled.map(String).join(', ') : 'none';
321
+ return listDirectories({ directory: join(opts.root, '.agents', 'skills') })
322
+ .filter((name) => shipped.has(name))
323
+ .map((name) =>
324
+ createViolation({
325
+ check: DoctorChecks.SKILLS,
326
+ file: `.agents/skills/${name}`,
327
+ message: `'${name}' is a shipped skill - rename the project skill, for example to '${ProjectManifest.projectNameOf({ root: opts.root, config: opts.config })}-${name}'`,
328
+ }),
329
+ );
330
+ }
331
+
332
+ static checkMake(opts: ICheckContext): IViolation[] {
333
+ const makefile = readText({ file: join(opts.root, 'Makefile') });
334
+ const violations: IViolation[] = [];
335
+
336
+ if (!DoctorConstants.MAKE_INCLUDE_PATTERN.test(makefile)) {
337
+ violations.push(
338
+ createViolation({
339
+ check: DoctorChecks.MAKE,
340
+ file: 'Makefile',
341
+ message: `add: ${ProjectLayout.MAKE_INCLUDE_LINE}`,
342
+ }),
343
+ );
344
+ }
752
345
 
753
- warnings.push(
754
- mcpWarning({
755
- file: CLAUDE_SETTINGS_FILE,
756
- message: `enabledMcpjsonServers does not include atlas (has: ${has}): Claude asks before using the server - run vulcan sync`,
346
+ const shipped = new Set(
347
+ Makefile.parseMakeTargets({
348
+ makefile: readText({ file: join(BASE_DIRECTORY, 'make', 'vulcan.mk') }),
757
349
  }),
758
350
  );
351
+
352
+ for (const file of findProjectMakefiles({ root: opts.root })) {
353
+ const targets = Makefile.parseMakeTargets({
354
+ makefile: readText({ file: join(opts.root, file) }),
355
+ });
356
+
357
+ for (const target of targets.filter((name) => shipped.has(name))) {
358
+ violations.push(
359
+ createViolation({
360
+ check: DoctorChecks.MAKE,
361
+ file,
362
+ message: `'${target}' is a shipped target - give the project target another name`,
363
+ }),
364
+ );
365
+ }
366
+ }
367
+
368
+ return violations;
759
369
  }
760
370
 
761
- return warnings;
762
- };
371
+ static checkHooks(opts: ICheckContext): IViolation[] {
372
+ return opts.config.hooks
373
+ .filter((hook) => hook.command.includes(DoctorConstants.SHIPPED_HOOKS_PATH))
374
+ .map((hook) =>
375
+ createViolation({
376
+ check: DoctorChecks.HOOKS,
377
+ file: opts.configFile,
378
+ message: `the ${hook.event} hook runs a shipped hook - sync registers those, never the project`,
379
+ }),
380
+ );
381
+ }
763
382
 
764
- const DOCKERFILE = '.configs/builders/Dockerfile';
383
+ static checkAdapters(opts: ICheckContext): IViolation[] {
384
+ const pending = SyncPlanner.plan({
385
+ root: opts.root,
386
+ config: opts.config,
387
+ agents: AgentSelection.resolveQuietly({ root: opts.root, configAgents: opts.config.agents }),
388
+ })
389
+ .filter((action) => action.status !== SyncStatuses.UNCHANGED)
390
+ .filter((action) => action.path !== join(opts.root, ManifestConstants.FILE));
391
+ const absent = pending.filter((action) => action.status === SyncStatuses.CREATED);
392
+ const differing = pending.filter((action) => action.status !== SyncStatuses.CREATED);
393
+
394
+ // A clean checkout has none of the gitignored adapters: say so once, with the fix, not once per file.
395
+ const violations =
396
+ absent.length === 0
397
+ ? []
398
+ : [
399
+ createViolation({
400
+ check: DoctorChecks.ADAPTERS,
401
+ file: relative(opts.root, absent[0].path),
402
+ message: `not synced yet - run '${ProjectLayout.VULCAN_COMMAND} sync' (make vulcan-sync) first`,
403
+ }),
404
+ ];
405
+
406
+ return [
407
+ ...violations,
408
+ ...differing.map((action) =>
409
+ createViolation({
410
+ check: DoctorChecks.ADAPTERS,
411
+ file: relative(opts.root, action.path),
412
+ message:
413
+ action.status === SyncStatuses.SKIPPED
414
+ ? (action.note ?? 'skipped by sync')
415
+ : `stale (${action.status}) - run '${ProjectLayout.VULCAN_COMMAND} sync'`,
416
+ }),
417
+ ),
418
+ ];
419
+ }
765
420
 
766
- const SECRET_LINES = ['**/.env', '**/.env.*', '!**/.env.example'];
767
- const ADD_SECRET_LINES = `add ${SECRET_LINES[0]}, ${SECRET_LINES[1]} and ${SECRET_LINES[2]} (in that order) to the root .dockerignore`;
421
+ /** What `sync --prune` would remove: an old VULCAN or plugin-era hook command, a dead skill link. */
422
+ static checkPrune(opts: ICheckContext): IViolation[] {
423
+ return PrunePlan.plan({ root: opts.root }).map((action) =>
424
+ createViolation({
425
+ check: DoctorChecks.PRUNE,
426
+ file: relative(opts.root, action.path),
427
+ message: `${action.note ?? 'stale'} - run '${ProjectLayout.VULCAN_COMMAND} sync --prune'`,
428
+ }),
429
+ );
430
+ }
768
431
 
769
- /** Whether a `.dockerignore` pattern, as Docker reads it, names the file `opts.file` at any depth. */
770
- const patternNames = (opts: { pattern: string; file: string }): boolean => {
771
- const bare = opts.pattern.replace(/^\*\*\//, '').replace(/^\//, '');
432
+ /**
433
+ * C1: the committed manifest is what the config renders - atlas reads the file, never the config.
434
+ * A file written before the `$generated` note existed is current; a hand-edited one is not.
435
+ */
436
+ static checkManifest(opts: ICheckContext): IViolation[] {
437
+ const action = SyncPlanner.planManifest({ root: opts.root, config: opts.config });
772
438
 
773
- return (
774
- bare === opts.file ||
775
- (bare.endsWith('*') && opts.file.startsWith(bare.slice(0, -1)) && bare.startsWith('.env'))
776
- );
777
- };
439
+ if (
440
+ action.status === SyncStatuses.UNCHANGED ||
441
+ (action.status === SyncStatuses.REPLACED &&
442
+ ProjectManifest.isCurrent({
443
+ committed: readFileSync(join(opts.root, ManifestConstants.FILE), 'utf8'),
444
+ rendered: ProjectManifest.render({ root: opts.root, config: opts.config }),
445
+ }))
446
+ ) {
447
+ return [];
448
+ }
778
449
 
779
- /** Whether the last pattern that names `opts.file` excludes it: a later `!` line brings it back. */
780
- const excludes = (opts: { lines: string[]; file: string }): boolean => {
781
- let excluded = false;
450
+ const fix = `run '${ProjectLayout.VULCAN_COMMAND} sync' and commit it`;
782
451
 
783
- for (const line of opts.lines) {
784
- const negated = line.startsWith('!');
452
+ return [
453
+ createViolation({
454
+ check: DoctorChecks.MANIFEST,
455
+ file: ManifestConstants.FILE,
456
+ message:
457
+ action.status === SyncStatuses.CREATED
458
+ ? `missing - ${fix}`
459
+ : `stale against the config, or edited by hand - the manifest is generated, never edit it: edit .configs/vulcan.config.* and ${fix}`,
460
+ }),
461
+ ];
462
+ }
785
463
 
786
- if (patternNames({ pattern: negated ? line.slice(1) : line, file: opts.file })) {
787
- excluded = !negated;
464
+ /**
465
+ * D9: the shared coding style - every lint config builds on it, and the package whose `.configs/`
466
+ * holds the config declares it, or the root does. A project with no lint config declares it at the
467
+ * root. Owners are `packages/*` and every configured package's `path`, such as `umbras/kit`.
468
+ */
469
+ static checkStyle(opts: ICheckContext): IViolation[] {
470
+ const violations: IViolation[] = [];
471
+ const owners = [
472
+ ...new Set([
473
+ '.',
474
+ ...listDirectories({ directory: join(opts.root, 'packages') }).map((name) =>
475
+ join('packages', name),
476
+ ),
477
+ ...ProjectPackages.resolve({ config: opts.config }).map(
478
+ (entry) => relative(opts.root, join(opts.root, entry.path)) || '.',
479
+ ),
480
+ ]),
481
+ ];
482
+ const isRootDeclared = hasStylePackage({ directory: opts.root });
483
+ let lintConfigs = 0;
484
+
485
+ for (const owner of owners) {
486
+ const configs = join(owner, '.configs');
487
+ const found = ['.', ...new Set(Object.values(DoctorConstants.LINT_CONFIG_FOLDERS))].flatMap(
488
+ (folder) => {
489
+ const directory = join(configs, folder);
490
+
491
+ return existsSync(join(opts.root, directory))
492
+ ? readdirSync(join(opts.root, directory))
493
+ .filter((file) => DoctorConstants.LINT_CONFIG_FILE.test(file))
494
+ .map((file) => ({
495
+ file: join(directory, file),
496
+ name: file,
497
+ legacy: folder === '.',
498
+ }))
499
+ : [];
500
+ },
501
+ );
502
+ const names = found.map((item) => item.file);
503
+
504
+ lintConfigs += names.length;
505
+
506
+ if (
507
+ names.length > 0 &&
508
+ !isRootDeclared &&
509
+ !hasStylePackage({ directory: join(opts.root, owner) })
510
+ ) {
511
+ violations.push(
512
+ createViolation({
513
+ check: DoctorChecks.STYLE,
514
+ file: join(owner, 'package.json'),
515
+ message: `add ${ProjectLayout.STYLE_PACKAGE} as a devDependency - here, or at the root`,
516
+ }),
517
+ );
518
+ }
519
+
520
+ for (const item of found) {
521
+ const { file } = item;
522
+
523
+ if (item.legacy) {
524
+ const tool = item.name.split('.')[0];
525
+
526
+ violations.push(
527
+ createViolation({
528
+ check: DoctorChecks.STYLE,
529
+ file,
530
+ message: `move it to .configs/${DoctorConstants.LINT_CONFIG_FOLDERS[tool]}/${item.name}`,
531
+ }),
532
+ );
533
+ }
534
+
535
+ if (!readText({ file: join(opts.root, file) }).includes(ProjectLayout.STYLE_PACKAGE)) {
536
+ violations.push(
537
+ createViolation({
538
+ check: DoctorChecks.STYLE,
539
+ file,
540
+ message: `build on the shared style: import from ${ProjectLayout.STYLE_PACKAGE}`,
541
+ }),
542
+ );
543
+ }
544
+ }
788
545
  }
546
+
547
+ if (lintConfigs === 0 && !isRootDeclared) {
548
+ violations.push(
549
+ createViolation({
550
+ check: DoctorChecks.STYLE,
551
+ file: 'package.json',
552
+ message: `add ${ProjectLayout.STYLE_PACKAGE} as a devDependency`,
553
+ }),
554
+ );
555
+ }
556
+
557
+ return violations;
789
558
  }
790
559
 
791
- return excluded;
792
- };
560
+ /**
561
+ * The scaffold is filled in: `init` writes a config and a knowledge index to be edited, and a
562
+ * project that never did would otherwise pass. A workspaces project declares its packages, and the
563
+ * knowledge index drops the scaffold marker once it describes the project.
564
+ */
565
+ static checkScaffold(opts: ICheckContext): IViolation[] {
566
+ const violations: IViolation[] = [];
793
567
 
794
- /**
795
- * A Dockerfile is built from the project root. Without a root `.dockerignore` the context carries
796
- * node_modules, dist, .git and every `.env` (secrets that would land in an image layer a CI cache
797
- * can keep); with one that does not exclude `.env` and `.env.*` the secrets are still copied.
798
- * A warning, not a violation: the exit code is unchanged, so a project made before this check
799
- * does not start failing.
800
- */
801
- export const checkDockerignore = (opts: ICheckContext): IViolation[] => {
802
- const file = join(opts.root, '.dockerignore');
803
- const lines = existsSync(file)
804
- ? readText({ file })
805
- .split('\n')
806
- .map((line) => line.trim())
807
- .filter((line) => line !== '' && !line.startsWith('#'))
808
- : undefined;
809
-
810
- if (
811
- lines !== undefined &&
812
- excludes({ lines, file: '.env' }) &&
813
- excludes({ lines, file: '.env.production' })
814
- ) {
815
- return [];
568
+ if (
569
+ ProjectScaffold.declaresWorkspaces({ root: opts.root }) &&
570
+ ProjectPackages.resolve({ config: opts.config }).length === 0
571
+ ) {
572
+ violations.push(
573
+ createViolation({
574
+ check: DoctorChecks.SCAFFOLD,
575
+ file: opts.configFile,
576
+ message:
577
+ 'package.json declares workspaces but the config lists no packages - add packages: [{ dir, name, path }] in release order',
578
+ }),
579
+ );
580
+ }
581
+
582
+ const index = join(opts.config.knowledge.bundle, 'index.md');
583
+
584
+ if (readText({ file: join(opts.root, index) }).includes(ProjectLayout.SCAFFOLD_MARKER)) {
585
+ violations.push(
586
+ createViolation({
587
+ check: DoctorChecks.SCAFFOLD,
588
+ file: index,
589
+ message: `still the scaffold - describe the project, then delete the ${ProjectLayout.SCAFFOLD_MARKER} line`,
590
+ }),
591
+ );
592
+ }
593
+
594
+ return violations;
816
595
  }
817
596
 
818
- const apps = resolvePackages({ config: opts.config })
819
- .filter((entry) => !entry.retired && existsSync(join(opts.root, entry.path, DOCKERFILE)))
820
- .map((entry) => entry.dir);
597
+ /** Apps sit in the folders the user named, and every named folder is a workspace. */
598
+ static checkApps(opts: ICheckContext): IViolation[] {
599
+ const layout = opts.config.layout;
600
+
601
+ if (layout === undefined) {
602
+ return [];
603
+ }
604
+
605
+ const globs = ProjectScaffold.readWorkspaceGlobs({ root: opts.root });
606
+ const folders = LayoutKeys.ALL.flatMap((key) =>
607
+ LayoutFolder.layoutFoldersOf({ value: layout[key] }).map((folder) => ({ side: key, folder })),
608
+ );
609
+ // A folder under `other` is deliberately not managed: it need not be a workspace, only a package in it is allowed.
610
+ const violations = folders
611
+ .filter(
612
+ ({ side, folder }) =>
613
+ side !== LayoutKeys.OTHER && !ProjectScaffold.coversFolder({ globs, folder }),
614
+ )
615
+ .map(({ side, folder }) =>
616
+ createViolation({
617
+ check: DoctorChecks.APPS,
618
+ file: 'package.json',
619
+ message: `layout.${side} '${folder}' is not in package.json workspaces - add '${folder}/*'`,
620
+ }),
621
+ );
622
+ const names = folders.map(({ folder }) => folder);
623
+ // A package may be an `other` folder itself (a docs site at `docs`); a side folder only holds packages.
624
+ const otherNames = folders
625
+ .filter(({ side }) => side === LayoutKeys.OTHER)
626
+ .map(({ folder }) => folder);
627
+
628
+ for (const entry of ProjectPackages.resolve({ config: opts.config }).filter(
629
+ (item) => !item.retired,
630
+ )) {
631
+ if (entry.kind === 'lib') {
632
+ const parent = dirname(entry.path);
633
+
634
+ // A library lives where the project keeps libraries; it only has to be a workspace.
635
+ if (!ProjectScaffold.coversFolder({ globs, folder: parent })) {
636
+ violations.push(
637
+ createViolation({
638
+ check: DoctorChecks.APPS,
639
+ file: opts.configFile,
640
+ message: `package ${entry.dir} lives at ${entry.path}, which no workspace glob covers - add '${parent}/*' to workspaces`,
641
+ }),
642
+ );
643
+ }
644
+
645
+ continue;
646
+ }
647
+
648
+ if (
649
+ !names.some((folder) => entry.path.startsWith(`${folder}/`)) &&
650
+ !otherNames.includes(entry.path)
651
+ ) {
652
+ violations.push(
653
+ createViolation({
654
+ check: DoctorChecks.APPS,
655
+ file: opts.configFile,
656
+ message: `package ${entry.dir} lives at ${entry.path}, outside every layout folder (${names.join(', ')})`,
657
+ }),
658
+ );
659
+ }
660
+ }
821
661
 
822
- if (apps.length === 0) {
823
- return [];
662
+ return violations;
824
663
  }
825
664
 
826
- const subject = apps.length === 1 ? `app ${apps[0]} has` : `apps ${apps.join(', ')} have`;
827
-
828
- return [
829
- createViolation({
830
- check: DoctorChecks.DOCKERIGNORE,
831
- file: '.dockerignore',
832
- message:
833
- lines === undefined
834
- ? `${subject} a Dockerfile and the root has no .dockerignore: the build context would carry node_modules, dist, .git and every .env file (secrets) - create it, then ${ADD_SECRET_LINES}`
835
- : `${subject} a Dockerfile and the root .dockerignore does not exclude .env files, which hold secrets and would land in the image layer: ${ADD_SECRET_LINES}`,
836
- }),
837
- ];
838
- };
665
+ /**
666
+ * Info only, never a failure: an app that lacks a standard script or carries a legacy one gets one
667
+ * line naming them. Apps are the live packages inside the backend and frontend folders.
668
+ */
669
+ static checkAppScripts(opts: ICheckContext): IViolation[] {
670
+ const layout = opts.config.layout;
839
671
 
840
- const FMT_SECTION_ADVICE =
841
- 'add a [fmt] section (printWidth = 100, singleQuote = true, arrowParens = "always", flavor = "oxfmt"): without it bun fmt formats with Bun\'s defaults, not the shared style';
842
- const FMT_FLAVOR_ADVICE =
843
- 'without it bun fmt uses its default style when oxfmt is not a dependency, and the output changes';
844
- const OXFMT_LOADED_ADVICE =
845
- 'bun fmt loads it and it overrides the [fmt] section of bunfig.toml - delete it, or move its settings to [fmt]';
672
+ if (layout === undefined) {
673
+ return [];
674
+ }
846
675
 
847
- /** The folders that can hold a package.json and an oxfmt config: the root, `packages/*` and every configured package. */
848
- const formatOwners = (opts: ICheckContext): string[] => [
849
- ...new Set([
850
- '.',
851
- ...listDirectories({ directory: join(opts.root, 'packages') }).map((name) =>
852
- join('packages', name),
853
- ),
854
- ...resolvePackages({ config: opts.config })
855
- .filter((entry) => !entry.retired)
856
- .map((entry) => relative(opts.root, join(opts.root, entry.path)) || '.'),
857
- ]),
858
- ];
676
+ const appFolders = [
677
+ ...LayoutFolder.layoutFoldersOf({ value: layout.backend }),
678
+ ...LayoutFolder.layoutFoldersOf({ value: layout.frontend }),
679
+ ];
680
+ const notes: IViolation[] = [];
859
681
 
860
- /**
861
- * `bun fmt` reads the `[fmt]` section of `bunfig.toml`; without it, it formats with Bun's defaults
862
- * (width 80, double quotes) and rewrites a tree the shared style formatted, and without
863
- * `flavor = "oxfmt"` it formats like Prettier once oxfmt is not a dependency. A `fmt` script in a
864
- * `package.json` runs instead of the formatter, and an oxfmt config `bun fmt` finds by itself
865
- * overrides `[fmt]`; the `oxfmt.config.*` init used to write in `.configs/formatters/` is read by
866
- * nothing. Warnings, never failures: a project made before `bun fmt` does not start failing.
867
- */
868
- export const checkFormat = (opts: ICheckContext): IViolation[] => {
869
- const warnings: IViolation[] = [];
870
- const bunfig = join(opts.root, 'bunfig.toml');
871
- const bunfigText = readText({ file: bunfig });
682
+ for (const entry of ProjectPackages.resolve({ config: opts.config }).filter(
683
+ (item) => !item.retired,
684
+ )) {
685
+ if (!appFolders.some((folder) => entry.path.startsWith(`${folder}/`))) {
686
+ continue;
687
+ }
872
688
 
873
- if (!existsSync(bunfig)) {
874
- warnings.push(
875
- createViolation({
876
- check: DoctorChecks.FORMAT,
877
- file: 'bunfig.toml',
878
- message: `missing - ${FMT_SECTION_ADVICE}`,
879
- }),
880
- );
881
- } else if (!DoctorConstants.BUNFIG_FMT_SECTION.test(bunfigText)) {
882
- warnings.push(
883
- createViolation({
884
- check: DoctorChecks.FORMAT,
885
- file: 'bunfig.toml',
886
- message: `no [fmt] section - ${FMT_SECTION_ADVICE}`,
887
- }),
888
- );
889
- } else if (!DoctorConstants.BUNFIG_FMT_FLAVOR.test(bunfigText)) {
890
- warnings.push(
891
- createViolation({
892
- check: DoctorChecks.FORMAT,
893
- file: 'bunfig.toml',
894
- message: `[fmt] has no flavor = "oxfmt" - ${FMT_FLAVOR_ADVICE}`,
895
- }),
896
- );
689
+ const file = `${entry.path}/package.json`;
690
+ const names = readScriptNames({ file: join(opts.root, file) });
691
+
692
+ if (names === undefined) {
693
+ continue;
694
+ }
695
+
696
+ const missing = AppScripts.STANDARD.filter((name) => !names.includes(name));
697
+ const legacy = AppScripts.LEGACY.filter((name) => names.includes(name));
698
+ const parts = [
699
+ ...(missing.length === 0 ? [] : [`missing ${missing.join(', ')}`]),
700
+ ...(legacy.length === 0 ? [] : [`legacy ${legacy.join(', ')} (use the standard names)`]),
701
+ ];
702
+
703
+ if (parts.length > 0) {
704
+ notes.push(
705
+ createViolation({
706
+ check: DoctorChecks.SCRIPTS,
707
+ file,
708
+ message: `app ${entry.dir}: ${parts.join('; ')}`,
709
+ }),
710
+ );
711
+ }
712
+ }
713
+
714
+ return notes;
715
+ }
716
+
717
+ /** The developer's stored agents must parse and name known agents; a broken file would otherwise hide as a default. */
718
+ static checkAgents(opts: ICheckContext): IViolation[] {
719
+ const stored = LocalChoice.read({ root: opts.root });
720
+
721
+ return stored.ok
722
+ ? []
723
+ : [
724
+ createViolation({
725
+ check: DoctorChecks.AGENTS,
726
+ file: '.agents/vulcan.local.json',
727
+ message: stored.error,
728
+ }),
729
+ ];
897
730
  }
898
731
 
899
- for (const owner of formatOwners(opts)) {
900
- const manifest = join(owner, 'package.json');
901
- const formatters = join(owner, '.configs', 'formatters');
732
+ /**
733
+ * The atlas server is registered the one way every project does: the root `.mcp.json` (a per-machine
734
+ * file `sync` writes for the agents that read it) holds an `atlas` entry that runs the project's own
735
+ * atlas (`--root .`), and the managed Claude settings enable `atlas` by that name. A server under
736
+ * another name, or one that serves another folder, is never enabled automatically or serves the wrong
737
+ * knowledge. A `.mcp.json` git still tracks is told how to hand over to `sync`; one that is untracked and not ignored is told how to hide it. Warnings, not violations.
738
+ */
739
+ static checkMcpAtlas(opts: ICheckContext): IViolation[] {
740
+ const warnings: IViolation[] = [];
741
+ const file = join(opts.root, MCP_FILE);
742
+ const chosen = AgentSelection.resolveQuietly({
743
+ root: opts.root,
744
+ configAgents: opts.config.agents,
745
+ });
746
+ const readsMcpFile = AgentTable.read().some(
747
+ (entry) => chosen.includes(entry.id) && entry.mcp.scope === AgentScopes.SHARED,
748
+ );
749
+
750
+ // The root `.mcp.json` is a per-machine file of the agents that read it; a missing one is the
751
+ // `adapters` check's (not synced yet), so only an existing file is looked at.
752
+ if (readsMcpFile && existsSync(file)) {
753
+ if (AgentFiles.isTracked({ root: opts.root, path: MCP_FILE })) {
754
+ warnings.push(
755
+ mcpWarning({
756
+ file: MCP_FILE,
757
+ message:
758
+ 'tracked by git; VULCAN now writes it per machine. Run `git rm --cached .mcp.json` and let sync manage it.',
759
+ }),
760
+ );
761
+ } else if (isUntrackedAndVisible({ root: opts.root, path: MCP_FILE })) {
762
+ warnings.push(
763
+ mcpWarning({
764
+ file: MCP_FILE,
765
+ message:
766
+ 'untracked and not ignored, so a clean-tree check (a release) refuses to run. Add `/.mcp.json` to .gitignore, or run `vulcan sync` at the top level of the repository, which lists it in .git/info/exclude.',
767
+ }),
768
+ );
769
+ }
770
+
771
+ const parsed = readJsonObject({ file });
772
+
773
+ if (parsed === undefined) {
774
+ warnings.push(
775
+ mcpWarning({
776
+ file: MCP_FILE,
777
+ message: `not valid JSON - it must hold ${MCP_SERVER_HINT} under mcpServers`,
778
+ }),
779
+ );
780
+ } else {
781
+ const holder = { value: parsed['mcpServers'] };
782
+ const servers = RecordValue.isRecord(holder.value) ? holder.value : {};
783
+ const entry = { value: servers[ATLAS_SERVER] };
784
+ const args = RecordValue.isRecord(entry.value) ? entry.value['args'] : undefined;
785
+ const isCanonical =
786
+ RecordValue.isRecord(entry.value) &&
787
+ entry.value['command'] === 'bun' &&
788
+ Array.isArray(args) &&
789
+ args.length === CANONICAL_ATLAS_ARGS.length &&
790
+ args.every((arg, index) => arg === CANONICAL_ATLAS_ARGS[index]);
791
+
792
+ if (!RecordValue.isRecord(entry.value)) {
793
+ warnings.push(
794
+ mcpWarning({
795
+ file: MCP_FILE,
796
+ message: `no server named atlas (found: ${Object.keys(servers).join(', ') || 'none'}): a differently named server is not enabled automatically - use ${MCP_SERVER_HINT}`,
797
+ }),
798
+ );
799
+ } else if (!isCanonical) {
800
+ const shown = JSON.stringify(entry.value)
801
+ .replace('{"command":', '{ "command": ')
802
+ .replace(',"args":[', ', "args": [')
803
+ .replaceAll('","', '", "')
804
+ .replace(/\]\}$/, '] }');
805
+
806
+ warnings.push(
807
+ mcpWarning({
808
+ file: MCP_FILE,
809
+ message: `the atlas entry is ${shown}, expected ${MCP_SERVER_HINT}`,
810
+ }),
811
+ );
812
+ }
813
+ }
814
+ }
815
+
816
+ const settings = join(opts.root, CLAUDE_SETTINGS_FILE);
817
+ const enabled = existsSync(settings)
818
+ ? readJsonObject({ file: settings })?.['enabledMcpjsonServers']
819
+ : undefined;
820
+
821
+ if (existsSync(settings) && !(Array.isArray(enabled) && enabled.includes(ATLAS_SERVER))) {
822
+ const has = Array.isArray(enabled) ? enabled.map(String).join(', ') : 'none';
902
823
 
903
- if (readScriptNames({ file: join(opts.root, manifest) })?.includes('fmt')) {
904
824
  warnings.push(
905
- createViolation({
906
- check: DoctorChecks.FORMAT,
907
- file: manifest,
908
- message:
909
- 'defines a "fmt" script: bun fmt runs it instead of formatting - rename it (the standard names are lint and lint:fix)',
825
+ mcpWarning({
826
+ file: CLAUDE_SETTINGS_FILE,
827
+ message: `enabledMcpjsonServers does not include atlas (has: ${has}): Claude asks before using the server - run vulcan sync`,
910
828
  }),
911
829
  );
912
830
  }
913
831
 
914
- const copy = join(owner, 'bunfig.toml');
832
+ return warnings;
833
+ }
834
+
835
+ /**
836
+ * A Dockerfile is built from the project root. Without a root `.dockerignore` the context carries
837
+ * node_modules, dist, .git and every `.env` (secrets that would land in an image layer a CI cache
838
+ * can keep); with one that does not exclude `.env` and `.env.*` the secrets are still copied.
839
+ * A warning, not a violation: the exit code is unchanged, so a project made before this check
840
+ * does not start failing.
841
+ */
842
+ static checkDockerignore(opts: ICheckContext): IViolation[] {
843
+ const file = join(opts.root, '.dockerignore');
844
+ const lines = existsSync(file)
845
+ ? readText({ file })
846
+ .split('\n')
847
+ .map((line) => line.trim())
848
+ .filter((line) => line !== '' && !line.startsWith('#'))
849
+ : undefined;
915
850
 
916
851
  if (
917
- owner !== '.' &&
918
- DoctorConstants.BUNFIG_FMT_SECTION.test(readText({ file: join(opts.root, copy) }))
852
+ lines !== undefined &&
853
+ excludes({ lines, file: '.env' }) &&
854
+ excludes({ lines, file: '.env.production' })
919
855
  ) {
856
+ return [];
857
+ }
858
+
859
+ const apps = ProjectPackages.resolve({ config: opts.config })
860
+ .filter((entry) => !entry.retired && existsSync(join(opts.root, entry.path, DOCKERFILE)))
861
+ .map((entry) => entry.dir);
862
+
863
+ if (apps.length === 0) {
864
+ return [];
865
+ }
866
+
867
+ const subject = apps.length === 1 ? `app ${apps[0]} has` : `apps ${apps.join(', ')} have`;
868
+
869
+ return [
870
+ createViolation({
871
+ check: DoctorChecks.DOCKERIGNORE,
872
+ file: '.dockerignore',
873
+ message:
874
+ lines === undefined
875
+ ? `${subject} a Dockerfile and the root has no .dockerignore: the build context would carry node_modules, dist, .git and every .env file (secrets) - create it, then ${ADD_SECRET_LINES}`
876
+ : `${subject} a Dockerfile and the root .dockerignore does not exclude .env files, which hold secrets and would land in the image layer: ${ADD_SECRET_LINES}`,
877
+ }),
878
+ ];
879
+ }
880
+
881
+ /**
882
+ * `bun fmt` reads the `[fmt]` section of `bunfig.toml`; without it, it formats with Bun's defaults
883
+ * (width 80, double quotes) and rewrites a tree the shared style formatted, and without
884
+ * `flavor = "oxfmt"` it formats like Prettier once oxfmt is not a dependency. A `fmt` script in a
885
+ * `package.json` runs instead of the formatter, and an oxfmt config `bun fmt` finds by itself
886
+ * overrides `[fmt]`; the `oxfmt.config.*` init used to write in `.configs/formatters/` is read by
887
+ * nothing. Warnings, never failures: a project made before `bun fmt` does not start failing.
888
+ */
889
+ static checkFormat(opts: ICheckContext): IViolation[] {
890
+ const warnings: IViolation[] = [];
891
+ const bunfig = join(opts.root, 'bunfig.toml');
892
+ const bunfigText = readText({ file: bunfig });
893
+
894
+ if (!existsSync(bunfig)) {
920
895
  warnings.push(
921
896
  createViolation({
922
897
  check: DoctorChecks.FORMAT,
923
- file: copy,
924
- message:
925
- 'a [fmt] copy: bun fmt inherits the root bunfig.toml, and a copy here can drift from it - delete the section',
898
+ file: 'bunfig.toml',
899
+ message: `missing - ${FMT_SECTION_ADVICE}`,
900
+ }),
901
+ );
902
+ } else if (!DoctorConstants.BUNFIG_FMT_SECTION.test(bunfigText)) {
903
+ warnings.push(
904
+ createViolation({
905
+ check: DoctorChecks.FORMAT,
906
+ file: 'bunfig.toml',
907
+ message: `no [fmt] section - ${FMT_SECTION_ADVICE}`,
908
+ }),
909
+ );
910
+ } else if (!DoctorConstants.BUNFIG_FMT_FLAVOR.test(bunfigText)) {
911
+ warnings.push(
912
+ createViolation({
913
+ check: DoctorChecks.FORMAT,
914
+ file: 'bunfig.toml',
915
+ message: `[fmt] has no flavor = "oxfmt" - ${FMT_FLAVOR_ADVICE}`,
926
916
  }),
927
917
  );
928
918
  }
929
919
 
930
- for (const file of DoctorConstants.OXFMT_AUTOLOADED_FILES) {
931
- if (existsSync(join(opts.root, owner, file))) {
920
+ for (const owner of formatOwners(opts)) {
921
+ const manifest = join(owner, 'package.json');
922
+ const formatters = join(owner, '.configs', 'formatters');
923
+
924
+ if (readScriptNames({ file: join(opts.root, manifest) })?.includes('fmt')) {
932
925
  warnings.push(
933
926
  createViolation({
934
927
  check: DoctorChecks.FORMAT,
935
- file: join(owner, file),
936
- message: OXFMT_LOADED_ADVICE,
928
+ file: manifest,
929
+ message:
930
+ 'defines a "fmt" script: bun fmt runs it instead of formatting - rename it (the standard names are lint and lint:fix)',
937
931
  }),
938
932
  );
939
933
  }
940
- }
941
934
 
942
- if (existsSync(join(opts.root, formatters))) {
943
- for (const file of readdirSync(join(opts.root, formatters)).filter((name) =>
944
- DoctorConstants.OXFMT_CONFIG_FILE.test(name),
945
- )) {
935
+ const copy = join(owner, 'bunfig.toml');
936
+
937
+ if (
938
+ owner !== '.' &&
939
+ DoctorConstants.BUNFIG_FMT_SECTION.test(readText({ file: join(opts.root, copy) }))
940
+ ) {
946
941
  warnings.push(
947
942
  createViolation({
948
943
  check: DoctorChecks.FORMAT,
949
- file: join(formatters, file),
944
+ file: copy,
950
945
  message:
951
- 'not used any more: bun fmt formats with the [fmt] section of bunfig.toml - delete it',
946
+ 'a [fmt] copy: bun fmt inherits the root bunfig.toml, and a copy here can drift from it - delete the section',
952
947
  }),
953
948
  );
954
949
  }
950
+
951
+ for (const file of DoctorConstants.OXFMT_AUTOLOADED_FILES) {
952
+ if (existsSync(join(opts.root, owner, file))) {
953
+ warnings.push(
954
+ createViolation({
955
+ check: DoctorChecks.FORMAT,
956
+ file: join(owner, file),
957
+ message: OXFMT_LOADED_ADVICE,
958
+ }),
959
+ );
960
+ }
961
+ }
962
+
963
+ if (existsSync(join(opts.root, formatters))) {
964
+ for (const file of readdirSync(join(opts.root, formatters)).filter((name) =>
965
+ DoctorConstants.OXFMT_CONFIG_FILE.test(name),
966
+ )) {
967
+ warnings.push(
968
+ createViolation({
969
+ check: DoctorChecks.FORMAT,
970
+ file: join(formatters, file),
971
+ message:
972
+ 'not used any more: bun fmt formats with the [fmt] section of bunfig.toml - delete it',
973
+ }),
974
+ );
975
+ }
976
+ }
955
977
  }
978
+
979
+ return warnings;
956
980
  }
957
981
 
958
- return warnings;
959
- };
982
+ static checkAtlasBlock(opts: ICheckContext): IViolation[] {
983
+ const merged = AtlasBlockPlan.merged({ root: opts.root, config: opts.config });
960
984
 
961
- export const checkAtlasBlock = (opts: ICheckContext): IViolation[] => {
962
- const merged = mergedAtlasBlock({ root: opts.root, config: opts.config });
985
+ return merged === undefined || !merged.changed
986
+ ? []
987
+ : [
988
+ createViolation({
989
+ check: DoctorChecks.AGENTS,
990
+ file: 'AGENTS.md',
991
+ message: `the Atlas block is missing or out of date - run '${ProjectLayout.VULCAN_COMMAND} sync'`,
992
+ }),
993
+ ];
994
+ }
963
995
 
964
- return merged === undefined || !merged.changed
965
- ? []
966
- : [
996
+ /** A skill with no "Use when" part gives the atlas server's instructions nothing to say when to load it: a warning, never a failure. */
997
+ static checkSkillTriggers(opts: ICheckContext): IViolation[] {
998
+ return SkillCatalog.catalogOf({ root: opts.root })
999
+ .filter((entry) => !SkillCatalog.triggerOf({ description: entry.description }).hasUseWhen)
1000
+ .map((entry) =>
967
1001
  createViolation({
968
- check: DoctorChecks.AGENTS,
969
- file: 'AGENTS.md',
970
- message: `the Atlas block is missing or out of date - run '${ProjectLayout.VULCAN_COMMAND} sync'`,
1002
+ check: DoctorChecks.SKILLS,
1003
+ file: entry.source === 'project' ? `.agents/skills/${entry.name}/SKILL.md` : entry.name,
1004
+ message: `'${entry.name}' has no "Use when" part in its description - atlas cannot say when to load it`,
971
1005
  }),
972
- ];
973
- };
1006
+ );
1007
+ }
974
1008
 
975
- /** A skill with no "Use when" part gives the atlas server's instructions nothing to say when to load it: a warning, never a failure. */
976
- export const checkSkillTriggers = (opts: ICheckContext): IViolation[] =>
977
- skillCatalogOf({ root: opts.root })
978
- .filter((entry) => !triggerOf({ description: entry.description }).hasUseWhen)
979
- .map((entry) =>
980
- createViolation({
981
- check: DoctorChecks.SKILLS,
982
- file: entry.source === 'project' ? `.agents/skills/${entry.name}/SKILL.md` : entry.name,
983
- message: `'${entry.name}' has no "Use when" part in its description - atlas cannot say when to load it`,
984
- }),
985
- );
1009
+ /** `.agents/local/` exists with its subdirectories and is gitignored: `sync` does both, so an upgraded project that has not synced yet is told here. */
1010
+ static checkLocalWorkspace(opts: ICheckContext): IViolation[] {
1011
+ return LocalPlan.planWorkspace({ root: opts.root })
1012
+ .filter((action) => action.status !== SyncStatuses.UNCHANGED)
1013
+ .map((action) =>
1014
+ createViolation({
1015
+ check: DoctorChecks.LOCAL,
1016
+ file: relative(opts.root, action.path) || '.',
1017
+ message: `${action.note ?? 'out of date'} - run 'bun x --no-install vulcan sync'`,
1018
+ }),
1019
+ );
1020
+ }
986
1021
 
987
- /** `.agents/local/` exists with its subdirectories and is gitignored: `sync` does both, so an upgraded project that has not synced yet is told here. */
988
- export const checkLocalWorkspace = (opts: ICheckContext): IViolation[] =>
989
- planLocalWorkspace({ root: opts.root })
990
- .filter((action) => action.status !== SyncStatuses.UNCHANGED)
991
- .map((action) =>
992
- createViolation({
993
- check: DoctorChecks.LOCAL,
994
- file: relative(opts.root, action.path) || '.',
995
- message: `${action.note ?? 'out of date'} - run 'bun x --no-install vulcan sync'`,
996
- }),
997
- );
1022
+ /**
1023
+ * A worktree of this repository that lives outside it: the repository's own `git worktree list` names it
1024
+ * (git metadata is inside the project), and the exact command moves it in. Nothing is moved or removed.
1025
+ */
1026
+ static checkOutsideWorktrees(opts: ICheckContext): IViolation[] {
1027
+ const listed = spawnSync('git', ['worktree', 'list', '--porcelain'], {
1028
+ cwd: opts.root,
1029
+ encoding: 'utf8',
1030
+ timeout: 5000,
1031
+ });
998
1032
 
999
- /**
1000
- * A worktree of this repository that lives outside it: the repository's own `git worktree list` names it
1001
- * (git metadata is inside the project), and the exact command moves it in. Nothing is moved or removed.
1002
- */
1003
- export const checkOutsideWorktrees = (opts: ICheckContext): IViolation[] => {
1004
- const listed = spawnSync('git', ['worktree', 'list', '--porcelain'], {
1005
- cwd: opts.root,
1006
- encoding: 'utf8',
1007
- timeout: 5000,
1008
- });
1033
+ if (listed.status !== 0) {
1034
+ return [];
1035
+ }
1009
1036
 
1010
- if (listed.status !== 0) {
1011
- return [];
1012
- }
1037
+ const [boundary, ...linked] = listed.stdout
1038
+ .split('\n')
1039
+ .filter((line) => line.startsWith('worktree '))
1040
+ .map((line) => line.slice('worktree '.length));
1041
+
1042
+ if (boundary === undefined) {
1043
+ return [];
1044
+ }
1045
+
1046
+ const inside = (path: string): boolean => {
1047
+ const real = existsSync(path) ? realpathSync(path) : path;
1013
1048
 
1014
- const [boundary, ...linked] = listed.stdout
1015
- .split('\n')
1016
- .filter((line) => line.startsWith('worktree '))
1017
- .map((line) => line.slice('worktree '.length));
1049
+ return real === boundary || real.startsWith(`${boundary}${sep}`);
1050
+ };
1018
1051
 
1019
- if (boundary === undefined) {
1020
- return [];
1052
+ return linked
1053
+ .filter((path) => !inside(path))
1054
+ .map((path) =>
1055
+ createViolation({
1056
+ check: DoctorChecks.LOCAL,
1057
+ file: path,
1058
+ message: `a git worktree outside the project - move it in: git worktree move '${path}' '${join(boundary, ProjectLayout.LOCAL_DIRECTORY, 'worktrees', basename(path))}'`,
1059
+ }),
1060
+ );
1021
1061
  }
1022
1062
 
1023
- const inside = (path: string): boolean => {
1024
- const real = existsSync(path) ? realpathSync(path) : path;
1063
+ /** The personal profile: a file that cannot be read is named, and one git tracks is a personal file about to be shared. */
1064
+ static checkProfile(opts: ICheckContext): IViolation[] {
1065
+ const read = OwnerProfile.read({ root: opts.root });
1066
+ const violations: IViolation[] = [];
1025
1067
 
1026
- return real === boundary || real.startsWith(`${boundary}${sep}`);
1027
- };
1068
+ if (!read.ok) {
1069
+ violations.push(
1070
+ createViolation({
1071
+ check: DoctorChecks.PROFILE,
1072
+ file: OwnerConstants.PROFILE_FILE,
1073
+ message: `${read.error} - fix it or delete it and run the profile form again`,
1074
+ }),
1075
+ );
1076
+ }
1028
1077
 
1029
- return linked
1030
- .filter((path) => !inside(path))
1031
- .map((path) =>
1032
- createViolation({
1033
- check: DoctorChecks.LOCAL,
1034
- file: path,
1035
- message: `a git worktree outside the project - move it in: git worktree move '${path}' '${join(boundary, ProjectLayout.LOCAL_DIRECTORY, 'worktrees', basename(path))}'`,
1036
- }),
1037
- );
1038
- };
1078
+ if (
1079
+ existsSync(join(opts.root, OwnerConstants.PROFILE_FILE)) &&
1080
+ !OwnerProfile.profileIsIgnored({ root: opts.root })
1081
+ ) {
1082
+ violations.push(
1083
+ createViolation({
1084
+ check: DoctorChecks.PROFILE,
1085
+ file: OwnerConstants.PROFILE_FILE,
1086
+ message:
1087
+ 'git does not ignore this personal file - add .agents/local/ to .gitignore (vulcan sync does it)',
1088
+ }),
1089
+ );
1090
+ }
1039
1091
 
1040
- /** The personal profile: a file that cannot be read is named, and one git tracks is a personal file about to be shared. */
1041
- export const checkProfile = (opts: ICheckContext): IViolation[] => {
1042
- const read = readProfile({ root: opts.root });
1043
- const violations: IViolation[] = [];
1092
+ if (
1093
+ existsSync(join(opts.root, OwnerConstants.PROFILE_FILE)) &&
1094
+ AgentFiles.isTracked({ root: opts.root, path: OwnerConstants.PROFILE_FILE })
1095
+ ) {
1096
+ violations.push(
1097
+ createViolation({
1098
+ check: DoctorChecks.PROFILE,
1099
+ file: OwnerConstants.PROFILE_FILE,
1100
+ message:
1101
+ 'git tracks this personal file - run: git rm --cached .agents/local/profile.json (and keep .agents/local/ in .gitignore)',
1102
+ }),
1103
+ );
1104
+ }
1044
1105
 
1045
- if (!read.ok) {
1046
- violations.push(
1047
- createViolation({
1048
- check: DoctorChecks.PROFILE,
1049
- file: OwnerConstants.PROFILE_FILE,
1050
- message: `${read.error} - fix it or delete it and run the profile form again`,
1051
- }),
1052
- );
1106
+ return violations;
1053
1107
  }
1054
1108
 
1055
- if (
1056
- existsSync(join(opts.root, OwnerConstants.PROFILE_FILE)) &&
1057
- !profileIsIgnored({ root: opts.root })
1058
- ) {
1059
- violations.push(
1060
- createViolation({
1061
- check: DoctorChecks.PROFILE,
1062
- file: OwnerConstants.PROFILE_FILE,
1063
- message:
1064
- 'git does not ignore this personal file - add .agents/local/ to .gitignore (vulcan sync does it)',
1065
- }),
1066
- );
1109
+ /** What an agent left under `.agents/local/` that has outlived its use, one line each with the command that clears it. */
1110
+ static checkStaleLocal(opts: ICheckContext): IViolation[] {
1111
+ return LocalScan.scan({ root: opts.root })
1112
+ .filter((entry) =>
1113
+ [LocalStates.STALE, LocalStates.MERGED, LocalStates.GONE, LocalStates.ORPHAN].includes(
1114
+ entry.state,
1115
+ ),
1116
+ )
1117
+ .map((entry) =>
1118
+ createViolation({
1119
+ check: DoctorChecks.LOCAL,
1120
+ file: `${ProjectLayout.LOCAL_DIRECTORY}/${entry.scope}/${entry.name}`,
1121
+ message: `${entry.state === LocalStates.STALE ? `left ${LocalFormat.formatAge({ ageMs: entry.ageMs })} ago` : entry.note} (${LocalFormat.formatBytes({ bytes: entry.bytes })}) - run: vulcan clean --${entry.scope} --yes`,
1122
+ }),
1123
+ );
1067
1124
  }
1068
1125
 
1069
- if (
1070
- existsSync(join(opts.root, OwnerConstants.PROFILE_FILE)) &&
1071
- isTracked({ root: opts.root, path: OwnerConstants.PROFILE_FILE })
1072
- ) {
1073
- violations.push(
1074
- createViolation({
1075
- check: DoctorChecks.PROFILE,
1076
- file: OwnerConstants.PROFILE_FILE,
1077
- message:
1078
- 'git tracks this personal file - run: git rm --cached .agents/local/profile.json (and keep .agents/local/ in .gitignore)',
1079
- }),
1080
- );
1081
- }
1126
+ /** How often replies to the owner were flagged (the report shape, or a claim the turn did not back), from the log the Stop hook keeps; a note, never a failure. */
1127
+ static checkReplyShape(opts: ICheckContext): IViolation[] {
1128
+ const { byClass, replies, days } = ViolationLog.readCounts({ root: opts.root });
1082
1129
 
1083
- return violations;
1084
- };
1130
+ if (replies === 0) {
1131
+ return [];
1132
+ }
1085
1133
 
1086
- /** What an agent left under `.agents/local/` that has outlived its use, one line each with the command that clears it. */
1087
- export const checkStaleLocal = (opts: ICheckContext): IViolation[] =>
1088
- scanLocal({ root: opts.root })
1089
- .filter((entry) =>
1090
- [LocalStates.STALE, LocalStates.MERGED, LocalStates.GONE, LocalStates.ORPHAN].includes(
1091
- entry.state,
1092
- ),
1093
- )
1094
- .map((entry) =>
1134
+ const parts = [...byClass.entries()]
1135
+ .sort((first, second) => second[1] - first[1])
1136
+ .map(([name, count]) => `${name} ${count}`);
1137
+
1138
+ const isFull =
1139
+ ViolationLog.violationBytes({ root: opts.root }) > ViolationConstants.LOG_MAX_BYTES;
1140
+
1141
+ return [
1142
+ ...(isFull
1143
+ ? [
1144
+ createViolation({
1145
+ check: DoctorChecks.LOCAL,
1146
+ file: `${ProjectLayout.LOCAL_DIRECTORY}/${ViolationConstants.LOG_FILE}`,
1147
+ message: `the log is full (${LocalFormat.formatBytes({ bytes: ViolationConstants.LOG_MAX_BYTES })}) and no longer grows; keep or delete it, and a new one starts`,
1148
+ }),
1149
+ ]
1150
+ : []),
1095
1151
  createViolation({
1096
1152
  check: DoctorChecks.LOCAL,
1097
- file: `${ProjectLayout.LOCAL_DIRECTORY}/${entry.scope}/${entry.name}`,
1098
- message: `${entry.state === LocalStates.STALE ? `left ${formatAge({ ageMs: entry.ageMs })} ago` : entry.note} (${formatBytes({ bytes: entry.bytes })}) - run: vulcan clean --${entry.scope} --yes`,
1153
+ file: `${ProjectLayout.LOCAL_DIRECTORY}/${ViolationConstants.LOG_FILE}`,
1154
+ message: `${replies} repl${replies === 1 ? 'y was' : 'ies were'} flagged on ${days} day${days === 1 ? '' : 's'} (${parts.join(', ')}); the retro skill turns a pattern into a check`,
1099
1155
  }),
1100
- );
1101
-
1102
- /** How often replies to the owner were flagged (the report shape, or a claim the turn did not back), from the log the Stop hook keeps; a note, never a failure. */
1103
- export const checkReplyShape = (opts: ICheckContext): IViolation[] => {
1104
- const { byClass, replies, days } = readViolationCounts({ root: opts.root });
1105
-
1106
- if (replies === 0) {
1107
- return [];
1156
+ ];
1108
1157
  }
1109
1158
 
1110
- const parts = [...byClass.entries()]
1111
- .sort((first, second) => second[1] - first[1])
1112
- .map(([name, count]) => `${name} ${count}`);
1113
-
1114
- const isFull = violationLogBytes({ root: opts.root }) > ViolationConstants.LOG_MAX_BYTES;
1115
-
1116
- return [
1117
- ...(isFull
1159
+ /** The owner reply shape is off for this shell (`VULCAN_OWNER_REPLY=off`): a session an agent starts sets it, an owner who exported it by mistake sees why nothing is checked; a note, never a failure. */
1160
+ static checkOwnerReplySwitch(opts: { env: Record<string, string | undefined> }): IViolation[] {
1161
+ return ReplySwitch.isOwnerOff({ env: opts.env })
1118
1162
  ? [
1119
1163
  createViolation({
1120
1164
  check: DoctorChecks.LOCAL,
1121
- file: `${ProjectLayout.LOCAL_DIRECTORY}/${ViolationConstants.LOG_FILE}`,
1122
- message: `the log is full (${formatBytes({ bytes: ViolationConstants.LOG_MAX_BYTES })}) and no longer grows; keep or delete it, and a new one starts`,
1165
+ file: OwnerReplySwitch.ENV,
1166
+ message: `set to ${OwnerReplySwitch.OFF} in this shell: a session started from here is not held to the owner reply shape and its replies are not logged. Unset it for a session whose reader is the owner`,
1123
1167
  }),
1124
1168
  ]
1125
- : []),
1126
- createViolation({
1127
- check: DoctorChecks.LOCAL,
1128
- file: `${ProjectLayout.LOCAL_DIRECTORY}/${ViolationConstants.LOG_FILE}`,
1129
- message: `${replies} repl${replies === 1 ? 'y was' : 'ies were'} flagged on ${days} day${days === 1 ? '' : 's'} (${parts.join(', ')}); the retro skill turns a pattern into a check`,
1130
- }),
1131
- ];
1132
- };
1169
+ : [];
1170
+ }
1171
+
1172
+ /** A Claude Code settings file of the project sets `VULCAN_OWNER_REPLY=off` in `env`: every session of the project then skips the owner reply shape. A warning, never a failure. */
1173
+ static checkOwnerReplySettings(opts: { root: string }): IViolation[] {
1174
+ return ['.claude/settings.json', '.claude/settings.local.json'].flatMap((file) => {
1175
+ const env = readJsonObject({ file: join(opts.root, file) })?.['env'];
1176
+
1177
+ return typeof env === 'object' &&
1178
+ env !== null &&
1179
+ Reflect.get(env, OwnerReplySwitch.ENV) === OwnerReplySwitch.OFF
1180
+ ? [
1181
+ createViolation({
1182
+ check: DoctorChecks.LOCAL,
1183
+ file,
1184
+ message: `env sets ${OwnerReplySwitch.ENV}=${OwnerReplySwitch.OFF}: every session of this project skips the owner reply shape. Remove it and set the variable on the command that starts a session whose reader is an agent`,
1185
+ }),
1186
+ ]
1187
+ : [];
1188
+ });
1189
+ }
1190
+
1191
+ /** One line per script in `guard.writes.trustedScripts` with what git says about it now (a note). */
1192
+ static checkTrustedScripts(opts: ICheckContext): IViolation[] {
1193
+ return opts.config.guard.writes.trustedScripts.map((entry) => {
1194
+ const { script, readOnly } = trustedScriptOf({ entry });
1195
+ const trust = ScriptTrust.trustOf({ root: opts.root, script });
1196
+ const scope = readOnly === undefined ? 'mutating calls' : `the calls ${readOnly.join(', ')}`;
1197
+
1198
+ return createViolation({
1199
+ check: DoctorChecks.GUARDS,
1200
+ file: script,
1201
+ message:
1202
+ trust.state === TrustStates.TRUSTED
1203
+ ? `guard-writes does not read this script for ${scope} (guard.writes.trustedScripts); it is ` +
1204
+ trust.reason
1205
+ : `listed in guard.writes.trustedScripts, but guard-writes reads it like any script now: ${trust.reason}`,
1206
+ });
1207
+ });
1208
+ }
1209
+
1210
+ /** A listed script that does not exist or is not committed: the exemption never applies (a warning). */
1211
+ static checkStaleTrustedScripts(opts: ICheckContext): IViolation[] {
1212
+ return opts.config.guard.writes.trustedScripts.flatMap((entry) => {
1213
+ const { script } = trustedScriptOf({ entry });
1214
+ const trust = ScriptTrust.trustOf({ root: opts.root, script });
1215
+
1216
+ return STALE_TRUST_STATES.has(trust.state)
1217
+ ? [
1218
+ createViolation({
1219
+ check: DoctorChecks.GUARDS,
1220
+ file: script,
1221
+ message: `guard.writes.trustedScripts lists it, but it never takes effect: ${trust.reason}; fix the path, or commit the script`,
1222
+ }),
1223
+ ]
1224
+ : [];
1225
+ });
1226
+ }
1227
+
1228
+ /**
1229
+ * The commands and push targets the project adds to guard-writes and guard-git, one note each: so the
1230
+ * guards' reach beyond their own list is visible where a person looks, with the rule and the pattern.
1231
+ */
1232
+ static checkGuardPatterns(opts: ICheckContext): IViolation[] {
1233
+ const { commands } = opts.config.guard.writes;
1234
+ const { askPush } = opts.config.guard.git;
1133
1235
 
1134
- /** The owner reply shape is off for this shell (`VULCAN_OWNER_REPLY=off`): a session an agent starts sets it, an owner who exported it by mistake sees why nothing is checked; a note, never a failure. */
1135
- export const checkOwnerReplySwitch = (opts: {
1136
- env: Record<string, string | undefined>;
1137
- }): IViolation[] =>
1138
- isOwnerReplyOff({ env: opts.env })
1139
- ? [
1236
+ return [
1237
+ ...commands.map((command) =>
1140
1238
  createViolation({
1141
- check: DoctorChecks.LOCAL,
1142
- file: OwnerReplySwitch.ENV,
1143
- message: `set to ${OwnerReplySwitch.OFF} in this shell: a session started from here is not held to the owner reply shape and its replies are not logged. Unset it for a session whose reader is the owner`,
1239
+ check: DoctorChecks.GUARDS,
1240
+ file: opts.configFile,
1241
+ message: `guard.writes.commands: ${command.rule} '${command.what}' asks when a command matches /${command.pattern}/${command.ignoreCase === true ? 'i' : ''}`,
1144
1242
  }),
1145
- ]
1146
- : [];
1243
+ ),
1244
+ ...(askPush.length === 0
1245
+ ? []
1246
+ : [
1247
+ createViolation({
1248
+ check: DoctorChecks.GUARDS,
1249
+ file: opts.configFile,
1250
+ message: `guard.git.askPush: a plain git push asks for ${askPush.join(', ')}`,
1251
+ }),
1252
+ ]),
1253
+ ];
1254
+ }
1147
1255
 
1148
- /** A Claude Code settings file of the project sets `VULCAN_OWNER_REPLY=off` in `env`: every session of the project then skips the owner reply shape. A warning, never a failure. */
1149
- export const checkOwnerReplySettings = (opts: { root: string }): IViolation[] =>
1150
- ['.claude/settings.json', '.claude/settings.local.json'].flatMap((file) => {
1151
- const env = readJsonObject({ file: join(opts.root, file) })?.['env'];
1256
+ static checkLocalSize(opts: ICheckContext): IViolation[] {
1257
+ const entries = LocalScan.scan({ root: opts.root });
1258
+ const total = entries.reduce((sum, entry) => sum + entry.bytes, 0);
1152
1259
 
1153
- return typeof env === 'object' &&
1154
- env !== null &&
1155
- Reflect.get(env, OwnerReplySwitch.ENV) === OwnerReplySwitch.OFF
1156
- ? [
1157
- createViolation({
1158
- check: DoctorChecks.LOCAL,
1159
- file,
1160
- message: `env sets ${OwnerReplySwitch.ENV}=${OwnerReplySwitch.OFF}: every session of this project skips the owner reply shape. Remove it and set the variable on the command that starts a session whose reader is an agent`,
1161
- }),
1162
- ]
1163
- : [];
1164
- });
1260
+ if (total < LocalConstants.NOTE_BYTES) {
1261
+ return [];
1262
+ }
1165
1263
 
1166
- /** The size of `.agents/local/` once it is large: where the space went, and the command that gives it back. */
1167
- /** The states of a listed script worth a warning: a typo or a script nobody committed. A modified one is normal work, so it is only a note. */
1168
- const STALE_TRUST_STATES = new Set<string>([
1169
- TrustStates.MISSING,
1170
- TrustStates.UNTRACKED,
1171
- TrustStates.UNCOMMITTED,
1172
- TrustStates.SYMLINK,
1173
- TrustStates.UNKNOWN,
1174
- ]);
1264
+ const byScope = new Map<string, number>();
1175
1265
 
1176
- /** One line per script in `guard.writes.trustedScripts` with what git says about it now (a note). */
1177
- export const checkTrustedScripts = (opts: ICheckContext): IViolation[] =>
1178
- opts.config.guard.writes.trustedScripts.map((script) => {
1179
- const trust = trustOf({ root: opts.root, script });
1180
-
1181
- return createViolation({
1182
- check: DoctorChecks.GUARDS,
1183
- file: script,
1184
- message:
1185
- trust.state === TrustStates.TRUSTED
1186
- ? 'guard-writes does not read this script for mutating calls (guard.writes.trustedScripts); it is ' +
1187
- trust.reason
1188
- : `listed in guard.writes.trustedScripts, but guard-writes reads it like any script now: ${trust.reason}`,
1189
- });
1190
- });
1266
+ for (const entry of entries) {
1267
+ byScope.set(entry.scope, (byScope.get(entry.scope) ?? 0) + entry.bytes);
1268
+ }
1191
1269
 
1192
- /** A listed script that does not exist or is not committed: the exemption never applies (a warning). */
1193
- export const checkStaleTrustedScripts = (opts: ICheckContext): IViolation[] =>
1194
- opts.config.guard.writes.trustedScripts.flatMap((script) => {
1195
- const trust = trustOf({ root: opts.root, script });
1270
+ const parts = [...byScope.entries()]
1271
+ .sort((first, second) => second[1] - first[1])
1272
+ .map(([scope, bytes]) => `${scope} ${LocalFormat.formatBytes({ bytes })}`);
1196
1273
 
1197
- return STALE_TRUST_STATES.has(trust.state)
1198
- ? [
1199
- createViolation({
1200
- check: DoctorChecks.GUARDS,
1201
- file: script,
1202
- message: `guard.writes.trustedScripts lists it, but it never takes effect: ${trust.reason}; fix the path, or commit the script`,
1203
- }),
1204
- ]
1205
- : [];
1206
- });
1274
+ return [
1275
+ createViolation({
1276
+ check: DoctorChecks.LOCAL,
1277
+ file: ProjectLayout.LOCAL_DIRECTORY,
1278
+ message: `holds ${LocalFormat.formatBytes({ bytes: total })} (${parts.join(', ')}); vulcan clean lists what an agent left and --yes removes it`,
1279
+ }),
1280
+ ];
1281
+ }
1282
+ }
1283
+
1284
+ const QUOTES = ["'", '"', '`'];
1207
1285
 
1208
1286
  /**
1209
- * The commands and push targets the project adds to guard-writes and guard-git, one note each: so the
1210
- * guards' reach beyond their own list is visible where a person looks, with the rule and the pattern.
1287
+ * A subcommand an object entry lists that its script never holds as a quoted string (a note). It reads the
1288
+ * text of the file, so it cannot tell a subcommand the script handles another way from a typo.
1211
1289
  */
1212
- export const checkGuardPatterns = (opts: ICheckContext): IViolation[] => {
1213
- const { commands } = opts.config.guard.writes;
1214
- const { askPush } = opts.config.guard.git;
1290
+ export class ReadOnlySubcommandChecks {
1291
+ static readonly MAX_SOURCE_BYTES = 1_000_000;
1292
+
1293
+ static sourceOf(opts: { path: string }): string | undefined {
1294
+ try {
1295
+ const stat = lstatSync(opts.path);
1296
+
1297
+ return stat.isFile() && stat.size <= ReadOnlySubcommandChecks.MAX_SOURCE_BYTES
1298
+ ? readFileSync(opts.path, 'utf8')
1299
+ : undefined;
1300
+ } catch {
1301
+ return undefined;
1302
+ }
1303
+ }
1215
1304
 
1216
- return [
1217
- ...commands.map((command) =>
1218
- createViolation({
1219
- check: DoctorChecks.GUARDS,
1220
- file: opts.configFile,
1221
- message: `guard.writes.commands: ${command.rule} '${command.what}' asks when a command matches /${command.pattern}/${command.ignoreCase === true ? 'i' : ''}`,
1222
- }),
1223
- ),
1224
- ...(askPush.length === 0
1225
- ? []
1226
- : [
1227
- createViolation({
1228
- check: DoctorChecks.GUARDS,
1229
- file: opts.configFile,
1230
- message: `guard.git.askPush: a plain git push asks for ${askPush.join(', ')}`,
1231
- }),
1232
- ]),
1233
- ];
1234
- };
1305
+ static check(opts: ICheckContext): IViolation[] {
1306
+ return opts.config.guard.writes.trustedScripts.flatMap((entry) => {
1307
+ const { script, readOnly } = trustedScriptOf({ entry });
1308
+ const path = join(opts.root, script);
1235
1309
 
1236
- export const checkLocalSize = (opts: ICheckContext): IViolation[] => {
1237
- const entries = scanLocal({ root: opts.root });
1238
- const total = entries.reduce((sum, entry) => sum + entry.bytes, 0);
1310
+ if (readOnly === undefined) {
1311
+ return [];
1312
+ }
1239
1313
 
1240
- if (total < LocalConstants.NOTE_BYTES) {
1241
- return [];
1242
- }
1314
+ // Only a plain, small file inside the repo is read: a link, a folder or a device is skipped, never followed.
1315
+ const source = ReadOnlySubcommandChecks.sourceOf({ path });
1243
1316
 
1244
- const byScope = new Map<string, number>();
1317
+ if (source === undefined) {
1318
+ return [];
1319
+ }
1245
1320
 
1246
- for (const entry of entries) {
1247
- byScope.set(entry.scope, (byScope.get(entry.scope) ?? 0) + entry.bytes);
1321
+ return readOnly
1322
+ .filter((word) => !QUOTES.some((quote) => source.includes(`${quote}${word}${quote}`)))
1323
+ .map((word) =>
1324
+ createViolation({
1325
+ check: DoctorChecks.GUARDS,
1326
+ file: script,
1327
+ message: `guard.writes.trustedScripts lists the subcommand '${word}' for this script, but the script does not hold it as a quoted string; this is a check of the text of the file, not what the script does`,
1328
+ }),
1329
+ );
1330
+ });
1248
1331
  }
1249
-
1250
- const parts = [...byScope.entries()]
1251
- .sort((first, second) => second[1] - first[1])
1252
- .map(([scope, bytes]) => `${scope} ${formatBytes({ bytes })}`);
1253
-
1254
- return [
1255
- createViolation({
1256
- check: DoctorChecks.LOCAL,
1257
- file: ProjectLayout.LOCAL_DIRECTORY,
1258
- message: `holds ${formatBytes({ bytes: total })} (${parts.join(', ')}); vulcan clean lists what an agent left and --yes removes it`,
1259
- }),
1260
- ];
1261
- };
1332
+ }