@markjaquith/agency 2.20.0 → 2.22.0

package/README.md

@@ -408,6 +408,9 @@ agency epic create <id> --ticket-url <url> [--description <text>] [--json]
   --repo <alias>:<ref> [--repo <alias>:<ref>...]
 agency epic list [filters] [--json]
 agency epic show <id> [--json]
+agency epic update <id> [--ticket-url <url>] [--description <text>]
+  [--clear-description] [--repo <alias>:<ref>...] [--json]
+agency epic rename <id> <new-id> [--json]
 ```
 
 Creating a task with `--epic <id>` adds the task to the epic and writes the task
@@ -463,8 +466,18 @@ Inspect tasks:
 agency task list [filters] [--json]
 agency task show <id> [--json]
 agency task status <id> <open|done|dropped> [--json]
+agency task update <id> [metadata options] [--json]
+agency task rename <id> <new-id> [--json]
+agency task move <id> (--epic <epic-id> | --no-epic) [--json]
+agency task dependency <add|remove> <task-id> <dependency-id> [--json]
 ```
 
+Task updates can replace or clear descriptions, tickets, repository references,
+and pull request URLs, or replace writable repository, branch, and base metadata.
+Execution metadata changes refuse to run while code is materialized. Moving a
+task with scoped incoming or outgoing dependencies also refuses until those
+dependencies are removed.
+
 To add a phase to an existing single-phase task, name the phase that will own
 the task's current execution fields with `--first-phase`:
 
@@ -490,8 +503,18 @@ agency phase create <task-id> <phase-id>
 agency phase list <task-id> [filters] [--json]
 agency phase show <task-id> <phase-id> [--json]
 agency phase status <task-id> <phase-id> <open|done|dropped> [--json]
