@markjaquith/agency 2.60.0 → 2.61.1

package/src/services/TaskService.ts

@@ -1,15 +1,19 @@
 import { Schema, TreeFormatter } from "@effect/schema"
 import { Data, Effect, Either } from "effect"
+import { readdir } from "node:fs/promises"
 import { join } from "node:path"
 import { FileSystemService } from "./FileSystemService"
-import { WorkbaseService } from "./WorkbaseService"
+import { WorkbaseService, type ValidationReport } from "./WorkbaseService"
 import { VersionControlService } from "./VersionControlService"
 import { EpicService, type EpicRecord } from "./EpicService"
 import {
 	EntityId,
+	PhaseFrontmatter,
 	TaskFrontmatter,
 	type RepositoryReference,
 	type ReviewRecord,
+	type TaskHandoff,
+	type TaskPurpose,
 	type TaskFrontmatter as TaskData,
 	WorkStatus,
 } from "../workbase/schemas"
@@ -17,6 +21,7 @@ import {
 	formatMarkdownDocument,
 	formatWorkDocumentBody,
 	parseFrontmatter,
+	parseFrontmatterSync,
 } from "../workbase/frontmatter"
 import { canTransitionStatus } from "../readiness"
 import { documentRevision } from "../workbase/document-revision"
@@ -27,6 +32,7 @@ import {
 } from "../workbase/completion"
 import {
 	documentWriteStep,
+	pathMustNotExistStep,
 	runLifecycleTransaction,
 	type TransactionStep,
 } from "./LifecycleTransaction"
@@ -54,6 +60,27 @@ export interface CreateTaskInput {
 	readonly branch?: string
 	readonly base?: string
 	readonly review?: ReviewRecord
+	readonly purpose?: TaskPurpose
+	readonly handoff?: TaskHandoff
+	readonly preconditions?: readonly {
+		readonly path: string
+		readonly revision: string
+	}[]
+	readonly transactionSteps?: readonly TransactionStep[]
+	readonly postWriteSteps?: readonly TransactionStep[]
+}
+
+export interface HandoffTaskInput {
+	readonly sourceTaskId: string
+	readonly sourcePhaseId?: string
+	readonly id: string
+	readonly ticketUrl: string | null
+	readonly description?: string
+	readonly epic?: string
+	readonly repo: string
+	readonly repos?: readonly RepositoryReference[]
+	readonly branch: string
+	readonly base: string
 }
 
 const decodeTask = (input: unknown) => {
@@ -82,6 +109,72 @@ const decodeStatus = (status: string) => {
 		: Effect.succeed(result.right)
 }
 
+const decodePhase = (input: unknown) => {
+	const result = Schema.decodeUnknownEither(PhaseFrontmatter, {
+		errors: "all",
+		onExcessProperty: "error",
+	})(input)
+	return Either.isLeft(result)
+		? Effect.fail(
+				new TaskError({ message: TreeFormatter.formatErrorSync(result.left) }),
+			)
+		: Effect.succeed(result.right)
+}
+
+const branchAvailableStep = (
+	root: string,
+	repo: string,
+	branch: string,
+	destinationId: string,
+): TransactionStep => ({
+	label: `verify branch ${repo}:${branch} is available`,
+	preflight: async () => {
+		const taskEntries = await readdir(join(root, "tasks"), {
+			withFileTypes: true,
+		}).catch(() => [])
+		for (const taskEntry of taskEntries) {
+			if (!taskEntry.isDirectory() || taskEntry.name === destinationId) continue
+			const taskPath = join(root, "tasks", taskEntry.name, "TASK.md")
+			const taskContent = await Bun.file(taskPath).text()
+			const taskData = Schema.decodeUnknownSync(TaskFrontmatter, {
+				errors: "all",
+				onExcessProperty: "error",
+			})(parseFrontmatterSync(taskContent, taskPath).data)
+			if (
+				"repo" in taskData &&
+				taskData.repo === repo &&
+				taskData.branch === branch
+			) {
+				throw new Error(
+					`Writable branch '${branch}' for repository '${repo}' is already owned by task '${taskEntry.name}'`,
+				)
+			}
+			if (!("phases" in taskData)) continue
+			for (const phase of taskData.phases) {
+				const phasePath = join(
+					root,
+					"tasks",
+					taskEntry.name,
+					"phases",
+					phase.id,
+					"PHASE.md",
+				)
+				const phaseContent = await Bun.file(phasePath).text()
+				const phaseData = Schema.decodeUnknownSync(PhaseFrontmatter, {
+					errors: "all",
+					onExcessProperty: "error",
+				})(parseFrontmatterSync(phaseContent, phasePath).data)
+				if (phaseData.repo === repo && phaseData.branch === branch) {
+					throw new Error(
+						`Writable branch '${branch}' for repository '${repo}' is already owned by phase '${taskEntry.name}/${phase.id}'`,
+					)
+				}
+			}
+		}
+	},
+	apply: async () => {},
+})
+
 const reviewPinRef = (taskId: string) =>
 	`refs/agency/reviews/${Buffer.from(taskId).toString("hex")}`
 
@@ -151,7 +244,22 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 				}
 				if (yield* fs.exists(archivedTaskDirectory(root, id))) {
 					return yield* new TaskError({
-						message: `Task '${id}' is archived; restore it before reusing this ID`,
+						message: `Task '${id}' is archived; explicit creation requires a different ID`,
+					})
+				}
+				const taskMetadata = {
+					...(input.purpose ? { purpose: input.purpose } : {}),
+					...(input.handoff ? { handoff: input.handoff } : {}),
+				}
+				if (input.handoff && input.purpose !== "implementation") {
+					return yield* new TaskError({
+						message:
+							"Task handoff provenance requires purpose 'implementation'",
+					})
+				}
+				if (input.purpose === "implementation" && !input.handoff) {
+					return yield* new TaskError({
+						message: "Implementation-purpose tasks require handoff provenance",
 					})
 				}
 
