genesis-compiler 1.2.26 → 1.2.28

package/docs/stack-components.md

@@ -46,7 +46,26 @@ Concise technology context.
 
 ## Resources
 
-- Resource `database` kind `postgresql`: `DATABASE_URL` OR `DB_HOST` + `DB_NAME`
+```json genesis-resource
+{
+  "id": "database",
+  "kind": "postgresql",
+  "environmentAlternatives": [
+    {
+      "bindings": {
+        "database": "DB_NAME",
+        "host": "DB_HOST",
+        "password": "DB_PASSWORD",
+        "port": "DB_PORT",
+        "username": "DB_USER"
+      },
+      "allowEmpty": ["password"],
+      "preferred": true
+    },
+    { "bindings": { "url": "DATABASE_URL" } }
+  ]
+}
+```
 
 ## Environment defaults
 
@@ -92,24 +111,27 @@ complete authoritative Agent Skill directory. `Indexers` selects installed
 structural adapters.
 `Resources`, `Environment defaults`, `Environment files`, and `Verification`
 use the small Genesis grammars documented below. Every other `##` section is an
-opaque extension.
+opaque extension. These component sections are initial proposals. They do not
+remain a hidden runtime layer beneath the project.
 
 ## Genesis-owned declarations
 
 Resources describe required external inputs as alternatives of environment
 variable names. Genesis can report which names are absent, but never reads a
-service, provisions infrastructure, or returns a supplied value. A project
-`## Resources` section replaces all component resource defaults.
+service, provisions infrastructure, or returns a supplied value. Selection
+materializes the composed proposal into the project's `## Resources` section.
 
-Environment defaults are public, non-secret constants. Component defaults
+Environment defaults are public, non-secret constants. Component proposals
 compose by variable name; identical values collapse and conflicting values
-fail. A project `## Environment defaults` section replaces component defaults.
-Explicit process values always win.
+fail. Selection writes the result into the project's `## Environment defaults`
+section. Explicit process values always win. Conventional host, port, driver,
+database, or username values may be proposed; passwords, tokens, and other
+secrets must not be invented.
 
 Environment files describe safe project-relative dotenv projection paths.
 Genesis returns only the format and path. It does not materialize the file,
-choose which values belong there, or store secrets. A project declaration
-replaces component declarations; otherwise paths compose.
+choose which values belong there, or store secrets. Component paths compose
+during selection and are then written as the project declaration.
 
 Verification contains exact argv tokens:
 
@@ -122,8 +144,9 @@ Verification contains exact argv tokens:
 
 Genesis is the consumer of this section. `genesis verify` runs the declared
 commands directly without a shell after generic resource preflight and records
-the exact successful code, Stack, and command hashes. A project Verification
-section replaces component defaults.
+the exact successful code, Stack, and command hashes. Selection writes proposed
+commands into the project Verification section; only that project section is
+executed afterward.
 
 ## Opaque extensions
 
@@ -131,12 +154,16 @@ Any other `##` heading is consumer-owned data. Genesis validates only the
 section name and composition. It does not parse the body, infer its purpose,
 validate a private schema, map runtimes, execute commands, or prove success.
 
-Composition is intentionally small:
+Proposal composition is intentionally small:
+
+1. An existing project section remains authoritative and is never overwritten.
+2. Without a project section, one component proposal is copied unchanged.
+3. Competing component proposals produce `STACK_SECTION_AMBIGUOUS`; Genesis
+   never merges their bodies or guesses a winner.
 
-1. A project section replaces component declarations with the same name.
-2. Without a project section, one component declaration is returned unchanged.
-3. Competing component declarations produce `STACK_SECTION_AMBIGUOUS`; Genesis
-   never merges their bodies.
+After selection every effective opaque section is project-owned. The component
+catalog may improve later without silently changing the application's setup,
+launch, deployment, packaging, signing, migration, or any other operation.
 
 Call `inspectStackSection({ name, projectRoot })` or:
 
@@ -152,12 +179,18 @@ firmware, desktop software, and future systems Genesis has never seen.
 
 ## Selection and identity
 
-`genesis stack add` records selected packages and component dependency closure
-without discarding project declarations. Stack identity includes component ids,
-resources, environment declarations, Verification commands, City presentation,
-and every opaque extension body. Changing any executable or consumer-owned
-contract therefore stales prior Genesis verification evidence even though
-Genesis does not interpret the extension.
+`genesis stack add` records selected packages and component dependency closure,
+materializes every missing operation proposal, and preserves existing project
+declarations. It then returns one preparation prompt containing every exact
+project contract heading and body. The current agent must make the source and
+commands satisfy those contracts or replace a complete section with evidenced
+reality. Repeating an already-complete selection is quiet.
+
+Stack identity includes component ids, project-owned resources, environment
+declarations, Verification commands, City presentation, and every opaque
+extension body. Changing any executable or consumer-owned contract therefore
+stales prior Genesis verification evidence even though Genesis does not
+interpret the extension.
 
 Prose and Agent Skill contents are instructions rather than verification
 evidence. Changes to Description, Guidance, Adoption, Post-change, Deslop, or
