@vitest-agent/mcp 1.0.0

package/tools/tdd-artifact.js

@@ -0,0 +1,101 @@
+import { publicProcedure } from "../context.js";
+import { DataReader } from "@vitest-agent/sdk";
+import { Effect, ParseResult, Schema } from "effect";
+
+//#region src/tools/tdd-artifact.ts
+/**
+* `tdd_artifact_list` MCP tool — Schema-driven implementation.
+*
+* Returns the artifacts recorded for a TDD task, ordered with the
+* most recent first. The structuredContent payload carries
+* tddTaskId, the applied filters, the count, and the artifact
+* rows so the orchestrator can extract artifact ids without parsing
+* markdown. The legacy `format` input was dropped because
+* structuredContent supersedes it.
+*
+* @packageDocumentation
+*/
+const ArtifactKindSchema = Schema.Literal("test_written", "test_failed_run", "code_written", "test_passed_run", "refactor", "test_weakened");
+const TddArtifactRow = Schema.Struct({
+	id: Schema.Number.annotations({
+		title: "tdd_artifacts.id",
+		description: "Pass as `citedArtifactId` to `tdd_phase_transition_request`."
+	}),
+	tddTaskId: Schema.Number,
+	phaseId: Schema.Number,
+	phaseName: Schema.Literal("spike", "red", "red.triangulate", "green", "green.fake-it", "refactor", "extended-red", "green-without-red"),
+	artifactKind: ArtifactKindSchema,
+	behaviorId: Schema.NullOr(Schema.Number),
+	testCaseId: Schema.NullOr(Schema.Number),
+	testRunId: Schema.NullOr(Schema.Number),
+	testFirstFailureRunId: Schema.NullOr(Schema.Number),
+	recordedAt: Schema.String
+}).annotations({ identifier: "TddArtifactListRow" });
+const ArtifactFilters = Schema.Struct({
+	artifactKind: Schema.optional(ArtifactKindSchema),
+	phaseId: Schema.optional(Schema.Number),
+	behaviorId: Schema.optional(Schema.Number)
+}).annotations({ identifier: "TddArtifactFilters" });
+const TddArtifactListResult = Schema.Struct({
+	tddTaskId: Schema.Number,
+	filters: ArtifactFilters,
+	count: Schema.Number,
+	artifacts: Schema.Array(TddArtifactRow)
+}).annotations({
+	identifier: "TddArtifactListResult",
+	title: "tdd_artifact_list result",
+	description: "Newest-first artifact rows for a TDD task. Echoes the filters that were applied so callers can reason about what is/isn't included."
+});
+const describeFilters = (filters) => {
+	const parts = [];
+	if (filters.artifactKind !== void 0) parts.push(`artifactKind=${filters.artifactKind}`);
+	if (filters.phaseId !== void 0) parts.push(`phaseId=${filters.phaseId}`);
+	if (filters.behaviorId !== void 0) parts.push(`behaviorId=${filters.behaviorId}`);
+	return parts.length > 0 ? ` matching ${parts.join(", ")}` : "";
+};
+const formatTddArtifactListMarkdown = (data) => {
+	if (data.count === 0) return `No artifacts recorded for tdd_task ${data.tddTaskId}${describeFilters(data.filters)}.`;
+	const lines = [`# Artifacts for tdd_task ${data.tddTaskId} (newest first, ${data.count} shown)`, ""];
+	for (const r of data.artifacts) {
+		const extras = [`phase=${r.phaseName} [phaseId=${r.phaseId}]`];
+		if (r.behaviorId !== null) extras.push(`behaviorId=${r.behaviorId}`);
+		if (r.testCaseId !== null) extras.push(`testCaseId=${r.testCaseId}`);
+		if (r.testRunId !== null) extras.push(`testRunId=${r.testRunId}`);
+		lines.push(`- **${r.artifactKind}** [id=${r.id}] at=${r.recordedAt} ${extras.join(" ")}`);
+	}
+	return lines.join("\n");
+};
+const TddArtifactListAsMarkdown = Schema.transformOrFail(TddArtifactListResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(formatTddArtifactListMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "TddArtifactListAsMarkdown is one-way."))
+});
+const TddArtifactListInput = Schema.Struct({
+	tddTaskId: Schema.Number,
+	artifactKind: Schema.optional(ArtifactKindSchema),
+	phaseId: Schema.optional(Schema.Number),
+	behaviorId: Schema.optional(Schema.Number),
+	limit: Schema.optional(Schema.Number)
+});
+const tddArtifactList = publicProcedure.input(Schema.standardSchemaV1(TddArtifactListInput)).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+	const rows = yield* (yield* DataReader).listTddArtifactsForTask({
+		tddTaskId: input.tddTaskId,
+		...input.artifactKind !== void 0 && { artifactKind: input.artifactKind },
+		...input.phaseId !== void 0 && { phaseId: input.phaseId },
+		...input.behaviorId !== void 0 && { behaviorId: input.behaviorId },
+		...input.limit !== void 0 && { limit: input.limit }
+	});
+	return {
+		tddTaskId: input.tddTaskId,
+		filters: {
+			...input.artifactKind !== void 0 && { artifactKind: input.artifactKind },
+			...input.phaseId !== void 0 && { phaseId: input.phaseId },
+			...input.behaviorId !== void 0 && { behaviorId: input.behaviorId }
+		},
+		count: rows.length,
+		artifacts: rows
+	};
+})));
+
+//#endregion
+export { TddArtifactListAsMarkdown, TddArtifactListResult, tddArtifactList };

