@markjaquith/agency 2.59.0 → 2.60.0

package/README.md

@@ -684,6 +684,32 @@ The branch defaults to `task/<id>` and the base defaults to `main`.
 `task create` is always noninteractive and requires `--repo` for a single-phase
 task. Use it instead of `task new` in scripts and agent workflows.
 
+For deterministic callers, creation also accepts recalled context:
+
+```text
+agency task create <id>
+  --context-repo <alias> --context-base <base> --context-slug <id>
+  [--authoritative-source <absolute-path-or-http-url>...] --json
+```
+
+Recalled values are used instead of rediscovery but must agree with equivalent
+explicit flags. The preferred slug must equal the created ID, repository aliases
+are validated by normal task creation, and authoritative sources must be absolute
+paths or HTTP(S) URLs.
+
+Machine output adds fields without changing the version 1 protocol envelope. It
+includes `selector`, absolute `documentPath`, the document `revision`, full
+`validation`, normalized `recalledContext`, and `evidence`. Evidence version 1 is
+an auditable local payload containing the canonical workbase root, target and
+document identities, aggregate workbase revision, configuration revision,
+repository-mapping revision, kickoff-contract version, validity result, recalled
+context, and a digest over those fields. It is not a signature or an authority
+grant. A different workbase, target, document revision, document set,
+configuration, repository mapping, contract version, or payload digest
+invalidates reuse. Older creation output without evidence remains compatible;
+preflight simply validates again. The published machine schema is
+`schemas/agency-kickoff-v1.schema.json`.
+
 Create a multi-phase task container:
 
 ```text
@@ -892,7 +918,7 @@ until restored.
 
 ```text
 agency work [<directory> | --epic <epic-id>] [--runner <name>] [--auto] [--print-command]
-agency work prepare [target] [--dry-run] [--json]
+agency work prepare [target] [--evidence <json-or-path>] [--dry-run] [--json]
 agency worktree <list|inspect|prepare|remove|rebuild|repair>
 agency push [--json]
 agency pr create <task-id> [phase-id] [--draft] [--force] [--json]
@@ -912,9 +938,25 @@ their built-in presets. Launches are interactive and promptless by default; use
 `agency work prepare` resolves an execution unit and creates or reuses its
 writable and reference worktrees, or its single pinned review checkout, without
 launching an agent or changing status.
-Its JSON result includes document and checkout paths, resolved commits, actions,
-and Git operations. Use `--dry-run` to report planned fetch, branch, and worktree
-changes without applying them.
+Its JSON result includes the workspace, validation result, whether supplied
+evidence was `reused` or `refreshed` with stable reason strings, refreshed
+evidence, and a versioned `agency-kickoff-v1` orchestration plan. The plan has a
+deterministic idempotency key and ordered, retry-safe actions for worktree
+preflight/preparation, a background tab, side-by-side task document,
+`agency work . --auto`, and exactly one final `agency context <document> --json`.
+The evidence argument may be an evidence object, task-creation JSON, or a path to
+either. Use `--dry-run` to report planned fetch, branch, and worktree changes
+without applying them. Validation reuse never skips readiness, active-claim,
+repository, ownership, reference-drift, dirty-workspace, or worktree safety
+checks.
+
+The authoritative implementation locations for this contract are
+`src/commands/task.ts` (creation output),
+`src/workbase/kickoff-contract.ts` (evidence and orchestration schemas),
+`src/commands/work.ts` (launch preflight),
+`src/services/WorktreeService.ts` (workspace safety), and
+`src/workbase/AGENTS.md` (generated OpenCode guidance). These paths are the
+deterministic source-location fixture for compatible orchestrators.
 
 `agency worktree list` and `inspect` report each declared checkout's expected and
 registered path, branch, commit, Agency owner, dirtiness, and conflicts. `prepare`

package/cli-main.ts

@@ -494,6 +494,10 @@ const commands: Record<string, Command> = {
 					references: options.reference,
 					branch: options.branch,
 					base: options.base,
+					contextRepo: options["context-repo"],
+					contextBase: options["context-base"],
+					contextSlug: options["context-slug"],
+					authoritativeSources: options["authoritative-source"],
 					clearReferences: options["clear-references"],
 					prUrl: options["pr-url"],
 					clearPr: options["clear-pr"],
@@ -560,6 +564,7 @@ const commands: Record<string, Command> = {
 					cwd: options.cwd,
 					taskId: options.task,
 					phaseId: options.phase,
+					evidence: options.evidence,
 				}),
 			)
 		},

package/index.ts

@@ -2,3 +2,4 @@ export * from "./src/workbase/schemas"
 export * from "./src/protocol"
 export * from "./src/graph-schema"
 export * from "./src/readiness"
