forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/lib/fixtures/beta5-corpus/v1/state/kernel.sql

@@ -0,0 +1,20 @@
+PRAGMA user_version = 1;
+CREATE TABLE kernel_migrations (id TEXT PRIMARY KEY, applied_at TEXT NOT NULL);
+CREATE TABLE kernel_issues (id TEXT PRIMARY KEY, title TEXT NOT NULL, status TEXT NOT NULL, entity_revision INTEGER NOT NULL);
+CREATE TABLE kernel_comments (id TEXT PRIMARY KEY, issue_id TEXT NOT NULL, body TEXT NOT NULL, actor TEXT NOT NULL);
+CREATE TABLE kernel_dependencies (id TEXT PRIMARY KEY, issue_id TEXT NOT NULL, blocks_issue_id TEXT NOT NULL);
+CREATE TABLE kernel_claims (id TEXT PRIMARY KEY, issue_id TEXT NOT NULL, actor TEXT NOT NULL, state TEXT NOT NULL);
+CREATE TABLE kernel_worktrees (id TEXT PRIMARY KEY, path TEXT NOT NULL, branch TEXT NOT NULL, state TEXT NOT NULL);
+CREATE TABLE kernel_stage_runs (id TEXT PRIMARY KEY, issue_id TEXT NOT NULL, stage TEXT NOT NULL, status TEXT NOT NULL);
+CREATE TABLE kernel_projections (id TEXT PRIMARY KEY, target TEXT NOT NULL, entity_type TEXT NOT NULL, entity_id TEXT NOT NULL, status TEXT NOT NULL);
+CREATE TABLE kernel_events (id TEXT PRIMARY KEY, entity_type TEXT NOT NULL, entity_id TEXT NOT NULL, event_type TEXT NOT NULL);
+INSERT INTO kernel_migrations VALUES ('001_initial_kernel_schema', '2026-08-09T00:00:00.000Z');
+INSERT INTO kernel_issues VALUES ('synthetic-issue-1', 'Synthetic issue', 'open', 2); -- NOSONAR S1192: repeated synthetic foreign key preserves fixture readability.
+INSERT INTO kernel_issues VALUES ('synthetic-issue-2', 'Synthetic dependency', 'done', 1);
+INSERT INTO kernel_comments VALUES ('synthetic-comment-1', 'synthetic-issue-1', 'Synthetic comment', 'fixture');
+INSERT INTO kernel_dependencies VALUES ('synthetic-dependency-1', 'synthetic-issue-1', 'synthetic-issue-2');
+INSERT INTO kernel_claims VALUES ('synthetic-claim-1', 'synthetic-issue-1', 'fixture', 'active');
+INSERT INTO kernel_worktrees VALUES ('synthetic-worktree-1', '/synthetic/worktree', 'fixture/branch', 'active');
+INSERT INTO kernel_stage_runs VALUES ('synthetic-run-1', 'synthetic-issue-1', 'dev', 'done');
+INSERT INTO kernel_projections VALUES ('synthetic-projection-1', 'jsonl', 'issue', 'synthetic-issue-1', 'delivered');
+INSERT INTO kernel_events VALUES ('synthetic-event-1', 'issue', 'synthetic-issue-1', 'issue.updated');

package/lib/forge-context.js

@@ -7,8 +7,7 @@
  * injectable object, making state explicit and testable.
  *
  * Mirrors the globals: projectRoot, FORCE_MODE, VERBOSE_MODE,
- * NON_INTERACTIVE, SYMLINK_ONLY, SYNC_ENABLED, actionLog,
- * PKG_MANAGER, and packageDir.
+ * NON_INTERACTIVE, SYMLINK_ONLY, actionLog, PKG_MANAGER, and packageDir.
  *
  * @module forge-context
  */