package/tools/tdd-behavior.js

@@ -0,0 +1,177 @@
+import { idempotentProcedure } from "../middleware/idempotency.js";
+import { catchTddErrorsAsEnvelope } from "./_tdd-error-envelope.js";
+import { BehaviorDetail, BehaviorRow, DataReader, DataStore } from "@vitest-agent/sdk";
+import { Effect, Match, Option, Schema } from "effect";
+
+//#region src/tools/tdd-behavior.ts
+/**
+* Consolidated `tdd_behavior` MCP tool.
+*
+* Replaces `tdd_behavior_create`, `tdd_behavior_update`,
+* `tdd_behavior_delete`, `tdd_behavior_get`, and `tdd_behavior_list`
+* (the latter already had a goal/tdd_task scope discriminator that
+* folds into the action discriminator here as `list_by_goal` /
+* `list_by_tdd_task`).
+*/
+const BehaviorStatus = Schema.Literal("pending", "in_progress", "done", "abandoned");
+const TddBehaviorErrorEnvelope = Schema.Struct({
+	ok: Schema.Literal(false).annotations({ description: "Discriminant — `false` when a tagged TDD error was caught." }),
+	error: Schema.Struct({
+		_tag: Schema.String.annotations({ description: "Tagged error name (e.g. BehaviorNotFoundError, GoalNotFoundError)." }),
+		message: Schema.String,
+		remediation: Schema.optional(Schema.String)
+	}).pipe(Schema.extend(Schema.Record({
+		key: Schema.String,
+		value: Schema.Unknown
+	})))
+}).annotations({ identifier: "TddBehaviorErrorEnvelope" });
+const TddBehaviorCreateOk = Schema.Struct({
+	ok: Schema.Literal(true),
+	action: Schema.Literal("create"),
+	behavior: BehaviorRow.annotations({ description: "Newly inserted behavior row." })
+});
+const TddBehaviorUpdateOk = Schema.Struct({
+	ok: Schema.Literal(true),
+	action: Schema.Literal("update"),
+	behavior: BehaviorRow.annotations({ description: "Updated behavior row." })
+});
+const TddBehaviorDeleteOk = Schema.Struct({
+	ok: Schema.Literal(true),
+	action: Schema.Literal("delete"),
+	id: Schema.Number
+});
+const TddBehaviorGetFound = Schema.Struct({
+	action: Schema.Literal("get"),
+	found: Schema.Literal(true),
+	behavior: BehaviorDetail.annotations({ description: "Behavior with parentGoal + dependencies[]." })
+});
+const TddBehaviorGetMissing = Schema.Struct({
+	action: Schema.Literal("get"),
+	found: Schema.Literal(false),
+	id: Schema.Number
+});
+const TddBehaviorListByGoalOk = Schema.Struct({
+	ok: Schema.Literal(true),
+	action: Schema.Literal("list_by_goal"),
+	goalId: Schema.Number,
+	behaviors: Schema.Array(BehaviorRow)
+});
+const TddBehaviorListByTddTaskOk = Schema.Struct({
+	ok: Schema.Literal(true),
+	action: Schema.Literal("list_by_tdd_task"),
+	tddTaskId: Schema.Number,
+	behaviors: Schema.Array(BehaviorRow)
+});
+const TddBehaviorResult = Schema.Union(TddBehaviorCreateOk, TddBehaviorUpdateOk, TddBehaviorDeleteOk, TddBehaviorGetFound, TddBehaviorGetMissing, TddBehaviorListByGoalOk, TddBehaviorListByTddTaskOk, TddBehaviorErrorEnvelope).annotations({
+	identifier: "TddBehaviorResult",
+	title: "tdd_behavior result",
+	description: "Discriminate on `action` (or `ok=false` for the tagged-error envelope)."
+});
+const CreateVariant = Schema.Struct({
+	action: Schema.Literal("create"),
+	goalId: Schema.Number,
+	behavior: Schema.String,
+	suggestedTestName: Schema.optional(Schema.String),
+	dependsOnBehaviorIds: Schema.optional(Schema.Array(Schema.Number))
+});
+const UpdateVariant = Schema.Struct({
+	action: Schema.Literal("update"),
+	id: Schema.Number,
+	behavior: Schema.optional(Schema.String),
+	suggestedTestName: Schema.optional(Schema.NullOr(Schema.String)),
+	status: Schema.optional(BehaviorStatus),
+	dependsOnBehaviorIds: Schema.optional(Schema.Array(Schema.Number))
+});
+const DeleteVariant = Schema.Struct({
+	action: Schema.Literal("delete"),
+	id: Schema.Number
+});
+const GetVariant = Schema.Struct({
+	action: Schema.Literal("get"),
+	id: Schema.Number
+});
+const ListByGoalVariant = Schema.Struct({
+	action: Schema.Literal("list_by_goal"),
+	goalId: Schema.Number
+});
+const ListByTddTaskVariant = Schema.Struct({
+	action: Schema.Literal("list_by_tdd_task"),
+	tddTaskId: Schema.Number
+});
+const TddBehaviorInput = Schema.Union(CreateVariant, UpdateVariant, DeleteVariant, GetVariant, ListByGoalVariant, ListByTddTaskVariant);
+const tddBehavior = idempotentProcedure.input(Schema.standardSchemaV1(TddBehaviorInput)).mutation(async ({ ctx, input }) => {
+	return ctx.runtime.runPromise(Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
+		create: (variant) => catchTddErrorsAsEnvelope(Effect.gen(function* () {
+			return {
+				ok: true,
+				action: "create",
+				behavior: yield* (yield* DataStore).createBehavior({
+					goalId: variant.goalId,
+					behavior: variant.behavior,
+					...variant.suggestedTestName !== void 0 && { suggestedTestName: variant.suggestedTestName },
+					...variant.dependsOnBehaviorIds !== void 0 && { dependsOnBehaviorIds: variant.dependsOnBehaviorIds }
+				})
+			};
+		})),
+		update: (variant) => catchTddErrorsAsEnvelope(Effect.gen(function* () {
+			return {
+				ok: true,
+				action: "update",
+				behavior: yield* (yield* DataStore).updateBehavior({
+					id: variant.id,
+					...variant.behavior !== void 0 && { behavior: variant.behavior },
+					...variant.suggestedTestName !== void 0 && { suggestedTestName: variant.suggestedTestName },
+					...variant.status !== void 0 && { status: variant.status },
+					...variant.dependsOnBehaviorIds !== void 0 && { dependsOnBehaviorIds: variant.dependsOnBehaviorIds }
+				})
+			};
+		})),
+		delete: (variant) => catchTddErrorsAsEnvelope(Effect.gen(function* () {
+			yield* (yield* DataStore).deleteBehavior(variant.id);
+			return {
+				ok: true,
+				action: "delete",
+				id: variant.id
+			};
+		})),
+		get: (variant) => Effect.gen(function* () {
+			const opt = yield* (yield* DataReader).getBehaviorById(variant.id);
+			return Option.isNone(opt) ? {
+				action: "get",
+				found: false,
+				id: variant.id
+			} : {
+				action: "get",
+				found: true,
+				behavior: opt.value
+			};
+		}),
+		list_by_goal: (variant) => catchTddErrorsAsEnvelope(Effect.gen(function* () {
+			const store = yield* DataStore;
+			const reader = yield* DataReader;
+			yield* store.listBehaviorsByGoal(variant.goalId);
+			const behaviors = yield* reader.getBehaviorsByGoal(variant.goalId);
+			return {
+				ok: true,
+				action: "list_by_goal",
+				goalId: variant.goalId,
+				behaviors
+			};
+		})),
+		list_by_tdd_task: (variant) => catchTddErrorsAsEnvelope(Effect.gen(function* () {
+			const store = yield* DataStore;
+			const reader = yield* DataReader;
+			yield* store.listBehaviorsByTddTask(variant.tddTaskId);
+			const behaviors = yield* reader.getBehaviorsByTddTask(variant.tddTaskId);
+			return {
+				ok: true,
+				action: "list_by_tdd_task",
+				tddTaskId: variant.tddTaskId,
+				behaviors
+			};
+		}))
+	})));
+});
+
+//#endregion
+export { TddBehaviorResult, tddBehavior };

