gsd-pi 2.81.0 → 2.82.0-dev.ed17d078d

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/migrate/command.js

@@ -21,6 +21,9 @@ import { migrateFromMarkdown } from "../md-importer.js";
 import { invalidateStateCache } from "../state.js";
 function assertMigrationImportMatchesPreview(imported, preview) {
     const mismatches = [];
+    if (imported.decisions !== preview.decisions.total) {
+        mismatches.push(`decisions ${imported.decisions}/${preview.decisions.total}`);
+    }
     if (imported.hierarchy.milestones !== preview.milestoneCount) {
         mismatches.push(`milestones ${imported.hierarchy.milestones}/${preview.milestoneCount}`);
     }
@@ -55,6 +58,7 @@ export async function importWrittenMigrationToDb(basePath, preview) {
 /** Format preview stats for embedding in the review prompt. */
 function formatPreviewStats(preview) {
     const lines = [
+        `- Decisions: ${preview.decisions.total}`,
         `- Milestones: ${preview.milestoneCount}`,
         `- Slices: ${preview.totalSlices} (${preview.doneSlices} done — ${preview.sliceCompletionPct}%)`,
         `- Tasks: ${preview.totalTasks} (${preview.doneTasks} done — ${preview.taskCompletionPct}%)`,
@@ -124,6 +128,7 @@ export async function handleMigrate(args, ctx, pi) {
     const preview = generatePreview(project);
     // ── Build preview text ─────────────────────────────────────────────────────
     const lines = [
+        `Decisions: ${preview.decisions.total}`,
         `Milestones: ${preview.milestoneCount}`,
         `Slices: ${preview.totalSlices} (${preview.doneSlices} done — ${preview.sliceCompletionPct}%)`,
         `Tasks: ${preview.totalTasks} (${preview.doneTasks} done — ${preview.taskCompletionPct}%)`,

package/dist/resources/extensions/gsd/migrate/preview.js

@@ -1,5 +1,11 @@
 // GSD Migration Preview — Pre-write statistics
 // Pure function, no I/O. Computes counts from a GSDProject.
+function countCanonicalDecisionRows(content) {
+    return content
+        .split('\n')
+        .filter((line) => /^\|\s*D\d+\s*\|/.test(line.trim()))
+        .length;
+}
 /**
  * Compute pre-write statistics from a GSDProject without performing I/O.
  * Used to show the user what a migration will produce before writing anything.
@@ -35,6 +41,9 @@ export function generatePreview(project) {
         reqCounts.total++;
     }
     return {
+        decisions: {
+            total: countCanonicalDecisionRows(project.decisionsContent),
+        },
         milestoneCount: project.milestones.length,
         totalSlices,
         totalTasks,

package/dist/resources/extensions/gsd/migrate/transformer.js

@@ -187,16 +187,48 @@ function normalizeStatus(status) {
         return 'validated';
     return 'active';
 }
+function normalizeRequirementId(id) {
+    const match = id.trim().match(/^R(\d+)$/i);
+    if (!match)
+        return null;
+    return `R${match[1].padStart(3, '0')}`;
+}
 function mapRequirements(reqs) {
     let autoId = 0;
+    const reservedIds = new Set(reqs
+        .map((req) => normalizeRequirementId(req.id))
+        .filter((id) => id !== null));
+    const usedIds = new Set();
+    function nextRequirementId() {
+        let id = '';
+        do {
+            autoId++;
+            id = padId('R', autoId, 3);
+        } while (usedIds.has(id) || reservedIds.has(id));
+        usedIds.add(id);
+        return id;
+    }
     return reqs.map((req) => {
-        autoId++;
+        const originalId = req.id.trim();
+        const canonicalId = normalizeRequirementId(originalId);
+        let id;
+        let description = req.description;
+        if (canonicalId && !usedIds.has(canonicalId)) {
+            id = canonicalId;
+            usedIds.add(id);
+        }
+        else {
+            id = nextRequirementId();
+            if (originalId) {
+                description = `Legacy ID: ${originalId}\n\n${description}`;
+            }
+        }
         return {
-            id: req.id && req.id.trim() !== '' ? req.id : padId('R', autoId, 3),
+            id,
             title: req.title,
             class: 'core-capability',
             status: normalizeStatus(req.status),
-            description: req.description,
+            description,
             source: 'inferred',
             primarySlice: 'none yet',
         };
@@ -233,7 +265,22 @@ function deriveDecisions(parsed) {
     }
     if (decisions.length === 0)
         return '';
-    return decisions.map((d) => `- ${d}`).join('\n');
+    const lines = [
+        '# Decisions Register',
+        '',
+        '<!-- Append-only. Never edit or remove existing rows.',
+        '     To reverse a decision, add a new row that supersedes it.',
+        '     Read this file at the start of any planning or research phase. -->',
+        '',
+        '| # | When | Scope | Decision | Choice | Rationale | Revisable? | Made By |',
+        '|---|------|-------|----------|--------|-----------|------------|---------|',
+    ];
+    decisions.forEach((decision, index) => {
+        const id = padId('D', index + 1, 3);
+        const escaped = decision.replace(/\|/g, '\\|');
+        lines.push(`| ${id} | migration | migrated-summary | ${escaped} | ${escaped} | Migrated from legacy summary key-decisions | Yes | agent |`);
+    });
+    return lines.join('\n') + '\n';
 }
 // ─── Main Entry Point ──────────────────────────────────────────────────────
 export function transformToGSD(parsed) {

package/dist/resources/extensions/gsd/migrate/writer.js

@@ -296,7 +296,17 @@ export function formatProject(content) {
  */
 export function formatDecisions(content) {
     if (!content || !content.trim()) {
-        return '# Decisions\n\n<!-- Append-only register of architectural and pattern decisions -->\n\n| ID | Decision | Rationale | Date |\n|----|----------|-----------|------|\n';
+        return [
+            '# Decisions Register',
+            '',
+            '<!-- Append-only. Never edit or remove existing rows.',
+            '     To reverse a decision, add a new row that supersedes it.',
+            '     Read this file at the start of any planning or research phase. -->',
+            '',
+            '| # | When | Scope | Decision | Choice | Rationale | Revisable? | Made By |',
+            '|---|------|-------|----------|--------|-----------|------------|---------|',
+            '',
+        ].join('\n');
     }
     return content.endsWith('\n') ? content : content + '\n';
 }

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