@ai-sdlc/orchestrator 0.5.0 → 0.6.0

package/dist/action-enforcement.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Action enforcement — checks shell commands against blockedActions
+ * patterns from AgentRole constraints. Prevents agents from executing
+ * dangerous operations like merging PRs, force-pushing, or dismissing reviews.
+ */
+import type { AuditLog } from '@ai-sdlc/reference';
+export interface ActionEnforcementResult {
+    allowed: boolean;
+    /** The pattern that matched, if blocked. */
+    matchedPattern?: string;
+    /** The full command that was checked. */
+    command: string;
+}
+/**
+ * Check if a shell command is allowed by the blocked actions policy.
+ */
+export declare function checkAction(command: string, blockedActions: string[]): ActionEnforcementResult;
+/**
+ * Check an action and record the result in the audit log if blocked.
+ */
+export declare function enforceAction(command: string, blockedActions: string[], auditLog?: AuditLog, agentName?: string): ActionEnforcementResult;
+/**
+ * Default blocked actions for all agents.
+ */
+export declare const DEFAULT_BLOCKED_ACTIONS: string[];
+//# sourceMappingURL=action-enforcement.d.ts.map

package/dist/action-enforcement.js

@@ -0,0 +1,70 @@
+/**
+ * Action enforcement — checks shell commands against blockedActions
+ * patterns from AgentRole constraints. Prevents agents from executing
+ * dangerous operations like merging PRs, force-pushing, or dismissing reviews.
+ */
+/**
+ * Convert a glob-like blocked action pattern to a regex.
+ * Supports * (any characters) anywhere in the pattern.
+ */
+function patternToRegex(pattern) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+    const regexStr = escaped.replace(/\*/g, '.*');
+    return new RegExp(`^${regexStr}$`, 'i');
+}
+/**
+ * Check if a shell command is allowed by the blocked actions policy.
+ */
+export function checkAction(command, blockedActions) {
+    const trimmed = command.trim();
+    if (!trimmed)
+        return { allowed: true, command: trimmed };
+    for (const pattern of blockedActions) {
+        const regex = patternToRegex(pattern);
+        if (regex.test(trimmed)) {
+            return {
+                allowed: false,
+                matchedPattern: pattern,
+                command: trimmed,
+            };
+        }
+    }
+    return { allowed: true, command: trimmed };
+}
+/**
+ * Check an action and record the result in the audit log if blocked.
+ */
+export function enforceAction(command, blockedActions, auditLog, agentName) {
+    const result = checkAction(command, blockedActions);
+    if (!result.allowed && auditLog) {
+        auditLog.record({
+            actor: agentName ?? 'agent',
+            action: 'execute',
+            resource: `command/${result.command.slice(0, 100)}`,
+            decision: 'denied',
+            details: {
+                reason: 'blocked-action',
+                pattern: result.matchedPattern,
+                command: result.command,
+            },
+        });
+    }
+    return result;
+}
+/**
+ * Default blocked actions for all agents.
+ */
+export const DEFAULT_BLOCKED_ACTIONS = [
+    'gh pr merge*',
+    'git merge*',
+    'git push --force*',
+    'git push -f*',
+    'gh pr close*',
+    'gh issue close*',
+    'git branch -D*',
+    'git branch -d*',
+    'git reset --hard*',
+    'git checkout -- .',
+    'git restore .',
+];
+//# sourceMappingURL=action-enforcement.js.map

