genesis-compiler 1.2.27 → 1.2.29

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.27",
+  "version": "1.2.29",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with project agent guidance.",
   "repository": {
@@ -34,6 +34,9 @@
     "prompts/program.txt",
     "prompts/review.txt",
     "prompts/start.txt",
+    "prompts/start-existing.txt",
+    "prompts/start-existing-uninitialized.txt",
+    "prompts/start-new.txt",
     "prompts/work.txt",
     "plugins/genesis",
     "plugins/opencode",

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

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

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-existing-uninitialized.txt

@@ -0,0 +1,8 @@
+This is an existing project without Genesis project context. Do not ask
+new-project product-discovery questions. Ask what the person wants to understand
+or change and strongly recommend preparing the project for guided editing before
+substantial work. Explain in product language that preparation preserves the
+implementation while importing its current product, setup, run, data, preview,
+and verification facts. Do not require the person to know Genesis terminology or
+type a command. If they approve, run the Genesis `adopt` operation and follow its
+prompt. If they decline, continue normally and do not repeat the recommendation.

package/prompts/start-existing.txt

@@ -0,0 +1,23 @@
+The project already exists. Do not ask new-project product-discovery questions
+and do not offer an unselected technology catalog. Use the Blueprint as product
+intent, the selected Stack summary and full guidance as technical direction, and
+the compact Program status only as orientation. If USER REQUEST is actionable,
+proceed with it. Otherwise ask what the person wants to understand or change.
+
+After locating the relevant source, run the Genesis `context <relevant-path...>`
+operation before implementation to load the exact Program modules, project
+contracts, indexed functions, verification commands, and applicable skills.
+
+If the user requests an unselected technology, run the Genesis `stack list`
+operation first. For one exact match, ask whether to add it and prepare the
+project with its official guidance; only after confirmation run `stack add
+<piece...>` and follow its preparation prompt. If nothing matches, use the
+technology's authoritative documentation without inventing a component.
+
+When no Stack is selected, inspect the project's actual scripts, build and setup
+files, server entrypoint, and readiness behavior before recording a technology.
+Component proposals are not evidence, and selecting a component does not port an
+older implementation. Preserve evidenced project-owned contracts in their
+consumer's current schema. If the existing implementation is not usefully
+explained, recommend the Genesis description path instead of pretending its
+intent or operations are known.

package/prompts/start-new.txt

@@ -0,0 +1,27 @@
+The project is new. Before technology research or source creation, establish
+what is being built, who or what will use or invoke it, and the first observable
+useful outcome. Ask at most three concise questions at a time, and do not repeat
+facts already supplied by the user. A Stack choice is not product intent.
+
+Use `availableStackPieces` to offer only relevant technology choices in product
+language. Never silently select one. If the user names an unselected technology,
+run the Genesis `stack list` operation first. For one exact match, ask whether to
+add it and prepare the project with its official guidance. On confirmation, run
+the Genesis `stack add <piece...>` operation, follow its preparation prompt in
+this task, then run `context .` or `context <relevant-path>` and load any
+applicable installed skill. Never infer an install command from a component id.
+If the user declines, do not ask again; if nothing matches, use the technology's
+authoritative documentation without inventing a component.
+
+Establish the non-technical Blueprint before implementation. If product intent
+is clear while Stack is empty, present the relevant Stack choices in this same
+turn. The default `focused.v1` engineering profile suits ordinary work; use
+`availableEngineeringProfiles` only when the user requests another approach or
+the product has material long-lived compatibility, operational, security,
+reliability, or compliance constraints. Apply an explicit choice with the
+Genesis `engineering set <profile>` operation.
+
+This opening owns product direction and Stack selection, not final verification.
+Do not run the Genesis `verify` operation before implementation exists. Use
+`check` only when structural validation is useful. Once direction and Stack are
+clear, follow one smallest implementation path through the selected guidance.

package/prompts/start.txt

@@ -1,57 +1,5 @@
 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.
-
-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
-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
-Stack choices in that same turn and ask the user to select one explicitly.
-The default `focused.v1` engineering profile is already suitable for ordinary
-work, so do not force a separate profile question. When the user asks for a
-different engineering approach, or the product clearly has long-lived
-compatibility, operational, security, reliability, or compliance constraints,
-use `availableEngineeringProfiles` to explain only the relevant choices in
-product language. After an explicit choice, run the Genesis `engineering set
-<profile>` operation; do not invent or duplicate a built-in profile. Record
-additional explicit obligations in `genesis/engineering.md` under Project
-requirements.
-This opening turn owns product direction and Stack selection, not final
-verification. Do not run the Genesis `verify` operation before implementation
-exists. If structural validation is useful, run the Genesis `check` operation;
-consumer-owned operations remain governed by their own tools and must not be
-inferred here.
-
-When `projectKind` is `existing`, ask what the user wants to understand or
-change. Use the current Blueprint, Stack, Program, and code index when present.
-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.
-
-When `projectKind` is `existing-uninitialized`, ask what the user wants to
-understand or change and strongly recommend preparing the existing project for
-guided editing before substantial work. Explain in product language that this
-preserves the implementation while importing its current setup, run, database,
-preview, verification, and product context. Do not require the user to know
-Genesis terminology or type a command. If they approve, run the Genesis `adopt`
-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.
+This is the project-opening conversation. Follow only the project-kind
+instructions below. Treat USER REQUEST as the person's actual request, preserve
+what it already establishes, and ask only unresolved high-impact questions.

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/assets.js

@@ -3,6 +3,9 @@ import { readFile } from 'node:fs/promises';
 const root = new URL('../../', import.meta.url);
 const assets = {
   start: new URL('prompts/start.txt', root),
+  'start-new': new URL('prompts/start-new.txt', root),
+  'start-existing': new URL('prompts/start-existing.txt', root),
+  'start-existing-uninitialized': new URL('prompts/start-existing-uninitialized.txt', root),
   adopt: new URL('prompts/adopt.txt', root),
   work: new URL('prompts/work.txt', root),
   describe: new URL('prompts/describe.txt', root),

package/src/index/codex-hooks.js

@@ -3,11 +3,11 @@ import path from 'node:path';
 
 import { GenesisError } from './errors.js';
 import { gitContext } from './git.js';
-import { isProjectContentPath } from './paths.js';
-import { runGit } from './process.js';
-import { normalizeRelative, pathState, writeFileAtomic } from './utils.js';
+import { classifyProjectKind } from './project-files.js';
+import { 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 +68,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 +78,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] ||= [];
@@ -88,20 +89,15 @@ export async function installCodexHooks({ projectRoot } = {}) {
   return { status: 'updated', changedFiles: [HOOKS_PATH] };
 }
 
-function zeroPaths(buffer) {
-  return [...new Set(buffer.toString('utf8').split('\0').map(normalizeRelative).filter(Boolean))];
-}
-
 export async function codexAdoptionRecommendation({ projectRoot = process.cwd() } = {}) {
   let root;
   try { root = (await gitContext(projectRoot)).repositoryRoot; } catch { return { status: 'not-applicable', output: '' }; }
   if ((await pathState(path.join(root, 'genesis/blueprint.md'))).exists) {
     return { status: 'not-applicable', output: '' };
   }
-  const files = zeroPaths((await runGit(root, [
-    'ls-files', '-z', '--cached', '--others', '--exclude-standard',
-  ])).stdout).filter(isProjectContentPath);
-  if (files.length === 0) return { status: 'not-applicable', output: '' };
+  if (await classifyProjectKind({ projectRoot: root }) === 'new') {
+    return { status: 'not-applicable', output: '' };
+  }
   return {
     status: 'ready',
     output: [

package/src/index/context.js

@@ -31,16 +31,30 @@ function stackSummary(stack) {
 }
 
 function stackGuidance(stack) {
-  const pieces = stack.components.filter(({ guidance }) => guidance);
-  if (pieces.length === 0) return [];
+  if (!stack.guidance) return [];
   return [
     '',
     '## Selected Stack guidance',
     '',
-    ...pieces.flatMap(({ id, guidance }) => [
-      `### ${id}`,
+    stack.guidance,
+    '',
+  ];
+}
+
+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}\``,
       '',
-      guidance,
+      '```markdown',
+      ...lines,
+      '```',
       '',
     ]),
   ];
@@ -108,6 +122,7 @@ export async function contextForProjectPaths({ paths, projectRoot, stackPackages
     '',
     ...stackSummary(stack),
     ...stackGuidance(stack),
+    ...stackContracts(stack),
     '',
     '## Existing functions',
     '',