@markjaquith/agency 2.59.0 → 2.61.0

package/README.md

@@ -427,6 +427,24 @@ status: open
 ---
 ```
 
+Tasks may also record a purpose and one-way investigation handoff provenance:
+
+```yaml
+purpose: implementation
+handoff:
+  source:
+    kind: phase
+    taskId: investigate-checkout
+    phaseId: reproduce
+  sourceRevision: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+```
+
+The source revision is historical evidence, not a readiness dependency or a
+claim that the source still has that content. Source rename, archive, restore,
+or later edits do not rewrite it. Destination rename, archive, and restore
+preserve it unchanged. Task show, context, and graph JSON expose the record as
+task metadata; graph output does not add an edge for it.
+
 ### Multi-Phase Task
 
 ```yaml
@@ -684,6 +702,64 @@ 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 investigation-only work with the existing task architecture:
+
+```text
+agency task create <id> --purpose investigation --repo <alias> [options]
+```
+
+This records `purpose: investigation` and generates explicit Investigation
+Boundary, Evidence, Findings, Recommendation, Implementation Handoff, and
+Important Decisions sections. A no-change recommendation is a valid result;
+implementation does not belong in the investigation task merely because that
+task has execution authority.
+
+Create a distinct implementation task from an investigation task or phase:
+
+```text
+agency task handoff <investigation-task> <new-task> --repo <alias> [options] --json
+agency task handoff <investigation-task> <new-task> --source-phase <phase> --repo <alias> [options] --json
+```
+
+The destination ID must be new across active and archived work; Agency never
+restores, reopens, renames, or reuses a matching item. Explicit requests for a
+new, separate, or follow-up item always override reuse, even when the subject or
+suggested ID matches existing work. The transaction writes only the destination
+task and any requested epic backlink, while revision-checking the source.
+
+JSON returns the exact destination selector, directory and document path,
+branch/base and revision; source selector, document path and captured revision;
+the validation report; and the later `worktree prepare` target and command.
+Handoff creation does not prepare a worktree, change status, launch an agent, or
+perform UI actions. Run `agency context <new-task> --json` to verify authority,
+and prepare or launch only when separately requested.
+
 Create a multi-phase task container:
 
 ```text
@@ -892,7 +968,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 +988,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,12 @@ 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"],
+					purpose: options.purpose,
+					sourcePhase: options["source-phase"],
 					clearReferences: options["clear-references"],
 					prUrl: options["pr-url"],
 					clearPr: options["clear-pr"],
@@ -560,6 +566,7 @@ const commands: Record<string, Command> = {
 					cwd: options.cwd,
 					taskId: options.task,
 					phaseId: options.phase,
+					evidence: options.evidence,
 				}),
 			)
 		},

package/fixtures/protocol/orchestration-recipes.json

@@ -3,6 +3,25 @@
   ["worktree", "inspect", "checkout", "ui", "--json"],
   ["next", "--json"],
   ["graph", "--ready", "--json"],
+  [
+    "task",
+    "create",
+    "investigate-checkout",
+    "--purpose",
+    "investigation",
+    "--repo",
+    "agency",
+    "--json"
+  ],
+  [
+    "task",
+    "handoff",
+    "investigate-checkout",
+    "implement-checkout",
+    "--repo",
+    "agency",
+    "--json"
+  ],
   [
     "claim",
     "checkout",

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.61.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-graph-v1.schema.json

@@ -333,6 +333,8 @@
         "ticketUrl": { "type": ["string", "null"] },
         "description": { "type": "string" },
         "epic": { "type": "string" },
+        "purpose": { "$ref": "#/$defs/taskPurpose" },
+        "handoff": { "$ref": "#/$defs/taskHandoff" },
         "repo": { "type": "string" },
         "repos": {
           "type": "array",
@@ -354,6 +356,8 @@
         "ticketUrl": { "type": ["string", "null"] },
         "description": { "type": "string" },
         "epic": { "type": "string" },
+        "purpose": { "$ref": "#/$defs/taskPurpose" },
+        "handoff": { "$ref": "#/$defs/taskHandoff" },
         "phases": {
           "type": "array",
           "items": { "$ref": "#/$defs/dependency" }
@@ -416,6 +420,8 @@
         "ticketUrl": { "type": ["string", "null"] },
         "description": { "type": "string" },
         "epic": { "type": "string" },
+        "purpose": { "$ref": "#/$defs/taskPurpose" },
+        "handoff": { "$ref": "#/$defs/taskHandoff" },
         "review": { "$ref": "#/$defs/reviewRecord" },
         "status": { "$ref": "#/$defs/status" },
         "claim": { "$ref": "#/$defs/claim" },
@@ -452,6 +458,8 @@
             "phaseId": { "type": "string" },
             "ticketUrl": { "type": ["string", "null"] },
             "epic": { "type": "string" },
+            "purpose": { "$ref": "#/$defs/taskPurpose" },
+            "handoff": { "$ref": "#/$defs/taskHandoff" },
             "description": { "type": "string" },
             "repo": { "type": "string" },
             "repos": {
@@ -474,6 +482,8 @@
             "ticketUrl": { "type": ["string", "null"] },
             "description": { "type": "string" },
             "epic": { "type": "string" },
+            "purpose": { "$ref": "#/$defs/taskPurpose" },
+            "handoff": { "$ref": "#/$defs/taskHandoff" },
             "review": { "$ref": "#/$defs/reviewRecord" },
             "status": { "$ref": "#/$defs/status" },
             "claim": { "$ref": "#/$defs/claim" }
@@ -481,6 +491,49 @@
         }
       ]
     },
+    "taskPurpose": {
+      "enum": ["investigation", "implementation"]
+    },
+    "taskHandoff": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "sourceRevision"],
+      "properties": {
+        "source": {
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["kind", "taskId"],
+              "properties": {
+                "kind": { "const": "task" },
+                "taskId": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$"
+                }
+              }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["kind", "taskId", "phaseId"],
+              "properties": {
+                "kind": { "const": "phase" },
+                "taskId": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$"
+                },
+                "phaseId": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$"
+                }
+              }
+            }
+          ]
+        },
+        "sourceRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      }
+    },
     "claim": {
       "type": "object",
       "additionalProperties": false,

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

@@ -759,10 +759,58 @@ describe("strict CLI parsing", () => {
 		)
 		expectUsageError(
 			["task", "crate"],
-			"agency task <new|create|list|show|status|update|rename|move|dependency>",
+			"agency task <new|create|handoff|list|show|status|update|rename|move|dependency>",
 		)
 	})
 
+	test("parses investigation creation and explicit handoff commands", () => {
+		expect(
+			parseCli([
+				"task",
+				"create",
+				"investigate",
+				"--purpose",
+				"investigation",
+				"--repo",
+				"agency",
+			]),
+		).toMatchObject({
+			args: ["create", "investigate"],
+			values: { purpose: "investigation", repo: ["agency"] },
+		})
+		expect(
+			parseCli([
+				"task",
+				"handoff",
+				"investigate",
+				"implement",
+				"--source-phase",
+				"evidence",
+				"--repo",
+				"agency",
+				"--json",
+			]),
+		).toMatchObject({
+			args: ["handoff", "investigate", "implement"],
+			values: {
+				"source-phase": "evidence",
+				repo: ["agency"],
+				json: true,
+			},
+		})
+		expect(() =>
+			parseCli([
+				"task",
+				"create",
+				"investigate",
+				"--purpose",
+				"unknown",
+				"--repo",
+				"agency",
+			]),
+		).toThrow("Invalid '--purpose' value")
+	})
+
 	test("parses graph mutation commands and rejects unsafe ambiguity", () => {
 		expect(
 			parseCli([
@@ -809,7 +857,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,12 @@ 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 },
+	purpose: { type: "string" },
+	"source-phase": { type: "string" },
 } satisfies OptionConfig
 
 const phaseCreateOptions = {
@@ -363,7 +369,7 @@ const commands = {
 	},
 	task: {
 		usage:
-			"agency task <new|create|list|show|status|update|rename|move|dependency>",
+			"agency task <new|create|handoff|list|show|status|update|rename|move|dependency>",
 		options: {
 			...taskCreateOptions,
 			...newWorkOptions,
@@ -386,6 +392,7 @@ const commands = {
 					"reference",
 					"branch",
 					"base",
+					"purpose",
 					"multi-phase",
 					"work",
 					"auto",
@@ -396,7 +403,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: [
@@ -407,12 +414,36 @@ const commands = {
 					"reference",
 					"branch",
 					"base",
+					"purpose",
 					"multi-phase",
 					"review",
 					"pull-request",
 					"ref",
+					"context-repo",
+					"context-base",
+					"context-slug",
+					"authoritative-source",
 					"json",
 				],
+				repeatable: ["reference", "authoritative-source"],
+			},
+			handoff: {
+				usage:
+					"agency task handoff <source-task-id> <new-task-id> --repo <alias> [--source-phase <phase-id>] [options]",
+				minArgs: 2,
+				maxArgs: 2,
+				options: [
+					"ticket-url",
+					"description",
+					"epic",
+					"repo",
+					"reference",
+					"branch",
+					"base",
+					"source-phase",
+					"json",
+				],
+				required: ["repo"],
 				repeatable: ["reference"],
 			},
 			list: {
@@ -873,6 +904,7 @@ const commands = {
 			opencode: { type: "boolean" },
 			claude: { type: "boolean" },
 			force: { type: "boolean" },
+			evidence: { type: "string" },
 		},
 		command: {
 			usage:
@@ -891,6 +923,7 @@ const commands = {
 				"opencode",
 				"claude",
 				"force",
+				"evidence",
 			],
 			conflicts: [
 				["opencode", "claude"],
@@ -1221,6 +1254,12 @@ function validateTaskCreate(
 	spec: LeafCommand,
 	requireRepo: boolean,
 ) {
+	if (values.purpose !== undefined && values.purpose !== "investigation") {
+		throw usageError(
+			`Invalid '--purpose' value '${String(values.purpose)}'. Expected: investigation.`,
+			spec.usage,
+		)
+	}
 	const review = values.review !== undefined
 	const pullRequest = values["pull-request"] !== undefined
 	const ref = values.ref !== undefined
@@ -1262,9 +1301,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 +1663,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-phase.test.ts

@@ -86,6 +86,55 @@ describe("task and phase command JSON output", () => {
 		})
 	})
 
+	test("returns complete handoff JSON without preparing work", async () => {
+		await runTestEffect(
+			task({
+				subcommand: "create",
+				args: ["investigate"],
+				repo: "agency",
+				purpose: "investigation",
+				cwd: root,
+				silent: true,
+			}),
+		)
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				task({
+					subcommand: "handoff",
+					args: ["investigate", "implement"],
+					repo: "agency",
+					cwd: root,
+					json: true,
+				}),
+			),
+		)
+		const output = JSON.parse(logs[0]!)
+		expect(output).toMatchObject({
+			task: {
+				id: "implement",
+				selector: "task/implement",
+				directory: join(root, "tasks/implement"),
+				documentPath: join(root, "tasks/implement/TASK.md"),
+				branch: "task/implement",
+				base: "main",
+			},
+			source: {
+				selector: "task/investigate",
+				documentPath: join(root, "tasks/investigate/TASK.md"),
+			},
+			validation: { valid: true },
+			worktreePrepare: {
+				target: "task/implement",
+				command: ["agency", "worktree", "prepare", "implement"],
+			},
+		})
+		expect(output.task.revision).toMatch(/^[a-f0-9]{64}$/)
+		expect(output.source.revision).toMatch(/^[a-f0-9]{64}$/)
+		expect(await Bun.file(join(root, "tasks/implement/code")).exists()).toBe(
+			false,
+		)
+	})
+
 	test("lists and shows phase metadata without Markdown content", async () => {
 		const listLogs = await captureLogs(() =>
 			runTestEffect(