@markjaquith/agency 2.48.1 → 2.50.0

package/src/services/WorktreeService.ts

@@ -43,7 +43,8 @@ interface ExecutionWorkspace {
 	readonly taskPath: string
 	readonly phasePath: string | null
 	readonly codePath: string
-	readonly writablePath: string
+	readonly writablePath: string | null
+	readonly reviewPath: string | null
 	readonly repo: string
 	readonly repos: readonly RepositoryReference[]
 	readonly dryRun: boolean
@@ -181,12 +182,14 @@ const inspectExecution = (
 		const root = yield* workbase.discover(startPath)
 		const task = yield* tasks.show(taskId, root)
 
-		let execution: {
-			repo: string
-			repos?: readonly RepositoryReference[]
-			branch: string
-			base: string
-		}
+		let execution:
+			| {
+					repo: string
+					repos?: readonly RepositoryReference[]
+					branch: string
+					base: string
+			  }
+			| { review: { repo: string; commit: string } }
 		let owner: WorktreeOwner
 		let codePath: string
 		if ("phases" in task.data) {
@@ -230,6 +233,7 @@ const inspectExecution = (
 					ownership.set(key, owners)
 				}
 			} else {
+				if (!("repo" in taskRecord.data)) continue
 				const key = `${taskRecord.data.repo}:${taskRecord.data.branch}`
 				const owners = ownership.get(key) ?? []
 				owners.push({
@@ -244,10 +248,13 @@ const inspectExecution = (
 		const declared: readonly (
 			| { readonly repo: string; readonly branch: string }
 			| RepositoryReference
-		)[] = [
-			{ repo: execution.repo, branch: execution.branch },
-			...(execution.repos ?? []),
-		]
+		)[] =
+			"review" in execution
+				? [{ repo: execution.review.repo, ref: execution.review.commit }]
+				: [
+						{ repo: execution.repo, branch: execution.branch },
+						...(execution.repos ?? []),
+					]
 		const checkouts: WorktreeCheckoutInspection[] = []
 		for (const checkout of declared) {
 			const repositoryPath = join(root, "repos", checkout.repo)
@@ -608,12 +615,14 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 						}
 						const task = yield* tasks.show(taskId, root)
 
-						let execution: {
-							repo: string
-							repos?: readonly RepositoryReference[]
-							branch: string
-							base: string
-						}
+						let execution:
+							| {
+									repo: string
+									repos?: readonly RepositoryReference[]
+									branch: string
+									base: string
+							  }
+							| { review: { repo: string; commit: string } }
 						let phasePath: string | null = null
 						let codePath: string
 						if ("phases" in task.data) {
@@ -639,10 +648,19 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 						const requestedCheckouts: readonly (
 							| { readonly repo: string; readonly branch: string }
 							| RepositoryReference
-						)[] = [
-							{ repo: execution.repo, branch: execution.branch },
-							...(execution.repos ?? []),
-						]
+						)[] =
+							"review" in execution
+								? [
+										{
+											repo: execution.review.repo,
+											ref: execution.review.commit,
+										},
+									]
+								: [
+										{ repo: execution.repo, branch: execution.branch },
+										...(execution.repos ?? []),
+									]
+						const executionBase = "base" in execution ? execution.base : ""
 						const canonicalCodePath = (yield* fs.exists(codePath))
 							? yield* fs.realPath(codePath)
 							: resolve(codePath)
@@ -732,7 +750,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											repositoryPath,
 											"rev-parse",
 											"--verify",
-											`${execution.base}^{commit}`,
+											`${executionBase}^{commit}`,
 										],
 										{ captureOutput: true },
 									)
@@ -744,7 +762,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 												repositoryPath,
 												"ls-remote",
 												"origin",
-												originRef(execution.base),
+												originRef(executionBase),
 											],
 											{ captureOutput: true },
 										)
@@ -753,7 +771,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											!remoteBase.stdout.trim()
 										) {
 											return yield* new WorktreeError({
-												message: `Base '${execution.base}' for repository '${alias}' does not resolve to a commit`,
+												message: `Base '${executionBase}' for repository '${alias}' does not resolve to a commit`,
 											})
 										}
 									}
@@ -764,7 +782,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											repo: repositoryPath,
 											worktree: checkoutPath,
 											branch: checkout.branch,
