genesis-compiler 1.2.2 → 1.2.3

package/README.md

@@ -116,8 +116,13 @@ Genesis never overwrites an unmanaged skill and preserves locally modified
 managed skills. Run `genesis init` after manually editing `genesis/stack.md`,
 or use `genesis stack add`, to synchronize selected skills.
 
-Hosts that create dependency-empty workspaces can call the public
-`inspectWorkspaceSetup()` API. A concrete Stack piece may declare one exact,
+Run `genesis prepare` to execute the selected Stack's exact workspace recipe
+directly with the caller's environment and installed toolchain. It executes
+argument arrays without a shell, honors declared project-relative working
+directories and conditional paths, stops on the first failure, and never
+returns environment values. Hosts that need their own runtime, permission, or
+process policy can instead call the public `inspectWorkspaceSetup()` API and
+execute the same normalized recipe themselves. A concrete Stack piece may declare one exact,
 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
@@ -127,8 +132,9 @@ piece waits for `package.json` and then declares `npm install`; generic
 `genesis/stack.md` replaces all component defaults, including with
 `- Nothing.`. Without that override, exactly one component recipe is used;
 multiple component recipes are reported as ambiguous and never merged.
-Genesis does not run the recipe. Stack resources such as database variables do
-not gate dependency installation.
+The standalone command does not provision declared resources: callers provide
+their own database, credentials, compilers, and other infrastructure. Stack
+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

package/docs/assurance-model.md

@@ -24,3 +24,18 @@ semantically current, or that passing checks prove the whole product correct.
 
 Git remains the review and recovery boundary. The host running the generated
 prompt owns the agent and its interaction.
+
+## Filesystem ownership
+
+Genesis does not copy package-file ownership or broad source modes into a
+project. It creates ordinary project files with mode `0666`, directories and
+executable skill files with mode `0777`, and lets the invoking process umask
+and the destination directory's inherited ACL establish the effective mode and
+group. Atomic replacements are created beside their destination so they inherit
+the same filesystem policy before becoming visible. Private hook continuation
+state remains explicitly `0600`.
+
+This keeps ordinary single-user projects conventional while allowing a managed
+host to require shared-group writes and no access for other users. The host is
+responsible for establishing and verifying that umask, setgid directory, ACL,
+and cross-identity contract before Genesis or an agent starts.

package/docs/stack-components.md

@@ -24,6 +24,17 @@ What this component contributes.
 
 - `javascript`
 
