gsd-pi 2.78.1-dev.eccf86e27 → 2.79.0-dev.487011134

package/src/resources/extensions/gsd/tests/uok-contracts.test.ts

@@ -1,5 +1,10 @@
+// GSD2 UOK Contract Versioning and DB Authority Tests
+
 import test from "node:test";
 import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
 import type {
   AuditEventEnvelope,
@@ -11,8 +16,17 @@ import type {
   WriteRecord,
   WriterToken,
 } from "../uok/contracts.ts";
-import { buildAuditEnvelope } from "../uok/audit.ts";
+import {
+  CURRENT_UOK_CONTRACT_VERSION,
+  normalizeAuditEvent,
+  validateAuditEvent,
+  validateDispatchEnvelope,
+  validateTurnResult,
+} from "../uok/contracts.ts";
+import { buildAuditEnvelope, emitUokAuditEvent } from "../uok/audit.ts";
 import { buildDispatchEnvelope, explainDispatch } from "../uok/dispatch-envelope.ts";
+import { buildTurnTimeline } from "../uok/timeline.ts";
+import { _getAdapter, closeDatabase, openDatabase } from "../gsd-db.ts";
 
 test("uok contracts serialize/deserialize turn envelopes", () => {
   const contract: TurnContract = {
@@ -37,6 +51,7 @@ test("uok contracts serialize/deserialize turn envelopes", () => {
   };
 
   const result: TurnResult = {
+    version: CURRENT_UOK_CONTRACT_VERSION,
     traceId: contract.traceId,
     turnId: contract.turnId,
     iteration: contract.iteration,
@@ -56,8 +71,10 @@ test("uok contracts serialize/deserialize turn envelopes", () => {
 
   const roundTrip = JSON.parse(JSON.stringify(result)) as TurnResult;
   assert.equal(roundTrip.turnId, "turn-1");
+  assert.equal(roundTrip.version, CURRENT_UOK_CONTRACT_VERSION);
   assert.equal(roundTrip.gateResults?.[0]?.gateId, "Q3");
   assert.equal(roundTrip.phaseResults.length, 3);
+  assert.equal(validateTurnResult(roundTrip).ok, true);
 });
 
 test("uok contracts include required DAG node kinds", () => {
@@ -84,9 +101,11 @@ test("uok audit envelope includes trace/turn/causality fields", () => {
   });
 
   assert.equal(event.traceId, "trace-xyz");
+  assert.equal(event.version, CURRENT_UOK_CONTRACT_VERSION);
   assert.equal(event.turnId, "turn-xyz");
   assert.equal(event.causedBy, "turn-start");
   assert.equal(event.payload.status, "completed");
+  assert.equal(validateAuditEvent(event).ok, true);
 });
 
 test("uok dispatch envelope carries scheduler reason and constraints", () => {
@@ -107,9 +126,98 @@ test("uok dispatch envelope carries scheduler reason and constraints", () => {
   });
 
   assert.equal(envelope.nodeKind, "unit");
+  assert.equal(envelope.version, CURRENT_UOK_CONTRACT_VERSION);
   assert.equal(envelope.reason.reasonCode, "dependency");
   assert.deepEqual(envelope.constraints?.dependsOn, ["plan-gate"]);
   assert.ok(explainDispatch(envelope).includes("execute-task M001/S01/T01"));
+  assert.equal(validateDispatchEnvelope(envelope).ok, true);
+});
+
+test("uok contracts normalize legacy records without losing payload fields", () => {
+  const legacy = {
+    eventId: "event-legacy",
+    traceId: "trace-legacy",
+    category: "orchestration",
+    type: "turn-result",
+    ts: new Date().toISOString(),
+    payload: { status: "completed", extra: "preserved" },
+  } as AuditEventEnvelope;
+
+  const normalized = normalizeAuditEvent(legacy);
+  assert.equal(normalized.version, "0");
+  assert.equal(normalized.payload.extra, "preserved");
+  assert.equal(validateAuditEvent(legacy).ok, true);
+});
+
+test("uok audit emission writes DB as authoritative before jsonl projection", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-db-audit-"));
+  mkdirSync(join(basePath, ".gsd"), { recursive: true });
+  t.after(() => {
+    closeDatabase();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  assert.equal(openDatabase(join(basePath, ".gsd", "gsd.db")), true);
+  emitUokAuditEvent(
+    basePath,
+    buildAuditEnvelope({
+      traceId: "trace-db",
+      turnId: "turn-db",
+      category: "orchestration",
+      type: "turn-start",
+      payload: { unitType: "execute-task" },
+    }),
+  );
+
+  const row = _getAdapter()!.prepare(
+    "SELECT payload_json FROM audit_events WHERE trace_id = 'trace-db' AND turn_id = 'turn-db'",
+  ).get() as { payload_json: string } | undefined;
+  assert.ok(row, "DB audit row should be written");
+  assert.equal(JSON.parse(row.payload_json).contractVersion, CURRENT_UOK_CONTRACT_VERSION);
+
+  const projection = readFileSync(join(basePath, ".gsd", "audit", "events.jsonl"), "utf-8");
+  assert.ok(projection.includes("trace-db"), "jsonl projection should still be written");
+});
+
+test("uok timeline prefers DB records over jsonl projection when DB is available", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-timeline-"));
+  const auditDir = join(basePath, ".gsd", "audit");
+  mkdirSync(auditDir, { recursive: true });
+  writeFileSync(
+    join(auditDir, "events.jsonl"),
+    `${JSON.stringify({
+      version: CURRENT_UOK_CONTRACT_VERSION,
+      eventId: "jsonl-only",
+      traceId: "trace-timeline",
+      turnId: "turn-timeline",
+      category: "orchestration",
+      type: "jsonl-projection",
+      ts: "2026-01-01T00:00:00.000Z",
+      payload: {},
+    })}\n`,
+  );
+  t.after(() => {
+    closeDatabase();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  assert.equal(openDatabase(join(basePath, ".gsd", "gsd.db")), true);
+  emitUokAuditEvent(
+    basePath,
+    buildAuditEnvelope({
+      traceId: "trace-timeline",
+      turnId: "turn-timeline",
+      category: "orchestration",
+      type: "db-authoritative",
+      payload: {},
+    }),
+  );
+
+  const timeline = buildTurnTimeline(basePath, { traceId: "trace-timeline", turnId: "turn-timeline" });
+  assert.equal(timeline.authoritative, "db");
+  assert.equal(timeline.degraded, false);
+  assert.ok(timeline.entries.some((entry) => entry.type === "db-authoritative"));
+  assert.equal(timeline.entries.some((entry) => entry.type === "jsonl-projection"), false);
 });
 
 test("uok writer records serialize sequence metadata", () => {

package/src/resources/extensions/gsd/tests/uok-loop-adapter-writer.test.ts

@@ -63,3 +63,101 @@ test("uok turn observer adds writer sequence metadata to audit events", (t) => {
   assert.equal(payloads[1]?.writeSequence, 2);
   assert.equal(typeof payloads[0]?.writerTokenId, "string");
 });
+
+test("uok turn observer releases writer token when validation throws", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-loop-writer-throw-"));
+  resetWriterTokensForTests();
+  t.after(() => {
+    resetWriterTokensForTests();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  const observer = createTurnObserver({
+    basePath,
+    gitAction: "status-only",
+    gitPush: false,
+    enableAudit: false,
+    enableGitops: false,
+  });
+
+  observer.onTurnStart({
+    basePath,
+    traceId: "trace-throw",
+    turnId: "turn-throw",
+    iteration: 1,
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    startedAt: new Date().toISOString(),
+  });
+  assert.equal(hasActiveWriterToken(basePath, "turn-throw"), true);
+
+  // Invalid payload (missing required fields like status/finishedAt) should
+  // trigger validateTurnResult to fail and throw.
+  assert.throws(() => {
+    observer.onTurnResult({
+      traceId: "trace-throw",
+      turnId: "turn-throw",
+      // @ts-expect-error intentionally invalid for test
+      iteration: "not-a-number",
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+      status: "completed",
+      failureClass: "none",
+      phaseResults: [],
+      startedAt: new Date().toISOString(),
+      finishedAt: new Date().toISOString(),
+    });
+  }, /Invalid UOK turn result/);
+
+  // Cleanup must run in finally — token released, no leaked state.
+  assert.equal(hasActiveWriterToken(basePath, "turn-throw"), false);
+});
+
+test("uok turn observer falls back to cached phaseResults when result.phaseResults is missing", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-loop-writer-missing-"));
+  resetWriterTokensForTests();
+  t.after(() => {
+    resetWriterTokensForTests();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  const observer = createTurnObserver({
+    basePath,
+    gitAction: "status-only",
+    gitPush: false,
+    enableAudit: false,
+    enableGitops: false,
+  });
+
+  observer.onTurnStart({
+    basePath,
+    traceId: "trace-missing",
+    turnId: "turn-missing",
+    iteration: 1,
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    startedAt: new Date().toISOString(),
+  });
+
+  // Without the Array.isArray guard, accessing result.phaseResults.length on a
+  // payload where phaseResults is undefined would throw TypeError before
+  // validateTurnResult could surface a structured error. The guard must defer
+  // to the cached phaseResults fallback so the turn completes cleanly.
+  assert.doesNotThrow(() => {
+    observer.onTurnResult({
+      traceId: "trace-missing",
+      turnId: "turn-missing",
+      iteration: 1,
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+      status: "completed",
+      failureClass: "none",
+      // @ts-expect-error intentionally missing for test
+      phaseResults: undefined,
+      startedAt: new Date().toISOString(),
+      finishedAt: new Date().toISOString(),
+    });
+  });
+
+  assert.equal(hasActiveWriterToken(basePath, "turn-missing"), false);
+});

package/src/resources/extensions/gsd/tests/workflow-tool-executors.test.ts

@@ -11,7 +11,9 @@ import {
   _getAdapter,
   insertGateRow,
   upsertRequirement,
+  getAllMilestones,
 } from "../gsd-db.ts";
+import { deriveState, invalidateStateCache } from "../state.ts";
 import { markApprovalGateVerified, markDepthVerified, clearDiscussionFlowState, loadWriteGateSnapshot, setPendingGate } from "../bootstrap/write-gate.ts";
 import {
   executeCompleteMilestone,
@@ -737,6 +739,104 @@ test("executeSummarySave supports root-level deep planning artifacts", async ()
   }
 });
 
+test("executeSummarySave registers PROJECT milestone sequence for the next run", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+
+    const result = await inProjectDir(base, () => executeSummarySave({
+      artifact_type: "PROJECT",
+      content: [
+        "# Project",
+        "",
+        "## What This Is",
+        "",
+        "Deep project setup output.",
+        "",
+        "## Project Shape",
+        "",
+        "**Complexity:** complex",
+        "**Why:** It spans multiple delivery steps.",
+        "",
+        "## Capability Contract",
+        "",
+        "See .gsd/REQUIREMENTS.md.",
+        "",
+        "## Milestone Sequence",
+        "",
+        "- [ ] M001: Foundation - Establish the first runnable slice.",
+        "- [ ] M002: Polish - Follow-up experience work.",
+        "",
+      ].join("\n"),
+    }, base));
+
+    assert.equal(result.isError, undefined);
+    assert.deepEqual(result.details.registeredMilestones, ["M001", "M002"]);
+
+    const milestones = getAllMilestones();
+    assert.deepEqual(
+      milestones.map((m) => [m.id, m.title, m.status]),
+      [
+        ["M001", "Foundation", "queued"],
+        ["M002", "Polish", "queued"],
+      ],
+    );
+
+    invalidateStateCache();
+    const state = await deriveState(base);
+    assert.equal(state.activeMilestone?.id, "M001");
+    assert.equal(state.phase, "pre-planning");
+    assert.equal(state.registry[0]?.status, "active");
+    assert.equal(state.registry[1]?.status, "pending");
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeSummarySave keeps PROJECT artifact save successful if milestone registration fails", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+    const db = _getAdapter();
+    assert.ok(db, "DB should be open");
+    const originalPrepare = db.prepare.bind(db);
+    (db as any).prepare = (sql: string) => {
+      if (sql.includes("INSERT OR IGNORE INTO milestones")) {
+        throw new Error("simulated milestone registration failure");
+      }
+      return originalPrepare(sql);
+    };
+
+    const result = await inProjectDir(base, () => executeSummarySave({
+      artifact_type: "PROJECT",
+      content: [
+        "# Project",
+        "",
+        "## What This Is",
+        "",
+        "Deep project setup output.",
+        "",
+        "## Milestone Sequence",
+        "",
+        "- [ ] M001: Foundation - Establish the first runnable slice.",
+        "",
+      ].join("\n"),
+    }, base));
+
+    assert.equal(result.isError, undefined);
+    assert.equal(result.details.path, "PROJECT.md");
+    assert.equal(result.details.registeredMilestones, undefined);
+    assert.match(String(result.details.warning), /milestone registration failed/);
+    assert.ok(existsSync(join(base, ".gsd", "PROJECT.md")));
+    const artifact = originalPrepare("SELECT path FROM artifacts WHERE path = ?").get("PROJECT.md");
+    assert.equal(artifact?.path, "PROJECT.md");
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
 test("executeSummarySave blocks final root artifacts while approval gate is pending", async () => {
   const base = makeTmpBase();
   try {

package/src/resources/extensions/gsd/tests/worktree-path-injection.test.ts

@@ -229,6 +229,9 @@ test("worktree-aware prompt builders include the explicit working directory", as
     ),
   ]);
 
+  assert.ok(prompts[0].includes("## Context Mode"), "discuss-milestone should include standalone Context Mode guidance");
+  assert.ok(prompts[0].includes("interview lane"), "discuss-milestone should render the interview lane");
+
   for (const prompt of prompts) {
     assert.match(prompt, /working directory/i);
     assert.ok(prompt.includes(base), "prompt should include the provided working directory");

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -3,6 +3,7 @@ import { sanitizeCompleteMilestoneParams } from "../bootstrap/sanitize-complete-
 import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "../bootstrap/write-gate.js";
 import {
   getActiveRequirements,
+  insertMilestone,
   getMilestone,
   getSliceStatusSummary,
   getSliceTaskCounts,
@@ -31,6 +32,7 @@ import { handleValidateMilestone } from "./validate-milestone.js";
 import { logError, logWarning } from "../workflow-logger.js";
 import { invalidateStateCache } from "../state.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { parseProject } from "../schemas/parsers.js";
 
 export const SUPPORTED_SUMMARY_ARTIFACT_TYPES = [
   "SUMMARY",
@@ -71,6 +73,20 @@ export interface SummarySaveParams {
   content: string;
 }
 
+function registerProjectMilestoneSequence(content: string): string[] {
+  const parsed = parseProject(content);
+  const registered: string[] = [];
+  for (const milestone of parsed.milestones) {
+    insertMilestone({
+      id: milestone.id,
+      title: milestone.title,
+      status: milestone.done ? "complete" : "queued",
+    });
+    registered.push(milestone.id);
+  }
+  return registered;
+}
+
 export async function executeSummarySave(
   params: SummarySaveParams,
   basePath: string = process.cwd(),
@@ -173,6 +189,23 @@ export async function executeSummarySave(
       basePath,
     );
 
+    let registeredMilestones: string[] = [];
+    let registrationWarning: string | undefined;
+    if (params.artifact_type === "PROJECT") {
+      try {
+        registeredMilestones = registerProjectMilestoneSequence(contentToSave);
+        if (registeredMilestones.length > 0) invalidateStateCache();
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        registrationWarning = `PROJECT artifact saved, but milestone registration failed: ${msg}`;
+        logWarning("tool", registrationWarning, {
+          tool: "gsd_summary_save",
+          error: String(err),
+          stack: err instanceof Error ? err.stack ?? "" : "",
+        });
+      }
+    }
+
     if (params.artifact_type === "CONTEXT" && !params.task_id) {
       try {
         const draftFile = params.slice_id
@@ -186,7 +219,14 @@ export async function executeSummarySave(
 
     return {
       content: [{ type: "text", text: `Saved ${params.artifact_type} artifact to ${relativePath}` }],
-      details: { operation: "save_summary", path: relativePath, artifact_type: params.artifact_type, content_source: contentSource },
+      details: {
+        operation: "save_summary",
+        path: relativePath,
+        artifact_type: params.artifact_type,
+        content_source: contentSource,
+        ...(registeredMilestones.length > 0 ? { registeredMilestones } : {}),
+        ...(registrationWarning ? { warning: registrationWarning } : {}),
+      },
     };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);

package/src/resources/extensions/gsd/unit-context-composer.ts

@@ -42,6 +42,7 @@ import {
   type BaseResolverContext,
   type ComputedArtifactId,
   type ComputedArtifactRegistry,
+  type ContextModePolicy,
   type UnitContextManifest,
 } from "./unit-context-manifest.js";
 
@@ -92,6 +93,54 @@ export function manifestBudgetChars(unitType: string): number | null {
   return manifest ? manifest.maxSystemPromptChars : null;
 }
 
+// ─── Context Mode lane guidance ──────────────────────────────────────────
+
+export type ContextModeRenderMode = "standalone" | "nested";
+
+export interface ComposeContextModeInstructionOptions {
+  readonly enabled: boolean;
+  readonly renderMode: ContextModeRenderMode;
+}
+
+const CONTEXT_MODE_LANE_LABELS: Record<Exclude<ContextModePolicy, "none">, string> = {
+  interview: "interview",
+  research: "research",
+  planning: "planning",
+  execution: "execution",
+  verification: "verification",
+  orchestration: "orchestration",
+  docs: "documentation",
+};
+
+const CONTEXT_MODE_GUIDANCE =
+  "Use `gsd_exec` for noisy scans, builds, and tests so full output stays out of prompt context; call `gsd_exec_search` before repeating prior runs; call `gsd_resume` after compaction or resume to recover stored execution context.";
+
+/**
+ * Render the Context Mode instruction lane for a unit type. Unknown unit
+ * types, disabled config, and explicit `contextMode: "none"` all omit the
+ * block so callers can prefix this safely without extra branching.
+ */
+export function composeContextModeInstructions(
+  unitType: string,
+  opts: ComposeContextModeInstructionOptions,
+): string {
+  if (!opts.enabled) return "";
+  const manifest = resolveManifest(unitType);
+  if (!manifest || manifest.contextMode === "none") return "";
+
+  const lane = CONTEXT_MODE_LANE_LABELS[manifest.contextMode];
+  if (opts.renderMode === "nested") {
+    return `Context Mode (${lane} lane): ${CONTEXT_MODE_GUIDANCE}`;
+  }
+
+  return [
+    "## Context Mode",
+    "",
+    `Lane: **${lane} lane**.`,
+    CONTEXT_MODE_GUIDANCE,
+  ].join("\n");
+}
+
 // ─── v2 surface (#4924) ───────────────────────────────────────────────────
 
 /**