@venizia/vulcan 0.1.0-2 → 0.2.0-1

package/src/doctor/checks.ts

@@ -2,9 +2,17 @@ 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';
+import { resolvePackages } from '../config/index.ts';
 import type { TResolvedConfig } from '../config/index.ts';
-import { parseRuleIds, readSlots, RuleConstants } from '../rules/index.ts';
-import { planSync, SyncStatuses } from '../sync/index.ts';
+import {
+  parseBaseReferences,
+  readBaseRules,
+  readRetiredRuleIds,
+  readSlots,
+  RuleConstants,
+} from '../rules/index.ts';
+import { ManifestConstants, projectNameOf } from '../manifest/index.ts';
+import { planManifest, planPrune, planSync, SyncStatuses } from '../sync/index.ts';
 import { DoctorChecks, DoctorConstants } from './common/index.ts';
 import type { IViolation, TDoctorCheck } from './common/index.ts';
 import { parseMakeIncludes, parseMakeTargets } from './makefile.ts';
@@ -46,17 +54,28 @@ export const checkLayout = (opts: ICheckContext): IViolation[] =>
       }),
     );
 
-/** The base owns the `V-` namespace; a project's own IDs stay bare and can reuse any letter and number. */
-export const checkRuleIds = (opts: ICheckContext): IViolation[] =>
-  parseRuleIds({ markdown: readText({ file: join(opts.root, '.agents', 'rules.md') }) })
-    .filter(id => id.startsWith(RuleConstants.BASE_NAMESPACE))
+/**
+ * The base owns the `V-` namespace: a project defines its rules with bare IDs, and a `V-` ID in its
+ * rules points at a base rule - one the base does not carry, or has retired, dangles.
+ */
+export const checkRuleIds = (opts: ICheckContext): IViolation[] => {
+  const base = readBaseRules();
+  const retired = new Set(readRetiredRuleIds());
+
+  return parseBaseReferences({
+    markdown: readText({ file: join(opts.root, '.agents', 'rules.md') }),
+  })
+    .filter(id => base[id] === undefined)
     .map(id =>
       createViolation({
         check: DoctorChecks.RULE_IDS,
         file: '.agents/rules.md',
-        message: `${id} is in the base namespace ${RuleConstants.BASE_NAMESPACE} - give the extension a bare ID`,
+        message: retired.has(id)
+          ? `${id} is retired in the base - drop the reference`
+          : `${id} is not a base rule - give the extension a bare ID`,
       }),
     );
+};
 
 export const checkRuleSlots = (opts: ICheckContext): IViolation[] => {
   const slots = readSlots();
@@ -115,7 +134,7 @@ export const checkSkills = (opts: ICheckContext): IViolation[] => {
       createViolation({
         check: DoctorChecks.SKILLS,
         file: `.agents/skills/${name}`,
-        message: `'${name}' is a shipped skill - rename the project skill`,
+        message: `'${name}' is a shipped skill - rename the project skill, for example to '${projectNameOf({ root: opts.root, config: opts.config })}-${name}'`,
       }),
     );
 };
@@ -198,6 +217,7 @@ export const checkHooks = (opts: ICheckContext): IViolation[] =>
 export const checkAdapters = (opts: ICheckContext): IViolation[] =>
   planSync({ root: opts.root, config: opts.config })
     .filter(action => action.status !== SyncStatuses.UNCHANGED)
+    .filter(action => action.path !== join(opts.root, ManifestConstants.FILE))
     .map(action =>
       createViolation({
         check: DoctorChecks.ADAPTERS,
@@ -209,8 +229,33 @@ export const checkAdapters = (opts: ICheckContext): IViolation[] =>
       }),
     );
 
