@aperant/framework 0.6.3 → 0.6.5

package/src/cli/task/worktree-cleanup.mjs

@@ -12,13 +12,85 @@
 
 import { execFileSync } from 'node:child_process'
 
+/**
+ * Truncate a thrown git error to its first 3 stderr/message lines for
+ * surfacing in cleanup envelopes. Extracted from the original inline
+ * duplication at the auto-mode merge-error catch.
+ *
+ * @param {unknown} err
+ * @returns {string}
+ */
+function shortErr(err) {
+	return (err?.stderr || err?.message || '').toString().trim().split('\n').slice(0, 3).join(' ')
+}
+
+/**
+ * Sanitize an error message for inclusion in returned envelopes: first line
+ * only, absolute paths replaced with a placeholder to avoid leaking local
+ * filesystem layout.
+ *
+ * @param {string} msg
+ * @returns {string}
+ */
+function sanitizeErrMsg(msg) {
+	return msg
+		.split('\n')[0]
+		.replace(/\/[^\s:'"]+/g, '<path>')
+		.trim()
+}
+
+/**
+ * Run `git <args>` with up to 3 attempts and ~200ms backoff when the
+ * thrown error's stderr names `.git/index.lock`. Other errors propagate
+ * on the first failure. Two concurrent `task close-merged` invocations
+ * from different terminals race on git's internal index.lock;
+ * retry-on-EEXIST handles that without an app-level mutex (which
+ * wouldn't prevent the underlying git race anyway).
+ *
+ * Sleep uses the same Atomics.wait pattern as withFileLock in
+ * util/fs-lock.mjs to park the event loop without spinning the CPU.
+ *
+ * @param {string[]} args
+ * @param {object} opts - forwarded to execFileSync
+ * @returns {string} stdout
+ */
+function runGitWithRetry(args, opts) {
+	const maxAttempts = 3
+	const backoffMs = 200
+	let lastErr = null
+	for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+		try {
+			return execFileSync('git', args, opts)
+		} catch (err) {
+			lastErr = err
+			const stderrText = String(err?.stderr ?? '')
+			if (!/index\.lock/i.test(stderrText) || attempt === maxAttempts) {
+				throw err
+			}
+			try {
+				Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, backoffMs)
+			} catch {
+				/* runtime without SharedArrayBuffer — fall through, retry immediately */
+			}
+		}
+	}
+	// Unreachable — the loop either returns or throws.
+	throw lastErr
+}
+
 /**
  * @param {object} task - closed task record with worktree_path/branch/base_branch.
  * @param {string} mode - 'never' | 'ask' | 'auto'
  * @param {string} targetDir - main-repo project directory (cwd for git ops).
+ * @param {object} [opts]
+ * @param {boolean} [opts.prMerged=false] - true when the PR has been confirmed
+ *   merged on the remote. Skips local merge-back regardless of merge strategy
+ *   (merge / squash / rebase). Instead: fetch + ff-only the base branch, then
+ *   GC worktree + branch. Defaults to false so existing callers retain
+ *   byte-identical legacy behavior.
  * @returns {object|null} cleanup report block, or null if no worktree on task.
  */
