@venizia/vulcan 0.4.9-0 → 0.4.9-2

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 (141) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +2 -2
  3. package/base/hooks/codex-guards.ts +15 -5
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +4 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +5 -6
  8. package/base/hooks/guard-remote-hosts.ts +6 -7
  9. package/base/hooks/guard-scripting.ts +5 -6
  10. package/base/hooks/guard-writes.ts +8 -9
  11. package/base/hooks/post-tool.ts +2 -2
  12. package/base/hooks/prompt-submit.ts +2 -2
  13. package/base/hooks/session-start.ts +3 -3
  14. package/base/hooks/stop.ts +2 -2
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/skills/docs-update/SKILL.md +4 -2
  17. package/base/skills/visualize-work/SKILL.md +9 -0
  18. package/package.json +3 -3
  19. package/src/agents/atlas-block.ts +43 -43
  20. package/src/agents/codex-hooks.ts +45 -43
  21. package/src/agents/detect.ts +19 -16
  22. package/src/agents/exclude.ts +96 -97
  23. package/src/agents/hooks-json.ts +38 -36
  24. package/src/agents/local.ts +46 -43
  25. package/src/agents/prompt.ts +45 -42
  26. package/src/agents/render.ts +201 -195
  27. package/src/agents/resolve.ts +133 -134
  28. package/src/agents/table.ts +12 -8
  29. package/src/commands/add.command.ts +2 -2
  30. package/src/commands/agents.command.ts +11 -17
  31. package/src/commands/clean.command.ts +6 -6
  32. package/src/commands/doctor.command.ts +4 -4
  33. package/src/commands/init.command.ts +12 -8
  34. package/src/commands/preset.command.ts +2 -2
  35. package/src/commands/profile.command.ts +42 -49
  36. package/src/commands/sync.command.ts +109 -111
  37. package/src/commands/upgrade.command.ts +80 -75
  38. package/src/commands/visualize.command.ts +7 -13
  39. package/src/commands/x.command.ts +55 -50
  40. package/src/common/format.ts +23 -21
  41. package/src/common/json.ts +8 -5
  42. package/src/common/layout-folder.ts +94 -91
  43. package/src/common/paths.ts +14 -12
  44. package/src/config/loader.ts +52 -49
  45. package/src/config/packages.ts +14 -11
  46. package/src/config/schema.ts +3 -3
  47. package/src/create/add-app.ts +519 -509
  48. package/src/create/add-lib.ts +237 -240
  49. package/src/create/bunfig.ts +26 -23
  50. package/src/create/checks.ts +36 -34
  51. package/src/create/diff.ts +21 -23
  52. package/src/create/dockerignore.ts +26 -24
  53. package/src/create/files.ts +7 -5
  54. package/src/create/init-monorepo.ts +75 -80
  55. package/src/create/lib-preset.ts +59 -63
  56. package/src/create/manifest-json.ts +10 -4
  57. package/src/create/names.ts +217 -210
  58. package/src/create/next.ts +26 -23
  59. package/src/create/plan.ts +15 -12
  60. package/src/create/preset-diff.ts +301 -303
  61. package/src/create/preset-menu.ts +38 -32
  62. package/src/create/preset.ts +202 -197
  63. package/src/create/process.ts +79 -72
  64. package/src/create/scratch.ts +48 -49
  65. package/src/create/workspace.ts +404 -396
  66. package/src/doctor/checks.ts +1027 -1014
  67. package/src/doctor/makefile.ts +17 -13
  68. package/src/doctor/runner.ts +88 -118
  69. package/src/doctor/skills.ts +97 -95
  70. package/src/doctor/tags.ts +42 -37
  71. package/src/hooks/codex-patch.ts +25 -22
  72. package/src/hooks/command-view.ts +44 -39
  73. package/src/hooks/decision.ts +37 -37
  74. package/src/hooks/guard-git.ts +51 -49
  75. package/src/hooks/guard-manifest.ts +58 -55
  76. package/src/hooks/guard-outside.ts +93 -91
  77. package/src/hooks/guard-package.ts +82 -79
  78. package/src/hooks/guard-scripting.ts +19 -14
  79. package/src/hooks/guard-writes.ts +154 -149
  80. package/src/hooks/owner-reply.ts +127 -127
  81. package/src/hooks/post-tool.ts +94 -93
  82. package/src/hooks/project-guards.ts +65 -62
  83. package/src/hooks/project-tmp.ts +27 -24
  84. package/src/hooks/remote-hosts.ts +153 -130
  85. package/src/hooks/session-digest.ts +98 -101
  86. package/src/hooks/shell.ts +509 -499
  87. package/src/hooks/subagent-card.ts +11 -7
  88. package/src/hooks/trusted-scripts.ts +106 -104
  89. package/src/init/scaffold.ts +135 -132
  90. package/src/local/clean.ts +38 -36
  91. package/src/local/format.ts +21 -17
  92. package/src/local/scan.ts +144 -138
  93. package/src/manifest/render.ts +110 -104
  94. package/src/owner/card.ts +51 -46
  95. package/src/owner/profile.ts +99 -93
  96. package/src/owner/reply-switch.ts +9 -6
  97. package/src/owner/shape.ts +71 -69
  98. package/src/owner/survey.ts +173 -171
  99. package/src/owner/view.ts +62 -59
  100. package/src/owner/violations.ts +119 -123
  101. package/src/rules/base.ts +15 -11
  102. package/src/rules/parser.ts +39 -32
  103. package/src/rules/slots.ts +8 -6
  104. package/src/signals/claims.ts +30 -28
  105. package/src/signals/classify.ts +38 -33
  106. package/src/signals/loop.ts +39 -37
  107. package/src/signals/state.ts +79 -81
  108. package/src/skills/frontmatter.ts +28 -28
  109. package/src/sync/agent-files.ts +217 -199
  110. package/src/sync/agent-removal.ts +56 -59
  111. package/src/sync/atlas-block.ts +45 -43
  112. package/src/sync/base-rules.ts +32 -30
  113. package/src/sync/claude-launch.ts +36 -34
  114. package/src/sync/exclude.ts +77 -69
  115. package/src/sync/local-choice.ts +50 -47
  116. package/src/sync/planner.ts +59 -61
  117. package/src/sync/prune.ts +52 -48
  118. package/src/sync/settings.ts +166 -167
  119. package/src/ui/capability.ts +12 -7
  120. package/src/ui/keyboard.ts +38 -38
  121. package/src/ui/prompt.ts +79 -77
  122. package/src/visualize/assets.ts +33 -24
  123. package/src/visualize/charts.ts +179 -176
  124. package/src/visualize/compare-css.ts +3 -2
  125. package/src/visualize/compare-render.ts +9 -7
  126. package/src/visualize/diagrams.ts +189 -174
  127. package/src/visualize/grid-span.ts +34 -0
  128. package/src/visualize/icons.ts +7 -5
  129. package/src/visualize/kinds-render.ts +50 -45
  130. package/src/visualize/kinds-validate.ts +12 -10
  131. package/src/visualize/labels.ts +21 -17
  132. package/src/visualize/layout.ts +112 -97
  133. package/src/visualize/page.ts +92 -104
  134. package/src/visualize/render.ts +143 -140
  135. package/src/visualize/sections.ts +395 -384
  136. package/src/visualize/sources.ts +2 -2
  137. package/src/visualize/theme.ts +12 -10
  138. package/src/visualize/validate.ts +13 -9
  139. package/src/wiki/anchors.ts +38 -36
  140. package/src/wiki/command.ts +4 -4
  141. package/src/wiki/source-links.ts +46 -44
