genesis-compiler 1.2.20 → 1.2.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.2.20",
+  "version": "1.2.22",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with optional Codex hooks.",
   "repository": {

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

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

package/prompts/adopt.txt

@@ -9,17 +9,18 @@ Genesis again or require them to understand Genesis terminology.
 Application source, dependencies, migrations, runtime behavior, and deployment
 files are read-only in this turn. You may edit `genesis/blueprint.md`,
 `genesis/stack.md`, explanatory Markdown below `genesis/program/`, and
-Genesis-managed skills/indexes produced by `genesis stack add` or Genesis
-inspection commands. Do not install dependencies, prepare a database, run
-migrations or seeds, start a server, deploy, or add compatibility code.
+Genesis-managed skills/indexes produced by the Genesis `stack add` operation or
+Genesis inspection commands. Do not install dependencies, prepare a database,
+run migrations or seeds, start a server, deploy, or add compatibility code.
 
 If Stack has no components, inspect direct evidence such as manifests,
 lockfiles, build files, entrypoints, package scripts, tests, configuration,
 database and migration code, and existing project-tool metadata. Record only
-technologies the implementation already uses with `genesis stack add
-<piece...>`; this is factual import, not a new-technology choice. Ask a concise
-product-language question only when evidence is genuinely ambiguous. Then run
-`genesis prompt --task adopt "Continue the approved existing-project import."`
+technologies the implementation already uses with the Genesis `stack add
+<piece...>` operation; this is factual import, not a new-technology choice. Ask
+a concise product-language question only when evidence is genuinely ambiguous.
+Then run the Genesis
+`prompt --task adopt "Continue the approved existing-project import."` operation
 and follow the regenerated prompt so every selected Stack piece contributes its
 Adoption requirements.
 
@@ -51,9 +52,10 @@ 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.
 
-Run `genesis check` only for structural validation. Missing environment inputs,
-Verification commands, or evidence required by a consumer-owned contract are
-honest import findings, not permission to invent or execute them. Finish with a
-clear inventory of what was imported, what remains unconfigured or blocked, and
-what would require a separately approved implementation port. Never claim the
-project is ready merely because Stack components were selected.
+Run the Genesis `check` operation only for structural validation. Missing
+environment inputs, Verification commands, or evidence required by a
+consumer-owned contract are honest import findings, not permission to invent or
+execute them. Finish with a clear inventory of what was imported, what remains
+unconfigured or blocked, and what would require a separately approved
+implementation port. Never claim the project is ready merely because Stack
+components were selected.

package/prompts/deslop.txt

@@ -8,9 +8,10 @@ and immediately related code. Apply every selected Stack cleanup instruction
 supplied below and load applicable official technology skills for additional
 language and framework context.
 
-Use `.genesis/machine-city.json` and `genesis index <name-or-path>` to find
-existing public and internal functions. Remove or consolidate genuine repeated
-helpers, but confirm behavior and call sites in source before changing them.
+Use `.genesis/machine-city.json` and the Genesis `index <name-or-path>` operation
+to find existing public and internal functions. Remove or consolidate genuine
+repeated helpers, but confirm behavior and call sites in source before changing
+them.
 
 The changed paths and nearby code are a location boundary, not permission to
 implement other behavior found there. Deslop may reorganize behavior already

package/prompts/start.txt

@@ -7,9 +7,10 @@ step are clear.
 When `projectKind` is `new`, first ask what the app is about. Ask up to three
 concise, high-impact questions at a time. Use `availableStackPieces` to present
 only the relevant choices, explain them in product language, and let the user
-decide. Never silently select a technology. After an explicit choice, use
-`genesis stack add <piece...>`; do not edit `genesis/stack.md` by hand. Establish
-the non-technical Blueprint from the user's answers before implementation.
+decide. Never silently select a technology. After an explicit choice, use the
+Genesis `stack add <piece...>` operation; do not edit `genesis/stack.md` by
+hand. Establish the non-technical Blueprint from the user's answers before
+implementation.
 If the product direction becomes clear while Stack is still empty, do not end
 the turn after only writing or summarizing the Blueprint: present the relevant
 Stack choices in that same turn and ask the user to select one explicitly.
@@ -18,13 +19,15 @@ work, so do not force a separate profile question. When the user asks for a
 different engineering approach, or the product clearly has long-lived
 compatibility, operational, security, reliability, or compliance constraints,
 use `availableEngineeringProfiles` to explain only the relevant choices in
-product language. After an explicit choice, run `genesis engineering set
-<profile>`; do not invent or duplicate a built-in profile. Record additional
-explicit obligations in `genesis/engineering.md` under Project requirements.
+product language. After an explicit choice, run the Genesis `engineering set
+<profile>` operation; do not invent or duplicate a built-in profile. Record
+additional explicit obligations in `genesis/engineering.md` under Project
+requirements.
 This opening turn owns product direction and Stack selection, not final
-verification. Do not run `genesis verify` before implementation exists. If
-structural validation is useful, run `genesis check`; consumer-owned operations
-remain governed by their own tools and must not be inferred here.
+verification. Do not run the Genesis `verify` operation before implementation
+exists. If structural validation is useful, run the Genesis `check` operation;
+consumer-owned operations remain governed by their own tools and must not be
+inferred here.
 
 When `projectKind` is `existing`, ask what the user wants to understand or
 change. Use the current Blueprint, Stack, Program, and code index when present.
@@ -45,9 +48,9 @@ understand or change and strongly recommend preparing the existing project for
 guided editing before substantial work. Explain in product language that this
 preserves the implementation while importing its current setup, run, database,
 preview, verification, and product context. Do not require the user to know
-Genesis terminology or type a command. If they approve, run `genesis adopt`
-yourself and follow its adoption prompt. If they decline, continue normally and
-do not repeat the recommendation.
+Genesis terminology or type a command. If they approve, run the Genesis `adopt`
+operation yourself and follow its adoption prompt. If they decline, continue
+normally and do not repeat the recommendation.
 
 If the request already contains an unambiguous product description and an
 explicit Stack choice, you may apply that choice and establish the Blueprint.

package/prompts/work.txt

@@ -4,8 +4,9 @@ implement the request in the ordinary local Git tree.
 Load the applicable official or project technology skills listed below. Use
 their normal generators, commands, packages, and established seams. Do not
 search package internals or unrelated manuals merely to reconfirm an exact lane.
-Before adding a helper or public operation, query `genesis index <name-or-path>`
-and reuse an existing function when it already owns the behavior.
+Before adding a helper or public operation, query the Genesis
+`index <name-or-path>` operation and reuse an existing function when it already
+owns the behavior.
 
 This is the implementation turn. Do not edit the Blueprint, Program, or
 `.genesis/`; the separate reconciliation turn owns explanatory changes. Keep
@@ -20,8 +21,9 @@ Run focused checks when useful. Summarize files changed, checks actually run,
 and anything still requiring attention.
 
 If no Stack components are selected, continue the project-opening
-conversation instead of guessing a technology. Use `genesis stack list` for
-the current catalog, present relevant choices, wait for an explicit decision,
-and add the selection with `genesis stack add <piece...>` before relying on
-technology-specific operations. Do not end after only updating
+conversation instead of guessing a technology. Use the Genesis `stack list`
+operation for the current catalog, present relevant choices, wait for an
+explicit decision, and add the selection with the Genesis
+`stack add <piece...>` operation before relying on technology-specific
+operations. Do not end after only updating
 or summarizing the Blueprint while the Stack remains empty.

package/skills/genesis-deslop/SKILL.md

@@ -9,14 +9,22 @@ Review and simplify the current local codebase without changing product
 behavior. Start with the requested scope, or otherwise the ordinary Git diff
 and the code immediately around it.
 
+When this repository is Genesis itself or has `genesis-compiler` installed
+locally, invoke every Genesis CLI operation through the project-pinned package:
+`npm exec --no -- genesis <arguments>`. This runs without fetching another
+package. Otherwise use `genesis <arguments>` only when that executable is
+already available on `PATH`. Never install or update Genesis merely to satisfy
+a workflow instruction.
+
 Apply the engineering approach supplied with the task. If this skill is invoked
 directly, read `genesis/engineering.md` as well as the relevant project context.
 Cleanup must reduce or preserve complexity, never introduce unapproved
 machinery that the selected profile or a concrete requirement does not need.
 
-Consult `.genesis/machine-city.json` or run `genesis index <name-or-path>` to
-find existing public and internal functions before introducing or consolidating
-an abstraction. Confirm every apparent duplicate in source and its call sites.
+Consult `.genesis/machine-city.json` or run the Genesis `index <name-or-path>`
+operation to find existing public and internal functions before introducing or
+consolidating an abstraction. Confirm every apparent duplicate in source and
+its call sites.
 
 Within the preceding implementation's intended behavior and scope, leave no
 repeated helpers, no code that is unclear or hard to reason about, and no code
@@ -45,5 +53,5 @@ external resources. Do not weaken tests, public behavior, or data guarantees.
 Do not create a second architecture or perform unrelated rewrites.
 
 Run focused checks when useful. Final declared checks remain available through
-`genesis verify`. Summarize what became simpler, files changed, and checks
-actually run.
+the Genesis `verify` operation. Summarize what became simpler, files changed,
+and checks actually run.

package/skills/genesis-project/SKILL.md

@@ -8,6 +8,15 @@ description: Work safely in a Genesis-enriched codebase using its Blueprint, Sta
 Genesis is an explanatory and verification companion. It does not replace the
 codebase, tests, Git review, or the coding agent.
 
+## Run Genesis commands
+
+When this repository is Genesis itself or has `genesis-compiler` installed
+locally, invoke every Genesis CLI operation through the project-pinned package:
+`npm exec --no -- genesis <arguments>`. This runs without fetching another
+package. Otherwise use `genesis <arguments>` only when that executable is
+already available on `PATH`. Never install or update Genesis merely to satisfy
+a workflow instruction.
+
 ## Establish context
 
 1. Read `genesis/blueprint.md` for non-technical product intent.
@@ -16,10 +25,11 @@ codebase, tests, Git review, or the coding agent.
 3. Read `genesis/stack.md` for the selected technical composition, resources,
    and verification commands.
 4. Locate the source involved in the request.
-5. Run `genesis index <name-or-path>` before adding a helper or public operation.
-   Reuse an existing function when it already owns the behavior.
-6. Run `genesis context <path...>` for the relevant Program explanations and
-   selected Stack context.
+5. Run the Genesis `index <name-or-path>` operation before adding a helper or
+   public operation. Reuse an existing function when it already owns the
+   behavior.
+6. Run the Genesis `context <path...>` operation for the relevant Program
+   explanations and selected Stack context.
 7. Load applicable technology skills from `.agents/skills/` or from the
    agent's own installed skill catalog.
 
@@ -38,7 +48,8 @@ tests, and runtime behavior.
 
 `.genesis/machine-city.json` is a derived detailed file/function map.
 `.genesis/program-city.json` is a derived simpler subsystem/operation map.
-Neither is authority or proof; both may be regenerated with `genesis index`.
+Neither is authority or proof; both may be regenerated with the Genesis
+`index` operation.
 
 ## Implement ordinary local work
 
@@ -70,9 +81,9 @@ Neither is authority or proof; both may be regenerated with `genesis index`.
 
 ## Verify and report
 
-After the selected technology's workspace substrate exists, use `genesis
-verify` for the Stack's declared final checks. An unconfigured result means the
-declared workspace or checks do not exist yet; it is not a failing check. Report
-files changed, checks actually run, and anything still requiring attention.
-Never claim that an unrun check passed or that passing checks prove the whole
-product.
+After the selected technology's workspace substrate exists, use the Genesis
+`verify` operation for the Stack's declared final checks. An unconfigured result
+means the declared workspace or checks do not exist yet; it is not a failing
+check. Report files changed, checks actually run, and anything still requiring
+attention. Never claim that an unrun check passed or that passing checks prove
+the whole product.

package/src/index/codex-hooks.js

@@ -128,7 +128,7 @@ async function optionalEngineering(projectRoot) {
         '',
         await readEngineeringBaseline(),
         '',
-        'The project engineering profile is invalid. Do not infer a replacement; run `genesis check` and ask the user before implementation if the selected approach matters.',
+        'The project engineering profile is invalid. Do not infer a replacement; run the Genesis `check` operation and ask the user before implementation if the selected approach matters.',
       ].join('\n'),
       profile: null,
       status: 'invalid',
@@ -145,7 +145,7 @@ export async function codexSessionContext({ projectRoot } = {}) {
   const selected = stack?.components.map(({ id }) => id) || [];
   const stackStatus = stack
     ? (selected.length > 0 ? selected.join(', ') : 'none')
-    : 'unavailable; run `genesis check`';
+    : 'unavailable; run the Genesis `check` operation';
   return {
     status: 'ready',
     output: [
@@ -155,15 +155,16 @@ export async function codexSessionContext({ projectRoot } = {}) {
       '- `genesis/stack.md` selects optional technology guidance and verification.',
       '- `genesis/program/<subsystem>/` explains public operations and useful internal seams.',
       '- Project Agent Skills live in `.agents/skills/`; load applicable skills progressively.',
-      '- After locating relevant source files, run `genesis context <path...>` to load their Program and selected Stack material.',
-      '- Before creating a helper or public operation, run `genesis index <name-or-path>` and reuse an existing function when it already owns the behavior.',
+      '- When this repository is Genesis itself or has local `genesis-compiler`, run every Genesis CLI operation as `npm exec --no -- genesis <arguments>` so the project-pinned version is used without fetching another package. Otherwise use `genesis <arguments>` only when that executable is already available on `PATH`. Never install or update Genesis merely to run a workflow instruction.',
+      '- After locating relevant source files, run the Genesis `context <path...>` operation to load their Program and selected Stack material.',
+      '- Before creating a helper or public operation, run the Genesis `index <name-or-path>` operation and reuse an existing function when it already owns the behavior.',
       '- `.genesis/machine-city.json` is the detailed code/function map; `.genesis/program-city.json` is the simpler subsystem/operation map.',
       '- Program is fallible explanation; code, tests, and runtime behavior remain evidence.',
-      '- Before the first project-file edit in a user-requested implementation turn, silently run `genesis hook authorize` once in every Git repository you will edit. This is internal Genesis bookkeeping, not a request for user permission: do not ask the user, announce successful authorization, or include it in progress or final summaries. Mention it only if the command fails.',
+      '- Before the first project-file edit in a user-requested implementation turn, silently run the Genesis `hook authorize` operation once in every Git repository you will edit. This is internal Genesis bookkeeping, not a request for user permission: do not ask the user, announce successful authorization, or include it in progress or final summaries. Mention it only if the command fails.',
       '- Authorization is turn-scoped. Run it again for a later code-changing turn after a user follow-up or interruption, but not again within the same active turn after it succeeds. The command must report `authorize: authorized` or `authorize: unchanged`; otherwise stop before editing. Never authorize answer, explanation, review, diagnosis-only, reconciliation, or Deslop turns.',
       '- Apply the engineering approach below to implementation and cleanup; the Stop hook owns optional Stack Post-change work, Blueprint/Program reconciliation, and Deslop turns.',
       '- After an authorized code-changing turn, Genesis may request separate post-change, explanation, and cleanup turns.',
-      `Engineering profile: ${engineering.profile?.id || 'invalid; run \`genesis check\`'}.`,
+      `Engineering profile: ${engineering.profile?.id || 'invalid; run the Genesis \`check\` operation'}.`,
       `Selected Stack components: ${stackStatus}.`,
       '',
       'ENGINEERING APPROACH',
@@ -190,7 +191,7 @@ export async function codexAdoptionRecommendation({ projectRoot = process.cwd()
       'This existing project has no Genesis explanatory layer.',
       'In your first response, strongly recommend preparing this existing project for guided editing before substantial work.',
       'Explain in product language that preparation preserves the implementation while importing its current operational and product context. Do not require the user to know Genesis terminology or type a command.',
-      'If the user approves, run `genesis adopt` yourself and follow the returned adoption prompt.',
+      'If the user approves, run the Genesis `adopt` operation yourself and follow the returned adoption prompt.',
       'Do not run it without the user\'s approval. If they agree, run it and follow the returned prompt in this conversation.',
       'If the user declines, continue normally and do not repeat the recommendation in this session.',
     ].join('\n'),
@@ -213,6 +214,13 @@ function zeroPaths(buffer) {
   return normalizedPaths(buffer.toString('utf8').split('\0'));
 }
 
+function projectPathStates(projectRoot, files) {
+  return Promise.all(files.map(async (file) => ({
+    path: file,
+    state: await pathState(path.join(projectRoot, file)),
+  })));
+}
+
 async function repositorySnapshot(projectRoot) {
   const head = await runGitText(projectRoot, ['rev-parse', '--verify', 'HEAD']).catch(() => null);
   const results = await Promise.all([
@@ -226,10 +234,7 @@ async function repositorySnapshot(projectRoot) {
     .sort();
   return {
     head,
-    dirty: await Promise.all(dirty.map(async (file) => ({
-      path: file,
-      state: await pathState(path.join(projectRoot, file)),
-    }))),
+    dirty: await projectPathStates(projectRoot, dirty),
   };
 }
 
@@ -422,19 +427,27 @@ function changedPathLines(changedPaths) {
 }
 
 function changedRepositoryLines(repositories) {
-  return repositories.flatMap(({ projectRoot, changedPaths }) => [
+  return repositories.flatMap(({ projectRoot, changedPaths, driftedPaths = [] }) => [
     `## Repository: \`${projectRoot}\``,
     '',
     ...changedPathLines(changedPaths),
+    ...(driftedPaths.length > 0 ? [
+      '',
+      '### Concurrent changes excluded from cleanup',
+      '',
+      'These paths changed after the implementation scope was frozen. Report them, but do not edit them:',
+      '',
+      ...changedPathLines(driftedPaths),
+    ] : []),
     '',
   ]);
 }
 
