@venizia/vulcan 0.1.0-0 → 0.1.0-1

package/README.md

@@ -46,7 +46,7 @@ An unknown key is an error; every error names the file and the field.
 
 ## What ships (`base/`)
 
-- `rules.md` - the base rules: write boundaries, security, process, build, and the IGNIS coding style V-C-01..V-C-18.
+- `rules.md` - the base rules: write boundaries, security, process, build, and the IGNIS coding style V-C-01..V-C-18 (37 rules; V-W-05, V-C-03 and V-C-05 are retired).
 - `slots.json` - rules a project picks a wording for (V-W-01 today).
 - `skills/` - `knowledge-sync`, `docs-writing` (project-neutral; a project-specific skill stays in its project).
 - `hooks/` - `session-start.ts` (prints the rules digest) and `guard-writes.ts` (asks before a database write, a migration, a deploy or a mutating HTTP call).

package/base/rules.md

@@ -2,12 +2,16 @@
 
 <!-- Shipped by @venizia/vulcan. Never edit in a project: add extensions in .agents/rules.md.
      W, S, P, B are INTERIM until the base-rules work reconciles the rules IGNIS, ARDOR and BANA share.
-     C is IGNIS's coding style, V-C-01..V-C-18 verbatim from IGNIS (only IGNIS-only literals generalized), shipped to every project. -->
+     C is IGNIS's coding style, shipped to every project; the rules that bind IGNIS's own stack live in IGNIS. -->
 
 Cite by ID. Every rule has "Enforced by". Base IDs carry the `V-` namespace (`V-W-01`, `V-C-04`).
 A project extends this set in its own `.agents/rules.md` with bare IDs (`W-06`, `C-19`), which can
 never collide with a base ID; it never claims the `V-` namespace (`vulcan doctor` enforces it).
 
+Retired IDs are never reused: `V-W-05` (task-manager loop), `V-C-03` (`@inject` on container-built
+classes) and `V-C-05` (`getError` / `ApplicationError`) - the last two, with the hard stack once in
+`V-C-18`, are IGNIS rules now (2026-10-17).
+
 ## W - Write boundaries
 
 | ID | Rule | Enforced by |