@@ -3,59 +3,35 @@ import { spawnSync } from 'node:child_process';
3
3
  import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
4
4
  import { basename, dirname, join, relative, sep } from 'node:path';
5
5
  import { BASE_DIRECTORY, ProjectLayout, RecordValue } 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';
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
30
  import { SkillCatalog } from '@venizia/vulcan-atlas';
55
- import { trustOf, TrustStates } from '../hooks/index.ts';
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 vulcan-sync) 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 => {
@@ -658,545 +158,1130 @@ const isUntrackedAndVisible = (opts: { root: string; path: string }): boolean =>
658
158
  const mcpWarning = (opts: { file: string; message: string }): IViolation =>
659
159
  createViolation({ check: DoctorChecks.MCP, file: opts.file, message: opts.message });
660
160
 
661
- /**
662
- * The atlas server is registered the one way every project does: the root `.mcp.json` (a per-machine
663
- * file `sync` writes for the agents that read it) holds an `atlas` entry that runs the project's own
664
- * atlas (`--root .`), and the managed Claude settings enable `atlas` by that name. A server under
665
- * another name, or one that serves another folder, is never enabled automatically or serves the wrong
666
- * 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.
667
- */
668
- export const checkMcpAtlas = (opts: ICheckContext): IViolation[] => {
669
- const warnings: IViolation[] = [];
670
- const file = join(opts.root, MCP_FILE);
671
- const chosen = resolveAgentsQuietly({ root: opts.root, configAgents: opts.config.agents });
672
- const readsMcpFile = readAgentTable().some(
673
- (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'))
674
174
  );
175
+ };
675
176
 
676
- // The root `.mcp.json` is a per-machine file of the agents that read it; a missing one is the
677
- // `adapters` check's (not synced yet), so only an existing file is looked at.
678
- if (readsMcpFile && existsSync(file)) {
679
- if (isTracked({ root: opts.root, path: MCP_FILE })) {
680
- warnings.push(
681
- mcpWarning({
682
- file: MCP_FILE,
683
- message:
684
- 'tracked by git; VULCAN now writes it per machine. Run `git rm --cached .mcp.json` and let sync manage it.',
685
- }),
686
- );
687
- } else if (isUntrackedAndVisible({ root: opts.root, path: MCP_FILE })) {
688
- warnings.push(
689
- mcpWarning({
690
- file: MCP_FILE,
691
- message:
692
- '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.',
693
- }),
694
- );
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;
695
186
  }
187
+ }
696
188
 
697
- const parsed = readJsonObject({ file });
189
+ return excluded;
190
+ };
698
191
 
699
- if (parsed === undefined) {
700
- warnings.push(
701
- mcpWarning({
702
- file: MCP_FILE,
703
- 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'`,
704
241
  }),
705
242
  );
706
- } else {
707
- const holder = { value: parsed['mcpServers'] };
708
- const servers = RecordValue.isRecord(holder.value) ? holder.value : {};
709
- const entry = { value: servers[ATLAS_SERVER] };
710
- const args = RecordValue.isRecord(entry.value) ? entry.value['args'] : undefined;
711
- const isCanonical =
712
- RecordValue.isRecord(entry.value) &&
713
- entry.value['command'] === 'bun' &&
714
- Array.isArray(args) &&
715
- args.length === CANONICAL_ATLAS_ARGS.length &&
716
- args.every((arg, index) => arg === CANONICAL_ATLAS_ARGS[index]);
717
-
718
- if (!RecordValue.isRecord(entry.value)) {
719
- warnings.push(
720
- mcpWarning({
721
- file: MCP_FILE,
722
- 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} }`,
723
282
  }),
724
283
  );
725
- } else if (!isCanonical) {
726
- const shown = JSON.stringify(entry.value)
727
- .replace('{"command":', '{ "command": ')
728
- .replace(',"args":[', ', "args": [')
729
- .replaceAll('","', '", "')
730
- .replace(/\]\}$/, '] }');
284
+ continue;
285
+ }
731
286
 
732
- warnings.push(
733
- mcpWarning({
734
- file: MCP_FILE,
735
- 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})`,
736
293
  }),
737
294
  );
738
295
  }