package/dist/admission-score.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Issue admission scoring — maps GitHub issue fields to PPA dimensions
+ * and determines whether an issue should enter the pipeline.
+ *
+ * Extracted from dogfood/scripts/ppa-score.ts for reuse across CLI
+ * scripts and workflows.
+ */
+import { type PriorityInput, type PriorityScore, type PriorityConfig } from './priority.js';
+/**
+ * GitHub author_association values indicating trust level.
+ * OWNER/MEMBER/COLLABORATOR = trusted (project team)
+ * CONTRIBUTOR = semi-trusted (has had PRs merged)
+ * NONE = untrusted (external)
+ */
+export type AuthorAssociation = 'OWNER' | 'MEMBER' | 'COLLABORATOR' | 'CONTRIBUTOR' | 'FIRST_TIMER' | 'FIRST_TIME_CONTRIBUTOR' | 'NONE';
+export interface AdmissionInput {
+    issueNumber: number;
+    title: string;
+    body: string;
+    labels: string[];
+    /** Total thumbsUp + heart reactions. */
+    reactionCount: number;
+    /** Number of human comments. */
+    commentCount: number;
+    /** ISO timestamp of issue creation. */
+    createdAt: string;
+    /** GitHub author_association — determines trust-based signal boosting. */
+    authorAssociation?: AuthorAssociation;
+}
+export interface AdmissionThresholds {
+    minimumScore: number;
+    minimumConfidence: number;
+}
+export interface IssueAdmissionResult {
+    admitted: boolean;
+    score: PriorityScore;
+    reason: string;
+    suggestions?: string[];
+}
+/**
+ * Map GitHub issue fields to PPA PriorityInput dimensions.
+ *
+ * Heuristics (ported from dogfood/scripts/ppa-score.ts):
+ * - Labels → bug severity, soul alignment hints, builder conviction
+ * - Reactions → team consensus, customer request count
+ * - Comments → demand signal
+ * - Body complexity section → complexity score
+ * - Issue age → competitive drift
+ */
+export declare function mapIssueToPriorityInput(input: AdmissionInput): PriorityInput;
+/**
+ * Score a GitHub issue for pipeline admission using the Product Priority Algorithm.
+ *
+ * Returns whether the issue is admitted (score and confidence above thresholds)
+ * along with the full score and, if rejected, suggestions for improvement.
+ */
+export declare function scoreIssueForAdmission(input: AdmissionInput, thresholds: AdmissionThresholds, priorityConfig?: PriorityConfig): IssueAdmissionResult;
+//# sourceMappingURL=admission-score.d.ts.map

package/dist/admission-score.js