-const hasStylePackage = (opts: { root: string }): boolean => {
-  const file = join(opts.root, 'package.json');
+/** What `sync --prune` would remove: an old VULCAN or plugin-era hook command, a dead skill link. */
+export const checkPrune = (opts: ICheckContext): IViolation[] =>
+  planPrune({ root: opts.root }).map(action =>
+    createViolation({
+      check: DoctorChecks.PRUNE,
+      file: relative(opts.root, action.path),
+      message: `${action.note ?? 'stale'} - run '${ProjectLayout.VULCAN_COMMAND} sync --prune'`,
+    }),
+  );
+
+/** C1: the committed manifest is what the config renders - atlas reads the file, never the config. */
+export const checkManifest = (opts: ICheckContext): IViolation[] => {
+  const action = planManifest({ root: opts.root, config: opts.config });
+
+  return action.status === SyncStatuses.UNCHANGED
+    ? []
+    : [
+        createViolation({
+          check: DoctorChecks.MANIFEST,
+          file: ManifestConstants.FILE,
+          message: `${action.status === SyncStatuses.CREATED ? 'missing' : 'stale against the config'} - run '${ProjectLayout.VULCAN_COMMAND} sync' and commit it`,
+        }),
+      ];
+};
+
+const hasStylePackage = (opts: { directory: string }): boolean => {
+  const file = join(opts.directory, 'package.json');
 
   if (!existsSync(file)) {
     return false;
@@ -224,31 +269,52 @@ const hasStylePackage = (opts: { root: string }): boolean => {
   return ProjectLayout.STYLE_PACKAGE in { ...manifest.dependencies, ...manifest.devDependencies };
 };
 
-/** D9: the shared coding style - the package is a dependency, and every lint config builds on it. */
+/**
+ * D9: the shared coding style - every lint config builds on it, and the package whose `.configs/`
+ * holds the config declares it, or the root does. A project with no lint config declares it at the
+ * root. Owners are `packages/*` and every configured package's `path`, such as `umbras/kit`.
+ */
 export const checkStyle = (opts: ICheckContext): IViolation[] => {
   const violations: IViolation[] = [];
-
-  if (!hasStylePackage({ root: opts.root })) {
-    violations.push(
-      createViolation({
-        check: DoctorChecks.STYLE,
-        file: 'package.json',
-        message: `add ${ProjectLayout.STYLE_PACKAGE} as a devDependency`,
-      }),
-    );
-  }
-
-  const configDirectories = [
-    '.configs',
-    ...listDirectories({ directory: join(opts.root, 'packages') }).map(name =>
-      join('packages', name, '.configs'),
-    ),
+  const owners = [
+    ...new Set([
+      '.',
+      ...listDirectories({ directory: join(opts.root, 'packages') }).map(name =>
+        join('packages', name),
+      ),
+      ...resolvePackages({ config: opts.config }).map(
+        entry => relative(opts.root, join(opts.root, entry.path)) || '.',
+      ),
+    ]),
   ];
+  const isRootDeclared = hasStylePackage({ directory: opts.root });
+  let lintConfigs = 0;
+
+  for (const owner of owners) {
+    const directory = join(owner, '.configs');
+    const names = existsSync(join(opts.root, directory))
+      ? readdirSync(join(opts.root, directory)).filter(file =>
+          DoctorConstants.LINT_CONFIG_FILE.test(file),
+        )
+      : [];
+
+    lintConfigs += names.length;
+
+    if (
+      names.length > 0 &&
+      !isRootDeclared &&
+      !hasStylePackage({ directory: join(opts.root, owner) })
+    ) {
+      violations.push(
+        createViolation({
+          check: DoctorChecks.STYLE,
+          file: join(owner, 'package.json'),
+          message: `add ${ProjectLayout.STYLE_PACKAGE} as a devDependency - here, or at the root`,
+        }),
+      );
+    }
 
-  for (const directory of configDirectories.filter(path => existsSync(join(opts.root, path)))) {
-    for (const name of readdirSync(join(opts.root, directory)).filter(file =>
-      DoctorConstants.LINT_CONFIG_FILE.test(file),
-    )) {
+    for (const name of names) {
       const file = join(directory, name);
 
       if (!readText({ file: join(opts.root, file) }).includes(ProjectLayout.STYLE_PACKAGE)) {
@@ -263,5 +329,15 @@ export const checkStyle = (opts: ICheckContext): IViolation[] => {
     }
   }
 
+  if (lintConfigs === 0 && !isRootDeclared) {
+    violations.push(
+      createViolation({
+        check: DoctorChecks.STYLE,
+        file: 'package.json',
+        message: `add ${ProjectLayout.STYLE_PACKAGE} as a devDependency`,
+      }),
+    );
+  }
+
   return violations;
 };

package/src/doctor/common/constants.ts

@@ -8,6 +8,9 @@ export class DoctorChecks {
   static readonly HOOKS = 'hooks';
   static readonly ADAPTERS = 'adapters';
   static readonly STYLE = 'style';
+  static readonly MANIFEST = 'manifest';
+  static readonly TAGS = 'tags';
+  static readonly PRUNE = 'prune';
   static readonly SCHEME_SET = new Set<string>([
     this.CONFIG,
     this.LAYOUT,
@@ -18,6 +21,9 @@ export class DoctorChecks {
     this.HOOKS,
     this.ADAPTERS,
     this.STYLE,
+    this.MANIFEST,
+    this.TAGS,
+    this.PRUNE,
   ]);
   static isValid(value: string): boolean {
     return this.SCHEME_SET.has(value);

package/src/doctor/index.ts

@@ -2,3 +2,4 @@ export * from './checks.ts';
 export * from './common/index.ts';
 export * from './makefile.ts';
 export * from './runner.ts';
+export * from './skills.ts';

package/src/doctor/runner.ts

@@ -2,6 +2,8 @@ import { relative } from 'node:path';
 import { loadConfig } from '../config/index.ts';
 import {
   checkAdapters,
+  checkManifest,
+  checkPrune,
   checkHooks,
   checkLayout,
   checkMake,
@@ -10,6 +12,8 @@ import {
   checkSkills,
   checkStyle,
 } from './checks.ts';
+import { checkSkillLint } from './skills.ts';
+import { checkTags } from './tags.ts';
 import { DoctorChecks } from './common/index.ts';
 import type { IViolation } from './common/index.ts';
 
@@ -41,6 +45,10 @@ export const runDoctorChecks = async (opts: { root: string }): Promise<IViolatio
     ...checkMake(context),
     ...checkHooks(context),
     ...checkAdapters(context),
+    ...checkPrune(context),
+    ...checkManifest(context),
+    ...checkTags(context),
+    ...checkSkillLint(context),
     ...checkStyle(context),
   ];
 };

package/src/doctor/skills.ts

@@ -0,0 +1,157 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import type { ICheckContext } from './checks.ts';
+import { DoctorChecks } from './common/index.ts';
+import type { IViolation } from './common/index.ts';
+
+/**
+ * Anthropic's skill-authoring rules (platform.claude.com, Agent Skills best practices), as checks:
+ * the frontmatter limits, SKILL.md under 500 lines, a contents list in any file past 100 lines (an
+ * agent may preview only the first lines), references one level deep from SKILL.md, and named
+ * requirements for a skill that runs scripts.
+ */
+const NAME_PATTERN = /^[a-z0-9-]{1,64}$/;
+const RESERVED_NAME = /claude|anthropic/;
+const XML_TAG = /<\/?[a-zA-Z][^>]*>/;
+const MAX_DESCRIPTION = 1024;
+const MAX_BODY_LINES = 500;
+const CONTENTS_AFTER_LINES = 100;
+const CONTENTS_WITHIN_LINES = 30;
+const CONTENTS_MARK = /^(\*\*Contents\*\*|#{2,3} Contents|<!-- okf:generated:contents start -->)/;
+const MARKDOWN_LINK = /\]\(([^)#\s]+\.md)(?:#[^)]*)?\)/g;
+const SCRIPT = /\.(js|mjs|ts|py|sh)$/;
+const REQUIREMENTS = /^## (Requirements|Prerequisites)\b/m;
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n/;
+
+const filesOf = (opts: { directory: string }): string[] =>
+  readdirSync(opts.directory).flatMap(name => {
+    const path = join(opts.directory, name);
+
+    return statSync(path).isDirectory() ? filesOf({ directory: path }) : [path];
+  });
+
+const lineCountOf = (opts: { text: string }): number =>
+  opts.text.replace(/\n$/, '').split('\n').length;
+
+const frontmatterOf = (opts: { text: string }): Record<string, unknown> => {
+  const block = FRONTMATTER.exec(opts.text)?.[1];
+  const parsed: unknown = block === undefined ? undefined : Bun.YAML.parse(block);
+
+  return typeof parsed === 'object' && parsed !== null
+    ? Object.fromEntries(Object.entries(parsed))
+    : {};
+};
+
+/** Every rule one skill directory breaks, each a message naming the file. */
+export const lintSkill = (opts: { directory: string }): string[] => {
+  const skillFile = join(opts.directory, 'SKILL.md');
+
+  if (!existsSync(skillFile)) {
+    return ['SKILL.md is missing'];
+  }
+
+  const problems: string[] = [];
+  const text = readFileSync(skillFile, 'utf8');
+  const frontmatter = frontmatterOf({ text });
+  const { name, description } = frontmatter;
+
+  if (typeof name !== 'string' || !NAME_PATTERN.test(name) || RESERVED_NAME.test(name)) {
+    problems.push(
+      `SKILL.md: name '${String(name)}' - at most 64 characters of a-z, 0-9 and hyphens, never 'claude' or 'anthropic'`,
+    );
+  }
+
+  if (
+    typeof description !== 'string' ||
+    description.trim().length === 0 ||
+    description.length > MAX_DESCRIPTION ||
+    XML_TAG.test(description)
+  ) {
+    problems.push('SKILL.md: the description must be 1-1024 characters with no XML tags');
+  }
+
+  const body = text.slice(FRONTMATTER.exec(text)?.[0].length ?? 0);
+  const bodyLines = lineCountOf({ text: body });
+
+  if (bodyLines >= MAX_BODY_LINES) {
+    problems.push(
+      `SKILL.md: the body is ${bodyLines} lines - keep it under ${MAX_BODY_LINES}, move detail into reference files`,
+    );
+  }
+
+  const files = filesOf({ directory: opts.directory }).sort();
+  const shown = (path: string): string => relative(opts.directory, path);
+
+  for (const file of files.filter(path => path.endsWith('.md'))) {
+    const content = readFileSync(file, 'utf8');
+    const count = lineCountOf({ text: content });
+    const opening = content.split('\n').slice(0, CONTENTS_WITHIN_LINES);
+
+    if (count > CONTENTS_AFTER_LINES && !opening.some(line => CONTENTS_MARK.test(line))) {
+      problems.push(
+        `${shown(file)}: ${count} lines and no contents list in its first ${CONTENTS_WITHIN_LINES} lines - an agent may read only the first lines`,
+      );
+    }
+
+    if (file === skillFile) {
+      continue;
+    }
+
+    for (const match of content.matchAll(MARKDOWN_LINK)) {
+      const target = resolve(dirname(file), match[1]);
+
+      if (target !== skillFile && target.startsWith(`${opts.directory}/`) && existsSync(target)) {
+        problems.push(
+          `${shown(file)} links ${shown(target)} - link every reference from SKILL.md, one level deep`,
+        );
+      }
+    }
+  }
+
+  if (files.some(path => SCRIPT.test(path)) && !REQUIREMENTS.test(text)) {
+    problems.push(
+      'SKILL.md: the skill runs scripts and has no ## Requirements section - name what they need',
+    );
+  }
+
+  return problems;
+};
+
+/** The project's own skills, linted; a nested one is reported - sync links flat skills only. */
+export const checkSkillLint = (opts: ICheckContext): IViolation[] => {
+  const skills = join(opts.root, '.agents', 'skills');
+
+  if (!existsSync(skills)) {
+    return [];
+  }
+
+  return readdirSync(skills)
+    .filter(name => statSync(join(skills, name)).isDirectory())
+    .sort()
+    .flatMap(name => {
+      const directory = join(skills, name);
+      const file = `.agents/skills/${name}`;
+
+      if (!existsSync(join(directory, 'SKILL.md'))) {
+        const inner = readdirSync(directory).find(child =>
+          existsSync(join(directory, child, 'SKILL.md')),
+        );
+
+        return inner === undefined
+          ? []
+          : [
+              {
+                check: DoctorChecks.SKILLS,
+                file,
+                message: `skills are flat - sync links .agents/skills/<name> only; move ${name}/${inner} up to .agents/skills/${inner}`,
+              },
+            ];
+      }
+
+      return lintSkill({ directory }).map(message => ({
+        check: DoctorChecks.SKILLS,
+        file,
+        message,
+      }));
+    });
+};

package/src/doctor/tags.ts

@@ -0,0 +1,79 @@
+import { spawnSync } from 'node:child_process';
+import { resolvePackages } from '../config/index.ts';
+import type { ICheckContext } from './checks.ts';
+import { DoctorChecks } from './common/index.ts';
+import type { IViolation } from './common/index.ts';
+
+const escapeLiteral = (opts: { text: string }): string =>
+  opts.text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** The tag pattern as a regular expression that captures `<dir>` (or `<package>`). */
+const tagPatternOf = (opts: { template: string }): RegExp =>
+  new RegExp(
+    `^${opts.template
+      .split(/(<(?:dir|package|version|date)>)/)
+      .map(part => {
+        switch (part) {
+          case '<dir>':
+          case '<package>': {
+            return '(?<dir>[a-z0-9][a-z0-9.-]*)';
+          }
+
+          case '<version>': {
+            return '\\S+';
+          }
+
+          case '<date>': {
+            return '\\d{4}-\\d{2}-\\d{2}';
+          }
+
+          default: {
+            return escapeLiteral({ text: part });
+          }
+        }
+      })
+      .join('')}$`,
+  );
+
+/**
+ * Project Contract v1, C4: every tag `atlas.tagPattern` reads names a declared package - by
+ * directory or alias, retired ones included - because atlas computes releases from the tags. A tag
+ * of an old layout is ignored through `atlas.ignoreTags`. A repo-level pattern (no `<dir>`) has
+ * nothing to check; a directory that is not a git repository has no tags.
+ */
+export const checkTags = (opts: ICheckContext): IViolation[] => {
+  const template = opts.config.atlas.tagPattern;
+
+  if (!/<(?:dir|package)>/.test(template)) {
+    return [];
+  }
+
+  const listed = spawnSync('git', ['tag', '--list'], { cwd: opts.root, encoding: 'utf8' });
+
+  if (listed.status !== 0) {
+    return [];
+  }
+
+  const pattern = tagPatternOf({ template });
+  const ignored = (opts.config.atlas.ignoreTags ?? []).map(glob => new Bun.Glob(glob));
+  const names = new Set(
+    resolvePackages({ config: opts.config }).flatMap(entry => [entry.dir, ...entry.aliases]),
+  );
+
+  return listed.stdout
+    .split('\n')
+    .filter(tag => tag.length > 0 && !ignored.some(glob => glob.match(tag)))
+    .flatMap(tag => {
+      const dir = pattern.exec(tag)?.groups?.dir;
+
+      return dir === undefined || names.has(dir)
+        ? []
+        : [
+            {
+              check: DoctorChecks.TAGS,
+              file: 'git tags',
+              message: `tag ${tag} reads as a release of '${dir}', which no package declares - declare it (retired: true if it is gone), add it as an alias, or ignore the tag (atlas.ignoreTags)`,
+            },
+          ];
+    });
+};

package/src/hooks/session-digest.ts

@@ -1,28 +1,42 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { BASE_DIRECTORY, ProjectLayout } from '../common/index.ts';
-import { loadConfig } from '../config/index.ts';
-import { extractRuleRows, readSlots, RuleConstants } from '../rules/index.ts';
+import { ConfigConstants, loadConfig } from '../config/index.ts';
+import { extractRuleRows, parseRuleIds, readSlots, RuleConstants } from '../rules/index.ts';
 
-/** The base rules a session drops most; quoted from the rule file, so the digest cannot drift. */
-const OFTEN_DROPPED = ['V-B-03', 'V-P-05', 'V-P-06', 'V-B-04', 'V-W-04', 'V-C-02', 'V-C-10'];
+/** A project row whose first cell lists IDs - `| V-W-02, V-W-03 |` - elaborates those base rules. */
+const ID_LIST_ROW =
+  /^\|\s*(?:\*\*)?(?:[A-Z]+-)?[A-Z]-\d{2}(?:\*\*)?(?:\s*,\s*(?:\*\*)?(?:[A-Z]+-)?[A-Z]-\d{2}(?:\*\*)?)+\s*\|/;
+
+/** The project's own picture of itself, printed verbatim at session start. */
+const MINIMAP = /<!-- minimap-shape:start -->\n([\s\S]*?)\n?<!-- minimap-shape:end -->/;
 
 const TABLE_HEADER = ['| ID | Rule | Enforced by |', '|----|------|-------------|'];
 
+/** Each listed ID's row, plain or bold (`| **W-00** |`), quoted from its rule file so it cannot drift. */
 const selectRows = (opts: { rows: string[]; ids: string[] }): string[] =>
   opts.ids
-    .map(id => opts.rows.find(row => row.startsWith(`| ${id} |`)))
+    .map(id => opts.rows.find(row => parseRuleIds({ markdown: row })[0] === id))
     .filter((row): row is string => row !== undefined);
 
-const readRuleRows = (opts: { file: string }): string[] =>
-  existsSync(opts.file) ? extractRuleRows({ markdown: readFileSync(opts.file, 'utf8') }) : [];
+const readText = (opts: { file: string }): string =>
+  existsSync(opts.file) ? readFileSync(opts.file, 'utf8') : '';
 
 /** The SessionStart context: base write boundaries, this project's slot choices and own rules, the often-dropped rules. */
 export const buildSessionDigest = async (opts: { projectRoot: string }): Promise<string> => {
-  const baseRows = readRuleRows({ file: join(BASE_DIRECTORY, 'rules.md') });
-  const projectRows = readRuleRows({ file: join(opts.projectRoot, '.agents', 'rules.md') });
+  const baseRows = extractRuleRows({
+    markdown: readText({ file: join(BASE_DIRECTORY, 'rules.md') }),
+  });
+  const projectText = readText({ file: join(opts.projectRoot, '.agents', 'rules.md') });
+  const projectRows = projectText
+    .split('\n')
+    .filter(line => extractRuleRows({ markdown: line }).length > 0 || ID_LIST_ROW.test(line));
+  const minimap = MINIMAP.exec(projectText)?.[1].trim();
   const loaded = await loadConfig({ root: opts.projectRoot });
   const choices = loaded.ok ? loaded.config.rules : {};
+  const oftenDropped = loaded.ok
+    ? loaded.config.digest.oftenDropped
+    : ConfigConstants.DEFAULT_OFTEN_DROPPED;
 
   const slotRows = Object.entries(readSlots()).map(([id, slot]) => {
     const choice = choices[id];
@@ -53,12 +67,16 @@ export const buildSessionDigest = async (opts: { projectRoot: string }): Promise
     lines.push('', "## This project's own rules", '', ...TABLE_HEADER, ...projectRows);
   }
 
+  if (minimap !== undefined && minimap.length > 0) {
+    lines.push('', "## This project's minimap", '', minimap);
+  }
+
   lines.push(
     '',
     '## The rules sessions drop most',
     '',
     ...TABLE_HEADER,
-    ...selectRows({ rows: baseRows, ids: OFTEN_DROPPED }),
+    ...selectRows({ rows: [...baseRows, ...projectRows], ids: oftenDropped }),
   );
 
   return `${lines.join('\n')}\n`;

package/src/manifest/index.ts

@@ -0,0 +1 @@
+export * from './render.ts';

package/src/manifest/render.ts

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { resolvePackages } from '../config/index.ts';
+import type { TResolvedConfig } from '../config/index.ts';
+import { readBaseRules } from '../rules/index.ts';
+
+export class ManifestConstants {
+  /** Committed; what atlas reads from a project - local or fetched - and nothing else. */
+  static readonly FILE = '.agents/vulcan.manifest.json';
+  static readonly SCHEMA_VERSION = 1;
+  static readonly PROJECT_RULES = '.agents/rules.md';
+  static readonly ENV = 'VULCAN_MANIFEST';
+}
+
+const HASH_LENGTH = 8;
+
+/** `@acme/shop-workspace` gives `shop`; a project with no package name takes its directory's. */
+export const projectNameOf = (opts: { root: string; config: TResolvedConfig }): string => {
+  if (opts.config.name !== undefined) {
+    return opts.config.name;
+  }
+
+  const file = join(opts.root, 'package.json');
+  const manifest: { name?: unknown } = existsSync(file)
+    ? JSON.parse(readFileSync(file, 'utf8'))
+    : {};
+  const name = typeof manifest.name === 'string' ? manifest.name : basename(opts.root);
+
+  return name
+    .replace(/^@[^/]+\//, '')
+    .replace(/-workspace$/, '')
+    .toLowerCase();
+};
+
+/** Each base rule's ID with a hash of its row: a sync after an upgrade can say which rules changed. */
+export const buildBaseRuleHashes = (): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(readBaseRules()).map(([id, row]) => {
+      const hash = new Bun.CryptoHasher('sha256').update(row.trim()).digest('hex');
+
+      return [id, hash.slice(0, HASH_LENGTH)];
+    }),
+  );
+
+/**
+ * The project manifest (Project Contract v1, C1): data only, rendered from the config with a fixed
+ * key order, so the committed file is byte-stable and a stale one shows as a diff.
+ */
+export const renderManifest = (opts: { root: string; config: TResolvedConfig }): string => {
+  const { config } = opts;
+  const { wiki, changelogs, syncAreas } = config.knowledge;
+
+  const manifest = {
+    schemaVersion: ManifestConstants.SCHEMA_VERSION,
+    name: projectNameOf(opts),
+    packages: resolvePackages({ config }).map(entry => ({
+      name: entry.name,
+      dir: entry.dir,
+      path: entry.path,
+      aliases: entry.aliases,
+      retired: entry.retired,
+    })),
+    knowledge: {
+      bundle: config.knowledge.bundle,
+      ...(wiki === undefined ? {} : { wiki }),
+      ...(changelogs === undefined ? {} : { changelogs }),
+      ...(syncAreas === undefined ? {} : { syncAreas }),
+    },
+    release: {
+      tagPattern: config.atlas.tagPattern,
+      legacyTagPrefixes: config.atlas.legacyTagPrefixes ?? [],
+      ignoreTags: config.atlas.ignoreTags ?? [],
+    },
+    rules: { project: ManifestConstants.PROJECT_RULES, base: buildBaseRuleHashes() },
+    // The sources this project reads knowledge from (atlas, git mode); a project without any carries none.
+    ...(config.atlas.sources.length === 0 ? {} : { sources: config.atlas.sources }),
+  };
+
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+};

package/src/okf.ts

@@ -0,0 +1,13 @@
+/**
+ * `@venizia/vulcan/okf` - the okf renderer API for a project module. A project installs
+ * `@venizia/vulcan` alone; its okf is a dependency, not resolvable from the project, so the API is
+ * re-exported here.
+ */
+export { defineRenderer } from '@venizia/vulcan-okf';
+export type {
+  IRenderContext,
+  IRenderedFile,
+  IRenderer,
+  IRenderPage,
+  IRenderSource,
+} from '@venizia/vulcan-okf';