@@ -175,6 +283,7 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 							? { description: input.description }
 							: {}),
 						...(input.epic ? { epic: input.epic } : {}),
+						...taskMetadata,
 						review: input.review,
 					})
 				} else if (input.multiPhase) {
@@ -184,6 +293,7 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 							? { description: input.description }
 							: {}),
 						...(input.epic ? { epic: input.epic } : {}),
+						...taskMetadata,
 						phases: [],
 					})
 				} else {
@@ -198,6 +308,7 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 							? { description: input.description }
 							: {}),
 						...(input.epic ? { epic: input.epic } : {}),
+						...taskMetadata,
 						repo: input.repo,
 						...(input.repos?.length ? { repos: input.repos } : {}),
 						branch: input.branch,
@@ -245,7 +356,7 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					.join(" ")
 				const content = formatMarkdownDocument(
 					data,
-					formatWorkDocumentBody(title, "task"),
+					formatWorkDocumentBody(title, "task", input.purpose),
 				)
 				const writes: {
 					path: string
@@ -273,14 +384,29 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 				}
 				yield* runLifecycleTransaction({
 					root,
-					preconditions: parentEpic
-						? [{ path: parentEpic.path, revision: parentEpic.revision }]
-						: [],
+					preconditions: [
+						...(input.preconditions ?? []),
+						...(parentEpic
+							? [{ path: parentEpic.path, revision: parentEpic.revision }]
+							: []),
+					],
 					steps: [
+						...(input.transactionSteps ?? []),
+						pathMustNotExistStep(
+							root,
+							directory,
+							`Task '${id}' already exists`,
+						),
+						pathMustNotExistStep(
+							root,
+							archivedTaskDirectory(root, id),
+							`Task '${id}' is archived; explicit creation requires a different ID`,
+						),
 						...(input.review
 							? [reviewPinStep(root, id, input.review, reviewEnvironment)]
 							: []),
 						documentWriteStep(root, writes),
+						...(input.postWriteSteps ?? []),
 					],
 				})
 
@@ -293,6 +419,139 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 				} satisfies TaskRecord
 			}),
 
