@markjaquith/agency 2.60.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
@@ -710,6 +728,38 @@ 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

package/cli-main.ts

@@ -498,6 +498,8 @@ const commands: Record<string, Command> = {
 					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"],

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.60.0",
+  "version": "2.61.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

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/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([

package/src/cli-parser.ts

@@ -89,6 +89,8 @@ const taskCreateOptions = {
 	"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 = {
@@ -367,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,
@@ -390,6 +392,7 @@ const commands = {
 					"reference",
 					"branch",
 					"base",
+					"purpose",
 					"multi-phase",
 					"work",
 					"auto",
@@ -411,6 +414,7 @@ const commands = {
 					"reference",
 					"branch",
 					"base",
+					"purpose",
 					"multi-phase",
 					"review",
 					"pull-request",
@@ -423,6 +427,25 @@ const commands = {
 				],
 				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: {
 				usage: "agency task list [filters] [--json]",
 				minArgs: 0,
@@ -1231,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

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(

package/src/commands/task.ts

@@ -53,6 +53,8 @@ interface TaskOptions extends BaseCommandOptions {
 	readonly contextBase?: string
 	readonly contextSlug?: string
 	readonly authoritativeSources?: readonly string[]
+	readonly purpose?: string
+	readonly sourcePhase?: string
 }
 
 export interface TaskInteraction {
@@ -197,6 +199,7 @@ export const task = (
 						repos: parseRepositoryReferences(options.references),
 						branch: multiPhase ? undefined : (options.branch ?? `task/${id}`),
 						base: multiPhase ? undefined : (options.base ?? "main"),
+						purpose: options.purpose as "investigation" | undefined,
 					},
 					cwd,
 				)
@@ -289,6 +292,7 @@ export const task = (
 								? undefined
 								: (options.branch ?? `task/${id}`),
 						base: multiPhase || review ? undefined : base,
+						purpose: options.purpose as "investigation" | undefined,
 					},
 					cwd,
 				)
@@ -321,6 +325,40 @@ export const task = (
 				)
 				return
 			}
+			case "handoff": {
+				const [sourceTaskId, id] = options.args
+				if (!sourceTaskId || !id) {
+					return yield* Effect.fail(
+						new Error("Source task ID and new task ID are required"),
+					)
+				}
+				if (!options.repo) {
+					return yield* Effect.fail(
+						new Error("Writable repository is required for task handoff"),
+					)
+				}
+				const output = yield* tasks.handoff(
+					{
+						sourceTaskId,
+						sourcePhaseId: options.sourcePhase,
+						id,
+						ticketUrl: options.ticketUrl?.trim() || null,
+						description: options.description?.trim() || undefined,
+						epic: options.epic,
+						repo: options.repo,
+						repos: parseRepositoryReferences(options.references),
+						branch: options.branch ?? `task/${id}`,
+						base: options.base ?? "main",
+					},
+					cwd,
+				)
+				log(
+					options.json
+						? JSON.stringify(output, null, 2)
+						: `Created implementation task '${id}' from '${output.source.selector}'`,
+				)
+				return
+			}
 			case "list": {
 				const records = yield* tasks.list(cwd)
 				const { taskRows } = yield* getWorkViews({
@@ -507,7 +545,7 @@ export const task = (
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Subcommand is required. Available: new, create, list, show, status, update, rename, move, dependency",
+						"Subcommand is required. Available: new, create, handoff, list, show, status, update, rename, move, dependency",
 					),
 				)
 		}
@@ -519,6 +557,7 @@ Usage: agency task <subcommand>
 Subcommands:
   new [id]              Create a task with guided input
   create <id>           Create a task without prompting
+  handoff <source> <id> Create implementation work from an investigation
   list                  List tasks
   show <id>             Show a task
   status <id> <status>  Set open, working, dropped, or explicit non-PR done
@@ -539,6 +578,8 @@ Non-PR completion options (status done only):
 Create options:
   --ticket-url <url>    External ticket URL (optional)
   --description <text>  Short description of the task
+	--purpose investigation
+	                       Generate an investigation-only task
   --epic <id>           Parent epic
   --repo <alias>        Writable repository
   --reference <alias>:<ref>
@@ -558,6 +599,11 @@ Create options:
   --work                Start work on the new task after creating it
   --auto                Pass --auto to work; requires --work
 
+Handoff options:
+  --source-phase <id>   Use a phase document as the source evidence
+  --repo <alias>        Writable implementation repository
+  --reference, --branch, --base, --ticket-url, --description, --epic
+
 Update options:
   --ticket-url <url> / --clear-ticket
   --description <text> / --clear-description

package/src/graph-schema.test.ts

@@ -27,6 +27,14 @@ describe("graph contract", () => {
 			readiness: { type: "null" },
 			aggregate: { type: "null" },
 		})
+		expect(jsonSchema.$defs.taskHandoff).toMatchObject({
+			additionalProperties: false,
+			required: ["source", "sourceRevision"],
+		})
+		expect(jsonSchema.$defs.singleTaskData.properties).toMatchObject({
+			purpose: { $ref: "#/$defs/taskPurpose" },
+			handoff: { $ref: "#/$defs/taskHandoff" },
+		})
 	})
 
 	test("streams records that reconstruct graph semantics", () => {

package/src/graph-schema.ts

@@ -5,6 +5,7 @@ import {
 	PullRequestRecord,
 	ClaimRecord,
 	ReviewRecord,
+	TaskHandoff,
 	TaskFrontmatter,
 	WorkStatus,
 } from "./workbase/schemas"
@@ -80,6 +81,10 @@ export const GraphExecutionData = Schema.Union(
 			phaseId: Schema.optional(Schema.String),
 			ticketUrl: Schema.optional(Schema.NullOr(Schema.String)),
 			epic: Schema.optional(Schema.String),
+			purpose: Schema.optional(
+				Schema.Literal("investigation", "implementation"),
+			),
+			handoff: Schema.optional(TaskHandoff),
 		}),
 	),
 	Schema.Struct({
@@ -87,6 +92,8 @@ export const GraphExecutionData = Schema.Union(
 		ticketUrl: Schema.NullOr(Schema.String),
 		description: Schema.optional(Schema.String),
 		epic: Schema.optional(Schema.String),
+		purpose: Schema.optional(Schema.Literal("investigation", "implementation")),
+		handoff: Schema.optional(TaskHandoff),
 		review: ReviewRecord,
 		status: WorkStatus,
 		claim: Schema.optional(ClaimRecord),

package/src/services/ArchiveService.test.ts

@@ -734,6 +734,11 @@ describe("ArchiveService", () => {
 							repo: "agency",
 							branch: "task/child",
 							base: "main",
+							purpose: "implementation",
+							handoff: {
+								source: { kind: "task", taskId: "investigation" },
+								sourceRevision: "a".repeat(64),
+							},
 						},
 						root,
 					),
@@ -787,6 +792,18 @@ describe("ArchiveService", () => {
 			),
 		)
 		expect(epic.data.tasks).toEqual([{ id: "child" }])
+		const restoredTask = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("child", root)),
+			),
+		)
+		expect(restoredTask.data).toMatchObject({
+			purpose: "implementation",
+			handoff: {
+				source: { kind: "task", taskId: "investigation" },
+				sourceRevision: "a".repeat(64),
+			},
+		})
 		const provenance = await Bun.file(
 			join(root, "tasks/child/.agency-lifecycle.json"),
 		).json()
@@ -1040,7 +1057,7 @@ describe("ArchiveService", () => {
 					),
 				),
 			),
-		).rejects.toThrow("is archived; restore it")
+		).rejects.toThrow("is archived; explicit creation requires a different ID")
 	})
 
 	test("does not remove worktrees when another lifecycle mutation holds the lock", async () => {

package/src/services/GraphMutationService.test.ts

@@ -326,6 +326,54 @@ describe("GraphMutationService", () => {
 		)
 	})
 
+	test("preserves historical handoff provenance across source and destination renames", async () => {
+		await runTestEffect(
+			Effect.gen(function* () {
+				const tasks = yield* TaskService
+				yield* tasks.create(
+					{
+						id: "investigation",
+						ticketUrl: null,
+						repo: "agency",
+						branch: "task/investigation",
+						base: "main",
+						purpose: "investigation",
+					},
+					root,
+				)
+				yield* tasks.handoff(
+					{
+						sourceTaskId: "investigation",
+						id: "implementation",
+						ticketUrl: null,
+						repo: "docs",
+						branch: "task/implementation",
+						base: "main",
+					},
+					root,
+				)
+				const before = yield* tasks.show("implementation", root)
+				const mutations = yield* GraphMutationService
+				yield* mutations.renameTask(
+					"investigation",
+					"investigation-renamed",
+					root,
+				)
+				yield* mutations.renameTask(
+					"implementation",
+					"implementation-renamed",
+					root,
+				)
+				const after = yield* tasks.show("implementation-renamed", root)
+				expect(after.data.handoff).toEqual(before.data.handoff)
+				expect(after.data.handoff?.source).toEqual({
+					kind: "task",
+					taskId: "investigation",
+				})
+			}),
+		)
+	})
+
 	test("moves task membership in both directions", async () => {
 		await runTestEffect(
 			Effect.gen(function* () {

package/src/services/IntegrationService.test.ts

@@ -420,6 +420,13 @@ describe("IntegrationService", () => {
 		expect(body).toContain("authority.writable.checkoutPath")
 		expect(body).toContain("Only `done` satisfies a dependency")
 		expect(body).toContain("Require explicit user intent")
+		expect(body).toContain(
+			"explicit request for a new, separate, or follow-up item",
+		)
+		expect(body).toContain("agency task handoff")
+		expect(body).toContain(
+			"Creation and handoff do not imply worktree preparation",
+		)
 		expect(body).toContain("changing repository")
 		expect(body).toMatch(
 			/archiving, restoring,\s+dropping, reopening, or completing work without a pull request/,
@@ -517,6 +524,9 @@ describe("IntegrationService", () => {
 		})
 		expect(config.agent.agency.model).toBeUndefined()
 		expect(config.agent.agency.permission).toBeUndefined()
+		expect(config.agent["agency-plan"].prompt).toContain(
+			"Explicit-new intent overrides reuse",
+		)
 		expect(config.agent.agency.hidden).toBeUndefined()
 		expect(config.agent.agency.steps).toBeUndefined()
 		expect(config.agent.agency.prompt).toContain(

package/src/services/LifecycleTransaction.ts

@@ -25,6 +25,18 @@ export interface TransactionStep {
 	readonly manualRecovery?: string
 }
 
+export const pathMustNotExistStep = (
+	root: string,
+	path: string,
+	message: string,
+): TransactionStep => ({
+	label: `verify ${relative(root, path)} is available`,
+	preflight: async () => {
+		if (await exists(path)) throw new Error(message)
+	},
+	apply: async () => {},
+})
+
 interface DocumentWrite {
 	readonly path: string
 	readonly content: string

package/src/services/PhaseService.ts

@@ -249,6 +249,8 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 								? { description: task.data.description }
 								: {}),
 							...(task.data.epic ? { epic: task.data.epic } : {}),
+							...(task.data.purpose ? { purpose: task.data.purpose } : {}),
+							...(task.data.handoff ? { handoff: task.data.handoff } : {}),
 							phases: [
 								{ id: firstPhaseId! },
 								{