@@ -21,7 +20,6 @@ class ForgeContext { // NOSONAR — constructor-only class is intentional: serve
    * @param {boolean}  [options.verboseMode]    - Verbose output (--verbose)
    * @param {boolean}  [options.nonInteractive] - Skip prompts (--quick / --yes)
    * @param {boolean}  [options.symlinkOnly]    - Fail instead of copy fallback (--symlink)
-   * @param {boolean}  [options.syncEnabled]    - Scaffold Beads GitHub sync (--sync)
    * @param {string}   [options.pkgManager]     - Detected package manager
    * @param {Array}    [options.actionLog]      - Incremental setup action log
    * @param {string}   [options.packageDir]     - Forge package directory
@@ -32,7 +30,6 @@ class ForgeContext { // NOSONAR — constructor-only class is intentional: serve
     this.verboseMode = options.verboseMode || false;
     this.nonInteractive = options.nonInteractive || false;
     this.symlinkOnly = options.symlinkOnly || false;
-    this.syncEnabled = options.syncEnabled || false;
     this.pkgManager = options.pkgManager || 'npm';
     this.actionLog = options.actionLog || [];
     this.packageDir = options.packageDir || '';

package/lib/forge-issues.js

@@ -7,6 +7,8 @@ const { createLocalBroker, buildLocalBrokerConfig } = require('./kernel/broker')
 const { createBuiltinSQLiteDriver } = require('./kernel/sqlite-driver');
 const { detectWorktree } = require('./detect-worktree');
 const { DEFAULT_LEASE_TTL_MS } = require('./kernel/lease-enforcer');
+const { ISSUE_TYPES } = require('./kernel/issue-command-contract');
+const { loadRuntimeGraphConfig } = require('./core/runtime-graph');
 
 const OPERATION_METHOD_ALIASES = {
   'dep.add': 'depAdd',
@@ -25,6 +27,7 @@ function isHelpInvocation(args = []) {
 // on a missing `exec` method before ever reaching the "no tables" case.
 function createDefaultKernelBroker(brokerContext, deps) {
   let driver = deps.kernelDriver;
+  const ownsDriver = !driver;
   if (!driver) {
     const config = buildLocalBrokerConfig({
       projectRoot: brokerContext.projectRoot,
@@ -35,7 +38,7 @@ function createDefaultKernelBroker(brokerContext, deps) {
     driver = createBuiltinSQLiteDriver({ databasePath: config.databasePath });
   }
 
-  return createLocalBroker({
+  const broker = createLocalBroker({
     projectRoot: brokerContext.projectRoot,
     gitCommonDir: deps.gitCommonDir,
     databasePath: deps.kernelDatabasePath,
@@ -46,6 +49,10 @@ function createDefaultKernelBroker(brokerContext, deps) {
     // classifier instead of paying the real Windows drive probe per per-op broker.
     classifyFilesystem: deps.classifyFilesystem,
   });
+  if (ownsDriver && typeof driver.close === 'function') {
+    broker.close = () => driver.close();
+  }
+  return broker;
 }
 
 // Symbol marker for the memoized lazy-init promise. Stored ON the broker object
@@ -82,6 +89,11 @@ function withLazyKernelInit(broker) {
     async initialize() {
       return ensureInitialized();
     },
+    async close() {
+      if (typeof broker.close === 'function') {
+        await broker.close();
+      }
+    },
     async runIssueOperation(operation, args = [], context = {}) {
       await ensureInitialized();
       return broker.runIssueOperation(operation, args, context);
@@ -94,11 +106,14 @@ function createKernelIssueBackend(context = {}) {
   const createBroker = deps.createKernelBroker
     || ((brokerContext) => createDefaultKernelBroker(brokerContext, deps));
 
+  const ownsBroker = !deps.kernelBroker;
   const broker = deps.kernelBroker || createBroker(context);
-
-  return new KernelIssueAdapter({
-    broker: withLazyKernelInit(broker),
-  });
+  const managedBroker = withLazyKernelInit(broker);
+  const backend = new KernelIssueAdapter({ broker: managedBroker });
+  if (ownsBroker && typeof managedBroker?.close === 'function') {
+    backend.dispose = () => managedBroker.close();
+  }
+  return backend;
 }
 
 function createIssueService({ backend } = {}) {
@@ -108,6 +123,11 @@ function createIssueService({ backend } = {}) {
   const resolvedBackend = backend || createKernelIssueBackend();
 
   return {
+    async dispose() {
+      if (typeof resolvedBackend?.dispose === 'function') {
+        await resolvedBackend.dispose();
+      }
+    },
     async run(operation, args = [], context = {}) {
       const methodName = operation === 'show' && typeof resolvedBackend?.show !== 'function'
         ? 'read'
@@ -181,6 +201,75 @@ function resolveLeaseTtlMs(env = {}) {
   return ttl;
 }
 
+function readIssueContractValues(loaded, fail) {
+	const missing = Symbol('missing issue contract config');
+	const ownDataValue = (object, key, path) => {
+		if (!object || (typeof object !== 'object' && typeof object !== 'function')) return missing;
+		const descriptor = Object.getOwnPropertyDescriptor(object, key);
+		if (!descriptor) return missing;
+		if (!Object.prototype.hasOwnProperty.call(descriptor, 'value')) {
+			fail(`${path} must be a data property`);
+		}
+		return descriptor.value;
+	};
+	const issues = ownDataValue(loaded?.config, 'issues', 'issues');
+	const readiness = issues === missing ? missing : ownDataValue(issues, 'readiness', 'issues.readiness');
+	const configured = readiness === missing
+		? missing
+		: ownDataValue(readiness, 'contracts', 'issues.readiness.contracts');
+	if (configured === missing || configured == null) return null;
+	if (typeof configured !== 'object'
+		|| Array.isArray(configured)
+		|| Object.getPrototypeOf(configured) !== Object.prototype) {
+		fail('issues.readiness.contracts must be a plain JSON object');
+	}
+	const allowedKeys = new Set(['enabled', 'workClasses']);
+	const ownKeys = Reflect.ownKeys(configured);
+	const unknownKeys = ownKeys.filter(key => typeof key !== 'string' || !allowedKeys.has(key));
+	if (unknownKeys.length > 0) {
+		fail(`unknown issues.readiness.contracts keys: ${unknownKeys.map(String).sort((left, right) => left.localeCompare(right)).join(', ')}`);
+	}
+	const values = Object.create(null);
+	for (const key of ownKeys) {
+		const descriptor = Object.getOwnPropertyDescriptor(configured, key);
+		if (!descriptor || !Object.prototype.hasOwnProperty.call(descriptor, 'value')) {
+			fail(`issues.readiness.contracts.${key} must be a data property`);
+		}
+		values[key] = descriptor.value;
+	}
+	return values;
+}
+
+function resolveIssueContractPolicy(projectRoot, deps = {}) {
+	const loadConfig = deps.loadRuntimeGraphConfig || loadRuntimeGraphConfig;
+	const loaded = loadConfig({ projectRoot });
+	const fail = message => {
+		const error = new Error(`FORGE_ISSUE_CONTRACT_CONFIG_INVALID: ${message}`);
+		error.code = 'FORGE_ISSUE_CONTRACT_CONFIG_INVALID';
+		throw error;
+	};
+	if (Array.isArray(loaded?.errors) && loaded.errors.length > 0) {
+		fail(loaded.errors.map(error => error.message || error.code || String(error)).join('; '));
+	}
+	const values = readIssueContractValues(loaded, fail);
+	if (values === null) return null;
+	if (values.enabled !== undefined && typeof values.enabled !== 'boolean') {
+		fail('issues.readiness.contracts.enabled must be a boolean');
+	}
+	if (values.enabled !== true) return { enabled: false, workClasses: [] };
+	if (!Array.isArray(values.workClasses) || values.workClasses.length === 0) {
+		fail('issues.readiness.contracts.workClasses must be a non-empty array');
+	}
+	const allowedClasses = new Set(ISSUE_TYPES);
+	if (values.workClasses.some(value => typeof value !== 'string' || !allowedClasses.has(value))) {
+		fail('issues.readiness.contracts.workClasses contains an unknown work class');
+	}
+	return {
+		enabled: true,
+		workClasses: [...new Set(values.workClasses)],
+	};
+}
+
 async function runIssueOperation(operation, rawArgs, projectRoot, deps = {}) {
   const injectedService = deps.createService;
 
@@ -188,6 +277,7 @@ async function runIssueOperation(operation, rawArgs, projectRoot, deps = {}) {
     backend: createKernelIssueBackend({ projectRoot, deps }),
   }));
 
+  const contractPolicy = resolveIssueContractPolicy(projectRoot, deps);
   const service = createService();
   // Thread a distinct per-agent actor (and, when present, a stable session id) into the
   // mutation context so the Kernel's claim idempotency key is scoped per agent rather than
@@ -205,36 +295,47 @@ async function runIssueOperation(operation, rawArgs, projectRoot, deps = {}) {
   const isClaim = operation === 'claim';
   const worktreeId = isClaim ? resolveWorktreeId(projectRoot, actorEnv, deps) : undefined;
   const leaseTtlMs = isClaim ? resolveLeaseTtlMs(actorEnv) : undefined;
-  const result = await service.run(operation, rawArgs, {
-    projectRoot,
-    deps,
-    ...(actor ? { actor } : {}),
-    ...(sessionId ? { sessionId } : {}),
-    ...(worktreeId ? { worktreeId } : {}),
-    ...(leaseTtlMs ? { leaseTtlMs } : {}),
-    // Kernel mutations enqueue a projection-outbox "dirty marker" that `forge export`
-    // (the D16 git-JSONL portability projection) drains under target 'jsonl'. The
-    // broker's legacy primitive default is still 'beads', so without steering the target
-    // here every Kernel-created issue would be enqueued as 'beads' and `forge export` —
-    // which drains 'jsonl' — would find nothing, silently never emitting git-tracked
-    // JSONL. Unconditional now that the Kernel is the only backend.
-    projectionTarget: 'jsonl',
-  });
+	const isTrustedAdoption = typeof deps.verifyIssueContractAdoption === 'function'
+		? deps.verifyIssueContractAdoption
+		: undefined;
+  try {
+    const result = await service.run(operation, rawArgs, {
+      projectRoot,
+      deps,
+      ...(actor ? { actor } : {}),
+      ...(sessionId ? { sessionId } : {}),
+      ...(worktreeId ? { worktreeId } : {}),
+      ...(leaseTtlMs ? { leaseTtlMs } : {}),
+		...(contractPolicy ? { contractPolicy } : {}),
+		...(isTrustedAdoption ? { isTrustedAdoption } : {}),
+      // Kernel mutations enqueue a projection-outbox "dirty marker" that `forge export`
+      // (the D16 git-JSONL portability projection) drains under target 'jsonl'. The
+      // broker's legacy primitive default is still 'beads', so without steering the target
+      // here every Kernel-created issue would be enqueued as 'beads' and `forge export` —
+      // which drains 'jsonl' — would find nothing, silently never emitting git-tracked
+      // JSONL. Unconditional now that the Kernel is the only backend.
+      projectionTarget: 'jsonl',
+    });
 
-  const queueGitHubProjection = deps.enqueueGitHubProjection || deps.queueGitHubProjection;
-  if (result?.success && typeof queueGitHubProjection === 'function') {
-    const projectionPlan = createGitHubProjectionPlan(operation, rawArgs);
-    if (projectionPlan) {
-      await queueGitHubProjection(projectionPlan, {
-        operation,
-        args: rawArgs,
-        projectRoot,
-        result,
-      });
+    const queueGitHubProjection = deps.enqueueGitHubProjection || deps.queueGitHubProjection;
+    if (result?.success && typeof queueGitHubProjection === 'function') {
+      const projectionPlan = createGitHubProjectionPlan(operation, rawArgs);
+      if (projectionPlan) {
+        await queueGitHubProjection(projectionPlan, {
+          operation,
+          args: rawArgs,
+          projectRoot,
+          result,
+        });
+      }
     }
-  }
 
-  return result;
+    return result;
+  } finally {
+    if (!injectedService && typeof service.dispose === 'function') {
+      try { await service.dispose(); } catch { /* cleanup must not mask the operation outcome */ }
+    }
+  }
 }
 
 module.exports = {
@@ -243,4 +344,5 @@ module.exports = {
   runIssueOperation,
   isHelpInvocation,
   resolveIssueActor,
+	resolveIssueContractPolicy,
 };

package/lib/gate-events.js

@@ -49,8 +49,13 @@ const GATE_EVENT_ORIGIN = 'cli';
  * SAME-actor re-approval mints no duplicate, while a later reject (different
  * decision) or a different actor is recorded as its own event.
  */
-function gateIdempotencyKey(eventType, issueId, gateId, actor) {
-  return `${eventType}:${issueId}:${gateId}:${actor}`;
+function gateIdempotencyKey(eventType, issueId, gateId, actor, expiresAt) {
+  const base = `${eventType}:${issueId}:${gateId}:${actor}`;
+  return expiresAt ? `${base}:${expiresAt}` : base;
+}
+
+function gateControlId(issueId, gateId) {
+  return `gate:${issueId}:${gateId}`;
 }
 
 /** Shape a stored kernel_events row into the gate-event view callers consume. */
@@ -67,6 +72,18 @@ function parseGateEvent(row) {
     actor: row.actor,
     created_at: row.created_at,
   };
+  // Older direct callers supplied only the legacy row subset and consumed its
+  // exact four-field view. Stored Kernel rows always carry entity_id, so enrich
+  // those audit/status views without changing that legacy parse contract.
+  if (row.entity_id) {
+    view.issue_id = row.entity_id;
+    view.control_id = payload.control_id || gateControlId(row.entity_id, payload.gate);
+    view.decision = row.event_type === GATE_APPROVED_EVENT ? 'approved' : 'rejected';
+    view.issued_at = row.created_at;
+    view.expires_at = payload.expires_at ?? null;
+    view.request_identity = payload.request_identity ?? null;
+    view.generation = Number.isInteger(payload.generation) ? payload.generation : 0;
+  }
   if (payload.reason !== undefined) view.reason = payload.reason;
   return view;
 }
@@ -76,10 +93,43 @@ function isIdempotencyRace(error) {
   return /UNIQUE constraint failed/i.test(message) && /idempotency_key/i.test(message);
 }
 
+function isActiveApproval(event, now) {
+  if (!event || event.event_type !== GATE_APPROVED_EVENT) return false;
+  if (!event.expires_at) return true;
+  const nowMillis = Date.parse(now);
+  const expiryMillis = Date.parse(event.expires_at);
+  return Number.isFinite(nowMillis) && Number.isFinite(expiryMillis) && nowMillis < expiryMillis;
+}
+
+function planGateGeneration(events, params) {
+  const { gateId, decision, actor, requestIdentity, now } = params;
+  const gateEvents = events.filter(event => event.gate === gateId);
+  const latest = gateEvents.at(-1);
+  const maxGeneration = gateEvents.reduce(
+    (max, event) => Math.max(max, Number.isInteger(event.generation) ? event.generation : 0),
+    -1,
+  );
+
+  if (decision === 'approved') {
+    const identicalActive = latest
+      && latest.actor === actor
+      && latest.request_identity === requestIdentity
+      && isActiveApproval(latest, now);
+    if (identicalActive) return { duplicateEvent: latest, generation: latest.generation };
+    return { duplicateEvent: null, generation: maxGeneration + 1 };
+  }
+
+  if (latest?.event_type === GATE_REJECTED_EVENT && latest.actor === actor) {
+    return { duplicateEvent: latest, generation: latest.generation };
+  }
+  return { duplicateEvent: null, generation: Math.max(maxGeneration, 0) };
+}
+
 /**
- * Record a gate decision as a kernel event on the issue. Idempotent per
- * issue+gate+actor+decision. Validates the issue exists (the caller validates the
- * gate id against the known-gate set before calling).
+ * Record a gate decision as a kernel event on the issue. Active identical
+ * requests are idempotent; expiry/rejection advances the durable generation so
+ * a later approval can become authoritative. Validates the issue exists (the
+ * caller validates the gate id against the known-gate set before calling).
  *
  * @param {string} projectRoot
  * @param {Object} params
@@ -93,7 +143,7 @@ function isIdempotencyRace(error) {
  * @returns {Promise<{ ok: boolean, duplicate?: boolean, issueMissing?: boolean, event?: Object, actor?: string }>}
  */
 async function recordGateEvent(projectRoot, params = {}) {
-  const { issueId, gateId, decision, reason, env, deps, now } = params;
+  const { issueId, gateId, decision, reason, expiresAt, requestIdentity, env, deps, now } = params;
   const eventType = GATE_EVENT_TYPES[decision];
   if (!eventType) {
     throw new Error(`Unknown gate decision '${decision}' (expected 'approved' or 'rejected').`);
@@ -109,14 +159,42 @@ async function recordGateEvent(projectRoot, params = {}) {
       return { ok: false, issueMissing: true, actor };
     }
 
-    const idempotencyKey = gateIdempotencyKey(eventType, issueId, gateId, actor);
+    const createdAt = now || new Date().toISOString();
+    const stableRequestIdentity = requestIdentity ?? expiresAt ?? null;
+    const rows = await driver.listKernelEvents(ISSUE_ENTITY_TYPE, issueId, {}, config);
+    const generationPlan = planGateGeneration((rows || []).map(parseGateEvent), {
+      gateId,
+      decision,
+      actor,
+      requestIdentity: stableRequestIdentity,
+      now: createdAt,
+    });
+    if (generationPlan.duplicateEvent) {
+      return { ok: true, duplicate: true, event: generationPlan.duplicateEvent, actor };
+    }
+    const keyParts = [stableRequestIdentity];
+    if (generationPlan.generation > 0) keyParts.push(`generation=${generationPlan.generation}`);
+    const idempotencyKey = gateIdempotencyKey(
+      eventType,
+      issueId,
+      gateId,
+      actor,
+      keyParts.filter(Boolean).join(':') || undefined,
+    );
 
     const existing = await driver.loadKernelEventByIdempotencyKey(idempotencyKey, {}, config);
     if (existing) {
       return { ok: true, duplicate: true, event: parseGateEvent(existing), actor };
     }
 
-    const payload = { gate: gateId, actor };
+    const payload = {
+      gate: gateId,
+      actor,
+      control_id: gateControlId(issueId, gateId),
+      expires_at: expiresAt ?? null,
+      request_identity: stableRequestIdentity,
+      generation: generationPlan.generation,
+    };
     if (typeof reason === 'string' && reason.length > 0) payload.reason = reason;
 
     const event = {
@@ -128,7 +206,7 @@ async function recordGateEvent(projectRoot, params = {}) {
       actor,
       origin: GATE_EVENT_ORIGIN,
       payload,
-      created_at: now || new Date().toISOString(),
+      created_at: createdAt,
     };
 
     try {
@@ -166,6 +244,12 @@ async function listGateEvents(projectRoot, issueId, options = {}) {
   }
 }
 
+function evaluateGateApproval(events, gateId, now = new Date().toISOString()) {
+  const decisions = events.filter(event => event.gate === gateId);
+  const event = decisions.at(-1);
+  return { approved: isActiveApproval(event, now), event };
+}
+
 /**
  * True iff a `gate.approved` event exists for this issue + gate.
  *
@@ -177,7 +261,7 @@ async function listGateEvents(projectRoot, issueId, options = {}) {
  */
 async function isGateApproved(projectRoot, issueId, gateId, options = {}) {
   const events = await listGateEvents(projectRoot, issueId, options);
-  return events.some(event => event.event_type === GATE_APPROVED_EVENT && event.gate === gateId);
+  return evaluateGateApproval(events, gateId, options.now).approved;
 }
 
 module.exports = {
@@ -185,8 +269,12 @@ module.exports = {
   GATE_REJECTED_EVENT,
   GATE_EVENT_TYPES,
   gateIdempotencyKey,
+  gateControlId,
+  isActiveApproval,
+  planGateGeneration,
   parseGateEvent,
   recordGateEvent,
   listGateEvents,
+  evaluateGateApproval,
   isGateApproved,
 };

package/lib/git-defaults.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+/**
+ * Detect the default branch of the repository.
+ *
+ * Strategy (in order):
+ *   1. `git symbolic-ref refs/remotes/origin/HEAD` -> parse branch name
+ *   2. `git remote show origin` -> parse "HEAD branch:" line
+ *   3. Fall back to `'main'`
+ *
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @param {object} [options] - Options object.
+ * @param {Function} [options._exec] - Injected execFileSync for testing.
+ * @returns {string} The default branch name.
+ */
+function detectDefaultBranch(projectRoot, options = {}) {
+  const exec = options._exec || execFileSync;
+
+  // Strategy 1: symbolic-ref
+  try {
+    const out = exec('git', ['symbolic-ref', 'refs/remotes/origin/HEAD'], {
+      cwd: projectRoot,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const ref = out.toString().trim();
+    // refs/remotes/origin/release/2026 -> release/2026 (branch names may contain '/')
+    const prefix = 'refs/remotes/origin/';
+    if (ref.startsWith(prefix)) {
+      return ref.slice(prefix.length);
+    }
+  } catch (_e) { // NOSONAR S2486 — symbolic-ref fails when origin/HEAD is unset; fall through to strategy 2
+  }
+
+  // Strategy 2: remote show origin
+  try {
+    const out = exec('git', ['remote', 'show', 'origin'], {
+      cwd: projectRoot,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const text = out.toString();
+    const match = text.match(/HEAD branch:\s*(.+)/);
+    if (match) {
+      return match[1].trim();
+    }
+  } catch (_e) { // NOSONAR S2486 — 'git remote show origin' fails with no remote configured; fall through to the default
+  }
+
+  // Strategy 3: fallback
+  return 'main';
+}
+
+module.exports = {
+  detectDefaultBranch,
+};