+		handoff: (input: HandoffTaskInput, startPath: string = process.cwd()) =>
+			Effect.gen(function* () {
+				const fs = yield* FileSystemService
+				const workbase = yield* WorkbaseService
+				const service = yield* TaskService
+				const root = yield* workbase.discover(startPath)
+				const sourceTaskId = yield* decodeId(input.sourceTaskId)
+				const sourceTask = yield* service.show(sourceTaskId, root)
+				const validation = yield* workbase.validate(root)
+				if (!validation.valid) {
+					return yield* new TaskError({
+						message: "Cannot create a handoff in an invalid workbase",
+					})
+				}
+				if (sourceTask.data.purpose !== "investigation") {
+					return yield* new TaskError({
+						message: `Task '${sourceTaskId}' is not an investigation task`,
+					})
+				}
+
+				const preconditions = [
+					{ path: sourceTask.path, revision: sourceTask.revision },
+				]
+				let source: TaskHandoff["source"]
+				let committedValidation: ValidationReport | undefined
+				let sourcePath = sourceTask.path
+				let sourceRevision = sourceTask.revision
+				if (input.sourcePhaseId) {
+					const phaseId = yield* decodeId(input.sourcePhaseId)
+					if (
+						!("phases" in sourceTask.data) ||
+						!sourceTask.data.phases.some((phase) => phase.id === phaseId)
+					) {
+						return yield* new TaskError({
+							message: `Phase '${sourceTaskId}/${phaseId}' does not exist`,
+						})
+					}
+					sourcePath = join(
+						root,
+						"tasks",
+						sourceTaskId,
+						"phases",
+						phaseId,
+						"PHASE.md",
+					)
+					const sourceContent = yield* fs.readFile(sourcePath)
+					const parsed = yield* parseFrontmatter(sourceContent, sourcePath)
+					yield* decodePhase(parsed.data)
+					sourceRevision = documentRevision(sourceContent)
+					preconditions.push({ path: sourcePath, revision: sourceRevision })
+					source = { kind: "phase", taskId: sourceTaskId, phaseId }
+				} else {
+					source = { kind: "task", taskId: sourceTaskId }
+				}
+
+				const record = yield* service.create(
+					{
+						id: input.id,
+						ticketUrl: input.ticketUrl,
+						description: input.description,
+						epic: input.epic,
+						repo: input.repo,
+						repos: input.repos,
+						branch: input.branch,
+						base: input.base,
+						purpose: "implementation",
+						handoff: { source, sourceRevision },
+						preconditions,
+						transactionSteps: [
+							branchAvailableStep(root, input.repo, input.branch, input.id),
+						],
+						postWriteSteps: [
+							{
+								label: "validate resulting workbase",
+								apply: async () => {
+									const report = await Effect.runPromise(
+										workbase
+											.validate(root)
+											.pipe(
+												Effect.provideService(FileSystemService, fs),
+												Effect.provideService(WorkbaseService, workbase),
+											),
+									)
+									if (!report.valid) {
+										throw new Error(
+											`Handoff would create an invalid workbase: ${report.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`,
+										)
+									}
+									committedValidation = report
+								},
+							},
+						],
+					},
+					root,
+				)
+				if (!("repo" in record.data)) {
+					return yield* new TaskError({
+						message: `Task '${record.id}' is not an implementation execution unit`,
+					})
+				}
+				if (!committedValidation) {
+					return yield* new TaskError({
+						message: "Handoff validation did not produce a result",
+					})
+				}
+				const taskDirectory = join(root, "tasks", record.id)
+				const sourceSelector =
+					source.kind === "phase"
+						? `phase/${source.taskId}/${source.phaseId}`
+						: `task/${source.taskId}`
+				return {
+					task: {
+						id: record.id,
+						selector: `task/${record.id}`,
+						directory: taskDirectory,
+						documentPath: record.path,
+						revision: record.revision,
+						branch: record.data.branch,
+						base: record.data.base,
+					},
+					source: {
+						selector: sourceSelector,
+						documentPath: sourcePath,
+						revision: sourceRevision,
+					},
+					validation: committedValidation,
+					worktreePrepare: {
+						target: `task/${record.id}`,
+						command: ["agency", "worktree", "prepare", record.id],
+					},
+				}
+			}),
+
 		list: (startPath: string = process.cwd()) =>
 			Effect.gen(function* () {
 				const fs = yield* FileSystemService

package/src/services/WorkbaseService.ts

@@ -818,6 +818,36 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 						validateRepositories(task)
 						validateBranchOwnership(task)
 						validateCompletion(task)
+						if (task.data.handoff && task.data.purpose !== "implementation") {
+							issue(
+								task.path,
+								"Task handoff provenance requires purpose 'implementation'",
+							)
+						}
+						if (task.data.purpose === "implementation" && !task.data.handoff) {
+							issue(
+								task.path,
+								"Implementation-purpose tasks require handoff provenance",
+							)
+						}
+						if (
+							task.data.handoff?.source.kind === "task" &&
+							task.data.handoff.source.taskId === task.id
+						) {
+							issue(
+								task.path,
+								"Task handoff provenance cannot reference itself",
+							)
+						}
+						if (
+							task.data.handoff?.source.kind === "phase" &&
+							task.data.handoff.source.taskId === task.id
+						) {
+							issue(
+								task.path,
+								"Task handoff provenance cannot reference one of its own phases",
+							)
+						}
 						if (task.data.epic) {
 							const parent = epics.get(task.data.epic)
 							if (!parent) {

package/src/workbase/AGENTS.md

@@ -62,6 +62,31 @@ agent from an active agent session; creating a pull request; archiving, restorin
 dropping, reopening, or completing work without a pull request; or using `--force`
 to override readiness.
 
+## Investigation Handoffs
+
+An explicit request for a new, separate, or follow-up item overrides reuse of
+every active or archived item, even when the subject or suggested ID matches.
+Existing work may be inspected for duplicate scope, but do not mutate or select
+it as the destination unless the user explicitly asks to reuse it.
+
+Use this ordered flow for investigation-to-implementation work:
+
+1. Create investigation-only work with `agency task create <id> --purpose
+investigation ...`.
+2. Record its boundary, evidence, findings, recommendation, and any no-change
+   outcome in the generated task sections.
+3. Create a distinct implementation task with `agency task handoff
+<investigation-task> <new-task> ...`; add `--source-phase <phase>` when the
+   evidence belongs to one phase.
+4. Verify the returned new selector, source selector and revision, validation
+   result, and then confirm authority with `agency context <new-task> --json`.
+5. Prepare, open, or launch the new item only when separately requested.
+
+Creation and handoff do not imply worktree preparation, status changes, agent
+launch, or UI actions. Handoff provenance is one-way historical evidence, not a
+dependency: source rename or content changes can make its selector unresolved or
+revision stale, and Agency must not silently rewrite that evidence.
+
 ## Safety
 
 - Stop on validation errors, dependency blockers, an unexpected writable

package/src/workbase/delivery-command.test.ts

@@ -104,8 +104,24 @@ describe("delivery commands", () => {
 			isDraft: false,
 		}
 		expect(
-			recordFromGitHubJson({ ...base, state: "OPEN", mergeable: "MERGEABLE" }),
-		).toMatchObject({ state: "open", merged: false, mergeable: true })
+			recordFromGitHubJson({
+				...base,
+				state: "OPEN",
+				headRefName: "feat/example",
+				baseRefName: "main",
+				headRepository: { nameWithOwner: "fork/agency" },
+				baseRepository: { nameWithOwner: "example/agency" },
+				mergeable: "MERGEABLE",
+			}),
+		).toMatchObject({
+			state: "open",
+			merged: false,
+			headRepository: "fork/agency",
+			headBranch: "feat/example",
+			baseRepository: "example/agency",
+			baseBranch: "main",
+			mergeable: true,
+		})
 		expect(
 			recordFromGitHubJson({
 				...base,

package/src/workbase/delivery-command.ts

@@ -156,11 +156,24 @@ export const recordFromGitHubUrl = (url: string): PullRequestRecord => {
 export const recordFromGitHubJson = (value: Record<string, unknown>) => {
 	const url = typeof value.url === "string" ? value.url : ""
 	const record = recordFromGitHubUrl(url)
+	const repositoryName = (repository: unknown) => {
+		if (!repository || typeof repository !== "object") return undefined
+		const nameWithOwner = (repository as Record<string, unknown>).nameWithOwner
+		return typeof nameWithOwner === "string" && nameWithOwner
+			? nameWithOwner
+			: undefined
+	}
 	const githubState = String(value.state ?? "OPEN").toLowerCase()
 	const merged = githubState === "merged" || value.mergedAt != null
 	const mergeable = String(value.mergeable ?? "UNKNOWN").toLowerCase()
 	return {
 		...record,
+		headRepository: repositoryName(value.headRepository),
+		headBranch:
+			typeof value.headRefName === "string" ? value.headRefName : undefined,
+		baseRepository: repositoryName(value.baseRepository) ?? record.repository,
+		baseBranch:
+			typeof value.baseRefName === "string" ? value.baseRefName : undefined,
 		state: merged ? "merged" : githubState === "closed" ? "closed" : "open",
 		draft: value.isDraft === true,
 		merged,

package/src/workbase/frontmatter.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test"
 import { Effect } from "effect"
-import { parseFrontmatter } from "./frontmatter"
+import { formatWorkDocumentBody, parseFrontmatter } from "./frontmatter"
 
 describe("parseFrontmatter", () => {
 	test("parses YAML 1.2 frontmatter and body", async () => {
@@ -48,3 +48,20 @@ describe("parseFrontmatter", () => {
 		).rejects.toThrow("must begin with YAML frontmatter")
 	})
 })
+
+describe("formatWorkDocumentBody", () => {
+	test("generates explicit investigation sections", () => {
+		const body = formatWorkDocumentBody(
+			"Investigate Checkout",
+			"task",
+			"investigation",
+		)
+
+		expect(body).toContain("## Investigation Boundary")
+		expect(body).toContain("## Evidence")
+		expect(body).toContain("## Findings")
+		expect(body).toContain("## Recommendation")
+		expect(body).toContain("## Implementation Handoff")
+		expect(body).not.toContain("Describe the task outcome")
+	})
+})

package/src/workbase/frontmatter.ts

@@ -85,7 +85,35 @@ export const formatMarkdownDocument = (data: object, body: string) =>
 export const formatWorkDocumentBody = (
 	title: string,
 	kind: "epic" | "task" | "phase",
-) => `# ${title}
+	purpose?: "investigation" | "implementation",
+) =>
+	purpose === "investigation"
+		? `# ${title}
+
+## Investigation Boundary
+
+State the question, scope, and implementation excluded from this investigation.
+
+## Evidence
+
+Record inspected sources, commands, observations, and supporting links.
+
+## Findings
+
+Record findings, confidence, uncertainty, and relevant constraints.
+
+## Recommendation
+
+Recommend implementation, no change, or further investigation.
+
+## Implementation Handoff
+
+Record any distinct implementation task created from this investigation.
+
+## Important Decisions
+
+Record consequential decisions and their rationale.`
+		: `# ${title}
 
 ## Outcome
 

package/src/workbase/opencode-file.ts

@@ -10,7 +10,7 @@ const agencyPlanPrompt = `You are in Agency Plan mode. Think, read, search, and
 
 Start with \`agency context . --json\`. Use its document paths and revisions, then inspect the graph, related epics, tasks, phases, linked tickets, and repository declarations needed to understand the work. Use machine-readable Agency output when available instead of inferring structure from directory names.
 
-When planning an epic, decompose it into independently deliverable tasks with explicit dependencies. Add phases only when one task genuinely requires multiple ordered delivery units. Reuse or update existing work instead of creating duplicate tasks or phases.
+When planning an epic, decompose it into independently deliverable tasks with explicit dependencies. Add phases only when one task genuinely requires multiple ordered delivery units. Reuse or update existing work instead of creating duplicate tasks or phases, except when the user explicitly requests a new, separate, or follow-up item. Explicit-new intent overrides reuse of active and archived work even when the subject or suggested ID matches.
 
 Use the Agency CLI for full workbase orchestration when the plan requires it, including creating or updating related epics, tasks, and phases; moving tasks; maintaining dependencies; and changing lifecycle state. Use \`--if-revision\` with the revision returned by context for mutations that support it, and run \`agency validate\` after changing workbase structure. Use available ticket tools to inspect or update a linked external ticket when the plan requires it.
 

package/src/workbase/schemas.test.ts

@@ -64,6 +64,42 @@ describe("portable repository declarations", () => {
 })
 
 describe("body-of-work descriptions", () => {
+	test("decodes strict task purpose and handoff provenance", () => {
+		const handoff = {
+			source: { kind: "phase", taskId: "investigate", phaseId: "evidence" },
+			sourceRevision: "a".repeat(64),
+		}
+		const task = Schema.decodeUnknownSync(TaskFrontmatter, {
+			onExcessProperty: "error",
+		})({
+			ticketUrl: null,
+			purpose: "implementation",
+			handoff,
+			repo: "agency",
+			branch: "task/implement",
+			base: "main",
+			pr: null,
+		})
+		expect(task).toMatchObject({ purpose: "implementation", handoff })
+
+		for (const invalid of [
+			{ ...handoff, sourceRevision: "short" },
+			{ ...handoff, source: { kind: "phase", taskId: "investigate" } },
+			{ ...handoff, source: { kind: "task", taskId: "../unsafe" } },
+		]) {
+			expect(() =>
+				Schema.decodeUnknownSync(TaskFrontmatter, {
+					onExcessProperty: "error",
+				})({
+					ticketUrl: null,
+					purpose: "implementation",
+					handoff: invalid,
+					phases: [],
+				}),
+			).toThrow()
+		}
+	})
+
 	test("decodes review tasks strictly and rejects writable execution fields", () => {
 		const review = {
 			ticketUrl: null,

package/src/workbase/schemas.ts

@@ -46,7 +46,9 @@ const IsoTimestamp = NonEmptyString.pipe(
 
 const GitCommit = Schema.String.pipe(Schema.pattern(/^[a-f0-9]{40}$/))
 
-const DocumentRevision = Schema.String.pipe(Schema.pattern(/^[a-f0-9]{64}$/))
+export const DocumentRevision = Schema.String.pipe(
+	Schema.pattern(/^[a-f0-9]{64}$/),
+)
 
 export const ClaimRecord = Schema.Struct({
 	claimant: NonEmptyString,
@@ -70,6 +72,10 @@ const GitHubPullRequestUrl = NonEmptyString.pipe(
 export const PullRequestRecord = Schema.Struct({
 	provider: EntityId,
 	repository: NonEmptyString,
+	headRepository: Schema.optional(NonEmptyString),
+	headBranch: Schema.optional(NonEmptyString),
+	baseRepository: Schema.optional(NonEmptyString),
+	baseBranch: Schema.optional(NonEmptyString),
 	identifier: NonEmptyString,
 	url: Url,
 	state: Schema.Literal("open", "closed", "merged"),
@@ -155,6 +161,30 @@ const ExecutionUnit = {
 	completion: Schema.optional(CompletionRecord),
 }
 
+export const TaskPurpose = Schema.Literal("investigation", "implementation")
+
+export const TaskHandoffSource = Schema.Union(
+	Schema.Struct({
+		kind: Schema.Literal("task"),
+		taskId: EntityId,
+	}),
+	Schema.Struct({
+		kind: Schema.Literal("phase"),
+		taskId: EntityId,
+		phaseId: EntityId,
+	}),
+)
+
+export const TaskHandoff = Schema.Struct({
+	source: TaskHandoffSource,
+	sourceRevision: DocumentRevision,
+})
+
+const TaskMetadata = {
+	purpose: Schema.optional(TaskPurpose),
+	handoff: Schema.optional(TaskHandoff),
+}
+
 export const EpicFrontmatter = Schema.Struct({
 	ticketUrl: Url,
 	description: Description,
@@ -166,6 +196,7 @@ const SinglePhaseTaskFrontmatter = Schema.Struct({
 	ticketUrl: Schema.NullOr(Url),
 	description: Description,
 	epic: Schema.optional(EntityId),
+	...TaskMetadata,
 	...ExecutionUnit,
 })
 
@@ -173,6 +204,7 @@ const MultiPhaseTaskFrontmatter = Schema.Struct({
 	ticketUrl: Schema.NullOr(Url),
 	description: Description,
 	epic: Schema.optional(EntityId),
+	...TaskMetadata,
 	phases: Schema.Array(Dependency),
 })
 
@@ -221,6 +253,7 @@ const ReviewTaskFrontmatter = Schema.Struct({
 	ticketUrl: Schema.NullOr(Url),
 	description: Description,
 	epic: Schema.optional(EntityId),
+	...TaskMetadata,
 	review: ReviewRecord,
 	status: Schema.optionalWith(WorkStatus, { default: () => "open" as const }),
 	claim: Schema.optional(ClaimRecord),
@@ -254,6 +287,9 @@ export type PullRequestRecord = Schema.Schema.Type<typeof PullRequestRecord>
 export type ReviewSource = Schema.Schema.Type<typeof ReviewSource>
 export type ReviewRecord = Schema.Schema.Type<typeof ReviewRecord>
 export type CompletionRecord = Schema.Schema.Type<typeof CompletionRecord>
+export type TaskPurpose = Schema.Schema.Type<typeof TaskPurpose>
+export type TaskHandoffSource = Schema.Schema.Type<typeof TaskHandoffSource>
+export type TaskHandoff = Schema.Schema.Type<typeof TaskHandoff>
 export type EpicFrontmatter = Schema.Schema.Type<typeof EpicFrontmatter>
 export type TaskFrontmatter = Schema.Schema.Type<typeof TaskFrontmatter>
 export type PhaseFrontmatter = Schema.Schema.Type<typeof PhaseFrontmatter>