739
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;
740
316
  }
741
317
 
742
- const settings = join(opts.root, CLAUDE_SETTINGS_FILE);
743
- const enabled = existsSync(settings)
744
- ? readJsonObject({ file: settings })?.['enabledMcpjsonServers']
745
- : undefined;
318
+ static checkSkills(opts: ICheckContext): IViolation[] {
319
+ const shipped = new Set(listDirectories({ directory: join(BASE_DIRECTORY, 'skills') }));
320
+
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
+ }
746
331
 
747
- if (existsSync(settings) && !(Array.isArray(enabled) && enabled.includes(ATLAS_SERVER))) {
748
- const has = Array.isArray(enabled) ? enabled.map(String).join(', ') : 'none';
332
+ static checkMake(opts: ICheckContext): IViolation[] {
333
+ const makefile = readText({ file: join(opts.root, 'Makefile') });
334
+ const violations: IViolation[] = [];
749
335
 
750
- warnings.push(
751
- mcpWarning({
752
- file: CLAUDE_SETTINGS_FILE,
753
- message: `enabledMcpjsonServers does not include atlas (has: ${has}): Claude asks before using the server - run vulcan sync`,
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
+ }
345
+
346
+ const shipped = new Set(
347
+ Makefile.parseMakeTargets({
348
+ makefile: readText({ file: join(BASE_DIRECTORY, 'make', 'vulcan.mk') }),
754
349
  }),
755
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;
756
369
  }
757
370
 
758
- return warnings;
759
- };
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
+ }
760
382
 
761
- 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
+ }
762
420
 
763
- const SECRET_LINES = ['**/.env', '**/.env.*', '!**/.env.example'];
764
- 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
+ }
765
431
 
766
- /** Whether a `.dockerignore` pattern, as Docker reads it, names the file `opts.file` at any depth. */
767
- const patternNames = (opts: { pattern: string; file: string }): boolean => {
768
- 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 });
769
438
 
770
- return (
771
- bare === opts.file ||
772
- (bare.endsWith('*') && opts.file.startsWith(bare.slice(0, -1)) && bare.startsWith('.env'))
773
- );
774
- };
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
+ }
775
449
 
