@devtrack-solution/codesdd 1.2.2 → 1.2.4-rc3

package/dist/core/sdd/parallel-feat-automation.js

@@ -0,0 +1,424 @@
+import { z } from 'zod';
+const FEATURE_REF_PATTERN = /^FEAT-\d{4}$/;
+const featureRefSchema = z.string().regex(FEATURE_REF_PATTERN);
+const sddPolicyPathSchema = z
+    .string()
+    .min(1)
+    .refine((value) => value === '.sdd' || value.startsWith('.sdd/'), {
+    message: 'Execution plans may only declare writes inside the canonical .sdd boundary.',
+});
+const agentProviderSchema = z.enum([
+    'codex',
+    'opencode',
+    'claude-code',
+    'cloudcode',
+    'deepagents',
+    'fake',
+]);
+export const parallelFeatStateBoundarySchema = z.object({
+    id: z.literal('codesdd-canonical-sdd-state'),
+    canonical_state_glob: z.literal('.sdd/state/*.yaml'),
+    project_state_root: z.literal('.sdd'),
+    hidden_state_allowed: z.literal(false),
+    external_state_allowed: z.literal(false),
+});
+export const PARALLEL_FEAT_STATE_BOUNDARY = {
+    id: 'codesdd-canonical-sdd-state',
+    canonical_state_glob: '.sdd/state/*.yaml',
+    project_state_root: '.sdd',
+    hidden_state_allowed: false,
+    external_state_allowed: false,
+};
+export const parallelFeatAutomationFeatureSchema = z.object({
+    feature_ref: featureRefSchema,
+    title: z.string().min(3),
+    recommended_skills: z.array(z.string().min(1)).default([]),
+    lock_domains: z.array(z.string().min(1)).default([]),
+});
+export const parallelFeatSchedulerFeatureSchema = parallelFeatAutomationFeatureSchema.extend({
+    blocked_by: z.array(featureRefSchema).default([]),
+    status: z.enum(['READY', 'IN_PROGRESS', 'BLOCKED', 'DONE']).default('READY'),
+});
+export const parallelFeatAutomationRequestSchema = z
+    .object({
+    schema_version: z.literal(1).default(1),
+    generated_at: z.string().datetime().optional(),
+    max_agents: z.number().int().min(1).max(10).default(5),
+    require_clean_worktree: z.boolean().default(true),
+    require_commit_per_feature: z.boolean().default(true),
+    require_finalize_before_commit: z.boolean().default(true),
+    agent_provider: agentProviderSchema.optional(),
+    features: z.array(parallelFeatAutomationFeatureSchema).default([]),
+    waves: z.array(z.array(featureRefSchema).min(1)).default([]),
+})
+    .superRefine((request, context) => {
+    const featureRefs = new Set(request.features.map((feature) => feature.feature_ref));
+    const seenWaveRefs = new Set();
+    for (const [waveIndex, wave] of request.waves.entries()) {
+        for (const [featureIndex, featureRef] of wave.entries()) {
+            if (!featureRefs.has(featureRef)) {
+                context.addIssue({
+                    code: 'custom',
+                    path: ['waves', waveIndex, featureIndex],
+                    message: `Wave references unknown feature ${featureRef}.`,
+                });
+            }
+            if (seenWaveRefs.has(featureRef)) {
+                context.addIssue({
+                    code: 'custom',
+                    path: ['waves', waveIndex, featureIndex],
+                    message: `Feature ${featureRef} appears in more than one wave.`,
+                });
+            }
+            seenWaveRefs.add(featureRef);
+        }
+    }
+});
+export const parallelFeatSchedulerRequestSchema = z
+    .object({
+    schema_version: z.literal(1).default(1),
+    generated_at: z.string().datetime().optional(),
+    max_agents: z.number().int().min(1).max(10).default(5),
+    require_clean_worktree: z.boolean().default(true),
+    require_commit_per_feature: z.boolean().default(true),
+    require_finalize_before_commit: z.boolean().default(true),
+    agent_provider: agentProviderSchema.optional(),
+    features: z.array(parallelFeatSchedulerFeatureSchema).default([]),
+})
+    .superRefine((request, context) => {
+    const seenFeatureRefs = new Set();
+    for (const [featureIndex, feature] of request.features.entries()) {
+        if (seenFeatureRefs.has(feature.feature_ref)) {
+            context.addIssue({
+                code: 'custom',
+                path: ['features', featureIndex, 'feature_ref'],
+                message: `Feature ${feature.feature_ref} appears more than once.`,
+            });
+        }
+        seenFeatureRefs.add(feature.feature_ref);
+    }
+});
+export const parallelFeatAutomationStepSchema = z.object({
+    feature_ref: featureRefSchema,
+    title: z.string().min(3),
+    sequence: z.number().int().positive(),
+    delegation: z.object({
+        mode: z.enum(['local-codex', 'agent-adapter']),
+        provider: agentProviderSchema.optional(),
+    }),
+    commands: z.array(z.string().min(1)).min(1),
+    commit_boundary: z.object({
+        clean_worktree_required: z.boolean(),
+        finalize_before_commit: z.boolean(),
+        commit_per_feature: z.boolean(),
+        commit_message: z.string().min(1),
+    }),
+    state_boundary_ref: z.literal('codesdd-canonical-sdd-state'),
+    allowed_state_writes: z.array(sddPolicyPathSchema).min(1),
+    forbidden_state_writes: z.array(z.string().min(1)).default(['.codesdd/**', 'external-context/**']),
+    evidence_required: z.array(z.string().min(1)).default([]),
+});
+export const parallelFeatAutomationWaveSchema = z.object({
+    wave_index: z.number().int().positive(),
+    max_parallel: z.number().int().positive(),
+    status: z.enum(['ready', 'blocked']),
+    conflicts: z.array(z.string()).default([]),
+    steps: z.array(parallelFeatAutomationStepSchema).default([]),
+});
+export const parallelFeatAutomationPlanSchema = z.object({
+    schema_version: z.literal(1),
+    generated_at: z.string().datetime(),
+    status: z.enum(['ready', 'blocked', 'empty']),
+    max_agents: z.number().int().positive(),
+    state_boundary: parallelFeatStateBoundarySchema,
+    write_policy: z.object({
+        allowed_root: z.literal('.sdd'),
+        canonical_state_glob: z.literal('.sdd/state/*.yaml'),
+        hidden_state_allowed: z.literal(false),
+        external_state_allowed: z.literal(false),
+    }),
+    rules: z.array(z.string().min(1)).default([]),
+    waves: z.array(parallelFeatAutomationWaveSchema).default([]),
+    summary: z.object({
+        feature_count: z.number().int().nonnegative(),
+        wave_count: z.number().int().nonnegative(),
+        blocked_wave_count: z.number().int().nonnegative(),
+    }),
+});
+export const parallelFeatSchedulerBlockedFeatureSchema = z.object({
+    feature_ref: featureRefSchema,
+    blocked_by: z.array(featureRefSchema).default([]),
+    reason: z.string().min(1),
+});
+export const parallelFeatSchedulerResultSchema = z.object({
+    schema_version: z.literal(1),
+    generated_at: z.string().datetime(),
+    status: z.enum(['ready', 'blocked', 'empty']),
+    plan: parallelFeatAutomationPlanSchema,
+    blocked_features: z.array(parallelFeatSchedulerBlockedFeatureSchema).default([]),
+    summary: z.object({
+        feature_count: z.number().int().nonnegative(),
+        scheduled_feature_count: z.number().int().nonnegative(),
+        done_feature_count: z.number().int().nonnegative(),
+        blocked_feature_count: z.number().int().nonnegative(),
+        wave_count: z.number().int().nonnegative(),
+    }),
+});
+export function buildParallelFeatAutomationPlan(input) {
+    const request = parallelFeatAutomationRequestSchema.parse(input);
+    const generatedAt = request.generated_at ?? new Date().toISOString();
+    const featureMap = new Map(request.features.map((feature) => [feature.feature_ref, feature]));
+    const normalizedWaves = normalizeWaves(request);
+    if (request.features.length === 0) {
+        return parallelFeatAutomationPlanSchema.parse({
+            schema_version: 1,
+            generated_at: generatedAt,
+            status: 'empty',
+            max_agents: request.max_agents,
+            state_boundary: PARALLEL_FEAT_STATE_BOUNDARY,
+            write_policy: buildWritePolicy(),
+            rules: automationRules(request),
+            waves: [],
+            summary: {
+                feature_count: 0,
+                wave_count: 0,
+                blocked_wave_count: 0,
+            },
+        });
+    }
+    const waves = normalizedWaves.map((waveRefs, index) => {
+        const features = waveRefs.map((featureRef) => featureMap.get(featureRef));
+        const conflicts = detectLockConflicts(features, index + 1);
+        return parallelFeatAutomationWaveSchema.parse({
+            wave_index: index + 1,
+            max_parallel: Math.min(request.max_agents, features.length),
+            status: conflicts.length > 0 ? 'blocked' : 'ready',
+            conflicts,
+            steps: features.map((feature, featureIndex) => buildStep(feature, featureIndex + 1, request)),
+        });
+    });
+    const blockedWaveCount = waves.filter((wave) => wave.status === 'blocked').length;
+    return parallelFeatAutomationPlanSchema.parse({
+        schema_version: 1,
+        generated_at: generatedAt,
+        status: blockedWaveCount > 0 ? 'blocked' : 'ready',
+        max_agents: request.max_agents,
+        state_boundary: PARALLEL_FEAT_STATE_BOUNDARY,
+        write_policy: buildWritePolicy(),
+        rules: automationRules(request),
+        waves,
+        summary: {
+            feature_count: request.features.length,
+            wave_count: waves.length,
+            blocked_wave_count: blockedWaveCount,
+        },
+    });
+}
+export function scheduleChainedFeatWaves(input) {
+    const request = parallelFeatSchedulerRequestSchema.parse(input);
+    const generatedAt = request.generated_at ?? new Date().toISOString();
+    const doneFeatureRefs = new Set(request.features
+        .filter((feature) => feature.status === 'DONE')
+        .map((feature) => feature.feature_ref));
+    const pendingFeatures = request.features.filter((feature) => feature.status !== 'DONE');
+    if (pendingFeatures.length === 0) {
+        const plan = buildParallelFeatAutomationPlan({
+            ...request,
+            generated_at: generatedAt,
+            features: [],
+            waves: [],
+        });
+        return parallelFeatSchedulerResultSchema.parse({
+            schema_version: 1,
+            generated_at: generatedAt,
+            status: 'empty',
+            plan,
+            blocked_features: [],
+            summary: {
+                feature_count: request.features.length,
+                scheduled_feature_count: 0,
+                done_feature_count: doneFeatureRefs.size,
+                blocked_feature_count: 0,
+                wave_count: 0,
+            },
+        });
+    }
+    const featureMap = new Map(request.features.map((feature) => [feature.feature_ref, feature]));
+    const scheduledFeatureRefs = new Set(doneFeatureRefs);
+    const unscheduled = new Map(pendingFeatures.map((feature) => [feature.feature_ref, feature]));
+    const waves = [];
+    while (unscheduled.size > 0) {
+        const candidates = [...unscheduled.values()].filter((feature) => getBlockingDependencies(feature, scheduledFeatureRefs, featureMap).length === 0);
+        if (candidates.length === 0) {
+            break;
+        }
+        const wave = selectConflictFreeWave(candidates, request.max_agents);
+        waves.push(wave.map((feature) => feature.feature_ref));
+        for (const feature of wave) {
+            scheduledFeatureRefs.add(feature.feature_ref);
+            unscheduled.delete(feature.feature_ref);
+        }
+    }
+    const scheduledFeatures = waves
+        .flat()
+        .map((featureRef) => featureMap.get(featureRef));
+    const blockedFeatures = [...unscheduled.values()].map((feature) => {
+        const blockedBy = getBlockingDependencies(feature, scheduledFeatureRefs, featureMap);
+        return parallelFeatSchedulerBlockedFeatureSchema.parse({
+            feature_ref: feature.feature_ref,
+            blocked_by: blockedBy,
+            reason: blockedBy.length > 0
+                ? `Waiting for unscheduled dependencies: ${blockedBy.join(', ')}.`
+                : 'Deferred because no dependency-safe execution slot was available.',
+        });
+    });
+    const plan = buildParallelFeatAutomationPlan({
+        ...request,
+        generated_at: generatedAt,
+        features: scheduledFeatures.map(toAutomationFeature),
+        waves,
+    });
+    return parallelFeatSchedulerResultSchema.parse({
+        schema_version: 1,
+        generated_at: generatedAt,
+        status: blockedFeatures.length > 0 ? 'blocked' : plan.status,
+        plan,
+        blocked_features: blockedFeatures,
+        summary: {
+            feature_count: request.features.length,
+            scheduled_feature_count: scheduledFeatures.length,
+            done_feature_count: doneFeatureRefs.size,
+            blocked_feature_count: blockedFeatures.length,
+            wave_count: waves.length,
+        },
+    });
+}
+function normalizeWaves(request) {
+    const sourceWaves = request.waves.length > 0
+        ? request.waves
+        : [request.features.map((feature) => feature.feature_ref)];
+    return sourceWaves.flatMap((wave) => chunk(wave, request.max_agents));
+}
+function chunk(values, size) {
+    const chunks = [];
+    for (let index = 0; index < values.length; index += size) {
+        chunks.push(values.slice(index, index + size));
+    }
+    return chunks;
+}
+function buildStep(feature, sequence, request) {
+    const provider = request.agent_provider;
+    return parallelFeatAutomationStepSchema.parse({
+        feature_ref: feature.feature_ref,
+        title: feature.title,
+        sequence,
+        delegation: provider
+            ? {
+                mode: 'agent-adapter',
+                provider,
+            }
+            : {
+                mode: 'local-codex',
+            },
+        commands: [
+            `codesdd sdd start ${feature.feature_ref}`,
+            `codesdd sdd context ${feature.feature_ref}`,
+            'pnpm run build',
+            'pnpm run lint',
+            'pnpm test',
+            'pnpm run test:e2e',
+            'pnpm run sdd:validate',
+            `codesdd sdd frontend-impact ${feature.feature_ref} --status none --reason "No frontend impact declared by automation plan; revise to required when UI surfaces change."`,
+            `codesdd sdd finalize --ref ${feature.feature_ref}`,
+        ],
+        commit_boundary: {
+            clean_worktree_required: request.require_clean_worktree,
+            finalize_before_commit: request.require_finalize_before_commit,
+            commit_per_feature: request.require_commit_per_feature,
+            commit_message: `feat(sdd): execute ${feature.feature_ref.toLowerCase()}`,
+        },
+        state_boundary_ref: 'codesdd-canonical-sdd-state',
+        allowed_state_writes: [
+            `.sdd/active/${feature.feature_ref}/`,
+            `.sdd/archived/${feature.feature_ref}/`,
+            '.sdd/state/backlog.yaml',
+            '.sdd/state/finalize-queue.yaml',
+            '.sdd/state/transition-log.yaml',
+        ],
+        forbidden_state_writes: ['.codesdd/**', 'external-context/**'],
+        evidence_required: [
+            'focused_coverage',
+            'build',
+            'lint',
+            'full_tests',
+            'e2e',
+            'sdd_validate',
+            'frontend_impact',
+            'commit_hash',
+        ],
+    });
+}
+function buildWritePolicy() {
+    return {
+        allowed_root: '.sdd',
+        canonical_state_glob: '.sdd/state/*.yaml',
+        hidden_state_allowed: false,
+        external_state_allowed: false,
+    };
+}
+function automationRules(request) {
+    return [
+        'state_boundary=codesdd-canonical-sdd-state',
+        `max_agents=${request.max_agents}`,
+        `clean_worktree_required=${request.require_clean_worktree}`,
+        `commit_per_feature=${request.require_commit_per_feature}`,
+        `finalize_before_commit=${request.require_finalize_before_commit}`,
+        request.agent_provider ? `agent_provider=${request.agent_provider}` : 'agent_provider=local-codex',
+    ];
+}
+function detectLockConflicts(features, waveIndex) {
+    const ownersByLock = new Map();
+    for (const feature of features) {
+        for (const lockDomain of feature.lock_domains) {
+            ownersByLock.set(lockDomain, [...(ownersByLock.get(lockDomain) ?? []), feature.feature_ref]);
+        }
+    }
+    return [...ownersByLock.entries()]
+        .filter(([, owners]) => owners.length > 1)
+        .map(([lockDomain, owners]) => `wave ${waveIndex} lock ${lockDomain} shared by ${owners.join(', ')}`);
+}
+function getBlockingDependencies(feature, scheduledFeatureRefs, featureMap) {
+    return feature.blocked_by.filter((dependencyRef) => {
+        if (scheduledFeatureRefs.has(dependencyRef)) {
+            return false;
+        }
+        return featureMap.has(dependencyRef) || !scheduledFeatureRefs.has(dependencyRef);
+    });
+}
+function selectConflictFreeWave(candidates, maxAgents) {
+    const selected = [];
+    const selectedLockDomains = new Set();
+    for (const candidate of candidates) {
+        if (selected.length >= maxAgents) {
+            break;
+        }
+        const hasLockConflict = candidate.lock_domains.some((lockDomain) => selectedLockDomains.has(lockDomain));
+        if (hasLockConflict) {
+            continue;
+        }
+        selected.push(candidate);
+        for (const lockDomain of candidate.lock_domains) {
+            selectedLockDomains.add(lockDomain);
+        }
+    }
+    return selected;
+}
+function toAutomationFeature(feature) {
+    return {
+        feature_ref: feature.feature_ref,
+        title: feature.title,
+        recommended_skills: feature.recommended_skills,
+        lock_domains: feature.lock_domains,
+    };
+}
+//# sourceMappingURL=parallel-feat-automation.js.map