@venizia/vulcan 0.4.10-2 → 0.4.10-21

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 (208) hide show
  1. package/README.md +30 -23
  2. package/base/checks/wiki-source-links.ts +17 -1
  3. package/base/claude/events.json +1 -11
  4. package/base/claude/settings.json +5 -76
  5. package/base/extensions/vulcan-guards.ts +81 -18
  6. package/base/hooks/guard-git.ts +95 -19
  7. package/base/hooks/guard-outside.ts +163 -43
  8. package/base/hooks/guard-writes.ts +15 -36
  9. package/base/hooks/session-start.ts +1 -1
  10. package/base/make/vulcan.mk +8 -5
  11. package/base/packs/venizia.md +16 -0
  12. package/base/references/delegation-brief.md +3 -5
  13. package/base/references/testing.md +1 -9
  14. package/base/rules.md +33 -38
  15. package/base/skills/build-a-feature/SKILL.md +4 -4
  16. package/base/skills/docs-update/SKILL.md +19 -8
  17. package/base/skills/fix-a-bug/SKILL.md +4 -2
  18. package/base/skills/plan-a-change/SKILL.md +1 -1
  19. package/base/skills/research/SKILL.md +1 -1
  20. package/base/skills/retro/SKILL.md +2 -2
  21. package/base/skills/review-a-change/SKILL.md +1 -1
  22. package/base/skills/visualize-work/SKILL.md +3 -3
  23. package/base/skills/visualize-work/references/spec.md +6 -3
  24. package/base/templates/AGENTS.md +9 -7
  25. package/base/templates/board.html +10 -110
  26. package/package.json +3 -3
  27. package/src/agents/atlas-block.ts +8 -31
  28. package/src/agents/codex-hooks.ts +1 -1
  29. package/src/agents/generated-block.ts +52 -0
  30. package/src/agents/hooks-json.ts +22 -3
  31. package/src/agents/index.ts +2 -0
  32. package/src/agents/render.ts +15 -2
  33. package/src/agents/resolve.ts +1 -0
  34. package/src/agents/rules-block.ts +92 -0
  35. package/src/board/command.ts +92 -30
  36. package/src/board/common/constants.ts +26 -0
  37. package/src/board/common/types.ts +10 -3
  38. package/src/board/fold.ts +1 -1
  39. package/src/board/github.ts +1 -2
  40. package/src/board/gitlab.ts +436 -0
  41. package/src/board/index.ts +1 -0
  42. package/src/board/logo.ts +49 -0
  43. package/src/board/open-file.ts +110 -0
  44. package/src/board/page.ts +57 -5
  45. package/src/board/schema.ts +4 -1
  46. package/src/board/server.ts +87 -3
  47. package/src/board/settings.ts +21 -24
  48. package/src/commands/changelog.command.ts +40 -0
  49. package/src/commands/clean.command.ts +6 -1
  50. package/src/commands/help.command.ts +2 -63
  51. package/src/commands/index.ts +6 -1
  52. package/src/commands/migrate.command.ts +71 -0
  53. package/src/commands/profile.command.ts +1 -1
  54. package/src/commands/runners.command.ts +43 -0
  55. package/src/commands/sync.command.ts +8 -4
  56. package/src/commands/table.ts +362 -0
  57. package/src/commit/check.ts +1 -0
  58. package/src/commit/common/constants.ts +4 -0
  59. package/src/commit/hook.ts +112 -8
  60. package/src/common/constants.ts +11 -9
  61. package/src/common/env-variables.ts +41 -0
  62. package/src/common/index.ts +1 -0
  63. package/src/common/layout-folder.ts +3 -4
  64. package/src/common/record.ts +5 -0
  65. package/src/config/common/constants.ts +28 -22
  66. package/src/config/loader.ts +22 -0
  67. package/src/config/schema.ts +330 -146
  68. package/src/create/add-app.ts +7 -2
  69. package/src/create/add-lib.ts +2 -4
  70. package/src/create/common/constants.ts +5 -3
  71. package/src/create/preset.ts +1 -0
  72. package/src/create/scratch.ts +2 -1
  73. package/src/doctor/checks.ts +277 -448
  74. package/src/doctor/common/constants.ts +27 -19
  75. package/src/doctor/private-values.ts +4 -1
  76. package/src/doctor/runner.ts +5 -12
  77. package/src/doctor/schema.ts +4 -0
  78. package/src/events/common/actor-names.ts +12 -0
  79. package/src/events/common/constants.ts +65 -38
  80. package/src/events/common/index.ts +1 -0
  81. package/src/events/hook.ts +5 -56
  82. package/src/events/text.ts +41 -6
  83. package/src/hooks/command-view.ts +80 -19
  84. package/src/hooks/common/constants.ts +26 -17
  85. package/src/hooks/common/types.ts +13 -24
  86. package/src/hooks/decision.ts +30 -12
  87. package/src/hooks/git-queries.ts +113 -0
  88. package/src/hooks/guard-git.ts +76 -24
  89. package/src/hooks/guard-outside.ts +334 -311
  90. package/src/hooks/guard-runner.ts +206 -0
  91. package/src/hooks/guard-writes.ts +87 -184
  92. package/src/hooks/hook-input.ts +57 -0
  93. package/src/hooks/index.ts +3 -6
  94. package/src/hooks/link-makers.ts +315 -0
  95. package/src/hooks/package-runners.ts +268 -0
  96. package/src/hooks/project-guards.ts +81 -44
  97. package/src/hooks/project-tmp.ts +39 -4
  98. package/src/hooks/runner-scan.ts +257 -0
  99. package/src/hooks/script-runners.ts +400 -0
  100. package/src/hooks/session-digest.ts +27 -117
  101. package/src/hooks/shell-folders.ts +760 -0
  102. package/src/hooks/shell-writes.ts +646 -0
  103. package/src/hooks/shell.ts +1421 -194
  104. package/src/hooks/subagent-card.ts +2 -2
  105. package/src/hooks/write-commands.ts +898 -0
  106. package/src/init/scaffold.ts +2 -3
  107. package/src/local/auto-clean.ts +2 -1
  108. package/src/local/browser-socket.ts +33 -0
  109. package/src/local/clean.ts +37 -6
  110. package/src/local/constants.ts +15 -1
  111. package/src/local/index.ts +1 -0
  112. package/src/local/scan.ts +41 -10
  113. package/src/manifest/render.ts +84 -30
  114. package/src/owner/constants.ts +4 -5
  115. package/src/owner/index.ts +0 -2
  116. package/src/owner/profile.ts +1 -0
  117. package/src/owner/schema.ts +51 -27
  118. package/src/owner/survey.ts +0 -3
  119. package/src/owner/view.ts +0 -9
  120. package/src/router.ts +8 -132
  121. package/src/rules/base.ts +12 -7
  122. package/src/rules/index.ts +1 -0
  123. package/src/rules/packs.ts +44 -0
  124. package/src/runners/check.ts +130 -0
  125. package/src/skills/frontmatter.ts +1 -0
  126. package/src/sync/agents-block.ts +104 -0
  127. package/src/sync/base-rules.ts +3 -3
  128. package/src/sync/claude-launch.ts +12 -12
  129. package/src/sync/common/constants.ts +0 -2
  130. package/src/sync/index.ts +1 -1
  131. package/src/sync/local-choice.ts +32 -3
  132. package/src/sync/planner.ts +2 -15
  133. package/src/sync/settings.ts +0 -17
  134. package/src/theme/index.ts +1 -0
  135. package/src/theme/tokens.ts +410 -0
  136. package/src/ui/prompt.ts +1 -0
  137. package/src/visualize/architecture.ts +504 -0
  138. package/src/visualize/assets.ts +41 -30
  139. package/src/visualize/compare-render.ts +22 -24
  140. package/src/visualize/constants.ts +27 -0
  141. package/src/visualize/diagrams.ts +13 -121
  142. package/src/visualize/kinds-render.ts +2 -2
  143. package/src/visualize/kinds-schema.ts +49 -0
  144. package/src/visualize/labels-vi.ts +25 -0
  145. package/src/visualize/labels.ts +2 -0
  146. package/src/visualize/layout.ts +415 -66
  147. package/src/visualize/page.ts +82 -15
  148. package/src/visualize/render.ts +2 -1
  149. package/src/visualize/schema.ts +29 -1
  150. package/src/visualize/sections.ts +78 -9
  151. package/src/visualize/theme.ts +49 -18
  152. package/src/wiki/anchors.ts +1 -0
  153. package/src/wiki/command.ts +10 -3
  154. package/src/wiki/source-links.ts +57 -18
  155. package/base/ci-global.json +0 -13
  156. package/base/claude/remote-hosts.json +0 -15
  157. package/base/hooks/guard-manifest.ts +0 -27
  158. package/base/hooks/guard-package.ts +0 -30
  159. package/base/hooks/guard-remote-hosts.ts +0 -70
  160. package/base/hooks/guard-scripting.ts +0 -32
  161. package/base/hooks/post-tool.ts +0 -37
  162. package/base/hooks/prompt-submit.ts +0 -54
  163. package/base/hooks/stop.ts +0 -40
  164. package/base/skills/build-a-feature/evals/evals.json +0 -29
  165. package/base/skills/docs-update/evals/evals.json +0 -23
  166. package/base/skills/docs-writing/evals/evals.json +0 -17
  167. package/base/skills/fix-a-bug/evals/evals.json +0 -17
  168. package/base/skills/knowledge-sync/SKILL.md +0 -81
  169. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
  170. package/base/skills/knowledge-sync/references/workflow.md +0 -44
  171. package/base/skills/plan-a-change/evals/evals.json +0 -47
  172. package/base/skills/report-back/evals/evals.json +0 -23
  173. package/base/skills/research/evals/evals.json +0 -17
  174. package/base/skills/retro/evals/evals.json +0 -17
  175. package/base/skills/review-a-change/evals/evals.json +0 -17
  176. package/base/skills/ship/evals/evals.json +0 -23
  177. package/base/skills/visualize-work/evals/evals.json +0 -17
  178. package/base/templates/ci/github-actions.yml +0 -75
  179. package/base/templates/ci/gitlab-ci.yml +0 -52
  180. package/base/templates/trusted-hosts.local.example +0 -11
  181. package/src/ci/affected.ts +0 -176
  182. package/src/ci/command.ts +0 -166
  183. package/src/ci/common/constants.ts +0 -76
  184. package/src/ci/common/index.ts +0 -2
  185. package/src/ci/common/types.ts +0 -37
  186. package/src/ci/git.ts +0 -72
  187. package/src/ci/global.ts +0 -48
  188. package/src/ci/graph.ts +0 -43
  189. package/src/ci/index.ts +0 -7
  190. package/src/ci/workspace.ts +0 -119
  191. package/src/commands/ci.command.ts +0 -4
  192. package/src/hooks/guard-manifest.ts +0 -109
  193. package/src/hooks/guard-package.ts +0 -226
  194. package/src/hooks/guard-scripting.ts +0 -36
  195. package/src/hooks/host-pattern.ts +0 -17
  196. package/src/hooks/owner-reply.ts +0 -162
  197. package/src/hooks/post-tool.ts +0 -138
  198. package/src/hooks/remote-hosts.ts +0 -1013
  199. package/src/hooks/trusted-scripts.ts +0 -212
  200. package/src/owner/shape.ts +0 -496
  201. package/src/owner/violations.ts +0 -332
  202. package/src/signals/claims.ts +0 -73
  203. package/src/signals/classify.ts +0 -137
  204. package/src/signals/constants.ts +0 -88
  205. package/src/signals/index.ts +0 -5
  206. package/src/signals/loop.ts +0 -48
  207. package/src/signals/state.ts +0 -271
  208. package/src/sync/atlas-block.ts +0 -56
