@thebackstoryis/engineering-with-ai 0.2.9

package/src/runtime/execution-leases.mjs

@@ -0,0 +1,299 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { deriveExecutionState } from '../execution-state.mjs';
+import { dependencyRequirementBlockers } from '../intent-dependencies.mjs';
+import { validateTaskReport } from '../task-graph.mjs';
+import { projectPaths } from '../paths.mjs';
+import { openRuntimeDatabase } from './database.mjs';
+import { syncWorkItems } from './work.mjs';
+
+const defaultDurationMs = 15 * 60 * 1000;
+const maximumDurationMs = 24 * 60 * 60 * 1000;
+
+function required(value, label) {
+  const normalized = String(value ?? '').trim();
+  if (!normalized) throw new Error(`Execution lease requires ${label}.`);
+  return normalized;
+}
+
+function duration(value) {
+  const milliseconds = Number(value ?? defaultDurationMs);
+  if (!Number.isInteger(milliseconds) || milliseconds < 1_000 || milliseconds > maximumDurationMs) {
+    throw new Error(`Execution lease duration must be between 1000 and ${maximumDurationMs} milliseconds.`);
+  }
+  return milliseconds;
+}
+
+function timestamp(value = new Date()) {
+  return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
+}
+
+function rowToLease(row) {
+  return {
+    id: row.id,
+    workItemId: row.work_item_id,
+    taskId: row.task_id,
+    ownerId: row.owner_id,
+    tool: row.tool,
+    runId: row.run_id,
+    token: row.token,
+    status: row.status,
+    acquiredAt: row.acquired_at,
+    heartbeatAt: row.heartbeat_at,
+    expiresAt: row.expires_at,
+    releasedAt: row.released_at,
+    outcome: row.outcome,
+  };
+}
+
+function rowToIntent(row) {
+  return {
+    id: row.id,
+    slug: row.slug,
+    domain: row.domain,
+    title: row.title,
+    status: row.status,
+    deliveryStatus: row.delivery_status,
+    currentPhase: row.current_phase,
+    deliveryStatePath: row.delivery_state_path,
+    path: row.path,
+    relationships: JSON.parse(row.relationships_json || '[]'),
+  };
+}
+
+function findWorkItem(database, reference) {
+  const direct = database.prepare('SELECT * FROM work_items WHERE id = ?').get(reference);
+  if (direct) return direct;
+  const matches = database.prepare('SELECT * FROM work_items WHERE slug = ? ORDER BY id LIMIT 2').all(reference);
+  if (matches.length > 1) throw new Error(`Ambiguous work item slug: ${reference}`);
+  if (!matches.length) throw new Error(`Unknown work item: ${reference}`);
+  return matches[0];
+}
+
+function expireStale(database, at) {
+  database.prepare(`
+    UPDATE execution_leases
+    SET status = 'expired', released_at = ?, outcome = CASE WHEN outcome = '' THEN 'lease-expired' ELSE outcome END
+    WHERE status = 'active' AND expires_at <= ?
+  `).run(at, at);
+}
+
+function executionReadiness(projectRoot, database, item, taskId) {
+  const intentCatalog = new Map(database.prepare('SELECT * FROM intents ORDER BY id').all().map((row) => {
+    const intent = rowToIntent(row);
+    return [intent.id, intent];
+  }));
+  const intent = intentCatalog.get(item.intent_id);
+  if (!intent) throw new Error(`Cannot lease ${taskId}: intent projection ${item.intent_id} does not exist.`);
+  const leases = database.prepare(`
+    SELECT id, work_item_id, task_id, owner_id, tool, run_id, status,
+      acquired_at, heartbeat_at, expires_at, released_at, outcome
+    FROM execution_leases WHERE work_item_id = ? AND status = 'active' AND expires_at > ?
+  `).all(item.id, new Date().toISOString()).map((lease) => ({
+    id: lease.id,
+    workItemId: lease.work_item_id,
+    taskId: lease.task_id,
+    ownerId: lease.owner_id,
+    tool: lease.tool,
+    runId: lease.run_id,
+    status: lease.status,
+    acquiredAt: lease.acquired_at,
+    heartbeatAt: lease.heartbeat_at,
+    expiresAt: lease.expires_at,
+    releasedAt: lease.released_at,
+    outcome: lease.outcome,
+  }));
+  const execution = deriveExecutionState(projectRoot, intent, { leases, intentCatalog });
+  if (!execution.valid) {
+    const reasons = execution.blockers.map((blocker) => blocker.message).join('; ');
+    throw new Error(`Cannot lease ${taskId}: delivery evidence is invalid or inconsistent${reasons ? `: ${reasons}` : '.'}`);
+  }
+  const dependencyBlockers = dependencyRequirementBlockers(projectRoot, intent, intentCatalog, 'build');
+  if (dependencyBlockers.length) {
+    throw new Error(`Cannot lease ${taskId}: ${dependencyBlockers.map((blocker) => blocker.message).join('; ')}`);
+  }
+  const task = execution.tasks.tasks.find((candidate) => candidate.id === taskId);
+  if (!task) throw new Error(`Cannot lease ${taskId}: task does not exist in task-graph.json.`);
+  return { execution, task };
+}
+
+function withDatabase(projectRoot, operation) {
+  const database = openRuntimeDatabase(projectRoot);
+  try {
+    syncWorkItems(projectRoot, database);
+    return operation(database);
+  } finally {
+    database.close();
+  }
+}
+
+export function acquireExecutionLease(projectRoot, reference, input = {}) {
+  const taskId = required(input.taskId, 'taskId');
+  const ownerId = required(input.ownerId, 'ownerId');
+  const tool = String(input.tool ?? '').trim();
+  const runId = required(input.runId, 'runId');
+  const at = timestamp(input.now);
+  const expiresAt = timestamp(new Date(new Date(at).getTime() + duration(input.durationMs)));
+
+  return withDatabase(projectRoot, (database) => {
+    const item = findWorkItem(database, reference);
+    const readiness = executionReadiness(projectRoot, database, item, taskId);
+    database.exec('BEGIN IMMEDIATE;');
+    try {
+      expireStale(database, at);
+      const existing = database.prepare(`
+        SELECT * FROM execution_leases WHERE work_item_id = ? AND task_id = ? AND status = 'active'
+      `).get(item.id, taskId);
+      if (existing) {
+        if (existing.owner_id !== ownerId || existing.run_id !== runId || existing.tool !== tool) {
+          throw new Error(`${taskId} is already leased by ${existing.owner_id} (${existing.tool || 'unknown tool'}).`);
+        }
+        database.prepare(`
+          UPDATE execution_leases SET heartbeat_at = ?, expires_at = ? WHERE id = ?
+        `).run(at, expiresAt, existing.id);
+        const renewed = database.prepare('SELECT * FROM execution_leases WHERE id = ?').get(existing.id);
+        database.exec('COMMIT;');
+        return rowToLease(renewed);
+      }
+
+      if (!readiness.execution.actions.acquireTask.permitted || readiness.task.status !== 'ready') {
+        const reason = readiness.execution.actions.acquireTask.blockers[0]?.message ?? `task state is ${readiness.task.status}`;
+        throw new Error(`Cannot lease ${taskId}: ${reason}`);
+      }
+
+      const activeCount = database.prepare(`
+        SELECT COUNT(*) AS count FROM execution_leases WHERE work_item_id = ? AND status = 'active'
+      `).get(item.id).count;
+      if (activeCount >= readiness.execution.tasks.maxParallelTasks) {
+        throw new Error(`Cannot lease ${taskId}: the task graph allows at most ${readiness.execution.tasks.maxParallelTasks} parallel task(s).`);
+      }
+
+      const id = randomUUID();
+      const token = randomUUID();
+      database.prepare(`
+        INSERT INTO execution_leases (
+          id, work_item_id, task_id, owner_id, tool, run_id, token,
+          status, acquired_at, heartbeat_at, expires_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, 'active', ?, ?, ?)
+      `).run(id, item.id, taskId, ownerId, tool, runId, token, at, at, expiresAt);
+      const created = database.prepare('SELECT * FROM execution_leases WHERE id = ?').get(id);
+      database.exec('COMMIT;');
+      return rowToLease(created);
+    } catch (error) {
+      database.exec('ROLLBACK;');
+      throw error;
+    }
+  });
+}
+
+export function heartbeatExecutionLease(projectRoot, leaseId, input = {}) {
+  const token = required(input.token, 'token');
+  const at = timestamp(input.now);
+  const expiresAt = timestamp(new Date(new Date(at).getTime() + duration(input.durationMs)));
+  return withDatabase(projectRoot, (database) => {
+    database.exec('BEGIN IMMEDIATE;');
+    try {
+      expireStale(database, at);
+      const lease = database.prepare('SELECT * FROM execution_leases WHERE id = ?').get(leaseId);
+      if (!lease) throw new Error(`Unknown execution lease: ${leaseId}`);
+      if (lease.token !== token) throw new Error('Execution lease token does not match.');
+      if (lease.status !== 'active') throw new Error(`Execution lease is ${lease.status}, not active.`);
+      database.prepare('UPDATE execution_leases SET heartbeat_at = ?, expires_at = ? WHERE id = ?')
+        .run(at, expiresAt, leaseId);
+      const updated = database.prepare('SELECT * FROM execution_leases WHERE id = ?').get(leaseId);
+      database.exec('COMMIT;');
+      return rowToLease(updated);
+    } catch (error) {
+      database.exec('ROLLBACK;');
+      throw error;
+    }
+  });
+}
+
+export function releaseExecutionLease(projectRoot, leaseId, input = {}) {
+  const token = required(input.token, 'token');
+  const outcome = String(input.outcome ?? 'released').trim();
+  const at = timestamp(input.now);
+  return withDatabase(projectRoot, (database) => {
+    database.exec('BEGIN IMMEDIATE;');
+    try {
+      expireStale(database, at);
+      const lease = database.prepare('SELECT * FROM execution_leases WHERE id = ?').get(leaseId);
+      if (!lease) throw new Error(`Unknown execution lease: ${leaseId}`);
+      if (lease.token !== token) throw new Error('Execution lease token does not match.');
+      if (lease.status !== 'active') throw new Error(`Execution lease is ${lease.status}, not active.`);
+      if (outcome === 'completed') {
+        const item = database.prepare('SELECT slug FROM work_items WHERE id = ?').get(lease.work_item_id);
+        const deliveryRoot = resolve(projectPaths(projectRoot).buildRoot, item.slug);
+        const graph = JSON.parse(readFileSync(resolve(deliveryRoot, 'task-graph.json'), 'utf8'));
+        const task = graph.tasks?.find((candidate) => candidate.id === lease.task_id);
+        if (!task) throw new Error(`Cannot complete ${lease.task_id}: task is missing from task-graph.json.`);
+        const report = validateTaskReport(deliveryRoot, task);
+        if (report.status !== 'complete') {
+          throw new Error(`Cannot complete ${lease.task_id}: task report is incomplete (${report.errors.join('; ')}).`);
+        }
+      }
+      database.prepare(`
+        UPDATE execution_leases SET status = 'released', released_at = ?, outcome = ? WHERE id = ?
+      `).run(at, outcome, leaseId);
+      const released = database.prepare('SELECT * FROM execution_leases WHERE id = ?').get(leaseId);
+      database.exec('COMMIT;');
+      return rowToLease(released);
+    } catch (error) {
+      database.exec('ROLLBACK;');
+      throw error;
+    }
+  });
+}
+
+export function listExecutionLeases(projectRoot, options = {}) {
+  const at = timestamp(options.now);
+  return withDatabase(projectRoot, (database) => {
+    database.exec('BEGIN IMMEDIATE;');
+    try {
+      expireStale(database, at);
+      const rows = database.prepare(`
+        SELECT * FROM execution_leases
+        WHERE (? = 0 OR status = 'active')
+          AND (? = '' OR work_item_id = ?)
+        ORDER BY acquired_at DESC
+      `).all(options.activeOnly === true ? 1 : 0, options.workItemId ?? '', options.workItemId ?? '');
+      database.exec('COMMIT;');
+      return rows.map((row) => {
+        const lease = rowToLease(row);
+        if (options.includeTokens !== true) delete lease.token;
+        return lease;
+      });
+    } catch (error) {
+      database.exec('ROLLBACK;');
+      throw error;
+    }
+  });
+}
+
+// Conductor recovery deliberately does not require the private capability token: it is
+// scoped to one durable run ID and can only abandon leases, never complete work.
+export function abandonExecutionLeasesForRun(projectRoot, runId, input = {}) {
+  const requiredRunId = required(runId, 'runId');
+  const at = timestamp(input.now);
+  const outcome = String(input.outcome ?? 'conductor-recovered').trim();
+  return withDatabase(projectRoot, (database) => {
+    database.exec('BEGIN IMMEDIATE;');
+    try {
+      expireStale(database, at);
+      const rows = database.prepare(`
+        SELECT * FROM execution_leases WHERE run_id = ? AND status = 'active'
+      `).all(requiredRunId);
+      database.prepare(`
+        UPDATE execution_leases SET status = 'released', released_at = ?, outcome = ?
+        WHERE run_id = ? AND status = 'active'
+      `).run(at, outcome, requiredRunId);
+      database.exec('COMMIT;');
+      return rows.map((row) => ({ ...rowToLease(row), status: 'released', releasedAt: at, outcome }));
+    } catch (error) {
+      database.exec('ROLLBACK;');
+      throw error;
+    }
+  });
+}

