genesis-compiler 1.2.17 → 1.2.19

package/src/index/codex-hooks.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 
 import { readInstalledAsset } from './assets.js';
 import { buildProjectIndex } from './code-index.js';
+import { readEngineering, readEngineeringBaseline } from './engineering.js';
 import { GenesisError } from './errors.js';
 import { gitContext } from './git.js';
 import { isProjectContentPath } from './paths.js';
@@ -115,9 +116,30 @@ async function optionalStack(projectRoot) {
   try { return await readStack(projectRoot); } catch { return null; }
 }
 
+async function optionalEngineering(projectRoot) {
+  try {
+    return await readEngineering(projectRoot);
+  } catch {
+    return {
+      guidance: [
+        '## Universal complexity gate',
+        '',
+        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.',
+      ].join('\n'),
+      profile: null,
+      status: 'invalid',
+    };
+  }
+}
+
 export async function codexSessionContext({ projectRoot } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
-  const stack = await optionalStack(root);
+  const [stack, engineering] = await Promise.all([
+    optionalStack(root),
+    optionalEngineering(root),
+  ]);
   const selected = stack?.components.map(({ id }) => id) || [];
   const stackStatus = stack
     ? (selected.length > 0 ? selected.join(', ') : 'none')
@@ -127,6 +149,7 @@ export async function codexSessionContext({ projectRoot } = {}) {
     output: [
       'This is a Genesis-enriched project.',
       '- `genesis/blueprint.md` describes non-technical product intent.',
+      '- `genesis/engineering.md` selects the project engineering approach and any project-specific requirements.',
       '- `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.',
@@ -134,9 +157,15 @@ export async function codexSessionContext({ projectRoot } = {}) {
       '- Before creating a helper or public operation, run `genesis index <name-or-path>` 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.',
-      '- Keep implementation focused; the Stop hook owns optional Stack Post-change work, Blueprint/Program reconciliation, and Deslop turns.',
-      '- After a code-changing turn, Genesis may request separate post-change, explanation, cleanup, and final-summary turns.',
+      '- Before changing project files for a user-requested implementation, run `genesis hook authorize`. Never authorize answer, explanation, review, or diagnosis-only 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\`'}.`,
       `Selected Stack components: ${stackStatus}.`,
+      '',
+      'ENGINEERING APPROACH',
+      '',
+      engineering.guidance,
     ].join('\n'),
   };
 }
@@ -222,6 +251,7 @@ export async function recordCodexTurn({ input, projectRoot } = {}) {
     schemaVersion: HOOK_STATE_SCHEMA_VERSION,
     turnId: hookId(input, 'turn_id'),
     phase: 'implementation',
+    implementationAuthorized: false,
     snapshot: await repositorySnapshot(root),
   };
   await writeTurnState(statePath, state);
@@ -235,6 +265,27 @@ async function readTurnState(statePath) {
   }
 }
 
+export async function authorizeCodexTurn({
+  projectRoot = process.cwd(),
+  sessionId = process.env.CODEX_SESSION_ID,
+} = {}) {
+  if (!sessionId) {
+    throw new GenesisError(
+      'CODEX_SESSION_ID_MISSING',
+      'genesis hook authorize requires the current Codex session.',
+    );
+  }
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const statePath = await hookStatePath(root, { session_id: sessionId });
+  const state = await readTurnState(statePath);
+  if (!state || state.schemaVersion !== HOOK_STATE_SCHEMA_VERSION || state.phase !== 'implementation') {
+    return { status: 'not-applicable' };
+  }
+  if (state.implementationAuthorized === true) return { status: 'unchanged' };
+  await writeTurnState(statePath, { ...state, implementationAuthorized: true });
+  return { status: 'authorized' };
+}
+
 async function committedPaths(projectRoot, before, after) {
   if (before === after) return [];
   if (!after) return ['repository history changed'];
@@ -279,9 +330,10 @@ function changedPathLines(changedPaths) {
 }
 
 async function reconciliationContinuation(projectRoot, changedPaths) {
-  const [instructions, stack] = await Promise.all([
+  const [instructions, stack, engineering] = await Promise.all([
     readInstalledAsset('reconcile'),
     optionalStack(projectRoot),
+    optionalEngineering(projectRoot),
   ]);
   return [
     'This is the automatic Genesis explanation turn for the preceding implementation turn.',
@@ -292,11 +344,15 @@ async function reconciliationContinuation(projectRoot, changedPaths) {
     ...changedPathLines(changedPaths),
     '',
     instructions.trim(),
+    '',
+    'ENGINEERING APPROACH',
+    '',
+    engineering.guidance,
     ...(stack?.guidance ? ['', 'SELECTED STACK GUIDANCE', '', stack.guidance] : []),
   ].join('\n');
 }
 
-function postChangeContinuation(changedPaths, stack) {
+function postChangeContinuation(changedPaths, stack, engineering) {
   return [
     'This is the one automatic Stack Post-change turn for the preceding implementation.',
     'Use the same conversation context and the Git-visible changes below.',
@@ -310,14 +366,19 @@ function postChangeContinuation(changedPaths, stack) {
     'COMPOSED STACK POST-CHANGE WORK',
     '',
     stack.postChange,
+    '',
+    'ENGINEERING APPROACH',
+    '',
+    engineering.guidance,
     ...(stack.guidance ? ['', 'SELECTED STACK GUIDANCE', '', stack.guidance] : []),
   ].join('\n');
 }
 
 async function deslopContinuation(projectRoot, changedPaths) {
-  const [instructions, stack] = await Promise.all([
+  const [instructions, stack, engineering] = await Promise.all([
     readInstalledAsset('deslop'),
     optionalStack(projectRoot),
+    optionalEngineering(projectRoot),
   ]);
   return [
     'This is the final automatic Genesis Deslop turn for the preceding implementation.',
@@ -328,6 +389,10 @@ async function deslopContinuation(projectRoot, changedPaths) {
     ...changedPathLines(changedPaths),
     '',
     instructions.trim(),
+    '',
+    'ENGINEERING APPROACH',
+    '',
+    engineering.guidance,
     ...(stack?.guidance ? ['', 'SELECTED STACK GUIDANCE', '', stack.guidance] : []),
     ...(stack?.deslop ? ['', 'SELECTED STACK CLEANUP GUIDANCE', '', stack.deslop] : []),
     '',
@@ -340,16 +405,17 @@ async function deslopContinuation(projectRoot, changedPaths) {
   ].join('\n');
 }
 
-async function finalSummaryContinuation() {
-  return (await readInstalledAsset('finalSummary')).trim();
-}
-
 export async function completeCodexTurn({ input, projectRoot } = {}) {
   const root = (await gitContext(projectRoot || input?.cwd)).repositoryRoot;
   const statePath = await hookStatePath(root, input);
   const state = await readTurnState(statePath);
   if (!state || state.schemaVersion !== HOOK_STATE_SCHEMA_VERSION) return {};
 
+  if (state.implementationAuthorized !== true) {
+    await rm(statePath, { force: true });
+    return {};
+  }
+
   if (state.phase === 'implementation') {
     if (input?.stop_hook_active === true || state.turnId !== hookId(input, 'turn_id')) {
       await rm(statePath, { force: true });
@@ -360,7 +426,10 @@ export async function completeCodexTurn({ input, projectRoot } = {}) {
       await rm(statePath, { force: true });
       return {};
     }
-    const stack = await optionalStack(root);
+    const [stack, engineering] = await Promise.all([
+      optionalStack(root),
+      optionalEngineering(root),
+    ]);
     const postChange = Boolean(stack?.postChange?.trim());
     await writeTurnState(statePath, {
       ...state,
@@ -370,7 +439,7 @@ export async function completeCodexTurn({ input, projectRoot } = {}) {
     return {
       decision: 'block',
       reason: postChange
-        ? postChangeContinuation(changedPaths, stack)
+        ? postChangeContinuation(changedPaths, stack, engineering)
         : await reconciliationContinuation(root, changedPaths),
     };
   }
@@ -420,14 +489,8 @@ export async function completeCodexTurn({ input, projectRoot } = {}) {
 
   if (state.phase === 'deslop') {
     await refreshProjectIndex(root);
-    await writeTurnState(statePath, {
-      ...state,
-      phase: 'summary',
-    });
-    return {
-      decision: 'block',
-      reason: await finalSummaryContinuation(),
-    };
+    await rm(statePath, { force: true });
+    return {};
   }
 
   await rm(statePath, { force: true });

package/src/index/context.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { inspectProjectSkills, renderAgentSkillCatalog } from './agent-skills.js';
 import { buildProjectIndex } from './code-index.js';
 import { asDiagnostic, GenesisError } from './errors.js';
+import { readEngineering } from './engineering.js';
 import { gitContext } from './git.js';
 import { inspectProgram } from './program.js';
 import { readStack } from './stack.js';
@@ -56,13 +57,14 @@ export async function contextForProjectPaths({ paths, projectRoot, stackPackages
   const location = await gitContext(projectRoot);
   const root = location.repositoryRoot;
   const targets = [...new Set(paths.map((value) => projectPath(root, location.workingDirectory, value)))];
-  const [program, stack] = await Promise.all([
+  const [program, stack, engineering] = await Promise.all([
     inspectProgram(root).catch((error) => ({
       status: 'invalid',
       modules: [],
       diagnostic: asDiagnostic(error),
     })),
     readStack(root, { stackPackages }),
+    readEngineering(root),
   ]);
   const modules = program.modules.filter((module) => targets.some((target) => citesTarget(module, target)));
   const moduleSources = await Promise.all(modules.map(async (module) => ({
@@ -98,6 +100,12 @@ export async function contextForProjectPaths({ paths, projectRoot, stackPackages
     '## Relevant Program',
     '',
     ...programDetails,
+    '## Engineering approach',
+    '',
+    `Profile: \`${engineering.profile.id}\` — ${engineering.profile.description}`,
+    '',
+    engineering.guidance,
+    '',
     ...stackSummary(stack),
     ...stackGuidance(stack),
     '',
@@ -125,6 +133,7 @@ export async function contextForProjectPaths({ paths, projectRoot, stackPackages
     paths: targets,
     modules: moduleSources.map(({ source: _source, ...module }) => module),
     components: stack.components.map(({ id }) => id),
+    engineeringProfile: engineering.profile.id,
     verificationCommands: stack.verificationCommands.map(({ label, argv }) => ({ label, argv })),
     warnings: [
       ...(program.diagnostic ? [program.diagnostic] : []),

package/src/index/contracts.js

@@ -1,5 +1,6 @@
 export const GENESIS_CONTRACTS = Object.freeze({
   derivedArtifacts: 'genesis.derived-artifacts.v1',
+  engineering: 'genesis.engineering.v1',
   environment: 'genesis.environment.v2',
   stackSection: 'genesis.stack-section.v1',
   verification: 'genesis.verification.v1',

package/src/index/engineering.js

@@ -0,0 +1,274 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { GENESIS_CONTRACTS } from './contracts.js';
+import { GenesisError } from './errors.js';
+import { gitContext } from './git.js';
+import { ENGINEERING_PATH } from './paths.js';
+import { normalizeSource, writeFileAtomic } from './utils.js';
+
+const PROFILE_ID_PATTERN = /^[a-z][a-z0-9-]*\.v[1-9][0-9]*$/u;
+const PROFILE_IDS = Object.freeze(['focused.v1', 'durable.v1', 'high-assurance.v1']);
+const PROFILE_ASSETS = new Map(PROFILE_IDS.map((id) => [
+  id,
+  new URL(`../../profiles/engineering/${id}.md`, import.meta.url),
+]));
+const BASELINE_ASSET = new URL('../../profiles/engineering/baseline.md', import.meta.url);
+
+export const DEFAULT_ENGINEERING_PROFILE_ID = 'focused.v1';
+export const ENGINEERING_SKELETON_SOURCE = `# Engineering approach
+
+## Profile
+
+- \`${DEFAULT_ENGINEERING_PROFILE_ID}\`
+
+## Project requirements
+
+- Nothing.
+`;
+
+function normalizeProfileId(value) {
+  const id = String(value ?? '').trim();
+  if (!PROFILE_ID_PATTERN.test(id)) {
+    throw new GenesisError(
+      'ENGINEERING_PROFILE_INVALID',
+      'Engineering profile ids use a lowercase name followed by a version, such as `focused.v1`.',
+      { profile: value },
+    );
+  }
+  return id;
+}
+
+function sections(source, { title, sourcePath }) {
+  const lines = normalizeSource(source).split('\n');
+  if (lines.filter((line) => line.trim() === title).length !== 1) {
+    throw new GenesisError('ENGINEERING_INVALID', `${sourcePath} needs exactly one \`${title}\` title.`);
+  }
+  const result = new Map();
+  let current = null;
+  for (const line of lines) {
+    const heading = line.match(/^##\s+(.+?)\s*$/u);
+    if (heading) {
+      if (result.has(heading[1])) {
+        throw new GenesisError('ENGINEERING_INVALID', `Duplicate engineering section: ${heading[1]}.`, {
+          path: sourcePath,
+        });
+      }
+      current = [];
+      result.set(heading[1], current);
+    } else if (current) {
+      current.push(line);
+    } else if (line.trim() && line.trim() !== title) {
+      throw new GenesisError('ENGINEERING_INVALID', `${sourcePath} contains content outside an engineering section.`);
+    }
+  }
+  return result;
+}
+
+function sectionText(all, name) {
+  return (all.get(name) || []).join('\n').trim();
+}
+
+function parseProfileSource(source, { id }) {
+  const normalized = normalizeSource(source);
+  const titleMatch = normalized.match(/^# ([^\r\n]+)[ \t]*$/mu);
+  if (!titleMatch || normalized.match(/^# [^\r\n]+[ \t]*$/gmu)?.length !== 1) {
+    throw new GenesisError('ENGINEERING_PROFILE_INVALID', `Engineering profile ${id} needs one title.`);
+  }
+  const all = sections(normalized, {
+    sourcePath: `profiles/engineering/${id}.md`,
+    title: titleMatch[0].trim(),
+  });
+  const unknown = [...all.keys()].filter((name) => !['Description', 'Guidance'].includes(name));
+  const description = sectionText(all, 'Description');
+  const guidance = sectionText(all, 'Guidance');
+  if (unknown.length > 0 || !description || !guidance) {
+    throw new GenesisError(
+      'ENGINEERING_PROFILE_INVALID',
+      `Engineering profile ${id} needs only non-empty Description and Guidance sections.`,
+      { profile: id },
+    );
+  }
+  return Object.freeze({ id, name: titleMatch[1].trim(), description, guidance });
+}
+
+export async function engineeringProfile(value) {
+  const id = normalizeProfileId(value);
+  const location = PROFILE_ASSETS.get(id);
+  if (!location) {
+    throw new GenesisError(
+      'ENGINEERING_PROFILE_UNKNOWN',
+      `No installed engineering profile exists for ${id}.`,
+      { profile: id },
+    );
+  }
+  return parseProfileSource(await readFile(location, 'utf8'), { id });
+}
+
+export async function readEngineeringBaseline() {
+  const source = normalizeSource(await readFile(BASELINE_ASSET, 'utf8')).trim();
+  if (!/^# Engineering baseline[ \t]*$/mu.test(source)) {
+    throw new GenesisError('ENGINEERING_PROFILE_INVALID', 'The installed engineering baseline is invalid.');
+  }
+  return source.replace(/^# Engineering baseline[ \t]*\n?/mu, '').trim();
+}
+
+export function parseEngineeringSource(source) {
+  const normalized = normalizeSource(source);
+  const all = sections(normalized, {
+    sourcePath: ENGINEERING_PATH,
+    title: '# Engineering approach',
+  });
+  const unknown = [...all.keys()].filter((name) => !['Profile', 'Project requirements'].includes(name));
+  if (unknown.length > 0 || !all.has('Profile') || !all.has('Project requirements')) {
+    throw new GenesisError(
+      'ENGINEERING_INVALID',
+      `${ENGINEERING_PATH} needs only Profile and Project requirements sections.`,
+      { path: ENGINEERING_PATH },
+    );
+  }
+  const profileLines = (all.get('Profile') || []).filter((line) => line.trim());
+  const match = profileLines.length === 1
+    ? profileLines[0].trim().match(/^- `([^`]+)`$/u)
+    : null;
+  if (!match) {
+    throw new GenesisError(
+      'ENGINEERING_INVALID',
+      'The engineering Profile must be exactly one bullet containing a backticked profile id.',
+      { path: ENGINEERING_PATH },
+    );
+  }
+  const requirementsSource = sectionText(all, 'Project requirements');
+  if (!requirementsSource) {
+    throw new GenesisError(
+      'ENGINEERING_INVALID',
+      'Project requirements must contain requirements or `- Nothing.`.',
+      { path: ENGINEERING_PATH },
+    );
+  }
+  if (Buffer.byteLength(requirementsSource, 'utf8') > 64 * 1024) {
+    throw new GenesisError('ENGINEERING_INVALID', 'Project engineering requirements exceed 64 KiB.', {
+      path: ENGINEERING_PATH,
+    });
+  }
+  return {
+    path: ENGINEERING_PATH,
+    profileId: normalizeProfileId(match[1]),
+    requirements: requirementsSource === '- Nothing.' ? '' : requirementsSource,
+    source: normalized,
+  };
+}
+
+function renderEngineering({ profileId, requirements = '' }) {
+  return [
+    '# Engineering approach',
+    '',
+    '## Profile',
+    '',
+    `- \`${profileId}\``,
+    '',
+    '## Project requirements',
+    '',
+    requirements.trim() || '- Nothing.',
+    '',
+  ].join('\n');
+}
+
+function effectiveGuidance({ baseline, profile, requirements }) {
+  return [
+    '## Universal complexity gate',
+    '',
+    baseline,
+    '',
+    `## Selected profile: ${profile.name} (\`${profile.id}\`)`,
+    '',
+    profile.guidance,
+    ...(requirements ? [
+      '',
+      '## Project requirements',
+      '',
+      requirements,
+    ] : []),
+  ].join('\n');
+}
+
+export async function readEngineering(projectRoot) {
+  const location = path.join(projectRoot, ENGINEERING_PATH);
+  let parsed;
+  let status = 'configured';
+  try {
+    parsed = parseEngineeringSource(await readFile(location, 'utf8'));
+  } catch (error) {
+    if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) throw error;
+    parsed = parseEngineeringSource(ENGINEERING_SKELETON_SOURCE);
+    status = 'defaulted';
+  }
+  const [baseline, profile] = await Promise.all([
+    readEngineeringBaseline(),
+    engineeringProfile(parsed.profileId),
+  ]);
+  return {
+    contract: GENESIS_CONTRACTS.engineering,
+    path: ENGINEERING_PATH,
+    status,
+    profile,
+    requirements: parsed.requirements,
+    source: status === 'configured' ? parsed.source : null,
+    guidance: effectiveGuidance({ baseline, profile, requirements: parsed.requirements }),
+  };
+}
+
+export function engineeringPromptContext(engineering) {
+  return {
+    path: engineering.path,
+    status: engineering.status,
+    profile: {
+      id: engineering.profile.id,
+      name: engineering.profile.name,
+      description: engineering.profile.description,
+    },
+    requirements: engineering.requirements || 'Nothing.',
+  };
+}
+
+export function listEngineeringProfileCatalog() {
+  return Promise.all(PROFILE_IDS.map(engineeringProfile));
+}
+
+export async function inspectProjectEngineering({ projectRoot } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const [engineering, profiles] = await Promise.all([
+    readEngineering(root),
+    listEngineeringProfileCatalog(),
+  ]);
+  return {
+    contract: engineering.contract,
+    path: engineering.path,
+    status: engineering.status,
+    profile: engineering.profile,
+    profiles,
+    requirements: engineering.requirements,
+    guidance: engineering.guidance,
+  };
+}
+
+export async function selectEngineeringProfile({ profile, projectRoot } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const selected = await engineeringProfile(profile);
+  const current = await readEngineering(root);
+  const rendered = renderEngineering({
+    profileId: selected.id,
+    requirements: current.requirements,
+  });
+  const changed = current.source !== rendered;
+  if (changed) await writeFileAtomic(path.join(root, ENGINEERING_PATH), rendered);
+  return {
+    contract: GENESIS_CONTRACTS.engineering,
+    status: changed ? 'updated' : 'unchanged',
+    summary: changed
+      ? `Selected engineering profile: ${selected.id}.`
+      : `Engineering profile ${selected.id} is already selected.`,
+    profile: selected,
+    changedFiles: changed ? [ENGINEERING_PATH] : [],
+  };
+}

package/src/index/init.js

@@ -4,8 +4,9 @@ import path from 'node:path';
 import { syncProjectSkills } from './agent-skills.js';
 import { BLUEPRINT_SKELETON_SOURCE } from './blueprint.js';
 import { installCodexHooks } from './codex-hooks.js';
+import { ENGINEERING_SKELETON_SOURCE } from './engineering.js';
 import { gitContext } from './git.js';
-import { BLUEPRINT_PATH, PROGRAM_ROOT, STACK_PATH } from './paths.js';
+import { BLUEPRINT_PATH, ENGINEERING_PATH, PROGRAM_ROOT, STACK_PATH } from './paths.js';
 import { EMPTY_STACK_SOURCE, readStack } from './stack.js';
 
 async function createIfMissing(projectRoot, relativePath, source) {
@@ -24,6 +25,7 @@ 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, ENGINEERING_PATH, ENGINEERING_SKELETON_SOURCE),
     createIfMissing(root, STACK_PATH, EMPTY_STACK_SOURCE),
   ])).filter(Boolean);
   await mkdir(path.join(root, PROGRAM_ROOT), { recursive: true });
@@ -42,6 +44,7 @@ export async function initializeProject({ projectRoot, stackPackages = [] } = {}
       'Open Codex and use /hooks to review and trust the project hooks.',
       'Genesis workflow skills are available in .agents/skills/.',
       'Describe product intent in genesis/blueprint.md.',
+      'Choose the project engineering approach with genesis engineering set <profile>.',
       'Stack components are optional; add them with genesis stack add <piece...>.',
     ].join(' '),
   };

package/src/index/paths.js

@@ -1,4 +1,5 @@
 export const BLUEPRINT_PATH = 'genesis/blueprint.md';
+export const ENGINEERING_PATH = 'genesis/engineering.md';
 export const STACK_PATH = 'genesis/stack.md';
 export const PROGRAM_ROOT = 'genesis/program';
 export const VERIFICATION_PATH = '.genesis/verification.json';