@ai-sdlc/orchestrator 0.5.0 → 0.6.0

package/dist/execute.js

@@ -8,10 +8,11 @@
 import { createGitHubSourceControl, routeByComplexity, evaluatePromotion, evaluateComplexity, selectModel, withSpan, getMeter, SPAN_NAMES, METRIC_NAMES, ATTRIBUTE_KEYS, } from '@ai-sdlc/reference';
 import { loadConfigAsync } from './config.js';
 import { validateIssue, validateIssueWithExtensions, parseComplexity } from './validate-issue.js';
+import { validateAgentOutput } from './validate-agent-output.js';
 import { createLogger } from './logger.js';
 import { createStructuredConsoleLogger, createStructuredBufferLogger, } from './structured-logger.js';
 import { ClaudeCodeRunner } from './runners/claude-code.js';
-import { execFileAsync, getGitHubConfig, resolveRepoRoot, createDefaultAuditLog, resolveAutonomyLevel, resolveConstraints, isAutonomousStrategy, recordMetric, validateAndAuditOutput, evaluatePipelineCompliance, authorizeFilesChanged, interpolateBranchPattern, interpolatePRTitle, issueIdToNumber, formatIssueRef, } from './shared.js';
+import { execFileAsync, getGitHubConfig, resolveRepoRoot, createDefaultAuditLog, resolveAutonomyLevel, resolveConstraints, isAutonomousStrategy, recordMetric, evaluatePipelineCompliance, authorizeFilesChanged, interpolateBranchPattern, interpolatePRTitle, issueIdToNumber, formatIssueRef, } from './shared.js';
 import { checkKillSwitch, issueAgentCredentials, revokeAgentCredentials, classifyAndSubmitApproval, createPipelineSecurity, } from './security.js';
 import { createPipelineOrchestration, executePipelineOrchestration, validatePipelineHandoffs, } from './orchestration.js';
 import { createPipelineProvenance, attachProvenanceToPR, validatePipelineProvenance, } from './provenance.js';