@@ -4,41 +4,39 @@ import {
4
4
  accessSync,
5
5
  constants,
6
6
  existsSync,
7
- lstatSync,
8
7
  readdirSync,
9
8
  readFileSync,
10
9
  realpathSync,
11
10
  statSync,
12
11
  } from 'node:fs';
13
- import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
12
+ import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
14
13
  import { BASE_DIRECTORY, ProjectLayout, RecordValue } from '../common/index.ts';
15
14
  import { LayoutKeys, LayoutFolder } from '../common/layout-folder.ts';
16
15
  import { MCP_SERVER_HINT, ProjectScaffold } from '../init/index.ts';
17
16
  import { ProjectPackages } from '../config/index.ts';
18
17
  import { ProjectKey } from '../events/project-key.ts';
19
18
  import type { TResolvedConfig } from '../config/index.ts';
20
- import { BaseRules, RuleParser, RuleSlots } from '../rules/index.ts';
19
+ import { BaseRules, RulePacks, RuleParser, RuleSlots } from '../rules/index.ts';
21
20
  import { ManifestConstants, ProjectManifest } from '../manifest/index.ts';
22
21
  import { AgentScopes, AgentSelection, AgentTable, LocalChoice } from '../agents/index.ts';
23
22
  import { CommitHook, CommitHookStates } from '../commit/index.ts';
24
23
  import { EventConstants } from '../events/common/index.ts';
25
24
  import { EventRetention } from '../events/retention.ts';
26
25
  import { EventSettings } from '../events/settings.ts';
27
- import { AgentFiles, AtlasBlockPlan, LocalPlan, SyncPlanner, SyncStatuses } from '../sync/index.ts';
28
- import { LocalConstants, LocalFormat, LocalScan, LocalStates } from '../local/index.ts';
29
- import { CLAUDE_LAUNCH_FILE, ClaudeLaunch } from '../sync/claude-launch.ts';
30
- import { PrivateValues } from './private-values.ts';
31
26
  import {
32
- ReplySwitch,
33
- OwnerConstants,
34
- OwnerReplySwitch,
35
- OwnerProfile,
36
- ViolationLog,
37
- ViolationConstants,
38
- } from '../owner/index.ts';
39
- import { SkillCatalog } from '@venizia/vulcan-atlas';
40
- import { ScriptTrust, TrustStates } from '../hooks/index.ts';
41
- import { AppScripts, DoctorChecks, DoctorConstants } from './common/index.ts';
27
+ AgentFiles,
28
+ AgentsBlockPlan,
29
+ LocalPlan,
30
+ SyncPlanner,
31
+ SyncStatuses,
32
+ } from '../sync/index.ts';
33
+ import { BrowserSocket, LocalFormat, LocalScan, LocalStates } from '../local/index.ts';
34
+ import { CLAUDE_LAUNCH_FILE } from '../sync/claude-launch.ts';
35
+ import { PrivateValues } from './private-values.ts';
36
+ import { ReplySwitch, OwnerConstants, OwnerReplySwitch, OwnerProfile } from '../owner/index.ts';
37
+ import { SkillCatalog, VersionFolders } from '@venizia/vulcan-atlas';
38
+ import { HookConstants, ProjectTmp } from '../hooks/index.ts';
39
+ import { DoctorChecks, DoctorConstants, PrivateValueKinds } from './common/index.ts';
42
40
  import type { IViolation, TDoctorCheck } from './common/index.ts';
