genesis-compiler 1.8.5 → 1.9.0

package/README.md

@@ -860,8 +860,10 @@ genesis check
 - Blueprint, engineering approach, and Stack validity;
 - selected Agent Skill presence and structural validity;
 - Program presence and structural validity;
-- environment declarations and consumer-owned Stack extensions as `ready`,
-  `blocked`, or honestly `unconfigured`;
+- environment declarations as `ready`, `missing-inputs`, or honestly
+  `unconfigured`, and consumer-owned Stack extensions as `ready` or
+  `unconfigured` (an undecided competing section makes the Stack invalid with
+  `STACK_SECTION_AMBIGUOUS` until the project authors it);
 - missing Stack-declared environment inputs (without claiming the service is
   reachable);
 - verification evidence as `current`, `stale`, `missing`, `invalid`, or
@@ -1005,6 +1007,13 @@ repository. It retains the same Stack validation and performs no writes or
 commands. Missing/invalid roots fail; this is never an automatic fallback from
 Git ownership or discovery errors.
 
+`inspectStackSections({ names, projectRoot, rootMode, stackPackages })` returns
+an array of those same section results in the requested order. Names must be
+distinct and the array must be nonempty. It discovers the root once and reads
+the Stack once, so related sections share one Stack identity. Each call reads
+current files; results are not cached across calls. Missing sections retain
+their ordinary `unconfigured` result and repository/directory rules are unchanged.
+
 Hosts that already validate access to a shared worktree may wrap an operation
 in `withTrustedGitRepository(absoluteWorktreeRoot, () => inspectEnvironment({
 projectRoot: absoluteWorktreeRoot }))`. This explicitly trusts that one

package/docs/prompt-integration.md

@@ -99,6 +99,10 @@ The executable returns exactly one JSON result:
   means the host already delivers through a native system field. This result
   is valid only for session scope.
 
+A validated complete host delivery is resolved before CLI project-format, Git
+root, or Stack inspection. Unclaimed conversations and host contributions retain
+the normal project diagnostics and composition. The resolver runs once per hook.
+
 Malformed results and configured-resolver failures fail the hook. An unavailable
 claimed owner must fail rather than returning `unclaimed`. Ownership belongs to
 the native conversation: these results do not change project hook files, so

package/docs/stack-components.md

@@ -157,9 +157,20 @@ validate a private schema, map runtimes, execute commands, or prove success.
 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.
+2. A component's proposal supersedes the proposals of selected components it
+   requires, directly or transitively. Laravel's proposal therefore replaces
+   the PHP and Node proposals for the same heading.
+3. Without a project section, exactly one remaining proposal is copied
+   unchanged.
+4. Several remaining proposals from unrelated components are a project
+   decision. `genesis stack add` still succeeds, materializes every other
+   section, leaves that heading unwritten, and returns a
+   `STACK_SECTION_AMBIGUOUS` diagnostic whose details list each competing
+   source and its exact lines. Its preparation prompt quotes the proposals and
+   asks the agent to author one complete project section first. Current-format
+   reads, `genesis check`, inspection and context reject the Stack with the
+   same message until that section exists. Genesis never merges the bodies or
+   guesses a winner.
 
 After selection every effective opaque section is project-owned. The component
 catalog may improve later without silently changing the application's setup,
@@ -184,6 +195,13 @@ discovery. Default library and CLI inspection continue to use the enclosing
 Git repository and its trust checks. Invalid modes or directory roots fail;
 there is no automatic fallback.
 
+When a consumer needs several related declarations, use
+`inspectStackSections({ names: ['First operation', 'Second operation'], projectRoot })`.
+It returns an array of the same `genesis.stack-section.v1` results in the requested
+order, using one repository discovery and one fresh Stack read. All results have
+the same Stack hash. The names array must be nonempty and contain no duplicates.
+The explicit directory mode is also supported; no cross-call cache is retained.
+
 ## Selection and identity
 
 `genesis stack add` records selected packages and component dependency closure,
@@ -263,5 +281,32 @@ 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.
+Competing proposals that no requirement resolves do not fail the migration:
+it completes, leaves that heading unwritten, and returns the same
+`STACK_SECTION_AMBIGUOUS` diagnostic and decision prompt as `genesis stack add`.
 Current-format reads reject a selected component whose required contract was
 not materialized, so a tool upgrade cannot quietly substitute a new proposal.
