@ai-sdlc/orchestrator 0.6.0 → 0.9.0

package/dist/review-meta.js

@@ -0,0 +1,149 @@
+/**
+ * Meta-review pass — filters medium-confidence findings through a
+ * lightweight LLM call (Haiku) to reduce false positives.
+ *
+ * Flow:
+ *   High confidence (>0.8)  → post directly
+ *   Medium (0.5-0.8)        → meta-review decides keep/drop
+ *   Low (<0.5)              → already suppressed by parseVerdict()
+ */
+// ── Thresholds ───────────────────────────────────────────────────────
+const HIGH_CONFIDENCE = 0.8;
+// ── Meta-reviewer ────────────────────────────────────────────────────
+/**
+ * Run a meta-review pass on medium-confidence findings.
+ *
+ * @param verdict - The original verdict from a review agent
+ * @param principles - Review principles text for context
+ * @param callLLM - Function to make a single-turn LLM call (injectable for testing)
+ */
+export async function metaReview(verdict, principles, callLLM) {
+    const highConfidence = [];
+    const mediumConfidence = [];
+    for (const finding of verdict.findings) {
+        const conf = finding.confidence ?? 1.0; // legacy findings without confidence pass through
+        if (conf >= HIGH_CONFIDENCE) {
+            highConfidence.push(finding);
+        }
+        else {
+            mediumConfidence.push(finding);
+        }
+    }
+    // If no medium-confidence findings, return as-is
+    if (mediumConfidence.length === 0) {
+        return {
+            verdict,
+            decisions: [],
+            suppressed: 0,
+        };
+    }
+    // Review each medium-confidence finding
+    const decisions = [];
+    const kept = [...highConfidence];
+    for (const finding of mediumConfidence) {
+        try {
+            const decision = await reviewSingleFinding(finding, principles, callLLM);
+            decisions.push({ finding, decision });
+            if (decision.keep) {
+                kept.push({
+                    ...finding,
+                    severity: decision.adjustedSeverity ?? finding.severity,
+                });
+            }
+        }
+        catch {
+            // Meta-review failure = keep the finding (conservative)
+            kept.push(finding);
+            decisions.push({
+                finding,
+                decision: { keep: true, reason: 'Meta-review failed, keeping conservatively' },
+            });
+        }
+    }
+    return {
+        verdict: {
+            ...verdict,
+            findings: kept,
+            // If all findings were suppressed, approve
+            approved: kept.length === 0 ? true : verdict.approved,
+        },
+        decisions,
+        suppressed: Math.max(0, mediumConfidence.length - (kept.length - highConfidence.length)),
+    };
+}
+async function reviewSingleFinding(finding, principles, callLLM) {
+    const prompt = `You are a meta-reviewer evaluating whether a code review finding should be posted to a pull request.
+
+## Review Principles
+${principles}
+
+## Finding to evaluate
+- Severity: ${finding.severity}
+- Confidence: ${finding.confidence}
+- Category: ${finding.category ?? 'unknown'}
+- File: ${finding.file ?? 'N/A'}
+- Message: ${finding.message}
+${finding.evidence?.failureScenario ? `- Failure scenario: ${finding.evidence.failureScenario}` : '- No failure scenario provided'}
+${finding.evidence?.codePathTraced ? `- Code path: ${finding.evidence.codePathTraced}` : ''}
+
+## Decision criteria
+- Is this a real issue or noise?
+- Does the evidence support the severity?
+- Would a senior engineer flag this?
+- Is this something CI already catches?
+
+Respond with ONLY a JSON object:
+{"keep": true/false, "adjustedSeverity": "critical|major|minor|suggestion" (optional), "reason": "brief explanation"}`;
+    const response = await callLLM(prompt);
+    // Parse response
+    const cleaned = response.replace(/^```(?:json)?\s*/m, '').replace(/\s*```$/m, '');
+    const parsed = JSON.parse(cleaned);
+    return {
+        keep: Boolean(parsed.keep),
+        adjustedSeverity: parsed.adjustedSeverity ?? undefined,
+        reason: String(parsed.reason ?? ''),
+    };
+}
+/**
+ * Store for tracking human feedback on review findings.
+ * Used to calibrate confidence thresholds over time.
+ */
+export class ReviewFeedbackStore {
+    entries = [];
+    record(feedback) {
+        this.entries.push(feedback);
+    }
+    /** Get all feedback entries. */
+    getAll() {
+        return [...this.entries];
+    }
+    /** Get precision: accepted / (accepted + dismissed). */
+    precision() {
+        const accepted = this.entries.filter((e) => e.signal === 'accepted').length;
+        const dismissed = this.entries.filter((e) => e.signal === 'dismissed').length;
+        const total = accepted + dismissed;
+        return total === 0 ? 1.0 : accepted / total;
+    }
+    /** Get feedback by category. */
+    byCategory() {
+        const result = {};
+        for (const entry of this.entries) {
+            const cat = entry.finding.category ?? 'other';
+            if (!result[cat])
+                result[cat] = { accepted: 0, dismissed: 0, ignored: 0 };
+            result[cat][entry.signal]++;
+        }
+        return result;
+    }
+    /** Categories with high false-positive rate (dismissed > 50%). */
+    highFalsePositiveCategories() {
+        const cats = this.byCategory();
+        return Object.entries(cats)
+            .filter(([, v]) => {
+            const total = v.accepted + v.dismissed;
+            return total >= 3 && v.dismissed / total > 0.5;
+        })
+            .map(([k]) => k);
+    }
+}
+//# sourceMappingURL=review-meta.js.map