776
- /** Whether the last pattern that names `opts.file` excludes it: a later `!` line brings it back. */
777
- const excludes = (opts: { lines: string[]; file: string }): boolean => {
778
- let excluded = false;
450
+ const fix = `run '${ProjectLayout.VULCAN_COMMAND} sync' and commit it`;
779
451
 
780
- for (const line of opts.lines) {
781
- 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
+ }
782
463
 
783
- if (patternNames({ pattern: negated ? line.slice(1) : line, file: opts.file })) {
784
- 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
+ }
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
+ );
785
555
  }
556
+
557
+ return violations;
786
558
  }
787
559
 
788
- return excluded;
789
- };
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[] = [];
790
567
 
791
- /**
792
- * A Dockerfile is built from the project root. Without a root `.dockerignore` the context carries
793
- * node_modules, dist, .git and every `.env` (secrets that would land in an image layer a CI cache
794
- * can keep); with one that does not exclude `.env` and `.env.*` the secrets are still copied.
795
- * A warning, not a violation: the exit code is unchanged, so a project made before this check
796
- * does not start failing.
797
- */
798
- export const checkDockerignore = (opts: ICheckContext): IViolation[] => {
799
- const file = join(opts.root, '.dockerignore');
800
- const lines = existsSync(file)
801
- ? readText({ file })
802
- .split('\n')
803
- .map((line) => line.trim())
804
- .filter((line) => line !== '' && !line.startsWith('#'))
805
- : undefined;
806
-
807
- if (
808
- lines !== undefined &&
809
- excludes({ lines, file: '.env' }) &&
810
- excludes({ lines, file: '.env.production' })
811
- ) {
812
- 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;
813
595
  }
814
596
 
815
- const apps = resolvePackages({ config: opts.config })
816
- .filter((entry) => !entry.retired && existsSync(join(opts.root, entry.path, DOCKERFILE)))
817
- .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
+ }
818
647
 
819
- if (apps.length === 0) {
820
- return [];
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
+ }
661
+
662
+ return violations;
821
663
  }
822
664
 
823
- const subject = apps.length === 1 ? `app ${apps[0]} has` : `apps ${apps.join(', ')} have`;
824
-
825
- return [
826
- createViolation({
827
- check: DoctorChecks.DOCKERIGNORE,
828
- file: '.dockerignore',
829
- message:
830
- lines === undefined
831
- ? `${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}`
832
- : `${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}`,
833
- }),
834
- ];
835
- };
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;
836
671
 
837
- const FMT_SECTION_ADVICE =
838
- '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';
839
- const FMT_FLAVOR_ADVICE =
840
- 'without it bun fmt uses its default style when oxfmt is not a dependency, and the output changes';
841
- const OXFMT_LOADED_ADVICE =
842
- '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
+ }
843
675
 
844
- /** The folders that can hold a package.json and an oxfmt config: the root, `packages/*` and every configured package. */
845
- const formatOwners = (opts: ICheckContext): string[] => [
846
- ...new Set([
847
- '.',
848
- ...listDirectories({ directory: join(opts.root, 'packages') }).map((name) =>
849
- join('packages', name),
850
- ),
851
- ...resolvePackages({ config: opts.config })
852
- .filter((entry) => !entry.retired)
853
- .map((entry) => relative(opts.root, join(opts.root, entry.path)) || '.'),
854
- ]),
855
- ];
676
+ const appFolders = [
677
+ ...LayoutFolder.layoutFoldersOf({ value: layout.backend }),
678
+ ...LayoutFolder.layoutFoldersOf({ value: layout.frontend }),
679
+ ];
680
+ const notes: IViolation[] = [];
856
681
 
857
- /**
858
- * `bun fmt` reads the `[fmt]` section of `bunfig.toml`; without it, it formats with Bun's defaults
859
- * (width 80, double quotes) and rewrites a tree the shared style formatted, and without
860
- * `flavor = "oxfmt"` it formats like Prettier once oxfmt is not a dependency. A `fmt` script in a
861
- * `package.json` runs instead of the formatter, and an oxfmt config `bun fmt` finds by itself
862
- * overrides `[fmt]`; the `oxfmt.config.*` init used to write in `.configs/formatters/` is read by
863
- * nothing. Warnings, never failures: a project made before `bun fmt` does not start failing.
864
- */
865
- export const checkFormat = (opts: ICheckContext): IViolation[] => {
866
- const warnings: IViolation[] = [];
867
- const bunfig = join(opts.root, 'bunfig.toml');
868
- 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
+ }
869
688
 
