@venizia/vulcan 0.4.0 → 0.4.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/claude/remote-hosts.json +1 -1
  2. package/base/claude/settings.json +75 -3
  3. package/base/hooks/guard-git.ts +55 -0
  4. package/base/hooks/guard-manifest.ts +1 -1
  5. package/base/hooks/guard-outside.ts +66 -0
  6. package/base/hooks/guard-package.ts +3 -2
  7. package/base/hooks/guard-remote-hosts.ts +3 -2
  8. package/base/hooks/guard-writes.ts +1 -1
  9. package/base/hooks/post-tool.ts +36 -0
  10. package/base/hooks/prompt-submit.ts +52 -0
  11. package/base/hooks/stop.ts +38 -0
  12. package/base/hooks/subagent-start.ts +18 -0
  13. package/base/references/delegation-brief.md +63 -0
  14. package/base/references/design-pass.md +39 -0
  15. package/base/references/evidence.md +36 -0
  16. package/base/references/phase-boundaries.md +20 -0
  17. package/base/references/testing.md +89 -0
  18. package/base/rules.md +11 -2
  19. package/base/skills/build-a-feature/SKILL.md +49 -23
  20. package/base/skills/docs-update/SKILL.md +12 -1
  21. package/base/skills/docs-writing/SKILL.md +2 -2
  22. package/base/skills/docs-writing/references/agent-documents.md +53 -0
  23. package/base/skills/fix-a-bug/SKILL.md +84 -0
  24. package/base/skills/fix-a-bug/evals/evals.json +17 -0
  25. package/base/skills/knowledge-sync/SKILL.md +4 -1
  26. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +10 -10
  27. package/base/skills/plan-a-change/SKILL.md +95 -0
  28. package/base/skills/plan-a-change/evals/evals.json +23 -0
  29. package/base/skills/plan-a-change/references/spec-card.md +39 -0
  30. package/base/skills/report-back/SKILL.md +112 -0
  31. package/base/skills/report-back/evals/evals.json +23 -0
  32. package/base/skills/research/SKILL.md +64 -0
  33. package/base/skills/research/evals/evals.json +17 -0
  34. package/base/skills/retro/SKILL.md +69 -0
  35. package/base/skills/retro/evals/evals.json +17 -0
  36. package/base/skills/review-a-change/SKILL.md +90 -0
  37. package/base/skills/review-a-change/evals/evals.json +17 -0
  38. package/base/skills/ship/SKILL.md +82 -0
  39. package/base/skills/ship/evals/evals.json +23 -0
  40. package/base/skills/visualize-work/SKILL.md +87 -0
  41. package/base/skills/visualize-work/evals/evals.json +17 -0
  42. package/base/skills/visualize-work/references/spec.md +65 -0
  43. package/package.json +3 -3
  44. package/src/agents/common/schema.ts +2 -2
  45. package/src/agents/detect.ts +5 -5
  46. package/src/agents/exclude.ts +3 -3
  47. package/src/agents/local.ts +1 -1
  48. package/src/agents/prompt.ts +2 -2
  49. package/src/agents/render.ts +2 -2
  50. package/src/agents/resolve.ts +6 -6
  51. package/src/agents/table.ts +1 -1
  52. package/src/commands/agents.command.ts +4 -4
  53. package/src/commands/clean.command.ts +72 -0
  54. package/src/commands/help.command.ts +11 -0
  55. package/src/commands/index.ts +6 -0
  56. package/src/commands/init.command.ts +4 -1
  57. package/src/commands/profile.command.ts +255 -0
  58. package/src/commands/sync.command.ts +6 -4
  59. package/src/commands/upgrade.command.ts +1 -1
  60. package/src/commands/visualize.command.ts +107 -0
  61. package/src/common/constants.ts +23 -0
  62. package/src/config/common/constants.ts +2 -0
  63. package/src/config/loader.ts +4 -4
  64. package/src/config/packages.ts +1 -1
  65. package/src/config/schema.ts +16 -5
  66. package/src/create/add-app.ts +15 -15
  67. package/src/create/add-lib.ts +7 -7
  68. package/src/create/bunfig.ts +1 -1
  69. package/src/create/dockerignore.ts +4 -4
  70. package/src/create/init-monorepo.ts +3 -1
  71. package/src/create/lib-preset.ts +1 -1
  72. package/src/create/names.ts +7 -6
  73. package/src/create/next.ts +4 -4
  74. package/src/create/preset-menu.ts +4 -4
  75. package/src/create/preset.ts +3 -3
  76. package/src/create/scratch.ts +27 -6
  77. package/src/create/workspace.ts +11 -11
  78. package/src/doctor/checks.ts +231 -45
  79. package/src/doctor/common/constants.ts +4 -0
  80. package/src/doctor/makefile.ts +3 -3
  81. package/src/doctor/runner.ts +16 -1
  82. package/src/doctor/skills.ts +8 -8
  83. package/src/doctor/tags.ts +5 -5
  84. package/src/hooks/common/constants.ts +29 -0
  85. package/src/hooks/common/types.ts +20 -0
  86. package/src/hooks/decision.ts +15 -0
  87. package/src/hooks/guard-git.ts +288 -0
  88. package/src/hooks/guard-manifest.ts +1 -1
  89. package/src/hooks/guard-outside.ts +399 -0
  90. package/src/hooks/guard-package.ts +4 -4
  91. package/src/hooks/guard-writes.ts +5 -5
  92. package/src/hooks/index.ts +6 -0
  93. package/src/hooks/owner-reply.ts +148 -0
  94. package/src/hooks/post-tool.ts +137 -0
  95. package/src/hooks/remote-hosts.ts +25 -23
  96. package/src/hooks/session-digest.ts +24 -4
  97. package/src/hooks/shell.ts +325 -0
  98. package/src/hooks/subagent-card.ts +32 -0
  99. package/src/init/scaffold.ts +6 -6
  100. package/src/local/clean.ts +88 -0
  101. package/src/local/constants.ts +50 -0
  102. package/src/local/format.ts +25 -0
  103. package/src/local/index.ts +4 -0
  104. package/src/local/scan.ts +368 -0
  105. package/src/manifest/render.ts +1 -1
  106. package/src/owner/card.ts +85 -0
  107. package/src/owner/constants.ts +105 -0
  108. package/src/owner/index.ts +8 -0
  109. package/src/owner/profile.ts +123 -0
  110. package/src/owner/schema.ts +147 -0
  111. package/src/owner/shape.ts +388 -0
  112. package/src/owner/survey.ts +289 -0
  113. package/src/owner/view.ts +76 -0
  114. package/src/owner/violations.ts +202 -0
  115. package/src/router.ts +18 -1
  116. package/src/rules/base.ts +1 -1
  117. package/src/rules/parser.ts +5 -5
  118. package/src/signals/claims.ts +71 -0
  119. package/src/signals/classify.ts +132 -0
  120. package/src/signals/constants.ts +88 -0
  121. package/src/signals/index.ts +5 -0
  122. package/src/signals/loop.ts +46 -0
  123. package/src/signals/state.ts +276 -0
  124. package/src/sync/agent-files.ts +4 -4
  125. package/src/sync/agent-removal.ts +6 -6
  126. package/src/sync/atlas-block.ts +1 -1
  127. package/src/sync/base-rules.ts +1 -1
  128. package/src/sync/exclude.ts +9 -9
  129. package/src/sync/local-choice.ts +35 -5
  130. package/src/sync/planner.ts +16 -16
  131. package/src/sync/prune.ts +3 -3
  132. package/src/sync/settings.ts +15 -15
  133. package/src/ui/prompt.ts +3 -3
  134. package/src/visualize/assets.ts +80 -0
  135. package/src/visualize/constants.ts +126 -0
  136. package/src/visualize/index.ts +6 -0
  137. package/src/visualize/layout.ts +107 -0
  138. package/src/visualize/page.ts +211 -0
  139. package/src/visualize/render.ts +161 -0
  140. package/src/visualize/schema.ts +178 -0
  141. package/src/visualize/validate.ts +127 -0
