genesis-compiler 1.7.4 → 1.7.6

package/docs/prompt-integration.md

@@ -198,6 +198,15 @@ init`. All receive the same short operating guide for a new session and after
 compaction. The Codex session hook sets `additionalContextLimit: 0` so native
 truncation cannot remove part of the bounded guide or host contribution.
 Codex and Claude Code use `SessionStart` for startup, resume, clear, and compact events.
+Claude's generated session hooks use `genesis hook session --claude-part <1-4>`.
+Claude caps each hook output at 10,000 characters, so four hooks deliver the
+unchanged guide in numbered parts below that limit. Empty parts emit nothing.
+A guide above 36,000 characters delivers an explicit guidance-unavailable
+warning instead of a partial guide. Claude does not enforce startup hook stop
+requests; this warning instructs the model to report the problem before work,
+and is not a runtime admission control. Turn guidance is already bounded at 512
+bytes and uses the ordinary turn command. This is provider transport only;
+composition and the host bridge remain shared.
 Claude settings preserve unrelated hooks and configuration. The common operating
 guide lists installed project skills and their canonical `.agents/skills/` paths;
 an agent reads the relevant skill before following its workflow. Genesis exposes

package/docs/templates.md

@@ -23,8 +23,8 @@ components or authored project contracts when no catalogue technology matches.
 The exact bootstrap allowlist is `GENESIS_BOOTSTRAP_PATHS` in
 `src/index/project-inspection.js`: the four core Markdown documents and version,
 the two derived Cities, Genesis's Codex/OpenCode integration files, its managed
-skills manifest, and the SKILL.md/openai.yaml pair for each of the three Genesis
-workflow skills. Whole `.agents/`, `.codex/`, or `genesis/` directories are not
+skills manifest, the relative Claude discovery link, and the SKILL.md/openai.yaml
+pair for each of the three Genesis workflow skills. Whole `.agents/`, `.codex/`, or `genesis/` directories are not
 exempt. A README, `.gitignore`, application manifest, unfamiliar source file, or
 custom agent tool counts as existing content. Ignored files also count, except
 installed `node_modules` dependencies. Source recognition does not depend on a
@@ -56,8 +56,14 @@ Each branch is a complete, current Genesis project with actual application
 source, dependency lockfile, setup/run contracts and focused checks.
 
 Applying fetches the explicitly named branch once, resolves its commit and reads
-its ordinary Git blobs into a temporary project. Genesis rejects links,
+its ordinary Git blobs into a temporary project. Genesis rejects arbitrary links,
 submodules, unsafe paths, dependencies and private dotenv files in the template.
+The only link exception is the exact generated Claude skill discovery link
+`.claude/skills/<name>` → `../../.agents/skills/<name>`. Incoming discovery links
+are omitted and regenerated from the canonical skill directories by initialization.
+Existing exact generated links are preserved and checked again before copying;
+links with another target remain rejected. A bare destination receives the same
+generated links without following links supplied by a template.
 It validates the prepared project before changing the destination. A project
 lock serializes competing imports; the source and authored bootstrap files are
 checked again immediately before the copy. An ordinary copy failure rolls back

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.7.4",
+  "version": "1.7.6",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with project agent guidance.",
   "repository": {

package/src/cli.js

@@ -88,6 +88,7 @@ Options:
   --directory <path>     Parser cache directory (parsers commands only)
   --all                  Select every parser (parsers install/verify only)
   --json                 Emit one machine-readable result
+  --claude-part <1-4>    Emit one bounded Claude session-hook part
   -h, --help             Show this help
 
 Genesis generates prompts; it never starts or manages an AI agent. Give the
@@ -111,6 +112,7 @@ function parseCommand(argv) {
       strict: true,
       options: {
         json: { type: 'boolean', default: false },
+        'claude-part': { type: 'string' },
         all: { type: 'boolean', default: false },
         directory: { type: 'string' },
         'project-root': { type: 'string' },
@@ -124,6 +126,7 @@ function parseCommand(argv) {
   }
   const options = {
     json: parsed.values.json,
+    claudePart: parsed.values['claude-part'],
     all: parsed.values.all,
     directory: parsed.values.directory,
     projectRoot: parsed.values['project-root'],
@@ -138,6 +141,9 @@ function parseCommand(argv) {
     task: parsed.values.task,
   };
   const operands = parsed.positionals;
+  if (options.claudePart !== undefined && (command !== 'hook' || operands[0] !== 'session' || !/^[1-4]$/u.test(options.claudePart) || options.json)) {
+    fail('CLI_OPTION_NOT_APPLICABLE', 'Option --claude-part requires hook session, a part from 1 to 4, and no --json.');
+  }
   if (command !== 'parsers' && (options.all || options.directory !== undefined)) {
     fail('CLI_OPTION_NOT_APPLICABLE', 'Options --all and --directory apply only to parsers commands.');
   }
@@ -665,9 +671,24 @@ export async function runCli(argv = process.argv.slice(2)) {
       projectFormat,
       formatDiagnostic,
     );
-    if (options.json) line(process.stdout, JSON.stringify(result));
-    else {
-      writeResult(parsed.command, result);
+    if (options.claudePart !== undefined) {
+      // Claude spills each hook output over 10,000 characters to a file.
+      // Four native hooks deliver the exact text in bounded parts instead.
+      if (result.output.length > 36000) {
+        if (options.claudePart === '1') line(process.stdout,
+          'GENESIS GUIDANCE UNAVAILABLE: The session guide exceeds the Claude hook capacity of 36,000 characters. The guide was not delivered. Tell the user before doing project work. Shorten the project guidance and restart the conversation to load it completely.');
+        return 0;
+      }
+      let start = (Number(options.claudePart) - 1) * 9000;
+      let end = start + 9000;
+      // Keep UTF-16 surrogate pairs together at the shared part boundaries.
+      if (/[\uDC00-\uDFFF]/u.test(result.output[start] || '')) start--;
+      if (/[\uDC00-\uDFFF]/u.test(result.output[end] || '')) end--;
+      const part = result.output.slice(start, end);
+      if (part) process.stdout.write(`Genesis session guidance, part ${options.claudePart} of ${Math.ceil(result.output.length / 9000)} (read in numeric order):\n${part}`);
+    } else if (options.json) line(process.stdout, JSON.stringify(result));
+    else writeResult(parsed.command, result);
+    if (!options.json) {
       for (const warning of result.warnings || []) {
         if (warning.code !== formatDiagnostic?.code) line(process.stderr, `WARNING: ${warning.code}: ${warning.message}`);
       }

package/src/index/claude-hooks.js

@@ -7,8 +7,11 @@ import { genesisHookCommand } from './hook-command.js';
 import { writeFileAtomic } from './utils.js';
 
 const SETTINGS_PATH = '.claude/settings.json';
-const SESSION_COMMAND = genesisHookCommand('session');
+const SESSION_COMMANDS = [1, 2, 3, 4].map((claudePart) => genesisHookCommand('session', { claudePart }));
 const TURN_COMMAND = genesisHookCommand('turn');
+// Refresh exact generated commands, including the previous plain-text output.
+const OWNED_COMMANDS = new Set([...SESSION_COMMANDS, TURN_COMMAND,
+  genesisHookCommand('session')]);
 
 async function renderedSettings(projectRoot) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
@@ -34,13 +37,13 @@ async function renderedSettings(projectRoot) {
     }
     value.hooks[event] = groups.flatMap((group) => {
       if (!Array.isArray(group?.hooks)) return [group];
-      const hooks = group.hooks.filter((hook) => ![SESSION_COMMAND, TURN_COMMAND].includes(hook?.command));
+      const hooks = group.hooks.filter((hook) => !OWNED_COMMANDS.has(hook?.command));
       return hooks.length ? [{ ...group, hooks }] : [];
     });
   }
   (value.hooks.SessionStart ||= []).push({
     matcher: '^(startup|resume|clear|compact)$',
-    hooks: [{ type: 'command', command: SESSION_COMMAND, timeout: 30 }],
+    hooks: SESSION_COMMANDS.map((command) => ({ type: 'command', command, timeout: 30 })),
   });
   (value.hooks.UserPromptSubmit ||= []).push({
     hooks: [{ type: 'command', command: TURN_COMMAND, timeout: 30 }],
@@ -50,6 +53,11 @@ async function renderedSettings(projectRoot) {
 
 // Claude discovers .claude/skills; the canonical files remain in .agents/skills.
 // Only exact generated links are owned here. User-owned Claude skills win.
+export function claudeSkillLinkTarget(relative) {
+  const name = /^\.claude\/skills\/([^/\\]+)$/u.exec(relative)?.[1];
+  return name && name !== '.' && name !== '..' ? `../../.agents/skills/${name}` : null;
+}
+
 export async function claudeSkillLinks(root, write = false) {
   const [canonical, installed] = await Promise.all(['.agents/skills', '.claude/skills'].map(async (directory) => {
     try { return await readdir(path.join(root, directory), { withFileTypes: true }); }
@@ -62,7 +70,7 @@ export async function claudeSkillLinks(root, write = false) {
   for (const name of new Set([...names, ...existing.keys()])) {
     const relative = `.claude/skills/${name}`;
     const location = path.join(root, relative);
-    const target = `../../.agents/skills/${name}`;
+    const target = claudeSkillLinkTarget(relative);
     const entry = existing.get(name);
     const owned = entry?.isSymbolicLink() && await readlink(location) === target;
     if (!names.has(name)) {

package/src/index/hook-command.js

@@ -1,4 +1,4 @@
-export function genesisHookCommand(action) {
-  const local = `const {runCli}=await import('genesis-compiler/cli');process.exitCode=await runCli(['hook','${action}'])`;
-  return `if command -v genesis >/dev/null 2>&1; then genesis hook ${action}; else node --input-type=module --eval "${local}"; fi`;
+export function genesisHookCommand(action, { claudePart } = {}) {
+  const local = `const {runCli}=await import('genesis-compiler/cli');process.exitCode=await runCli(['hook','${action}'${claudePart ? `,'--claude-part','${claudePart}'` : ''}])`;
+  return `if command -v genesis >/dev/null 2>&1; then genesis hook ${action}${claudePart ? ` --claude-part ${claudePart}` : ''}; else node --input-type=module --eval "${local}"; fi`;
 }

package/src/index/template-project.js

@@ -1,4 +1,4 @@
-import { lstat, mkdir, mkdtemp, readFile, readdir, rm, rmdir, writeFile } from 'node:fs/promises';
+import { lstat, mkdir, mkdtemp, readFile, readdir, readlink, rm, rmdir, symlink, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { parseBlueprintSource } from './blueprint.js';
@@ -13,6 +13,7 @@ import { listTemplates, resolveTemplate } from './template-catalog.js';
 import { readGitSnapshot } from './template-source.js';
 import { readStack } from './stack.js';
 import { writeFileAtomic } from './utils.js';
+import { claudeSkillLinkTarget } from './claude-hooks.js';
 
 function sections(source) {
   const result = new Map();
@@ -43,8 +44,12 @@ async function existingFile(root, name) {
   const location = path.join(root, name);
   try {
     const state = await lstat(location);
+    if (state.isSymbolicLink()) {
+      const linkTarget = claudeSkillLinkTarget(name);
+      if (linkTarget && await readlink(location) === linkTarget) return { contents: Buffer.from(linkTarget), linkTarget };
+    }
     if (!state.isFile()) throw new GenesisError('TEMPLATE_DESTINATION_CONFLICT', `Template destination is not an ordinary file: ${name}.`);
-    return await readFile(location);
+    return { contents: await readFile(location), linkTarget: null };
   } catch (error) {
     if (error.code === 'ENOENT') return null;
     throw error;
@@ -57,7 +62,7 @@ async function filesBelow(root, relative = '') {
     if (!relative && entry.name === '.git') continue;
     const name = relative ? `${relative}/${entry.name}` : entry.name;
     if (entry.isDirectory()) files.push(...await filesBelow(root, name));
-    else if (entry.isFile()) files.push({ path: name, contents: await readFile(path.join(root, name)), mode: (await lstat(path.join(root, name))).mode & 0o111 ? 0o777 : 0o666 });
+    else if (entry.isFile() || entry.isSymbolicLink()) files.push({ path: name, ...await existingFile(root, name), mode: (await lstat(path.join(root, name))).mode & 0o111 ? 0o777 : 0o666 });
     else throw new GenesisError('TEMPLATE_TREE_INVALID', `Template contains a non-ordinary file: ${name}.`);
   }
   return files;
@@ -96,28 +101,34 @@ export async function applyTemplate({ projectRoot, templateId, stackPackages = [
       await mkdir(path.dirname(path.join(stagingRoot, file.path)), { recursive: true });
       await writeFile(path.join(stagingRoot, file.path), file.contents, { flag: 'wx', mode: file.mode });
     }
-    const stackSource = await existingFile(stagingRoot, 'genesis/stack.md');
-    if (!stackSource) throw new GenesisError('TEMPLATE_STACK_REQUIRED', 'A template must contain its complete genesis/stack.md.');
+    const stackFile = await existingFile(stagingRoot, 'genesis/stack.md');
+    if (!stackFile) throw new GenesisError('TEMPLATE_STACK_REQUIRED', 'A template must contain its complete genesis/stack.md.');
     const seedStack = await readStack(stagingRoot, { stackPackages });
     if (!seedStack.components.some(({ id }) => id === template.technology)) {
       throw new GenesisError('TEMPLATE_STACK_MISMATCH', 'The template Stack does not contain its advertised technology.');
     }
-    for (const [name, contents] of preserved) {
-      if (contents === null || name.startsWith('.genesis/')) continue;
+    for (const [name, previous] of preserved) {
+      if (previous === null || name.startsWith('.genesis/')) continue;
+      const { contents, linkTarget } = previous;
       if (name === 'genesis/blueprint.md' && !parseBlueprintSource(contents.toString('utf8')).description) continue;
       let value = contents;
-      if (name === 'genesis/stack.md') value = mergeTemplateStack(stackSource.toString('utf8'), contents.toString('utf8'));
-      await mkdir(path.dirname(path.join(stagingRoot, name)), { recursive: true });
-      await writeFile(path.join(stagingRoot, name), value);
+      if (name === 'genesis/stack.md') value = mergeTemplateStack(stackFile.contents.toString('utf8'), contents.toString('utf8'));
+      const location = path.join(stagingRoot, name);
+      await mkdir(path.dirname(location), { recursive: true });
+      if (linkTarget) {
+        await rm(location, { force: true });
+        await symlink(linkTarget, location, 'dir');
+      } else await writeFile(location, value);
     }
     await initializeProject({ projectRoot: stagingRoot, stackPackages });
     await buildProjectIndex({ projectRoot: stagingRoot, stackPackages });
     const prepared = await inspectProject({ projectRoot: stagingRoot, stackPackages });
     if (prepared.state !== 'ready') throw new GenesisError('TEMPLATE_PROJECT_INVALID', 'The prepared template does not contain a usable Genesis project.', { inspection: prepared });
     await assertSeedable(root, stackPackages);
-    for (const [name, contents] of preserved) {
+    for (const [name, previous] of preserved) {
       const current = await existingFile(root, name);
-      if ((contents === null) !== (current === null) || contents && !contents.equals(current)) {
+      if ((previous === null) !== (current === null) || previous &&
+        (previous.linkTarget !== current.linkTarget || !previous.contents.equals(current.contents))) {
         throw new GenesisError('TEMPLATE_DESTINATION_CHANGED', 'Project context changed while the template was being prepared. Nothing was applied.');
       }
     }
@@ -126,16 +137,19 @@ export async function applyTemplate({ projectRoot, templateId, stackPackages = [
     try {
       for (const file of files) {
         const previous = await existingFile(root, file.path);
-        if (previous && previous.equals(file.contents)) continue;
+        if (previous && previous.linkTarget === file.linkTarget && previous.contents.equals(file.contents)) continue;
         if (previous && !preserved.has(file.path)) throw new GenesisError('TEMPLATE_DESTINATION_CHANGED', `Existing project content was preserved: ${file.path}.`);
         await mkdir(path.dirname(path.join(root, file.path)), { recursive: true });
-        if (previous) await writeFileAtomic(path.join(root, file.path), file.contents);
+        if (file.linkTarget || previous?.linkTarget) {
+          if (previous) throw new GenesisError('TEMPLATE_DESTINATION_CHANGED', `Existing project link was preserved: ${file.path}.`);
+          await symlink(file.linkTarget, path.join(root, file.path), 'dir');
+        } else if (previous) await writeFileAtomic(path.join(root, file.path), file.contents);
         else await writeFile(path.join(root, file.path), file.contents, { flag: 'wx', mode: file.mode });
         applied.push({ path: file.path, previous });
       }
     } catch (error) {
       for (const file of applied.reverse()) {
-        if (file.previous) await writeFileAtomic(path.join(root, file.path), file.previous);
+        if (file.previous) await writeFileAtomic(path.join(root, file.path), file.previous.contents);
         else await rm(path.join(root, file.path));
       }
       throw error;

package/src/index/template-source.js

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { GenesisError } from './errors.js';
 import { runGit, runGitText } from './process.js';
+import { claudeSkillLinkTarget } from './claude-hooks.js';
 
 function validateRepository(repository) {
   if (typeof repository !== 'string' || !repository || repository.startsWith('-')) {
@@ -35,11 +36,19 @@ export async function readGitSnapshot({ repository, branch }) {
       const separator = item.indexOf('\t');
       const [mode, type, object] = item.slice(0, separator).split(' ');
       const name = item.slice(separator + 1);
-      if (!['100644', '100755'].includes(mode) || type !== 'blob' || path.isAbsolute(name)
+      if (!['100644', '100755', '120000'].includes(mode) || type !== 'blob' || path.isAbsolute(name)
         || name.includes('\\') || name.split('/').some((part) => !part || ['.', '..', '.git'].includes(part.toLowerCase()))) {
         throw new GenesisError('TEMPLATE_TREE_INVALID', `Template contains an unsupported path or file: ${name}.`);
       }
       const blob = await runGit(temporaryRoot, ['cat-file', 'blob', object]);
+      if (mode === '120000') {
+        const target = claudeSkillLinkTarget(name);
+        if (!target || !blob.stdout.equals(Buffer.from(target))) {
+          throw new GenesisError('TEMPLATE_TREE_INVALID', `Template contains an unsupported link: ${name}.`);
+        }
+        // Regenerate these through initialization from the canonical skill files.
+        continue;
+      }
       bytes += blob.stdout.length;
       if (bytes > 64 * 1024 * 1024 || files.length >= 10_000) {
         throw new GenesisError('TEMPLATE_TREE_TOO_LARGE', 'Template exceeds the source size limit.');