thevoidforge 21.0.0

package/dist/wizard/lib/campaign-proposer.js

@@ -0,0 +1,180 @@
+/**
+ * Tuvok's Campaign Proposer — generates data-driven campaign proposals (v12.1).
+ *
+ * Takes the situation model (with Seven's gap analysis) and generates a
+ * complete campaign proposal: name, missions, predicted impact, risk, alternatives.
+ *
+ * PRD Reference: ROADMAP v12.1, DEEP_CURRENT.md PROPOSE step
+ */
+import { mkdir, writeFile as writeFileAsync } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { PROPOSALS_DIR } from './deep-current.js';
+import { findWeakestDimension } from './gap-analysis.js';
+// ── Proposal Templates Per Dimension ──────────────────
+function proposeForFeatureCompleteness(model) {
+    const weakest = findWeakestDimension(model);
+    return {
+        id: randomUUID(),
+        name: 'Feature Sprint',
+        generatedAt: new Date().toISOString(),
+        trigger: `Feature completeness score ${weakest.score}/100 is the lowest dimension`,
+        dimension: 'featureCompleteness',
+        dimensionScore: weakest.score,
+        theCase: `The project has significant PRD requirements that are not yet implemented. ${weakest.gaps.join('. ')}. Building core features will increase the product's value proposition and move toward a shippable state.`,
+        missions: [
+            { number: 1, name: 'Core Feature Build', objective: 'Implement the highest-priority unbuilt PRD features', estimatedFiles: 15 },
+            { number: 2, name: 'Supporting Features', objective: 'Build supporting features that depend on core', estimatedFiles: 10 },
+            { number: 3, name: 'Integration Wiring', objective: 'Connect new features to existing infrastructure', estimatedFiles: 5 },
+        ],
+        expectedImpact: `Feature completeness +${Math.min(30, 100 - weakest.score)} points. PRD coverage from ${weakest.score}% to ~${Math.min(100, weakest.score + 30)}%.`,
+        riskAssessment: 'New features may introduce bugs. Victory Gauntlet will catch them.',
+        alternativesConsidered: ['Focus on quality first (gauntlet findings)', 'Focus on growth (marketing before features)'],
+        autonomyRecommendation: 1, // Feature builds need human judgment
+        estimatedSessions: 2,
+    };
+}
+function proposeForQuality(model) {
+    const dim = model.dimensions.quality;
+    return {
+        id: randomUUID(),
+        name: 'Quality Hardening',
+        generatedAt: new Date().toISOString(),
+        trigger: `Quality score ${dim.score}/100 is the lowest dimension`,
+        dimension: 'quality',
+        dimensionScore: dim.score,
+        theCase: `The project has quality gaps that risk user trust and developer velocity. ${dim.gaps.join('. ')}. Investing in testing, fixing gauntlet findings, and establishing quality baselines will pay dividends in every future campaign.`,
+        missions: [
+            { number: 1, name: 'Test Coverage', objective: 'Write missing unit and integration tests', estimatedFiles: 20 },
+            { number: 2, name: 'Finding Resolution', objective: 'Fix outstanding gauntlet and review findings', estimatedFiles: 10 },
+            { number: 3, name: 'Quality Gates', objective: 'Establish CI/CD quality checks', estimatedFiles: 5 },
+        ],
+        expectedImpact: `Quality score +${Math.min(25, 100 - dim.score)} points. Test coverage increase. Gauntlet findings resolved.`,
+        riskAssessment: 'Quality campaigns have low risk. Tests protect against regressions.',
+        alternativesConsidered: ['Ship features first, quality later (technical debt risk)', 'Focus on performance instead'],
+        autonomyRecommendation: 2, // Quality campaigns are safe to auto-execute
+        estimatedSessions: 2,
+    };
+}
+function proposeForPerformance(model) {
+    const dim = model.dimensions.performance;
+    const scan = model.lastSiteScan;
+    return {
+        id: randomUUID(),
+        name: 'Performance Optimization',
+        generatedAt: new Date().toISOString(),
+        trigger: `Performance score ${dim.score}/100 is the lowest dimension`,
+        dimension: 'performance',
+        dimensionScore: dim.score,
+        theCase: `The deployed site has performance issues that affect user experience and SEO rankings. ${dim.gaps.join('. ')}. ${scan?.performance.ttfbMs ? `TTFB is ${scan.performance.ttfbMs}ms.` : ''} Improving Core Web Vitals will increase search rankings and reduce bounce rates.`,
+        missions: [
+            { number: 1, name: 'Core Web Vitals', objective: 'Fix LCP, CLS, and FID issues', estimatedFiles: 10 },
+            { number: 2, name: 'Asset Optimization', objective: 'Compression, caching, image optimization', estimatedFiles: 5 },
+        ],
+        expectedImpact: `Performance score +${Math.min(30, 100 - dim.score)} points. Estimated +10-20% search visibility from CWV improvements.`,
+        riskAssessment: 'Performance changes can break layouts. Visual regression testing recommended.',
+        alternativesConsidered: ['Focus on growth instead (marketing over performance)', 'Focus on features'],
+        autonomyRecommendation: 2, // Performance fixes are usually safe
+        estimatedSessions: 1,
+    };
+}
+function proposeForGrowthReadiness(model) {
+    const dim = model.dimensions.growthReadiness;
+    return {
+        id: randomUUID(),
+        name: 'Growth Foundation',
+        generatedAt: new Date().toISOString(),
+        trigger: `Growth readiness score ${dim.score}/100 is the lowest dimension`,
+        dimension: 'growthReadiness',
+        dimensionScore: dim.score,
+        theCase: `The project lacks growth infrastructure. ${dim.gaps.join('. ')}. Without analytics, SEO, and conversion paths, no amount of traffic will translate to results. This is the foundation that all growth campaigns build on.`,
+        missions: [
+            { number: 1, name: 'Analytics + SEO Foundation', objective: 'Install analytics, meta tags, sitemap, JSON-LD', estimatedFiles: 8 },
+            { number: 2, name: 'Conversion Paths', objective: 'Email capture, CTAs, social proof', estimatedFiles: 6 },
+            { number: 3, name: 'Content Foundation', objective: 'Blog setup, landing page optimization', estimatedFiles: 10 },
+        ],
+        expectedImpact: `Growth readiness +${Math.min(35, 100 - dim.score)} points. Analytics baseline established. Organic traffic pipeline started.`,
+        riskAssessment: 'Low risk. Growth foundation is additive — no existing features are modified.',
+        alternativesConsidered: ['Run /grow directly (requires deployed site)', 'Focus on revenue first'],
+        autonomyRecommendation: 1, // Growth strategy needs human input
+        estimatedSessions: 2,
+    };
+}
+function proposeForRevenuePotential(model) {
+    const dim = model.dimensions.revenuePotential;
+    return {
+        id: randomUUID(),
+        name: 'Revenue Infrastructure',
+        generatedAt: new Date().toISOString(),
+        trigger: `Revenue potential score ${dim.score}/100 is the lowest dimension`,
+        dimension: 'revenuePotential',
+        dimensionScore: dim.score,
+        theCase: `The project has limited revenue infrastructure. ${dim.gaps.join('. ')}. Connecting payment processing, setting up pricing pages, and establishing revenue tracking will enable monetization.`,
+        missions: [
+            { number: 1, name: 'Payment Integration', objective: 'Stripe/Paddle setup, checkout flow', estimatedFiles: 12 },
+            { number: 2, name: 'Pricing + Plans', objective: 'Pricing page, plan tiers, billing management', estimatedFiles: 8 },
+            { number: 3, name: 'Treasury Setup', objective: 'Revenue tracking, reconciliation, /treasury connection', estimatedFiles: 5 },
+        ],
+        expectedImpact: `Revenue potential +${Math.min(30, 100 - dim.score)} points. Payment pipeline established. Revenue tracking active.`,
+        riskAssessment: 'Payment integration involves real money. Requires thorough testing and security review.',
+        alternativesConsidered: ['Focus on growth first (users before revenue)', 'Focus on features'],
+        autonomyRecommendation: 1, // Revenue/payment changes need human oversight
+        estimatedSessions: 2,
+    };
+}
+// ── Main Proposal Generator ───────────────────────────
+const DIMENSION_PROPOSERS = {
+    'Feature Completeness': proposeForFeatureCompleteness,
+    'Quality': proposeForQuality,
+    'Performance': proposeForPerformance,
+    'Growth Readiness': proposeForGrowthReadiness,
+    'Revenue Potential': proposeForRevenuePotential,
+};
+/**
+ * Generate a campaign proposal targeting the weakest dimension.
+ */
+export function generateProposal(model) {
+    const weakest = findWeakestDimension(model);
+    const proposer = DIMENSION_PROPOSERS[weakest.name];
+    if (!proposer)
+        return proposeForFeatureCompleteness(model); // fallback
+    return proposer(model);
+}
+/**
+ * Save a proposal to disk as markdown.
+ */
+export async function saveProposal(proposal) {
+    await mkdir(PROPOSALS_DIR, { recursive: true });
+    const date = new Date().toISOString().split('T')[0];
+    const slug = proposal.name.toLowerCase().replace(/\s+/g, '-');
+    const filename = `${date}-${slug}.md`;
+    const filepath = join(PROPOSALS_DIR, filename);
+    const content = `# Campaign Proposal — ${proposal.name}
+## Generated by: The Deep Current (Tuvok)
+## Date: ${proposal.generatedAt}
+## Trigger: ${proposal.trigger}
+
+### The Case
+${proposal.theCase}
+
+### Missions
+${proposal.missions.map(m => `${m.number}. **${m.name}** — ${m.objective} (~${m.estimatedFiles} files)`).join('\n')}
+
+### Expected Impact
+${proposal.expectedImpact}
+
+### Risk Assessment
+${proposal.riskAssessment}
+
+### Alternatives Considered
+${proposal.alternativesConsidered.map(a => `- ${a}`).join('\n')}
+
+### Autonomy Recommendation
+Tier ${proposal.autonomyRecommendation} — ${proposal.autonomyRecommendation === 1 ? 'Human approval required' : proposal.autonomyRecommendation === 2 ? 'Supervised autonomy (24h delay)' : 'Full autonomy'}
+
+### Estimated Effort
+${proposal.estimatedSessions} session(s)
+`;
+    await writeFileAsync(filepath, content);
+    return filepath;
+}

