@markjaquith/agency 2.60.0 → 2.61.0

package/src/services/TaskPhaseService.test.ts

@@ -116,6 +116,234 @@ describe("task and phase services", () => {
 		expect(epic.data.tasks).toEqual([])
 	})
 
+	test("creates revision-bound task and phase investigation handoffs", async () => {
+		const source = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "investigate",
+							ticketUrl: null,
+							multiPhase: true,
+							purpose: "investigation",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const phase = await runTestEffect(
+			PhaseService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							taskId: "investigate",
+							id: "evidence",
+							repo: "agency",
+							branch: "task/investigate-evidence",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const currentSource = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("investigate", root)),
+			),
+		)
+		const sourceContent = await Bun.file(source.path).text()
+		const phaseContent = await Bun.file(phase.path).text()
+
+		const fromTask = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.handoff(
+						{
+							sourceTaskId: "investigate",
+							id: "implement-task",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/implement-task",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const fromPhase = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.handoff(
+						{
+							sourceTaskId: "investigate",
+							sourcePhaseId: "evidence",
+							id: "implement-phase",
+							ticketUrl: null,
+							repo: "effect",
+							branch: "task/implement-phase",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+
+		expect(fromTask.source).toEqual({
+			selector: "task/investigate",
+			documentPath: source.path,
+			revision: currentSource.revision,
+		})
+		expect(fromPhase.source).toEqual({
+			selector: "phase/investigate/evidence",
+			documentPath: phase.path,
+			revision: phase.revision,
+		})
+		expect(fromPhase.validation.valid).toBe(true)
+		expect(fromPhase.worktreePrepare.command).toEqual([
+			"agency",
+			"worktree",
+			"prepare",
+			"implement-phase",
+		])
+		expect(await Bun.file(source.path).text()).toBe(sourceContent)
+		expect(await Bun.file(phase.path).text()).toBe(phaseContent)
+		expect(
+			await Bun.file(join(root, "tasks/implement-phase/code")).exists(),
+		).toBe(false)
+
+		const created = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("implement-phase", root)),
+			),
+		)
+		expect(created.data).toMatchObject({
+			purpose: "implementation",
+			handoff: {
+				source: {
+					kind: "phase",
+					taskId: "investigate",
+					phaseId: "evidence",
+				},
+				sourceRevision: phase.revision,
+			},
+			status: "open",
+		})
+		await Bun.write(
+			phase.path,
+			phaseContent.replace(
+				"Describe the phase outcome.",
+				"Recorded evidence remains stale-safe.",
+			),
+		)
+		const staleSource = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("implement-phase", root)),
+			),
+		)
+		expect(staleSource.data.handoff?.sourceRevision).toBe(phase.revision)
+
+		await expect(
+			runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.handoff(
+							{
+								sourceTaskId: "investigate",
+								id: "implement-task",
+								ticketUrl: null,
+								repo: "agency",
+								branch: "task/duplicate",
+								base: "main",
+							},
+							root,
+						),
+					),
+				),
+			),
+		).rejects.toThrow("already exists")
+
+		await mkdir(join(root, "archive/tasks/reserved"), { recursive: true })
+		await expect(
+			runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.handoff(
+							{
+								sourceTaskId: "investigate",
+								id: "reserved",
+								ticketUrl: null,
+								repo: "agency",
+								branch: "task/reserved",
+								base: "main",
+							},
+							root,
+						),
+					),
+				),
+			),
+		).rejects.toThrow("explicit creation requires a different ID")
+	})
+
+	test("rolls back handoff creation when a source revision is stale", async () => {
+		const source = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "stale-investigation",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/stale-investigation",
+							base: "main",
+							purpose: "investigation",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const staleRevision = source.revision
+		await Bun.write(
+			source.path,
+			`${source.content}\nChanged after inspection.\n`,
+		)
+
+		await expect(
+			runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.create(
+							{
+								id: "stale-implementation",
+								ticketUrl: null,
+								repo: "effect",
+								branch: "task/stale-implementation",
+								base: "main",
+								purpose: "implementation",
+								handoff: {
+									source: {
+										kind: "task",
+										taskId: "stale-investigation",
+									},
+									sourceRevision: staleRevision,
+								},
+								preconditions: [{ path: source.path, revision: staleRevision }],
+							},
+							root,
+						),
+					),
+				),
+			),
+		).rejects.toThrow("Revision conflict")
+		expect(
+			await Bun.file(join(root, "tasks/stale-implementation/TASK.md")).exists(),
+		).toBe(false)
+	})
+
 	test("creates and sequences phases on a multi-phase task", async () => {
 		await runTestEffect(
 			TaskService.pipe(
@@ -192,6 +420,11 @@ describe("task and phase services", () => {
 							repos: [{ repo: "effect", ref: "main" }],
 							branch: "task/single",
 							base: "main",
+							purpose: "implementation",
+							handoff: {
+								source: { kind: "task", taskId: "investigation" },
+								sourceRevision: "a".repeat(64),
+							},
 						},
 						root,
 					),
@@ -256,6 +489,11 @@ describe("task and phase services", () => {
 		expect(task.data).toEqual({
 			ticketUrl: "https://example.com/task",
 			description: "Deliver the complete task.",
+			purpose: "implementation",
+			handoff: {
+				source: { kind: "task", taskId: "investigation" },
+				sourceRevision: "a".repeat(64),
+			},
 			phases: [
 				{ id: "implementation" },
 				{ id: "extra", dependsOn: ["implementation"] },

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