gsd-pi 2.76.0 → 2.77.0-dev.2daa994b6

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

@@ -0,0 +1,355 @@
+// GSD-2 — #4782 phase 2 composer tests. Pure-function tests using mock
+// resolvers plus an integration check that reassess-roadmap's migrated
+// builder produces a prompt matching expectations.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  composeInlinedContext,
+  composeUnitContext,
+  manifestBudgetChars,
+  type ArtifactResolver,
+  type ExcerptResolver,
+} from "../unit-context-composer.ts";
+import type {
+  ArtifactKey,
+  BaseResolverContext,
+  ComputedArtifactRegistry,
+  UnitContextManifest,
+} from "../unit-context-manifest.ts";
+import { UNIT_MANIFESTS } from "../unit-context-manifest.ts";
+import { buildReassessRoadmapPrompt } from "../auto-prompts.ts";
+import { invalidateAllCaches } from "../cache.ts";
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+  upsertMilestonePlanning,
+  insertSlice,
+} from "../gsd-db.ts";
+
+// ─── Pure composer tests ──────────────────────────────────────────────────
+
+test("#4782 composer: returns empty string for unknown unit type", async () => {
+  const out = await composeInlinedContext("never-dispatched", async () => "body");
+  assert.strictEqual(out, "");
+});
+
+test("#4782 composer: walks the manifest's inline list in declared order", async () => {
+  // reassess-roadmap manifest: [roadmap, slice-context, slice-summary, project, requirements, decisions]
+  const calls: ArtifactKey[] = [];
+  const resolver: ArtifactResolver = async (key) => {
+    calls.push(key);
+    return `BODY:${key}`;
+  };
+  const out = await composeInlinedContext("reassess-roadmap", resolver);
+  assert.deepEqual(calls, [
+    "roadmap",
+    "slice-context",
+    "slice-summary",
+    "project",
+    "requirements",
+    "decisions",
+  ]);
+  // Output joins blocks with the "---" separator.
+  assert.match(out, /BODY:roadmap\n\n---\n\nBODY:slice-context/);
+});
+
+test("#4782 composer: null-returning resolvers are silently omitted", async () => {
+  const resolver: ArtifactResolver = async (key) => {
+    if (key === "slice-context" || key === "project") return null;
+    return `BODY:${key}`;
+  };
+  const out = await composeInlinedContext("reassess-roadmap", resolver);
+  // slice-context + project skipped — not in output, no empty blocks
+  assert.ok(!out.includes("BODY:slice-context"));
+  assert.ok(!out.includes("BODY:project"));
+  // Remaining keys still emitted in declared order
+  assert.match(out, /BODY:roadmap\n\n---\n\nBODY:slice-summary\n\n---\n\nBODY:requirements\n\n---\n\nBODY:decisions/);
+});
+
+test("#4782 composer: empty-string resolvers are omitted (treated as no-op)", async () => {
+  const resolver: ArtifactResolver = async (key) => {
+    if (key === "slice-context") return "";
+    if (key === "slice-summary") return null;
+    return `BODY:${key}`;
+  };
+  const out = await composeInlinedContext("reassess-roadmap", resolver);
+  assert.ok(!out.includes("BODY:slice-context"));
+  assert.ok(!out.includes("BODY:slice-summary"));
+  // Must not leave double-separators when blocks are skipped
+  assert.ok(!out.includes("---\n\n---"));
+});
+
+test("#4782 composer: resolver errors surface to caller", async () => {
+  const resolver: ArtifactResolver = async () => {
+    throw new Error("resolver boom");
+  };
+  await assert.rejects(
+    () => composeInlinedContext("reassess-roadmap", resolver),
+    /resolver boom/,
+  );
+});
+
+test("#4782 composer: manifestBudgetChars returns declared budget", () => {
+  const small = manifestBudgetChars("reassess-roadmap");
+  assert.ok(small !== null && small > 0);
+  assert.strictEqual(manifestBudgetChars("never-dispatched"), null);
+});
+
+// ─── Integration: migrated buildReassessRoadmapPrompt ─────────────────────
+
+function makeFixtureBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-composer-pilot-"));
+  mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks"), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { closeDatabase(); } catch { /* noop */ }
+  invalidateAllCaches();
+  rmSync(base, { recursive: true, force: true });
+}
+
+function seed(base: string, mid: string): void {
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: mid, title: "Test", status: "active", depends_on: [] });
+  upsertMilestonePlanning(mid, {
+    title: "Test",
+    status: "active",
+    vision: "Ship it",
+    successCriteria: ["It ships"],
+    keyRisks: [],
+    proofStrategy: [],
+    verificationContract: "",
+    verificationIntegration: "",
+    verificationOperational: "",
+    verificationUat: "",
+    definitionOfDone: [],
+    requirementCoverage: "",
+    boundaryMapMarkdown: "",
+  });
+  insertSlice({
+    id: "S01",
+    milestoneId: mid,
+    title: "First",
+    status: "complete",
+    risk: "low",
+    depends: [],
+    demo: "",
+    sequence: 1,
+  });
+}
+
+function writeArtifacts(base: string): void {
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
+    "# M001\n## Slices\n- [x] **S01: First** `risk:low` `depends:[]`\n",
+  );
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-SUMMARY.md"),
+    "---\nid: S01\nparent: M001\n---\n# S01 Summary\n**One-liner**\n\n## What Happened\nDone.\n",
+  );
+}
+
+test("#4782 phase 2: buildReassessRoadmapPrompt emits composer-shaped context with manifest-declared artifacts", async (t) => {
+  const base = makeFixtureBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  seed(base, "M001");
+  writeArtifacts(base);
+
+  const prompt = await buildReassessRoadmapPrompt("M001", "Test", "S01", base);
+
+  // Context block wrapper from capPreamble
+  assert.match(prompt, /## Inlined Context \(preloaded — do not re-read these files\)/);
+
+  // Roadmap inlined first (manifest order)
+  assert.match(prompt, /### Current Roadmap/);
+  assert.match(prompt, /S01: First/);
+
+  // Slice summary present
+  assert.match(prompt, /### S01 Summary/);
+  assert.match(prompt, /One-liner/);
+
+  // Slice context is optional and not present in this fixture — must not
+  // leave a stray empty section
+  assert.ok(!prompt.includes("Slice Context (from discussion)"));
+});
+
+// ─── v2 surface (#4924) ───────────────────────────────────────────────────
+
+const fakeBase: BaseResolverContext = {
+  unitType: "reassess-roadmap",
+  basePath: "/tmp/fake",
+  milestoneId: "M001",
+  sliceId: "S01",
+};
+
+test("#4924 v2 composer: returns empty sections for unknown unit type", async () => {
+  const out = await composeUnitContext("never-dispatched", { base: fakeBase });
+  assert.deepEqual(out, { prepend: "", inline: "" });
+});
+
+test("#4924 v2 composer: omitting resolveArtifact skips inline keys without erroring", async () => {
+  const out = await composeUnitContext("reassess-roadmap", { base: fakeBase });
+  assert.strictEqual(out.inline, "");
+  assert.strictEqual(out.prepend, "");
+});
+
+test("#4924 v2 composer: walks inline + excerpt + computed sections in declared order", async () => {
+  // Reuse the run-uat manifest shape (small inline, no excerpt/computed) and
+  // synthesise a manifest-shape override via a temporary registration would
+  // require touching production data. Instead, drive the composer through
+  // the existing manifest plus mock resolvers and verify ordering against
+  // the declared sequence.
+  const calls: string[] = [];
+  const resolveArtifact: ArtifactResolver = async (key) => {
+    calls.push(`art:${key}`);
+    return `BODY:${key}`;
+  };
+  const out = await composeUnitContext("run-uat", { base: { ...fakeBase, unitType: "run-uat" }, resolveArtifact });
+  // run-uat manifest inline order: slice-uat, slice-summary, project
+  assert.deepEqual(calls, ["art:slice-uat", "art:slice-summary", "art:project"]);
+  assert.match(out.inline, /BODY:slice-uat\n\n---\n\nBODY:slice-summary\n\n---\n\nBODY:project/);
+});
+
+test("#4924 v2 composer: excerpt section calls resolveExcerpt for declared keys", async () => {
+  // complete-milestone declares slice-summary as excerpt — perfect target.
+  const inlineCalls: ArtifactKey[] = [];
+  const excerptCalls: ArtifactKey[] = [];
+  const resolveArtifact: ArtifactResolver = async (key) => {
+    inlineCalls.push(key);
+    return `INLINE:${key}`;
+  };
+  const resolveExcerpt: ExcerptResolver = async (key) => {
+    excerptCalls.push(key);
+    return `EXCERPT:${key}`;
+  };
+  const out = await composeUnitContext("complete-milestone", {
+    base: { ...fakeBase, unitType: "complete-milestone" },
+    resolveArtifact,
+    resolveExcerpt,
+  });
+  assert.ok(excerptCalls.includes("slice-summary"));
+  // Excerpt body appears in the composed inline section, after inline keys.
+  assert.match(out.inline, /EXCERPT:slice-summary/);
+  // The inline keys come first per the manifest order.
+  const cmManifest = UNIT_MANIFESTS["complete-milestone"];
+  const firstInlineKey = cmManifest.artifacts.inline[0]!;
+  const firstInlineIdx = out.inline.indexOf(`INLINE:${firstInlineKey}`);
+  const excerptIdx = out.inline.indexOf("EXCERPT:slice-summary");
+  assert.ok(firstInlineIdx >= 0 && excerptIdx > firstInlineIdx, "inline body should precede excerpt body");
+});
+
+test("#4924 v2 composer: prepend block is separate from inline section", async () => {
+  // No production manifest declares a prepend block yet (those land with
+  // each batched migration). Drive the composer through a synthetic
+  // manifest by patching UNIT_MANIFESTS just for this test.
+  const original = UNIT_MANIFESTS["run-uat"];
+  type Mutable<T> = { -readonly [P in keyof T]: T[P] };
+  const patched: UnitContextManifest = {
+    ...original,
+    prepend: ["test-banner"] as never[], // computed id not in production registry — typed via cast for the test
+  };
+  (UNIT_MANIFESTS as Mutable<typeof UNIT_MANIFESTS>)["run-uat"] = patched;
+  try {
+    const computed = {
+      "test-banner": {
+        build: async (_inputs: never, base: BaseResolverContext) => `BANNER for ${base.unitType}`,
+        inputs: undefined as never,
+      },
+    } as unknown as ComputedArtifactRegistry;
+    const out = await composeUnitContext("run-uat", {
+      base: { ...fakeBase, unitType: "run-uat" },
+      computed,
+    });
+    assert.strictEqual(out.prepend, "BANNER for run-uat");
+    assert.strictEqual(out.inline, "");
+  } finally {
+    (UNIT_MANIFESTS as Mutable<typeof UNIT_MANIFESTS>)["run-uat"] = original;
+  }
+});
+
+test("#4924 v2 composer: missing computed registry entry is skipped silently", async () => {
+  const original = UNIT_MANIFESTS["run-uat"];
+  type Mutable<T> = { -readonly [P in keyof T]: T[P] };
+  const patched: UnitContextManifest = {
+    ...original,
+    prepend: ["test-banner"] as never[],
+  };
+  (UNIT_MANIFESTS as Mutable<typeof UNIT_MANIFESTS>)["run-uat"] = patched;
+  try {
+    // No `computed` registry supplied — declared id should be skipped, not throw.
+    const out = await composeUnitContext("run-uat", { base: { ...fakeBase, unitType: "run-uat" } });
+    assert.strictEqual(out.prepend, "");
+  } finally {
+    (UNIT_MANIFESTS as Mutable<typeof UNIT_MANIFESTS>)["run-uat"] = original;
+  }
+});
+
+test("#4924 v2 composer: computed builder returning null omits the section (no empty separator)", async () => {
+  const original = UNIT_MANIFESTS["run-uat"];
+  type Mutable<T> = { -readonly [P in keyof T]: T[P] };
+  const patched: UnitContextManifest = {
+    ...original,
+    prepend: ["test-banner-a", "test-banner-b"] as never[],
+  };
+  (UNIT_MANIFESTS as Mutable<typeof UNIT_MANIFESTS>)["run-uat"] = patched;
+  try {
+    const computed = {
+      "test-banner-a": { build: async () => null, inputs: undefined as never },
+      "test-banner-b": { build: async () => "B", inputs: undefined as never },
+    } as unknown as ComputedArtifactRegistry;
+    const out = await composeUnitContext("run-uat", { base: { ...fakeBase, unitType: "run-uat" }, computed });
+    assert.strictEqual(out.prepend, "B");
+    assert.ok(!out.prepend.includes("---"));
+  } finally {
+    (UNIT_MANIFESTS as Mutable<typeof UNIT_MANIFESTS>)["run-uat"] = original;
+  }
+});
+
+test("#4924 v2 composer: backward-compat — composeInlinedContext still works for v1 callers", async () => {
+  const out = await composeInlinedContext("run-uat", async (key) => `BODY:${key}`);
+  assert.match(out, /BODY:slice-uat\n\n---\n\nBODY:slice-summary\n\n---\n\nBODY:project/);
+});
+
+test("#4926 review: computed builders see normalized base.unitType matching the resolved manifest", async () => {
+  // Caller passes one unitType to composeUnitContext but a different (stale)
+  // value in opts.base. Composer must normalize so builders observe the
+  // unitType the manifest was resolved against — preventing manifests and
+  // computed context from drifting.
+  const original = UNIT_MANIFESTS["run-uat"];
+  type Mutable<T> = { -readonly [P in keyof T]: T[P] };
+  const patched: UnitContextManifest = {
+    ...original,
+    prepend: ["test-banner"] as never[],
+  };
+  (UNIT_MANIFESTS as Mutable<typeof UNIT_MANIFESTS>)["run-uat"] = patched;
+  try {
+    let observedUnitType: string | undefined;
+    const computed = {
+      "test-banner": {
+        build: async (_inputs: never, base: BaseResolverContext) => {
+          observedUnitType = base.unitType;
+          return `BANNER for ${base.unitType}`;
+        },
+        inputs: undefined as never,
+      },
+    } as unknown as ComputedArtifactRegistry;
+    const out = await composeUnitContext("run-uat", {
+      // Deliberately mismatched: function arg "run-uat" vs. base.unitType "stale-other-unit".
+      base: { ...fakeBase, unitType: "stale-other-unit" },
+      computed,
+    });
+    assert.strictEqual(observedUnitType, "run-uat", "builder must see the unitType the manifest was resolved against");
+    assert.strictEqual(out.prepend, "BANNER for run-uat");
+  } finally {
+    (UNIT_MANIFESTS as Mutable<typeof UNIT_MANIFESTS>)["run-uat"] = original;
+  }
+});

package/src/resources/extensions/gsd/tests/unit-context-manifest.test.ts

@@ -0,0 +1,203 @@
+// GSD-2 — #4782 phase 1: schema tests + CI coverage guard for manifests.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  ARTIFACT_KEYS,
+  KNOWN_UNIT_TYPES,
+  UNIT_MANIFESTS,
+  resolveManifest,
+  type ArtifactKey,
+  type SkillsPolicy,
+  type UnitContextManifest,
+} from "../unit-context-manifest.ts";
+
+// ─── Coverage: every known unit type has a manifest ──────────────────────
+
+test("#4782 phase 1: every KNOWN_UNIT_TYPES entry has a UNIT_MANIFESTS entry", () => {
+  for (const unitType of KNOWN_UNIT_TYPES) {
+    assert.ok(
+      UNIT_MANIFESTS[unitType],
+      `unit type "${unitType}" is declared in KNOWN_UNIT_TYPES but has no manifest`,
+    );
+  }
+});
+
+test("#4782 phase 1: every UNIT_MANIFESTS entry corresponds to a known unit type", () => {
+  const known = new Set<string>(KNOWN_UNIT_TYPES as readonly string[]);
+  for (const unitType of Object.keys(UNIT_MANIFESTS)) {
+    assert.ok(
+      known.has(unitType),
+      `manifest entry "${unitType}" is not in KNOWN_UNIT_TYPES — add it there or remove the manifest`,
+    );
+  }
+});
+
+// ─── Coverage: every unitType stringly-typed in auto-dispatch.ts is known ─
+
+test("#4782 phase 1: every unitType string in auto-dispatch.ts has a manifest", () => {
+  // Source-only coverage check — read the dispatcher and enumerate its
+  // unitType literals. This is a CI guard against manifest drift: if a
+  // new dispatch rule is added without a corresponding manifest entry,
+  // this test fails loudly. Read-only check of source text; the cheapest
+  // way to enumerate declared unit types without running the dispatcher.
+  // allow-source-grep: enumerate unitType literals for CI coverage guard
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const dispatchSrc = readFileSync(join(__dirname, "..", "auto-dispatch.ts"), "utf-8");
+  const matches = Array.from(dispatchSrc.matchAll(/unitType:\s*"([^"]+)"/g));
+  const seen = new Set<string>();
+  for (const m of matches) {
+    const t = m[1];
+    if (!t) continue;
+    seen.add(t);
+  }
+  const missing: string[] = [];
+  for (const t of seen) {
+    if (!UNIT_MANIFESTS[t as keyof typeof UNIT_MANIFESTS]) {
+      missing.push(t);
+    }
+  }
+  assert.deepEqual(missing, [], `unit types dispatched in auto-dispatch.ts but missing from UNIT_MANIFESTS: ${missing.join(", ")}`);
+});
+
+// ─── Shape: every manifest conforms to the schema invariants ──────────────
+
+test("#4782 phase 1: every manifest's artifacts reference known ArtifactKey values", () => {
+  const validKeys = new Set<string>(ARTIFACT_KEYS as readonly string[]);
+  for (const [unitType, manifest] of Object.entries(UNIT_MANIFESTS)) {
+    const all: ArtifactKey[] = [
+      ...manifest.artifacts.inline,
+      ...manifest.artifacts.excerpt,
+      ...manifest.artifacts.onDemand,
+    ];
+    for (const key of all) {
+      assert.ok(
+        validKeys.has(key),
+        `manifest "${unitType}" references unknown artifact key "${key}"`,
+      );
+    }
+  }
+});
+
+test("#4782 phase 1: no manifest has the same artifact key in inline AND excerpt (mutually exclusive)", () => {
+  for (const [unitType, manifest] of Object.entries(UNIT_MANIFESTS)) {
+    const inline = new Set<string>(manifest.artifacts.inline as readonly string[]);
+    const clashes = (manifest.artifacts.excerpt as readonly string[]).filter(k => inline.has(k));
+    assert.deepEqual(
+      clashes,
+      [],
+      `manifest "${unitType}" has overlapping inline+excerpt artifact keys: ${clashes.join(", ")}. Pick one.`,
+    );
+  }
+});
+
+test("#4782 phase 1: every manifest has a positive maxSystemPromptChars", () => {
+  for (const [unitType, manifest] of Object.entries(UNIT_MANIFESTS)) {
+    assert.ok(
+      typeof manifest.maxSystemPromptChars === "number" && manifest.maxSystemPromptChars > 0,
+      `manifest "${unitType}" has invalid maxSystemPromptChars: ${manifest.maxSystemPromptChars}`,
+    );
+  }
+});
+
+test("#4782 phase 1: skills policy shapes are valid discriminated-union members", () => {
+  for (const [unitType, manifest] of Object.entries(UNIT_MANIFESTS)) {
+    const p = manifest.skills as SkillsPolicy;
+    switch (p.mode) {
+      case "none":
+      case "all":
+        break;
+      case "allowlist":
+        assert.ok(
+          Array.isArray(p.skills) && p.skills.every(s => typeof s === "string"),
+          `manifest "${unitType}" has allowlist policy with invalid skills[]`,
+        );
+        break;
+      default: {
+        const _exhaustive: never = p;
+        void _exhaustive;
+        assert.fail(`manifest "${unitType}" has unrecognized skills.mode`);
+      }
+    }
+  }
+});
+
+// ─── Lookup helper ────────────────────────────────────────────────────────
+
+test("#4782 phase 1: resolveManifest returns null for an unknown unit type", () => {
+  assert.strictEqual(resolveManifest("never-dispatched-unit-type"), null);
+});
+
+test("#4782 phase 1: resolveManifest returns a manifest for every known unit type", () => {
+  for (const unitType of KNOWN_UNIT_TYPES) {
+    const m = resolveManifest(unitType);
+    assert.ok(m, `resolveManifest("${unitType}") should return a manifest`);
+    // Identity check — the helper should return the exact object, not a copy.
+    assert.strictEqual(m, UNIT_MANIFESTS[unitType]);
+  }
+});
+
+// ─── Phase-2 target: complete-milestone manifest reflects #4780's excerpt shape ─
+
+test("#4782 phase 1: complete-milestone manifest declares slice-summary as excerpt (matches #4780)", () => {
+  const m = UNIT_MANIFESTS["complete-milestone"];
+  assert.ok(
+    m.artifacts.excerpt.includes("slice-summary"),
+    "complete-milestone should declare slice-summary as excerpt (alignment with #4780)",
+  );
+  assert.ok(
+    !m.artifacts.inline.includes("slice-summary"),
+    "complete-milestone should NOT declare slice-summary as inline — that was the #4780 bloat",
+  );
+});
+
+// ─── v2 contract invariants (#4924) ──────────────────────────────────────
+
+test("#4924: computed + prepend ids (when declared) are non-empty strings", () => {
+  for (const [unitType, manifest] of Object.entries(UNIT_MANIFESTS)) {
+    const ids: string[] = [
+      ...((manifest.artifacts as { computed?: readonly string[] }).computed ?? []),
+      ...((manifest as { prepend?: readonly string[] }).prepend ?? []),
+    ];
+    for (const id of ids) {
+      assert.ok(
+        typeof id === "string" && id.length > 0,
+        `manifest "${unitType}" has an empty/invalid computed/prepend id: ${JSON.stringify(id)}`,
+      );
+    }
+  }
+});
+
+test("#4924: no computed id appears in both artifacts.computed AND prepend (mutually exclusive position)", () => {
+  for (const [unitType, manifest] of Object.entries(UNIT_MANIFESTS)) {
+    const inlineComputed = new Set<string>(
+      ((manifest.artifacts as { computed?: readonly string[] }).computed ?? []),
+    );
+    const clashes = ((manifest as { prepend?: readonly string[] }).prepend ?? [])
+      .filter(id => inlineComputed.has(id));
+    assert.deepEqual(
+      clashes,
+      [],
+      `manifest "${unitType}" places computed id(s) in both prepend and inline-computed: ${clashes.join(", ")}. Pick one position.`,
+    );
+  }
+});
+
+// ─── Budget floor: run-uat + gate-evaluate hit the smallest budget tier ──
+
+test("#4782 phase 2: run-uat and gate-evaluate use the smallest budget tier", () => {
+  const uatBudget = UNIT_MANIFESTS["run-uat"].maxSystemPromptChars;
+  const gateBudget = UNIT_MANIFESTS["gate-evaluate"].maxSystemPromptChars;
+  assert.strictEqual(uatBudget, gateBudget, "run-uat and gate-evaluate both use COMMON_BUDGET_SMALL");
+  // They should be the tightest (or tied for tightest) across all manifests
+  for (const [unitType, other] of Object.entries(UNIT_MANIFESTS)) {
+    assert.ok(
+      uatBudget <= other.maxSystemPromptChars,
+      `run-uat budget (${uatBudget}) should be ≤ ${unitType} budget (${other.maxSystemPromptChars})`,
+    );
+  }
+});

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

@@ -3,12 +3,16 @@ import assert from "node:assert/strict";
 
 import type {
   AuditEventEnvelope,
+  UokDispatchEnvelope,
   GateResult,
   TurnContract,
   TurnResult,
   UokNodeKind,
+  WriteRecord,
+  WriterToken,
 } from "../uok/contracts.ts";
 import { buildAuditEnvelope } from "../uok/audit.ts";
+import { buildDispatchEnvelope, explainDispatch } from "../uok/dispatch-envelope.ts";
 
 test("uok contracts serialize/deserialize turn envelopes", () => {
   const contract: TurnContract = {
@@ -84,3 +88,50 @@ test("uok audit envelope includes trace/turn/causality fields", () => {
   assert.equal(event.causedBy, "turn-start");
   assert.equal(event.payload.status, "completed");
 });
+
+test("uok dispatch envelope carries scheduler reason and constraints", () => {
+  const envelope: UokDispatchEnvelope = buildDispatchEnvelope({
+    action: "dispatch",
+    node: {
+      kind: "unit",
+      dependsOn: ["plan-gate"],
+      reads: ["M001-ROADMAP.md"],
+      writes: ["M001/S01/T01-SUMMARY.md"],
+    },
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    prompt: "do work",
+    reasonCode: "dependency",
+    summary: "all dependencies are closed and output path is available",
+    evidence: { readyTaskCount: 1 },
+  });
+
+  assert.equal(envelope.nodeKind, "unit");
+  assert.equal(envelope.reason.reasonCode, "dependency");
+  assert.deepEqual(envelope.constraints?.dependsOn, ["plan-gate"]);
+  assert.ok(explainDispatch(envelope).includes("execute-task M001/S01/T01"));
+});
+
+test("uok writer records serialize sequence metadata", () => {
+  const token: WriterToken = {
+    tokenId: "token-1",
+    traceId: "trace-1",
+    turnId: "turn-1",
+    acquiredAt: new Date().toISOString(),
+    owner: "uok",
+  };
+
+  const record: WriteRecord = {
+    writerToken: token,
+    sequence: { traceId: token.traceId, turnId: token.turnId, sequence: 7 },
+    category: "audit",
+    operation: "append",
+    path: ".gsd/audit/events.jsonl",
+    ts: new Date().toISOString(),
+  };
+
+  const roundTrip = JSON.parse(JSON.stringify(record)) as WriteRecord;
+  assert.equal(roundTrip.writerToken.tokenId, "token-1");
+  assert.equal(roundTrip.sequence.sequence, 7);
+  assert.equal(roundTrip.category, "audit");
+});

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

@@ -5,6 +5,7 @@ import {
   selectConflictFreeBatch,
   selectReactiveDispatchBatch,
   buildSidecarQueueNodes,
+  buildExecutionGraphSnapshot,
   scheduleSidecarQueue,
 } from "../uok/execution-graph.ts";
 
@@ -67,3 +68,18 @@ test("uok execution graph sidecar scheduler preserves deterministic queue order"
     queue.map((item) => item.unitId),
   );
 });
+
+test("uok execution graph snapshot captures deterministic order and conflicts", () => {
+  const snapshot = buildExecutionGraphSnapshot(
+    [
+      { id: "b", kind: "unit", dependsOn: ["a"], writes: ["src/shared.ts"] },
+      { id: "a", kind: "unit", dependsOn: [], writes: ["src/a.ts"] },
+      { id: "c", kind: "verification", dependsOn: [], writes: ["src/shared.ts"] },
+    ],
+    "before-unit",
+  );
+
+  assert.equal(snapshot.phase, "before-unit");
+  assert.deepEqual(snapshot.order, ["a", "b", "c"]);
+  assert.ok(snapshot.conflicts.some((c) => c.file === "src/shared.ts"));
+});