@@ -1,6 +1,7 @@
1
1
  import { Glob } from 'bun';
2
- import { existsSync, readdirSync, readFileSync } from 'node:fs';
3
- import { dirname, join, relative } from 'node:path';
2
+ import { spawnSync } from 'node:child_process';
3
+ import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
4
+ import { basename, dirname, join, relative, sep } from 'node:path';
4
5
  import { BASE_DIRECTORY, ProjectLayout } from '../common/index.ts';
5
6
  import {
6
7
  coversFolder,
@@ -32,11 +33,21 @@ import {
32
33
  import {
33
34
  isTracked,
34
35
  mergedAtlasBlock,
36
+ planLocalWorkspace,
35
37
  planManifest,
36
38
  planPrune,
37
39
  planSync,
38
40
  SyncStatuses,
39
41
  } from '../sync/index.ts';
42
+ import { formatAge, formatBytes, LocalConstants, LocalStates, scanLocal } from '../local/index.ts';
43
+ import {
44
+ OwnerConstants,
45
+ profileIsIgnored,
46
+ readProfile,
47
+ readViolationCounts,
48
+ violationLogBytes,
49
+ ViolationConstants,
50
+ } from '../owner/index.ts';
40
51
  import { skillCatalogOf, triggerOf } from '@venizia/vulcan-atlas';
41
52
  import { AppScripts, DoctorChecks, DoctorConstants } from './common/index.ts';
42
53
  import type { IViolation, TDoctorCheck } from './common/index.ts';
@@ -64,14 +75,14 @@ const readText = (opts: { file: string }): string =>
64
75
  const listDirectories = (opts: { directory: string }): string[] =>
65
76
  existsSync(opts.directory)
66
77
  ? readdirSync(opts.directory, { withFileTypes: true })
67
- .filter(entry => entry.isDirectory())
68
- .map(entry => entry.name)
78
+ .filter((entry) => entry.isDirectory())
79
+ .map((entry) => entry.name)
69
80
  : [];
70
81
 
71
82
  export const checkLayout = (opts: ICheckContext): IViolation[] =>
72
83
  ['AGENTS.md', '.agents/rules.md', opts.config.knowledge.bundle]
73
- .filter(path => !existsSync(join(opts.root, path)))
74
- .map(path =>
84
+ .filter((path) => !existsSync(join(opts.root, path)))
85
+ .map((path) =>
75
86
  createViolation({
76
87
  check: DoctorChecks.LAYOUT,
77
88
  file: path,
@@ -90,8 +101,8 @@ export const checkRuleIds = (opts: ICheckContext): IViolation[] => {
90
101
  return parseBaseReferences({
91
102
  markdown: readText({ file: join(opts.root, '.agents', 'rules.md') }),
92
103
  })
93
- .filter(id => base[id] === undefined)
94
- .map(id =>
104
+ .filter((id) => base[id] === undefined)
105
+ .map((id) =>
95
106
  createViolation({
96
107
  check: DoctorChecks.RULE_IDS,
97
108
  file: '.agents/rules.md',
@@ -132,7 +143,7 @@ export const checkRuleSlots = (opts: ICheckContext): IViolation[] => {
132
143
  }
133
144
  }
134
145
 
135
- for (const id of Object.keys(opts.config.rules).filter(ruleId => slots[ruleId] === undefined)) {
146
+ for (const id of Object.keys(opts.config.rules).filter((ruleId) => slots[ruleId] === undefined)) {
136
147
  const namespaced = `${RuleConstants.BASE_NAMESPACE}${id}`;
137
148
 
138
149
  violations.push(
@@ -154,8 +165,8 @@ export const checkSkills = (opts: ICheckContext): IViolation[] => {
154
165
  const shipped = new Set(listDirectories({ directory: join(BASE_DIRECTORY, 'skills') }));
155
166
 
156
167
  return listDirectories({ directory: join(opts.root, '.agents', 'skills') })
157
- .filter(name => shipped.has(name))
158
- .map(name =>
168
+ .filter((name) => shipped.has(name))
169
+ .map((name) =>
159
170
  createViolation({
160
171
  check: DoctorChecks.SKILLS,
161
172
  file: `.agents/skills/${name}`,
@@ -186,7 +197,7 @@ const findProjectMakefiles = (opts: { root: string }): string[] => {
186
197
  })) {
187
198
  const matches = [...new Glob(pattern).scanSync({ cwd: opts.root, onlyFiles: true })].sort();
188
199
 
189
- pending.push(...matches.filter(match => !match.split('/').includes('node_modules')));
200
+ pending.push(...matches.filter((match) => !match.split('/').includes('node_modules')));
190
201
  }
191
202
  }
192
203
 
@@ -214,7 +225,7 @@ export const checkMake = (opts: ICheckContext): IViolation[] => {
214
225
  for (const file of findProjectMakefiles({ root: opts.root })) {
215
226
  const targets = parseMakeTargets({ makefile: readText({ file: join(opts.root, file) }) });
216
227
 
217
- for (const target of targets.filter(name => shipped.has(name))) {
228
+ for (const target of targets.filter((name) => shipped.has(name))) {
218
229
  violations.push(
219
230
  createViolation({
220
231
  check: DoctorChecks.MAKE,
@@ -230,8 +241,8 @@ export const checkMake = (opts: ICheckContext): IViolation[] => {
230
241
 
231
242
  export const checkHooks = (opts: ICheckContext): IViolation[] =>
232
243
  opts.config.hooks
233
- .filter(hook => hook.command.includes(DoctorConstants.SHIPPED_HOOKS_PATH))
234
- .map(hook =>
244
+ .filter((hook) => hook.command.includes(DoctorConstants.SHIPPED_HOOKS_PATH))
245
+ .map((hook) =>
235
246
  createViolation({
236
247
  check: DoctorChecks.HOOKS,
237
248
  file: opts.configFile,
@@ -245,10 +256,10 @@ export const checkAdapters = (opts: ICheckContext): IViolation[] => {
245
256
  config: opts.config,
246
257
  agents: resolveAgentsQuietly({ root: opts.root, configAgents: opts.config.agents }),
247
258
  })
248
- .filter(action => action.status !== SyncStatuses.UNCHANGED)
249
- .filter(action => action.path !== join(opts.root, ManifestConstants.FILE));
250
- const absent = pending.filter(action => action.status === SyncStatuses.CREATED);
251
- const differing = pending.filter(action => action.status !== SyncStatuses.CREATED);
259
+ .filter((action) => action.status !== SyncStatuses.UNCHANGED)
260
+ .filter((action) => action.path !== join(opts.root, ManifestConstants.FILE));
261
+ const absent = pending.filter((action) => action.status === SyncStatuses.CREATED);
262
+ const differing = pending.filter((action) => action.status !== SyncStatuses.CREATED);
252
263
 
253
264
  // A clean checkout has none of the gitignored adapters: say so once, with the fix, not once per file.
254
265
  const violations =
@@ -264,7 +275,7 @@ export const checkAdapters = (opts: ICheckContext): IViolation[] => {
264
275
 
265
276
  return [
266
277
  ...violations,
267
- ...differing.map(action =>
278
+ ...differing.map((action) =>
268
279
  createViolation({
269
280
  check: DoctorChecks.ADAPTERS,
270
281
  file: relative(opts.root, action.path),
@@ -279,7 +290,7 @@ export const checkAdapters = (opts: ICheckContext): IViolation[] => {
279
290
 
280
291
  /** What `sync --prune` would remove: an old VULCAN or plugin-era hook command, a dead skill link. */
281
292
  export const checkPrune = (opts: ICheckContext): IViolation[] =>
282
- planPrune({ root: opts.root }).map(action =>
293
+ planPrune({ root: opts.root }).map((action) =>
283
294
  createViolation({
284
295
  check: DoctorChecks.PRUNE,
285
296
  file: relative(opts.root, action.path),
@@ -344,11 +355,11 @@ export const checkStyle = (opts: ICheckContext): IViolation[] => {
344
355
  const owners = [
345
356
  ...new Set([
346
357
  '.',
347
- ...listDirectories({ directory: join(opts.root, 'packages') }).map(name =>
358
+ ...listDirectories({ directory: join(opts.root, 'packages') }).map((name) =>
348
359
  join('packages', name),
349
360
  ),
350
361
  ...resolvePackages({ config: opts.config }).map(
351
- entry => relative(opts.root, join(opts.root, entry.path)) || '.',
362
+ (entry) => relative(opts.root, join(opts.root, entry.path)) || '.',
352
363
  ),
353
364
  ]),
354
365
  ];
@@ -358,17 +369,17 @@ export const checkStyle = (opts: ICheckContext): IViolation[] => {
358
369
  for (const owner of owners) {
359
370
  const configs = join(owner, '.configs');
360
371
  const found = ['.', ...new Set(Object.values(DoctorConstants.LINT_CONFIG_FOLDERS))].flatMap(
361
- folder => {
372
+ (folder) => {
362
373
  const directory = join(configs, folder);
363
374
 
364
375
  return existsSync(join(opts.root, directory))
365
376
  ? readdirSync(join(opts.root, directory))
366
- .filter(file => DoctorConstants.LINT_CONFIG_FILE.test(file))
367
- .map(file => ({ file: join(directory, file), name: file, legacy: folder === '.' }))
377
+ .filter((file) => DoctorConstants.LINT_CONFIG_FILE.test(file))
378
+ .map((file) => ({ file: join(directory, file), name: file, legacy: folder === '.' }))
368
379
  : [];
369
380
  },
370
381
  );
371
- const names = found.map(item => item.file);
382
+ const names = found.map((item) => item.file);
372
383
 
373
384
  lintConfigs += names.length;
374
385
 
@@ -486,7 +497,7 @@ export const checkApps = (opts: ICheckContext): IViolation[] => {
486
497
  );
487
498
  const names = folders.map(([, folder]) => folder);
488
499
 
489
- for (const entry of resolvePackages({ config: opts.config }).filter(item => !item.retired)) {
500
+ for (const entry of resolvePackages({ config: opts.config }).filter((item) => !item.retired)) {
490
501
  if (entry.kind === 'lib') {
491
502
  const parent = dirname(entry.path);
492
503
 
@@ -504,7 +515,7 @@ export const checkApps = (opts: ICheckContext): IViolation[] => {
504
515
  continue;
505
516
  }
506
517
 
507
- if (!names.some(folder => entry.path.startsWith(`${folder}/`))) {
518
+ if (!names.some((folder) => entry.path.startsWith(`${folder}/`))) {
508
519
  violations.push(
509
520
  createViolation({
510
521
  check: DoctorChecks.APPS,
@@ -554,8 +565,8 @@ export const checkAppScripts = (opts: ICheckContext): IViolation[] => {
554
565
  );
555
566
  const notes: IViolation[] = [];
556
567
 
557
- for (const entry of resolvePackages({ config: opts.config }).filter(item => !item.retired)) {
558
- if (!appFolders.some(folder => entry.path.startsWith(`${folder}/`))) {
568
+ for (const entry of resolvePackages({ config: opts.config }).filter((item) => !item.retired)) {
569
+ if (!appFolders.some((folder) => entry.path.startsWith(`${folder}/`))) {
559
570
  continue;
560
571
  }
561
572
 
@@ -566,8 +577,8 @@ export const checkAppScripts = (opts: ICheckContext): IViolation[] => {
566
577
  continue;
567
578
  }
568
579
 
569
- const missing = AppScripts.STANDARD.filter(name => !names.includes(name));
570
- const legacy = AppScripts.LEGACY.filter(name => names.includes(name));
580
+ const missing = AppScripts.STANDARD.filter((name) => !names.includes(name));
581
+ const legacy = AppScripts.LEGACY.filter((name) => names.includes(name));
571
582
  const parts = [
572
583
  ...(missing.length === 0 ? [] : [`missing ${missing.join(', ')}`]),
573
584
  ...(legacy.length === 0 ? [] : [`legacy ${legacy.join(', ')} (use the standard names)`]),
@@ -638,7 +649,7 @@ export const checkMcpAtlas = (opts: ICheckContext): IViolation[] => {
638
649
  const file = join(opts.root, MCP_FILE);
639
650
  const chosen = resolveAgentsQuietly({ root: opts.root, configAgents: opts.config.agents });
640
651
  const readsMcpFile = readAgentTable().some(
641
- entry => chosen.includes(entry.id) && entry.mcp.scope === AgentScopes.SHARED,
652
+ (entry) => chosen.includes(entry.id) && entry.mcp.scope === AgentScopes.SHARED,
642
653
  );
643
654
 
644
655
  // The root `.mcp.json` is a per-machine file of the agents that read it; a missing one is the
@@ -760,8 +771,8 @@ export const checkDockerignore = (opts: ICheckContext): IViolation[] => {
760
771
  const lines = existsSync(file)
761
772
  ? readText({ file })
762
773
  .split('\n')
763
- .map(line => line.trim())
764
- .filter(line => line !== '' && !line.startsWith('#'))
774
+ .map((line) => line.trim())
775
+ .filter((line) => line !== '' && !line.startsWith('#'))
765
776
  : undefined;
766
777
 
767
778
  if (
@@ -773,8 +784,8 @@ export const checkDockerignore = (opts: ICheckContext): IViolation[] => {
773
784
  }
774
785
 
775
786
  const apps = resolvePackages({ config: opts.config })
776
- .filter(entry => !entry.retired && existsSync(join(opts.root, entry.path, DOCKERFILE)))
777
- .map(entry => entry.dir);
787
+ .filter((entry) => !entry.retired && existsSync(join(opts.root, entry.path, DOCKERFILE)))
788
+ .map((entry) => entry.dir);
778
789
 
779
790
  if (apps.length === 0) {
780
791
  return [];
@@ -795,7 +806,7 @@ export const checkDockerignore = (opts: ICheckContext): IViolation[] => {
795
806
  };
796
807
 
797
808
  const FMT_SECTION_ADVICE =
798
- 'add a [fmt] section (printWidth = 100, singleQuote = true, arrowParens = "avoid", flavor = "oxfmt"): without it bun fmt formats with Bun\'s defaults, not the shared style';
809
+ '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';
799
810
  const FMT_FLAVOR_ADVICE =
800
811
  'without it bun fmt formats like Prettier when oxfmt is not a dependency, and the output changes';
801
812
  const OXFMT_LOADED_ADVICE =
@@ -805,12 +816,12 @@ const OXFMT_LOADED_ADVICE =
805
816
  const formatOwners = (opts: ICheckContext): string[] => [
806
817
  ...new Set([
807
818
  '.',
808
- ...listDirectories({ directory: join(opts.root, 'packages') }).map(name =>
819
+ ...listDirectories({ directory: join(opts.root, 'packages') }).map((name) =>
809
820
  join('packages', name),
810
821
  ),
811
822
  ...resolvePackages({ config: opts.config })
812
- .filter(entry => !entry.retired)
813
- .map(entry => relative(opts.root, join(opts.root, entry.path)) || '.'),
823
+ .filter((entry) => !entry.retired)
824
+ .map((entry) => relative(opts.root, join(opts.root, entry.path)) || '.'),
814
825
  ]),
815
826
  ];
816
827
 
@@ -897,7 +908,7 @@ export const checkFormat = (opts: ICheckContext): IViolation[] => {
897
908
  }
898
909
 
899
910
  if (existsSync(join(opts.root, formatters))) {
900
- for (const file of readdirSync(join(opts.root, formatters)).filter(name =>
911
+ for (const file of readdirSync(join(opts.root, formatters)).filter((name) =>
901
912
  DoctorConstants.OXFMT_CONFIG_FILE.test(name),
902
913
  )) {
903
914
  warnings.push(
@@ -932,11 +943,186 @@ export const checkAtlasBlock = (opts: ICheckContext): IViolation[] => {
932
943
  /** 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. */
933
944
  export const checkSkillTriggers = (opts: ICheckContext): IViolation[] =>
934
945
  skillCatalogOf({ root: opts.root })
935
- .filter(entry => !triggerOf({ description: entry.description }).hasUseWhen)
936
- .map(entry =>
946
+ .filter((entry) => !triggerOf({ description: entry.description }).hasUseWhen)
947
+ .map((entry) =>
937
948
  createViolation({
938
949
  check: DoctorChecks.SKILLS,
939
950
  file: entry.source === 'project' ? `.agents/skills/${entry.name}/SKILL.md` : entry.name,
940
951
  message: `'${entry.name}' has no "Use when" part in its description - atlas cannot say when to load it`,
941
952
  }),
942
953
  );
954
+
955
+ /** `.agents/local/` exists with its subdirectories and is gitignored: `sync` does both, so an upgraded project that has not synced yet is told here. */
956
+ export const checkLocalWorkspace = (opts: ICheckContext): IViolation[] =>
957
+ planLocalWorkspace({ root: opts.root })
958
+ .filter((action) => action.status !== SyncStatuses.UNCHANGED)
959
+ .map((action) =>
960
+ createViolation({
961
+ check: DoctorChecks.LOCAL,
962
+ file: relative(opts.root, action.path) || '.',
963
+ message: `${action.note ?? 'out of date'} - run 'bun x --no-install vulcan sync'`,
964
+ }),
965
+ );
966
+
967
+ /**
968
+ * A worktree of this repository that lives outside it: the repository's own `git worktree list` names it
969
+ * (git metadata is inside the project), and the exact command moves it in. Nothing is moved or removed.
970
+ */
971
+ export const checkOutsideWorktrees = (opts: ICheckContext): IViolation[] => {
972
+ const listed = spawnSync('git', ['worktree', 'list', '--porcelain'], {
973
+ cwd: opts.root,
974
+ encoding: 'utf8',
975
+ timeout: 5000,
976
+ });
977
+
978
+ if (listed.status !== 0) {
979
+ return [];
980
+ }
981
+
982
+ const [boundary, ...linked] = listed.stdout
983
+ .split('\n')
984
+ .filter((line) => line.startsWith('worktree '))
985
+ .map((line) => line.slice('worktree '.length));
986
+
987
+ if (boundary === undefined) {
988
+ return [];
989
+ }
990
+
991
+ const inside = (path: string): boolean => {
992
+ const real = existsSync(path) ? realpathSync(path) : path;
993
+
994
+ return real === boundary || real.startsWith(`${boundary}${sep}`);
995
+ };
996
+
997
+ return linked
998
+ .filter((path) => !inside(path))
999
+ .map((path) =>
1000
+ createViolation({
1001
+ check: DoctorChecks.LOCAL,
1002
+ file: path,
1003
+ message: `a git worktree outside the project - move it in: git worktree move '${path}' '${join(boundary, ProjectLayout.LOCAL_DIRECTORY, 'worktrees', basename(path))}'`,
1004
+ }),
1005
+ );
1006
+ };
1007
+
1008
+ /** The personal profile: a file that cannot be read is named, and one git tracks is a personal file about to be shared. */
1009
+ export const checkProfile = (opts: ICheckContext): IViolation[] => {
1010
+ const read = readProfile({ root: opts.root });
1011
+ const violations: IViolation[] = [];
1012
+
1013
+ if (!read.ok) {
1014
+ violations.push(
1015
+ createViolation({
1016
+ check: DoctorChecks.PROFILE,
1017
+ file: OwnerConstants.PROFILE_FILE,
1018
+ message: `${read.error} - fix it or delete it and run the profile form again`,
1019
+ }),
1020
+ );
1021
+ }
1022
+
1023
+ if (
1024
+ existsSync(join(opts.root, OwnerConstants.PROFILE_FILE)) &&
1025
+ !profileIsIgnored({ root: opts.root })
1026
+ ) {
1027
+ violations.push(
1028
+ createViolation({
1029
+ check: DoctorChecks.PROFILE,
1030
+ file: OwnerConstants.PROFILE_FILE,
1031
+ message:
1032
+ 'git does not ignore this personal file - add .agents/local/ to .gitignore (vulcan sync does it)',
1033
+ }),
1034
+ );
1035
+ }
1036
+
1037
+ if (
1038
+ existsSync(join(opts.root, OwnerConstants.PROFILE_FILE)) &&
1039
+ isTracked({ root: opts.root, path: OwnerConstants.PROFILE_FILE })
1040
+ ) {
1041
+ violations.push(
1042
+ createViolation({
1043
+ check: DoctorChecks.PROFILE,
1044
+ file: OwnerConstants.PROFILE_FILE,
1045
+ message:
1046
+ 'git tracks this personal file - run: git rm --cached .agents/local/profile.json (and keep .agents/local/ in .gitignore)',
1047
+ }),
1048
+ );
1049
+ }
1050
+
1051
+ return violations;
1052
+ };
1053
+
1054
+ /** What an agent left under `.agents/local/` that has outlived its use, one line each with the command that clears it. */
1055
+ export const checkStaleLocal = (opts: ICheckContext): IViolation[] =>
1056
+ scanLocal({ root: opts.root })
1057
+ .filter((entry) =>
1058
+ [LocalStates.STALE, LocalStates.MERGED, LocalStates.GONE, LocalStates.ORPHAN].includes(
1059
+ entry.state,
1060
+ ),
1061
+ )
1062
+ .map((entry) =>
1063
+ createViolation({
1064
+ check: DoctorChecks.LOCAL,
1065
+ file: `${ProjectLayout.LOCAL_DIRECTORY}/${entry.scope}/${entry.name}`,
1066
+ message: `${entry.state === LocalStates.STALE ? `left ${formatAge({ ageMs: entry.ageMs })} ago` : entry.note} (${formatBytes({ bytes: entry.bytes })}) - run: vulcan clean --${entry.scope} --yes`,
1067
+ }),
1068
+ );
1069
+
1070
+ /** 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. */
1071
+ export const checkReplyShape = (opts: ICheckContext): IViolation[] => {
1072
+ const { byClass, replies, days } = readViolationCounts({ root: opts.root });
1073
+
1074
+ if (replies === 0) {
1075
+ return [];
1076
+ }
1077
+
1078
+ const parts = [...byClass.entries()]
1079
+ .sort((first, second) => second[1] - first[1])
1080
+ .map(([name, count]) => `${name} ${count}`);
1081
+
1082
+ const isFull = violationLogBytes({ root: opts.root }) > ViolationConstants.LOG_MAX_BYTES;
1083
+
1084
+ return [
1085
+ ...(isFull
1086
+ ? [
1087
+ createViolation({
1088
+ check: DoctorChecks.LOCAL,
1089
+ file: `${ProjectLayout.LOCAL_DIRECTORY}/${ViolationConstants.LOG_FILE}`,
1090
+ message: `the log is full (${formatBytes({ bytes: ViolationConstants.LOG_MAX_BYTES })}) and no longer grows; keep or delete it, and a new one starts`,
1091
+ }),
1092
+ ]
1093
+ : []),
1094
+ createViolation({
1095
+ check: DoctorChecks.LOCAL,
1096
+ file: `${ProjectLayout.LOCAL_DIRECTORY}/${ViolationConstants.LOG_FILE}`,
1097
+ 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`,
1098
+ }),
1099
+ ];
1100
+ };
1101
+
1102
+ /** The size of `.agents/local/` once it is large: where the space went, and the command that gives it back. */
1103
+ export const checkLocalSize = (opts: ICheckContext): IViolation[] => {
1104
+ const entries = scanLocal({ root: opts.root });
1105
+ const total = entries.reduce((sum, entry) => sum + entry.bytes, 0);
1106
+
1107
+ if (total < LocalConstants.NOTE_BYTES) {
1108
+ return [];
1109
+ }
1110
+
1111
+ const byScope = new Map<string, number>();
1112
+
1113
+ for (const entry of entries) {
1114
+ byScope.set(entry.scope, (byScope.get(entry.scope) ?? 0) + entry.bytes);
1115
+ }
1116
+
1117
+ const parts = [...byScope.entries()]
1118
+ .sort((first, second) => second[1] - first[1])
1119
+ .map(([scope, bytes]) => `${scope} ${formatBytes({ bytes })}`);
1120
+
1121
+ return [
1122
+ createViolation({
1123
+ check: DoctorChecks.LOCAL,
1124
+ file: ProjectLayout.LOCAL_DIRECTORY,
1125
+ message: `holds ${formatBytes({ bytes: total })} (${parts.join(', ')}); vulcan clean lists what an agent left and --yes removes it`,
1126
+ }),
1127
+ ];
1128
+ };
@@ -18,6 +18,8 @@ export class DoctorChecks {
18
18
  static readonly DOCKERIGNORE = 'dockerignore';
19
19
  static readonly MCP = 'mcp';
20
20
  static readonly FORMAT = 'format';
21
+ static readonly LOCAL = 'local';
22
+ static readonly PROFILE = 'profile';
21
23
  static readonly SCHEME_SET = new Set<string>([
22
24
  this.CONFIG,
23
25
  this.LAYOUT,
@@ -38,6 +40,8 @@ export class DoctorChecks {
38
40
  this.DOCKERIGNORE,
39
41
  this.MCP,
40
42
  this.FORMAT,
43
+ this.LOCAL,
44
+ this.PROFILE,
41
45
  ]);
42
46
  static isValid(value: string): boolean {
43
47
  return this.SCHEME_SET.has(value);
@@ -4,7 +4,7 @@ const RULE_TARGET = /^([A-Za-z0-9][A-Za-z0-9_.-]*)\s*:(?!=)/;
4
4
  export const parseMakeTargets = (opts: { makefile: string }): string[] =>
5
5
  opts.makefile
6
6
  .split('\n')
7
- .map(line => RULE_TARGET.exec(line)?.[1])
7
+ .map((line) => RULE_TARGET.exec(line)?.[1])
8
8
  .filter((target): target is string => target !== undefined);
9
9
 
10
10
  const INCLUDE_LINE = /^\s*(?:-include|sinclude|include)\s+(.+?)\s*$/;
@@ -13,5 +13,5 @@ const INCLUDE_LINE = /^\s*(?:-include|sinclude|include)\s+(.+?)\s*$/;
13
13
  export const parseMakeIncludes = (opts: { makefile: string }): string[] =>
14
14
  opts.makefile
15
15
  .split('\n')
16
- .flatMap(line => INCLUDE_LINE.exec(line)?.[1].split(/\s+/) ?? [])
17
- .filter(path => !path.includes('$('));
16
+ .flatMap((line) => INCLUDE_LINE.exec(line)?.[1].split(/\s+/) ?? [])
17
+ .filter((path) => !path.includes('$('));
@@ -11,10 +11,16 @@ import {
11
11
  checkMcpAtlas,
12
12
  checkApps,
13
13
  checkManifest,
14
+ checkLocalSize,
15
+ checkProfile,
16
+ checkReplyShape,
14
17
  checkPrune,
18
+ checkStaleLocal,
15
19
  checkHooks,
16
20
  checkLayout,
21
+ checkLocalWorkspace,
17
22
  checkMake,
23
+ checkOutsideWorktrees,
18
24
  checkRuleIds,
19
25
  checkRuleSlots,
20
26
  checkScaffold,
@@ -79,7 +85,12 @@ export const runDoctorNotes = async (opts: { root: string }): Promise<IViolation
79
85
  configFile: relative(opts.root, loaded.file),
80
86
  };
81
87
 
82
- return [...checkAppScripts(context), ...checkAtlasBlock(context)];
88
+ return [
89
+ ...checkAppScripts(context),
90
+ ...checkAtlasBlock(context),
91
+ ...checkLocalSize(context),
92
+ ...checkReplyShape(context),
93
+ ];
83
94
  };
84
95
 
85
96
  /** Warnings: louder than a note, still never a failure - a security gap a project made earlier may carry. */
@@ -101,5 +112,9 @@ export const runDoctorWarnings = async (opts: { root: string }): Promise<IViolat
101
112
  ...checkDockerignore(context),
102
113
  ...checkSkillTriggers(context),
103
114
  ...checkFormat(context),
115
+ ...checkLocalWorkspace(context),
116
+ ...checkOutsideWorktrees(context),
117
+ ...checkProfile(context),
118
+ ...checkStaleLocal(context),
104
119
  ];
105
120
  };
@@ -25,7 +25,7 @@ const REQUIREMENTS = /^## (Requirements|Prerequisites)\b/m;
25
25
  const FRONTMATTER = /^---\n([\s\S]*?)\n---\n/;
26
26
 
27
27
  const filesOf = (opts: { directory: string }): string[] =>
28
- readdirSync(opts.directory).flatMap(name => {
28
+ readdirSync(opts.directory).flatMap((name) => {
29
29
  const path = join(opts.directory, name);
30
30
 
31
31
  return statSync(path).isDirectory() ? filesOf({ directory: path }) : [path];
@@ -78,12 +78,12 @@ export const lintSkill = (opts: { directory: string }): string[] => {
78
78
  const files = filesOf({ directory: opts.directory }).sort();
79
79
  const shown = (path: string): string => relative(opts.directory, path);
80
80
 
81
- for (const file of files.filter(path => path.endsWith('.md'))) {
81
+ for (const file of files.filter((path) => path.endsWith('.md'))) {
82
82
  const content = readFileSync(file, 'utf8');
83
83
  const count = lineCountOf({ text: content });
84
84
  const opening = content.split('\n').slice(0, CONTENTS_WITHIN_LINES);
85
85
 
86
- if (count > CONTENTS_AFTER_LINES && !opening.some(line => CONTENTS_MARK.test(line))) {
86
+ if (count > CONTENTS_AFTER_LINES && !opening.some((line) => CONTENTS_MARK.test(line))) {
87
87
  problems.push(
88
88
  `${shown(file)}: ${count} lines and no contents list in its first ${CONTENTS_WITHIN_LINES} lines - an agent may read only the first lines`,
89
89
  );
@@ -104,7 +104,7 @@ export const lintSkill = (opts: { directory: string }): string[] => {
104
104
  }
105
105
  }
106
106
 
107
- if (files.some(path => SCRIPT.test(path)) && !REQUIREMENTS.test(text)) {
107
+ if (files.some((path) => SCRIPT.test(path)) && !REQUIREMENTS.test(text)) {
108
108
  problems.push(
109
109
  'SKILL.md: the skill runs scripts and has no ## Requirements section - name what they need',
110
110
  );
@@ -122,14 +122,14 @@ export const checkSkillLint = (opts: ICheckContext): IViolation[] => {
122
122
  }
123
123
 
124
124
  return readdirSync(skills)
125
- .filter(name => statSync(join(skills, name)).isDirectory())
125
+ .filter((name) => statSync(join(skills, name)).isDirectory())
126
126
  .sort()
127
- .flatMap(name => {
127
+ .flatMap((name) => {
128
128
  const directory = join(skills, name);
129
129
  const file = `.agents/skills/${name}`;
130
130
 
131
131
  if (!existsSync(join(directory, 'SKILL.md'))) {
132
- const inner = readdirSync(directory).find(child =>
132
+ const inner = readdirSync(directory).find((child) =>
133
133
  existsSync(join(directory, child, 'SKILL.md')),
134
134
  );
135
135
 
@@ -144,7 +144,7 @@ export const checkSkillLint = (opts: ICheckContext): IViolation[] => {
144
144
  ];
145
145
  }
146
146
 
147
- return lintSkill({ directory }).map(message => ({
147
+ return lintSkill({ directory }).map((message) => ({
148
148
  check: DoctorChecks.SKILLS,
149
149
  file,
150
150
  message,
@@ -12,7 +12,7 @@ const tagPatternOf = (opts: { template: string }): RegExp =>
12
12
  new RegExp(
13
13
  `^${opts.template
14
14
  .split(/(<(?:dir|package|version|date)>)/)
15
- .map(part => {
15
+ .map((part) => {
16
16
  switch (part) {
17
17
  case '<dir>':
18
18
  case '<package>': {
@@ -55,15 +55,15 @@ export const checkTags = (opts: ICheckContext): IViolation[] => {
55
55
  }
56
56
 
57
57
  const pattern = tagPatternOf({ template });
58
- const ignored = (opts.config.atlas.ignoreTags ?? []).map(glob => new Bun.Glob(glob));
58
+ const ignored = (opts.config.atlas.ignoreTags ?? []).map((glob) => new Bun.Glob(glob));
59
59
  const names = new Set(
60
- resolvePackages({ config: opts.config }).flatMap(entry => [entry.dir, ...entry.aliases]),
60
+ resolvePackages({ config: opts.config }).flatMap((entry) => [entry.dir, ...entry.aliases]),
61
61
  );
62
62
 
63
63
  return listed.stdout
64
64
  .split('\n')
65
- .filter(tag => tag.length > 0 && !ignored.some(glob => glob.match(tag)))
66
- .flatMap(tag => {
65
+ .filter((tag) => tag.length > 0 && !ignored.some((glob) => glob.match(tag)))
66
+ .flatMap((tag) => {
67
67
  const dir = pattern.exec(tag)?.groups?.dir;
68
68
 
69
69
  return dir === undefined || names.has(dir)
@@ -12,4 +12,33 @@ export class HookConstants {
12
12
  /** `ask` until the transcript shows the guard does not over-fire; a false positive costs one keystroke. */
13
13
  static readonly GUARD_DECISION = GuardDecisions.ASK;
14
14
  static readonly PRE_TOOL_USE = 'PreToolUse';
15
+ static readonly SUBAGENT_START = 'SubagentStart';
16
+ /** `git` and `gh` queries the guards make; a slow one is dropped and the command passes. */
17
+ static readonly QUERY_TIMEOUT_MS = 5000;
18
+ /** Branches no agent deletes or force-pushes (V-W-06). */
19
+ static readonly PROTECTED_BRANCHES = new Set(['develop', 'main']);
20
+ /** Set to `off` to switch the guards off for a session; the hooks then pass every call. */
21
+ static readonly KILL_SWITCH_ENV = 'VULCAN_GUARDS';
22
+ static readonly KILL_SWITCH_OFF = 'off';
23
+ /**
24
+ * Tool-owned stores an agent may write into: package manager caches, the runtime dir for locks, the
25
+ * agent tool's memory. Never a directory on PATH (`~/.bun/bin`) or a file git or a shell runs (`~/.gitconfig`).
26
+ */
27
+ static readonly TOOL_OWNED_PATHS = [
28
+ '$BUN_INSTALL/install/**',
29
+ '~/.bun/install/**',
30
+ '~/.npm/_cacache/**',
31
+ '~/.npm/_logs/**',
32
+ '~/.pnpm-store/**',
33
+ '~/.local/share/pnpm/store/**',
34
+ '~/.yarn/berry/cache/**',
35
+ '~/.yarn/cache/**',
36
+ '$XDG_RUNTIME_DIR/**',
37
+ '$CLAUDE_CONFIG_DIR/projects/*/memory/**',
38
+ '~/.claude/projects/*/memory/**',
39
+ '/dev/null',
40
+ '/dev/stdout',
41
+ '/dev/stderr',
42
+ '/dev/tty',
43
+ ];
15
44
  }