+agency phase update <task-id> <phase-id> [metadata options] [--json]
+agency phase rename <task-id> <phase-id> <new-id> [--json]
+agency phase dependency <add|remove> <task-id> <phase-id> <dependency-id>
+  [--json]
 ```
 
+Dependency additions append without reordering existing declarations and reject
+unknown IDs, self-dependencies, and cycles. Rename operations update structured
+references as one rollback-capable mutation and refuse when a materialized
+worktree would make the directory move unsafe. Mutation JSON includes changed
+paths and the focused validation scope.
+
 Single-phase tasks and phases store status in YAML. New execution units start
 `open`, and `agency work` marks the selected execution unit `working` immediately
 before launch. Use claims for coordinated ownership and the status subcommands

package/cli.ts

@@ -38,6 +38,7 @@ import { GraphService } from "./src/services/GraphService"
 import { ClaimService } from "./src/services/ClaimService"
 import { SyncService } from "./src/services/SyncService"
 import { ReadinessService } from "./src/services/ReadinessService"
+import { GraphMutationService } from "./src/services/GraphMutationService"
 import {
 	claimCommand,
 	claimHelp,
@@ -68,6 +69,7 @@ const CliLayer = Layer.mergeAll(
 	ClaimService.Default,
 	SyncService.Default,
 	ReadinessService.Default,
+	GraphMutationService.Default,
 )
 
 /**
@@ -235,6 +237,7 @@ const commands: Record<string, Command> = {
 					args: args.slice(1),
 					ticketUrl: options["ticket-url"],
 					description: options.description,
+					clearDescription: options["clear-description"],
 					repos: options.repo,
 					json: options.json,
 					statuses: options.status,
@@ -278,10 +281,14 @@ const commands: Record<string, Command> = {
 					subcommand: args[0],
 					args: args.slice(1),
 					description: options.description,
+					clearDescription: options["clear-description"],
 					repo: options.repo?.[0],
 					references: options.reference,
 					branch: options.branch,
 					base: options.base,
+					clearReferences: options["clear-references"],
+					prUrl: options["pr-url"],
+					clearPr: options["clear-pr"],
 					dependsOn: options["depends-on"],
 					firstPhase: options["first-phase"],
 					json: options.json,
@@ -381,12 +388,18 @@ const commands: Record<string, Command> = {
 					subcommand: args[0],
 					args: args.slice(1),
 					ticketUrl: options["ticket-url"],
+					clearTicket: options["clear-ticket"],
 					description: options.description,
+					clearDescription: options["clear-description"],
 					epic: options.epic,
 					repo: options.repo?.[0],
 					references: options.reference,
 					branch: options.branch,
 					base: options.base,
+					clearReferences: options["clear-references"],
+					prUrl: options["pr-url"],
+					clearPr: options["clear-pr"],
+					noEpic: options["no-epic"],
 					multiPhase: options["multi-phase"],
 					json: options.json,
 					statuses: options.status,

package/package.json

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

package/src/cli-parser.test.ts

@@ -387,7 +387,51 @@ describe("strict CLI parsing", () => {
 		)
 		expectUsageError(
 			["task", "crate"],
-			"agency task <new|create|list|show|status>",
+			"agency task <new|create|list|show|status|update|rename|move|dependency>",
+		)
+	})
+
+	test("parses graph mutation commands and rejects unsafe ambiguity", () => {
+		expect(
+			parseCli([
+				"task",
+				"update",
+				"example",
+				"--description",
+				"Revised",
+				"--reference",
+				"docs:main",
+				"--reference",
+				"api:main",
+				"--clear-pr",
+			]),
+		).toMatchObject({
+			args: ["update", "example"],
+			values: {
+				description: "Revised",
+				reference: ["docs:main", "api:main"],
+				"clear-pr": true,
+			},
+		})
+		expect(
+			parseCli(["task", "move", "example", "--no-epic"]).values,
+		).toMatchObject({
+			"no-epic": true,
+		})
+		expect(parseCli(["phase", "rename", "task", "old", "new"]).args).toEqual([
+			"rename",
+			"task",
+			"old",
+			"new",
+		])
+		expect(() => parseCli(["task", "update", "example"])).toThrow(
+			"At least one update option",
+		)
+		expect(() =>
+			parseCli(["task", "move", "example", "--epic", "one", "--no-epic"]),
+		).toThrow("cannot be combined")
+		expect(() => parseCli(["task", "dependency", "replace", "a", "b"])).toThrow(
+			"must be 'add' or 'remove'",
 		)
 	})
 

package/src/cli-parser.ts

@@ -90,6 +90,15 @@ const phaseCreateOptions = {
 	"first-phase": { type: "string" },
 } satisfies OptionConfig
 
+const mutationOptions = {
+	"clear-description": { type: "boolean" },
+	"clear-ticket": { type: "boolean" },
+	"clear-references": { type: "boolean" },
+	"pr-url": { type: "string" },
+	"clear-pr": { type: "boolean" },
+	"no-epic": { type: "boolean" },
+} satisfies OptionConfig
+
 const claimOptions = {
 	...outputOptions,
 	claimant: { type: "string" },
@@ -200,8 +209,13 @@ const commands = {
 		},
 	},
 	epic: {
-		usage: "agency epic <create|list|show>",
-		options: { ...createOptions, ...viewOptions, epic: { type: "string" } },
+		usage: "agency epic <create|list|show|update|rename>",
+		options: {
+			...createOptions,
+			...viewOptions,
+			...mutationOptions,
+			epic: { type: "string" },
+		},
 		subcommands: {
 			create: {
 				usage:
@@ -226,11 +240,38 @@ const commands = {
 				maxArgs: 1,
 				options: ["json", "epic"],
 			},
+			update: {
+				usage: "agency epic update <id> [options] [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: [
+					"description",
+					"clear-description",
+					"ticket-url",
+					"repo",
+					"json",
+				],
+				repeatable: ["repo"],
+				conflicts: [["description", "clear-description"]],
+			},
+			rename: {
+				usage: "agency epic rename <id> <new-id> [--json]",
+				minArgs: 2,
+				maxArgs: 2,
+				options: ["json"],
+			},
 		},
 	},
 	task: {
-		usage: "agency task <new|create|list|show|status>",
-		options: { ...taskCreateOptions, ...viewOptions, task: { type: "string" } },
+		usage:
+			"agency task <new|create|list|show|status|update|rename|move|dependency>",
+		options: {
+			...taskCreateOptions,
+			...viewOptions,
+			...mutationOptions,
+			"pr-url": { type: "string" },
+			task: { type: "string" },
+		},
 		subcommands: {
 			new: {
 				usage: "agency task new [id] [options]",
@@ -287,13 +328,61 @@ const commands = {
 				maxArgs: 2,
 				options: ["json", "task"],
 			},
+			update: {
+				usage: "agency task update <id> [options] [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: [
+					"ticket-url",
+					"clear-ticket",
+					"description",
+					"clear-description",
+					"repo",
+					"reference",
+					"clear-references",
+					"branch",
+					"base",
+					"pr-url",
+					"clear-pr",
+					"json",
+				],
+				repeatable: ["reference"],
+				conflicts: [
+					["ticket-url", "clear-ticket"],
+					["description", "clear-description"],
+					["reference", "clear-references"],
+					["pr-url", "clear-pr"],
+				],
+			},
+			rename: {
+				usage: "agency task rename <id> <new-id> [--json]",
+				minArgs: 2,
+				maxArgs: 2,
+				options: ["json"],
+			},
+			move: {
+				usage: "agency task move <id> (--epic <id> | --no-epic) [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["epic", "no-epic", "json"],
+				conflicts: [["epic", "no-epic"]],
+			},
+			dependency: {
+				usage:
+					"agency task dependency <add|remove> <task-id> <dependency-id> [--json]",
+				minArgs: 3,
+				maxArgs: 3,
+				options: ["json"],
+			},
 		},
 	},
 	phase: {
-		usage: "agency phase <create|list|show|status>",
+		usage: "agency phase <create|list|show|status|update|rename|dependency>",
 		options: {
 			...phaseCreateOptions,
 			...viewOptions,
+			...mutationOptions,
+			"pr-url": { type: "string" },
 			task: { type: "string" },
 			phase: { type: "string" },
 		},
@@ -338,6 +427,42 @@ const commands = {
 				maxArgs: 3,
 				options: ["json", "task", "phase"],
 			},
+			update: {
+				usage: "agency phase update <task-id> <phase-id> [options] [--json]",
+				minArgs: 2,
+				maxArgs: 2,
+				options: [
+					"description",
+					"clear-description",
+					"repo",
+					"reference",
+					"clear-references",
+					"branch",
+					"base",
+					"pr-url",
+					"clear-pr",
+					"json",
+				],
+				repeatable: ["reference"],
+				conflicts: [
+					["description", "clear-description"],
+					["reference", "clear-references"],
+					["pr-url", "clear-pr"],
+				],
+			},
+			rename: {
+				usage: "agency phase rename <task-id> <phase-id> <new-id> [--json]",
+				minArgs: 3,
+				maxArgs: 3,
+				options: ["json"],
+			},
+			dependency: {
+				usage:
+					"agency phase dependency <add|remove> <task-id> <phase-id> <dependency-id> [--json]",
+				minArgs: 4,
+				maxArgs: 4,
+				options: ["json"],
+			},
 		},
 	},
 	claim: {
@@ -977,6 +1102,34 @@ export function parseCli(args: readonly string[]): ParsedCli {
 	) {
 		validateTaskCreate(parsed.values, spec, subcommand === "create")
 	}
+	if (["task", "phase"].includes(commandName) && subcommand === "dependency") {
+		if (!["add", "remove"].includes(commandPositionals[0] ?? "")) {
+			throw usageError(
+				"Dependency operation must be 'add' or 'remove'.",
+				spec.usage,
+			)
+		}
+	}
+	if (commandName === "task" && subcommand === "move") {
+		if (
+			parsed.values.epic === undefined &&
+			parsed.values["no-epic"] === undefined
+		) {
+			throw usageError(
+				"One of '--epic' or '--no-epic' is required.",
+				spec.usage,
+			)
+		}
+	}
+	if (
+		["epic", "task", "phase"].includes(commandName) &&
+		subcommand === "update"
+	) {
+		const mutationNames = (spec.options ?? []).filter((name) => name !== "json")
+		if (!mutationNames.some((name) => parsed.values[name] !== undefined)) {
+			throw usageError("At least one update option is required.", spec.usage)
+		}
+	}
 	if (commandName === "graph") {
 		validateGraphOptions(parsed.values, spec)
 	}

package/src/cli.test.ts

@@ -166,6 +166,68 @@ describe("CLI", () => {
 		expect(finished.claim).toMatchObject({ state: "finished", outcome: "done" })
 	})
 
+	test("routes graph mutations through structured output", async () => {
+		const root = await createTempDir()
+		tempDirs.push(root)
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		await mkdir(join(root, "repos", "agency"), { recursive: true })
+		parseJson(
+			await runCli(
+				[
+					"epic",
+					"create",
+					"delivery",
+					"--ticket-url",
+					"https://example.com/delivery",
+					"--repo",
+					"agency:main",
+					"--json",
+				],
+				root,
+			),
+		)
+		for (const id of ["first", "second"]) {
+			parseJson(
+				await runCli(
+					[
+						"task",
+						"create",
+						id,
+						"--repo",
+						"agency",
+						"--epic",
+						"delivery",
+						"--json",
+					],
+					root,
+				),
+			)
+		}
+
+		const updated = parseJson(
+			await runCli(
+				["task", "update", "second", "--description", "Revised", "--json"],
+				root,
+			),
+		)
+		expect(updated).toMatchObject({
+			operation: "task.update",
+			entity: { kind: "task", id: "second" },
+			validation: { valid: true, scope: ["tasks/second/TASK.md"] },
+		})
+
+		const dependency = parseJson(
+			await runCli(
+				["task", "dependency", "add", "second", "first", "--json"],
+				root,
+			),
+		)
+		expect(dependency).toMatchObject({
+			operation: "task.dependency.add",
+			changedPaths: ["epics/delivery/EPIC.md"],
+		})
+	})
+
 	test("emits one versioned error envelope for usage and command failures", async () => {
 		const usage = await runCli(["unknown", "--json"])
 		expect(usage.exitCode).toBe(1)

package/src/commands/epic.ts

@@ -5,12 +5,14 @@ import { createLoggers } from "../utils/effect"
 import { formatTable } from "../utils/table"
 import { getWorkViews } from "../work-view"
 import { parseRepositoryReferences } from "../workbase/repository-reference"
+import { GraphMutationService } from "../services/GraphMutationService"
 
 interface EpicOptions extends BaseCommandOptions {
 	readonly subcommand?: string
 	readonly args: readonly string[]
 	readonly ticketUrl?: string
 	readonly description?: string
+	readonly clearDescription?: boolean
 	readonly repos?: readonly string[]
 	readonly json?: boolean
 	readonly statuses?: readonly string[]
@@ -23,6 +25,7 @@ interface EpicOptions extends BaseCommandOptions {
 export const epic = (options: EpicOptions) =>
 	Effect.gen(function* () {
 		const epics = yield* EpicService
+		const mutations = yield* GraphMutationService
 		const { log } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
 
@@ -105,10 +108,49 @@ export const epic = (options: EpicOptions) =>
 				return
 			}
 
+			case "update": {
+				const id = options.args[0]
+				if (!id) return yield* Effect.fail(new Error("Epic ID is required"))
+				const output = yield* mutations.updateEpic(
+					id,
+					{
+						description: options.clearDescription ? null : options.description,
+						ticketUrl: options.ticketUrl,
+						repos:
+							options.repos === undefined
+								? undefined
+								: parseRepositoryReferences(options.repos),
+					},
+					cwd,
+				)
+				log(
+					options.json
+						? JSON.stringify(output, null, 2)
+						: `Updated epic '${id}'`,
+				)
+				return
+			}
+
+			case "rename": {
+				const [id, newId] = options.args
+				if (!id || !newId) {
+					return yield* Effect.fail(
+						new Error("Epic ID and new ID are required"),
+					)
+				}
+				const output = yield* mutations.renameEpic(id, newId, cwd)
+				log(
+					options.json
+						? JSON.stringify(output, null, 2)
+						: `Renamed epic '${id}' to '${newId}'`,
+				)
+				return
+			}
+
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Subcommand is required. Available subcommands: create, list, show",
+						"Subcommand is required. Available subcommands: create, list, show, update, rename",
 					),
 				)
 		}
@@ -121,12 +163,20 @@ Subcommands:
   create <id>           Create an epic
   list                  List epics
   show <id>             Show an epic
+  update <id>           Update epic metadata
+  rename <id> <new-id>  Rename an epic and update task references
 
 Create options:
   --ticket-url <url>    External ticket URL
   --description <text>  Short description of the epic
   --repo <alias>:<ref>  Read-only repository reference; repeatable
 
+Update options:
+  --ticket-url <url>    Replace the external ticket URL
+  --description <text>  Replace the description
+  --clear-description   Remove the description
+  --repo <alias>:<ref>  Replace repository references; repeatable
+
 Options:
   --json                Output results as JSON
   --status <status>     Filter list by status; repeatable

package/src/commands/phase.ts

@@ -5,15 +5,20 @@ import { createLoggers } from "../utils/effect"
 import { formatTable } from "../utils/table"
 import { getWorkViews } from "../work-view"
 import { parseRepositoryReferences } from "../workbase/repository-reference"
+import { GraphMutationService } from "../services/GraphMutationService"
 
 interface PhaseOptions extends BaseCommandOptions {
 	readonly subcommand?: string
 	readonly args: readonly string[]
 	readonly description?: string
+	readonly clearDescription?: boolean
 	readonly repo?: string
 	readonly references?: readonly string[]
 	readonly branch?: string
 	readonly base?: string
+	readonly clearReferences?: boolean
+	readonly prUrl?: string
+	readonly clearPr?: boolean
 	readonly dependsOn?: readonly string[]
 	readonly firstPhase?: string
 	readonly json?: boolean
@@ -27,6 +32,7 @@ interface PhaseOptions extends BaseCommandOptions {
 export const phase = (options: PhaseOptions) =>
 	Effect.gen(function* () {
 		const phases = yield* PhaseService
+		const mutations = yield* GraphMutationService
 		const { log } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
 		const [taskId, phaseId] = options.args
@@ -153,10 +159,84 @@ export const phase = (options: PhaseOptions) =>
 				)
 				return
 			}
+			case "update": {
+				if (!taskId || !phaseId) {
+					return yield* Effect.fail(
+						new Error("Task ID and phase ID are required"),
+					)
+				}
+				const output = yield* mutations.updatePhase(
+					taskId,
+					phaseId,
+					{
+						description: options.clearDescription ? null : options.description,
+						repo: options.repo,
+						repos: options.clearReferences
+							? null
+							: options.references === undefined
+								? undefined
+								: parseRepositoryReferences(options.references),
+						branch: options.branch,
+						base: options.base,
+						pr: options.clearPr ? null : options.prUrl,
+					},
+					cwd,
+				)
+				log(
+					options.json
+						? JSON.stringify(output, null, 2)
+						: `Updated phase '${phaseId}'`,
+				)
+				return
+			}
+			case "rename": {
+				const newId = options.args[2]
+				if (!taskId || !phaseId || !newId) {
+					return yield* Effect.fail(
+						new Error("Task ID, phase ID, and new ID are required"),
+					)
+				}
+				const output = yield* mutations.renamePhase(taskId, phaseId, newId, cwd)
+				log(
+					options.json
+						? JSON.stringify(output, null, 2)
+						: `Renamed phase '${phaseId}' to '${newId}'`,
+				)
+				return
+			}
+			case "dependency": {
+				const [operation, dependencyTaskId, dependencyPhaseId, dependencyId] =
+					options.args
+				if (
+					(operation !== "add" && operation !== "remove") ||
+					!dependencyTaskId ||
+					!dependencyPhaseId ||
+					!dependencyId
+				) {
+					return yield* Effect.fail(
+						new Error(
+							"Usage: agency phase dependency <add|remove> <task-id> <phase-id> <dependency-id>",
+						),
+					)
+				}
+				const output = yield* mutations.mutatePhaseDependency(
+					operation,
+					dependencyTaskId,
+					dependencyPhaseId,
+					dependencyId,
+					cwd,
+				)
+				log(
+					options.json
+						? JSON.stringify(output, null, 2)
+						: `${operation === "add" ? "Added" : "Removed"} dependency '${dependencyId}' ${operation === "add" ? "to" : "from"} phase '${dependencyPhaseId}'`,
+				)
+				return
+			}
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Subcommand is required. Available: create, list, show, status",
+						"Subcommand is required. Available: create, list, show, status, update, rename, dependency",
 					),
 				)
 		}
@@ -171,6 +251,11 @@ Subcommands:
   show <task> <phase>   Show a phase
   status <task> <phase> <status>
                         Set open, done, or dropped
+  update <task> <phase> Update phase metadata
+  rename <task> <phase> <new-id>
+                        Rename a phase and update dependencies
+  dependency <operation> <task> <phase> <dependency>
+                        Add or remove a phase dependency
 
 Create options:
   --description <text>  Short description of the phase
@@ -182,6 +267,14 @@ Create options:
   --depends-on <id>     Phase dependency; repeatable
   --first-phase <id>    Existing execution phase ID when converting a task
 
+Update options:
+  --description <text> / --clear-description
+  --repo <alias>        Replace the writable repository
+  --reference <alias>:<ref> / --clear-references
+  --branch <name>       Replace the working branch
+  --base <name>         Replace the base branch
+  --pr-url <url> / --clear-pr
+
 Options:
   --json                Output results as JSON
   --status <status>     Filter list by status; repeatable

package/src/commands/pr.ts

@@ -33,8 +33,8 @@ export const pr = (options: PrOptions) =>
 export const help = `
 Usage: agency pr create <task-id> [phase-id]
 
-Push the execution branch, create a GitHub pull request, and update its
-task or phase document.
+Push the execution branch, create a pull request with the delivery provider,
+and update its task or phase document.
 
 Options:
   --draft             Create a draft pull request