@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
@@ -10,14 +10,13 @@ import type { IInitEntry, IScaffoldFile } from './common/index.ts';
10
10
 
11
11
  /** The atlas entry of the root `.mcp.json`, as `sync` writes it and `doctor` shows it. */
12
12
  export const MCP_SERVER_HINT =
13
- '"atlas": { "command": "bun", "args": ["x", "--no-install", "vulcan", "x", "atlas", "mcp", "--root", "."] }';
13
+ '"atlas": { "command": "bun", "args": ["node_modules/.bin/vulcan", "x", "atlas", "mcp", "--root", "."] }';
14
14
 
15
15
  /** The files every project gets, apart from the config. */
16
16
  const SCAFFOLD_FILES: IScaffoldFile[] = [
17
17
  { path: 'AGENTS.md', template: 'AGENTS.md' },
18
18
  { path: '.agents/rules.md', template: 'rules.md' },
19
19
  { path: '.agents/knowledge/index.md', template: 'knowledge-index.md' },
20
- { path: `${ProjectLayout.TRUSTED_HOSTS_FILE}.example`, template: 'trusted-hosts.local.example' },
21
20
  ];
22
21
 
23
22
  /** The lint configs of a single-package project. A workspaces project keeps them in each app. */
@@ -81,6 +80,7 @@ const writeIfAbsent = (opts: { root: string; path: string; content: string }): I
81
80
  return { status: InitStatuses.CREATED, subject: opts.path };
82
81
  };
83
82
 