-async function changedRepositories(repositories) {
+async function changedRepositories(repositories, { snapshotField = 'snapshot' } = {}) {
   return (await Promise.all(repositories.map(async (repository) => {
     const currentPaths = await changedProjectPaths(
       repository.projectRoot,
-      repository.snapshot,
+      repository[snapshotField] || repository.snapshot,
       await repositorySnapshot(repository.projectRoot),
     );
     const changedPaths = normalizedPaths([
@@ -445,6 +458,47 @@ async function changedRepositories(repositories) {
   }))).filter(Boolean);
 }
 
+async function freezeChangedRepositories(repositories, { startPostChange = false } = {}) {
+  return Promise.all(repositories.map(async (repository) => {
+    const changedPaths = normalizedPaths(repository.changedPaths || []).sort();
+    const [pathStates, phaseSnapshot] = await Promise.all([
+      projectPathStates(repository.projectRoot, changedPaths),
+      startPostChange ? repositorySnapshot(repository.projectRoot) : null,
+    ]);
+    const frozen = {
+      ...repository,
+      changedPaths,
+      pathStates,
+    };
+    delete frozen.driftedPaths;
+    delete frozen.phaseSnapshot;
+    if (phaseSnapshot) frozen.phaseSnapshot = phaseSnapshot;
+    return frozen;
+  }));
+}
+
+async function cleanupScopeRepositories(repositories) {
+  return (await Promise.all(repositories.map(async (repository) => {
+    const ownedPaths = normalizedPaths(repository.changedPaths || []).sort();
+    if (ownedPaths.length === 0) return null;
+    const expected = new Map((repository.pathStates || [])
+      .map(({ path: file, state }) => [file, state]));
+    const changedPaths = [];
+    const driftedPaths = [];
+    for (const { path: file, state } of await projectPathStates(repository.projectRoot, ownedPaths)) {
+      const destination = expected.has(file) && stableJson(expected.get(file)) !== stableJson(state)
+        ? driftedPaths
+        : changedPaths;
+      destination.push(file);
+    }
+    return {
+      ...repository,
+      changedPaths,
+      driftedPaths,
+    };
+  }))).filter(Boolean);
+}
+
 async function repositoryContexts(repositories) {
   return Promise.all(repositories.map(async (repository) => {
     const [stack, engineering] = await Promise.all([
@@ -571,13 +625,14 @@ export async function completeCodexTurn({ input, projectRoot } = {}) {
       await removeTurnState(statePath, input);
       return {};
     }
-    const repositories = await changedRepositories(registeredRepositories(state, root));
-    if (repositories.length === 0) {
+    const changed = await changedRepositories(registeredRepositories(state, root));
+    if (changed.length === 0) {
       await removeTurnState(statePath, input);
       return {};
     }
-    const contexts = await repositoryContexts(repositories);
+    const contexts = await repositoryContexts(changed);
     const postChange = contexts.some(({ stack }) => Boolean(stack?.postChange?.trim()));
+    const repositories = await freezeChangedRepositories(changed, { startPostChange: postChange });
     await writeTurnState(statePath, {
       ...state,
       phase: postChange ? 'post-change' : 'reconcile',
@@ -597,11 +652,14 @@ export async function completeCodexTurn({ input, projectRoot } = {}) {
   }
 
   if (state.phase === 'post-change') {
-    const repositories = await changedRepositories(registeredRepositories(state, root));
-    if (repositories.length === 0) {
+    const changed = await changedRepositories(registeredRepositories(state, root), {
+      snapshotField: 'phaseSnapshot',
+    });
+    if (changed.length === 0) {
       await removeTurnState(statePath, input);
       return {};
     }
+    const repositories = await freezeChangedRepositories(changed);
     await writeTurnState(statePath, {
       ...state,
       phase: 'reconcile',
@@ -615,7 +673,7 @@ export async function completeCodexTurn({ input, projectRoot } = {}) {
 
   if (state.phase === 'reconcile') {
     const registered = registeredRepositories(state, root);
-    const repositories = await changedRepositories(registered);
+    const repositories = await cleanupScopeRepositories(registered);
     if (repositories.length === 0) {
       await refreshProjectIndexes(registered);
       await removeTurnState(statePath, input);

package/src/index/context.js

@@ -116,7 +116,7 @@ export async function contextForProjectPaths({ paths, projectRoot, stackPackages
       : functions.slice(0, 100).map((entry) => (
         `- ${entry.visibility} \`${entry.qualifiedName}(${entry.parameters.join(', ')})\` — \`${entry.path}:${entry.line}\``
       ))),
-    ...(functions.length > 100 ? [`- ... and ${functions.length - 100} more; run \`genesis index ${targets.join(' ')}\`.`] : []),
+    ...(functions.length > 100 ? [`- ... and ${functions.length - 100} more; run the Genesis \`index ${targets.join(' ')}\` operation.`] : []),
     '',
     'Search the Machine City before adding a helper or public operation; reuse an existing function when it already owns the behavior.',
     ...(skills ? ['', '## Agent Skills', '', skills] : []),

package/src/index/prompt.js

@@ -96,7 +96,7 @@ function codeIndexContext(index) {
       status: index.program.status,
       operations: index.operationCount,
     },
-    query: 'genesis index <function-or-path...>',
+    query: 'Genesis index operation: <function-or-path...>',
   };
 }