870
- if (!existsSync(bunfig)) {
871
- warnings.push(
872
- createViolation({
873
- check: DoctorChecks.FORMAT,
874
- file: 'bunfig.toml',
875
- message: `missing - ${FMT_SECTION_ADVICE}`,
876
- }),
877
- );
878
- } else if (!DoctorConstants.BUNFIG_FMT_SECTION.test(bunfigText)) {
879
- warnings.push(
880
- createViolation({
881
- check: DoctorChecks.FORMAT,
882
- file: 'bunfig.toml',
883
- message: `no [fmt] section - ${FMT_SECTION_ADVICE}`,
884
- }),
885
- );
886
- } else if (!DoctorConstants.BUNFIG_FMT_FLAVOR.test(bunfigText)) {
887
- warnings.push(
888
- createViolation({
889
- check: DoctorChecks.FORMAT,
890
- file: 'bunfig.toml',
891
- message: `[fmt] has no flavor = "oxfmt" - ${FMT_FLAVOR_ADVICE}`,
892
- }),
893
- );
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;
894
715
  }
895
716
 
896
- for (const owner of formatOwners(opts)) {
897
- const manifest = join(owner, 'package.json');
898
- const formatters = join(owner, '.configs', 'formatters');
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
+ ];
730
+ }
731
+
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';
899
823
 
900
- if (readScriptNames({ file: join(opts.root, manifest) })?.includes('fmt')) {
901
824
  warnings.push(
902
- createViolation({
903
- check: DoctorChecks.FORMAT,
904
- file: manifest,
905
- message:
906
- '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`,
907
828
  }),
908
829
  );
909
830
  }
910
831
 
911
- 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;
912
850
 
913
851
  if (
914
- owner !== '.' &&
915
- 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' })
916
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)) {
917
895
  warnings.push(
918
896
  createViolation({
919
897
  check: DoctorChecks.FORMAT,
920
- file: copy,
921
- message:
922
- '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}`,
923
916
  }),
924
917
  );
925
918
  }
926
919
 
927
- for (const file of DoctorConstants.OXFMT_AUTOLOADED_FILES) {
928
- 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')) {
929
925
  warnings.push(
930
926
  createViolation({
931
927
  check: DoctorChecks.FORMAT,
932
- file: join(owner, file),
933
- 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)',
934
931
  }),
935
932
  );
936
933
  }
937
- }
938
934
 
939
- if (existsSync(join(opts.root, formatters))) {
940
- for (const file of readdirSync(join(opts.root, formatters)).filter((name) =>
941
- DoctorConstants.OXFMT_CONFIG_FILE.test(name),
942
- )) {
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
+ ) {
943
941
  warnings.push(
944
942
  createViolation({
945
943
  check: DoctorChecks.FORMAT,
946
- file: join(formatters, file),
944
+ file: copy,
947
945
  message:
948
- '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',
949
947
  }),
950
948
  );
951
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
+ }
952
977
  }
978
+
979
+ return warnings;
953
980
  }
954
981
 
