@markjaquith/agency 2.48.1 → 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.
@@ -610,7 +630,8 @@ Inspect tasks:
 ```text
 agency task list [filters] [--json]
 agency task show <id> [--json]
-agency task status <id> <open|working|dropped> [--json]
+agency task status <id> <open|working|done|dropped>
+  [--no-pull-request --summary <text> [--evidence-url <url>]] [--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]
@@ -649,7 +670,8 @@ 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|working|dropped> [--json]
+agency phase status <task-id> <phase-id> <open|working|done|dropped>
+  [--no-pull-request --summary <text> [--evidence-url <url>]] [--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>
@@ -672,8 +694,12 @@ 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. Running `agency work` again can relaunch unclaimed `working` work.
-The `done` status is reserved for an authoritative merged pull request and is
-applied by `agency sync --apply`, not by task or phase status commands.
+By default, `done` requires an authoritative merged pull request and is applied
+by `agency sync --apply`. Work whose intended outcome genuinely requires no pull
+request may instead use an explicit `--no-pull-request --summary <text>` status
+transition. Agency records the summary, completion time, and optional evidence
+URL durably; reopening removes that evidence. This exceptional path refuses work
+that already has a recorded pull request.
 Use explicit claims only when an external orchestrator needs coordinated
 ownership. The interactive work selector displays status markers before
 execution units. Existing working and delegated work may be released to `open`
@@ -704,15 +730,19 @@ agency claim <task-id> [phase-id] --claimant <id> --runner <id>
 agency release <task-id> [phase-id] --session-id <id>
   --revision <sha256> [--json]
 agency finish <task-id> [phase-id] --session-id <id>
-  --revision <sha256> --outcome <done|dropped> [--json]
+  --revision <sha256> --outcome <done|dropped>
+  [--no-pull-request --summary <text> [--evidence-url <url>]] [--json]
 ```
 
 An active claim sets status to `working`. Release returns it to `open`. Finish
 records the claim outcome and ownership history; a `done` claim outcome leaves
 the execution unit `working` until its pull request is merged, while `dropped`
-remains terminal. Conflicts return the current revision and complete ownership
-record in the machine error envelope rather than overwriting it. Expired claims
-may be replaced with a revision-guarded claim.
+remains terminal. For a genuine non-PR outcome, `--no-pull-request` atomically
+records completion evidence, finishes the claim, and sets the execution unit to
+`done`; `--summary` is required and `--evidence-url` is optional. Conflicts return
+the current revision and complete ownership record in the machine error envelope
+rather than overwriting it. Expired claims may be replaced with a
+revision-guarded claim.
 
 `agency work` does not claim execution units. It refuses active explicit claims,
 marks open execution work `working`, and launches the runner. External
@@ -761,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,
 )
 
 /**
@@ -205,6 +208,9 @@ const commands: Record<string, Command> = {
 					sessionId: options["session-id"],
 					revision: options.revision,
 					outcome: options.outcome,
+					noPullRequest: options["no-pull-request"],
+					summary: options.summary,
+					evidenceUrl: options["evidence-url"],
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
@@ -298,6 +304,9 @@ const commands: Record<string, Command> = {
 					clearReferences: options["clear-references"],
 					prUrl: options["pr-url"],
 					clearPr: options["clear-pr"],
+					noPullRequest: options["no-pull-request"],
+					summary: options.summary,
+					evidenceUrl: options["evidence-url"],
 					ifRevision: options["if-revision"],
 					dependsOn: options["depends-on"],
 					firstPhase: options["first-phase"],
@@ -443,12 +452,18 @@ 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,
 					clearReferences: options["clear-references"],
 					prUrl: options["pr-url"],
 					clearPr: options["clear-pr"],
+					noPullRequest: options["no-pull-request"],
+					summary: options.summary,
+					evidenceUrl: options["evidence-url"],
 					ifRevision: options["if-revision"],
 					noEpic: options["no-epic"],
 					multiPhase: options["multi-phase"],
@@ -468,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) {
@@ -674,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.48.1",
+  "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()
@@ -362,6 +424,64 @@ describe("strict CLI parsing", () => {
 				"working",
 			]),
 		).toThrow("must be 'done' or 'dropped'")
+		expect(
+			parseCli([
+				"finish",
+				"task",
+				"--session-id",
+				"job-1",
+				"--revision",
+				revision,
+				"--outcome",
+				"done",
+				"--no-pull-request",
+				"--summary",
+				"Investigation completed",
+				"--evidence-url",
+				"https://example.com/result",
+			]),
+		).toMatchObject({
+			values: {
+				"no-pull-request": true,
+				summary: "Investigation completed",
+				"evidence-url": "https://example.com/result",
+			},
+		})
+		expect(() =>
+			parseCli([
+				"finish",
+				"task",
+				"--session-id",
+				"job-1",
+				"--revision",
+				revision,
+				"--outcome",
+				"done",
+				"--no-pull-request",
+			]),
+		).toThrow("--summary' is required")
+		expect(() =>
+			parseCli([
+				"task",
+				"status",
+				"example",
+				"working",
+				"--no-pull-request",
+				"--summary",
+				"Not done",
+			]),
+		).toThrow("valid only with a done status")
+		expect(() =>
+			parseCli([
+				"phase",
+				"status",
+				"task",
+				"phase",
+				"done",
+				"--summary",
+				"Missing explicit flag",
+			]),
+		).toThrow("require '--no-pull-request'")
 	})
 
 	test("accepts valid mutation revisions and rejects malformed hashes", () => {