+export * from "./src/workbase/kickoff-contract"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.59.0",
+  "version": "2.60.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",
@@ -44,6 +44,9 @@
     "./schemas/agency-graph-v1.json": {
       "default": "./schemas/agency-graph-v1.schema.json"
     },
+    "./schemas/agency-kickoff-v1.json": {
+      "default": "./schemas/agency-kickoff-v1.schema.json"
+    },
     "./fixtures/protocol/success.json": {
       "default": "./fixtures/protocol/success.json"
     },

package/schemas/agency-kickoff-v1.schema.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/markjaquith/agency/schemas/agency-kickoff-v1.schema.json",
+  "title": "Agency kickoff contract v1",
+  "oneOf": [
+    { "$ref": "#/$defs/validationEvidence" },
+    { "$ref": "#/$defs/kickoffPlan" }
+  ],
+  "$defs": {
+    "recalledContext": {
+      "type": "object",
+      "required": ["preferredSlug", "authoritativeSources"],
+      "properties": {
+        "repo": { "type": "string", "minLength": 1 },
+        "base": { "type": "string", "minLength": 1 },
+        "preferredSlug": { "type": "string", "minLength": 1 },
+        "authoritativeSources": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      },
+      "additionalProperties": false
+    },
+    "validationEvidence": {
+      "type": "object",
+      "required": [
+        "version",
+        "workbaseRoot",
+        "target",
+        "documentPath",
+        "documentRevision",
+        "workbaseRevision",
+        "configRevision",
+        "repositoryMappingRevision",
+        "valid",
+        "recalledContext",
+        "digest"
+      ],
+      "properties": {
+        "version": { "const": 1 },
+        "workbaseRoot": { "type": "string" },
+        "target": { "type": "string" },
+        "documentPath": { "type": "string" },
+        "documentRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "workbaseRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "configRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "repositoryMappingRevision": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "valid": { "const": true },
+        "recalledContext": { "$ref": "#/$defs/recalledContext" },
+        "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      },
+      "additionalProperties": false
+    },
+    "kickoffPlan": {
+      "type": "object",
+      "required": [
+        "version",
+        "idempotencyKey",
+        "workbaseRoot",
+        "target",
+        "documentRevision",
+        "sourceLocations",
+        "taskDirectory",
+        "taskDocument",
+        "phaseDocument",
+        "preparedCheckout",
+        "orchestrator",
+        "steps",
+        "successFields"
+      ],
+      "properties": {
+        "version": { "const": 1 },
+        "idempotencyKey": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "workbaseRoot": { "type": "string" },
+        "target": { "type": "string" },
+        "documentRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "sourceLocations": { "type": "array", "items": { "type": "string" } },
+        "taskDirectory": { "type": "string" },
+        "taskDocument": { "type": "string" },
+        "phaseDocument": { "type": ["string", "null"] },
+        "preparedCheckout": { "type": ["string", "null"] },
+        "orchestrator": {
+          "type": "object",
+          "required": [
+            "capability",
+            "knownCurrentCommandsBypassDiscovery",
+            "fallback"
+          ],
+          "properties": {
+            "capability": { "const": "agency-kickoff-v1" },
+            "knownCurrentCommandsBypassDiscovery": { "const": true },
+            "fallback": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        "steps": {
+          "type": "array",
+          "minItems": 6,
+          "items": {
+            "type": "object",
+            "required": ["id"],
+            "properties": {
+              "id": { "type": "string" },
+              "argv": { "type": "array", "items": { "type": "string" } },
+              "cwd": { "type": "string" },
+              "action": { "type": "string" },
+              "path": { "type": "string" },
+              "retry": { "type": "string" },
+              "recovery": { "type": "string" },
+              "idempotencyKey": { "type": "string" },
+              "exactlyOnce": { "type": "boolean" }
+            },
+            "additionalProperties": false
+          }
+        },
+        "successFields": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/src/cli-parser.test.ts

@@ -809,7 +809,7 @@ describe("strict CLI parsing", () => {
 
 	test("rejects required-option omissions and explicit conflicts", () => {
 		expect(() => parseCli(["task", "create", "example"])).toThrow(
-			"--repo' is required",
+			"--repo' or '--context-repo' is required",
 		)
 		for (const option of ["repo", "reference", "branch", "base"] as const) {
 			const value = option === "reference" ? "other:main" : "value"

package/src/cli-parser.ts

@@ -85,6 +85,10 @@ const taskCreateOptions = {
 	review: { type: "string" },
 	"pull-request": { type: "string" },
 	ref: { type: "string" },
+	"context-repo": { type: "string" },
+	"context-base": { type: "string" },
+	"context-slug": { type: "string" },
+	"authoritative-source": { type: "string", multiple: true },
 } satisfies OptionConfig
 
 const phaseCreateOptions = {
@@ -396,7 +400,7 @@ const commands = {
 			},
 			create: {
 				usage:
-					"agency task create <id> (--repo <alias> | --multi-phase | --review <alias> (--pull-request <value> | --ref <remote-ref>)) [options]",
+					"agency task create <id> (--repo <alias> | --context-repo <alias> | --multi-phase | --review <alias> (--pull-request <value> | --ref <remote-ref>)) [options]",
 				minArgs: 1,
 				maxArgs: 1,
 				options: [
@@ -411,9 +415,13 @@ const commands = {
 					"review",
 					"pull-request",
 					"ref",
+					"context-repo",
+					"context-base",
+					"context-slug",
+					"authoritative-source",
 					"json",
 				],
-				repeatable: ["reference"],
+				repeatable: ["reference", "authoritative-source"],
 			},
 			list: {
 				usage: "agency task list [filters] [--json]",
@@ -873,6 +881,7 @@ const commands = {
 			opencode: { type: "boolean" },
 			claude: { type: "boolean" },
 			force: { type: "boolean" },
+			evidence: { type: "string" },
 		},
 		command: {
 			usage:
@@ -891,6 +900,7 @@ const commands = {
 				"opencode",
 				"claude",
 				"force",
+				"evidence",
 			],
 			conflicts: [
 				["opencode", "claude"],
@@ -1262,9 +1272,13 @@ function validateTaskCreate(
 				)
 			}
 		}
-	} else if (requireRepo && values.repo === undefined) {
+	} else if (
+		requireRepo &&
+		values.repo === undefined &&
+		values["context-repo"] === undefined
+	) {
 		throw usageError(
-			"Option '--repo' is required unless '--multi-phase' is used.",
+			"Option '--repo' or '--context-repo' is required unless '--multi-phase' is used.",
 			spec.usage,
 		)
 	}
@@ -1620,9 +1634,12 @@ export function parseCli(args: readonly string[]): ParsedCli {
 				spec.usage,
 			)
 		}
-		if (!preparing && (parsed.values.json || parsed.values["dry-run"])) {
+		if (
+			!preparing &&
+			(parsed.values.json || parsed.values["dry-run"] || parsed.values.evidence)
+		) {
 			throw usageError(
-				"Options '--json' and '--dry-run' are only valid with 'agency work prepare'.",
+				"Options '--json', '--dry-run', and '--evidence' are only valid with 'agency work prepare'.",
 				spec.usage,
 			)
 		}

package/src/commands/task.test.ts

@@ -2,7 +2,12 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
 import { mkdir } from "node:fs/promises"
 import { join } from "node:path"
-import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
 import { task, type TaskInteraction } from "./task"
 
 describe("task creation input", () => {
@@ -125,6 +130,77 @@ describe("task creation input", () => {
 		expect(content).toContain("base: main")
 	})
 
+	test("returns revision-bound validation evidence and normalized recalled context", async () => {
+		const [output] = await captureLogs(() =>
+			runTestEffect(
+				task({
+					subcommand: "create",
+					args: ["scripted-context"],
+					contextRepo: "agency",
+					contextBase: "main",
+					contextSlug: "scripted-context",
+					authoritativeSources: [
+						"https://example.com/spec",
+						join(root, "SOURCE.md"),
+					],
+					cwd: root,
+					json: true,
+				}),
+			),
+		)
+		const result = JSON.parse(output!)
+		expect(result.selector).toBe("execution-unit:task/scripted-context")
+		expect(result.documentPath).toBe(
+			join(root, "tasks/scripted-context/TASK.md"),
+		)
+		expect(result.validation.valid).toBe(true)
+		expect(result.evidence).toEqual(
+			expect.objectContaining({
+				version: 1,
+				target: "execution-unit:task/scripted-context",
+				documentRevision: result.revision,
+				valid: true,
+				digest: expect.any(String),
+			}),
+		)
+		expect(result.recalledContext).toEqual({
+			repo: "agency",
+			base: "main",
+			preferredSlug: "scripted-context",
+			authoritativeSources: [
+				join(root, "SOURCE.md"),
+				"https://example.com/spec",
+			],
+		})
+	})
+
+	test("rejects stale or conflicting recalled context", async () => {
+		await expect(
+			runTestEffect(
+				task({
+					subcommand: "create",
+					args: ["conflict"],
+					repo: "agency",
+					contextRepo: "other",
+					cwd: root,
+					silent: true,
+				}),
+			),
+		).rejects.toThrow("conflicts with --repo")
+		await expect(
+			runTestEffect(
+				task({
+					subcommand: "create",
+					args: ["conflict"],
+					contextRepo: "agency",
+					contextSlug: "stale-slug",
+					cwd: root,
+					silent: true,
+				}),
+			),
+		).rejects.toThrow("conflicts with task ID")
+	})
+
 	test("never prompts when scripted creation is incomplete", async () => {
 		const interaction: TaskInteraction = {
 			text: () => Effect.fail(new Error("unexpected text prompt")),

package/src/commands/task.ts

@@ -12,6 +12,10 @@ import { getWorkViews } from "../work-view"
 import { GraphMutationService } from "../services/GraphMutationService"
 import { work as startWork, type StartWork } from "./work"
 import { ReviewService } from "../services/ReviewService"
+import {
+	buildValidationEvidence,
+	normalizeRecalledContext,
+} from "../workbase/kickoff-contract"
 
 interface TaskOptions extends BaseCommandOptions {
 	readonly subcommand?: string
@@ -45,6 +49,10 @@ interface TaskOptions extends BaseCommandOptions {
 	readonly noPullRequest?: boolean
 	readonly summary?: string
 	readonly evidenceUrl?: string
+	readonly contextRepo?: string
+	readonly contextBase?: string
+	readonly contextSlug?: string
+	readonly authoritativeSources?: readonly string[]
 }
 
 export interface TaskInteraction {
@@ -216,7 +224,43 @@ export const task = (
 					return yield* Effect.fail(new Error("Task ID is required"))
 				}
 				const multiPhase = options.multiPhase ?? false
-				if (!multiPhase && !options.repo && !options.review) {
+				if (
+					options.repo &&
+					options.contextRepo &&
+					options.repo !== options.contextRepo
+				) {
+					return yield* Effect.fail(
+						new Error(
+							`Recalled repository '${options.contextRepo}' conflicts with --repo '${options.repo}'`,
+						),
+					)
+				}
+				if (
+					options.base &&
+					options.contextBase &&
+					options.base !== options.contextBase
+				) {
+					return yield* Effect.fail(
+						new Error(
+							`Recalled base '${options.contextBase}' conflicts with --base '${options.base}'`,
+						),
+					)
+				}
+				const repo = options.repo ?? options.contextRepo
+				const base = options.base ?? options.contextBase ?? "main"
+				const recalledContext = yield* Effect.try({
+					try: () =>
+						normalizeRecalledContext({
+							id,
+							repo,
+							base: multiPhase || options.review ? undefined : base,
+							preferredSlug: options.contextSlug,
+							authoritativeSources: options.authoritativeSources,
+						}),
+					catch: (cause) =>
+						cause instanceof Error ? cause : new Error(String(cause)),
+				})
+				if (!multiPhase && !repo && !options.review) {
 					return yield* Effect.fail(
 						new Error("Writable repository is required for task create"),
 					)
@@ -236,7 +280,7 @@ export const task = (
 						epic: options.epic,
 						multiPhase,
 						review,
-						repo: options.repo,
+						repo: review ? undefined : repo,
 						repos: review
 							? undefined
 							: parseRepositoryReferences(options.references),
@@ -244,11 +288,32 @@ export const task = (
 							multiPhase || review
 								? undefined
 								: (options.branch ?? `task/${id}`),
-						base: multiPhase || review ? undefined : (options.base ?? "main"),
+						base: multiPhase || review ? undefined : base,
 					},
 					cwd,
 				)
-				const { content: _, ...output } = record
+				const validation = yield* workbase.validate(cwd)
+				const selector = multiPhase
+					? `task:${record.id}`
+					: `execution-unit:task/${record.id}`
+				const evidence = validation.valid
+					? yield* buildValidationEvidence({
+							startPath: cwd,
+							target: selector,
+							documentPath: record.path,
+							documentRevision: record.revision,
+							recalledContext,
+						})
+					: null
+				const { content: _, ...created } = record
+				const output = {
+					...created,
+					selector,
+					documentPath: record.path,
+					validation,
+					evidence,
+					recalledContext,
+				}
 				log(
 					options.json
 						? JSON.stringify(output, null, 2)
@@ -480,6 +545,11 @@ Create options:
                         Read-only repository reference; repeatable
   --branch <name>       Working branch (default: task/<id>)
   --base <name>         Base branch (default: main)
+	--context-repo <alias> Recalled repository; must agree with --repo
+	--context-base <name>  Recalled base; must agree with --base
+	--context-slug <id>    Recalled preferred slug; must equal the task ID
+	--authoritative-source <path-or-url>
+	                       Authoritative input location; repeatable
 	--multi-phase         Create a task container for phases
 	--review <alias>      Create a pinned read-only review task
 	--pull-request <url-or-number>
@@ -497,8 +567,8 @@ Update options:
   --base <name>         Replace the base branch
   --pr-url <url> / --clear-pr
 
-Task creation is noninteractive. Single-phase tasks require --repo; use
---multi-phase instead for a task container. Guided input is available only
+Task creation is noninteractive. Single-phase tasks require --repo or
+--context-repo; use --multi-phase instead for a task container. Guided input is available only
 through task new, which fails when --no-input is set or no TTY is available.
 
 Options:

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 () => {