@markjaquith/agency 2.49.0 → 2.51.0

package/README.md

@@ -2,13 +2,14 @@
 
 Agency manages durable agentic work across repositories. Epics, tasks, and
 phases live as Markdown documents in a filesystem-backed workbase. Repository
-aliases and Git worktrees provide each execution unit with the code it may read
-or write.
+aliases and managed workspaces provide each execution unit with the code it may
+read or write.
 
 ## Requirements
 
 - [Bun](https://bun.sh) 1.0 or newer
 - Git
+- [Jujutsu](https://jj-vcs.github.io/jj/) is preferred when available
 - [GitHub CLI](https://cli.github.com/) for `agency pr create`
 - OpenCode, Claude Code, or a configured runner for `agency work`
 
@@ -122,14 +123,15 @@ The plugin grants whole-workbase access dynamically, while the portable
 reference advertises that context to agents. Bash and Agency operations must
 still follow the write authority reported by `agency context`.
 
-Repository aliases and canonical fetch remotes are declared in tracked
-`agency.json`; local bare clones and symlinks remain ignored under
+Repository aliases, the version-control backend, and canonical fetch remotes are
+declared in tracked `agency.json`; local clones and symlinks remain ignored under
 `repos/{alias}`. A declaration contains no local path, symlink target, checkout,
 or credential:
 
 ```json
 {
 	"version": 2,
+	"vcs": "jj",
 	"repositories": {
 		"frontend": {
 			"remote": "git@example.com:team/frontend.git"
@@ -138,6 +140,29 @@ or credential:
 }
 ```
 
+New workbases select `"jj"` when the `jj` executable is available and otherwise
+select `"git"`. Existing version 2 workbases without `vcs` remain Git workbases.
+The selected backend is a workbase-level invariant: jj workbases initialize
+managed clones with `jj git init` and create jj workspaces, while Git workbases
+continue to use Git worktrees.
+
+Inspect the current backend and migration readiness with:
+
+```bash
+agency vcs status
+agency vcs migrate jj          # dry-run
+agency vcs migrate jj --apply
+agency vcs migrate git --apply
+```
+
+Migration is workbase-wide and transactional. Agency locks every execution
+unit, requires clean registered workspaces, blocks active claims and working or
+delegated units, converts repository metadata, recreates checkout paths with the
+target backend, and updates `agency.json` last. Migration from jj to Git also
+blocks jj-only heads that are not preserved by a bookmark or workspace. Failed
+migrations restore the source repositories and workspaces when rollback is
+possible and report explicit manual recovery paths otherwise.
+
 Existing version 2 workbases without `repositories` remain valid. Run
 `agency repo setup` to preview deterministic adoption of legacy local aliases;
 `agency repo setup --apply` writes declarations only when a portable origin is
@@ -146,7 +171,7 @@ creation command.
 
 ### Custom Worktree Command
 
-By default, Agency creates worktrees with Git. Set `worktreeCreateCommand` to an
+Git workbases create worktrees with Git. Set `worktreeCreateCommand` to an
 argv template when another tool should create writable worktrees:
 
 ```json
@@ -205,9 +230,10 @@ Custom commands own writable branch creation. Agency checks for conflicting
 worktrees first, invokes the command only when the branch is not checked out,
 and verifies that `{worktree}` exists afterward.
 
-The configured command applies only to the writable checkout. Supplemental
-read-only repositories remain detached Git worktrees at their declared refs so
-they do not acquire writable branches.
+The configured command applies only to the writable checkout of a Git workbase.
+Supplemental read-only repositories remain detached Git worktrees at their
+declared refs so they do not acquire writable branches. Jj workbases always use
+jj workspaces and ignore this Git-specific customization.
 
 ### Agent Runners
 
@@ -589,6 +615,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 +817,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,15 @@ 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 {
+	GitVersionControlService,
+	JjVersionControlService,
+	VersionControlService,
+} from "./src/services/VersionControlService"
+import { review, help as reviewHelp } from "./src/commands/review"
+import { vcs, help as vcsHelp } from "./src/commands/vcs"
+import { VcsMigrationService } from "./src/services/VcsMigrationService"
 import {
 	claimCommand,
 	claimHelp,
@@ -60,6 +69,10 @@ import {
 const CliLayer = Layer.mergeAll(
 	FileSystemService.Default,
 	WorkbaseService.Default,
+	GitVersionControlService.Default,
+	JjVersionControlService.Default,
+	VersionControlService.Default,
+	VcsMigrationService.Default,
 	RepositoryService.Default,
 	EpicService.Default,
 	TaskService.Default,
@@ -75,6 +88,7 @@ const CliLayer = Layer.mergeAll(
 	ReadinessService.Default,
 	GraphMutationService.Default,
 	DoctorService.Default,
+	ReviewService.Default,
 )
 
 /**
@@ -449,6 +463,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 +494,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) {
@@ -525,6 +558,26 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	vcs: {
+		run: async (args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(vcsHelp)
+				return
+			}
+			await runCommand(
+				vcs({
+					subcommand: args[0],
+					target: args[1],
+					apply: options.apply,
+					dryRun: options["dry-run"],
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+					cwd: options.cwd,
+				}),
+			)
+		},
+	},
 	next: {
 		run: async (_args: string[], options: Record<string, any>) => {
 			if (options.help) return console.log(nextHelp)
@@ -680,9 +733,11 @@ Commands:
   archive <type>         Archive a work item
   task <subcommand>      Manage tasks
   work [directory|task]  Work on an epic, task, or phase
-  worktree <subcommand>  Inspect and maintain managed worktrees
+  worktree <subcommand>  Inspect and maintain managed workspaces
+  vcs <subcommand>       Inspect or migrate the version-control backend
   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.51.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

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

@@ -22,6 +22,7 @@
       "required": ["version"],
       "properties": {
         "version": { "const": 2 },
+        "vcs": { "enum": ["git", "jj"] },
         "root": { "type": "string" }
       }
     },
@@ -176,6 +177,7 @@
             { "$ref": "#/$defs/epicData" },
             { "$ref": "#/$defs/singleTaskData" },
             { "$ref": "#/$defs/multiTaskData" },
+            { "$ref": "#/$defs/reviewTaskData" },
             { "$ref": "#/$defs/phaseData" },
             { "$ref": "#/$defs/executionData" },
             { "$ref": "#/$defs/repositoryData" }
@@ -220,7 +222,8 @@
               "data": {
                 "oneOf": [
                   { "$ref": "#/$defs/singleTaskData" },
-                  { "$ref": "#/$defs/multiTaskData" }
+                  { "$ref": "#/$defs/multiTaskData" },
+                  { "$ref": "#/$defs/reviewTaskData" }
                 ]
               },
               "workspace": { "$ref": "#/$defs/documentWorkspace" },
@@ -358,34 +361,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 +437,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 +551,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()
@@ -509,6 +571,25 @@ describe("strict CLI parsing", () => {
 		)
 	})
 
+	test("parses VCS status and migration commands", () => {
+		expect(parseCli(["vcs", "status", "--json"])).toMatchObject({
+			commandName: "vcs",
+			args: ["status"],
+			values: { json: true },
+		})
+		expect(
+			parseCli(["vcs", "migrate", "jj", "--apply", "--json"]),
+		).toMatchObject({
+			commandName: "vcs",
+			args: ["migrate", "jj"],
+			values: { apply: true, json: true },
+		})
+		expectUsageError(["vcs", "migrate"], "agency vcs migrate")
+		expect(() =>
+			parseCli(["vcs", "migrate", "jj", "--dry-run", "--apply"]),
+		).toThrow("cannot be combined")
+	})
+
 	test("accepts runner selection and command inspection for work", () => {
 		expect(
 			parseCli([