@opengsd/gsd-pi 1.9.0-dev.e10b60d4 → 1.10.0-dev.a5e42e99

package/src/resources/extensions/gsd/tests/workflow-authority-faults.test.ts

@@ -0,0 +1,238 @@
+import assert from "node:assert/strict";
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import test from "node:test";
+
+import type { CompleteSliceParams } from "../types.js";
+import {
+  closeDatabase,
+  getSlice,
+  getTask,
+  insertSlice,
+  insertTask,
+  updateTaskStatus,
+} from "../gsd-db.js";
+import { relSliceFile } from "../paths.js";
+import { handleCompleteSlice } from "../tools/complete-slice.js";
+import { createWorkflowAuthorityFixture } from "./workflow-authority-fixture.js";
+import {
+  createWorkflowFaultHarness,
+  type WorkflowFaultHarness,
+  type WorkflowFaultPoint,
+} from "./workflow-fault-harness.js";
+
+interface FaultScenario {
+  point: WorkflowFaultPoint;
+  committed: boolean;
+}
+
+interface AuthoritySnapshot {
+  pid: number;
+  taskStatus: string | null;
+  sliceStatus: string | null;
+  activeSlice: string | null;
+}
+
+const SCENARIOS: FaultScenario[] = [
+  { point: "before-transaction-commit", committed: false },
+  { point: "after-db-commit-before-render", committed: true },
+  { point: "during-projection-write", committed: true },
+  { point: "before-independent-reopen", committed: true },
+  { point: "after-independent-reopen", committed: true },
+];
+
+const COMPLETE_SLICE_PARAMS: CompleteSliceParams = {
+  milestoneId: "M001",
+  sliceId: "S02",
+  sliceTitle: "Ready dependent slice",
+  oneLiner: "Complete the dependent slice",
+  narrative: "The database records the completed slice before projections are refreshed.",
+  verification: "The focused authority matrix passed.",
+  uatContent: "## UAT Type\n\n- UAT mode: runtime-executable\n\n## Result\n\nPassed.",
+};
+
+function seedCompletionBoundary(): void {
+  updateTaskStatus("M001", "S02", "T01", "complete", "2026-07-11T00:00:00.000Z");
+  insertSlice({
+    id: "S03",
+    milestoneId: "M001",
+    title: "Blocked dependent slice",
+    status: "pending",
+    depends: ["S02"],
+    sequence: 3,
+  });
+  insertTask({
+    id: "T01",
+    milestoneId: "M001",
+    sliceId: "S03",
+    title: "Blocked task",
+    status: "pending",
+    sequence: 1,
+  });
+}
+
+function writeProjection(root: string, relativePath: string, content: string): void {
+  const path = join(root, ".gsd", relativePath);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content, "utf8");
+}
+
+function writeContradictoryProjection(root: string, committed: boolean): void {
+  const s02Checked = committed ? " " : "x";
+  const s03Checked = committed ? "x" : " ";
+  writeProjection(
+    root,
+    "milestones/M001/M001-ROADMAP.md",
+    [
+      "# M001: Contradictory projection",
+      "",
+      "## Slices",
+      "- [x] **S01: Completed prerequisite** `risk:low` `depends:[]`",
+      `- [${s02Checked}] **S02: Ready dependent slice** \`risk:medium\` \`depends:[S01]\``,
+      `- [${s03Checked}] **S03: Blocked dependent slice** \`risk:low\` \`depends:[S02]\``,
+    ].join("\n"),
+  );
+  writeProjection(
+    root,
+    "STATE.md",
+    [
+      "# GSD State",
+      "",
+      `**Active Slice:** ${committed ? "S02" : "S03"}`,
+      "**Phase:** executing",
+    ].join("\n"),
+  );
+}
+
+function armProductionFault(
+  point: WorkflowFaultPoint,
+  harness: WorkflowFaultHarness,
+  root: string,
+): void {
+  if (point === "before-transaction-commit") {
+    harness.armDatabaseAbort("status", "NEW.status = 'complete' AND OLD.status <> 'complete'");
+  } else if (point === "after-db-commit-before-render") {
+    harness.armDatabaseAbort("full_summary_md", "NEW.full_summary_md IS NOT OLD.full_summary_md");
+  } else if (point === "during-projection-write") {
+    const summaryPath = join(root, relSliceFile(root, "M001", "S02", "SUMMARY"));
+    harness.obstructProjection(summaryPath);
+  }
+}
+
+function runAuthorityProcess(
+  root: string,
+  dbPath: string,
+  faultPoint?: WorkflowFaultPoint,
+): SpawnSyncReturns<string> {
+  const resolver = join(process.cwd(), "src/resources/extensions/gsd/tests/resolve-ts.mjs");
+  const databaseModule = pathToFileURL(join(process.cwd(), "src/resources/extensions/gsd/gsd-db.ts")).href;
+  const stateModule = pathToFileURL(join(process.cwd(), "src/resources/extensions/gsd/state.ts")).href;
+  const faultHarnessModule = pathToFileURL(join(
+    process.cwd(),
+    "src/resources/extensions/gsd/tests/workflow-fault-harness.ts",
+  )).href;
+  const script = `
+    const [
+      { openDatabase, closeDatabase, getSlice, getTask },
+      { deriveStateFromDb },
+      { createWorkflowFaultHarness },
+    ] = await Promise.all([
+      import(${JSON.stringify(databaseModule)}),
+      import(${JSON.stringify(stateModule)}),
+      import(${JSON.stringify(faultHarnessModule)}),
+    ]);
+    const [root, dbPath, faultPoint] = process.argv.slice(-3);
+    if (!openDatabase(dbPath)) throw new Error("fresh process could not open workflow database");
+    if (faultPoint) {
+      process.stderr.write("DATABASE_OPENED_BEFORE_FAULT=" + process.pid + "\\n");
+      createWorkflowFaultHarness(faultPoint).hit(faultPoint, "fresh-process-reopen");
+    }
+    const state = await deriveStateFromDb(root);
+    const snapshot = {
+      pid: process.pid,
+      taskStatus: getTask("M001", "S02", "T01")?.status ?? null,
+      sliceStatus: getSlice("M001", "S02")?.status ?? null,
+      activeSlice: state.activeSlice?.id ?? null,
+    };
+    closeDatabase();
+    process.stdout.write("AUTHORITY_SNAPSHOT=" + JSON.stringify(snapshot) + "\\n");
+  `;
+  return spawnSync(
+    process.execPath,
+    [
+      "--import",
+      resolver,
+      "--experimental-strip-types",
+      "--input-type=module",
+      "--eval",
+      script,
+      root,
+      dbPath,
+      faultPoint ?? "",
+    ],
+    { cwd: process.cwd(), encoding: "utf8" },
+  );
+}
+
+function readAuthorityInFreshProcess(root: string, dbPath: string): AuthoritySnapshot {
+  const child = runAuthorityProcess(root, dbPath);
+
+  assert.equal(child.status, 0, child.stderr || child.stdout);
+  const line = child.stdout.split("\n").find((entry) => entry.startsWith("AUTHORITY_SNAPSHOT="));
+  assert.ok(line, `fresh process did not return an authority snapshot: ${child.stdout}`);
+  return JSON.parse(line.slice("AUTHORITY_SNAPSHOT=".length)) as AuthoritySnapshot;
+}
+
+for (const scenario of SCENARIOS) {
+  test(`database authority remains coherent at ${scenario.point}`, async (t) => {
+    const fixture = await createWorkflowAuthorityFixture();
+    t.after(() => fixture.cleanup());
+    seedCompletionBoundary();
+    const harness = createWorkflowFaultHarness(scenario.point);
+    armProductionFault(scenario.point, harness, fixture.root);
+
+    let completionError: unknown;
+    let completionStale = false;
+    try {
+      const result = await handleCompleteSlice(COMPLETE_SLICE_PARAMS, fixture.root);
+      assert.ok(!("error" in result), "production completion must reach its mutation boundary");
+      completionStale = result.stale === true;
+      harness.hit("before-independent-reopen", "complete-dependent-slice");
+    } catch (error) {
+      completionError = error;
+    }
+
+    if (scenario.point === "during-projection-write") {
+      assert.equal(completionStale, true, "the production renderer must surface a stale projection");
+    } else if (scenario.point === "after-independent-reopen") {
+      assert.equal(completionError, undefined, "completion must succeed before the reopen fault");
+      assert.equal(completionStale, false, "completion must not be stale before the reopen fault");
+    } else {
+      assert.match(String(completionError), new RegExp(scenario.point));
+    }
+
+    writeContradictoryProjection(fixture.root, scenario.committed);
+    closeDatabase();
+    if (scenario.point === "after-independent-reopen") {
+      const faultedChild = runAuthorityProcess(fixture.root, fixture.dbPath, scenario.point);
+      assert.notEqual(faultedChild.status, 0, "fresh process must fault after opening the database");
+      assert.match(faultedChild.stderr, /DATABASE_OPENED_BEFORE_FAULT=/);
+      assert.match(faultedChild.stderr, /after-independent-reopen/);
+    }
+    const snapshot = readAuthorityInFreshProcess(fixture.root, fixture.dbPath);
+    fixture.reopen();
+
+    const expectedStatus = scenario.committed ? "complete" : "pending";
+    const { pid, ...authority } = snapshot;
+    assert.notEqual(pid, process.pid, "authority must be verified by another process");
+    assert.deepEqual(authority, {
+      taskStatus: "complete",
+      sliceStatus: expectedStatus,
+      activeSlice: scenario.committed ? "S03" : "S02",
+    });
+    assert.equal(getTask("M001", "S02", "T01")?.status, "complete");
+    assert.equal(getSlice("M001", "S02")?.status, expectedStatus);
+  });
+}

