@markjaquith/agency 2.53.0 → 2.54.0

package/README.md

@@ -489,9 +489,10 @@ materializations, then compares every execution declaration with local branch
 and worktree registration, checkout dirtiness, resolved reference commits, claim
 expiry, and pull request state, merge state, and mergeability. It reports
 structured `changes`, `warnings`, `unresolved`, and per-execution evidence. The
-default and `--dry-run` modes are observational.
+default mode applies safe reconciliation transitions; `--dry-run` is explicitly
+observational.
 
-`agency sync --apply` performs only these safe transitions:
+`agency sync` performs only these safe transitions:
 
 - materialize declared but missing repositories from their canonical remotes;
 - adopt legacy materializations only when they have an unambiguous portable origin;
@@ -722,7 +723,7 @@ 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.
 By default, `done` requires an authoritative merged pull request and is applied
-by `agency sync --apply`. Work whose intended outcome genuinely requires no pull
+by `agency sync`. 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

package/cli-main.ts

@@ -694,7 +694,6 @@ const commands: Record<string, Command> = {
 			}
 			await runCommand(
 				sync({
-					apply: options.apply,
 					dryRun: options["dry-run"],
 					json: options.json,
 					silent: options.silent,

package/fixtures/protocol/orchestration-recipes.json

@@ -30,7 +30,7 @@
   ["work", "prepare", "--task", "checkout", "--phase", "ui", "--json"],
   ["work", "tasks/checkout/phases/ui", "--runner", "opencode"],
   ["sync", "--dry-run", "--json"],
-  ["sync", "--apply", "--json"],
+  ["sync", "--json"],
   ["pr", "create", "checkout", "ui", "--json"],
   [
     "finish",

package/package.json

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

package/src/cli-parser.test.ts

@@ -371,18 +371,16 @@ describe("strict CLI parsing", () => {
 		})
 	})
 
-	test("parses reconciliation modes and rejects conflicting modes", () => {
-		expect(parseCli(["sync", "--dry-run", "--json"])).toMatchObject({
+	test("parses explicit dry-run reconciliation", () => {
+		expect(parseCli(["sync"])).toMatchObject({
 			commandName: "sync",
-			values: { "dry-run": true, json: true },
+			values: {},
 		})
-		expect(parseCli(["sync", "--apply"])).toMatchObject({
+		expect(parseCli(["sync", "--dry-run", "--json"])).toMatchObject({
 			commandName: "sync",
-			values: { apply: true },
+			values: { "dry-run": true, json: true },
 		})
-		expect(() => parseCli(["sync", "--dry-run", "--apply"])).toThrow(
-			"cannot be combined",
-		)
+		expect(() => parseCli(["sync", "--apply"])).toThrow("Unknown option")
 	})
 
 	test("accepts archive dry-run", () => {

package/src/cli-parser.ts

@@ -678,18 +678,16 @@ const commands = {
 		},
 	},
 	sync: {
-		usage: "agency sync [--dry-run | --apply] [--json]",
+		usage: "agency sync [--dry-run] [--json]",
 		options: {
 			...outputOptions,
 			"dry-run": { type: "boolean" },
-			apply: { type: "boolean" },
 		},
 		command: {
-			usage: "agency sync [--dry-run | --apply] [--json]",
+			usage: "agency sync [--dry-run] [--json]",
 			minArgs: 0,
 			maxArgs: 0,
-			options: ["dry-run", "apply", "json"],
-			conflicts: [["dry-run", "apply"]],
+			options: ["dry-run", "json"],
 		},
 	},
 	archive: {

package/src/commands/claim.ts

@@ -117,6 +117,6 @@ export const finishHelp = `
 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. Use
+working; agency sync marks the execution unit done after merge. Use
 --no-pull-request with a summary for an explicit non-PR completion.
 `

package/src/commands/sync.test.ts

@@ -0,0 +1,100 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { mkdir } from "node:fs/promises"
+import { join } from "node:path"
+import { TaskService } from "../services/TaskService"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
+import { sync } from "./sync"
+
+const git = async (args: string[], cwd: string) => {
+	const process = Bun.spawn(["git", ...args], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	})
+	await process.exited
+	if (process.exitCode !== 0) {
+		throw new Error(await new Response(process.stderr).text())
+	}
+}
+
+describe("sync command", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		const source = join(root, "source")
+		await mkdir(source)
+		await git(["init", "--initial-branch=main"], source)
+		await git(["config", "user.email", "test@example.com"], source)
+		await git(["config", "user.name", "Test"], source)
+		await Bun.write(join(source, "README.md"), "example\n")
+		await git(["add", "README.md"], source)
+		await git(["-c", "commit.gpgsign=false", "commit", "-m", "initial"], source)
+		await mkdir(join(root, "repos"))
+		await git(["clone", "--bare", source, join(root, "repos/agency")], root)
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "example",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	test("applies safe reconciliation by default", async () => {
+		const logs = await captureLogs(() => runTestEffect(sync({ cwd: root })))
+
+		expect(
+			await Bun.file(join(root, "tasks/example/code/agency/README.md")).text(),
+		).toBe("example\n")
+		expect(logs).toContainEqual(
+			expect.stringContaining("Applied materialize-workspace 'task:example'"),
+		)
+		expect(() => JSON.parse(logs.join("\n"))).toThrow()
+	})
+
+	test("keeps explicit dry-run observational", async () => {
+		await runTestEffect(sync({ cwd: root, dryRun: true, silent: true }))
+
+		expect(
+			await Bun.file(
+				join(root, "tasks/example/code/agency/README.md"),
+			).exists(),
+		).toBe(false)
+	})
+
+	test("preserves structured output behind --json", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(sync({ cwd: root, dryRun: true, json: true })),
+		)
+
+		expect(logs).toHaveLength(1)
+		expect(JSON.parse(logs[0]!)).toMatchObject({
+			mode: "dry-run",
+			changes: [
+				expect.objectContaining({
+					kind: "materialize-workspace",
+					status: "planned",
+				}),
+			],
+		})
+	})
+})

package/src/commands/sync.ts

@@ -4,7 +4,6 @@ import type { BaseCommandOptions } from "../utils/command"
 import { createLoggers } from "../utils/effect"
 
 interface SyncCommandOptions extends BaseCommandOptions {
-	readonly apply?: boolean
 	readonly dryRun?: boolean
 }
 
@@ -14,24 +13,62 @@ export const sync = (options: SyncCommandOptions = {}) =>
 		const { log } = createLoggers(options)
 		const result = yield* service.reconcile({
 			cwd: options.cwd,
-			apply: options.apply === true,
+			apply: options.dryRun !== true,
 		})
-		log(JSON.stringify(result, null, 2))
+		if (options.json) return log(JSON.stringify(result, null, 2))
+
+		for (const action of result.repositories.actions) {
+			log(
+				`${action.status === "applied" ? "Applied" : "Planned"} repository ${action.kind} '${action.alias}' from ${action.remote}`,
+			)
+		}
+		for (const change of result.changes) {
+			log(
+				`${change.status === "applied" ? "Applied" : "Planned"} ${change.kind} '${change.target}': ${change.message}`,
+			)
+		}
+		for (const warning of result.warnings) {
+			log(
+				`Warning '${warning.target}': ${warning.message}${warning.action ? `. ${warning.action}` : ""}`,
+			)
+		}
+		for (const issue of result.repositories.unresolved) {
+			log(
+				`Unresolved repository '${issue.alias}': ${issue.message}. ${issue.action}`,
+			)
+		}
+		for (const issue of result.unresolved) {
+			log(
+				`Unresolved '${issue.target}': ${issue.message}${issue.action ? `. ${issue.action}` : ""}`,
+			)
+		}
+		if (
+			result.repositories.actions.length === 0 &&
+			result.changes.length === 0 &&
+			result.warnings.length === 0 &&
+			result.repositories.unresolved.length === 0 &&
+			result.unresolved.length === 0
+		) {
+			log(
+				result.mode === "apply"
+					? "Workbase sync is current"
+					: "Workbase sync plan is current",
+			)
+		}
 	})
 
 export const help = `
-Usage: agency sync [--dry-run | --apply] [--json]
+Usage: agency sync [--dry-run] [--json]
 
 Compare portable repository declarations and execution state with local Git
 repositories, worktrees, branches, references, claims, and pull requests.
-Dry-run is the default.
+Safe reconciliation transitions are applied by default.
 
 Options:
   --dry-run                 Report planned safe transitions without changing state
-  --apply                   Apply safe reconciliation transitions
   --json                    Output one versioned machine result
 
-Apply may materialize declared repositories and unambiguous missing checkouts,
+Sync may materialize declared repositories and unambiguous missing checkouts,
 adopt legacy repositories with portable origins, release expired claims,
 record a uniquely matched PR, and mark merged work done. Dirty, stale, or
 conflicting checkouts are always left unresolved.

package/src/services/IntegrationService.test.ts

@@ -282,7 +282,7 @@ describe("IntegrationService", () => {
 		expect(body).toMatch(/completing\s+a refinement loop/)
 		expect(body).toContain("pausing or handing off")
 		expect(body).toContain("`agency finish`")
-		expect(body).toContain("`agency sync --apply`")
+		expect(body).toContain("`agency sync`")
 		expect(body).toContain("`--no-pull-request --summary <text>`")
 		expect(body).toContain("`TASK.md` or `PHASE.md`")
 		expect(body).toContain("PR state, current head, diff summary")

package/src/services/PhaseService.ts

@@ -654,7 +654,7 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 						if (validStatus === "done") {
 							return yield* new PhaseError({
 								message:
-									"Work becomes done after its authoritative pull request is merged; run 'agency sync --apply', or explicitly complete a non-PR outcome with '--no-pull-request --summary <text>'",
+									"Work becomes done after its authoritative pull request is merged; run 'agency sync', or explicitly complete a non-PR outcome with '--no-pull-request --summary <text>'",
 							})
 						}
 						return yield* new PhaseError({

package/src/services/TaskService.ts

@@ -381,7 +381,7 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					if (validStatus === "done") {
 						return yield* new TaskError({
 							message:
-								"Work becomes done after its authoritative pull request is merged; run 'agency sync --apply', or explicitly complete a non-PR outcome with '--no-pull-request --summary <text>'",
+								"Work becomes done after its authoritative pull request is merged; run 'agency sync', or explicitly complete a non-PR outcome with '--no-pull-request --summary <text>'",
 						})
 					}
 					return yield* new TaskError({

package/src/workbase/AGENTS.md

@@ -91,7 +91,7 @@ a refinement loop, or pausing or handing off completed implementation work):
 - Finish an active claim with the current revision via `agency finish`; a
   successful claim outcome leaves unmerged work `working`. For unclaimed work,
   keep the execution unit `working` through review and merge.
-- After merge, run `agency sync --apply` to reconcile the execution unit to
+- After merge, run `agency sync` 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.