@venizia/vulcan 0.4.9-2 → 0.4.9-4

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 (73) hide show
  1. package/README.md +5 -6
  2. package/base/claude/commit-attribution.json +7 -0
  3. package/base/commit-agents.json +41 -0
  4. package/base/make/vulcan.mk +1 -11
  5. package/base/rules.md +3 -8
  6. package/package.json +3 -3
  7. package/src/agents/atlas-block.ts +2 -2
  8. package/src/agents/common/constants.ts +1 -21
  9. package/src/agents/exclude.ts +2 -2
  10. package/src/agents/render.ts +2 -2
  11. package/src/agents/resolve.ts +1 -16
  12. package/src/commands/agents.command.ts +1 -1
  13. package/src/commands/commit-check.command.ts +5 -0
  14. package/src/commands/help.command.ts +7 -4
  15. package/src/commands/index.ts +25 -27
  16. package/src/commands/init.command.ts +2 -15
  17. package/src/commands/sync.command.ts +2 -5
  18. package/src/commands/x.command.ts +1 -1
  19. package/src/commit/agents.ts +32 -0
  20. package/src/commit/check.ts +160 -0
  21. package/src/commit/common/constants.ts +28 -0
  22. package/src/commit/common/index.ts +2 -0
  23. package/src/commit/common/types.ts +57 -0
  24. package/src/commit/hook.ts +187 -0
  25. package/src/commit/index.ts +8 -0
  26. package/src/commit/message.ts +74 -0
  27. package/src/commit/policy.ts +110 -0
  28. package/src/commit/signature.ts +94 -0
  29. package/src/commit/subject.ts +40 -0
  30. package/src/common/constants.ts +3 -22
  31. package/src/common/layout-folder.ts +1 -5
  32. package/src/common/types.ts +0 -5
  33. package/src/config/common/constants.ts +2 -23
  34. package/src/config/common/types.ts +1 -10
  35. package/src/config/loader.ts +15 -16
  36. package/src/config/schema.ts +69 -21
  37. package/src/create/add-app.ts +2 -10
  38. package/src/create/add-lib.ts +1 -8
  39. package/src/create/common/constants.ts +0 -14
  40. package/src/create/common/types.ts +1 -2
  41. package/src/create/preset.ts +0 -12
  42. package/src/create/workspace.ts +5 -5
  43. package/src/doctor/checks.ts +68 -85
  44. package/src/doctor/common/constants.ts +3 -33
  45. package/src/doctor/runner.ts +1 -1
  46. package/src/doctor/tags.ts +4 -5
  47. package/src/hooks/codex-patch.ts +0 -6
  48. package/src/hooks/common/constants.ts +0 -24
  49. package/src/hooks/guard-manifest.ts +1 -1
  50. package/src/hooks/subagent-card.ts +1 -4
  51. package/src/init/common/constants.ts +0 -11
  52. package/src/init/scaffold.ts +8 -16
  53. package/src/manifest/render.ts +25 -25
  54. package/src/owner/constants.ts +0 -4
  55. package/src/owner/violations.ts +1 -15
  56. package/src/router.ts +24 -9
  57. package/src/rules/base.ts +0 -4
  58. package/src/rules/parser.ts +0 -10
  59. package/src/sync/base-rules.ts +1 -2
  60. package/src/sync/common/constants.ts +1 -18
  61. package/src/sync/common/types.ts +1 -1
  62. package/src/sync/index.ts +0 -1
  63. package/src/sync/planner.ts +12 -18
  64. package/src/sync/settings.ts +0 -9
  65. package/src/visualize/assets.ts +1 -1
  66. package/src/visualize/compare-schema.ts +0 -4
  67. package/src/visualize/constants.ts +0 -24
  68. package/src/visualize/kinds-schema.ts +0 -8
  69. package/src/wiki/constants.ts +0 -4
  70. package/base/templates/vulcan.config.js +0 -5
  71. package/base/templates/vulcan.config.mjs +0 -5
  72. package/base/templates/vulcan.config.ts +0 -6
  73. package/src/sync/prune.ts +0 -142
@@ -7,17 +7,11 @@ import { LayoutKeys, LayoutFolder } from '../common/layout-folder.ts';
7
7
  import { MCP_SERVER_HINT, ProjectScaffold } from '../init/index.ts';
8
8
  import { ProjectPackages } from '../config/index.ts';
9
9
  import type { TResolvedConfig } from '../config/index.ts';
