genesis-compiler 1.10.11 → 1.10.12

package/README.md

@@ -1052,10 +1052,12 @@ The CLI can also prepare and verify parsers for an offline host; see
 [language parser management](docs/parsers.md).
 `migrate()` updates recognized older Genesis project-file formats and returns
 the resulting structural check for hosts.
-`inspectProjectFormat({ projectRoot })` returns only the format marker's `path`,
+`inspectProjectFormat({ projectRoot, rootMode })` returns only the format marker's `path`,
 `status`, `projectVersion`, `supportedVersion`, `action`, and diagnostic when
-invalid. It retains Git repository discovery and trust checks, but does not
+invalid. By default it retains Git repository discovery and trust checks, but does not
 enumerate application files, load Stack catalogs, or inspect project guidance.
+`rootMode: "directory"` reads an explicit absolute directory without Git, as for
+Stack sections below.
 Missing markers distinguish uninitialized projects from unversioned Genesis
 material. Each call reads current state; it neither migrates nor writes files.
 `adoptProject()` also returns the initial `adopt` prompt for an existing
@@ -1116,7 +1118,11 @@ hosts may pass `rootMode: "directory"` and an explicit absolute `projectRoot`.
 This reads that exact directory, including when it sits inside another Git
 repository. It retains the same Stack validation and performs no writes or
 commands. Missing/invalid roots fail; this is never an automatic fallback from
-Git ownership or discovery errors.
+Git ownership or discovery errors. `inspectEnvironment()` and
+`inspectProjectFormat()` accept the same `rootMode` with the same rules. A host
+that already knows the project root and inspects it on every request, such as a
+preview status poll, can pass `rootMode: "directory"` to all three and start no
+Git process.
 
 `inspectStackSections({ names, projectRoot, rootMode, stackPackages })` returns
 an array of those same section results in the requested order. Names must be

package/package.json

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