package/tools/tdd-goal.js

@@ -0,0 +1,147 @@
+import { idempotentProcedure } from "../middleware/idempotency.js";
+import { catchTddErrorsAsEnvelope } from "./_tdd-error-envelope.js";
+import { DataReader, DataStore, GoalDetail, GoalRow } from "@vitest-agent/sdk";
+import { Effect, Match, Option, Schema } from "effect";
+
+//#region src/tools/tdd-goal.ts
+/**
+* Consolidated `tdd_goal` MCP tool.
+*
+* Replaces `tdd_goal_create`, `tdd_goal_update`, `tdd_goal_delete`,
+* `tdd_goal_get`, and `tdd_goal_list` with a single tool keyed on
+* `action`. All five tagged TDD errors are caught and surfaced as
+* `{ ok: false, error: { _tag, ..., remediation } }` envelopes via
+* the shared helper.
+*/
+const GoalStatus = Schema.Literal("pending", "in_progress", "done", "abandoned");
+const TddErrorEnvelope = Schema.Struct({
+	ok: Schema.Literal(false).annotations({ description: "Discriminant — `false` when a tagged TDD error was caught." }),
+	error: Schema.Struct({
+		_tag: Schema.String.annotations({ description: "Tagged error name (e.g. GoalNotFoundError, TddTaskNotFoundError)." }),
+		message: Schema.String,
+		remediation: Schema.optional(Schema.String).annotations({ description: "Suggested next action when known." })
+	}).pipe(Schema.extend(Schema.Record({
+		key: Schema.String,
+		value: Schema.Unknown
+	})))
+}).annotations({ identifier: "TddErrorEnvelope" });
+const TddGoalCreateOk = Schema.Struct({
+	ok: Schema.Literal(true),
+	action: Schema.Literal("create"),
+	goal: GoalRow.annotations({ description: "Newly inserted goal row." })
+}).annotations({ identifier: "TddGoalCreateOk" });
+const TddGoalUpdateOk = Schema.Struct({
+	ok: Schema.Literal(true),
+	action: Schema.Literal("update"),
+	goal: GoalRow.annotations({ description: "Updated goal row." })
+}).annotations({ identifier: "TddGoalUpdateOk" });
+const TddGoalDeleteOk = Schema.Struct({
+	ok: Schema.Literal(true),
+	action: Schema.Literal("delete"),
+	id: Schema.Number
+}).annotations({ identifier: "TddGoalDeleteOk" });
+const TddGoalGetFound = Schema.Struct({
+	action: Schema.Literal("get"),
+	found: Schema.Literal(true),
+	goal: GoalDetail.annotations({ description: "Goal with nested behaviors[]." })
+}).annotations({ identifier: "TddGoalGetFound" });
+const TddGoalGetMissing = Schema.Struct({
+	action: Schema.Literal("get"),
+	found: Schema.Literal(false),
+	id: Schema.Number
+}).annotations({ identifier: "TddGoalGetMissing" });
+const TddGoalListOk = Schema.Struct({
+	ok: Schema.Literal(true),
+	action: Schema.Literal("list"),
+	tddTaskId: Schema.Number,
+	goals: Schema.Array(GoalDetail).annotations({ description: "All goals for the TDD task, with their behaviors." })
+}).annotations({ identifier: "TddGoalListOk" });
+const TddGoalResult = Schema.Union(TddGoalCreateOk, TddGoalUpdateOk, TddGoalDeleteOk, TddGoalGetFound, TddGoalGetMissing, TddGoalListOk, TddErrorEnvelope).annotations({
+	identifier: "TddGoalResult",
+	title: "tdd_goal result",
+	description: "Discriminate first on `action` (or on `ok=false` for the tagged-error envelope). Get returns `found:true|false`; create/update/delete/list return `ok:true` on success."
+});
+const CreateVariant = Schema.Struct({
+	action: Schema.Literal("create"),
+	tddTaskId: Schema.Number,
+	goal: Schema.String
+});
+const UpdateVariant = Schema.Struct({
+	action: Schema.Literal("update"),
+	id: Schema.Number,
+	goal: Schema.optional(Schema.String),
+	status: Schema.optional(GoalStatus)
+});
+const DeleteVariant = Schema.Struct({
+	action: Schema.Literal("delete"),
+	id: Schema.Number
+});
+const GetVariant = Schema.Struct({
+	action: Schema.Literal("get"),
+	id: Schema.Number
+});
+const ListVariant = Schema.Struct({
+	action: Schema.Literal("list"),
+	tddTaskId: Schema.Number
+});
+const TddGoalInput = Schema.Union(CreateVariant, UpdateVariant, DeleteVariant, GetVariant, ListVariant);
+const tddGoal = idempotentProcedure.input(Schema.standardSchemaV1(TddGoalInput)).mutation(async ({ ctx, input }) => {
+	return ctx.runtime.runPromise(Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
+		create: (variant) => catchTddErrorsAsEnvelope(Effect.gen(function* () {
+			return {
+				ok: true,
+				action: "create",
+				goal: yield* (yield* DataStore).createGoal({
+					tddTaskId: variant.tddTaskId,
+					goal: variant.goal
+				})
+			};
+		})),
+		update: (variant) => catchTddErrorsAsEnvelope(Effect.gen(function* () {
+			return {
+				ok: true,
+				action: "update",
+				goal: yield* (yield* DataStore).updateGoal({
+					id: variant.id,
+					...variant.goal !== void 0 && { goal: variant.goal },
+					...variant.status !== void 0 && { status: variant.status }
+				})
+			};
+		})),
+		delete: (variant) => catchTddErrorsAsEnvelope(Effect.gen(function* () {
+			yield* (yield* DataStore).deleteGoal(variant.id);
+			return {
+				ok: true,
+				action: "delete",
+				id: variant.id
+			};
+		})),
+		get: (variant) => Effect.gen(function* () {
+			const opt = yield* (yield* DataReader).getGoalById(variant.id);
+			return Option.isNone(opt) ? {
+				action: "get",
+				found: false,
+				id: variant.id
+			} : {
+				action: "get",
+				found: true,
+				goal: opt.value
+			};
+		}),
+		list: (variant) => catchTddErrorsAsEnvelope(Effect.gen(function* () {
+			const store = yield* DataStore;
+			const reader = yield* DataReader;
+			yield* store.listGoalsByTddTask(variant.tddTaskId);
+			const goals = yield* reader.getGoalsByTddTask(variant.tddTaskId);
+			return {
+				ok: true,
+				action: "list",
+				tddTaskId: variant.tddTaskId,
+				goals
+			};
+		}))
+	})));
+});
+
+//#endregion
+export { TddGoalResult, tddGoal };