955
- return warnings;
956
- };
982
+ static checkAtlasBlock(opts: ICheckContext): IViolation[] {
983
+ const merged = AtlasBlockPlan.merged({ root: opts.root, config: opts.config });
957
984
 
958
- export const checkAtlasBlock = (opts: ICheckContext): IViolation[] => {
959
- 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
+ }
960
995
 
961
- return merged === undefined || !merged.changed
962
- ? []
963
- : [
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) =>
964
1001
  createViolation({
965
- check: DoctorChecks.AGENTS,
966
- file: 'AGENTS.md',
967
- 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`,
968
1005
  }),
969
- ];
970
- };
1006
+ );
1007
+ }
971
1008
 
972
- /** 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. */
973
- export const checkSkillTriggers = (opts: ICheckContext): IViolation[] =>
974
- SkillCatalog.catalogOf({ root: opts.root })
975
- .filter((entry) => !SkillCatalog.triggerOf({ description: entry.description }).hasUseWhen)
976
- .map((entry) =>
977
- createViolation({
978
- check: DoctorChecks.SKILLS,
979
- file: entry.source === 'project' ? `.agents/skills/${entry.name}/SKILL.md` : entry.name,
980
- message: `'${entry.name}' has no "Use when" part in its description - atlas cannot say when to load it`,
981
- }),
982
- );
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
+ }
983
1021
 
984
- /** `.agents/local/` exists with its subdirectories and is gitignored: `sync` does both, so an upgraded project that has not synced yet is told here. */
985
- export const checkLocalWorkspace = (opts: ICheckContext): IViolation[] =>
986
- planLocalWorkspace({ root: opts.root })
987
- .filter((action) => action.status !== SyncStatuses.UNCHANGED)
988
- .map((action) =>
989
- createViolation({
990
- check: DoctorChecks.LOCAL,
991
- file: relative(opts.root, action.path) || '.',
992
- message: `${action.note ?? 'out of date'} - run 'bun x --no-install vulcan sync'`,
993
- }),
994
- );
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
+ });
995
1032
 
996
- /**
997
- * A worktree of this repository that lives outside it: the repository's own `git worktree list` names it
998
- * (git metadata is inside the project), and the exact command moves it in. Nothing is moved or removed.
999
- */
1000
- export const checkOutsideWorktrees = (opts: ICheckContext): IViolation[] => {
1001
- const listed = spawnSync('git', ['worktree', 'list', '--porcelain'], {
1002
- cwd: opts.root,
1003
- encoding: 'utf8',
1004
- timeout: 5000,
1005
- });
1033
+ if (listed.status !== 0) {
1034
+ return [];
1035
+ }
1006
1036
 
1007
- if (listed.status !== 0) {
1008
- return [];
1009
- }
1037
+ const [boundary, ...linked] = listed.stdout
1038
+ .split('\n')
1039
+ .filter((line) => line.startsWith('worktree '))
1040
+ .map((line) => line.slice('worktree '.length));
1010
1041
 
1011
- const [boundary, ...linked] = listed.stdout
1012
- .split('\n')
1013
- .filter((line) => line.startsWith('worktree '))
1014
- .map((line) => line.slice('worktree '.length));
1042
+ if (boundary === undefined) {
1043
+ return [];
1044
+ }
1045
+
1046
+ const inside = (path: string): boolean => {
1047
+ const real = existsSync(path) ? realpathSync(path) : path;
1015
1048
 
1016
- if (boundary === undefined) {
1017
- return [];
1049
+ return real === boundary || real.startsWith(`${boundary}${sep}`);
1050
+ };
1051
+
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
+ );
1018
1061
  }
1019
1062
 
1020
- const inside = (path: string): boolean => {
1021
- 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[] = [];
1022
1067
 
1023
- return real === boundary || real.startsWith(`${boundary}${sep}`);
1024
- };
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
+ }
1025
1077
 
1026
- return linked
1027
- .filter((path) => !inside(path))
1028
- .map((path) =>
1029
- createViolation({
1030
- check: DoctorChecks.LOCAL,
1031
- file: path,
1032
- message: `a git worktree outside the project - move it in: git worktree move '${path}' '${join(boundary, ProjectLayout.LOCAL_DIRECTORY, 'worktrees', basename(path))}'`,
1033
- }),
1034
- );
1035
- };
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
+ }
1036
1091
 
1037
- /** The personal profile: a file that cannot be read is named, and one git tracks is a personal file about to be shared. */
1038
- export const checkProfile = (opts: ICheckContext): IViolation[] => {
1039
- const read = readProfile({ root: opts.root });
1040
- 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
+ }
1041
1105
 
1042
- if (!read.ok) {
1043
- violations.push(
1044
- createViolation({
1045
- check: DoctorChecks.PROFILE,
1046
- file: OwnerConstants.PROFILE_FILE,
1047
- message: `${read.error} - fix it or delete it and run the profile form again`,
1048
- }),
1049
- );
1106
+ return violations;
1050
1107
  }
1051
1108
 
1052
- if (
1053
- existsSync(join(opts.root, OwnerConstants.PROFILE_FILE)) &&
1054
- !profileIsIgnored({ root: opts.root })
1055
- ) {
1056
- violations.push(
1057
- createViolation({
1058
- check: DoctorChecks.PROFILE,
1059
- file: OwnerConstants.PROFILE_FILE,
1060
- message:
1061
- 'git does not ignore this personal file - add .agents/local/ to .gitignore (vulcan sync does it)',
1062
- }),
1063
- );
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
+ );
1064
1124
  }
1065
1125
 
1066
- if (
1067
- existsSync(join(opts.root, OwnerConstants.PROFILE_FILE)) &&
1068
- isTracked({ root: opts.root, path: OwnerConstants.PROFILE_FILE })
1069
- ) {
1070
- violations.push(
1071
- createViolation({
1072
- check: DoctorChecks.PROFILE,
1073
- file: OwnerConstants.PROFILE_FILE,
1074
- message:
1075
- 'git tracks this personal file - run: git rm --cached .agents/local/profile.json (and keep .agents/local/ in .gitignore)',
1076
- }),
1077
- );
1078
- }
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 });
1079
1129
 
1080
- return violations;
1081
- };
1130
+ if (replies === 0) {
1131
+ return [];
1132
+ }
1082
1133
 
1083
- /** What an agent left under `.agents/local/` that has outlived its use, one line each with the command that clears it. */
1084
- export const checkStaleLocal = (opts: ICheckContext): IViolation[] =>
1085
- scanLocal({ root: opts.root })
1086
- .filter((entry) =>
1087
- [LocalStates.STALE, LocalStates.MERGED, LocalStates.GONE, LocalStates.ORPHAN].includes(
1088
- entry.state,
1089
- ),
1090
- )
1091
- .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
+ : []),
1092
1151
  createViolation({
1093
1152
  check: DoctorChecks.LOCAL,
1094
- file: `${ProjectLayout.LOCAL_DIRECTORY}/${entry.scope}/${entry.name}`,
1095
- 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`,
1096
1155
  }),
1097
- );
1098
-
1099
- /** 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. */
1100
- export const checkReplyShape = (opts: ICheckContext): IViolation[] => {
1101
- const { byClass, replies, days } = readViolationCounts({ root: opts.root });
1102
-
1103
- if (replies === 0) {
1104
- return [];
1156
+ ];
1105
1157
  }