package/dist/wizard/lib/campaign-state-machine.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Campaign State Machine — Event-sourced transitions with validation (§9.17).
+ *
+ * 10 states, validated transitions, event-sourced history.
+ * Only valid transitions are allowed. Invalid transitions throw.
+ * Each transition is logged as an event with source, reason, and optional ruleId.
+ *
+ * PRD Reference: §9.9 (GrowthCampaign), §9.17 (state machine), §9.19.11 (agent source)
+ */
+type CampaignStatus = 'draft' | 'pending_approval' | 'creating' | 'active' | 'paused' | 'completed' | 'error' | 'suspended' | 'deleting' | 'freeze_pending';
+type CampaignEventSource = 'cli' | 'daemon' | 'platform' | 'agent';
+interface CampaignStateEvent {
+    timestamp: string;
+    source: CampaignEventSource;
+    oldStatus: CampaignStatus;
+    newStatus: CampaignStatus;
+    reason: string;
+    ruleId?: string;
+}
+declare const VALID_TRANSITIONS: Record<CampaignStatus, CampaignStatus[]>;
+declare const AGENT_ALLOWED_TRANSITIONS: Array<{
+    from: CampaignStatus;
+    to: CampaignStatus;
+}>;
+declare const AGENT_ALLOWED_REASONS: string[];
+declare function isValidTransition(from: CampaignStatus, to: CampaignStatus): boolean;
+declare function isAgentAllowed(from: CampaignStatus, to: CampaignStatus, reason: string): boolean;
+declare function transition(currentStatus: CampaignStatus, newStatus: CampaignStatus, source: CampaignEventSource, reason: string, ruleId?: string): CampaignStateEvent;
+interface SpendIntent {
+    intentId: string;
+    platform: string;
+    campaignConfig: unknown;
+    budgetLocked: boolean;
+    status: 'pending' | 'executing' | 'completed' | 'failed' | 'stale';
+    createdAt: string;
+    completedAt?: string;
+    error?: string;
+}
+/**
+ * Create a spend intent (WAL entry) before executing a platform API call.
+ * The intent ID serves as the idempotency key for the platform (ADR-3).
+ */
+declare function createSpendIntent(intentId: string, platform: string, campaignConfig: unknown): SpendIntent;
+/**
+ * Lock the budget for a spend intent.
+ * Verifies the daily budget has room for this campaign.
+ * Returns false if budget is exhausted.
+ */
+declare function lockBudget(intent: SpendIntent, dailyBudgetCents: number, currentDailySpendCents: number, hardStopCents: number): boolean;
+/**
+ * Execute the spend intent: WAL → platform API → spend log → campaign record.
+ * Each step is logged. On failure, the intent is marked failed and can be retried.
+ */
+declare function executeSpendIntent(intent: SpendIntent, platformCall: () => Promise<{
+    externalId: string;
+}>, logSpend: (intentId: string, externalId: string) => Promise<void>): Promise<{
+    success: boolean;
+    externalId?: string;
+    error?: string;
+}>;
+type PauseReason = 'budget_exhausted' | 'user_paused' | 'compliance' | 'underperforming' | 'freeze' | 'token_expired' | 'platform_suspended' | 'approval_timeout' | 'killed_by_agent' | 'killed_by_user' | 'ab_test_loser';
+export type { CampaignStatus, CampaignEventSource, CampaignStateEvent, SpendIntent, PauseReason };
+export { VALID_TRANSITIONS, AGENT_ALLOWED_TRANSITIONS, AGENT_ALLOWED_REASONS, isValidTransition, isAgentAllowed, transition, createSpendIntent, lockBudget, executeSpendIntent, };

