@ai-sdlc/orchestrator 0.9.0 → 0.13.0

package/dist/embedding/types.d.ts

@@ -0,0 +1,180 @@
+/**
+ * EmbeddingAdapter interface per RFC-0019 §5.
+ *
+ * Every embedding adapter MUST implement this interface. Adapters are registered
+ * in orchestrator/src/embedding/registry.ts and resolved by name at pipeline-load.
+ *
+ * The pattern mirrors HarnessAdapter (RFC-0010 §13) and DatabaseBranchAdapter (RFC-0010 §15).
+ */
+/**
+ * Result of an adapter liveness probe (isAvailable()).
+ */
+export interface EmbeddingAvailability {
+    available: boolean;
+    /** Structured reason — helps operators understand what to fix. */
+    reason?: 'env-var-missing' | 'health-check-failed' | 'rate-limited' | 'unknown';
+    /** Human-readable detail naming the missing env var or failing probe. */
+    detail?: string;
+}
+/**
+ * Runtime dependency declaration for an embedding adapter.
+ * Parallel to HarnessRequires in RFC-0010 §13.8.
+ */
+export interface EmbeddingRequires {
+    /** Environment variable required by this adapter (e.g., 'OPENAI_API_KEY'). */
+    envVar?: string;
+    /** Optional npm package or binary name required (for local/ONNX adapters). */
+    binary?: string;
+    /** Semver range for the binary, if applicable. */
+    versionRange?: string;
+    /** Path to model file (e.g., for ONNX-based adapters). */
+    modelFile?: string;
+}
+/**
+ * Billing model for the adapter — drives cost-tracker routing.
+ *
+ * - 'pay-per-token': tokens are billed via provider invoice (e.g., OpenAI).
+ *   embeddingTokens are recorded in cost-tracker but do NOT consume SubscriptionLedger
+ *   window quota (OQ-7 re-walkthrough).
+ * - 'subscription-quota': tokens are billed via the operator's subscription
+ *   (e.g., future Anthropic embeddings). Routes through SubscriptionLedger via
+ *   the inputTokens/outputTokens mechanism.
+ */
+export type EmbeddingBillingModel = 'pay-per-token' | 'subscription-quota';
+/**
+ * Capability matrix for an embedding adapter (RFC-0019 §6.2).
+ * Normative for in-tree adapters; adopter-registered adapters SHOULD declare these.
+ */
+export interface EmbeddingCapabilities {
+    /** Output vector length. */
+    dimensions: number;
+    /** Maximum tokens per single embed() call. */
+    maxInputTokens: number;
+    /** Whether the adapter implements embedBatch(). */
+    supportsBatching: boolean;
+    /** Whether the adapter runs locally (no external API call). */
+    selfHosted: boolean;
+    /** Billing model — drives cost-tracker routing (OQ-7 re-walkthrough). */
+    billingModel: EmbeddingBillingModel;
+    /** Approximate cost per 1M tokens in USD (for display / cost estimation). Null for local. */
+    approxCostPer1MTokens?: number;
+    /**
+     * Adapter-declared default deprecation grace period in days per RFC-0019
+     * §9.1 OQ-4 re-walkthrough. When set, this overrides the framework default
+     * (90d) but is itself overridden by per-org `gracePeriodDays`. Fast-moving
+     * providers (e.g., Cohere with 6-month deprecation cycles) declare a smaller
+     * value here so the warning window scales to the provider's actual lifecycle.
+     *
+     * The three-layer precedence is:
+     *   per-org `gracePeriodDays` (highest)
+     *   adapter `defaultGracePeriodDays` (this field)
+     *   framework `FRAMEWORK_DEFAULT_GRACE_PERIOD_DAYS` (90, lowest)
+     */
+    defaultGracePeriodDays?: number;
+}
+/**
+ * The EmbeddingAdapter interface per RFC-0019 §5.
+ * Implemented by every embedding adapter registered in the registry.
+ */
+export interface EmbeddingAdapter {
+    /**
+     * Canonical adapter alias — the value adopters set in Pipeline.spec.embedding.provider.
+     * MUST be unique across the registry. Convention: '<vendor>-<model-family>-<size>'.
+     * Examples: 'openai-text-embedding-3-small', 'cohere-embed-v3-multilingual'.
+     */
+    readonly name: string;
+    /**
+     * Provider-specific model identifier — passed to the upstream API.
+     * Example: 'text-embedding-3-small' (posted to OpenAI's /embeddings endpoint).
+     */
+    readonly modelId: string;
+    /**
+     * Snapshot identifier — ISO date for date-pinned snapshots, semver for versioned models.
+     * Used as part of the storage key so vectors don't collide across model snapshots.
+     * Example: '2024-01-25' for OpenAI's 2024-01-25 text-embedding-3-small snapshot.
+     */
+    readonly modelVersion: string;
+    /**
+     * Vector length the adapter emits. Validated against storage on first write.
+     * Redundant with capabilities.dimensions but declared at the top level for
+     * fast dimension-mismatch detection without unpacking capabilities.
+     */
+    readonly dimensions: number;
+    /** Static capability matrix. */
+    readonly capabilities: EmbeddingCapabilities;
+    /** Runtime dependency declaration. */
+    readonly requires: EmbeddingRequires;
+    /**
+     * ISO date when the deprecation warning period starts.
+     * When set, pipeline-load emits EmbeddingModelDeprecating warning 90d before
+     * and EmbeddingModelDeprecated error at/after this date.
+     */
+    readonly deprecatedAt?: string;
+    /**
+     * ISO date when the adapter is removed.
+     * When set AND today >= removedAt, pipeline-load FAILS with EmbeddingModelRemoved.
+     */
+    readonly removedAt?: string;
+    /**
+     * Canonical name of the adapter operators should migrate to.
+     * Included in deprecation warnings/errors.
+     */
+    readonly replacementAlias?: string;
+    /**
+     * Embed a single text string. Returns the vector as number[].
+     *
+     * Implementations MUST:
+     *  - throw on empty input (no silent zero-vector emission)
+     *  - throw on input exceeding the provider's per-call token limit
+     *  - return a vector of length === this.dimensions (orchestrator validates post-hoc)
+     *
+     * @param text - Source text to embed. MUST be non-empty.
+     * @param consumerLabel - Optional label for cost attribution per OQ-6 re-walkthrough.
+     *   Default: 'unspecified'. Examples: 'rfc-0009-tessellation-drift', 'rfc-0008-ppa-similarity'.
+     */
+    embed(text: string, consumerLabel?: string): Promise<number[]>;
+    /**
+     * Optional batch interface. Adapters MAY implement for efficiency; orchestrator
+     * calls embed() in a loop when this is undefined.
+     * Implementations MUST preserve input order in the returned array.
+     *
+     * @param texts - Array of source texts to embed. Each MUST be non-empty.
+     * @param consumerLabel - Optional label for cost attribution. Applies to all texts in batch.
+     */
+    embedBatch?(texts: string[], consumerLabel?: string): Promise<number[][]>;
+    /**
+     * Cheap liveness probe. Combines env-var presence (e.g., OPENAI_API_KEY)
+     * + lightweight provider health check (optional).
+     * Result MAY be cached for the orchestrator's lifetime.
+     */
+    isAvailable(): Promise<EmbeddingAvailability>;
+    /**
+     * Stable identifier for the credential / account in scope. Used by cost-tracker
+     * to attribute spend per credential. MUST be a one-way derivation (e.g., SHA-256
+     * of the API key + adapter name) and MUST NOT leak the credential itself.
+     * Returns null when the adapter cannot derive an account identity (e.g., self-hosted).
+     */
+    getAccountId(): Promise<string | null>;
+}
+/**
+ * Record of a single embedding cost event, passed to the cost-tracker.
+ * Captures the (provider, modelVersion, accountId, consumerLabel) dimensions
+ * per OQ-6 re-walkthrough.
+ */
+export interface EmbeddingCostRecord {
+    /** Adapter name (e.g., 'openai-text-embedding-3-small'). */
+    provider: string;
+    /** Adapter model version (e.g., '2024-01-25'). */
+    modelVersion: string;
+    /** One-way hash of the API credential, or null for self-hosted. */
+    accountId: string | null;
+    /** Consumer attribution label for per-consumer cost breakdown. Default: 'unspecified'. */
+    consumerLabel: string;
+    /** Total tokens consumed by this embed() call. */
+    tokens: number;
+    /** USD cost for this call. */
+    costUsd: number;
+    /** Billing model — used to decide whether to decrement SubscriptionLedger. */
+    billingModel: EmbeddingBillingModel;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/embedding/types.js

@@ -0,0 +1,10 @@
+/**
+ * EmbeddingAdapter interface per RFC-0019 §5.
+ *
+ * Every embedding adapter MUST implement this interface. Adapters are registered
+ * in orchestrator/src/embedding/registry.ts and resolved by name at pipeline-load.
+ *
+ * The pattern mirrors HarnessAdapter (RFC-0010 §13) and DatabaseBranchAdapter (RFC-0010 §15).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/execute.d.ts

@@ -6,6 +6,7 @@
  *   create branch -> invoke agent -> authorize -> validate -> push -> create PR -> comment
  */
 import { type IssueTracker, type SourceControl, type AuditLog, type MetricStore, type AgentMemory, type ExpressionEvaluator, type LLMEvaluator, type SecretStore } from '@ai-sdlc/reference';
+import { type AiSdlcConfig } from './config.js';
 import { type Logger } from './logger.js';
 import type { AgentRunner } from './runners/types.js';
 import { type SecurityContext } from './security.js';
@@ -30,8 +31,14 @@ export interface ExecuteOptions {
     configDir?: string;
     /** Override the working directory (defaults to `process.cwd()`). */
     workDir?: string;
-    /** Inject a custom runner (for testing). */
+    /** Inject a custom runner (for testing). Wins over runnerName and registry. */
     runner?: AgentRunner;
+    /**
+     * Select a runner by name from the registry (maps to `--runner <name>` CLI flag).
+     * Must be registered (built-in, env-discovered, or loaded via AI_SDLC_RUNNER_PLUGIN).
+     * Throws when the name is unknown — no silent fallback.
+     */
+    runnerName?: string;
     /** Inject a custom issue tracker (for testing). */
     tracker?: IssueTracker;
     /** Inject a custom source control adapter (for testing). */
@@ -85,6 +92,20 @@ export interface ExecuteOptions {
      */
     pipelineOverride?: import('@ai-sdlc/reference').Pipeline;
 }
+/**
+ * Build an actionable error message when a required resource kind is absent.
+ *
+ * The loader silently drops resource-shaped YAML files that fail schema
+ * validation (recording them as `config.warnings`). Without this helper, the
+ * caller would only see "No <Kind> resource found in .ai-sdlc/" with no pointer
+ * to the real cause. This helper attaches any relevant warnings so the adopter
+ * knows *which* file to fix and *why* it was dropped.
+ *
+ * Non-resource YAMLs (no apiVersion+kind) are silently skipped by design
+ * (AISDLC-722 guard); this helper is only called when the resource is truly
+ * absent — i.e. no file with the right kind and a passing schema exists.
+ */
+export declare function buildMissingResourceError(kind: string, config: AiSdlcConfig, configDir: string): string;
 /**
  * Execute the full AI-SDLC pipeline for a given issue ID.
  */
@@ -116,9 +137,15 @@ export declare function restoreOriginalBranch(workDir: string, originalHead: str
  * rebase HEAD onto origin/<branch>, retry once. Rebase conflicts surface as
  * the original error so the operator can resolve manually.
  *
+ * Local-only mode (AISDLC-530 / AISDLC-527): when there is no 'origin' remote,
+ * push is skipped gracefully (returns true to signal the skip). This mirrors the
+ * AISDLC-527 fetch guard at step 7 — we detect the "no such remote" pattern in
+ * the push error and swallow it exactly as the fetch step does.
+ *
+ * @returns `true` when push was skipped (local-only repo), `false` when pushed successfully.
  * @internal — exported for unit tests.
  */
 export declare function pushBranchWithRebase(workDir: string, branchName: string, log: {
     info: (msg: string) => void;
-} | undefined): Promise<void>;
+} | undefined): Promise<boolean>;
 //# sourceMappingURL=execute.d.ts.map

package/dist/execute.js

@@ -5,13 +5,13 @@
  *   load config -> fetch issue -> validate -> check autonomy ->
  *   create branch -> invoke agent -> authorize -> validate -> push -> create PR -> comment
  */
-import { createGitHubSourceControl, routeByComplexity, evaluatePromotion, evaluateComplexity, selectModel, withSpan, getMeter, SPAN_NAMES, METRIC_NAMES, ATTRIBUTE_KEYS, } from '@ai-sdlc/reference';
+import { 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 { createRunnerRegistry, resolveRunner } from './runners/runner-registry.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';
@@ -23,7 +23,7 @@ import { createPipelineExpressionEvaluator, createPipelineLLMEvaluator, createPi
 import { verifyAuditIntegrity, createFileAuditLog, loadAuditEntries, computeAuditHash, } from './audit-extended.js';
 import { renderTemplate } from './notifications.js';
 import { admitIssueResource, createPipelineAdmission, } from './admission.js';
-import { createPipelineAdapterRegistry, createPipelineWebhookBridge, resolveAdapterFromGit, scanPipelineAdapters, resolveIssueTrackerFromConfig, } from './adapters.js';
+import { createPipelineAdapterRegistry, createPipelineWebhookBridge, resolveAdapterFromGit, scanPipelineAdapters, resolveIssueTrackerFromConfig, resolveSourceControlFromConfig, } from './adapters.js';
 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';
@@ -35,6 +35,33 @@ 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';
+/**
+ * Build an actionable error message when a required resource kind is absent.
+ *
+ * The loader silently drops resource-shaped YAML files that fail schema
+ * validation (recording them as `config.warnings`). Without this helper, the
+ * caller would only see "No <Kind> resource found in .ai-sdlc/" with no pointer
+ * to the real cause. This helper attaches any relevant warnings so the adopter
+ * knows *which* file to fix and *why* it was dropped.
+ *
+ * Non-resource YAMLs (no apiVersion+kind) are silently skipped by design
+ * (AISDLC-722 guard); this helper is only called when the resource is truly
+ * absent — i.e. no file with the right kind and a passing schema exists.
+ */
+export function buildMissingResourceError(kind, config, configDir) {
+    const base = `No ${kind} resource found in ${configDir}`;
+    // Find any warnings that mention this kind — these are resource-shaped files
+    // that had `apiVersion`+`kind` but failed schema validation and were dropped.
+    const relevant = (config.warnings ?? []).filter((w) => w.error.includes('validation failed') || w.error.includes('unknown kind'));
+    if (relevant.length === 0) {
+        return `${base}. Add a ${kind} YAML file to your .ai-sdlc/ directory. Run \`ai-sdlc init\` to scaffold a minimal working configuration.`;
+    }
+    const details = relevant.map((w) => `  - ${w.file}: ${w.error}`).join('\n');
+    return (`${base}.\n` +
+        `The following file(s) declared a resource but failed schema validation and were dropped:\n` +
+        `${details}\n` +
+        `Fix the validation error(s) above, or run \`ai-sdlc init\` to scaffold a minimal working configuration.`);
+}
 /**
  * Execute the full AI-SDLC pipeline for a given issue ID.
  */
@@ -45,11 +72,14 @@ 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.
+    // RFC-0010 §6/§7 Phase 2: parallelism. Per AISDLC-116 (maintainer directive 2026-05-01),
+    // AI_SDLC_PARALLELISM now defaults to 'on' — corpus-driven (no parallelism-related incidents
+    // in the trailing observation window) rather than calendar-driven. Explicit
+    // 'experimental' is preserved for callers pinning the pre-promotion mode; explicit
+    // 'off' / 'disabled' / 'false' / '0' is the opt-out path. When the resolved mode is
+    // not 'off', a WorktreePoolManager is instantiated for the worker-pool dispatcher
+    // (RFC-0010 §9). The manager is constructed but not yet routed through — Phase 2
+    // shipped the wire-in surface; Phase 3 wires the worker pool to consume it.
     const parallelismMode = readParallelismMode();
     let worktreePool;
     if (parallelismMode !== 'off') {
@@ -86,13 +116,13 @@ export async function executePipeline(issueId, options = {}) {
         });
     }
     if (!config.qualityGate) {
-        throw new Error('No QualityGate resource found in .ai-sdlc/');
+        throw new Error(buildMissingResourceError('QualityGate', config, configDir));
     }
     if (!config.agentRole) {
-        throw new Error('No AgentRole resource found in .ai-sdlc/');
+        throw new Error(buildMissingResourceError('AgentRole', config, configDir));
     }
     if (!config.autonomyPolicy) {
-        throw new Error('No AutonomyPolicy resource found in .ai-sdlc/');
+        throw new Error(buildMissingResourceError('AutonomyPolicy', config, configDir));
     }
     // Capture narrowed types for use in closures
     const qualityGate = config.qualityGate;
@@ -111,7 +141,11 @@ export async function executePipeline(issueId, options = {}) {
     const { org, repo } = getGitHubConfig(options.secretStore);
     const ghConfig = { org, repo, token: { secretRef: 'github-token' } };
     const tracker = options.tracker ?? resolveIssueTrackerFromConfig(config, ghConfig);
-    const sc = options.sourceControl ?? createGitHubSourceControl(ghConfig);
+    // Resolve the source-control adapter from AdapterBinding config.
+    // options.sourceControl injection still wins (programmatic/testing use).
+    // When no SourceControl AdapterBinding is present, defaults to GitHub exactly
+    // as before — no regression for existing GitHub adopters (AC #2, AISDLC-530).
+    const sc = options.sourceControl ?? resolveSourceControlFromConfig(config, ghConfig);
     // 3. Fetch issue
     log.stage('validate-issue');
     const issue = await tracker.getIssue(issueId);
@@ -230,6 +264,12 @@ export async function restoreOriginalBranch(workDir, originalHead, log) {
  * rebase HEAD onto origin/<branch>, retry once. Rebase conflicts surface as
  * the original error so the operator can resolve manually.
  *
+ * Local-only mode (AISDLC-530 / AISDLC-527): when there is no 'origin' remote,
+ * push is skipped gracefully (returns true to signal the skip). This mirrors the
+ * AISDLC-527 fetch guard at step 7 — we detect the "no such remote" pattern in
+ * the push error and swallow it exactly as the fetch step does.
+ *
+ * @returns `true` when push was skipped (local-only repo), `false` when pushed successfully.
  * @internal — exported for unit tests.
  */
 export async function pushBranchWithRebase(workDir, branchName, log) {
@@ -238,10 +278,16 @@ export async function pushBranchWithRebase(workDir, branchName, log) {
     const env = cleanGitEnv();
     try {
         await execFileAsync('git', ['push', 'origin', branchName], { cwd: workDir, env });
-        return;
+        return false;
     }
     catch (err) {
         const stderr = err.stderr ?? err.message;
+        // Local-only repos: no 'origin' remote configured — skip push gracefully.
+        // Mirror the AISDLC-527 fetch guard pattern exactly.
+        if (/no such remote|does not appear to be a git repository/i.test(stderr)) {
+            log?.info(`[pipeline] git push skipped: no 'origin' remote configured (local-only repo)`);
+            return true;
+        }
         if (!/non-fast-forward|rejected/i.test(stderr)) {
             throw err;
         }
@@ -264,6 +310,7 @@ export async function pushBranchWithRebase(workDir, branchName, log) {
             `Resolve conflicts manually and re-run the pipeline.`);
     }
     await execFileAsync('git', ['push', 'origin', branchName], { cwd: workDir, env });
+    return false;
 }
 async function executePipelineBody(issueId, issue, config, qualityGate, agentRole, autonomyPolicy, tracker, sc, auditLog, metricStore, options, log, workDir) {
     const issueNumber = issueIdToNumber(issueId);
@@ -408,11 +455,53 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
     const branchName = interpolateBranchPattern(config.pipeline?.spec.branching?.pattern, branchVars);
     await sc.createBranch({ name: branchName });
     // 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() });
+    // Guard: skip fetch when no 'origin' remote is configured (local-only repos).
+    // The push step already degrades gracefully for local repos; fetch must too.
+    //
+    // AISDLC-530 review fix: track whether we are in local-only mode so the checkout
+    // step can use `git checkout -b` (create) instead of `git checkout` (switch to
+    // existing).  Remote paths create the branch via the SC adapter API THEN fetch it
+    // locally — so the branch already exists locally after the fetch, and plain
+    // `git checkout <name>` is correct.  Local-only paths never have a remote, the
+    // SC adapter's createBranch is a no-op, so the branch does NOT exist yet and we
+    // MUST use `-b` to create it in one step.
+    let localOnlyMode = false;
+    try {
+        await execFileAsync('git', ['fetch', 'origin', branchName], {
+            cwd: workDir,
+            env: cleanGitEnv(),
+        });
+    }
+    catch (fetchErr) {
+        const fetchMsg = fetchErr.stderr ??
+            fetchErr.message ??
+            '';
+        // Only swallow the "origin remote is not configured at all" shape (local-only
+        // repos). Do NOT match a bare "not found" — that also matches "repository not
+        // found" (origin IS configured but the URL is wrong/deleted/inaccessible), which
+        // must propagate as a real config error rather than be silently skipped
+        // (AISDLC-527 code-review finding).
+        if (/no such remote|does not appear to be a git repository/i.test(fetchMsg)) {
+            log.info(`[pipeline] git fetch skipped: no 'origin' remote configured (local-only repo)`);
+            localOnlyMode = true;
+        }
+        else {
+            throw fetchErr;
+        }
+    }
+    // Local-only: branch was never pushed to a remote, so we must CREATE it with
+    // `git checkout -b <name>`.  Remote paths: branch was fetched from origin, so
+    // it exists locally as FETCH_HEAD / refs/remotes/origin/<name> — plain
+    // `git checkout <name>` switches to the already-created tracking branch.
+    if (localOnlyMode) {
+        await execFileAsync('git', ['checkout', '-b', branchName], {
+            cwd: workDir,
+            env: cleanGitEnv(),
+        });
+    }
+    else {
+        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
@@ -441,7 +530,18 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
         `| 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();
+    // Resolve runner via registry (after discoverFromEnv):
+    //   1. options.runner injection (tests / programmatic override) — wins
+    //   2. options.runnerName (--runner flag) — must be registered; throws on unknown
+    //   3. AI_SDLC_RUNNER_PLUGIN env — dynamically loaded plugin
+    //   4. ClaudeCodeRunner built-in default
+    // NOTE: env-discovered runners (openai, copilot, etc.) are registered + selectable by
+    // name via --runner, but do NOT auto-win on env-var presence (AISDLC-529 code review).
+    const runnerRegistry = createRunnerRegistry();
+    const runner = await resolveRunner(runnerRegistry, {
+        injectedRunner: options.runner,
+        runnerName: options.runnerName,
+    });
     // Set up progress tracking — collects streaming events for the activity log
     const progressLog = [];
     const onProgress = (event) => {
@@ -532,7 +632,13 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
                 await tracker.addComment(issueId, `## ${agentFailComment.title}\n\n${agentFailComment.body}`);
                 throw new Error(`Agent failed on issue ${formatIssueRef(issueId)}: ${err}`);
             }
-            result = stepOutput;
+            // Guard: ensure filesChanged is always an array even when a runner returns
+            // a partial AgentResult. Downstream consumers (.length, .map, etc.) crash
+            // on undefined — defaulting here keeps all reads safe (AISDLC-527).
+            result = {
+                ...stepOutput,
+                filesChanged: stepOutput.filesChanged ?? [],
+            };
             log.stageEnd('agent');
             auditLog.record({
                 actor: 'system',
@@ -558,9 +664,29 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
         }
     }
     // 10. ABAC authorization check (if write permissions are defined)
-    if (currentLevel.permissions.write.length > 0) {
+    // Guard: default to [] when permissions.write is undefined (minimal/default autonomy configs
+    // may omit the write list, causing .length to throw on undefined — AISDLC-527).
+    //
+    // NOTE on the empty/undefined case (AISDLC-527 security-review finding): per the
+    // framework's existing autonomy-policy semantics, an empty write allowlist means
+    // "no per-file write restriction at this level" (the default autonomy level ships
+    // `write: []`), so this block intentionally SKIPS per-file authorization when the
+    // list is empty. The `?? []` makes a *missing* list behave the same as an explicit
+    // empty one rather than crashing. Because skipping authorization is a permissive
+    // (fail-open) path, we log it so it is auditable rather than silent. Tightening the
+    // empty-allowlist semantics to fail-closed is a framework-wide policy change (it would
+    // change the meaning of the default `write: []` level) and is tracked separately, NOT
+    // resolved in this crash-guard task. Downstream `validateAgentOutput` blocked-paths +
+    // branch protection + human merge remain as defense-in-depth.
+    const writePermissions = currentLevel.permissions.write ?? [];
+    if (writePermissions.length > 0) {
         authorizeFilesChanged(result.filesChanged, currentLevel.permissions, agentRole.spec.constraints, auditLog, agentRole.metadata.name);
     }
+    else {
+        log.info(`[pipeline] ABAC per-file write authorization skipped: autonomy level '${currentLevel.name ?? 'unknown'}' ` +
+            `has an empty/undefined permissions.write allowlist (framework default semantics). ` +
+            `Downstream blocked-paths validation + branch protection still apply.`);
+    }
     // 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\`\`\``
@@ -574,15 +700,20 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
     // 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.
+    //
+    // Local-only mode (AISDLC-530): when there's no 'origin' remote, the push
+    // is skipped just like the fetch step at step 7. We detect this by attempting
+    // the push and checking for the "no such remote" pattern — same approach
+    // AISDLC-527 uses for the fetch guard above (build on, not duplicate).
     log.stage('push');
-    await pushBranchWithRebase(workDir, branchName, log);
+    const pushSkipped = 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 },
+        details: { filesChanged: result.filesChanged.length, issueId, localOnly: pushSkipped },
     });
     // 13. Validate agent output against guardrails (after push)
     const validation = await withSpan(SPAN_NAMES.PIPELINE_STAGE, {
@@ -771,26 +902,39 @@ async function executePipelineBody(issueId, issue, config, qualityGate, agentRol
             targetBranch,
         });
         log.stageEnd('create-pr');
+        // Local-only mode (AISDLC-530): when the source-control adapter is local,
+        // createPR returns a sentinel pr.url === 'local' — record as skipped.
+        const isLocalPr = prResult.url === 'local';
+        if (isLocalPr) {
+            log.info(`[pipeline] create-pr skipped: local-only mode (no remote). ` +
+                `Branch '${branchName}' is available locally.`);
+        }
         auditLog.record({
             actor: 'system',
             action: 'create',
             resource: 'pull-request',
             decision: 'allowed',
-            details: { prUrl: prResult.url, issueId },
+            details: { prUrl: prResult.url, issueId, localOnly: isLocalPr },
         });
         return prResult;
     });
-    // 14. Comment on issue with success (use notification template when available)
-    const notifTemplates = config.pipeline?.spec.notifications?.templates;
-    const prCreatedTemplate = notifTemplates?.['pr-created'];
-    const prCreatedComment = prCreatedTemplate
-        ? renderTemplate(prCreatedTemplate, {
-            prUrl: pr.url,
-            issueNumber: issueId,
-        })
-        : { 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}`);
+    // 14. Comment on issue with success (use notification template when available).
+    // Local-only mode (AISDLC-530): skip tracker comment + Slack notification when
+    // there is no remote PR URL — posting "PR created: local" to the tracker would
+    // be misleading and is not actionable.
+    const isLocalOnlyPr = pr.url === 'local';
+    if (!isLocalOnlyPr) {
+        const notifTemplates = config.pipeline?.spec.notifications?.templates;
+        const prCreatedTemplate = notifTemplates?.['pr-created'];
+        const prCreatedComment = prCreatedTemplate
+            ? renderTemplate(prCreatedTemplate, {
+                prUrl: pr.url,
+                issueNumber: issueId,
+            })
+            : { 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;