genesis-compiler 1.2.5 → 1.2.7

package/README.md

@@ -51,6 +51,18 @@ completely or correctly explains the implementation.
 
 Genesis requires Node.js 22 or newer and Git.
 
+Install the framework-neutral compiler and the optional first-party technology
+catalog as separate packages:
+
+```bash
+npm install --global genesis-compiler genesis-stack
+```
+
+`genesis-compiler` has no dependency on `genesis-stack` or on any framework.
+The catalog is static Markdown and contains the complete curated set of
+language, database, UI, and framework pieces. A host may supply another catalog
+through the same contract.
+
 For an existing codebase, `adopt` is the direct entry point:
 
 ```bash
@@ -102,7 +114,8 @@ that, use Codex normally. No technology is assumed until you explicitly select
 Stack components:
 
 ```bash
-genesis stack add nodejs         # or jskit jskit-mysql / jskit-postgresql
+genesis stack add --stack-package genesis-stack nodejs
+# or: genesis stack add --stack-package genesis-stack jskit jskit-mysql
 ```
 
 Genesis does not install substitute generic `nodejs`, `vue`, `php`, or similar
@@ -110,8 +123,9 @@ skills. Official, user, or host skills retain their normal names. A Stack piece
 may instead name one authoritative technology skill; Genesis copies that
 complete directory into `.agents/skills/`, including its `references/`,
 `scripts/`, `assets/`, and agent metadata. The agent loads those resources only
-when the skill requires them. For example, the JSKIT piece installs the JSKIT
-package's own `jskit` skill. A piece's optional `## Guidance` is concise
+when the skill requires them. For example, the `genesis-stack` catalog's JSKIT
+piece installs the JSKIT package's own `jskit` skill. A piece's optional
+`## Guidance` is concise
 supplemental project-work guidance; it does not create or replace a generic
 technology skill.
 
@@ -130,8 +144,8 @@ execute the same normalized recipe themselves. A concrete Stack piece may declar
 ordered `## Workspace setup` recipe with labels, argument arrays expressed as
 backticked tokens, abstract runtimes, and optional project-relative working
 directories and readiness paths. A recipe whose declared project marker does
-not exist remains unconfigured until a later inspection. The built-in `jskit`
-piece waits for `package.json` and then declares `npm install`; generic
+not exist remains unconfigured until a later inspection. The catalog's
+`jskit` piece waits for `package.json` and then declares `npm install`; generic
 `nodejs` and `php` deliberately declare no installer. One project section in
 `genesis/stack.md` replaces all component defaults, including with
 `- Nothing.`. Without that override, exactly one component recipe is used;
@@ -143,7 +157,7 @@ resources such as database variables do not gate dependency installation.
 Hosts that manage project environments can call `inspectEnvironment()`.
 Concrete Stack integrations may declare public, non-secret Environment
 defaults such as the database driver selected by that integration. Explicit
-host or user values take precedence. The built-in JSKIT MySQL and PostgreSQL
+host or user values take precedence. The catalog's JSKIT MySQL and PostgreSQL
 pieces respectively declare `DB_CLIENT=mysql2` and `DB_CLIENT=pg`, so users
 provide connection values rather than restating a deterministic technology
 choice.
@@ -164,7 +178,8 @@ optional readable `## Launch` section in `genesis/stack.md` declares labeled
 targets, exact backticked argument tokens, relative working directories,
 abstract runtime requirements, `{host}`/`{port}` substitutions, and an optional
 application-owned Preview identity block. Concrete components may provide a
-default: `jskit` declares its app-owned `npm run develop` command; generic
+default: the catalog's `jskit` piece declares its app-owned `npm run develop`
+command; generic
 `nodejs` and `php` do not guess. Genesis starts nothing itself. It returns preview identity
 command metadata and environment variable names, never their values. The host
 continues to own pinned runtimes, ports, processes, readiness probing and
@@ -177,7 +192,7 @@ Hosts that publish applications can call the separate public
 `inspectDeployment()` API. An optional readable `## Deployment` section
 declares an ordered production recipe: project-relative workdir, abstract
 runtimes, exact Prepare/Build/Migrate/Serve argv, and one HTTP readiness
