@ai-sdlc/orchestrator 0.6.0 → 0.9.0

package/dist/dispatch/worker-pool.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Bounded-concurrency worker pool per RFC-0010 §9. Accepts a stream of work items in
+ * PPA-priority order, dispatches up to `maxConcurrent` simultaneously, and surfaces
+ * structured admission/dispatch events.
+ */
+export interface WorkItem<T> {
+    /** Unique id (typically issue id). */
+    id: string;
+    /** PPA composite score; higher = higher priority. */
+    ppaScore: number;
+    /** The actual work to perform when admitted. */
+    payload: T;
+}
+export interface WorkerPoolDeps<T, R> {
+    /** Number of in-flight items allowed at once. */
+    maxConcurrent: number;
+    /** Execute a single work item; called by the pool with concurrency-bounded parallelism. */
+    execute: (item: WorkItem<T>) => Promise<R>;
+    /** Optional admission gate; return false to defer the item back into the queue. */
+    admit?: (item: WorkItem<T>) => Promise<boolean>;
+    /** Optional structured event sink. */
+    onEvent?: (event: WorkerPoolEvent<T>) => void;
+}
+export type WorkerPoolEvent<T> = {
+    type: 'queued';
+    item: WorkItem<T>;
+    queueSize: number;
+} | {
+    type: 'admission-deferred';
+    item: WorkItem<T>;
+} | {
+    type: 'started';
+    item: WorkItem<T>;
+    inFlight: number;
+} | {
+    type: 'completed';
+    item: WorkItem<T>;
+    durationMs: number;
+} | {
+    type: 'failed';
+    item: WorkItem<T>;
+    error: Error;
+};
+export interface WorkerPoolResult<T, R> {
+    succeeded: Array<{
+        item: WorkItem<T>;
+        result: R;
+    }>;
+    failed: Array<{
+        item: WorkItem<T>;
+        error: Error;
+    }>;
+    deferred: Array<WorkItem<T>>;
+}
+/**
+ * Process all items with bounded concurrency. Items are dispatched in PPA score order
+ * (descending). Items that the admission gate rejects are returned in `deferred` for
+ * the caller to requeue or escalate. Failed executions are returned in `failed`; the
+ * pool does NOT auto-retry — that's the caller's responsibility (see RFC §9.4).
+ */
+export declare function runWorkerPool<T, R>(items: WorkItem<T>[], deps: WorkerPoolDeps<T, R>): Promise<WorkerPoolResult<T, R>>;
+//# sourceMappingURL=worker-pool.d.ts.map

package/dist/dispatch/worker-pool.js

@@ -0,0 +1,60 @@
+/**
+ * Bounded-concurrency worker pool per RFC-0010 §9. Accepts a stream of work items in
+ * PPA-priority order, dispatches up to `maxConcurrent` simultaneously, and surfaces
+ * structured admission/dispatch events.
+ */
+/**
+ * Process all items with bounded concurrency. Items are dispatched in PPA score order
+ * (descending). Items that the admission gate rejects are returned in `deferred` for
+ * the caller to requeue or escalate. Failed executions are returned in `failed`; the
+ * pool does NOT auto-retry — that's the caller's responsibility (see RFC §9.4).
+ */
+export async function runWorkerPool(items, deps) {
+    if (deps.maxConcurrent < 1) {
+        throw new Error(`maxConcurrent must be >= 1 (got ${deps.maxConcurrent})`);
+    }
+    const sorted = [...items].sort((a, b) => b.ppaScore - a.ppaScore);
+    const result = { succeeded: [], failed: [], deferred: [] };
+    const onEvent = deps.onEvent ?? (() => { });
+    for (const item of sorted) {
+        onEvent({ type: 'queued', item, queueSize: sorted.length });
+    }
+    let inFlight = 0;
+    const queue = [...sorted];
+    // Spawn N workers that pull from the shared queue until empty.
+    const worker = async () => {
+        for (;;) {
+            const item = queue.shift();
+            if (!item)
+                return;
+            inFlight++;
+            try {
+                if (deps.admit) {
+                    const admitted = await deps.admit(item);
+                    if (!admitted) {
+                        onEvent({ type: 'admission-deferred', item });
+                        result.deferred.push(item);
+                        continue;
+                    }
+                }
+                const start = Date.now();
+                onEvent({ type: 'started', item, inFlight });
+                const r = await deps.execute(item);
+                onEvent({ type: 'completed', item, durationMs: Date.now() - start });
+                result.succeeded.push({ item, result: r });
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                onEvent({ type: 'failed', item, error });
+                result.failed.push({ item, error });
+            }
+            finally {
+                inFlight--;
+            }
+        }
+    };
+    const workers = Array.from({ length: Math.min(deps.maxConcurrent, sorted.length) }, () => worker());
+    await Promise.all(workers);
+    return result;
+}
+//# sourceMappingURL=worker-pool.js.map

package/dist/execute.d.ts