package/dist/wizard/lib/campaign-state-machine.js

@@ -0,0 +1,114 @@
+/**
+ * Campaign State Machine — Event-sourced transitions with validation (§9.17).
+ *
+ * 10 states, validated transitions, event-sourced history.
+ * Only valid transitions are allowed. Invalid transitions throw.
+ * Each transition is logged as an event with source, reason, and optional ruleId.
+ *
+ * PRD Reference: §9.9 (GrowthCampaign), §9.17 (state machine), §9.19.11 (agent source)
+ */
+// ── Valid Transitions ─────────────────────────────────
+const VALID_TRANSITIONS = {
+    draft: ['pending_approval', 'deleting'],
+    pending_approval: ['creating', 'draft', 'deleting'], // approve → creating, reject → draft
+    creating: ['active', 'error', 'deleting'], // success → active, fail → error
+    active: ['paused', 'completed', 'error', 'suspended', 'deleting', 'freeze_pending'],
+    paused: ['active', 'deleting', 'completed'], // resume, delete, or mark done
+    completed: [], // terminal
+    error: ['creating', 'deleting', 'draft'], // retry → creating, abandon → deleting
+    suspended: ['active', 'paused', 'deleting'], // platform reinstates, or we give up
+    deleting: ['completed'], // deletion confirmed → terminal
+    freeze_pending: ['paused', 'active'], // freeze succeeds → paused, freeze fails → active
+};
+// ── Agent-Allowed Transitions (§9.19.11) ──────────────
+// Daemon Tier 1 rules can ONLY perform these transitions
+const AGENT_ALLOWED_TRANSITIONS = [
+    { from: 'active', to: 'paused' }, // kill underperformer, A/B test loser
+];
+const AGENT_ALLOWED_REASONS = [
+    'killed_by_agent',
+    'underperforming',
+    'budget_exhausted',
+    'ab_test_loser',
+];
+// ── State Machine ─────────────────────────────────────
+function isValidTransition(from, to) {
+    return VALID_TRANSITIONS[from]?.includes(to) ?? false;
+}
+function isAgentAllowed(from, to, reason) {
+    const transitionOk = AGENT_ALLOWED_TRANSITIONS.some(t => t.from === from && t.to === to);
+    const reasonOk = AGENT_ALLOWED_REASONS.includes(reason);
+    return transitionOk && reasonOk;
+}
+function transition(currentStatus, newStatus, source, reason, ruleId) {
+    // Validate transition is valid
+    if (!isValidTransition(currentStatus, newStatus)) {
+        throw new Error(`Invalid campaign transition: ${currentStatus} → ${newStatus}. ` +
+            `Valid targets from ${currentStatus}: [${VALID_TRANSITIONS[currentStatus].join(', ')}]`);
+    }
+    // If source is 'agent', validate it's in the allowed set
+    if (source === 'agent' && !isAgentAllowed(currentStatus, newStatus, reason)) {
+        throw new Error(`Agent-initiated transition ${currentStatus} → ${newStatus} (reason: ${reason}) is not authorized. ` +
+            `Agents can only: active → paused with reasons: ${AGENT_ALLOWED_REASONS.join(', ')}`);
+    }
+    return {
+        timestamp: new Date().toISOString(),
+        source,
+        oldStatus: currentStatus,
+        newStatus,
+        reason,
+        ruleId,
+    };
+}
+/**
+ * Create a spend intent (WAL entry) before executing a platform API call.
+ * The intent ID serves as the idempotency key for the platform (ADR-3).
+ */
+function createSpendIntent(intentId, platform, campaignConfig) {
+    return {
+        intentId,
+        platform,
+        campaignConfig,
+        budgetLocked: false,
+        status: 'pending',
+        createdAt: new Date().toISOString(),
+    };
+}
+/**
+ * Lock the budget for a spend intent.
+ * Verifies the daily budget has room for this campaign.
+ * Returns false if budget is exhausted.
+ */
+function lockBudget(intent, dailyBudgetCents, currentDailySpendCents, hardStopCents) {
+    if (currentDailySpendCents + dailyBudgetCents >= hardStopCents) {
+        return false; // Would exceed hard stop
+    }
+    intent.budgetLocked = true;
+    return true;
+}
+/**
+ * Execute the spend intent: WAL → platform API → spend log → campaign record.
+ * Each step is logged. On failure, the intent is marked failed and can be retried.
+ */
+async function executeSpendIntent(intent, platformCall, logSpend) {
+    if (!intent.budgetLocked) {
+        return { success: false, error: 'Budget not locked — call lockBudget() first' };
+    }
+    intent.status = 'executing';
+    try {
+        // Step 1: Call platform API with idempotency key
+        const result = await platformCall();
+        // Step 2: Log to spend log
+        await logSpend(intent.intentId, result.externalId);
+        // Step 3: Mark complete
+        intent.status = 'completed';
+        intent.completedAt = new Date().toISOString();
+        return { success: true, externalId: result.externalId };
+    }
+    catch (err) {
+        intent.status = 'failed';
+        intent.error = String(err);
+        return { success: false, error: String(err) };
+    }
+}
+export { VALID_TRANSITIONS, AGENT_ALLOWED_TRANSITIONS, AGENT_ALLOWED_REASONS, isValidTransition, isAgentAllowed, transition, createSpendIntent, lockBudget, executeSpendIntent, };