+
+`genesis migrate` does not materialize newly added catalog proposals when the
+project already uses the current format. Reconcile those explicitly with the
+existing `genesis stack add` operation for an already-selected component. For
+example, if `nodejs` is selected and the missing heading is
+`## Connected development`, run `genesis stack add nodejs` and review its
+preparation prompt. This adds the Node `npm` default without choosing connected
+repositories or installing dependencies. Every package-ecosystem language piece
+proposes its own default the same way (PHP `composer`, Python `pip`, Ruby
+`bundler`, Go `gomod`, Rust `cargo`, Java `maven`, Kotlin `gradle`, C#
+`nuget`); Laravel proposes `composer`, superseding the PHP and Node proposals it
+requires. C/C++ and shell propose none. When several unrelated languages are
+selected, the add reports the competing defaults and the project authors one
+`## Connected development` section choosing its default. Existing complete
+project sections remain authoritative; reconcile any proposed operation against
+the real source. Use the project's pinned compiler invocation when it declares
+`genesis-compiler`: `npm exec --no -- genesis stack add nodejs`.
+
+Before rolling out a catalog that adds operation proposals, operators should
+run read-only project inspection against representative existing projects with
+the candidate compiler and catalog. Arrange explicit reconciliation of affected
+projects before rollout. A format marker alone does not establish compatibility
+with new catalog proposals. Do not repair project contracts through opening,
+status reads or another lazy write path.

package/docs/templates.md

@@ -14,6 +14,9 @@ application has been described or that an application has been created.
 `genesis inspect project --json` is a read-only opening inspection shared by
 the CLI, session guidance, and hosts such as Vibe64:
 
+The diagnostics list reports each identical failure once, even when separate
+inspectors encounter it. Distinct failures remain available for repair.
+
 | State | Evidence | Next step |
 | --- | --- | --- |
 | `new` | No content beyond known bootstrap files | Choose a template or create through conversation |

package/package.json

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

package/src/cli.js

@@ -471,7 +471,7 @@ async function cliStackPackages(projectRoot, supplied) {
   return installedFirstPartyStackPackages({ projectRoot });
 }
 