-											base: execution.base,
+											base: executionBase,
 										})
 									} catch (cause) {
 										return yield* new WorktreeError({
@@ -991,7 +1009,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											repo: repositoryPath,
 											worktree: checkoutPath,
 											branch: checkout.branch,
-											base: execution.base,
+											base: executionBase,
 										}
 										try {
 											args = expandWorktreeCreateCommand(
@@ -1026,7 +1044,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 												repositoryPath,
 												"branch",
 												checkout.branch,
-												execution.base,
+												executionBase,
 											]
 											operations.push({
 												action: "create-branch",
@@ -1085,7 +1103,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 													repositoryPath,
 													"rev-parse",
 													"--verify",
-													`${execution.base}^{commit}`,
+													`${executionBase}^{commit}`,
 												],
 												{ captureOutput: true },
 											)
@@ -1266,9 +1284,17 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								taskPath: task.path,
 								phasePath,
 								codePath,
-								writablePath: join(codePath, execution.repo),
-								repo: execution.repo,
-								repos: execution.repos ?? [],
+								writablePath:
+									"review" in execution ? null : join(codePath, execution.repo),
+								reviewPath:
+									"review" in execution
+										? join(codePath, execution.review.repo)
+										: null,
+								repo:
+									"review" in execution
+										? execution.review.repo
+										: execution.repo,
+								repos: "review" in execution ? [] : (execution.repos ?? []),
 								dryRun: options.dryRun === true,
 								checkouts: checkoutReports,
 								operations,
@@ -1412,11 +1438,13 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 						}
 						const task = yield* tasks.show(taskId, root)
 
-						let execution: {
-							repo: string
-							repos?: readonly RepositoryReference[]
-							branch: string
-						}
+						let execution:
+							| {
+									repo: string
+									repos?: readonly RepositoryReference[]
+									branch: string
+							  }
+							| { review: { repo: string; commit: string } }
 						let codePath: string
 						if ("phases" in task.data) {
 							if (!phaseId) {
@@ -1450,10 +1478,18 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 						const expectedCheckouts: readonly (
 							| { readonly repo: string; readonly branch: string }
 							| RepositoryReference
-						)[] = [
-							{ repo: execution.repo, branch: execution.branch },
-							...(execution.repos ?? []),
-						]
+						)[] =
+							"review" in execution
+								? [
+										{
+											repo: execution.review.repo,
+											ref: execution.review.commit,
+										},
+									]
+								: [
+										{ repo: execution.repo, branch: execution.branch },
+										...(execution.repos ?? []),
+									]
 						const expectedAliases = expectedCheckouts.map(({ repo }) => repo)
 						if (codeDirectoryExists) {
 							const unmanaged = (yield* fs.readDirectory(codePath)).filter(

package/src/test-utils.ts

@@ -20,6 +20,7 @@ import { SyncService } from "./services/SyncService"
 import { ReadinessService } from "./services/ReadinessService"
 import { GraphMutationService } from "./services/GraphMutationService"
 import { DoctorService } from "./services/DoctorService"
+import { ReviewService } from "./services/ReviewService"
 
 export const createTempDir = () => mkdtemp(join(tmpdir(), "agency-test-"))
 
@@ -44,6 +45,7 @@ const TestLayer = Layer.mergeAll(
 	ReadinessService.Default,
 	GraphMutationService.Default,
 	DoctorService.Default,
+	ReviewService.Default,
 )
 
 export async function runTestEffect<A, E>(

package/src/work-view.ts

@@ -79,7 +79,11 @@ const rowFor = (
 	executions: readonly ExecutionNode[],
 ): WorkViewRow => {
 	const branches = [
-		...new Set(executions.map((execution) => execution.data.branch)),
+		...new Set(
+			executions.flatMap((execution) =>
+				"branch" in execution.data ? [execution.data.branch] : [],
+			),
+		),
 	]
 	const parent =
 		node.kind === "task"
@@ -105,16 +109,19 @@ const rowFor = (
 				: branches.length === 1
 					? branches[0]!
 					: "multiple",
-		pr: aggregateLabel(executions, (execution) => Boolean(execution.data.pr), [
-			"present",
-			"absent",
-		]),
+		pr: aggregateLabel(
+			executions,
+			(execution) => "pr" in execution.data && Boolean(execution.data.pr),
+			["present", "absent"],
+		),
 		worktree: aggregateLabel(
 			executions,
 			(execution) => execution.workspace?.materialized === true,
 			["materialized", "absent"],
 		),
-		hasPr: executions.some((execution) => Boolean(execution.data.pr)),
+		hasPr: executions.some(
+			(execution) => "pr" in execution.data && Boolean(execution.data.pr),
+		),
 	}
 }
 
@@ -213,6 +220,7 @@ export const getWorkViews = (options: WorkViewOptions = {}) =>
 				return executions.filter(
 					(execution) =>
 						execution.data.taskId === taskId &&
+						"phaseId" in execution.data &&
 						execution.data.phaseId === phaseId,
 				)
 			}

package/src/workbase/AGENTS.md

@@ -43,7 +43,8 @@ reason to edit `agency.json` or `repos/` by hand.
 Require explicit user intent before initializing a workbase; changing repository
 aliases or applying repository setup or workbase sync changes; launching another
 agent from an active agent session; creating a pull request; archiving, restoring,
-dropping, or reopening work; or using `--force` to override readiness.
+dropping, reopening, or completing work without a pull request; or using `--force`
+to override readiness.
 
 ## Safety
 
@@ -80,7 +81,9 @@ release the claim with the current document revision.
 An execution unit remains `working` after implementation is committed and while
 its pull request is open. It becomes `done` only after its authoritative pull
 request is merged and Agency reconciles that state. Do not mark committed or
-review-ready work `done` manually.
+review-ready work `done` manually. A genuine investigation, operational action,
+or no-change result may complete without a pull request only with explicit user
+intent, `--no-pull-request`, and a durable outcome summary.
 
 At each closeout trigger (creating or updating a PR, marking it ready, completing
 a refinement loop, or pausing or handing off completed implementation work):
@@ -90,6 +93,8 @@ a refinement loop, or pausing or handing off completed implementation work):
   keep the execution unit `working` through review and merge.
 - After merge, run `agency sync --apply` to reconcile the execution unit to
   `done`.
+- For an approved non-PR outcome, finish an active claim or update unclaimed
+  status with `--no-pull-request --summary <text>` and optional supporting URL.
 - Refresh durable delivery context in `TASK.md` or `PHASE.md`, including recorded
   PR state, current head, diff summary, and verification results after later
   pushes when those details are maintained there.

package/src/workbase/completion.ts

@@ -0,0 +1,28 @@
+import type { CompletionRecord } from "./schemas"
+
+export interface NonPrCompletionInput {
+	readonly summary: string
+	readonly evidenceUrl?: string
+}
+
+export const buildNonPrCompletion = (
+	input: NonPrCompletionInput,
+	now: Date,
+): { readonly value: CompletionRecord } | { readonly error: string } => {
+	const summary = input.summary.trim()
+	if (!summary) return { error: "Non-PR completion summary must not be empty" }
+
+	const evidenceUrl = input.evidenceUrl?.trim()
+	if (evidenceUrl && !/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(evidenceUrl)) {
+		return { error: `Invalid completion evidence URL: ${evidenceUrl}` }
+	}
+
+	return {
+		value: {
+			mode: "non-pr",
+			completedAt: now.toISOString(),
+			summary,
+			...(evidenceUrl ? { evidenceUrl } : {}),
+		},
+	}
+}

package/src/workbase/schemas.test.ts

@@ -64,6 +64,63 @@ describe("portable repository declarations", () => {
 })
 
 describe("body-of-work descriptions", () => {
+	test("decodes review tasks strictly and rejects writable execution fields", () => {
+		const review = {
+			ticketUrl: null,
+			review: {
+				repo: "agency",
+				source: { kind: "branch", ref: "refs/heads/feature/review" },
+				commit: "a".repeat(40),
+				refreshedAt: "2026-07-23T12:00:00.000Z",
+			},
+		}
+		expect(
+			Schema.decodeUnknownSync(TaskFrontmatter, { onExcessProperty: "error" })(
+				review,
+			),
+		).toMatchObject({ status: "open", review: review.review })
+		for (const field of ["repo", "repos", "branch", "base", "pr"]) {
+			expect(() =>
+				Schema.decodeUnknownSync(TaskFrontmatter, {
+					onExcessProperty: "error",
+				})({ ...review, [field]: field === "repos" ? [] : "forbidden" }),
+			).toThrow()
+		}
+	})
+
+	test("rejects inconsistent pull request source provenance", () => {
+		const source = {
+			kind: "pull-request",
+			provider: "github",
+			repository: "owner/repo",
+			identifier: "42",
+			url: "https://github.com/owner/repo/pull/42",
+			fetchRef: "refs/pull/42/head",
+		}
+		const review = {
+			ticketUrl: null,
+			review: {
+				repo: "agency",
+				source,
+				commit: "a".repeat(40),
+				refreshedAt: "2026-07-23T12:00:00.000Z",
+			},
+		}
+		expect(Schema.decodeUnknownSync(TaskFrontmatter)(review)).toBeDefined()
+		for (const inconsistent of [
+			{ ...source, url: "https://github.com/owner/repo/pull/41" },
+			{ ...source, repository: "other/repo" },
+			{ ...source, fetchRef: "refs/pull/41/head" },
+		]) {
+			expect(() =>
+				Schema.decodeUnknownSync(TaskFrontmatter)({
+					...review,
+					review: { ...review.review, source: inconsistent },
+				}),
+			).toThrow()
+		}
+	})
+
 	test("accepts descriptions on epics, tasks, and phases", () => {
 		const epic = Schema.decodeUnknownSync(EpicFrontmatter)({
 			ticketUrl: "https://example.com/epic",

package/src/workbase/schemas.ts

@@ -43,6 +43,8 @@ const IsoTimestamp = NonEmptyString.pipe(
 	Schema.pattern(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/),
 )
 
+const GitCommit = Schema.String.pipe(Schema.pattern(/^[a-f0-9]{40}$/))
+
 const DocumentRevision = Schema.String.pipe(Schema.pattern(/^[a-f0-9]{64}$/))
 
 export const ClaimRecord = Schema.Struct({
@@ -75,6 +77,13 @@ export const PullRequestRecord = Schema.Struct({
 	mergeable: Schema.optional(Schema.NullOr(Schema.Boolean)),
 })
 
+export const CompletionRecord = Schema.Struct({
+	mode: Schema.Literal("non-pr"),
+	completedAt: IsoTimestamp,
+	summary: NonEmptyString,
+	evidenceUrl: Schema.optional(Url),
+})
+
 const DeliveryProvider = Schema.Struct({
 	provider: EntityId,
 	remote: Schema.optional(NonEmptyString),
@@ -141,6 +150,7 @@ const ExecutionUnit = {
 	pr: Schema.NullOr(Schema.Union(GitHubPullRequestUrl, PullRequestRecord)),
 	status: Schema.optionalWith(WorkStatus, { default: () => "open" as const }),
 	claim: Schema.optional(ClaimRecord),
+	completion: Schema.optional(CompletionRecord),
 }
 
 export const EpicFrontmatter = Schema.Struct({
@@ -164,9 +174,61 @@ const MultiPhaseTaskFrontmatter = Schema.Struct({
 	phases: Schema.Array(Dependency),
 })
 
+export const ReviewPullRequestSource = Schema.Struct({
+	kind: Schema.Literal("pull-request"),
+	provider: Schema.Literal("github"),
+	repository: NonEmptyString,
+	identifier: NonEmptyString.pipe(Schema.pattern(/^\d+$/)),
+	url: GitHubPullRequestUrl,
+	fetchRef: NonEmptyString,
+}).pipe(
+	Schema.filter(
+		(source) =>
+			source.url ===
+				`https://github.com/${source.repository}/pull/${source.identifier}` &&
+			source.fetchRef === `refs/pull/${source.identifier}/head`,
+		{
+			message: () =>
+				"Pull request review source URL, repository, identifier, and fetch ref must agree",
+		},
+	),
+)
+
+export const ReviewBranchSource = Schema.Struct({
+	kind: Schema.Literal("branch"),
+	ref: NonEmptyString.pipe(
+		Schema.pattern(
+			/^refs\/heads\/(?!HEAD$)(?!.*(?:\.\.|@\{|[ ~^:?*\[\\\]]))(?!.*\/\/)(?!.*(?:^|\/)\.)(?!.*\/$)(?!.*\.lock(?:\/|$))[A-Za-z0-9._\/-]+$/,
+		),
+	),
+})
+
+export const ReviewSource = Schema.Union(
+	ReviewPullRequestSource,
+	ReviewBranchSource,
+)
+
+export const ReviewRecord = Schema.Struct({
+	repo: RepositoryAlias,
+	source: ReviewSource,
+	commit: GitCommit,
+	refreshedAt: IsoTimestamp,
+})
+
+const ReviewTaskFrontmatter = Schema.Struct({
+	ticketUrl: Schema.NullOr(Url),
+	description: Description,
+	epic: Schema.optional(EntityId),
+	review: ReviewRecord,
+	status: Schema.optionalWith(WorkStatus, { default: () => "open" as const }),
+	claim: Schema.optional(ClaimRecord),
+	completion: Schema.optional(CompletionRecord),
+})
+
 export const TaskFrontmatter = Schema.Union(
 	SinglePhaseTaskFrontmatter,
 	MultiPhaseTaskFrontmatter,
+	ReviewTaskFrontmatter,
 )
 
 export const PhaseFrontmatter = Schema.Struct({
@@ -187,6 +249,9 @@ export type RepositoryDeclaration = Schema.Schema.Type<
 export type WorkStatus = Schema.Schema.Type<typeof WorkStatus>
 export type ClaimRecord = Schema.Schema.Type<typeof ClaimRecord>
 export type PullRequestRecord = Schema.Schema.Type<typeof PullRequestRecord>
+export type ReviewSource = Schema.Schema.Type<typeof ReviewSource>
+export type ReviewRecord = Schema.Schema.Type<typeof ReviewRecord>
+export type CompletionRecord = Schema.Schema.Type<typeof CompletionRecord>
 export type EpicFrontmatter = Schema.Schema.Type<typeof EpicFrontmatter>
 export type TaskFrontmatter = Schema.Schema.Type<typeof TaskFrontmatter>
 export type PhaseFrontmatter = Schema.Schema.Type<typeof PhaseFrontmatter>