@markjaquith/agency 2.48.1 → 2.50.0

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 = {
@@ -120,6 +123,12 @@ const ownedClaimOptions = {
 	revision: { type: "string" },
 } satisfies OptionConfig
 
+const nonPrCompletionOptions = {
+	"no-pull-request": { type: "boolean" },
+	summary: { type: "string" },
+	"evidence-url": { type: "string" },
+} satisfies OptionConfig
+
 const commands = {
 	init: {
 		usage: "agency init [path] [--json]",
@@ -360,6 +369,7 @@ const commands = {
 			...newWorkOptions,
 			...viewOptions,
 			...mutationOptions,
+			...nonPrCompletionOptions,
 			"pr-url": { type: "string" },
 			task: { type: "string" },
 		},
@@ -386,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: [
@@ -398,6 +408,9 @@ const commands = {
 					"branch",
 					"base",
 					"multi-phase",
+					"review",
+					"pull-request",
+					"ref",
 					"json",
 				],
 				repeatable: ["reference"],
@@ -417,10 +430,10 @@ const commands = {
 				options: ["json", "task"],
 			},
 			status: {
-				usage: "agency task status <id> <status> [--json]",
+				usage: "agency task status <id> <status> [options] [--json]",
 				minArgs: 2,
 				maxArgs: 2,
-				options: ["json", "task"],
+				options: ["json", "task", "no-pull-request", "summary", "evidence-url"],
 			},
 			update: {
 				usage: "agency task update <id> [options] [--json]",
@@ -479,6 +492,7 @@ const commands = {
 			...newWorkOptions,
 			...viewOptions,
 			...mutationOptions,
+			...nonPrCompletionOptions,
 			"pr-url": { type: "string" },
 			task: { type: "string" },
 			phase: { type: "string" },
@@ -542,10 +556,18 @@ const commands = {
 				options: ["json", "task", "phase"],
 			},
 			status: {
-				usage: "agency phase status <task-id> <phase-id> <status> [--json]",
+				usage:
+					"agency phase status <task-id> <phase-id> <status> [options] [--json]",
 				minArgs: 3,
 				maxArgs: 3,
-				options: ["json", "task", "phase"],
+				options: [
+					"json",
+					"task",
+					"phase",
+					"no-pull-request",
+					"summary",
+					"evidence-url",
+				],
 			},
 			update: {
 				usage: "agency phase update <task-id> <phase-id> [options] [--json]",
@@ -631,16 +653,27 @@ const commands = {
 		usage: "agency finish <task-id> [phase-id] [options]",
 		options: {
 			...ownedClaimOptions,
+			...nonPrCompletionOptions,
 			outcome: { type: "string" },
 			task: { type: "string" },
 			phase: { type: "string" },
 		},
 		command: {
 			usage:
-				"agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped> [--json]",
+				"agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped> [options] [--json]",
 			minArgs: 1,
 			maxArgs: 2,
-			options: ["session-id", "revision", "outcome", "json", "task", "phase"],
+			options: [
+				"session-id",
+				"revision",
+				"outcome",
+				"no-pull-request",
+				"summary",
+				"evidence-url",
+				"json",
+				"task",
+				"phase",
+			],
 			required: ["session-id", "revision", "outcome"],
 		},
 	},
@@ -733,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: {
@@ -1134,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) {
@@ -1409,6 +1490,40 @@ export function parseCli(args: readonly string[]): ParsedCli {
 			spec.usage,
 		)
 	}
+	const nonPrCompletion = parsed.values["no-pull-request"] === true
+	const completionSummary = parsed.values.summary
+	const completionEvidenceUrl = parsed.values["evidence-url"]
+	if (
+		(completionSummary !== undefined || completionEvidenceUrl !== undefined) &&
+		!nonPrCompletion
+	) {
+		throw usageError(
+			"Options '--summary' and '--evidence-url' require '--no-pull-request'.",
+			spec.usage,
+		)
+	}
+	if (nonPrCompletion) {
+		if (
+			typeof completionSummary !== "string" ||
+			completionSummary.trim().length === 0
+		) {
+			throw usageError(
+				"Option '--summary' is required with '--no-pull-request'.",
+				spec.usage,
+			)
+		}
+		const completesDone =
+			(commandName === "finish" && parsed.values.outcome === "done") ||
+			(["task", "phase"].includes(commandName) &&
+				subcommand === "status" &&
+				commandPositionals.at(-1) === "done")
+		if (!completesDone) {
+			throw usageError(
+				"Option '--no-pull-request' is valid only with a done status or outcome.",
+				spec.usage,
+			)
+		}
+	}
 	if (commandName === "work") {
 		const preparing = commandPositionals[0] === "prepare"
 		if (

package/src/cli.test.ts

@@ -248,6 +248,77 @@ describe("CLI", () => {
 			parseJson(await runCli(["task", "show", "claimed", "--json"], root)).data
 				.status,
 		).toBe("working")
+
+		parseJson(
+			await runCli(
+				["task", "create", "non-pr", "--repo", "agency", "--json"],
+				root,
+			),
+		)
+		const nonPrContext = parseJson(
+			await runCli(["context", "tasks/non-pr", "--json"], root),
+		)
+		const nonPrClaim = parseJson(
+			await runCli(
+				[
+					"claim",
+					"non-pr",
+					"--claimant",
+					"orchestrator",
+					"--runner",
+					"agent",
+					"--session-id",
+					"job-2",
+					"--revision",
+					nonPrContext.documents.task.sha256,
+					"--json",
+				],
+				root,
+			),
+		)
+		parseJson(
+			await runCli(
+				[
+					"finish",
+					"non-pr",
+					"--session-id",
+					"job-2",
+					"--revision",
+					nonPrClaim.revision,
+					"--outcome",
+					"done",
+					"--no-pull-request",
+					"--summary",
+					"Investigation completed without changes.",
+					"--evidence-url",
+					"https://example.com/result",
+					"--json",
+				],
+				root,
+			),
+		)
+		expect(
+			parseJson(await runCli(["task", "show", "non-pr", "--json"], root)).data,
+		).toMatchObject({
+			status: "done",
+			completion: {
+				mode: "non-pr",
+				summary: "Investigation completed without changes.",
+				evidenceUrl: "https://example.com/result",
+			},
+		})
+		const prUpdate = await runCli(
+			[
+				"task",
+				"update",
+				"non-pr",
+				"--pr-url",
+				"https://github.com/example/agency/pull/1",
+			],
+			root,
+		)
+		expect(prUpdate.exitCode).toBe(1)
+		expect(prUpdate.stderr).toContain("Reopen non-PR completed work")
 	})
 
 	test("routes graph mutations through structured output", async () => {

package/src/commands/claim.ts

@@ -13,6 +13,9 @@ interface ClaimCommandOptions extends BaseCommandOptions {
 	readonly revision?: string
 	readonly expiresAt?: string
 	readonly outcome?: string
+	readonly noPullRequest?: boolean
+	readonly summary?: string
+	readonly evidenceUrl?: string
 	readonly json?: boolean
 }
 
@@ -32,6 +35,16 @@ export const claimCommand = (options: ClaimCommandOptions) =>
 				new Error("Claimant and runner identities are required"),
 			)
 		}
+		if (options.noPullRequest && !options.summary?.trim()) {
+			return yield* Effect.fail(
+				new Error("Non-PR completion requires a non-empty summary"),
+			)
+		}
+		if (options.noPullRequest && options.outcome !== "done") {
+			return yield* Effect.fail(
+				new Error("Non-PR completion is valid only with a done outcome"),
+			)
+		}
 		if (
 			options.operation === "finish" &&
 			options.outcome !== "done" &&
@@ -65,6 +78,16 @@ export const claimCommand = (options: ClaimCommandOptions) =>
 							{
 								...common,
 								outcome: options.outcome as "done" | "dropped",
+								...(options.noPullRequest
+									? {
+											nonPrCompletion: {
+												summary: options.summary!,
+												...(options.evidenceUrl
+													? { evidenceUrl: options.evidenceUrl }
+													: {}),
+											},
+										}
+									: {}),
 							},
 							cwd,
 						)
@@ -91,8 +114,9 @@ Release an execution unit owned by the session.
 `
 
 export const finishHelp = `
-Usage: agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped>
+Usage: agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped> [--no-pull-request --summary <text> [--evidence-url <url>]]
 
 Finish a claim owned by the session. A done claim outcome leaves unmerged work
-working; agency sync --apply marks the execution unit done after merge.
+working; agency sync --apply marks the execution unit done after merge. Use
+--no-pull-request with a summary for an explicit non-PR completion.
 `

package/src/commands/phase.ts

@@ -31,6 +31,9 @@ interface PhaseOptions extends BaseCommandOptions {
 	readonly pr?: boolean
 	readonly work?: boolean
 	readonly auto?: boolean
+	readonly noPullRequest?: boolean
+	readonly summary?: string
+	readonly evidenceUrl?: string
 }
 
 export const phase = (options: PhaseOptions, work: StartWork = startWork) =>
@@ -166,7 +169,20 @@ export const phase = (options: PhaseOptions, work: StartWork = startWork) =>
 						),
 					)
 				}
-				const record = yield* phases.setStatus(taskId, phaseId, status, cwd)
+				const record = yield* phases.setStatus(
+					taskId,
+					phaseId,
+					status,
+					cwd,
+					options.noPullRequest
+						? {
+								summary: options.summary ?? "",
+								...(options.evidenceUrl
+									? { evidenceUrl: options.evidenceUrl }
+									: {}),
+							}
+						: undefined,
+				)
 				const { content: _, ...output } = record
 				log(
 					options.json
@@ -275,7 +291,7 @@ Subcommands:
   list <task>           List task phases
   show <task> <phase>   Show a phase
   status <task> <phase> <status>
-                        Set open, working, or dropped
+                        Set open, working, dropped, or explicit non-PR done
   update <task> <phase> Update phase metadata
   rename <task> <phase> <new-id>
                         Rename a phase and update dependencies
@@ -285,6 +301,11 @@ Subcommands:
 Mutation option:
   --if-revision <hash>  Require the target's current revision
 
+Non-PR completion options (status done only):
+  --no-pull-request     Complete without a pull request
+  --summary <text>      Required durable outcome summary
+  --evidence-url <url>  Optional supporting record
+
 Create options:
   --description <text>  Short description of the phase
   --repo <alias>        Writable repository

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[]
@@ -38,6 +42,9 @@ interface TaskOptions extends BaseCommandOptions {
 	readonly pr?: boolean
 	readonly work?: boolean
 	readonly auto?: boolean
+	readonly noPullRequest?: boolean
+	readonly summary?: string
+	readonly evidenceUrl?: string
 }
 
 export interface TaskInteraction {
@@ -82,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()
 
@@ -208,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,
@@ -220,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,
 				)
@@ -304,7 +325,19 @@ export const task = (
 						new Error("Usage: agency task status <id> <status>"),
 					)
 				}
-				const record = yield* tasks.setStatus(id, status, cwd)
+				const record = yield* tasks.setStatus(
+					id,
+					status,
+					cwd,
+					options.noPullRequest
+						? {
+								summary: options.summary ?? "",
+								...(options.evidenceUrl
+									? { evidenceUrl: options.evidenceUrl }
+									: {}),
+							}
+						: undefined,
+				)
 				const { content: _, ...output } = record
 				log(
 					options.json
@@ -423,7 +456,7 @@ Subcommands:
   create <id>           Create a task without prompting
   list                  List tasks
   show <id>             Show a task
-  status <id> <status>  Set open, working, or dropped
+  status <id> <status>  Set open, working, dropped, or explicit non-PR done
   update <id>           Update task metadata
   rename <id> <new-id>  Rename a task and update graph references
   move <id>             Move a task with --epic or --no-epic
@@ -433,6 +466,11 @@ Subcommands:
 Mutation option:
   --if-revision <hash>  Require the target's current revision
 
+Non-PR completion options (status done only):
+  --no-pull-request     Complete without a pull request
+  --summary <text>      Required durable outcome summary
+  --evidence-url <url>  Optional supporting record
+
 Create options:
   --ticket-url <url>    External ticket URL (optional)
   --description <text>  Short description of the task
@@ -442,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}`,
 			)
 		}
 	})

package/src/graph-schema.ts

@@ -3,6 +3,8 @@ import {
 	EpicFrontmatter,
 	PhaseFrontmatter,
 	PullRequestRecord,
+	ClaimRecord,
+	ReviewRecord,
 	TaskFrontmatter,
 	WorkStatus,
 } from "./workbase/schemas"
@@ -69,13 +71,24 @@ const DocumentHash = Schema.Struct({ sha256: Schema.String })
 export const GraphEpicData = Schema.extend(EpicFrontmatter, DocumentHash)
 export const GraphTaskData = Schema.extend(TaskFrontmatter, DocumentHash)
 export const GraphPhaseData = Schema.extend(PhaseFrontmatter, DocumentHash)
-export const GraphExecutionData = Schema.extend(
-	PhaseFrontmatter,
+export const GraphExecutionData = Schema.Union(
+	Schema.extend(
+		PhaseFrontmatter,
+		Schema.Struct({
+			taskId: Schema.String,
+			phaseId: Schema.optional(Schema.String),
+			ticketUrl: Schema.optional(Schema.NullOr(Schema.String)),
+			epic: Schema.optional(Schema.String),
+		}),
+	),
 	Schema.Struct({
 		taskId: Schema.String,
-		phaseId: Schema.optional(Schema.String),
-		ticketUrl: Schema.optional(Schema.NullOr(Schema.String)),
+		ticketUrl: Schema.NullOr(Schema.String),
+		description: Schema.optional(Schema.String),
 		epic: Schema.optional(Schema.String),
+		review: ReviewRecord,
+		status: WorkStatus,
+		claim: Schema.optional(ClaimRecord),
 	}),
 )
 
@@ -98,15 +111,24 @@ export const GraphRepositoryGit = Schema.Struct({
 	head: Schema.NullOr(Schema.String),
 	branch: Schema.NullOr(Schema.String),
 })
-export const GraphExecutionGit = Schema.Struct({
-	branch: Schema.String,
-	base: Schema.String,
-	branchCommit: Schema.NullOr(Schema.String),
-	baseCommit: Schema.NullOr(Schema.String),
-	checkoutCommit: Schema.NullOr(Schema.String),
-	checkoutBranch: Schema.NullOr(Schema.String),
-	dirty: Schema.NullOr(Schema.Boolean),
-})
+export const GraphExecutionGit = Schema.Union(
+	Schema.Struct({
+		branch: Schema.String,
+		base: Schema.String,
+		branchCommit: Schema.NullOr(Schema.String),
+		baseCommit: Schema.NullOr(Schema.String),
+		checkoutCommit: Schema.NullOr(Schema.String),
+		checkoutBranch: Schema.NullOr(Schema.String),
+		dirty: Schema.NullOr(Schema.Boolean),
+	}),
+	Schema.Struct({
+		pinnedCommit: Schema.String,
+		sourceCommit: Schema.NullOr(Schema.String),
+		checkoutCommit: Schema.NullOr(Schema.String),
+		checkoutBranch: Schema.NullOr(Schema.String),
+		dirty: Schema.NullOr(Schema.Boolean),
+	}),
+)
 export const GraphPr = Schema.Union(
 	Schema.Struct({ url: Schema.Null, state: Schema.Literal("none") }),
 	Schema.Struct({ url: Schema.String, state: Schema.Literal("unavailable") }),

package/src/protocol.ts

@@ -100,6 +100,7 @@ const errorMetadata: Readonly<Record<string, ErrorMetadata>> = {
 	ArchiveError: { code: "ARCHIVE_ERROR", retryable: false },
 	WorktreeError: { code: "WORKTREE_ERROR", retryable: false },
 	PullRequestError: { code: "PULL_REQUEST_ERROR", retryable: false },
+	ReviewError: { code: "REVIEW_ERROR", retryable: false },
 	ContextError: {
 		code: "CONTEXT_ERROR",
 		retryable: false,