-async function execute({ command, operands, options }, { signal } = {}) {
+async function execute({ command, operands, options }, { signal, hostContext = null } = {}) {
   if (command === 'parsers') {
     const parserOptions = {
       languages: operands.slice(1), all: options.all, directory: options.directory, signal,
@@ -576,23 +576,6 @@ async function execute({ command, operands, options }, { signal } = {}) {
       return { kind: 'discover', ...await codexAdoptionRecommendation({ projectRoot }) };
     }
     const scope = operands[0];
-    if (scope === 'turn' && process.env.GENESIS_TURN_CONTEXT_ENABLED === '0') {
-      return { kind: 'turn', status: 'ready', output: '' };
-    }
-    if (scope === 'session' && process.env[SESSION_CONTEXT_INSTALLED_ENV] === '1') {
-      return { kind: 'session', status: 'ready', output: '' };
-    }
-    const nativeSession = await hookSessionInput();
-    const hostContext = await resolveConfiguredHostContext({
-      projectRoot,
-      ...nativeSession,
-      scope,
-    });
-    // Ownership is resolved for this native conversation, not for the project.
-    // A host-owned delivery already contains everything its runtime requires.
-    if (hostContext?.kind === 'delivery') {
-      return { kind: 'session', status: 'ready', output: hostContext.text };
-    }
     if (scope === 'turn') {
       return hostContext === null
         ? { kind: 'turn', status: 'ready', output: '' }
@@ -669,7 +652,25 @@ export async function runCli(argv = process.argv.slice(2)) {
       return 0;
     }
     options = parsed.options;
-    const projectFormat = parsed.command === 'parsers' ? null : await optionalProjectFormat(options.projectRoot || process.cwd());
+    const projectRoot = options.projectRoot || process.cwd();
+    let hookResult = null;
+    let hostContext = null;
+    if (parsed.command === 'hook' && parsed.operands[0] !== 'discover') {
+      const scope = parsed.operands[0];
+      if ((scope === 'turn' && process.env.GENESIS_TURN_CONTEXT_ENABLED === '0') ||
+          (scope === 'session' && process.env[SESSION_CONTEXT_INSTALLED_ENV] === '1')) {
+        hookResult = { kind: scope, status: 'ready', output: '' };
+      } else {
+        const nativeSession = await hookSessionInput();
+        hostContext = await resolveConfiguredHostContext({ projectRoot, ...nativeSession, scope });
+        // A validated owner supplies the complete delivery; project composition is unused.
+        if (hostContext?.kind === 'delivery') {
+          hookResult = { kind: 'session', status: 'ready', output: hostContext.text };
+        }
+      }
+    }
+    const projectFormat = hookResult || parsed.command === 'parsers'
+      ? null : await optionalProjectFormat(projectRoot);
     const formatDiagnostic = projectFormatDiagnostic(projectFormat);
     if (formatDiagnostic && !options.json) {
       line(process.stderr, `WARNING: ${formatDiagnostic.message}`);
@@ -680,7 +681,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     process.once('SIGINT', abort);
     process.once('SIGTERM', abort);
     const result = withProjectFormatWarning(
-      await withParserCancellation(controller.signal, () => execute(parsed, { signal: controller.signal })),
+      hookResult ?? await withParserCancellation(controller.signal, () => execute(parsed, { signal: controller.signal, hostContext })),
       projectFormat,
       formatDiagnostic,
     );

package/src/index/check.js

@@ -124,12 +124,10 @@ export async function checkProject({
     projectRoot: root,
     stackPackages,
   });
-  const extensionDiagnostics = stack.extensions.flatMap(({ diagnostics }) => diagnostics);
   const diagnostics = [
     ...(program.diagnostic ? [program.diagnostic] : []),
     ...skills.diagnostics,
     ...missingResources,
-    ...extensionDiagnostics,
     ...(verification.status === 'invalid' ? [{
       code: 'VERIFICATION_EVIDENCE_INVALID',
       message: 'Saved verification evidence is malformed.',
@@ -145,7 +143,6 @@ export async function checkProject({
   if (missingResources.length > 0) {
     guidance.push(`${missingResources.map(({ message }) => message).join(' ')} Prompt generation remains available.`);
   }
-  if (extensionDiagnostics.length > 0) guidance.push('Resolve the competing consumer-owned Stack sections.');
   if (['missing', 'stale'].includes(verification.status)) guidance.push('Run genesis verify to refresh concrete evidence.');
   if (verification.status === 'unconfigured') guidance.push('Add project verification commands to genesis/stack.md.');
   guidance.push('Use genesis prompt --task review for a semantic, evidence-based comparison.');
@@ -154,7 +151,6 @@ export async function checkProject({
     || engineering.status === 'defaulted'
     || ['missing', 'outdated'].includes(skills.status)
     || missingResources.length > 0
-    || extensionDiagnostics.length > 0
     || ['missing', 'stale', 'unconfigured'].includes(verification.status);
 
   return {
@@ -169,9 +165,7 @@ export async function checkProject({
     skills: skills.status,
     program: program.status,
     environment: projectEnvironment.status,
-    extensions: extensionDiagnostics.length > 0
-      ? 'blocked'
-      : stack.extensions.length > 0 ? 'ready' : 'unconfigured',
+    extensions: stack.extensions.length > 0 ? 'ready' : 'unconfigured',
     resources: missingResources.length > 0 ? 'missing' : 'inputs-present',
     verification: verification.status,
     programFiles: program.files,

package/src/index/code-index.js

@@ -253,6 +253,7 @@ function formatCount(value, singular) {
 }
 
 export async function buildProjectIndex({
+  allowUnresolvedSections = false,
   projectRoot,
   queries = [],
   stackPackages = [],
@@ -264,7 +265,7 @@ export async function buildProjectIndex({
   const observationReader = typeof observations === 'function' ? observations : null;
   if (observationReader) observations = null;
   const root = (await gitContext(projectRoot)).repositoryRoot;
-  const stack = await readStack(root, { stackPackages });
+  const stack = await readStack(root, { allowUnresolvedSections, stackPackages });
   const packageRoots = stack.packageDiscovery.discoveries.flatMap(discovery => discovery.manifests.map(manifest => path.posix.join(path.posix.dirname(manifest), discovery.packageRoot)));
   const includePath = filePath => isProjectContentPath(filePath) && !packageRoots.some(directory => filePath === directory || filePath.startsWith(`${directory}/`));
   const states = await gitVisibleFileStates(root, { includePath });
@@ -322,7 +323,7 @@ export async function buildProjectIndex({
   // valid artifact after an inspector/parser read racing a source change.
   const finalStates = await gitVisibleFileStates(root, { includePath });
   const finalFiles = [...finalStates].filter(([filePath, state]) => state.exists && !state.symlink && !state.special && state.hash && !cityPathExcluded(filePath, stack.cityExclusions)).map(([filePath, state]) => ({ path: filePath, hash: state.hash, mode: state.mode }));
-  const finalStack = await readStack(root, { stackPackages });
+  const finalStack = await readStack(root, { allowUnresolvedSections, stackPackages });
   const finalMap = await inspectSubsystems({ projectRoot: root }).catch(() => null);
   if (stableJson(finalFiles) !== stableJson(files) || finalStack.identityHash !== stack.identityHash || (finalMap?.identity || null) !== (subsystemMap?.identity || null)) {
     throw new GenesisError('ARCHITECTURE_SOURCE_CHANGED', 'Source or Stack changed during architecture analysis. The previous index is retained; refresh after the changes settle.');

package/src/index/init.js

@@ -21,7 +21,7 @@ import {
   inspectProjectFormatAtRoot,
   requireCurrentProjectFormat,
 } from './project-format.js';
-import { EMPTY_STACK_SOURCE, readStack } from './stack.js';
+import { EMPTY_STACK_SOURCE, readStack, stackDecisionResult } from './stack.js';
 
 async function createIfMissing(projectRoot, relativePath, source) {
   const location = path.join(projectRoot, relativePath);
@@ -35,7 +35,11 @@ async function createIfMissing(projectRoot, relativePath, source) {
   }
 }
 
-export async function initializeProject({ projectRoot, stackPackages = [] } = {}) {
+export async function initializeProject({
+  allowUnresolvedSections = false,
+  projectRoot,
+  stackPackages = [],
+} = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const projectFormat = await inspectProjectFormatAtRoot(root);
   requireCurrentProjectFormat(projectFormat, { allowUninitialized: true });
@@ -47,7 +51,8 @@ export async function initializeProject({ projectRoot, stackPackages = [] } = {}
     createIfMissing(root, STACK_PATH, EMPTY_STACK_SOURCE),
   ])).filter(Boolean);
   await mkdir(path.join(root, PROGRAM_ROOT), { recursive: true });
-  const stack = await readStack(root, { stackPackages });
+  const stack = await readStack(root, { allowUnresolvedSections, stackPackages });
+  const decisions = stackDecisionResult(stack);
   const skills = await syncProjectSkills({ projectRoot: root, stack });
   const integrations = await syncAgentIntegrations({ projectRoot: root });
   const version = projectFormat.status === 'uninitialized'
@@ -67,7 +72,8 @@ export async function initializeProject({ projectRoot, stackPackages = [] } = {}
       ? 'Initialized Genesis, Agent Skills, and project guidance for Codex, Claude Code and OpenCode.'
       : 'Genesis, its Agent Skills, and project guidance for Codex, Claude Code and OpenCode are already initialized.',
     changedFiles,
-    diagnostics: skills.diagnostics,
+    diagnostics: [...decisions.diagnostics, ...skills.diagnostics],
+    ...(decisions.prompt ? { prompt: decisions.prompt } : {}),
     ...(integrations.warnings ? { warnings: integrations.warnings } : {}),
     guidance: [
       'Open Codex and use /hooks to review and trust the project guidance hook.',

package/src/index/migration.js

@@ -79,7 +79,13 @@ export async function migrateProject({ projectRoot, stackPackages = [] } = {}) {
     migratedFiles.push(PROJECT_VERSION_PATH);
   }
 
-  const initialized = await initializeProject({ projectRoot: root, stackPackages });
+  // Like selection, migration completes and reports competing Stack sections
+  // as project decisions; ordinary reads keep rejecting until they are authored.
+  const initialized = await initializeProject({
+    allowUnresolvedSections: true,
+    projectRoot: root,
+    stackPackages,
+  });
   const changedFiles = uniqueSorted([...migratedFiles, ...initialized.changedFiles]);
   const migrated = initial.status !== 'current';
   return {
@@ -92,5 +98,6 @@ export async function migrateProject({ projectRoot, stackPackages = [] } = {}) {
     projectFormat: await inspectProjectFormatAtRoot(root),
     changedFiles,
     diagnostics: initialized.diagnostics,
+    ...(initialized.prompt ? { prompt: initialized.prompt } : {}),
   };
 }

package/src/index/project-inspection.js

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 
 import { readBlueprint } from './blueprint.js';
 import { readCollaboration } from './collaboration.js';
@@ -125,6 +126,9 @@ export async function inspectProject({ projectRoot, stackPackages = [] } = {}) {
     try { await read(root); } catch (error) { result.diagnostics.push(asDiagnostic(error)); }
   }
   try { await inspectProgram(root); } catch (error) { result.diagnostics.push(asDiagnostic(error)); }
+  // Program resource validation can encounter the same Stack failure already reported above.
+  result.diagnostics = result.diagnostics.filter((diagnostic, index, diagnostics) =>
+    !diagnostics.slice(0, index).some((previous) => isDeepStrictEqual(previous, diagnostic)));
   if (result.diagnostics.length) return result;
   if (content.kind !== 'existing') {
     return { ...result, state: 'new', templateEligible: true, nextAction: 'create' };

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

@@ -112,10 +112,12 @@ function contractSections({ components, knownSectionNames, sections }) {
     components,
     opaqueStackSections(sections, knownSectionNames),
   );
+  const unresolvedSections = [];
   for (const extension of extensions) {
     const [diagnostic] = extension.diagnostics;
     if (diagnostic) {
-      throw new GenesisError(diagnostic.code, diagnostic.message, diagnostic.details);
+      unresolvedSections.push({ name: extension.name, diagnostic });
+      continue;
     }
     projectLines.set(extension.name, trimStackSectionLines(extension.lines));
     if (!sections.has(extension.name)) materializedSections.push(extension.name);
@@ -130,15 +132,36 @@ function contractSections({ components, knownSectionNames, sections }) {
     materializedSections,
     projectContracts: [...projectLines].map(([name, lines]) => ({ name, lines })),
     resourceLines: projectLines.get('Resources') ?? null,
+    unresolvedSections,
     verificationLines: projectLines.get('Verification') ?? null,
   };
 }
 
+function unresolvedSectionsError(unresolvedSections) {
+  if (unresolvedSections.length === 1) {
+    const [{ diagnostic }] = unresolvedSections;
+    return new GenesisError(diagnostic.code, diagnostic.message, diagnostic.details);
+  }
+  return new GenesisError(
+    'STACK_SECTION_AMBIGUOUS',
+    unresolvedSections.map(({ diagnostic }) => diagnostic.message).join('\n\n'),
+    { sections: unresolvedSections.map(({ diagnostic }) => diagnostic.details) },
+  );
+}
+
 export function materializeStackProjectContracts(options) {
   return contractSections(options);
 }
 
-export function requireMaterializedStackProjectContracts(options) {
+/**
+ * Require every selected proposal to be project-owned. A competing proposal
+ * is a project decision; only the add operation that reports it may continue
+ * without it.
+ */
+export function requireMaterializedStackProjectContracts({
+  allowUnresolvedSections = false,
+  ...options
+}) {
   const result = contractSections(options);
   if (result.materializedSections.length > 0) {
     const headings = result.materializedSections.map((name) => `\`## ${name}\``);
@@ -148,11 +171,15 @@ export function requireMaterializedStackProjectContracts(options) {
       { sections: result.materializedSections },
     );
   }
+  if (!allowUnresolvedSections && result.unresolvedSections.length > 0) {
+    throw unresolvedSectionsError(result.unresolvedSections);
+  }
   return result;
 }
 
-function contractBlocks(projectContracts) {
+function contractBlocks(projectContracts, hasDecisions) {
   if (projectContracts.length === 0) {
+    if (hasDecisions) return ['No other operation contract was proposed by these components.'];
     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.',
     ];
@@ -167,14 +194,43 @@ function contractBlocks(projectContracts) {
   ]);
 }
 
+function decisionBlocks(unresolvedSections) {
+  return unresolvedSections.flatMap(({ name, diagnostic }) => [
+    `### \`## ${name}\``,
+    '',
+    ...diagnostic.details.proposals.flatMap(({ source, lines }) => [
+      `Proposal from \`${source}\`:`,
+      '',
+      '~~~markdown',
+      ...lines,
+      '~~~',
+      '',
+    ]),
+  ]);
+}
+
 export function renderStackPreparationPrompt({
   components,
   materializedSections = [],
   newlySelected = [],
   projectContracts = [],
   reviewSections = [],
+  unresolvedSections = [],
 } = {}) {
-  if (newlySelected.length === 0 && materializedSections.length === 0) return '';
+  if (newlySelected.length === 0 && materializedSections.length === 0
+    && unresolvedSections.length === 0) return '';
+  const decisionHeadings = unresolvedSections.map(({ name }) => `\`## ${name}\``).join(', ');
+  const steps = [
+    ...(unresolvedSections.length > 0 ? [
+      `Decide ${decisionHeadings} first. Selected components propose competing bodies and none requires the other, so Genesis left ${unresolvedSections.length === 1 ? 'that heading' : 'those headings'} unwritten. Author one complete project-owned section per heading in \`genesis/stack.md\`, choosing between the proposals quoted under “Project decisions required” for this application. Until then current-format Genesis reads, including \`genesis check\` and \`genesis context\`, reject the Stack with \`STACK_SECTION_AMBIGUOUS\`.`,
+    ] : []),
+    'Read `genesis/blueprint.md`, `genesis/engineering.md`, and the complete `genesis/stack.md`, then run `genesis context .` (or the relevant source paths).',
+    'Load every applicable installed Agent Skill and follow the selected technology’s authoritative guidance before creating dependencies or source.',
+    '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.',
+    'Keep each consumer-owned section opaque to Genesis. Validate it with the consumer or framework that owns its grammar and behavior.',
+    'Establish or update the non-technical Blueprint and affected Program explanations as the product becomes concrete.',
+    '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.',
+  ];
   const selected = components.map(({ id }) => `\`${id}\``).join(', ');
   return [
     '# Prepare the selected Stack',
@@ -188,18 +244,23 @@ export function renderStackPreparationPrompt({
       '',
       `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.`,
     ] : []),
+    ...(unresolvedSections.length > 0 ? [
+      '',
+      `Unresolved project decisions: ${decisionHeadings}.`,
+    ] : []),
     '',
     '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.',
+    ...steps.map((step, index) => `${index + 1}. ${step}`),
+    ...(unresolvedSections.length > 0 ? [
+      '',
+      '## Project decisions required',
+      '',
+      ...trimStackSectionLines(decisionBlocks(unresolvedSections)),
+    ] : []),
     '',
     '## Project contracts to satisfy',
     '',
-    ...contractBlocks(projectContracts),
+    ...contractBlocks(projectContracts, unresolvedSections.length > 0),
   ].join('\n').trimEnd();
 }

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

@@ -10,11 +10,25 @@ import { sha256, stableJson } from './utils.js';
 /** Inspect one consumer-owned Stack section without interpreting its contents. */
 export async function inspectProjectStackSection({
   name,
+  ...options
+} = {}) {
+  return (await inspectProjectStackSections({ ...options, names: [name] }))[0];
+}
+
+/** Inspect several sections from one fresh Stack read, in the requested order. */
+export async function inspectProjectStackSections({
+  names,
   projectRoot,
   rootMode = 'repository',
   stackPackages = [],
 } = {}) {
-  const sectionName = normalizeStackSectionName(name);
+  if (!Array.isArray(names) || names.length === 0) {
+    throw new TypeError('Stack section inspection requires a nonempty names array.');
+  }
+  const sectionNames = names.map(normalizeStackSectionName);
+  if (new Set(sectionNames).size !== sectionNames.length) {
+    throw new TypeError('Stack section inspection requires distinct names.');
+  }
   let root;
   if (rootMode === 'repository') {
     root = (await gitContext(projectRoot)).repositoryRoot;
@@ -28,20 +42,22 @@ export async function inspectProjectStackSection({
     throw new TypeError('Stack section rootMode must be repository or directory.');
   }
   const stack = await readStack(root, { stackPackages });
-  const section = stack.extensions.find((candidate) => candidate.name === sectionName);
-  const diagnostics = [...(section?.diagnostics || [])];
-  const status = diagnostics.length > 0 ? 'blocked' : section ? 'ready' : 'unconfigured';
-  const lines = section ? [...section.lines] : [];
-  return {
-    contract: GENESIS_CONTRACTS.stackSection,
-    status,
-    stackHash: stack.identityHash,
-    sectionHash: status === 'ready' ? sha256(stableJson({ name: sectionName, lines })) : '',
-    components: stack.components.map(({ id }) => id),
-    name: sectionName,
-    source: section?.source || null,
-    content: lines.join('\n'),
-    lines,
-    diagnostics,
-  };
+  return sectionNames.map((sectionName) => {
+    const section = stack.extensions.find((candidate) => candidate.name === sectionName);
+    const diagnostics = [...(section?.diagnostics || [])];
+    const status = diagnostics.length > 0 ? 'blocked' : section ? 'ready' : 'unconfigured';
+    const lines = section ? [...section.lines] : [];
+    return {
+      contract: GENESIS_CONTRACTS.stackSection,
+      status,
+      stackHash: stack.identityHash,
+      sectionHash: status === 'ready' ? sha256(stableJson({ name: sectionName, lines })) : '',
+      components: stack.components.map(({ id }) => id),
+      name: sectionName,
+      source: section?.source || null,
+      content: lines.join('\n'),
+      lines,
+      diagnostics,
+    };
+  });
 }

package/src/index/stack-section.js

@@ -29,19 +29,55 @@ export function opaqueStackSections(sections, knownNames) {
     }));
 }
 
+function requirementClosures(components) {
+  const byId = new Map(components.map((component) => [component.id, component]));
+  const closures = new Map();
+  const closure = (id) => {
+    if (closures.has(id)) return closures.get(id);
+    const required = new Set();
+    closures.set(id, required);
+    for (const dependency of byId.get(id)?.requires || []) {
+      if (!byId.has(dependency) || dependency === id) continue;
+      required.add(dependency);
+      for (const transitive of closure(dependency)) required.add(transitive);
+    }
+    return required;
+  };
+  for (const { id } of components) closure(id);
+  return closures;
+}
+
+function quotedProposal({ source, lines }) {
+  return [`- \`${source}\` proposes:`, '', '  ~~~markdown', ...lines.map((line) => (line ? `  ${line}` : '')), '  ~~~'];
+}
+
+/** Render the actionable decision message for one unresolved section. */
+export function unresolvedStackSectionMessage(name, proposals) {
+  return [
+    `Selected Stack components propose competing \`## ${name}\` sections and none supersedes the others: ${proposals.map(({ source }) => source).join(', ')}.`,
+    `Author one complete project \`## ${name}\` section in genesis/stack.md that chooses between these proposals; Genesis never merges them or picks one.`,
+    '',
+    ...proposals.flatMap(quotedProposal),
+  ].join('\n');
+}
+
 /**
  * Compose consumer-owned Stack sections without interpreting their contents.
- * An existing project declaration wins; otherwise exactly one selected
- * component may propose a section for materialization under a given name.
+ * An existing project declaration wins. Otherwise a component's proposal
+ * supersedes the proposals of selected components it transitively requires;
+ * exactly one remaining proposal is materialized, and several remaining
+ * proposals are an unresolved project decision.
  */
 export function composeStackSections(components = [], projectSections = []) {
   const projectByName = new Map(projectSections.map((section) => [section.name, section]));
+  const closures = requirementClosures(components);
   const componentByName = new Map();
   for (const component of components) {
     for (const section of component.extensions || []) {
       const declarations = componentByName.get(section.name) || [];
       declarations.push({
         ...section,
+        component: component.id,
         source: `component:${component.id}`,
       });
       componentByName.set(section.name, declarations);
@@ -59,23 +95,29 @@ export function composeStackSections(components = [], projectSections = []) {
       };
     }
     const declarations = componentByName.get(name) || [];
-    if (declarations.length === 1) {
+    const remaining = declarations.filter(({ component }) => !declarations.some((other) => (
+      other.component !== component && closures.get(other.component)?.has(component)
+    )));
+    if (remaining.length === 1) {
       return {
         name,
-        lines: [...declarations[0].lines],
-        source: declarations[0].source,
+        lines: [...remaining[0].lines],
+        source: remaining[0].source,
         diagnostics: [],
       };
     }
-    const sources = declarations.map(({ source }) => source).sort();
+    const proposals = remaining
+      .map(({ source, lines }) => ({ source, lines: trimStackSectionLines(lines) }))
+      .sort((left, right) => left.source.localeCompare(right.source));
+    const sources = proposals.map(({ source }) => source);
     return {
       name,
       lines: [],
       source: null,
       diagnostics: [{
         code: 'STACK_SECTION_AMBIGUOUS',
-        message: `Selected Stack components provide competing \`${name}\` sections: ${sources.join(', ')}. Add one project \`## ${name}\` section to select the exact declaration.`,
-        details: { name, sources },
+        message: unresolvedStackSectionMessage(name, proposals),
+        details: { name, sources, proposals },
       }],
     };
   });

package/src/index/stack.js

@@ -230,7 +230,11 @@ export async function addStackPieces({ pieces, projectRoot, stackPackages = [] }
   });
   const stackChanged = rendered !== source;
   if (stackChanged) await writeFileAtomic(location, rendered);
-  const stack = await readStack(projectRoot, { stackPackages: availablePackages });
+  const stack = await readStack(projectRoot, {
+    allowUnresolvedSections: true,
+    stackPackages: availablePackages,
+  });
+  const { unresolvedSections } = stack;
   const skills = await syncProjectSkills({
     projectRoot,
     stack,
@@ -246,7 +250,10 @@ export async function addStackPieces({ pieces, projectRoot, stackPackages = [] }
       : 'Every requested Stack component and Agent Skill is already selected.',
     components: selected,
     changedFiles,
-    diagnostics: skills.diagnostics,
+    diagnostics: [
+      ...unresolvedSections.map(({ diagnostic }) => diagnostic),
+      ...skills.diagnostics,
+    ],
     prompt: renderStackPreparationPrompt({
       components: stack.components,
       materializedSections: projectContracts.materializedSections,
@@ -254,6 +261,7 @@ export async function addStackPieces({ pieces, projectRoot, stackPackages = [] }
       projectContracts: stack.projectContracts,
       reviewSections: [...new Set(newlySelectedPieces.flatMap(stackPieceContractNames))]
         .filter((name) => sections.has(name)),
+      unresolvedSections,
     }),
   };
 }
@@ -295,6 +303,7 @@ async function customizePiece(projectRoot, piece) {
 
 async function readStackWithContractMode(projectRoot, {
   allowComponentContracts,
+  allowUnresolvedSections = false,
   stackPackages = [],
 }) {
   const location = path.join(projectRoot, STACK_PATH);
@@ -324,6 +333,7 @@ async function readStackWithContractMode(projectRoot, {
   const projectContracts = (allowComponentContracts
     ? materializeStackProjectContracts
     : requireMaterializedStackProjectContracts)({
+    allowUnresolvedSections,
     components,
     knownSectionNames: STACK_SECTIONS,
     sections,
@@ -386,6 +396,7 @@ async function readStackWithContractMode(projectRoot, {
     environmentFiles,
     extensions,
     projectContracts: projectContracts.projectContracts,
+    ...(allowUnresolvedSections ? { unresolvedSections: projectContracts.unresolvedSections } : {}),
     resources,
     guidance: composedProse(components, 'guidance'),
     adoption: composedProse(components, 'adoption'),
@@ -394,13 +405,32 @@ async function readStackWithContractMode(projectRoot, {
   };
 }
 
-export function readStack(projectRoot, { stackPackages = [] } = {}) {
+/**
+ * Read the current-format Stack. Only operations that report pending project
+ * decisions themselves (selection and migration) may allow unresolved
+ * competing sections; the returned Stack then lists them.
+ */
+export function readStack(projectRoot, { allowUnresolvedSections = false, stackPackages = [] } = {}) {
   return readStackWithContractMode(projectRoot, {
     allowComponentContracts: false,
+    allowUnresolvedSections,
     stackPackages,
   });
 }
 
+/** Diagnostics and the preparation prompt for a Stack read with unresolved sections allowed. */
+export function stackDecisionResult(stack) {
+  const unresolvedSections = stack.unresolvedSections || [];
+  return {
+    diagnostics: unresolvedSections.map(({ diagnostic }) => diagnostic),
+    prompt: renderStackPreparationPrompt({
+      components: stack.components,
+      projectContracts: stack.projectContracts,
+      unresolvedSections,
+    }),
+  };
+}
+
 export function readLegacyStack(projectRoot, { stackPackages = [] } = {}) {
   return readStackWithContractMode(projectRoot, {
     allowComponentContracts: true,

package/src/index.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 
 import { checkProject } from './index/check.js';
 import { inspectProjectSkills, syncProjectSkills } from './index/agent-skills.js';
@@ -21,7 +22,7 @@ import { initializeProject } from './index/init.js';
 import { migrateProject } from './index/migration.js';
 import { installCodexPlugin } from './index/codex-plugin.js';
 import { inspectProjectEnvironment } from './index/environment-files.js';
-import { inspectProjectStackSection } from './index/stack-section-inspection.js';
+import { inspectProjectStackSection, inspectProjectStackSections } from './index/stack-section-inspection.js';
 import { listStackCatalogPieces } from './index/stack-catalog.js';
 import { addStackPieces, readStack } from './index/stack.js';
 import { uniqueSorted } from './index/utils.js';
@@ -84,14 +85,16 @@ export async function initialize({ projectRoot = process.cwd(), stackPackages =
 
 export async function migrate({ projectRoot = process.cwd(), stackPackages = [] } = {}) {
   const migrated = await migrateProject({ projectRoot, stackPackages });
-  const index = await buildProjectIndex({ projectRoot, stackPackages });
+  const index = await buildProjectIndex({ allowUnresolvedSections: true, projectRoot, stackPackages });
   const result = withIndexResult(migrated, index);
   const checked = await checkProject({ projectRoot, stackPackages });
   return {
     ...result,
     projectFormat: checked.projectFormat,
     check: checked,
-    diagnostics: [...result.diagnostics, ...checked.diagnostics],
+    diagnostics: [...result.diagnostics, ...checked.diagnostics].filter((diagnostic, index, all) => (
+      !all.slice(0, index).some((previous) => isDeepStrictEqual(previous, diagnostic))
+    )),
     guidance: checked.guidance,
   };
 }
@@ -127,7 +130,11 @@ export function installCodex({ environment = process.env } = {}) {
 export async function addStack({ pieces, projectRoot = process.cwd(), stackPackages = [] } = {}) {
   const root = path.resolve(projectRoot);
   const selected = await addStackPieces({ pieces, projectRoot: root, stackPackages });
-  const index = await buildProjectIndex({ projectRoot: root, stackPackages });
+  const index = await buildProjectIndex({
+    allowUnresolvedSections: true,
+    projectRoot: root,
+    stackPackages,
+  });
   return withIndexResult(selected, index);
 }
 
@@ -161,6 +168,10 @@ export function inspectStackSection(options) {
   return inspectProjectStackSection(options);
 }
 
+export function inspectStackSections(options) {
+  return inspectProjectStackSections(options);
+}
+
 export function listEngineeringProfiles() {
   return listEngineeringProfileCatalog();
 }