@venizia/vulcan 0.3.3 → 0.3.5

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.
package/README.md CHANGED
@@ -50,7 +50,7 @@ An unknown key is an error; every error names the file and the field.
50
50
 
51
51
  ## What ships (`base/`)
52
52
 
53
- - `rules.md` - the base rules: write boundaries, security, process, build, and the IGNIS coding style V-C-01..V-C-18 (37 rules; it lists V-W-05, V-C-03 and V-C-05 as retired).
53
+ - `rules.md` - the base rules: write boundaries, security, process, build, and the IGNIS coding style V-C-01..V-C-18 (38 rules; it lists V-W-05, V-C-03 and V-C-05 as retired).
54
54
  - `slots.json` - rules a project picks a wording for (V-W-01 today).
55
55
  - `skills/` - `knowledge-sync`, `docs-writing`, `docs-update` (project-neutral; a project-specific skill stays in its project). Skill evals have not been run against a model: the skills pass the lint, and their output is a draft to review.
56
56
  - `hooks/` - `session-start.ts` (prints the rules digest) `guard-writes.ts` (asks before a database write, a migration, a deploy or a mutating HTTP call) `guard-manifest.ts` (refuses a write to the generated `.agents/vulcan.manifest.json`) and `guard-remote-hosts.ts` (only for a config with `remoteHosts`: asks before a command reaches a host that is not listed; whole-name or `*` match, never substring).
package/base/rules.md CHANGED
@@ -47,6 +47,7 @@ Retired IDs are never reused (2026-10-17):
47
47
  | V-P-04 | Fact changes → update `.agents/knowledge/` in the same change. | SOFT |
48
48
  | V-P-05 | Partner, not stenographer. Wrong instruction → say so with reasoning + better option; human decides. Never overrides W rules or V-P-03. | SOFT |
49
49
  | V-P-06 | Scope discipline: exactly the issue at hand. Discoveries → NEW issues. Scope creep = defect. | SOFT |
50
+ | V-P-07 | **Facts come from atlas, not memory.** Before you use an API of the project's framework or of its own packages, look it up with atlas: `symbol` for an export you import, `search` for how something works, `version` or `changes` for a release. A signature, option or behavior recalled from memory is a guess until atlas confirms it. | SOFT - atlas server instructions and tool descriptions, session-start digest |
50
51
 
51
52
  ## B - Build and quality
52
53
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.3.3",
3
+ "version": "0.3.5",
4
4
  "description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
5
5
  "homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
6
6
  "repository": {
@@ -44,8 +44,8 @@
44
44
  "test": "NODE_ENV=test bun test --env-file=.env.test"
45
45
  },
46
46
  "dependencies": {
47
- "@venizia/vulcan-atlas": "0.3.3",
48
- "@venizia/vulcan-okf": "0.3.3",
47
+ "@venizia/vulcan-atlas": "0.3.5",
48
+ "@venizia/vulcan-okf": "0.3.5",
49
49
  "zod": "^4.5.4"
50
50
  },
