@ai-sdlc/orchestrator 0.10.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.
  */
@@ -89,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;
@@ -114,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);
@@ -233,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) {
@@ -241,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;
         }
@@ -267,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);
@@ -411,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
@@ -444,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) => {
@@ -535,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',
@@ -561,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\`\`\``
@@ -577,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, {
@@ -774,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;

package/dist/index.d.ts

@@ -22,8 +22,12 @@ export { computePriority, rankWorkItems, type PriorityScore, type PriorityInput,
 export { checkAction, enforceAction, DEFAULT_BLOCKED_ACTIONS, type ActionEnforcementResult, } from './action-enforcement.js';
 export { scoreIssueForAdmission, mapIssueToPriorityInput, type AdmissionInput, type AdmissionThresholds, type IssueAdmissionResult, type AuthorAssociation, type DesignSystemContext, type AutonomyContext, type CodeAreaQuality, type DesignAuthoritySignal, type DesignAuthoritySignalType, type DesignQualityMetrics, } from './admission-score.js';
 export { enrichAdmissionInput, computeDesignSystemReadiness, computeReadinessFromDesignSystemContext, computeDefectRiskFactor, computeAutonomyFactor, computeDesignAuthorityWeight, complexityToAutonomyLevel, type EnrichmentContext, type LifecyclePhase, } from './admission-enrichment.js';
-export { computeAdmissionComposite, type AdmissionComposite } from './admission-composite.js';
-export { parseBacklogTask, loadBacklogTaskFromRoot, mapBacklogTaskToAdmissionInput, loadSoulTracks, loadMaintainers, type BacklogTaskSnapshot, type BacklogAcceptanceCriterion, type BacklogMappingOptions, type BacklogAdmissionMapping, } from './backlog-adapter.js';
+export { computeAdmissionComposite, type AdmissionComposite, type AdmissionCompositeOptions, } from './admission-composite.js';
+export { resolveAffectedSouls, applyCrossSoulRule, computeTessellatedScores, type DepGraphSoulEntry, type SoulScores, type TessellationContext, type TessellatedSaResult, } from './tessellation-admission.js';
+export { detectTessellationDrift, DEFAULT_DIVERGENCE_THRESHOLD, type TessellationDriftRule, type TessellationDriftDetectedEvent, type AstScanDetails, type AstScanFinding, type CrossSoulProvenanceDetails, type CrossSoulProvenanceFinding, type SubstrateFile, type ProvenanceAuditEntry, type TessellationDriftConfig, type TessellationDriftInput, type TessellationDriftResult, } from './tessellation-drift.js';
+export { parseTargetedVariantRef, resolveTargetedVariants, applyCrossVariantRule, computeVariantScopedScores, defaultCrossSoulVariantRule, type VariantOverlay, type VariantDesignOverridesFramework, type VariantDesignOverridesExt, type VariantScores, type VariantConfig, type VariantAggregationRule, type WorkItemVariantTargeting, type VariantContext, type ParsedVariantRef, type VariantScopedSaResult, } from './variant-admission.js';
+export { combineVariantSaForSoulAlignment } from './admission-composite.js';
+export { parseBacklogTask, loadBacklogTaskFromRoot, mapBacklogTaskToAdmissionInput, loadSoulTracks, loadMaintainers, extractCodeAreaFromReferences, parseBodyReferences, type BacklogTaskSnapshot, type BacklogAcceptanceCriterion, type BacklogMappingOptions, type BacklogAdmissionMapping, } from './backlog-adapter.js';
 export { computePillarBreakdown, detectTensions, pillarSignalScore, type PillarBreakdown, type PillarContribution, type PillarName, type SharedDimensions, type TensionFlag, type TensionFlagType, type HcChannelBreakdown, } from './pillar-breakdown.js';
 export { compileDid, validatePhase2bReadiness, hashDidSpec, canonicalJson, tokenize, serializeForStore, deserializeFromStore, type CompiledDid, type CompiledScopeLists, type CompiledScopeEntry, type CompiledConstraintRule, type CompiledAntiPattern, type CompiledAntiPatternLists, type CompiledMeasurableSignal, type Bm25Corpus, type Bm25Document, type PrincipleCorpora, type ReadinessResult, } from './sa-scoring/did-compiler.js';
 export { HttpDepparseClient, FakeDepparseClient, DepparseError, type DepparseClient, type DepparseMatch, type DepparseMatchRequest, type DepparseMatchResponse, type DepparseHealth, type DepparseErrorKind, } from './sa-scoring/depparse-client.js';
@@ -36,6 +40,7 @@ export { SAFeedbackStore, SA_FEEDBACK_LABELS, classifyLabel, recordOverrideFeedb
 export { computeCalibrationCoefficient, buildCategoryCoefficients, type CategoryFeedback, type BuildCategoryCoefficientsInput, } from './calibration.js';
 export { autoCalibratePhaseWeights, computePhase3Weights, decideCalibrationDirection, renderCalibrationDiff, WEIGHT_FLOOR, WEIGHT_CEILING, DEFAULT_SHIFT_SIZE, DEFAULT_WINDOW_DAYS, PRECISION_DELTA_THRESHOLD, type PrecisionPair, type CalibrationDecision, type ComputePhase3WeightsInput, type AutoCalibrateDeps, type AutoCalibrateResult, type DimensionDiff, } from './sa-scoring/auto-calibrate.js';
 export { detectSoulDrift, computeWindowStats, computeTrend, describeDriftSource, DEFAULT_MEAN_THRESHOLD, DEFAULT_STDDEV_THRESHOLD, DEFAULT_CONSECUTIVE_WINDOWS, DEFAULT_RECOVERY_MS, type SoulDriftDetectedEvent, type DriftTrend, type WindowStats, type DriftDetectorDeps, } from './sa-scoring/drift-monitor.js';
+export { classifyDrift, deriveApprovalPath, computeConfidence, evaluateRevisionProposal, triggerConditionMet, isFieldLocked, isProposalExpired, archiveExpiredProposals, recordRejection, computeRejectionPrecedentFactor, DEFAULT_DISMISS_THRESHOLD, DEFAULT_DEMAND_MISALIGNMENT_THRESHOLD, DEFAULT_DRIFT_EVENTS_THRESHOLD, DEFAULT_TRIGGER_WINDOW_DAYS, DEFAULT_PROPOSAL_EXPIRY_DAYS, HEALTHY_ICP_MATCH_MIN, UNHEALTHY_ICP_MATCH_MAX, type DriftClassification, type IdentityClass, type ApprovalPath, type ProposalStatus, type ProposalConfidence, type ClassificationEvidence, type TriggerEvidence, type TriggerConditions, type TriggerConfig, type CalibrationLockConfig, type DIDRevisionProposalEvent, type SoulHealthDiagnosticEvent, type DIDRevisionProposalExpiredEvent, type ProposalRejectionRecord, type EvaluateRevisionProposalInput, type EvaluateRevisionProposalResult, } from './sa-scoring/revision-proposal.js';
 export { handleCoreIdentityChanged, type CoreIdentityChangedEvent, type BacklogReshuffledEvent, type SoulGraphStaleFlag, type RescoreDeps, type HandleResult, } from './sa-scoring/rescore-orchestrator.js';
 export { scoreSoulAlignment, resolveSoulAlignmentOverride, type ScoreSoulAlignmentInput, type ScoreSoulAlignmentDeps, type SoulAlignmentScoringResult, } from './sa-scoring/index.js';
 export type { SaDimension, FeedbackSignal } from './state/types.js';
@@ -47,6 +52,10 @@ export { createPipelineAdapterRegistry, createPipelineWebhookBridge, resolveAdap
 export { createPipelineReconciler, createGateReconciler, createAutonomyReconciler, hasResourceChanged, fingerprintResource, } from './reconcilers.js';
 export { createFileAuditLog, verifyAuditIntegrity, loadAuditEntries, rotateAuditLog, computeAuditHash, } from './audit-extended.js';
 export { checkFrameworkCompliance, getControlCatalog, getFrameworkMappings, listSupportedFrameworks, } from './compliance-extended.js';
+export { HARD_REGULATORY_REGIME_PREFIXES, isHardRegulatoryRegime, validateComplianceRegimes, computeComplianceClearance, type ValidateComplianceRegimesResult, type ComplianceViolation, type ComplianceViolationEntry, type SoulComplianceRegimes, type ComplianceClearanceContext, type ComplianceClearanceResult, } from './compliance-clearance.js';
+export { loadCompliancePosture, DEFAULT_COMPLIANCE_MANIFEST_PATH, type LoadCompliancePostureOptions, } from './compliance/loader.js';
+export { MissingComplianceAttestation, MissingDerivedGateOverrideNotes, UnknownRegime, CompliancePostureValidationError, } from './compliance/errors.js';
+export { BASELINE_DERIVED_GATES, BASELINE_POSTURE, type CompliancePosture, type Regime, type DerivedGates, type PartialDerivedGatesOverrides, type AuditExportSpec, } from './compliance/types.js';
 export { createSilentLogger, withPipelineSpanSync, getPipelineTracer, validateResourceSchema, } from './telemetry-extended.js';
 export { ClaudeCodeRunner, ClaudeCodeRunner as GitHubActionsRunner, GenericLLMRunner, CopilotRunner, CursorRunner, CodexRunner, RunnerRegistry, createRunnerRegistry, SecurityTriageRunner, ReviewAgentRunner, REVIEW_PROMPTS, type AgentRunner, type AgentContext, type AgentResult, type AgentProgressEvent, type GenericLLMConfig, type RegisteredRunner, type SecurityTriageConfig, type TriageVerdict, type ReviewAgentConfig, type ReviewType, type ReviewFinding, type ReviewVerdict, } from './runners/index.js';
 export type { TokenUsage } from './runners/index.js';
@@ -98,6 +107,9 @@ export { WorktreePoolManager, WorktreePoolError, WorktreeOwnershipError, determi
 export { HarnessRegistry, UnknownHarnessError, ClaudeCodeAdapter, CodexAdapter, createDefaultHarnessRegistry, probeVersion, matchesRange, enforceIndependence, validateIndependenceGraph, CyclicIndependenceConstraintError, type HarnessAdapter, type HarnessAvailability, type HarnessCapabilities, type HarnessEvent, type HarnessInput, type HarnessName, type HarnessRequires, type HarnessResult, type HarnessResultStatus, type ClaudeCodeAdapterDeps, type CodexAdapterDeps, type IndependenceResult, type UpstreamRun, type ToolDefinition, } from './harness/index.js';
 export { SubscriptionLedger, validateTenantShares, evaluateSchedule, CalibrationStore, COLD_START_DEFAULT, buildBurnDownReport, analyzeTier, PLAN_COSTS_USD, isOffPeakAt, nextOffPeakStart, ageInDays, freshnessLevel, DEFAULT_TENANT, COLD_START_DEFAULT_INPUT, COLD_START_DEFAULT_OUTPUT, ESTIMATE_VARIANCE_THRESHOLD, ROLLING_WINDOW_SIZE, type SubscriptionPlan, type Schedule, type TokenEstimate, type LedgerKey, type WindowState, type AdmissionDecision, type BurnDownReport, type LedgerEvent, type BillingMode, type QuotaSource, type OffPeakSchedule, type BurnDownInput, type CalibrationStoreDeps, type LedgerDeps, type ScheduleDecision, type ScheduleEvaluationContext, type Confidence, type ContentionEvent, type TierAnalysisInput, type TierAnalysisResult, type FreshnessLevel, } from './scheduling/index.js';
 export { DatabaseAdapterRegistry, UnknownDatabaseAdapterError, SqliteCopyAdapter, NeonAdapter, PgSnapshotRestoreAdapter, ExternalAdapter, createDefaultDatabaseAdapterRegistry, buildInjectionOverrides, parsePostgresUrl, maskConnectionString, enforceTopologyGuard, buildMigrationDivergedEvent, DatabaseBranchAdapterError, BranchTopologyForbiddenError, type DatabaseBranchAdapter, type DatabaseBranchCapabilities, type DatabaseBranchHandle, type DatabaseAdapterName, type ResolvedDatabaseBranchPool, type DatabaseAccess, type SqliteCopyAdapterDeps, type NeonAdapterDeps, type PgSnapshotRestoreAdapterDeps, type ExternalAdapterDeps, type InjectedEnvOverrides, type KnownInFlightBranches, type MigrationDivergedEvent, } from './database/index.js';
+export { AdapterCredentialInvalid, CommunityThreadSignalSourceAdapter, ManualSignalIncomplete, ManualSignalSourceAdapter, SignalSourceRegistry, SignalSourceUnavailable, SupportTicketSignalSourceAdapter, UnknownSignalSource, createDefaultSignalSourceRegistry, fetchSignalsFromAvailableAdapters, getSignalSourceAdapter, type AdapterCredentialInvalidDecision, type CommunityThreadAdapterOptions, type CustomerTier, type ManualSignalIncompleteDecision, type ManualSignalInput, type RawSignal, type SignalFetchResult, type SignalSourceAdapter, type SignalSourceName, type SignalTier, type SupportTicketAdapterOptions, } from './signal-ingestion/index.js';
+export { classifySignals, computeRecencyDecay, computeSignalWeight, resolveCustomerTier, resolveIcpResonance, tokenize as tokenizeSignalPayload, DEFAULT_SIGNAL_INGESTION_CONFIG, DEFAULT_SIGNAL_INGESTION_CONFIG_PATH, SignalIngestionConfigError, loadSignalIngestionConfig, type ClassificationResult, type ClassifiedSignal, type ClassifySignalsOptions, type ClusteringConfig, type CustomerTierRegistry, type ICPResonance, type IcpResonanceWeights, type LoadSignalIngestionConfigOptions, type SaResonanceThresholds, type SignalIngestionConfig, type SignalLanguageUnsupportedDecision, type Tier2SignificanceThreshold, type TierMultipliers, } from './signal-ingestion/index.js';
+export { aggregateD1FromClusters, composeD1Inputs, computeClusterD1, enrichDemandSignalFromClusters, type AggregatedD1Result, type ClusterD1Score, type ClusterMatcher, type ComposeD1InputsArgs, type ComposedD1Result, type D1CompositionWeights, type EnrichDemandSignalArgs, type EnrichDemandSignalResult, } from './signal-ingestion/index.js';
 export { StateWriter, appendEvent, readEvents, atomicWriteJson, listActiveStates, HEARTBEAT_INTERVAL_MS, HEARTBEAT_STALE_MS, type RuntimeState, type ArtifactEvent, type StageStatus, } from './artifacts/index.js';
 export { runWorkerPool, withMergeGate, forceReleaseMergeGate, isBranchUpToDate, MergeGateLockTimeoutError, decideRequeue, appendTriageHistory, type WorkItem, type WorkerPoolDeps, type WorkerPoolEvent, type WorkerPoolResult, type FailureEvent, type RequeueTrigger, type RequeueDecision, type RequeueDecisionInput, type TriageHistoryEntry, type FailureClassification, type MergeGateDeps, } from './dispatch/index.js';
 export { ModelRegistry, ModelRemovedError, UnknownAliasError, DEFAULT_REGISTRY, decideFromRawOutput, decideFromInvocationFailure, validateClassifierOutput, defaultRulesetDecision, appendCalibrationEntry, ALL_REVIEWERS, type ModelEntry, type ResolutionContext, type ResolutionResult, type ResolutionEvent, type ReviewerName, type ClassifierOutput, type ClassifierDecision, type FellOpenReason, type CalibrationLogEntry, type DiffSummary, } from './models/index.js';