@markjaquith/agency 2.58.2 → 2.60.0

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/services/ArchiveService.ts

@@ -413,6 +413,7 @@ const restoreWorktreeSnapshots = async (
 				snapshot.head,
 				snapshot.path,
 			])
+			await runGit(["jj", "-R", snapshot.path, "edit", snapshot.head])
 			continue
 		}
 		await runGit(
@@ -723,6 +724,7 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 						removedWorktrees.push(
 							...(yield* worktrees.remove(unit.taskId, unit.phaseId, root, {
 								dryRun: true,
+								persistResume: false,
 							})),
 						)
 					}
@@ -781,6 +783,7 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 												worktrees.remove(unit.taskId, unit.phaseId, root, {
 													snapshots,
 													lockHeld: true,
+													persistResume: false,
 												}),
 											)
 									} catch (cause) {
@@ -891,6 +894,7 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 							const result = yield* worktrees
 								.remove(unit.taskId, executionPhaseId(unit), root, {
 									dryRun: true,
+									persistResume: false,
 								})
 								.pipe(Effect.either)
 							if (Either.isLeft(result)) {
@@ -1064,6 +1068,7 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 												worktrees.remove(unit.taskId, unit.phaseId, root, {
 													snapshots,
 													lockHeld: true,
+													persistResume: false,
 												}),
 											)
 										}
@@ -1212,6 +1217,7 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 								root,
 								{
 									dryRun: true,
+									persistResume: false,
 								},
 							)),
 						)
@@ -1267,6 +1273,7 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 													{
 														snapshots,
 														lockHeld: true,
+														persistResume: false,
 													},
 												),
 											)
@@ -1359,6 +1366,7 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 					yield* rejectExistingDestination(destination, "Archive")
 					const removedWorktrees = yield* worktrees.remove(taskId, id, root, {
 						dryRun: true,
+						persistResume: false,
 					})
 					const at = new Date().toISOString()
 					const content = yield* declarationContent(task, {
@@ -1407,6 +1415,7 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 													worktrees.remove(taskId, id, root, {
 														snapshots,
 														lockHeld: true,
+														persistResume: false,
 													}),
 												)
 											},

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",
@@ -445,6 +460,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))
 

package/src/services/ReviewService.ts

@@ -101,6 +101,7 @@ const restoreSnapshots = async (
 				snapshot.head,
 				snapshot.path,
 			])
+			await runGit(["jj", "-R", snapshot.path, "edit", snapshot.head])
 			continue
 		}
 		await runGit(
@@ -392,6 +393,7 @@ export class ReviewService extends Effect.Service<ReviewService>()(
 											worktrees.remove(taskId, undefined, root, {
 												snapshots,
 												lockHeld: true,
+												persistResume: false,
 											}),
 										).then(() => undefined),
 									rollback: () => restoreSnapshots(snapshots),