package/src/runtime/guided-discovery.mjs

@@ -0,0 +1,350 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import { atomicJson } from '../delivery-documents.mjs';
+import {
+  commitProjectDiscovery,
+  discoveryQuestionnaire,
+  prepareProjectDiscovery
+} from '../discovery.mjs';
+import {
+  listOrganisationBlueprints,
+  projectOrganisationBlueprint,
+  resolveOrganisationBlueprint,
+} from '../organisation-blueprints.mjs';
+import {
+  ORGANISATION_POLICY_BASELINE_PATH,
+  materialisePolicyBaseline,
+  previewPolicyBaseline,
+  readPolicyBaselineStatus,
+  resolveOrganisationPolicy,
+} from '../organisation-policies.mjs';
+import { loadProjectConfig } from '../project.mjs';
+import { selectContextualPersonas } from './persona-engagement.mjs';
+import { readEvidenceDepthWorkspace } from './evidence-depth-workspace.mjs';
+import { runtimePaths } from './paths.mjs';
+
+const DRAFT_SCHEMA = 'ewai.guided-discovery-draft/v1';
+const RESPONSE_SCHEMA = 'ewai.guided-discovery/v1';
+
+function failure(message, statusCode = 409) {
+  const error = new Error(message);
+  error.statusCode = statusCode;
+  return error;
+}
+
+function cleanText(value) {
+  return String(value ?? '').trim();
+}
+
+function sectionContract(sectionId) {
+  const questionnaire = discoveryQuestionnaire();
+  const section = questionnaire.sections.find((candidate) => candidate.id === sectionId);
+  if (!section) throw failure(`Unknown discovery section: ${sectionId}`, 400);
+  return { questionnaire, section };
+}
+
+export function selectDiscoveryPersonas(sectionId, personaCatalogue = [], answers = {}) {
+  const { section } = sectionContract(sectionId);
+  return selectContextualPersonas({
+    contextLabel: section.title,
+    signals: section.perspectiveSignals,
+    context: answers,
+    personaCatalogue,
+    limit: 4
+  });
+}
+
+function initialAnswers(projectRoot) {
+  const { config } = loadProjectConfig(projectRoot);
+  return {
+    schema: 'ewai.discovery-answers/v1',
+    project: { name: config.project?.name ?? '' },
+    delivery: {},
+    assurance: {}
+  };
+}
+
+function initialDraft(projectRoot) {
+  return {
+    schema: DRAFT_SCHEMA,
+    revision: 0,
+    currentSection: 'purpose',
+    answers: initialAnswers(projectRoot),
+    preparedAt: null,
+    createdAt: null,
+    updatedAt: null
+  };
+}
+
+function readDraft(projectRoot) {
+  const { guidedDiscoveryDraftPath } = runtimePaths(projectRoot);
+  if (!existsSync(guidedDiscoveryDraftPath)) return initialDraft(projectRoot);
+  let draft;
+  try {
+    draft = JSON.parse(readFileSync(guidedDiscoveryDraftPath, 'utf8'));
+  } catch (error) {
+    throw failure(`Guided discovery draft is not valid JSON: ${error.message}`);
+  }
+  if (draft.schema !== DRAFT_SCHEMA || !Number.isInteger(draft.revision) || draft.revision < 1) {
+    throw failure('Guided discovery draft has an unsupported schema or revision');
+  }
+  sectionContract(draft.currentSection);
+  return draft;
+}
+
+function discoveryEvidenceDimension(question) {
+  const path = question.answerPath;
+  if (path === 'assurance.dataClassification' || /personalData|sensitiveData|jurisdictions/.test(path)) return 'data';
+  if (/authentication|multiTenant|internetFacing|payments/.test(path)) return 'security';
+  if (/availability/.test(path)) return 'operations';
+  if (path.startsWith('assurance.')) return 'governance';
+  if (/technology|deploymentTarget/.test(path)) return 'architecture';
+  if (path.startsWith('delivery.') || /definitionOfReady|definitionOfDone|ownership\.delivery/.test(path)) return 'delivery';
+  if (/hardConstraints|nonNegotiables|dontTouch|risks/.test(path)) return 'governance';
+  if (/ownership\.technical|inScope|capabilities|productTypes/.test(path)) return 'architecture';
+  return 'product';
+}
+
+function hasDiscoveryEvidence(value) {
+  if (Array.isArray(value)) return value.some((item) => cleanText(item));
+  if (value && typeof value === 'object') return Object.keys(value).length > 0;
+  return cleanText(value).length > 0;
+}
+
+function discoveryEvidenceDigest(value) {
+  const canonical = Array.isArray(value)
+    ? value.map((item) => cleanText(item)).filter(Boolean).sort()
+    : value && typeof value === 'object'
+      ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, value[key]]))
+      : cleanText(value);
+  return `sha256:${createHash('sha256').update(JSON.stringify(canonical)).digest('hex')}`;
+}
+
+export function guidedDiscoveryOwnerEvidence(projectRoot) {
+  const draft = readDraft(projectRoot);
+  const entries = discoveryQuestionnaire().sections.flatMap((section) => section.questions)
+    .filter((question) => hasDiscoveryEvidence(question.answerPath.split('.').reduce((value, key) => value?.[key], draft.answers)))
+    .map((question) => {
+      const value = question.answerPath.split('.').reduce((current, key) => current?.[key], draft.answers);
+      return {
+        id: `discovery:${question.id}`,
+        dimension: discoveryEvidenceDimension(question),
+        authority: 'declared',
+        evidenceDigest: discoveryEvidenceDigest(value),
+        answerCode: `${question.id}-answer-recorded`,
+        reasonCode: `guided-discovery-r${draft.revision}`,
+        contradiction: 'none',
+      };
+    });
+  return entries.slice(0, 50);
+}
+
+function validationPath(error) {
+  const required = error.message.match(/^Discovery answer is required: (.+)$/);
+  return required?.[1] ?? '';
+}
+
+function organisationBlueprintCatalogue(projectRoot, options) {
+  return options.organisationBlueprints ?? listOrganisationBlueprints({
+    projectRoot,
+    roots: options.organisationBlueprintRoots,
+    home: options.home
+  });
+}
+
+function prepareDraft(projectRoot, draft, options = {}, catalogue = organisationBlueprintCatalogue(projectRoot, options)) {
+  try {
+    const prepared = prepareProjectDiscovery(projectRoot, draft.answers, {
+      now: draft.preparedAt ?? undefined,
+      organisationBlueprints: catalogue
+    });
+    return {
+      validation: { valid: true, errors: [] },
+      preview: {
+        schema: prepared.schema,
+        preparedAt: prepared.preparedAt,
+        outputs: prepared.outputs.map(({ kind, relative, exists }) => ({ kind, relative, exists })),
+        conflicts: prepared.conflicts,
+        selectedPacks: prepared.selectedPacks,
+        detectedPacks: prepared.detectedPacks,
+        organisationBlueprint: prepared.organisationBlueprint,
+        minimumStandards: prepared.minimumStandards,
+        complianceReviews: prepared.complianceReviews
+      },
+      prepared
+    };
+  } catch (error) {
+    return {
+      validation: { valid: false, errors: [{ path: validationPath(error), message: error.message }] },
+      preview: null,
+      prepared: null
+    };
+  }
+}
+
+function draftPolicyBaseline(draft, catalogue) {
+  const selection = draft.answers?.delivery?.organisationBlueprint;
+  if (!selection?.packId) return { resolved: null, preview: previewPolicyBaseline(null) };
+  try {
+    const blueprint = resolveOrganisationBlueprint(selection.packId, catalogue, {
+      enabledModules: selection.enabledModules ?? [],
+    });
+    const resolved = resolveOrganisationPolicy(blueprint);
+    return { resolved, preview: previewPolicyBaseline(resolved) };
+  } catch (error) {
+    return {
+      resolved: null,
+      preview: {
+        schema: 'ewai.policy-baseline-preview/v1',
+        status: 'invalid',
+        enabled: false,
+        blocking: false,
+        notice: error.message,
+        counts: { policies: 0, rules: 0 },
+        policies: [],
+      },
+    };
+  }
+}
+
+function guidedResponse(projectRoot, draft, options = {}) {
+  const { questionnaire, section } = sectionContract(draft.currentSection);
+  const catalogue = organisationBlueprintCatalogue(projectRoot, options);
+  const { validation, preview } = prepareDraft(projectRoot, draft, options, catalogue);
+  const policyBaseline = draftPolicyBaseline(draft, catalogue).preview;
+  const activePersonas = selectDiscoveryPersonas(section.id, options.personas ?? [], draft.answers);
+  const evidenceDepth = (() => {
+    try {
+      return readEvidenceDepthWorkspace(projectRoot, {
+        sourceMap: options.sourceMap,
+        personas: options.personas ?? [],
+      });
+    } catch (error) {
+      return {
+        schema: 'ewai.evidence-depth-workspace/v1',
+        status: 'unavailable',
+        preparation: null,
+        questions: [],
+        activePersonas: [],
+        runs: [],
+        recovery: {
+          command: 'node bin/ewai archaeology depth-status --project .',
+          label: 'Inspect evidence depth',
+        },
+        reason: error.message,
+      };
+    }
+  })();
+  return {
+    schema: RESPONSE_SCHEMA,
+    questionnaire,
+    draft,
+    validation,
+    preview,
+    organisationBlueprints: catalogue.map(projectOrganisationBlueprint),
+    policyBaseline,
+    activePersonas,
+    evidenceDepth,
+    guidance: {
+      advisory: true,
+      humanEvidenceTakesPriority: true,
+      section: section.id,
+      prompts: activePersonas.map((persona) => ({ personaId: persona.id, text: persona.engagementReason }))
+    }
+  };
+}
+
+export function readGuidedDiscovery(projectRoot, options = {}) {
+  return guidedResponse(projectRoot, readDraft(projectRoot), options);
+}
+
+export function saveGuidedDiscoveryDraft(projectRoot, input = {}, options = {}) {
+  const current = readDraft(projectRoot);
+  const expectedRevision = Number(input.expectedRevision);
+  if (!Number.isInteger(expectedRevision) || expectedRevision !== current.revision) {
+    throw failure(`A newer revision of this guided discovery draft exists (current revision ${current.revision})`);
+  }
+  const { section } = sectionContract(cleanText(input.currentSection) || current.currentSection);
+  if (!input.answers || typeof input.answers !== 'object' || Array.isArray(input.answers)) {
+    throw failure('Guided discovery answers must be an object', 400);
+  }
+  const timestamp = options.now ?? new Date().toISOString();
+  const draft = {
+    schema: DRAFT_SCHEMA,
+    revision: current.revision + 1,
+    currentSection: section.id,
+    answers: structuredClone(input.answers),
+    preparedAt: timestamp,
+    createdAt: current.createdAt ?? timestamp,
+    updatedAt: timestamp
+  };
+  atomicJson(runtimePaths(projectRoot).guidedDiscoveryDraftPath, draft);
+  return guidedResponse(projectRoot, draft, options);
+}
+
+export function approveGuidedDiscovery(projectRoot, input = {}, options = {}) {
+  if (input.confirmed !== true) throw failure('Canonical discovery requires explicit confirmation');
+  const approvedBy = cleanText(input.approvedBy);
+  if (!approvedBy) throw failure('Canonical discovery requires an accountable approver name');
+  const draft = readDraft(projectRoot);
+  const expectedRevision = Number(input.expectedRevision);
+  if (!Number.isInteger(expectedRevision) || expectedRevision !== draft.revision) {
+    throw failure(`A newer revision of this guided discovery draft exists (current revision ${draft.revision})`);
+  }
+  const { validation, prepared } = prepareDraft(projectRoot, draft, options);
+  if (!validation.valid || !prepared) throw failure('The current guided discovery draft is incomplete or invalid');
+  if (prepared.conflicts.length) {
+    throw failure(`Discovery outputs already exist and cannot be overwritten: ${prepared.conflicts.join(', ')}`);
+  }
+  const approvedAt = options.now ?? new Date().toISOString();
+  const catalogue = organisationBlueprintCatalogue(projectRoot, options);
+  const policy = draftPolicyBaseline(draft, catalogue);
+  if (policy.preview.status === 'invalid') throw failure(`The selected organisation policy is invalid: ${policy.preview.notice}`);
+  const commit = options.commit ?? commitProjectDiscovery;
+  const { paths } = loadProjectConfig(projectRoot);
+  const originalConfig = readFileSync(paths.configPath, 'utf8');
+  const baselinePath = resolve(paths.projectRoot, ORGANISATION_POLICY_BASELINE_PATH);
+  const hadBaseline = existsSync(baselinePath);
+  const originalBaseline = hadBaseline ? readFileSync(baselinePath, 'utf8') : null;
+  const materialise = options.materialisePolicy ?? materialisePolicyBaseline;
+  let policyBaseline;
+  let policyApplied = false;
+  let result;
+  try {
+    policyBaseline = policy.resolved?.contributions.length
+      ? materialise(projectRoot, policy.resolved, {
+        confirmed: true,
+        approvedBy,
+        expectedDigest: policy.resolved.effectiveDigest,
+        now: approvedAt,
+      })
+      : readPolicyBaselineStatus(projectRoot);
+    policyApplied = Boolean(policy.resolved?.contributions.length);
+    result = commit(projectRoot, prepared, {
+      approvedBy,
+      approvedAt,
+      organisationBlueprints: options.organisationBlueprints,
+      organisationBlueprintRoots: options.organisationBlueprintRoots,
+      home: options.home,
+      personas: selectDiscoveryPersonas('review', options.personas ?? [], draft.answers),
+    });
+  } catch (error) {
+    if (policyApplied) {
+      writeFileSync(paths.configPath, originalConfig, 'utf8');
+      if (hadBaseline) writeFileSync(baselinePath, originalBaseline, 'utf8');
+      else rmSync(baselinePath, { force: true });
+    }
+    throw error;
+  }
+  rmSync(runtimePaths(projectRoot).guidedDiscoveryDraftPath, { force: true });
+  return {
+    schema: 'ewai.guided-discovery-approval/v1',
+    status: 'completed',
+    approval: { approvedBy, approvedAt, revision: draft.revision },
+    created: result.created,
+    organisationBlueprint: result.organisationBlueprint,
+    policyBaseline,
+    nextCommand: result.nextCommand
+  };
+}