genesis-compiler 1.3.3 → 1.4.1

package/src/index/codex-hooks.js

@@ -4,7 +4,8 @@ import path from 'node:path';
 import { GenesisError } from './errors.js';
 import { gitContext } from './git.js';
 import { classifyProjectKind } from './project-files.js';
-import { pathState, writeFileAtomic } from './utils.js';
+import { writeFileAtomic } from './utils.js';
+import { inspectProjectFormatAtRoot } from './project-format.js';
 
 const HOOKS_PATH = '.codex/hooks.json';
 const LEGACY_GENESIS_HOOKS_DESCRIPTION = 'Genesis project hooks.';
@@ -18,7 +19,7 @@ function hookCommand(action) {
 const SESSION_HOOK = {
   event: 'SessionStart',
   group: {
-    matcher: '^(startup|clear|compact)$',
+    matcher: '^(startup|resume|clear|compact)$',
     hooks: [{
       type: 'command',
       command: hookCommand('session'),
@@ -107,7 +108,7 @@ export async function installCodexHooks({ projectRoot } = {}) {
 export async function codexAdoptionRecommendation({ projectRoot = process.cwd() } = {}) {
   let root;
   try { root = (await gitContext(projectRoot)).repositoryRoot; } catch { return { status: 'not-applicable', output: '' }; }
-  if ((await pathState(path.join(root, 'genesis/blueprint.md'))).exists) {
+  if ((await inspectProjectFormatAtRoot(root)).status !== 'uninitialized') {
     return { status: 'not-applicable', output: '' };
   }
   if (await classifyProjectKind({ projectRoot: root }) === 'new') {

package/src/index/collaboration.js

@@ -198,6 +198,10 @@ function collaborationCatalog() {
 
 function collaborationGuidance(value) {
   return [
+    'Apply the configured tone, response length, assumed experience, and explanation style to every user-facing message, including progress updates and final responses.',
+    'Match technical depth and terminology to the configured experience level. Report concrete changes, findings, decisions, or blockers at that level of detail.',
+    'Do not announce that you are following project, UI, Stack, or Agent Skill guidance, or add unsolicited assurances about unrelated behavior staying unchanged. Explain process or scope when the user asks or it matters to a decision or blocker, using the configured style.',
+    '',
     '## Tone',
     '',
     DIMENSIONS.tone[value.tone].guidance,

package/src/index/contracts.js

@@ -1,4 +1,7 @@
 export const GENESIS_CONTRACTS = Object.freeze({
+  projectInspection: 'genesis.project-inspection.v1',
+  templates: 'genesis.templates.v1',
+  templateApplication: 'genesis.template-application.v1',
   collaboration: 'genesis.collaboration.v1',
   derivedArtifacts: 'genesis.derived-artifacts.v1',
   engineering: 'genesis.engineering.v1',

package/src/index/process.js

@@ -210,6 +210,8 @@ export async function runGit(cwd, args, options = {}) {
       ...options.env,
     }),
     maxBytes: options.maxBytes,
+    timeoutMs: options.timeoutMs,
+    signal: options.signal,
     code: options.code || 'GIT_EXEC_FAILED',
   });
 }

package/src/index/project-files.js

@@ -1,8 +1,8 @@
 import path from 'node:path';
 
-import { isProjectContentPath, OPENCODE_PLUGIN_PATH } from './paths.js';
 import { runGit } from './process.js';
 import { pathState } from './utils.js';
+import { inspectProjectContent } from './project-inspection.js';
 
 async function visiblePaths(projectRoot) {
   const [visible, deleted] = await Promise.all([
@@ -25,12 +25,7 @@ export async function gitVisibleFileStates(projectRoot, { includePath = () => tr
 }
 
 /** Classifies opening behavior from cheap Git-visible paths and selected Stack state. */
-export async function classifyProjectKind({ projectRoot, stackComponents = [] } = {}) {
-  if (stackComponents.length > 0) return 'existing';
-  const existing = (await visiblePaths(projectRoot)).some((file) => (
-    isProjectContentPath(file)
-    && file !== OPENCODE_PLUGIN_PATH
-    && !file.split('/').includes('node_modules')
-  ));
-  return existing ? 'existing' : 'new';
+export async function classifyProjectKind({ projectRoot } = {}) {
+  const content = await inspectProjectContent(projectRoot);
+  return content.kind === 'existing' ? 'existing' : 'new';
 }

package/src/index/project-inspection.js

@@ -0,0 +1,107 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { readBlueprint } from './blueprint.js';
+import { readCollaboration } from './collaboration.js';
+import { GENESIS_CONTRACTS } from './contracts.js';
+import { readEngineering } from './engineering.js';
+import { asDiagnostic } from './errors.js';
+import { gitContext } from './git.js';
+import { inspectProjectFormatAtRoot, projectFormatDiagnostic } from './project-format.js';
+import { inspectProgram } from './program.js';
+import { runGit } from './process.js';
+import { readStack } from './stack.js';
+
+// These are initialization outputs, not whole directories that may contain user code.
+export const GENESIS_BOOTSTRAP_PATHS = Object.freeze([
+  'genesis/version',
+  'genesis/blueprint.md',
+  'genesis/stack.md',
+  'genesis/collaboration.md',
+  'genesis/engineering.md',
+  '.genesis/machine-city.json',
+  '.genesis/program-city.json',
+  '.codex/hooks.json',
+  '.opencode/plugins/genesis-project-guidance.js',
+  '.agents/skills/.genesis-managed.json',
+  ...['genesis-project', 'genesis-program', 'genesis-deslop'].flatMap((name) => [
+    `.agents/skills/${name}/SKILL.md`,
+    `.agents/skills/${name}/agents/openai.yaml`,
+  ]),
+]);
+const bootstrapPaths = new Set(GENESIS_BOOTSTRAP_PATHS);
+
+export async function inspectProjectContent(projectRoot) {
+  const [visible, deleted, ignored] = await Promise.all([
+    runGit(projectRoot, ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', '.']),
+    runGit(projectRoot, ['ls-files', '-z', '--deleted', '--', '.']),
+    runGit(projectRoot, ['ls-files', '-z', '--others', '--ignored', '--exclude-standard', '--', '.']),
+  ]);
+  const absent = new Set(deleted.stdout.toString('utf8').split('\0').filter(Boolean));
+  const paths = [...new Set([visible, ignored].flatMap(({ stdout }) => stdout.toString('utf8').split('\0').filter(Boolean)))]
+    .filter((file) => !absent.has(file) && file !== '.git' && !file.startsWith('.git/'))
+    .sort();
+  const existingPaths = paths.filter((file) => !bootstrapPaths.has(file) && !file.split('/').includes('node_modules'));
+  return {
+    kind: existingPaths.length ? 'existing' : paths.length ? 'bootstrap' : 'empty',
+    existingPaths,
+    paths,
+  };
+}
+
+/** Read-only opening inspection: no index generation, verification, or application execution. */
+export async function inspectProject({ projectRoot, stackPackages = [] } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const [content, format] = await Promise.all([
+    inspectProjectContent(root),
+    inspectProjectFormatAtRoot(root),
+  ]);
+  const result = {
+    contract: GENESIS_CONTRACTS.projectInspection,
+    state: 'attention',
+    content: { kind: content.kind, count: content.existingPaths.length },
+    projectFormat: format,
+    templateEligible: false,
+    stackComponents: [],
+    diagnostics: [],
+    nextAction: 'repair',
+  };
+  if (!['uninitialized', 'current'].includes(format.status)) {
+    result.nextAction = format.action;
+    result.diagnostics = [projectFormatDiagnostic(format)];
+    return result;
+  }
+  if (format.status === 'uninitialized') {
+    return { ...result,
+      state: content.kind === 'existing' ? 'adoption' : 'new',
+      templateEligible: content.kind !== 'existing',
+      nextAction: content.kind === 'existing' ? 'adopt' : 'init',
+    };
+  }
+
+  let blueprintEmpty = false;
+  try {
+    const blueprint = await readBlueprint(root, { required: true });
+    blueprintEmpty = !blueprint.description;
+  } catch (error) { result.diagnostics.push(asDiagnostic(error)); }
+  let stack;
+  try {
+    // Missing Stack must not be hidden by readStack's optional default.
+    await readFile(path.join(root, 'genesis/stack.md'), 'utf8');
+    stack = await readStack(root, { stackPackages });
+    result.stackComponents = stack.components.map(({ id }) => id);
+  } catch (error) { result.diagnostics.push(asDiagnostic(error)); }
+  for (const read of [readCollaboration, readEngineering]) {
+    try { await read(root); } catch (error) { result.diagnostics.push(asDiagnostic(error)); }
+  }
+  try { await inspectProgram(root); } catch (error) { result.diagnostics.push(asDiagnostic(error)); }
+  if (result.diagnostics.length) return result;
+  if (content.kind !== 'existing') {
+    return { ...result, state: 'new', templateEligible: true, nextAction: 'create' };
+  }
+  const stackDescribed = stack.components.length > 0 || stack.projectContracts.some(({ lines }) => lines.some((line) => line.trim()));
+  if (blueprintEmpty || !stackDescribed) {
+    return { ...result, state: 'adoption', nextAction: 'adopt' };
+  }
+  return { ...result, state: 'ready', nextAction: 'work' };
+}

package/src/index/prompt.js

@@ -20,13 +20,14 @@ import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { stableJson } from './utils.js';
 import { classifyProjectKind } from './project-files.js';
 import { inspectProjectFormatAtRoot } from './project-format.js';
+import { inspectProject } from './project-inspection.js';
 
 const TASKS = new Set(['start', 'adopt', 'work', 'deslop', 'program', 'blueprint', 'describe', 'review']);
 const DEFAULT_REQUEST = {
   start: 'Start a conversation about this project.',
   adopt: 'Import the existing project into a truthful Genesis project contract.',
   work: 'Implement the product intent expressed by the current Blueprint.',
-  deslop: 'Deslop the latest commit.',
+  deslop: 'Deslop your own changes for the current task.',
   program: 'Refresh the complete useful Program for the code that exists now.',
   describe: 'Create or refresh the complete Blueprint and useful Program for the codebase that exists now.',
   review: 'Review the complete useful relationship between Blueprint, code, Program, and tests.',
@@ -284,6 +285,7 @@ async function generateExplanationPrompt({ instructions, program, request, root,
 }
 
 async function generateStartPrompt({
+  inspection,
   hiddenStackPieces,
   instructions,
   program,
@@ -292,6 +294,20 @@ async function generateStartPrompt({
   sessionPrompt,
   stackPackages,
 }) {
+  inspection ??= await inspectProject({ projectRoot: root, stackPackages });
+  if (inspection.state === 'adoption') {
+    return {
+      status: 'ready', task: 'start',
+      prompt: renderPrompt({
+        instructions: await startInstructions(instructions, 'existing-uninitialized'), request,
+        context: { task: 'start', projectRoot: root, projectKind: 'existing-uninitialized', inspection,
+          genesis: { initialized: inspection.projectFormat.status === 'current' }, ...sessionPrompt.context },
+        collaborationGuidance: sessionPrompt.collaborationGuidance,
+        engineeringGuidance: sessionPrompt.engineeringGuidance,
+      }),
+      warnings: inspection.diagnostics, verificationCommands: [],
+    };
+  }
   let blueprint;
   try {
     blueprint = await readBlueprint(root, { required: true });
@@ -384,6 +400,15 @@ export async function generateProjectPrompt({
   }
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const userRequest = requestText(request, task);
+  const openingInspection = task === 'start' ? await inspectProject({ projectRoot: root, stackPackages }) : null;
+  if (openingInspection) {
+    const inspection = openingInspection;
+    if (inspection.state === 'attention') {
+      return { status: 'ready', task: 'start',
+        prompt: `This existing Genesis project needs attention. Preserve source and history; never offer a seed. Explain the reported issue and the exact next action. Do not run application verification on startup.\n\n${JSON.stringify(inspection, null, 2)}\n\nUSER REQUEST\n${userRequest}\n`,
+        warnings: inspection.diagnostics, verificationCommands: [] };
+    }
+  }
   const [instructions, collaboration, engineering] = await Promise.all([
     readInstalledAsset(task),
     collaborationForPrompt(root),
@@ -426,6 +451,7 @@ export async function generateProjectPrompt({
   const program = await observeProgram(root);
   if (task === 'start') {
     return generateStartPrompt({
+      inspection: openingInspection,
       instructions,
       hiddenStackPieces,
       program,

package/src/index/session-context.js

@@ -3,6 +3,7 @@ import { GENESIS_CONTRACTS } from './contracts.js';
 import { readEngineering, readEngineeringBaseline } from './engineering.js';
 import { GenesisError } from './errors.js';
 import { gitContext } from './git.js';
+import { inspectProject } from './project-inspection.js';
 import { readStack } from './stack.js';
 import { listStackCatalogPieces } from './stack-catalog.js';
 import { normalizeSource, sha256, stableJson } from './utils.js';
@@ -109,11 +110,12 @@ export async function projectSessionContext({
   stackPackages = [],
 } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
-  const [stack, collaboration, engineering, hostContext] = await Promise.all([
+  const [stack, collaboration, engineering, hostContext, inspection] = await Promise.all([
     optionalStack(root, stackPackages),
     optionalCollaboration(root),
     optionalEngineering(root),
     hostContextContribution({ hostDriver, hostDriverInput, scope: 'session' }),
+    inspectProject({ projectRoot: root, stackPackages }),
   ]);
   const availableComponents = await optionalStackComponentIds(root, stack, stackPackages);
   const selected = stack?.components.map(({ id }) => id) || [];
@@ -122,6 +124,15 @@ export async function projectSessionContext({
     : 'unavailable; run the Genesis `check` operation';
   const output = [
     'This is a Genesis-enriched project.',
+    `Project opening state: ${inspection.state}.`,
+    ...(inspection.state === 'new' ? [
+      '- This directory contains only bootstrap files. Offer a ready-made template (`genesis templates list`) or creation through conversation. Apply one explicitly selected template to this empty project; a selected Stack alone does not mean source exists.',
+    ] : inspection.state === 'adoption' ? [
+      '- Existing project content needs description and configuration. Ask what this project does and what the user wants to run, using answers already supplied. Inspect its implementation to work backwards into Blueprint, Stack and Program. Do not offer seeds or replace existing source/history. Run `genesis adopt` and follow its prompt; initialized Genesis files already express the user’s decision to use Genesis.',
+    ] : inspection.state === 'attention' ? [
+      `- Genesis needs attention: ${inspection.diagnostics.map(({ message }) => message).join(' ')} Next action: ${inspection.nextAction}. Preserve source and explain the specific issue before the relevant migration or repair. Do not offer seeds.`,
+    ] : []),
+    '- Opening or resuming a session only reads project metadata and content paths. Do not run verification, tests, builds, dependency installation, or database preparation just because a session started. Run relevant checks when the requested work calls for them.',
     '- Read `genesis/blueprint.md`, `genesis/collaboration.md`, `genesis/engineering.md`, and `genesis/stack.md` for product intent, collaboration approach, engineering approach, and selected technology.',
     '- For a new project whose Blueprint does not yet establish product direction, do not research technology or create source until the user has made clear what is being built, who or what will use or invoke it, and the first observable useful outcome. Ask only unresolved high-impact questions. A reply confirms only what it explicitly answers; Stack confirmation is not product intent.',
     '- Once product direction is clear, choose one smallest implementation path through selected technology guidance, or authoritative technology documentation when the catalog has no match, and read only what that path requires. Do not survey alternatives, clone whole technology repositories, inspect unrelated package internals, or delegate research unless one concrete failure requires one exact investigation.',
@@ -133,7 +144,7 @@ export async function projectSessionContext({
     '- Program is fallible explanation; code, tests, and runtime behavior remain evidence.',
     '- Keep Blueprint and affected Program explanations aligned with intentional observable product behavior in the same implementation turn. Private restructuring may need only source citations or no explanatory change.',
     '- Before reporting completion, compare the requested observable behavior, required inputs and resources, declared project operations, and focused evidence with what actually exists. State anything not proven.',
-    '- Deslop only when explicitly requested. Genesis defines its behavior-preserving committed scope; selected Stack components may add technology-specific cleanup guidance.',
+    '- Deslop only when explicitly requested. By default, clean up your own changes for the current task, committed or uncommitted; explicit commits or ranges take precedence. Preserve behavior, unrelated work, and existing staging; a dirty worktree is allowed. Selected Stack components may add technology-specific cleanup guidance.',
     '- This guidance is loaded for a new session and refreshed after compaction. Continue the active request without restarting completed work.',
     `Engineering profile: ${engineering.profile?.id || 'invalid; run the Genesis `check` operation'}.`,
     `Selected Stack components: ${stackStatus}.`,

package/src/index/template-catalog.js

@@ -0,0 +1,100 @@
+import { createRequire } from 'node:module';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { GenesisError } from './errors.js';
+import { GENESIS_CONTRACTS } from './contracts.js';
+import { readGitSnapshot } from './template-source.js';
+import { readStack } from './stack.js';
+
+const require = createRequire(import.meta.url);
+const NAME = /^[a-z][a-z0-9-]*$/u;
+const ID = /^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/u;
+
+function templateCatalogError(message) {
+  return new GenesisError('TEMPLATE_CATALOG_INVALID', message);
+}
+
+function parseTemplateCatalog(value, namespace) {
+  if (!NAME.test(namespace) || value?.schemaVersion !== 1 || !Array.isArray(value.templates)) {
+    throw templateCatalogError('A template catalogue requires a namespace, schemaVersion 1, and templates.');
+  }
+  const ids = new Set();
+  return value.templates.map((entry) => {
+    if (!ID.test(entry?.id) || ids.has(entry.id)
+      || typeof entry.name !== 'string' || !entry.name.trim()
+      || typeof entry.repository !== 'string' || !entry.repository
+      || typeof entry.branch !== 'string' || !entry.branch
+      || entry.technology !== entry.id.split('/')[0]) {
+      throw templateCatalogError(`Invalid or duplicate template in ${namespace}: ${entry?.id || '(missing id)'}.`);
+    }
+    ids.add(entry.id);
+    return {
+      id: `${namespace}:${entry.id}`,
+      namespace,
+      technology: entry.technology,
+      variant: entry.id.split('/')[1],
+      name: entry.name.trim(),
+      description: typeof entry.description === 'string' ? entry.description.trim() : '',
+      repository: entry.repository,
+      branch: entry.branch,
+    };
+  });
+}
+
+async function installedCatalogs(stackPackages, projectRoot) {
+  const sources = [];
+  for (const packageName of stackPackages) {
+    let manifestPath;
+    try {
+      manifestPath = require.resolve(`${packageName}/package.json`, { paths: [projectRoot, ...require.resolve.paths(packageName)] });
+    } catch { throw templateCatalogError(`Configured Stack package is not installed: ${packageName}.`); }
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    const declaration = manifest.genesis?.templates;
+    if (!declaration) continue;
+    if (!NAME.test(declaration.namespace) || declaration.path !== 'genesis.templates.json') {
+      throw templateCatalogError(`Invalid template declaration in ${packageName}.`);
+    }
+    sources.push({
+      namespace: declaration.namespace,
+      catalog: JSON.parse(await readFile(path.join(path.dirname(manifestPath), declaration.path), 'utf8')),
+    });
+  }
+  return sources;
+}
+
+/** Catalogues are explicit data sources. A Stack or Skill never implicitly installs a template. */
+export async function listTemplates({ projectRoot = process.cwd(), stackPackages = [], templateSources = [] } = {}) {
+  let recorded = [];
+  try { recorded = (await readStack(projectRoot, { stackPackages })).stackPackages; } catch { /* Explicit sources also work before init. */ }
+  stackPackages = [...new Set([...recorded, ...stackPackages])];
+  const sources = [...await installedCatalogs(stackPackages, projectRoot), ...templateSources];
+  const namespaces = new Set();
+  const templates = [];
+  for (const source of sources) {
+    if (!NAME.test(source.namespace) || namespaces.has(source.namespace)) {
+      throw templateCatalogError(`Duplicate or invalid template source namespace: ${source.namespace}.`);
+    }
+    namespaces.add(source.namespace);
+    let catalog = source.catalog;
+    if (!catalog) {
+      const snapshot = await readGitSnapshot({ repository: source.repository, branch: source.branch || 'main' });
+      const file = snapshot.files.find(({ path: name }) => name === 'genesis.templates.json');
+      if (!file) throw templateCatalogError(`${source.namespace} does not contain genesis.templates.json.`);
+      try { catalog = JSON.parse(file.contents.toString('utf8')); }
+      catch { throw templateCatalogError(`${source.namespace}/genesis.templates.json is not valid JSON.`); }
+    }
+    templates.push(...parseTemplateCatalog(catalog, source.namespace));
+  }
+  return { contract: GENESIS_CONTRACTS.templates, templates };
+}
+
+export function resolveTemplate(templates, id) {
+  const matches = templates.filter((entry) => entry.id === id || (!id.includes(':') && entry.id.split(':')[1] === id));
+  if (matches.length !== 1) {
+    throw new GenesisError(matches.length ? 'TEMPLATE_AMBIGUOUS' : 'TEMPLATE_NOT_FOUND',
+      matches.length ? `Choose a catalogue-qualified template: ${matches.map(({ id: name }) => name).join(', ')}.`
+        : `No configured template matches ${id}.`, { matches: matches.map(({ id: name }) => name) });
+  }
+  return matches[0];
+}

package/src/index/template-project.js

@@ -0,0 +1,152 @@
+import { lstat, mkdir, mkdtemp, readFile, readdir, rm, rmdir, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { parseBlueprintSource } from './blueprint.js';
+import { buildProjectIndex } from './code-index.js';
+import { GenesisError } from './errors.js';
+import { GENESIS_CONTRACTS } from './contracts.js';
+import { gitContext } from './git.js';
+import { initializeProject } from './init.js';
+import { GENESIS_BOOTSTRAP_PATHS, inspectProject } from './project-inspection.js';
+import { runGit, runGitText } from './process.js';
+import { listTemplates, resolveTemplate } from './template-catalog.js';
+import { readGitSnapshot } from './template-source.js';
+import { readStack } from './stack.js';
+import { writeFileAtomic } from './utils.js';
+
+function sections(source) {
+  const result = new Map();
+  let name = '';
+  let fence = false;
+  for (const line of source.split('\n')) {
+    if (/^```/u.test(line)) fence = !fence;
+    const heading = !fence && line.match(/^## (.+)$/u);
+    if (heading) { name = heading[1]; result.set(name, []); }
+    else if (name) result.get(name).push(line);
+  }
+  return result;
+}
+
+// Existing authored sections remain whole. The template contributes only missing sections.
+function mergeTemplateStack(templateSource, existingSource) {
+  const template = sections(templateSource);
+  const existing = sections(existingSource);
+  for (const [name, lines] of existing) {
+    if (['Components', 'Stack packages'].includes(name)) {
+      template.set(name, [...new Set([...(template.get(name) || []), ...lines].map((line) => line.trim()).filter(Boolean))]);
+    } else template.set(name, lines);
+  }
+  return `# Stack\n\n${[...template].map(([name, lines]) => `## ${name}\n\n${lines.join('\n').trim()}`).join('\n\n')}\n`;
+}
+
+async function existingFile(root, name) {
+  const location = path.join(root, name);
+  try {
+    const state = await lstat(location);
+    if (!state.isFile()) throw new GenesisError('TEMPLATE_DESTINATION_CONFLICT', `Template destination is not an ordinary file: ${name}.`);
+    return await readFile(location);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function filesBelow(root, relative = '') {
+  const files = [];
+  for (const entry of await readdir(path.join(root, relative), { withFileTypes: true })) {
+    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 throw new GenesisError('TEMPLATE_TREE_INVALID', `Template contains a non-ordinary file: ${name}.`);
+  }
+  return files;
+}
+
+async function assertSeedable(root, stackPackages) {
+  const inspection = await inspectProject({ projectRoot: root, stackPackages });
+  if (!inspection.templateEligible) {
+    throw new GenesisError('TEMPLATE_PROJECT_NOT_EMPTY', 'This project contains existing content or Genesis needs attention. Its source was preserved.', { inspection });
+  }
+}
+
+/** Apply one complete source tree without changing Git history or running application commands. */
+export async function applyTemplate({ projectRoot, templateId, stackPackages = [], templateSources = [] } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const lockPath = path.resolve(root, await runGitText(root, ['rev-parse', '--git-path', 'genesis-template.lock']));
+  try { await mkdir(lockPath); }
+  catch (error) {
+    if (error.code === 'EEXIST') throw new GenesisError('TEMPLATE_PROJECT_BUSY', 'Another template operation holds this project lock.');
+    throw error;
+  }
+  let stagingRoot;
+  try {
+    await assertSeedable(root, stackPackages);
+    const { templates } = await listTemplates({ projectRoot: root, stackPackages, templateSources });
+    const template = resolveTemplate(templates, String(templateId || ''));
+    const preserved = new Map();
+    for (const name of GENESIS_BOOTSTRAP_PATHS) preserved.set(name, await existingFile(root, name));
+    const snapshot = await readGitSnapshot(template);
+    stagingRoot = await mkdtemp(path.join(os.tmpdir(), 'genesis-template-project-'));
+    await runGit(stagingRoot, ['init', '--quiet']);
+    for (const file of snapshot.files) {
+      if (file.path.split('/').includes('node_modules') || file.path.split('/').some((part) => part === '.env' || part.startsWith('.env.') && part !== '.env.example')) {
+        throw new GenesisError('TEMPLATE_TREE_INVALID', `Template contains private environment or installed dependencies: ${file.path}.`);
+      }
+      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 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;
+      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);
+    }
+    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) {
+      const current = await existingFile(root, name);
+      if ((contents === null) !== (current === null) || contents && !contents.equals(current)) {
+        throw new GenesisError('TEMPLATE_DESTINATION_CHANGED', 'Project context changed while the template was being prepared. Nothing was applied.');
+      }
+    }
+    const files = await filesBelow(stagingRoot);
+    const applied = [];
+    try {
+      for (const file of files) {
+        const previous = await existingFile(root, file.path);
+        if (previous && previous.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);
+        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);
+        else await rm(path.join(root, file.path));
+      }
+      throw error;
+    }
+    return { contract: GENESIS_CONTRACTS.templateApplication, status: 'applied', template,
+      source: { repository: snapshot.repository, branch: snapshot.branch, revision: snapshot.revision },
+      changedFiles: applied.map(({ path: name }) => name).sort(),
+      guidance: 'The starting application is ready for its declared workspace setup. No application commands or Git commits were run.',
+    };
+  } finally {
+    if (stagingRoot) await rm(stagingRoot, { recursive: true, force: true });
+    await rmdir(lockPath);
+  }
+}

package/src/index/template-source.js

@@ -0,0 +1,51 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { GenesisError } from './errors.js';
+import { runGit, runGitText } from './process.js';
+
+function validateRepository(repository) {
+  if (typeof repository !== 'string' || !repository || repository.startsWith('-')) {
+    throw new GenesisError('TEMPLATE_SOURCE_INVALID', 'A template repository is required.');
+  }
+  if (path.isAbsolute(repository)) return;
+  let url;
+  try { url = new URL(repository); } catch { /* diagnosed below */ }
+  if (!url || url.protocol !== 'https:' || url.username || url.password || url.hash || url.search) {
+    throw new GenesisError('TEMPLATE_SOURCE_INVALID', 'Template sources must be HTTPS repositories or explicit local absolute paths.');
+  }
+}
+
+/** Fetch a branch once and read ordinary blobs; never execute or check out remote hooks/filters. */
+export async function readGitSnapshot({ repository, branch }) {
+  validateRepository(repository);
+  if (typeof branch !== 'string' || !branch || branch.startsWith('-')) {
+    throw new GenesisError('TEMPLATE_SOURCE_INVALID', 'A template branch is required.');
+  }
+  const temporaryRoot = await mkdtemp(path.join(os.tmpdir(), 'genesis-template-source-'));
+  try {
+    await runGit(temporaryRoot, ['init', '--bare', '--quiet']);
+    await runGit(temporaryRoot, ['check-ref-format', `refs/heads/${branch}`]);
+    await runGit(temporaryRoot, ['fetch', '--quiet', '--depth=1', '--no-tags', '--', repository, `refs/heads/${branch}`], { timeoutMs: 120_000 });
+    const revision = await runGitText(temporaryRoot, ['rev-parse', 'FETCH_HEAD^{commit}']);
+    const tree = await runGit(temporaryRoot, ['ls-tree', '-rz', '--full-tree', revision]);
+    const files = [];
+    let bytes = 0;
+    for (const item of tree.stdout.toString('utf8').split('\0').filter(Boolean)) {
+      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)
+        || 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]);
+      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.');
+      }
+      files.push({ path: name, contents: blob.stdout, mode: mode === '100755' ? 0o777 : 0o666 });
+    }
+    return { repository, branch, revision, files };
+  } finally { await rm(temporaryRoot, { recursive: true, force: true }); }
+}

package/src/index.js

@@ -22,9 +22,14 @@ import { inspectProjectStackSection } from './index/stack-section-inspection.js'
 import { listStackCatalogPieces } from './index/stack-catalog.js';
 import { addStackPieces, readStack } from './index/stack.js';
 import { uniqueSorted } from './index/utils.js';
+import { inspectProject } from './index/project-inspection.js';
 import { verifyProject } from './index/verification.js';
 import { projectSessionContext, projectTurnContext } from './index/session-context.js';
 import { withTrustedGitRepository } from './index/process.js';
+
+export { inspectProject };
+export { listTemplates } from './index/template-catalog.js';
+export { applyTemplate } from './index/template-project.js';
 import {
   HOST_CONTEXT_RESOLVER_DATA_ENV,
   HOST_CONTEXT_RESOLVER_ENV,
@@ -59,8 +64,14 @@ async function initializeWithIndex(projectRoot, stackPackages = []) {
   return withIndexResult(initialized, index);
 }
 
-export function initialize({ projectRoot = process.cwd(), stackPackages = [] } = {}) {
-  return initializeWithIndex(projectRoot, stackPackages);
+export async function initialize({ projectRoot = process.cwd(), stackPackages = [] } = {}) {
+  const initialized = await initializeWithIndex(projectRoot, stackPackages);
+  const inspection = await inspectProject({ projectRoot, stackPackages });
+  return { ...initialized, inspection, guidance: `${initialized.guidance}\n${inspection.state === 'adoption'
+    ? 'Existing application detected. Initialization has not documented it: open your agent to describe the project and choose what to run. Do not seed this repository.'
+    : inspection.state === 'new'
+      ? 'Ready for a new project. Open your agent or list ready-made starting points with genesis templates list.'
+      : 'Open your agent to continue. Session startup does not run application verification.'}` };
 }
 
 export async function migrate({ projectRoot = process.cwd(), stackPackages = [] } = {}) {