@@ -24,7 +25,7 @@ import { admitIssueResource, createPipelineAdmission, } from './admission.js';
 import { createPipelineAdapterRegistry, createPipelineWebhookBridge, resolveAdapterFromGit, scanPipelineAdapters, resolveIssueTrackerFromConfig, } from './adapters.js';
 import { existsSync, readFileSync, appendFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { defaultSandboxConstraints, DEFAULT_CONFIG_DIR_NAME, DEFAULT_PR_FOOTER, NOTIFICATION_TITLES, } from './defaults.js';
+import { defaultSandboxConstraints, DEFAULT_CONFIG_DIR_NAME, DEFAULT_PR_FOOTER, DEFAULT_LINT_COMMAND, DEFAULT_FORMAT_COMMAND, DEFAULT_COMMIT_MESSAGE_TEMPLATE, DEFAULT_COMMIT_CO_AUTHOR, NOTIFICATION_TITLES, } from './defaults.js';
 import { checkFrameworkCompliance, getControlCatalog, getFrameworkMappings, listSupportedFrameworks, } from './compliance-extended.js';
 import { createSilentLogger, withPipelineSpanSync, getPipelineTracer, validateResourceSchema, } from './telemetry-extended.js';
 import { createPipelineMemory } from './shared.js';
@@ -125,6 +126,36 @@ export async function executePipeline(issueId, options = {}) {
 async function executePipelineBody(issueId, issue, config, qualityGate, agentRole, autonomyPolicy, tracker, sc, auditLog, metricStore, options, log, workDir) {
     const issueNumber = issueIdToNumber(issueId);
     const meter = getMeter();
+    // Slack notifications (optional — activates when SLACK_BOT_TOKEN is set)
+    let slackThreadId;
+    const slackToken = process.env.SLACK_BOT_TOKEN;
+    const slackChannel = process.env.SLACK_CHANNEL;
+    const notifySlack = async (message) => {
+        if (!slackToken || !slackChannel)
+            return;
+        try {
+            const body = { channel: slackChannel, text: message };
+            if (slackThreadId)
+                body.thread_ts = slackThreadId;
+            const res = await fetch('https://slack.com/api/chat.postMessage', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${slackToken}`,
+                },
+                body: JSON.stringify(body),
+            });
+            const data = (await res.json());
+            // Capture the first message's timestamp as thread ID
+            if (data.ok && !slackThreadId && data.ts) {
+                slackThreadId = data.ts;
+            }
+        }
+        catch {
+            // Best-effort — don't fail the pipeline for Slack
+        }
+    };
+    await notifySlack(`:rocket: *Pipeline started* for <https://github.com/${process.env.GITHUB_REPOSITORY ?? ''}/issues/${issueId}|#${issueId}: ${issue.title}>`);
     // Discovery: register agent and resolve by issue labels
     const discovery = createPipelineDiscovery();
     discovery.register(agentRole);
@@ -256,7 +287,26 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
     ensureRuntimeGitignore(workDir);
     // 9. Invoke agent (with sandbox + JIT credential lifecycle when security is provided)
     log.stage('agent');
+    // Post progress comment so users can see the pipeline is working
+    await tracker.addComment(issueId, `## AI-SDLC: Agent Started\n\n` +
+        `The AI agent is now working on this issue on branch \`${branchName}\`.\n\n` +
+        `| Detail | Value |\n|---|---|\n` +
+        `| Model | ${selectedModel ?? 'default'} |\n` +
+        `| Complexity | ${complexity} |\n` +
+        `| Strategy | ${strategy} |\n`);
+    await notifySlack(`:hammer_and_wrench: Agent working on \`${branchName}\` (model: ${selectedModel ?? 'default'}, complexity: ${complexity})`);
     const runner = options.runner ?? new ClaudeCodeRunner();
+    // Set up progress tracking — collects streaming events for the activity log
+    const progressLog = [];
+    const onProgress = (event) => {
+        const timestamp = new Date().toISOString().slice(11, 19);
+        if (event.type === 'tool_start' && event.tool) {
+            progressLog.push(`[${timestamp}] ${event.tool}${event.file ? `: ${event.file}` : ''}`);
+        }
+        else if (event.type === 'cost') {
+            progressLog.push(`[${timestamp}] Cost: $${event.costUsd?.toFixed(4)}`);
+        }
+    };
     // Sandbox isolation around agent execution
     const codeStage = config.pipeline?.spec.stages.find((s) => s.name === 'code');
     let sandboxId;
@@ -304,6 +354,12 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
                     codebaseContext: options.codebaseContext,
                     episodicContext,
                     sandboxId,
+                    lintCommand: DEFAULT_LINT_COMMAND,
+                    formatCommand: DEFAULT_FORMAT_COMMAND,
+                    typecheckCommand: process.env.AI_SDLC_TYPECHECK_COMMAND,
+                    commitMessageTemplate: DEFAULT_COMMIT_MESSAGE_TEMPLATE,
+                    commitCoAuthor: DEFAULT_COMMIT_CO_AUTHOR,
+                    onProgress,
                 }));
             });
             // Extract the AgentResult from orchestration output
@@ -359,11 +415,31 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
     if (currentLevel.permissions.write.length > 0) {
         authorizeFilesChanged(result.filesChanged, currentLevel.permissions, agentRole.spec.constraints, auditLog, agentRole.metadata.name);
     }
-    // 11. Validate agent output against guardrails
-    await withSpan(SPAN_NAMES.PIPELINE_STAGE, {
+    // 11. Post activity log so users can see what the agent did
+    const activitySection = progressLog.length > 0
+        ? `### Activity Log\n\n\`\`\`\n${progressLog.slice(-40).join('\n')}\n\`\`\``
+        : '';
+    await tracker.addComment(issueId, `## AI-SDLC: Agent Complete\n\n` +
+        `**${result.filesChanged.length} files changed.** Pushing branch...\n\n` +
+        activitySection);
+    await notifySlack(`:white_check_mark: Agent complete — ${result.filesChanged.length} files changed. Pushing...`);
+    // 12. Push branch (before validation to preserve work even if validation fails)
+    log.stage('push');
+    await execFileAsync('git', ['push', 'origin', branchName], { cwd: workDir });
+    log.stageEnd('push');
+    auditLog.record({
+        actor: 'system',
+        action: 'push',
+        resource: `branch/${branchName}`,
+        decision: 'allowed',
+        details: { filesChanged: result.filesChanged.length, issueId },
+    });
+    // 13. Validate agent output against guardrails (after push)
+    const validation = await withSpan(SPAN_NAMES.PIPELINE_STAGE, {
         [ATTRIBUTE_KEYS.STAGE]: 'validate-output',
     }, async () => {
-        await validateAndAuditOutput({
+        log.stage('validate-output');
+        const validationResult = await validateAgentOutput({
             filesChanged: result.filesChanged,
             workDir,
             constraints: {
@@ -372,14 +448,37 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
                 blockedPaths: resolved.blockedPaths,
             },
             guardrails: { maxLinesPerPR: currentLevel.guardrails.maxLinesPerPR },
-            auditLog,
-            log,
-            onViolation: async (violationList) => {
-                await tracker.addComment(issueId, `## ${NOTIFICATION_TITLES.guardrailViolations}\n\n${violationList}`);
-            },
         });
+        log.stageEnd('validate-output');
+        return validationResult;
+    });
+    if (!validation.passed) {
+        // Record validation failure in audit log
+        auditLog.record({
+            actor: 'system',
+            action: 'check',
+            resource: 'agent-output',
+            decision: 'denied',
+            details: { violations: validation.violations.map((v) => v.rule) },
+        });
+        // Post comment explaining the violations
+        const violationList = validation.violations
+            .map((v) => `- **${v.rule}**: ${v.message}`)
+            .join('\n');
+        await tracker.addComment(issueId, `## ${NOTIFICATION_TITLES.guardrailViolations}\n\n${violationList}\n\n` +
+            `The branch \`${branchName}\` has been pushed with your changes. You can review the work, ` +
+            `cherry-pick valid changes, or adjust the guardrails as needed.`);
+        // Exit without creating PR
+        throw new Error(`Agent output failed guardrail validation. Branch ${branchName} preserved for review.`);
+    }
+    // Validation passed — record success
+    auditLog.record({
+        actor: 'system',
+        action: 'check',
+        resource: 'agent-output',
+        decision: 'allowed',
     });
-    // 11b. Evaluate quality gates and report as GitHub Check Runs
+    // 13b. Evaluate quality gates and report as GitHub Check Runs
     if (qualityGate.spec.gates.length > 0) {
         try {
             const { stdout: headSha } = await execFileAsync('git', ['rev-parse', 'HEAD'], {
@@ -416,7 +515,7 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
             log.info('Post-agent gate evaluation skipped');
         }
     }
-    // 11c. Post-agent complexity evaluation (non-blocking)
+    // 13c. Post-agent complexity evaluation (non-blocking)
     try {
         const { stdout: diffStat } = await execFileAsync('git', ['diff', '--stat', 'HEAD~1'], {
             cwd: workDir,
@@ -445,11 +544,7 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
     catch {
         log.info('Post-agent complexity evaluation skipped');
     }
-    // 12. Push branch
-    log.stage('push');
-    await execFileAsync('git', ['push', 'origin', branchName], { cwd: workDir });
-    log.stageEnd('push');
-    // 12b. Compute cost receipt for provenance (before PR creation)
+    // 14. Compute cost receipt for provenance (before PR creation)
     let costReceipt;
     if (result.tokenUsage) {
         const tu = result.tokenUsage;
@@ -467,7 +562,7 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
             },
         };
     }
-    // 13. Create PR (with optional provenance, reading config from pipeline)
+    // 15. Create PR (with optional provenance, reading config from pipeline)
     const prConfig = config.pipeline?.spec.pullRequest;
     const shouldIncludeProvenance = options.includeProvenance ?? prConfig?.includeProvenance ?? options.security !== undefined;
     let provenanceBlock = '';
@@ -531,6 +626,7 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
         })
         : { title: NOTIFICATION_TITLES.prCreated, body: `Pull request created: ${pr.url}` };
     await tracker.addComment(issueId, `## ${prCreatedComment.title}\n\n${prCreatedComment.body}`);
+    await notifySlack(`:pull_request: PR created: ${pr.url}`);
     // 14b. Record cost from agent result
     if (options.costTracker && result.tokenUsage) {
         const tu = result.tokenUsage;
@@ -769,25 +865,24 @@ function runPipelineDiagnostics(input) {
     }
 }
 // ── Gitignore helper ─────────────────────────────────────────────────
-const RUNTIME_GITIGNORE_ENTRIES = [
-    '# AI-SDLC runtime artifacts',
-    '.ai-sdlc/state.db',
-    '.ai-sdlc/state/',
-    '.ai-sdlc/audit.jsonl',
-];
+const RUNTIME_GITIGNORE_PATHS = ['.ai-sdlc/state.db', '.ai-sdlc/state/', '.ai-sdlc/audit.jsonl'];
 /**
  * Ensure .gitignore in the working directory covers AI-SDLC runtime artifacts.
  * Without this the agent sees untracked runtime files and appends duplicate
  * gitignore entries on every run.
+ *
+ * Only checks path entries (not the comment header) to avoid false mismatches.
+ * Writes the block once with any missing paths.
  */
 function ensureRuntimeGitignore(workDir) {
     try {
         const gitignorePath = join(workDir, '.gitignore');
         const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf-8') : '';
-        const missing = RUNTIME_GITIGNORE_ENTRIES.filter((entry) => !existing.includes(entry));
+        const missing = RUNTIME_GITIGNORE_PATHS.filter((entry) => !existing.includes(entry));
         if (missing.length === 0)
             return;
-        appendFileSync(gitignorePath, '\n' + missing.join('\n') + '\n', 'utf-8');
+        const block = '\n# AI-SDLC runtime artifacts\n' + missing.join('\n') + '\n';
+        appendFileSync(gitignorePath, block, 'utf-8');
     }
     catch {
         // Best-effort — workDir may not exist yet in tests or dry-run scenarios

package/dist/fix-ci.js

@@ -13,6 +13,7 @@ import { renderTemplate } from './notifications.js';
 import { parseDuration } from './policy-evaluators.js';
 import { checkKillSwitch, issueAgentCredentials, revokeAgentCredentials, } from './security.js';
 import { DEFAULT_MAX_FIX_ATTEMPTS, DEFAULT_MAX_LOG_LINES, DEFAULT_GH_CLI_TIMEOUT_MS, DEFAULT_CONFIG_DIR_NAME, defaultSandboxConstraints, NOTIFICATION_TITLES, } from './defaults.js';
+import { createCycleDetectorFromConfig, checkAndHandleCycle } from './cycle-utils.js';
 export const MAX_FIX_ATTEMPTS = DEFAULT_MAX_FIX_ATTEMPTS;
 export const MAX_LOG_LINES = DEFAULT_MAX_LOG_LINES;
 export const RETRY_MARKER = '<!-- ai-sdlc-fix-ci-attempt -->';
@@ -107,6 +108,8 @@ export async function executeFixCI(prNumber, runId, options = {}) {
     }
     // Tracker is available if injected directly or if we're not in test mode
     const trackerAvailable = !!options.tracker || options._prComments === undefined;
+    // Create cycle detector (marker generated after all guard conditions pass)
+    const cycleDetector = createCycleDetectorFromConfig(config.pipeline?.spec ?? {});
     // 2. Count retry attempts (via injected comments or IssueTracker)
     log.stage('check-retries');
     let comments;
@@ -126,6 +129,27 @@ export async function executeFixCI(prNumber, runId, options = {}) {
             await getTracker().addComment(String(prNumber), body);
         }
     };
+    // Check for pipeline-level cycles AFTER retry counting
+    // (so legitimate retries under the limit aren't blocked)
+    if (trackerAvailable) {
+        const cycleCheck = await checkAndHandleCycle({
+            issueOrPrId: String(prNumber),
+            stage: 'fix-ci',
+            tracker: getTracker(),
+            detector: cycleDetector,
+        });
+        if (cycleCheck.cycleDetected) {
+            log.info('Pipeline cycle detected. Halting fix-ci execution.');
+            auditLog.record({
+                actor: 'system',
+                action: 'evaluate',
+                resource: `pr#${prNumber}`,
+                decision: 'denied',
+                details: { reason: 'pipeline-cycle-detected' },
+            });
+            return;
+        }
+    }
     if (attempts >= maxFixAttempts) {
         log.info(`Fix-CI retry limit reached (${maxFixAttempts}). Commenting and stopping.`);
         auditLog.record({
@@ -148,6 +172,9 @@ export async function executeFixCI(prNumber, runId, options = {}) {
         await addComment(`## ${limitComment.title}\n\n${limitComment.body}`);
         return;
     }
+    // Generate cycle marker AFTER all guard conditions (retry limit + cycle detection)
+    // so it's only recorded when we actually proceed with execution
+    const cycleMarker = cycleDetector.recordInvocation('fix-ci');
     // 3. Fetch CI logs
     log.stage('fetch-logs');
     const ciLogs = await fetchCILogs(runId, options._ciLogs, options.ciAdapter);
@@ -259,7 +286,8 @@ export async function executeFixCI(prNumber, runId, options = {}) {
                         const agentFailComment = agentFailTpl
                             ? renderTemplate(agentFailTpl, { stageName: 'fix-ci', details: errorDetail })
                             : { title: NOTIFICATION_TITLES.fixCIAgentFailed, body: errorDetail };
-                        await addComment(`## ${agentFailComment.title}\n\n${agentFailComment.body}\n\n${RETRY_MARKER}`);
+                        // Use pre-created marker (one per execution, prevents double-counting)
+                        await addComment(`## ${agentFailComment.title}\n\n${agentFailComment.body}\n\n${RETRY_MARKER}\n${cycleMarker}`);
                         throw new Error(`Fix-CI agent failed on PR #${prNumber}: ${r.error}`);
                     }
                     log.stageEnd('agent');
@@ -308,7 +336,7 @@ export async function executeFixCI(prNumber, runId, options = {}) {
                 auditLog,
                 log,
                 onViolation: async (violationList) => {
-                    await addComment(`## ${NOTIFICATION_TITLES.fixCIGuardrailViolations}\n\n${violationList}\n\n${RETRY_MARKER}`);
+                    await addComment(`## ${NOTIFICATION_TITLES.fixCIGuardrailViolations}\n\n${violationList}\n\n${RETRY_MARKER}\n${cycleMarker}`);
                 },
             });
         });
@@ -335,6 +363,7 @@ export async function executeFixCI(prNumber, runId, options = {}) {
                 title: NOTIFICATION_TITLES.fixCIApplied,
                 body: `Attempt ${attempts + 1} of ${maxFixAttempts} — pushed fixes to \`${currentBranch}\`.`,
             };
+        // Use pre-created marker (one per execution, prevents double-counting)
         await addComment([
             `## ${successComment.title}`,
             '',
@@ -344,6 +373,7 @@ export async function executeFixCI(prNumber, runId, options = {}) {
             result.filesChanged.map((f) => `- \`${f}\``).join('\n'),
             '',
             RETRY_MARKER,
+            cycleMarker,
         ].join('\n'));
         // 12. Record episodic memory (success)
         if (options.memory) {

package/dist/fix-review.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Fix-Review orchestrator — detects review findings on agent-created PRs,
+ * fetches review comments, and re-invokes the agent with review context.
+ * Capped at MAX_FIX_ATTEMPTS to prevent infinite loops.
+ */
+import { type IssueTracker, type AuditLog, type MetricStore, type AgentMemory, type SecretStore } from '@ai-sdlc/reference';
+import { type Logger } from './logger.js';
+import type { AgentRunner } from './runners/types.js';
+import { type SecurityContext } from './security.js';
+export declare const MAX_REVIEW_FIX_ATTEMPTS = 2;
+export declare const RETRY_MARKER = "<!-- ai-sdlc-fix-review-attempt -->";
+export interface FixReviewOptions {
+    /** Override the config directory (defaults to `.ai-sdlc`). */
+    configDir?: string;
+    /** Override the working directory (defaults to repo root). */
+    workDir?: string;
+    /** Inject a custom runner (for testing). */
+    runner?: AgentRunner;
+    /** Inject a custom logger (for testing). */
+    logger?: Logger;
+    /** Inject PR comments for testing (bypasses IssueTracker call). */
+    _prComments?: string[];
+    /** Inject review findings for testing (bypasses GitHub API call). */
+    _reviewFindings?: string;
+    /** Inject a custom audit log (for testing). */
+    auditLog?: AuditLog;
+    /** Inject a custom issue tracker (for testing). */
+    tracker?: IssueTracker;
+    /** In-process metric store for testable telemetry. */
+    metricStore?: MetricStore;
+    /** Agent memory for episodic recall. */
+    memory?: AgentMemory;
+    /** Security context for kill switch and JIT credentials. */
+    security?: SecurityContext;
+    /** Use the reference structured logger instead of the plain console logger. */
+    useStructuredLogger?: boolean;
+    /** Secret store adapter for resolving credentials (defaults to process.env). */
+    secretStore?: SecretStore;
+}
+/**
+ * Count how many fix-review retry attempts have been made on a PR
+ * by scanning comments for the hidden retry marker.
+ */
+export declare function countRetryAttempts(comments: string[]): number;
+/**
+ * Validate that a PR number is a positive integer.
+ */
+export declare function validatePrNumber(prNumber: number): void;
+/**
+ * Sanitize a git branch name to prevent command injection.
+ * Allows only alphanumeric characters, slashes, dashes, underscores, and dots.
+ */
+export declare function sanitizeBranchName(branch: string): string;
+/**
+ * Fetch review findings from PR reviews that requested changes.
+ * Returns a formatted string with all findings from review agents.
+ */
+export declare function fetchReviewFindings(prNumber: number, injectedFindings?: string, _secretStore?: SecretStore): Promise<string>;
+/**
+ * Execute the fix-review pipeline for a PR with review findings.
+ *
+ * Returns gracefully (no throw) when the retry limit is reached.
+ * Throws on agent failure or guardrail violations.
+ */
+export declare function executeFixReview(prNumber: number, options?: FixReviewOptions): Promise<void>;
+//# sourceMappingURL=fix-review.d.ts.map