genesis-compiler 1.2.27 → 1.2.29

package/src/index/migration.js

@@ -11,14 +11,17 @@ import {
   writeProjectFormatVersion,
 } from './project-format.js';
 import { PROJECT_VERSION_PATH } from './paths.js';
-import { readStack } from './stack.js';
+import {
+  materializeProjectStackContracts,
+  readLegacyStack,
+} from './stack.js';
 import { uniqueSorted } from './utils.js';
 
 async function validateLegacyProject({ projectRoot, stackPackages }) {
   try {
     await readBlueprint(projectRoot, { required: true });
     await readEngineering(projectRoot);
-    await readStack(projectRoot, { stackPackages });
+    await readLegacyStack(projectRoot, { stackPackages });
     try {
       await inspectProgram(projectRoot);
     } catch (error) {
@@ -33,8 +36,13 @@ async function validateLegacyProject({ projectRoot, stackPackages }) {
   }
 }
 
+async function materializeProjectContracts({ projectRoot, stackPackages }) {
+  return materializeProjectStackContracts({ projectRoot, stackPackages });
+}
+
 const MIGRATIONS = new Map([
   [0, validateLegacyProject],
+  [1, materializeProjectContracts],
 ]);
 
 export async function migrateProject({ projectRoot, stackPackages = [] } = {}) {
@@ -62,7 +70,8 @@ export async function migrateProject({ projectRoot, stackPackages = [] } = {}) {
         { projectVersion: version, supportedVersion: CURRENT_PROJECT_FORMAT_VERSION },
       );
     }
-    await migration({ projectRoot: root, stackPackages });
+    const result = await migration({ projectRoot: root, stackPackages });
+    migratedFiles.push(...(result?.changedFiles || []));
     version += 1;
     await writeProjectFormatVersion(root, version);
     migratedFiles.push(PROJECT_VERSION_PATH);

package/src/index/opencode-plugin.js

@@ -2,9 +2,9 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import { gitContext } from './git.js';
+import { OPENCODE_PLUGIN_PATH } from './paths.js';
 import { writeFileAtomic } from './utils.js';
 
-const OPENCODE_PLUGIN_PATH = '.opencode/plugins/genesis-project-guidance.js';
 const OPENCODE_PLUGIN_SOURCE = new URL('../../plugins/opencode/project-guidance.js', import.meta.url);
 
 async function existingSource(location) {

package/src/index/paths.js

@@ -4,6 +4,7 @@ export const STACK_PATH = 'genesis/stack.md';
 export const PROGRAM_ROOT = 'genesis/program';
 export const PROJECT_VERSION_PATH = 'genesis/version';
 export const VERIFICATION_PATH = '.genesis/verification.json';
+export const OPENCODE_PLUGIN_PATH = '.opencode/plugins/genesis-project-guidance.js';
 
 export function isProjectContentPath(file) {
   const first = file.split('/')[0];

package/src/index/project-files.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 
+import { isProjectContentPath, OPENCODE_PLUGIN_PATH } from './paths.js';
 import { runGit } from './process.js';
 import { pathState } from './utils.js';
 
@@ -22,3 +23,14 @@ export async function gitVisibleFileStates(projectRoot, { includePath = () => tr
   }
   return states;
 }
+
+/** 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';
+}

package/src/index/project-format.js

@@ -12,7 +12,7 @@ import {
 } from './paths.js';
 import { normalizeSource, pathState, writeFileAtomic } from './utils.js';
 
-export const CURRENT_PROJECT_FORMAT_VERSION = 1;
+export const CURRENT_PROJECT_FORMAT_VERSION = 2;
 export const CURRENT_PROJECT_FORMAT_SOURCE = `${CURRENT_PROJECT_FORMAT_VERSION}\n`;
 
 const VERSION_PATTERN = /^(0|[1-9][0-9]*)\n?$/u;

package/src/index/prompt.js

@@ -17,8 +17,7 @@ import { inspectVerification } from './project-state.js';
 import { missingStackResources } from './stack-preflight.js';
 import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { stableJson } from './utils.js';
-import { gitVisibleFileStates } from './project-files.js';
-import { isProjectContentPath } from './paths.js';
+import { classifyProjectKind } from './project-files.js';
 
 const TASKS = new Set(['start', 'adopt', 'work', 'deslop', 'program', 'blueprint', 'describe', 'review']);
 const DEFAULT_REQUEST = {
@@ -83,6 +82,26 @@ function programContext(program) {
   };
 }
 
+function startProgramContext(program) {
+  return {
+    status: program.status,
+    subsystems: program.subsystems,
+    moduleCount: program.modules.length,
+    ...(program.diagnostic ? { diagnostic: program.diagnostic } : {}),
+  };
+}
+
+function startStackContext(stack) {
+  return {
+    components: stack.components.map(({ id, description }) => ({ id, description })),
+  };
+}
+
+async function startInstructions(instructions, projectKind) {
+  const specific = await readInstalledAsset(`start-${projectKind}`);
+  return `${instructions.trim()}\n\n${specific.trim()}`;
+}
+
 function codeIndexContext(index) {
   return {
     machineCity: {
@@ -231,21 +250,17 @@ async function generateStartPrompt({
   root,
   stackPackages,
 }) {
-  const availableEngineeringProfiles = (await listEngineeringProfileCatalog())
-    .map(({ id, name, description }) => ({ id, name, description }));
   let blueprint;
   try {
     blueprint = await readBlueprint(root, { required: true });
   } catch (error) {
     if (error?.code !== 'BLUEPRINT_REQUIRED') throw error;
-    const files = await gitVisibleFileStates(root, { includePath: isProjectContentPath });
-    const existing = [...files.values()].some((state) => state.exists);
-    if (!existing) throw error;
+    if (await classifyProjectKind({ projectRoot: root }) === 'new') throw error;
     return {
       status: 'ready',
       task: 'start',
       prompt: renderPrompt({
-        instructions,
+        instructions: await startInstructions(instructions, 'existing-uninitialized'),
         request,
         context: {
           task: 'start',
@@ -253,8 +268,6 @@ async function generateStartPrompt({
           projectKind: 'existing-uninitialized',
           genesis: { initialized: false },
           engineering: engineeringPromptContext(engineering),
-          availableEngineeringProfiles,
-          program: programContext(program),
         },
         engineeringGuidance: engineering.guidance,
       }),
@@ -263,42 +276,51 @@ async function generateStartPrompt({
     };
   }
   const stack = await readStack(root, { stackPackages });
+  const projectKind = await classifyProjectKind({
+    projectRoot: root,
+    stackComponents: stack.components,
+  });
   const availableStackPackages = [...new Set([...stack.stackPackages, ...stackPackages])];
-  const [index, catalog] = await Promise.all([
-    buildProjectIndex({ projectRoot: root, stackPackages, write: false }),
-    listStackCatalogPieces({ projectRoot: root, stackPackages: availableStackPackages }),
+  const [catalog, availableEngineeringProfiles, projectSkills, renderedInstructions] = await Promise.all([
+    projectKind === 'new'
+      ? listStackCatalogPieces({ projectRoot: root, stackPackages: availableStackPackages })
+      : Promise.resolve([]),
+    projectKind === 'new'
+      ? listEngineeringProfileCatalog()
+        .then((profiles) => profiles.map(({ id, name, description }) => ({ id, name, description })))
+      : Promise.resolve([]),
+    inspectProjectSkills({ projectRoot: root, stack }),
+    startInstructions(instructions, projectKind),
   ]);
-  const projectSkills = await inspectProjectSkills({ projectRoot: root, stack });
-  const newProject = stack.components.length === 0 && index.fileCount === 0;
   return {
     status: 'ready',
     task: 'start',
     prompt: renderPrompt({
-      instructions,
+      instructions: renderedInstructions,
       request,
       context: {
         task: 'start',
         projectRoot: root,
-        projectKind: newProject ? 'new' : 'existing',
+        projectKind,
         blueprint: {
           path: blueprint.path,
           description: blueprint.description,
         },
         engineering: engineeringPromptContext(engineering),
-        availableEngineeringProfiles,
-        stack: stackPromptContext(stack),
-        availableStackPieces: stackCatalogContext(catalog, hiddenStackPieces),
-        program: programContext(program),
-        codeIndex: codeIndexContext(index),
+        stack: startStackContext(stack),
+        ...(projectKind === 'new'
+          ? {
+            availableEngineeringProfiles,
+            availableStackPieces: stackCatalogContext(catalog, hiddenStackPieces),
+          }
+          : { program: startProgramContext(program) }),
       },
       engineeringGuidance: engineering.guidance,
       guidance: stack.guidance,
-      skills: renderAgentSkillCatalog(projectSkills.skills),
     }),
     warnings: [
       ...(program.diagnostic ? [program.diagnostic] : []),
       ...projectSkills.diagnostics,
-      ...index.diagnostics,
     ],
     verificationCommands: [],
   };

package/src/index/session-context.js

@@ -1,6 +1,7 @@
 import { readEngineering, readEngineeringBaseline } from './engineering.js';
 import { gitContext } from './git.js';
 import { readStack } from './stack.js';
+import { listStackCatalogPieces } from './stack-catalog.js';
 
 async function optionalStack(projectRoot, stackPackages) {
   try { return await readStack(projectRoot, { stackPackages }); } catch { return null; }
@@ -23,12 +24,23 @@ async function optionalEngineering(projectRoot) {
   }
 }
 
+async function optionalStackComponentIds(projectRoot, stack, stackPackages) {
+  try {
+    const packages = [...new Set([...(stack?.stackPackages || []), ...stackPackages])];
+    return (await listStackCatalogPieces({ projectRoot, stackPackages: packages }))
+      .map(({ id }) => id);
+  } catch {
+    return [];
+  }
+}
+
 export async function projectSessionContext({ projectRoot, stackPackages = [] } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const [stack, engineering] = await Promise.all([
     optionalStack(root, stackPackages),
     optionalEngineering(root),
   ]);
+  const availableComponents = await optionalStackComponentIds(root, stack, stackPackages);
   const selected = stack?.components.map(({ id }) => id) || [];
   const stackStatus = stack
     ? (selected.length > 0 ? selected.join(', ') : 'none')
@@ -38,10 +50,16 @@ export async function projectSessionContext({ projectRoot, stackPackages = [] }
     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'}.`,

package/src/index/stack-catalog.js

@@ -10,6 +10,7 @@ import {
 
 const require = createRequire(import.meta.url);
 const PACKAGE_NAME = /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/u;
+const FIRST_PARTY_STACK_PACKAGE = 'genesis-stack';
 
 export function normalizeStackPackageName(value) {
   const name = String(value ?? '').trim();
@@ -50,6 +51,16 @@ async function packageDirectory(packageName, projectRoot) {
   );
 }
 
+export async function installedFirstPartyStackPackages({ projectRoot } = {}) {
+  try {
+    await packageDirectory(FIRST_PARTY_STACK_PACKAGE, projectRoot);
+    return [FIRST_PARTY_STACK_PACKAGE];
+  } catch (error) {
+    if (error?.code === 'STACK_PACKAGE_UNAVAILABLE') return [];
+    throw error;
+  }
+}
+
 async function readPieceDirectory(
   directory,
   sourcePrefix,

package/src/index/stack-project-contracts.js

@@ -0,0 +1,205 @@
+import { GenesisError } from './errors.js';
+import { composeStackEnvironmentDefaults } from './stack-environment-defaults.js';
+import { composeStackEnvironmentFiles } from './stack-environment-files.js';
+import {
+  composeStackSections,
+  opaqueStackSections,
+  trimStackSectionLines,
+} from './stack-section.js';
+
+const PROJECT_CONTRACT_NAMES = [
+  'Resources',
+  'Environment defaults',
+  'Environment files',
+  'Verification',
+];
+
+function distinctVerificationCommands(components) {
+  const seen = new Set();
+  return components.flatMap(({ verificationCommands }) => verificationCommands)
+    .filter(({ label, argv }) => {
+      const key = JSON.stringify([label, argv]);
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+}
+
+function projectResource(resource) {
+  return {
+    id: resource.id,
+    kind: resource.kind,
+    environmentAlternatives: resource.environmentAlternatives.map((alternative) => ({
+      bindings: alternative.bindings,
+      ...(alternative.allowEmpty.length > 0 ? { allowEmpty: alternative.allowEmpty } : {}),
+      ...(alternative.preferred ? { preferred: true } : {}),
+    })),
+    ...(Object.keys(resource.optionalBindings).length > 0
+      ? { optionalBindings: resource.optionalBindings }
+      : {}),
+  };
+}
+
+function resourceLines(components) {
+  const resources = components.flatMap(({ resources }) => resources);
+  if (resources.length === 0) return null;
+  return resources.flatMap((resource, index) => [
+    ...(index > 0 ? [''] : []),
+    '```json genesis-resource',
+    JSON.stringify(projectResource(resource), null, 2),
+    '```',
+  ]);
+}
+
+function environmentDefaultLines(components) {
+  const defaults = composeStackEnvironmentDefaults(components);
+  if (defaults.length === 0) return null;
+  return defaults.map(({ name, value }) => `- Default \`${name}\`: \`${value}\``);
+}
+
+function environmentFileLines(components) {
+  const files = composeStackEnvironmentFiles(components, null);
+  if (files.length === 0) return null;
+  return files.map(({ path }) => `- Dotenv \`${path}\``);
+}
+
+function verificationLines(components) {
+  const commands = distinctVerificationCommands(components);
+  if (commands.length === 0) return null;
+  return commands.map(({ label, argv }) => (
+    `- Verify \`${label}\`: ${argv.map((value) => `\`${value}\``).join(' ')}`
+  ));
+}
+
+function componentGenesisContracts(components, sections) {
+  return new Map([
+    ['Resources', sections.has('Resources') ? null : resourceLines(components)],
+    ['Environment defaults', sections.has('Environment defaults')
+      ? null
+      : environmentDefaultLines(components)],
+    ['Environment files', sections.has('Environment files')
+      ? null
+      : environmentFileLines(components)],
+    ['Verification', sections.has('Verification') ? null : verificationLines(components)],
+  ].filter(([, lines]) => lines !== null));
+}
+
+export function stackPieceContractNames(piece) {
+  return [
+    ...(piece.resources.length > 0 ? ['Resources'] : []),
+    ...(piece.environmentDefaults.length > 0 ? ['Environment defaults'] : []),
+    ...(piece.environmentFiles.length > 0 ? ['Environment files'] : []),
+    ...(piece.verificationCommands.length > 0 ? ['Verification'] : []),
+    ...piece.extensions.map(({ name }) => name),
+  ];
+}
+
+function contractSections({ components, knownSectionNames, sections }) {
+  const genesisContracts = componentGenesisContracts(components, sections);
+  const materializedSections = [];
+  const projectLines = new Map();
+
+  for (const name of PROJECT_CONTRACT_NAMES) {
+    if (sections.has(name)) {
+      projectLines.set(name, trimStackSectionLines(sections.get(name)));
+    } else if (genesisContracts.has(name)) {
+      projectLines.set(name, genesisContracts.get(name));
+      materializedSections.push(name);
+    }
+  }
+
+  const extensions = composeStackSections(
+    components,
+    opaqueStackSections(sections, knownSectionNames),
+  );
+  for (const extension of extensions) {
+    const [diagnostic] = extension.diagnostics;
+    if (diagnostic) {
+      throw new GenesisError(diagnostic.code, diagnostic.message, diagnostic.details);
+    }
+    projectLines.set(extension.name, trimStackSectionLines(extension.lines));
+    if (!sections.has(extension.name)) materializedSections.push(extension.name);
+  }
+
+  return {
+    environmentDefaultLines: projectLines.get('Environment defaults') ?? null,
+    environmentFileLines: projectLines.get('Environment files') ?? null,
+    extensionSections: [...projectLines.entries()]
+      .filter(([name]) => !PROJECT_CONTRACT_NAMES.includes(name))
+      .map(([name, lines]) => ({ name, lines })),
+    materializedSections,
+    projectContracts: [...projectLines].map(([name, lines]) => ({ name, lines })),
+    resourceLines: projectLines.get('Resources') ?? null,
+    verificationLines: projectLines.get('Verification') ?? null,
+  };
+}
+
+export function materializeStackProjectContracts(options) {
+  return contractSections(options);
+}
+
+export function requireMaterializedStackProjectContracts(options) {
+  const result = contractSections(options);
+  if (result.materializedSections.length > 0) {
+    const headings = result.materializedSections.map((name) => `\`## ${name}\``);
+    throw new GenesisError(
+      'STACK_PROJECT_CONTRACTS_INCOMPLETE',
+      `Selected Stack components require project-owned contracts missing from genesis/stack.md: ${headings.join(', ')}. Run \`genesis migrate\` for an older project or re-run the confirmed \`genesis stack add\` operation for a current project.`,
+      { sections: result.materializedSections },
+    );
+  }
+  return result;
+}
+
+function contractBlocks(projectContracts) {
+  if (projectContracts.length === 0) {
+    return [
+      'No operation contract was proposed by these components. Inspect the application you are creating and declare only its real setup, verification, output, and other consumer operations before calling it ready.',
+    ];
+  }
+  return projectContracts.flatMap(({ name, lines }) => [
+    `### \`## ${name}\``,
+    '',
+    '~~~markdown',
+    ...lines,
+    '~~~',
+    '',
+  ]);
+}
+
+export function renderStackPreparationPrompt({
+  components,
+  materializedSections = [],
+  newlySelected = [],
+  projectContracts = [],
+  reviewSections = [],
+} = {}) {
+  if (newlySelected.length === 0 && materializedSections.length === 0) return '';
+  const selected = components.map(({ id }) => `\`${id}\``).join(', ');
+  return [
+    '# Prepare the selected Stack',
+    '',
+    `Genesis selected ${selected} and made its concrete operation proposals project-owned in \`genesis/stack.md\`. That file is now the durable contract for this application; future catalog releases must not silently change it.`,
+    ...(materializedSections.length > 0 ? [
+      '',
+      `Materialized contract headings: ${materializedSections.map((name) => `\`## ${name}\``).join(', ')}.`,
+    ] : []),
+    ...(reviewSections.length > 0 ? [
+      '',
+      `These existing project contracts remained authoritative while the new components were added: ${reviewSections.map((name) => `\`## ${name}\``).join(', ')}. Reconcile them against the newly selected technology using source evidence; Genesis deliberately did not overwrite them.`,
+    ] : []),
+    '',
+    'Continue this same task now:',
+    '',
+    '1. Read `genesis/blueprint.md`, `genesis/engineering.md`, and the complete `genesis/stack.md`, then run `genesis context .` (or the relevant source paths).',
+    '2. Load every applicable installed Agent Skill and follow the selected technology’s authoritative guidance before creating dependencies or source.',
+    '3. For a new project, implement the source and commands so every project contract below is true. For existing source, inspect reality first and change a complete project section when the inherited proposal is not already true; do not add compatibility code merely to imitate a proposal.',
+    '4. Keep each consumer-owned section opaque to Genesis. Validate it with the consumer or framework that owns its grammar and behavior.',
+    '5. Establish or update the non-technical Blueprint and affected Program explanations as the product becomes concrete.',
+    '6. Run `genesis check`, resolve structural or incomplete-contract diagnostics, and run `genesis verify` only after the declared verification commands exist. Passing verification is evidence for those commands, not proof of every consumer operation.',
+    '',
+    '## Project contracts to satisfy',
+    '',
+    ...contractBlocks(projectContracts),
+  ].join('\n').trimEnd();
+}

package/src/index/stack-section.js

@@ -31,8 +31,8 @@ export function opaqueStackSections(sections, knownNames) {
 
 /**
  * Compose consumer-owned Stack sections without interpreting their contents.
- * A project declaration replaces component defaults; otherwise exactly one
- * selected component may provide a section with a given name.
+ * An existing project declaration wins; otherwise exactly one selected
+ * component may propose a section for materialization under a given name.
  */
 export function composeStackSections(components = [], projectSections = []) {
   const projectByName = new Map(projectSections.map((section) => [section.name, section]));