package/plugins/genesis/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis",
-  "version": "1.10.11",
+  "version": "1.10.12",
   "description": "Makes Codex aware of optional Genesis adoption for existing projects.",
   "author": {
     "name": "Mobily Enterprises"

package/plugins/opencode/project-guidance.js

@@ -6,11 +6,11 @@ import { promisify } from "node:util";
 const execute = promisify(execFile);
 
 const HOST_CONTEXT_INPUT_ENV = "GENESIS_HOST_CONTEXT_INPUT";
+const HOOK_TIMEOUT_MS = 5_000;
 
-async function renderContext(projectRoot, sessionId, scope, parentSessionIds = []) {
+async function renderContext(projectRoot, sessionId, scope, parentSessionIds = [], timeoutMs = HOOK_TIMEOUT_MS) {
   if (scope === "turn" && process.env.GENESIS_TURN_CONTEXT_ENABLED === "0") return "";
   const started = Date.now();
-  const timeoutMs = 5_000;
   try {
     const { stdout } = await execute(
       "genesis",
@@ -54,7 +54,8 @@ function eventSessionId(event = {}) {
   ).trim();
 }
 
-export const GenesisProjectGuidance = async ({ client, directory, worktree } = {}) => {
+// OpenCode passes no hookTimeoutMs, so its hooks get five seconds; a test passes a shorter deadline to prove it.
+export const GenesisProjectGuidance = async ({ client, directory, worktree, hookTimeoutMs = HOOK_TIMEOUT_MS } = {}) => {
   const projectRoot = path.resolve(directory || worktree || process.cwd());
   const contexts = new Map();
   const turnContexts = new Map();
@@ -72,7 +73,7 @@ export const GenesisProjectGuidance = async ({ client, directory, worktree } = {
           if (!id || id === sessionId || parents.includes(id)) break;
           parents.push(id);
         }
-        return renderContext(projectRoot, sessionId, "session", parents);
+        return renderContext(projectRoot, sessionId, "session", parents, hookTimeoutMs);
       });
       contexts.set(sessionId, context);
       context.catch(() => {
@@ -108,7 +109,7 @@ export const GenesisProjectGuidance = async ({ client, directory, worktree } = {
       if (!sessionId || !messageId || !Array.isArray(message.parts)) return;
       let current = turnContexts.get(sessionId);
       if (current?.messageId !== messageId) {
-        current = { messageId, context: renderContext(projectRoot, sessionId, "turn") };
+        current = { messageId, context: renderContext(projectRoot, sessionId, "turn", [], hookTimeoutMs) };
         turnContexts.set(sessionId, current);
         current.context.catch(() => {
           if (turnContexts.get(sessionId) === current) turnContexts.delete(sessionId);

package/src/cli-commands.js

@@ -0,0 +1,193 @@
+import process from 'node:process';
+
+import {
+  addStack,
+  adoptProject,
+  applyTemplate,
+  check,
+  generatePrompt,
+  getContext,
+  indexCodebase,
+  initialize,
+  inspectCollaboration,
+  inspectEngineering,
+  inspectEnvironment,
+  inspectStackSection,
+  inspectSubsystems,
+  inspectProject,
+  inspectSkills,
+  installCodex,
+  listEngineeringProfiles,
+  listStackPieces,
+  listTemplates,
+  listParsers,
+  installParsers,
+  verifyParsers,
+  migrate,
+  setCollaboration,
+  setEngineeringProfile,
+  syncSkills,
+  verify,
+} from './index.js';
+import {
+  codexAdoptionRecommendation,
+} from './index/codex-hooks.js';
+import { engineeringProfile, readEngineeringBaseline } from './index/engineering.js';
+import { fail } from './index/errors.js';
+import { projectSessionContext } from './index/session-context.js';
+import { installedFirstPartyStackPackages } from './index/stack-catalog.js';
+import { readStack } from './index/stack.js';
+import { withParserCancellation } from './index/code-indexers/parsers.js';
+
+// The CLI's commands, which load every project operation. cli.js imports this module for every command except
+// `genesis hook turn`, which runs on every agent turn and composes only the host's context.
+
+async function cliStackPackages(projectRoot, supplied) {
+  if (supplied.length > 0) return supplied;
+  try {
+    const stack = await readStack(projectRoot);
+    if (stack.stackPackages.length > 0) return [];
+  } catch (error) {
+    if (error?.code !== 'STACK_REQUIRED') return [];
+  }
+  return installedFirstPartyStackPackages({ projectRoot });
+}
+
+async function execute({ command, operands, options }, { signal, hostContext = null, progress }) {
+  if (command === 'parsers') {
+    const parserOptions = {
+      languages: operands.slice(1), all: options.all, directory: options.directory, signal,
+      onProgress: progress,
+    };
+    return { list: listParsers, install: installParsers, verify: verifyParsers }[operands[0]](parserOptions);
+  }
+  const projectRoot = options.projectRoot || process.cwd();
+  const stackPackages = await cliStackPackages(projectRoot, options.stackPackages || []);
+  if (command === 'init') return initialize({ projectRoot, stackPackages });
+  if (command === 'templates') {
+    const templateOptions = { projectRoot, stackPackages, templateSources: options.templateSources };
+    return operands[0] === 'list' ? listTemplates(templateOptions) : applyTemplate({ ...templateOptions, templateId: operands[1] });
+  }
+  if (command === 'migrate') return migrate({ projectRoot, stackPackages });
+  if (command === 'skills') return syncSkills({ projectRoot, stackPackages });
+  if (command === 'adopt') {
+    return adoptProject({ projectRoot, request: operands.join(' '), stackPackages });
+  }
+  if (command === 'codex') return installCodex();
+  if (command === 'collaboration') {
+    if (operands[0] === 'show') {
+      return { action: 'show', ...await inspectCollaboration({ projectRoot }) };
+    }
+    return {
+      action: 'set',
+      ...await setCollaboration({
+        projectRoot,
+        tone: operands[1],
+        responseLength: operands[2],
+        experience: operands[3],
+        explanationStyle: operands[4],
+        longChecks: operands[5],
+        ...(operands.length > 6 ? { requirements: operands.slice(6).join(' ') } : {}),
+      }),
+    };
+  }
+  if (command === 'engineering') {
+    if (operands[0] === 'list') {
+      return { action: 'list', status: 'ok', profiles: await listEngineeringProfiles() };
+    }
+    if (operands[0] === 'show') {
+      if (!operands[1]) return { action: 'show', ...await inspectEngineering({ projectRoot }) };
+      const [baseline, profile] = await Promise.all([
+        readEngineeringBaseline(),
+        engineeringProfile(operands[1]),
+      ]);
+      return {
+        action: 'show',
+        status: 'ready',
+        profile,
+        guidance: [
+          '## Universal complexity gate',
+          '',
+          baseline,
+          '',
+          '## Profile guidance',
+          '',
+          profile.guidance,
+        ].join('\n'),
+      };
+    }
+    return {
+      action: 'set',
+      ...await setEngineeringProfile({ profile: operands[1], projectRoot }),
+    };
+  }
+  if (command === 'stack') {
+    if (operands[0] === 'list') {
+      return { status: 'ok', pieces: await listStackPieces({ projectRoot, stackPackages }) };
+    }
+    return addStack({ pieces: operands.slice(1), projectRoot, stackPackages });
+  }
+  if (command === 'prompt') {
+    return generatePrompt({
+      projectRoot,
+      task: options.task || 'work',
+      request: operands.join(' '),
+      stackPackages,
+    });
+  }
+  if (command === 'context') return getContext({ paths: operands, projectRoot, stackPackages });
+  if (command === 'index') return indexCodebase({ projectRoot, queries: operands, stackPackages, callWeb: options.callWeb });
+  if (command === 'inspect') {
+    if (operands[0] === 'section') {
+      return {
+        inspection: 'section',
+        ...await inspectStackSection({
+          name: operands.slice(1).join(' '),
+          projectRoot,
+          stackPackages,
+        }),
+      };
+    }
+    const inspections = { subsystems: inspectSubsystems, environment: inspectEnvironment, project: inspectProject, skills: inspectSkills };
+    return {
+      inspection: operands[0],
+      ...await inspections[operands[0]]({ projectRoot, stackPackages }),
+    };
+  }
+  if (command === 'hook') {
+    if (operands[0] === 'discover') {
+      return { kind: 'discover', ...await codexAdoptionRecommendation({ projectRoot }) };
+    }
+    return {
+      kind: 'session',
+      ...await projectSessionContext({
+        ...(hostContext === null ? {} : {
+          hostDriver: () => hostContext.text,
+          hostDriverInput: { scope: 'session' },
+        }),
+        projectRoot,
+        stackPackages,
+      }),
+    };
+  }
+  if (command === 'verify') {
+    return verify({
+      projectRoot,
+      signal,
+      stackPackages,
+      onEvent: (event) => {
+        if (!options.json) progress(event.message);
+      },
+    });
+  }
+  if (command === 'check') return check({ projectRoot, stackPackages });
+  fail('CLI_UNKNOWN_COMMAND', `Unknown command: ${command}`);
+}
+
+/**
+ * Runs a parsed CLI command other than the turn hook. `progress` writes one line of progress for the person.
+ * @returns {Promise<object>} The command's result.
+ */
+export function runCommand(parsed, { signal, hostContext = null, progress }) {
+  return withParserCancellation(signal, () => execute(parsed, { signal, hostContext, progress }));
+}

package/src/cli.js

@@ -1,40 +1,8 @@
 import process from 'node:process';
 import { parseArgs } from 'node:util';
 
-import {
-  addStack,
-  adoptProject,
-  applyTemplate,
-  check,
-  generatePrompt,
-  getContext,
-  indexCodebase,
-  initialize,
-  inspectCollaboration,
-  inspectEngineering,
-  inspectEnvironment,
-  inspectStackSection,
-  inspectSubsystems,
-  inspectProject,
-  inspectSkills,
-  installCodex,
-  listEngineeringProfiles,
-  listStackPieces,
-  listTemplates,
-  listParsers,
-  installParsers,
-  verifyParsers,
-  migrate,
-  setCollaboration,
-  setEngineeringProfile,
-  syncSkills,
-  verify,
-} from './index.js';
-import {
-  codexAdoptionRecommendation,
-} from './index/codex-hooks.js';
-import { engineeringProfile, readEngineeringBaseline } from './index/engineering.js';
 import { asDiagnostic, fail } from './index/errors.js';
+import { projectTurnContext } from './index/host-context.js';
 import {
   HOST_CONTEXT_INPUT_ENV,
   HOST_CONTEXT_RESOLVER_ENV,
@@ -45,10 +13,6 @@ import {
   inspectProjectFormat,
   projectFormatDiagnostic,
 } from './index/project-format.js';
-import { projectSessionContext, projectTurnContext } from './index/session-context.js';
-import { installedFirstPartyStackPackages } from './index/stack-catalog.js';
-import { readStack } from './index/stack.js';
-import { withParserCancellation } from './index/code-indexers/parsers.js';
 
 const USAGE = `Usage:
   genesis init
@@ -473,158 +437,22 @@ async function hookSessionInput(environment = process.env) {
   };
 }
 
-async function cliStackPackages(projectRoot, supplied) {
-  if (supplied.length > 0) return supplied;
-  try {
-    const stack = await readStack(projectRoot);
-    if (stack.stackPackages.length > 0) return [];
-  } catch (error) {
-    if (error?.code !== 'STACK_REQUIRED') return [];
-  }
-  return installedFirstPartyStackPackages({ projectRoot });
-}
-
-async function execute({ command, operands, options }, { signal, hostContext = null } = {}) {
-  if (command === 'parsers') {
-    const parserOptions = {
-      languages: operands.slice(1), all: options.all, directory: options.directory, signal,
-      onProgress: (message) => line(process.stderr, message),
-    };
-    return { list: listParsers, install: installParsers, verify: verifyParsers }[operands[0]](parserOptions);
-  }
-  const projectRoot = options.projectRoot || process.cwd();
-  const stackPackages = await cliStackPackages(projectRoot, options.stackPackages || []);
-  if (command === 'init') return initialize({ projectRoot, stackPackages });
-  if (command === 'templates') {
-    const templateOptions = { projectRoot, stackPackages, templateSources: options.templateSources };
-    return operands[0] === 'list' ? listTemplates(templateOptions) : applyTemplate({ ...templateOptions, templateId: operands[1] });
-  }
-  if (command === 'migrate') return migrate({ projectRoot, stackPackages });
-  if (command === 'skills') return syncSkills({ projectRoot, stackPackages });
-  if (command === 'adopt') {
-    return adoptProject({ projectRoot, request: operands.join(' '), stackPackages });
-  }
-  if (command === 'codex') return installCodex();
-  if (command === 'collaboration') {
-    if (operands[0] === 'show') {
-      return { action: 'show', ...await inspectCollaboration({ projectRoot }) };
-    }
-    return {
-      action: 'set',
-      ...await setCollaboration({
-        projectRoot,
-        tone: operands[1],
-        responseLength: operands[2],
-        experience: operands[3],
-        explanationStyle: operands[4],
-        longChecks: operands[5],
-        ...(operands.length > 6 ? { requirements: operands.slice(6).join(' ') } : {}),
-      }),
-    };
-  }
-  if (command === 'engineering') {
-    if (operands[0] === 'list') {
-      return { action: 'list', status: 'ok', profiles: await listEngineeringProfiles() };
-    }
-    if (operands[0] === 'show') {
-      if (!operands[1]) return { action: 'show', ...await inspectEngineering({ projectRoot }) };
-      const [baseline, profile] = await Promise.all([
-        readEngineeringBaseline(),
-        engineeringProfile(operands[1]),
-      ]);
-      return {
-        action: 'show',
-        status: 'ready',
-        profile,
-        guidance: [
-          '## Universal complexity gate',
-          '',
-          baseline,
-          '',
-          '## Profile guidance',
-          '',
-          profile.guidance,
-        ].join('\n'),
-      };
-    }
-    return {
-      action: 'set',
-      ...await setEngineeringProfile({ profile: operands[1], projectRoot }),
-    };
-  }
-  if (command === 'stack') {
-    if (operands[0] === 'list') {
-      return { status: 'ok', pieces: await listStackPieces({ projectRoot, stackPackages }) };
-    }
-    return addStack({ pieces: operands.slice(1), projectRoot, stackPackages });
-  }
-  if (command === 'prompt') {
-    return generatePrompt({
-      projectRoot,
-      task: options.task || 'work',
-      request: operands.join(' '),
-      stackPackages,
-    });
-  }
-  if (command === 'context') return getContext({ paths: operands, projectRoot, stackPackages });
-  if (command === 'index') return indexCodebase({ projectRoot, queries: operands, stackPackages, callWeb: options.callWeb });
-  if (command === 'inspect') {
-    if (operands[0] === 'section') {
-      return {
-        inspection: 'section',
-        ...await inspectStackSection({
-          name: operands.slice(1).join(' '),
-          projectRoot,
-          stackPackages,
-        }),
-      };
-    }
-    const inspections = { subsystems: inspectSubsystems, environment: inspectEnvironment, project: inspectProject, skills: inspectSkills };
-    return {
-      inspection: operands[0],
-      ...await inspections[operands[0]]({ projectRoot, stackPackages }),
-    };
-  }
-  if (command === 'hook') {
-    if (operands[0] === 'discover') {
-      return { kind: 'discover', ...await codexAdoptionRecommendation({ projectRoot }) };
-    }
-    const scope = operands[0];
-    if (scope === 'turn') {
-      return hostContext === null
-        ? { kind: 'turn', status: 'ready', output: '' }
-        : {
-            kind: 'turn',
-            ...await projectTurnContext({
-              hostDriver: () => hostContext.text,
-              hostDriverInput: { scope: 'turn' },
-            }),
-          };
-    }
-    return {
-      kind: 'session',
-      ...await projectSessionContext({
-        ...(hostContext === null ? {} : {
-          hostDriver: () => hostContext.text,
-          hostDriverInput: { scope: 'session' },
-        }),
-        projectRoot,
-        stackPackages,
-      }),
-    };
-  }
-  if (command === 'verify') {
-    return verify({
-      projectRoot,
-      signal,
-      stackPackages,
-      onEvent: (event) => {
-        if (!options.json) line(process.stderr, event.message);
-      },
-    });
-  }
-  if (command === 'check') return check({ projectRoot, stackPackages });
-  fail('CLI_UNKNOWN_COMMAND', `Unknown command: ${command}`);
+// `genesis hook turn` runs on every agent turn and composes only the host's context, so it loads none of the project
+// operations; every other command loads them with cli-commands.js when it runs.
+async function executeCommand(parsed, { signal, hostContext }) {
+  if (parsed.command === 'hook' && parsed.operands[0] === 'turn') {
+    return hostContext === null
+      ? { kind: 'turn', status: 'ready', output: '' }
+      : {
+          kind: 'turn',
+          ...await projectTurnContext({
+            hostDriver: () => hostContext.text,
+            hostDriverInput: { scope: 'turn' },
+          }),
+        };
+  }
+  const { runCommand } = await import('./cli-commands.js');
+  return runCommand(parsed, { signal, hostContext, progress: (message) => line(process.stderr, message) });
 }
 
 async function optionalProjectFormat(projectRoot) {
@@ -695,7 +523,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     process.once('SIGINT', abort);
     process.once('SIGTERM', abort);
     const result = withProjectFormatWarning(
-      hookResult ?? await withParserCancellation(controller.signal, () => execute(parsed, { signal: controller.signal, hostContext })),
+      hookResult ?? await executeCommand(parsed, { signal: controller.signal, hostContext }),
       projectFormat,
       formatDiagnostic,
     );

package/src/index/agent-skills.js

@@ -85,11 +85,32 @@ function markdownDestinations(tree) {
   while (nodes.length > 0) {
     const node = nodes.pop();
     if (['definition', 'image', 'link'].includes(node?.type) && typeof node.url === 'string') {
-      destinations.push({ line: node.position?.start?.line, url: node.url });
+      destinations.push(Object.freeze({ line: node.position?.start?.line, url: node.url }));
     }
     if (Array.isArray(node?.children)) nodes.push(...node.children);
   }
-  return destinations.sort((left, right) => (left.line || 0) - (right.line || 0));
+  return Object.freeze(destinations.sort((left, right) => (left.line || 0) - (right.line || 0)));
+}
+
+// Link destinations by Markdown content hash. A skill plan validates every Markdown file of every selected skill,
+// and one operation builds several plans (synchronization, inspection, context, prompts), so the same skill text was
+// parsed again each time; the full CommonMark parse was 40% of the test suite's CPU. The destinations depend only on
+// the text, so each distinct text is parsed once per process. Whether each local target exists is still checked on
+// every validation.
+const MAX_PARSED_MARKDOWN = 256;
+const parsedMarkdownDestinations = new Map();
+
+function markdownDestinationsOf(source) {
+  const key = sha256(source);
+  let destinations = parsedMarkdownDestinations.get(key);
+  if (!destinations) {
+    destinations = markdownDestinations(fromMarkdown(source));
+    if (parsedMarkdownDestinations.size >= MAX_PARSED_MARKDOWN) {
+      parsedMarkdownDestinations.delete(parsedMarkdownDestinations.keys().next().value);
+    }
+    parsedMarkdownDestinations.set(key, destinations);
+  }
+  return destinations;
 }
 
 function localReferencePath(url) {
@@ -121,16 +142,16 @@ async function validateMarkdownReferences(directory, files) {
   const problems = [];
   for (const file of files.filter(({ path: filePath }) => filePath.endsWith('.md'))) {
     const location = path.join(root, file.path);
-    let tree;
+    let destinations;
     try {
-      tree = fromMarkdown(await readFile(location, 'utf8'));
+      destinations = markdownDestinationsOf(await readFile(location, 'utf8'));
     } catch (error) {
       invalidSkill(`Agent Skill Markdown is invalid: ${location}.`, {
         cause: error.message,
         path: file.path,
       });
     }
-    for (const destination of markdownDestinations(tree)) {
+    for (const destination of destinations) {
       const local = localReferencePath(destination.url);
       if (!local) continue;
       const problem = {

package/src/index/environment-files.js

@@ -1,4 +1,4 @@
-import { gitContext } from './git.js';
+import { inspectionRoot } from './git.js';
 import { readStack } from './stack.js';
 import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { missingStackResources } from './stack-preflight.js';
@@ -8,9 +8,10 @@ import { GENESIS_CONTRACTS } from './contracts.js';
 export async function inspectProjectEnvironment({
   environment = process.env,
   projectRoot,
+  rootMode = 'repository',
   stackPackages = [],
 } = {}) {
-  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const root = await inspectionRoot({ projectRoot, rootMode, subject: 'Environment' });
   const stack = await readStack(root, { stackPackages });
   const diagnostics = missingStackResources({
     environment: withStackEnvironmentDefaults(environment, stack.environmentDefaults),

package/src/index/git.js

@@ -1,4 +1,4 @@
-import { realpath } from 'node:fs/promises';
+import { realpath, stat } from 'node:fs/promises';
 import path from 'node:path';
 
 import { fail } from './errors.js';
@@ -51,3 +51,19 @@ export async function gitContext(projectRoot = process.cwd()) {
   }
   return { workingDirectory: root, repositoryRoot };
 }
+
+/**
+ * The root a read-only inspection reads. The default `repository` mode discovers the enclosing Git worktree with
+ * its trust checks. `directory` reads exactly an explicit absolute directory without starting Git: a source
+ * snapshot without Git metadata, or a host that already knows the project root. There is no fallback between them.
+ */
+export async function inspectionRoot({ projectRoot, rootMode = 'repository', subject }) {
+  if (rootMode === 'repository') return (await gitContext(projectRoot)).repositoryRoot;
+  if (rootMode !== 'directory') throw new TypeError(`${subject} rootMode must be repository or directory.`);
+  if (typeof projectRoot !== 'string' || !path.isAbsolute(projectRoot)) {
+    throw new TypeError('Directory inspection requires an explicit absolute projectRoot.');
+  }
+  const root = await realpath(projectRoot);
+  if (!(await stat(root)).isDirectory()) throw new TypeError('Directory inspection requires a directory.');
+  return root;
+}

package/src/index/host-context.js

@@ -0,0 +1,70 @@
+import { GENESIS_CONTRACTS } from './contracts.js';
+import { GenesisError } from './errors.js';
+import { normalizeSource, sha256, stableJson } from './utils.js';
+
+// The host's contribution to the session and turn context lanes, and the turn lane itself. The turn lane composes only
+// that contribution, and `genesis hook turn` runs it on every agent turn, so this module imports nothing that reads the
+// project; the session lane (session-context.js) adds the project's guidance.
+const HOST_CONTEXT_MAX_BYTES = Object.freeze({
+  session: 24 * 1024,
+  turn: 512,
+});
+
+export async function hostContextContribution({ hostDriver, hostDriverInput, scope }) {
+  if (hostDriver === undefined || hostDriver === null) {
+    if (hostDriverInput !== undefined) {
+      throw new GenesisError(
+        'HOST_CONTEXT_INVALID',
+        'Host context input requires an explicitly registered host driver.',
+      );
+    }
+    return '';
+  }
+  if (typeof hostDriver !== 'function') {
+    throw new GenesisError('HOST_CONTEXT_INVALID', 'The registered host driver must be a function.');
+  }
+  if (
+    !hostDriverInput
+    || typeof hostDriverInput !== 'object'
+    || Array.isArray(hostDriverInput)
+    || hostDriverInput.scope !== scope
+  ) {
+    throw new GenesisError(
+      'HOST_CONTEXT_INVALID',
+      `The ${scope} context lane requires host input with scope \`${scope}\`.`,
+    );
+  }
+  const value = await hostDriver(hostDriverInput);
+  if (typeof value !== 'string') {
+    throw new GenesisError('HOST_CONTEXT_INVALID', 'The registered host driver must return plain text.');
+  }
+  const output = normalizeSource(value).trim();
+  if (Buffer.byteLength(output, 'utf8') > HOST_CONTEXT_MAX_BYTES[scope]) {
+    throw new GenesisError(
+      'HOST_CONTEXT_INVALID',
+      `The registered host driver's ${scope} contribution exceeds ${HOST_CONTEXT_MAX_BYTES[scope]} bytes.`,
+    );
+  }
+  return output;
+}
+
+export function composedContext(contract, output) {
+  return {
+    contract,
+    status: 'ready',
+    output,
+    identity: sha256(stableJson({ contract, output })),
+  };
+}
+
+export async function projectTurnContext({ hostDriver, hostDriverInput } = {}) {
+  const output = await hostContextContribution({
+    hostDriver,
+    hostDriverInput,
+    scope: 'turn',
+  });
+  return {
+    ...composedContext(GENESIS_CONTRACTS.turnContext, output),
+    trust: 'untrusted',
+  };
+}

package/src/index/program.js

@@ -170,8 +170,13 @@ export async function inspectProgram(projectRoot) {
     const contents = moduleContents(source, programPath);
     if (!assignments.has(programPath)) throw new GenesisError('SUBSYSTEMS_PROGRAM_UNASSIGNED', `Program module has no declared subsystem: ${programPath}.`);
     const { sources } = contents;
-    for (const sourcePath of sources) {
-      if (!sourcePath || !isProjectContentPath(sourcePath) || !await sourceExists(projectRoot, sourcePath)) {
+    // A module cites dozens of sources; check them all at once and report the first problem in citation order.
+    const checks = await Promise.allSettled(sources.map((sourcePath) => (
+      sourcePath && isProjectContentPath(sourcePath) && sourceExists(projectRoot, sourcePath)
+    )));
+    for (const [index, sourcePath] of sources.entries()) {
+      if (checks[index].status === 'rejected') throw checks[index].reason;
+      if (!checks[index].value) {
         throw new GenesisError(
           'PROGRAM_SOURCE_MISSING',
           `Program module cites a missing or ineligible source file: ${sourcePath}.`,

package/src/index/project-files.js

@@ -30,6 +30,6 @@ export async function gitVisibleFileStates(projectRoot, { includePath = () => tr
 
 /** Classifies opening behavior from cheap Git-visible paths and selected Stack state. */
 export async function classifyProjectKind({ projectRoot } = {}) {
-  const content = await inspectProjectContent(projectRoot);
-  return content.kind === 'existing' ? 'existing' : 'new';
+  const { kind } = await inspectProjectContent(projectRoot, { kindOnly: true });
+  return kind === 'existing' ? 'existing' : 'new';
 }

package/src/index/project-format.js

@@ -2,7 +2,7 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import { asDiagnostic, GenesisError } from './errors.js';
-import { gitContext } from './git.js';
+import { inspectionRoot } from './git.js';
 import {
   BLUEPRINT_PATH,
   COLLABORATION_PATH,
@@ -90,9 +90,8 @@ export async function inspectProjectFormatAtRoot(projectRoot) {
   return projectFormat('current', version, null);
 }
 
-export async function inspectProjectFormat({ projectRoot } = {}) {
-  const root = (await gitContext(projectRoot)).repositoryRoot;
-  return inspectProjectFormatAtRoot(root);
+export async function inspectProjectFormat({ projectRoot, rootMode = 'repository' } = {}) {
+  return inspectProjectFormatAtRoot(await inspectionRoot({ projectRoot, rootMode, subject: 'Project format' }));
 }
 
 export function projectFormatDiagnostic(format) {

package/src/index/project-inspection.js

@@ -51,22 +51,39 @@ async function isBootstrapGitignore(projectRoot, paths) {
   }
 }
 
-export async function inspectProjectContent(projectRoot) {
+async function listFiles(projectRoot, options) {
   // Exclude dependency paths in Git before collecting and sorting its output.
-  const sourcePaths = ['--', '.', ':(exclude,glob)**/node_modules/**'];
+  const { stdout } = await runGit(projectRoot, ['ls-files', '-z', ...options, '--', '.', ':(exclude,glob)**/node_modules/**']);
+  return stdout.toString('utf8').split('\0').filter(Boolean);
+}
+
+/**
+ * With kindOnly, only `kind` is returned. Listing ignored files walks ignored dependency trees such as node_modules
+ * despite the exclusion, which dominates the inspection of an installed application, so it is skipped when Git's
+ * visible files already include project content: ignored files can add existing content, never remove it.
+ */
+export async function inspectProjectContent(projectRoot, { kindOnly = false } = {}) {
+  const listIgnored = () => listFiles(projectRoot, ['--others', '--ignored', '--exclude-standard']);
   const [visible, deleted, ignored] = await Promise.all([
-    runGit(projectRoot, ['ls-files', '-z', '--cached', '--others', '--exclude-standard', ...sourcePaths]),
-    runGit(projectRoot, ['ls-files', '-z', '--deleted', ...sourcePaths]),
-    runGit(projectRoot, ['ls-files', '-z', '--others', '--ignored', '--exclude-standard', ...sourcePaths]),
+    listFiles(projectRoot, ['--cached', '--others', '--exclude-standard']),
+    listFiles(projectRoot, ['--deleted']),
+    kindOnly ? [] : listIgnored(),
   ]);
-  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)))]
+  if (!kindOnly) return classifyContent(projectRoot, visible, deleted, ignored);
+  const { kind } = await classifyContent(projectRoot, visible, deleted, []);
+  if (kind === 'existing') return { kind };
+  return { kind: (await classifyContent(projectRoot, visible, deleted, await listIgnored())).kind };
+}
+
+async function classifyContent(projectRoot, visible, deleted, ignored) {
+  const absent = new Set(deleted);
+  const paths = [...new Set([...visible, ...ignored])]
     .filter((file) => !absent.has(file) && file !== '.git' && !file.startsWith('.git/'))
     .sort();
   // OpenCode installs its plugin dependency beside the generated guidance plugin.
   // Recognize only its exact ignored scaffolding, never an authored config tree.
   const opencodePaths = ['.opencode/.gitignore', '.opencode/package.json', '.opencode/package-lock.json'];
-  const ignoredPaths = new Set(ignored.stdout.toString('utf8').split('\0').filter(Boolean));
+  const ignoredPaths = new Set(ignored);
   let opencodeBootstrap = [];
   if (opencodePaths.every((file) => ignoredPaths.has(file))) {
     try {
@@ -100,15 +117,19 @@ export async function inspectProjectContent(projectRoot) {
 
 /** Read-only opening inspection: no index generation, verification, or application execution. */
 export async function inspectProject({ projectRoot, stackPackages = [] } = {}) {
-  const root = (await gitContext(projectRoot)).repositoryRoot;
+  return inspectProjectAtRoot((await gitContext(projectRoot)).repositoryRoot, { stackPackages });
+}
+
+/** The same inspection of a resolved repository root; without `count`, content reports only its kind. */
+export async function inspectProjectAtRoot(root, { stackPackages = [], count = true } = {}) {
   const [content, format] = await Promise.all([
-    inspectProjectContent(root),
+    inspectProjectContent(root, { kindOnly: !count }),
     inspectProjectFormatAtRoot(root),
   ]);
   const result = {
     contract: GENESIS_CONTRACTS.projectInspection,
     state: 'attention',
-    content: { kind: content.kind, count: content.existingPaths.length },
+    content: count ? { kind: content.kind, count: content.existingPaths.length } : { kind: content.kind },
     projectFormat: format,
     templateEligible: false,
     stackComponents: [],

package/src/index/session-context.js

@@ -2,17 +2,12 @@ import { readCollaboration } from './collaboration.js';
 import { inspectProjectSkills, renderAgentSkillCatalog } from './agent-skills.js';
 import { GENESIS_CONTRACTS } from './contracts.js';
 import { readEngineering, readEngineeringBaseline } from './engineering.js';
-import { asDiagnostic, GenesisError } from './errors.js';
+import { asDiagnostic } from './errors.js';
 import { gitContext } from './git.js';
-import { inspectProject } from './project-inspection.js';
+import { inspectProjectAtRoot } from './project-inspection.js';
 import { readStack } from './stack.js';
 import { listStackCatalogPieces } from './stack-catalog.js';
-import { normalizeSource, sha256, stableJson } from './utils.js';
-
-const HOST_CONTEXT_MAX_BYTES = Object.freeze({
-  session: 24 * 1024,
-  turn: 512,
-});
+import { composedContext, hostContextContribution } from './host-context.js';
 
 async function optionalStack(projectRoot, stackPackages) {
   try { return await readStack(projectRoot, { stackPackages }); } catch { return null; }
@@ -47,53 +42,6 @@ async function optionalCollaboration(projectRoot) {
   }
 }
 
-async function hostContextContribution({ hostDriver, hostDriverInput, scope }) {
-  if (hostDriver === undefined || hostDriver === null) {
-    if (hostDriverInput !== undefined) {
-      throw new GenesisError(
-        'HOST_CONTEXT_INVALID',
-        'Host context input requires an explicitly registered host driver.',
-      );
-    }
-    return '';
-  }
-  if (typeof hostDriver !== 'function') {
-    throw new GenesisError('HOST_CONTEXT_INVALID', 'The registered host driver must be a function.');
-  }
-  if (
-    !hostDriverInput
-    || typeof hostDriverInput !== 'object'
-    || Array.isArray(hostDriverInput)
-    || hostDriverInput.scope !== scope
-  ) {
-    throw new GenesisError(
-      'HOST_CONTEXT_INVALID',
-      `The ${scope} context lane requires host input with scope \`${scope}\`.`,
-    );
-  }
-  const value = await hostDriver(hostDriverInput);
-  if (typeof value !== 'string') {
-    throw new GenesisError('HOST_CONTEXT_INVALID', 'The registered host driver must return plain text.');
-  }
-  const output = normalizeSource(value).trim();
-  if (Buffer.byteLength(output, 'utf8') > HOST_CONTEXT_MAX_BYTES[scope]) {
-    throw new GenesisError(
-      'HOST_CONTEXT_INVALID',
-      `The registered host driver's ${scope} contribution exceeds ${HOST_CONTEXT_MAX_BYTES[scope]} bytes.`,
-    );
-  }
-  return output;
-}
-
-function composedContext(contract, output) {
-  return {
-    contract,
-    status: 'ready',
-    output,
-    identity: sha256(stableJson({ contract, output })),
-  };
-}
-
 async function optionalStackComponentIds(projectRoot, stack, stackPackages) {
   try {
     const packages = [...new Set([...(stack?.stackPackages || []), ...stackPackages])];
@@ -116,7 +64,8 @@ export async function projectSessionContext({
     optionalCollaboration(root),
     optionalEngineering(root),
     hostContextContribution({ hostDriver, hostDriverInput, scope: 'session' }),
-    inspectProject({ projectRoot: root, stackPackages }),
+    // The opening state needs only the content kind, not a count of every ignored file.
+    inspectProjectAtRoot(root, { stackPackages, count: false }),
   ]);
   const availableComponents = await optionalStackComponentIds(root, stack, stackPackages);
   const skills = stack && inspection.projectFormat.status === 'current'
@@ -172,14 +121,4 @@ export async function projectSessionContext({
   return { ...composedContext(GENESIS_CONTRACTS.sessionContext, output), warnings: skills.diagnostics };
 }
 
-export async function projectTurnContext({ hostDriver, hostDriverInput } = {}) {
-  const output = await hostContextContribution({
-    hostDriver,
-    hostDriverInput,
-    scope: 'turn',
-  });
-  return {
-    ...composedContext(GENESIS_CONTRACTS.turnContext, output),
-    trust: 'untrusted',
-  };
-}
+export { projectTurnContext } from './host-context.js';

package/src/index/stack-catalog.js

@@ -7,11 +7,39 @@ import {
   normalizeStackPieceId,
   parseStackPieceSource,
 } from './stack-piece.js';
+import { sha256 } from './utils.js';
 
 const require = createRequire(import.meta.url);
 const PACKAGE_NAME = /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/u;
 const FIRST_PARTY_STACK_PACKAGE = 'genesis-stack';
 
+// Parsed catalogue pieces by source text. One operation reads the catalogue several times (the Stack, then the code
+// index, context and prompts each read it again), and every read parsed every piece. A parse depends only on the text,
+// the expected id and the path its errors name, so each distinct piece is parsed once per process; the result is
+// frozen so no reader can change what another reads. Every read still reads each file, so an edited piece is parsed
+// again, and a piece that fails to parse is never kept.
+const MAX_PARSED_PIECES = 512;
+const parsedPieces = new Map();
+
+function deepFreeze(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) deepFreeze(child);
+  }
+  return value;
+}
+
+function parsedStackPiece(source, expectedId, piecePath) {
+  const key = `${sha256(source)}\0${expectedId}\0${piecePath}`;
+  let piece = parsedPieces.get(key);
+  if (!piece) {
+    piece = deepFreeze(parseStackPieceSource(source, { expectedId, path: piecePath }));
+    if (parsedPieces.size >= MAX_PARSED_PIECES) parsedPieces.delete(parsedPieces.keys().next().value);
+    parsedPieces.set(key, piece);
+  }
+  return piece;
+}
+
 export function normalizeStackPackageName(value) {
   const name = String(value ?? '').trim();
   if (!PACKAGE_NAME.test(name)) {
@@ -94,7 +122,7 @@ async function readPieceDirectory(
   return Promise.all(files.map(async (file) => {
     const id = normalizeStackPieceId(file.slice(0, -3));
     const source = await readFile(path.join(directory, file), 'utf8');
-    const piece = parseStackPieceSource(source, { expectedId: id, path: `${sourcePrefix}:${id}` });
+    const piece = parsedStackPiece(source, id, `${sourcePrefix}:${id}`);
     return {
       ...piece,
       skill: piece.skill === null ? null : { ...piece.skill, resolveFrom: stackPackageRoot },

package/src/index/stack-section-inspection.js

@@ -1,8 +1,5 @@
-import { realpath, stat } from 'node:fs/promises';
-import path from 'node:path';
-
 import { GENESIS_CONTRACTS } from './contracts.js';
-import { gitContext } from './git.js';
+import { inspectionRoot } from './git.js';
 import { readStack } from './stack.js';
 import { normalizeStackSectionName } from './stack-section.js';
 import { sha256, stableJson } from './utils.js';
@@ -29,18 +26,7 @@ export async function inspectProjectStackSections({
   if (new Set(sectionNames).size !== sectionNames.length) {
     throw new TypeError('Stack section inspection requires distinct names.');
   }
-  let root;
-  if (rootMode === 'repository') {
-    root = (await gitContext(projectRoot)).repositoryRoot;
-  } else if (rootMode === 'directory') {
-    if (typeof projectRoot !== 'string' || !path.isAbsolute(projectRoot)) {
-      throw new TypeError('Directory inspection requires an explicit absolute projectRoot.');
-    }
-    root = await realpath(projectRoot);
-    if (!(await stat(root)).isDirectory()) throw new TypeError('Directory inspection requires a directory.');
-  } else {
-    throw new TypeError('Stack section rootMode must be repository or directory.');
-  }
+  const root = await inspectionRoot({ projectRoot, rootMode, subject: 'Stack section' });
   const stack = await readStack(root, { stackPackages });
   return sectionNames.map((sectionName) => {
     const section = stack.extensions.find((candidate) => candidate.name === sectionName);