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

package/lib/commands/clean.js

@@ -118,13 +118,15 @@ function parseMainWorktree(output) {
 }
 
 /**
- * GitHub tier: collect head refs of merged PRs (one memoized call).
- * Returns an empty Set when gh is unavailable or errors — a safe no-signal.
+ * GitHub tier: collect merged PRs keyed by head branch (one memoized call).
+ * Returns an empty Map when gh is unavailable or errors — a safe no-signal.
+ * The number/title/merge-commit ride along so a merge can be CITED as evidence on
+ * the kernel issue the branch was linked to (18f1988e), not just detected.
  * @param {Function} runFile - execFileSync-compatible function
- * @returns {Map<string, string>} Map of merged PR head branch name -> head commit OID
+ * @returns {Map<string, {headRefOid: string, number: number, title: string, mergeCommitOid: string|null}>}
  */
-function getGhMergedRefs(runFile) {
-  const out = tryRun(runFile, 'gh', ['pr', 'list', '--state', 'merged', '--json', 'headRefName,headRefOid', '--limit', '200']);
+function getGhMergedPrs(runFile) {
+  const out = tryRun(runFile, 'gh', ['pr', 'list', '--state', 'merged', '--json', 'number,title,headRefName,headRefOid,mergeCommit', '--limit', '200']);
   if (!out) return new Map();
   try {
     const arr = JSON.parse(out);
@@ -133,7 +135,14 @@ function getGhMergedRefs(runFile) {
     // Record the head OID too: a reused/advanced branch name must NOT be treated as
     // merged unless its current tip still matches the OID GitHub merged.
     for (const p of arr) {
-      if (p && p.headRefName && p.headRefOid) map.set(p.headRefName, p.headRefOid);
+      if (p && p.headRefName && p.headRefOid) {
+        map.set(p.headRefName, {
+          headRefOid: p.headRefOid,
+          number: p.number,
+          title: p.title,
+          mergeCommitOid: (p.mergeCommit && p.mergeCommit.oid) || null,
+        });
+      }
     }
     return map;
   } catch (_e) { /* intentional: malformed gh output → no signal */ // NOSONAR S2486
@@ -166,30 +175,63 @@ function isSquashMerged(branch, defaultBranch, runFile) {
   return cherry.startsWith('-');
 }
 
+/**
+ * GitHub tier: a merged PR whose head OID still matches the branch tip. This is
+ * direct evidence THIS tip was merged, not a git-topology inference — a
+ * reused/advanced branch name falls through to the git-only tiers instead.
+ * @param {string} branch - Branch name
+ * @param {object} ctx - Detection context (see detectMerged)
+ * @returns {boolean} True iff a merged PR is pinned to the current branch tip
+ */
+function hasMergedPrEvidence(branch, ctx) {
+  const pr = ctx.ghMergedPrs && ctx.ghMergedPrs.get(branch);
+  if (!pr || !pr.headRefOid) return false;
+  const tip = tryRun(ctx.runFile, 'git', ['rev-parse', branch]);
+  return Boolean(tip) && tip === pr.headRefOid;
+}
+
+/**
+ * Whether a branch has contributed nothing yet — zero commits ahead of the
+ * default branch (kernel c5ab529e).
+ *
+ * A branch created but not yet committed to points AT a default-branch commit,
+ * so `git branch --merged` lists it and squash patch-equivalence finds an empty
+ * diff already present: every git-only tier reads it as merged. It is unstarted
+ * work, and `forge clean` deleted a live agent's fresh worktree and closed its
+ * issue on that reading. Only a VERIFIED count of 0 counts as unstarted; an
+ * unreadable count leaves detection exactly as it was.
+ *
+ * @param {string} branch - Branch name
+ * @param {object} ctx - Detection context (see detectMerged)
+ * @returns {boolean} True iff the branch is verified to have no commits of its own
+ */
+function isUnstartedBranch(branch, ctx) {
+  const out = tryRun(ctx.runFile, 'git', ['rev-list', '--count', `${ctx.defaultBranch}..${branch}`]);
+  return out !== '' && parseInt(out, 10) === 0;
+}
+
 /**
  * Squash-aware merged detection over three short-circuiting tiers:
- *   (a) ancestry list (`git branch --merged`), (b) merged-PR head refs (gh),
+ *   (a) merged-PR head refs (gh), (b) ancestry list (`git branch --merged`),
  *   (c) git-only squash patch-equivalence. A branch confirmed by none stays.
+ *
+ * The gh tier runs first because it is the only tier that cites real merge
+ * evidence, so it still recognizes a fast-forward/merge-commit PR whose branch
+ * ends up 0 commits ahead. The git-only tiers below cannot tell that case apart
+ * from an unstarted branch, so they are gated on the branch having commits.
+ *
  * @param {string} branch - Branch name
  * @param {object} ctx - Detection context
  * @param {string} ctx.defaultBranch - Default branch name
  * @param {string[]} ctx.mergedBranches - Ancestry-merged branch names
- * @param {Map<string, string>} ctx.ghMergedRefs - Merged PR head branch -> head OID
+ * @param {Map<string, object>} ctx.ghMergedPrs - Merged PR head branch -> PR evidence
  * @param {Function} ctx.runFile - execFileSync-compatible function
  * @returns {boolean} True iff the branch is merged (any tier)
  */
 function detectMerged(branch, ctx) {
+  if (hasMergedPrEvidence(branch, ctx)) return true;
+  if (isUnstartedBranch(branch, ctx)) return false;
   if (ctx.mergedBranches.includes(branch)) return true;
-  if (ctx.ghMergedRefs) {
-    const mergedOid = ctx.ghMergedRefs.get(branch);
-    // Only trust the gh "merged" signal when the merged PR's head OID still matches
-    // the branch tip; a reused/advanced branch name with new commits falls through
-    // to the squash patch-equivalence check (never remove on doubt).
-    if (mergedOid) {
-      const tip = tryRun(ctx.runFile, 'git', ['rev-parse', branch]);
-      if (tip && tip === mergedOid) return true;
-    }
-  }
   return isSquashMerged(branch, ctx.defaultBranch, ctx.runFile);
 }
 
@@ -270,32 +312,40 @@ async function removeWorktreeRobust(wtPath, runFile, fsApi, opts = {}) {
  * @param {Function} runFile - execFileSync-compatible function
  * @param {object} fsApi - fs-compatible module
  * @param {object} opts - Removal injection options
- * @returns {Promise<{ status: string, path: string, branch: string|null, error?: string }>}
+ * @returns {Promise<{ status: string, path: string, branch: string|null,
+ *   closeIssue: boolean, error?: string }>}
  */
 async function cleanWorktree(dir, worktreeMap, isMergedFn, worktreesDir, dryRun, runFile, fsApi, opts) {
   const wtPath = path.resolve(worktreesDir, dir);
   // Lookup by canonical key (86b04c20): porcelain emits C:/ paths, resolve emits C:\.
   const branch = worktreeMap.get(normalizeWorktreeKey(wtPath)) || null;
 
+  // `closeIssue` rides on the SAME outcome that decides removal (kernel c5ab529e).
+  // Closing is irreversible — `done` is terminal — so it may never be recomputed
+  // independently and drift away from what cleanup actually decided to do.
   if (!branch || !isMergedFn(branch)) {
-    return { status: 'active', path: wtPath, branch };
+    return { status: 'active', path: wtPath, branch, closeIssue: false };
   }
 
   // Merged, but never blow away uncommitted local edits. Checked BEFORE the dry-run
   // branch so a dry run reports the same "dirty" skip the real run would take.
+  // Held back for safety => the work is not confirmed finished => never closed.
   if (isWorktreeDirty(wtPath, runFile)) {
-    return { status: 'dirty', path: wtPath, branch };
+    return { status: 'dirty', path: wtPath, branch, closeIssue: false };
   }
 
+  // A dry run reports what it would do and mutates nothing, kernel included.
   if (dryRun) {
-    return { status: 'cleaned', path: wtPath, branch };
+    return { status: 'cleaned', path: wtPath, branch, closeIssue: false };
   }
 
   const outcome = await removeWorktreeRobust(wtPath, runFile, fsApi, opts);
   if (outcome.removed) {
-    return { status: 'cleaned', path: wtPath, branch, method: outcome.method };
+    return { status: 'cleaned', path: wtPath, branch, method: outcome.method, closeIssue: true };
   }
-  return { status: 'survivor', path: wtPath, branch, error: outcome.error };
+  // Merged with a clean tree; only the directory removal lost to an FS lock. The
+  // work IS in the default branch, so the issue is finished either way.
+  return { status: 'survivor', path: wtPath, branch, error: outcome.error, closeIssue: true };
 }
 
 /**
@@ -449,6 +499,13 @@ function renderSurvivors(survivors, lines) {
   for (const s of survivors) lines.push(`  - ${s.path}${s.error ? ` (${s.error})` : ''}`);
 }
 
+/** Append the closed-linked-issue lines. */
+function renderClosedIssues(closedIssues, lines) {
+  if (!closedIssues || closedIssues.length === 0) return;
+  lines.push(`Closed ${closedIssues.length} linked issue(s) on merge:`);
+  for (const c of closedIssues) lines.push(`  - ${c.issueId} (${c.branch})`);
+}
+
 /** Append the master-sync outcome line(s). */
 function renderMasterSync(masterSync, lines) {
   if (!masterSync || !masterSync.attempted) return;
@@ -472,10 +529,94 @@ function formatOutput(summary) {
   lines.push(`${verb} ${summary.cleaned} merged worktree(s); ${summary.active} active kept.`);
   renderDirty(summary.dirty, lines);
   renderSurvivors(summary.survivors, lines);
+  renderClosedIssues(summary.closedIssues, lines);
   renderMasterSync(summary.masterSync, lines);
   return lines.join('\n');
 }
 
+/**
+ * Strip the merged-PR record down to the evidence cited on the kernel issue.
+ * @param {Map<string, object>} ghMergedPrs
+ * @param {string} branch
+ * @returns {{number: number, title: string, mergeCommitOid: string|null}|null}
+ */
+function prEvidenceFor(ghMergedPrs, branch) {
+  const pr = ghMergedPrs && ghMergedPrs.get(branch);
+  if (!pr || !pr.number) return null;
+  return { number: pr.number, title: pr.title, mergeCommitOid: pr.mergeCommitOid };
+}
+
+/**
+ * Bridge from a merged branch to the close-on-merge primitive (kernel 18f1988e).
+ *
+ * The kernel driver + issue runner are built ONCE and only on the first merged
+ * branch, so a clean run that removes nothing pays nothing. The driver is closed
+ * by `dispose()` — and ONLY when this helper owns it, since an injected driver
+ * belongs to the caller. Leaving an owned sqlite handle open keeps the kernel file
+ * locked and fails Windows cleanup.
+ *
+ * @param {string} projectRoot
+ * @param {Function} runFile - execFileSync-compatible function (repo probe)
+ * @param {object} opts - DI (`_closeLinkedIssue`, `_kernelDriver`, `_runIssueOperation`)
+ * @returns {{ close: Function, dispose: Function }}
+ */
+function createIssueCloser(projectRoot, runFile, opts) {
+  const injected = opts._closeLinkedIssue;
+  let built = null;
+  const unavailable = { driver: null, run: null, owned: false };
+
+  async function resolveDeps() {
+    if (built) return built;
+    if (opts._kernelDriver && opts._runIssueOperation) {
+      built = { driver: opts._kernelDriver, run: opts._runIssueOperation, owned: false };
+      return built;
+    }
+    // Only reach for the kernel inside a REAL git repo. buildMigratedKernelIssueDeps
+    // CREATES the store at <git-common-dir>/forge/kernel.sqlite, so probing first is
+    // what stops a clean run pointed at a non-repo path from minting a stray kernel
+    // there. An empty result (rev-parse failed) means "not a repo".
+    if (!tryRun(runFile, 'git', ['-C', projectRoot, 'rev-parse', '--git-common-dir'])) {
+      built = unavailable;
+      return built;
+    }
+    try {
+      const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
+      const { runIssueOperation } = require('../forge-issues');
+      const { kernelDriver, kernelBroker } = await buildMigratedKernelIssueDeps({ projectRoot });
+      // Thread the broker through so every op reuses THIS driver instead of opening
+      // a fresh kernel handle per call.
+      built = {
+        driver: kernelDriver,
+        run: (operation, args, root) => runIssueOperation(operation, args, root, { kernelBroker }),
+        owned: true,
+      };
+    } catch (_e) { /* intentional: no kernel → close nothing, clean normally */ // NOSONAR S2486
+      built = unavailable;
+    }
+    return built;
+  }
+
+  return {
+    async close(branch, pr) {
+      try {
+        if (injected) return await injected({ branch, pr, projectRoot });
+        const { driver, run } = await resolveDeps();
+        if (!driver || !run) return { closed: false, reason: 'unavailable' };
+        const { closeLinkedIssueOnMerge } = require('../kernel/close-on-merge');
+        return await closeLinkedIssueOnMerge({ branch, projectRoot, pr, driver, runIssueOperation: run });
+      } catch (error) {
+        // Best-effort: cleanup must never fail because tracking did.
+        return { closed: false, reason: 'error', error: error && error.message };
+      }
+    },
+    dispose() {
+      if (built && built.owned && built.driver && typeof built.driver.close === 'function') {
+        try { built.driver.close(); } catch (_e) { /* best-effort */ } // NOSONAR S2486
+      }
+    },
+  };
+}
+
 /**
  * Main handler for the clean command.
  * @param {string[]} _args - Positional arguments (unused)
@@ -492,10 +633,11 @@ function formatOutput(summary) {
  * Scan .worktrees/ and remove the merged ones (squash-aware). Returns the tallies;
  * a no-op ({0,0,[],[]}) when .worktrees/ is absent or empty. Extracted from handler
  * so the top-level orchestration stays under the complexity gate.
- * @returns {Promise<{ cleaned: number, active: number, survivors: object[], dirty: string[] }>}
+ * @param {{close: Function}|null} [closer] - Close-on-merge bridge (null in dry-run)
+ * @returns {Promise<{ cleaned: number, active: number, survivors: object[], dirty: string[], closedIssues: object[] }>}
  */
-async function cleanWorktrees(worktreesDir, runFile, fsApi, dryRun, opts) {
-  const acc = { cleaned: 0, active: 0, survivors: [], dirty: [] };
+async function cleanWorktrees(worktreesDir, runFile, fsApi, dryRun, opts, closer = null) {
+  const acc = { cleaned: 0, active: 0, survivors: [], dirty: [], closedIssues: [] };
   if (!fsApi.existsSync(worktreesDir)) return acc;
 
   const entries = fsApi.readdirSync(worktreesDir, { withFileTypes: true });
@@ -512,8 +654,8 @@ async function cleanWorktrees(worktreesDir, runFile, fsApi, dryRun, opts) {
     // ancestry fast path instead of falling through to the slower squash tier.
     mergedBranches = mergedOut.split('\n').map(b => b.trim().replace(/^[*+]\s*/, '')).filter(Boolean);
   }
-  const ghMergedRefs = getGhMergedRefs(runFile);
-  const ctx = { defaultBranch, mergedBranches, ghMergedRefs, runFile };
+  const ghMergedPrs = getGhMergedPrs(runFile);
+  const ctx = { defaultBranch, mergedBranches, ghMergedPrs, runFile };
   const isMergedFn = opts._isMerged || (branch => detectMerged(branch, ctx));
 
   const listOutput = tryRun(runFile, 'git', ['worktree', 'list', '--porcelain']);
@@ -525,6 +667,16 @@ async function cleanWorktrees(worktreesDir, runFile, fsApi, dryRun, opts) {
     else if (res.status === 'survivor') acc.survivors.push(res);
     else if (res.status === 'dirty') acc.dirty.push(res.path);
     else acc.active++;
+
+    // Close only what THIS outcome authorized (18f1988e, tightened by c5ab529e):
+    // `closeIssue` is set by cleanWorktree alongside the removal decision, so a
+    // worktree held back for any reason cannot have its issue closed.
+    if (closer && res.branch && res.closeIssue) {
+      const outcome = await closer.close(res.branch, prEvidenceFor(ghMergedPrs, res.branch));
+      if (outcome && outcome.closed) {
+        acc.closedIssues.push({ branch: res.branch, issueId: outcome.issueId });
+      }
+    }
   }
 
   if (!dryRun && acc.cleaned > 0) {
@@ -541,7 +693,15 @@ async function handler(_args, flags, projectRoot, opts = {}) {
   const worktreesDir = path.resolve(projectRoot, '.worktrees');
 
   // Worktree cleanup (no-op when .worktrees/ absent); master auto-update is independent.
-  const { cleaned, active, survivors, dirty } = await cleanWorktrees(worktreesDir, runFile, fsApi, dryRun, opts);
+  // A dry run detects merges but must not mutate the kernel, so it gets no closer.
+  const closer = dryRun ? null : createIssueCloser(projectRoot, runFile, opts);
+  let scan;
+  try {
+    scan = await cleanWorktrees(worktreesDir, runFile, fsApi, dryRun, opts, closer);
+  } finally {
+    if (closer) closer.dispose();
+  }
+  const { cleaned, active, survivors, dirty, closedIssues } = scan;
 
   // Post-merge master auto-update (default-on; skipped in dry-run).
   let masterSync = null;
@@ -550,7 +710,7 @@ async function handler(_args, flags, projectRoot, opts = {}) {
     masterSync = await doSync();
   }
 
-  return finalize({ success: true, cleaned, active, dryRun, survivors, dirty }, masterSync);
+  return finalize({ success: true, cleaned, active, dryRun, survivors, dirty, closedIssues }, masterSync);
 }
 
 /**
@@ -576,8 +736,12 @@ module.exports = {
     normalizeWorktreeKey,
     parseWorktreeList,
     parseMainWorktree,
-    getGhMergedRefs,
+    getGhMergedPrs,
+    prEvidenceFor,
+    createIssueCloser,
     isSquashMerged,
+    hasMergedPrEvidence,
+    isUnstartedBranch,
     detectMerged,
     isWorktreeDirty,
     removeWorktreeRobust,

package/lib/commands/dev.js

@@ -460,50 +460,21 @@ function withDevAuditEvidence(featureName, phase, result, options = {}) {
 		},
 	};
 
+	// Evidence is best-effort: it records what the dev cycle did, so a log the
+	// process could not write never changes the outcome it was recording.
 	try {
-		const auditEvidence = emitImplementerAuditEvidence(auditEvent, options.auditOptions || {});
-		if (auditEvidence.record?.success === false) {
-			const auditError = auditEvidence.record.error || 'bd audit record failed';
-			return {
-				...result,
-				success: false,
-				error: result.success === false ? result.error : `Audit evidence persistence failed: ${auditError}`,
-				auditEvidence,
-			};
-		}
-
 		return {
 			...result,
-			auditEvidence,
+			auditEvidence: emitImplementerAuditEvidence(auditEvent, options.auditOptions || {}),
 		};
 	} catch (error) {
-		if (isAuditCommandUnavailableError(error)) {
-			return {
-				...result,
-				auditEvidence: {
-					success: false,
-					skipped: true,
-					error: error.message,
-				},
-			};
-		}
-
 		return {
 			...result,
-			success: false,
-			error: result.success === false ? result.error : `Audit evidence persistence failed: ${error.message}`,
-			auditEvidence: {
-				success: false,
-				error: error.message,
-			},
+			auditEvidence: { success: false, error: error.message },
 		};
 	}
 }
 
-function isAuditCommandUnavailableError(error) {
-	return error?.code === 'ENOENT' || /\bbd\b.*not found/i.test(error?.message || '');
-}
-
 /**
  * Decision gate route constants
  *