@markjaquith/agency 2.59.0 → 2.61.0

package/src/workbase/kickoff-contract.test.ts

@@ -0,0 +1,145 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { mkdir } from "node:fs/promises"
+import { join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { documentRevision } from "./document-revision"
+import {
+	assessValidationEvidence,
+	buildKickoffPlan,
+	buildValidationEvidence,
+	KICKOFF_SOURCE_LOCATIONS,
+	normalizeRecalledContext,
+	parseValidationEvidence,
+	readValidationEvidence,
+} from "./kickoff-contract"
+
+describe("kickoff contract", () => {
+	let root: string
+	let taskPath: string
+	let taskContent: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		taskPath = join(root, "tasks/example/TASK.md")
+		taskContent =
+			"---\nticketUrl: null\nrepo: agency\nbranch: task/example\nbase: main\npr: null\nstatus: open\n---\n\n# Example\n"
+		await mkdir(join(root, "repos/agency"), { recursive: true })
+		await mkdir(join(root, "tasks/example"), { recursive: true })
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		await Bun.write(taskPath, taskContent)
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	const createEvidence = () =>
+		runTestEffect(
+			buildValidationEvidence({
+				startPath: root,
+				target: "execution-unit:task/example",
+				documentPath: taskPath,
+				documentRevision: documentRevision(taskContent),
+				recalledContext: normalizeRecalledContext({
+					id: "example",
+					repo: "agency",
+					base: "main",
+				}),
+			}),
+		)
+
+	test("reuses evidence only for the same workbase and revision", async () => {
+		const evidence = await createEvidence()
+		expect(parseValidationEvidence(evidence)).toEqual(evidence)
+		const assessment = await runTestEffect(
+			assessValidationEvidence({
+				evidence,
+				startPath: root,
+				target: evidence.target,
+				documentPath: taskPath,
+				documentRevision: evidence.documentRevision,
+			}),
+		)
+		expect(assessment.disposition).toEqual({ status: "reused", reasons: [] })
+	})
+
+	test("treats legacy creation output as a validation refresh", async () => {
+		expect(
+			await runTestEffect(
+				readValidationEvidence(
+					JSON.stringify({ version: 1, ok: true, result: { id: "example" } }),
+					root,
+				),
+			),
+		).toBeUndefined()
+	})
+
+	test("refreshes evidence after document, config, mapping, or payload changes", async () => {
+		const evidence = await createEvidence()
+		const changedContent = `${taskContent}\nChanged\n`
+		await Bun.write(taskPath, changedContent)
+		await mkdir(join(root, "repos/other"), { recursive: true })
+		await Bun.write(
+			join(root, "agency.json"),
+			'{"version":2,"repositories":{"other":{"remote":"https://example.com/other.git"}}}\n',
+		)
+		const assessment = await runTestEffect(
+			assessValidationEvidence({
+				evidence: { ...evidence, digest: "0".repeat(64) },
+				startPath: root,
+				target: evidence.target,
+				documentPath: taskPath,
+				documentRevision: documentRevision(changedContent),
+			}),
+		)
+		expect(assessment.disposition.status).toBe("refreshed")
+		expect(assessment.disposition.reasons).toEqual(
+			expect.arrayContaining([
+				"digest-mismatch",
+				"document-revision-changed",
+				"workbase-revision-changed",
+				"configuration-changed",
+				"repository-mapping-changed",
+			]),
+		)
+	})
+
+	test("plans retry-safe single-phase and phased launches with one verification", () => {
+		const single = buildKickoffPlan({
+			workbaseRoot: root,
+			target: "execution-unit:task/example",
+			taskId: "example",
+			taskPath,
+			checkoutPath: join(root, "tasks/example/code/agency"),
+			documentRevision: "a".repeat(64),
+		})
+		const phased = buildKickoffPlan({
+			workbaseRoot: root,
+			target: "execution-unit:phase/example/implementation",
+			taskId: "example",
+			phaseId: "implementation",
+			taskPath,
+			phasePath: join(root, "tasks/example/phases/implementation/PHASE.md"),
+			documentRevision: "b".repeat(64),
+		})
+		expect(single.steps[0]?.argv).toContain("example")
+		expect(phased.steps[0]?.argv).toEqual(
+			expect.arrayContaining(["example", "implementation"]),
+		)
+		expect(
+			single.steps.filter(({ id }) => id === "final-context-verification"),
+		).toHaveLength(1)
+		expect(single.orchestrator.knownCurrentCommandsBypassDiscovery).toBe(true)
+		expect(single.sourceLocations).toEqual(KICKOFF_SOURCE_LOCATIONS)
+		expect(
+			single.steps.find(({ id }) => id === "herdr-tab")?.recovery,
+		).toContain("never create a duplicate")
+		expect(single.idempotencyKey).toBe(
+			buildKickoffPlan({
+				workbaseRoot: root,
+				target: "execution-unit:task/example",
+				taskId: "example",
+				taskPath,
+				documentRevision: "a".repeat(64),
+			}).idempotencyKey,
+		)
+	})
+})

package/src/workbase/kickoff-contract.ts

@@ -0,0 +1,358 @@
+import { Schema, TreeFormatter } from "@effect/schema"
+import { Effect, Either } from "effect"
+import { dirname, isAbsolute, join, resolve } from "node:path"
+import { FileSystemService } from "../services/FileSystemService"
+import { WorkbaseService } from "../services/WorkbaseService"
+import { documentRevision } from "./document-revision"
+
+export const KICKOFF_CONTRACT_VERSION = 1 as const
+
+export const KICKOFF_SOURCE_LOCATIONS = [
+	"src/commands/task.ts",
+	"src/workbase/kickoff-contract.ts",
+	"src/commands/work.ts",
+	"src/services/WorktreeService.ts",
+	"src/workbase/AGENTS.md",
+] as const
+
+export const RecalledTaskContext = Schema.Struct({
+	repo: Schema.optional(Schema.String),
+	base: Schema.optional(Schema.String),
+	preferredSlug: Schema.String,
+	authoritativeSources: Schema.Array(Schema.String),
+})
+
+export type RecalledTaskContext = Schema.Schema.Type<typeof RecalledTaskContext>
+
+const ValidationEvidencePayload = Schema.Struct({
+	version: Schema.Literal(KICKOFF_CONTRACT_VERSION),
+	workbaseRoot: Schema.String,
+	target: Schema.String,
+	documentPath: Schema.String,
+	documentRevision: Schema.String,
+	workbaseRevision: Schema.String,
+	configRevision: Schema.String,
+	repositoryMappingRevision: Schema.String,
+	valid: Schema.Literal(true),
+	recalledContext: RecalledTaskContext,
+})
+
+export const ValidationEvidence = Schema.Struct({
+	...ValidationEvidencePayload.fields,
+	digest: Schema.String,
+})
+
+export type ValidationEvidence = Schema.Schema.Type<typeof ValidationEvidence>
+
+export type EvidenceDisposition =
+	| { readonly status: "reused"; readonly reasons: readonly [] }
+	| {
+			readonly status: "refreshed"
+			readonly reasons: readonly string[]
+	  }
+
+const digest = (value: unknown) => documentRevision(JSON.stringify(value))
+
+const validateSource = (source: string) => {
+	if (!source.trim()) throw new Error("Authoritative source cannot be empty")
+	if (isAbsolute(source)) return source
+	try {
+		const url = new URL(source)
+		if (url.protocol === "https:" || url.protocol === "http:") return source
+	} catch {}
+	throw new Error(
+		`Authoritative source '${source}' must be an absolute path or HTTP(S) URL`,
+	)
+}
+
+export const normalizeRecalledContext = (input: {
+	readonly id: string
+	readonly repo?: string
+	readonly base?: string
+	readonly preferredSlug?: string
+	readonly authoritativeSources?: readonly string[]
+}): RecalledTaskContext => {
+	if (input.repo !== undefined && !input.repo.trim()) {
+		throw new Error("Recalled repository cannot be empty")
+	}
+	if (input.base !== undefined && !input.base.trim()) {
+		throw new Error("Recalled base cannot be empty")
+	}
+	if (input.preferredSlug !== undefined && !input.preferredSlug.trim()) {
+		throw new Error("Recalled task slug cannot be empty")
+	}
+	if (input.preferredSlug && input.preferredSlug !== input.id) {
+		throw new Error(
+			`Recalled task slug '${input.preferredSlug}' conflicts with task ID '${input.id}'`,
+		)
+	}
+	return {
+		...(input.repo ? { repo: input.repo } : {}),
+		...(input.base ? { base: input.base } : {}),
+		preferredSlug: input.id,
+		authoritativeSources: [...(input.authoritativeSources ?? [])]
+			.map(validateSource)
+			.sort(),
+	}
+}
+
+const workbaseIdentity = (startPath: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const workbase = yield* WorkbaseService
+		const root = yield* workbase.discover(startPath)
+		const configPath = join(root, "agency.json")
+		const configContent = yield* fs.readFile(configPath)
+		const { config } = yield* workbase.loadConfig(root)
+		const documents: Array<readonly [string, string]> = []
+
+		const collect = (directory: string, filename: string) =>
+			Effect.gen(function* () {
+				if (!(yield* fs.isDirectory(directory))) return
+				for (const entry of (yield* fs.readDirectory(directory)).sort((a, b) =>
+					a.name.localeCompare(b.name),
+				)) {
+					if (!entry.isDirectory) continue
+					const path = join(directory, entry.name, filename)
+					if (yield* fs.exists(path))
+						documents.push([path, yield* fs.readFile(path)])
+				}
+			})
+
+		yield* collect(join(root, "epics"), "EPIC.md")
+		yield* collect(join(root, "tasks"), "TASK.md")
+		const tasksDirectory = join(root, "tasks")
+		if (yield* fs.isDirectory(tasksDirectory)) {
+			for (const task of yield* fs.readDirectory(tasksDirectory)) {
+				if (task.isDirectory) {
+					yield* collect(join(tasksDirectory, task.name, "phases"), "PHASE.md")
+				}
+			}
+		}
+		documents.sort(([left], [right]) => left.localeCompare(right))
+		const aliases = yield* workbase.repositoryAliases(root)
+		const materializedMappings: Array<readonly [string, string | null]> = []
+		for (const alias of aliases) {
+			const path = join(root, "repos", alias)
+			materializedMappings.push([
+				alias,
+				(yield* fs.exists(path)) ? yield* fs.realPath(path) : null,
+			])
+		}
+		return {
+			root,
+			configRevision: documentRevision(configContent),
+			repositoryMappingRevision: digest({
+				repositories: config.repositories ?? {},
+				aliases,
+				materializedMappings,
+			}),
+			workbaseRevision: digest(
+				documents.map(([path, content]) => [
+					path.slice(root.length),
+					digest(content),
+				]),
+			),
+		}
+	})
+
+export const buildValidationEvidence = (input: {
+	readonly startPath: string
+	readonly target: string
+	readonly documentPath: string
+	readonly documentRevision: string
+	readonly recalledContext: RecalledTaskContext
+}) =>
+	Effect.gen(function* () {
+		const identity = yield* workbaseIdentity(input.startPath)
+		const payload = {
+			version: KICKOFF_CONTRACT_VERSION,
+			workbaseRoot: identity.root,
+			target: input.target,
+			documentPath: resolve(input.documentPath),
+			documentRevision: input.documentRevision,
+			workbaseRevision: identity.workbaseRevision,
+			configRevision: identity.configRevision,
+			repositoryMappingRevision: identity.repositoryMappingRevision,
+			valid: true as const,
+			recalledContext: input.recalledContext,
+		}
+		return { ...payload, digest: digest(payload) } satisfies ValidationEvidence
+	})
+
+export const parseValidationEvidence = (value: unknown): ValidationEvidence => {
+	const decoded = Schema.decodeUnknownEither(ValidationEvidence, {
+		errors: "all",
+		onExcessProperty: "error",
+	})(value)
+	if (Either.isLeft(decoded)) {
+		throw new Error(
+			`Invalid validation evidence: ${TreeFormatter.formatErrorSync(decoded.left)}`,
+		)
+	}
+	return decoded.right
+}
+
+export const readValidationEvidence = (input: string, cwd: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const trimmed = input.trim()
+		const content = trimmed.startsWith("{")
+			? trimmed
+			: yield* fs.readFile(resolve(cwd, trimmed))
+		try {
+			const parsed = JSON.parse(content)
+			const candidate =
+				parsed?.result?.validationEvidence?.evidence ??
+				parsed?.result?.evidence ??
+				parsed?.validationEvidence?.evidence ??
+				parsed?.evidence ??
+				(parsed?.target && parsed?.documentRevision ? parsed : undefined)
+			if (!candidate || candidate.version !== KICKOFF_CONTRACT_VERSION) {
+				return undefined
+			}
+			return parseValidationEvidence(candidate)
+		} catch (cause) {
+			return yield* Effect.fail(
+				cause instanceof Error ? cause : new Error(String(cause)),
+			)
+		}
+	})
+
+export const assessValidationEvidence = (input: {
+	readonly evidence?: ValidationEvidence
+	readonly startPath: string
+	readonly target: string
+	readonly documentPath: string
+	readonly documentRevision: string
+}) =>
+	Effect.gen(function* () {
+		const identity = yield* workbaseIdentity(input.startPath)
+		const evidence = input.evidence
+		const reasons: string[] = []
+		if (!evidence) reasons.push("not-supplied")
+		else {
+			const { digest: evidenceDigest, ...payload } = evidence
+			if (digest(payload) !== evidenceDigest) reasons.push("digest-mismatch")
+			if (evidence.workbaseRoot !== identity.root)
+				reasons.push("workbase-mismatch")
+			if (evidence.target !== input.target) reasons.push("target-mismatch")
+			if (evidence.documentPath !== resolve(input.documentPath))
+				reasons.push("document-path-mismatch")
+			if (evidence.documentRevision !== input.documentRevision)
+				reasons.push("document-revision-changed")
+			if (evidence.workbaseRevision !== identity.workbaseRevision)
+				reasons.push("workbase-revision-changed")
+			if (evidence.configRevision !== identity.configRevision)
+				reasons.push("configuration-changed")
+			if (
+				evidence.repositoryMappingRevision !==
+				identity.repositoryMappingRevision
+			)
+				reasons.push("repository-mapping-changed")
+		}
+		return {
+			identity,
+			disposition: reasons.length
+				? ({ status: "refreshed", reasons } as const)
+				: ({ status: "reused", reasons: [] } as const),
+		}
+	})
+
+export const buildKickoffPlan = (input: {
+	readonly workbaseRoot: string
+	readonly target: string
+	readonly taskId: string
+	readonly phaseId?: string
+	readonly taskPath: string
+	readonly phasePath?: string | null
+	readonly checkoutPath?: string | null
+	readonly documentRevision: string
+}) => {
+	const selector = [input.taskId, ...(input.phaseId ? [input.phaseId] : [])]
+	const taskDirectory = dirname(input.phasePath ?? input.taskPath)
+	const idempotencyKey = digest({
+		version: KICKOFF_CONTRACT_VERSION,
+		workbaseRoot: input.workbaseRoot,
+		target: input.target,
+	})
+	return {
+		version: KICKOFF_CONTRACT_VERSION,
+		idempotencyKey,
+		workbaseRoot: input.workbaseRoot,
+		target: input.target,
+		documentRevision: input.documentRevision,
+		sourceLocations: KICKOFF_SOURCE_LOCATIONS,
+		taskDirectory,
+		taskDocument: input.taskPath,
+		phaseDocument: input.phasePath ?? null,
+		preparedCheckout: input.checkoutPath ?? null,
+		orchestrator: {
+			capability: "agency-kickoff-v1",
+			knownCurrentCommandsBypassDiscovery: true,
+			fallback:
+				"Discover Herdr capabilities only when capability/version evidence is absent or stale.",
+		},
+		steps: [
+			{
+				id: "worktree-dry-run",
+				argv: [
+					"agency",
+					"worktree",
+					"prepare",
+					...selector,
+					"--dry-run",
+					"--json",
+				],
+				retry: "safe",
+			},
+			{
+				id: "worktree-prepare",
+				argv: ["agency", "worktree", "prepare", ...selector, "--json"],
+				retry: "reuses matching clean workspaces",
+			},
+			{
+				id: "herdr-tab",
+				action: "create-or-reuse-background-tab",
+				idempotencyKey,
+				recovery:
+					"Reuse the tab recorded for this idempotency key; never create a duplicate.",
+			},
+			{
+				id: "task-document-split",
+				action: "open-side-by-side-document",
+				path: input.phasePath ?? input.taskPath,
+				recovery: "Reuse the existing split when present.",
+			},
+			{
+				id: "runner-start",
+				cwd: taskDirectory,
+				argv: ["agency", "work", ".", "--auto"],
+				recovery:
+					"Inspect the recorded tab before retrying; a working runner must not be duplicated.",
+			},
+			{
+				id: "final-context-verification",
+				argv: [
+					"agency",
+					"context",
+					input.phasePath ?? input.taskPath,
+					"--json",
+				],
+				exactlyOnce: true,
+				recovery:
+					"If verification fails, inspect the existing tab; do not launch another runner.",
+			},
+		],
+		successFields: [
+			"target",
+			"taskDirectory",
+			"taskDocument",
+			"preparedCheckout",
+			"herdrWorkspace",
+			"herdrTab",
+			"runnerStart",
+			"contextVerification",
+		],
+	}
+}

