gsd-pi 2.74.0 → 2.75.0-dev.2203010a0

package/dist/resources/extensions/gsd/guided-flow.js

@@ -26,6 +26,8 @@ import { nativeIsRepo, nativeInit } from "./native-git-bridge.js";
 import { isInheritedRepo } from "./repo-identity.js";
 import { ensureGitignore, ensurePreferences, untrackRuntimeFiles } from "./gitignore.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { resolveUokFlags } from "./uok/flags.js";
+import { ensurePlanV2Graph } from "./uok/plan-v2.js";
 import { detectProjectState } from "./detection.js";
 import { showProjectInit, offerMigration } from "./init-wizard.js";
 import { validateDirectory } from "./validate-directory.js";
@@ -53,6 +55,25 @@ function nextMilestoneIdReserved(existingIds, uniqueEnabled) {
     reserveMilestoneId(id);
     return id;
 }
+function needsPlanV2Gate(state) {
+    return state.phase === "executing"
+        || state.phase === "summarizing"
+        || state.phase === "validating-milestone"
+        || state.phase === "completing-milestone";
+}
+function runPlanV2Gate(ctx, basePath, state) {
+    const prefs = loadEffectiveGSDPreferences()?.preferences;
+    const uokFlags = resolveUokFlags(prefs);
+    if (!uokFlags.planV2 || !needsPlanV2Gate(state))
+        return true;
+    const compiled = ensurePlanV2Graph(basePath, state);
+    if (!compiled.ok) {
+        const reason = compiled.reason ?? "plan-v2 compilation failed";
+        ctx.ui.notify(`Plan gate failed-closed: ${reason}. Complete plan/discuss artifacts before execution.`, "error");
+        return false;
+    }
+    return true;
+}
 // ─── Commit Instruction Helpers ──────────────────────────────────────────────
 /** Build commit instruction for planning prompts. .gsd/ is managed externally and always gitignored. */
 function buildDocsCommitInstruction(_message) {
@@ -191,14 +212,16 @@ export function checkAutoStartAfterDiscuss() {
         logWarning("guided", `CONTEXT-DRAFT.md unlink failed: ${e.message}`);
     }
     // Cleanup: remove discussion manifest after auto-start (only needed during discussion)
-    try {
-        unlinkSync(manifestPath);
-    }
-    catch (e) {
-        logWarning("guided", `manifest unlink failed: ${e.message}`);
+    if (existsSync(manifestPath)) {
+        try {
+            unlinkSync(manifestPath);
+        }
+        catch (e) {
+            logWarning("guided", `manifest unlink failed: ${e.message}`);
+        }
     }
     pendingAutoStartMap.delete(basePath);
-    ctx.ui.notify(`Milestone ${milestoneId} ready.`, "info");
+    ctx.ui.notify(`Milestone ${milestoneId} ready.`, "success");
     startAutoDetached(ctx, pi, basePath, false, { step });
     return true;
 }
@@ -1110,6 +1133,8 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     catch (err) {
         logWarning("guided", `STATE.md rebuild failed: ${err.message}`);
     }
+    if (!runPlanV2Gate(ctx, basePath, state))
+        return;
     if (!state.activeMilestone?.id) {
         // Guard: if a discuss session is already in flight, don't re-inject the prompt.
         // Both /gsd and /gsd auto reach this branch when no milestone exists yet.

package/dist/resources/extensions/gsd/health-widget-core.js

@@ -43,47 +43,75 @@ function truncateMessage(msg, maxLen) {
 }
 /**
  * Build compact health lines for the widget.
- * Returns a string array suitable for setWidget().
+ * When `width` is provided, system + budget render left and last-commit
+ * right-aligned. Without width, all parts are joined inline (RPC fallback).
  */
-export function buildHealthLines(data) {
+export function buildHealthLines(data, width) {
     if (data.projectState === "none") {
         return ["  GSD  No project loaded — run /gsd to start"];
     }
     if (data.projectState === "initialized") {
         return ["  GSD  Project initialized — run /gsd to continue setup"];
     }
-    const parts = [];
+    const leftParts = [];
     const totalIssues = data.environmentErrorCount + data.environmentWarningCount + (data.providerIssue ? 1 : 0);
     if (totalIssues === 0) {
-        parts.push("● System OK");
+        leftParts.push("● System OK");
     }
     else if (data.environmentErrorCount > 0 || data.providerIssue?.includes("✗")) {
-        parts.push(`✗ ${totalIssues} issue${totalIssues > 1 ? "s" : ""}`);
+        leftParts.push(`✗ ${totalIssues} issue${totalIssues > 1 ? "s" : ""}`);
     }
     else {
-        parts.push(`⚠ ${totalIssues} warning${totalIssues > 1 ? "s" : ""}`);
+        leftParts.push(`⚠ ${totalIssues} warning${totalIssues > 1 ? "s" : ""}`);
     }
     if (data.budgetCeiling !== undefined && data.budgetCeiling > 0) {
         const pct = Math.min(100, (data.budgetSpent / data.budgetCeiling) * 100);
-        parts.push(`Budget: ${formatCost(data.budgetSpent)}/${formatCost(data.budgetCeiling)} (${pct.toFixed(0)}%)`);
+        leftParts.push(`Budget: ${formatCost(data.budgetSpent)}/${formatCost(data.budgetCeiling)} (${pct.toFixed(0)}%)`);
     }
     else if (data.budgetSpent > 0) {
-        parts.push(`Spent: ${formatCost(data.budgetSpent)}`);
+        leftParts.push(`Spent: ${formatCost(data.budgetSpent)}`);
     }
     if (data.providerIssue) {
-        parts.push(data.providerIssue);
+        leftParts.push(data.providerIssue);
     }
     if (data.environmentErrorCount > 0) {
-        parts.push(`Env: ${data.environmentErrorCount} error${data.environmentErrorCount > 1 ? "s" : ""}`);
+        leftParts.push(`Env: ${data.environmentErrorCount} error${data.environmentErrorCount > 1 ? "s" : ""}`);
     }
     else if (data.environmentWarningCount > 0) {
-        parts.push(`Env: ${data.environmentWarningCount} warning${data.environmentWarningCount > 1 ? "s" : ""}`);
+        leftParts.push(`Env: ${data.environmentWarningCount} warning${data.environmentWarningCount > 1 ? "s" : ""}`);
     }
-    // Always-on last commit display — shows relative time + truncated message
+    // Last commit goes on the right-hand side when width is known.
+    let rightText = "";
     if (data.lastCommitEpoch !== null && data.lastCommitEpoch > 0) {
         const relTime = formatRelativeTime(data.lastCommitEpoch);
         const msg = data.lastCommitMessage ? ` — ${truncateMessage(data.lastCommitMessage, 50)}` : "";
-        parts.push(`Last commit: ${relTime}${msg}`);
+        rightText = `Last commit: ${relTime}${msg}`;
     }
-    return [`  ${parts.join("  │  ")}`];
+    const leftText = leftParts.join("  │  ");
+    if (width === undefined) {
+        const inline = rightText ? `${leftText}  │  ${rightText}` : leftText;
+        return [`  ${inline}`];
+    }
+    const prefix = "  ";
+    const innerWidth = Math.max(0, width - prefix.length);
+    const leftVis = leftText.length;
+    const rightVis = rightText.length;
+    if (!rightText)
+        return [`${prefix}${truncateMessage(leftText, innerWidth)}`];
+    const MIN_GAP = 2;
+    if (leftVis + MIN_GAP + rightVis > innerWidth) {
+        // Preserve the left (status + budget) and truncate the right side
+        // (last commit) with an ellipsis so the combined line never exceeds
+        // innerWidth. If even the left alone overflows, clamp it too.
+        const leftRoom = Math.max(1, Math.min(leftVis, innerWidth - MIN_GAP - 1));
+        const clampedLeft = truncateMessage(leftText, leftRoom);
+        const rightRoom = Math.max(0, innerWidth - clampedLeft.length - MIN_GAP);
+        const clampedRight = rightRoom > 0 ? truncateMessage(rightText, rightRoom) : "";
+        if (!clampedRight)
+            return [`${prefix}${clampedLeft}`];
+        const pad = " ".repeat(Math.max(MIN_GAP, innerWidth - clampedLeft.length - clampedRight.length));
+        return [`${prefix}${clampedLeft}${pad}${clampedRight}`];
+    }
+    const padding = " ".repeat(innerWidth - leftVis - rightVis);
+    return [`${prefix}${leftText}${padding}${rightText}`];
 }

package/dist/resources/extensions/gsd/health-widget.js

@@ -111,13 +111,16 @@ export function initHealthWidget(ctx) {
         const refreshTimer = setInterval(() => {
             void refresh();
         }, REFRESH_INTERVAL_MS);
+        let cachedWidth;
         return {
-            render(_width) {
-                if (!cachedLines)
-                    cachedLines = buildHealthLines(data);
+            render(width) {
+                if (!cachedLines || cachedWidth !== width) {
+                    cachedLines = buildHealthLines(data, width);
+                    cachedWidth = width;
+                }
                 return cachedLines;
             },
-            invalidate() { cachedLines = undefined; },
+            invalidate() { cachedLines = undefined; cachedWidth = undefined; },
             dispose() {
                 clearInterval(refreshTimer);
             },

package/dist/resources/extensions/gsd/index.js

@@ -1,5 +1,18 @@
 export { isDepthConfirmationAnswer, isDepthVerified, isGateQuestionId, isQueuePhaseActive, setQueuePhaseActive, shouldBlockContextWrite, shouldBlockPendingGate, shouldBlockPendingGateBash, shouldBlockQueueExecution, setPendingGate, clearPendingGate, getPendingGate, } from "./bootstrap/write-gate.js";
 export default async function registerExtension(pi) {
-    const { registerGsdExtension } = await import("./bootstrap/register-extension.js");
-    registerGsdExtension(pi);
+    // Always register the core /gsd command first, in isolation.
+    // This ensures /gsd is available even if the full bootstrap (shortcuts,
+    // tools, hooks) fails — e.g. due to a Windows-specific import error.
+    const { registerGSDCommand } = await import("./commands/index.js");
+    registerGSDCommand(pi);
+    // Full setup (shortcuts, tools, hooks) in a separate try/catch so that
+    // any platform-specific load failure doesn't take out the core command.
+    try {
+        const { registerGsdExtension } = await import("./bootstrap/register-extension.js");
+        registerGsdExtension(pi);
+    }
+    catch (err) {
+        const { logWarning } = await import("./workflow-logger.js");
+        logWarning("bootstrap", `Extension setup partially failed — /gsd commands are available but shortcuts/tools may be missing: ${err instanceof Error ? err.message : String(err)}`);
+    }
 }

package/dist/resources/extensions/gsd/init-wizard.js

@@ -14,6 +14,7 @@ import { gsdRoot } from "./paths.js";
 import { assertSafeDirectory } from "./validate-directory.js";
 import { runSkillInstallStep } from "./skill-catalog.js";
 import { generateCodebaseMap, writeCodebaseMap } from "./codebase-generator.js";
+import { handlePrefsWizard, writePreferencesFile } from "./commands-prefs-wizard.js";
 // ─── Defaults ───────────────────────────────────────────────────────────────────
 const DEFAULT_PREFS = {
     mode: "solo",
@@ -185,8 +186,51 @@ export async function showProjectInit(ctx, pi, basePath, detection) {
     catch {
         // Non-fatal — skill installation failure should never block project init
     }
-    // ── Step 9: Bootstrap .gsd/ ────────────────────────────────────────────────
-    bootstrapGsdDirectory(basePath, prefs, signals);
+    // ── Step 9: Optional full-prefs review ─────────────────────────────────────
+    // Ask BEFORE bootstrapping so a defer (`not_yet`) leaves the project untouched.
+    // Once the user commits, we bootstrap and route preferences through the unified
+    // writer (commands-prefs-wizard.writePreferencesFile) so init and the prefs
+    // wizard share one serializer. The "Open full wizard" branch surfaces every
+    // configurable preference, prefilled with the init answers.
+    const reviewChoice = await showNextAction(ctx, {
+        title: "GSD — Review All Preferences (Optional)",
+        summary: [
+            "Open the full preferences wizard now? It includes models, timeouts,",
+            "budget, notifications, and skills — all pre-filled with your answers.",
+            "",
+            "Skip if you just want sensible defaults; you can always run /gsd prefs project later.",
+        ],
+        actions: [
+            { id: "skip", label: "Skip — use defaults", description: "Save preferences and continue", recommended: true },
+            { id: "review", label: "Open full wizard", description: "Tweak any category before saving" },
+        ],
+        notYetMessage: "Run /gsd init when ready.",
+    });
+    if (reviewChoice === "not_yet") {
+        // User deferred — don't create .gsd/ or persist preferences. Pre-step state
+        // (e.g. git init from Step 2) remains as-is, matching prior step semantics.
+        return { completed: false, bootstrapped: false };
+    }
+    // ── Step 10: Bootstrap .gsd/ + write preferences ───────────────────────────
+    bootstrapGsdDirectoryStructure(basePath, signals);
+    const prefillPrefs = mapInitPrefsToWizardShape(prefs);
+    // Always derive the preferences path from basePath so init writing the
+    // structure to one location and preferences to another (cwd-derived) is
+    // impossible — see #4457 codex review.
+    const projectPrefsPath = join(gsdRoot(basePath), "PREFERENCES.md");
+    if (reviewChoice === "review") {
+        // Wizard writes via writePreferencesFile internally; pass pathOverride so it
+        // targets basePath rather than cwd.
+        await handlePrefsWizard(ctx, "project", prefillPrefs, { pathOverride: projectPrefsPath });
+    }
+    else {
+        // Direct path: write the init-collected prefs through the unified writer.
+        await writePreferencesFile(projectPrefsPath, prefillPrefs, ctx, {
+            scope: "project",
+            defaultBody: buildInitPreferencesBody(),
+            notifyOnSave: false,
+        });
+    }
     // Initialize SQLite database so GSD starts in full-capability mode (#3880).
     // Without this, isDbAvailable() returns false and GSD enters degraded
     // markdown-only mode until a tool handler happens to call ensureDbOpen().
@@ -336,6 +380,7 @@ async function customizeAdvancedPrefs(ctx, prefs) {
             { id: "balanced", label: "Balanced", description: "Good trade-off (default)", recommended: true },
             { id: "budget", label: "Budget", description: "Minimize token usage" },
             { id: "quality", label: "Quality", description: "Maximize thoroughness" },
+            { id: "burn-max", label: "Burn Max", description: "Maximum depth, no phase skips" },
         ],
     });
     if (profileChoice !== "not_yet") {
@@ -371,67 +416,64 @@ async function customizeAdvancedPrefs(ctx, prefs) {
     prefs.autoPush = pushChoice !== "no";
 }
 // ─── Bootstrap ──────────────────────────────────────────────────────────────────
-function bootstrapGsdDirectory(basePath, prefs, signals) {
+/**
+ * Create .gsd/ directory structure and seed CONTEXT.md.
+ *
+ * Preferences are written separately by the caller via the unified
+ * writePreferencesFile helper so init and the prefs wizard share one path.
+ */
+function bootstrapGsdDirectoryStructure(basePath, signals) {
     // Final safety check before writing any files
     assertSafeDirectory(basePath);
     const gsd = gsdRoot(basePath);
     mkdirSync(join(gsd, "milestones"), { recursive: true });
     mkdirSync(join(gsd, "runtime"), { recursive: true });
-    // Write PREFERENCES.md from wizard answers
-    const preferencesContent = buildPreferencesFile(prefs);
-    writeFileSync(join(gsd, "PREFERENCES.md"), preferencesContent, "utf-8");
     // Seed CONTEXT.md with detected project signals
     const contextContent = buildContextSeed(signals);
     if (contextContent) {
         writeFileSync(join(gsd, "CONTEXT.md"), contextContent, "utf-8");
     }
 }
-function buildPreferencesFile(prefs) {
-    const lines = ["---"];
-    lines.push("version: 1");
-    lines.push(`mode: ${prefs.mode}`);
-    // Git preferences
-    lines.push("git:");
-    lines.push(`  isolation: ${prefs.gitIsolation}`);
-    lines.push(`  main_branch: ${prefs.mainBranch}`);
-    lines.push(`  auto_push: ${prefs.autoPush}`);
-    // Verification commands
+/**
+ * Map init wizard's typed ProjectPreferences to the prefs-wizard's
+ * Record<string, unknown> shape, matching the keys serializePreferencesToFrontmatter
+ * expects (mode, git.{isolation,main_branch,auto_push}, verification_commands, etc.).
+ *
+ * Exported for testing; init-wizard uses it inline.
+ */
+export function mapInitPrefsToWizardShape(prefs) {
+    const out = {
+        mode: prefs.mode,
+        git: {
+            isolation: prefs.gitIsolation,
+            main_branch: prefs.mainBranch,
+            auto_push: prefs.autoPush,
+        },
+    };
     if (prefs.verificationCommands.length > 0) {
-        lines.push("verification_commands:");
-        for (const cmd of prefs.verificationCommands) {
-            lines.push(`  - "${cmd}"`);
-        }
+        out.verification_commands = prefs.verificationCommands;
     }
-    // Custom instructions
     if (prefs.customInstructions.length > 0) {
-        lines.push("custom_instructions:");
-        for (const inst of prefs.customInstructions) {
-            lines.push(`  - "${inst.replace(/"/g, '\\"')}"`);
-        }
+        out.custom_instructions = prefs.customInstructions;
     }
-    // Token profile (only if non-default)
     if (prefs.tokenProfile !== "balanced") {
-        lines.push(`token_profile: ${prefs.tokenProfile}`);
+        out.token_profile = prefs.tokenProfile;
     }
-    // Phase skips
     if (prefs.skipResearch) {
-        lines.push("phases:");
-        lines.push("  skip_research: true");
-    }
-    // Defaults for wizard-generated files
-    lines.push("always_use_skills: []");
-    lines.push("prefer_skills: []");
-    lines.push("avoid_skills: []");
-    lines.push("skill_rules: []");
-    lines.push("---");
-    lines.push("");
-    lines.push("# GSD Project Preferences");
-    lines.push("");
-    lines.push("Generated by `/gsd init`. Edit directly or use `/gsd prefs project` to modify.");
-    lines.push("");
-    lines.push("See `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation.");
-    lines.push("");
-    return lines.join("\n");
+        out.phases = { skip_research: true };
+    }
+    return out;
+}
+function buildInitPreferencesBody() {
+    return [
+        "",
+        "# GSD Project Preferences",
+        "",
+        "Generated by `/gsd init`. Edit directly or use `/gsd prefs project` to modify.",
+        "",
+        "See `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation.",
+        "",
+    ].join("\n");
 }
 function buildContextSeed(signals) {
     const lines = [];

package/dist/resources/extensions/gsd/journal.js

@@ -14,6 +14,8 @@
 import { appendFileSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
+import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
 // ─── Emit ─────────────────────────────────────────────────────────────────────
 /**
  * Append a journal event to the daily JSONL file.
@@ -34,6 +36,31 @@ export function emitJournalEvent(basePath, entry) {
     catch {
         // Silent failure — journal must never break auto-mode
     }
+    if (!isUnifiedAuditEnabled())
+        return;
+    try {
+        const causedBy = entry.causedBy
+            ? `${entry.causedBy.flowId}:${entry.causedBy.seq}`
+            : undefined;
+        const turnId = typeof entry.data?.turnId === "string"
+            ? entry.data.turnId
+            : undefined;
+        emitUokAuditEvent(basePath, buildAuditEnvelope({
+            traceId: entry.flowId,
+            turnId,
+            causedBy,
+            category: "orchestration",
+            type: `journal-${entry.eventType}`,
+            payload: {
+                seq: entry.seq,
+                rule: entry.rule,
+                data: entry.data ?? {},
+            },
+        }));
+    }
+    catch {
+        // Best-effort: audit projection must never block journal writes.
+    }
 }
 // ─── Query ────────────────────────────────────────────────────────────────────
 /**

package/dist/resources/extensions/gsd/markdown-renderer.js

@@ -115,7 +115,7 @@ function renderRoadmapMarkdown(milestone, slices) {
     lines.push("## Slices");
     lines.push("");
     for (const slice of slices) {
-        const done = slice.status === "complete" ? "x" : " ";
+        const done = isClosedStatus(slice.status) ? "x" : " ";
         const depends = `[${(slice.depends ?? []).join(",")}]`;
         lines.push(`- [${done}] **${slice.id}: ${slice.title}** \`risk:${slice.risk}\` \`depends:${depends}\``);
         lines.push(`  > After this: ${slice.demo}`);
@@ -386,7 +386,7 @@ export async function renderRoadmapCheckboxes(basePath, milestoneId) {
     // Apply checkbox patches for each slice
     let updated = content;
     for (const slice of slices) {
-        const isDone = slice.status === "complete";
+        const isDone = isClosedStatus(slice.status);
         const sid = slice.id;
         if (isDone) {
             // Set [x]: replace "- [ ] **S01:" with "- [x] **S01:"
@@ -631,20 +631,20 @@ export function detectStaleRenders(basePath) {
                 const content = readFileSync(roadmapPath, "utf-8");
                 const parsed = parseRoadmap(content);
                 for (const slice of slices) {
-                    const isCompleteInDb = slice.status === "complete";
+                    const isCompleteInDb = isClosedStatus(slice.status);
                     const roadmapSlice = parsed.slices.find((s) => s.id === slice.id);
                     if (!roadmapSlice)
                         continue;
                     if (isCompleteInDb && !roadmapSlice.done) {
                         stale.push({
                             path: roadmapPath,
-                            reason: `${slice.id} is complete in DB but unchecked in roadmap`,
+                            reason: `${slice.id} is closed in DB but unchecked in roadmap`,
                         });
                     }
                     else if (!isCompleteInDb && roadmapSlice.done) {
                         stale.push({
                             path: roadmapPath,
-                            reason: `${slice.id} is not complete in DB but checked in roadmap`,
+                            reason: `${slice.id} is not closed in DB but checked in roadmap`,
                         });
                     }
                 }

package/dist/resources/extensions/gsd/md-importer.js

@@ -5,7 +5,7 @@
 // Exports: parseDecisionsTable, parseRequirementsSections, migrateFromMarkdown
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { upsertDecision, upsertRequirement, insertArtifact, insertMilestone, insertSlice, insertTask, openDatabase, transaction, _getAdapter, } from './gsd-db.js';
+import { upsertDecision, upsertRequirement, insertArtifact, insertMilestone, insertSlice, insertTask, openDatabase, transaction, updateSliceStatus, _getAdapter, } from './gsd-db.js';
 import { resolveGsdRootFile, resolveMilestoneFile, resolveSliceFile, resolveTasksDir, milestonesDir, gsdRoot, resolveTaskFiles, } from './paths.js';
 import { findMilestoneIds } from './guided-flow.js';
 import { parseRoadmap, parsePlan } from './parsers-legacy.js';
@@ -571,9 +571,8 @@ export function migrateHierarchyToDb(basePath) {
                     return t.done && existsSync(summaryFile);
                 });
                 if (allTasksDone && hasSliceSummary) {
-                    const adapter = _getAdapter();
-                    if (adapter) {
-                        adapter.prepare(`UPDATE slices SET status = 'complete' WHERE id = :sid AND milestone_id = :mid`).run({ ':sid': sliceEntry.id, ':mid': milestoneId });
+                    if (_getAdapter()) {
+                        updateSliceStatus(milestoneId, sliceEntry.id, 'complete');
                         process.stderr.write(`gsd-migrate: ${milestoneId}/${sliceEntry.id} all tasks + slice summary complete — upgrading slice to complete\n`);
                     }
                 }

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

@@ -2,7 +2,7 @@
 //
 // Storage layer for auto-learned project memories. Follows context-store.ts patterns.
 // All functions degrade gracefully: return empty results when DB unavailable, never throw.
-import { isDbAvailable, _getAdapter, transaction } from './gsd-db.js';
+import { isDbAvailable, _getAdapter, transaction, insertMemoryRow, rewriteMemoryId, updateMemoryContentRow, incrementMemoryHitCount, supersedeMemoryRow, markMemoryUnitProcessed, decayMemoriesBefore, supersedeLowestRankedMemories, } from './gsd-db.js';
 // ─── Category Display Order ─────────────────────────────────────────────────
 const CATEGORY_PRIORITY = {
     gotcha: 0,
@@ -112,27 +112,23 @@ export function createMemory(fields) {
         const now = new Date().toISOString();
         // Insert with a temporary placeholder ID — seq is auto-assigned
         const placeholder = `_TMP_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
-        adapter.prepare(`INSERT INTO memories (id, category, content, confidence, source_unit_type, source_unit_id, created_at, updated_at)
-       VALUES (:id, :category, :content, :confidence, :source_unit_type, :source_unit_id, :created_at, :updated_at)`).run({
-            ':id': placeholder,
-            ':category': fields.category,
-            ':content': fields.content,
-            ':confidence': fields.confidence ?? 0.8,
-            ':source_unit_type': fields.source_unit_type ?? null,
-            ':source_unit_id': fields.source_unit_id ?? null,
-            ':created_at': now,
-            ':updated_at': now,
+        insertMemoryRow({
+            id: placeholder,
+            category: fields.category,
+            content: fields.content,
+            confidence: fields.confidence ?? 0.8,
+            sourceUnitType: fields.source_unit_type ?? null,
+            sourceUnitId: fields.source_unit_id ?? null,
+            createdAt: now,
+            updatedAt: now,
         });
-        // Derive the real ID from the assigned seq
+        // Derive the real ID from the assigned seq (SELECT is still fine via adapter)
         const row = adapter.prepare('SELECT seq FROM memories WHERE id = :id').get({ ':id': placeholder });
         if (!row)
             return placeholder; // fallback — should not happen
         const seq = row['seq'];
         const realId = `MEM${String(seq).padStart(3, '0')}`;
-        adapter.prepare('UPDATE memories SET id = :real_id WHERE id = :placeholder').run({
-            ':real_id': realId,
-            ':placeholder': placeholder,
-        });
+        rewriteMemoryId(placeholder, realId);
         return realId;
     }
     catch {
@@ -145,17 +141,8 @@ export function createMemory(fields) {
 export function updateMemoryContent(id, content, confidence) {
     if (!isDbAvailable())
         return false;
-    const adapter = _getAdapter();
-    if (!adapter)
-        return false;
     try {
-        const now = new Date().toISOString();
-        if (confidence != null) {
-            adapter.prepare('UPDATE memories SET content = :content, confidence = :confidence, updated_at = :updated_at WHERE id = :id').run({ ':content': content, ':confidence': confidence, ':updated_at': now, ':id': id });
-        }
-        else {
-            adapter.prepare('UPDATE memories SET content = :content, updated_at = :updated_at WHERE id = :id').run({ ':content': content, ':updated_at': now, ':id': id });
-        }
+        updateMemoryContentRow(id, content, confidence, new Date().toISOString());
         return true;
     }
     catch {
@@ -168,11 +155,8 @@ export function updateMemoryContent(id, content, confidence) {
 export function reinforceMemory(id) {
     if (!isDbAvailable())
         return false;
-    const adapter = _getAdapter();
-    if (!adapter)
-        return false;
     try {
-        adapter.prepare('UPDATE memories SET hit_count = hit_count + 1, updated_at = :updated_at WHERE id = :id').run({ ':updated_at': new Date().toISOString(), ':id': id });
+        incrementMemoryHitCount(id, new Date().toISOString());
         return true;
     }
     catch {
@@ -185,11 +169,8 @@ export function reinforceMemory(id) {
 export function supersedeMemory(oldId, newId) {
     if (!isDbAvailable())
         return false;
-    const adapter = _getAdapter();
-    if (!adapter)
-        return false;
     try {
-        adapter.prepare('UPDATE memories SET superseded_by = :new_id, updated_at = :updated_at WHERE id = :old_id').run({ ':new_id': newId, ':updated_at': new Date().toISOString(), ':old_id': oldId });
+        supersedeMemoryRow(oldId, newId, new Date().toISOString());
         return true;
     }
     catch {
@@ -220,12 +201,8 @@ export function isUnitProcessed(unitKey) {
 export function markUnitProcessed(unitKey, activityFile) {
     if (!isDbAvailable())
         return false;
-    const adapter = _getAdapter();
-    if (!adapter)
-        return false;
     try {
-        adapter.prepare(`INSERT OR IGNORE INTO memory_processed_units (unit_key, activity_file, processed_at)
-       VALUES (:key, :file, :at)`).run({ ':key': unitKey, ':file': activityFile, ':at': new Date().toISOString() });
+        markMemoryUnitProcessed(unitKey, activityFile, new Date().toISOString());
         return true;
     }
     catch {
@@ -244,16 +221,14 @@ export function decayStaleMemories(thresholdUnits = 20) {
     if (!adapter)
         return;
     try {
-        // Find the timestamp of the Nth most recent processed unit
+        // Find the timestamp of the Nth most recent processed unit (read-only SELECT)
         const row = adapter.prepare(`SELECT processed_at FROM memory_processed_units
        ORDER BY processed_at DESC
        LIMIT 1 OFFSET :offset`).get({ ':offset': thresholdUnits - 1 });
         if (!row)
             return; // not enough processed units yet
         const cutoff = row['processed_at'];
-        adapter.prepare(`UPDATE memories
-       SET confidence = MAX(0.1, confidence - 0.1), updated_at = :now
-       WHERE superseded_by IS NULL AND updated_at < :cutoff AND confidence > 0.1`).run({ ':now': new Date().toISOString(), ':cutoff': cutoff });
+        decayMemoriesBefore(cutoff, new Date().toISOString());
     }
     catch {
         // non-fatal
@@ -274,14 +249,7 @@ export function enforceMemoryCap(max = 50) {
         if (count <= max)
             return;
         const excess = count - max;
-        // Batch update: supersede lowest-ranked active memories in a single statement
-        adapter.prepare(`UPDATE memories SET superseded_by = 'CAP_EXCEEDED', updated_at = :now
-       WHERE id IN (
-         SELECT id FROM memories
-         WHERE superseded_by IS NULL
-         ORDER BY (confidence * (1.0 + hit_count * 0.1)) ASC
-         LIMIT :limit
-       )`).run({ ':now': new Date().toISOString(), ':limit': excess });
+        supersedeLowestRankedMemories(excess, new Date().toISOString());
     }
     catch {
         // non-fatal