package/src/resources/extensions/gsd/tests/workflow-authority-fixture.test.ts

@@ -0,0 +1,48 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { getMilestoneSlices, getSliceTasks } from "../gsd-db.ts";
+import { queryDecisionsFromMemories, queryRequirements } from "../context-store.ts";
+import { deriveStateFromDb } from "../state.ts";
+import { createWorkflowAuthorityFixture } from "./workflow-authority-fixture.ts";
+
+test("workflow authority fixture seeds a reopenable DB-backed workflow", async (t) => {
+  const fixture = await createWorkflowAuthorityFixture();
+  t.after(() => fixture.cleanup());
+  fixture.reopen();
+
+  const state = await deriveStateFromDb(fixture.root);
+  const slices = getMilestoneSlices(fixture.ids.milestone);
+  const completedTasks = getSliceTasks(fixture.ids.milestone, fixture.ids.completedSlice);
+  const readyTasks = getSliceTasks(fixture.ids.milestone, fixture.ids.readySlice);
+  const requirements = queryRequirements({
+    milestoneId: fixture.ids.milestone,
+    sliceId: fixture.ids.readySlice,
+  });
+  const decisions = queryDecisionsFromMemories({ milestoneId: fixture.ids.milestone });
+
+  assert.equal(state.phase, "executing");
+  assert.equal(state.activeMilestone?.id, fixture.ids.milestone);
+  assert.equal(state.activeSlice?.id, fixture.ids.readySlice);
+  assert.equal(state.activeTask?.id, fixture.ids.readyTask);
+  assert.deepEqual(
+    slices.map((slice) => ({ id: slice.id, status: slice.status, depends: slice.depends })),
+    [
+      { id: fixture.ids.completedSlice, status: "complete", depends: [] },
+      { id: fixture.ids.readySlice, status: "pending", depends: [fixture.ids.completedSlice] },
+    ],
+  );
+  assert.deepEqual(
+    completedTasks.map((task) => ({ id: task.id, status: task.status })),
+    [{ id: fixture.ids.completedTask, status: "complete" }],
+  );
+  assert.deepEqual(
+    readyTasks.map((task) => ({ id: task.id, status: task.status })),
+    [{ id: fixture.ids.readyTask, status: "pending" }],
+  );
+  assert.ok(state.requirements);
+  assert.equal(state.requirements.active, 1);
+  assert.equal(state.requirements.total, 1);
+  assert.deepEqual(requirements.map((requirement) => requirement.id), [fixture.ids.requirement]);
+  assert.deepEqual(decisions.map((decision) => decision.id), [fixture.ids.decision]);
+});