10
- import { BaseRules, RuleConstants, RuleParser, RuleSlots } from '../rules/index.ts';
10
+ import { BaseRules, RuleParser, RuleSlots } from '../rules/index.ts';
11
11
  import { ManifestConstants, ProjectManifest } from '../manifest/index.ts';
12
12
  import { AgentScopes, AgentSelection, AgentTable, LocalChoice } from '../agents/index.ts';
13
- import {
14
- AgentFiles,
15
- AtlasBlockPlan,
16
- LocalPlan,
17
- PrunePlan,
18
- SyncPlanner,
19
- SyncStatuses,
20
- } from '../sync/index.ts';
13
+ import { CommitHook, CommitHookStates } from '../commit/index.ts';
14
+ import { AgentFiles, AtlasBlockPlan, LocalPlan, SyncPlanner, SyncStatuses } from '../sync/index.ts';
21
15
  import { LocalConstants, LocalFormat, LocalScan, LocalStates } from '../local/index.ts';
22
16
  import {
23
17
  ReplySwitch,
@@ -123,7 +117,6 @@ const readScriptNames = (opts: { file: string }): string[] | undefined => {
123
117
  }
124
118
  };
125
119
 
126
- /** Info only: the Atlas block of AGENTS.md is missing or no longer matches the config. */
127
120
  const CANONICAL_ATLAS_ARGS = ['x', '--no-install', 'vulcan', 'x', 'atlas', 'mcp', '--root', '.'];
128
121
 
129
122
  const MCP_FILE = '.mcp.json';
@@ -211,7 +204,6 @@ const formatOwners = (opts: ICheckContext): string[] => [
211
204
  ]),
212
205
  ];
213
206
 
214
- /** The size of `.agents/local/` once it is large: where the space went, and the command that gives it back. */
215
207
  /** The states of a listed script worth a warning: a typo or a script nobody committed. A modified one is normal work, so it is only a note. */