package/dist/review.d.ts

@@ -16,6 +16,10 @@ export interface ReviewOptions {
     logger?: Logger;
     /** Inject runner for testing. */
     runner?: ReviewAgentRunner;
+    /** Review principles text for meta-review context. */
+    principles?: string;
+    /** LLM caller for meta-review pass. If provided, medium-confidence findings are filtered. */
+    metaReviewLLM?: (prompt: string) => Promise<string>;
 }
 /**
  * Execute a single review agent against a PR diff.

package/dist/review.js

@@ -3,6 +3,7 @@
  * that handles context assembly and verdict extraction.
  */
 import { ReviewAgentRunner, } from './runners/review-agent.js';
+import { metaReview } from './review-meta.js';
 // ── Public API ───────────────────────────────────────────────────────
 /**
  * Execute a single review agent against a PR diff.
@@ -52,9 +53,18 @@ export async function executeReview(prNumber, diff, reviewType, context, options
         };
     }
     try {
-        const verdict = JSON.parse(result.summary);
+        let verdict = JSON.parse(result.summary);
+        verdict = { ...verdict, type: reviewType };
+        // Run meta-review on medium-confidence findings if LLM caller provided
+        if (options?.metaReviewLLM && options?.principles) {
+            const metaResult = await metaReview(verdict, options.principles, options.metaReviewLLM);
+            if (metaResult.suppressed > 0) {
+                logger?.info?.(`${reviewType} meta-review: ${metaResult.suppressed} finding(s) suppressed`);
+            }
+            verdict = metaResult.verdict;
+        }
         logger?.info?.(`${reviewType} review complete: ${verdict.approved ? 'APPROVED' : 'CHANGES REQUESTED'} (${verdict.findings.length} findings)`);
-        return { ...verdict, type: reviewType };
+        return verdict;
     }
     catch {
         logger?.error?.(`Failed to parse ${reviewType} verdict from runner output`);

package/dist/runners/claude-code-sdk.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Claude Code SDK runner — invokes Claude Code via the Agent SDK's query() API
+ * instead of spawning a CLI subprocess.
+ *
+ * Advantages over ClaudeCodeRunner:
+ * - maxBudgetUsd / maxTurns — hard limits enforced by the engine
+ * - allowedTools / disallowedTools — fine-grained tool filtering with glob patterns
+ * - appendSystemPrompt — inject governance without replacing Claude Code defaults
+ * - Structured NDJSON messages — no stdout parsing
+ */
+import type { AgentRunner, AgentContext, AgentResult } from './types.js';
+/**
+ * Map agent-role tool names to SDK-compatible tool filter patterns.
+ */
+/** @internal Exported for testing. */
+export declare function mapToolsToSdkFormat(allowedTools?: string[]): string[] | undefined;
+/**
+ * Build tool deny-list from blocked actions.
+ * Converts blockedActions glob patterns to SDK disallowedTools format.
+ */
+/** @internal Exported for testing. */
+export declare function mapBlockedActionsToSdkDenyList(blockedActions?: string[]): string[];
+/**
+ * Build governance system prompt appendix from constraints.
+ */
+/** @internal Exported for testing. */
+export declare function buildGovernancePrompt(ctx: AgentContext): string;
+export declare class ClaudeCodeSdkRunner implements AgentRunner {
+    run(ctx: AgentContext): Promise<AgentResult>;
+}
+//# sourceMappingURL=claude-code-sdk.d.ts.map