51
51
  "devDependencies": {
@@ -53,6 +53,7 @@ export class ConfigConstants {
53
53
  static readonly RULE_ID_PATTERN = /^(?:[A-Z]+-)?[A-Z]-\d{2}$/;
54
54
  /** The rules a session drops most, printed at every session start unless the project lists its own. */
55
55
  static readonly DEFAULT_OFTEN_DROPPED = [
56
+ 'V-P-07',
56
57
  'V-B-03',
57
58
  'V-P-05',
58
59
  'V-P-06',
@@ -42,6 +42,8 @@ export interface IPreset {
42
42
  checks: string[];
43
43
  /** Paths under the dev port worth opening (`/api/hello`); none means the root. */
44
44
  urls: string[];
45
+ /** The app's `package.json` `imports` (Node subpath imports), copied as they are written. */
46
+ imports: Record<string, string>;
45
47
  /** The folder holding the files to copy, absolute once the preset is located. */
46
48
  files: string;
47
49
  atlas: IPresetAtlasSource[];
@@ -29,11 +29,22 @@ const PRESET_SCHEMA = z
29
29
  scripts: z.record(z.string(), z.string()).default({}),
30
30
  checks: z.array(z.string()).default([]),
31
31
  urls: z.array(z.string().startsWith('/')).default([]),
32
+ imports: z.record(z.string(), z.string()).default({}),
32
33
  files: z.string(),
33
34
  atlas: z.array(z.object({ name: z.string(), repo: z.string(), ref: z.string() })).default([]),
34
35
  })
35
36
  // A check is run as `bun run <check>`; an entry that is not a script could be a bun flag.
36
37
  .superRefine((value, context) => {
38
+ for (const key of Object.keys(value.imports)) {
39
+ if (!key.startsWith('#')) {
40
+ context.addIssue({
41
+ code: 'custom',
42
+ path: ['imports', key],
43
+ message: `"${key}" is not a subpath import: a key starts with #`,
44
+ });
45
+ }
46
+ }
47
+
37
48
  value.checks.forEach((check, index) => {
38
49
  if (!Object.hasOwn(value.scripts, check)) {
39
50
  context.addIssue({
@@ -153,6 +153,8 @@ export const renderAppManifest = (opts: {
153
153
  name: opts.app,
154
154
  version: '0.0.0',
155
155
  private: true,
156
+ // The preset's own text: no token is replaced here, a path pattern has no use for one.
157
+ ...(Object.keys(opts.preset.imports).length === 0 ? {} : { imports: opts.preset.imports }),
156
158
  scripts: opts.preset.scripts,
157
159
  dependencies: toCatalog({
158
160
  dependencies: {
@@ -1,5 +1,5 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
- import { join } from 'node:path';
2
+ import { basename, join } from 'node:path';
3
3
  import { BASE_DIRECTORY, ProjectLayout } from '../common/index.ts';
4
4
  import { ConfigConstants, loadConfig } from '../config/index.ts';
5
5
  import { extractRuleRows, parseRuleIds, readSlots, RuleConstants } from '../rules/index.ts';
@@ -22,6 +22,25 @@ const selectRows = (opts: { rows: string[]; ids: string[] }): string[] =>
22
22
  const readText = (opts: { file: string }): string =>
23
23
  existsSync(opts.file) ? readFileSync(opts.file, 'utf8') : '';
24
24
 
25
+ /** The Atlas block: only for a project whose `.mcp.json` runs the atlas server. */
26
+ const buildAtlasBlock = (opts: {
27
+ projectRoot: string;
28
+ project: string;
29
+ sources: string[];
30
+ }): string[] => {
31
+ if (!/\batlas\b/.test(readText({ file: join(opts.projectRoot, '.mcp.json') }))) {
32
+ return [];
33
+ }
34
+
35
+ return [
36
+ '## Atlas',
37
+ '',
38
+ `The \`atlas\` MCP server holds the real code and docs of: ${[`${opts.project} (this repository)`, ...opts.sources].join(', ')}.`,
39
+ 'Look facts up there before you answer or write from memory: `symbol` for an export you import, `search` for how something works, `version` or `changes` for a release (V-P-07).',
40
+ '',
41
+ ];
42
+ };
43
+
25
44
  /** The SessionStart context: base write boundaries, this project's slot choices and own rules, the often-dropped rules. */
26
45
  export const buildSessionDigest = async (opts: { projectRoot: string }): Promise<string> => {
27
46
  const baseRows = extractRuleRows({
@@ -53,6 +72,13 @@ export const buildSessionDigest = async (opts: { projectRoot: string }): Promise
53
72
  '',
54
73
  'Base rules: `node_modules/@venizia/vulcan/base/rules.md`. This project: `.agents/rules.md`.',
55
74
  '',
75
+ ...buildAtlasBlock({
76
+ projectRoot: opts.projectRoot,
77
+ project: loaded.ok
78
+ ? (loaded.config.name ?? basename(opts.projectRoot))
79
+ : basename(opts.projectRoot),
80
+ sources: loaded.ok ? loaded.config.atlas.sources.map(source => source.name) : [],
81
+ }),
56
82
  '## Write boundaries',
57
83
  '',
58
84
  ...TABLE_HEADER,