@markjaquith/agency 2.59.0 → 2.61.0

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

@@ -272,6 +272,7 @@ interface MaterializeOptions extends BaseCommandOptions {
 	readonly force?: boolean
 	readonly lockHeld?: boolean
 	readonly allowReferenceDrift?: boolean
+	readonly validationAlreadyPerformed?: boolean
 }
 
 interface RemoveOptions extends BaseCommandOptions {
@@ -1850,12 +1851,14 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 					const { root, config } = yield* workbase.loadConfig(startPath)
 					const backend = yield* versionControl.forWorkbase(root)
 					const materialization = Effect.gen(function* () {
-						const report = yield* workbase.validate(root)
-						const validationIssue = report.issues[0]
-						if (validationIssue && !options.force) {
-							return yield* new WorktreeError({
-								message: `${validationIssue.path}: ${validationIssue.message}`,
-							})
+						if (!options.validationAlreadyPerformed) {
+							const report = yield* workbase.validate(root)
+							const validationIssue = report.issues[0]
+							if (validationIssue && !options.force) {
+								return yield* new WorktreeError({
+									message: `${validationIssue.path}: ${validationIssue.message}`,
+								})
+							}
 						}
 						const task = yield* tasks.show(taskId, root)
 

package/src/workbase/AGENTS.md

@@ -20,10 +20,26 @@ At the workbase root, use `agency next --json` or `agency graph --json` to choos
 work, then inspect the returned document path or explicit entity selectors. Use
 `agency --help` and `agency <command> --help` for exact command syntax.
 
-If context or doctor reports a declared but missing repository, run
-`agency repo setup --dry-run` and obtain explicit approval before
-`agency repo setup --apply`. Missing declared aliases are setup state, not a
-reason to edit `agency.json` or `repos/` by hand.
+## Adding a Repository
+
+Add and materialize a new repository alias with:
+
+```bash
+agency repo add <alias> <remote> --json
+```
+
+`agency repo add` mutates immediately and does not accept `--apply`. Do not edit
+`agency.json` or `repos/` manually. `agency repo setup --dry-run` and
+`agency repo setup --apply` are only for repositories that are already declared
+but locally missing; obtain explicit approval before applying setup.
+
+After adding a repository, run only these checks, in order, unless
+`agency context` reports a relevant problem:
+
+```bash
+agency repo verify <alias> --json
+agency validate --json
+```
 
 ## Authority
 
@@ -46,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
@@ -64,6 +105,41 @@ to override readiness.
 
 ## Execution
 
+### Canonical create and kickoff
+
+This Agency recipe takes precedence over generic Herdr defaults whenever the
+request creates, opens, works, launches, starts, or kicks off an Agency item.
+Do not rediscover commands that this recipe or a known-current
+`agency-kickoff-v1` plan supplies.
+
+1. Create noninteractively with explicit recalled context when available:
+   `agency task create <slug> --context-repo <alias> --context-base <base> --context-slug <slug> --authoritative-source <absolute-path-or-url> --json`.
+   Repeat `--authoritative-source` as needed. Supplied context must agree with
+   explicit task flags; Agency rejects stale or conflicting values.
+2. For create-only intent, return the creation result and stop. For open intent,
+   prepare the task with
+   `agency work prepare <slug> --evidence <creation-json> --dry-run --json`, then
+   execute the returned plan through `task-document-split` to prepare the
+   checkout and open or reuse the background tab. Stop before `runner-start`.
+3. For work/launch/start/kickoff intent, run that same preflight and execute its
+   ordered kickoff steps. The plan owns worktree dry-run/preparation, a
+   retry-safe background Herdr tab, the side-by-side task document,
+   `agency work . --auto`, and exactly one final
+   `agency context <document-path> --json` verification.
+4. When the orchestrator has known-current support for the plan's
+   `agency-kickoff-v1` capability, execute the supplied actions directly. Do not
+   call Herdr help, skill, or CLI discovery. If capability/version evidence is
+   absent or stale, discovery is the compatibility path; then resume the same
+   idempotency key rather than creating another tab, checkout, or runner.
+5. After the one final context verification succeeds, leave the runner in the
+   background and stop. Do not inspect, poll, or babysit it unless the user asks.
+
+Validation evidence is a local, auditable optimization, not authority. Preflight
+refreshes it after workbase, target document, configuration, repository mapping,
+payload digest, or kickoff-contract changes. Readiness, claims, repository
+materialization, branch ownership, reference drift, and dirty-workspace checks
+still run on every preparation.
+
 For implementation work, read the task and phase prose returned by context,
 change only the writable checkout, keep durable decisions current, and run the
 repository's formatting, type checks, build, dead-code checks, and focused tests.

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