gsd-pi 2.82.0 → 3.0.0

package/src/resources/extensions/gsd/context-store.ts

@@ -5,7 +5,7 @@
 // All functions degrade gracefully: return empty results when DB unavailable, never throw.
 
 import { isDbAvailable, _getAdapter } from './gsd-db.js';
-import type { Decision, Requirement } from './types.js';
+import type { Decision, DecisionMadeBy, Requirement } from './types.js';
 
 // ─── Query Functions ───────────────────────────────────────────────────────
 
@@ -66,6 +66,125 @@ export function queryDecisions(opts?: DecisionQueryOpts): Decision[] {
   }
 }
 
+/**
+ * Internal: shared core for the two memory-sourced decision queries. Reads
+ * memory rows tagged with `sourceDecisionId` and reconstructs `Decision[]`
+ * from their `structured_fields` JSON.
+ *
+ * @param includeSuperseded — when false, drops rows whose
+ *   `structured_fields.superseded_by` is non-null. The supersedes-chain is
+ *   captured by the backfill (`memory-backfill.ts`) and kept in sync by
+ *   the backfill's drift auto-heal pass.
+ */
+function readDecisionsFromMemories(
+  opts: DecisionQueryOpts | undefined,
+  includeSuperseded: boolean,
+): Decision[] {
+  if (!isDbAvailable()) return [];
+  const adapter = _getAdapter();
+  if (!adapter) return [];
+
+  try {
+    const clauses: string[] = [
+      "category = 'architecture'",
+      "structured_fields LIKE '%\"sourceDecisionId\":\"%'",
+    ];
+    const params: Record<string, unknown> = {};
+
+    if (opts?.milestoneId) {
+      // when_context is a free-text JSON value; substring match preserves the
+      // semantics of `when_context LIKE '%milestoneId%'` on the legacy table.
+      clauses.push("json_extract(structured_fields, '$.when_context') LIKE :milestone_pattern");
+      params[':milestone_pattern'] = `%${opts.milestoneId}%`;
+    }
+
+    if (opts?.scope) {
+      // Stage 1 used `json_extract` in main (post-merge); preserve that
+      // style here. Exact equality on the JSON value avoids the prefix
+      // collision risk LIKE patterns had (scope=M001 vs scope=M001-S01).
+      clauses.push("json_extract(structured_fields, '$.scope') = :scope");
+      params[':scope'] = opts.scope;
+    }
+
+    const sql = `SELECT seq, structured_fields FROM memories WHERE ${clauses.join(' AND ')} ORDER BY seq`;
+    const rows = adapter.prepare(sql).all(params) as Array<Record<string, unknown>>;
+
+    const decisions: Decision[] = [];
+    for (const row of rows) {
+      const seq = row['seq'] as number;
+      const sfRaw = row['structured_fields'] as string | null;
+      if (!sfRaw) continue;
+      let sf: Record<string, unknown>;
+      try {
+        sf = JSON.parse(sfRaw) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      const sourceId = sf['sourceDecisionId'];
+      if (typeof sourceId !== 'string' || sourceId.length === 0) continue;
+
+      // Decision-level superseded status lives in structured_fields.superseded_by
+      // (written by mirrorDecisionToMemory / memory-backfill.ts). The top-level
+      // memories.superseded_by column is intentionally never set for decision mirrors,
+      // so active-only filtering must be done here in the JS loop.
+      const supersededBy = typeof sf['superseded_by'] === 'string' ? (sf['superseded_by'] as string) : null;
+      if (!includeSuperseded && supersededBy) continue;
+
+      decisions.push({
+        seq,
+        id: sourceId,
+        when_context: typeof sf['when_context'] === 'string' ? (sf['when_context'] as string) : '',
+        scope: typeof sf['scope'] === 'string' ? (sf['scope'] as string) : '',
+        decision: typeof sf['decision'] === 'string' ? (sf['decision'] as string) : '',
+        choice: typeof sf['choice'] === 'string' ? (sf['choice'] as string) : '',
+        rationale: typeof sf['rationale'] === 'string' ? (sf['rationale'] as string) : '',
+        revisable: typeof sf['revisable'] === 'string' ? (sf['revisable'] as string) : '',
+        made_by: ((typeof sf['made_by'] === 'string' ? sf['made_by'] : 'agent') as DecisionMadeBy),
+        superseded_by: supersededBy,
+      });
+    }
+
+    return decisions;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * ADR-013 Phase 6 cutover (Stage 1): read **active** decisions from the
+ * `memories` table instead of the legacy `decisions` table. Returns the
+ * same `Decision[]` shape as `queryDecisions` so downstream formatters
+ * work unchanged.
+ *
+ * Filter semantics match `queryDecisions` exactly:
+ * - active only (skips rows where `structured_fields.superseded_by` is set)
+ * - `milestoneId`: substring match on `structured_fields.when_context`
+ * - `scope`: exact match on `structured_fields.scope`
+ *
+ * Used by the prompt-inline path (`inlineDecisionsFromDb` in
+ * `auto-prompts.ts`). For the projection regen (which renders superseded
+ * rows too), see `getAllDecisionsFromMemories`.
+ */
+export function queryDecisionsFromMemories(opts?: DecisionQueryOpts): Decision[] {
+  return readDecisionsFromMemories(opts, /* includeSuperseded */ false);
+}
+
+/**
+ * ADR-013 Phase 6 cutover (Stage 2a): read **all** decisions (active +
+ * superseded) from the `memories` table. Used by the DECISIONS.md
+ * projection regen in `saveDecisionToDb`, which must render the full
+ * supersedes-chain for the canonical register format.
+ *
+ * Equivalent to `SELECT * FROM decisions ORDER BY seq` over the legacy
+ * table — but sourced from memories so the legacy table can be retired
+ * in Stage 3. Includes `superseded_by` reconstructed from
+ * `structured_fields.superseded_by` (populated by the backfill's drift
+ * auto-heal pass).
+ */
+export function getAllDecisionsFromMemories(): Decision[] {
+  return readDecisionsFromMemories(undefined, /* includeSuperseded */ true);
+}
+
 /**
  * Query active (non-superseded) requirements with optional filters.
  * - milestoneId: combined with sliceId for precise filtering (e.g. %M005/S01%)

package/src/resources/extensions/gsd/crash-recovery.ts

@@ -30,9 +30,12 @@ import { join } from "node:path";
 import {
   findStaleWorkerForProject,
   getAllAutoWorkers,
+  markWorkerCrashed,
+  markWorkerStopping,
   type AutoWorkerRow,
 } from "./db/auto-workers.js";
-import { getLatestForUnit, type DispatchStatus } from "./db/unit-dispatches.js";
+import { forceReleaseLeasesForWorker } from "./db/milestone-leases.js";
+import { markLatestActiveForWorkerCanceled, type DispatchStatus } from "./db/unit-dispatches.js";
 import { getRuntimeKv, setRuntimeKv, deleteRuntimeKv } from "./db/runtime-kv.js";
 import { _getAdapter, isDbAvailable } from "./gsd-db.js";
 import { gsdRoot, normalizeRealPath } from "./paths.js";
@@ -56,6 +59,15 @@ function lockPath(basePath: string): string {
   return join(gsdRoot(basePath), effectiveLockFile());
 }
 
+function clearLegacyLockFile(basePath: string): void {
+  try {
+    const p = lockPath(basePath);
+    if (existsSync(p)) unlinkSync(p);
+  } catch {
+    // Best-effort.
+  }
+}
+
 function readLegacyLock(basePath: string): LockData | null {
   try {
     const p = lockPath(basePath);
@@ -204,18 +216,46 @@ export function writeLock(
  * stale session-file pointer.
  */
 export function clearLock(basePath: string): void {
+  clearLegacyLockFile(basePath);
+
+  if (!isDbAvailable()) return;
   try {
-    const p = lockPath(basePath);
-    if (existsSync(p)) unlinkSync(p);
+    const projectRoot = normalizeRealPath(basePath);
+    const staleWorker = findStaleWorkerForProject(projectRoot);
+    if (staleWorker) {
+      markWorkerCrashed(staleWorker.worker_id);
+      forceReleaseLeasesForWorker(staleWorker.worker_id);
+      deleteRuntimeKv("worker", staleWorker.worker_id, SESSION_FILE_KV_KEY);
+      return;
+    }
+    const worker = findActiveWorkerForCurrentProcess(projectRoot);
+    if (worker) deleteRuntimeKv("worker", worker.worker_id, SESSION_FILE_KV_KEY);
+
+    const stale = findStaleWorkerForProject(projectRoot);
+    if (stale) {
+      markWorkerStopping(stale.worker_id);
+      deleteRuntimeKv("worker", stale.worker_id, SESSION_FILE_KV_KEY);
+    }
   } catch {
     // Best-effort.
   }
+}
+
+/**
+ * Clear a stale DB-backed worker lock after readCrashLock/findStaleWorkerForProject
+ * has identified a dead worker. Unlike clearLock(), this targets the stale
+ * worker row instead of the current process's active worker.
+ */
+export function clearStaleWorkerLock(basePath: string): void {
+  clearLegacyLockFile(basePath);
 
   if (!isDbAvailable()) return;
   try {
     const projectRoot = normalizeRealPath(basePath);
-    const worker = findActiveWorkerForCurrentProcess(projectRoot);
+    const worker = findStaleWorkerForProject(projectRoot);
     if (!worker) return;
+    markLatestActiveForWorkerCanceled(worker.worker_id, "crash-recovered");
+    markWorkerCrashed(worker.worker_id);
     deleteRuntimeKv("worker", worker.worker_id, SESSION_FILE_KV_KEY);
   } catch {
     // Best-effort.

package/src/resources/extensions/gsd/db/milestone-leases.ts

@@ -255,6 +255,32 @@ export function releaseMilestoneLease(
   });
 }
 
+/**
+ * Force-release all held leases for a worker.
+ *
+ * Used by crash recovery once PID liveness has confirmed the worker is dead.
+ * No fencing token is required because this path is cleanup-only for a
+ * non-running process.
+ */
+export function forceReleaseLeasesForWorker(workerId: string): number {
+  if (!isDbAvailable()) return 0;
+  const db = _getAdapter()!;
+  let changes = 0;
+  transaction(() => {
+    const result = db.prepare(
+      `UPDATE milestone_leases
+       SET status = 'released'
+       WHERE worker_id = :worker_id
+         AND status = 'held'`,
+    ).run({ ":worker_id": workerId });
+    changes =
+      typeof (result as { changes?: unknown }).changes === "number"
+        ? (result as { changes: number }).changes
+        : 0;
+  });
+  return changes;
+}
+
 /**
  * Read current lease row for diagnostics. Returns null if no row exists.
  */

package/src/resources/extensions/gsd/db/unit-dispatches.ts

@@ -524,17 +524,18 @@ export function getRecentUnitKeysForProjectRoot(
   if (!isDbAvailable()) return [];
   const db = _getAdapter()!;
   const rows = db.prepare(
-    `SELECT ud.unit_id
+    `SELECT ud.unit_type, ud.unit_id
      FROM unit_dispatches ud
      INNER JOIN workers w ON w.worker_id = ud.worker_id
      WHERE w.project_root_realpath = :project_root_realpath
+       AND w.status != 'crashed'
      ORDER BY ud.started_at DESC, ud.id DESC
      LIMIT :limit`,
   ).all({
     ":project_root_realpath": projectRootRealpath,
     ":limit": limit,
-  }) as Array<{ unit_id: string }>;
-  return rows.reverse().map((r) => ({ key: r.unit_id }));
+  }) as Array<{ unit_type: string; unit_id: string }>;
+  return rows.reverse().map((r) => ({ key: `${r.unit_type}/${r.unit_id}` }));
 }
 
 /**

package/src/resources/extensions/gsd/db-writer.ts

@@ -235,14 +235,63 @@ export async function nextDecisionId(): Promise<string> {
   }
 }
 
-/** Synchronous variant for use inside db.transaction(). */
-function nextDecisionIdSync(adapter: ReturnType<typeof import('./gsd-db.js')._getAdapter>): string {
+/**
+ * ADR-013 Stage 3: compute the next `D###` identifier across both the legacy
+ * `decisions` table AND the `memories.structured_fields.sourceDecisionId`
+ * surface. Returns the max numeric suffix from either side + 1, three-digit
+ * padded.
+ *
+ * Used by `saveDecisionToDb` once writes to the `decisions` table stop —
+ * new decisions live only in memories, but historical IDs sit in both
+ * places during the cutover bake. The cross-surface max keeps IDs
+ * monotonic and avoids collisions on the next save.
+ */
+function nextDecisionIdAcrossSurfaces(
+  adapter: ReturnType<typeof import('./gsd-db.js')._getAdapter>,
+): string {
   if (!adapter) return 'D001';
-  const row = adapter
-    .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM decisions')
-    .get();
-  const maxNum = row ? (row['max_num'] as number | null) : null;
-  if (maxNum == null || isNaN(maxNum)) return 'D001';
+
+  let maxNum = 0;
+
+  // Legacy table — best-effort.
+  try {
+    const row = adapter
+      .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM decisions')
+      .get();
+    const candidate = row ? (row['max_num'] as number | null) : null;
+    if (typeof candidate === 'number' && Number.isFinite(candidate)) {
+      maxNum = Math.max(maxNum, candidate);
+    }
+  } catch {
+    // fall through to memory-only
+  }
+
+  // Memory surface: scan structuredFields.sourceDecisionId for D### values.
+  // SQLite LIKE on the JSON-stringified field is sufficient — rows tagged
+  // with sourceDecisionId are bounded by the decisions count.
+  try {
+    const rows = adapter
+      .prepare(
+        "SELECT structured_fields FROM memories WHERE structured_fields LIKE '%\"sourceDecisionId\":\"D%'",
+      )
+      .all() as Array<{ structured_fields: string | null }>;
+    for (const row of rows) {
+      if (!row.structured_fields) continue;
+      let sf: Record<string, unknown>;
+      try {
+        sf = JSON.parse(row.structured_fields) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      const sourceId = sf['sourceDecisionId'];
+      if (typeof sourceId !== 'string' || !sourceId.startsWith('D')) continue;
+      const num = parseInt(sourceId.slice(1), 10);
+      if (Number.isFinite(num) && num > maxNum) maxNum = num;
+    }
+  } catch {
+    // best-effort
+  }
+
   const next = maxNum + 1;
   return `D${String(next).padStart(3, '0')}`;
 }
@@ -416,6 +465,16 @@ export interface SaveDecisionFields {
   source?: string;
 }
 
+type NormalizedSaveDecisionFields = Omit<
+  SaveDecisionFields,
+  'when_context' | 'revisable' | 'made_by' | 'source'
+> & {
+  when_context: string;
+  revisable: string;
+  made_by: NonNullable<SaveDecisionFields['made_by']>;
+  source: string;
+};
+
 /**
  * Save a new decision to DB and regenerate DECISIONS.md.
  * Auto-assigns the next ID via nextDecisionId().
@@ -445,44 +504,59 @@ export async function saveDecisionToDb(
 
   try {
     const db = await import('./gsd-db.js');
-
     const adapter = db._getAdapter();
+    const normalized: NormalizedSaveDecisionFields = {
+      ...fields,
+      when_context: fields.when_context ?? '',
+      revisable: fields.revisable ?? 'Yes',
+      made_by: fields.made_by ?? 'agent',
+      source: fields.source ?? 'discussion',
+    };
 
-    const id = db.transaction(() => {
-      const nextId = nextDecisionIdSync(adapter);
-      db.upsertDecision({
-        id: nextId,
-        when_context: fields.when_context ?? '',
-        scope: fields.scope,
-        decision: fields.decision,
-        choice: fields.choice,
-        rationale: fields.rationale,
-        revisable: fields.revisable ?? 'Yes',
-        made_by: fields.made_by ?? 'agent',
-        source: fields.source ?? 'discussion',
-        superseded_by: null,
+    // ADR-013 Stage 3 (destructive): writes to the `decisions` table stop
+    // here. New decisions live only in the `memories` table; the projection
+    // regen below sources from memories (Stage 2a). The decisions table
+    // remains for backwards-compat reads (queryDecisions, md-importer,
+    // commands-inspect, workflow-manifest) until #5756 drops it.
+    //
+    // Reversal: a code revert of this change restores the upsertDecision
+    // call. Memory rows written between merge and revert stay durable; the
+    // legacy table simply doesn't grow during the cutover window.
+    const id = nextDecisionIdAcrossSurfaces(adapter);
+
+    // The mirror-to-memories write is what persists the new decision. Must
+    // run before the projection regen — the regen sources from memories
+    // (Stage 2a) and would otherwise miss the just-saved decision. Pass
+    // the normalized field set so defaults (revisable, made_by, source)
+    // are recorded on the memory row.
+    await mirrorDecisionToMemory(id, normalized);
+
+    // Fetch all decisions (including superseded for the full register).
+    // ADR-013 Stage 2a: source from the `memories` table. The Phase 5
+    // dual-write keeps memories in sync with each decision save; the backfill
+    // (memory-backfill.ts) absorbs the historical chain and drift-heals
+    // superseded_by on every session start.
+    const { getAllDecisionsFromMemories } = await import('./context-store.js');
+    let allDecisions: Decision[] = getAllDecisionsFromMemories();
+    if (!allDecisions.some(d => d.id === id)) {
+      logWarning('projection', 'just-saved decision missing from memories after mirror; injecting fallback for projection', {
+        fn: 'saveDecisionToDb',
+        decisionId: id,
       });
-
-
-      return nextId;
-    });
-
-    // Fetch all decisions (including superseded for the full register)
-    let allDecisions: Decision[] = [];
-    if (adapter) {
-      const rows = adapter.prepare('SELECT * FROM decisions ORDER BY seq').all();
-      allDecisions = rows.map(row => ({
-        seq: row['seq'] as number,
-        id: row['id'] as string,
-        when_context: row['when_context'] as string,
-        scope: row['scope'] as string,
-        decision: row['decision'] as string,
-        choice: row['choice'] as string,
-        rationale: row['rationale'] as string,
-        revisable: row['revisable'] as string,
-        made_by: (row['made_by'] as string as import('./types.js').DecisionMadeBy) ?? 'agent',
-        superseded_by: (row['superseded_by'] as string) ?? null,
-      }));
+      const nextSeq = allDecisions.reduce((max, d) => Math.max(max, d.seq ?? 0), 0) + 1;
+      const fallback: Decision = {
+        seq: nextSeq,
+        id,
+        when_context: normalized.when_context,
+        scope: normalized.scope,
+        decision: normalized.decision,
+        choice: normalized.choice,
+        rationale: normalized.rationale,
+        revisable: normalized.revisable,
+        made_by: normalized.made_by,
+        superseded_by: null,
+      };
+      allDecisions = [...allDecisions, fallback];
     }
 
     const filePath = resolveGsdRootFile(basePath, 'DECISIONS');
@@ -538,48 +612,6 @@ export async function saveDecisionToDb(
     clearPathCache();
     clearParseCache();
 
-    // ADR-013 dual-write: keep the memory store in sync with every decision
-    // persisted via the legacy gsd_save_decision path. Without this, prompts
-    // that still call gsd_save_decision (discuss.md, plan-milestone.md,
-    // plan-slice.md, et al.) would create decisions rows invisible to
-    // memory_query and loadMemoryBlock.
-    // Best-effort — never throw, never roll back the decision on failure.
-    try {
-      const { createMemory } = await import('./memory-store.js');
-      const decisionText = (fields.decision ?? '').trim();
-      const choiceText = (fields.choice ?? '').trim();
-      const rationaleText = (fields.rationale ?? '').trim();
-      const contentParts: string[] = [];
-      if (decisionText) contentParts.push(decisionText);
-      if (choiceText) contentParts.push(`Chose: ${choiceText}.`);
-      if (rationaleText) contentParts.push(`Rationale: ${rationaleText}.`);
-      const content = contentParts.join(' ').slice(0, 600);
-      if (content) {
-        createMemory({
-          category: 'architecture',
-          content,
-          scope: fields.scope || 'project',
-          confidence: 0.85,
-          structuredFields: {
-            sourceDecisionId: id,
-            when_context: fields.when_context ?? '',
-            scope: fields.scope,
-            decision: fields.decision,
-            choice: fields.choice,
-            rationale: fields.rationale,
-            made_by: fields.made_by ?? 'agent',
-            revisable: fields.revisable ?? '',
-          },
-        });
-      }
-    } catch (mirrorErr) {
-      logError('manifest', 'memory-store mirror write failed (non-fatal)', {
-        fn: 'saveDecisionToDb',
-        decisionId: id,
-        error: String((mirrorErr as Error).message),
-      });
-    }
-
     return { id };
   } catch (err) {
     logError('manifest', 'saveDecisionToDb failed', { fn: 'saveDecisionToDb', error: String((err as Error).message) });
@@ -589,6 +621,57 @@ export async function saveDecisionToDb(
   }
 }
 
+/**
+ * ADR-013 dual-write — mirror a freshly-saved decision into the `memories`
+ * table so the memory store remains the single source of truth for the
+ * DECISIONS.md projection (Stage 2a) and for prompt-inline reads (Stage 1).
+ *
+ * Best-effort mirror: logs failures without throwing to avoid blocking saves.
+ * Caller invokes this AFTER the decisions-table write completes and
+ * BEFORE the projection regen — the regen sources from memories and would
+ * otherwise miss the just-saved decision.
+ */
+async function mirrorDecisionToMemory(
+  id: string,
+  normalizedFields: NormalizedSaveDecisionFields,
+): Promise<boolean> {
+  try {
+    const { createMemory } = await import('./memory-store.js');
+    const { synthesizeDecisionMemoryContent } = await import('./memory-backfill.js');
+    const content = synthesizeDecisionMemoryContent(normalizedFields);
+    if (!content) return false;
+
+    createMemory({
+      category: 'architecture',
+      content,
+      scope: normalizedFields.scope || 'project',
+      confidence: 0.85,
+      structuredFields: {
+        sourceDecisionId: id,
+        when_context: normalizedFields.when_context,
+        scope: normalizedFields.scope,
+        decision: normalizedFields.decision,
+        choice: normalizedFields.choice,
+        rationale: normalizedFields.rationale,
+        made_by: normalizedFields.made_by,
+        revisable: normalizedFields.revisable,
+        // New decisions are always written as active; md-importer can later
+        // set superseded_by on the source decision row, and the backfill's
+        // drift auto-heal pass propagates that update to this memory.
+        superseded_by: null,
+      },
+    });
+    return true;
+  } catch (mirrorErr) {
+    logError('manifest', 'memory-store mirror write failed', {
+      fn: 'saveDecisionToDb',
+      decisionId: id,
+      error: String((mirrorErr as Error).message),
+    });
+    return false;
+  }
+}
+
 /**
  * Extract a milestone/slice reference from a deferral decision.
  *

package/src/resources/extensions/gsd/dispatch-guard.ts

@@ -5,7 +5,7 @@ import { findMilestoneIds } from "./guided-flow.js";
 import { parseUnitId } from "./unit-id.js";
 import { isDbAvailable, getMilestoneSlices, getMilestone } from "./gsd-db.js";
 import { parseRoadmap } from "./parsers-legacy.js";
-import { isClosedStatus } from "./status-guards.js";
+import { isClosedStatus, isSkippedForDispatch } from "./status-guards.js";
 import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import { readFileSync } from "node:fs";
 
@@ -58,7 +58,7 @@ export function getPriorSliceCompletionBlocker(
     //      DB-backed projects must not treat SUMMARY.md as authoritative.
     if (isDbAvailable()) {
       const milestoneRow = getMilestone(mid);
-      if (milestoneRow && isClosedStatus(milestoneRow.status)) continue;
+      if (milestoneRow && isSkippedForDispatch(milestoneRow.status)) continue;
     } else {
       const summaryPath = resolveMilestoneFile(base, mid, "SUMMARY");
       let summaryContent: string | null = null;

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -100,7 +100,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 - `skill_rules`: situational rules with a human-readable `when` trigger and one or more of `use`, `prefer`, or `avoid`.
 
-- `custom_instructions`: extra durable instructions related to skill use. For operational project knowledge (recurring rules, gotchas, patterns), use `.gsd/KNOWLEDGE.md` instead — it's injected into every agent prompt automatically and agents can append to it during execution.
+- `custom_instructions`: extra durable instructions related to skill use. For operational project knowledge, use `.gsd/KNOWLEDGE.md` instead. Rules are file-canonical; patterns and lessons are persisted to the `memories` table and projected back into `KNOWLEDGE.md` on the next session start.
 
 - `language`: preferred response language for all GSD interactions. Accepts any language name or code — `"Chinese"`, `"zh"`, `"German"`, `"de"`, `"日本語"`, etc. When set, GSD injects "Always respond in \<language\>" into every agent's system prompt, including after `/clear`. Quickest way to set it: `/gsd language <name>`. To clear: `/gsd language off`.