43
41
  import { Makefile } from './makefile.ts';
44
42
 
@@ -132,7 +130,9 @@ const readScriptNames = (opts: { file: string }): string[] | undefined => {
132
130
  }
133
131
  };
134
132
 
135
- const CANONICAL_ATLAS_ARGS = ['x', '--no-install', 'vulcan', 'x', 'atlas', 'mcp', '--root', '.'];
133
+ const CANONICAL_ATLAS_ARGS = ['node_modules/.bin/vulcan', 'x', 'atlas', 'mcp', '--root', '.'];
134
+ /** What sync wrote before V-S-08: it can run a copy bunx cached, so it is stale and not merely different. */
135
+ const LEGACY_ATLAS_ARGS = ['x', '--no-install', 'vulcan', 'x', 'atlas', 'mcp', '--root', '.'];
136
136
 
137
137
  const MCP_FILE = '.mcp.json';
138
138
 
@@ -166,37 +166,6 @@ const isUntrackedAndVisible = (opts: { root: string; path: string }): boolean =>
166
166
  const mcpWarning = (opts: { file: string; message: string }): IViolation =>
167
167
  createViolation({ check: DoctorChecks.MCP, file: opts.file, message: opts.message });
168
168
 
169
- const DOCKERFILE = '.configs/builders/Dockerfile';
170
-
171
- const SECRET_LINES = ['**/.env', '**/.env.*', '!**/.env.example'];
172
-
173
- const ADD_SECRET_LINES = `add ${SECRET_LINES[0]}, ${SECRET_LINES[1]} and ${SECRET_LINES[2]} (in that order) to the root .dockerignore`;
174
-
175
- /** Whether a `.dockerignore` pattern, as Docker reads it, names the file `opts.file` at any depth. */
176
- const patternNames = (opts: { pattern: string; file: string }): boolean => {
177
- const bare = opts.pattern.replace(/^\*\*\//, '').replace(/^\//, '');
178
-
179
- return (
180
- bare === opts.file ||
181
- (bare.endsWith('*') && opts.file.startsWith(bare.slice(0, -1)) && bare.startsWith('.env'))
182
- );
183
- };
184
-
185
- /** Whether the last pattern that names `opts.file` excludes it: a later `!` line brings it back. */
186
- const excludes = (opts: { lines: string[]; file: string }): boolean => {
187
- let excluded = false;
188
-
189
- for (const line of opts.lines) {
190
- const negated = line.startsWith('!');
191
-
192
- if (patternNames({ pattern: negated ? line.slice(1) : line, file: opts.file })) {
193
- excluded = !negated;
194
- }
195
- }
196
-
197
- return excluded;
198
- };
199
-
200
169
  const FMT_SECTION_ADVICE =
201
170
  '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';
202
171
 
@@ -219,23 +188,6 @@ const formatOwners = (opts: ICheckContext): string[] => [
219
188
  ]),
220
189
  ];
221
190
 
