gsd-pi 2.76.0-dev.fe143342a → 2.77.0-dev.1d17f366c

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

@@ -3,9 +3,10 @@
 import { resolveMilestoneFile } from "./paths.js";
 import { findMilestoneIds } from "./guided-flow.js";
 import { parseUnitId } from "./unit-id.js";
-import { isDbAvailable, getMilestoneSlices } from "./gsd-db.js";
+import { isDbAvailable, getMilestoneSlices, getMilestone } from "./gsd-db.js";
 import { parseRoadmap } from "./parsers-legacy.js";
 import { isClosedStatus } from "./status-guards.js";
+import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import { readFileSync } from "node:fs";
 
 const SLICE_DISPATCH_TYPES = new Set([
@@ -47,7 +48,30 @@ export function getPriorSliceCompletionBlocker(
 
   for (const mid of milestoneIds) {
     if (resolveMilestoneFile(base, mid, "PARKED")) continue;
-    if (resolveMilestoneFile(base, mid, "SUMMARY")) continue;
+
+    // DB/SUMMARY completion check (#4663 sibling to #4658).
+    // Prior behavior treated any SUMMARY file on disk as proof of milestone
+    // completion, which is wrong when the SUMMARY is a failure-path report
+    // (verification FAILED, blocker placeholder, etc.). Resolve as follows:
+    //   1. When DB is available and status is closed → skip (authoritative).
+    //   2. When SUMMARY exists but looks like a failure/blocker report →
+    //      do not short-circuit; fall through to the slice-level check so
+    //      the guard can still block dependents of an active milestone.
+    //   3. Otherwise (SUMMARY without failure markers) → skip. Preserves
+    //      the #1716 contract where a completed milestone with unchecked
+    //      remediation slices is still treated as done.
+    const summaryPath = resolveMilestoneFile(base, mid, "SUMMARY");
+    if (isDbAvailable()) {
+      const milestoneRow = getMilestone(mid);
+      if (milestoneRow && isClosedStatus(milestoneRow.status)) continue;
+    }
+    if (summaryPath) {
+      let summaryContent: string | null = null;
+      try { summaryContent = readFileSync(summaryPath, "utf-8"); } catch { /* ignore */ }
+      if (!summaryContent || classifyMilestoneSummaryContent(summaryContent) !== "failure") {
+        continue;
+      }
+    }
 
     // Normalised slice list from DB or file fallback
     type NormSlice = { id: string; done: boolean; depends: string[] };

package/src/resources/extensions/gsd/file-lock.ts

@@ -1,12 +1,21 @@
 import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
 
-function _require(name: string) {
+// The file-lock module is loaded in both CJS builds and ESM sources. Under ESM
+// the bare `require` identifier is not defined, so we always go through
+// createRequire. We try the current module's resolution context first and fall
+// back to the installed gsd-pi package if we are running from a consumer
+// project that does not hoist proper-lockfile.
+const localRequire = createRequire(import.meta.url);
+
+function _require(name: string): any {
   try {
-    return require(name);
+    return localRequire(name);
   } catch {
     try {
-      const gsdPiRequire = require("module").createRequire(
-        require("path").join(process.cwd(), "node_modules", "gsd-pi", "index.js")
+      const gsdPiRequire = createRequire(
+        join(process.cwd(), "node_modules", "gsd-pi", "index.js"),
       );
       return gsdPiRequire(name);
     } catch {
@@ -15,43 +24,107 @@ function _require(name: string) {
   }
 }
 
-export function withFileLockSync<T>(filePath: string, fn: () => T): T {
+export type OnLocked = "fail" | "skip";
+
+export interface FileLockOptions {
+  /**
+   * Behavior when the lock cannot be acquired after retries (ELOCKED).
+   * - "fail" (default): rethrow the ELOCKED error so the caller can react.
+   * - "skip": run fn() unlocked. Only choose this for best-effort writes
+   *   that genuinely tolerate contention (e.g. high-frequency audit appends
+   *   where dropping one entry is acceptable). Silent unlocked execution was
+   *   the legacy behavior and is a correctness hazard for shared state.
+   */
+  onLocked?: OnLocked;
+  /** proper-lockfile retries (default 5). */
+  retries?: number;
+  /** proper-lockfile stale threshold in ms (default 10000). */
+  stale?: number;
+}
+
+const DEFAULT_RETRIES = 5;
+const DEFAULT_STALE_MS = 10000;
+const SYNC_RETRY_DELAY_MS = 50;
+
+// Block the thread for `ms` milliseconds without spinning the CPU.
+// Used by the sync lock retry loop, since proper-lockfile's lockSync does not
+// accept a `retries` option (only the async `lock` does).
+function sleepSync(ms: number): void {
+  if (ms <= 0) return;
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function acquireLockSyncWithRetry(
+  lockfile: any,
+  filePath: string,
+  retries: number,
+  stale: number,
+): () => void {
+  let lastErr: any;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      return lockfile.lockSync(filePath, { stale });
+    } catch (err: any) {
+      lastErr = err;
+      if (err?.code !== "ELOCKED") throw err;
+      if (attempt < retries) sleepSync(SYNC_RETRY_DELAY_MS);
+    }
+  }
+  throw lastErr;
+}
+
+export function withFileLockSync<T>(
+  filePath: string,
+  fn: () => T,
+  opts: FileLockOptions = {},
+): T {
   const lockfile = _require("proper-lockfile");
   if (!lockfile) return fn();
 
   if (!existsSync(filePath)) return fn();
 
+  const retries = opts.retries ?? DEFAULT_RETRIES;
+  const stale = opts.stale ?? DEFAULT_STALE_MS;
+  const onLocked: OnLocked = opts.onLocked ?? "fail";
+
   try {
-    const release = lockfile.lockSync(filePath, { retries: 5, stale: 10000 });
+    const release = acquireLockSyncWithRetry(lockfile, filePath, retries, stale);
     try {
       return fn();
     } finally {
       release();
     }
   } catch (err: any) {
-    if (err.code === "ELOCKED") {
-      // Could not get lock after retries, let's fallback to un-locked instead of crashing the whole state machine
+    if (err?.code === "ELOCKED" && onLocked === "skip") {
       return fn();
     }
     throw err;
   }
 }
 
-export async function withFileLock<T>(filePath: string, fn: () => Promise<T> | T): Promise<T> {
+export async function withFileLock<T>(
+  filePath: string,
+  fn: () => Promise<T> | T,
+  opts: FileLockOptions = {},
+): Promise<T> {
   const lockfile = _require("proper-lockfile");
   if (!lockfile) return await fn();
 
   if (!existsSync(filePath)) return await fn();
 
+  const retries = opts.retries ?? DEFAULT_RETRIES;
+  const stale = opts.stale ?? DEFAULT_STALE_MS;
+  const onLocked: OnLocked = opts.onLocked ?? "fail";
+
   try {
-    const release = await lockfile.lock(filePath, { retries: 5, stale: 10000 });
+    const release = await lockfile.lock(filePath, { retries, stale });
     try {
       return await fn();
     } finally {
       await release();
     }
   } catch (err: any) {
-    if (err.code === "ELOCKED") {
+    if (err?.code === "ELOCKED" && onLocked === "skip") {
       return await fn();
     }
     throw err;

package/src/resources/extensions/gsd/git-service.ts

@@ -210,6 +210,7 @@ export interface PreMergeCheckResult {
  */
 export const RUNTIME_EXCLUSION_PATHS: readonly string[] = [
   ".gsd/activity/",
+  ".gsd/audit/",
   ".gsd/forensics/",
   ".gsd/runtime/",
   ".gsd/worktrees/",

package/src/resources/extensions/gsd/gitignore.ts

@@ -26,6 +26,7 @@ import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
  */
 const GSD_RUNTIME_PATTERNS = [
   ".gsd/activity/",
+  ".gsd/audit/",
   ".gsd/forensics/",
   ".gsd/runtime/",
   ".gsd/worktrees/",
@@ -48,6 +49,7 @@ const BASELINE_PATTERNS = [
   // ── GSD state directory (symlink to external storage) ──
   ".gsd",
   ".gsd-id",
+  ".mcp.json",
   ".bg-shell/",
 
   // ── OS junk ──
@@ -319,4 +321,3 @@ custom_instructions:
   writeFileSync(preferencesPath, template, "utf-8");
   return true;
 }
-

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

@@ -180,7 +180,7 @@ function openRawDb(path: string): unknown {
   return new Database(path);
 }
 
-const SCHEMA_VERSION = 21;
+const SCHEMA_VERSION = 22;
 
 function indexExists(db: DbAdapter, name: string): boolean {
   return !!db.prepare(
@@ -559,18 +559,6 @@ function initSchema(db: DbAdapter, fileBacked: boolean): void {
 
     db.exec("CREATE INDEX IF NOT EXISTS idx_memories_active ON memories(superseded_by)");
 
-    // Existing DBs may arrive here before migrateSchema() has added columns
-    // that fresh installs already have. Add only columns needed by bootstrap
-    // indexes so old DBs can open far enough for the normal migration chain.
-    ensureBootstrapIndexColumns(db);
-
-    if (columnExists(db, "memories", "scope")) {
-      db.exec("CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope)");
-    }
-    db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_kind ON memory_sources(kind)");
-    db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_scope ON memory_sources(scope)");
-    db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_from ON memory_relations(from_id)");
-    db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_to ON memory_relations(to_id)");
     db.exec("CREATE INDEX IF NOT EXISTS idx_replan_history_milestone ON replan_history(milestone_id, created_at)");
 
     // v13 indexes — hot-path dispatch queries
@@ -588,9 +576,6 @@ function initSchema(db: DbAdapter, fileBacked: boolean): void {
     db.exec("CREATE INDEX IF NOT EXISTS idx_turn_git_tx_turn ON turn_git_transactions(trace_id, turn_id)");
     db.exec("CREATE INDEX IF NOT EXISTS idx_audit_events_trace ON audit_events(trace_id, ts)");
     db.exec("CREATE INDEX IF NOT EXISTS idx_audit_events_turn ON audit_events(trace_id, turn_id, ts)");
-    // ADR-011 Phase 2 — also created by the v17 migration; fresh installs
-    // skip migrations so the index must be created here too.
-    db.exec("CREATE INDEX IF NOT EXISTS idx_tasks_escalation_pending ON tasks(milestone_id, slice_id, escalation_pending)");
 
     db.exec(`CREATE VIEW IF NOT EXISTS active_decisions AS SELECT * FROM decisions WHERE superseded_by IS NULL`);
     db.exec(`CREATE VIEW IF NOT EXISTS active_requirements AS SELECT * FROM requirements WHERE superseded_by IS NULL`);
@@ -598,6 +583,17 @@ function initSchema(db: DbAdapter, fileBacked: boolean): void {
 
     const existing = db.prepare("SELECT count(*) as cnt FROM schema_version").get();
     if (existing && (existing["cnt"] as number) === 0) {
+      // Fresh install — all tables are created above with the full current schema,
+      // so it is safe to create all migration-specific indexes here.  For existing
+      // databases these indexes are created inside the individual migration guards
+      // in migrateSchema() after the corresponding columns have been added.
+      db.exec("CREATE INDEX IF NOT EXISTS idx_tasks_escalation_pending ON tasks(milestone_id, slice_id, escalation_pending)");
+      db.exec("CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope)");
+      db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_kind ON memory_sources(kind)");
+      db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_scope ON memory_sources(scope)");
+      db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_from ON memory_relations(from_id)");
+      db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_to ON memory_relations(to_id)");
+
       db.prepare(
         "INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)",
       ).run({
@@ -674,14 +670,6 @@ function ensureColumn(db: DbAdapter, table: string, column: string, ddl: string)
   if (!columnExists(db, table, column)) db.exec(ddl);
 }
 
-function ensureBootstrapIndexColumns(db: DbAdapter): void {
-  ensureColumn(db, "memories", "scope", `ALTER TABLE memories ADD COLUMN scope TEXT NOT NULL DEFAULT 'project'`);
-  ensureColumn(db, "memories", "tags", `ALTER TABLE memories ADD COLUMN tags TEXT NOT NULL DEFAULT '[]'`);
-  ensureColumn(db, "memory_sources", "scope", `ALTER TABLE memory_sources ADD COLUMN scope TEXT NOT NULL DEFAULT 'project'`);
-  ensureColumn(db, "memory_sources", "tags", `ALTER TABLE memory_sources ADD COLUMN tags TEXT NOT NULL DEFAULT '[]'`);
-  ensureColumn(db, "tasks", "escalation_pending", `ALTER TABLE tasks ADD COLUMN escalation_pending INTEGER NOT NULL DEFAULT 0`);
-}
-
 function migrateSchema(db: DbAdapter): void {
   const row = db.prepare("SELECT MAX(version) as v FROM schema_version").get();
   const currentVersion = row ? (row["v"] as number) : 0;
@@ -949,19 +937,24 @@ function migrateSchema(db: DbAdapter): void {
     }
 
     if (currentVersion < 12) {
+      // NOTE: The original DDL used COALESCE(task_id, '') in the PRIMARY KEY
+      // expression, which is invalid SQLite syntax and causes startup errors on
+      // DBs that migrate through v12. The corrected DDL uses
+      // task_id TEXT NOT NULL DEFAULT '' with a plain column list PK. DBs that
+      // were created with the broken DDL are repaired by the v22 migration below.
       db.exec(`
         CREATE TABLE IF NOT EXISTS quality_gates (
           milestone_id TEXT NOT NULL,
           slice_id TEXT NOT NULL,
           gate_id TEXT NOT NULL,
           scope TEXT NOT NULL DEFAULT 'slice',
-          task_id TEXT DEFAULT NULL,
+          task_id TEXT NOT NULL DEFAULT '',
           status TEXT NOT NULL DEFAULT 'pending',
           verdict TEXT NOT NULL DEFAULT '',
           rationale TEXT NOT NULL DEFAULT '',
           findings TEXT NOT NULL DEFAULT '',
           evaluated_at TEXT DEFAULT NULL,
-          PRIMARY KEY (milestone_id, slice_id, gate_id, COALESCE(task_id, '')),
+          PRIMARY KEY (milestone_id, slice_id, gate_id, task_id),
           FOREIGN KEY (milestone_id, slice_id) REFERENCES slices(milestone_id, id)
         )
       `);
@@ -1119,6 +1112,10 @@ function migrateSchema(db: DbAdapter): void {
           tags TEXT NOT NULL DEFAULT '[]'
         )
       `);
+      // If memory_sources already existed before v18 (created by an earlier
+      // version of initSchema that lacked scope/tags), add the missing columns.
+      ensureColumn(db, "memory_sources", "scope", `ALTER TABLE memory_sources ADD COLUMN scope TEXT NOT NULL DEFAULT 'project'`);
+      ensureColumn(db, "memory_sources", "tags", `ALTER TABLE memory_sources ADD COLUMN tags TEXT NOT NULL DEFAULT '[]'`);
       db.exec("CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope)");
       db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_kind ON memory_sources(kind)");
       db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_scope ON memory_sources(scope)");
@@ -1189,6 +1186,52 @@ function migrateSchema(db: DbAdapter): void {
       });
     }
 
+    if (currentVersion < 22) {
+      // v22: Repair quality_gates tables that were created by the broken v12
+      // migration (which used COALESCE(task_id, '') as a PK expression — invalid
+      // SQLite DDL). Those DBs have task_id nullable (dflt_value NULL, notnull 0).
+      // Rebuild the table with the correct schema, migrating existing rows via
+      // COALESCE so no data is lost.
+      const qgInfo = db.prepare("PRAGMA table_info(quality_gates)").all() as Array<Record<string, unknown>>;
+      const taskIdCol = qgInfo.find((r) => r["name"] === "task_id");
+      const needsRepair = taskIdCol && (taskIdCol["notnull"] === 0 || taskIdCol["notnull"] === "0");
+      if (needsRepair) {
+        db.exec(`
+          CREATE TABLE quality_gates_new (
+            milestone_id TEXT NOT NULL,
+            slice_id TEXT NOT NULL,
+            gate_id TEXT NOT NULL,
+            scope TEXT NOT NULL DEFAULT 'slice',
+            task_id TEXT NOT NULL DEFAULT '',
+            status TEXT NOT NULL DEFAULT 'pending',
+            verdict TEXT NOT NULL DEFAULT '',
+            rationale TEXT NOT NULL DEFAULT '',
+            findings TEXT NOT NULL DEFAULT '',
+            evaluated_at TEXT DEFAULT NULL,
+            PRIMARY KEY (milestone_id, slice_id, gate_id, task_id),
+            FOREIGN KEY (milestone_id, slice_id) REFERENCES slices(milestone_id, id)
+          )
+        `);
+        db.exec(`
+          INSERT OR IGNORE INTO quality_gates_new
+            (milestone_id, slice_id, gate_id, scope, task_id, status, verdict, rationale, findings, evaluated_at)
+          SELECT milestone_id, slice_id, gate_id, scope, COALESCE(task_id, ''), status, verdict, rationale, findings, evaluated_at
+          FROM quality_gates
+        `);
+        db.exec("DROP TABLE quality_gates");
+        db.exec("ALTER TABLE quality_gates_new RENAME TO quality_gates");
+        db.exec("CREATE INDEX IF NOT EXISTS idx_quality_gates_pending ON quality_gates(milestone_id, slice_id, status)");
+      }
+      // Ensure scope column exists on quality_gates and assessments (guard
+      // against DBs that somehow lack it after a partial migration).
+      ensureColumn(db, "quality_gates", "scope", "ALTER TABLE quality_gates ADD COLUMN scope TEXT NOT NULL DEFAULT 'slice'");
+      ensureColumn(db, "assessments", "scope", "ALTER TABLE assessments ADD COLUMN scope TEXT NOT NULL DEFAULT ''");
+      db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
+        ":version": 22,
+        ":applied_at": new Date().toISOString(),
+      });
+    }
+
     db.exec("COMMIT");
   } catch (err) {
     db.exec("ROLLBACK");
@@ -2733,7 +2776,10 @@ export function reconcileWorktreeDb(
           FROM wt.artifacts
         `).run());
 
-        // Merge milestones — worktree may have updated status/planning fields
+        // Merge milestones — worktree may have updated status/planning fields.
+        // Never downgrade status: complete > active > pre-planning (#4372).
+        // A stale worktree may carry an older 'active' status for a milestone
+        // that the main DB has already marked 'complete'; preserve the higher status.
         merged.milestones = countChanges(adapter.prepare(`
           INSERT OR REPLACE INTO milestones (
             id, title, status, depends_on, created_at, completed_at,
@@ -2741,11 +2787,25 @@ export function reconcileWorktreeDb(
             verification_contract, verification_integration, verification_operational, verification_uat,
             definition_of_done, requirement_coverage, boundary_map_markdown
           )
-          SELECT id, title, status, depends_on, created_at, completed_at,
-                 vision, success_criteria, key_risks, proof_strategy,
-                 verification_contract, verification_integration, verification_operational, verification_uat,
-                 definition_of_done, requirement_coverage, boundary_map_markdown
-          FROM wt.milestones
+          SELECT w.id, w.title,
+                 CASE
+                   WHEN m.status IN ('complete', 'done') AND w.status NOT IN ('complete', 'done')
+                   THEN m.status ELSE w.status
+                 END,
+                 w.depends_on,
+                 CASE
+                   WHEN m.status IN ('complete', 'done') AND w.status NOT IN ('complete', 'done')
+                   THEN m.created_at ELSE w.created_at
+                 END,
+                 CASE
+                   WHEN m.status IN ('complete', 'done') AND w.status NOT IN ('complete', 'done')
+                   THEN m.completed_at ELSE w.completed_at
+                 END,
+                 w.vision, w.success_criteria, w.key_risks, w.proof_strategy,
+                 w.verification_contract, w.verification_integration, w.verification_operational, w.verification_uat,
+                 w.definition_of_done, w.requirement_coverage, w.boundary_map_markdown
+          FROM wt.milestones w
+          LEFT JOIN milestones m ON m.id = w.id
         `).run());
 
         // Merge slices — preserve worktree progress but never downgrade completed status (#2558).

package/src/resources/extensions/gsd/guided-flow-queue.ts

@@ -18,6 +18,7 @@ import {
   resolveGsdRootFile, relGsdRootFile, relSliceFile,
 } from "./paths.js";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { atomicWriteSync } from "./atomic-write.js";
 import { nativeAddPaths, nativeCommit } from "./native-git-bridge.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { loadQueueOrder, sortByQueueOrder, saveQueueOrder } from "./queue-order.js";
@@ -435,5 +436,7 @@ function syncProjectMdSequence(
   const separatorLine = lines[tableStart + 1];
   const newTable = [headerLine, separatorLine, ...newRows];
   lines.splice(tableStart, tableEnd - tableStart, ...newTable);
-  writeFileSync(projectPath, lines.join("\n"), "utf-8");
+  // Atomic write: tmp+rename avoids a torn PROJECT.md appearing dirty in
+  // another worktree's working tree during a concurrent /gsd auto merge.
+  atomicWriteSync(projectPath, lines.join("\n"), "utf-8");
 }