package/tools/tdd-phase-transition-request.js

@@ -0,0 +1,212 @@
+import { publicProcedure } from "../context.js";
+import { DataReader, DataStore, requiredArtifactForTransition, validatePhaseTransition } from "@vitest-agent/sdk";
+import { Effect, Option, Schema } from "effect";
+
+//#region src/tools/tdd-phase-transition-request.ts
+const phaseLiteral = Schema.Literal("spike", "red", "red.triangulate", "green", "green.fake-it", "refactor", "extended-red", "green-without-red");
+const artifactKindLiteral = Schema.Literal("test_written", "test_failed_run", "code_written", "test_passed_run", "refactor", "test_weakened");
+const denialReasonLiteral = Schema.Literal("missing_artifact_evidence", "wrong_artifact_kind", "wrong_source_phase", "unknown_tdd_task", "tdd_task_already_ended", "goal_not_started", "goal_not_found", "goal_not_in_progress", "goal_not_in_tdd_task", "behavior_not_found", "behavior_not_in_goal", "refactor_without_passing_run", "evidence_not_in_phase_window", "evidence_not_for_behavior", "evidence_test_was_already_failing");
+const RemediationSchema = Schema.Struct({
+	suggestedTool: Schema.String.annotations({ description: "Next tool the agent should call to make progress." }),
+	suggestedArgs: Schema.Record({
+		key: Schema.String,
+		value: Schema.Unknown
+	}).annotations({ description: "Concrete arguments for `suggestedTool` that fix the underlying issue." }),
+	humanHint: Schema.String.annotations({ description: "Plain-language explanation of what to do next." })
+}).annotations({ identifier: "PhaseTransitionRemediation" });
+const PhaseTransitionAccepted = Schema.Struct({
+	accepted: Schema.Literal(true).annotations({ description: "Discriminant — `true` when the transition was granted." }),
+	phase: phaseLiteral.annotations({ description: "Phase the session is now in (echo of `requestedPhase`)." }),
+	newPhaseId: Schema.Number.annotations({ description: "`tdd_phases.id` of the freshly opened row." }),
+	previousPhaseId: Schema.NullOr(Schema.Number).annotations({ description: "`tdd_phases.id` of the phase that was closed (`null` for the first transition)." }),
+	citedArtifactId: Schema.optional(Schema.Number).annotations({ description: "Resolved `tdd_artifacts.id` actually used. Absent only for transitions that need no artifact (e.g. spike→red)." }),
+	citedArtifactSource: Schema.optional(Schema.Literal("explicit-id", "explicit-kind", "transition-derived", "none")).annotations({ description: "Where `citedArtifactId` came from: `explicit-id` (caller passed it), `explicit-kind` (resolved from caller's `citedArtifactKind`), `transition-derived` (resolved from the transition's required-evidence rule), or `none` (no artifact needed)." })
+}).annotations({ identifier: "PhaseTransitionAccepted" });
+const PhaseTransitionDenied = Schema.Struct({
+	accepted: Schema.Literal(false).annotations({ description: "Discriminant — `false` when the transition was refused." }),
+	phase: phaseLiteral.annotations({ description: "Phase the session remains in (the current phase, unchanged)." }),
+	denialReason: denialReasonLiteral.annotations({ description: "Categorical refusal reason; see `remediation` for the suggested fix." }),
+	remediation: RemediationSchema
+}).annotations({ identifier: "PhaseTransitionDenied" });
+const PhaseTransitionResult = Schema.Union(PhaseTransitionAccepted, PhaseTransitionDenied).annotations({
+	identifier: "PhaseTransitionResult",
+	title: "tdd_phase_transition_request result",
+	description: "Discriminate on `accepted`. Acceptance carries the new phaseId; denial carries a typed reason and a remediation pointer."
+});
+const tddPhaseTransitionRequest = publicProcedure.input(Schema.standardSchemaV1(Schema.Struct({
+	tddTaskId: Schema.Number,
+	goalId: Schema.Number,
+	requestedPhase: phaseLiteral,
+	citedArtifactId: Schema.optional(Schema.Number),
+	citedArtifactKind: Schema.optional(artifactKindLiteral),
+	behaviorId: Schema.optional(Schema.Number),
+	reason: Schema.optional(Schema.String)
+}))).mutation(async ({ ctx, input }) => {
+	return ctx.runtime.runPromise(Effect.gen(function* () {
+		const reader = yield* DataReader;
+		const store = yield* DataStore;
+		const currentOpt = yield* reader.getCurrentTddPhase(input.tddTaskId);
+		const currentPhase = Option.isSome(currentOpt) ? currentOpt.value.phase : "spike";
+		const phaseStartedAt = Option.isSome(currentOpt) ? currentOpt.value.startedAt : (/* @__PURE__ */ new Date()).toISOString();
+		const goalOpt = yield* reader.getGoalById(input.goalId);
+		if (Option.isNone(goalOpt)) return {
+			accepted: false,
+			phase: currentPhase,
+			denialReason: "goal_not_found",
+			remediation: {
+				suggestedTool: "tdd_goal",
+				suggestedArgs: {
+					action: "list",
+					tddTaskId: input.tddTaskId
+				},
+				humanHint: `No tdd_session_goals row with id=${input.goalId}. Call tdd_goal({ action: "list" }) to find the correct goal id.`
+			}
+		};
+		if (goalOpt.value.sessionId !== input.tddTaskId) return {
+			accepted: false,
+			phase: currentPhase,
+			denialReason: "goal_not_in_tdd_task",
+			remediation: {
+				suggestedTool: "tdd_goal",
+				suggestedArgs: {
+					action: "list",
+					tddTaskId: input.tddTaskId
+				},
+				humanHint: `Goal id=${input.goalId} belongs to TDD task ${goalOpt.value.sessionId}, not the requested tddTaskId=${input.tddTaskId}. Pass the tddTaskId of the goal's parent task, or pick a goal that belongs to the active task.`
+			}
+		};
+		if (goalOpt.value.status !== "in_progress") return {
+			accepted: false,
+			phase: currentPhase,
+			denialReason: "goal_not_in_progress",
+			remediation: {
+				suggestedTool: "tdd_goal_update",
+				suggestedArgs: {
+					id: input.goalId,
+					status: "in_progress"
+				},
+				humanHint: `Goal id=${input.goalId} has status '${goalOpt.value.status}'. Phase transitions require the goal to be in_progress. Call tdd_goal_update({status:'in_progress'}) before requesting transitions.`
+			}
+		};
+		if (input.behaviorId !== void 0) {
+			const behaviorOpt = yield* reader.getBehaviorById(input.behaviorId);
+			if (Option.isNone(behaviorOpt)) return {
+				accepted: false,
+				phase: currentPhase,
+				denialReason: "behavior_not_found",
+				remediation: {
+					suggestedTool: "tdd_behavior_list",
+					suggestedArgs: {
+						scope: "goal",
+						goalId: input.goalId
+					},
+					humanHint: `No tdd_session_behaviors row with id=${input.behaviorId}. Call tdd_behavior_list to find the correct behavior id.`
+				}
+			};
+			if (behaviorOpt.value.goalId !== input.goalId) return {
+				accepted: false,
+				phase: currentPhase,
+				denialReason: "behavior_not_in_goal",
+				remediation: {
+					suggestedTool: "tdd_behavior_get",
+					suggestedArgs: { id: input.behaviorId },
+					humanHint: `Behavior id=${input.behaviorId} belongs to goal ${behaviorOpt.value.goalId}, not the requested goalId=${input.goalId}. Pass the goalId of the behavior's parent goal.`
+				}
+			};
+		}
+		const requiredKindForTransition = requiredArtifactForTransition(currentPhase, input.requestedPhase);
+		let resolvedArtifactId;
+		let resolvedKindSource = "none";
+		let kindToLookUp;
+		if (input.citedArtifactId !== void 0) {
+			resolvedArtifactId = input.citedArtifactId;
+			resolvedKindSource = "explicit-id";
+		} else if (input.citedArtifactKind !== void 0) {
+			kindToLookUp = input.citedArtifactKind;
+			resolvedKindSource = "explicit-kind";
+		} else if (requiredKindForTransition !== null) {
+			kindToLookUp = requiredKindForTransition.kind;
+			resolvedKindSource = "transition-derived";
+		}
+		if (resolvedArtifactId === void 0 && kindToLookUp !== void 0) {
+			const recent = yield* reader.listTddArtifactsForTask({
+				tddTaskId: input.tddTaskId,
+				artifactKind: kindToLookUp,
+				limit: 1
+			});
+			if (recent.length === 0) return {
+				accepted: false,
+				phase: currentPhase,
+				denialReason: "missing_artifact_evidence",
+				remediation: {
+					suggestedTool: "run_tests",
+					suggestedArgs: {},
+					humanHint: `No '${kindToLookUp}' artifact has been recorded for tdd_task ${input.tddTaskId}. Artifacts are recorded by hooks observing your tool calls (Decision D7) — run the test (e.g. via run_tests) or make the file edit first; the post-tool-use hook will write the matching tdd_artifacts row and the next call to this tool will pick it up automatically.`
+				}
+			};
+			resolvedArtifactId = recent[0].id;
+		}
+		let citedArtifact;
+		if (resolvedArtifactId !== void 0) {
+			const artifactOpt = yield* reader.getTddArtifactWithContext(resolvedArtifactId);
+			if (Option.isNone(artifactOpt)) return {
+				accepted: false,
+				phase: currentPhase,
+				denialReason: "missing_artifact_evidence",
+				remediation: {
+					suggestedTool: "run_tests",
+					suggestedArgs: {},
+					humanHint: `Cited artifact id ${resolvedArtifactId} does not exist. Artifacts are recorded by hooks observing your tool calls (Decision D7), so run the test (e.g. via the run_tests MCP tool) or make the file edit first; the post-tool-use hook will write the matching tdd_artifacts row and return its id, which can then be cited here.`
+				}
+			};
+			citedArtifact = artifactOpt.value;
+		} else citedArtifact = {
+			id: -1,
+			phase_id: -1,
+			artifact_kind: "test_written",
+			test_case_id: null,
+			test_case_created_turn_at: null,
+			test_case_authored_in_session: false,
+			test_run_id: null,
+			test_first_failure_run_id: null,
+			behavior_id: null
+		};
+		const result = validatePhaseTransition({
+			tdd_task_id: input.tddTaskId,
+			current_phase: currentPhase,
+			phase_started_at: phaseStartedAt,
+			now: (/* @__PURE__ */ new Date()).toISOString(),
+			requested_phase: input.requestedPhase,
+			cited_artifact: citedArtifact,
+			requested_behavior_id: input.behaviorId ?? null
+		});
+		if (!result.accepted) return result;
+		const out = yield* store.writeTddPhase({
+			tddTaskId: input.tddTaskId,
+			phase: result.phase,
+			startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			...input.behaviorId !== void 0 && { behaviorId: input.behaviorId },
+			...input.reason !== void 0 && { transitionReason: input.reason }
+		});
+		if (input.behaviorId !== void 0) yield* Effect.ignoreLogged(Effect.gen(function* () {
+			const behOpt = yield* reader.getBehaviorById(input.behaviorId);
+			if (Option.isSome(behOpt) && behOpt.value.status === "pending") yield* store.updateBehavior({
+				id: input.behaviorId,
+				status: "in_progress"
+			});
+		}));
+		return {
+			accepted: true,
+			phase: result.phase,
+			newPhaseId: out.id,
+			previousPhaseId: out.previousPhaseId,
+			...resolvedArtifactId !== void 0 && {
+				citedArtifactId: resolvedArtifactId,
+				citedArtifactSource: resolvedKindSource
+			}
+		};
+	}));
+});
+
+//#endregion
+export { PhaseTransitionResult, tddPhaseTransitionRequest };