package/dist/wizard/lib/ci-generator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * GitHub Actions CI/CD workflow generator (ADR-017).
+ * Generates ci.yml (test + lint on PR) and deploy.yml (deploy on merge to main).
+ * Framework-aware: Node → npm test, Django → pytest, Rails → rspec.
+ */
+export interface CIGeneratorResult {
+    success: boolean;
+    files: string[];
+    error?: string;
+}
+/**
+ * Generate CI/CD workflow files in the project's .github/workflows/ directory.
+ */
+export declare function generateCIWorkflows(projectDir: string, framework: string, deployTarget: string): Promise<CIGeneratorResult>;

package/dist/wizard/lib/ci-generator.js

@@ -0,0 +1,187 @@
+/**
+ * GitHub Actions CI/CD workflow generator (ADR-017).
+ * Generates ci.yml (test + lint on PR) and deploy.yml (deploy on merge to main).
+ * Framework-aware: Node → npm test, Django → pytest, Rails → rspec.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getBuildOutputDir } from './build-step.js';
+const FRAMEWORK_CI = {
+    'next.js': { runtime: 'node', buildCommand: 'npm run build', testCommand: 'npm run test --if-present', lintCommand: 'npm run lint --if-present' },
+    'express': { runtime: 'node', buildCommand: 'npm run build', testCommand: 'npm run test --if-present', lintCommand: 'npm run lint --if-present' },
+    'vite': { runtime: 'node', buildCommand: 'npm run build', testCommand: 'npm run test --if-present', lintCommand: 'npm run lint --if-present' },
+    'nuxt': { runtime: 'node', buildCommand: 'npm run build', testCommand: 'npm run test --if-present', lintCommand: 'npm run lint --if-present' },
+    'remix': { runtime: 'node', buildCommand: 'npm run build', testCommand: 'npm run test --if-present', lintCommand: 'npm run lint --if-present' },
+    'svelte': { runtime: 'node', buildCommand: 'npm run build', testCommand: 'npm run test --if-present', lintCommand: 'npm run lint --if-present' },
+    'sveltekit': { runtime: 'node', buildCommand: 'npm run build', testCommand: 'npm run test --if-present', lintCommand: 'npm run lint --if-present' },
+    'astro': { runtime: 'node', buildCommand: 'npm run build', testCommand: 'npm run test --if-present', lintCommand: 'npm run lint --if-present' },
+    'gatsby': { runtime: 'node', buildCommand: 'npm run build', testCommand: 'npm run test --if-present', lintCommand: 'npm run lint --if-present' },
+    'django': { runtime: 'python', installCommand: 'pip install -r requirements.txt', buildCommand: 'python manage.py collectstatic --noinput', testCommand: 'pytest', lintCommand: 'flake8 --max-line-length=120 || true' },
+    'flask': { runtime: 'python', installCommand: 'pip install -r requirements.txt', testCommand: 'pytest', lintCommand: 'flake8 --max-line-length=120 || true' },
+    'rails': { runtime: 'ruby', installCommand: 'bundle install', buildCommand: 'bundle exec rails assets:precompile', testCommand: 'bundle exec rspec', lintCommand: 'bundle exec rubocop --format simple || true' },
+};
+/** Check if a framework has an explicit build command (not a default fallback). */
+function hasBuildCommand(framework) {
+    return !!(FRAMEWORK_CI[framework]?.buildCommand);
+}
+function resolveConfig(framework) {
+    const partial = FRAMEWORK_CI[framework] || {};
+    return {
+        runtime: partial.runtime || 'node',
+        nodeVersion: '20',
+        pythonVersion: '3.12',
+        rubyVersion: '3.3',
+        installCommand: partial.installCommand || 'npm ci',
+        buildCommand: partial.buildCommand || 'npm run build',
+        testCommand: partial.testCommand || 'npm run test --if-present',
+        lintCommand: partial.lintCommand || 'npm run lint --if-present',
+    };
+}
+function generateSetupSteps(config) {
+    switch (config.runtime) {
+        case 'python':
+            return `      - uses: actions/setup-python@v5
+        with:
+          python-version: '${config.pythonVersion}'
+      - run: ${config.installCommand}`;
+        case 'ruby':
+            return `      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '${config.rubyVersion}'
+          bundler-cache: true`;
+        default:
+            return `      - uses: actions/setup-node@v4
+        with:
+          node-version: '${config.nodeVersion}'
+          cache: 'npm'
+      - run: npm ci`;
+    }
+}
+function generateCIWorkflow(framework) {
+    const config = resolveConfig(framework);
+    const setup = generateSetupSteps(config);
+    return `# CI — test + lint on pull request
+# Generated by VoidForge (ADR-017)
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+${setup}
+      - run: ${config.testCommand}
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+${setup}
+      - run: ${config.lintCommand}
+`;
+}
+/** Map deploy targets to their required GitHub secrets for documentation. */
+const DEPLOY_SECRETS = {
+    vercel: ['VERCEL_TOKEN', 'VERCEL_ORG_ID', 'VERCEL_PROJECT_ID'],
+    cloudflare: ['CLOUDFLARE_API_TOKEN', 'CF_PROJECT_NAME'],
+    railway: [],
+    vps: ['SSH_PRIVATE_KEY', 'SSH_USER', 'SSH_HOST'],
+    static: ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_REGION', 'S3_BUCKET'],
+};
+function generateDeployWorkflow(framework, deployTarget) {
+    const config = resolveConfig(framework);
+    const setup = generateSetupSteps(config);
+    let deployStep;
+    switch (deployTarget) {
+        case 'vercel':
+            deployStep = `      - uses: amondnet/vercel-action@v25
+        with:
+          vercel-token: \${{ secrets.VERCEL_TOKEN }}
+          vercel-org-id: \${{ secrets.VERCEL_ORG_ID }}
+          vercel-project-id: \${{ secrets.VERCEL_PROJECT_ID }}
+          vercel-args: '--prod'`;
+            break;
+        case 'cloudflare': {
+            const cfOutputDir = getBuildOutputDir(framework);
+            deployStep = `      - uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: \${{ secrets.CLOUDFLARE_API_TOKEN }}
+          command: pages deploy ./${cfOutputDir} --project-name=\${{ secrets.CF_PROJECT_NAME }}`;
+            break;
+        }
+        case 'railway':
+            deployStep = `      # Railway auto-deploys on push — this job just verifies the build
+      - run: echo "Railway auto-deploy triggered by push to main"`;
+            break;
+        case 'vps': {
+            const vpsBuild = config.runtime === 'python'
+                ? 'pip install -r requirements.txt && python manage.py collectstatic --noinput && sudo systemctl restart gunicorn'
+                : config.runtime === 'ruby'
+                    ? 'bundle install && bundle exec rails assets:precompile && sudo systemctl restart puma'
+                    : 'npm ci && npm run build && pm2 restart all';
+            deployStep = `      - run: |
+          mkdir -p ~/.ssh
+          echo "\${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/deploy-key.pem
+          chmod 600 ~/.ssh/deploy-key.pem
+          ssh -i ~/.ssh/deploy-key.pem -o StrictHostKeyChecking=accept-new \${{ secrets.SSH_USER }}@\${{ secrets.SSH_HOST }} "cd /opt/app/current && git pull && ${vpsBuild}"
+          rm -f ~/.ssh/deploy-key.pem`;
+            break;
+        }
+        case 'static': {
+            const s3OutputDir = getBuildOutputDir(framework);
+            deployStep = `      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: \${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: \${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: \${{ secrets.AWS_REGION }}
+      - run: aws s3 sync ./${s3OutputDir} s3://\${{ secrets.S3_BUCKET }} --delete`;
+            break;
+        }
+        default:
+            deployStep = `      - run: echo "Deploy step not configured for target: ${deployTarget}"`;
+    }
+    const secrets = DEPLOY_SECRETS[deployTarget] || [];
+    const secretsDoc = secrets.length > 0
+        ? `# Required secrets (set in GitHub repo > Settings > Secrets and variables > Actions):\n${secrets.map(s => `#   - ${s}`).join('\n')}\n`
+        : '';
+    return `# Deploy — build and deploy on merge to main
+# Generated by VoidForge (ADR-017)
+${secretsDoc}name: Deploy
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+${setup}
+${hasBuildCommand(framework) ? `      - run: ${config.buildCommand}\n` : ''}${deployStep}
+`;
+}
+/**
+ * Generate CI/CD workflow files in the project's .github/workflows/ directory.
+ */
+export async function generateCIWorkflows(projectDir, framework, deployTarget) {
+    const workflowDir = join(projectDir, '.github', 'workflows');
+    const files = [];
+    try {
+        await mkdir(workflowDir, { recursive: true });
+        const ciContent = generateCIWorkflow(framework);
+        await writeFile(join(workflowDir, 'ci.yml'), ciContent, 'utf-8');
+        files.push('.github/workflows/ci.yml');
+        const deployContent = generateDeployWorkflow(framework, deployTarget);
+        await writeFile(join(workflowDir, 'deploy.yml'), deployContent, 'utf-8');
+        files.push('.github/workflows/deploy.yml');
+        return { success: true, files };
+    }
+    catch (err) {
+        return { success: false, files, error: err.message };
+    }
+}