package/src/workbase/opencode-file.ts

@@ -10,7 +10,7 @@ const agencyPlanPrompt = `You are in Agency Plan mode. Think, read, search, and
 
 Start with \`agency context . --json\`. Use its document paths and revisions, then inspect the graph, related epics, tasks, phases, linked tickets, and repository declarations needed to understand the work. Use machine-readable Agency output when available instead of inferring structure from directory names.
 
-When planning an epic, decompose it into independently deliverable tasks with explicit dependencies. Add phases only when one task genuinely requires multiple ordered delivery units. Reuse or update existing work instead of creating duplicate tasks or phases.
+When planning an epic, decompose it into independently deliverable tasks with explicit dependencies. Add phases only when one task genuinely requires multiple ordered delivery units. Reuse or update existing work instead of creating duplicate tasks or phases, except when the user explicitly requests a new, separate, or follow-up item. Explicit-new intent overrides reuse of active and archived work even when the subject or suggested ID matches.
 
 Use the Agency CLI for full workbase orchestration when the plan requires it, including creating or updating related epics, tasks, and phases; moving tasks; maintaining dependencies; and changing lifecycle state. Use \`--if-revision\` with the revision returned by context for mutations that support it, and run \`agency validate\` after changing workbase structure. Use available ticket tools to inspect or update a linked external ticket when the plan requires it.
 

package/src/workbase/schemas.test.ts

@@ -64,6 +64,42 @@ describe("portable repository declarations", () => {
 })
 
 describe("body-of-work descriptions", () => {
+	test("decodes strict task purpose and handoff provenance", () => {
+		const handoff = {
+			source: { kind: "phase", taskId: "investigate", phaseId: "evidence" },
+			sourceRevision: "a".repeat(64),
+		}
+		const task = Schema.decodeUnknownSync(TaskFrontmatter, {
+			onExcessProperty: "error",
+		})({
+			ticketUrl: null,
+			purpose: "implementation",
+			handoff,
+			repo: "agency",
+			branch: "task/implement",
+			base: "main",
+			pr: null,
+		})
+		expect(task).toMatchObject({ purpose: "implementation", handoff })
+
+		for (const invalid of [
+			{ ...handoff, sourceRevision: "short" },
+			{ ...handoff, source: { kind: "phase", taskId: "investigate" } },
+			{ ...handoff, source: { kind: "task", taskId: "../unsafe" } },
+		]) {
+			expect(() =>
+				Schema.decodeUnknownSync(TaskFrontmatter, {
+					onExcessProperty: "error",
+				})({
+					ticketUrl: null,
+					purpose: "implementation",
+					handoff: invalid,
+					phases: [],
+				}),
+			).toThrow()
+		}
+	})
+
 	test("decodes review tasks strictly and rejects writable execution fields", () => {
 		const review = {
 			ticketUrl: null,

package/src/workbase/schemas.ts

@@ -46,7 +46,9 @@ const IsoTimestamp = NonEmptyString.pipe(
 
 const GitCommit = Schema.String.pipe(Schema.pattern(/^[a-f0-9]{40}$/))
 
-const DocumentRevision = Schema.String.pipe(Schema.pattern(/^[a-f0-9]{64}$/))
+export const DocumentRevision = Schema.String.pipe(
+	Schema.pattern(/^[a-f0-9]{64}$/),
+)
 
 export const ClaimRecord = Schema.Struct({
 	claimant: NonEmptyString,
@@ -155,6 +157,30 @@ const ExecutionUnit = {
 	completion: Schema.optional(CompletionRecord),
 }
 
+export const TaskPurpose = Schema.Literal("investigation", "implementation")
+
+export const TaskHandoffSource = Schema.Union(
+	Schema.Struct({
+		kind: Schema.Literal("task"),
+		taskId: EntityId,
+	}),
+	Schema.Struct({
+		kind: Schema.Literal("phase"),
+		taskId: EntityId,
+		phaseId: EntityId,
+	}),
+)
+
+export const TaskHandoff = Schema.Struct({
+	source: TaskHandoffSource,
+	sourceRevision: DocumentRevision,
+})
+
+const TaskMetadata = {
+	purpose: Schema.optional(TaskPurpose),
+	handoff: Schema.optional(TaskHandoff),
+}
+
 export const EpicFrontmatter = Schema.Struct({
 	ticketUrl: Url,
 	description: Description,
@@ -166,6 +192,7 @@ const SinglePhaseTaskFrontmatter = Schema.Struct({
 	ticketUrl: Schema.NullOr(Url),
 	description: Description,
 	epic: Schema.optional(EntityId),
+	...TaskMetadata,
 	...ExecutionUnit,
 })
 
@@ -173,6 +200,7 @@ const MultiPhaseTaskFrontmatter = Schema.Struct({
 	ticketUrl: Schema.NullOr(Url),
 	description: Description,
 	epic: Schema.optional(EntityId),
+	...TaskMetadata,
 	phases: Schema.Array(Dependency),
 })
 
@@ -221,6 +249,7 @@ const ReviewTaskFrontmatter = Schema.Struct({
 	ticketUrl: Schema.NullOr(Url),
 	description: Description,
 	epic: Schema.optional(EntityId),
+	...TaskMetadata,
 	review: ReviewRecord,
 	status: Schema.optionalWith(WorkStatus, { default: () => "open" as const }),
 	claim: Schema.optional(ClaimRecord),
@@ -254,6 +283,9 @@ export type PullRequestRecord = Schema.Schema.Type<typeof PullRequestRecord>
 export type ReviewSource = Schema.Schema.Type<typeof ReviewSource>
 export type ReviewRecord = Schema.Schema.Type<typeof ReviewRecord>
 export type CompletionRecord = Schema.Schema.Type<typeof CompletionRecord>
+export type TaskPurpose = Schema.Schema.Type<typeof TaskPurpose>
+export type TaskHandoffSource = Schema.Schema.Type<typeof TaskHandoffSource>
+export type TaskHandoff = Schema.Schema.Type<typeof TaskHandoff>
 export type EpicFrontmatter = Schema.Schema.Type<typeof EpicFrontmatter>
 export type TaskFrontmatter = Schema.Schema.Type<typeof TaskFrontmatter>
 export type PhaseFrontmatter = Schema.Schema.Type<typeof PhaseFrontmatter>