package/src/resources/extensions/gsd/tests/workflow-authority-fixture.ts

@@ -0,0 +1,141 @@
+import { mkdirSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  openDatabase,
+  transaction,
+} from "../gsd-db.ts";
+import { saveDecisionToDb, saveRequirementToDb } from "../db-writer.ts";
+import { invalidateStateCache } from "../state.ts";
+
+export interface WorkflowAuthorityFixture {
+  root: string;
+  dbPath: string;
+  ids: {
+    milestone: string;
+    completedSlice: string;
+    readySlice: string;
+    completedTask: string;
+    readyTask: string;
+    requirement: string;
+    decision: string;
+  };
+  reopen(): void;
+  cleanup(): void;
+}
+
+function openFixtureDatabase(dbPath: string): void {
+  if (!openDatabase(dbPath)) {
+    throw new Error(`Could not open workflow authority fixture database: ${dbPath}`);
+  }
+}
+
+export async function createWorkflowAuthorityFixture(): Promise<WorkflowAuthorityFixture> {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-workflow-authority-")));
+  const dbPath = join(root, ".gsd", "gsd.db");
+  let cleanedUp = false;
+
+  mkdirSync(join(root, ".gsd"), { recursive: true });
+  openFixtureDatabase(dbPath);
+
+  try {
+    transaction(() => {
+      insertMilestone({ id: "M001", title: "Authority Fixture", status: "active" });
+      insertSlice({
+        id: "S01",
+        milestoneId: "M001",
+        title: "Completed prerequisite",
+        status: "complete",
+        risk: "low",
+        depends: [],
+        sequence: 1,
+      });
+      insertSlice({
+        id: "S02",
+        milestoneId: "M001",
+        title: "Ready dependent slice",
+        status: "pending",
+        risk: "medium",
+        depends: ["S01"],
+        sequence: 2,
+      });
+      insertTask({
+        id: "T01",
+        milestoneId: "M001",
+        sliceId: "S01",
+        title: "Completed task",
+        status: "complete",
+        sequence: 1,
+      });
+      insertTask({
+        id: "T01",
+        milestoneId: "M001",
+        sliceId: "S02",
+        title: "Ready task",
+        status: "pending",
+        sequence: 1,
+      });
+    });
+
+    const requirement = await saveRequirementToDb(
+      {
+        class: "core-capability",
+        status: "active",
+        description: "SQLite is authoritative",
+        why: "Readable projections must not control workflow state.",
+        source: "workflow-authority-fixture",
+        primary_owner: "M001/S02",
+        validation: "DB-derived state remains canonical",
+      },
+      root,
+    );
+    const decision = await saveDecisionToDb(
+      {
+        when_context: "M001/S02",
+        scope: "architecture",
+        decision: "Choose the workflow authority",
+        choice: "SQLite is authoritative",
+        rationale: "Projections may lag without losing saved intent.",
+        revisable: "No",
+        made_by: "human",
+        source: "discussion",
+      },
+      root,
+    );
+
+    return {
+      root,
+      dbPath,
+      ids: {
+        milestone: "M001",
+        completedSlice: "S01",
+        readySlice: "S02",
+        completedTask: "T01",
+        readyTask: "T01",
+        requirement: requirement.id,
+        decision: decision.id,
+      },
+      reopen() {
+        closeDatabase();
+        openFixtureDatabase(dbPath);
+        invalidateStateCache();
+      },
+      cleanup() {
+        if (cleanedUp) return;
+        cleanedUp = true;
+        closeDatabase();
+        invalidateStateCache();
+        rmSync(root, { recursive: true, force: true });
+      },
+    };
+  } catch (error) {
+    closeDatabase();
+    rmSync(root, { recursive: true, force: true });
+    throw error;
+  }
+}

