@markjaquith/agency 2.59.0 → 2.61.0

package/src/commands/task.test.ts

@@ -2,7 +2,12 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
 import { mkdir } from "node:fs/promises"
 import { join } from "node:path"
-import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
 import { task, type TaskInteraction } from "./task"
 
 describe("task creation input", () => {
@@ -125,6 +130,77 @@ describe("task creation input", () => {
 		expect(content).toContain("base: main")
 	})
 
+	test("returns revision-bound validation evidence and normalized recalled context", async () => {
+		const [output] = await captureLogs(() =>
+			runTestEffect(
+				task({
+					subcommand: "create",
+					args: ["scripted-context"],
+					contextRepo: "agency",
+					contextBase: "main",
+					contextSlug: "scripted-context",
+					authoritativeSources: [
+						"https://example.com/spec",
+						join(root, "SOURCE.md"),
+					],
+					cwd: root,
+					json: true,
+				}),
+			),
+		)
+		const result = JSON.parse(output!)
+		expect(result.selector).toBe("execution-unit:task/scripted-context")
+		expect(result.documentPath).toBe(
+			join(root, "tasks/scripted-context/TASK.md"),
+		)
+		expect(result.validation.valid).toBe(true)
+		expect(result.evidence).toEqual(
+			expect.objectContaining({
+				version: 1,
+				target: "execution-unit:task/scripted-context",
+				documentRevision: result.revision,
+				valid: true,
+				digest: expect.any(String),
+			}),
+		)
+		expect(result.recalledContext).toEqual({
+			repo: "agency",
+			base: "main",
+			preferredSlug: "scripted-context",
+			authoritativeSources: [
+				join(root, "SOURCE.md"),
+				"https://example.com/spec",
+			],
+		})
+	})
+
+	test("rejects stale or conflicting recalled context", async () => {
+		await expect(
+			runTestEffect(
+				task({
+					subcommand: "create",
+					args: ["conflict"],
+					repo: "agency",
+					contextRepo: "other",
+					cwd: root,
+					silent: true,
+				}),
+			),
+		).rejects.toThrow("conflicts with --repo")
+		await expect(
+			runTestEffect(
+				task({
+					subcommand: "create",
+					args: ["conflict"],
+					contextRepo: "agency",
+					contextSlug: "stale-slug",
+					cwd: root,
+					silent: true,
+				}),
+			),
+		).rejects.toThrow("conflicts with task ID")
+	})
+
 	test("never prompts when scripted creation is incomplete", async () => {
 		const interaction: TaskInteraction = {
 			text: () => Effect.fail(new Error("unexpected text prompt")),

package/src/commands/task.ts

@@ -12,6 +12,10 @@ import { getWorkViews } from "../work-view"
 import { GraphMutationService } from "../services/GraphMutationService"
 import { work as startWork, type StartWork } from "./work"
 import { ReviewService } from "../services/ReviewService"
+import {
+	buildValidationEvidence,
+	normalizeRecalledContext,
+} from "../workbase/kickoff-contract"
 
 interface TaskOptions extends BaseCommandOptions {
 	readonly subcommand?: string
@@ -45,6 +49,12 @@ interface TaskOptions extends BaseCommandOptions {
 	readonly noPullRequest?: boolean
 	readonly summary?: string
 	readonly evidenceUrl?: string
+	readonly contextRepo?: string
+	readonly contextBase?: string
+	readonly contextSlug?: string
+	readonly authoritativeSources?: readonly string[]
+	readonly purpose?: string
+	readonly sourcePhase?: string
 }
 
 export interface TaskInteraction {
@@ -189,6 +199,7 @@ export const task = (
 						repos: parseRepositoryReferences(options.references),
 						branch: multiPhase ? undefined : (options.branch ?? `task/${id}`),
 						base: multiPhase ? undefined : (options.base ?? "main"),
+						purpose: options.purpose as "investigation" | undefined,
 					},
 					cwd,
 				)
@@ -216,7 +227,43 @@ export const task = (
 					return yield* Effect.fail(new Error("Task ID is required"))
 				}
 				const multiPhase = options.multiPhase ?? false
-				if (!multiPhase && !options.repo && !options.review) {
+				if (
+					options.repo &&
+					options.contextRepo &&
+					options.repo !== options.contextRepo
+				) {
+					return yield* Effect.fail(
+						new Error(
+							`Recalled repository '${options.contextRepo}' conflicts with --repo '${options.repo}'`,
+						),
+					)
+				}
+				if (
+					options.base &&
+					options.contextBase &&
+					options.base !== options.contextBase
+				) {
+					return yield* Effect.fail(
+						new Error(
+							`Recalled base '${options.contextBase}' conflicts with --base '${options.base}'`,
+						),
+					)
+				}
+				const repo = options.repo ?? options.contextRepo
+				const base = options.base ?? options.contextBase ?? "main"
+				const recalledContext = yield* Effect.try({
+					try: () =>
+						normalizeRecalledContext({
+							id,
+							repo,
+							base: multiPhase || options.review ? undefined : base,
+							preferredSlug: options.contextSlug,
+							authoritativeSources: options.authoritativeSources,
+						}),
+					catch: (cause) =>
+						cause instanceof Error ? cause : new Error(String(cause)),
+				})
+				if (!multiPhase && !repo && !options.review) {
 					return yield* Effect.fail(
 						new Error("Writable repository is required for task create"),
 					)
@@ -236,7 +283,7 @@ export const task = (
 						epic: options.epic,
 						multiPhase,
 						review,
-						repo: options.repo,
+						repo: review ? undefined : repo,
 						repos: review
 							? undefined
 							: parseRepositoryReferences(options.references),
@@ -244,11 +291,33 @@ export const task = (
 							multiPhase || review
 								? undefined
 								: (options.branch ?? `task/${id}`),
-						base: multiPhase || review ? undefined : (options.base ?? "main"),
+						base: multiPhase || review ? undefined : base,
+						purpose: options.purpose as "investigation" | undefined,
 					},
 					cwd,
 				)
-				const { content: _, ...output } = record
+				const validation = yield* workbase.validate(cwd)
+				const selector = multiPhase
+					? `task:${record.id}`
+					: `execution-unit:task/${record.id}`
+				const evidence = validation.valid
+					? yield* buildValidationEvidence({
+							startPath: cwd,
+							target: selector,
+							documentPath: record.path,
+							documentRevision: record.revision,
+							recalledContext,
+						})
+					: null
+				const { content: _, ...created } = record
+				const output = {
+					...created,
+					selector,
+					documentPath: record.path,
+					validation,
+					evidence,
+					recalledContext,
+				}
 				log(
 					options.json
 						? JSON.stringify(output, null, 2)
@@ -256,6 +325,40 @@ export const task = (
 				)
 				return
 			}
+			case "handoff": {
+				const [sourceTaskId, id] = options.args
+				if (!sourceTaskId || !id) {
+					return yield* Effect.fail(
+						new Error("Source task ID and new task ID are required"),
+					)
+				}
+				if (!options.repo) {
+					return yield* Effect.fail(
+						new Error("Writable repository is required for task handoff"),
+					)
+				}
+				const output = yield* tasks.handoff(
+					{
+						sourceTaskId,
+						sourcePhaseId: options.sourcePhase,
+						id,
+						ticketUrl: options.ticketUrl?.trim() || null,
+						description: options.description?.trim() || undefined,
+						epic: options.epic,
+						repo: options.repo,
+						repos: parseRepositoryReferences(options.references),
+						branch: options.branch ?? `task/${id}`,
+						base: options.base ?? "main",
+					},
+					cwd,
+				)
+				log(
+					options.json
+						? JSON.stringify(output, null, 2)
+						: `Created implementation task '${id}' from '${output.source.selector}'`,
+				)
+				return
+			}
 			case "list": {
 				const records = yield* tasks.list(cwd)
 				const { taskRows } = yield* getWorkViews({
@@ -442,7 +545,7 @@ export const task = (
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Subcommand is required. Available: new, create, list, show, status, update, rename, move, dependency",
+						"Subcommand is required. Available: new, create, handoff, list, show, status, update, rename, move, dependency",
 					),
 				)
 		}
@@ -454,6 +557,7 @@ Usage: agency task <subcommand>
 Subcommands:
   new [id]              Create a task with guided input
   create <id>           Create a task without prompting
+  handoff <source> <id> Create implementation work from an investigation
   list                  List tasks
   show <id>             Show a task
   status <id> <status>  Set open, working, dropped, or explicit non-PR done
@@ -474,12 +578,19 @@ Non-PR completion options (status done only):
 Create options:
   --ticket-url <url>    External ticket URL (optional)
   --description <text>  Short description of the task
+	--purpose investigation
+	                       Generate an investigation-only task
   --epic <id>           Parent epic
   --repo <alias>        Writable repository
   --reference <alias>:<ref>
                         Read-only repository reference; repeatable
   --branch <name>       Working branch (default: task/<id>)
   --base <name>         Base branch (default: main)
+	--context-repo <alias> Recalled repository; must agree with --repo
+	--context-base <name>  Recalled base; must agree with --base
+	--context-slug <id>    Recalled preferred slug; must equal the task ID
+	--authoritative-source <path-or-url>
+	                       Authoritative input location; repeatable
 	--multi-phase         Create a task container for phases
 	--review <alias>      Create a pinned read-only review task
 	--pull-request <url-or-number>
@@ -488,6 +599,11 @@ Create options:
   --work                Start work on the new task after creating it
   --auto                Pass --auto to work; requires --work
 
+Handoff options:
+  --source-phase <id>   Use a phase document as the source evidence
+  --repo <alias>        Writable implementation repository
+  --reference, --branch, --base, --ticket-url, --description, --epic
+
 Update options:
   --ticket-url <url> / --clear-ticket
   --description <text> / --clear-description
@@ -497,8 +613,8 @@ Update options:
   --base <name>         Replace the base branch
   --pr-url <url> / --clear-pr
 
-Task creation is noninteractive. Single-phase tasks require --repo; use
---multi-phase instead for a task container. Guided input is available only
+Task creation is noninteractive. Single-phase tasks require --repo or
+--context-repo; use --multi-phase instead for a task container. Guided input is available only
 through task new, which fails when --no-input is set or no TTY is available.
 
 Options:

package/src/commands/work.test.ts

@@ -82,6 +82,7 @@ interface HarnessOptions {
 	readonly phaseStatuses?: Readonly<
 		Record<string, "open" | "working" | "delegated" | "done" | "dropped">
 	>
+	readonly taskRepo?: string
 }
 
 const createHarness = (options: HarnessOptions = {}) => {
@@ -138,6 +139,16 @@ const createHarness = (options: HarnessOptions = {}) => {
 					runners: options.runners,
 				},
 			}),
+		repositoryAliases: () => Effect.succeed(["agency"]),
+		validate: () =>
+			Effect.succeed({
+				root: "/workbase",
+				issues: [],
+				epicCount: 0,
+				taskCount: 1,
+				phaseCount: 0,
+				valid: true,
+			}),
 	}
 	const epics = {
 		show: (id: string) =>
@@ -154,10 +165,11 @@ const createHarness = (options: HarnessOptions = {}) => {
 			return Effect.succeed({
 				id,
 				path: `/workbase/tasks/${id}/TASK.md`,
+				revision: "a".repeat(64),
 				data: options.multiPhaseTasks?.includes(id)
 					? { phases: [] }
 					: {
-							repo: "agency",
+							repo: options.taskRepo ?? "agency",
 							branch: `task/${id}`,
 							base: "main",
 							status: taskStatuses[id] ?? options.taskStatus ?? "open",
@@ -182,6 +194,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 				taskId,
 				id,
 				path: `/workbase/tasks/${taskId}/phases/${id}/PHASE.md`,
+				revision: "b".repeat(64),
 				data: {
 					repo: "agency",
 					branch: `task/${id}`,
@@ -246,7 +259,16 @@ const createHarness = (options: HarnessOptions = {}) => {
 	}
 	const fs = {
 		isDirectory: (path: string) =>
-			Effect.succeed(options.existingDirectories?.includes(path) ?? true),
+			Effect.succeed(
+				path === "/workbase/epics" || path === "/workbase/tasks"
+					? false
+					: (options.existingDirectories?.includes(path) ?? true),
+			),
+		readFile: (path: string) =>
+			Effect.succeed(path.endsWith("agency.json") ? '{"version":2}\n' : ""),
+		readDirectory: () => Effect.succeed([]),
+		exists: () => Effect.succeed(false),
+		realPath: (path: string) => Effect.succeed(path),
 		runCommand: (args: readonly string[]) => {
 			const cli = args[1]!
 			events.push(`probe:${cli}`)
@@ -306,6 +328,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 				Effect.provideService(WorkbaseService, workbase as never),
 				Effect.provideService(TaskService, tasks as never),
 				Effect.provideService(PhaseService, phases as never),
+				Effect.provideService(ReadinessService, readiness as never),
 			) as Effect.Effect<void, unknown, never>,
 		)
 
@@ -458,7 +481,7 @@ describe("work command", () => {
 	test("prepares without launching or changing lifecycle status", async () => {
 		const harness = createHarness({ existingDirectories: [] })
 
-		await captureLogs(() =>
+		const [output] = await captureLogs(() =>
 			harness.runPrepare({
 				cwd: "/workbase",
 				directory: "example",
@@ -473,7 +496,43 @@ describe("work command", () => {
 		expect(harness.materializeOptions[0]).toMatchObject({
 			json: true,
 			dryRun: true,
+			validationAlreadyPerformed: true,
+		})
+		const result = JSON.parse(output!)
+		expect(result.validationEvidence.status).toBe("refreshed")
+		expect(result.validationEvidence.reasons).toEqual(["not-supplied"])
+		expect(result.kickoff.target).toBe("execution-unit:task/example")
+		expect(
+			result.kickoff.steps.filter(
+				({ id }: { id: string }) => id === "final-context-verification",
+			),
+		).toHaveLength(1)
+
+		const [reusedOutput] = await captureLogs(() =>
+			harness.runPrepare({
+				cwd: "/workbase",
+				directory: "example",
+				json: true,
+				dryRun: true,
+				evidence: JSON.stringify(result.validationEvidence.evidence),
+			}),
+		)
+		expect(JSON.parse(reusedOutput!).validationEvidence).toEqual(
+			expect.objectContaining({ status: "reused", reasons: [] }),
+		)
+
+		const conflicting = createHarness({
+			existingDirectories: [],
+			taskRepo: "other",
 		})
+		await expect(
+			conflicting.runPrepare({
+				cwd: "/workbase",
+				directory: "example",
+				dryRun: true,
+				evidence: JSON.stringify(result.validationEvidence.evidence),
+			}),
+		).rejects.toThrow("Recalled repository conflicts")
 	})
 
 	test("launches an epic agent from an epic directory", async () => {

package/src/commands/work.ts

@@ -29,6 +29,13 @@ import {
 	resolveRunnerCommand,
 	runnerEnvironment,
 } from "../workbase/runner-command"
+import {
+	assessValidationEvidence,
+	buildKickoffPlan,
+	buildValidationEvidence,
+	normalizeRecalledContext,
+	readValidationEvidence,
+} from "../workbase/kickoff-contract"
 
 export interface WorkOptions extends BaseCommandOptions {
 	readonly directory?: string
@@ -41,6 +48,7 @@ export interface WorkOptions extends BaseCommandOptions {
 	readonly printCommand?: boolean
 	readonly auto?: boolean
 	readonly force?: boolean
+	readonly evidence?: string
 }
 
 export type StartWork = (options: WorkOptions) => ReturnType<typeof work>
@@ -422,6 +430,7 @@ export const workPrepare = (options: WorkOptions = {}) =>
 		const tasks = yield* TaskService
 		const phases = yield* PhaseService
 		const worktrees = yield* WorktreeService
+		const readiness = yield* ReadinessService
 		const { log } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
 		const targetPath = options.directory ? resolve(cwd, options.directory) : cwd
@@ -461,22 +470,111 @@ export const workPrepare = (options: WorkOptions = {}) =>
 			)
 		}
 
+		const task = yield* tasks.show(taskId, root)
+		const phase = phaseId
+			? yield* phases.show(taskId, phaseId, root)
+			: undefined
+		if ("phases" in task.data && !phase) {
+			return yield* Effect.fail(
+				new Error(`Task '${taskId}' has multiple phases; phase ID is required`),
+			)
+		}
+		if (!("phases" in task.data) && phaseId) {
+			return yield* Effect.fail(
+				new Error(
+					`Task '${taskId}' is single-phase and does not accept a phase ID`,
+				),
+			)
+		}
+		const target = phase
+			? `execution-unit:phase/${taskId}/${phase.id}`
+			: `execution-unit:task/${taskId}`
+		const document = phase ?? task
+		const suppliedEvidence = options.evidence
+			? yield* readValidationEvidence(options.evidence, cwd)
+			: undefined
+		if (
+			suppliedEvidence?.recalledContext.repo &&
+			(!("repo" in document.data) ||
+				suppliedEvidence.recalledContext.repo !== document.data.repo)
+		) {
+			return yield* Effect.fail(
+				new Error(
+					"Recalled repository conflicts with the current execution unit",
+				),
+			)
+		}
+		if (
+			suppliedEvidence?.recalledContext.base &&
+			(!("base" in document.data) ||
+				suppliedEvidence.recalledContext.base !== document.data.base)
+		) {
+			return yield* Effect.fail(
+				new Error("Recalled base conflicts with the current execution unit"),
+			)
+		}
+		const assessment = yield* assessValidationEvidence({
+			evidence: suppliedEvidence,
+			startPath: root,
+			target,
+			documentPath: document.path,
+			documentRevision: document.revision,
+		})
+		let validation: unknown = { valid: true, source: "evidence" }
+		if (assessment.disposition.status === "refreshed") {
+			validation = yield* workbase.validate(root)
+			if (!(validation as { valid: boolean }).valid && !options.force) {
+				return yield* Effect.fail(new Error("Workbase validation failed"))
+			}
+		}
+		yield* readiness.guardWorkTarget(target, root, options.force)
 		const workspace = yield* worktrees.materialize(taskId, phaseId, root, {
 			...options,
 			dryRun: options.dryRun,
+			validationAlreadyPerformed: true,
+		})
+		const recalledContext =
+			suppliedEvidence?.recalledContext ??
+			normalizeRecalledContext({
+				id: taskId,
+				repo: "repo" in document.data ? document.data.repo : undefined,
+				base: "base" in document.data ? document.data.base : undefined,
+			})
+		const evidence = yield* buildValidationEvidence({
+			startPath: root,
+			target,
+			documentPath: document.path,
+			documentRevision: document.revision,
+			recalledContext,
 		})
+		const result = {
+			...workspace,
+			workspace,
+			validation,
+			validationEvidence: { ...assessment.disposition, evidence },
+			kickoff: buildKickoffPlan({
+				workbaseRoot: root,
+				target,
+				taskId,
+				phaseId: phase?.id,
+				taskPath: task.path,
+				phasePath: phase?.path,
+				checkoutPath: workspace.writablePath ?? workspace.reviewPath,
+				documentRevision: document.revision,
+			}),
+		}
 		if (options.json) {
-			log(JSON.stringify(workspace, null, 2))
+			log(JSON.stringify(result, null, 2))
 		} else {
 			log(
-				`${workspace.dryRun ? "Workspace plan" : "Workspace ready"}: ${workspace.writablePath ?? workspace.reviewPath}`,
+				`${workspace.dryRun ? "Kickoff plan" : "Workspace ready"}: ${workspace.writablePath ?? workspace.reviewPath}`,
 			)
 		}
 	})
 
 export const help = `
 Usage: agency work [<directory-or-task-id> | --epic <epic-id>] [--runner <name>] [--auto]
-       agency work prepare [target] [--dry-run] [--json]
+       agency work prepare [target] [--evidence <json-or-path>] [--dry-run] [--json]
 
 Launch an agent for an epic, task, or phase. With no directory, select one
 interactively. A positional argument resolves as a directory first, then as a task
@@ -487,6 +585,10 @@ Agency's project plugin; Agency context remains authoritative for writes.
 The prepare subcommand resolves and materializes an execution workspace without
 launching an agent or changing lifecycle status. --dry-run reports planned Git
 changes without fetching, creating branches, or creating worktrees.
+It emits revision-bound validation evidence and an idempotent external-orchestrator
+contract. Evidence is reused only while the target, workbase, configuration, and
+repository mapping remain unchanged. Dynamic readiness and workspace safety checks
+always run.
 
 Options:
   --epic <id>          Work on an epic
@@ -500,6 +602,7 @@ Options:
   --opencode           Require the OpenCode preset
   --claude             Require the Claude Code preset
   --force              Override readiness; reopen terminal execution units
+	--evidence <value>   Validation evidence JSON or a path to JSON (prepare only)
   --no-input           Never open an interactive selector
 
 Without interactive input, provide an explicit workbase or cwd and an entity

package/src/graph-schema.test.ts

@@ -27,6 +27,14 @@ describe("graph contract", () => {
 			readiness: { type: "null" },
 			aggregate: { type: "null" },
 		})
+		expect(jsonSchema.$defs.taskHandoff).toMatchObject({
+			additionalProperties: false,
+			required: ["source", "sourceRevision"],
+		})
+		expect(jsonSchema.$defs.singleTaskData.properties).toMatchObject({
+			purpose: { $ref: "#/$defs/taskPurpose" },
+			handoff: { $ref: "#/$defs/taskHandoff" },
+		})
 	})
 
 	test("streams records that reconstruct graph semantics", () => {

package/src/graph-schema.ts

@@ -5,6 +5,7 @@ import {
 	PullRequestRecord,
 	ClaimRecord,
 	ReviewRecord,
+	TaskHandoff,
 	TaskFrontmatter,
 	WorkStatus,
 } from "./workbase/schemas"
@@ -80,6 +81,10 @@ export const GraphExecutionData = Schema.Union(
 			phaseId: Schema.optional(Schema.String),
 			ticketUrl: Schema.optional(Schema.NullOr(Schema.String)),
 			epic: Schema.optional(Schema.String),
+			purpose: Schema.optional(
+				Schema.Literal("investigation", "implementation"),
+			),
+			handoff: Schema.optional(TaskHandoff),
 		}),
 	),
 	Schema.Struct({
@@ -87,6 +92,8 @@ export const GraphExecutionData = Schema.Union(
 		ticketUrl: Schema.NullOr(Schema.String),
 		description: Schema.optional(Schema.String),
 		epic: Schema.optional(Schema.String),
+		purpose: Schema.optional(Schema.Literal("investigation", "implementation")),
+		handoff: Schema.optional(TaskHandoff),
 		review: ReviewRecord,
 		status: WorkStatus,
 		claim: Schema.optional(ClaimRecord),

package/src/services/ArchiveService.test.ts

@@ -734,6 +734,11 @@ describe("ArchiveService", () => {
 							repo: "agency",
 							branch: "task/child",
 							base: "main",
+							purpose: "implementation",
+							handoff: {
+								source: { kind: "task", taskId: "investigation" },
+								sourceRevision: "a".repeat(64),
+							},
 						},
 						root,
 					),
@@ -787,6 +792,18 @@ describe("ArchiveService", () => {
 			),
 		)
 		expect(epic.data.tasks).toEqual([{ id: "child" }])
+		const restoredTask = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("child", root)),
+			),
+		)
+		expect(restoredTask.data).toMatchObject({
+			purpose: "implementation",
+			handoff: {
+				source: { kind: "task", taskId: "investigation" },
+				sourceRevision: "a".repeat(64),
+			},
+		})
 		const provenance = await Bun.file(
 			join(root, "tasks/child/.agency-lifecycle.json"),
 		).json()
@@ -1040,7 +1057,7 @@ describe("ArchiveService", () => {
 					),
 				),
 			),
-		).rejects.toThrow("is archived; restore it")
+		).rejects.toThrow("is archived; explicit creation requires a different ID")
 	})
 
 	test("does not remove worktrees when another lifecycle mutation holds the lock", async () => {