-predicate. A concrete component may provide the recipe; the built-in `jskit`
+predicate. A concrete component may provide the recipe; the catalog's `jskit`
 piece declares production dependency installation, build, database preparation,
 `npm start`, and `/api/health`. Generic language pieces do not guess. A project
 section replaces component defaults wholesale, and `- Nothing.` explicitly
@@ -201,8 +216,9 @@ genesis inspect deployment --json
 ```
 
 Without `--json`, the commands print concise human-readable summaries. They
-never execute setup, start a process, probe a server, materialize environment
-files, or deploy.
+never start the application, probe a server, materialize environment files, or
+deploy. `genesis prepare` is the separate explicit command that executes only
+the finite Workspace setup recipe.
 
 At session start, Codex receives only a short explanation of how Genesis is
 organized. After it locates the source involved in a request, it can load the
@@ -354,17 +370,19 @@ object.
 
 ## Stack
 
-List and select the built-in Stack components:
+List and select pieces from the installed optional catalog:
 
 ```bash
-genesis stack list
-genesis stack add jskit jskit-mysql      # or jskit-postgresql
+genesis stack list --stack-package genesis-stack
+genesis stack add --stack-package genesis-stack jskit jskit-mysql
 ```
 
-`genesis/stack.md` records component ids and optional project verification
-commands. Selecting no components is valid. Built-in components include the
-eleven common language families listed above, plus Vue, MySQL, PostgreSQL,
-JSKIT, and JSKIT database integrations. Components may contribute:
+`genesis/stack.md` records the owning Stack package, component ids, and optional
+project verification commands. After the first selection, ordinary commands
+resolve the recorded package without another flag. Selecting no components is
+valid. `genesis-stack` contains the eleven common language families listed
+above, plus Vue, MySQL, PostgreSQL, JSKIT, and JSKIT database integrations.
+Components may contribute:
 
 - a concise description and supplemental Guidance used across relevant tasks;
 - existing-project Adoption requirements used only while importing a codebase;
@@ -380,8 +398,8 @@ cleanup tasks; `Adoption` adds import-only requirements; `Deslop` adds
 cleanup-only rules. None shadows an official generic technology skill or
 assumes that an upstream skill contains every rule Genesis needs.
 
-Genesis core contains no database, framework, language, or platform-specific
-controller behavior. See [Stack components](docs/stack-components.md).
+Genesis core contains no Stack pieces and no database, framework, language, or
+platform dependency. See [Stack components](docs/stack-components.md).
 
 ## Verification
 
@@ -428,6 +446,8 @@ genesis check
 - Blueprint and Stack validity;
 - selected Agent Skill presence and structural validity;
 - Program presence and structural validity;
+- Workspace setup, environment, Launch, and Deployment as `ready`, `blocked`,
+  or honestly `unconfigured`;
 - missing Stack-declared environment inputs (without claiming the service is
   reachable);
 - verification evidence as `current`, `stale`, `missing`, `invalid`, or
@@ -484,6 +504,12 @@ identity, secret, and browser policy.
 `inspectDeployment()` returns the separate normalized production recipe without
 executing or provisioning it.
 
+Normalized operational results identify their stable public contract in the
+`contract` field: `genesis.workspace-setup.v1`, `genesis.environment.v1`,
+`genesis.launch.v1`, `genesis.deployment.v1`, or
+`genesis.verification.v1`. Hosts validate that identity instead of
+feature-detecting individual fields.
+
 A host such as Vibe64 can send the generated prompt to its existing agent:
 
 ```js

package/docs/prompt-integration.md

@@ -35,7 +35,7 @@ Genesis keeps each instruction at one useful level:
   project's `.agents/skills/` directory.
 - `prompts/<task>.txt` is a task launcher. It selects the relevant
   workflow skill and states only that turn's edit boundary.
-- `stacks/pieces/<component>.md` supplies concise Description, supplemental
+- a declared Stack package's `stacks/pieces/<component>.md` supplies concise Description, supplemental
   Guidance, Adoption requirements, Resources, Deslop overlays, structural Indexers, verification
   Commands, and an optional authoritative Agent Skill source.
 - `genesis/blueprint.md`, `genesis/program/`, and `genesis/stack.md` are the