package/dist/wizard/lib/claude-merge.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CLAUDE.md Merge Utility — Safe append of project directives.
+ *
+ * Merges project-specific directives into VoidForge's CLAUDE.md by
+ * appending them under a clearly marked section. Never replaces the
+ * methodology content. Idempotent — won't duplicate if run multiple times.
+ *
+ * PRD Reference: RFC-blueprint-path.md
+ */
+export interface MergeResult {
+    merged: boolean;
+    reason: string;
+    claudeMdPath: string;
+    directivesPath: string;
+}
+/**
+ * Append project directives to CLAUDE.md.
+ *
+ * Rules:
+ * - VoidForge's CLAUDE.md content is NEVER replaced
+ * - Project directives are appended under a clear marker section
+ * - Idempotent: if the marker already exists, the merge is skipped
+ * - The source directive file path is recorded in the merged section
+ *
+ * @param projectRoot - The project's root directory
+ * @param directivesRelativePath - Relative path to the directives file (e.g., 'docs/PROJECT-DIRECTIVES.md')
+ * @returns MergeResult describing what happened
+ */
+export declare function mergeProjectDirectives(projectRoot: string, directivesRelativePath: string): Promise<MergeResult>;
+/**
+ * Check if project directives have already been merged into CLAUDE.md.
+ */
+export declare function isAlreadyMerged(projectRoot: string): Promise<boolean>;
+/**
+ * Remove previously merged project directives from CLAUDE.md.
+ * Useful for re-merging with updated directives.
+ */
+export declare function unmergeProjectDirectives(projectRoot: string): Promise<boolean>;