@duypham93/openkit 0.2.0

package/.opencode/tests/session-start-hook.test.js

@@ -0,0 +1,357 @@
+const test = require("node:test")
+const assert = require("node:assert/strict")
+const fs = require("fs")
+const os = require("os")
+const path = require("path")
+const { spawnSync } = require("child_process")
+
+function makeTempProject() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "openkit-session-hook-"))
+}
+
+function writeState(projectRoot, state) {
+  const opencodeDir = path.join(projectRoot, ".opencode")
+  fs.mkdirSync(opencodeDir, { recursive: true })
+  fs.writeFileSync(path.join(opencodeDir, "workflow-state.json"), `${JSON.stringify(state, null, 2)}\n`, "utf8")
+}
+
+function makeQuickState(overrides = {}) {
+  return {
+    feature_id: "TASK-500",
+    feature_slug: "quick-copy-fix",
+    mode: "quick",
+    mode_reason: "Scoped task",
+    routing_profile: {
+      work_intent: "maintenance",
+      behavior_delta: "preserve",
+      dominant_uncertainty: "low_local",
+      scope_shape: "local",
+      selection_reason: "Scoped task",
+    },
+    current_stage: "quick_verify",
+    status: "in_progress",
+    current_owner: "QAAgent",
+    artifacts: {
+      task_card: null,
+      brief: null,
+      spec: null,
+      architecture: null,
+      plan: null,
+      migration_report: null,
+      qa_report: null,
+      adr: [],
+    },
+    approvals: {
+      quick_verified: {
+        status: "pending",
+        approved_by: null,
+        approved_at: null,
+        notes: null,
+      },
+    },
+    issues: [],
+    retry_count: 0,
+    escalated_from: null,
+    escalation_reason: null,
+    updated_at: "2026-03-21T00:00:00.000Z",
+    ...overrides,
+  }
+}
+
+function writeManifest(projectRoot) {
+  const opencodeDir = path.join(projectRoot, ".opencode")
+  fs.mkdirSync(opencodeDir, { recursive: true })
+  fs.writeFileSync(
+    path.join(opencodeDir, "opencode.json"),
+    `${JSON.stringify({
+      kit: {
+        name: "OpenKit AI Software Factory",
+        version: "0.1.0",
+        entryAgent: "MasterOrchestrator",
+      },
+    }, null, 2)}\n`,
+    "utf8",
+  )
+}
+
+function writeWorkItemBoard(projectRoot, workItemId, board) {
+  const boardPath = path.join(projectRoot, ".opencode", "work-items", workItemId, "tasks.json")
+  fs.mkdirSync(path.dirname(boardPath), { recursive: true })
+  fs.writeFileSync(boardPath, `${JSON.stringify(board, null, 2)}\n`, "utf8")
+}
+
+function makeFullState(overrides = {}) {
+  return {
+    feature_id: "FEATURE-700",
+    feature_slug: "parallel-runtime-rollout",
+    mode: "full",
+    mode_reason: "Feature-sized task board rollout",
+    routing_profile: {
+      work_intent: "feature",
+      behavior_delta: "extend",
+      dominant_uncertainty: "product",
+      scope_shape: "cross_boundary",
+      selection_reason: "Feature-sized task board rollout",
+    },
+    current_stage: "full_implementation",
+    status: "in_progress",
+    current_owner: "FullstackAgent",
+    artifacts: {
+      task_card: null,
+      brief: "docs/briefs/2026-03-21-parallel-runtime-rollout.md",
+      spec: "docs/specs/2026-03-21-parallel-runtime-rollout.md",
+      architecture: "docs/architecture/2026-03-21-parallel-runtime-rollout.md",
+      plan: "docs/plans/2026-03-21-parallel-runtime-rollout.md",
+      migration_report: null,
+      qa_report: null,
+      adr: [],
+    },
+    approvals: {
+      pm_to_ba: { status: "approved", approved_by: "BAAgent", approved_at: "2026-03-21", notes: "ok" },
+      ba_to_architect: { status: "approved", approved_by: "ArchitectAgent", approved_at: "2026-03-21", notes: "ok" },
+      architect_to_tech_lead: { status: "approved", approved_by: "TechLeadAgent", approved_at: "2026-03-21", notes: "ok" },
+      tech_lead_to_fullstack: { status: "approved", approved_by: "FullstackAgent", approved_at: "2026-03-21", notes: "ok" },
+      fullstack_to_qa: { status: "pending", approved_by: null, approved_at: null, notes: null },
+      qa_to_done: { status: "pending", approved_by: null, approved_at: null, notes: null },
+    },
+    issues: [],
+    retry_count: 0,
+    escalated_from: null,
+    escalation_reason: null,
+    updated_at: "2026-03-21T00:00:00.000Z",
+    work_item_id: "feature-700",
+    ...overrides,
+  }
+}
+
+function writeMetaSkill(projectRoot) {
+  const skillDir = path.join(projectRoot, "skills", "using-skills")
+  fs.mkdirSync(skillDir, { recursive: true })
+  fs.writeFileSync(path.join(skillDir, "SKILL.md"), "# using-skills\n", "utf8")
+}
+
+function writeFailingPythonShim(projectRoot) {
+  const binDir = path.join(projectRoot, "bin")
+  const shimPath = path.join(binDir, "python3-shim")
+  fs.mkdirSync(binDir, { recursive: true })
+  fs.writeFileSync(shimPath, "#!/usr/bin/env bash\nexit 1\n", { encoding: "utf8", mode: 0o755 })
+  return shimPath
+}
+
+test("session-start emits mode-aware resume hint for quick tasks", () => {
+  const projectRoot = makeTempProject()
+
+  writeManifest(projectRoot)
+  writeState(projectRoot, makeQuickState())
+
+  const result = spawnSync(path.resolve(__dirname, "../../hooks/session-start"), {
+    cwd: projectRoot,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      OPENKIT_PROJECT_ROOT: projectRoot,
+      OPENKIT_SESSION_START_NO_SKILL: "1",
+      OPENKIT_WORKFLOW_STATE: path.join(projectRoot, ".opencode", "workflow-state.json"),
+    },
+  })
+
+  assert.equal(result.status, 0)
+  assert.match(result.stdout, /<openkit_runtime_status>/)
+  assert.match(result.stdout, /kit: OpenKit AI Software Factory v0\.1\.0/)
+  assert.match(result.stdout, /startup skill: skipped/)
+  assert.match(result.stdout, /node \.opencode\/workflow-state\.js status/)
+  assert.match(result.stdout, /node \.opencode\/workflow-state\.js doctor/)
+  assert.match(result.stdout, /<workflow_resume_hint>/)
+  assert.match(result.stdout, /mode: quick/)
+  assert.match(result.stdout, /stage: quick_verify/)
+  assert.match(result.stdout, /work item: TASK-500 \(quick-copy-fix\)/)
+})
+
+test("session-start reports quick_plan as a resumable quick stage", () => {
+  const projectRoot = makeTempProject()
+
+  writeManifest(projectRoot)
+  writeState(
+    projectRoot,
+    makeQuickState({
+      feature_id: "TASK-502",
+      feature_slug: "quick-plan-resume",
+      current_stage: "quick_plan",
+      current_owner: "MasterOrchestrator",
+    }),
+  )
+
+  const result = spawnSync(path.resolve(__dirname, "../../hooks/session-start"), {
+    cwd: projectRoot,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      OPENKIT_PROJECT_ROOT: projectRoot,
+      OPENKIT_SESSION_START_NO_SKILL: "1",
+      OPENKIT_WORKFLOW_STATE: path.join(projectRoot, ".opencode", "workflow-state.json"),
+    },
+  })
+
+  assert.equal(result.status, 0)
+  assert.match(result.stdout, /<workflow_resume_hint>/)
+  assert.match(result.stdout, /mode: quick/)
+  assert.match(result.stdout, /stage: quick_plan/)
+  assert.match(result.stdout, /owner: MasterOrchestrator/)
+})
+
+test("session-start reports loaded startup skill when meta-skill exists", () => {
+  const projectRoot = makeTempProject()
+
+  writeManifest(projectRoot)
+  writeMetaSkill(projectRoot)
+  writeState(
+    projectRoot,
+    makeQuickState({
+      feature_id: "TASK-501",
+      feature_slug: "loaded-skill",
+      current_stage: "quick_intake",
+      current_owner: "MasterOrchestrator",
+    }),
+  )
+
+  const result = spawnSync(path.resolve(__dirname, "../../hooks/session-start"), {
+    cwd: projectRoot,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      OPENKIT_PROJECT_ROOT: projectRoot,
+      OPENKIT_WORKFLOW_STATE: path.join(projectRoot, ".opencode", "workflow-state.json"),
+    },
+  })
+
+  assert.equal(result.status, 0)
+  assert.match(result.stdout, /startup skill: loaded/)
+  assert.match(result.stdout, /<skill_system_instruction>/)
+})
+
+test("session-start prints canonical resume guidance and inspection commands", () => {
+  const projectRoot = makeTempProject()
+
+  writeManifest(projectRoot)
+  writeState(
+    projectRoot,
+    makeQuickState({
+      feature_id: "TASK-503",
+      feature_slug: "canonical-resume-guidance",
+      current_stage: "quick_build",
+      current_owner: "FullstackAgent",
+    }),
+  )
+
+  const result = spawnSync(path.resolve(__dirname, "../../hooks/session-start"), {
+    cwd: projectRoot,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      OPENKIT_PROJECT_ROOT: projectRoot,
+      OPENKIT_SESSION_START_NO_SKILL: "1",
+      OPENKIT_WORKFLOW_STATE: path.join(projectRoot, ".opencode", "workflow-state.json"),
+    },
+  })
+
+  assert.equal(result.status, 0)
+  assert.match(result.stdout, /help: node \.opencode\/workflow-state\.js status/)
+  assert.match(result.stdout, /doctor: node \.opencode\/workflow-state\.js doctor/)
+  assert.match(result.stdout, /show: node \.opencode\/workflow-state\.js show/)
+  assert.match(result.stdout, /Read first: AGENTS\.md -> context\/navigation\.md -> context\/core\/workflow\.md -> \.opencode\/workflow-state\.json/)
+  assert.match(result.stdout, /Then load resume guidance from context\/core\/session-resume\.md\./)
+})
+
+test("session-start degrades gracefully when the JSON helper fails", () => {
+  const projectRoot = makeTempProject()
+
+  writeManifest(projectRoot)
+  writeState(projectRoot, makeQuickState())
+  const pythonShim = writeFailingPythonShim(projectRoot)
+
+  const result = spawnSync(path.resolve(__dirname, "../../hooks/session-start"), {
+    cwd: projectRoot,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      OPENKIT_PROJECT_ROOT: projectRoot,
+      OPENKIT_SESSION_START_NO_SKILL: "1",
+      OPENKIT_WORKFLOW_STATE: path.join(projectRoot, ".opencode", "workflow-state.json"),
+      OPENKIT_PYTHON_BIN: pythonShim,
+    },
+  })
+
+  assert.equal(result.status, 0)
+  assert.match(result.stdout, /<openkit_runtime_status>/)
+  assert.match(result.stdout, /json helper: degraded/)
+  assert.doesNotMatch(result.stdout, /<workflow_resume_hint>/)
+})
+
+test("session-start emits task-aware resume hint for active full-delivery work", () => {
+  const projectRoot = makeTempProject()
+
+  writeManifest(projectRoot)
+  writeState(projectRoot, makeFullState())
+  writeWorkItemBoard(projectRoot, "feature-700", {
+    mode: "full",
+    current_stage: "full_implementation",
+    tasks: [
+      {
+        task_id: "TASK-700-A",
+        title: "Implement diagnostics",
+        summary: "Task-aware summaries",
+        kind: "implementation",
+        status: "in_progress",
+        primary_owner: "Dev-A",
+        qa_owner: null,
+        depends_on: [],
+        blocked_by: [],
+        artifact_refs: [],
+        plan_refs: ["docs/plans/2026-03-21-parallel-runtime-rollout.md"],
+        branch_or_worktree: ".worktrees/parallel-agent-rollout/task-700-a",
+        created_by: "TechLeadAgent",
+        created_at: "2026-03-21T00:00:00.000Z",
+        updated_at: "2026-03-21T00:00:00.000Z",
+      },
+      {
+        task_id: "TASK-700-B",
+        title: "QA diagnostics",
+        summary: "QA active task",
+        kind: "qa",
+        status: "qa_in_progress",
+        primary_owner: "Dev-B",
+        qa_owner: "QA-Agent",
+        depends_on: [],
+        blocked_by: [],
+        artifact_refs: [],
+        plan_refs: ["docs/plans/2026-03-21-parallel-runtime-rollout.md"],
+        branch_or_worktree: ".worktrees/parallel-agent-rollout/task-700-b",
+        created_by: "TechLeadAgent",
+        created_at: "2026-03-21T00:00:00.000Z",
+        updated_at: "2026-03-21T00:00:00.000Z",
+      },
+    ],
+    issues: [],
+  })
+
+  const result = spawnSync(path.resolve(__dirname, "../../hooks/session-start"), {
+    cwd: projectRoot,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      OPENKIT_PROJECT_ROOT: projectRoot,
+      OPENKIT_SESSION_START_NO_SKILL: "1",
+      OPENKIT_WORKFLOW_STATE: path.join(projectRoot, ".opencode", "workflow-state.json"),
+    },
+  })
+
+  assert.equal(result.status, 0)
+  assert.match(result.stdout, /<workflow_resume_hint>/)
+  assert.match(result.stdout, /mode: full/)
+  assert.match(result.stdout, /stage: full_implementation/)
+  assert.match(result.stdout, /work item: FEATURE-700 \(parallel-runtime-rollout\)/)
+  assert.match(result.stdout, /active work item id: feature-700/)
+  assert.match(result.stdout, /task board: 2 tasks \| ready 0 \| active 2/)
+  assert.match(result.stdout, /active tasks: TASK-700-A \(in_progress, primary: Dev-A\); TASK-700-B \(qa_in_progress, qa: QA-Agent\)/)
+  assert.match(result.stdout, /Parallel task support is not yet assumed safe by this hook; confirm with `node \.opencode\/workflow-state\.js doctor` before relying on it\./)
+})

