genesis-compiler 1.8.6 → 1.9.1

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
@@ -1124,7 +1126,9 @@ publishing access to the selected package. In Vibe64, save it in the project's
 **Env → Development**, enable **Secret**, and choose **Add**. Managed shell
 commands receive the saved value; credentials do not belong in source or chat.
 
-Update the selected package's version and lockfile, run the relevant checks,
+Update the selected package's version and lockfile (for the compiler, also the
+packaged Codex plugin version in `plugins/genesis/.codex-plugin/plugin.json`,
+which must equal `package.json`), run the relevant checks,
 then commit and push the release source to `main`. Publish from a clean checkout
 whose `HEAD` matches `origin`'s actual `main`, with development dependencies
 installed through `npm ci`:

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,
@@ -270,6 +281,9 @@ 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.
 
@@ -279,10 +293,16 @@ 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. 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`.
+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

package/package.json

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

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/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.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';
@@ -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);
 }