-export function computeWorktreeCleanup(task, mode, targetDir) {
+export function computeWorktreeCleanup(task, mode, targetDir, opts = {}) {
 	if (!task?.worktree_path) return null
 
 	const wtPath = task.worktree_path
@@ -36,17 +108,132 @@ export function computeWorktreeCleanup(task, mode, targetDir) {
 	}
 
 	if (mode === 'ask') {
+		// When the PR is already merged on the remote, teach humans the
+		// fetch + ff-only recipe instead of the legacy local-merge recipe
+		// (which corrupts main when local task ref is stale or the PR used
+		// squash/rebase).
+		const cleanupCmd =
+			opts.prMerged === true
+				? `git fetch origin '${baseBranch}' && git checkout '${baseBranch}' && git merge --ff-only 'origin/${baseBranch}' && git worktree remove '${wtPath}' && git branch -d '${taskBranch}'`
+				: `git checkout '${baseBranch}' && git merge --no-edit '${taskBranch}' && git worktree remove '${wtPath}' && git branch -d '${taskBranch}'`
 		return {
 			mode,
 			worktree_path: wtPath,
 			branch: taskBranch,
 			base_branch: baseBranch,
 			action: 'pending',
-			cleanup_command: `git checkout ${baseBranch} && git merge --no-edit ${taskBranch} && git worktree remove ${wtPath} && git branch -d ${taskBranch}`,
+			cleanup_command: cleanupCmd,
+			...(opts.prMerged === true ? { pr_merged_remotely: true } : {}),
+		}
+	}
+
+	// mode === 'auto' && opts.prMerged === true.
+	// Trust origin as the merge authority. Method-agnostic across merge,
+	// squash, and rebase: fetch + checkout + ff-only, then GC. Never
+	// local-merge the task branch when GitHub already merged the PR.
+	if (opts.prMerged === true) {
+		let fetchOk = false
+		let ffOk = false
+		let branchDeleted = false
+		const warnings = []
+		try {
+			runGitWithRetry(['fetch', 'origin', baseBranch, '--no-tags'], {
+				cwd: targetDir,
+				encoding: 'utf-8',
+				stdio: 'pipe',
+			})
+			fetchOk = true
+		} catch (err) {
+			// Offline or network-error. Skip ff-only; user must
+			// `git pull --ff-only` later. Cleanup still proceeds.
+			warnings.push(`fetch_failed: ${sanitizeErrMsg(shortErr(err))}`)
+		}
+
+		try {
+			runGitWithRetry(['checkout', baseBranch], {
+				cwd: targetDir,
+				encoding: 'utf-8',
+				stdio: 'pipe',
+			})
+		} catch (err) {
+			// Couldn't switch to base branch (e.g. fresh clone where base
+			// doesn't exist locally). Surface and abort cleanup; preserve
+			// local repo state — do NOT GC the worktree+branch.
+			return {
+				mode,
+				worktree_path: wtPath,
+				branch: taskBranch,
+				base_branch: baseBranch,
+				action: 'checkout_failed',
+				error: shortErr(err),
+				message: `Could not checkout ${baseBranch}; local repo state preserved. Resolve and re-run.`,
+			}
+		}
+
+		if (fetchOk) {
+			try {
+				runGitWithRetry(['merge', '--ff-only', `origin/${baseBranch}`], {
+					cwd: targetDir,
+					encoding: 'utf-8',
+					stdio: 'pipe',
+				})
+				ffOk = true
+			} catch (err) {
+				// ff-only failed → local base has commits not on origin. Do
+				// NOT auto-resolve; warn and leave local at its current
+				// commit. Worktree + branch GC still runs.
+				warnings.push(`ff_only_failed: ${sanitizeErrMsg(shortErr(err))}`)
+			}
+		}
+
+		try {
+			runGitWithRetry(['worktree', 'remove', wtPath], {
+				cwd: targetDir,
+				encoding: 'utf-8',
+				stdio: 'pipe',
+			})
+		} catch {
+			try {
+				runGitWithRetry(['worktree', 'remove', '--force', wtPath], {
+					cwd: targetDir,
+					encoding: 'utf-8',
+					stdio: 'pipe',
+				})
+			} catch {
+				/* worktree already gone or unreachable */
+			}
+		}
+		try {
+			runGitWithRetry(['branch', '-d', taskBranch], {
+				cwd: targetDir,
+				encoding: 'utf-8',
+				stdio: 'pipe',
+			})
+			branchDeleted = true
+		} catch (err) {
+			// Squash/rebase strategies leave the local task branch as
+			// "not fully merged" (different SHAs from origin). Surface as
+			// a warning rather than force-delete; user can `git branch -D`
+			// manually if they want.
+			warnings.push(`branch_delete_failed: ${sanitizeErrMsg(shortErr(err))}`)
+		}
+
+		return {
+			mode,
+			worktree_path: wtPath,
+			branch: taskBranch,
+			base_branch: baseBranch,
+			action: 'pr_merged_remotely_cleaned',
+			fetched: fetchOk,
+			fast_forwarded: ffOk,
+			branch_deleted: branchDeleted,
+			...(warnings.length ? { warnings } : {}),
 		}
 	}
 
-	// mode === 'auto' — attempt merge-back in the main repo (never in the worktree).
+	// mode === 'auto' (legacy) — attempt merge-back in the main repo
+	// (never in the worktree). Direct `task close` callers without
+	// --pr-merged-remotely hit this path; byte-identical legacy behavior.
 	let mergeOk = false
 	let mergeError = null
 	try {
@@ -62,12 +249,7 @@ export function computeWorktreeCleanup(task, mode, targetDir) {
 		})
 		mergeOk = true
 	} catch (err) {
-		mergeError = (err.stderr || err.message || '')
-			.toString()
-			.trim()
-			.split('\n')
-			.slice(0, 3)
-			.join(' ')
+		mergeError = shortErr(err)
 		// Abort the failed merge so the main repo is left clean.
 		try {
 			execFileSync('git', ['merge', '--abort'], {

package/templates/adr-format.md

@@ -0,0 +1,56 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/ADR-FORMAT.md
+Licensed under MIT. Modifications: ported as the Aperant ADR template
+emitted by `apt-tools adr write` with Nygard's 3-gate filter
+(hard-to-reverse AND surprising-without-context AND real-trade-off).
+-->
+
+# ADR-NNNN: {Title}
+
+**Status:** {Proposed | Accepted | Deprecated | Superseded}
+**Date:** {YYYY-MM-DD}
+
+## Context
+
+{What is the issue that we're seeing that is motivating this decision or
+change? Include enough background that a reader 12 months from now can
+understand WHY this decision was needed without reading the surrounding
+codebase. Cite empirical evidence, prior decisions, or codebase artifacts
+where possible.}
+
+## Decision
+
+{What is the change that we're proposing or have agreed to implement?
+State the decision in declarative terms — what WILL be done, not what
+might be considered.}
+
+## Consequences
+
+{What becomes easier or harder to do because of this change? Enumerate
+both the positive and negative consequences. The Nygard form is
+deliberately neutral — you list both upsides and downsides so a future
+reader can weigh whether the trade-off still holds.}
+
+---
+
+## Nygard 3-gate filter (audit trail)
+
+This ADR was written via `apt-tools adr write` and passed all three of
+Nygard's filter gates. If any one had failed, the decision would have
+stayed in `.aperant/context/notes/{task-id}.md` and no ADR file would
+have been created. The filter prevents ADR pollution — only durable,
+surprising, trade-off-bearing decisions become ADRs.
+
+- **Hard to reverse:** {true | false} — Could this be undone in a single
+  PR if we changed our minds in 6 months? If "yes, easily" → not an ADR.
+- **Surprising without context:** {true | false} — Would a new
+  contributor reading the code be surprised by this choice and want to
+  know why? If "no, this is the obvious approach" → not an ADR.
+- **Real trade-off:** {true | false} — Did we genuinely consider an
+  alternative and pick the worse-along-one-axis option for a
+  better-along-another? If "no, no alternative was real" → not an ADR.
+
+Reversible decisions, obvious decisions, and trade-off-free decisions
+all stay in context-notes — they survive the task but don't deserve a
+permanent ADR slot.

package/templates/config.json

@@ -106,6 +106,10 @@
 		"review_mode": "auto",
 		"debate_mode": "auto"
 	},
+	"diagram": {
+		"mode": "file",
+		"mcpConsent": null
+	},
 	"docs_policy": {
 		"$comment": "C33 docs-coherence policy. Override via /apt:setup Batch 7. Keys are globs/paths; values are 'auto-update' | 'flag-drift' | 'skip'. Missing block → defaults from packages/framework/templates/docs-policy-defaults.json apply."
 	},

package/templates/context-format.md

@@ -0,0 +1,34 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md
+Licensed under MIT. Modifications: ported as the Aperant CONTEXT.md
+template emitted by `apt-tools context write`. Adds the "Project glossary"
+header and example dialogue section.
+-->
+
+# Project glossary (CONTEXT.md)
+
+This file is the persistent project glossary. Each term-block carries the
+following fields per Pocock's CONTEXT.md format:
+
+- **{Term}** — definition (one line).
+  - **Aliases to avoid:** comma-separated synonyms or near-synonyms that
+    should NOT be used interchangeably. Prevents conflated-terminology
+    bugs that no amount of code review catches.
+  - **Cardinality:** one-to-one, one-to-many, many-to-many. When the
+    term refers to an entity, this is the relationship to its parent or
+    children.
+  - **Flagged ambiguities:** any known gray areas where the term is used
+    inconsistently in the codebase. Resolving these is part of the
+    grill loop.
+  - **Example dialogue:** a 1-2 turn example showing how the term is
+    used in a sentence (or in a UI label, error message, API field
+    name). Anchors the term to surface usage.
+
+`apt-tools context write` upserts term-blocks into this file. The writer
+is idempotent — re-running with the same `--term` overwrites the
+existing block in place. Fields not explicitly overridden are preserved.
+
+The format intentionally mirrors a domain glossary, not a code glossary.
+Terms are user-facing concepts (e.g., "Plan thread", "Sparring round"),
+not implementation details (e.g., "ChatSession", "useTaskStore").