@markjaquith/agency 2.21.0 → 2.23.0

package/README.md

@@ -400,6 +400,8 @@ repository. Alias names are then used by all documents and commands.
 Commands that print Agency-owned results accept `--json`, including initialization,
 integration inspection/sync, repository mutations, entity creation/list/show,
 status, validation, graph export, reconciliation, and PR creation.
+Entity create, list, and show results include a stable SHA-256 `revision` of the
+complete Markdown document.
 
 ### Epics
 
@@ -515,6 +517,13 @@ 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.
 
+Epic, task, and phase update, rename, move, and dependency mutations accept
+`--if-revision <hash>`. The option is optional for interactive human use. When
+provided, Agency fails with a structured `REVISION_CONFLICT` containing the
+expected and current revisions if the target changed. Multi-document mutations
+also recheck every affected document after taking the mutation lock and before
+writing anything.
+
 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

@@ -238,6 +238,7 @@ const commands: Record<string, Command> = {
 					ticketUrl: options["ticket-url"],
 					description: options.description,
 					clearDescription: options["clear-description"],
+					ifRevision: options["if-revision"],
 					repos: options.repo,
 					json: options.json,
 					statuses: options.status,
@@ -289,6 +290,7 @@ const commands: Record<string, Command> = {
 					clearReferences: options["clear-references"],
 					prUrl: options["pr-url"],
 					clearPr: options["clear-pr"],
+					ifRevision: options["if-revision"],
 					dependsOn: options["depends-on"],
 					firstPhase: options["first-phase"],
 					json: options.json,
@@ -399,6 +401,7 @@ const commands: Record<string, Command> = {
 					clearReferences: options["clear-references"],
 					prUrl: options["pr-url"],
 					clearPr: options["clear-pr"],
+					ifRevision: options["if-revision"],
 					noEpic: options["no-epic"],
 					multiPhase: options["multi-phase"],
 					json: options.json,

package/package.json

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

package/src/cli-parser.test.ts

@@ -296,6 +296,31 @@ describe("strict CLI parsing", () => {
 		).toThrow("must be 'done' or 'dropped'")
 	})
 
+	test("accepts valid mutation revisions and rejects malformed hashes", () => {
+		const revision = "a".repeat(64)
+		expect(
+			parseCli([
+				"task",
+				"move",
+				"example",
+				"--no-epic",
+				"--if-revision",
+				revision,
+			]),
+		).toMatchObject({ values: { "if-revision": revision } })
+		expect(() =>
+			parseCli([
+				"phase",
+				"rename",
+				"task",
+				"phase",
+				"renamed",
+				"--if-revision",
+				"stale",
+			]),
+		).toThrow("64-character SHA-256 hash")
+	})
+
 	test("accepts context projections and keeps compact command-local", () => {
 		expect(parseCli(["context", ".", "--json", "--compact"])).toMatchObject({
 			commandName: "context",

package/src/cli-parser.ts

@@ -91,6 +91,7 @@ const phaseCreateOptions = {
 } satisfies OptionConfig
 
 const mutationOptions = {
+	"if-revision": { type: "string" },
 	"clear-description": { type: "boolean" },
 	"clear-ticket": { type: "boolean" },
 	"clear-references": { type: "boolean" },
@@ -249,6 +250,7 @@ const commands = {
 					"clear-description",
 					"ticket-url",
 					"repo",
+					"if-revision",
 					"json",
 				],
 				repeatable: ["repo"],
@@ -258,7 +260,7 @@ const commands = {
 				usage: "agency epic rename <id> <new-id> [--json]",
 				minArgs: 2,
 				maxArgs: 2,
-				options: ["json"],
+				options: ["if-revision", "json"],
 			},
 		},
 	},
@@ -344,6 +346,7 @@ const commands = {
 					"base",
 					"pr-url",
 					"clear-pr",
+					"if-revision",
 					"json",
 				],
 				repeatable: ["reference"],
@@ -358,13 +361,13 @@ const commands = {
 				usage: "agency task rename <id> <new-id> [--json]",
 				minArgs: 2,
 				maxArgs: 2,
-				options: ["json"],
+				options: ["if-revision", "json"],
 			},
 			move: {
 				usage: "agency task move <id> (--epic <id> | --no-epic) [--json]",
 				minArgs: 1,
 				maxArgs: 1,
-				options: ["epic", "no-epic", "json"],
+				options: ["epic", "no-epic", "if-revision", "json"],
 				conflicts: [["epic", "no-epic"]],
 			},
 			dependency: {
@@ -372,7 +375,7 @@ const commands = {
 					"agency task dependency <add|remove> <task-id> <dependency-id> [--json]",
 				minArgs: 3,
 				maxArgs: 3,
-				options: ["json"],
+				options: ["if-revision", "json"],
 			},
 		},
 	},
@@ -441,6 +444,7 @@ const commands = {
 					"base",
 					"pr-url",
 					"clear-pr",
+					"if-revision",
 					"json",
 				],
 				repeatable: ["reference"],
@@ -454,14 +458,14 @@ const commands = {
 				usage: "agency phase rename <task-id> <phase-id> <new-id> [--json]",
 				minArgs: 3,
 				maxArgs: 3,
-				options: ["json"],
+				options: ["if-revision", "json"],
 			},
 			dependency: {
 				usage:
 					"agency phase dependency <add|remove> <task-id> <phase-id> <dependency-id> [--json]",
 				minArgs: 4,
 				maxArgs: 4,
-				options: ["json"],
+				options: ["if-revision", "json"],
 			},
 		},
 	},
@@ -1125,11 +1129,22 @@ export function parseCli(args: readonly string[]): ParsedCli {
 		["epic", "task", "phase"].includes(commandName) &&
 		subcommand === "update"
 	) {
-		const mutationNames = (spec.options ?? []).filter((name) => name !== "json")
+		const mutationNames = (spec.options ?? []).filter(
+			(name) => name !== "json" && name !== "if-revision",
+		)
 		if (!mutationNames.some((name) => parsed.values[name] !== undefined)) {
 			throw usageError("At least one update option is required.", spec.usage)
 		}
 	}
+	if (
+		typeof parsed.values["if-revision"] === "string" &&
+		!/^[a-f0-9]{64}$/.test(parsed.values["if-revision"])
+	) {
+		throw usageError(
+			"Option '--if-revision' must be a 64-character SHA-256 hash.",
+			spec.usage,
+		)
+	}
 	if (commandName === "graph") {
 		validateGraphOptions(parsed.values, spec)
 	}

package/src/cli.test.ts

@@ -203,6 +203,41 @@ describe("CLI", () => {
 				),
 			)
 		}
+		const observed = parseJson(
+			await runCli(["task", "show", "second", "--json"], root),
+		)
+		const taskPath = join(root, "tasks/second/TASK.md")
+		await Bun.write(
+			taskPath,
+			`${await Bun.file(taskPath).text()}\nConcurrent edit.\n`,
+		)
+		const conflict = await runCli(
+			[
+				"task",
+				"update",
+				"second",
+				"--description",
+				"Stale update",
+				"--if-revision",
+				observed.revision,
+				"--json",
+			],
+			root,
+		)
+		expect(conflict.exitCode).toBe(1)
+		expect(JSON.parse(conflict.stdout)).toMatchObject({
+			ok: false,
+			error: {
+				code: "REVISION_CONFLICT",
+				retryable: true,
+				fields: {
+					path: "tasks/second/TASK.md",
+					expectedRevision: observed.revision,
+					currentRevision: expect.stringMatching(/^[a-f0-9]{64}$/),
+				},
+			},
+		})
+		expect(await Bun.file(taskPath).text()).toContain("Concurrent edit.")
 
 		const updated = parseJson(
 			await runCli(

package/src/commands/epic.test.ts

@@ -40,9 +40,12 @@ describe("epic command", () => {
 			),
 		)
 
-		expect(JSON.parse(logs[0]!)).toEqual({
+		const created = JSON.parse(logs[0]!)
+		expect(created.revision).toMatch(/^[a-f0-9]{64}$/)
+		expect(created).toEqual({
 			id: "example",
 			path: join(root, "epics/example/EPIC.md"),
+			revision: created.revision,
 			data: {
 				ticketUrl: "https://example.com/epic",
 				repos: [{ repo: "agency", ref: "main" }],
@@ -68,10 +71,13 @@ describe("epic command", () => {
 				epic({ subcommand: "list", args: [], cwd: root, json: true }),
 			),
 		)
-		expect(JSON.parse(listLogs[0]!)).toEqual([
+		const listed = JSON.parse(listLogs[0]!)
+		expect(listed[0].revision).toMatch(/^[a-f0-9]{64}$/)
+		expect(listed).toEqual([
 			{
 				id: "example",
 				path: join(root, "epics/example/EPIC.md"),
+				revision: listed[0].revision,
 				data: {
 					ticketUrl: "https://example.com/epic",
 					repos: [{ repo: "agency", ref: "main" }],
@@ -90,9 +96,12 @@ describe("epic command", () => {
 				}),
 			),
 		)
-		expect(JSON.parse(showLogs[0]!)).toEqual({
+		const shown = JSON.parse(showLogs[0]!)
+		expect(shown.revision).toBe(listed[0].revision)
+		expect(shown).toEqual({
 			id: "example",
 			path: join(root, "epics/example/EPIC.md"),
+			revision: shown.revision,
 			data: {
 				ticketUrl: "https://example.com/epic",
 				repos: [{ repo: "agency", ref: "main" }],

package/src/commands/epic.ts

@@ -13,6 +13,7 @@ interface EpicOptions extends BaseCommandOptions {
 	readonly ticketUrl?: string
 	readonly description?: string
 	readonly clearDescription?: boolean
+	readonly ifRevision?: string
 	readonly repos?: readonly string[]
 	readonly json?: boolean
 	readonly statuses?: readonly string[]
@@ -122,6 +123,7 @@ export const epic = (options: EpicOptions) =>
 								: parseRepositoryReferences(options.repos),
 					},
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -138,7 +140,12 @@ export const epic = (options: EpicOptions) =>
 						new Error("Epic ID and new ID are required"),
 					)
 				}
-				const output = yield* mutations.renameEpic(id, newId, cwd)
+				const output = yield* mutations.renameEpic(
+					id,
+					newId,
+					cwd,
+					options.ifRevision,
+				)
 				log(
 					options.json
 						? JSON.stringify(output, null, 2)
@@ -177,6 +184,9 @@ Update options:
   --clear-description   Remove the description
   --repo <alias>:<ref>  Replace repository references; repeatable
 
+Mutation options:
+  --if-revision <hash>  Require the target's current revision
+
 Options:
   --json                Output results as JSON
   --status <status>     Filter list by status; repeatable

package/src/commands/phase.ts

@@ -19,6 +19,7 @@ interface PhaseOptions extends BaseCommandOptions {
 	readonly clearReferences?: boolean
 	readonly prUrl?: string
 	readonly clearPr?: boolean
+	readonly ifRevision?: string
 	readonly dependsOn?: readonly string[]
 	readonly firstPhase?: string
 	readonly json?: boolean
@@ -181,6 +182,7 @@ export const phase = (options: PhaseOptions) =>
 						pr: options.clearPr ? null : options.prUrl,
 					},
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -196,7 +198,13 @@ export const phase = (options: PhaseOptions) =>
 						new Error("Task ID, phase ID, and new ID are required"),
 					)
 				}
-				const output = yield* mutations.renamePhase(taskId, phaseId, newId, cwd)
+				const output = yield* mutations.renamePhase(
+					taskId,
+					phaseId,
+					newId,
+					cwd,
+					options.ifRevision,
+				)
 				log(
 					options.json
 						? JSON.stringify(output, null, 2)
@@ -225,6 +233,7 @@ export const phase = (options: PhaseOptions) =>
 					dependencyPhaseId,
 					dependencyId,
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -257,6 +266,9 @@ Subcommands:
   dependency <operation> <task> <phase> <dependency>
                         Add or remove a phase dependency
 
+Mutation option:
+  --if-revision <hash>  Require the target's current revision
+
 Create options:
   --description <text>  Short description of the phase
   --repo <alias>        Writable repository

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

package/src/commands/task-phase.test.ts

@@ -48,10 +48,13 @@ describe("task and phase command JSON output", () => {
 				task({ subcommand: "list", args: [], cwd: root, json: true }),
 			),
 		)
-		expect(JSON.parse(listLogs[0]!)).toEqual([
+		const listed = JSON.parse(listLogs[0]!)
+		expect(listed[0].revision).toMatch(/^[a-f0-9]{64}$/)
+		expect(listed).toEqual([
 			{
 				id: "multi",
 				path: join(root, "tasks/multi/TASK.md"),
+				revision: listed[0].revision,
 				data: {
 					ticketUrl: "https://example.com/task",
 					phases: [{ id: "first" }],
@@ -69,9 +72,12 @@ describe("task and phase command JSON output", () => {
 				}),
 			),
 		)
-		expect(JSON.parse(showLogs[0]!)).toEqual({
+		const shown = JSON.parse(showLogs[0]!)
+		expect(shown.revision).toBe(listed[0].revision)
+		expect(shown).toEqual({
 			id: "multi",
 			path: join(root, "tasks/multi/TASK.md"),
+			revision: shown.revision,
 			data: {
 				ticketUrl: "https://example.com/task",
 				phases: [{ id: "first" }],
@@ -85,11 +91,14 @@ describe("task and phase command JSON output", () => {
 				phase({ subcommand: "list", args: ["multi"], cwd: root, json: true }),
 			),
 		)
-		expect(JSON.parse(listLogs[0]!)).toEqual([
+		const listed = JSON.parse(listLogs[0]!)
+		expect(listed[0].revision).toMatch(/^[a-f0-9]{64}$/)
+		expect(listed).toEqual([
 			{
 				taskId: "multi",
 				id: "first",
 				path: join(root, "tasks/multi/phases/first/PHASE.md"),
+				revision: listed[0].revision,
 				data: {
 					repo: "agency",
 					branch: "task/first",
@@ -110,10 +119,13 @@ describe("task and phase command JSON output", () => {
 				}),
 			),
 		)
-		expect(JSON.parse(showLogs[0]!)).toEqual({
+		const shown = JSON.parse(showLogs[0]!)
+		expect(shown.revision).toBe(listed[0].revision)
+		expect(shown).toEqual({
 			taskId: "multi",
 			id: "first",
 			path: join(root, "tasks/multi/phases/first/PHASE.md"),
+			revision: shown.revision,
 			data: {
 				repo: "agency",
 				branch: "task/first",

package/src/commands/task.ts

@@ -27,6 +27,7 @@ interface TaskOptions extends BaseCommandOptions {
 	readonly clearReferences?: boolean
 	readonly prUrl?: string
 	readonly clearPr?: boolean
+	readonly ifRevision?: string
 	readonly noEpic?: boolean
 	readonly multiPhase?: boolean
 	readonly json?: boolean
@@ -318,6 +319,7 @@ export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
 						pr: options.clearPr ? null : options.prUrl,
 					},
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -333,7 +335,12 @@ export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
 						new Error("Task ID and new ID are required"),
 					)
 				}
-				const output = yield* mutations.renameTask(id, newId, cwd)
+				const output = yield* mutations.renameTask(
+					id,
+					newId,
+					cwd,
+					options.ifRevision,
+				)
 				log(
 					options.json
 						? JSON.stringify(output, null, 2)
@@ -348,6 +355,7 @@ export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
 					id,
 					options.noEpic ? null : (options.epic ?? null),
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -376,6 +384,7 @@ export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
 					id,
 					dependencyId,
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -408,6 +417,9 @@ Subcommands:
   dependency <operation> <task> <dependency>
                         Add or remove a task dependency
 
+Mutation option:
+  --if-revision <hash>  Require the target's current revision
+
 Create options:
   --ticket-url <url>    External ticket URL (optional)
   --description <text>  Short description of the task

package/src/graph-schema.ts

@@ -2,6 +2,7 @@ import { Schema } from "@effect/schema"
 import {
 	EpicFrontmatter,
 	PhaseFrontmatter,
+	PullRequestRecord,
 	TaskFrontmatter,
 	WorkStatus,
 } from "./workbase/schemas"
@@ -109,16 +110,7 @@ export const GraphExecutionGit = Schema.Struct({
 export const GraphPr = Schema.Union(
 	Schema.Struct({ url: Schema.Null, state: Schema.Literal("none") }),
 	Schema.Struct({ url: Schema.String, state: Schema.Literal("unavailable") }),
-	Schema.Struct({
-		recordedUrl: Schema.String,
-		number: Schema.Number,
-		state: Schema.String,
-		title: Schema.String,
-		isDraft: Schema.Boolean,
-		headRefName: Schema.String,
-		baseRefName: Schema.String,
-		url: Schema.String,
-	}),
+	PullRequestRecord,
 )
 
 const NodeIdentity = {

package/src/protocol.test.ts

@@ -108,5 +108,24 @@ describe("machine protocol", () => {
 				},
 			},
 		})
+		expect(
+			errorEnvelope({
+				_tag: "RevisionConflictError",
+				message: "revision conflict",
+				path: "tasks/example/TASK.md",
+				expectedRevision: "a".repeat(64),
+				currentRevision: "b".repeat(64),
+			}),
+		).toMatchObject({
+			error: {
+				code: "REVISION_CONFLICT",
+				retryable: true,
+				fields: {
+					path: "tasks/example/TASK.md",
+					expectedRevision: "a".repeat(64),
+					currentRevision: "b".repeat(64),
+				},
+			},
+		})
 	})
 })