@markjaquith/agency 2.49.0 → 2.50.0

package/README.md

@@ -589,6 +589,26 @@ agency task create <id> --multi-phase
   [--ticket-url <url>] [--description <text>] [--epic <id>] [--json]
 ```
 
+Create a pinned, read-only review task from the selected alias's origin:
+
+```text
+agency task create <id> --review <alias> --pull-request <url-or-number>
+agency task create <id> --review <alias> --ref <remote-ref>
+agency review refresh <id> [--if-revision <hash>] [--json]
+```
+
+Review creation fetches the source and records its exact 40-character commit.
+GitHub pull requests use the base alias's `refs/pull/<number>/head`, including
+fork pull requests exposed through that ref. Review workspaces contain one
+detached checkout and no writable branch. Source movement is observed separately
+from the pin and applied only by `review refresh`; sync, doctor, work, cleanup,
+and archive never move the pin implicitly. Dirty or structurally unexpected
+review checkouts block refresh and cleanup. Review tasks support normal status
+and claim lifecycle, but reject phase conversion and delivery PR operations.
+Each active or archived review task owns one internal task-scoped pin ref. A
+refresh advances that ref transactionally; failed creation removes it. Archiving
+retains the pin so a deleted source can still be restored and inspected.
+
 ### Noninteractive Use
 
 Agency never prompts when `--no-input` is set or stdin/stderr are not TTYs.
@@ -771,7 +791,8 @@ their built-in presets. Launches are interactive and promptless by default; use
 `--auto` to send Agency's generated context prompt.
 
 `agency work prepare` resolves an execution unit and creates or reuses its
-writable and reference worktrees without launching an agent or changing status.
+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.

package/cli.ts

@@ -43,6 +43,8 @@ import { SyncService } from "./src/services/SyncService"
 import { ReadinessService } from "./src/services/ReadinessService"
 import { GraphMutationService } from "./src/services/GraphMutationService"
 import { DoctorService } from "./src/services/DoctorService"
+import { ReviewService } from "./src/services/ReviewService"
+import { review, help as reviewHelp } from "./src/commands/review"
 import {
 	claimCommand,
 	claimHelp,
@@ -75,6 +77,7 @@ const CliLayer = Layer.mergeAll(
 	ReadinessService.Default,
 	GraphMutationService.Default,
 	DoctorService.Default,
+	ReviewService.Default,
 )
 
 /**
@@ -449,6 +452,9 @@ const commands: Record<string, Command> = {
 					clearDescription: options["clear-description"],
 					epic: options.epic,
 					repo: options.repo?.[0],
+					review: options.review,
+					pullRequest: options["pull-request"],
+					ref: options.ref,
 					references: options.reference,
 					branch: options.branch,
 					base: options.base,
@@ -477,6 +483,22 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	review: {
+		run: async (args: string[], options: Record<string, any>) => {
+			if (options.help) return console.log(reviewHelp)
+			await runCommand(
+				review({
+					subcommand: args[0],
+					taskId: args[1],
+					ifRevision: options["if-revision"],
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+					cwd: options.cwd,
+				}),
+			)
+		},
+	},
 	work: {
 		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) {
@@ -683,6 +705,7 @@ Commands:
   worktree <subcommand>  Inspect and maintain managed worktrees
   next                   List or select ready execution units
   pr create              Create a pull request for an execution unit
+  review refresh         Explicitly refresh a pinned review task
   repo <subcommand>      Manage workbase repositories
   status                 Show status for the current workbase
   doctor                 Diagnose workbase health and integrations

package/package.json

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

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

@@ -176,6 +176,7 @@
             { "$ref": "#/$defs/epicData" },
             { "$ref": "#/$defs/singleTaskData" },
             { "$ref": "#/$defs/multiTaskData" },
+            { "$ref": "#/$defs/reviewTaskData" },
             { "$ref": "#/$defs/phaseData" },
             { "$ref": "#/$defs/executionData" },
             { "$ref": "#/$defs/repositoryData" }
@@ -220,7 +221,8 @@
               "data": {
                 "oneOf": [
                   { "$ref": "#/$defs/singleTaskData" },
-                  { "$ref": "#/$defs/multiTaskData" }
+                  { "$ref": "#/$defs/multiTaskData" },
+                  { "$ref": "#/$defs/reviewTaskData" }
                 ]
               },
               "workspace": { "$ref": "#/$defs/documentWorkspace" },
@@ -358,34 +360,72 @@
         "sha256": { "type": "string" }
       }
     },
-    "phaseData": {
+    "reviewSource": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "provider",
+            "repository",
+            "identifier",
+            "url",
+            "fetchRef"
+          ],
+          "properties": {
+            "kind": { "const": "pull-request" },
+            "provider": { "const": "github" },
+            "repository": { "type": "string" },
+            "identifier": { "type": "string", "pattern": "^\\d+$" },
+            "url": {
+              "type": "string",
+              "pattern": "^https://github\\.com/[^/]+/[^/]+/pull/\\d+$"
+            },
+            "fetchRef": { "type": "string", "pattern": "^refs/pull/\\d+/head$" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "ref"],
+          "properties": {
+            "kind": { "const": "branch" },
+            "ref": { "type": "string", "pattern": "^refs/heads/" }
+          }
+        }
+      ]
+    },
+    "reviewRecord": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["repo", "branch", "base", "pr", "status", "sha256"],
+      "required": ["repo", "source", "commit", "refreshedAt"],
       "properties": {
-        "description": { "type": "string" },
         "repo": { "type": "string" },
-        "repos": {
-          "type": "array",
-          "items": { "$ref": "#/$defs/repositoryReference" }
-        },
-        "branch": { "type": "string" },
-        "base": { "type": "string" },
-        "pr": { "type": ["string", "null"] },
+        "source": { "$ref": "#/$defs/reviewSource" },
+        "commit": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+        "refreshedAt": { "type": "string", "format": "date-time" }
+      }
+    },
+    "reviewTaskData": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ticketUrl", "review", "status", "sha256"],
+      "properties": {
+        "ticketUrl": { "type": ["string", "null"] },
+        "description": { "type": "string" },
+        "epic": { "type": "string" },
+        "review": { "$ref": "#/$defs/reviewRecord" },
         "status": { "$ref": "#/$defs/status" },
         "claim": { "$ref": "#/$defs/claim" },
         "sha256": { "type": "string" }
       }
     },
-    "executionData": {
+    "phaseData": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["taskId", "repo", "branch", "base", "pr", "status"],
+      "required": ["repo", "branch", "base", "pr", "status", "sha256"],
       "properties": {
-        "taskId": { "type": "string" },
-        "phaseId": { "type": "string" },
-        "ticketUrl": { "type": ["string", "null"] },
-        "epic": { "type": "string" },
         "description": { "type": "string" },
         "repo": { "type": "string" },
         "repos": {
@@ -396,9 +436,50 @@
         "base": { "type": "string" },
         "pr": { "type": ["string", "null"] },
         "status": { "$ref": "#/$defs/status" },
-        "claim": { "$ref": "#/$defs/claim" }
+        "claim": { "$ref": "#/$defs/claim" },
+        "sha256": { "type": "string" }
       }
     },
+    "executionData": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["taskId", "repo", "branch", "base", "pr", "status"],
+          "properties": {
+            "taskId": { "type": "string" },
+            "phaseId": { "type": "string" },
+            "ticketUrl": { "type": ["string", "null"] },
+            "epic": { "type": "string" },
+            "description": { "type": "string" },
+            "repo": { "type": "string" },
+            "repos": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/repositoryReference" }
+            },
+            "branch": { "type": "string" },
+            "base": { "type": "string" },
+            "pr": { "type": ["string", "null"] },
+            "status": { "$ref": "#/$defs/status" },
+            "claim": { "$ref": "#/$defs/claim" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["taskId", "ticketUrl", "review", "status"],
+          "properties": {
+            "taskId": { "type": "string" },
+            "ticketUrl": { "type": ["string", "null"] },
+            "description": { "type": "string" },
+            "epic": { "type": "string" },
+            "review": { "$ref": "#/$defs/reviewRecord" },
+            "status": { "$ref": "#/$defs/status" },
+            "claim": { "$ref": "#/$defs/claim" }
+          }
+        }
+      ]
+    },
     "claim": {
       "type": "object",
       "additionalProperties": false,
@@ -469,26 +550,48 @@
       }
     },
     "executionGit": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "branch",
-        "base",
-        "branchCommit",
-        "baseCommit",
-        "checkoutCommit",
-        "checkoutBranch",
-        "dirty"
-      ],
-      "properties": {
-        "branch": { "type": "string" },
-        "base": { "type": "string" },
-        "branchCommit": { "type": ["string", "null"] },
-        "baseCommit": { "type": ["string", "null"] },
-        "checkoutCommit": { "type": ["string", "null"] },
-        "checkoutBranch": { "type": ["string", "null"] },
-        "dirty": { "type": ["boolean", "null"] }
-      }
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "branch",
+            "base",
+            "branchCommit",
+            "baseCommit",
+            "checkoutCommit",
+            "checkoutBranch",
+            "dirty"
+          ],
+          "properties": {
+            "branch": { "type": "string" },
+            "base": { "type": "string" },
+            "branchCommit": { "type": ["string", "null"] },
+            "baseCommit": { "type": ["string", "null"] },
+            "checkoutCommit": { "type": ["string", "null"] },
+            "checkoutBranch": { "type": ["string", "null"] },
+            "dirty": { "type": ["boolean", "null"] }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "pinnedCommit",
+            "sourceCommit",
+            "checkoutCommit",
+            "checkoutBranch",
+            "dirty"
+          ],
+          "properties": {
+            "pinnedCommit": { "type": "string" },
+            "sourceCommit": { "type": ["string", "null"] },
+            "checkoutCommit": { "type": ["string", "null"] },
+            "checkoutBranch": { "type": ["string", "null"] },
+            "dirty": { "type": ["boolean", "null"] }
+          }
+        }
+      ]
     },
     "pr": {
       "oneOf": [

package/src/cli-parser.test.ts

@@ -7,6 +7,68 @@ const expectUsageError = (args: string[], usage: string) => {
 }
 
 describe("strict CLI parsing", () => {
+	test("accepts review creation and refresh while enforcing one source", () => {
+		expect(
+			parseCli([
+				"task",
+				"create",
+				"review-it",
+				"--review",
+				"agency",
+				"--pull-request",
+				"42",
+			]).values,
+		).toMatchObject({ review: "agency", "pull-request": "42" })
+		expect(() =>
+			parseCli([
+				"task",
+				"create",
+				"review-it",
+				"--review",
+				"agency",
+				"--ref",
+				"feature/review",
+			]),
+		).not.toThrow()
+		expect(() =>
+			parseCli([
+				"review",
+				"refresh",
+				"review-it",
+				"--if-revision",
+				"a".repeat(64),
+			]),
+		).not.toThrow()
+		expect(() =>
+			parseCli([
+				"task",
+				"create",
+				"review-it",
+				"--review",
+				"agency",
+				"--pull-request",
+				"42",
+				"--ref",
+				"feature/review",
+			]),
+		).toThrow("exactly one")
+		for (const extra of [
+			["--ref", "feature/review", "--repo", "agency"],
+			["--ref", "feature/review", "--multi-phase"],
+		]) {
+			expect(() =>
+				parseCli([
+					"task",
+					"create",
+					"review-it",
+					"--review",
+					"agency",
+					...extra,
+				]),
+			).toThrow("cannot be combined")
+		}
+	})
+
 	test("accepts every documented orchestration recipe command", () => {
 		for (const args of orchestrationRecipes) {
 			expect(() => parseCli(args)).not.toThrow()

package/src/cli-parser.ts

@@ -82,6 +82,9 @@ const taskCreateOptions = {
 	branch: { type: "string" },
 	base: { type: "string" },
 	"multi-phase": { type: "boolean" },
+	review: { type: "string" },
+	"pull-request": { type: "string" },
+	ref: { type: "string" },
 } satisfies OptionConfig
 
 const phaseCreateOptions = {
@@ -393,7 +396,7 @@ const commands = {
 			},
 			create: {
 				usage:
-					"agency task create <id> (--repo <alias> | --multi-phase) [options]",
+					"agency task create <id> (--repo <alias> | --multi-phase | --review <alias> (--pull-request <value> | --ref <remote-ref>)) [options]",
 				minArgs: 1,
 				maxArgs: 1,
 				options: [
@@ -405,6 +408,9 @@ const commands = {
 					"branch",
 					"base",
 					"multi-phase",
+					"review",
+					"pull-request",
+					"ref",
 					"json",
 				],
 				repeatable: ["reference"],
@@ -760,6 +766,22 @@ const commands = {
 			},
 		},
 	},
+	review: {
+		usage: "agency review refresh <task-id> [--if-revision <hash>] [--json]",
+		options: {
+			...outputOptions,
+			"if-revision": { type: "string" },
+		},
+		subcommands: {
+			refresh: {
+				usage:
+					"agency review refresh <task-id> [--if-revision <hash>] [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["if-revision", "json"],
+			},
+		},
+	},
 	worktree: {
 		usage: "agency worktree <list|inspect|prepare|remove|rebuild|repair>",
 		options: {
@@ -1161,6 +1183,38 @@ function validateTaskCreate(
 	spec: LeafCommand,
 	requireRepo: boolean,
 ) {
+	const review = values.review !== undefined
+	const pullRequest = values["pull-request"] !== undefined
+	const ref = values.ref !== undefined
+	if (review) {
+		if (pullRequest === ref) {
+			throw usageError(
+				"Option '--review' requires exactly one of '--pull-request' or '--ref'.",
+				spec.usage,
+			)
+		}
+		for (const option of [
+			"repo",
+			"reference",
+			"branch",
+			"base",
+			"multi-phase",
+		] as const) {
+			if (values[option] !== undefined) {
+				throw usageError(
+					`Option '--review' cannot be combined with '${optionLabel(option)}'.`,
+					spec.usage,
+				)
+			}
+		}
+		return
+	}
+	if (pullRequest || ref) {
+		throw usageError(
+			`Option '${pullRequest ? "--pull-request" : "--ref"}' requires '--review'.`,
+			spec.usage,
+		)
+	}
 	if (values["multi-phase"]) {
 		for (const option of ["repo", "reference", "branch", "base"] as const) {
 			if (values[option] !== undefined) {

package/src/commands/review.ts

@@ -0,0 +1,38 @@
+import { Effect } from "effect"
+import { ReviewService } from "../services/ReviewService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+interface ReviewOptions extends BaseCommandOptions {
+	readonly subcommand?: string
+	readonly taskId?: string
+	readonly ifRevision?: string
+	readonly json?: boolean
+}
+
+export const review = (options: ReviewOptions) =>
+	Effect.gen(function* () {
+		if (options.subcommand !== "refresh" || !options.taskId) {
+			return yield* Effect.fail(
+				new Error("Usage: agency review refresh <task>"),
+			)
+		}
+		const result = yield* (yield* ReviewService).refresh(
+			options.taskId,
+			options.cwd,
+			options.ifRevision,
+		)
+		const { log } = createLoggers(options)
+		log(
+			options.json
+				? JSON.stringify(result, null, 2)
+				: `Refreshed review '${options.taskId}' at ${result.commit}`,
+		)
+	})
+
+export const help = `
+Usage: agency review refresh <task-id> [--if-revision <hash>] [--json]
+
+Fetch the review source explicitly and replace the pinned commit and any clean,
+detached review checkout. Review sources never move implicitly.
+`

package/src/commands/task.ts

@@ -11,6 +11,7 @@ import { formatTable } from "../utils/table"
 import { getWorkViews } from "../work-view"
 import { GraphMutationService } from "../services/GraphMutationService"
 import { work as startWork, type StartWork } from "./work"
+import { ReviewService } from "../services/ReviewService"
 
 interface TaskOptions extends BaseCommandOptions {
 	readonly subcommand?: string
@@ -30,6 +31,9 @@ interface TaskOptions extends BaseCommandOptions {
 	readonly ifRevision?: string
 	readonly noEpic?: boolean
 	readonly multiPhase?: boolean
+	readonly review?: string
+	readonly pullRequest?: string
+	readonly ref?: string
 	readonly json?: boolean
 	readonly statuses?: readonly string[]
 	readonly repositories?: readonly string[]
@@ -85,6 +89,7 @@ export const task = (
 		const repositories = yield* RepositoryService
 		const workbase = yield* WorkbaseService
 		const mutations = yield* GraphMutationService
+		const reviews = yield* ReviewService
 		const { log } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
 
@@ -211,11 +216,18 @@ export const task = (
 					return yield* Effect.fail(new Error("Task ID is required"))
 				}
 				const multiPhase = options.multiPhase ?? false
-				if (!multiPhase && !options.repo) {
+				if (!multiPhase && !options.repo && !options.review) {
 					return yield* Effect.fail(
 						new Error("Writable repository is required for task create"),
 					)
 				}
+				const review = options.review
+					? yield* reviews.resolve(
+							options.review,
+							{ pullRequest: options.pullRequest, ref: options.ref },
+							cwd,
+						)
+					: undefined
 				const record = yield* tasks.create(
 					{
 						id,
@@ -223,10 +235,16 @@ export const task = (
 						description: options.description?.trim() || undefined,
 						epic: options.epic,
 						multiPhase,
+						review,
 						repo: options.repo,
-						repos: parseRepositoryReferences(options.references),
-						branch: multiPhase ? undefined : (options.branch ?? `task/${id}`),
-						base: multiPhase ? undefined : (options.base ?? "main"),
+						repos: review
+							? undefined
+							: parseRepositoryReferences(options.references),
+						branch:
+							multiPhase || review
+								? undefined
+								: (options.branch ?? `task/${id}`),
+						base: multiPhase || review ? undefined : (options.base ?? "main"),
 					},
 					cwd,
 				)
@@ -462,7 +480,11 @@ Create options:
                         Read-only repository reference; repeatable
   --branch <name>       Working branch (default: task/<id>)
   --base <name>         Base branch (default: main)
-  --multi-phase         Create a task container for phases
+	--multi-phase         Create a task container for phases
+	--review <alias>      Create a pinned read-only review task
+	--pull-request <url-or-number>
+	                       Review a GitHub pull request from the alias origin
+	--ref <remote-ref>    Review a branch or other fetchable origin ref
   --work                Start work on the new task after creating it
   --auto                Pass --auto to work; requires --work
 

package/src/commands/work.test.ts

@@ -24,6 +24,7 @@ const singlePhaseWorkspace: ExecutionWorkspace = {
 	phasePath: null,
 	codePath: "/workbase/tasks/example/code",
 	writablePath: "/workbase/tasks/example/code/agency",
+	reviewPath: null,
 	repo: "agency",
 	repos: [],
 	dryRun: false,
@@ -37,6 +38,7 @@ const multiPhaseWorkspace: ExecutionWorkspace = {
 	phasePath: "/workbase/tasks/example/phases/implementation/PHASE.md",
 	codePath: "/workbase/tasks/example/phases/implementation/code",
 	writablePath: "/workbase/tasks/example/phases/implementation/code/agency",
+	reviewPath: null,
 	repo: "agency",
 	repos: [],
 	dryRun: false,

package/src/commands/work.ts

@@ -262,7 +262,7 @@ export const work = (
 				? `${action} the task. Read ${workspace.taskPath} and ${workspace.phasePath}.`
 				: `${action} the task. Read ${workspace.taskPath}.`
 			launchPath = dirname(workspace.phasePath ?? workspace.taskPath)
-			writablePath = workspace.writablePath
+			writablePath = workspace.writablePath ?? undefined
 		}
 
 		const explicitlyRequested = Boolean(
@@ -468,7 +468,7 @@ export const workPrepare = (options: WorkOptions = {}) =>
 			log(JSON.stringify(workspace, null, 2))
 		} else {
 			log(
-				`${workspace.dryRun ? "Workspace plan" : "Workspace ready"}: ${workspace.writablePath}`,
+				`${workspace.dryRun ? "Workspace plan" : "Workspace ready"}: ${workspace.writablePath ?? workspace.reviewPath}`,
 			)
 		}
 	})