216
208
  const STALE_TRUST_STATES = new Set<string>([
217
209
  TrustStates.MISSING,
@@ -244,11 +236,10 @@ export class ProjectContract {
244
236
 
245
237
  /**
246
238
  * The base owns the `V-` namespace: a project defines its rules with bare IDs, and a `V-` ID in its
247
- * rules points at a base rule - one the base does not carry, or has retired, dangles.
239
+ * rules points at a base rule - one the base does not carry dangles.
248
240
  */
249
241
  static checkRuleIds(opts: ICheckContext): IViolation[] {
250
242
  const base = BaseRules.read();
251
- const retired = new Set(BaseRules.readRetiredIds());
252
243
 
253
244
  return RuleParser.parseBaseReferences({
254
245
  markdown: readText({ file: join(opts.root, '.agents', 'rules.md') }),
@@ -258,9 +249,7 @@ export class ProjectContract {
258
249
  createViolation({
259
250
  check: DoctorChecks.RULE_IDS,
260
251
  file: '.agents/rules.md',
261
- message: retired.has(id)
262
- ? `${id} is retired in the base - drop the reference`
263
- : `${id} is not a base rule - give the extension a bare ID`,
252
+ message: `${id} is not a base rule - give the extension a bare ID`,
264
253
  }),
265
254
  );
266
255
  }
@@ -298,16 +287,11 @@ export class ProjectContract {
298
287
  for (const id of Object.keys(opts.config.rules).filter(
299
288
  (ruleId) => slots[ruleId] === undefined,
300
289
  )) {
301
- const namespaced = `${RuleConstants.BASE_NAMESPACE}${id}`;
302
-
303
290
  violations.push(
304
291
  createViolation({
305
292
  check: DoctorChecks.RULE_SLOTS,
306
293
  file: opts.configFile,
307
- message:
308
- slots[namespaced] === undefined
309
- ? `${id} is not a slot - only ${Object.keys(slots).join(', ')} take a choice`
310
- : `'${id}' is not a slot - the base rule is now '${namespaced}'`,
294
+ message: `${id} is not a slot - only ${Object.keys(slots).join(', ')} take a choice`,
311
295
  }),
312
296
  );
313
297
  }
@@ -418,32 +402,14 @@ export class ProjectContract {
418
402
  ];
419
403
  }
420
404
 
421
- /** What `sync --prune` would remove: an old VULCAN or plugin-era hook command, a dead skill link. */
422
- static checkPrune(opts: ICheckContext): IViolation[] {
423
- return PrunePlan.plan({ root: opts.root }).map((action) =>
424
- createViolation({
425
- check: DoctorChecks.PRUNE,
426
- file: relative(opts.root, action.path),
427
- message: `${action.note ?? 'stale'} - run '${ProjectLayout.VULCAN_COMMAND} sync --prune'`,
428
- }),
429
- );
430
- }
431
-
432
405
  /**
433
406
  * C1: the committed manifest is what the config renders - atlas reads the file, never the config.
434
- * A file written before the `$generated` note existed is current; a hand-edited one is not.
407
+ * A hand-edited one, or one without the `$generated` note, is not.
435
408
  */
436
409
  static checkManifest(opts: ICheckContext): IViolation[] {
437
410
  const action = SyncPlanner.planManifest({ root: opts.root, config: opts.config });
438
411
 
439
- if (
440
- action.status === SyncStatuses.UNCHANGED ||
441
- (action.status === SyncStatuses.REPLACED &&
442
- ProjectManifest.isCurrent({
443
- committed: readFileSync(join(opts.root, ManifestConstants.FILE), 'utf8'),
444
- rendered: ProjectManifest.render({ root: opts.root, config: opts.config }),
445
- }))
446
- ) {
412
+ if (action.status === SyncStatuses.UNCHANGED) {
447
413
  return [];
448
414
  }
449
415
 
@@ -484,27 +450,17 @@ export class ProjectContract {
484
450
 
485
451
  for (const owner of owners) {
486
452
  const configs = join(owner, '.configs');
487
- const found = ['.', ...new Set(Object.values(DoctorConstants.LINT_CONFIG_FOLDERS))].flatMap(
488
- (folder) => {
489
- const directory = join(configs, folder);
490
-
491
- return existsSync(join(opts.root, directory))
492
- ? readdirSync(join(opts.root, directory))
493
- .filter((file) => DoctorConstants.LINT_CONFIG_FILE.test(file))
494
- .map((file) => ({
495
- file: join(directory, file),
496
- name: file,
497
- legacy: folder === '.',
498
- }))
499
- : [];
500
- },
501
- );
502
- const names = found.map((item) => item.file);
453
+ const directory = join(configs, DoctorConstants.LINT_CONFIG_FOLDER);
454
+ const found = existsSync(join(opts.root, directory))
455
+ ? readdirSync(join(opts.root, directory))
456
+ .filter((file) => DoctorConstants.LINT_CONFIG_FILE.test(file))
457
+ .map((file) => join(directory, file))
458
+ : [];
503
459
 
504
- lintConfigs += names.length;
460
+ lintConfigs += found.length;
505
461
 
506
462
  if (
507
- names.length > 0 &&
463
+ found.length > 0 &&
508
464
  !isRootDeclared &&
509
465
  !hasStylePackage({ directory: join(opts.root, owner) })
510
466
  ) {
@@ -517,21 +473,7 @@ export class ProjectContract {
517
473
  );
518
474
  }
519
475
 
520
- for (const item of found) {
521
- const { file } = item;
522
-
523
- if (item.legacy) {
524
- const tool = item.name.split('.')[0];
525
-
526
- violations.push(
527
- createViolation({
528
- check: DoctorChecks.STYLE,
529
- file,
530
- message: `move it to .configs/${DoctorConstants.LINT_CONFIG_FOLDERS[tool]}/${item.name}`,
531
- }),
532
- );
533
- }
534
-
476
+ for (const file of found) {
535
477
  if (!readText({ file: join(opts.root, file) }).includes(ProjectLayout.STYLE_PACKAGE)) {
536
478
  violations.push(
537
479
  createViolation({
@@ -729,12 +671,59 @@ export class ProjectContract {
729
671
  ];
730
672
  }
731
673
 
674
+ /**
675
+ * The `commit-msg` hook of this clone, when the project turned a commit check on: a missing or out-of-date
676
+ * one is fixed by `vulcan sync`; one that is not ours and does not call the check, or one a project with
677
+ * `core.hooksPath` owns, is told the line to add. Per clone, so a warning and never a violation.
678
+ */
679
+ static checkCommitHook(opts: ICheckContext): IViolation[] {
680
+ const status = CommitHook.stateOf({ root: opts.root, config: opts.config });
681
+ const file = relative(opts.root, status.path);
682
+ const fix = `run '${ProjectLayout.VULCAN_COMMAND} sync' (make vulcan-sync)`;
683
+
684
+ switch (status.state) {
685
+ case CommitHookStates.MISSING: {
686
+ return [
687
+ createViolation({
688
+ check: DoctorChecks.COMMIT_HOOK,
689
+ file,
690
+ message: `the commit-msg hook is not installed, so commit messages are not checked - ${fix}`,
691
+ }),
692
+ ];
693
+ }
694
+
695
+ case CommitHookStates.STALE: {
696
+ return [
697
+ createViolation({
698
+ check: DoctorChecks.COMMIT_HOOK,
699
+ file,
700
+ message: `the commit-msg hook is out of date - ${fix}`,
701
+ }),
702
+ ];
703
+ }
704
+
705
+ case CommitHookStates.UNWIRED: {
706
+ return [
707
+ createViolation({
708
+ check: DoctorChecks.COMMIT_HOOK,
709
+ file,
710
+ message: `the commit-msg hook does not run the commit check - ${status.note ?? fix}`,
711
+ }),
712
+ ];
713
+ }
714
+
715
+ default: {
716
+ return [];
717
+ }
718
+ }
719
+ }
720
+
732
721
  /**
733
722
  * The atlas server is registered the one way every project does: the root `.mcp.json` (a per-machine
734
723
  * file `sync` writes for the agents that read it) holds an `atlas` entry that runs the project's own
735
724
  * atlas (`--root .`), and the managed Claude settings enable `atlas` by that name. A server under
736
725
  * another name, or one that serves another folder, is never enabled automatically or serves the wrong
737
- * knowledge. A `.mcp.json` git still tracks is told how to hand over to `sync`; one that is untracked and not ignored is told how to hide it. Warnings, not violations.
726
+ * knowledge. One that is untracked and not ignored is told how to hide it. Warnings, not violations.
738
727
  */
739
728
  static checkMcpAtlas(opts: ICheckContext): IViolation[] {
740
729
  const warnings: IViolation[] = [];
@@ -750,15 +739,7 @@ export class ProjectContract {
750
739
  // The root `.mcp.json` is a per-machine file of the agents that read it; a missing one is the
751
740
  // `adapters` check's (not synced yet), so only an existing file is looked at.
752
741
  if (readsMcpFile && existsSync(file)) {
753
- if (AgentFiles.isTracked({ root: opts.root, path: MCP_FILE })) {
754
- warnings.push(
755
- mcpWarning({
756
- file: MCP_FILE,
757
- message:
758
- 'tracked by git; VULCAN now writes it per machine. Run `git rm --cached .mcp.json` and let sync manage it.',
759
- }),
760
- );
761
- } else if (isUntrackedAndVisible({ root: opts.root, path: MCP_FILE })) {
742
+ if (isUntrackedAndVisible({ root: opts.root, path: MCP_FILE })) {
762
743
  warnings.push(
763
744
  mcpWarning({
764
745
  file: MCP_FILE,
@@ -979,6 +960,7 @@ export class ProjectContract {
979
960
  return warnings;
980
961
  }
981
962
 
963
+ /** Info only: the Atlas block of AGENTS.md is missing or no longer matches the config. */
982
964
  static checkAtlasBlock(opts: ICheckContext): IViolation[] {
983
965
  const merged = AtlasBlockPlan.merged({ root: opts.root, config: opts.config });
984
966
 
@@ -1253,6 +1235,7 @@ export class ProjectContract {
1253
1235
  ];
1254
1236
  }
1255
1237
 
1238
+ /** The size of `.agents/local/` once it is large: where the space went, and the command that gives it back. */
1256
1239
  static checkLocalSize(opts: ICheckContext): IViolation[] {
1257
1240
  const entries = LocalScan.scan({ root: opts.root });
1258
1241
  const total = entries.reduce((sum, entry) => sum + entry.bytes, 0);
@@ -10,7 +10,6 @@ export class DoctorChecks {
10
10
  static readonly STYLE = 'style';
11
11
  static readonly MANIFEST = 'manifest';
12
12
  static readonly TAGS = 'tags';
13
- static readonly PRUNE = 'prune';
14
13
  static readonly SCAFFOLD = 'scaffold';
15
14
  static readonly APPS = 'apps';
16
15
  static readonly SCRIPTS = 'scripts';
@@ -21,33 +20,7 @@ export class DoctorChecks {
21
20
  static readonly LOCAL = 'local';
22
21
  static readonly PROFILE = 'profile';
23
22
  static readonly GUARDS = 'guards';
24
- static readonly SCHEME_SET = new Set<string>([
25
- this.CONFIG,
26
- this.LAYOUT,
27
- this.RULE_IDS,
28
- this.RULE_SLOTS,
29
- this.SKILLS,
30
- this.MAKE,
31
- this.HOOKS,
32
- this.ADAPTERS,
33
- this.STYLE,
34
- this.MANIFEST,
35
- this.TAGS,
36
- this.PRUNE,
37
- this.SCAFFOLD,
38
- this.APPS,
39
- this.SCRIPTS,
40
- this.AGENTS,
41
- this.DOCKERIGNORE,
42
- this.MCP,
43
- this.FORMAT,
44
- this.LOCAL,
45
- this.PROFILE,
46
- this.GUARDS,
47
- ]);
48
- static isValid(value: string): boolean {
49
- return this.SCHEME_SET.has(value);
50
- }
23
+ static readonly COMMIT_HOOK = 'commit-hook';
51
24
  }
52
25
 
53
26
  /** The `package.json` scripts every app carries, and the names the standard retired. */
@@ -76,9 +49,6 @@ export class DoctorConstants {
76
49
  /** The oxfmt config names `bun fmt` finds by itself, in a package folder or above it; they override `[fmt]`. */
77
50
  static readonly OXFMT_AUTOLOADED_FILES = ['.oxfmtrc.json', '.oxfmtrc.jsonc', 'oxfmt.config.ts'];
78
51
  static readonly LINT_CONFIG_FILE = /^(oxlint|eslint)\.config\.(mts|ts|mjs|js|cjs)$/;
79
- /** Where each tool's config lives under `.configs/`; a file left directly in `.configs/` is told where it belongs. */
80
- static readonly LINT_CONFIG_FOLDERS: Record<string, string> = {
81
- oxlint: 'lints',
82
- eslint: 'lints',
83
- };
52
+ /** Where the lint configs live under `.configs/`. */
53
+ static readonly LINT_CONFIG_FOLDER = 'lints';
84
54
  }
@@ -36,7 +36,6 @@ export class DoctorRunner {
36
36
  ...ProjectContract.checkHooks(context),
37
37
  ...ProjectContract.checkAdapters(context),
38
38
  ...ProjectContract.checkAgents(context),
39
- ...ProjectContract.checkPrune(context),
40
39
  ...ProjectContract.checkManifest(context),
41
40
  ...TagCheck.check(context),
42
41
  ...SkillLint.check(context),
@@ -92,6 +91,7 @@ export class DoctorRunner {
92
91
 
93
92
  return [
94
93
  ...ProjectContract.checkMcpAtlas(context),
94
+ ...ProjectContract.checkCommitHook(context),
95
95
  ...ProjectContract.checkDockerignore(context),
96
96
  ...ProjectContract.checkSkillTriggers(context),
97
97
  ...ProjectContract.checkFormat(context),
@@ -5,15 +5,14 @@ import type { ICheckContext } from './checks.ts';
5
5
  import { DoctorChecks } from './common/index.ts';
6
6
  import type { IViolation } from './common/index.ts';
7
7
 
8
- /** The tag pattern as a regular expression that captures `<dir>` (or `<package>`). */
8
+ /** The tag pattern as a regular expression that captures `<dir>`. */
9
9
  const tagPatternOf = (opts: { template: string }): RegExp =>
10
10
  new RegExp(
11
11
  `^${opts.template
12
- .split(/(<(?:dir|package|version|date)>)/)
12
+ .split(/(<(?:dir|version|date)>)/)
13
13
  .map((part) => {
14
14
  switch (part) {
15
- case '<dir>':
16
- case '<package>': {
15
+ case '<dir>': {
17
16
  return '(?<dir>[a-z0-9][a-z0-9.-]*)';
18
17
  }
19
18
 
@@ -43,7 +42,7 @@ export class TagCheck {
43
42
  static check(opts: ICheckContext): IViolation[] {
44
43
  const template = opts.config.atlas.tagPattern;
45
44
 
46
- if (!/<(?:dir|package)>/.test(template)) {
45
+ if (!template.includes('<dir>')) {
47
46
  return [];
48
47
  }
49
48
 
@@ -5,12 +5,6 @@ import type { TConstValue } from '../common/index.ts';
5
5
  export class PatchedTools {
6
6
  static readonly WRITE = 'write';
7
7
  static readonly EDIT = 'edit';
8
-
9
- static readonly SCHEME_SET = new Set<string>([this.WRITE, this.EDIT]);
10
-
11
- static isValid(value: string): boolean {
12
- return this.SCHEME_SET.has(value);
13
- }
14
8
  }
15
9
 
16
10
  type TPatchedTool = TConstValue<typeof PatchedTools>;
@@ -2,22 +2,12 @@
2
2
  export class GuardDecisions {
3
3
  static readonly ASK = 'ask';
4
4
  static readonly DENY = 'deny';
5
- static readonly SCHEME_SET = new Set<string>([this.ASK, this.DENY]);
6
- static isValid(value: string): boolean {
7
- return this.SCHEME_SET.has(value);
8
- }
9
5
  }
10
6
 
11
7
  /** What the package guard says about a hand-made package: refuse where a `vulcan add` command exists, else warn. */
12
8
  export class PackageVerdictKinds {
13
9
  static readonly DENY = GuardDecisions.DENY;
14
10
  static readonly WARN = 'warn';
15
-
16
- static readonly SCHEME_SET = new Set<string>([this.DENY, this.WARN]);
17
-
18
- static isValid(value: string): boolean {
19
- return this.SCHEME_SET.has(value);
20
- }
21
11
  }
22
12
 
23
13
  /** What git says about a script a project trusts: only `TRUSTED` skips the script checks of guard-writes. */
@@ -29,20 +19,6 @@ export class TrustStates {
29
19
  static readonly MODIFIED = 'modified';
30
20
  static readonly SYMLINK = 'symlink';
31
21
  static readonly UNKNOWN = 'unknown';
32
-
33
- static readonly SCHEME_SET = new Set<string>([
34
- this.TRUSTED,
35
- this.MISSING,
36
- this.UNTRACKED,
37
- this.UNCOMMITTED,
38
- this.MODIFIED,
39
- this.SYMLINK,
40
- this.UNKNOWN,
41
- ]);
42
-
43
- static isValid(value: string): boolean {
44
- return this.SCHEME_SET.has(value);
45
- }
46
22
  }
47
23
 
48
24
  export class HookConstants {
@@ -6,7 +6,7 @@ import { HookDecision } from './decision.ts';
6
6
  /** The shell tool under the names the hosts give it: Cursor's `Shell`, and a lower-case `bash`. */
7
7
  const SHELL_NAMES = new Set(['Shell', 'shell', 'bash']);
8
8
 
9
- export const MANIFEST_BLOCK_MESSAGE =
9
+ const MANIFEST_BLOCK_MESSAGE =
10
10
  'vulcan.manifest.json is generated - edit .configs/vulcan.config.* and run `vulcan sync`';
11
11
 
12
12
  const MANIFEST_SUFFIX = '/.agents/vulcan.manifest.json';
@@ -1,13 +1,10 @@
1
1
  import { HookConstants } from './common/index.ts';
2
2
 
3
- /** The most a subagent's start card may be: it is paid for once per subagent, so it carries gates only. */
4
- export const SUBAGENT_CARD_MAX_CHARACTERS = 1600;
5
-
6
3
  /**
7
4
  * What a subagent must keep, and nothing else: the project's own rules are one path away, and the owner
8
5
  * shape and the profile are for the agent that talks to the owner. Each line cites its base rule.
9
6
  */
10
- export const SUBAGENT_CARD = [
7
+ const SUBAGENT_CARD = [
11
8
  '# VULCAN: rules for a subagent',
12
9
  '',
13
10
  'You work for a main agent, inside this project. Base rules: `node_modules/@venizia/vulcan/base/rules.md`; this project: `.agents/rules.md`.',
@@ -4,19 +4,8 @@ export class InitStatuses {
4
4
  static readonly KEPT = 'kept';
5
5
  static readonly ADD = 'add';
6
6
  static readonly SKIPPED = 'skipped';
7
- static readonly SCHEME_SET = new Set<string>([
8
- this.CREATED,
9
- this.UPDATED,
10
- this.KEPT,
11
- this.ADD,
12
- this.SKIPPED,
13
- ]);
14
- static isValid(value: string): boolean {
15
- return this.SCHEME_SET.has(value);
16
- }
17
7
  }
18
8
 
19
9
  export class InitConstants {
20
10
  static readonly NAME_TOKEN = '{{name}}';
21
- static readonly CONFIG_FLAG = '--config';
22
11
  }
@@ -3,7 +3,6 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
3
3
  import { basename, dirname, join, relative } from 'node:path';
4
4
  import { BASE_DIRECTORY, JsonValue, ProjectLayout } from '../common/index.ts';
5
5
  import { ConfigConstants, ConfigLoader } from '../config/index.ts';
6
- import type { TConfigExtension } from '../config/index.ts';
7
6
  import { InitConstants, InitStatuses } from './common/index.ts';
8
7
  import { Bunfig } from '../create/bunfig.ts';
9
8
  import { Dockerignore } from '../create/dockerignore.ts';
@@ -13,7 +12,7 @@ import type { IInitEntry, IScaffoldFile } from './common/index.ts';
13
12
  export const MCP_SERVER_HINT =
14
13
  '"atlas": { "command": "bun", "args": ["x", "--no-install", "vulcan", "x", "atlas", "mcp", "--root", "."] }';
15
14
 
16
- /** The files every project gets, apart from the config, whose format the user picks. */
15
+ /** The files every project gets, apart from the config. */
17
16
  const SCAFFOLD_FILES: IScaffoldFile[] = [
18
17
  { path: 'AGENTS.md', template: 'AGENTS.md' },
19
18
  { path: '.agents/rules.md', template: 'rules.md' },
@@ -132,7 +131,7 @@ export class ProjectScaffold {
132
131
  }
133
132
 
134
133
  /** Scaffolds the project layer at `root`. Never overwrites: an existing file is kept and a needed edit becomes a hint; only `.gitignore` is appended to, line by line. */
135
- static scaffold(opts: { root: string; extension: TConfigExtension }): IScaffoldResult {
134
+ static scaffold(opts: { root: string }): IScaffoldResult {
136
135
  const { root } = opts;
137
136
  const name = resolveProjectName({ root });
138
137
  const isWorkspaces = ProjectScaffold.declaresWorkspaces({ root });
@@ -149,29 +148,22 @@ export class ProjectScaffold {
149
148
  if (isWorkspaces) {
150
149
  entries.push({
151
150
  status: InitStatuses.SKIPPED,
152
- subject: `.configs/{lints,formatters}: a workspaces project keeps them per app (apps/<name>/.configs/lints/, apps/<name>/.configs/formatters/); the templates are in node_modules/@venizia/vulcan/base/templates/`,
151
+ subject: `.configs/lints: a workspaces project keeps them per app (apps/<name>/.configs/lints/); the templates are in node_modules/@venizia/vulcan/base/templates/`,
153
152
  });
154
153
  }
155
154
 
156
- const configs = ConfigLoader.findFiles({ root });
157
-
158
- if (configs.length === 0) {
159
- const configFile = `${ConfigConstants.BASENAME}.${opts.extension}`;
155
+ const config = ConfigLoader.findFile({ root });
160
156
 
157
+ if (config === undefined) {
161
158
  entries.push(
162
159
  writeIfAbsent({
163
160
  root,
164
- path: join(ConfigConstants.DIRECTORY, configFile),
165
- content: ProjectScaffold.renderTemplate({ template: configFile, name }),
161
+ path: join(ConfigConstants.DIRECTORY, ConfigConstants.FILE),
162
+ content: ProjectScaffold.renderTemplate({ template: ConfigConstants.FILE, name }),
166
163
  }),
167
164
  );
168
165
  } else {
169
- entries.push(
170
- ...configs.map((file): IInitEntry => ({
171
- status: InitStatuses.KEPT,
172
- subject: relative(root, file),
173
- })),
174
- );
166
+ entries.push({ status: InitStatuses.KEPT, subject: relative(root, config) });
175
167
  }
176
168
 
177
169
  entries.push(writeIfAbsent({ root, path: '.dockerignore', content: Dockerignore.render() }));
@@ -1,6 +1,7 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
2
  import { basename, join } from 'node:path';
3
3
  import { BunFormatter } from '../common/index.ts';
4
+ import { AgentSignaturePolicies } from '../commit/common/index.ts';
4
5
  import { ProjectPackages } from '../config/index.ts';
5
6
  import type { TResolvedConfig } from '../config/index.ts';
6
7
  import { BaseRules } from '../rules/index.ts';
@@ -11,7 +12,7 @@ export class ManifestConstants {
11
12
  static readonly SCHEMA_VERSION = 1;
12
13
  static readonly PROJECT_RULES = '.agents/rules.md';
13
14
  static readonly ENV = 'VULCAN_MANIFEST';
14
- /** The first key: a reader sees at once that the file is generated. Readers ignore it; absent in older files. */
15
+ /** The first key: a reader sees at once that the file is generated. Readers ignore it. */
15
16
  static readonly GENERATED_KEY = '$generated';
16
17
  static readonly GENERATED_NOTE = 'by vulcan sync from .configs/vulcan.config.* - do not edit';
17
18
  }
@@ -47,6 +48,28 @@ const guardBlockOf = (opts: { config: TResolvedConfig }): { guard?: Record<strin
47
48
  return Object.keys(block).length === 0 ? {} : { guard: block };
48
49
  };
49
50
 
51
+ const commitBlockOf = (opts: { config: TResolvedConfig }): { commit?: Record<string, unknown> } => {
52
+ const { agent, subject } = opts.config.commit.message;
53
+ const isDenied = agent.signature === AgentSignaturePolicies.DENY;
54
+
55
+ if (!isDenied && subject === undefined) {
56
+ return {};
57
+ }
58
+
59
+ return {
60
+ commit: {
61
+ message: {
62
+ agent: {
63
+ signature: agent.signature,
64
+ ...(isDenied && agent.names.length > 0 ? { names: agent.names } : {}),
65
+ ...(isDenied && agent.allow.length > 0 ? { allow: agent.allow } : {}),
66
+ },
67
+ ...(subject === undefined ? {} : { subject }),
68
+ },
69
+ },
70
+ };
71
+ };
72
+
50
73
  /** The manifest's `atlas` block: only what the config sets (keys listed, the download turned off). */
51
74
  const atlasBlockOf = (opts: { config: TResolvedConfig }): { atlas?: Record<string, unknown> } => {
52
75
  const keys = opts.config.atlas.index?.keys ?? [];
@@ -140,6 +163,7 @@ export class ProjectManifest {
140
163
  ...(config.remoteHosts === undefined ? {} : { remoteHosts: config.remoteHosts }),
141
164
  // The colour `vulcan visualize` takes for its pages; a project without the key gets the neutral default.
142
165
  ...(config.theme === undefined ? {} : { theme: config.theme }),
166
+ ...commitBlockOf({ config }),
143
167
  };
144
168
 
145
169
  return BunFormatter.format({
@@ -147,28 +171,4 @@ export class ProjectManifest {
147
171
  file: ManifestConstants.FILE,
148
172
  });
149
173
  }
150
-
151
- /**
152
- * Whether a committed manifest holds what the config renders, apart from the `$generated` note: a
153
- * file written before the note existed is current, a hand-edited one is not.
154
- */
155
- static isCurrent(opts: { committed: string; rendered: string }): boolean {
156
- try {
157
- const strip = (text: string): string => {
158
- const record: Record<string, unknown> = JSON.parse(text);
159
-
160
- delete record[ManifestConstants.GENERATED_KEY];
161
-
162
- return JSON.stringify(record);
163
- };
164
-
165
- return strip(opts.committed) === strip(opts.rendered);
166
- } catch (error) {
167
- console.error(
168
- `[ProjectManifest.isCurrent] unreadable manifest | ${error instanceof Error ? error.message : String(error)}`,
169
- );
170
-
171
- return false;
172
- }
173
- }
174
174
  }
@@ -119,8 +119,4 @@ export class OwnerReplySwitch {
119
119
  export class OwnerLabelModes {
120
120
  static readonly EXACT = 'exact';
121
121
  static readonly FREE = 'free';
122
- static readonly SCHEME_SET = new Set<string>([this.EXACT, this.FREE]);
123
- static isValid(value: string): boolean {
124
- return this.SCHEME_SET.has(value);
125
- }
126
122
  }
@@ -19,8 +19,6 @@ const isKnownClass = (value: string): boolean =>
19
19
  export class ViolationConstants {
20
20
  /** One line per checked reply that broke the shape: the date and the classes, never the reply. */
21
21
  static readonly LOG_FILE = 'violations.jsonl';
22
- /** The one-file-per-project note of 0.4.2 and before; removed when a session note is written. */
23
- static readonly LEGACY_LAST_FILE = 'last-reply.json';
24
22
  /** One note per session under the cache: its last checked reply's classes, for that session's next reminder. */
25
23
  static readonly NOTES_DIRECTORY = 'cache/replies';
26
24
  /** The note name of an event that carries no session id. */
@@ -148,21 +146,9 @@ const readNote = (opts: { root: string; session?: string }): Record<string, unkn
148
146
  }
149
147
  };
150
148
 
151
- /**
152
- * Removes the notes older than the reminder window, the oldest beyond the cap, and the one-file note
153
- * of 0.4.2 and before, so the folder never grows. A note that cannot be removed is left.
154
- */
149
+ /** Removes the notes older than the reminder window and the oldest beyond the cap, so the folder never grows. A note that cannot be removed is left. */
155
150
  const pruneNotes = (opts: { root: string; now: number }): void => {
156
151
  const directory = notesDirectoryOf({ root: opts.root, create: false });
157
- const local = LocalScan.localRootOf({ root: opts.root });
158
-
159
- if (local !== undefined) {
160
- const legacy = join(local, ViolationConstants.LEGACY_LAST_FILE);
161
-
162
- if (lstatSync(legacy, { throwIfNoEntry: false })?.isFile() === true) {
163
- rmSync(legacy, { force: true });
164
- }
165
- }
166
152
 
167
153
  if (directory === undefined) {
168
154
  return;