package/docs/stack-components.md

@@ -1,8 +1,23 @@
 # Stack components
 
 Genesis core knows no framework, language, database, package manager, or
-environment-variable name. A built-in component is one Markdown file at
-`stacks/pieces/<id>.md`.
+environment-variable name, and it ships no technology pieces. A Stack package
+is an ordinary npm package with one static manifest pointer:
+
+```json
+{
+  "name": "example-stack",
+  "genesis": { "stackPieces": "stacks/pieces" }
+}
+```
+
+Each piece is one Markdown file in that declared directory. Genesis reads the
+manifest and Markdown only; it never imports or executes package code. Catalog
+names are explicit, collisions fail, and the selected package is recorded in
+the project's `## Stack packages` section. The first-party optional
+`genesis-stack` package contains the complete curated catalog; Genesis core does
+not depend on it. A framework contributes to that catalog rather than requiring
+a compiler release or a separate catalog package.
 
 ````markdown
 # Stack piece: example
@@ -169,7 +184,7 @@ environment name and value. Selected
 component defaults compose by name; identical declarations collapse and
 different values fail rather than silently choosing one. Defaults participate
 in Stack identity, resource preflight, prompt context, Launch inspection, and
-verification execution. The JSKIT database integrations use this contract for
+verification execution. The `genesis-stack` JSKIT database integrations use this contract for
 their deterministic `DB_CLIENT` driver ids; generic database pieces do not.
 Secrets and deployment-specific connection values remain host inputs and must
 never be declared as defaults.
@@ -288,7 +303,7 @@ district to a region and a campus while generating
 must not reclassify or filter paths. Under a matched prefix, the first directory
 is a campus, while files directly below the prefix belong to the prefix campus.
 Under the fallback, each top-level directory is a campus and project-root files
-belong to the project-root campus. The built-in JSKIT piece excludes exact
+belong to the project-root campus. The `genesis-stack` JSKIT piece excludes exact
 `test`, `tests`, and `__tests__` path segments plus `*.test.*` and `*.spec.*`
 files, then declares `Packages`, `Source`, and `Everything else`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with optional Codex hooks.",
   "repository": {
@@ -39,8 +39,7 @@
     "prompts/work.txt",
     "plugins/genesis",
     "skills",
-    "src",
-    "stacks/pieces"
+    "src"
   ],
   "scripts": {
     "test": "node --test test/*.test.js"
@@ -58,7 +57,6 @@
     "@ast-grep/lang-ruby": "^0.0.7",
     "@ast-grep/lang-rust": "^0.0.7",
     "@ast-grep/napi": "^0.45.1",
-    "@jskit-ai/agent-docs": "0.1.134",
     "yaml": "^2.9.0"
   }
 }

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

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

package/prompts/adopt.txt

@@ -50,6 +50,12 @@ 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.
 
+The resulting project contract may therefore own complete `## Resources`,
+`## Environment defaults`, `## Environment files`, `## Workspace setup`,
+`## Commands`, `## Launch`, and `## Deployment` sections. Treat these as one
+operational inventory: do not preserve setup while silently dropping its
+resource, launch, readiness, identity, verification, or deployment counterpart.
+
 Create the non-technical Blueprint and useful subsystem-oriented Program from
 current source and tests. Do not cite archive internals or Git object storage as
 implementation source; Program sources must be current Git-visible files.

package/src/cli.js

