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

package/src/resources/extensions/gsd/auto/orchestrator.ts

@@ -7,6 +7,16 @@ function now(): number {
   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 implements AutoOrchestrationModule {
   private status: AutoStatus = {
     phase: "idle",
@@ -14,6 +24,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
   };
   private readonly deps: AutoOrchestratorDeps;
   private lastAdvanceKey: string | null = null;
+  private dispatchKeyWindow: string[] = [];
 
   public constructor(deps: AutoOrchestratorDeps) {
     this.deps = deps;
@@ -21,6 +32,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
 
   public async start(_sessionContext: AutoSessionContext): Promise<AutoAdvanceResult> {
     this.lastAdvanceKey = null;
+    this.dispatchKeyWindow = [];
     this.status.phase = "running";
     this.bumpTransition();
     await this.deps.runtime.journalTransition({ name: "start" });
@@ -31,19 +43,72 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
   public async advance(): Promise<AutoAdvanceResult> {
     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: AutoAdvanceResult = { 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: AutoAdvanceResult = { 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: AutoAdvanceResult = { 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: AutoAdvanceResult = {
           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 });
@@ -57,6 +122,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         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);
@@ -64,8 +130,45 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
       }
 
       const nextKey = `${decision.unitType}:${decision.unitId}`;
-      if (this.lastAdvanceKey === nextKey) {
-        const blocked: AutoAdvanceResult = { 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: AutoAdvanceResult = { 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: AutoAdvanceResult = {
+          kind: "blocked",
+          reason: `stuck-loop: ${nextKey} picked ${matchingCount} times`,
+          action: "stop",
+        };
         await this.deps.runtime.journalTransition({
           name: "advance-blocked",
           reason: blocked.reason,
@@ -81,6 +184,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         const blocked: AutoAdvanceResult = {
           kind: "blocked",
           reason: contract.reason,
+          action: "pause",
           stateSnapshot: reconciliation.stateSnapshot,
         };
         await this.deps.runtime.journalTransition({
@@ -98,6 +202,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         const blocked: AutoAdvanceResult = {
           kind: "blocked",
           reason: worktree.reason,
+          action: "pause",
           stateSnapshot: reconciliation.stateSnapshot,
         };
         await this.deps.runtime.journalTransition({
@@ -123,7 +228,11 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
       });
       await this.deps.worktree.syncAfterUnit(decision.unitType, decision.unitId);
 
-      const advanced: AutoAdvanceResult = { kind: "advanced", stateSnapshot: reconciliation.stateSnapshot };
+      const advanced: AutoAdvanceResult = {
+        kind: "advanced",
+        unit: { unitType: decision.unitType, unitId: decision.unitId },
+        stateSnapshot: reconciliation.stateSnapshot,
+      };
       await this.deps.health.postAdvanceRecord(advanced);
       return advanced;
     } catch (error) {
@@ -148,6 +257,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
 
       if (result.kind === "stopped") {
         this.lastAdvanceKey = null;
+        this.dispatchKeyWindow = [];
         this.status.activeUnit = undefined;
       }
       this.bumpTransition();
@@ -173,6 +283,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
 
   public async resume(): Promise<AutoAdvanceResult> {
     this.lastAdvanceKey = null;
+    this.dispatchKeyWindow = [];
     this.status.phase = "running";
     this.bumpTransition();
     await this.deps.runtime.journalTransition({ name: "resume" });
@@ -188,6 +299,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     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/src/resources/extensions/gsd/auto.ts

@@ -240,12 +240,14 @@ import { runAutoLoopWithUok } from "./uok/kernel.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { validateDirectory } from "./validate-directory.js";
 import { createAutoOrchestrator } from "./auto/orchestrator.js";
-import type { AutoOrchestrationModule, AutoOrchestratorDeps } from "./auto/contracts.js";
+import type { AutoOrchestrationModule, AutoOrchestratorDeps, DispatchAdapter } from "./auto/contracts.js";
 import { reconcileBeforeDispatch } from "./state-reconciliation.js";
 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 type { MinimalModelRegistry } from "./context-budget.js";
 // Slice-level parallelism (#2340)
 import { getEligibleSlices } from "./slice-parallel-eligibility.js";
 import { startSliceParallel } from "./slice-parallel-orchestrator.js";
@@ -1048,13 +1050,11 @@ export async function cleanupAfterLoopExit(ctx: ExtensionContext): Promise<void>
     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();
@@ -1065,11 +1065,6 @@ export async function cleanupAfterLoopExit(ctx: ExtensionContext): Promise<void>
         { 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) {
@@ -1384,20 +1379,14 @@ export async function stopAuto(
     }
 
     // ── 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();
       } 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.
@@ -1792,6 +1781,75 @@ function buildLifecycle(): WorktreeLifecycle {
   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: ExtensionContext,
+  pi: ExtensionAPI,
+  dispatchBasePath: string,
+): DispatchAdapter {
+  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 as MinimalModelRegistry | undefined);
+      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.
  *
@@ -1801,7 +1859,7 @@ function buildLifecycle(): WorktreeLifecycle {
  */
 export function createWiredAutoOrchestrationModule(
   ctx: ExtensionContext,
-  _pi: ExtensionAPI,
+  pi: ExtensionAPI,
   dispatchBasePath: string,
   runtimeBasePath = resolveProjectRoot(dispatchBasePath),
 ): AutoOrchestrationModule {
@@ -1830,30 +1888,7 @@ export function createWiredAutoOrchestrationModule(
         };
       },
     },
-    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);
@@ -1902,12 +1937,25 @@ export function createWiredAutoOrchestrationModule(
       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") {
@@ -1975,6 +2023,43 @@ export function createWiredAutoOrchestrationModule(
         }
       },
     },
+    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/src/resources/extensions/gsd/md-importer.ts

@@ -306,7 +306,7 @@ function importRequirements(gsdDir: string): number {
 // ─── 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/src/resources/extensions/gsd/migrate/command.ts

@@ -34,6 +34,9 @@ export type MigrationImportCounts = ReturnType<typeof migrateFromMarkdown>;
 
 function assertMigrationImportMatchesPreview(imported: MigrationImportCounts, preview: MigrationPreview): void {
   const mismatches: string[] = [];
+  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}`);
   }
@@ -73,6 +76,7 @@ export async function importWrittenMigrationToDb(
 /** Format preview stats for embedding in the review prompt. */
 function formatPreviewStats(preview: MigrationPreview): string {
   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}%)`,
@@ -179,6 +183,7 @@ export async function handleMigrate(
 
   // ── Build preview text ─────────────────────────────────────────────────────
   const lines: string[] = [
+    `Decisions: ${preview.decisions.total}`,
     `Milestones: ${preview.milestoneCount}`,
     `Slices: ${preview.totalSlices} (${preview.doneSlices} done — ${preview.sliceCompletionPct}%)`,
     `Tasks: ${preview.totalTasks} (${preview.doneTasks} done — ${preview.taskCompletionPct}%)`,

package/src/resources/extensions/gsd/migrate/preview.ts

@@ -4,6 +4,13 @@
 import type { GSDProject } from './types.js';
 import type { MigrationPreview } from './writer.js';
 
+function countCanonicalDecisionRows(content: string): number {
+  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.
@@ -36,6 +43,9 @@ export function generatePreview(project: GSDProject): MigrationPreview {
   }
 
   return {
+    decisions: {
+      total: countCanonicalDecisionRows(project.decisionsContent),
+    },
     milestoneCount: project.milestones.length,
     totalSlices,
     totalTasks,

package/src/resources/extensions/gsd/migrate/transformer.ts

@@ -238,16 +238,53 @@ function normalizeStatus(status: string): 'active' | 'validated' | 'deferred' {
   return 'active';
 }
 
+function normalizeRequirementId(id: string): string | null {
+  const match = id.trim().match(/^R(\d+)$/i);
+  if (!match) return null;
+  return `R${match[1].padStart(3, '0')}`;
+}
+
 function mapRequirements(reqs: PlanningRequirement[]): GSDRequirement[] {
   let autoId = 0;
+  const reservedIds = new Set(
+    reqs
+      .map((req) => normalizeRequirementId(req.id))
+      .filter((id): id is string => id !== null),
+  );
+  const usedIds = new Set<string>();
+
+  function nextRequirementId(): string {
+    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: string;
+    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',
     };
@@ -286,7 +323,24 @@ function deriveDecisions(parsed: PlanningProject): string {
     }
   }
   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 ──────────────────────────────────────────────────────

package/src/resources/extensions/gsd/migrate/writer.ts

@@ -37,6 +37,9 @@ export interface WrittenFiles {
 
 /** Pre-write statistics computed from a GSDProject without I/O. */
 export interface MigrationPreview {
+  decisions: {
+    total: number;
+  };
   milestoneCount: number;
   totalSlices: number;
   totalTasks: number;
@@ -374,7 +377,17 @@ export function formatProject(content: string): string {
  */
 export function formatDecisions(content: string): string {
   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';
 }