package/src/resources/extensions/gsd/tests/workflow-authority-projection-conflict.test.ts

@@ -0,0 +1,177 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { getMilestoneSlices, getSliceTasks } from "../gsd-db.ts";
+import { queryDecisionsFromMemories, queryRequirements } from "../context-store.ts";
+import { deriveStateFromDb } from "../state.ts";
+import {
+  createWorkflowAuthorityFixture,
+  type WorkflowAuthorityFixture,
+} from "./workflow-authority-fixture.ts";
+
+function writeProjection(root: string, path: string, content: string): void {
+  const fullPath = join(root, ".gsd", path);
+  mkdirSync(dirname(fullPath), { recursive: true });
+  writeFileSync(fullPath, content, "utf8");
+}
+
+function writeContradictoryProjections(root: string): void {
+  writeProjection(
+    root,
+    "STATE.md",
+    [
+      "# GSD State",
+      "",
+      "**Active Milestone:** M999",
+      "**Active Slice:** S99",
+      "**Phase:** complete",
+      "**Requirements Status:** 0 active · 1 validated",
+    ].join("\n"),
+  );
+  writeProjection(
+    root,
+    "PROJECT.md",
+    [
+      "# Projection-only project",
+      "",
+      "## Milestone Sequence",
+      "- [x] M001: Falsely complete",
+      "- [ ] M999: Projection-only active milestone",
+    ].join("\n"),
+  );
+  writeProjection(
+    root,
+    "REQUIREMENTS.md",
+    [
+      "# Requirements",
+      "",
+      "## Validated",
+      "### R999 — Markdown controls workflow state",
+      "- Status: validated",
+      "- Primary owning slice: M999/S99",
+    ].join("\n"),
+  );
+  writeProjection(
+    root,
+    "DECISIONS.md",
+    [
+      "# Decisions Register",
+      "",
+      "| # | When | Scope | Decision | Choice | Rationale | Revisable? | Made By |",
+      "|---|------|-------|----------|--------|-----------|------------|---------|",
+      "| D999 | M999/S99 | architecture | Choose authority | Markdown is authoritative | projection conflict | No | human |",
+    ].join("\n"),
+  );
+  writeProjection(
+    root,
+    "milestones/M001/M001-ROADMAP.md",
+    [
+      "# M001: Falsely complete",
+      "",
+      "## Slices",
+      "- [ ] **S01: Falsely reopened** `risk:low` `depends:[]`",
+      "- [x] **S02: Falsely complete** `risk:low` `depends:[]`",
+    ].join("\n"),
+  );
+  writeProjection(
+    root,
+    "milestones/M001/slices/S02/S02-PLAN.md",
+    [
+      "# S02: Falsely complete",
+      "",
+      "## Tasks",
+      "- [x] **T99: Projection-only task** `est:1m`",
+    ].join("\n"),
+  );
+}
+
+async function readDirectDbAuthoritySnapshot(fixture: WorkflowAuthorityFixture) {
+  const state = await deriveStateFromDb(fixture.root);
+  return {
+    state: {
+      phase: state.phase,
+      milestone: state.activeMilestone?.id ?? null,
+      slice: state.activeSlice?.id ?? null,
+      task: state.activeTask?.id ?? null,
+      requirements: state.requirements,
+    },
+    registry: state.registry.map((milestone) => ({
+      id: milestone.id,
+      status: milestone.status,
+    })),
+    slices: getMilestoneSlices(fixture.ids.milestone).map((slice) => ({
+      id: slice.id,
+      status: slice.status,
+      depends: slice.depends,
+    })),
+    tasks: {
+      completed: getSliceTasks(fixture.ids.milestone, fixture.ids.completedSlice).map((task) => ({
+        id: task.id,
+        status: task.status,
+      })),
+      ready: getSliceTasks(fixture.ids.milestone, fixture.ids.readySlice).map((task) => ({
+        id: task.id,
+        status: task.status,
+      })),
+    },
+    requirements: queryRequirements({
+      milestoneId: fixture.ids.milestone,
+      sliceId: fixture.ids.readySlice,
+    }).map((requirement) => ({
+      id: requirement.id,
+      status: requirement.status,
+      owner: requirement.primary_owner,
+    })),
+    decisions: queryDecisionsFromMemories().map((decision) => ({
+      id: decision.id,
+      choice: decision.choice,
+    })),
+  };
+}
+
+test("direct DB authority queries ignore contradictory Markdown projections", async (t) => {
+  const fixture = await createWorkflowAuthorityFixture();
+  t.after(() => fixture.cleanup());
+  fixture.reopen();
+  const before = await readDirectDbAuthoritySnapshot(fixture);
+
+  assert.deepEqual(before, {
+    state: {
+      phase: "executing",
+      milestone: fixture.ids.milestone,
+      slice: fixture.ids.readySlice,
+      task: fixture.ids.readyTask,
+      requirements: {
+        active: 1,
+        validated: 0,
+        deferred: 0,
+        outOfScope: 0,
+        blocked: 0,
+        total: 1,
+      },
+    },
+    registry: [{ id: fixture.ids.milestone, status: "active" }],
+    slices: [
+      { id: fixture.ids.completedSlice, status: "complete", depends: [] },
+      { id: fixture.ids.readySlice, status: "pending", depends: [fixture.ids.completedSlice] },
+    ],
+    tasks: {
+      completed: [{ id: fixture.ids.completedTask, status: "complete" }],
+      ready: [{ id: fixture.ids.readyTask, status: "pending" }],
+    },
+    requirements: [
+      { id: fixture.ids.requirement, status: "active", owner: "M001/S02" },
+    ],
+    decisions: [
+      { id: fixture.ids.decision, choice: "SQLite is authoritative" },
+    ],
+  });
+
+  writeContradictoryProjections(fixture.root);
+  fixture.reopen();
+
+  const after = await readDirectDbAuthoritySnapshot(fixture);
+  assert.deepEqual(after, before);
+});

