genesis-compiler 1.2.29 → 1.3.0

package/src/index/prompt.js

@@ -2,6 +2,7 @@ import { readInstalledAsset } from './assets.js';
 import { inspectProjectSkills, renderAgentSkillCatalog } from './agent-skills.js';
 import { buildProjectIndex, MACHINE_CITY_PATH, PROGRAM_CITY_PATH } from './code-index.js';
 import { BLUEPRINT_SKELETON_SOURCE, readBlueprint } from './blueprint.js';
+import { defaultCollaboration, readCollaboration } from './collaboration.js';
 import {
   engineeringPromptContext,
   listEngineeringProfileCatalog,
@@ -18,6 +19,7 @@ import { missingStackResources } from './stack-preflight.js';
 import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { stableJson } from './utils.js';
 import { classifyProjectKind } from './project-files.js';
+import { inspectProjectFormatAtRoot } from './project-format.js';
 
 const TASKS = new Set(['start', 'adopt', 'work', 'deslop', 'program', 'blueprint', 'describe', 'review']);
 const DEFAULT_REQUEST = {
@@ -128,6 +130,7 @@ function renderPrompt({
   cleanup = '',
   postChange = '',
   adoption = '',
+  collaborationGuidance = '',
   engineeringGuidance = '',
 }) {
   return [
@@ -143,6 +146,7 @@ function renderPrompt({
     stableJson(context).trimEnd(),
     '```',
     ...(engineeringGuidance ? ['', 'ENGINEERING APPROACH', '', engineeringGuidance] : []),
+    ...(collaborationGuidance ? ['', 'COLLABORATION APPROACH', '', collaborationGuidance] : []),
     ...(guidance ? ['', 'SELECTED STACK GUIDANCE', '', guidance] : []),
     ...(adoption ? ['', 'SELECTED STACK ADOPTION GUIDANCE', '', adoption] : []),
     ...(skills ? ['', 'AVAILABLE AGENT SKILLS', '', skills] : []),
@@ -152,7 +156,43 @@ function renderPrompt({
   ].join('\n');
 }
 
-async function generateAdoptionPrompt({ engineering, environment, instructions, program, request, root, stackPackages }) {
+function collaborationPromptContext(collaboration) {
+  return {
+    path: collaboration.path,
+    status: collaboration.status,
+    tone: collaboration.tone,
+    responseLength: collaboration.responseLength,
+    experience: collaboration.experience,
+    explanationStyle: collaboration.explanationStyle,
+    requirements: collaboration.requirements || 'Nothing.',
+  };
+}
+
+function stableSessionPromptParts({ collaboration, engineering, installed }) {
+  return installed
+    ? { context: {}, collaborationGuidance: '', engineeringGuidance: '' }
+    : {
+        context: {
+          collaboration: collaborationPromptContext(collaboration),
+          engineering: engineeringPromptContext(engineering),
+        },
+        collaborationGuidance: collaboration.guidance,
+        engineeringGuidance: engineering.guidance,
+      };
+}
+
+async function collaborationForPrompt(projectRoot) {
+  try {
+    return await readCollaboration(projectRoot);
+  } catch (error) {
+    if (error?.code !== 'COLLABORATION_REQUIRED') throw error;
+    const format = await inspectProjectFormatAtRoot(projectRoot);
+    if (format.status !== 'uninitialized') throw error;
+    return defaultCollaboration();
+  }
+}
+
+async function generateAdoptionPrompt({ environment, instructions, program, request, root, sessionPrompt, stackPackages }) {
   const blueprint = await readBlueprint(root, { required: true });
   const stack = await readStack(root, { stackPackages });
   const availableStackPackages = [...new Set([...stack.stackPackages, ...stackPackages])];
@@ -176,7 +216,7 @@ async function generateAdoptionPrompt({ engineering, environment, instructions,
         projectRoot: root,
         projectKind: 'existing',
         blueprint: { path: blueprint.path, source: blueprint.source },
-        engineering: engineeringPromptContext(engineering),
+        ...sessionPrompt.context,
         stack: stackPromptContext(stack),
         availableStackPieces: stackCatalogContext(catalog),
         program: programContext(program),
@@ -185,7 +225,8 @@ async function generateAdoptionPrompt({ engineering, environment, instructions,
           : { status: 'present' },
         codeIndex: codeIndexContext(index),
       },
-      engineeringGuidance: engineering.guidance,
+      collaborationGuidance: sessionPrompt.collaborationGuidance,
+      engineeringGuidance: sessionPrompt.engineeringGuidance,
       guidance: stack.guidance,
       adoption: stack.adoption,
       skills: renderAgentSkillCatalog(projectSkills.skills),
@@ -200,7 +241,7 @@ async function generateAdoptionPrompt({ engineering, environment, instructions,
   };
 }
 
-async function generateExplanationPrompt({ engineering, instructions, program, request, root, stackPackages, task }) {
+async function generateExplanationPrompt({ instructions, program, request, root, sessionPrompt, stackPackages, task }) {
   const blueprint = await readBlueprint(root, {
     required: true,
     requireDescription: task === 'program',
@@ -223,12 +264,13 @@ async function generateExplanationPrompt({ engineering, instructions, program, r
         task,
         projectRoot: root,
         blueprint: blueprintContext,
-        engineering: engineeringPromptContext(engineering),
+        ...sessionPrompt.context,
         stack: stackPromptContext(stack),
         program: programContext(program),
         codeIndex: codeIndexContext(index),
       },
-      engineeringGuidance: engineering.guidance,
+      collaborationGuidance: sessionPrompt.collaborationGuidance,
+      engineeringGuidance: sessionPrompt.engineeringGuidance,
       guidance: stack.guidance,
       skills: renderAgentSkillCatalog(projectSkills.skills),
     }),
@@ -243,11 +285,11 @@ async function generateExplanationPrompt({ engineering, instructions, program, r
 
 async function generateStartPrompt({
   hiddenStackPieces,
-  engineering,
   instructions,
   program,
   request,
   root,
+  sessionPrompt,
   stackPackages,
 }) {
   let blueprint;
@@ -267,9 +309,10 @@ async function generateStartPrompt({
           projectRoot: root,
           projectKind: 'existing-uninitialized',
           genesis: { initialized: false },
-          engineering: engineeringPromptContext(engineering),
+          ...sessionPrompt.context,
         },
-        engineeringGuidance: engineering.guidance,
+        collaborationGuidance: sessionPrompt.collaborationGuidance,
+        engineeringGuidance: sessionPrompt.engineeringGuidance,
       }),
       warnings: program.diagnostic ? [program.diagnostic] : [],
       verificationCommands: [],
@@ -306,7 +349,7 @@ async function generateStartPrompt({
           path: blueprint.path,
           description: blueprint.description,
         },
-        engineering: engineeringPromptContext(engineering),
+        ...sessionPrompt.context,
         stack: startStackContext(stack),
         ...(projectKind === 'new'
           ? {
@@ -315,7 +358,8 @@ async function generateStartPrompt({
           }
           : { program: startProgramContext(program) }),
       },
-      engineeringGuidance: engineering.guidance,
+      collaborationGuidance: sessionPrompt.collaborationGuidance,
+      engineeringGuidance: sessionPrompt.engineeringGuidance,
       guidance: stack.guidance,
     }),
     warnings: [
@@ -331,6 +375,7 @@ export async function generateProjectPrompt({
   hiddenStackPieces = [],
   projectRoot,
   request = '',
+  sessionContextInstalled = false,
   stackPackages = [],
   task = 'work',
 } = {}) {
@@ -339,10 +384,16 @@ export async function generateProjectPrompt({
   }
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const userRequest = requestText(request, task);
-  const [instructions, engineering] = await Promise.all([
+  const [instructions, collaboration, engineering] = await Promise.all([
     readInstalledAsset(task),
+    collaborationForPrompt(root),
     readEngineering(root),
   ]);
+  const sessionPrompt = stableSessionPromptParts({
+    collaboration,
+    engineering,
+    installed: sessionContextInstalled === true,
+  });
 
   if (task === 'blueprint') {
     const blueprint = await readBlueprint(root);
@@ -357,9 +408,10 @@ export async function generateProjectPrompt({
           path: 'genesis/blueprint.md',
           source: blueprint?.source || BLUEPRINT_SKELETON_SOURCE,
         },
-        engineering: engineeringPromptContext(engineering),
+        ...sessionPrompt.context,
       },
-      engineeringGuidance: engineering.guidance,
+      collaborationGuidance: sessionPrompt.collaborationGuidance,
+      engineeringGuidance: sessionPrompt.engineeringGuidance,
       skills: renderAgentSkillCatalog(projectSkills.skills),
     });
     return {
@@ -376,21 +428,21 @@ export async function generateProjectPrompt({
     return generateStartPrompt({
       instructions,
       hiddenStackPieces,
-      engineering,
       program,
       request: userRequest,
       root,
+      sessionPrompt,
       stackPackages,
     });
   }
   if (task === 'adopt') {
     return generateAdoptionPrompt({
       environment,
-      engineering,
       instructions,
       program,
       request: userRequest,
       root,
+      sessionPrompt,
       stackPackages,
     });
   }
@@ -403,10 +455,10 @@ export async function generateProjectPrompt({
       return generateStartPrompt({
         instructions: await readInstalledAsset('start'),
         hiddenStackPieces,
-        engineering,
         program,
         request: userRequest,
         root,
+        sessionPrompt,
         stackPackages,
       });
     }
@@ -414,10 +466,10 @@ export async function generateProjectPrompt({
       return generateStartPrompt({
         instructions: await readInstalledAsset('start'),
         hiddenStackPieces,
-        engineering,
         program,
         request: userRequest,
         root,
+        sessionPrompt,
         stackPackages,
       });
     }
@@ -425,10 +477,10 @@ export async function generateProjectPrompt({
   if (['describe', 'program'].includes(task)) {
     return generateExplanationPrompt({
       instructions,
-      engineering,
       program,
       request: userRequest,
       root,
+      sessionPrompt,
       stackPackages,
       task,
     });
@@ -454,7 +506,7 @@ export async function generateProjectPrompt({
     task,
     projectRoot: root,
     blueprint: { path: blueprint.path, description: blueprint.description },
-    engineering: engineeringPromptContext(engineering),
+    ...sessionPrompt.context,
     stack: stackPromptContext(stack),
     program: programContext(program),
     resourceInputs: missing.length > 0
@@ -472,7 +524,8 @@ export async function generateProjectPrompt({
     instructions,
     request: userRequest,
     context,
-    engineeringGuidance: engineering.guidance,
+    collaborationGuidance: sessionPrompt.collaborationGuidance,
+    engineeringGuidance: sessionPrompt.engineeringGuidance,
     guidance: stack.guidance,
     skills: renderAgentSkillCatalog(projectSkills.skills),
     postChange: task === 'work' ? stack.postChange : '',

package/src/index/session-context.js

@@ -1,7 +1,16 @@
+import { readCollaboration } from './collaboration.js';
+import { GENESIS_CONTRACTS } from './contracts.js';
 import { readEngineering, readEngineeringBaseline } from './engineering.js';
+import { GenesisError } from './errors.js';
 import { gitContext } from './git.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: 16 * 1024,
+  turn: 512,
+});
 
 async function optionalStack(projectRoot, stackPackages) {
   try { return await readStack(projectRoot, { stackPackages }); } catch { return null; }
@@ -24,6 +33,65 @@ async function optionalEngineering(projectRoot) {
   }
 }
 
+async function optionalCollaboration(projectRoot) {
+  try {
+    return await readCollaboration(projectRoot);
+  } catch {
+    return {
+      guidance: [
+        'The project collaboration approach is invalid. Do not infer replacement preferences; run the Genesis `check` operation.',
+      ].join('\n'),
+    };
+  }
+}
+
+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])];
@@ -34,40 +102,62 @@ async function optionalStackComponentIds(projectRoot, stack, stackPackages) {
   }
 }
 
-export async function projectSessionContext({ projectRoot, stackPackages = [] } = {}) {
+export async function projectSessionContext({
+  hostDriver,
+  hostDriverInput,
+  projectRoot,
+  stackPackages = [],
+} = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
-  const [stack, engineering] = await Promise.all([
+  const [stack, collaboration, engineering, hostContext] = await Promise.all([
     optionalStack(root, stackPackages),
+    optionalCollaboration(root),
     optionalEngineering(root),
+    hostContextContribution({ hostDriver, hostDriverInput, scope: 'session' }),
   ]);
   const availableComponents = await optionalStackComponentIds(root, stack, stackPackages);
   const selected = stack?.components.map(({ id }) => id) || [];
   const stackStatus = stack
     ? (selected.length > 0 ? selected.join(', ') : 'none')
     : 'unavailable; run the Genesis `check` operation';
+  const output = [
+    'This is a Genesis-enriched project.',
+    '- 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.',
+    `- Available Stack components: ${availableComponents.length > 0 ? availableComponents.map((id) => `\`${id}\``).join(', ') : 'none'}.`,
+    '- When the user names an unselected technology that exactly matches this catalog, run `genesis stack list`, ask whether to add and prepare it, and wait for confirmation. If confirmed, run `genesis stack add <piece...>` and follow its returned preparation prompt in the same task; then use `genesis context` and any installed technology skill. Never infer dependency commands from a component id. If declined or unmatched, continue through authoritative technology documentation without inventing a component.',
+    '- Project-owned operation sections in `genesis/stack.md` are the durable application contract. Make the implementation satisfy them or update a complete section to match evidenced reality; Genesis executes only Verification.',
+    '- Use the relevant project Agent Skills below `.agents/skills/`.',
+    '- After locating source, run `genesis context <path...>`; before adding a helper or public operation, run `genesis index <name-or-path...>` and reuse an existing owner.',
+    '- 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.',
+    '- 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}.`,
+    '',
+    'ENGINEERING APPROACH',
+    '',
+    engineering.guidance,
+    '',
+    'COLLABORATION APPROACH',
+    '',
+    collaboration.guidance,
+    ...(hostContext ? ['', 'HOST CONTEXT', '', hostContext] : []),
+  ].join('\n');
+  return composedContext(GENESIS_CONTRACTS.sessionContext, output);
+}
+
+export async function projectTurnContext({ hostDriver, hostDriverInput } = {}) {
+  const output = await hostContextContribution({
+    hostDriver,
+    hostDriverInput,
+    scope: 'turn',
+  });
   return {
-    status: 'ready',
-    output: [
-      'This is a Genesis-enriched project.',
-      '- Read `genesis/blueprint.md`, `genesis/engineering.md`, and `genesis/stack.md` for product intent, 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.',
-      `- Available Stack components: ${availableComponents.length > 0 ? availableComponents.map((id) => `\`${id}\``).join(', ') : 'none'}.`,
-      '- When the user names an unselected technology that exactly matches this catalog, run `genesis stack list`, ask whether to add and prepare it, and wait for confirmation. If confirmed, run `genesis stack add <piece...>` and follow its returned preparation prompt in the same task; then use `genesis context` and any installed technology skill. Never infer dependency commands from a component id. If declined or unmatched, continue through authoritative technology documentation without inventing a component.',
-      '- Project-owned operation sections in `genesis/stack.md` are the durable application contract. Make the implementation satisfy them or update a complete section to match evidenced reality; Genesis executes only Verification.',
-      '- Use the relevant project Agent Skills below `.agents/skills/`.',
-      '- After locating source, run `genesis context <path...>`; before adding a helper or public operation, run `genesis index <name-or-path...>` and reuse an existing owner.',
-      '- 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.',
-      '- 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}.`,
-      '',
-      'ENGINEERING APPROACH',
-      '',
-      engineering.guidance,
-    ].join('\n'),
+    ...composedContext(GENESIS_CONTRACTS.turnContext, output),
+    trust: 'untrusted',
   };
 }

package/src/index.js

@@ -2,6 +2,10 @@ import path from 'node:path';
 
 import { checkProject } from './index/check.js';
 import { buildProjectIndex, GENESIS_DERIVED_ARTIFACTS } from './index/code-index.js';
+import {
+  inspectProjectCollaboration,
+  setProjectCollaboration,
+} from './index/collaboration.js';
 import { GENESIS_CONTRACTS } from './index/contracts.js';
 import { contextForProjectPaths } from './index/context.js';
 import { generateProjectPrompt } from './index/prompt.js';
@@ -19,8 +23,21 @@ import { listStackCatalogPieces } from './index/stack-catalog.js';
 import { addStackPieces, readStack } from './index/stack.js';
 import { uniqueSorted } from './index/utils.js';
 import { verifyProject } from './index/verification.js';
-
-export { GENESIS_CONTRACTS };
+import { projectSessionContext, projectTurnContext } from './index/session-context.js';
+import {
+  HOST_CONTEXT_RESOLVER_DATA_ENV,
+  HOST_CONTEXT_RESOLVER_ENV,
+  SESSION_CONTEXT_INSTALLED_ENV,
+} from './index/host-context-resolver.js';
+
+export {
+  GENESIS_CONTRACTS,
+  HOST_CONTEXT_RESOLVER_DATA_ENV,
+  HOST_CONTEXT_RESOLVER_ENV,
+  SESSION_CONTEXT_INSTALLED_ENV,
+  projectSessionContext,
+  projectTurnContext,
+};
 
 function withIndexResult(result, index) {
   const changedFiles = uniqueSorted([...result.changedFiles, ...index.changedFiles]);
@@ -115,6 +132,10 @@ export function inspectEnvironment(options) {
   return inspectProjectEnvironment(options);
 }
 
+export function inspectCollaboration(options) {
+  return inspectProjectCollaboration(options);
+}
+
 export function inspectStackSection(options) {
   return inspectProjectStackSection(options);
 }
@@ -131,6 +152,10 @@ export function setEngineeringProfile(options) {
   return selectEngineeringProfile(options);
 }
 
+export function setCollaboration(options) {
+  return setProjectCollaboration(options);
+}
+
 export function generatePrompt(options) {
   return generateProjectPrompt(options);
 }