+## City regions
+
+- Ignore `**/test/**`
+- Ignore `**/tests/**`
+- Ignore `**/__tests__/**`
+- Ignore `**/*.test.*`
+- Ignore `**/*.spec.*`
+- Match `packages` as `Packages`: `packages/**`
+- Match `source` as `Source`: `src/**`
+- Fallback `everything-else` as `Everything else`
+
 ## Resources
 
 ```json genesis-resource
@@ -239,6 +250,25 @@ may contribute indexers, and duplicates are collapsed. Index output is
 navigation data, not proof that every dynamic callable or framework edge was
 discovered.
 
+`City regions` is an optional complete presentation contract for Machine City.
+Leading `Ignore` entries are canonical project-relative glob patterns using
+only `*` within a path segment and `**` across segments. Genesis excludes their
+matching files before it emits Machine City buildings or functions. This keeps
+test/spec source out of the product City without requiring a host-side filter.
+Each subsequent ordered `Match` entry declares one canonical project-relative
+`path/**` prefix, stable id, and human title. Exactly one final `Fallback` entry
+owns every remaining indexed path. Ignore patterns, ids, and prefixes must be
+unique, prefixes must not overlap, and no more than one selected component may
+declare the contract. Genesis resolves every indexed file and structural
+district to a region and a campus while generating
+`.genesis/machine-city.json`; a City renderer consumes those emitted facts and
+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
+`test`, `tests`, and `__tests__` path segments plus `*.test.*` and `*.spec.*`
+files, then declares `Packages`, `Source`, and `Everything else`.
+
 Do not create a Genesis-owned generic skill merely because a component is
 named `nodejs`, `php`, or another common technology. Official, user, and host
 skills with those names must coexist normally. Use `## Skill` only for an
@@ -337,6 +367,20 @@ blocked result.
 The optional environment object is accepted for a consistent host inspection
 boundary, but Workspace setup v1 neither reads nor returns its values.
 
+Standalone users may execute the same normalized recipe with their own
+environment and installed toolchain:
+
+```bash
+genesis prepare
+```
+
+`genesis prepare` runs each declared argv directly without a shell, in order,
+and stops at the first failure. It honors project-relative workdirs and
+conditional paths. It does not provision databases, compilers, credentials,
+runtimes, or other resources. Managed hosts remain free to consume
+`inspectWorkspaceSetup()` and enforce their own execution, identity, runtime,
+and permission policies.
+
 Preview hosts read the normalized Launch contract independently:
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with optional Codex hooks.",
   "repository": {
@@ -56,7 +56,7 @@
     "@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.131",
+    "@jskit-ai/agent-docs": "0.1.132",
     "yaml": "^2.9.0"
   }
 }

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

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

package/src/cli.js

@@ -11,6 +11,7 @@ import {
   initialize,
   installCodex,
   listStackPieces,
+  prepareWorkspace,
   verify,
 } from './index.js';
 import {
@@ -30,6 +31,7 @@ const USAGE = `Usage:
   genesis stack add <piece...>
   genesis context <path...>
   genesis index [function-or-path...]
+  genesis prepare
   genesis prompt [request...]
   genesis prompt --task <start|work|deslop|program|blueprint|describe|review> [request...]
   genesis verify
@@ -46,7 +48,7 @@ prompt to the agent you already use. Review all edits through the ordinary Git
 diff, then run genesis verify for the Stack's concrete checks.
 `;
 
-const COMMANDS = new Set(['adopt', 'check', 'codex', 'context', 'hook', 'index', 'init', 'prompt', 'stack', 'verify']);
+const COMMANDS = new Set(['adopt', 'check', 'codex', 'context', 'hook', 'index', 'init', 'prepare', 'prompt', 'stack', 'verify']);
 
 function parseCommand(argv) {
   if (argv.length === 0 || argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') {
@@ -165,6 +167,19 @@ function writeResult(command, result) {
     line(process.stdout, `index: ${result.status}`);
     return;
   }
+  if (command === 'prepare') {
+    if (result.summary) line(process.stdout, result.summary);
+    namedItems('Commands', result.commands?.map(({ label, argv }) => `${label}: ${argv.join(' ')}`));
+    for (const item of result.diagnostics || []) {
+      line(process.stdout, `${item.code}: ${item.message}`);
+      for (const field of ['stdout', 'stderr']) {
+        const output = item.details?.[field]?.trim();
+        if (output) line(process.stdout, output);
+      }
+    }
+    line(process.stdout, `prepare: ${result.status}`);
+    return;
+  }
   if (command === 'hook') {
     if (['discover', 'session'].includes(result.kind) && result.output) line(process.stdout, result.output);
     else if (result.kind === 'stop') line(process.stdout, JSON.stringify(result.output));
@@ -226,6 +241,14 @@ async function execute({ command, operands, options }) {
   }
   if (command === 'context') return getContext({ paths: operands, projectRoot });
   if (command === 'index') return indexCodebase({ projectRoot, queries: operands });
+  if (command === 'prepare') {
+    return prepareWorkspace({
+      projectRoot,
+      onEvent: (event) => {
+        if (!options.json) line(process.stderr, event.message);
+      },
+    });
+  }
   if (command === 'hook') {
     if (operands[0] === 'discover') {
       return { kind: 'discover', ...await codexAdoptionRecommendation({ projectRoot }) };

package/src/index/agent-skills.js

@@ -1,13 +1,13 @@
 import { randomUUID } from 'node:crypto';
 import { createRequire } from 'node:module';
 import {
-  cp,
   lstat,
   mkdir,
   readFile,
   readdir,
   rename,
   rm,
+  writeFile,
 } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -92,7 +92,7 @@ async function skillTree(directory, relative = '') {
     files.push({
       path: child,
       hash: sha256(content),
-      mode: (info.mode & 0o111) === 0 ? 0o100644 : 0o100755,
+      mode: (info.mode & 0o100) === 0 ? 0o100644 : 0o100755,
     });
   }
   return files;
@@ -251,7 +251,7 @@ async function replaceSkill(source, target) {
   await mkdir(path.dirname(target), { recursive: true });
   let replaced = false;
   try {
-    await cp(source, temporary, { recursive: true, errorOnExist: true });
+    await copySkillTree(source, temporary);
     try {
       await rename(target, backup);
       replaced = true;
@@ -271,6 +271,23 @@ async function replaceSkill(source, target) {
   }
 }
 
+async function copySkillTree(source, target) {
+  const info = await lstat(source);
+  if (info.isSymbolicLink() || (!info.isDirectory() && !info.isFile())) {
+    invalidSkill(`Agent Skill contains a non-ordinary entry: ${source}.`);
+  }
+  if (info.isDirectory()) {
+    await mkdir(target, { mode: 0o777 });
+    const entries = await readdir(source, { withFileTypes: true });
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      await copySkillTree(path.join(source, entry.name), path.join(target, entry.name));
+    }
+    return;
+  }
+  const mode = (info.mode & 0o100) === 0 ? 0o666 : 0o777;
+  await writeFile(target, await readFile(source), { flag: 'wx', mode });
+}
+
 function targetFiles(skill) {
   return skill.files.map(({ path: file }) => `${SKILLS_ROOT}/${skill.name}/${file}`);
 }
@@ -304,6 +321,10 @@ export async function syncProjectSkills({ projectRoot, stack } = {}) {
       continue;
     }
     if (installed.hash !== managed.hash) {
+      if (installed.hash === skill.hash) {
+        manifest.value.skills[skill.name] = { hash: skill.hash, source: skill.source };
+        continue;
+      }
       diagnostics.push({
         code: 'AGENT_SKILL_CUSTOMIZED',
         message: `Preserved locally modified Agent Skill ${skill.name}.`,
@@ -388,7 +409,7 @@ export async function inspectProjectSkills({ projectRoot, stack } = {}) {
         message: `Project Agent Skill ${expected.name} is externally managed; Genesis preserved it.`,
         details: { name: expected.name, path: `${SKILLS_ROOT}/${expected.name}/SKILL.md` },
       });
-    } else if (installed.hash !== managed.hash) {
+    } else if (installed.hash !== managed.hash && installed.hash !== expected.hash) {
       customized = true;
       diagnostics.push({
         code: 'AGENT_SKILL_CUSTOMIZED',

package/src/index/city-presentation.js

@@ -0,0 +1,83 @@
+import path from 'node:path';
+
+function presentationRegionForPath(filePath, regions) {
+  return regions.find((region) => (
+    !region.fallback
+    && (filePath === region.pathPrefix || filePath.startsWith(`${region.pathPrefix}/`))
+  )) || regions.find(({ fallback }) => fallback) || null;
+}
+
+function parentDirectory(filePath) {
+  const parent = path.posix.dirname(filePath);
+  return parent === '.' ? '' : parent;
+}
+
+function presentationCampusPath(filePath, region, { file = false } = {}) {
+  const ownershipPath = file ? parentDirectory(filePath) : filePath;
+  if (!region || region.fallback) {
+    return ownershipPath.split('/').filter(Boolean)[0] || '';
+  }
+  if (ownershipPath === region.pathPrefix) return region.pathPrefix;
+  const relative = ownershipPath.slice(region.pathPrefix.length + 1);
+  const child = relative.split('/').filter(Boolean)[0];
+  return child ? `${region.pathPrefix}/${child}` : region.pathPrefix;
+}
+
+function campusId(regionId, campusPath) {
+  return `presentation-campus:${regionId}:${campusPath || '.'}`;
+}
+
+/** Resolves Stack-declared City regions and campus roots into Machine City facts. */
+export function buildCityPresentation({ districts = [], files = [], regions = [] } = {}) {
+  if (regions.length === 0) {
+    return {
+      campuses: [],
+      placementForPath: () => ({ presentationCampusId: null, presentationRegionId: null }),
+      regions: [],
+    };
+  }
+  const districtsByPath = new Map(districts.map((district) => [district.path, district]));
+  const placements = new Map();
+  const mutableCampuses = new Map();
+  const mutableRegions = new Map(regions.map((region) => [region.id, {
+    ...region,
+    buildingCount: 0,
+  }]));
+
+  function resolvePlacement(filePath = '', { file = false } = {}) {
+    if (placements.has(filePath)) return placements.get(filePath);
+    const region = presentationRegionForPath(filePath, regions);
+    const campusPath = presentationCampusPath(filePath, region, { file });
+    const placement = {
+      presentationCampusId: campusId(region.id, campusPath),
+      presentationRegionId: region.id,
+    };
+    placements.set(filePath, placement);
+    if (!mutableCampuses.has(placement.presentationCampusId)) {
+      mutableCampuses.set(placement.presentationCampusId, {
+        id: placement.presentationCampusId,
+        regionId: region.id,
+        path: campusPath,
+        title: campusPath ? path.posix.basename(campusPath) : 'Project root',
+        districtId: districtsByPath.get(campusPath)?.id || null,
+        buildingCount: 0,
+      });
+    }
+    return placement;
+  }
+
+  for (const file of files) {
+    const placement = resolvePlacement(file.path, { file: true });
+    mutableRegions.get(placement.presentationRegionId).buildingCount += 1;
+    mutableCampuses.get(placement.presentationCampusId).buildingCount += 1;
+  }
+  for (const district of districts) resolvePlacement(district.path);
+
+  return {
+    campuses: [...mutableCampuses.values()]
+      .filter(({ buildingCount }) => buildingCount > 0)
+      .sort((left, right) => left.id.localeCompare(right.id)),
+    placementForPath: (filePath = '') => placements.get(filePath) || resolvePlacement(filePath),
+    regions: [...mutableRegions.values()],
+  };
+}