package/dist/runners/claude-code-sdk.js

@@ -0,0 +1,238 @@
+/**
+ * Claude Code SDK runner — invokes Claude Code via the Agent SDK's query() API
+ * instead of spawning a CLI subprocess.
+ *
+ * Advantages over ClaudeCodeRunner:
+ * - maxBudgetUsd / maxTurns — hard limits enforced by the engine
+ * - allowedTools / disallowedTools — fine-grained tool filtering with glob patterns
+ * - appendSystemPrompt — inject governance without replacing Claude Code defaults
+ * - Structured NDJSON messages — no stdout parsing
+ */
+import { buildPrompt } from './claude-code.js';
+import { detectChangedFiles, gitExec, runAutoFix, snapshotWorktree } from './git-utils.js';
+import { DEFAULT_MODEL, DEFAULT_ALLOWED_TOOLS, DEFAULT_LINT_COMMAND, DEFAULT_FORMAT_COMMAND, DEFAULT_COMMIT_MESSAGE_TEMPLATE, DEFAULT_COMMIT_CO_AUTHOR, } from '../defaults.js';
+/** Default budget cap per agent run. */
+const DEFAULT_MAX_BUDGET_USD = 5.0;
+/** Default turn limit per agent run. */
+const DEFAULT_MAX_TURNS = 100;
+/**
+ * Map agent-role tool names to SDK-compatible tool filter patterns.
+ */
+/** @internal Exported for testing. */
+export function mapToolsToSdkFormat(allowedTools) {
+    if (!allowedTools)
+        return undefined;
+    // SDK accepts tool names directly or glob patterns like Bash(git:*)
+    return allowedTools;
+}
+/**
+ * Build tool deny-list from blocked actions.
+ * Converts blockedActions glob patterns to SDK disallowedTools format.
+ */
+/** @internal Exported for testing. */
+export function mapBlockedActionsToSdkDenyList(blockedActions) {
+    if (!blockedActions || blockedActions.length === 0)
+        return [];
+    // Map each blocked action pattern to a Bash() deny rule
+    return blockedActions.map((pattern) => `Bash(${pattern})`);
+}
+/**
+ * Build governance system prompt appendix from constraints.
+ */
+/** @internal Exported for testing. */
+export function buildGovernancePrompt(ctx) {
+    const lines = ['## AI-SDLC Governance Constraints\n'];
+    if (ctx.constraints.blockedPaths.length > 0) {
+        lines.push(`Blocked paths (do NOT modify): ${ctx.constraints.blockedPaths.join(', ')}`);
+    }
+    if (ctx.constraints.blockedActions && ctx.constraints.blockedActions.length > 0) {
+        lines.push(`Blocked actions (NEVER execute): ${ctx.constraints.blockedActions.map((a) => `\`${a}\``).join(', ')}`);
+    }
+    lines.push(`Max files per change: ${ctx.constraints.maxFilesPerChange}`);
+    if (ctx.constraints.requireTests) {
+        lines.push('Tests required: every new module must have tests.');
+    }
+    lines.push('');
+    lines.push('**NEVER merge PRs. Only humans merge.**');
+    return lines.join('\n');
+}
+export class ClaudeCodeSdkRunner {
+    async run(ctx) {
+        // Dynamic import — SDK is an optional peer dependency
+        let query;
+        /* v8 ignore start — dynamic import fails in unit tests (SDK not installed) */
+        try {
+            const sdk = await import('@anthropic-ai/claude-agent-sdk');
+            query = sdk.query;
+        }
+        catch {
+            return {
+                success: false,
+                filesChanged: [],
+                summary: '',
+                error: '@anthropic-ai/claude-agent-sdk is not installed. Install it to use the SDK runner: pnpm add @anthropic-ai/claude-agent-sdk',
+            };
+        }
+        /* v8 ignore stop */
+        const prompt = buildPrompt(ctx);
+        const model = ctx.model ?? DEFAULT_MODEL;
+        const maxTurns = ctx.constraints.maxTurns ?? DEFAULT_MAX_TURNS;
+        const maxBudgetUsd = ctx.constraints.maxBudgetUsd ?? DEFAULT_MAX_BUDGET_USD;
+        const allowedTools = mapToolsToSdkFormat(ctx.allowedTools ?? DEFAULT_ALLOWED_TOOLS.split(','));
+        const disallowedTools = mapBlockedActionsToSdkDenyList(ctx.constraints.blockedActions);
+        const governancePrompt = buildGovernancePrompt(ctx);
+        let summary = '';
+        let tokenUsage;
+        // Capture worktree state before invoking the agent so untracked noise
+        // doesn't get swept into the eventual `git add`.
+        const baseline = await snapshotWorktree(ctx.workDir);
+        /* v8 ignore start — SDK streaming loop requires real SDK connection */
+        try {
+            const result = query({
+                prompt,
+                options: {
+                    model,
+                    maxTurns,
+                    maxBudgetUsd,
+                    appendSystemPrompt: governancePrompt,
+                    allowedTools,
+                    disallowedTools: disallowedTools.length > 0 ? disallowedTools : undefined,
+                    permissionMode: 'acceptEdits',
+                    cwd: ctx.workDir,
+                },
+            });
+            for await (const msg of result) {
+                const msgType = msg.type;
+                // Emit progress events
+                if (msgType === 'assistant' && ctx.onProgress) {
+                    const blocks = msg.message?.content;
+                    if (blocks) {
+                        for (const block of blocks) {
+                            if (block.type === 'tool_use') {
+                                ctx.onProgress({
+                                    type: 'tool_start',
+                                    tool: block.name,
+                                    message: `${block.name}`,
+                                });
+                            }
+                            else if (block.type === 'text') {
+                                summary = (block.text ?? '').slice(0, 2000);
+                            }
+                        }
+                    }
+                }
+                // Parse result event for token usage and cost
+                if (msgType === 'result') {
+                    const usage = msg.usage;
+                    const resultModel = msg.model ?? model;
+                    if (usage) {
+                        tokenUsage = {
+                            inputTokens: usage.input_tokens ?? 0,
+                            outputTokens: usage.output_tokens ?? 0,
+                            cacheReadTokens: usage.cache_read_input_tokens,
+                            model: resultModel,
+                        };
+                    }
+                    if (ctx.onProgress) {
+                        ctx.onProgress({
+                            type: 'cost',
+                            costUsd: msg.cost_usd,
+                        });
+                    }
+                    // Check exit reason
+                    const subtype = msg.subtype;
+                    if (subtype === 'error_max_turns') {
+                        return {
+                            success: false,
+                            filesChanged: [],
+                            summary: `Agent hit turn limit (${maxTurns})`,
+                            error: `Max turns (${maxTurns}) exceeded`,
+                            tokenUsage,
+                        };
+                    }
+                    if (subtype === 'error_max_budget_usd') {
+                        return {
+                            success: false,
+                            filesChanged: [],
+                            summary: `Agent hit budget limit ($${maxBudgetUsd})`,
+                            error: `Max budget ($${maxBudgetUsd}) exceeded`,
+                            tokenUsage,
+                        };
+                    }
+                }
+            }
+        }
+        catch (err) {
+            return {
+                success: false,
+                filesChanged: [],
+                summary: '',
+                error: `SDK runner error: ${err.message}`,
+                tokenUsage,
+            };
+        }
+        /* v8 ignore stop */
+        /* v8 ignore start — post-SDK commit/lint logic only runs when SDK succeeds */
+        // Detect changed files (same logic as ClaudeCodeRunner), excluding any
+        // untracked noise that pre-existed the agent invocation.
+        const { filesChanged, agentAlreadyCommitted } = await detectChangedFiles(ctx.workDir, baseline);
+        if (filesChanged.length === 0) {
+            return {
+                success: false,
+                filesChanged: [],
+                summary: 'Agent made no changes',
+                error: 'No files were modified',
+                tokenUsage,
+            };
+        }
+        if (agentAlreadyCommitted) {
+            return {
+                success: true,
+                filesChanged,
+                summary,
+                tokenUsage,
+            };
+        }
+        // Stage only the files the agent touched (NOT `git add -A` — the
+        // AISDLC-68 incident showed `add -A` sweeps in pre-existing untracked
+        // noise like sqlite working files and unrelated draft files).
+        await gitExec(ctx.workDir, ['add', '--', ...filesChanged]);
+        const lintCmd = ctx.lintCommand ?? DEFAULT_LINT_COMMAND;
+        const fmtCmd = ctx.formatCommand ?? DEFAULT_FORMAT_COMMAND;
+        await runAutoFix(ctx.workDir, lintCmd, fmtCmd);
+        await gitExec(ctx.workDir, ['add', '--', ...filesChanged]);
+        const tmpl = ctx.commitMessageTemplate ?? DEFAULT_COMMIT_MESSAGE_TEMPLATE;
+        const coAuthor = ctx.commitCoAuthor ?? DEFAULT_COMMIT_CO_AUTHOR;
+        const commitMsg = tmpl
+            .replace(/\{issueNumber\}/g, ctx.issueId)
+            .replace(/\{issueTitle\}/g, ctx.issueTitle);
+        try {
+            await gitExec(ctx.workDir, ['commit', '-m', `${commitMsg}\n\nCo-Authored-By: ${coAuthor}`]);
+        }
+        catch {
+            // Pre-commit hook failure — auto-fix and retry once
+            await runAutoFix(ctx.workDir, lintCmd, fmtCmd);
+            await gitExec(ctx.workDir, ['add', '--', ...filesChanged]);
+            try {
+                await gitExec(ctx.workDir, ['commit', '-m', `${commitMsg}\n\nCo-Authored-By: ${coAuthor}`]);
+            }
+            catch (retryErr) {
+                return {
+                    success: false,
+                    filesChanged,
+                    summary,
+                    error: `Commit failed after auto-fix retry: ${retryErr.message}`,
+                    tokenUsage,
+                };
+            }
+        }
+        return {
+            success: true,
+            filesChanged,
+            summary,
+            tokenUsage,
+        };
+        /* v8 ignore stop */
+    }
+}
+//# sourceMappingURL=claude-code-sdk.js.map

package/dist/runners/claude-code.d.ts

@@ -9,6 +9,9 @@ export declare function buildPrompt(ctx: AgentContext): string;
  * Claude Code CLI outputs token info to stderr in various formats.
  */
 export declare function parseTokenUsage(stderr: string, model: string): TokenUsage | undefined;
+/**
+ * Run lint --fix and format commands (best-effort) so pre-commit hooks pass.
+ */
 export declare class ClaudeCodeRunner implements AgentRunner {
     run(ctx: AgentContext): Promise<AgentResult>;
 }

package/dist/runners/claude-code.js

@@ -2,11 +2,10 @@
  * Claude Code runner — invokes Claude Code CLI in --print mode
  * and collects the result via git diff.
  */
-import { spawn, execFile } from 'node:child_process';
-import { promisify } from 'node:util';
+import { spawn } from 'node:child_process';
 import { DEFAULT_MODEL, DEFAULT_ALLOWED_TOOLS, DEFAULT_RUNNER_TIMEOUT_MS, DEFAULT_LINT_COMMAND, DEFAULT_FORMAT_COMMAND, DEFAULT_COMMIT_MESSAGE_TEMPLATE, DEFAULT_COMMIT_CO_AUTHOR, } from '../defaults.js';
 import { formatContextForPrompt } from '../analysis/context-builder.js';
-const execFileAsync = promisify(execFile);
+import { gitExec, detectChangedFiles, runAutoFix, snapshotWorktree, detectCrossRepoWrites, } from './git-utils.js';
 /**
  * Build verification step instructions (lint, format, typecheck).
  * Returns an array of numbered step strings starting from the given step number.
@@ -90,10 +89,6 @@ export function buildPrompt(ctx) {
     }
     return lines.join('\n');
 }
-async function gitExec(workDir, args) {
-    const { stdout } = await execFileAsync('git', args, { cwd: workDir });
-    return stdout.trim();
-}
 /**
  * Format a stream-json event into a concise, human-readable log line.
  */
@@ -402,30 +397,15 @@ export function parseTokenUsage(stderr, model) {
 /**
  * Run lint --fix and format commands (best-effort) so pre-commit hooks pass.
  */
-async function runAutoFix(workDir, lintCmd, fmtCmd) {
-    if (fmtCmd) {
-        try {
-            const [bin, ...args] = fmtCmd.split(' ');
-            await execFileAsync(bin, args, { cwd: workDir });
-        }
-        catch {
-            // Format failures are non-fatal — the commit hook will catch remaining issues
-        }
-    }
-    if (lintCmd) {
-        try {
-            const [bin, ...args] = lintCmd.split(' ');
-            await execFileAsync(bin, args, { cwd: workDir });
-        }
-        catch {
-            // Lint --fix failures are non-fatal
-        }
-    }
-}
 export class ClaudeCodeRunner {
     async run(ctx) {
         const prompt = buildPrompt(ctx);
         try {
+            // Snapshot the worktree BEFORE invoking the agent so we can subtract any
+            // pre-existing untracked noise (sqlite working files, draft files the user
+            // hasn't decided to commit yet, in-flight edits) from the agent's diff.
+            // Without this, `git add` would sweep them into the agent's commit.
+            const baseline = await snapshotWorktree(ctx.workDir);
             // Invoke Claude Code CLI with stream-json for real-time progress
             const result = await runClaude(prompt, ctx.workDir, {
                 allowedTools: ctx.allowedTools,
@@ -436,39 +416,9 @@ export class ClaudeCodeRunner {
             });
             // Token usage from stream-json result event (falls back to stderr parsing)
             const tokenUsage = parseTokenUsage(result.stderr, result.model);
-            // Collect changed files — check both uncommitted and already-committed changes
-            // The agent may have committed on its own (Claude Code can run git commit)
-            const diffOutput = await gitExec(ctx.workDir, ['diff', '--name-only']);
-            const untrackedOutput = await gitExec(ctx.workDir, [
-                'ls-files',
-                '--others',
-                '--exclude-standard',
-            ]);
-            const uncommittedFiles = [
-                ...diffOutput.split('\n').filter(Boolean),
-                ...untrackedOutput.split('\n').filter(Boolean),
-            ];
-            // Check if agent already committed (and possibly pushed) —
-            // compare against the merge base with the target branch (main)
-            let committedFiles = [];
-            let agentAlreadyCommitted = false;
-            try {
-                // Find the merge base with main to see all new commits on this branch
-                const mergeBase = (await gitExec(ctx.workDir, ['merge-base', 'HEAD', 'origin/main'])).trim();
-                if (mergeBase) {
-                    const commitDiff = await gitExec(ctx.workDir, [
-                        'diff',
-                        '--name-only',
-                        `${mergeBase}..HEAD`,
-                    ]);
-                    committedFiles = commitDiff.split('\n').filter(Boolean);
-                    agentAlreadyCommitted = committedFiles.length > 0 && uncommittedFiles.length === 0;
-                }
-            }
-            catch {
-                // merge-base may fail if main doesn't exist locally — that's fine
-            }
-            const filesChanged = agentAlreadyCommitted ? committedFiles : uncommittedFiles;
+            // Collect changed files (uncommitted + agent-committed), excluding
+            // pre-existing untracked noise.
+            const { filesChanged, agentAlreadyCommitted } = await detectChangedFiles(ctx.workDir, baseline);
             if (filesChanged.length === 0) {
                 return {
                     success: false,
@@ -487,14 +437,17 @@ export class ClaudeCodeRunner {
                     tokenUsage,
                 };
             }
-            // Stage, lint/format, and commit
-            await gitExec(ctx.workDir, ['add', '-A']);
+            // Stage only the files the agent touched (NOT `git add -A`, which
+            // would include pre-existing untracked noise per the AISDLC-68 incident).
+            await gitExec(ctx.workDir, ['add', '--', ...filesChanged]);
             // Run lint and format before committing to avoid pre-commit hook failures
             const lintCmd = ctx.lintCommand ?? DEFAULT_LINT_COMMAND;
             const fmtCmd = ctx.formatCommand ?? DEFAULT_FORMAT_COMMAND;
             await runAutoFix(ctx.workDir, lintCmd, fmtCmd);
-            // Re-stage after auto-fix may have modified files
-            await gitExec(ctx.workDir, ['add', '-A']);
+            // Re-stage the same set in case auto-fix re-modified them. Auto-fix should
+            // not touch files outside the agent's diff, but if it does, those changes
+            // are the user's problem to commit separately.
+            await gitExec(ctx.workDir, ['add', '--', ...filesChanged]);
             const tmpl = ctx.commitMessageTemplate ?? DEFAULT_COMMIT_MESSAGE_TEMPLATE;
             const coAuthor = ctx.commitCoAuthor ?? DEFAULT_COMMIT_CO_AUTHOR;
             const commitMsg = tmpl
@@ -504,11 +457,22 @@ export class ClaudeCodeRunner {
                 await gitExec(ctx.workDir, ['commit', '-m', `${commitMsg}\n\nCo-Authored-By: ${coAuthor}`]);
             }
             catch {
-                // Pre-commit hook may have auto-fixed files — re-stage and retry once
+                // Pre-commit hook may have auto-fixed files — re-stage the agent's
+                // file set and retry once.
                 await runAutoFix(ctx.workDir, lintCmd, fmtCmd);
-                await gitExec(ctx.workDir, ['add', '-A']);
+                await gitExec(ctx.workDir, ['add', '--', ...filesChanged]);
                 await gitExec(ctx.workDir, ['commit', '-m', `${commitMsg}\n\nCo-Authored-By: ${coAuthor}`]);
             }
+            // Detect cross-repo writes (e.g., agent edited files in ../sister-repo)
+            // and surface them as a stderr warning so the operator knows to commit
+            // them in the sibling repo separately. Not a hard failure — sometimes
+            // cross-repo work is intended (the AISDLC-68 docs sync, for example).
+            const crossRepoWrites = await detectCrossRepoWrites(ctx.workDir);
+            for (const write of crossRepoWrites) {
+                process.stderr.write(`[ai-sdlc:runner] WARNING: agent wrote ${write.files.length} file(s) into sibling repo ` +
+                    `${write.repoPath} — those changes are NOT in this PR. ` +
+                    `Files: ${write.files.slice(0, 5).join(', ')}${write.files.length > 5 ? ` (+${write.files.length - 5} more)` : ''}\n`);
+            }
             return {
                 success: true,
                 filesChanged,

package/dist/runners/codex.js

@@ -6,10 +6,13 @@ import { spawn, execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { DEFAULT_RUNNER_TIMEOUT_MS, DEFAULT_CODEX_MODEL, DEFAULT_COMMIT_MESSAGE_TEMPLATE, DEFAULT_COMMIT_CO_AUTHOR, } from '../defaults.js';
 import { buildPrompt } from './claude-code.js';
+import { cleanGitEnv } from '../runtime/git-env.js';
 export { buildPrompt };
 const execFileAsync = promisify(execFile);
+// Strip GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE so git resolves against
+// `workDir`'s own .git rather than whatever a parent process leaked (AISDLC-72).
 async function gitExec(workDir, args) {
-    const { stdout } = await execFileAsync('git', args, { cwd: workDir });
+    const { stdout } = await execFileAsync('git', args, { cwd: workDir, env: cleanGitEnv() });
     return stdout.trim();
 }
 /**

package/dist/runners/copilot.js

@@ -6,10 +6,13 @@ import { spawn, execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { DEFAULT_RUNNER_TIMEOUT_MS, DEFAULT_COPILOT_MODEL, DEFAULT_COMMIT_MESSAGE_TEMPLATE, DEFAULT_COMMIT_CO_AUTHOR, } from '../defaults.js';
 import { buildPrompt } from './claude-code.js';
+import { cleanGitEnv } from '../runtime/git-env.js';
 export { buildPrompt };
 const execFileAsync = promisify(execFile);
+// Strip GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE so git resolves against
+// `workDir`'s own .git rather than whatever a parent process leaked (AISDLC-72).
 async function gitExec(workDir, args) {
-    const { stdout } = await execFileAsync('git', args, { cwd: workDir });
+    const { stdout } = await execFileAsync('git', args, { cwd: workDir, env: cleanGitEnv() });
     return stdout.trim();
 }
 /**

package/dist/runners/cursor.js

@@ -6,10 +6,13 @@ import { spawn, execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { DEFAULT_RUNNER_TIMEOUT_MS, DEFAULT_CURSOR_MODEL, DEFAULT_COMMIT_MESSAGE_TEMPLATE, DEFAULT_COMMIT_CO_AUTHOR, } from '../defaults.js';
 import { buildPrompt } from './claude-code.js';
+import { cleanGitEnv } from '../runtime/git-env.js';
 export { buildPrompt };
 const execFileAsync = promisify(execFile);
+// Strip GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE so git resolves against
+// `workDir`'s own .git rather than whatever a parent process leaked (AISDLC-72).
 async function gitExec(workDir, args) {
-    const { stdout } = await execFileAsync('git', args, { cwd: workDir });
+    const { stdout } = await execFileAsync('git', args, { cwd: workDir, env: cleanGitEnv() });
     return stdout.trim();
 }
 /**