@markjaquith/agency 2.59.0 → 2.60.0

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/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/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
 
@@ -64,6 +80,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/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,
+		)
+	})
+})