@markjaquith/agency 3.4.2 → 3.5.0

package/package.json

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

package/src/cli-parser.ts

@@ -665,14 +665,14 @@ const commands = {
 		},
 	},
 	sync: {
-		usage: "agency sync [<task-id> [phase-id]] [--dry-run] [--json]",
+		usage: "agency sync [<task-id|path> [phase-id]] [--dry-run] [--json]",
 		options: {
 			...outputOptions,
 			...entitySelectorOptions,
 			"dry-run": { type: "boolean" },
 		},
 		command: {
-			usage: "agency sync [<task-id> [phase-id]] [--dry-run] [--json]",
+			usage: "agency sync [<task-id|path> [phase-id]] [--dry-run] [--json]",
 			minArgs: 0,
 			maxArgs: 2,
 			options: ["dry-run", "json", "task", "phase"],

package/src/commands/sync.ts

@@ -122,13 +122,14 @@ export const sync = (
 	})
 
 export const help = `
-Usage: agency sync [<task-id> [phase-id]] [--dry-run] [--json]
+Usage: agency sync [<task-id|path> [phase-id]] [--dry-run] [--json]
 
 Compare portable repository declarations and execution state with local Git
 repositories, worktrees, branches, references, and pull requests.
 Safe reconciliation transitions are applied by default.
-When a task or phase is provided, only that target and its repositories are
-queried or reconciled. Task scope includes all phases of a multi-phase task.
+When a task, phase, or item path is provided, only that target and its
+repositories are queried or reconciled. Task and epic scopes include their
+child execution units.
 
 Options:
   --dry-run                 Report planned safe transitions without changing state

package/src/services/SyncService.ts

@@ -1,5 +1,5 @@
 import { Data, Effect, Either } from "effect"
-import { dirname, join, resolve } from "node:path"
+import { dirname, join, relative, resolve, sep } from "node:path"
 import type {
 	PhaseFrontmatter,
 	RepositoryReference,
@@ -228,7 +228,17 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 				const worktrees = yield* WorktreeService
 				const repositories = yield* RepositoryService
 				const versionControl = yield* VersionControlService
-				const { root, config } = yield* workbase.loadConfig(options.cwd)
+				const cwd = resolve(options.cwd ?? process.cwd())
+				const candidate = options.taskId
+					? resolve(cwd, options.taskId)
+					: undefined
+				const candidateExists =
+					candidate !== undefined && !options.phaseId
+						? yield* fs.exists(candidate)
+						: false
+				const { root, config } = yield* workbase.loadConfig(
+					candidateExists ? candidate : cwd,
+				)
 				const backend = yield* versionControl.forWorkbase(root)
 				const validation = yield* workbase.validate(root, {
 					includeDocuments: true,
@@ -246,20 +256,49 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 					})
 				}
 				const documents = validation.documents!
+				let taskId = options.taskId
+				let phaseId = options.phaseId
+				let epicId: string | undefined
+				const existingTaskSelector =
+					options.taskId !== undefined &&
+					documents.tasks.some((task) => task.id === options.taskId)
+				if (candidateExists && candidate && !existingTaskSelector) {
+					const canonicalPath = yield* fs.realPath(candidate)
+					const canonicalRoot = yield* fs.realPath(root)
+					const parts = relative(canonicalRoot, canonicalPath).split(sep)
+					if (parts[0] === "epics" && parts[1]) {
+						epicId = parts[1]
+						taskId = undefined
+					} else if (parts[0] === "tasks" && parts[1]) {
+						taskId = parts[1]
+						phaseId = parts[2] === "phases" && parts[3] ? parts[3] : undefined
+					} else {
+						return yield* new SyncError({
+							message: `Sync path does not identify an active task, phase, or epic: ${canonicalPath}`,
+						})
+					}
+				}
+				if (epicId && !documents.epics.some((epic) => epic.id === epicId)) {
+					return yield* new SyncError({
+						message: `Epic '${epicId}' does not exist`,
+					})
+				}
 				const allTaskRecords = documents.tasks
-				const taskRecords = options.taskId
-					? allTaskRecords.filter((task) => task.id === options.taskId)
-					: allTaskRecords
-				if (options.taskId && taskRecords.length === 0) {
+				const taskRecords = taskId
+					? allTaskRecords.filter((task) => task.id === taskId)
+					: epicId
+						? allTaskRecords.filter((task) => task.data.epic === epicId)
+						: allTaskRecords
+				if (taskId && taskRecords.length === 0) {
 					return yield* new SyncError({
-						message: `Task '${options.taskId}' does not exist`,
+						message: `Task '${taskId}' does not exist`,
 					})
 				}
 				const records: ExecutionRecord[] = []
 				for (const task of taskRecords) {
 					if ("phases" in task.data) {
 						for (const phase of documents.phasesByTask.get(task.id) ?? []) {
-							if (options.phaseId && phase.id !== options.phaseId) continue
+							if (phaseId && phase.id !== phaseId) continue
 							records.push({
 								key: `phase:${task.id}/${phase.id}`,
 								taskId: task.id,
@@ -270,7 +309,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 								data: phase.data,
 							})
 						}
-					} else if (!options.phaseId && !("review" in task.data)) {
+					} else if (!phaseId && !("review" in task.data)) {
 						records.push({
 							key: `task:${task.id}`,
 							taskId: task.id,
@@ -281,12 +320,12 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 						})
 					}
 				}
-				const reviewRecords = options.phaseId
+				const reviewRecords = phaseId
 					? []
 					: taskRecords.filter((task) => "review" in task.data)
-				if (options.phaseId && records.length === 0) {
+				if (phaseId && records.length === 0) {
 					return yield* new SyncError({
-						message: `Phase '${options.taskId}/${options.phaseId}' does not exist`,
+						message: `Phase '${taskId}/${phaseId}' does not exist`,
 					})
 				}
 				const repositoryAliases = new Set<string>()
@@ -299,10 +338,15 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 					if ("review" in task.data)
 						repositoryAliases.add(task.data.review.repo)
 				}
+				if (epicId) {
+					const epic = documents.epics.find((record) => record.id === epicId)!
+					for (const reference of epic.data.repos)
+						repositoryAliases.add(reference.repo)
+				}
 				const repositorySetup = yield* repositories.setup({
 					cwd: root,
 					apply: options.apply === true,
-					...(options.taskId ? { aliases: [...repositoryAliases] } : {}),
+					...(taskId || epicId ? { aliases: [...repositoryAliases] } : {}),
 				})
 				options.onProgress?.({
 					stage: "repositories",