@@ -212,7 +245,16 @@ const operation = await inspectStackSection({
 });
 ```
 
-`inspectEnvironment()` uses `genesis.environment.v1` and never returns supplied
+`inspectEnvironment()` uses `genesis.environment.v2` and never returns supplied
 values. `inspectStackSection()` uses `genesis.stack-section.v1` and never
 interprets the section. There is no generic Genesis API that executes an opaque
 operation.
+
+## Project format migration
+
+Project format 2 removes runtime inheritance of operation declarations from
+the catalog. `genesis migrate` upgrades format 1 projects by composing the
+previously effective declarations once and writing them into
+`genesis/stack.md`. Existing project sections win exactly as they did before.
+Current-format reads reject a selected component whose required contract was
+not materialized, so a tool upgrade cannot quietly substitute a new proposal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.2.26",
+  "version": "1.2.28",
   "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.2.26",
+  "version": "1.2.28",
   "description": "Makes Codex aware of optional Genesis adoption for existing projects.",
   "author": {
     "name": "Mobily Enterprises"

package/plugins/opencode/project-guidance.js

@@ -50,8 +50,7 @@ export const GenesisProjectGuidance = async ({ directory, worktree } = {}) => {
       const sessionId = String(input.sessionID || input.sessionId || "").trim();
       if (!sessionId) return;
       const context = await contextForSession(sessionId);
-      const system = Array.isArray(output.system) ? output.system : [];
-      if (!system.includes(context)) output.system = [...system, context];
+      if (!output.system.includes(context)) output.system.push(context);
     }
   };
 };

package/prompts/adopt.txt

@@ -26,8 +26,9 @@ Adoption requirements.
 
 Read every selected technology skill named by the regenerated prompt and its
 relevant existing-application migration reference. Apply all SELECTED STACK
-ADOPTION GUIDANCE. Component defaults describe current foundations and are
-hypotheses until they match this source. They do not upgrade an older project.
+ADOPTION GUIDANCE. Materialized component proposals describe current
+foundations and remain hypotheses until they match this source. They do not
+upgrade an older project.
 
 Build one evidence-backed import inventory covering the selected technologies,
 public environment/resource declarations, concrete Verification commands, and
@@ -36,8 +37,8 @@ selected technology skill and the section's declared schema for any
 consumer-specific detail; do not invent a generic operational grammar.
 
 Translate observed contracts into exact project-owned Stack sections whenever
-the selected components' defaults differ. A project section replaces the
-component declaration for that concern, so it must be complete. Inspect retired
+a materialized proposal differs. Replace the complete section for that concern;
+do not leave a proposal that the implementation cannot perform. Inspect retired
 or tool-specific manifests as evidence and carry every still-valid fact into
 Genesis; never add a permanent legacy reader or shim. Do not delete an old
 manifest until all of its live facts have been accounted for.

package/prompts/deslop.txt

@@ -1,4 +1,6 @@
-Read and follow `.agents/skills/genesis-deslop/SKILL.md` completely.
+This Deslop task has already been rendered by Genesis. Do not generate another
+Deslop prompt. Read and follow `.agents/skills/genesis-deslop/SKILL.md`
+completely.
 
 This is an explicitly requested behavior-preserving cleanup of committed work.
 Resolve the commit or first-parent commit range from USER REQUEST exactly; when

package/prompts/start.txt

@@ -1,15 +1,37 @@
 Read and follow `.agents/skills/genesis-project/SKILL.md` completely.
 
-This is the project-opening conversation. Do not begin implementation until
-the product direction and any technology choice needed for the first useful
-step are clear.
+This is the project-opening conversation. For a new project, do not begin
+technology research 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.
 
-When `projectKind` is `new`, first ask what the app is about. Ask up to three
-concise, high-impact questions at a time. Use `availableStackPieces` to present
-only the relevant choices, explain them in product language, and let the user
-decide. Never silently select a technology. After an explicit choice, use the
-Genesis `stack add <piece...>` operation; do not edit `genesis/stack.md` by
-hand. Establish the non-technical Blueprint from the user's answers before
+When the user explicitly names a technology, framework, language, or database
+that is not selected, make the existing Genesis `stack list` operation the
+first technology action. If one catalog component exactly matches that choice,
+ask: "<Technology> is available in Genesis. Would you like me to add it to this
+project and prepare the app with its official guidance?" Do not run `stack add
+<piece...>` without that confirmation. If confirmed, add it, let Genesis apply
+its declared dependency closure and synchronize any skill the component
+declares. Follow the preparation prompt returned by `stack add` in this same
+task: make each materialized project contract true or replace a complete
+section with evidenced reality. Then run `context .` (or the relevant source
+path once source exists), load the applicable installed skill if present, and
+follow the technology-owned guidance to prepare actual project dependencies.
+Never infer an install command from a component id. If declined, continue
+without adding it or asking again.
+If no component matches, do not invent one; continue normally using
+authoritative technology documentation.
+
+When `projectKind` is `new`, establish what is being built, who or what will use
+or invoke it, and its first observable useful outcome. Ask up to three concise,
+high-impact questions at a time, and ask access, data, platform, or interface
+questions only when they are material to that product. Use
+`availableStackPieces` to present only the relevant choices, explain them in
+product language, and let the user decide. Never silently select a technology.
+After the user confirms the proposed component selection, use the Genesis
+`stack add <piece...>` operation; do not edit `genesis/stack.md` by hand.
+Establish the non-technical Blueprint from the user's answers before
 implementation.
 If the product direction becomes clear while Stack is still empty, do not end
 the turn after only writing or summarizing the Blueprint: present the relevant
@@ -35,13 +57,13 @@ If the existing implementation is not yet explained, recommend the Genesis
 description/adoption path instead of pretending its intent is known.
 When an existing implementation has no selected Stack yet, inspect its actual
 package scripts, build files, setup commands, server entrypoint, and readiness
-route before recording the user's technology choice. Consumer-owned sections
-declared by a component describe that component's current operational
-foundation; selecting the component does not port an older implementation to
-it. If the existing facts differ, add exact project-owned replacements using
-the consumer's current schema and the code that exists. Never report an
-inherited operation as usable merely because the component was selected, and
-never add compatibility implementation without the user asking for a port.
+route before recording the user's technology choice. Materialized component
+proposals describe that component's current operational foundation; selecting
+the component does not port an older implementation to it. If the existing
+facts differ, replace the complete project-owned section using the consumer's
+current schema and the code that exists. Never report a proposed operation as
+usable merely because the component was selected, and never add compatibility
+implementation without the user asking for a port.
 
 When `projectKind` is `existing-uninitialized`, ask what the user wants to
 understand or change and strongly recommend preparing the existing project for
@@ -53,5 +75,13 @@ operation yourself and follow its adoption prompt. If they decline, continue
 normally and do not repeat the recommendation.
 
 If the request already contains an unambiguous product description and an
-explicit Stack choice, you may apply that choice and establish the Blueprint.
-Otherwise this is a conversational turn: ask, listen, and preserve the source.
+explicit Stack choice, establish the Blueprint and ask for the component
+confirmation described above before applying that choice. Otherwise this is a
+conversational turn: ask, listen, and preserve the source.
+
+Once product direction and any relevant Stack selection are clear, choose one
+smallest implementation path through the applicable technology guidance, or
+authoritative technology documentation when the catalog has no match, and read
+only what that path requires. Do not survey alternative foundations, clone
+whole technology repositories, inspect unrelated package internals, or
+delegate research unless one concrete failure requires one exact investigation.

package/prompts/work.txt

@@ -3,7 +3,12 @@ implement the request in the ordinary local Git tree.
 
 Load the applicable official or project technology skills listed below. Use
 their normal generators, commands, packages, and established seams. Do not
-search package internals or unrelated manuals merely to reconfirm an exact lane.
+turn technology choices into another product questionnaire. Choose one smallest
+implementation path through selected guidance, or authoritative technology
+documentation when the catalog has no match, and read only what that path
+requires. Do not survey alternative foundations, clone whole technology
+repositories, inspect unrelated package internals, or delegate research unless
+one concrete failure requires one exact investigation.
 Before adding a helper or public operation, query the Genesis
 `index <name-or-path>` operation and reuse an existing function when it already
 owns the behavior.
@@ -20,8 +25,11 @@ a genuinely missing resource instead of constructing a parallel fallback.
 
 Apply any supplied Stack Post-change guidance before reporting completion. It
 belongs to this implementation turn and does not request a follow-up agent turn.
-Run focused checks when useful. Summarize files changed, checks actually run,
-and anything still requiring attention.
+Run focused checks when useful. Before reporting completion, compare the
+requested observable behavior, required inputs and resources, declared project
+operations, and focused evidence with what actually exists. Summarize
+files changed, checks actually run, anything not proven, and anything still
+requiring attention.
 
 If no Stack components are selected, continue the project-opening
 conversation instead of guessing a technology. Use the Genesis `stack list`

package/skills/genesis-deslop/SKILL.md

@@ -15,6 +15,23 @@ package. Otherwise use `genesis <arguments>` only when that executable is
 already available on `PATH`. Never install or update Genesis merely to satisfy
 a workflow instruction.
 
+## Load the effective project instructions once
+
+A Deslop request may arrive either as a complete Genesis-generated prompt or
+as a direct request such as `Deslop` in an agent session.
+
+If the current task already contains `GENESIS CONTEXT` whose task is `deslop`,
+continue with it directly. Do not generate another prompt.
+
+Otherwise, before resolving Git scope, run the Genesis
+`prompt --task deslop` operation once using the invocation rule above. For a
+bare `Deslop` request, pass no request argument. When the user names a count,
+commit, or range, pass that exact request as one safely quoted argument. Treat
+the printed prompt as the instructions for this same turn; do not dispatch it
+to another agent and do not generate it again. This step composes the selected
+Stack's technology-specific Deslop guidance and any project customization with
+the portable contract below.
+
 ## Resolve the committed scope
 
 Before reading or editing the selected change, require a clean worktree and

package/skills/genesis-project/SKILL.md

@@ -8,6 +8,21 @@ description: Work safely in a Genesis-enriched codebase using its Blueprint, Sta
 Genesis is an explanatory and verification companion. It does not replace the
 codebase, tests, Git review, or the coding agent.
 
+## Establish new-product direction
+
+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.
+
 ## Run Genesis commands
 
 When this repository is Genesis itself or has `genesis-compiler` installed
@@ -17,6 +32,28 @@ package. Otherwise use `genesis <arguments>` only when that executable is
 already available on `PATH`. Never install or update Genesis merely to satisfy
 a workflow instruction.
 
+## Resolve explicit technology choices
+
+Before external technology research or implementation, when the user explicitly
+names a technology, framework, language, or database that is not selected:
+
+1. Run the Genesis `stack list` operation as the first technology action.
+2. If one catalog component exactly matches the choice, ask: "<Technology> is
+   available in Genesis. Would you like me to add it to this project and prepare
+   the app with its official guidance?" Do not run `stack add <piece...>`
+   without that confirmation.
+3. If confirmed, add the component, let Genesis apply its declared dependency
+   closure and synchronize any authoritative Agent Skill declared by that
+   component. Follow the preparation prompt returned by `stack add` in the same
+   task: make each materialized project contract true or replace a complete
+   section with evidenced reality. Then run `context .`, or the relevant source
+   path once source exists, load the applicable installed skill if present, and
+   follow that technology-owned guidance to prepare actual project
+   dependencies. Never infer an installation command from a component id.
+4. If declined, continue without adding the component or asking again. If no
+   catalog component matches, do not invent one; continue normally using
+   authoritative documentation owned by that technology.
+
 ## Establish context
 
 1. Read `genesis/blueprint.md` for non-technical product intent.
@@ -34,13 +71,13 @@ a workflow instruction.
    agent's own installed skill catalog.
 
 For an existing application's first Stack selection, inspect its real setup,
-build, and output commands before relying on component defaults. A selected
-component describes its current foundation; it does not silently port older
-source. When the existing commands differ, keep the implementation unchanged
-and declare exact project-owned consumer-operation overrides (for Vibe64,
-`## Workspace setup` and `## Outputs`). Genesis composes those sections as
+build, and output commands before accepting materialized component proposals.
+A selected component describes its current foundation; it does not silently
+port older source. When the existing commands differ, keep the implementation
+unchanged and replace the complete project-owned consumer operation (for
+Vibe64, `## Workspace setup` or `## Outputs`). Genesis treats those sections as
 opaque text; the named consumer alone owns their meaning and execution. Do not
