@ai-sdlc/orchestrator 0.5.0 → 0.9.0

package/dist/execute.js

@@ -8,10 +8,12 @@
 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, buildIssueTemplateVars, } from './shared.js';
+import { cleanGitEnv } from './runtime/git-env.js';
 import { checkKillSwitch, issueAgentCredentials, revokeAgentCredentials, classifyAndSubmitApproval, createPipelineSecurity, } from './security.js';
 import { createPipelineOrchestration, executePipelineOrchestration, validatePipelineHandoffs, } from './orchestration.js';
 import { createPipelineProvenance, attachProvenanceToPR, validatePipelineProvenance, } from './provenance.js';
@@ -22,9 +24,9 @@ import { verifyAuditIntegrity, createFileAuditLog, loadAuditEntries, computeAudi
 import { renderTemplate } from './notifications.js';
 import { admitIssueResource, createPipelineAdmission, } from './admission.js';
 import { createPipelineAdapterRegistry, createPipelineWebhookBridge, resolveAdapterFromGit, scanPipelineAdapters, resolveIssueTrackerFromConfig, } from './adapters.js';
-import { existsSync, readFileSync, appendFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } 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';
@@ -32,6 +34,7 @@ import { hasResourceChanged, fingerprintResource } from './reconcilers.js';
 import { CostTracker } from './cost-tracker.js';
 import { enrichAgentContext } from './context-enrichment.js';
 import { reportGateCheckRuns } from './check-runs.js';
+import { WorktreePoolManager, readParallelismMode } from './runtime/index.js';
 /**
  * Execute the full AI-SDLC pipeline for a given issue ID.
  */
@@ -42,10 +45,29 @@ export async function executePipeline(issueId, options = {}) {
         (options.useStructuredLogger ? createStructuredConsoleLogger() : createLogger());
     const auditLog = options.auditLog ?? createDefaultAuditLog(workDir);
     const metricStore = options.metricStore;
+    // RFC-0010 §6/§7 Phase 2: parallelism opt-in. When AI_SDLC_PARALLELISM is unset (default),
+    // execution proceeds serially exactly as today. When set to 'experimental' or 'on', a
+    // WorktreePoolManager is instantiated for the worker-pool dispatcher landing in Phase 3
+    // (RFC-0010 §9). For now the manager is constructed but not yet routed through — Phase 2
+    // ships the wire-in surface; Phase 3 wires the worker pool to consume it.
+    const parallelismMode = readParallelismMode();
+    let worktreePool;
+    if (parallelismMode !== 'off') {
+        worktreePool = new WorktreePoolManager(workDir);
+        log.info(`[parallelism] mode=${parallelismMode}, pool root=${worktreePool.rootDir}`);
+    }
+    void worktreePool; // referenced by Phase 3 dispatcher; silences unused-var lint until then
     // 1. Load .ai-sdlc/ config (async: includes adapter scanning + manifest distribution)
     log.stage('load-config');
     const config = await loadConfigAsync(configDir);
     log.stageEnd('load-config');
+    // If the caller (e.g., cli-watch's pipeline dispatcher) selected a specific
+    // Pipeline resource, override the on-disk default. Without this, multi-
+    // pipeline configs (RFC-0010 dual workflow: pipeline.yaml + pipeline-backlog.yaml)
+    // always fall back to pipeline.yaml because loadConfig prefers it as canonical.
+    if (options.pipelineOverride) {
+        config.pipeline = options.pipelineOverride;
+    }
     // Kill switch check (before any work)
     if (options.security) {
         await checkKillSwitch(options.security);
@@ -101,6 +123,12 @@ export async function executePipeline(issueId, options = {}) {
             description: issue.description,
         });
     }
+    // Capture the user's current HEAD so we can restore it after the pipeline.
+    // Without this, `git checkout <issue-branch>` inside the pipeline body
+    // leaves the user's working tree on the issue branch even after the run
+    // completes (the AISDLC-68 incident). Long-term fix is a worktree pool
+    // (RFC-0010 §7); this is the pragmatic save+restore.
+    const originalHead = await captureCurrentBranch(workDir);
     // Wrap pipeline body in try/catch to record failure episodes
     try {
         return await executePipelineBody(issueId, issue, config, qualityGate, agentRole, autonomyPolicy, tracker, sc, auditLog, metricStore, options, log, workDir);
@@ -121,10 +149,155 @@ export async function executePipeline(issueId, options = {}) {
         }
         throw err;
     }
+    finally {
+        await restoreOriginalBranch(workDir, originalHead, log);
+    }
+}
+/**
+ * Capture the current branch name (or commit SHA in detached-HEAD state) so the
+ * pipeline can restore the user's worktree after the run. Returns null on git
+ * failure — callers treat null as "don't try to restore".
+ *
+ * @internal — exported for unit tests.
+ */
+export async function captureCurrentBranch(workDir) {
+    // cleanGitEnv() strips GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE so git
+    // resolves against `workDir`'s own .git rather than whatever a parent
+    // process (e.g. husky pre-push hook running in another worktree) leaked
+    // into the env (AISDLC-72).
+    try {
+        const { stdout } = await execFileAsync('git', ['symbolic-ref', '--short', 'HEAD'], {
+            cwd: workDir,
+            env: cleanGitEnv(),
+        });
+        return stdout.trim();
+    }
+    catch {
+        // Detached HEAD or no git repo. Try the SHA fallback.
+        try {
+            const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], {
+                cwd: workDir,
+                env: cleanGitEnv(),
+            });
+            return stdout.trim();
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Restore the user's original HEAD if the pipeline switched branches AND the
+ * working tree is clean. If the working tree has uncommitted changes (from a
+ * partial pipeline run), log a warning and leave HEAD where it is — better to
+ * preserve the pipeline's state than to clobber whatever the user has.
+ *
+ * @internal — exported for unit tests.
+ */
+export async function restoreOriginalBranch(workDir, originalHead, log) {
+    if (!originalHead)
+        return;
+    try {
+        const current = await captureCurrentBranch(workDir);
+        if (current === originalHead)
+            return;
+        // Refuse to checkout if the worktree has uncommitted changes — git would
+        // either block the checkout or carry the changes across, both bad.
+        // cleanGitEnv() prevents leaked GIT_DIR from corrupting these calls (AISDLC-72).
+        const { stdout } = await execFileAsync('git', ['status', '--porcelain'], {
+            cwd: workDir,
+            env: cleanGitEnv(),
+        });
+        if (stdout.trim().length > 0) {
+            log?.info(`[pipeline] worktree dirty after pipeline; HEAD left at \`${current}\`. ` +
+                `To restore: \`git stash && git checkout ${originalHead}\``);
+            return;
+        }
+        await execFileAsync('git', ['checkout', originalHead], {
+            cwd: workDir,
+            env: cleanGitEnv(),
+        });
+    }
+    catch (err) {
+        log?.info(`[pipeline] failed to restore HEAD to \`${originalHead}\`: ${err.message}`);
+    }
+}
+/**
+ * Push a branch to origin, rebasing onto the remote tip if it has advanced.
+ * Pre-AISDLC-68-rerun the pipeline did a plain `git push` and rejected with
+ * non-fast-forward when the remote branch had drifted (e.g. a previous run's
+ * commits or a manual edit). The fix: try push; on non-fast-forward, fetch +
+ * rebase HEAD onto origin/<branch>, retry once. Rebase conflicts surface as
+ * the original error so the operator can resolve manually.
+ *
+ * @internal — exported for unit tests.
+ */
+export async function pushBranchWithRebase(workDir, branchName, log) {
+    // cleanGitEnv() ensures these git calls bind to `workDir`'s own .git, not
+    // a leaked GIT_DIR from a parent process (AISDLC-72).
+    const env = cleanGitEnv();
+    try {
+        await execFileAsync('git', ['push', 'origin', branchName], { cwd: workDir, env });
+        return;
+    }
+    catch (err) {
+        const stderr = err.stderr ?? err.message;
+        if (!/non-fast-forward|rejected/i.test(stderr)) {
+            throw err;
+        }
+        log?.info(`[pipeline] push rejected (non-fast-forward); rebasing onto origin/${branchName}`);
+    }
+    // Fetch + rebase + retry. If the rebase fails, surface a clear error.
+    try {
+        await execFileAsync('git', ['fetch', 'origin', branchName], { cwd: workDir, env });
+        await execFileAsync('git', ['rebase', `origin/${branchName}`], { cwd: workDir, env });
+    }
+    catch (rebaseErr) {
+        // Abort the partial rebase so the worktree isn't left in a half-merged state.
+        try {
+            await execFileAsync('git', ['rebase', '--abort'], { cwd: workDir, env });
+        }
+        catch {
+            /* nothing to abort */
+        }
+        throw new Error(`Push rebase failed for branch ${branchName}: ${rebaseErr.message}. ` +
+            `Resolve conflicts manually and re-run the pipeline.`);
+    }
+    await execFileAsync('git', ['push', 'origin', branchName], { cwd: workDir, env });
 }
 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);