package/src/index/code-index.js

@@ -3,6 +3,8 @@ import path from 'node:path';
 
 import { astGrepCodeIndexers } from './code-indexers/ast-grep.js';
 import { asDiagnostic } from './errors.js';
+import { buildCityPresentation } from './city-presentation.js';
+import { cityPathExcluded } from './stack-city-presentation.js';
 import { gitContext } from './git.js';
 import { isProjectContentPath } from './paths.js';
 import { inspectProgram } from './program.js';
@@ -128,8 +130,14 @@ function mergeIndexedFiles(contributions) {
   };
 }
 
-function machineCity({ components, contributions, diagnostics, indexers }) {
+function machineCity({ cityRegions, components, contributions, diagnostics, indexers }) {
   const merged = mergeIndexedFiles(contributions);
+  const structuralDistricts = directoryRecords(merged.files.map(({ path: filePath }) => filePath));
+  const presentation = buildCityPresentation({
+    districts: structuralDistricts,
+    files: merged.files,
+    regions: cityRegions,
+  });
   const visibility = new Map(merged.functions.map((entry) => [entry.id, entry.visibility]));
   const codeHash = sha256(stableJson(merged.files.map(({ path: filePath, hash, mode }) => ({
     path: filePath,
@@ -141,13 +149,19 @@ function machineCity({ components, contributions, diagnostics, indexers }) {
     schemaVersion: 1,
     status: indexers.length === 0 ? 'unconfigured' : diagnostics.length > 0 ? 'completed-with-warning' : 'current',
     codeHash,
+    presentationRegions: presentation.regions,
+    presentationCampuses: presentation.campuses,
     stackComponents: components,
     indexers,
     diagnostics,
     functions: merged.functions,
-    districts: directoryRecords(merged.files.map(({ path: filePath }) => filePath)),
+    districts: structuralDistricts.map((district) => ({
+      ...district,
+      ...presentation.placementForPath(district.path),
+    })),
     buildings: merged.files.map((file) => ({
       ...file,
+      ...presentation.placementForPath(file.path),
       districtId: directoryId(parentDirectory(file.path)),
       title: path.posix.basename(file.path),
       publicFunctionCount: file.functionIds.filter((id) => visibility.get(id) === 'public').length,
@@ -229,7 +243,13 @@ export async function buildProjectIndex({ projectRoot, queries = [], write = tru
   const stack = await readStack(root);
   const states = await gitVisibleFileStates(root, { includePath: isProjectContentPath });
   const files = [...states]
-    .filter(([, state]) => state.exists && !state.symlink && !state.special && state.hash)
+    .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 indexers = [...new Set(stack.components.flatMap((component) => component.indexers || []))].sort();
   const contributions = [];
@@ -249,6 +269,7 @@ export async function buildProjectIndex({ projectRoot, queries = [], write = tru
     }
   }
   const machine = machineCity({
+    cityRegions: stack.cityRegions,
     components: stack.components.map(({ id }) => id),
     contributions,
     diagnostics,

package/src/index/init.js

@@ -12,7 +12,7 @@ async function createIfMissing(projectRoot, relativePath, source) {
   const location = path.join(projectRoot, relativePath);
   await mkdir(path.dirname(location), { recursive: true });
   try {
-    await writeFile(location, source, { flag: 'wx', mode: 0o644 });
+    await writeFile(location, source, { flag: 'wx', mode: 0o666 });
     return relativePath;
   } catch (error) {
     if (error?.code === 'EEXIST') return null;

package/src/index/stack-catalog.js

@@ -63,6 +63,8 @@ export async function listBuiltinStackPieces() {
       guidance: piece.guidance,
       requires: piece.requires,
       conflicts: piece.conflicts,
+      cityExclusions: piece.cityExclusions,
+      cityRegions: piece.cityRegions,
       indexers: piece.indexers,
       environmentDefaults: piece.environmentDefaults,
       launchTargets: piece.launchTargets.map(({ id }) => id),

package/src/index/stack-city-presentation.js

@@ -0,0 +1,178 @@
+import { GenesisError } from './errors.js';
+
+const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const IGNORE_LINE = /^- Ignore `([^`]+)`[ \t]*$/u;
+const MATCH_LINE = /^- Match `([^`]+)` as `([^`]+)`: `([^`]+)\/\*\*`[ \t]*$/u;
+const FALLBACK_LINE = /^- Fallback `([^`]+)` as `([^`]+)`[ \t]*$/u;
+const REGEXP_SPECIAL = /[.+^${}()|[\]\\]/u;
+const compiledGlobPatterns = new Map();
+
+function invalid(piecePath, message) {
+  throw new GenesisError('STACK_PIECE_INVALID', message, { path: piecePath });
+}
+
+function normalizedPrefix(value, piecePath) {
+  const prefix = String(value || '').trim();
+  if (
+    !prefix
+    || prefix.startsWith('/')
+    || prefix.includes('\\')
+    || /[*?\[\]{}!]/u.test(prefix)
+    || prefix.split('/').some((segment) => !segment || ['.', '..'].includes(segment))
+  ) {
+    invalid(piecePath, '## City regions match paths must be canonical project-relative prefixes.');
+  }
+  return prefix;
+}
+
+function normalizedGlob(value, piecePath) {
+  const pattern = String(value || '').trim();
+  if (
+    !pattern
+    || pattern.startsWith('/')
+    || pattern.includes('\\')
+    || pattern.includes('***')
+    || /[?\[\]{}!]/u.test(pattern)
+    || pattern.split('/').some((segment) => !segment || ['.', '..'].includes(segment))
+  ) {
+    invalid(
+      piecePath,
+      '## City regions ignore patterns must be canonical project-relative globs using only * and ** wildcards.',
+    );
+  }
+  return pattern;
+}
+
+function regionIdentity(id, title, piecePath) {
+  if (!ID_PATTERN.test(id)) {
+    invalid(piecePath, '## City regions ids must use lowercase letters, digits, and single hyphens.');
+  }
+  if (!title.trim()) invalid(piecePath, '## City regions titles must not be empty.');
+  return { id, title: title.trim() };
+}
+
+function globExpression(pattern) {
+  if (compiledGlobPatterns.has(pattern)) return compiledGlobPatterns.get(pattern);
+  let expression = '^';
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern[index];
+    if (character === '*' && pattern[index + 1] === '*') {
+      if (pattern[index + 2] === '/') {
+        expression += '(?:[^/]+/)*';
+        index += 2;
+      } else {
+        expression += '.*';
+        index += 1;
+      }
+    } else if (character === '*') {
+      expression += '[^/]*';
+    } else {
+      expression += REGEXP_SPECIAL.test(character) ? `\\${character}` : character;
+    }
+  }
+  const compiled = new RegExp(`${expression}$`, 'u');
+  compiledGlobPatterns.set(pattern, compiled);
+  return compiled;
+}
+
+export function cityPathExcluded(filePath, exclusions = []) {
+  return exclusions.some((pattern) => globExpression(pattern).test(filePath));
+}
+
+/**
+ * A City presentation declaration is one complete, ordered contract. Ignore
+ * globs remove non-product files before Machine City is emitted. Matching
+ * prefixes are explicit Stack facts; one final fallback owns every remaining
+ * path. Genesis resolves both region and campus placement, so renderers never
+ * classify or filter repository paths.
+ */
+export function parseStackCityPresentationLines(lines, { path = 'stack piece' } = {}) {
+  if (lines === undefined) return { exclusions: [], regions: [] };
+  const content = lines.filter((line) => line.trim());
+  if (content.length === 0 || (content.length === 1 && content[0].trim() === '- Nothing.')) {
+    return { exclusions: [], regions: [] };
+  }
+  const exclusions = [];
+  const regions = [];
+  let regionDeclarationStarted = false;
+  content.forEach((line, index) => {
+    const ignore = line.match(IGNORE_LINE);
+    if (ignore) {
+      if (regionDeclarationStarted) {
+        invalid(path, '## City regions Ignore entries must precede Match and Fallback entries.');
+      }
+      exclusions.push(normalizedGlob(ignore[1], path));
+      return;
+    }
+    regionDeclarationStarted = true;
+    const match = line.match(MATCH_LINE);
+    if (match) {
+      const identity = regionIdentity(match[1], match[2], path);
+      regions.push({
+        ...identity,
+        fallback: false,
+        pathPrefix: normalizedPrefix(match[3], path),
+      });
+      return;
+    }
+    const fallback = line.match(FALLBACK_LINE);
+    if (fallback) {
+      if (index !== content.length - 1) {
+        invalid(path, '## City regions fallback must be the final declaration.');
+      }
+      regions.push({
+        ...regionIdentity(fallback[1], fallback[2], path),
+        fallback: true,
+        pathPrefix: null,
+      });
+      return;
+    }
+    invalid(
+      path,
+      '## City regions entries must use Ignore with a glob, Match with an id, title, and path/**, or one final Fallback.',
+    );
+  });
+  if (new Set(exclusions).size !== exclusions.length) {
+    invalid(path, '## City regions contains a duplicate ignore pattern.');
+  }
+  if (new Set(regions.map(({ id }) => id)).size !== regions.length) {
+    invalid(path, '## City regions contains a duplicate region id.');
+  }
+  const matches = regions.filter(({ fallback }) => !fallback);
+  if (new Set(matches.map(({ pathPrefix }) => pathPrefix)).size !== matches.length) {
+    invalid(path, '## City regions contains a duplicate path prefix.');
+  }
+  if (regions.filter(({ fallback }) => fallback).length !== 1) {
+    invalid(path, '## City regions requires exactly one final fallback.');
+  }
+  for (const [index, left] of matches.entries()) {
+    if (matches.slice(index + 1).some((right) => (
+      left.pathPrefix.startsWith(`${right.pathPrefix}/`)
+      || right.pathPrefix.startsWith(`${left.pathPrefix}/`)
+    ))) {
+      invalid(path, '## City regions match prefixes must not overlap.');
+    }
+  }
+  return { exclusions, regions };
+}
+
+export function composeStackCityPresentation(components = []) {
+  const owners = components.filter((component) => (
+    component.cityRegions.length > 0 || component.cityExclusions.length > 0
+  ));
+  if (owners.length === 0) return { exclusions: [], regions: [] };
+  if (owners.length > 1) {
+    throw new GenesisError(
+      'STACK_CITY_PRESENTATION_AMBIGUOUS',
+      `Stack components ${owners.map(({ id }) => id).join(', ')} declare competing City presentation contracts.`,
+      { components: owners.map(({ id }) => id) },
+    );
+  }
+  return {
+    exclusions: [...owners[0].cityExclusions],
+    regions: owners[0].cityRegions.map((region) => ({
+      ...region,
+      component: owners[0].id,
+    })),
+  };
+}

package/src/index/stack-piece.js

@@ -1,5 +1,6 @@
 import { GenesisError } from './errors.js';
 import { parseStackCommandLines } from './stack-command.js';
+import { parseStackCityPresentationLines } from './stack-city-presentation.js';
 import { parseStackDeploymentLines } from './stack-deployment.js';
 import { parseStackEnvironmentDefaultLines } from './stack-environment-defaults.js';
 import { parseStackEnvironmentFileLines } from './stack-environment-files.js';
@@ -220,6 +221,10 @@ export function parseStackPieceSource(value, {
   const deslop = textSection(all, 'Deslop');
   if (!description) invalid(piecePath, 'Stack piece needs Description.');
   const commands = parseStackCommandLines(all.get('Commands') || [], { path: piecePath });
+  const cityPresentation = parseStackCityPresentationLines(
+    all.has('City regions') ? all.get('City regions') : undefined,
+    { path: piecePath },
+  );
   const environmentDefaults = parseStackEnvironmentDefaultLines(
     all.has('Environment defaults') ? all.get('Environment defaults') : undefined,
     { path: piecePath },
@@ -249,6 +254,8 @@ export function parseStackPieceSource(value, {
     skill: skill(all, piecePath),
     resources: resources(all, piecePath),
     commands: commands.map(({ line: _line, ...command }) => command),
+    cityExclusions: cityPresentation.exclusions,
+    cityRegions: cityPresentation.regions,
     environmentDefaults,
     environmentFiles: environmentFiles || [],
     launchTargets: launch?.targets || [],

package/src/index/stack.js

@@ -5,6 +5,7 @@ import { syncProjectSkills } from './agent-skills.js';
 import { GenesisError } from './errors.js';
 import { readBuiltinStackCatalog } from './stack-catalog.js';
 import { parseStackCommandLines } from './stack-command.js';
+import { composeStackCityPresentation } from './stack-city-presentation.js';
 import { composeStackDeployment, parseStackDeploymentLines } from './stack-deployment.js';
 import { resolveStackPieces } from './stack-composition.js';
 import {
@@ -264,6 +265,7 @@ export async function readStack(projectRoot) {
   ).map(({ line: _line, ...command }) => command);
   const componentCommands = components.flatMap((piece) => piece.commands);
   const commands = distinctCommands(projectCommands.length > 0 ? projectCommands : componentCommands);
+  const cityPresentation = composeStackCityPresentation(components);
   const resources = resourceDeclarations(components);
   const environmentDefaults = composeStackEnvironmentDefaults(components);
   const projectEnvironmentFiles = parseStackEnvironmentFileLines(
@@ -290,6 +292,8 @@ export async function readStack(projectRoot) {
     path: STACK_PATH,
     identityHash: sha256(stableJson({
       components: components.map(({ id }) => id),
+      cityExclusions: cityPresentation.exclusions,
+      cityRegions: cityPresentation.regions,
       commands: commands.map(({ label, argv }) => ({ label, argv })),
       environmentDefaults,
       environmentFiles,
@@ -299,6 +303,8 @@ export async function readStack(projectRoot) {
       workspaceSetup,
     })),
     components,
+    cityExclusions: cityPresentation.exclusions,
+    cityRegions: cityPresentation.regions,
     commands,
     environmentDefaults,
     environmentFiles,
@@ -319,6 +325,8 @@ export function stackPromptContext(stack) {
       ...(piece.guidance ? { guidance: piece.guidance } : {}),
       requires: piece.requires,
     })),
+    cityExclusions: stack.cityExclusions,
+    cityRegions: stack.cityRegions,
     verifyCommands: stack.commands.map(({ label, argv }) => ({ label, argv })),
     environmentDefaults: stack.environmentDefaults,
     environmentFiles: stack.environmentFiles,

package/src/index/utils.js

@@ -29,7 +29,7 @@ export function uniqueSorted(values = []) {
   return [...new Set(values)].sort();
 }
 
-export async function writeFileAtomic(filePath, source, { mode = 0o644 } = {}) {
+export async function writeFileAtomic(filePath, source, { mode = 0o666 } = {}) {
   const temporary = `${filePath}.${randomUUID()}.tmp`;
   await mkdir(path.dirname(filePath), { recursive: true });
   try {

package/src/index/workspace-setup.js

@@ -1,10 +1,17 @@
 import { access } from 'node:fs/promises';
 import path from 'node:path';
 
+import { asDiagnostic } from './errors.js';
 import { gitContext } from './git.js';
+import { runProcess } from './process.js';
 import { readStack } from './stack.js';
+import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { sha256, stableJson, uniqueSorted } from './utils.js';
 
+async function emit(onEvent, event) {
+  try { await onEvent?.(event); } catch { /* Progress observers do not control preparation. */ }
+}
+
 export async function inspectWorkspaceSetupForStack({ projectRoot: root, stack }) {
   const diagnostics = [...stack.workspaceSetup.diagnostics];
   const applicableSteps = [];
@@ -68,3 +75,72 @@ export async function inspectProjectWorkspaceSetup({
   const stack = await readStack(root);
   return inspectWorkspaceSetupForStack({ projectRoot: root, stack });
 }
+
+/** Execute the selected Stack's exact workspace recipe with the caller's environment. */
+export async function prepareProjectWorkspace({
+  environment = process.env,
+  onEvent,
+  processRunner = runProcess,
+  projectRoot,
+} = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const stack = await readStack(root);
+  const setup = await inspectWorkspaceSetupForStack({ projectRoot: root, stack });
+  if (setup.status !== 'ready') {
+    const summary = setup.diagnostics.map(({ message }) => message).join(' ')
+      || 'The selected Stack declares no applicable workspace preparation commands.';
+    return {
+      ...setup,
+      summary,
+      commands: [],
+    };
+  }
+
+  const resolvedEnvironment = withStackEnvironmentDefaults(
+    environment,
+    stack.environmentDefaults,
+  );
+  const commands = [];
+  try {
+    for (const step of setup.steps) {
+      await emit(onEvent, {
+        type: 'genesis.workspace-preparation',
+        code: 'WORKSPACE_PREPARATION_STARTED',
+        message: `Preparing: ${step.label}.`,
+        details: { label: step.label, argv: step.argv, workdir: step.workdir },
+      });
+      await processRunner(step.argv[0], step.argv.slice(1), {
+        cwd: path.resolve(root, step.workdir),
+        env: resolvedEnvironment,
+        maxBytes: 32 * 1024 * 1024,
+        code: 'WORKSPACE_PREPARATION_FAILED',
+      });
+      commands.push({
+        label: step.label,
+        argv: step.argv,
+        workdir: step.workdir,
+      });
+      await emit(onEvent, {
+        type: 'genesis.workspace-preparation',
+        code: 'WORKSPACE_PREPARATION_COMPLETED',
+        message: `Prepared: ${step.label}.`,
+        details: { label: step.label, argv: step.argv, workdir: step.workdir },
+      });
+    }
+    return {
+      ...setup,
+      status: 'passed',
+      summary: `Prepared the workspace with ${commands.length} command${commands.length === 1 ? '' : 's'}.`,
+      commands,
+      diagnostics: [],
+    };
+  } catch (error) {
+    return {
+      ...setup,
+      status: 'failed',
+      summary: error.message,
+      commands,
+      diagnostics: [asDiagnostic(error)],
+    };
+  }
+}

package/src/index.js

@@ -12,7 +12,10 @@ import { inspectProjectLaunch } from './index/launch.js';
 import { listBuiltinStackPieces } from './index/stack-catalog.js';
 import { addStackPieces } from './index/stack.js';
 import { verifyProject } from './index/verification.js';
-import { inspectProjectWorkspaceSetup } from './index/workspace-setup.js';
+import {
+  inspectProjectWorkspaceSetup,
+  prepareProjectWorkspace,
+} from './index/workspace-setup.js';
 
 function withIndexResult(result, index) {
   const changedFiles = [...new Set([...result.changedFiles, ...index.changedFiles])].sort();
@@ -86,6 +89,10 @@ export function inspectWorkspaceSetup(options) {
   return inspectProjectWorkspaceSetup(options);
 }
 
+export function prepareWorkspace(options) {
+  return prepareProjectWorkspace(options);
+}
+
 export function generatePrompt(options) {
   return generateProjectPrompt(options);
 }

package/stacks/pieces/jskit.md

@@ -36,6 +36,17 @@ application-owned composition.
 
 - Dotenv `.env`
 
+## City regions
+
+- Ignore `**/test/**`
+- Ignore `**/tests/**`
+- Ignore `**/__tests__/**`
+- Ignore `**/*.test.*`
+- Ignore `**/*.spec.*`
+- Match `packages` as `Packages`: `packages/**`
+- Match `source` as `Source`: `src/**`
+- Fallback `everything-else` as `Everything else`
+
 ## Launch
 
 ### Target `app`: Run app