gsd-pi 2.81.0 → 2.82.0-dev.725028083

package/dist/resources/extensions/gsd/memory-backfill.js

@@ -1,9 +1,10 @@
 // GSD2 — Decisions -> memories backfill (ADR-013 step 5)
 //
-// Idempotent one-shot migration that copies every active decisions row into
-// the memories table with category="architecture" and a structured_fields
-// payload preserving the original gsd_save_decision schema (when_context,
-// scope, decision, choice, rationale, made_by, revisable, sourceDecisionId).
+// Idempotent migration that copies every decisions row (active and
+// superseded — see Stage 2a note below) into the memories table with
+// category="architecture" and a structured_fields payload preserving the
+// original gsd_save_decision schema (when_context, scope, decision, choice,
+// rationale, made_by, revisable, superseded_by, sourceDecisionId).
 //
 // The backfill exists so the cutover in ADR-013 step 6 can drop the
 // decisions table without losing schema fidelity. Idempotency is enforced
@@ -14,11 +15,18 @@
 // only ever fires once per project. Costs O(N) inserts on first run where
 // N is the active-decisions count; subsequent runs are an O(N) lookup that
 // finds existing markers and exits.
+//
+// ADR-013 Stage 2a (PR #5755): backfill now includes superseded rows so the
+// DECISIONS.md projection regen can source from memories without losing
+// historical entries. An auto-heal pass runs after the initial migration to
+// pick up superseded_by changes that occurred after the source decision was
+// already migrated (e.g. a fresh md-importer run that introduced a new
+// supersedes-chain).
 import { isDbAvailable, _getAdapter } from "./gsd-db.js";
 import { createMemory } from "./memory-store.js";
 import { logWarning } from "./workflow-logger.js";
 /**
- * Backfill active decisions rows into the memories table.
+ * Backfill decisions rows into the memories table.
  *
  * - Idempotent (per-row): every row written carries
  *   `structured_fields.sourceDecisionId = "<decisionId>"`. Each candidate
@@ -27,13 +35,18 @@ import { logWarning } from "./workflow-logger.js";
  *   their own `sourceDecisionId` does NOT abort the backfill.
  * - Best-effort: never throws. Logs and returns 0 on failure so a broken
  *   backfill cannot block agent startup.
- * - Active-only: skips rows where `superseded_by IS NOT NULL`. Superseded
- *   decisions are historical record; the memory store is for active
- *   knowledge.
+ * - Full migration (ADR-013 Stage 2a): both active and superseded rows are
+ *   migrated. `structured_fields.superseded_by` preserves the supersedes
+ *   chain so the DECISIONS.md projection regen can source from memories
+ *   without losing historical entries.
+ * - Drift auto-heal: after the initial insert pass, the function updates
+ *   any pre-existing memory whose `structured_fields.superseded_by` drifted
+ *   from the source decision (e.g. a fresh md-importer run introduced a
+ *   new supersedes annotation after the initial migration).
  *
  * Returns the number of memories written (0 when already backfilled or
- * when the DB has no decisions). Callers can log the result or surface it
- * to the user.
+ * when the DB has no decisions). Drift-heal updates are not counted in
+ * this return — they are logged separately.
  */
 export function backfillDecisionsToMemories() {
     if (!isDbAvailable())
@@ -43,7 +56,7 @@ export function backfillDecisionsToMemories() {
         return 0;
     try {
         const decisions = adapter
-            .prepare("SELECT id, when_context, scope, decision, choice, rationale, made_by, revisable, superseded_by FROM decisions WHERE superseded_by IS NULL")
+            .prepare("SELECT id, when_context, scope, decision, choice, rationale, made_by, revisable, superseded_by FROM decisions ORDER BY seq")
             .all();
         if (decisions.length === 0)
             return 0;
@@ -52,8 +65,10 @@ export function backfillDecisionsToMemories() {
         // per row by matching that exact id, NOT by a global sentinel — a global
         // sentinel would silently abort the backfill if a user manually called
         // capture_thought with their own structuredFields.sourceDecisionId.
-        const checkExisting = adapter.prepare("SELECT 1 FROM memories WHERE structured_fields LIKE :pattern LIMIT 1");
+        const checkExisting = adapter.prepare("SELECT id, structured_fields FROM memories WHERE structured_fields LIKE :pattern LIMIT 1");
+        const updateStructuredFields = adapter.prepare("UPDATE memories SET structured_fields = :sf, updated_at = :ts WHERE id = :id");
         let written = 0;
+        let healed = 0;
         for (const raw of decisions) {
             const row = {
                 id: String(raw["id"] ?? ""),
@@ -68,11 +83,40 @@ export function backfillDecisionsToMemories() {
             };
             if (!row.id)
                 continue;
-            // Pattern is anchored to the JSON-stringified shape and the exact
-            // decision id to avoid prefix collisions (e.g. "D1" vs "D10").
-            if (checkExisting.get({ ":pattern": `%"sourceDecisionId":"${row.id}"%` }))
+            const pattern = `%"sourceDecisionId":"${row.id}"%`;
+            const existing = checkExisting.get({ ":pattern": pattern });
+            if (existing) {
+                // Drift auto-heal: if the source decision's superseded_by has changed
+                // since the original migration, update the memory in place. Read-side
+                // queries reconstruct Decision.superseded_by from this field, so the
+                // DECISIONS.md projection stays accurate without us having to track
+                // supersedes events at the write site.
+                const parsedSf = existing.structured_fields
+                    ? safeParse(existing.structured_fields)
+                    : {};
+                if (existing.structured_fields && !parsedSf) {
+                    logWarning("memory-backfill", `decisions->memories drift heal skipped for ${row.id}: invalid structured_fields JSON`);
+                    continue;
+                }
+                const currentSf = parsedSf ?? {};
+                const memorySuperseded = typeof currentSf["superseded_by"] === "string" || currentSf["superseded_by"] === null
+                    ? currentSf["superseded_by"]
+                    : null;
+                if (memorySuperseded !== row.superseded_by) {
+                    const merged = {
+                        ...currentSf,
+                        superseded_by: row.superseded_by,
+                    };
+                    updateStructuredFields.run({
+                        ":id": existing.id,
+                        ":sf": JSON.stringify(merged),
+                        ":ts": new Date().toISOString(),
+                    });
+                    healed += 1;
+                }
                 continue;
-            const content = synthesizeContent(row);
+            }
+            const content = synthesizeDecisionMemoryContent(row);
             const id = createMemory({
                 category: "architecture",
                 content,
@@ -87,11 +131,15 @@ export function backfillDecisionsToMemories() {
                     rationale: row.rationale,
                     made_by: row.made_by,
                     revisable: row.revisable,
+                    superseded_by: row.superseded_by,
                 },
             });
             if (id)
                 written += 1;
         }
+        if (healed > 0) {
+            logWarning("memory-backfill", `decisions->memories drift healed: ${healed} row${healed === 1 ? "" : "s"} updated superseded_by`);
+        }
         return written;
     }
     catch (e) {
@@ -99,6 +147,14 @@ export function backfillDecisionsToMemories() {
         return 0;
     }
 }
+function safeParse(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Combine the decision's structured fields into a 1-3 sentence content
  * string suitable for keyword retrieval and human review.
@@ -107,7 +163,7 @@ export function backfillDecisionsToMemories() {
  * Truncates each field to keep the synthesized line under ~600 chars so
  * memory_query rendering stays readable.
  */
-function synthesizeContent(row) {
+export function synthesizeDecisionMemoryContent(row) {
     const trim = (value, max) => {
         const cleaned = value.replace(/\s+/g, " ").trim();
         return cleaned.length > max ? cleaned.slice(0, max - 1) + "\u2026" : cleaned;

package/dist/resources/extensions/gsd/memory-consolidation-scanner.js

@@ -0,0 +1,222 @@
+// GSD-2 — ADR-013 Phase 6 preflight scanner.
+//
+// Read-only detection of rows in the legacy knowledge surfaces (decisions
+// table, `.gsd/KNOWLEDGE.md`) that lack a corresponding `memories` row.
+// Runs on session start (and on demand via doctor); never mutates state.
+//
+// The scanner exists so the destructive Phase 6 cutover (#5755) can prove
+// the migration is complete before any tables are dropped. Today's
+// `backfillDecisionsToMemories` writes a `structured_fields.sourceDecisionId`
+// marker on each migrated row; the scanner uses that marker for decisions
+// detection. A `sourceKnowledgeId` marker is reserved for the parallel
+// KNOWLEDGE.md backfill that Phase 6 will introduce — until that ships,
+// every KNOWLEDGE.md row is reported as unmigrated, which is the honest
+// state of the consolidation.
+import { existsSync, readFileSync } from "node:fs";
+import { _getAdapter, isDbAvailable } from "./gsd-db.js";
+import { appendNotification } from "./notification-store.js";
+import { resolveGsdRootFile } from "./paths.js";
+import { logWarning } from "./workflow-logger.js";
+// ─── KNOWLEDGE.md parsing ────────────────────────────────────────────────────
+const KNOWLEDGE_SECTIONS = [
+    { table: "rules", heading: "## Rules", idPrefix: "K" },
+    { table: "patterns", heading: "## Patterns", idPrefix: "P" },
+    { table: "lessons", heading: "## Lessons Learned", idPrefix: "L" },
+];
+/**
+ * Parse `.gsd/KNOWLEDGE.md` into rows, one per table entry. Skips the table
+ * header and separator lines; ignores rows from unrecognized sections.
+ *
+ * The format is locked in `files.ts:appendKnowledge` — three `## ` sections
+ * (Rules, Patterns, Lessons Learned), each a Markdown table. Row IDs are
+ * `K###` / `P###` / `L###`.
+ */
+export function parseKnowledgeRows(content) {
+    const rows = [];
+    if (!content.trim())
+        return rows;
+    // Slice the content into sections by heading. The leading text before the
+    // first ## heading is intro prose — ignored.
+    const lines = content.split("\n");
+    let activeSection;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("## ")) {
+            activeSection = KNOWLEDGE_SECTIONS.find((s) => s.heading === trimmed);
+            continue;
+        }
+        if (!activeSection)
+            continue;
+        if (!trimmed.startsWith("|"))
+            continue;
+        // Skip the table header rows: the column-titles line and the |---|---| separator.
+        // Real data rows start with `| <prefix>### |`.
+        const idMatch = new RegExp(`^\\|\\s*(${activeSection.idPrefix}\\d+)\\s*\\|`).exec(trimmed);
+        if (!idMatch)
+            continue;
+        rows.push({
+            table: activeSection.table,
+            id: idMatch[1] ?? "",
+            row: trimmed,
+        });
+    }
+    return rows;
+}
+function knowledgeMdContent(basePath) {
+    const path = resolveGsdRootFile(basePath, "KNOWLEDGE");
+    if (!existsSync(path))
+        return "";
+    try {
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+function getActiveDecisions() {
+    if (!isDbAvailable())
+        return [];
+    const adapter = _getAdapter();
+    if (!adapter)
+        return [];
+    try {
+        const rows = adapter
+            .prepare("SELECT id, decision FROM decisions WHERE superseded_by IS NULL")
+            .all();
+        return rows
+            .map((row) => ({
+            id: String(row["id"] ?? ""),
+            decision: String(row["decision"] ?? ""),
+        }))
+            .filter((row) => row.id.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * True when a memory row has a `structured_fields` JSON payload containing
+ * the given `markerKey: "value"` pair. Matches the LIKE pattern used by
+ * `backfillDecisionsToMemories` so the scanner is consistent with the
+ * backfill's idempotency check.
+ */
+function memoryHasSourceMarker(markerKey, value) {
+    if (!isDbAvailable())
+        return false;
+    const adapter = _getAdapter();
+    if (!adapter)
+        return false;
+    try {
+        const pattern = `%"${markerKey}":"${value}"%`;
+        const row = adapter
+            .prepare("SELECT 1 FROM memories WHERE structured_fields LIKE :pattern LIMIT 1")
+            .get({ ":pattern": pattern });
+        return row !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+const SAMPLE_LIMIT = 5;
+/**
+ * Scan the legacy knowledge surfaces and return a structured report of what's
+ * already in the `memories` table vs what's still unmigrated. Pure detection
+ * — no DB writes, no file writes, no notifications.
+ */
+export function scanConsolidationGaps(basePath) {
+    // ── Decisions ────────────────────────────────────────────────────────
+    const decisions = getActiveDecisions();
+    const decisionSamples = [];
+    let decisionMigrated = 0;
+    for (const decision of decisions) {
+        if (memoryHasSourceMarker("sourceDecisionId", decision.id)) {
+            decisionMigrated += 1;
+            continue;
+        }
+        if (decisionSamples.length < SAMPLE_LIMIT) {
+            decisionSamples.push({
+                id: decision.id,
+                decision: decision.decision.length > 80 ? decision.decision.slice(0, 79) + "…" : decision.decision,
+            });
+        }
+    }
+    // ── KNOWLEDGE.md ─────────────────────────────────────────────────────
+    const knowledgeRows = parseKnowledgeRows(knowledgeMdContent(basePath));
+    const knowledgeByTable = { rules: 0, patterns: 0, lessons: 0 };
+    const knowledgeSamples = [];
+    let knowledgeMigrated = 0;
+    for (const row of knowledgeRows) {
+        knowledgeByTable[row.table] += 1;
+        // Phase 6 will introduce a `sourceKnowledgeId` marker as part of the
+        // KNOWLEDGE.md backfill. Until that path ships, this check returns
+        // false for every row, which is the honest state of the consolidation.
+        if (memoryHasSourceMarker("sourceKnowledgeId", row.id)) {
+            knowledgeMigrated += 1;
+            continue;
+        }
+        if (knowledgeSamples.length < SAMPLE_LIMIT) {
+            knowledgeSamples.push({
+                table: row.table,
+                id: row.id,
+                row: row.row.length > 100 ? row.row.slice(0, 99) + "…" : row.row,
+            });
+        }
+    }
+    const decisionsReport = {
+        total: decisions.length,
+        migrated: decisionMigrated,
+        unmigrated: decisions.length - decisionMigrated,
+        samples: decisionSamples,
+    };
+    const knowledgeReport = {
+        total: knowledgeRows.length,
+        migrated: knowledgeMigrated,
+        unmigrated: knowledgeRows.length - knowledgeMigrated,
+        byTable: knowledgeByTable,
+        samples: knowledgeSamples,
+    };
+    const totalGaps = decisionsReport.unmigrated + knowledgeReport.unmigrated;
+    // Summary line is intentionally short so it fits in a single notification
+    // (notification-store truncates messages over 500 chars). Detail is
+    // accessible via getProviderSwitchStats-style callers, not embedded here.
+    const parts = [];
+    if (decisionsReport.unmigrated > 0) {
+        parts.push(`${decisionsReport.unmigrated} of ${decisionsReport.total} active decisions`);
+    }
+    if (knowledgeReport.unmigrated > 0) {
+        parts.push(`${knowledgeReport.unmigrated} of ${knowledgeReport.total} KNOWLEDGE.md rows`);
+    }
+    const summary = parts.length === 0
+        ? "Memory consolidation: all decisions and KNOWLEDGE.md rows are in memories."
+        : `Memory consolidation: ${parts.join(" and ")} not yet in memories table. Run /doctor for details.`;
+    return { decisions: decisionsReport, knowledge: knowledgeReport, totalGaps, summary };
+}
+/**
+ * Run the scanner and emit a persistent notification + workflow-logger
+ * warning when gaps exist. Best-effort: never throws; a broken scanner
+ * cannot block agent startup.
+ *
+ * Returns the full {@link ConsolidationGapReport} regardless of whether gaps
+ * exist (including when `totalGaps === 0`). Returns `null` only when
+ * `scanConsolidationGaps` itself throws. `appendNotification` and
+ * `logWarning` are called only when `report.totalGaps > 0`.
+ *
+ * Idempotent at the surface: the notification store applies its own
+ * 30-second dedup window keyed on (severity, source, message), so repeated
+ * boots with identical gaps produce one notification, not a flood.
+ */
+export function reportConsolidationGaps(basePath) {
+    try {
+        const report = scanConsolidationGaps(basePath);
+        if (report.totalGaps === 0)
+            return report;
+        appendNotification(report.summary, "warning", "workflow-logger");
+        logWarning("memory-consolidation", report.summary);
+        return report;
+    }
+    catch (e) {
+        logWarning("memory-consolidation", `scanner failed: ${e.message}`);
+        return null;
+    }
+}

package/dist/resources/extensions/gsd/native-git-bridge.js

@@ -551,21 +551,21 @@ export function nativeAddAll(basePath) {
 export function nativeAddTracked(basePath) {
     gitFileExec(basePath, ["add", "-u"]);
 }
-function isDotGsdIgnored(basePath) {
-    for (const path of [".gsd", ".gsd/"]) {
-        try {
-            execFileSync("git", ["check-ignore", "-q", path], {
-                cwd: basePath,
-                stdio: "pipe",
-                env: GIT_NO_PROMPT_ENV,
-            });
-            return true;
-        }
-        catch {
-            // exit 1 means this form is not ignored; try the next variant
-        }
+export function nativeIsIgnored(basePath, path) {
+    try {
+        execFileSync("git", ["check-ignore", "-q", "--", path], {
+            cwd: basePath,
+            stdio: "pipe",
+            env: GIT_NO_PROMPT_ENV,
+        });
+        return true;
+    }
+    catch {
+        return false;
     }
-    return false;
+}
+function isDotGsdIgnored(basePath) {
+    return [".gsd", ".gsd/"].some(path => nativeIsIgnored(basePath, path));
 }
 /**
  * Determine whether the project opts out of GSD-managed `.gitignore` via

package/dist/resources/extensions/gsd/notification-overlay.js

@@ -1,11 +1,25 @@
-// GSD Extension — Notification History Overlay
-// Scrollable panel showing all persisted notifications with severity filtering.
-// Toggled with Ctrl+Alt+N (⌃⌥N on macOS), Ctrl+Shift+N fallback, or /gsd notifications.
-import { truncateToWidth, visibleWidth, wrapTextWithAnsi, matchesKey, Key } from "@gsd/pi-tui";
+// Project/App: GSD-2
+// File Purpose: Notification history overlay with severity filtering and width-safe TUI rendering.
+import { truncateToWidth, visibleWidth, matchesKey, Key } from "@gsd/pi-tui";
 import { readNotifications, markAllRead, clearNotifications, onNotificationStoreChange, } from "./notification-store.js";
 import { formattedShortcutPair } from "./shortcut-defs.js";
-import { padRight, joinColumns } from "../shared/mod.js";
-const FILTER_CYCLE = ["all", "error", "warning", "info"];
+import { padRightVisible, renderFrame, renderKeyHints, rightAlign, wrapVisibleText, } from "./tui/render-kit.js";
+const FILTER_CYCLE = ["all", "error", "warning", "success", "info"];
+const OVERLAY_WIDTH = "58%";
+const OVERLAY_MIN_WIDTH = 68;
+const OVERLAY_MAX_HEIGHT_PERCENT = 52;
+const OVERLAY_MARGIN = { top: 2, right: 2, bottom: 6, left: 2 };
+export function notificationOverlayOptions() {
+    return {
+        width: OVERLAY_WIDTH,
+        minWidth: OVERLAY_MIN_WIDTH,
+        maxHeight: `${OVERLAY_MAX_HEIGHT_PERCENT}%`,
+        anchor: "top-center",
+        row: "24%",
+        margin: OVERLAY_MARGIN,
+        backdrop: true,
+    };
+}
 function severityIcon(severity) {
     switch (severity) {
         case "error": return "✗";
@@ -15,15 +29,6 @@ function severityIcon(severity) {
         default: return "●";
     }
 }
-/** Column-aware word wrap using pi-tui's native wrapper (handles unicode/ANSI). */
-function wrapText(text, maxWidth) {
-    if (maxWidth <= 0)
-        return [text];
-    const lines = wrapTextWithAnsi(text, maxWidth);
-    // Safety clamp: if any line still exceeds maxWidth (e.g. unbreakable long token),
-    // truncate it with an ellipsis so it cannot bleed past the box border.
-    return lines.map((l) => visibleWidth(l) > maxWidth ? truncateToWidth(l, maxWidth, "…") : l);
-}
 function formatTimestamp(ts) {
     try {
         const d = new Date(ts);
@@ -155,12 +160,15 @@ export class GSDNotificationOverlay {
             return this.cachedLines;
         }
         const content = this.buildContentLines(width);
-        const maxVisibleRows = Math.max(5, process.stdout.rows ? process.stdout.rows - 8 : 24) - 2;
+        const terminalRows = process.stdout.rows || 32;
+        const availableRows = Math.max(1, terminalRows - OVERLAY_MARGIN.top - OVERLAY_MARGIN.bottom);
+        const overlayRows = Math.min(availableRows, Math.max(1, Math.floor((terminalRows * OVERLAY_MAX_HEIGHT_PERCENT) / 100)));
+        const maxVisibleRows = Math.max(5, overlayRows - 2);
         const visibleContentRows = Math.min(content.length, maxVisibleRows);
         const maxScroll = Math.max(0, content.length - visibleContentRows);
         this.scrollOffset = Math.min(this.scrollOffset, maxScroll);
         const visibleContent = content.slice(this.scrollOffset, this.scrollOffset + visibleContentRows);
-        const lines = this.wrapInBox(visibleContent, width);
+        const lines = renderFrame(this.theme, visibleContent, width);
         this.cachedWidth = width;
         this.cachedLines = lines;
         return lines;
@@ -192,30 +200,14 @@ export class GSDNotificationOverlay {
             this.tui.requestRender();
         }
     }
-    wrapInBox(inner, width) {
-        const th = this.theme;
-        const border = (s) => th.fg("borderAccent", s);
-        const innerWidth = width - 4;
-        const lines = [];
-        lines.push(border("╭" + "─".repeat(width - 2) + "╮"));
-        for (const line of inner) {
-            const truncated = truncateToWidth(line, innerWidth);
-            const padWidth = Math.max(0, innerWidth - visibleWidth(truncated));
-            lines.push(border("│") + " " + truncated + " ".repeat(padWidth) + " " + border("│"));
-        }
-        lines.push(border("╰" + "─".repeat(width - 2) + "╯"));
-        return lines;
-    }
     buildContentLines(width) {
         const th = this.theme;
-        const shellWidth = width - 4;
-        const contentWidth = Math.min(shellWidth, 128);
-        const sidePad = Math.max(0, Math.floor((shellWidth - contentWidth) / 2));
-        const leftMargin = " ".repeat(sidePad);
+        const shellWidth = Math.max(1, width - 4);
+        const contentWidth = shellWidth;
         const lines = [];
         const row = (content = "") => {
             const truncated = truncateToWidth(content, contentWidth);
-            return leftMargin + padRight(truncated, contentWidth);
+            return padRightVisible(truncated, contentWidth);
         };
         const blank = () => row("");
         const hr = () => row(th.fg("dim", "─".repeat(contentWidth)));
@@ -223,13 +215,16 @@ export class GSDNotificationOverlay {
         const title = th.fg("accent", th.bold("Notifications"));
         const filterLabel = this.filter === "all"
             ? th.fg("dim", "all")
-            : th.fg(this.filter === "error" ? "error" : this.filter === "warning" ? "warning" : "dim", this.filter);
+            : th.fg(this.filter === "error" ? "error"
+                : this.filter === "warning" ? "warning"
+                    : this.filter === "success" ? "success"
+                        : "dim", this.filter);
         const count = `${this.filteredEntries.length} entries`;
-        lines.push(row(joinColumns(`${title}  ${th.fg("dim", "filter:")} ${filterLabel}`, th.fg("dim", count), contentWidth)));
+        lines.push(row(rightAlign(`${title}  ${th.fg("dim", "filter:")} ${filterLabel}`, th.fg("dim", count), contentWidth)));
         lines.push(hr());
         // Controls
         const closeShortcut = formattedShortcutPair("notifications");
-        lines.push(row(th.fg("dim", `↑/↓ scroll  f filter  c clear  Esc close  (${closeShortcut})`)));
+        lines.push(row(renderKeyHints(th, ["↑/↓ scroll", "f filter", "c clear", `Esc/${closeShortcut} close`], contentWidth)));
         lines.push(blank());
         // Entries
         const filtered = this.filteredEntries;
@@ -254,7 +249,7 @@ export class GSDNotificationOverlay {
             const prefixWidth = visibleWidth(prefix);
             const msgMaxWidth = Math.max(10, contentWidth - prefixWidth);
             // Wrap long messages onto continuation lines indented to align with message start
-            const msgLines = wrapText(entry.message, msgMaxWidth);
+            const msgLines = wrapVisibleText(entry.message, msgMaxWidth);
             const indent = " ".repeat(prefixWidth);
             for (let i = 0; i < msgLines.length; i++) {
                 if (i === 0) {

package/dist/resources/extensions/gsd/parallel-merge.js

@@ -7,9 +7,10 @@
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
-import { loadFile } from "./files.js";
-import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
-import { mergeMilestoneToMain } from "./auto-worktree.js";
+import { resolveGsdPathContract } from "./paths.js";
+import { getAutoWorktreePath } from "./auto-worktree.js";
+import { buildWorktreeLifecycleDeps } from "./auto.js";
+import { mergeMilestoneStandalone, } from "./worktree-lifecycle.js";
 import { MergeConflictError } from "./git-service.js";
 import { removeSessionStatus } from "./session-status-io.js";
 import { getErrorMessage } from "./error-utils.js";
@@ -105,37 +106,42 @@ export function determineMergeOrder(workers, order = "sequential", basePath) {
 }
 /**
  * Attempt to merge a single milestone's worktree back to main.
- * Wraps mergeMilestoneToMain with error handling for parallel context.
+ *
+ * Routes through `WorktreeLifecycle.mergeMilestoneStandalone` so parallel
+ * callers get the same projection-finalize / roadmap-fallback / secondary-
+ * teardown invariants as the single-loop path. Closes the parallel-merge
+ * bypass that ADR-016 names (issue #5618).
  */
 export async function mergeCompletedMilestone(basePath, milestoneId) {
+    // Resolve the worktree path explicitly; parallel-merge has no AutoSession
+    // to read it from. Only use the worktree path when git actually knows
+    // about it (`getAutoWorktreePath` returns non-null). When the directory
+    // exists on disk but isn't a registered git worktree (e.g. a stale
+    // session-status marker dir), fall back to the project root and let the
+    // standalone's mode detection pick branch-mode or skipped — using the
+    // un-registered dir as `worktreeBasePath` would cause `getCurrentBranch`
+    // to fail with a "Worktree HEAD diverged" error.
+    const registeredWtPath = getAutoWorktreePath(basePath, milestoneId);
+    const worktreeBasePath = registeredWtPath ?? basePath;
+    let result;
     try {
-        // Load the roadmap content (needed by mergeMilestoneToMain)
-        const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-        if (!roadmapPath) {
-            return {
-                milestoneId,
-                success: false,
-                error: `No roadmap found for ${milestoneId}`,
-            };
-        }
-        const roadmapContent = await loadFile(roadmapPath);
-        if (!roadmapContent) {
-            return {
-                milestoneId,
-                success: false,
-                error: `Could not read roadmap for ${milestoneId}`,
-            };
-        }
-        // Attempt the merge
-        const result = mergeMilestoneToMain(basePath, milestoneId, roadmapContent);
-        // Clean up parallel session status
-        removeSessionStatus(basePath, milestoneId);
-        return {
+        result = mergeMilestoneStandalone(buildWorktreeLifecycleDeps(), {
+            originalBasePath: basePath,
+            worktreeBasePath,
             milestoneId,
-            success: true,
-            commitMessage: result.commitMessage,
-            pushed: result.pushed,
-        };
+            // Parallel context never runs with degraded isolation — workers only
+            // exist when isolation succeeded. Pass `false` explicitly so the
+            // standalone's degraded-skip branch is not reached.
+            isolationDegraded: false,
+            notify: (msg, level) => {
+                // Surface user-visible messages from the standalone through the
+                // workflow logger so the parallel merge's progress is visible in
+                // the same channel as the rest of the parallel orchestration.
+                if (level === "error" || level === "warning") {
+                    logWarning("parallel", `${milestoneId}: ${msg}`);
+                }
+            },
+        });
     }
     catch (err) {
         if (err instanceof MergeConflictError) {
@@ -152,6 +158,23 @@ export async function mergeCompletedMilestone(basePath, milestoneId) {
             error: getErrorMessage(err),
         };
     }
+    if (!result.merged) {
+        return {
+            milestoneId,
+            success: false,
+            error: result.mode === "skipped"
+                ? `Merge skipped for ${milestoneId} (mode=none or isolation degraded).`
+                : `No roadmap for ${milestoneId} — milestone branch preserved for manual merge.`,
+        };
+    }
+    // Clean up parallel session status — only on a real merge.
+    removeSessionStatus(basePath, milestoneId);
+    return {
+        milestoneId,
+        success: true,
+        commitMessage: result.commitMessage,
+        pushed: result.pushed,
+    };
 }
 /**
  * Merge all completed milestones in sequence.