@markjaquith/agency 2.59.0 → 2.61.0

package/src/services/GraphMutationService.test.ts

@@ -326,6 +326,54 @@ describe("GraphMutationService", () => {
 		)
 	})
 
+	test("preserves historical handoff provenance across source and destination renames", async () => {
+		await runTestEffect(
+			Effect.gen(function* () {
+				const tasks = yield* TaskService
+				yield* tasks.create(
+					{
+						id: "investigation",
+						ticketUrl: null,
+						repo: "agency",
+						branch: "task/investigation",
+						base: "main",
+						purpose: "investigation",
+					},
+					root,
+				)
+				yield* tasks.handoff(
+					{
+						sourceTaskId: "investigation",
+						id: "implementation",
+						ticketUrl: null,
+						repo: "docs",
+						branch: "task/implementation",
+						base: "main",
+					},
+					root,
+				)
+				const before = yield* tasks.show("implementation", root)
+				const mutations = yield* GraphMutationService
+				yield* mutations.renameTask(
+					"investigation",
+					"investigation-renamed",
+					root,
+				)
+				yield* mutations.renameTask(
+					"implementation",
+					"implementation-renamed",
+					root,
+				)
+				const after = yield* tasks.show("implementation-renamed", root)
+				expect(after.data.handoff).toEqual(before.data.handoff)
+				expect(after.data.handoff?.source).toEqual({
+					kind: "task",
+					taskId: "investigation",
+				})
+			}),
+		)
+	})
+
 	test("moves task membership in both directions", async () => {
 		await runTestEffect(
 			Effect.gen(function* () {

package/src/services/IntegrationService.test.ts

@@ -107,6 +107,21 @@ describe("IntegrationService", () => {
 		])
 	})
 
+	test("generates the canonical Agency kickoff recipe with precedence", () => {
+		expect(managedWorkbaseAgents).toContain(
+			"takes precedence over generic Herdr defaults",
+		)
+		expect(managedWorkbaseAgents).toContain(
+			"agency work prepare <slug> --evidence",
+		)
+		expect(managedWorkbaseAgents).toContain("agency-kickoff-v1")
+		expect(managedWorkbaseAgents).toContain(
+			"call Herdr help, skill, or CLI discovery",
+		)
+		expect(managedWorkbaseAgents).toContain("exactly one final")
+		expect(managedWorkbaseAgents).toContain("leave the runner in the")
+	})
+
 	test("generates a dynamic workbase plugin", () => {
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			"process.env.AGENCY_WRITABLE_CHECKOUT",
@@ -405,6 +420,13 @@ describe("IntegrationService", () => {
 		expect(body).toContain("authority.writable.checkoutPath")
 		expect(body).toContain("Only `done` satisfies a dependency")
 		expect(body).toContain("Require explicit user intent")
+		expect(body).toContain(
+			"explicit request for a new, separate, or follow-up item",
+		)
+		expect(body).toContain("agency task handoff")
+		expect(body).toContain(
+			"Creation and handoff do not imply worktree preparation",
+		)
 		expect(body).toContain("changing repository")
 		expect(body).toMatch(
 			/archiving, restoring,\s+dropping, reopening, or completing work without a pull request/,
@@ -445,6 +467,28 @@ describe("IntegrationService", () => {
 		expect(body).not.toContain(".opencode/command/agency.md")
 	})
 
+	test("generates repository add and setup guidance", () => {
+		const body = managedBody(managedWorkbaseAgents)
+
+		expect(body).toContain("## Adding a Repository")
+		expect(body).toContain("agency repo add <alias> <remote> --json")
+		expect(body).toContain(
+			"`agency repo add` mutates immediately and does not accept `--apply`",
+		)
+		expect(body).toContain("agency repo setup --dry-run")
+		expect(body).toContain("agency repo setup --apply")
+		expect(body).toMatch(
+			/repositories that are already declared\s+but locally missing/,
+		)
+		expect(body).toContain("Do not edit\n`agency.json` or `repos/` manually")
+		expect(body).toMatch(
+			/agency repo verify <alias> --json\s+agency validate --json/,
+		)
+		expect(body).toMatch(
+			/run only these checks, in order, unless\s+`agency context` reports a relevant problem/,
+		)
+	})
+
 	test("configures Agency agents with complete workbase access", () => {
 		const config = JSON.parse(managedBody(managedWorkbaseOpencode))
 
@@ -480,6 +524,9 @@ describe("IntegrationService", () => {
 		})
 		expect(config.agent.agency.model).toBeUndefined()
 		expect(config.agent.agency.permission).toBeUndefined()
+		expect(config.agent["agency-plan"].prompt).toContain(
+			"Explicit-new intent overrides reuse",
+		)
 		expect(config.agent.agency.hidden).toBeUndefined()
 		expect(config.agent.agency.steps).toBeUndefined()
 		expect(config.agent.agency.prompt).toContain(

package/src/services/LifecycleTransaction.ts

@@ -25,6 +25,18 @@ export interface TransactionStep {
 	readonly manualRecovery?: string
 }
 
+export const pathMustNotExistStep = (
+	root: string,
+	path: string,
+	message: string,
+): TransactionStep => ({
+	label: `verify ${relative(root, path)} is available`,
+	preflight: async () => {
+		if (await exists(path)) throw new Error(message)
+	},
+	apply: async () => {},
+})
+
 interface DocumentWrite {
 	readonly path: string
 	readonly content: string

package/src/services/PhaseService.ts

@@ -249,6 +249,8 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 								? { description: task.data.description }
 								: {}),
 							...(task.data.epic ? { epic: task.data.epic } : {}),
+							...(task.data.purpose ? { purpose: task.data.purpose } : {}),
+							...(task.data.handoff ? { handoff: task.data.handoff } : {}),
 							phases: [
 								{ id: firstPhaseId! },
 								{

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"] },