@@ -76,9 +76,49 @@ export interface ExecuteOptions {
     stateStore?: StateStore;
     /** Priority score from PPA scoring (set by watch loop or caller). */
     priorityScore?: PriorityScore;
+    /**
+     * Override the Pipeline resource selected for this execution. When set, takes
+     * precedence over the on-disk `config.pipeline` loaded from `.ai-sdlc/`. The
+     * watch loop uses this to pass the dispatcher-selected pipeline (e.g., the
+     * backlog pipeline for AISDLC-* issues) instead of letting executePipeline
+     * fall back to the canonical pipeline.yaml.
+     */
+    pipelineOverride?: import('@ai-sdlc/reference').Pipeline;
 }
 /**
  * Execute the full AI-SDLC pipeline for a given issue ID.
  */
 export declare function executePipeline(issueId: string, options?: ExecuteOptions): Promise<PipelineResult>;
+/**
+ * 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 declare function captureCurrentBranch(workDir: string): Promise<string | 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 declare function restoreOriginalBranch(workDir: string, originalHead: string | null, log: {
+    info: (msg: string) => void;
+} | undefined): Promise<void>;
+/**
+ * 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 declare function pushBranchWithRebase(workDir: string, branchName: string, log: {
+    info: (msg: string) => void;
+} | undefined): Promise<void>;
 //# sourceMappingURL=execute.d.ts.map

package/dist/execute.js

@@ -12,7 +12,8 @@ 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, 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';
@@ -23,7 +24,7 @@ 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, 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';
@@ -33,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.
  */
@@ -43,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);
@@ -102,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);
@@ -122,6 +149,121 @@ 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);
@@ -262,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
@@ -423,9 +569,13 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
         `**${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)
+    // 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 execFileAsync('git', ['push', 'origin', branchName], { cwd: workDir });
+    await pushBranchWithRebase(workDir, branchName, log);
     log.stageEnd('push');
     auditLog.record({
         actor: 'system',
@@ -453,14 +603,24 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
         return validationResult;
     });
     if (!validation.passed) {
-        // Record validation failure in audit log
+        // 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) => v.rule) },
+            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}`)
@@ -468,8 +628,10 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
         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.`);
+        // 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({
@@ -483,6 +645,7 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
         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, {
@@ -519,6 +682,7 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
     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?\(-\)/);
@@ -578,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';
@@ -878,11 +1042,17 @@ function ensureRuntimeGitignore(workDir) {
     try {
         const gitignorePath = join(workDir, '.gitignore');
         const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf-8') : '';
-        const missing = RUNTIME_GITIGNORE_PATHS.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;
-        const block = '\n# AI-SDLC runtime artifacts\n' + missing.join('\n') + '\n';
-        appendFileSync(gitignorePath, block, '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

@@ -14,6 +14,7 @@ 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 -->';
@@ -180,8 +181,10 @@ export async function executeFixCI(prNumber, runId, options = {}) {
     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);
@@ -341,8 +344,12 @@ export async function executeFixCI(prNumber, runId, options = {}) {
             });
         });
         // 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',

package/dist/fix-review.js

@@ -14,6 +14,7 @@ import { parseDuration } from './policy-evaluators.js';
 import { checkKillSwitch, issueAgentCredentials, revokeAgentCredentials, } from './security.js';
 import { 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';
 // Default max review-fix attempts (lower than CI-fix since reviews are more deterministic)
 export const MAX_REVIEW_FIX_ATTEMPTS = 2;
 export const RETRY_MARKER = '<!-- ai-sdlc-fix-review-attempt -->';
@@ -210,8 +211,10 @@ export async function executeFixReview(prNumber, options = {}) {
         return;
     }
     // 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 = sanitizeBranchName(branchStdout.trim());
     const issueId = extractIssueId(currentBranch);
@@ -371,8 +374,12 @@ export async function executeFixReview(prNumber, options = {}) {
             });
         });
         // 10. Push to the same branch (review agents re-run automatically via pull_request.synchronize)
+        // 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',

package/dist/harness/adapters/claude-code.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ClaudeCodeAdapter — wraps Claude Code CLI behind the HarnessAdapter contract.
+ * Uses the local `claude` CLI in `-p --output-format stream-json` mode, authenticating
+ * via whatever credential the CLI is logged into (Pro/Max subscription or API key).
+ */
+import { spawn } from 'node:child_process';
+import type { HarnessAdapter, HarnessAvailability, HarnessCapabilities, HarnessEvent, HarnessInput, HarnessName, HarnessRequires, HarnessResult } from '../types.js';
+export interface ClaudeCodeAdapterDeps {
+    env?: NodeJS.ProcessEnv;
+    /** Override the actual invocation path; tests inject a stub. */
+    invoke?: (input: HarnessInput, onEvent?: (e: HarnessEvent) => void) => Promise<HarnessResult>;
+    /** Override version probe for tests. */
+    probe?: () => Promise<HarnessAvailability>;
+    /** Override the spawn function (tests inject a fake child process). */
+    spawn?: typeof spawn;
+}
+export declare class ClaudeCodeAdapter implements HarnessAdapter {
+    private readonly deps;
+    readonly name: HarnessName;
+    readonly capabilities: HarnessCapabilities;
+    readonly requires: HarnessRequires;
+    private cachedAvailability;
+    constructor(deps?: ClaudeCodeAdapterDeps);
+    getAccountId(): Promise<string | null>;
+    isAvailable(): Promise<HarnessAvailability>;
+    invoke(input: HarnessInput, onEvent?: (e: HarnessEvent) => void): Promise<HarnessResult>;
+    availableModels(): Promise<string[]>;
+}
+//# sourceMappingURL=claude-code.d.ts.map