@@ -0,0 +1,164 @@
+/**
+ * Issue admission scoring — maps GitHub issue fields to PPA dimensions
+ * and determines whether an issue should enter the pipeline.
+ *
+ * Extracted from dogfood/scripts/ppa-score.ts for reuse across CLI
+ * scripts and workflows.
+ */
+import { computePriority, } from './priority.js';
+// ── Mapping ──────────────────────────────────────────────────────────
+/**
+ * Map GitHub issue fields to PPA PriorityInput dimensions.
+ *
+ * Heuristics (ported from dogfood/scripts/ppa-score.ts):
+ * - Labels → bug severity, soul alignment hints, builder conviction
+ * - Reactions → team consensus, customer request count
+ * - Comments → demand signal
+ * - Body complexity section → complexity score
+ * - Issue age → competitive drift
+ */
+export function mapIssueToPriorityInput(input) {
+    const labels = input.labels;
+    const assoc = input.authorAssociation ?? 'NONE';
+    // ── Trust-based signal boosting ────────────────────────────────
+    // Trusted sources (project team) get baseline conviction and demand.
+    // Untrusted sources need external validation (reactions, comments).
+    const isTrusted = assoc === 'OWNER' || assoc === 'MEMBER' || assoc === 'COLLABORATOR';
+    const isContributor = assoc === 'CONTRIBUTOR';
+    // ── Complexity from issue body ───────────────────────────────
+    const complexityMatch = input.body?.match(/###?\s*Complexity\s*\n+\s*(\d+)/i);
+    const complexity = complexityMatch ? Number(complexityMatch[1]) : undefined;
+    // ── Bug severity from labels ─────────────────────────────────
+    let bugSeverity;
+    if (labels.includes('critical') || labels.includes('P0'))
+        bugSeverity = 5;
+    else if (labels.includes('bug'))
+        bugSeverity = 3;
+    // ── Soul alignment heuristic from labels ─────────────────────
+    let soulAlignment = 0.5;
+    if (labels.includes('security') || labels.includes('security-triage'))
+        soulAlignment = 0.7;
+    if (labels.includes('enhancement'))
+        soulAlignment = 0.6;
+    if (labels.includes('governance') || labels.includes('compliance'))
+        soulAlignment = 0.85;
+    if (labels.includes('spec') || labels.includes('rfc'))
+        soulAlignment = 0.9;
+    // Trusted authors get a soul alignment floor — they know the project mission
+    if (isTrusted && soulAlignment < 0.6)
+        soulAlignment = 0.6;
+    // ── Reactions → demand / consensus ───────────────────────────
+    const reactionConsensus = Math.min(1, input.reactionCount / 5);
+    // Trusted sources carry implicit team consensus
+    const teamConsensus = isTrusted ? Math.max(0.5, reactionConsensus) : reactionConsensus;
+    // ── Comment count → demand signal ────────────────────────────
+    const commentDemand = Math.min(1, input.commentCount / 5);
+    // Trusted sources filing an issue IS demand — they wouldn't file it otherwise
+    const demandSignal = isTrusted
+        ? Math.max(0.4, commentDemand)
+        : isContributor
+            ? Math.max(0.2, commentDemand)
+            : commentDemand;
+    // ── Builder conviction ─────────────────────────────────────────
+    // Trusted: high conviction (they're the builders)
+    // Contributor: moderate (proven track record)
+    // ai-eligible label: explicit signal
+    // Default: low (needs validation)
+    const builderConviction = labels.includes('ai-eligible')
+        ? 0.8
+        : isTrusted
+            ? 0.8
+            : isContributor
+                ? 0.6
+                : 0.4;
+    // ── Age → competitive drift ──────────────────────────────────
+    const ageMs = Date.now() - new Date(input.createdAt).getTime();
+    const ageDays = ageMs / (1000 * 60 * 60 * 24);
+    const competitiveDrift = Math.min(1, Math.max(0, (ageDays - 30) / 180));
+    // ── Security-rejected veto ───────────────────────────────────
+    if (labels.includes('security-rejected')) {
+        return {
+            itemId: `#${input.issueNumber}`,
+            title: input.title,
+            description: input.body ?? '',
+            labels,
+            soulAlignment: 0, // veto
+        };
+    }
+    return {
+        itemId: `#${input.issueNumber}`,
+        title: input.title,
+        description: input.body ?? '',
+        labels,
+        soulAlignment,
+        bugSeverity,
+        customerRequestCount: input.reactionCount,
+        demandSignal,
+        builderConviction,
+        complexity,
+        competitiveDrift,
+        teamConsensus,
+        explicitPriority: labels.includes('high') ? 0.8 : labels.includes('low') ? 0.2 : undefined,
+    };
+}
+// ── Suggestions ──────────────────────────────────────────────────────
+function generateSuggestions(input, score) {
+    const suggestions = [];
+    const d = score.dimensions;
+    if (score.confidence < 0.2) {
+        suggestions.push('Add more detail to improve scoring confidence (complexity, acceptance criteria, labels)');
+    }
+    if (!input.body?.match(/###?\s*Complexity\s*\n/i)) {
+        suggestions.push('Add a `### Complexity` section with a score from 1-10');
+    }
+    if (!input.body?.match(/###?\s*Acceptance Criteria/i)) {
+        suggestions.push('Add an `### Acceptance Criteria` section with testable criteria');
+    }
+    if (input.body.length < 50) {
+        suggestions.push('Provide a more detailed description of the problem or feature');
+    }
+    const assoc = input.authorAssociation ?? 'NONE';
+    const isTrusted = assoc === 'OWNER' || assoc === 'MEMBER' || assoc === 'COLLABORATOR';
+    if (d.demandPressure < 0.3 && !isTrusted) {
+        suggestions.push('Low demand signal — add reactions or comments to show interest');
+    }
+    if (d.soulAlignment < 0.5) {
+        suggestions.push('Add labels that indicate alignment with the project mission (e.g., governance, spec, security)');
+    }
+    return suggestions;
+}
+// ── Public API ───────────────────────────────────────────────────────
+/**
+ * Score a GitHub issue for pipeline admission using the Product Priority Algorithm.
+ *
+ * Returns whether the issue is admitted (score and confidence above thresholds)
+ * along with the full score and, if rejected, suggestions for improvement.
+ */
+export function scoreIssueForAdmission(input, thresholds, priorityConfig) {
+    const priorityInput = mapIssueToPriorityInput(input);
+    const score = computePriority(priorityInput, priorityConfig);
+    const scorePasses = score.composite >= thresholds.minimumScore;
+    const confidencePasses = score.confidence >= thresholds.minimumConfidence;
+    const admitted = scorePasses && confidencePasses;
+    if (admitted) {
+        return {
+            admitted: true,
+            score,
+            reason: `Score ${score.composite.toFixed(4)} meets threshold ${thresholds.minimumScore} with ${(score.confidence * 100).toFixed(0)}% confidence`,
+        };
+    }
+    const reasons = [];
+    if (!scorePasses) {
+        reasons.push(`score ${score.composite.toFixed(4)} below minimum ${thresholds.minimumScore}`);
+    }
+    if (!confidencePasses) {
+        reasons.push(`confidence ${(score.confidence * 100).toFixed(0)}% below minimum ${(thresholds.minimumConfidence * 100).toFixed(0)}%`);
+    }
+    return {
+        admitted: false,
+        score,
+        reason: `Not admitted: ${reasons.join('; ')}`,
+        suggestions: generateSuggestions(input, score),
+    };
+}
+//# sourceMappingURL=admission-score.js.map

package/dist/cycle-utils.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Utility functions for cycle detection and handling.
+ */
+import type { IssueTracker } from '@ai-sdlc/reference';
+import { PipelineCycleDetector, type PipelineStage } from './pipeline-cycle-detector.js';
+export interface CycleHandlerOptions {
+    /** Issue or PR identifier. */
+    issueOrPrId: string;
+    /** Stage being invoked. */
+    stage: PipelineStage;
+    /** Issue tracker for fetching/posting comments. */
+    tracker: IssueTracker;
+    /** Cycle detector instance. */
+    detector: PipelineCycleDetector;
+    /** Optional Slack notification callback. */
+    notifySlack?: (message: string) => Promise<void>;
+    /** Custom cycle notification template (optional). */
+    cycleTemplate?: {
+        title: string;
+        body: string;
+    };
+}
+export interface CycleCheckResult {
+    /** Whether a cycle was detected. */
+    cycleDetected: boolean;
+    /** Marker to append to comments for tracking. */
+    marker: string;
+    /** Formatted message describing the cycle (if detected). */
+    cycleMessage?: string;
+}
+/**
+ * Check for pipeline cycles and post notification if detected.
+ *
+ * The marker is generated upfront so the caller can append it to comments
+ * BEFORE executing the stage (records intent, prevents race conditions).
+ * Cycle detection accounts for the pending invocation (+1 to current count).
+ */
+export declare function checkAndHandleCycle(options: CycleHandlerOptions): Promise<CycleCheckResult>;
+/**
+ * Create a cycle detector from pipeline config.
+ * Reads maxRetries from stage configurations.
+ */
+export declare function createCycleDetectorFromConfig(config: {
+    stages?: Array<{
+        name: string;
+        onFailure?: {
+            maxRetries?: number;
+        };
+    }>;
+}): PipelineCycleDetector;
+//# sourceMappingURL=cycle-utils.d.ts.map

package/dist/cycle-utils.js

@@ -0,0 +1,77 @@
+/**
+ * Utility functions for cycle detection and handling.
+ */
+import { PipelineCycleDetector } from './pipeline-cycle-detector.js';
+import { NOTIFICATION_TITLES } from './defaults.js';
+/**
+ * Sanitize template content to prevent markdown/HTML injection.
+ * Strips HTML tags and limits length.
+ */
+function sanitizeTemplate(text) {
+    return text.replace(/<[^>]*>/g, '').slice(0, 2000);
+}
+/**
+ * Check for pipeline cycles and post notification if detected.
+ *
+ * The marker is generated upfront so the caller can append it to comments
+ * BEFORE executing the stage (records intent, prevents race conditions).
+ * Cycle detection accounts for the pending invocation (+1 to current count).
+ */
+export async function checkAndHandleCycle(options) {
+    const { issueOrPrId, stage, tracker, detector, notifySlack, cycleTemplate } = options;
+    // Detect cycles from existing comment markers (no +1 — marker is separate)
+    const cycleResult = await detector.detectCycle(tracker, issueOrPrId);
+    // Generate marker for the caller to append to comments
+    const marker = detector.recordInvocation(stage);
+    if (cycleResult.cycleDetected) {
+        const loopingSummary = cycleResult.loopingStages
+            .map((s) => `- **${s.stage}**: ${s.count}/${s.max} invocations`)
+            .join('\n');
+        const title = sanitizeTemplate(cycleTemplate?.title ?? NOTIFICATION_TITLES.pipelineCycleDetected);
+        const body = sanitizeTemplate(cycleTemplate?.body ??
+            `The pipeline has detected an infinite loop across the following stages:\n\n${loopingSummary}\n\n**Manual intervention is required** to resolve the cycle. Please review the issue and PR to determine the root cause.`);
+        const cycleMessage = `## ${title}\n\n${body}`;
+        // Post cycle detection comment
+        await tracker.addComment(issueOrPrId, cycleMessage);
+        // Send Slack notification if configured
+        if (notifySlack) {
+            const slackMessage = `:warning: *Pipeline Cycle Detected* for #${issueOrPrId}\n\nLooping stages:\n${cycleResult.loopingStages.map((s) => `• ${s.stage}: ${s.count}/${s.max}`).join('\n')}`;
+            await notifySlack(slackMessage).catch((err) => {
+                console.error('[cycle-detector] Slack notification failed:', err instanceof Error ? err.message : String(err));
+            });
+        }
+        return { cycleDetected: true, marker, cycleMessage };
+    }
+    return { cycleDetected: false, marker };
+}
+/**
+ * Create a cycle detector from pipeline config.
+ * Reads maxRetries from stage configurations.
+ */
+export function createCycleDetectorFromConfig(config) {
+    const detector = new PipelineCycleDetector();
+    if (config.stages) {
+        const overrides = {};
+        for (const stage of config.stages) {
+            const maxRetries = stage.onFailure?.maxRetries;
+            if (maxRetries !== undefined) {
+                if (stage.name === 'code') {
+                    overrides['fix-ci'] = maxRetries;
+                }
+                else if (stage.name === 'review') {
+                    overrides['fix-review'] = maxRetries;
+                }
+                else if (stage.name === 'admission' ||
+                    stage.name === 'triage' ||
+                    stage.name === 'agent') {
+                    overrides[stage.name] = maxRetries;
+                }
+            }
+        }
+        if (Object.keys(overrides).length > 0) {
+            detector.updateMaxInvocations(overrides);
+        }
+    }
+    return detector;
+}
+//# sourceMappingURL=cycle-utils.js.map

package/dist/defaults.d.ts

@@ -136,5 +136,10 @@ export declare const NOTIFICATION_TITLES: {
     readonly fixCIAgentFailed: "AI-SDLC: Fix-CI Agent Failed";
     readonly fixCIGuardrailViolations: "AI-SDLC: Fix-CI Guardrail Violations";
     readonly fixCIApplied: "AI-SDLC: Fix-CI Applied";
+    readonly fixReviewRetryLimit: "AI-SDLC: Fix-Review Retry Limit Reached";
+    readonly fixReviewAgentFailed: "AI-SDLC: Fix-Review Agent Failed";
+    readonly fixReviewGuardrailViolations: "AI-SDLC: Fix-Review Guardrail Violations";
+    readonly fixReviewApplied: "AI-SDLC: Fix-Review Applied";
+    readonly pipelineCycleDetected: "AI-SDLC: Pipeline Cycle Detected";
 };
 //# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.js

@@ -214,5 +214,10 @@ export const NOTIFICATION_TITLES = {
     fixCIAgentFailed: 'AI-SDLC: Fix-CI Agent Failed',
     fixCIGuardrailViolations: 'AI-SDLC: Fix-CI Guardrail Violations',
     fixCIApplied: 'AI-SDLC: Fix-CI Applied',
+    fixReviewRetryLimit: 'AI-SDLC: Fix-Review Retry Limit Reached',
+    fixReviewAgentFailed: 'AI-SDLC: Fix-Review Agent Failed',
+    fixReviewGuardrailViolations: 'AI-SDLC: Fix-Review Guardrail Violations',
+    fixReviewApplied: 'AI-SDLC: Fix-Review Applied',
+    pipelineCycleDetected: 'AI-SDLC: Pipeline Cycle Detected',
 };
 //# sourceMappingURL=defaults.js.map