222
- /** 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. */
223
- const STALE_TRUST_STATES = new Set<string>([
224
- TrustStates.MISSING,
225
- TrustStates.UNTRACKED,
226
- TrustStates.UNCOMMITTED,
227
- TrustStates.SYMLINK,
228
- TrustStates.UNKNOWN,
229
- ]);
230
-
231
- /** The path of a `guard.writes.trustedScripts` entry, and the subcommands when it is the object form. */
232
- const trustedScriptOf = (opts: {
233
- entry: TResolvedConfig['guard']['writes']['trustedScripts'][number];
234
- }): { script: string; readOnly: string[] | undefined } =>
235
- typeof opts.entry === 'string'
236
- ? { script: opts.entry, readOnly: undefined }
237
- : { script: opts.entry.script, readOnly: opts.entry.readOnly };
238
-
239
191
  export class ProjectContract {
240
192
  static checkLayout(opts: ICheckContext): IViolation[] {
241
193
  return ['AGENTS.md', '.agents/rules.md', opts.config.knowledge.bundle]
@@ -254,19 +206,24 @@ export class ProjectContract {
254
206
  * rules points at a base rule - one the base does not carry dangles.
255
207
  */
256
208
  static checkRuleIds(opts: ICheckContext): IViolation[] {
257
- const base = BaseRules.read();
209
+ const base = BaseRules.read({ packs: opts.config.packs });
258
210
 
259
211
  return RuleParser.parseBaseReferences({
260
212
  markdown: readText({ file: join(opts.root, '.agents', 'rules.md') }),
261
213
  })
262
214
  .filter((id) => base[id] === undefined)
263
- .map((id) =>
264
- createViolation({
215
+ .map((id) => {
216
+ const pack = RulePacks.holderOf({ id });
217
+
218
+ return createViolation({
265
219
  check: DoctorChecks.RULE_IDS,
266
220
  file: '.agents/rules.md',
267
- message: `${id} is not a base rule - give the extension a bare ID`,
268
- }),
269
- );
221
+ message:
222
+ pack === undefined
223
+ ? `${id} is not a base rule - give the extension a bare ID`
224
+ : `${id} is in the ${pack} pack - add '${pack}' to packs in the config`,
225
+ });
226
+ });
270
227
  }
271
228
 
272
229
  static checkRuleSlots(opts: ICheckContext): IViolation[] {
@@ -367,18 +324,6 @@ export class ProjectContract {
367
324
  return violations;
368
325
  }
369
326
 
370
- static checkHooks(opts: ICheckContext): IViolation[] {
371
- return opts.config.hooks
372
- .filter((hook) => hook.command.includes(DoctorConstants.SHIPPED_HOOKS_PATH))
373
- .map((hook) =>
374
- createViolation({
375
- check: DoctorChecks.HOOKS,
376
- file: opts.configFile,
377
- message: `the ${hook.event} hook runs a shipped hook - sync registers those, never the project`,
378
- }),
379
- );
380
- }
381
-
382
327
  static checkAdapters(opts: ICheckContext): IViolation[] {
383
328
  const pending = SyncPlanner.plan({
384
329
  root: opts.root,
@@ -442,6 +387,59 @@ export class ProjectContract {
442
387
  ];
443
388
  }
444
389
 
390
+ /**
391
+ * The changelog folders `changelogs/<X.Y.Z>/` are read by the atlas of VULCAN `CHANGELOG_FOLDERS_FROM` and later;
392
+ * an older one ignores them and answers with no changelog at all. A project that holds a folder with a `log.md`
393
+ * and has an older vulcan installed is told which to install. The version is compared whole: a prerelease of
394
+ * the line before the one that carries the reader still ignores the folders.
395
+ */
396
+ static checkChangelogFolders(opts: ICheckContext): IViolation[] {
397
+ const { changelogs } = opts.config.knowledge;
398
+
399
+ if (changelogs === undefined) {
400
+ return [];
401
+ }
402
+
403
+ const directory = resolve(opts.root, changelogs);
404
+ const hasFolder =
405
+ existsSync(directory) &&
406
+ readdirSync(directory).some(
407
+ (name) => VersionFolders.isName({ name }) && existsSync(join(directory, name, 'log.md')),
408
+ );
409
+ const installedAt = join(opts.root, 'node_modules', '@venizia', 'vulcan');
410
+ const installed = readJsonObject({ file: join(installedAt, 'package.json') })?.['version'];
411
+
412
+ if (!hasFolder || typeof installed !== 'string') {
413
+ return [];
414
+ }
415
+
416
+ // VULCAN's own repository links its workspace package there: that is the source of this project, not an older release.
417
+ try {
418
+ const real = realpathSync(installedAt);
419
+ const fromRoot = relative(realpathSync(opts.root), real);
420
+
421
+ if (
422
+ !isAbsolute(fromRoot) &&
423
+ !fromRoot.startsWith('..') &&
424
+ !fromRoot.split(sep).includes('node_modules')
425
+ ) {
426
+ return [];
427
+ }
428
+ } catch {
429
+ // A link that does not resolve is judged by the version it names.
430
+ }
431
+
432
+ return Bun.semver.order(installed, DoctorConstants.CHANGELOG_FOLDERS_FROM) >= 0
433
+ ? []
434
+ : [
435
+ createViolation({
436
+ check: DoctorChecks.CHANGELOG_FOLDERS,
437
+ file: changelogs,
438
+ message: `holds version folders, but the installed @venizia/vulcan is ${installed}: its atlas ignores them. Install ${DoctorConstants.CHANGELOG_FOLDERS_FROM} or later`,
439
+ }),
440
+ ];
441
+ }
442
+
445
443
  /**
446
444
  * D9: the shared coding style - every lint config builds on it, and the package whose `.configs/`
447
445
  * holds the config declares it, or the root does. A project with no lint config declares it at the
@@ -619,58 +617,6 @@ export class ProjectContract {
619
617
  return violations;
620
618
  }
621
619
 
622
- /**
623
- * Info only, never a failure: an app that lacks a standard script or carries a legacy one gets one
624
- * line naming them. Apps are the live packages inside the backend and frontend folders.
625
- */
626
- static checkAppScripts(opts: ICheckContext): IViolation[] {
627
- const layout = opts.config.layout;
628
-
629
- if (layout === undefined) {
630
- return [];
631
- }
632
-
633
- const appFolders = [
634
- ...LayoutFolder.layoutFoldersOf({ value: layout.backend }),
635
- ...LayoutFolder.layoutFoldersOf({ value: layout.frontend }),
636
- ];
637
- const notes: IViolation[] = [];
638
-
639
- for (const entry of ProjectPackages.resolve({ config: opts.config }).filter(
640
- (item) => !item.retired,
641
- )) {
642
- if (!appFolders.some((folder) => entry.path.startsWith(`${folder}/`))) {
643
- continue;
644
- }
645
-
646
- const file = `${entry.path}/package.json`;
647
- const names = readScriptNames({ file: join(opts.root, file) });
648
-
649
- if (names === undefined) {
650
- continue;
651
- }
652
-
653
- const missing = AppScripts.STANDARD.filter((name) => !names.includes(name));
654
- const legacy = AppScripts.LEGACY.filter((name) => names.includes(name));
655
- const parts = [
656
- ...(missing.length === 0 ? [] : [`missing ${missing.join(', ')}`]),
657
- ...(legacy.length === 0 ? [] : [`legacy ${legacy.join(', ')} (use the standard names)`]),
658
- ];
659
-
660
- if (parts.length > 0) {
661
- notes.push(
662
- createViolation({
663
- check: DoctorChecks.SCRIPTS,
664
- file,
665
- message: `app ${entry.dir}: ${parts.join('; ')}`,
666
- }),
667
- );
668
- }
669
- }
670
-
671
- return notes;
672
- }
673
-
674
620
  /** The developer's stored agents must parse and name known agents; a broken file would otherwise hide as a default. */
675
621
  static checkAgents(opts: ICheckContext): IViolation[] {
676
622
  const stored = LocalChoice.read({ root: opts.root });
@@ -717,6 +663,16 @@ export class ProjectContract {
717
663
  ];
718
664
  }
719
665
 
666
+ case CommitHookStates.LEGACY: {
667
+ return [
668
+ createViolation({
669
+ check: DoctorChecks.COMMIT_HOOK,
670
+ file,
671
+ message: `the commit-msg hook is out of date: ${status.note ?? fix}`,
672
+ }),
673
+ ];
674
+ }
675
+
720
676
  case CommitHookStates.UNWIRED: {
721
677
  return [
722
678
  createViolation({
@@ -727,6 +683,16 @@ export class ProjectContract {
727
683
  ];
728
684
  }
729
685
 
686
+ case CommitHookStates.OTHER_PROJECT: {
687
+ return [
688
+ createViolation({
689
+ check: DoctorChecks.COMMIT_HOOK,
690
+ file,
691
+ message: `this project's commit check is not installed: ${status.note ?? fix}`,
692
+ }),
693
+ ];
694
+ }
695
+
730
696
  default: {
731
697
  return [];
732
698
  }
@@ -865,6 +831,17 @@ export class ProjectContract {
865
831
  message: `no server named atlas (found: ${Object.keys(servers).join(', ') || 'none'}): a differently named server is not enabled automatically - use ${MCP_SERVER_HINT}`,
866
832
  }),
867
833
  );
834
+ } else if (
835
+ Array.isArray(args) &&
836
+ args.length === LEGACY_ATLAS_ARGS.length &&
837
+ args.every((arg, index) => arg === LEGACY_ATLAS_ARGS[index])
838
+ ) {
839
+ warnings.push(
840
+ mcpWarning({
841
+ file: MCP_FILE,
842
+ message: `the atlas entry is out of date: it starts the server through bunx, which can run a copy it cached when the bin is not linked there - run '${ProjectLayout.VULCAN_COMMAND} sync' to rewrite it as ${MCP_SERVER_HINT}`,
843
+ }),
844
+ );
868
845
  } else if (!isCanonical) {
869
846
  const shown = JSON.stringify(entry.value)
870
847
  .replace('{"command":', '{ "command": ')
@@ -901,52 +878,6 @@ export class ProjectContract {
901
878
  return warnings;
902
879
  }
903
880
 
904
- /**
905
- * A Dockerfile is built from the project root. Without a root `.dockerignore` the context carries
906
- * node_modules, dist, .git and every `.env` (secrets that would land in an image layer a CI cache
907
- * can keep); with one that does not exclude `.env` and `.env.*` the secrets are still copied.
908
- * A warning, not a violation: the exit code is unchanged, so a project made before this check
909
- * does not start failing.
910
- */
911
- static checkDockerignore(opts: ICheckContext): IViolation[] {
912
- const file = join(opts.root, '.dockerignore');
913
- const lines = existsSync(file)
914
- ? readText({ file })
915
- .split('\n')
916
- .map((line) => line.trim())
917
- .filter((line) => line !== '' && !line.startsWith('#'))
918
- : undefined;
919
-
920
- if (
921
- lines !== undefined &&
922
- excludes({ lines, file: '.env' }) &&
923
- excludes({ lines, file: '.env.production' })
924
- ) {
925
- return [];
926
- }
927
-
928
- const apps = ProjectPackages.resolve({ config: opts.config })
929
- .filter((entry) => !entry.retired && existsSync(join(opts.root, entry.path, DOCKERFILE)))
930
- .map((entry) => entry.dir);
931
-
932
- if (apps.length === 0) {
933
- return [];
934
- }
935
-
936
- const subject = apps.length === 1 ? `app ${apps[0]} has` : `apps ${apps.join(', ')} have`;
937
-
938
- return [
939
- createViolation({
940
- check: DoctorChecks.DOCKERIGNORE,
941
- file: '.dockerignore',
942
- message:
943
- lines === undefined
944
- ? `${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}`
945
- : `${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}`,
946
- }),
947
- ];
948
- }
949
-
950
881
  /**
951
882
  * `bun fmt` reads the `[fmt]` section of `bunfig.toml`; without it, it formats with Bun's defaults
952
883
  * (width 80, double quotes) and rewrites a tree the shared style formatted, and without
@@ -1048,9 +979,9 @@ export class ProjectContract {
1048
979
  return warnings;
1049
980
  }
1050
981
 
1051
- /** Info only: the Atlas block of AGENTS.md is missing or no longer matches the config. */
982
+ /** Info only: the Atlas or rules block of AGENTS.md is missing or no longer matches the config. */
1052
983
  static checkAtlasBlock(opts: ICheckContext): IViolation[] {
1053
- const merged = AtlasBlockPlan.merged({ root: opts.root, config: opts.config });
984
+ const merged = AgentsBlockPlan.merged({ root: opts.root, config: opts.config });
1054
985
 
1055
986
  return merged === undefined || !merged.changed
1056
987
  ? []
@@ -1058,7 +989,7 @@ export class ProjectContract {
1058
989
  createViolation({
1059
990
  check: DoctorChecks.AGENTS,
1060
991
  file: 'AGENTS.md',
1061
- message: `the Atlas block is missing or out of date - run '${ProjectLayout.VULCAN_COMMAND} sync'`,
992
+ message: `the Atlas or rules block of AGENTS.md is missing or out of date - run '${ProjectLayout.VULCAN_COMMAND} sync'`,
1062
993
  }),
1063
994
  ];
1064
995
  }
@@ -1078,54 +1009,16 @@ export class ProjectContract {
1078
1009
 
1079
1010
  /** `.agents/local/` exists with its subdirectories and is gitignored: `sync` does both, so an upgraded project that has not synced yet is told here. */
1080
1011
  static checkLocalWorkspace(opts: ICheckContext): IViolation[] {
1081
- return LocalPlan.planWorkspace({ root: opts.root })
1012
+ return LocalPlan.planWorkspace({
1013
+ root: opts.root,
1014
+ tmp: ProjectTmp.configuredOf({ tmp: opts.config.local.tmp }),
1015
+ })
1082
1016
  .filter((action) => action.status !== SyncStatuses.UNCHANGED)
1083
1017
  .map((action) =>
1084
1018
  createViolation({
1085
1019
  check: DoctorChecks.LOCAL,
1086
1020
  file: relative(opts.root, action.path) || '.',
1087
- message: `${action.note ?? 'out of date'} - run 'bun x --no-install vulcan sync'`,
1088
- }),
1089
- );
1090
- }
1091
-
1092
- /**
1093
- * A worktree of this repository that lives outside it: the repository's own `git worktree list` names it
1094
- * (git metadata is inside the project), and the exact command moves it in. Nothing is moved or removed.
1095
- */
1096
- static checkOutsideWorktrees(opts: ICheckContext): IViolation[] {
1097
- const listed = spawnSync('git', ['worktree', 'list', '--porcelain'], {
1098
- cwd: opts.root,
1099
- encoding: 'utf8',
1100
- timeout: 5000,
1101
- });
1102
-
1103
- if (listed.status !== 0) {
1104
- return [];
1105
- }
1106
-
1107
- const [boundary, ...linked] = listed.stdout
1108
- .split('\n')
1109
- .filter((line) => line.startsWith('worktree '))
1110
- .map((line) => line.slice('worktree '.length));
1111
-
1112
- if (boundary === undefined) {
1113
- return [];
1114
- }
1115
-
1116
- const inside = (path: string): boolean => {
1117
- const real = existsSync(path) ? realpathSync(path) : path;
1118
-
1119
- return real === boundary || real.startsWith(`${boundary}${sep}`);
1120
- };
1121
-
1122
- return linked
1123
- .filter((path) => !inside(path))
1124
- .map((path) =>
1125
- createViolation({
1126
- check: DoctorChecks.LOCAL,
1127
- file: path,
1128
- message: `a git worktree outside the project - move it in: git worktree move '${path}' '${join(boundary, ProjectLayout.LOCAL_DIRECTORY, 'worktrees', basename(path))}'`,
1021
+ message: `${action.note ?? 'out of date'} - run 'bun node_modules/.bin/vulcan sync'`,
1129
1022
  }),
1130
1023
  );
1131
1024
  }
@@ -1177,105 +1070,162 @@ export class ProjectContract {
1177
1070
  }
1178
1071
 
1179
1072
  /**
1180
- * Something directly under `.agents/local/` that is not a folder of the layout, a file VULCAN writes, or a
1181
- * browser's scratch folder. Nothing removes it; the message says where scratch belongs. A warning.
1073
+ * What is directly under `.agents/local/` and is not a folder of the layout, a file VULCAN writes, or a browser's
1074
+ * scratch folder, in one warning: how many, how big, and their names. Nothing removes them.
1182
1075
  */
1183
1076
  static checkUnknownLocal(opts: ICheckContext): IViolation[] {
1184
- return LocalScan.unknown({ root: opts.root }).map((entry) =>
1185
- createViolation({
1186
- check: DoctorChecks.LOCAL,
1187
- file: `${ProjectLayout.LOCAL_DIRECTORY}/${entry.name}`,
1188
- message: `not an entry VULCAN knows (${LocalFormat.formatBytes({ bytes: entry.bytes })}): put scratch in tmp/ and what you want to keep in reports/, what one agent keeps for itself in agents/<name>/; a script the team relies on belongs in the tracked tree (scripts/), where it gets review and history; nothing removes it`,
1189
- }),
1190
- );
1191
- }
1077
+ const unknown = LocalScan.unknown({ root: opts.root });
1192
1078
 
1193
- /** What an agent left under `.agents/local/` that has outlived its use, one line each with the command that clears it. */
1194
- static checkStaleLocal(opts: ICheckContext): IViolation[] {
1195
- return LocalScan.scan({ root: opts.root })
1196
- .filter((entry) =>
1197
- [
1198
- LocalStates.STALE,
1199
- LocalStates.MERGED,
1200
- LocalStates.GONE,
1201
- LocalStates.ORPHAN,
1202
- LocalStates.SHIPPED,
1203
- ].includes(entry.state),
1204
- )
1205
- .map((entry) =>
1206
- createViolation({
1207
- check: DoctorChecks.LOCAL,
1208
- file: `${ProjectLayout.LOCAL_DIRECTORY}/${entry.where}`,
1209
- message: `${entry.state === LocalStates.STALE && entry.note === '' ? `left ${LocalFormat.formatAge({ ageMs: entry.ageMs })} ago` : entry.note} (${LocalFormat.formatBytes({ bytes: entry.bytes })}) - run: vulcan clean --${entry.scope} --yes`,
1210
- }),
1211
- );
1079
+ return unknown.length === 0
1080
+ ? []
1081
+ : [
1082
+ createViolation({
1083
+ check: DoctorChecks.LOCAL,
1084
+ file: ProjectLayout.LOCAL_DIRECTORY,
1085
+ message: `${unknown.length} ${unknown.length === 1 ? 'entry is' : 'entries are'} not ${unknown.length === 1 ? 'one' : 'ones'} VULCAN knows: ${unknown
1086
+ .slice(0, 10)
1087
+ .map((entry) => `${entry.name} (${LocalFormat.formatBytes({ bytes: entry.bytes })})`)
1088
+ .join(
1089
+ ', ',
1090
+ )}${unknown.length > 10 ? `, and ${unknown.length - 10} more` : ''}; put scratch in tmp/ and what you want to keep in reports/, what one agent keeps for itself in agents/<name>/; a script the team relies on belongs in the tracked tree (scripts/), where it gets review and history; nothing removes ${unknown.length === 1 ? 'it' : 'them'}`,
1091
+ }),
1092
+ ];
1212
1093
  }
1213
1094
 
1214
- /** 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. */
1215
- static checkReplyShape(opts: ICheckContext): IViolation[] {
1216
- const { byClass, replies, days } = ViolationLog.readCounts({ root: opts.root });
1095
+ /**
1096
+ * What an agent left under `.agents/local/` that has outlived its use, in one warning: how many in each scope, how
1097
+ * big, and the command that clears them (which, without `--yes`, lists each one).
1098
+ */
1099
+ static checkStaleLocal(opts: ICheckContext): IViolation[] {
1100
+ const stale = LocalScan.scan({ root: opts.root }).filter((entry) =>
1101
+ [
1102
+ LocalStates.STALE,
1103
+ LocalStates.MERGED,
1104
+ LocalStates.GONE,
1105
+ LocalStates.ORPHAN,
1106
+ LocalStates.SHIPPED,
1107
+ ].includes(entry.state),
1108
+ );
1217
1109
 
1218
- if (replies === 0) {
1110
+ if (stale.length === 0) {
1219
1111
  return [];
1220
1112
  }
1221
1113
 
1222
- const parts = [...byClass.entries()]
1223
- .sort((first, second) => second[1] - first[1])
1224
- .map(([name, count]) => `${name} ${count}`);
1114
+ const scopes = [...new Set(stale.map((entry) => entry.scope))];
1115
+ const counts = new Map<string, number>();
1116
+
1117
+ for (const entry of stale) {
1118
+ const group = `${entry.state} in ${entry.scope}`;
1119
+
1120
+ counts.set(group, (counts.get(group) ?? 0) + 1);
1121
+ }
1225
1122
 
1226
- const isFull =
1227
- ViolationLog.violationBytes({ root: opts.root }) > ViolationConstants.LOG_MAX_BYTES;
1123
+ const groups = [...counts.entries()];
1124
+ const bytes = stale.reduce((total, entry) => total + entry.bytes, 0);
1228
1125
 
1229
1126
  return [
1230
- ...(isFull
1231
- ? [
1232
- createViolation({
1233
- check: DoctorChecks.LOCAL,
1234
- file: `${ProjectLayout.LOCAL_DIRECTORY}/${ViolationConstants.LOG_FILE}`,
1235
- 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`,
1236
- }),
1237
- ]
1238
- : []),
1239
1127
  createViolation({
1240
1128
  check: DoctorChecks.LOCAL,
1241
- file: `${ProjectLayout.LOCAL_DIRECTORY}/${ViolationConstants.LOG_FILE}`,
1242
- 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`,
1129
+ file: ProjectLayout.LOCAL_DIRECTORY,
1130
+ message: `${stale.length} ${stale.length === 1 ? 'entry has' : 'entries have'} outlived ${stale.length === 1 ? 'its' : 'their'} use (${LocalFormat.formatBytes({ bytes })}): ${groups.map(([group, count]) => `${count} ${group}`).join(', ')}; run: vulcan clean ${scopes.map((scope) => `--${scope}`).join(' ')} --yes (without --yes it lists each one)`,
1243
1131
  }),
1244
1132
  ];
1245
1133
  }
1246
1134
 
1247
- /** The owner reply shape is off for this shell (`VULCAN_OWNER_REPLY=off`): a session an agent starts sets it, an owner who exported it by mistake sees why nothing is checked; a note, never a failure. */
1135
+ /** The owner cards are off for this shell (`VULCAN_OWNER_REPLY=off`): a session an agent starts sets it, an owner who exported it by mistake sees why the rules carry no shape card; a note, never a failure. */
1248
1136
  static checkOwnerReplySwitch(opts: { env: Record<string, string | undefined> }): IViolation[] {
1249
1137
  return ReplySwitch.isOwnerOff({ env: opts.env })
1250
1138
  ? [
1251
1139
  createViolation({
1252
1140
  check: DoctorChecks.LOCAL,
1253
1141
  file: OwnerReplySwitch.ENV,
1254
- 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`,
1142
+ message: `set to ${OwnerReplySwitch.OFF} in this shell: a session started from here gets no owner shape card and no profile card in its rules. Unset it for a session whose reader is the owner`,
1255
1143
  }),
1256
1144
  ]
1257
1145
  : [];
1258
1146
  }
1259
1147
 
1260
1148
  /**
1261
- * The session running doctor is Claude Code (`CLAUDECODE` is set) and its `CLAUDE_CODE_TMPDIR` is not this project's folder: it was
1262
- * not started with the launch file, so its task output and its MCP servers use `/tmp`. Outside Claude Code doctor cannot know. A note.
1149
+ * What `local.tmp` must hold for `clean` and the hooks to be safe with it, and for a browser to start: it is not a folder
1150
+ * of the `layout` (or inside one) and holds no tracked file, because `clean` removes what is old in it; and its browser
1151
+ * socket path fits, so the key does what it exists for. Each is a failure here, not a surprise later. A project that does
1152
+ * not set the key gets the warning of `checkBrowserSocket`.
1263
1153
  */
1264
- static checkLaunchSettings(opts: {
1265
- root: string;
1266
- env: Record<string, string | undefined>;
1267
- }): IViolation[] {
1268
- const tmp = ClaudeLaunch.tmpOf(opts);
1154
+ static checkTmpFolder(opts: ICheckContext): IViolation[] {
1155
+ const { tmp } = opts.config.local;
1269
1156
 
1270
- return opts.env.CLAUDECODE !== undefined && tmp.state !== 'inside'
1271
- ? [
1272
- createViolation({
1273
- check: DoctorChecks.LOCAL,
1274
- file: CLAUDE_LAUNCH_FILE,
1275
- message: `this Claude Code session was not started with the launch file, so its task output and its MCP servers use ${tmp.folder ?? '/tmp'}. Start it with: ${ClaudeLaunch.COMMAND}`,
1276
- }),
1277
- ]
1278
- : [];
1157
+ if (tmp === undefined) {
1158
+ return [];
1159
+ }
1160
+
1161
+ const folder = ProjectTmp.projectOf({ root: resolve(opts.root), tmp });
1162
+ const layoutFolders = Object.values(opts.config.layout ?? {}).flatMap((value) =>
1163
+ LayoutFolder.layoutFoldersOf({ value }),
1164
+ );
1165
+ const clash = layoutFolders.find(
1166
+ (entry) => entry === tmp || entry.startsWith(`${tmp}/`) || tmp.startsWith(`${entry}/`),
1167
+ );
1168
+ const tracked = spawnSync('git', ['ls-files', '--', tmp], {
1169
+ cwd: opts.root,
1170
+ encoding: 'utf8',
1171
+ timeout: 5000,
1172
+ });
1173
+ const hasTracked = tracked.status === 0 && tracked.stdout.trim() !== '';
1174
+ const length = BrowserSocket.lengthOf({ folder });
1175
+ const problems = [
1176
+ ...(clash === undefined
1177
+ ? []
1178
+ : [`it is, or holds, the layout folder '${clash}': \`clean\` removes old files from it`]),
1179
+ ...(hasTracked
1180
+ ? [
1181
+ `git tracks files in it: \`clean\` removes old files from it. Pick a folder that only holds scratch`,
1182
+ ]
1183
+ : []),
1184
+ ...(BrowserSocket.fits({ folder })
1185
+ ? []
1186
+ : [
1187
+ `its socket path for a browser would be ${length} characters in ${folder} and the limit is ${BrowserSocket.PATH_MAX}. Use a shorter folder name or a shorter checkout path`,
1188
+ ]),
1189
+ ];
1190
+
1191
+ return problems.map((problem) =>
1192
+ createViolation({
1193
+ check: DoctorChecks.LOCAL,
1194
+ file: opts.configFile,
1195
+ message: `local.tmp '${tmp}': ${problem}`,
1196
+ }),
1197
+ );
1198
+ }
1199
+
1200
+ /**
1201
+ * The project's tmp folder is too deep for a browser: Chrome and Chromium put a socket below the temp folder
1202
+ * and exit with "Socket path too long" past the limit of a unix socket path (`BrowserSocket.PATH_MAX`, the Linux
1203
+ * value; macOS allows 104). The launch file points a session's `TMPDIR` at that folder, so a browser it starts
1204
+ * (Playwright MCP, a headless Chrome) fails; a project with no launch file is not asked. A warning, because only a
1205
+ * project that starts a browser meets it; the way out is a shorter checkout path. The root is made absolute first.
1206
+ */
1207
+ static checkBrowserSocket(opts: { root: string; tmp?: string }): IViolation[] {
1208
+ if (opts.tmp !== undefined) {
1209
+ return [];
1210
+ }
1211
+
1212
+ const root = resolve(opts.root);
1213
+ const folder = ProjectTmp.projectOf({ root, tmp: HookConstants.PROJECT_TMP });
1214
+ const length = BrowserSocket.lengthOf({ folder });
1215
+
1216
+ if (BrowserSocket.fits({ folder }) || !existsSync(join(root, CLAUDE_LAUNCH_FILE))) {
1217
+ return [];
1218
+ }
1219
+
1220
+ const spare = BrowserSocket.PATH_MAX - (length - root.length);
1221
+
1222
+ return [
1223
+ createViolation({
1224
+ check: DoctorChecks.LOCAL,
1225
+ file: CLAUDE_LAUNCH_FILE,
1226
+ message: `the temp folder ${folder} is too deep for a browser: Chrome's socket path would be ${length} characters (${BrowserSocket.longest()} below it) and the limit is ${BrowserSocket.PATH_MAX}, so a browser started with this folder exits with "${BrowserSocket.ERROR}". Set \`local.tmp\` in the config to a short folder of the project (for example \`tmp\`) and run \`vulcan sync\`, or move the checkout to a path of ${spare} characters or fewer`,
1227
+ }),
1228
+ ];
1279
1229
  }
1280
1230
 
1281
1231
  /**
@@ -1294,7 +1244,7 @@ export class ProjectContract {
1294
1244
  : [];
1295
1245
  }
1296
1246
 
1297
- /** 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. */
1247
+ /** A Claude Code settings file of the project sets `VULCAN_OWNER_REPLY=off` in `env`: every session of the project then gets no owner shape card. A warning, never a failure. */
1298
1248
  static checkOwnerReplySettings(opts: { root: string }): IViolation[] {
1299
1249
  return ['.claude/settings.json', '.claude/settings.local.json'].flatMap((file) => {
1300
1250
  const env = readJsonObject({ file: join(opts.root, file) })?.['env'];
@@ -1306,44 +1256,7 @@ export class ProjectContract {
1306
1256
  createViolation({
1307
1257
  check: DoctorChecks.LOCAL,
1308
1258
  file,
1309
- 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`,
1310
- }),
1311
- ]
1312
- : [];
1313
- });
1314
- }
1315
-
1316
- /** One line per script in `guard.writes.trustedScripts` with what git says about it now (a note). */
1317
- static checkTrustedScripts(opts: ICheckContext): IViolation[] {
1318
- return opts.config.guard.writes.trustedScripts.map((entry) => {
1319
- const { script, readOnly } = trustedScriptOf({ entry });
1320
- const trust = ScriptTrust.trustOf({ root: opts.root, script });
1321
- const scope = readOnly === undefined ? 'mutating calls' : `the calls ${readOnly.join(', ')}`;
1322
-
1323
- return createViolation({
1324
- check: DoctorChecks.GUARDS,
1325
- file: script,
1326
- message:
1327
- trust.state === TrustStates.TRUSTED
1328
- ? `guard-writes does not read this script for ${scope} (guard.writes.trustedScripts); it is ` +
1329
- trust.reason
1330
- : `listed in guard.writes.trustedScripts, but guard-writes reads it like any script now: ${trust.reason}`,
1331
- });
1332
- });
1333
- }
1334
-
1335
- /** A listed script that does not exist or is not committed: the exemption never applies (a warning). */
1336
- static checkStaleTrustedScripts(opts: ICheckContext): IViolation[] {
1337
- return opts.config.guard.writes.trustedScripts.flatMap((entry) => {
1338
- const { script } = trustedScriptOf({ entry });
1339
- const trust = ScriptTrust.trustOf({ root: opts.root, script });
1340
-
1341
- return STALE_TRUST_STATES.has(trust.state)
1342
- ? [
1343
- createViolation({
1344
- check: DoctorChecks.GUARDS,
1345
- file: script,
1346
- message: `guard.writes.trustedScripts lists it, but it never takes effect: ${trust.reason}; fix the path, or commit the script`,
1259
+ message: `env sets ${OwnerReplySwitch.ENV}=${OwnerReplySwitch.OFF}: every session of this project gets no owner shape card and no profile card. Remove it and set the variable on the command that starts a session whose reader is an agent`,
1347
1260
  }),
1348
1261
  ]
1349
1262
  : [];
@@ -1351,51 +1264,45 @@ export class ProjectContract {
1351
1264
  }
1352
1265
 
1353
1266
  /**
1354
- * The commands and push targets the project adds to guard-writes and guard-git, one note each: so the
1355
- * guards' reach beyond their own list is visible where a person looks, with the rule and the pattern.
1267
+ * Private values in committed files, never the text: one warning per file that holds a key, a token or a URL
1268
+ * credential, with the kinds and counts; the files that hold only addresses or machine paths (an example IP in a
1269
+ * policy file, a path in a doc) in one warning; and one per acknowledgment that covered nothing.
1356
1270
  */
1357
- static checkGuardPatterns(opts: ICheckContext): IViolation[] {
1358
- const { commands } = opts.config.guard.writes;
1359
- const { askPush } = opts.config.guard.git;
1360
-
1361
- return [
1362
- ...commands.map((command) =>
1363
- createViolation({
1364
- check: DoctorChecks.GUARDS,
1365
- file: opts.configFile,
1366
- message: `guard.writes.commands: ${command.rule} '${command.what}' asks when a command matches /${command.pattern}/${command.ignoreCase === true ? 'i' : ''}`,
1367
- }),
1368
- ),
1369
- ...(askPush.length === 0
1370
- ? []
1371
- : [
1372
- createViolation({
1373
- check: DoctorChecks.GUARDS,
1374
- file: opts.configFile,
1375
- message: `guard.git.askPush: a plain git push asks for ${askPush.join(', ')}`,
1376
- }),
1377
- ]),
1378
- ];
1379
- }
1380
-
1381
- /** Private values in committed files: one warning per file with the kinds and counts, never the text, and one per acknowledgment that covered nothing. */
1382
1271
  static checkPrivateValues(opts: ICheckContext): IViolation[] {
1383
1272
  const { findings, unmatched } = PrivateValues.scan({
1384
1273
  root: opts.root,
1385
1274
  acknowledged: opts.config.doctor.privateValues.acknowledged,
1386
1275
  });
1387
1276
  const where = 'doctor.privateValues.acknowledged';
1277
+ const kindsOf = (counts: Record<string, number | undefined>): string =>
1278
+ Object.entries(counts)
1279
+ .map(([kind, count]) => `${count} ${kind}`)
1280
+ .join(', ');
1281
+ const isMild = (finding: { counts: Record<string, number | undefined> }): boolean =>
1282
+ Object.keys(finding.counts).every((kind) =>
1283
+ [PrivateValueKinds.IPV4, PrivateValueKinds.MACHINE_PATH].includes(kind),
1284
+ );
1285
+ const mild = findings.filter((finding) => isMild(finding));
1388
1286
 
1389
1287
  return [
1390
- ...findings.map((finding) =>
1391
- createViolation({
1392
- check: DoctorChecks.PRIVATE_VALUES,
1393
- file: finding.file,
1394
- message: `holds private values: ${Object.entries(finding.counts)
1395
- .map(([kind, count]) => `${count} ${kind}`)
1396
- .join(', ')} (not shown); remove them, or record the decision in ${where}`,
1397
- }),
1398
- ),
1288
+ ...findings
1289
+ .filter((finding) => !isMild(finding))
1290
+ .map((finding) =>
1291
+ createViolation({
1292
+ check: DoctorChecks.PRIVATE_VALUES,
1293
+ file: finding.file,
1294
+ message: `holds private values: ${kindsOf(finding.counts)} (not shown); remove them, or record the decision in ${where}`,
1295
+ }),
1296
+ ),
1297
+ ...(mild.length === 0
1298
+ ? []
1299
+ : [
1300
+ createViolation({
1301
+ check: DoctorChecks.PRIVATE_VALUES,
1302
+ file: mild.length === 1 ? mild[0].file : `${mild.length} files`,
1303
+ message: `${mild.length === 1 ? 'holds' : `${mild.length} files hold`} only addresses or machine paths: ${mild.map((finding) => `${finding.file} (${kindsOf(finding.counts)})`).join(', ')} (not shown); remove them, or record the decision in ${where}`,
1304
+ }),
1305
+ ]),
1399
1306
  ...unmatched.map((entry) =>
1400
1307
  createViolation({
1401
1308
  check: DoctorChecks.PRIVATE_VALUES,
@@ -1424,82 +1331,4 @@ export class ProjectContract {
1424
1331
  }),
1425
1332
  ];
1426
1333
  }
1427
-
1428
- /** The size of `.agents/local/` once it is large: where the space went, and the command that gives it back. */
1429
- static checkLocalSize(opts: ICheckContext): IViolation[] {
1430
- const entries = LocalScan.scan({ root: opts.root });
1431
- const total = entries.reduce((sum, entry) => sum + entry.bytes, 0);
1432
-
1433
- if (total < LocalConstants.NOTE_BYTES) {
1434
- return [];
1435
- }
1436
-
1437
- const byScope = new Map<string, number>();
1438
-
1439
- for (const entry of entries) {
1440
- byScope.set(entry.scope, (byScope.get(entry.scope) ?? 0) + entry.bytes);
1441
- }
1442
-
1443
- const parts = [...byScope.entries()]
1444
- .sort((first, second) => second[1] - first[1])
1445
- .map(([scope, bytes]) => `${scope} ${LocalFormat.formatBytes({ bytes })}`);
1446
-
1447
- return [
1448
- createViolation({
1449
- check: DoctorChecks.LOCAL,
1450
- file: ProjectLayout.LOCAL_DIRECTORY,
1451
- message: `holds ${LocalFormat.formatBytes({ bytes: total })} (${parts.join(', ')}); vulcan clean lists what an agent left and --yes removes it`,
1452
- }),
1453
- ];
1454
- }
1455
- }
1456
-
1457
- const QUOTES = ["'", '"', '`'];
1458
-
1459
- /**
1460
- * A subcommand an object entry lists that its script never holds as a quoted string (a note). It reads the
1461
- * text of the file, so it cannot tell a subcommand the script handles another way from a typo.
1462
- */
1463
- export class ReadOnlySubcommandChecks {
1464
- static readonly MAX_SOURCE_BYTES = 1_000_000;
1465
-
1466
- static sourceOf(opts: { path: string }): string | undefined {
1467
- try {
1468
- const stat = lstatSync(opts.path);
1469
-
1470
- return stat.isFile() && stat.size <= ReadOnlySubcommandChecks.MAX_SOURCE_BYTES
1471
- ? readFileSync(opts.path, 'utf8')
1472
- : undefined;
1473
- } catch {
1474
- return undefined;
1475
- }
1476
- }
1477
-
1478
- static check(opts: ICheckContext): IViolation[] {
1479
- return opts.config.guard.writes.trustedScripts.flatMap((entry) => {
1480
- const { script, readOnly } = trustedScriptOf({ entry });
1481
- const path = join(opts.root, script);
1482
-
1483
- if (readOnly === undefined) {
1484
- return [];
1485
- }
1486
-
1487
- // Only a plain, small file inside the repo is read: a link, a folder or a device is skipped, never followed.
1488
- const source = ReadOnlySubcommandChecks.sourceOf({ path });
1489
-
1490
- if (source === undefined) {
1491
- return [];
1492
- }
1493
-
1494
- return readOnly
1495
- .filter((word) => !QUOTES.some((quote) => source.includes(`${quote}${word}${quote}`)))
1496
- .map((word) =>
1497
- createViolation({
1498
- check: DoctorChecks.GUARDS,
1499
- file: script,
1500
- message: `guard.writes.trustedScripts lists the subcommand '${word}' for this script, but the script does not hold it as a quoted string; this is a check of the text of the file, not what the script does`,
1501
- }),
1502
- );
1503
- });
1504
- }
1505
1334
  }