@@ -16,7 +20,6 @@ never collide with a base ID; it never claims the `V-` namespace (`vulcan doctor
 | V-W-02 | Never write to a database. Write the migration file, hand over. Read-only SELECT ok. | HARD - guard-writes hook (asks) |
 | V-W-03 | Never deploy or hot-apply (kubectl apply, docker compose up, restarts). | HARD - guard-writes hook (asks) |
 | V-W-04 | Ask before anything irreversible: deleting files you didn't create, side-effect APIs, publishing. | SOFT |
-| V-W-05 | Task-manager writes limited to the workflow loop. Bulk edits/deletions need preview + approval. | SOFT |
 
 ## S - Security
 
@@ -35,7 +38,7 @@ never collide with a base ID; it never claims the `V-` namespace (`vulcan doctor
 | ID | Rule | Enforced by |
 |----|------|-------------|
 | V-P-01 | Read `AGENTS.md`, these base rules, the project's `.agents/rules.md` and the relevant `.agents/knowledge/` before acting. | SOFT - session-start hook |
-| V-P-02 | New feature: no code until PRD reaches `gate: planned`. | SOFT |
+| V-P-02 | **Design the surface before the body.** For a feature, propose what its users see first - signatures, types, options, config, output - and get a yes before implementing. Priorities, in order: simplicity > flexibility > completeness. | SOFT |
 | V-P-03 | Plans need human approval before implementation. | SOFT |
 | V-P-04 | Fact changes → update `.agents/knowledge/` in the same change. | SOFT |
 | 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 |
@@ -56,9 +59,7 @@ never collide with a base ID; it never claims the `V-` namespace (`vulcan doctor
 |----|------|-------------|
 | V-C-01 | **English only in code** - identifiers, comments, commit messages, logs, docs. Vietnamese belongs in chat. | SOFT |
 | V-C-02 | **Options objects everywhere:** `fn({ key, value })`, never `fn(key, value)`. **One parameter is not an exception** - `isValidName({ name })`, not `isValidName(name)`. A single positional parameter reads fine until the second one arrives, and by then the method is published and every call site pays. The cost is highest on an interface others implement: `IStorageHelper` carried three positional methods for exactly this reason and the migration touched 72 call sites. Mixing the two styles in one interface is itself the defect - a reader cannot tell which shape a method takes without opening it. | SOFT |
-| V-C-03 | **Every constructor parameter of a container-instantiated class carries `@inject`.** Mixing decorated and undecorated parameters is refused at boot - the container has no channel to supply an undecorated one. Options a controller needs go in `super({ scope: X.name })`, never as an undecorated parameter. | SOFT |
 | V-C-04 | **Never abbreviate identifiers:** `ProductRepository` not `ProductRepo`, `ProductDocument` not `ProductDoc`; type parameters too (`TDocument`, not `TDoc`). A project lists its own exceptions in its rules (IGNIS: `tz` for a time zone). | SOFT |
-| V-C-05 | **Errors are `getError` / `ApplicationError`. Never `new Error`.** Never `instanceof ApplicationError` across a package boundary - the dual CJS+ESM build gives the class several identities; use `isApplicationError()`. | SOFT |
 | V-C-06 | **Never a silent catch - log it.** Always braces. Early return. `switch` with `default` over a long if-else chain. Strict TypeScript; no `any` where a type exists. | LINT (braces, floating promises) + SOFT |
 | V-C-07 | **A function name opens with its verb** - `generate` `build` `to` `is` `has` `assert` `extract` `enrich` `get` `resolve`. `is*` returns a boolean and leaves the branch to the caller; `assert*` throws and returns `void`, so the code after it needs none - reach for `assert*` when every caller would throw on `false` anyway. `has*` is the ownership question (`hasBucket`, never `isBucketExists`). That list is for UTILITY functions; service methods lean on a wider set. **Arrow functions, not `function` declarations** (do not churn existing ones). State plus the operations on it live in a class with static members - the `LoggerFactory` shape - never module-level `let` plus exported arrows. | SOFT |
 | V-C-08 | **Enumerable strings are a const class plus `TConstValue`,** never a raw string-literal union. Every such class carries `static readonly SCHEME_SET = new Set([...])` over its values and `static isValid(value: string): boolean` reading it, so a runtime check exists wherever a value crosses a boundary (`IsolationLevels` in connectors is the model; a subclass redeclares `SCHEME_SET` with `...Parent.SCHEME_SET` first). The `T`/`I` prefix follows the declaration keyword: `type` gets `T`, `interface` gets `I`; an interface turned into a type alias is renamed, and no tool catches it - grep both directions. | SOFT |
@@ -71,4 +72,4 @@ never collide with a base ID; it never claims the `V-` namespace (`vulcan doctor
 | V-C-15 | **One method with a mode option, not several specialized methods.** Payload variants are zod-per-variant with `z.infer`, discriminated. | SOFT |
 | V-C-16 | **One concept, one implementation.** When the same question is answered in several places, the bug lives at the seam and no tool catches it. Consolidate to one home before building on top. | SOFT |
 | V-C-17 | **A file is named by its role, never by repeating its folder:** `winston/logger.ts`, not `winston/winston-logger.ts`. | SOFT |
-| V-C-18 | **The hard stack, and derived types over duplicates.** Drizzle only (never TypeORM, Prisma, Sequelize); Hono only (never Express, Fastify, Koa); Zod only (never Joi, Yup, class-validator); PostgreSQL primary with SQLite alongside, the repository tier engine-neutral (`pgTable` and `sqliteTable` both). REST is default framework behavior, not a component. Prefer compile-time types derived from definitions (`typeof User.schema`) over hand-maintained copies. | SOFT |
+| V-C-18 | **Derived types over duplicates.** Prefer compile-time types derived from their definitions (`typeof schema`, `z.infer<typeof Schema>`, `ReturnType<typeof build>`) over hand-maintained copies - a copy drifts the day its source changes. A project's stack (framework, ORM, validator) is a project rule, not a base rule. | SOFT |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/vulcan",
-  "version": "0.1.0-0",
+  "version": "0.1.0-1",
   "description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
   "homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
   "repository": {
@@ -44,8 +44,8 @@
   },
   "dependencies": {
     "@venizia/ignis-helpers": "^0.2.2-5",
-    "@venizia/vulcan-atlas": "0.1.0-0",
-    "@venizia/vulcan-okf": "0.1.0-0",
+    "@venizia/vulcan-atlas": "0.1.0-1",
+    "@venizia/vulcan-okf": "0.1.0-1",
     "zod": "^4.5.4"
   },
   "devDependencies": {

package/src/doctor/checks.ts

@@ -1,3 +1,4 @@
+import { Glob } from 'bun';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { BASE_DIRECTORY, ProjectLayout } from '../common/index.ts';
@@ -6,7 +7,7 @@ import { parseRuleIds, readSlots, RuleConstants } from '../rules/index.ts';
 import { planSync, SyncStatuses } from '../sync/index.ts';
 import { DoctorChecks, DoctorConstants } from './common/index.ts';
 import type { IViolation, TDoctorCheck } from './common/index.ts';
-import { parseMakeTargets } from './makefile.ts';
+import { parseMakeIncludes, parseMakeTargets } from './makefile.ts';
 
 export interface ICheckContext {
   root: string;
@@ -119,6 +120,35 @@ export const checkSkills = (opts: ICheckContext): IViolation[] => {
     );
 };
 
+/**
+ * The project's Makefile and every file it includes, recursively, relative to the root. Includes
+ * under node_modules are shipped (vulcan.mk), never project targets.
+ */
+const findProjectMakefiles = (opts: { root: string }): string[] => {
+  const found: string[] = [];
+  const pending = ['Makefile'];
+
+  while (pending.length > 0) {
+    const file = pending.shift() ?? '';
+
+    if (found.includes(file) || !existsSync(join(opts.root, file))) {
+      continue;
+    }
+
+    found.push(file);
+
+    for (const pattern of parseMakeIncludes({
+      makefile: readText({ file: join(opts.root, file) }),
+    })) {
+      const matches = [...new Glob(pattern).scanSync({ cwd: opts.root, onlyFiles: true })].sort();
+
+      pending.push(...matches.filter(match => !match.split('/').includes('node_modules')));
+    }
+  }
+
+  return found;
+};
+
 export const checkMake = (opts: ICheckContext): IViolation[] => {
   const makefile = readText({ file: join(opts.root, 'Makefile') });
   const violations: IViolation[] = [];
@@ -137,14 +167,18 @@ export const checkMake = (opts: ICheckContext): IViolation[] => {
     parseMakeTargets({ makefile: readText({ file: join(BASE_DIRECTORY, 'make', 'vulcan.mk') }) }),
   );
 
-  for (const target of parseMakeTargets({ makefile }).filter(name => shipped.has(name))) {
-    violations.push(
-      createViolation({
-        check: DoctorChecks.MAKE,
-        file: 'Makefile',
-        message: `'${target}' is a shipped target - give the project target another name`,
-      }),
-    );
+  for (const file of findProjectMakefiles({ root: opts.root })) {
+    const targets = parseMakeTargets({ makefile: readText({ file: join(opts.root, file) }) });
+
+    for (const target of targets.filter(name => shipped.has(name))) {
+      violations.push(
+        createViolation({
+          check: DoctorChecks.MAKE,
+          file,
+          message: `'${target}' is a shipped target - give the project target another name`,
+        }),
+      );
+    }
   }
 
   return violations;

package/src/doctor/makefile.ts

@@ -6,3 +6,12 @@ export const parseMakeTargets = (opts: { makefile: string }): string[] =>
     .split('\n')
     .map(line => RULE_TARGET.exec(line)?.[1])
     .filter((target): target is string => target !== undefined);
+
+const INCLUDE_LINE = /^\s*(?:-include|sinclude|include)\s+(.+?)\s*$/;
+
+/** The paths and globs an `include`, `-include` or `sinclude` line names; one built from a variable is skipped. */
+export const parseMakeIncludes = (opts: { makefile: string }): string[] =>
+  opts.makefile
+    .split('\n')
+    .flatMap(line => INCLUDE_LINE.exec(line)?.[1].split(/\s+/) ?? [])
+    .filter(path => !path.includes('$('));

package/src/sync/planner.ts

@@ -19,6 +19,7 @@ import type { ISyncAction, TSettings } from './common/index.ts';
 import {
   buildProjectHookSettings,
   isSettingsObject,
+  keepKeyOrder,
   mergeSettings,
   removeManagedSettings,
 } from './settings.ts';
@@ -118,11 +119,13 @@ const planSettings = (opts: { root: string; config: TResolvedConfig }): ISyncAct
 
   const previous = readSettingsFile({ path: managedPath }) ?? {};
   const overlay = buildManagedOverlay({ config: opts.config });
-  const wanted = mergeSettings({
+  const merged = mergeSettings({
     base: removeManagedSettings({ settings: current, managed: previous }),
     overlay,
   });
 
+  const wanted = keepKeyOrder({ settings: merged, reference: current });
+
   const text = `${JSON.stringify(wanted, null, 2)}\n`;
   const managedText = `${JSON.stringify(overlay, null, 2)}\n`;
   const before = existsSync(path) ? readFileSync(path, 'utf8') : undefined;

package/src/sync/settings.ts

@@ -48,6 +48,37 @@ export const mergeSettings = (opts: { base: TSettings; overlay: TSettings }): TS
 
 const toKey = (opts: { value: unknown }): string => JSON.stringify(opts.value);
 
+/** `settings` with its keys in `reference`'s order: keys `reference` has keep their place, new keys follow. */
+const orderKeysLike = (opts: { settings: TSettings; reference: TSettings }): TSettings => {
+  const keys = [
+    ...Object.keys(opts.reference).filter(key => key in opts.settings),
+    ...Object.keys(opts.settings).filter(key => !(key in opts.reference)),
+  ];
+
+  return Object.fromEntries(keys.map(key => [key, opts.settings[key]]));
+};
+
+/**
+ * `settings` in the key order the user's file already has, here and one level down: a sync that only
+ * reorders keys rewrites the file, and `doctor` then calls a fresh sync stale.
+ */
+export const keepKeyOrder = (opts: { settings: TSettings; reference: TSettings }): TSettings => {
+  const ordered = orderKeysLike(opts);
+
+  for (const key of Object.keys(ordered).filter(entry =>
+    SyncConstants.MERGE_ONE_LEVEL.has(entry),
+  )) {
+    const value = { value: ordered[key] };
+    const previous = { value: opts.reference[key] };
+
+    if (isSettingsObject(value) && isSettingsObject(previous)) {
+      ordered[key] = orderKeysLike({ settings: value.value, reference: previous.value });
+    }
+  }
+
+  return ordered;
+};
+
 /** `settings` without what `managed` (the overlay of a previous sync) put there; anything else stays. */
 export const removeManagedSettings = (opts: {
   settings: TSettings;