package/.opencode/tests/state-guard.test.js

@@ -0,0 +1,124 @@
+const test = require("node:test")
+const assert = require("node:assert/strict")
+
+const {
+  captureRevision,
+  detectMirrorDivergence,
+  guardWrite,
+  planGuardedMirrorRefresh,
+} = require("../lib/state-guard")
+
+function createState(overrides = {}) {
+  return {
+    work_item_id: "feature-100",
+    feature_id: "FEATURE-100",
+    feature_slug: "parallel-runtime",
+    mode: "full",
+    routing_profile: {
+      work_intent: "feature",
+      behavior_delta: "extend",
+      dominant_uncertainty: "product",
+      scope_shape: "cross_boundary",
+      selection_reason: "feature example",
+    },
+    current_stage: "full_plan",
+    status: "in_progress",
+    updated_at: "2026-03-21T00:00:00.000Z",
+    ...overrides,
+  }
+}
+
+test("captureRevision returns a stable revision for equivalent state content", () => {
+  const first = createState({ artifacts: { plan: "docs/plans/feature-100.md", migration_report: null, qa_report: null } })
+  const second = {
+    status: "in_progress",
+    current_stage: "full_plan",
+    updated_at: "2026-03-21T00:00:00.000Z",
+    work_item_id: "feature-100",
+    feature_slug: "parallel-runtime",
+    feature_id: "FEATURE-100",
+    mode: "full",
+    routing_profile: {
+      selection_reason: "feature example",
+      scope_shape: "cross_boundary",
+      dominant_uncertainty: "product",
+      behavior_delta: "extend",
+      work_intent: "feature",
+    },
+    artifacts: { qa_report: null, migration_report: null, plan: "docs/plans/feature-100.md" },
+  }
+
+  const firstRevision = captureRevision(first)
+  const secondRevision = captureRevision(second)
+
+  assert.equal(typeof firstRevision, "string")
+  assert.equal(firstRevision.length > 0, true)
+  assert.equal(firstRevision, secondRevision)
+})
+
+test("guardWrite rejects compare-and-swap writes when the expected revision is stale", () => {
+  const persistedState = createState({ status: "in_progress" })
+  const staleState = createState({ status: "queued" })
+
+  const expectedRevision = captureRevision(staleState)
+  const currentRevision = captureRevision(persistedState)
+
+  let staleWriteError = null
+
+  try {
+    guardWrite({ currentState: persistedState, expectedRevision, nextState: createState({ status: "done" }) })
+  } catch (error) {
+    staleWriteError = error
+  }
+
+  assert.ok(staleWriteError)
+  assert.equal(staleWriteError.code, "STALE_WRITE")
+  assert.equal(staleWriteError.currentRevision, currentRevision)
+  assert.equal(staleWriteError.expectedRevision, expectedRevision)
+})
+
+test("planGuardedMirrorRefresh exposes abstract ordered phases without storage sink names", () => {
+  const activeState = createState({ status: "ready_for_qa" })
+
+  const activePlan = planGuardedMirrorRefresh({
+    activeWorkItemId: "feature-100",
+    targetWorkItemId: "feature-100",
+    nextState: activeState,
+  })
+
+  assert.equal(activePlan.shouldRefreshMirror, true)
+  assert.deepEqual(activePlan.phases, ["primary", "replica"])
+  assert.equal(activePlan.mirrorRevision, captureRevision(activeState))
+
+  const inactivePlan = planGuardedMirrorRefresh({
+    activeWorkItemId: "feature-100",
+    targetWorkItemId: "feature-101",
+    nextState: createState({ work_item_id: "feature-101", feature_id: "FEATURE-101" }),
+  })
+
+  assert.equal(inactivePlan.shouldRefreshMirror, false)
+  assert.deepEqual(inactivePlan.phases, ["primary"])
+})
+
+test("detectMirrorDivergence reports lagging or failed mirror refreshes against the active item revision", () => {
+  const activeState = createState({ status: "done" })
+  const staleMirrorState = createState({ status: "in_progress" })
+
+  const laggingMirror = detectMirrorDivergence({
+    activeWorkItemId: "feature-100",
+    activeState,
+    mirrorState: staleMirrorState,
+  })
+
+  assert.equal(laggingMirror.isDiverged, true)
+  assert.equal(laggingMirror.reason, "revision_mismatch")
+
+  const failedMirror = detectMirrorDivergence({
+    activeWorkItemId: "feature-100",
+    activeState,
+    mirrorState: null,
+  })
+
+  assert.equal(failedMirror.isDiverged, true)
+  assert.equal(failedMirror.reason, "mirror_missing")
+})