package/src/resources/extensions/gsd/tests/workflow-fault-harness.test.ts

@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  createWorkflowFaultHarness,
+  type WorkflowFaultPoint,
+} from "./workflow-fault-harness.js";
+
+test("fault harness throws once at the armed named boundary", () => {
+  const harness = createWorkflowFaultHarness("after-db-commit-before-render");
+
+  harness.hit("before-transaction-commit", "complete-task");
+  assert.throws(
+    () => harness.hit("after-db-commit-before-render", "complete-task"),
+    /complete-task.*after-db-commit-before-render.*hit 1/,
+  );
+
+  assert.equal(harness.count("before-transaction-commit"), 1);
+  assert.equal(harness.count("after-db-commit-before-render"), 1);
+});
+
+test("fault harness automatically disarms after its first matching hit", () => {
+  const point: WorkflowFaultPoint = "during-projection-write";
+  const harness = createWorkflowFaultHarness(point);
+
+  assert.throws(() => harness.hit(point, "complete-slice"));
+  assert.doesNotThrow(() => harness.hit(point, "complete-slice"));
+  assert.equal(harness.count(point), 2);
+});
+
+test("fault harness instances never share armed state or counts", () => {
+  const first = createWorkflowFaultHarness("before-independent-reopen");
+  const second = createWorkflowFaultHarness("before-independent-reopen");
+
+  assert.throws(() => first.hit("before-independent-reopen", "resume"));
+  assert.equal(first.count("before-independent-reopen"), 1);
+  assert.equal(second.count("before-independent-reopen"), 0);
+  assert.throws(() => second.hit("before-independent-reopen", "resume"));
+});