voidforge-build 23.10.0 → 23.11.0

package/dist/wizard/lib/image-gen.js

@@ -0,0 +1,159 @@
+/**
+ * Image generation provider abstraction — Celebrimbor's forge tools.
+ * Default: OpenAI (gpt-image-1). Extensible to other providers.
+ * Uses the same vault system as other VoidForge credentials.
+ */
+import { writeFile, readFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { httpsPost, httpsGet, safeJsonParse } from './provisioners/http-client.js';
+// ── OpenAI Provider ──────────────────────────────────────
+const OPENAI_API = 'api.openai.com';
+/**
+ * Generate an image via OpenAI's API.
+ * Returns the raw image bytes as a Buffer.
+ */
+export async function generateImage(apiKey, options, emit) {
+    const model = options.model || 'gpt-image-1';
+    const size = `${options.width}x${options.height}`;
+    // OpenAI only supports specific sizes — map to nearest and warn
+    const validSizes = ['1024x1024', '1792x1024', '1024x1792'];
+    const actualSize = validSizes.includes(size) ? size : '1024x1024';
+    if (actualSize !== size) {
+        emit({ step: 'image-gen', status: 'started', message: `Requested ${size} → using ${actualSize} (API constraint)` });
+    }
+    const body = JSON.stringify({
+        model,
+        prompt: options.prompt,
+        n: 1,
+        size: actualSize,
+        quality: options.quality || 'medium',
+        response_format: 'b64_json',
+    });
+    // Retry logic: 3 attempts with exponential backoff (1s, 3s, 9s)
+    // DALL-E 3 returns 500 errors on ~15% of requests (field report #1)
+    const MAX_RETRIES = 3;
+    const BACKOFF_BASE_MS = 1000;
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const res = await httpsPost(OPENAI_API, '/v1/images/generations', {
+                'Authorization': `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            }, body, 120_000); // 2 min timeout for image generation
+            if (res.status === 500 || res.status === 502 || res.status === 503) {
+                // Server error — retry with backoff
+                if (attempt < MAX_RETRIES) {
+                    const delay = BACKOFF_BASE_MS * Math.pow(3, attempt - 1);
+                    emit({ step: 'image-gen', status: 'started', message: `Server error (${res.status}), retrying in ${delay / 1000}s (attempt ${attempt}/${MAX_RETRIES})` });
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                    continue;
+                }
+                emit({ step: 'image-gen', status: 'error', message: `Server error (${res.status}) after ${MAX_RETRIES} attempts` });
+                return null;
+            }
+            if (res.status !== 200) {
+                const errData = safeJsonParse(res.body);
+                const errMsg = errData?.error?.message || `API returned ${res.status}`;
+                emit({ step: 'image-gen', status: 'error', message: `Generation failed: ${errMsg}` });
+                return null;
+            }
+            const data = safeJsonParse(res.body);
+            const b64 = data?.data?.[0]?.b64_json;
+            if (!b64) {
+                emit({ step: 'image-gen', status: 'error', message: 'No image data in API response' });
+                return null;
+            }
+            if (attempt > 1) {
+                emit({ step: 'image-gen', status: 'done', message: `Succeeded on attempt ${attempt}` });
+            }
+            return Buffer.from(b64, 'base64');
+        }
+        catch (err) {
+            if (attempt < MAX_RETRIES) {
+                const delay = BACKOFF_BASE_MS * Math.pow(3, attempt - 1);
+                emit({ step: 'image-gen', status: 'started', message: `Request failed, retrying in ${delay / 1000}s (attempt ${attempt}/${MAX_RETRIES})`, detail: err.message });
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                continue;
+            }
+            emit({ step: 'image-gen', status: 'error', message: `Image generation failed after ${MAX_RETRIES} attempts`, detail: err.message });
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Validate an OpenAI API key by making a lightweight models list request.
+ */
+export async function validateOpenAIKey(apiKey) {
+    try {
+        const res = await httpsGet(OPENAI_API, '/v1/models', {
+            'Authorization': `Bearer ${apiKey}`,
+        }, 10_000);
+        return res.status === 200;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Estimate the cost of generating N images.
+ */
+export function estimateImageCost(count, model = 'gpt-image-1') {
+    const costPerImage = {
+        'gpt-image-1': 0.04,
+        'dall-e-3': 0.08,
+    };
+    return count * (costPerImage[model] || 0.04);
+}
+// ── Asset Manifest ──────────────────────────────────────
+const MANIFEST_FILENAME = 'manifest.json';
+/**
+ * Read the asset manifest from disk.
+ */
+export async function readManifest(imagesDir) {
+    const manifestPath = join(imagesDir, MANIFEST_FILENAME);
+    try {
+        const content = await readFile(manifestPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write the asset manifest to disk.
+ */
+export async function writeManifest(imagesDir, manifest) {
+    await mkdir(imagesDir, { recursive: true });
+    await writeFile(join(imagesDir, MANIFEST_FILENAME), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Save a generated image to disk and update the manifest.
+ */
+export async function saveGeneratedImage(imagesDir, category, name, imageBuffer, prompt, size, manifest) {
+    const categoryDir = join(imagesDir, category);
+    await mkdir(categoryDir, { recursive: true });
+    const filename = `${category}/${name}.png`;
+    const filepath = join(imagesDir, filename);
+    await writeFile(filepath, imageBuffer);
+    const hash = createHash('sha256').update(imageBuffer).digest('hex');
+    // Remove any existing entry with the same filename (dedup for --regen)
+    manifest.assets = manifest.assets.filter(a => a.filename !== filename);
+    manifest.assets.push({
+        name,
+        filename,
+        prompt,
+        size,
+        generatedAt: new Date().toISOString(),
+        hash: `sha256:${hash}`,
+    });
+    await writeManifest(imagesDir, manifest);
+    return filepath;
+}
+/**
+ * Check if an asset already exists on disk.
+ */
+export function assetExists(imagesDir, category, name) {
+    return existsSync(join(imagesDir, category, `${name}.png`));
+}

package/dist/wizard/lib/natural-language-deploy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Natural Language Deploy — resolve prose deployment descriptions to YAML frontmatter.
+ *
+ * Parse: "I want a $20/month server with SSL and daily backups"
+ * → { deploy: 'vps', instanceType: 't3.small', hostname: '', resilience: { backups: 'daily', ... } }
+ *
+ * Uses keyword matching and heuristics — no AI API call required.
+ */
+export interface DeployConfig {
+    deploy: 'vps' | 'vercel' | 'railway' | 'cloudflare' | 'static' | 'docker';
+    instanceType: string;
+    hostname: string;
+    estimatedMonthlyCost: string;
+    resilience: {
+        multiEnv: boolean;
+        previewDeploys: boolean;
+        rollback: boolean;
+        migrations: 'auto' | 'manual' | 'no';
+        backups: 'daily' | 'weekly' | 'no';
+        healthCheck: boolean;
+        gracefulShutdown: boolean;
+        errorBoundaries: boolean;
+        rateLimiting: boolean;
+        deadLetterQueue: boolean;
+    };
+    reasoning: string[];
+}
+export declare function resolveDeployConfig(prose: string): DeployConfig | null;
+/** Convert a DeployConfig to YAML frontmatter fragment. */
+export declare function toFrontmatter(config: DeployConfig): string;

package/dist/wizard/lib/natural-language-deploy.js

@@ -0,0 +1,186 @@
+/**
+ * Natural Language Deploy — resolve prose deployment descriptions to YAML frontmatter.
+ *
+ * Parse: "I want a $20/month server with SSL and daily backups"
+ * → { deploy: 'vps', instanceType: 't3.small', hostname: '', resilience: { backups: 'daily', ... } }
+ *
+ * Uses keyword matching and heuristics — no AI API call required.
+ */
+const BUDGET_TIERS = [
+    { maxMonthly: 10, instanceType: 't3.micro', label: '~$8/mo' },
+    { maxMonthly: 25, instanceType: 't3.small', label: '~$17/mo' },
+    { maxMonthly: 50, instanceType: 't3.medium', label: '~$34/mo' },
+    { maxMonthly: 100, instanceType: 't3.large', label: '~$68/mo' },
+    { maxMonthly: Infinity, instanceType: 't3.xlarge', label: '~$136/mo' },
+];
+function resolveInstanceFromBudget(budget) {
+    return BUDGET_TIERS.find(t => budget <= t.maxMonthly) ?? BUDGET_TIERS[BUDGET_TIERS.length - 1];
+}
+// ── Keyword patterns ────────────────────────────
+const PLATFORM_KEYWORDS = [
+    { pattern: /\bvercel\b/i, target: 'vercel', reason: 'Vercel mentioned explicitly' },
+    { pattern: /\brailway\b/i, target: 'railway', reason: 'Railway mentioned explicitly' },
+    { pattern: /\bcloudflare\b/i, target: 'cloudflare', reason: 'Cloudflare mentioned explicitly' },
+    { pattern: /\bdocker\b|\bcontainer\b/i, target: 'docker', reason: 'Docker/container mentioned' },
+    { pattern: /\bstatic\s*(?:site|hosting|files?)\b/i, target: 'static', reason: 'Static site hosting' },
+    { pattern: /\bvps\b|\bserver\b|\bec2\b|\baws\b|\bssh\b/i, target: 'vps', reason: 'Server/VPS/AWS mentioned' },
+    { pattern: /\bserverless\b|\bedge\b/i, target: 'vercel', reason: 'Serverless/edge → Vercel' },
+    { pattern: /\bfree\s*tier\b|\bno\s*cost\b|\bfree\b/i, target: 'railway', reason: 'Free tier → Railway' },
+];
+const FEATURE_KEYWORDS = [
+    { pattern: /\bbackup/i, key: 'backups', reason: 'Backups requested' },
+    { pattern: /\bssl\b|\bhttps\b|\btls\b/i, key: 'ssl', reason: 'SSL/TLS requested' },
+    { pattern: /\bcustom\s*domain\b|\bmy\s*domain\b/i, key: 'customDomain', reason: 'Custom domain' },
+    { pattern: /\brollback\b|\brevert\b/i, key: 'rollback', reason: 'Rollback requested' },
+    { pattern: /\bpreview\b|\bpr\s*deploy/i, key: 'previewDeploys', reason: 'Preview deploys' },
+    { pattern: /\bhealth\s*check\b|\bmonitoring\b|\buptime\b/i, key: 'healthCheck', reason: 'Health monitoring' },
+    { pattern: /\brate\s*limit/i, key: 'rateLimiting', reason: 'Rate limiting' },
+    { pattern: /\bgraceful\b|\bzero\s*downtime\b/i, key: 'gracefulShutdown', reason: 'Zero-downtime' },
+    { pattern: /\bmulti\s*(?:env|environment)\b|\bstaging\b/i, key: 'multiEnv', reason: 'Multi-environment' },
+    { pattern: /\berror\s*boundar/i, key: 'errorBoundaries', reason: 'Error boundaries' },
+    { pattern: /\bdead\s*letter\b|\bdlq\b|\bretry\s*queue\b/i, key: 'deadLetterQueue', reason: 'Dead letter queue' },
+    { pattern: /\bmigration/i, key: 'migrations', reason: 'Database migrations' },
+];
+const SCALE_KEYWORDS = [
+    { pattern: /\bsmall\b|\bsimple\b|\bblog\b|\bpersonal\b|\bside\s*project\b|\bmvp\b|\bprototype\b/i, scale: 'small', reason: 'Small/simple project' },
+    { pattern: /\bmedium\b|\bstartup\b|\bsaas\b|\bteam\b|\bgrow/i, scale: 'medium', reason: 'Medium/startup scale' },
+    { pattern: /\blarge\b|\benterprise\b|\bthousands\b|\bhigh\s*traffic\b|\bscale\b|\bproduction\b/i, scale: 'large', reason: 'Large/production scale' },
+];
+// ── Main resolver ───────────────────────────────
+export function resolveDeployConfig(prose) {
+    if (!prose.trim())
+        return null;
+    const reasoning = [];
+    const features = new Set();
+    // Extract budget — prefer amounts near cost keywords, fall back to first $N
+    const costContextMatch = prose.match(/(?:budget|spend|cost|month|mo)[^$]*\$(\d+(?:\.\d+)?)/i)
+        ?? prose.match(/\$(\d+(?:\.\d+)?)(?:\s*\/\s*mo(?:nth)?)/i)
+        ?? prose.match(/\$(\d+(?:\.\d+)?)/i);
+    const budget = costContextMatch ? Math.round(parseFloat(costContextMatch[1])) : -1;
+    // Detect explicit platform
+    let deploy = 'vps'; // default
+    let platformDetected = false;
+    for (const kw of PLATFORM_KEYWORDS) {
+        if (kw.pattern.test(prose)) {
+            deploy = kw.target;
+            reasoning.push(kw.reason);
+            platformDetected = true;
+            break;
+        }
+    }
+    // Detect features
+    for (const kw of FEATURE_KEYWORDS) {
+        if (kw.pattern.test(prose)) {
+            features.add(kw.key);
+            reasoning.push(kw.reason);
+        }
+    }
+    // Detect scale
+    let scale = 'small';
+    for (const kw of SCALE_KEYWORDS) {
+        if (kw.pattern.test(prose)) {
+            scale = kw.scale;
+            reasoning.push(kw.reason);
+            break;
+        }
+    }
+    // If no platform detected, infer from features and scale
+    if (!platformDetected) {
+        if (features.has('previewDeploys') || features.has('errorBoundaries')) {
+            deploy = 'vercel';
+            reasoning.push('Preview deploys/error boundaries → Vercel (best support)');
+        }
+        else if (scale === 'large' || features.has('customDomain') || budget > 30) {
+            deploy = 'vps';
+            reasoning.push('Large scale or custom domain with budget → VPS');
+        }
+        else if (scale === 'small' && budget < 0) {
+            deploy = 'railway';
+            reasoning.push('Small project, no budget specified → Railway (easiest start)');
+        }
+        else {
+            deploy = 'vps';
+            reasoning.push('Default → VPS (most flexible)');
+        }
+    }
+    // Resolve instance type from budget or scale
+    let instanceType = '';
+    let estimatedCost = '';
+    if (deploy === 'vps') {
+        if (budget >= 0) {
+            const tier = resolveInstanceFromBudget(budget);
+            instanceType = tier.instanceType;
+            estimatedCost = tier.label;
+            reasoning.push(`Budget $${budget}/mo → ${tier.instanceType} (${tier.label})`);
+        }
+        else {
+            const scaleMap = { small: 't3.micro', medium: 't3.small', large: 't3.medium' };
+            const costMap = { small: '~$8/mo', medium: '~$17/mo', large: '~$34/mo' };
+            instanceType = scaleMap[scale];
+            estimatedCost = costMap[scale];
+            reasoning.push(`${scale} scale → ${instanceType} (${estimatedCost})`);
+        }
+    }
+    else {
+        estimatedCost = deploy === 'railway' ? 'Free tier available' :
+            deploy === 'vercel' ? 'Free tier available' :
+                deploy === 'cloudflare' ? 'Free tier available' :
+                    deploy === 'static' ? 'Minimal (~$1/mo S3)' : 'Varies';
+    }
+    // Extract hostname if mentioned
+    const hostnameMatch = prose.match(/(?:domain|hostname|url)[\s:]*([a-z0-9.-]+\.[a-z]{2,})/i);
+    const hostname = hostnameMatch ? hostnameMatch[1] : '';
+    if (hostname)
+        reasoning.push(`Hostname detected: ${hostname}`);
+    // Build resilience config — defaults based on deploy target + detected features
+    const isVps = deploy === 'vps';
+    const isPlatform = ['vercel', 'railway', 'cloudflare'].includes(deploy);
+    const resilience = {
+        multiEnv: features.has('multiEnv') || scale !== 'small',
+        previewDeploys: features.has('previewDeploys') || (isPlatform && scale !== 'small'),
+        rollback: features.has('rollback') || isPlatform,
+        migrations: features.has('migrations') ? 'auto' : (isVps ? 'manual' : 'no'),
+        backups: features.has('backups') ? 'daily' : (isVps && scale !== 'small' ? 'weekly' : 'no'),
+        healthCheck: features.has('healthCheck') || isVps || scale !== 'small',
+        gracefulShutdown: features.has('gracefulShutdown') || isVps,
+        errorBoundaries: features.has('errorBoundaries'),
+        rateLimiting: features.has('rateLimiting') || scale === 'large',
+        deadLetterQueue: features.has('deadLetterQueue'),
+    };
+    return {
+        deploy,
+        instanceType,
+        hostname,
+        estimatedMonthlyCost: estimatedCost,
+        resilience,
+        reasoning,
+    };
+}
+/** Sanitize a string for safe YAML double-quoted interpolation. */
+function yamlSafe(value) {
+    return value.replace(/[\\"]/g, '');
+}
+/** Convert a DeployConfig to YAML frontmatter fragment. */
+export function toFrontmatter(config) {
+    const lines = [
+        `deploy: "${yamlSafe(config.deploy)}"`,
+    ];
+    if (config.instanceType) {
+        lines.push(`instance_type: "${yamlSafe(config.instanceType)}"`);
+    }
+    if (config.hostname) {
+        lines.push(`hostname: "${yamlSafe(config.hostname.toLowerCase())}"`);
+    }
+    lines.push('resilience:');
+    lines.push(`  multi-env: ${config.resilience.multiEnv ? 'yes' : 'no'}`);
+    lines.push(`  preview-deploys: ${config.resilience.previewDeploys ? 'yes' : 'no'}`);
+    lines.push(`  rollback: ${config.resilience.rollback ? 'yes' : 'no'}`);
+    lines.push(`  migrations: "${yamlSafe(config.resilience.migrations)}"`);
+    lines.push(`  backups: "${yamlSafe(config.resilience.backups)}"`);
+    lines.push(`  health-check: ${config.resilience.healthCheck ? 'yes' : 'no'}`);
+    lines.push(`  graceful-shutdown: ${config.resilience.gracefulShutdown ? 'yes' : 'no'}`);
+    lines.push(`  error-boundaries: ${config.resilience.errorBoundaries ? 'yes' : 'no'}`);
+    lines.push(`  rate-limiting: ${config.resilience.rateLimiting ? 'yes' : 'no'}`);
+    lines.push(`  dead-letter-queue: ${config.resilience.deadLetterQueue ? 'yes' : 'no'}`);
+    return lines.join('\n');
+}

package/dist/wizard/lib/project-init.js

@@ -113,8 +113,65 @@ async function copyMethodology(methodologyRoot, projectDir, core) {
     if (existsSync(thumperSrc)) {
         count += await copyDir(thumperSrc, join(projectDir, 'scripts', 'thumper'));
     }
+    // Surfer-gate scripts (ADR-051 enforcement — closes #317).
+    // Ship the gate to every new project so the hook can mechanically enforce
+    // CLAUDE.md's Silver Surfer procedure. Without this the prose-backstop is
+    // the only thing holding the line in consumer installs.
+    const surferGateSrc = join(methodologyRoot, 'scripts', 'surfer-gate');
+    if (existsSync(surferGateSrc)) {
+        count += await copyDir(surferGateSrc, join(projectDir, 'scripts', 'surfer-gate'));
+        await chmodShellScripts(join(projectDir, 'scripts', 'surfer-gate'));
+        await mergeSettingsHook(projectDir);
+    }
     return count;
 }
+async function chmodShellScripts(dir) {
+    if (!existsSync(dir))
+        return;
+    const { chmod } = await import('node:fs/promises');
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isFile() && entry.name.endsWith('.sh')) {
+            await chmod(join(dir, entry.name), 0o755);
+        }
+    }
+}
+async function mergeSettingsHook(projectDir) {
+    const snippetPath = join(projectDir, 'scripts', 'surfer-gate', 'settings-snippet.json');
+    const settingsPath = join(projectDir, '.claude', 'settings.json');
+    if (!existsSync(snippetPath))
+        return;
+    const snippet = JSON.parse(await readFile(snippetPath, 'utf-8'));
+    const productionHook = snippet?.production_hook;
+    if (!productionHook?.PreToolUse)
+        return;
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
+        }
+        catch {
+            // Existing settings.json is unreadable — leave it alone.
+            return;
+        }
+    }
+    else {
+        await mkdir(join(projectDir, '.claude'), { recursive: true });
+    }
+    const existingHooks = (settings.hooks ?? {});
+    const existingPreTool = (existingHooks.PreToolUse ?? []);
+    const alreadyHasGate = existingPreTool.some((entry) => {
+        const hooks = (entry?.hooks ?? []);
+        return hooks.some((h) => typeof h?.command === 'string' && h.command.includes('surfer-gate/check.sh'));
+    });
+    if (alreadyHasGate)
+        return;
+    settings.hooks = {
+        ...existingHooks,
+        PreToolUse: [...existingPreTool, ...productionHook.PreToolUse],
+    };
+    await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+}
 // ── Identity Injection ───────────────────────────────────
 async function injectIdentity(projectDir, config) {
     const claudePath = join(projectDir, 'CLAUDE.md');

package/dist/wizard/lib/route-optimizer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Paris's Route Optimizer — ROI-weighted campaign sequencing (v12.3).
+ *
+ * Given multiple possible campaigns (from the proposal generator), Paris
+ * computes the optimal execution order based on estimated ROI, dependencies,
+ * risk, and urgency.
+ *
+ * PRD Reference: ROADMAP v12.3, DEEP_CURRENT.md Paris's role
+ */
+import type { CampaignProposal } from './campaign-proposer.js';
+import type { SituationModel } from './deep-current.js';
+interface RouteScore {
+    proposal: CampaignProposal;
+    roiScore: number;
+    urgencyScore: number;
+    riskScore: number;
+    totalScore: number;
+}
+/**
+ * Score and rank campaign proposals by optimal execution order.
+ * Returns proposals sorted by total score (highest first = execute first).
+ */
+export declare function optimizeRoute(proposals: CampaignProposal[], model: SituationModel): RouteScore[];
+/**
+ * Pick the single best campaign to execute next.
+ */
+export declare function pickBestCampaign(proposals: CampaignProposal[], model: SituationModel): CampaignProposal | null;
+export type { RouteScore };

package/dist/wizard/lib/route-optimizer.js

@@ -0,0 +1,93 @@
+/**
+ * Paris's Route Optimizer — ROI-weighted campaign sequencing (v12.3).
+ *
+ * Given multiple possible campaigns (from the proposal generator), Paris
+ * computes the optimal execution order based on estimated ROI, dependencies,
+ * risk, and urgency.
+ *
+ * PRD Reference: ROADMAP v12.3, DEEP_CURRENT.md Paris's role
+ */
+// ── Scoring Weights ───────────────────────────────────
+const WEIGHTS = {
+    roi: 0.40,
+    urgency: 0.35,
+    risk: 0.25, // Inverted — lower risk gets higher score
+};
+// ── ROI Estimation ────────────────────────────────────
+function estimateRoi(proposal, model) {
+    // ROI = (dimension improvement potential) / (estimated effort)
+    const currentScore = proposal.dimensionScore;
+    const potentialGain = Math.min(30, 100 - currentScore); // Cap at 30-point improvement
+    const effort = proposal.estimatedSessions;
+    // Higher gain per session = higher ROI
+    const roiRatio = potentialGain / Math.max(effort, 1);
+    return Math.min(100, Math.round(roiRatio * 10)); // Scale to 0-100
+}
+// ── Urgency Scoring ───────────────────────────────────
+function scoreUrgency(proposal, model) {
+    const dim = proposal.dimension;
+    const score = proposal.dimensionScore;
+    // Critical defects are always urgent
+    if (dim === 'quality' && score < 30)
+        return 100;
+    // Security issues are urgent
+    if (dim === 'performance' && model.lastSiteScan && !model.lastSiteScan.security.https)
+        return 90;
+    // Low scores are more urgent
+    if (score < 20)
+        return 80;
+    if (score < 40)
+        return 60;
+    if (score < 60)
+        return 40;
+    // Revenue is urgent for OPERATING projects
+    if (dim === 'revenuePotential' && model.projectState === 'OPERATING')
+        return 70;
+    return 20; // Low urgency by default
+}
+// ── Risk Scoring ──────────────────────────────────────
+function scoreRisk(proposal) {
+    // Revenue/payment campaigns are higher risk (real money)
+    if (proposal.dimension === 'revenuePotential')
+        return 70;
+    // Feature campaigns have moderate risk (new code)
+    if (proposal.dimension === 'featureCompleteness')
+        return 50;
+    // Quality and performance campaigns are low risk
+    if (proposal.dimension === 'quality')
+        return 20;
+    if (proposal.dimension === 'performance')
+        return 25;
+    // Growth foundation is low risk (additive, no existing code modified)
+    if (proposal.dimension === 'growthReadiness')
+        return 30;
+    return 40;
+}
+// ── Route Optimization ────────────────────────────────
+/**
+ * Score and rank campaign proposals by optimal execution order.
+ * Returns proposals sorted by total score (highest first = execute first).
+ */
+export function optimizeRoute(proposals, model) {
+    const scored = proposals.map(proposal => {
+        const roiScore = estimateRoi(proposal, model);
+        const urgencyScore = scoreUrgency(proposal, model);
+        const riskScore = 100 - scoreRisk(proposal); // Invert: low risk = high score
+        const totalScore = Math.round(roiScore * WEIGHTS.roi +
+            urgencyScore * WEIGHTS.urgency +
+            riskScore * WEIGHTS.risk);
+        return { proposal, roiScore, urgencyScore, riskScore, totalScore };
+    });
+    // Sort by total score descending (best first)
+    scored.sort((a, b) => b.totalScore - a.totalScore);
+    return scored;
+}
+/**
+ * Pick the single best campaign to execute next.
+ */
+export function pickBestCampaign(proposals, model) {
+    if (proposals.length === 0)
+        return null;
+    const ranked = optimizeRoute(proposals, model);
+    return ranked[0].proposal;
+}

package/dist/wizard/lib/service-install.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Service Install — launchd/systemd/Task Scheduler integration (§9.18, §9.19.2).
+ *
+ * Creates system services for:
+ * 1. Heartbeat daemon (com.voidforge.heartbeat)
+ * 2. Wizard server (com.voidforge.server) — persistent when Cultivation is installed
+ *
+ * PRD Reference: §9.18 (macOS LaunchAgent), §9.19.2 (two services)
+ */
+export declare function installHeartbeatService(): Promise<{
+    method: string;
+    path: string;
+}>;
+export declare function installServerService(port?: number): Promise<{
+    method: string;
+    path: string;
+}>;
+export declare function uninstallServices(): Promise<void>;