83
+ /** Writes the starter files of a project and detects workspace globs and the project name; used by `vulcan init` and the create flows. */
84
84
  export class ProjectScaffold {
85
85
  /** Whether the root `package.json` declares workspaces: the array form or `{ packages: [...] }`. */
86
86
  static declaresWorkspaces(opts: { root: string }): boolean {
@@ -237,7 +237,6 @@ export class ProjectScaffold {
237
237
  const install = needed.filter((packageName) => !(packageName in declared));
238
238
  const todo = [
239
239
  `describe the project in ${ConfigConstants.DEFAULT_KNOWLEDGE_BUNDLE}/index.md, then delete the ${ProjectLayout.SCAFFOLD_MARKER} line`,
240
- `private hosts go in ${ProjectLayout.TRUSTED_HOSTS_FILE} (copy the .example), not in the committed config`,
241
240
  ...(hasEnvRule
242
241
  ? [
243
242
  `.gitignore has .env rules of its own and was left as it is: check that they ignore ${ProjectLayout.SECRET_PATTERNS.join(' ')} the way you want`,
@@ -1,6 +1,7 @@
1
1
  import { spawn } from 'node:child_process';
2
2
  import { existsSync, readFileSync, writeFileSync } from 'node:fs';
3
3
  import { join } from 'node:path';
4
+ import { EnvVariables } from '../common/env-variables.ts';
4
5
  import { BASE_DIRECTORY } from '../common/paths.ts';
5
6
  import { RecordValue } from '../common/record.ts';
6
7
  import { EventLog } from '../events/log.ts';
@@ -23,7 +24,7 @@ export interface IAutoCleanStamp {
23
24
  */
24
25
  export class LocalAutoClean {
25
26
  static readonly STAMP = '.agents/local/auto-clean.json';
26
- static readonly OFF_ENV = 'VULCAN_AUTO_CLEAN';
27
+ static readonly OFF_ENV = EnvVariables.VULCAN_AUTO_CLEAN;
27
28
  static readonly SCRIPT = join('hooks', 'auto-clean.ts');
28
29
 
29
30
  /** On unless the project's manifest says `local.autoClean: false`, or the environment says `VULCAN_AUTO_CLEAN=off`. */
@@ -0,0 +1,33 @@
1
+ import { join } from 'node:path';
2
+
3
+ /**
4
+ * Chrome and Chromium put a unix socket at `<temp folder>/<profile folder>/SingletonSocket` and exit with "Socket path too long"
5
+ * when it passes the limit of a unix socket path. The tests and `vulcan doctor` read this one place.
6
+ */
7
+ export class BrowserSocket {
8
+ /** A unix socket path is 107 characters at most on Linux. */
9
+ static readonly PATH_MAX = 107;
10
+
11
+ /** What a browser prints when the socket path is over the limit. */
12
+ static readonly ERROR = 'Socket path too long';
13
+
14
+ /** What each browser adds below its temp folder; the profile folder is a name and six random characters. */
15
+ static readonly NAMES = [
16
+ join('com.google.Chrome.XXXXXX', 'SingletonSocket'),
17
+ join('org.chromium.Chromium.XXXXXX', 'SingletonSocket'),
18
+ ];
19
+
20
+ /** The longest of `NAMES`: a folder that holds it holds every browser's socket. */
21
+ static longest(): string {
22
+ return BrowserSocket.NAMES.reduce((a, b) => (b.length > a.length ? b : a));
23
+ }
24
+
25
+ /** The length of the longest socket path a browser would make in `folder`. */
26
+ static lengthOf(opts: { folder: string }): number {
27
+ return join(opts.folder, BrowserSocket.longest()).length;
28
+ }
29
+
30
+ static fits(opts: { folder: string }): boolean {
31
+ return BrowserSocket.lengthOf(opts) <= BrowserSocket.PATH_MAX;
32
+ }
33
+ }
@@ -1,9 +1,11 @@
1
1
  import { spawnSync } from 'node:child_process';
2
2
  import { existsSync, lstatSync, rmSync, unlinkSync } from 'node:fs';
3
3
  import { basename, dirname } from 'node:path';
4
+ import { ProjectLayout } from '../common/index.ts';
4
5
  import { EventRetention } from '../events/retention.ts';
5
6
  import { EventSettings } from '../events/settings.ts';
6
- import { CleanScopes, LocalConstants } from './constants.ts';
7
+ import { CleanScopes, LocalConstants, LocalStates } from './constants.ts';
8
+ import { LocalFormat } from './format.ts';
7
9
  import { LocalScan } from './scan.ts';
8
10
  import type { ILocalEntry } from './scan.ts';
9
11
 
@@ -81,12 +83,30 @@ const removeEntry = (opts: { root: string; entry: ILocalEntry }): string | undef
81
83
  }
82
84
  };
83
85
 
86
+ /** Plans and runs the removal of old scratch files under `.agents/local`; used by `vulcan clean` and the automatic clean. */
84
87
  export class LocalClean {
85
- /** What the chosen scopes hold: what `clean` would remove and what it keeps, with the reason. */
86
- static plan(opts: { root: string; scopes: string[]; now?: number }): ICleanPlan {
87
- const inScope = LocalScan.scan({ root: opts.root, now: opts.now }).filter((entry) =>
88
- opts.scopes.includes(entry.scope),
89
- );
88
+ /**
89
+ * What the chosen scopes hold: what `clean` would remove and what it keeps, with the reason. An item of a scope that
90
+ * goes stale (`tmp`, `clones`) that is not stale yet may belong to a live session: it is kept unless `includeFresh`
91
+ * is set. An item a live session always uses (`tmp/claude-*`) is kept whatever the flags.
92
+ */
93
+ static plan(opts: {
94
+ root: string;
95
+ scopes: string[];
96
+ now?: number;
97
+ includeFresh?: boolean;
98
+ }): ICleanPlan {
99
+ const inScope = LocalScan.scan({ root: opts.root, now: opts.now })
100
+ .filter((entry) => opts.scopes.includes(entry.scope))
101
+ .map((entry) =>
102
+ entry.removable && opts.includeFresh !== true && LocalClean.isFresh({ entry })
103
+ ? {
104
+ ...entry,
105
+ removable: false,
106
+ note: `fresh (${LocalFormat.formatAge({ ageMs: entry.ageMs })}): may be in use; --include-fresh removes it`,
107
+ }
108
+ : entry,
109
+ );
90
110
 
91
111
  return {
92
112
  remove: inScope.filter((entry) => entry.removable),
@@ -94,6 +114,17 @@ export class LocalClean {
94
114
  };
95
115
  }
96
116
 
117
+ /** An item of a scope that has a stale age, not past it yet. */
118
+ private static isFresh(opts: { entry: ILocalEntry }): boolean {
119
+ const { entry } = opts;
120
+
121
+ return (
122
+ ProjectLayout.LOCAL_LAYOUT.some(
123
+ (layout) => layout.name === entry.scope && 'staleAfterDays' in layout,
124
+ ) && entry.state !== LocalStates.STALE
125
+ );
126
+ }
127
+
97
128
  /** Removes the plan's entries, then prunes git's worktree list. Returns what went and what failed. */
98
129
  static run(opts: { root: string; plan: ICleanPlan }): {
99
130
  removed: ILocalEntry[];
@@ -57,7 +57,6 @@ export class LocalConstants {
57
57
  static readonly KNOWN_FILES = new Set([
58
58
  'profile.json',
59
59
  'claude.launch.settings.json',
60
- 'violations.jsonl',
61
60
  'auto-clean.json',
62
61
  '.gitkeep',
63
62
  ]);
@@ -84,3 +83,18 @@ export class LocalConstants {
84
83
  /** A stray folder may belong to a browser that is running; one this old does not. */
85
84
  static readonly STRAY_MIN_AGE_MS = 60 * 60 * 1000;
86
85
  }
86
+
87
+ /** What `clean` and the automatic clean never take, because a live session is using it. */
88
+ export class LocalProtected {
89
+ /** Claude Code's folder for the output of its background tasks: `tmp/claude-<uid>`. */
90
+ static readonly CLAUDE_TASKS = /^claude-\d+$/;
91
+
92
+ /** Why the item is never removed, or undefined when it may be. */
93
+ static noteOf(opts: { scope: string; name: string }): string | undefined {
94
+ if (opts.scope === CleanScopes.TMP && LocalProtected.CLAUDE_TASKS.test(opts.name)) {
95
+ return "in use: Claude Code's background task output; never removed";
96
+ }
97
+
98
+ return undefined;
99
+ }
100
+ }
@@ -1,4 +1,5 @@
1
1
  export * from './constants.ts';
2
+ export * from './browser-socket.ts';
2
3
  export * from './scan.ts';
3
4
  export * from './clean.ts';
4
5
  export * from './format.ts';
package/src/local/scan.ts CHANGED
@@ -1,10 +1,11 @@
1
+ import { ProjectTmp } from '../hooks/project-tmp.ts';
1
2
  import { spawnSync } from 'node:child_process';
2
3
  import { existsSync, lstatSync, readdirSync, realpathSync } from 'node:fs';
3
4
  import { join, resolve, sep } from 'node:path';
4
5
  import { ProjectLayout } from '../common/index.ts';
5
6
  import { EventRetention } from '../events/retention.ts';
6
7
  import { EventSettings } from '../events/settings.ts';
7
- import { CleanScopes, LocalConstants, LocalStates } from './constants.ts';
8
+ import { CleanScopes, LocalConstants, LocalProtected, LocalStates } from './constants.ts';
8
9
 
9
10
  /** One thing under `.agents/local/`: a child of one of its directories, or the profile file. */
10
11
  export interface ILocalEntry {
@@ -446,13 +447,18 @@ export class LocalScan {
446
447
  : undefined;
447
448
  const isEventsOutside = !`${eventsDir}${sep}`.startsWith(`${local}${sep}`);
448
449
 
450
+ const homes: Record<string, string> = {
451
+ [CleanScopes.EVENTS]: eventsDir,
452
+ [CleanScopes.TMP]: ProjectTmp.projectOf({ root: opts.root }),
453
+ };
454
+
449
455
  for (const layout of ProjectLayout.LOCAL_LAYOUT) {
450
456
  if (!wants(layout.name)) {
451
457
  continue;
452
458
  }
453
459
 
454
460
  const isEvents = layout.name === CleanScopes.EVENTS;
455
- const directory = isEvents ? eventsDir : join(local, layout.name);
461
+ const directory = homes[layout.name] ?? join(local, layout.name);
456
462
 
457
463
  if (!isRealDirectory({ path: directory })) {
458
464
  continue;
@@ -515,6 +521,13 @@ export class LocalScan {
515
521
  state = LocalStates.STALE;
516
522
  }
517
523
 
524
+ const inUse = LocalProtected.noteOf({ scope: layout.name, name });
525
+
526
+ if (inUse !== undefined) {
527
+ // Not stale either: it is in use, and doctor must not tell anyone to clean what clean never takes.
528
+ ({ state, removable, note } = { state: LocalStates.OK, removable: false, note: inUse });
529
+ }
530
+
518
531
  entries.push({
519
532
  scope: layout.name,
520
533
  name,
@@ -614,21 +627,39 @@ export class LocalScan {
614
627
  * symlink is not followed. A symlinked `.agents` or `.agents/local` makes it false for everything.
615
628
  */
616
629
  static isInside(opts: { root: string; path: string }): boolean {
617
- const local = LocalScan.localRootOf({ root: opts.root });
618
-
619
- if (local === undefined) {
620
- return false;
621
- }
622
-
630
+ const bases = [
631
+ LocalScan.localRootOf({ root: opts.root }),
632
+ LocalScan.tmpRootOf({ root: opts.root }),
633
+ ].filter((base): base is string => base !== undefined);
623
634
  const parent = resolve(opts.path, '..');
624
635
 
625
- if (!existsSync(parent)) {
636
+ if (bases.length === 0 || !existsSync(parent)) {
626
637
  return false;
627
638
  }
628
639
 
629
640
  const target = join(realpathSync(parent), resolve(opts.path).split(sep).at(-1) ?? '');
630
641
 
631
- return target.startsWith(`${local}${sep}`);
642
+ return bases.some((base) => target.startsWith(`${base}${sep}`));
643
+ }
644
+
645
+ /**
646
+ * The project's tmp folder as the disk has it, when it is a real folder (not a link) that sits inside the project, and
647
+ * `clean` may therefore remove from it; undefined when it is missing, a link, or leads out of the project.
648
+ */
649
+ static tmpRootOf(opts: { root: string }): string | undefined {
650
+ const folder = ProjectTmp.projectOf({ root: opts.root });
651
+
652
+ try {
653
+ if (!lstatSync(folder).isDirectory()) {
654
+ return undefined;
655
+ }
656
+
657
+ const real = realpathSync(folder);
658
+
659
+ return `${real}${sep}`.startsWith(`${realpathSync(opts.root)}${sep}`) ? real : undefined;
660
+ } catch {
661
+ return undefined;
662
+ }
632
663
  }
633
664
  }
634
665
 
@@ -1,17 +1,20 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
2
  import { basename, join } from 'node:path';
3
- import { BunFormatter } from '../common/index.ts';
3
+ import { ProviderTypes } from '../board/common/constants.ts';
4
+ import { BunFormatter, EnvVariables } from '../common/index.ts';
4
5
  import { AgentSignaturePolicies } from '../commit/common/index.ts';
5
6
  import { ProjectPackages } from '../config/index.ts';
7
+ import { GuardDecisions } from '../hooks/common/index.ts';
6
8
  import type { TResolvedConfig } from '../config/index.ts';
7
9
  import { BaseRules } from '../rules/index.ts';
10
+ import { ThemeTokens } from '../theme/index.ts';
8
11
 
9
12
  export class ManifestConstants {
10
13
  /** Committed; what atlas reads from a project - local or fetched - and nothing else. */
11
14
  static readonly FILE = '.agents/vulcan.manifest.json';
12
15
  static readonly SCHEMA_VERSION = 1;
13
16
  static readonly PROJECT_RULES = '.agents/rules.md';
14
- static readonly ENV = 'VULCAN_MANIFEST';
17
+ static readonly ENV = EnvVariables.VULCAN_MANIFEST;
15
18
  /** The first key: a reader sees at once that the file is generated. Readers ignore it. */
16
19
  static readonly GENERATED_KEY = '$generated';
17
20
  static readonly GENERATED_NOTE = 'by vulcan sync from .configs/vulcan.config.* - do not edit';
@@ -19,14 +22,16 @@ export class ManifestConstants {
19
22
 
20
23
  const HASH_LENGTH = 8;
21
24
 
22
- /** The manifest's `guard` block: what the project adds to guard-writes and guard-git, as data a hook reads without the config (the read-only script entries of `trustedScripts` included). */
25
+ /**
26
+ * The manifest's `guard` block: what the project sets for the guards, as data a hook reads without the config, so a
27
+ * config this VULCAN cannot parse never changes a guard: `outside` and `asks` (when not the default), `toolOwnedPaths`,
28
+ * the commands of guard-writes, the push targets of guard-git, the runners the runner guard accepts.
29
+ */
23
30
  const guardBlockOf = (opts: { config: TResolvedConfig }): { guard?: Record<string, unknown> } => {
24
- const { commands, trustedScripts } = opts.config.guard.writes;
31
+ const { commands } = opts.config.guard.writes;
25
32
  const { askPush } = opts.config.guard.git;
26
- // Only the object entries: a path string is read from the config by the hook, as before.
27
- const readOnlyScripts = trustedScripts.flatMap((entry) =>
28
- typeof entry === 'string' ? [] : [{ script: entry.script, readOnly: entry.readOnly }],
29
- );
33
+ const { allow } = opts.config.guard.runners;
34
+ const { outside, asks, toolOwnedPaths } = opts.config.guard;
30
35
  const writes = {
31
36
  ...(commands.length === 0
32
37
  ? {}
@@ -38,11 +43,14 @@ const guardBlockOf = (opts: { config: TResolvedConfig }): { guard?: Record<strin
38
43
  ...(command.ignoreCase === true ? { ignoreCase: true } : {}),
39
44
  })),
40
45
  }),
41
- ...(readOnlyScripts.length === 0 ? {} : { readOnlyScripts }),
42
46
  };
43
47
  const block = {
48
+ ...(outside === GuardDecisions.ASK ? {} : { outside }),
49
+ ...(asks === GuardDecisions.ASK ? {} : { asks }),
50
+ ...(toolOwnedPaths.length === 0 ? {} : { toolOwnedPaths }),
44
51
  ...(Object.keys(writes).length === 0 ? {} : { writes }),
45
52
  ...(askPush.length === 0 ? {} : { git: { askPush } }),
53
+ ...(allow.length === 0 ? {} : { runners: { allow } }),
46
54
  };
47
55
 
48
56
  return Object.keys(block).length === 0 ? {} : { guard: block };
@@ -70,13 +78,6 @@ const commitBlockOf = (opts: { config: TResolvedConfig }): { commit?: Record<str
70
78
  };
71
79
  };
72
80
 
73
- /** The manifest's `ci` block, which `vulcan ci affected` reads: only the globs the project adds. */
74
- const ciBlockOf = (opts: { config: TResolvedConfig }): { ci?: Record<string, unknown> } => {
75
- const { global } = opts.config.ci.affected;
76
-
77
- return global.length === 0 ? {} : { ci: { affected: { global } } };
78
- };
79
-
80
81
  /** The manifest's `events` block, which the hooks and `vulcan event` read: only when the log is on or has a folder. */
81
82
  const eventsBlockOf = (opts: { config: TResolvedConfig }): { events?: Record<string, unknown> } => {
82
83
  const { log, dir, maxSize, maxFiles, maxAgeDays } = opts.config.events;
@@ -91,9 +92,45 @@ const eventsBlockOf = (opts: { config: TResolvedConfig }): { events?: Record<str
91
92
  : {};
92
93
  };
93
94
 
94
- /** The manifest's `local` block: only when the project turns the automatic clean off, which the hook reads. */
95
- const localBlockOf = (opts: { config: TResolvedConfig }): { local?: Record<string, unknown> } =>
96
- opts.config.local.autoClean ? {} : { local: { autoClean: false } };
95
+ /** The manifest's `local` block, which the hooks and `vulcan clean` read: when the automatic clean is off or the project names its tmp folder. */
96
+ const localBlockOf = (opts: { config: TResolvedConfig }): { local?: Record<string, unknown> } => {
97
+ const { autoClean, tmp } = opts.config.local;
98
+ const block = {
99
+ ...(autoClean ? {} : { autoClean: false }),
100
+ ...(tmp === undefined ? {} : { tmp }),
101
+ };
102
+
103
+ return Object.keys(block).length === 0 ? {} : { local: block };
104
+ };
105
+
106
+ /**
107
+ * The manifest's `theme` block: the accent seeds the project gave, its preset, and the resolved design tokens (both
108
+ * modes, font, mono, radius) that the board, the pages and the wiki read. Always written: a project with no `theme`
109
+ * gets the default preset. A theme the check refused never reaches here (the config does not load).
110
+ */
111
+ const themeBlockOf = (opts: { config: TResolvedConfig }): { theme?: Record<string, unknown> } => {
112
+ const resolved = ThemeTokens.resolve({ theme: opts.config.theme });
113
+
114
+ if (!resolved.ok) {
115
+ return {};
116
+ }
117
+
118
+ const { preset, light, dark, font, mono, radius } = resolved.tokens;
119
+ const { accent, accentDark, accentText } = opts.config.theme ?? {};
120
+
121
+ return {
122
+ theme: {
123
+ ...(accent === undefined ? {} : { accent }),
124
+ ...(accentDark === undefined ? {} : { accentDark }),
125
+ ...(accentText === undefined ? {} : { accentText }),
126
+ preset,
127
+ tokens: { light, dark },
128
+ font,
129
+ mono,
130
+ radius,
131
+ },
132
+ };
133
+ };
97
134
 
98
135
  /** The manifest's `board` block, which `vulcan board` reads: only what the project sets. */
99
136
  const boardBlockOf = (opts: { config: TResolvedConfig }): { board?: Record<string, unknown> } => {
@@ -116,17 +153,32 @@ const boardBlockOf = (opts: { config: TResolvedConfig }): { board?: Record<strin
116
153
  };
117
154
  };
118
155
 
156
+ /** The manifest's `provider` block, which `vulcan board` reads: written only when the code host is not GitHub. */
157
+ const providerBlockOf = (opts: {
158
+ config: TResolvedConfig;
159
+ }): { provider?: Record<string, unknown> } => {
160
+ const { type, host } = opts.config.provider;
161
+
162
+ return type === ProviderTypes.GITHUB
163
+ ? {}
164
+ : { provider: { type, ...(host === undefined ? {} : { host }) } };
165
+ };
166
+
119
167
  /** The manifest's `atlas` block: only what the config sets (keys listed, the download turned off). */
120
168
  const atlasBlockOf = (opts: { config: TResolvedConfig }): { atlas?: Record<string, unknown> } => {
121
169
  const keys = opts.config.atlas.index?.keys ?? [];
122
170
  const block = {
123
171
  ...(keys.length === 0 ? {} : { index: { keys } }),
124
172
  ...(opts.config.atlas.prebuilt === false ? { prebuilt: false } : {}),
173
+ ...(opts.config.atlas.limits?.download === undefined
174
+ ? {}
175
+ : { limits: { download: opts.config.atlas.limits.download } }),
125
176
  };
126
177
 
127
178
  return Object.keys(block).length === 0 ? {} : { atlas: block };
128
179
  };
129
180
 
181
+ /** Renders `.agents/vulcan.manifest.json` from the config and the base rule hashes; written by `vulcan sync`. */
130
182
  export class ProjectManifest {
131
183
  /** `@acme/shop-workspace` gives `shop`; a project with no package name takes its directory's. */
132
184
  static projectNameOf(opts: { root: string; config: TResolvedConfig }): string {
@@ -147,9 +199,9 @@ export class ProjectManifest {
147
199
  }
148
200
 
149
201
  /** Each base rule's ID with a hash of its row: a sync after an upgrade can say which rules changed. */
150
- static buildBaseRuleHashes(): Record<string, string> {
202
+ static buildBaseRuleHashes(opts: { packs?: string[] } = {}): Record<string, string> {
151
203
  return Object.fromEntries(
152
- Object.entries(BaseRules.read()).map(([id, row]) => {
204
+ Object.entries(BaseRules.read(opts)).map(([id, row]) => {
153
205
  const hash = new Bun.CryptoHasher('sha256').update(row.trim()).digest('hex');
154
206
 
155
207
  return [id, hash.slice(0, HASH_LENGTH)];
@@ -163,7 +215,8 @@ export class ProjectManifest {
163
215
  */
164
216
  static render(opts: { root: string; config: TResolvedConfig }): string {
165
217
  const { config } = opts;
166
- const { wiki, changelogs, syncAreas } = config.knowledge;
218
+ const { wiki, changelogs, migrationFrom, datedUntil, siteUrl, codemodCommand } =
219
+ config.knowledge;
167
220
 
168
221
  const manifest = {
169
222
  [ManifestConstants.GENERATED_KEY]: ManifestConstants.GENERATED_NOTE,
@@ -185,7 +238,10 @@ export class ProjectManifest {
185
238
  bundle: config.knowledge.bundle,
186
239
  ...(wiki === undefined ? {} : { wiki }),
187
240
  ...(changelogs === undefined ? {} : { changelogs }),
188
- ...(syncAreas === undefined ? {} : { syncAreas }),
241
+ migrationFrom,
242
+ ...(datedUntil === undefined ? {} : { datedUntil }),
243
+ ...(siteUrl === undefined ? {} : { siteUrl }),
244
+ ...(codemodCommand === undefined ? {} : { codemodCommand }),
189
245
  },
190
246
  release: {
191
247
  tagPattern: config.atlas.tagPattern,
@@ -197,7 +253,7 @@ export class ProjectManifest {
197
253
  },
198
254
  rules: {
199
255
  project: ManifestConstants.PROJECT_RULES,
200
- base: ProjectManifest.buildBaseRuleHashes(),
256
+ base: ProjectManifest.buildBaseRuleHashes({ packs: config.packs }),
201
257
  },
202
258
  // The sources this project reads knowledge from (atlas, git mode); a project without any carries none.
203
259
  ...(config.atlas.sources.length === 0 ? {} : { sources: config.atlas.sources }),
@@ -205,15 +261,13 @@ export class ProjectManifest {
205
261
  ...atlasBlockOf({ config }),
206
262
  // The commands and push targets the guards ask about beyond their own list; neither set, nothing is written.
207
263
  ...guardBlockOf({ config }),
208
- // The remote-host guard reads its policy here; a project without the key has no guard.
209
- ...(config.remoteHosts === undefined ? {} : { remoteHosts: config.remoteHosts }),
210
- // The colour `vulcan visualize` takes for its pages; a project without the key gets the neutral default.
211
- ...(config.theme === undefined ? {} : { theme: config.theme }),
264
+ // The design tokens: the preset, the seeds the project gave and the resolved set every consumer reads.
265
+ ...themeBlockOf({ config }),
212
266
  ...commitBlockOf({ config }),
213
- // The files the project adds to the ones that make every package affected; none added, nothing is written.
214
- ...ciBlockOf({ config }),
215
267
  // The names and the logo `vulcan board` puts on its page; nothing set, nothing is written.
216
268
  ...boardBlockOf({ config }),
269
+ // The code host the board reads; GitHub, the default, writes nothing.
270
+ ...providerBlockOf({ config }),
217
271
  // The automatic clean of .agents/local is on unless the project turns it off here.
218
272
  ...localBlockOf({ config }),
219
273
  // Whether the Claude Code hooks write the agent event log, and the folder it goes to.
@@ -1,3 +1,5 @@
1
+ import { EnvVariables } from '../common/env-variables.ts';
2
+
1
3
  /** The sections of a reply to the owner; a project picks which appear and in what order. */
2
4
  export class OwnerSections {
3
5
  static readonly HEADLINE = 'headline';
@@ -17,7 +19,7 @@ export class OwnerSections {
17
19
  }
18
20
  }
19
21
 
20
- /** How hard the shape of an owner reply is held: not at all, by a reminder, or by blocking a wrong one once. */
22
+ /** Whether the shape card is shown: `off` leaves it out, `advise` and `block` show it. The stricter of two values wins. */
21
23
  export class OwnerEnforcement {
22
24
  static readonly OFF = 'off';
23
25
  static readonly ADVISE = 'advise';
@@ -93,9 +95,6 @@ export class OwnerConstants {
93
95
  },
94
96
  };
95
97
  static readonly DEFAULT_HEADLINE_MAX_SENTENCES = 2;
96
- /** A reply shorter than this many words (an acknowledgement) is exempt from the shape; 0 checks every reply. */
97
- static readonly DEFAULT_SHORT_REPLY_WORDS = 20;
98
- static readonly MAX_SHORT_REPLY_WORDS = 200;
99
98
  /** A language code: a 2-3 letter primary tag and optional subtags (`en`, `pt-BR`); never a word like `constructor`. */
100
99
  static readonly LANGUAGE_PATTERN = /^[a-z]{2,3}(-[a-z0-9]{2,8})*$/i;
101
100
  /** A label or a form of address sits inside one line of a digest card: no line breaks, backticks, pipes or quotes. */
@@ -106,7 +105,7 @@ export class OwnerConstants {
106
105
 
107
106
  /** The launcher of a session whose replies an agent reads sets this; the owner's own sessions never have it. */
108
107
  export class OwnerReplySwitch {
109
- static readonly ENV = 'VULCAN_OWNER_REPLY';
108
+ static readonly ENV = EnvVariables.VULCAN_OWNER_REPLY;
110
109
  /** The only value that counts: anything else is ignored, so a stray value never switches the check off. */
111
110
  static readonly OFF = 'off';
112
111
  }
@@ -5,5 +5,3 @@ export * from './view.ts';
5
5
  export * from './reply-switch.ts';
6
6
  export * from './card.ts';
7
7
  export * from './survey.ts';
8
- export * from './shape.ts';
9
- export * from './violations.ts';
@@ -9,6 +9,7 @@ type TProfileRead = { ok: true; profile: TProfile | undefined } | { ok: false; e
9
9
 
10
10
  const SYMLINK_ERROR = `${OwnerConstants.PROFILE_FILE} (or .agents/local) is a symlink - it must be a regular file inside the project`;
11
11
 
12
+ /** Reads, renders and writes the per-person owner profile file inside `.agents/local`; used by `vulcan profile`, `vulcan doctor` and the session digest. */
12
13
  export class OwnerProfile {
13
14
  /** A symlink at the profile's place, or at `.agents/local`, would read or write a file outside the project. */
14
15
  static linkedAt(opts: { root: string }): string | undefined {