gsd-pi 2.82.0-dev.725028083 → 2.82.0-dev.c22380fc3

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-5c6d4acc2e1d8c2b
+291e7683e17ec7a9

package/dist/resources/extensions/gsd/auto/orchestrator.js

@@ -3,6 +3,15 @@
 function now() {
     return Date.now();
 }
+/**
+ * Size of the dispatch-decision ring buffer used by the Auto Orchestration
+ * module's stuck-loop detector. When the same `${unitType}:${unitId}` key
+ * fills the window, advance() blocks with `action: "stop"`.
+ *
+ * Mirrors the legacy `STUCK_WINDOW_SIZE` in auto/phases.ts so behaviour is
+ * preserved across the eventual cutover (issue #5791).
+ */
+export const STUCK_WINDOW_SIZE = 6;
 export class AutoOrchestrator {
     status = {
         phase: "idle",
@@ -10,11 +19,13 @@ export class AutoOrchestrator {
     };
     deps;
     lastAdvanceKey = null;
+    dispatchKeyWindow = [];
     constructor(deps) {
         this.deps = deps;
     }
     async start(_sessionContext) {
         this.lastAdvanceKey = null;
+        this.dispatchKeyWindow = [];
         this.status.phase = "running";
         this.bumpTransition();
         await this.deps.runtime.journalTransition({ name: "start" });
@@ -24,18 +35,70 @@ export class AutoOrchestrator {
     async advance() {
         try {
             await this.deps.runtime.ensureLockOwnership();
+            const staleMsg = this.deps.health.checkResourcesStale();
+            if (staleMsg) {
+                await this.deps.uokGate.emit({
+                    gateId: "resource-version-guard",
+                    gateType: "policy",
+                    outcome: "fail",
+                    failureClass: "policy",
+                    rationale: "resource version guard blocked dispatch",
+                    findings: staleMsg,
+                });
+                const blocked = { kind: "blocked", reason: staleMsg, action: "stop" };
+                await this.deps.runtime.journalTransition({ name: "advance-blocked", reason: blocked.reason });
+                await this.deps.health.postAdvanceRecord(blocked);
+                return blocked;
+            }
+            await this.deps.uokGate.emit({
+                gateId: "resource-version-guard",
+                gateType: "policy",
+                outcome: "pass",
+                failureClass: "none",
+                rationale: "resource version guard passed",
+            });
             const gate = await this.deps.health.preAdvanceGate();
-            if (!gate.allow) {
-                const blocked = { kind: "blocked", reason: gate.reason ?? "health gate blocked" };
+            if (gate.kind === "fail") {
+                await this.deps.uokGate.emit({
+                    gateId: "pre-dispatch-health-gate",
+                    gateType: "execution",
+                    outcome: "manual-attention",
+                    failureClass: "manual-attention",
+                    rationale: "pre-dispatch health gate blocked dispatch",
+                    findings: gate.reason,
+                });
+                const blocked = { kind: "blocked", reason: gate.reason, action: "pause" };
                 await this.deps.runtime.journalTransition({ name: "advance-blocked", reason: blocked.reason });
                 await this.deps.health.postAdvanceRecord(blocked);
                 return blocked;
             }
+            if (gate.kind === "threw") {
+                await this.deps.uokGate.emit({
+                    gateId: "pre-dispatch-health-gate",
+                    gateType: "execution",
+                    outcome: "manual-attention",
+                    failureClass: "manual-attention",
+                    rationale: "pre-dispatch health gate threw unexpectedly",
+                    findings: String(gate.error),
+                });
+                // intentional fall-through: matches runPreDispatch behaviour
+            }
+            else {
+                await this.deps.uokGate.emit({
+                    gateId: "pre-dispatch-health-gate",
+                    gateType: "execution",
+                    outcome: "pass",
+                    failureClass: "none",
+                    rationale: "pre-dispatch health gate passed",
+                    findings: gate.fixesApplied?.join(", ") ?? "",
+                });
+            }
             const reconciliation = await this.deps.stateReconciliation.reconcileBeforeDispatch();
             if (!reconciliation.ok || !reconciliation.stateSnapshot) {
                 const blocked = {
                     kind: "blocked",
-                    reason: reconciliation.reason,
+                    reason: reconciliation.reason ?? "state reconciliation produced no snapshot",
+                    action: "pause",
                     stateSnapshot: reconciliation.stateSnapshot,
                 };
                 await this.deps.runtime.journalTransition({ name: "advance-blocked", reason: blocked.reason });
@@ -48,14 +111,49 @@ export class AutoOrchestrator {
                 this.status.phase = "stopped";
                 this.status.activeUnit = undefined;
                 this.lastAdvanceKey = null;
+                this.dispatchKeyWindow = [];
                 this.bumpTransition();
                 await this.deps.runtime.journalTransition({ name: "advance-stopped", reason: stopped.reason });
                 await this.deps.health.postAdvanceRecord(stopped);
                 return stopped;
             }
             const nextKey = `${decision.unitType}:${decision.unitId}`;
-            if (this.lastAdvanceKey === nextKey) {
-                const blocked = { kind: "blocked", reason: "idempotent advance: unit already active" };
+            // Record every dispatch decision in the ring buffer before pre-flight
+            // checks so the stuck-loop detector observes the full decision history
+            // (including decisions that idempotency would otherwise short-circuit).
+            // The ring is capped at STUCK_WINDOW_SIZE and evicts oldest-first.
+            this.dispatchKeyWindow.push(nextKey);
+            if (this.dispatchKeyWindow.length > STUCK_WINDOW_SIZE) {
+                this.dispatchKeyWindow.shift();
+            }
+            // Idempotency: same key as immediately previous successful advance.
+            // This is the soft, fast-path block kept from #5786. It only fires when
+            // the ring is NOT yet saturated for this key — once the ring is full of
+            // `nextKey`, the stuck-loop verdict takes precedence (see below). Both
+            // checks coexist: idempotency for the common immediate-repeat case,
+            // stuck-loop for the saturated-window case.
+            const matchingCount = this.dispatchKeyWindow.filter((k) => k === nextKey).length;
+            if (this.lastAdvanceKey === nextKey && matchingCount < STUCK_WINDOW_SIZE) {
+                const blocked = { kind: "blocked", reason: "idempotent advance: unit already active", action: "stop" };
+                await this.deps.runtime.journalTransition({
+                    name: "advance-blocked",
+                    reason: blocked.reason,
+                    unitType: decision.unitType,
+                    unitId: decision.unitId,
+                });
+                await this.deps.health.postAdvanceRecord(blocked);
+                return blocked;
+            }
+            // Stuck-loop detection: when the ring is saturated with copies of
+            // `nextKey` (count >= STUCK_WINDOW_SIZE), the orchestrator has been
+            // picking the same unit across the whole window and must hard-stop with
+            // a diagnosable reason.
+            if (matchingCount >= STUCK_WINDOW_SIZE) {
+                const blocked = {
+                    kind: "blocked",
+                    reason: `stuck-loop: ${nextKey} picked ${matchingCount} times`,
+                    action: "stop",
+                };
                 await this.deps.runtime.journalTransition({
                     name: "advance-blocked",
                     reason: blocked.reason,
@@ -70,6 +168,7 @@ export class AutoOrchestrator {
                 const blocked = {
                     kind: "blocked",
                     reason: contract.reason,
+                    action: "pause",
                     stateSnapshot: reconciliation.stateSnapshot,
                 };
                 await this.deps.runtime.journalTransition({
@@ -86,6 +185,7 @@ export class AutoOrchestrator {
                 const blocked = {
                     kind: "blocked",
                     reason: worktree.reason,
+                    action: "pause",
                     stateSnapshot: reconciliation.stateSnapshot,
                 };
                 await this.deps.runtime.journalTransition({
@@ -108,7 +208,11 @@ export class AutoOrchestrator {
                 unitId: decision.unitId,
             });
             await this.deps.worktree.syncAfterUnit(decision.unitType, decision.unitId);
-            const advanced = { kind: "advanced", stateSnapshot: reconciliation.stateSnapshot };
+            const advanced = {
+                kind: "advanced",
+                unit: { unitType: decision.unitType, unitId: decision.unitId },
+                stateSnapshot: reconciliation.stateSnapshot,
+            };
             await this.deps.health.postAdvanceRecord(advanced);
             return advanced;
         }
@@ -134,6 +238,7 @@ export class AutoOrchestrator {
             }
             if (result.kind === "stopped") {
                 this.lastAdvanceKey = null;
+                this.dispatchKeyWindow = [];
                 this.status.activeUnit = undefined;
             }
             this.bumpTransition();
@@ -158,6 +263,7 @@ export class AutoOrchestrator {
     }
     async resume() {
         this.lastAdvanceKey = null;
+        this.dispatchKeyWindow = [];
         this.status.phase = "running";
         this.bumpTransition();
         await this.deps.runtime.journalTransition({ name: "resume" });
@@ -172,6 +278,7 @@ export class AutoOrchestrator {
         this.status.phase = "stopped";
         this.status.activeUnit = undefined;
         this.lastAdvanceKey = null;
+        this.dispatchKeyWindow = [];
         this.bumpTransition();
         await this.deps.runtime.journalTransition({ name: "stop", reason });
         await this.deps.notifications.notifyLifecycle({ name: "stop", detail: reason });

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

@@ -92,6 +92,7 @@ import { compileUnitToolContract } from "./tool-contract.js";
 import { createWorktreeSafetyModule } from "./worktree-safety.js";
 import { resolveManifest } from "./unit-context-manifest.js";
 import { classifyFailure } from "./recovery-classification.js";
+import { supportsStructuredQuestions } from "./workflow-mcp.js";
 import { WorktreeLifecycle, } from "./worktree-lifecycle.js";
 import { WorktreeStateProjection } from "./worktree-state-projection.js";
 import { reorderForCaching } from "./prompt-ordering.js";
@@ -711,13 +712,11 @@ export async function cleanupAfterLoopExit(ctx) {
         }
         initHealthWidget(ctx);
     }
-    // ADR-016 phase 3 (#5693): the stop-path basePath restore routes through
-    // `Lifecycle.restoreToProjectRoot()`, the sole owner of `s.basePath`
-    // mutation. The verb assigns `s.basePath` before any throwable work
-    // (rebuildGitService, cache invalidation), so a thrown error still leaves
-    // basePath restored — no fallback assignment needed at the call site.
-    // The chdir stays here because `restoreToProjectRoot` is a pure
-    // session-state mutation.
+    // ADR-016 phase 3 (#5693): the stop-path basePath restore + chdir routes
+    // through `Lifecycle.restoreToProjectRoot()`, the sole owner of both
+    // `s.basePath` mutation and the paired `process.chdir` for auto-loop
+    // transitions. The verb assigns `s.basePath` before any throwable work, so
+    // a thrown error still leaves basePath restored.
     if (s.originalBasePath) {
         try {
             buildLifecycle().restoreToProjectRoot();
@@ -725,12 +724,6 @@ export async function cleanupAfterLoopExit(ctx) {
         catch (err) {
             logWarning("engine", `restore project root failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
         }
-        try {
-            process.chdir(s.originalBasePath);
-        }
-        catch (err) {
-            logWarning("engine", `basePath restore/chdir failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
-        }
     }
     if (s.originalBasePath && s.cmdCtx) {
         const result = await rerootCommandSession(s.cmdCtx, s.originalBasePath);
@@ -1001,8 +994,8 @@ export async function stopAuto(ctx, pi, reason, options = {}) {
             }
         }
         // ── Step 7: Restore basePath and chdir (ADR-016 phase 3, #5693) ──
-        // `restoreToProjectRoot` assigns s.basePath before any throwable work;
-        // no fallback assignment is needed at the call site.
+        // `restoreToProjectRoot` owns both s.basePath restore and process.chdir;
+        // no paired chdir is needed at the call site.
         if (s.originalBasePath) {
             try {
                 buildLifecycle().restoreToProjectRoot();
@@ -1010,13 +1003,6 @@ export async function stopAuto(ctx, pi, reason, options = {}) {
             catch (e) {
                 debugLog("stop-cleanup-basepath", { error: e instanceof Error ? e.message : String(e) });
             }
-            try {
-                process.chdir(s.basePath);
-            }
-            catch (err) {
-                /* best-effort */
-                logWarning("engine", `chdir failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
-            }
         }
         // Re-root the active command session/tool runtime after worktree teardown.
         // mergeAndExit restores process.cwd(), but AgentSession has already captured
@@ -1385,6 +1371,66 @@ export function buildWorktreeLifecycleDeps() {
 function buildLifecycle() {
     return new WorktreeLifecycle(s, buildWorktreeLifecycleDeps());
 }
+/**
+ * Build the production `DispatchAdapter` used by `createWiredAutoOrchestrationModule`.
+ *
+ * Exported so tests can verify parity with `runDispatch`'s `resolveDispatch` call —
+ * the wired adapter must derive `structuredQuestionsAvailable`, `sessionContextWindow`,
+ * `sessionProvider`, and `modelRegistry` the same way phases.ts:runDispatch does.
+ */
+export function createWiredDispatchAdapter(ctx, pi, dispatchBasePath) {
+    return {
+        async decideNextUnit(input) {
+            const state = input.stateSnapshot;
+            const active = state.activeMilestone;
+            if (!active)
+                return null;
+            const prefs = loadEffectiveGSDPreferences(dispatchBasePath)?.preferences;
+            // Derive session-derived dispatch inputs the same way phases.ts:runDispatch does
+            // (#5789). Prefer caller-supplied values when present so test harnesses and
+            // alternative wirings can inject deterministic snapshots; otherwise pull from
+            // the captured pi/ctx references.
+            const sessionProvider = input.sessionProvider ?? ctx.model?.provider;
+            const sessionContextWindow = input.sessionContextWindow ?? ctx.model?.contextWindow;
+            const modelRegistry = input.modelRegistry ?? ctx.modelRegistry;
+            const authMode = sessionProvider && typeof ctx.modelRegistry?.getProviderAuthMode === "function"
+                ? ctx.modelRegistry.getProviderAuthMode(sessionProvider)
+                : undefined;
+            const activeTools = typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [];
+            // Mirrors runDispatch: deep-planning keeps approval gates in plain chat
+            // because structured questions can be cancelled outside the chat turn on
+            // some transports.
+            const structuredQuestionsAvailable = input.structuredQuestionsAvailable ??
+                (prefs?.planning_depth === "deep"
+                    ? "false"
+                    : supportsStructuredQuestions(activeTools, {
+                        authMode,
+                        baseUrl: ctx.model?.baseUrl,
+                    })
+                        ? "true"
+                        : "false");
+            const action = await resolveDispatch({
+                basePath: dispatchBasePath,
+                mid: active.id,
+                midTitle: active.title,
+                state,
+                prefs,
+                structuredQuestionsAvailable,
+                sessionContextWindow,
+                sessionProvider,
+                modelRegistry,
+            });
+            if (action.action !== "dispatch")
+                return null;
+            return {
+                unitType: action.unitType,
+                unitId: action.unitId,
+                reason: action.matchedRule ?? "dispatch",
+                preconditions: [],
+            };
+        },
+    };
+}
 /**
  * Thin entry glue for the new Auto Orchestration module.
  *
@@ -1392,7 +1438,7 @@ function buildLifecycle() {
  * no behavior changes to the existing auto loop. It provides a concrete seam
  * the next refactor steps can adopt incrementally.
  */
-export function createWiredAutoOrchestrationModule(ctx, _pi, dispatchBasePath, runtimeBasePath = resolveProjectRoot(dispatchBasePath)) {
+export function createWiredAutoOrchestrationModule(ctx, pi, dispatchBasePath, runtimeBasePath = resolveProjectRoot(dispatchBasePath)) {
     const flowId = `auto-orchestrator-${Date.now()}`;
     let seq = 0;
     const deps = {
@@ -1416,30 +1462,7 @@ export function createWiredAutoOrchestrationModule(ctx, _pi, dispatchBasePath, r
                 };
             },
         },
-        dispatch: {
-            async decideNextUnit(input) {
-                const state = input.stateSnapshot;
-                const active = state.activeMilestone;
-                if (!active)
-                    return null;
-                const prefs = loadEffectiveGSDPreferences(dispatchBasePath)?.preferences;
-                const action = await resolveDispatch({
-                    basePath: dispatchBasePath,
-                    mid: active.id,
-                    midTitle: active.title,
-                    state,
-                    prefs,
-                });
-                if (action.action !== "dispatch")
-                    return null;
-                return {
-                    unitType: action.unitType,
-                    unitId: action.unitId,
-                    reason: action.matchedRule ?? "dispatch",
-                    preconditions: [],
-                };
-            },
-        },
+        dispatch: createWiredDispatchAdapter(ctx, pi, dispatchBasePath),
         recovery: {
             async classifyAndRecover(input) {
                 const recovery = classifyFailure(input);
@@ -1488,12 +1511,26 @@ export function createWiredAutoOrchestrationModule(ctx, _pi, dispatchBasePath, r
             async cleanupOnStop() { },
         },
         health: {
+            checkResourcesStale() {
+                return checkResourcesStale(s.resourceVersionOnStart);
+            },
             async preAdvanceGate() {
-                const gate = await preDispatchHealthGate(dispatchBasePath);
-                return {
-                    allow: gate.proceed,
-                    reason: gate.reason,
-                };
+                try {
+                    const gate = await preDispatchHealthGate(dispatchBasePath);
+                    if (gate.proceed) {
+                        return {
+                            kind: "pass",
+                            fixesApplied: gate.fixesApplied,
+                        };
+                    }
+                    return {
+                        kind: "fail",
+                        reason: gate.reason ?? "Pre-dispatch health check failed — run /gsd doctor for details.",
+                    };
+                }
+                catch (error) {
+                    return { kind: "threw", error };
+                }
             },
             async postAdvanceRecord(result) {
                 if (result.kind === "error") {
@@ -1561,6 +1598,45 @@ export function createWiredAutoOrchestrationModule(ctx, _pi, dispatchBasePath, r
                 }
             },
         },
+        uokGate: {
+            async emit(input) {
+                const prefs = loadEffectiveGSDPreferences(dispatchBasePath)?.preferences;
+                const uokFlags = resolveUokFlags(prefs);
+                if (!uokFlags.gates)
+                    return;
+                const milestoneId = input.milestoneId ?? s.currentMilestoneId ?? undefined;
+                try {
+                    const { UokGateRunner } = await import("./uok/gate-runner.js");
+                    const runner = new UokGateRunner();
+                    runner.register({
+                        id: input.gateId,
+                        type: input.gateType,
+                        execute: async () => ({
+                            outcome: input.outcome,
+                            failureClass: input.failureClass,
+                            rationale: input.rationale,
+                            findings: input.findings ?? "",
+                        }),
+                    });
+                    await runner.run(input.gateId, {
+                        basePath: dispatchBasePath,
+                        traceId: `pre-dispatch:${flowId}`,
+                        turnId: `orch-${seq}`,
+                        milestoneId,
+                        unitType: "pre-dispatch",
+                        unitId: `orch-${seq}`,
+                    });
+                }
+                catch (err) {
+                    logWarning("engine", `uok gate emit failed: ${getErrorMessage(err)}`, {
+                        file: "auto.ts",
+                        gateId: input.gateId,
+                        gateType: input.gateType,
+                        ...(milestoneId ? { milestoneId } : {}),
+                    });
+                }
+            },
+        },
     };
     return createAutoOrchestrator(deps);
 }

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

@@ -256,7 +256,7 @@ function importRequirements(gsdDir) {
 }
 // ─── Hierarchy Artifact Walker ─────────────────────────────────────────────
 /** Artifact suffixes to look for at each hierarchy level */
-const MILESTONE_SUFFIXES = ['ROADMAP', 'CONTEXT', 'RESEARCH', 'ASSESSMENT'];
+const MILESTONE_SUFFIXES = ['ROADMAP', 'CONTEXT', 'RESEARCH', 'ASSESSMENT', 'SUMMARY', 'VALIDATION'];
 const SLICE_SUFFIXES = ['PLAN', 'SUMMARY', 'RESEARCH', 'CONTEXT', 'ASSESSMENT', 'UAT'];
 const TASK_SUFFIXES = ['PLAN', 'SUMMARY', 'CONTINUE', 'CONTEXT', 'RESEARCH'];
 /**

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';
 }