package/.opencode/tests/task-board-rules.test.js

@@ -0,0 +1,204 @@
+const test = require("node:test")
+const assert = require("node:assert/strict")
+
+const {
+  TASK_STATUS_VALUES,
+  validateTaskBoard,
+  validateTaskShape,
+  validateTaskStatus,
+  validateTaskTransition,
+} = require("../lib/task-board-rules")
+
+function makeTask(overrides = {}) {
+  return {
+    task_id: "TASK-1",
+    title: "Implement task board helper",
+    summary: "Add isolated validation rules",
+    kind: "implementation",
+    status: "ready",
+    primary_owner: null,
+    qa_owner: null,
+    depends_on: [],
+    blocked_by: [],
+    artifact_refs: [],
+    plan_refs: ["docs/plans/2026-03-21-feature.md"],
+    branch_or_worktree: null,
+    created_by: "TechLeadAgent",
+    created_at: "2026-03-21T00:00:00.000Z",
+    updated_at: "2026-03-21T00:00:00.000Z",
+    ...overrides,
+  }
+}
+
+function makeBoard(overrides = {}) {
+  return {
+    mode: "full",
+    current_stage: "full_plan",
+    tasks: [makeTask()],
+    issues: [],
+    ...overrides,
+  }
+}
+
+test("validateTaskShape accepts the minimum full-delivery task record", () => {
+  const task = makeTask()
+
+  assert.doesNotThrow(() => validateTaskShape(task))
+})
+
+test("validateTaskShape rejects records with missing required fields", () => {
+  const task = makeTask({ summary: undefined })
+
+  assert.throws(() => validateTaskShape(task), /summary/)
+})
+
+test("validateTaskShape rejects malformed array contents", () => {
+  assert.throws(() => validateTaskShape(makeTask({ depends_on: ["TASK-2", ""] })), /depends_on/)
+  assert.throws(() => validateTaskShape(makeTask({ blocked_by: [null] })), /blocked_by/)
+  assert.throws(() => validateTaskShape(makeTask({ artifact_refs: [42] })), /artifact_refs/)
+  assert.throws(() => validateTaskShape(makeTask({ plan_refs: [""] })), /plan_refs/)
+})
+
+test("validateTaskShape requires branch_or_worktree in the task contract", () => {
+  const task = makeTask()
+  delete task.branch_or_worktree
+
+  assert.throws(() => validateTaskShape(task), /branch_or_worktree/)
+})
+
+test("validateTaskStatus allows only documented task-board statuses", () => {
+  const expected = [
+    "queued",
+    "ready",
+    "claimed",
+    "in_progress",
+    "dev_done",
+    "qa_ready",
+    "qa_in_progress",
+    "done",
+    "blocked",
+    "cancelled",
+  ]
+
+  assert.deepEqual(TASK_STATUS_VALUES, expected)
+
+  for (const status of expected) {
+    assert.equal(validateTaskStatus(status), status)
+  }
+
+  assert.throws(() => validateTaskStatus("idle"), /Unknown task status/)
+})
+
+test("validateTaskTransition allows documented happy-path transitions", () => {
+  assert.doesNotThrow(() => validateTaskTransition(makeTask({ status: "queued" }), "ready"))
+  assert.doesNotThrow(() => validateTaskTransition(makeTask({ status: "ready" }), "claimed"))
+  assert.doesNotThrow(() => validateTaskTransition(makeTask({ status: "claimed", primary_owner: "DevA" }), "in_progress"))
+  assert.doesNotThrow(() => validateTaskTransition(makeTask({ status: "in_progress", primary_owner: "DevA" }), "dev_done"))
+  assert.doesNotThrow(() => validateTaskTransition(makeTask({ status: "dev_done", qa_owner: "QAAgent" }), "qa_ready"))
+  assert.doesNotThrow(() => validateTaskTransition(makeTask({ status: "dev_done", qa_owner: null }), "qa_ready", {
+    allowQaAssignment: true,
+  }))
+  assert.doesNotThrow(() => validateTaskTransition(makeTask({ status: "qa_ready", qa_owner: "QAAgent" }), "qa_in_progress"))
+  assert.doesNotThrow(() => validateTaskTransition(makeTask({ status: "qa_ready", qa_owner: null }), "qa_in_progress", {
+    allowQaClaim: true,
+  }))
+  assert.doesNotThrow(() => validateTaskTransition(makeTask({ status: "qa_in_progress", qa_owner: "QAAgent" }), "done"))
+  assert.doesNotThrow(() => validateTaskTransition(makeTask({ status: "qa_in_progress", qa_owner: "QAAgent" }), "blocked"))
+  assert.doesNotThrow(() => validateTaskTransition(makeTask({ status: "qa_in_progress", qa_owner: "QAAgent" }), "in_progress", {
+    allowQaFailRework: true,
+    finding: { task_id: "TASK-1", summary: "Needs rework" },
+  }))
+})
+
+test("validateTaskTransition rejects invalid edges and missing handoff requirements", () => {
+  assert.throws(() => validateTaskTransition(makeTask({ status: "dev_done" }), "done"), /Invalid task transition/)
+  assert.throws(() => validateTaskTransition(makeTask({ status: "claimed" }), "dev_done"), /Invalid task transition/)
+  assert.throws(() => validateTaskTransition(makeTask({ status: "dev_done", qa_owner: null }), "qa_ready"), /qa_owner|QA assignment/)
+  assert.throws(() => validateTaskTransition(makeTask({ status: "qa_ready", qa_owner: null }), "qa_in_progress"), /qa_owner|QA claim/)
+  assert.throws(() => validateTaskTransition(makeTask({ status: "qa_in_progress", qa_owner: "QAAgent" }), "claimed"), /QA fail rework/)
+  assert.throws(() => validateTaskTransition(makeTask({ status: "qa_in_progress", qa_owner: "QAAgent" }), "claimed", {
+    allowQaFailRework: true,
+  }), /finding/)
+})
+
+test("validateTaskTransition rejects claiming tasks blocked by unresolved dependencies", () => {
+  const task = makeTask({
+    status: "ready",
+    depends_on: ["TASK-0"],
+    blocked_by: ["TASK-0"],
+  })
+
+  assert.throws(() => validateTaskTransition(task, "claimed"), /blocked dependency/)
+})
+
+test("validateTaskBoard rejects quick-mode task boards", () => {
+  assert.throws(() => validateTaskBoard(makeBoard({ mode: "quick", current_stage: "quick_plan" })), /Quick mode/)
+})
+
+test("validateTaskBoard rejects migration-mode task boards", () => {
+  assert.throws(
+    () => validateTaskBoard(makeBoard({ mode: "migration", current_stage: "migration_strategy" })),
+    /Migration mode/,
+  )
+})
+
+test("validateTaskBoard rejects dependency cycles", () => {
+  const tasks = [
+    makeTask({ task_id: "TASK-1", depends_on: ["TASK-2"], blocked_by: ["TASK-2"] }),
+    makeTask({ task_id: "TASK-2", depends_on: ["TASK-1"], blocked_by: ["TASK-1"] }),
+  ]
+
+  assert.throws(() => validateTaskBoard(makeBoard({ tasks })), /Dependency cycle/)
+})
+
+test("validateTaskBoard rejects duplicate task identifiers", () => {
+  const tasks = [
+    makeTask({ task_id: "TASK-1" }),
+    makeTask({ task_id: "TASK-1", title: "Duplicate task id" }),
+  ]
+
+  assert.throws(() => validateTaskBoard(makeBoard({ tasks })), /Duplicate task_id/)
+})
+
+test("validateTaskBoard rejects unknown dependency and blocker references", () => {
+  assert.throws(() => validateTaskBoard(makeBoard({
+    tasks: [makeTask({ depends_on: ["TASK-404"] })],
+  })), /depends on unknown task/)
+
+  assert.throws(() => validateTaskBoard(makeBoard({
+    tasks: [makeTask({ blocked_by: ["TASK-405"] })],
+  })), /blocked by unknown task/)
+})
+
+test("validateTaskBoard enforces full-delivery aggregate completion rules", () => {
+  const implementationBoard = makeBoard({
+    current_stage: "full_implementation",
+    tasks: [makeTask({ status: "queued" })],
+  })
+  assert.throws(() => validateTaskBoard(implementationBoard), /full_implementation/)
+
+  const qaBoard = makeBoard({
+    current_stage: "full_qa",
+    tasks: [makeTask({ status: "in_progress", primary_owner: "DevA" })],
+  })
+  assert.throws(() => validateTaskBoard(qaBoard), /full_qa/)
+
+  const doneBoard = makeBoard({
+    current_stage: "full_done",
+    tasks: [makeTask({ status: "qa_ready", qa_owner: "QAAgent" })],
+  })
+  assert.throws(() => validateTaskBoard(doneBoard), /full_done/)
+
+  const blockedIssueBoard = makeBoard({
+    current_stage: "full_done",
+    tasks: [makeTask({ status: "done", qa_owner: "QAAgent" })],
+    issues: [{ severity: "high", status: "open", blocks_completion: true }],
+  })
+  assert.throws(() => validateTaskBoard(blockedIssueBoard), /blocking issue/)
+
+  assert.doesNotThrow(() => validateTaskBoard(makeBoard({
+    current_stage: "full_done",
+    tasks: [makeTask({ status: "done", qa_owner: "QAAgent" })],
+    issues: [],
+  })))
+})