@@ -231,11 +404,15 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
     const currentLevel = resolveAutonomyLevel(autonomyPolicy);
     log.stageEnd('validate-issue');
     // 7. Create branch and checkout locally (read pattern from pipeline config)
-    const branchVars = { issueNumber: issueId, issueTitle: issue.title };
+    const branchVars = buildIssueTemplateVars(issueId, issue.title);
     const branchName = interpolateBranchPattern(config.pipeline?.spec.branching?.pattern, branchVars);
     await sc.createBranch({ name: branchName });
-    await execFileAsync('git', ['fetch', 'origin', branchName], { cwd: workDir });
-    await execFileAsync('git', ['checkout', branchName], { cwd: workDir });
+    // cleanGitEnv() prevents leaked GIT_DIR from corrupting these calls (AISDLC-72).
+    await execFileAsync('git', ['fetch', 'origin', branchName], {
+        cwd: workDir,
+        env: cleanGitEnv(),
+    });
+    await execFileAsync('git', ['checkout', branchName], { cwd: workDir, env: cleanGitEnv() });
     // 8. Resolve agent constraints
     const resolved = resolveConstraints(agentRole.spec.constraints, currentLevel);
     // 8b. Model selection: choose model based on complexity and budget pressure
@@ -256,7 +433,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 +500,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 +561,35 @@ 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).
+    // Fetch first + rebase if the remote has diverged so push fast-forwards
+    // cleanly. Without this, re-runs against an existing remote branch (e.g. when
+    // the issue branch was updated by another pipeline run or by a hand-edit)
+    // reject with non-fast-forward and the agent's work is stranded locally.
+    log.stage('push');
+    await pushBranchWithRebase(workDir, branchName, log);
+    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,18 +598,54 @@ 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) {
+        // One-line summary suitable for log lines + thrown error message.
+        const violationSummary = validation.violations.map((v) => `${v.rule}: ${v.message}`).join('; ');
+        // Record validation failure in audit log with full violation detail (rule
+        // + message), not just the rule names — the rule name alone doesn't tell
+        // the operator what to fix.
+        auditLog.record({
+            actor: 'system',
+            action: 'check',
+            resource: 'agent-output',
+            decision: 'denied',
+            details: {
+                violations: validation.violations.map((v) => ({ rule: v.rule, message: v.message })),
             },
         });
+        // Surface the rejection detail to the structured log so the operator sees
+        // it in stderr immediately. Without this the only signal was the
+        // (detail-free) thrown error message.
+        log.error(`[validate-output] rejected: ${violationSummary}`);
+        // 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. Include the violation summary in the error
+        // message so cli-watch and downstream loggers see the actual rejection.
+        throw new Error(`Agent output failed guardrail validation: ${violationSummary}. ` +
+            `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'], {
                 cwd: workDir,
+                env: cleanGitEnv(),
             });
             const gateResults = qualityGate.spec.gates.map((gate) => {
                 const evalResult = evaluatePipelineGate(gate, {
@@ -416,10 +678,11 @@ 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,
+            env: cleanGitEnv(),
         });
         const insertMatch = diffStat.match(/(\d+) insertions?\(\+\)/);
         const deleteMatch = diffStat.match(/(\d+) deletions?\(-\)/);
@@ -445,11 +708,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 +726,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 = '';
@@ -483,7 +742,7 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
         }
         provenanceBlock = '\n\n' + provenanceText;
     }
-    const prVars = { issueNumber: issueId, issueTitle: issue.title };
+    const prVars = buildIssueTemplateVars(issueId, issue.title);
     const prTitle = interpolatePRTitle(prConfig?.titleTemplate, prVars);
     const closeKeyword = prConfig?.closeKeyword ?? 'Closes';
     const targetBranch = config.pipeline?.spec.branching?.targetBranch ?? 'main';
@@ -531,6 +790,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 +1029,30 @@ 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 SENTINEL = '# ai-sdlc:runtime-gitignore';
+        if (existing.includes(SENTINEL))
+            return;
+        const missing = RUNTIME_GITIGNORE_PATHS.filter((entry) => !existing.split('\n').some((line) => line.trim() === entry));
         if (missing.length === 0)
             return;
-        appendFileSync(gitignorePath, '\n' + missing.join('\n') + '\n', 'utf-8');
+        // Write atomically (writeFileSync, not appendFileSync) to avoid race conditions
+        // when parallel test processes both read before either writes.
+        const block = `${SENTINEL}\n` + missing.join('\n') + '\n';
+        const newContent = existing.length > 0 ? existing.trimEnd() + '\n' + block : block;
+        writeFileSync(gitignorePath, newContent, 'utf-8');
     }
     catch {
         // Best-effort — workDir may not exist yet in tests or dry-run scenarios

package/dist/fix-ci.js

@@ -13,6 +13,8 @@ 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';
+import { cleanGitEnv } from './runtime/git-env.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 +109,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 +130,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,13 +173,18 @@ 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);
     log.stageEnd('fetch-logs');
     // 4. Determine branch and issue number
+    // cleanGitEnv() prevents leaked GIT_DIR from binding to a parent repo (AISDLC-72).
     const { stdout: branchStdout } = await execFileAsync('git', ['branch', '--show-current'], {
         cwd: workDir,
+        env: cleanGitEnv(),
     });
     const currentBranch = branchStdout.trim();
     const issueId = extractIssueId(currentBranch);
@@ -259,7 +289,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,13 +339,17 @@ 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}`);
                 },
             });
         });
         // 10. Push to the same branch (CI re-runs automatically)
+        // cleanGitEnv() prevents leaked GIT_DIR from binding to a parent repo (AISDLC-72).
         log.stage('push');
-        await execFileAsync('git', ['push', 'origin', currentBranch], { cwd: workDir });
+        await execFileAsync('git', ['push', 'origin', currentBranch], {
+            cwd: workDir,
+            env: cleanGitEnv(),
+        });
         log.stageEnd('push');
         auditLog.record({
             actor: 'system',
@@ -335,6 +370,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 +380,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