-claim the inherited component recipe is usable until it matches the source.
+claim a proposed recipe is usable until it matches the source.
 
 Program is concise, fallible explanation. Its Sources and optional
 Implementation maps aid navigation but never substitute for reading code,
@@ -90,6 +127,8 @@ Neither is authority or proof; both may be regenerated with the Genesis
 After the selected technology's workspace substrate exists, use the Genesis
 `verify` operation for the Stack's declared final checks. An unconfigured result
 means the declared workspace or checks do not exist yet; it is not a failing
-check. Report files changed, checks actually run, and anything still requiring
-attention. Never claim that an unrun check passed or that passing checks prove
-the whole product.
+check. Before reporting completion, compare the requested observable behavior,
+required inputs and resources, declared project operations, and focused evidence
+with what actually exists. Report files changed, checks actually run,
+anything not proven, and anything still requiring attention. Never claim that
+an unrun check passed or that passing checks prove the whole product.

package/src/cli.js

@@ -29,6 +29,8 @@ import {
   projectFormatDiagnostic,
 } from './index/project-format.js';
 import { projectSessionContext } from './index/session-context.js';
+import { installedFirstPartyStackPackages } from './index/stack-catalog.js';
+import { readStack } from './index/stack.js';
 
 const USAGE = `Usage:
   genesis init
@@ -283,12 +285,27 @@ function writeResult(command, result) {
     }
   }
   if (result.guidance) line(process.stdout, result.guidance);
+  if (result.prompt) {
+    line(process.stdout, '');
+    process.stdout.write(result.prompt.endsWith('\n') ? result.prompt : `${result.prompt}\n`);
+  }
   line(process.stdout, `${command}: ${result.status}`);
 }
 
+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 } = {}) {
   const projectRoot = options.projectRoot || process.cwd();
-  const stackPackages = options.stackPackages || [];
+  const stackPackages = await cliStackPackages(projectRoot, options.stackPackages || []);
   if (command === 'init') return initialize({ projectRoot, stackPackages });
   if (command === 'migrate') return migrate({ projectRoot, stackPackages });
   if (command === 'adopt') {
@@ -362,7 +379,7 @@ async function execute({ command, operands, options }, { signal } = {}) {
     if (operands[0] === 'discover') {
       return { kind: 'discover', ...await codexAdoptionRecommendation({ projectRoot }) };
     }
-    return { kind: 'session', ...await projectSessionContext({ projectRoot }) };
+    return { kind: 'session', ...await projectSessionContext({ projectRoot, stackPackages }) };
   }
   if (command === 'verify') {
     return verify({

package/src/index/codex-hooks.js

@@ -8,6 +8,7 @@ import { runGit } from './process.js';
 import { normalizeRelative, pathState, writeFileAtomic } from './utils.js';
 
 const HOOKS_PATH = '.codex/hooks.json';
+const LEGACY_GENESIS_HOOKS_DESCRIPTION = 'Genesis project hooks.';
 const PROJECT_HOOK_ACTIONS = ['session', 'begin', 'stop', 'end'];
 
 function hookCommand(action) {
@@ -68,7 +69,7 @@ async function installedHooksSource(location) {
     return { source, value };
   } catch (error) {
     if (['ENOENT', 'ENOTDIR'].includes(error?.code)) {
-      return { source: null, value: { description: 'Genesis project hooks.', hooks: {} } };
+      return { source: null, value: { hooks: {} } };
     }
     throw new GenesisError('CODEX_HOOKS_INVALID', `${HOOKS_PATH} is not valid hook configuration: ${error.message}.`);
   }
@@ -78,6 +79,7 @@ export async function installCodexHooks({ projectRoot } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const location = path.join(root, HOOKS_PATH);
   const { source, value } = await installedHooksSource(location);
+  if (value.description === LEGACY_GENESIS_HOOKS_DESCRIPTION) delete value.description;
   value.hooks ||= {};
   removeGenesisProjectHooks(value.hooks);
   const groups = value.hooks[SESSION_HOOK.event] ||= [];

package/src/index/context.js

@@ -46,6 +46,25 @@ function stackGuidance(stack) {
   ];
 }
 
+function stackContracts(stack) {
+  if (stack.projectContracts.length === 0) return [];
+  return [
+    '',
+    '## Project Stack contracts',
+    '',
+    'These exact project-owned sections in `genesis/stack.md` are authoritative. Genesis executes only Verification; each other named consumer owns its section.',
+    '',
+    ...stack.projectContracts.flatMap(({ name, lines }) => [
+      `### \`## ${name}\``,
+      '',
+      '```markdown',
+      ...lines,
+      '```',
+      '',
+    ]),
+  ];
+}
+
 function pathMatchesTarget(filePath, target) {
   return !target || filePath === target || filePath.startsWith(`${target}/`);
 }
@@ -108,6 +127,7 @@ export async function contextForProjectPaths({ paths, projectRoot, stackPackages
     '',
     ...stackSummary(stack),
     ...stackGuidance(stack),
+    ...stackContracts(stack),
     '',
     '## Existing functions',
     '',

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/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/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'}.`,