@@ -44,6 +44,7 @@ const USAGE = `Usage:
 
 Options:
   --project-root <path>  Set the project root (default: current directory)
+  --stack-package <name> Add an installed external Stack package (repeatable)
   --task <task>          Select the prompt task (default: work)
   --json                 Emit one machine-readable result
   -h, --help             Show this help
@@ -70,6 +71,7 @@ function parseCommand(argv) {
       options: {
         json: { type: 'boolean', default: false },
         'project-root': { type: 'string' },
+        'stack-package': { type: 'string', multiple: true, default: [] },
         task: { type: 'string' },
       },
     });
@@ -79,6 +81,7 @@ function parseCommand(argv) {
   const options = {
     json: parsed.values.json,
     projectRoot: parsed.values['project-root'],
+    stackPackages: parsed.values['stack-package'],
     task: parsed.values.task,
   };
   const operands = parsed.positionals;
@@ -131,6 +134,10 @@ function writeCheck(result) {
   line(process.stdout, `Stack: ${result.stack}`);
   line(process.stdout, `Agent Skills: ${result.skills}`);
   line(process.stdout, `Program: ${result.program}`);
+  line(process.stdout, `Workspace setup: ${result.workspaceSetup}`);
+  line(process.stdout, `Environment: ${result.environment}`);
+  line(process.stdout, `Launch: ${result.launch}`);
+  line(process.stdout, `Deployment: ${result.deployment}`);
   line(process.stdout, `Resource inputs: ${result.resources}`);
   line(process.stdout, `Verification: ${result.verification}`);
   namedItems('Program files', result.programFiles);
@@ -262,26 +269,30 @@ async function hookInput() {
   }
 }
 
-async function execute({ command, operands, options }) {
+async function execute({ command, operands, options }, { signal } = {}) {
   const projectRoot = options.projectRoot || process.cwd();
-  if (command === 'init') return initialize({ projectRoot });
+  const stackPackages = options.stackPackages || [];
+  if (command === 'init') return initialize({ projectRoot, stackPackages });
   if (command === 'adopt') {
-    return adoptProject({ projectRoot, request: operands.join(' ') });
+    return adoptProject({ projectRoot, request: operands.join(' '), stackPackages });
   }
   if (command === 'codex') return installCodex();
   if (command === 'stack') {
-    if (operands[0] === 'list') return { status: 'ok', pieces: await listStackPieces() };
-    return addStack({ pieces: operands.slice(1), projectRoot });
+    if (operands[0] === 'list') {
+      return { status: 'ok', pieces: await listStackPieces({ projectRoot, stackPackages }) };
+    }
+    return addStack({ pieces: operands.slice(1), projectRoot, stackPackages });
   }
   if (command === 'prompt') {
     return generatePrompt({
       projectRoot,
       task: options.task || 'work',
       request: operands.join(' '),
+      stackPackages,
     });
   }
-  if (command === 'context') return getContext({ paths: operands, projectRoot });
-  if (command === 'index') return indexCodebase({ projectRoot, queries: operands });
+  if (command === 'context') return getContext({ paths: operands, projectRoot, stackPackages });
+  if (command === 'index') return indexCodebase({ projectRoot, queries: operands, stackPackages });
   if (command === 'inspect') {
     const inspections = {
       workspace: inspectWorkspaceSetup,
@@ -289,11 +300,16 @@ async function execute({ command, operands, options }) {
       launch: inspectLaunch,
       deployment: inspectDeployment,
     };
-    return { inspection: operands[0], ...await inspections[operands[0]]({ projectRoot }) };
+    return {
+      inspection: operands[0],
+      ...await inspections[operands[0]]({ projectRoot, stackPackages }),
+    };
   }
   if (command === 'prepare') {
     return prepareWorkspace({
       projectRoot,
+      signal,
+      stackPackages,
       onEvent: (event) => {
         if (!options.json) line(process.stderr, event.message);
       },
@@ -318,17 +334,21 @@ async function execute({ command, operands, options }) {
   if (command === 'verify') {
     return verify({
       projectRoot,
+      signal,
+      stackPackages,
       onEvent: (event) => {
         if (!options.json) line(process.stderr, event.message);
       },
     });
   }
-  if (command === 'check') return check({ projectRoot });
+  if (command === 'check') return check({ projectRoot, stackPackages });
   fail('CLI_UNKNOWN_COMMAND', `Unknown command: ${command}`);
 }
 
 export async function runCli(argv = process.argv.slice(2)) {
   let options = {};
+  const controller = new AbortController();
+  const abort = () => controller.abort();
   try {
     const parsed = parseCommand(argv);
     if (parsed.command === 'help') {
@@ -336,7 +356,12 @@ export async function runCli(argv = process.argv.slice(2)) {
       return 0;
     }
     options = parsed.options;
-    const result = await execute(parsed);
+    const finiteCommand = ['prepare', 'verify'].includes(parsed.command);
+    if (finiteCommand) {
+      process.once('SIGINT', abort);
+      process.once('SIGTERM', abort);
+    }
+    const result = await execute(parsed, { signal: controller.signal });
     if (options.json) line(process.stdout, JSON.stringify(result));
     else writeResult(parsed.command, result);
     return ['blocked', 'failed', 'invalid'].includes(result?.status) ? 2 : 0;
@@ -345,5 +370,8 @@ export async function runCli(argv = process.argv.slice(2)) {
     if (options.json) line(process.stderr, JSON.stringify(diagnostic));
     else line(process.stderr, `${diagnostic.code}: ${diagnostic.message}`);
     return 1;
+  } finally {
+    process.removeListener('SIGINT', abort);
+    process.removeListener('SIGTERM', abort);
   }
 }

package/src/index/agent-skills.js

@@ -156,8 +156,14 @@ async function describeSkill(directory, source) {
   };
 }
 
-async function packageDirectory(packageName) {
-  for (const modulesRoot of require.resolve.paths(packageName) || []) {
+async function packageDirectory(packageName, resolveFrom = null) {
+  const roots = [
+    ...(resolveFrom
+      ? createRequire(path.join(resolveFrom, 'package.json')).resolve.paths(packageName) || []
+      : []),
+    ...(require.resolve.paths(packageName) || []),
+  ];
+  for (const modulesRoot of [...new Set(roots)]) {
     const manifest = path.join(modulesRoot, packageName, 'package.json');
     try {
       const value = JSON.parse(await readFile(manifest, 'utf8'));
@@ -180,7 +186,9 @@ async function packageDirectory(packageName) {
 }
 
 async function resolveLocator(locator) {
-  const root = locator.package ? await packageDirectory(locator.package) : packageRoot;
+  const root = locator.package
+    ? await packageDirectory(locator.package, locator.resolveFrom)
+    : packageRoot;
   const directory = path.join(root, locator.path);
   const source = locator.source || (
     locator.package

package/src/index/check.js

@@ -7,6 +7,10 @@ import { inspectProgram } from './program.js';
 import { inspectVerification } from './project-state.js';
 import { missingStackResources } from './stack-preflight.js';
 import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
+import { inspectProjectEnvironment } from './environment-files.js';
+import { inspectProjectLaunch } from './launch.js';
+import { inspectProjectDeployment } from './deployment.js';
+import { inspectWorkspaceSetupForStack } from './workspace-setup.js';
 
 function invalidResult(area, error) {
   return {
@@ -15,6 +19,10 @@ function invalidResult(area, error) {
     stack: area === 'stack' ? 'invalid' : 'unknown',
     skills: area === 'skills' ? 'invalid' : 'unknown',
     program: 'unknown',
+    workspaceSetup: 'unknown',
+    environment: 'unknown',
+    launch: 'unknown',
+    deployment: 'unknown',
     resources: 'unknown',
     verification: 'unknown',
     programFiles: [],
@@ -24,7 +32,11 @@ function invalidResult(area, error) {
   };
 }
 
-export async function checkProject({ environment = process.env, projectRoot } = {}) {
+export async function checkProject({
+  environment = process.env,
+  projectRoot,
+  stackPackages = [],
+} = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
   try {
     await readBlueprint(root, { required: true, requireDescription: true });
@@ -34,7 +46,7 @@ export async function checkProject({ environment = process.env, projectRoot } =
 
   let stack;
   try {
-    stack = await readStack(root);
+    stack = await readStack(root, { stackPackages });
   } catch (error) {
     return invalidResult('stack', error);
   }
@@ -61,10 +73,18 @@ export async function checkProject({ environment = process.env, projectRoot } =
     resources: stack.resources,
   });
   const verification = await inspectVerification({ projectRoot: root, stack });
+  const [workspaceSetup, projectEnvironment, launch, deployment] = await Promise.all([
+    inspectWorkspaceSetupForStack({ projectRoot: root, stack }),
+    inspectProjectEnvironment({ environment, projectRoot: root, stackPackages }),
+    inspectProjectLaunch({ environment, projectRoot: root, stackPackages }),
+    inspectProjectDeployment({ projectRoot: root, stackPackages }),
+  ]);
   const diagnostics = [
     ...(program.diagnostic ? [program.diagnostic] : []),
     ...skills.diagnostics,
     ...missingResources,
+    ...workspaceSetup.diagnostics.filter(({ code }) => code !== 'STACK_WORKSPACE_SETUP_WAITING'),
+    ...deployment.diagnostics,
     ...(verification.status === 'invalid' ? [{
       code: 'VERIFICATION_EVIDENCE_INVALID',
       message: 'Saved verification evidence is malformed.',
@@ -79,6 +99,8 @@ export async function checkProject({ environment = process.env, projectRoot } =
   if (missingResources.length > 0) {
     guidance.push(`${missingResources.map(({ message }) => message).join(' ')} Prompt generation remains available.`);
   }
+  if (workspaceSetup.status === 'blocked') guidance.push('Repair the project Workspace setup declaration.');
+  if (deployment.status === 'blocked') guidance.push('Repair the project Deployment declaration.');
   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.');
@@ -86,6 +108,8 @@ export async function checkProject({ environment = process.env, projectRoot } =
   const needsAttention = program.status === 'missing'
     || skills.status === 'missing'
     || missingResources.length > 0
+    || workspaceSetup.status === 'blocked'
+    || deployment.status === 'blocked'
     || ['missing', 'stale', 'unconfigured'].includes(verification.status);
 
   return {
@@ -96,6 +120,10 @@ export async function checkProject({ environment = process.env, projectRoot } =
     stack: 'valid',
     skills: skills.status,
     program: program.status,
+    workspaceSetup: workspaceSetup.status,
+    environment: projectEnvironment.status,
+    launch: launch.status,
+    deployment: deployment.status,
     resources: missingResources.length > 0 ? 'missing' : 'inputs-present',
     verification: verification.status,
     programFiles: program.files,

package/src/index/code-index.js

@@ -238,9 +238,14 @@ function formatCount(value, singular) {
   return `${value} ${singular}${value === 1 ? '' : 's'}`;
 }
 
-export async function buildProjectIndex({ projectRoot, queries = [], write = true } = {}) {
+export async function buildProjectIndex({
+  projectRoot,
+  queries = [],
+  stackPackages = [],
+  write = true,
+} = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
-  const stack = await readStack(root);
+  const stack = await readStack(root, { stackPackages });
   const states = await gitVisibleFileStates(root, { includePath: isProjectContentPath });
   const files = [...states]
     .filter(([filePath, state]) => (

package/src/index/context.js

@@ -49,7 +49,7 @@ function pathMatchesTarget(filePath, target) {
   return !target || filePath === target || filePath.startsWith(`${target}/`);
 }
 
-export async function contextForProjectPaths({ paths, projectRoot } = {}) {
+export async function contextForProjectPaths({ paths, projectRoot, stackPackages = [] } = {}) {
   if (!Array.isArray(paths) || paths.length === 0) {
     throw new GenesisError('CONTEXT_PATH_REQUIRED', 'Genesis context requires at least one project path.');
   }
@@ -62,7 +62,7 @@ export async function contextForProjectPaths({ paths, projectRoot } = {}) {
       modules: [],
       diagnostic: asDiagnostic(error),
     })),
-    readStack(root),
+    readStack(root, { stackPackages }),
   ]);
   const modules = program.modules.filter((module) => targets.some((target) => citesTarget(module, target)));
   const moduleSources = await Promise.all(modules.map(async (module) => ({

package/src/index/contracts.js

@@ -0,0 +1,7 @@
+export const GENESIS_CONTRACTS = Object.freeze({
+  deployment: 'genesis.deployment.v1',
+  environment: 'genesis.environment.v1',
+  launch: 'genesis.launch.v1',
+  verification: 'genesis.verification.v1',
+  workspaceSetup: 'genesis.workspace-setup.v1',
+});

package/src/index/deployment.js

@@ -1,11 +1,12 @@
 import { gitContext } from './git.js';
 import { readStack } from './stack.js';
 import { sha256, stableJson, uniqueSorted } from './utils.js';
+import { GENESIS_CONTRACTS } from './contracts.js';
 
 /** Read the Stack's production recipe without provisioning or publishing anything. */
-export async function inspectProjectDeployment({ projectRoot } = {}) {
+export async function inspectProjectDeployment({ projectRoot, stackPackages = [] } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
-  const stack = await readStack(root);
+  const stack = await readStack(root, { stackPackages });
   const diagnostics = [...stack.deployment.diagnostics];
   let status = 'unconfigured';
   if (diagnostics.length > 0) status = 'blocked';
@@ -18,6 +19,7 @@ export async function inspectProjectDeployment({ projectRoot } = {}) {
     steps: stack.deployment.steps,
   };
   return {
+    contract: GENESIS_CONTRACTS.deployment,
     status,
     stackHash: stack.identityHash,
     recipeHash: status === 'ready' ? sha256(stableJson(recipe)) : '',

package/src/index/environment-files.js

@@ -2,11 +2,16 @@ import { gitContext } from './git.js';
 import { readStack } from './stack.js';
 import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { missingStackResources } from './stack-preflight.js';
+import { GENESIS_CONTRACTS } from './contracts.js';
 
 /** Inspect Stack environment requirements without returning supplied host values. */
-export async function inspectProjectEnvironment({ environment = process.env, projectRoot } = {}) {
+export async function inspectProjectEnvironment({
+  environment = process.env,
+  projectRoot,
+  stackPackages = [],
+} = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
-  const stack = await readStack(root);
+  const stack = await readStack(root, { stackPackages });
   const diagnostics = missingStackResources({
     environment: withStackEnvironmentDefaults(environment, stack.environmentDefaults),
     resources: stack.resources,
@@ -15,6 +20,7 @@ export async function inspectProjectEnvironment({ environment = process.env, pro
     || stack.environmentFiles.length > 0
     || stack.resources.length > 0;
   return {
+    contract: GENESIS_CONTRACTS.environment,
     status: !configured ? 'unconfigured' : diagnostics.length > 0 ? 'missing-inputs' : 'ready',
     stackHash: stack.identityHash,
     components: stack.components.map(({ id }) => id),

package/src/index/init.js

@@ -20,14 +20,14 @@ async function createIfMissing(projectRoot, relativePath, source) {
   }
 }
 
-export async function initializeProject({ projectRoot } = {}) {
+export async function initializeProject({ projectRoot, stackPackages = [] } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const created = (await Promise.all([
     createIfMissing(root, BLUEPRINT_PATH, BLUEPRINT_SKELETON_SOURCE),
     createIfMissing(root, STACK_PATH, EMPTY_STACK_SOURCE),
   ])).filter(Boolean);
   await mkdir(path.join(root, PROGRAM_ROOT), { recursive: true });
-  const stack = await readStack(root);
+  const stack = await readStack(root, { stackPackages });
   const skills = await syncProjectSkills({ projectRoot: root, stack });
   const hooks = await installCodexHooks({ projectRoot: root });
   const changedFiles = [...created, ...hooks.changedFiles, ...skills.changedFiles].sort();

package/src/index/launch.js

@@ -3,14 +3,16 @@ import { missingStackResources } from './stack-preflight.js';
 import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { readStack } from './stack.js';
 import { uniqueSorted } from './utils.js';
+import { GENESIS_CONTRACTS } from './contracts.js';
 
 /** Read the Stack's launch declaration without choosing or starting a runtime. */
 export async function inspectProjectLaunch({
   environment = process.env,
   projectRoot,
+  stackPackages = [],
 } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
-  const stack = await readStack(root);
+  const stack = await readStack(root, { stackPackages });
   const diagnostics = missingStackResources({
     environment: withStackEnvironmentDefaults(environment, stack.environmentDefaults),
     resources: stack.resources,
@@ -27,6 +29,7 @@ export async function inspectProjectLaunch({
   if (targets.length === 0) status = 'unconfigured';
   else if (diagnostics.length > 0) status = 'blocked';
   return {
+    contract: GENESIS_CONTRACTS.launch,
     status,
     stackHash: stack.identityHash,
     components: stack.components.map(({ id }) => id),