1106
1158
 
1107
- const parts = [...byClass.entries()]
1108
- .sort((first, second) => second[1] - first[1])
1109
- .map(([name, count]) => `${name} ${count}`);
1110
-
1111
- const isFull = violationLogBytes({ root: opts.root }) > ViolationConstants.LOG_MAX_BYTES;
1112
-
1113
- return [
1114
- ...(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 })
1115
1162
  ? [
1116
1163
  createViolation({
1117
1164
  check: DoctorChecks.LOCAL,
1118
- file: `${ProjectLayout.LOCAL_DIRECTORY}/${ViolationConstants.LOG_FILE}`,
1119
- 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`,
1120
1167
  }),
1121
1168
  ]
1122
- : []),
1123
- createViolation({
1124
- check: DoctorChecks.LOCAL,
1125
- file: `${ProjectLayout.LOCAL_DIRECTORY}/${ViolationConstants.LOG_FILE}`,
1126
- 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`,
1127
- }),
1128
- ];
1129
- };
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
+ }
1130
1227
 
1131
- /** 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. */
1132
- export const checkOwnerReplySwitch = (opts: {
1133
- env: Record<string, string | undefined>;
1134
- }): IViolation[] =>
1135
- isOwnerReplyOff({ env: opts.env })
1136
- ? [
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;
1235
+
1236
+ return [
1237
+ ...commands.map((command) =>
1137
1238
  createViolation({
1138
- check: DoctorChecks.LOCAL,
1139
- file: OwnerReplySwitch.ENV,
1140
- 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' : ''}`,
1141
1242
  }),
1142
- ]
1143
- : [];
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
+ }
1144
1255
 
1145
- /** 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. */
1146
- export const checkOwnerReplySettings = (opts: { root: string }): IViolation[] =>
1147
- ['.claude/settings.json', '.claude/settings.local.json'].flatMap((file) => {
1148
- 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);
1149
1259
 
1150
- return typeof env === 'object' &&
1151
- env !== null &&
1152
- Reflect.get(env, OwnerReplySwitch.ENV) === OwnerReplySwitch.OFF
1153
- ? [
1154
- createViolation({
1155
- check: DoctorChecks.LOCAL,
1156
- file,
1157
- 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`,
1158
- }),
1159
- ]
1160
- : [];
1161
- });
1260
+ if (total < LocalConstants.NOTE_BYTES) {
1261
+ return [];
1262
+ }
1162
1263
 
1163
- /** The size of `.agents/local/` once it is large: where the space went, and the command that gives it back. */
1164
- /** 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. */
1165
- const STALE_TRUST_STATES = new Set<string>([
1166
- TrustStates.MISSING,
1167
- TrustStates.UNTRACKED,
1168
- TrustStates.UNCOMMITTED,
1169
- TrustStates.SYMLINK,
1170
- TrustStates.UNKNOWN,
1171
- ]);
1264
+ const byScope = new Map<string, number>();
1172
1265
 
1173
- const QUOTES = ["'", '"', '`'];
1266
+ for (const entry of entries) {
1267
+ byScope.set(entry.scope, (byScope.get(entry.scope) ?? 0) + entry.bytes);
1268
+ }
1174
1269
 
1175
- /** The path of a `guard.writes.trustedScripts` entry, and the subcommands when it is the object form. */
1176
- const trustedScriptOf = (opts: {
1177
- entry: TResolvedConfig['guard']['writes']['trustedScripts'][number];
1178
- }): { script: string; readOnly: string[] | undefined } =>
1179
- typeof opts.entry === 'string'
1180
- ? { script: opts.entry, readOnly: undefined }
1181
- : { script: opts.entry.script, readOnly: opts.entry.readOnly };
1270
+ const parts = [...byScope.entries()]
1271
+ .sort((first, second) => second[1] - first[1])
1272
+ .map(([scope, bytes]) => `${scope} ${LocalFormat.formatBytes({ bytes })}`);
1182
1273
 
1183
- /** One line per script in `guard.writes.trustedScripts` with what git says about it now (a note). */
1184
- export const checkTrustedScripts = (opts: ICheckContext): IViolation[] =>
1185
- opts.config.guard.writes.trustedScripts.map((entry) => {
1186
- const { script, readOnly } = trustedScriptOf({ entry });
1187
- const trust = trustOf({ root: opts.root, script });
1188
- const scope = readOnly === undefined ? 'mutating calls' : `the calls ${readOnly.join(', ')}`;
1189
-
1190
- return createViolation({
1191
- check: DoctorChecks.GUARDS,
1192
- file: script,
1193
- message:
1194
- trust.state === TrustStates.TRUSTED
1195
- ? `guard-writes does not read this script for ${scope} (guard.writes.trustedScripts); it is ` +
1196
- trust.reason
1197
- : `listed in guard.writes.trustedScripts, but guard-writes reads it like any script now: ${trust.reason}`,
1198
- });
1199
- });
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 = ["'", '"', '`'];
1200
1285
 
1201
1286
  /**
1202
1287
  * A subcommand an object entry lists that its script never holds as a quoted string (a note). It reads the
@@ -1245,75 +1330,3 @@ export class ReadOnlySubcommandChecks {
1245
1330
  });
1246
1331
  }
1247
1332
  }
1248
-
1249
- /** A listed script that does not exist or is not committed: the exemption never applies (a warning). */
1250
- export const checkStaleTrustedScripts = (opts: ICheckContext): IViolation[] =>
1251
- opts.config.guard.writes.trustedScripts.flatMap((entry) => {
1252
- const { script } = trustedScriptOf({ entry });
1253
- const trust = trustOf({ root: opts.root, script });
1254
-
1255
- return STALE_TRUST_STATES.has(trust.state)
1256
- ? [
1257
- createViolation({
1258
- check: DoctorChecks.GUARDS,
1259
- file: script,
1260
- message: `guard.writes.trustedScripts lists it, but it never takes effect: ${trust.reason}; fix the path, or commit the script`,
1261
- }),
1262
- ]
1263
- : [];
1264
- });
1265
-
1266
- /**
1267
- * The commands and push targets the project adds to guard-writes and guard-git, one note each: so the
1268
- * guards' reach beyond their own list is visible where a person looks, with the rule and the pattern.
1269
- */
1270
- export const checkGuardPatterns = (opts: ICheckContext): IViolation[] => {
1271
- const { commands } = opts.config.guard.writes;
1272
- const { askPush } = opts.config.guard.git;
1273
-
1274
- return [
1275
- ...commands.map((command) =>
1276
- createViolation({
1277
- check: DoctorChecks.GUARDS,
1278
- file: opts.configFile,
1279
- message: `guard.writes.commands: ${command.rule} '${command.what}' asks when a command matches /${command.pattern}/${command.ignoreCase === true ? 'i' : ''}`,
1280
- }),
1281
- ),
1282
- ...(askPush.length === 0
1283
- ? []
1284
- : [
1285
- createViolation({
1286
- check: DoctorChecks.GUARDS,
1287
- file: opts.configFile,
1288
- message: `guard.git.askPush: a plain git push asks for ${askPush.join(', ')}`,
1289
- }),
1290
- ]),
1291
- ];
1292
- };
1293
-
1294
- export const checkLocalSize = (opts: ICheckContext): IViolation[] => {
1295
- const entries = scanLocal({ root: opts.root });
1296
- const total = entries.reduce((sum, entry) => sum + entry.bytes, 0);
1297
-
1298
- if (total < LocalConstants.NOTE_BYTES) {
1299
- return [];
1300
- }
1301
-
1302
- const byScope = new Map<string, number>();
1303
-
1304
- for (const entry of entries) {
1305
- byScope.set(entry.scope, (byScope.get(entry.scope) ?? 0) + entry.bytes);
1306
- }
1307
-
1308
- const parts = [...byScope.entries()]
1309
- .sort((first, second) => second[1] - first[1])
1310
- .map(([scope, bytes]) => `${scope} ${formatBytes({ bytes })}`);
1311
-
1312
- return [
1313
- createViolation({
1314
- check: DoctorChecks.LOCAL,
1315
- file: ProjectLayout.LOCAL_DIRECTORY,
1316
- message: `holds ${formatBytes({ bytes: total })} (${parts.join(', ')}); vulcan clean lists what an agent left and --yes removes it`,
1317
- }),
1318
- ];
1319
- };