@markjaquith/agency 3.1.1 → 3.2.1

package/README.md

@@ -1028,7 +1028,7 @@ until restored.
 
 ```text
 agency work [<directory> | --epic <epic-id>] [--agent <name>] [--auto] [--print-command]
-agency work prepare [target] [--evidence <json-or-path>] [--dry-run] [--json]
+agency work prepare [target] [--evidence <json-or-path>] [--force] [--dry-run] [--json]
 agency worktree <list|inspect|prepare|remove|rebuild|repair>
 agency push [--json]
 agency pr create <task-id> [phase-id] [--draft] [--title <title>] [--head <branch>] [--base <branch>] [--label <label>] [--force] [--json]
@@ -1062,9 +1062,11 @@ work and reading context. It does not prescribe how callers present or execute
 prepared work.
 The evidence argument may be an evidence object, task-creation JSON, or a path to
 either. Use `--dry-run` to report planned fetch, branch, and worktree changes
-without applying them. Validation reuse never skips readiness, active-claim,
-repository, ownership, reference-drift, dirty-workspace, or worktree safety
-checks.
+without applying them. Use `--force` to prepare work blocked by readiness, such
+as a follow-on phase whose dependency is still active; preparation still does
+not launch an agent or change lifecycle status. Validation reuse never skips
+readiness, active-claim, repository, ownership, reference-drift, dirty-workspace,
+or worktree safety checks.
 
 The authoritative implementation locations for this contract are
 `src/commands/task.ts` (creation output),

package/package.json

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

package/src/cli-parser.test.ts

@@ -397,9 +397,11 @@ describe("strict CLI parsing", () => {
 			commandName: "work",
 			values: { force: true },
 		})
-		expect(() => parseCli(["work", "prepare", "example", "--force"])).toThrow(
-			"cannot be combined",
-		)
+		expect(parseCli(["work", "prepare", "example", "--force"])).toMatchObject({
+			commandName: "work",
+			args: ["prepare", "example"],
+			values: { force: true },
+		})
 	})
 
 	test("preserves every argument after pr without parsing it", () => {

package/src/cli-parser.ts

@@ -917,7 +917,7 @@ const commands = {
 	},
 	work: {
 		usage:
-			"agency work [<directory-or-task-id> | --epic <epic-id>] [--agent <name>] [--auto] | agency work prepare [target] [--dry-run] [--json]",
+			"agency work [<directory-or-task-id> | --epic <epic-id>] [--agent <name>] [--auto] | agency work prepare [target] [--force] [--dry-run] [--json]",
 		options: {
 			...commonOptions,
 			...entitySelectorOptions,
@@ -933,7 +933,7 @@ const commands = {
 		},
 		command: {
 			usage:
-				"agency work [<directory-or-task-id> | --epic <epic-id>] [--agent <name>] [--auto] | agency work prepare [target] [--dry-run] [--json]",
+				"agency work [<directory-or-task-id> | --epic <epic-id>] [--agent <name>] [--auto] | agency work prepare [target] [--force] [--dry-run] [--json]",
 			minArgs: 0,
 			maxArgs: 2,
 			options: [
@@ -1691,8 +1691,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 					parsed.values.claude ||
 					parsed.values.agent ||
 					parsed.values.auto ||
-					parsed.values["print-command"] ||
-					parsed.values.force))
+					parsed.values["print-command"]))
 		) {
 			throw usageError(
 				preparing

package/src/cli.test.ts

@@ -1310,7 +1310,12 @@ status: open
 					...process.env,
 					...contract.environment,
 					XDG_CONFIG_HOME: isolatedConfigHome,
+					OPENCODE_DISABLE_AUTOUPDATE: "1",
 					OPENCODE_DISABLE_EXTERNAL_SKILLS: "1",
+					OPENCODE_DISABLE_MODELS_FETCH: "1",
+					OPENCODE_CONFIG_CONTENT: JSON.stringify({
+						model: "opencode/big-pickle",
+					}),
 				}
 				const probe = Bun.spawnSync(["opencode", "debug", "agent", "build"], {
 					cwd: contract.cwd,
@@ -1409,7 +1414,9 @@ status: open
 				...process.env,
 				PATH: `${agencyBin}:${process.env.PATH ?? ""}`,
 				XDG_CONFIG_HOME: isolatedConfigHome,
+				OPENCODE_DISABLE_AUTOUPDATE: "1",
 				OPENCODE_DISABLE_EXTERNAL_SKILLS: "1",
+				OPENCODE_DISABLE_MODELS_FETCH: "1",
 			}
 			delete directEnvironment.OPENCODE_CONFIG
 			delete directEnvironment.OPENCODE_CONFIG_CONTENT
@@ -1480,6 +1487,7 @@ status: open
 				env: {
 					...directEnvironment,
 					OPENCODE_CONFIG_CONTENT: JSON.stringify({
+						model: "opencode/big-pickle",
 						permission: { external_directory: { "*": "deny" } },
 					}),
 				},
@@ -1578,7 +1586,7 @@ status: open
 				graph.nodes.find((node: any) => node.id === "task:pipeline").status,
 			).toBe("working")
 		},
-		180_000,
+		360_000,
 	)
 
 	test("envelopes help and version output in machine mode", async () => {

package/src/commands/context.test.ts

@@ -282,6 +282,20 @@ status: dropped
 	})
 
 	test("reads each workbase document at most once per invocation", async () => {
+		const unrelatedArchive = join(root, "archive/tasks/unrelated/TASK.md")
+		await write(
+			root,
+			"archive/tasks/unrelated/TASK.md",
+			`---
+ticketUrl: null
+repo: agency
+branch: unrelated
+base: main
+pr: null
+status: done
+---
+`,
+		)
 		const reads = new Map<string, number>()
 		const originalFile = Bun.file
 		Bun.file = mock((path: string) => {
@@ -304,6 +318,48 @@ status: dropped
 		)
 		expect(documents.length).toBeGreaterThan(0)
 		expect(documents.every(([, count]) => count === 1)).toBe(true)
+		expect(reads.has(unrelatedArchive)).toBe(false)
+	})
+
+	test("limits repository inspection and overlaps independent Git observations", async () => {
+		const commands: string[][] = []
+		let activeGitCommands = 0
+		let maxActiveGitCommands = 0
+		const originalSpawn = Bun.spawn
+		;(Bun as { spawn: unknown }).spawn = mock(((
+			args: string[],
+			options: Parameters<typeof Bun.spawn>[1],
+		) => {
+			const command = [...args]
+			const child = originalSpawn(command, options)
+			if (command[0] !== "git") return child
+			commands.push(command)
+			activeGitCommands += 1
+			maxActiveGitCommands = Math.max(maxActiveGitCommands, activeGitCommands)
+			const exited = child.exited.finally(() => {
+				activeGitCommands -= 1
+			})
+			return new Proxy(child, {
+				get(target, property) {
+					return property === "exited"
+						? exited
+						: Reflect.get(target, property, target)
+				},
+			})
+		}) as unknown as typeof Bun.spawn)
+		try {
+			await readContext(root, "tasks/agent-contract/phases/context-command")
+		} finally {
+			;(Bun as { spawn: unknown }).spawn = originalSpawn
+		}
+
+		expect(
+			commands.some(
+				(command) =>
+					command.includes("config") && command.includes("--show-origin"),
+			),
+		).toBe(false)
+		expect(maxActiveGitCommands).toBeGreaterThanOrEqual(3)
 	})
 
 	test("resolves a bare task ID and returns root discovery context", async () => {

package/src/commands/work.test.ts

@@ -569,6 +569,49 @@ describe("work command", () => {
 		).rejects.toThrow("Recalled repository conflicts")
 	})
 
+	test("force prepares a phase blocked by an active dependency without launching or changing status", async () => {
+		const blocked = createHarness({
+			workspace: multiPhaseWorkspace,
+			multiPhaseTasks: ["example"],
+			guardError: new Error("Phase dependency is working"),
+		})
+		await expect(
+			blocked.runPrepare({
+				cwd: "/workbase",
+				taskId: "example",
+				phaseId: "implementation",
+			}),
+		).rejects.toThrow("Phase dependency is working")
+		expect(blocked.events).toEqual(["guard"])
+
+		const forced = createHarness({
+			workspace: multiPhaseWorkspace,
+			multiPhaseTasks: ["example"],
+			guardError: new Error("Phase dependency is working"),
+		})
+		await forced.runPrepare({
+			cwd: "/workbase",
+			taskId: "example",
+			phaseId: "implementation",
+			force: true,
+			silent: true,
+		})
+
+		expect(forced.guards).toEqual([
+			{
+				target: "execution-unit:phase/example/implementation",
+				override: true,
+			},
+		])
+		expect(forced.events).toEqual(["guard", "materialize"])
+		expect(forced.materializeOptions[0]).toMatchObject({
+			force: true,
+			validationAlreadyPerformed: true,
+		})
+		expect(forced.launches).toEqual([])
+		expect(forced.statusUpdates).toEqual([])
+	})
+
 	test("launches an epic agent from an epic directory", async () => {
 		const harness = createHarness()
 

package/src/commands/work.ts

@@ -577,7 +577,7 @@ export const workPrepare = (options: WorkOptions = {}) =>
 
 export const help = `
 Usage: agency work [<directory-or-task-id> | --epic <epic-id>] [--agent <name>] [--auto]
-       agency work prepare [target] [--evidence <json-or-path>] [--dry-run] [--json]
+       agency work prepare [target] [--evidence <json-or-path>] [--force] [--dry-run] [--json]
 
 Launch an agent for an epic, task, or phase. With no directory, select one
 interactively. A positional argument resolves as a directory first, then as a task
@@ -592,7 +592,8 @@ changes without fetching, creating branches, or creating worktrees.
 It emits revision-bound validation evidence and an idempotent external-orchestrator
 contract. Evidence is reused only while the target, workbase, configuration, and
 repository mapping remain unchanged. Dynamic readiness and workspace safety checks
-always run.
+always run. With prepare, --force overrides readiness without launching or changing
+lifecycle status.
 
 Options:
   --epic <id>          Work on an epic
@@ -605,8 +606,8 @@ Options:
   --print-command      Print cwd, argv, and non-secret environment without launch
   --opencode           Require the OpenCode preset
   --claude             Require the Claude Code preset
-  --force              Override readiness; reopen terminal execution units
-	--evidence <value>   Validation evidence JSON or a path to JSON (prepare only)
+  --force              Override readiness; launched terminal work is reopened
+  --evidence <value>   Validation evidence JSON or a path to JSON (prepare only)
   --no-input           Never open an interactive selector
 
 Without interactive input, provide an explicit workbase or cwd and an entity

package/src/services/ContextService.ts

@@ -271,78 +271,57 @@ export class ContextService extends Effect.Service<ContextService>()(
 
 					if (relative(root, candidate) === "") {
 						const compact = !options.full
-						const discover = <S extends Schema.Schema.AnyNoContext>(
-							id: string,
-							path: string,
-							schema: S,
+						const validation = yield* provideContextServices(
+							workbase.validate(root, { includeDocuments: true }),
+						)
+						const projectDiscoveryDocument = <T>(
+							document: {
+								readonly id: string
+								readonly path: string
+								readonly content: string
+								readonly revision: string
+								readonly data: T
+							},
 							extra: Record<string, string> = {},
 						) =>
 							Effect.gen(function* () {
-								if (!(yield* fs.exists(path))) return null
-								const content = yield* fs.readFile(path)
-								const parsed = yield* Effect.either(
-									parseFrontmatter(content, path),
-								)
-								if (Either.isLeft(parsed)) return null
-								const decoded = decode(schema, parsed.right.data)
-								if (!decoded.ok) return null
+								const body = compact
+									? {}
+									: {
+											body: (yield* parseFrontmatter(
+												document.content,
+												document.path,
+											)).body,
+										}
 								return {
 									...extra,
-									id,
-									path,
-									sha256: documentRevision(content),
-									data: decoded.value,
-									...(compact ? {} : { body: parsed.right.body }),
+									id: document.id,
+									path: document.path,
+									sha256: document.revision,
+									data: document.data,
+									...body,
 								}
 							})
-
-						const epics: unknown[] = []
-						const tasks: unknown[] = []
-						const phases: unknown[] = []
-						const epicRoot = join(root, "epics")
-						if (yield* fs.isDirectory(epicRoot)) {
-							for (const entry of (yield* fs.readDirectory(epicRoot))
-								.filter((item) => item.isDirectory)
-								.sort((a, b) => a.name.localeCompare(b.name))) {
-								const document = yield* discover(
-									entry.name,
-									join(epicRoot, entry.name, "EPIC.md"),
-									EpicFrontmatter,
-								)
-								if (document) epics.push(document)
-							}
-						}
-
-						const taskRoot = join(root, "tasks")
-						if (yield* fs.isDirectory(taskRoot)) {
-							for (const entry of (yield* fs.readDirectory(taskRoot))
-								.filter((item) => item.isDirectory)
-								.sort((a, b) => a.name.localeCompare(b.name))) {
-								const document = yield* discover(
-									entry.name,
-									join(taskRoot, entry.name, "TASK.md"),
-									TaskFrontmatter,
-								)
-								if (document) tasks.push(document)
-
-								const phaseRoot = join(taskRoot, entry.name, "phases")
-								if (!(yield* fs.isDirectory(phaseRoot))) continue
-								for (const phaseEntry of (yield* fs.readDirectory(phaseRoot))
-									.filter((item) => item.isDirectory)
-									.sort((a, b) => a.name.localeCompare(b.name))) {
-									const phase = yield* discover(
-										phaseEntry.name,
-										join(phaseRoot, phaseEntry.name, "PHASE.md"),
-										PhaseFrontmatter,
-										{ taskId: entry.name },
-									)
-									if (phase) phases.push(phase)
-								}
-							}
-						}
-
-						const validation = yield* provideContextServices(
-							workbase.validate(root),
+						const documents = validation.documents!
+						const epics = yield* Effect.all(
+							documents.epics.map((document) =>
+								projectDiscoveryDocument(document),
+							),
+							{ concurrency: "unbounded" },
+						)
+						const tasks = yield* Effect.all(
+							documents.tasks.map((document) =>
+								projectDiscoveryDocument(document),
+							),
+							{ concurrency: "unbounded" },
+						)
+						const phases = yield* Effect.all(
+							[...documents.phasesByTask].flatMap(([taskId, records]) =>
+								records.map((document) =>
+									projectDiscoveryDocument(document, { taskId }),
+								),
+							),
+							{ concurrency: "unbounded" },
 						)
 						return {
 							projection: compact ? "compact" : "complete",
@@ -556,104 +535,74 @@ export class ContextService extends Effect.Service<ContextService>()(
 						})
 					}
 
-					const taskDocuments = new Map<string, Document<TaskData>>()
+					const validation = yield* provideContextServices(
+						workbase.validate(root, { includeDocuments: true }),
+					)
+					const validationDocuments = validation.documents!
+					const taskDocuments = new Map<string, Document<TaskData>>(
+						validationDocuments.tasks.map((document) => [
+							document.id,
+							{
+								id: document.id,
+								path: document.path,
+								sha256: document.revision,
+								data: document.data,
+								body: "",
+							},
+						]),
+					)
 					const phaseDocuments = new Map<string, Document<PhaseData>>()
-					for (const taskRoot of [
-						join(root, "tasks"),
-						join(root, "archive", "tasks"),
-					]) {
-						if (!(yield* fs.isDirectory(taskRoot))) continue
-						const entries = (yield* fs.readDirectory(taskRoot))
-							.filter((entry) => entry.isDirectory)
-							.sort((a, b) => a.name.localeCompare(b.name))
-						const documents = yield* Effect.all(
-							entries.map((entry) =>
-								Effect.gen(function* () {
-									const path = join(taskRoot, entry.name, "TASK.md")
-									let taskDocument: Document<TaskData> | null = null
-									if (yield* fs.exists(path)) {
-										const content = yield* fs.readFile(path)
-										const parsed = yield* Effect.either(
-											parseFrontmatter(content, path),
-										)
-										if (Either.isRight(parsed)) {
-											const decoded = decode(TaskFrontmatter, parsed.right.data)
-											if (decoded.ok) {
-												taskDocument = {
-													id: entry.name,
-													path,
-													sha256: documentRevision(content),
-													data: decoded.value,
-													body: parsed.right.body,
-												}
-											}
-										}
-									}
-
-									const phasesPath = join(taskRoot, entry.name, "phases")
-									if (!(yield* fs.isDirectory(phasesPath))) {
-										return { taskDocument, phaseDocuments: [] }
-									}
-									const phaseEntries = (yield* fs.readDirectory(phasesPath))
-										.filter((item) => item.isDirectory)
-										.sort((a, b) => a.name.localeCompare(b.name))
-									const childDocuments = yield* Effect.all(
-										phaseEntries.map((phaseEntry) =>
-											Effect.gen(function* () {
-												const phasePath = join(
-													phasesPath,
-													phaseEntry.name,
-													"PHASE.md",
-												)
-												if (!(yield* fs.exists(phasePath))) return null
-												const content = yield* fs.readFile(phasePath)
-												const parsed = yield* Effect.either(
-													parseFrontmatter(content, phasePath),
-												)
-												if (Either.isLeft(parsed)) return null
-												const decoded = decode(
-													PhaseFrontmatter,
-													parsed.right.data,
-												)
-												if (!decoded.ok) return null
-												return [
-													`${entry.name}/${phaseEntry.name}`,
-													{
-														id: phaseEntry.name,
-														path: phasePath,
-														sha256: documentRevision(content),
-														data: decoded.value,
-														body: parsed.right.body,
-													},
-												] as const
-											}),
-										),
-										{ concurrency: "unbounded" },
-									)
-									return {
-										taskDocument,
-										phaseDocuments: childDocuments.filter(
-											(document): document is NonNullable<typeof document> =>
-												document !== null,
-										),
-									}
-								}),
-							),
-							{ concurrency: "unbounded" },
-						)
+					for (const [taskId, documents] of validationDocuments.phasesByTask) {
 						for (const document of documents) {
-							if (
-								document.taskDocument &&
-								!taskDocuments.has(document.taskDocument.id)
-							) {
-								taskDocuments.set(
-									document.taskDocument.id,
-									document.taskDocument,
-								)
-							}
-							for (const [key, phaseDocument] of document.phaseDocuments) {
-								if (!phaseDocuments.has(key))
-									phaseDocuments.set(key, phaseDocument)
+							phaseDocuments.set(`${taskId}/${document.id}`, {
+								id: document.id,
+								path: document.path,
+								sha256: document.revision,
+								data: document.data,
+								body: "",
+							})
+						}
+					}
+					if (task && !taskDocuments.has(task.id))
+						taskDocuments.set(task.id, task)
+					if (phase && target.taskId) {
+						phaseDocuments.set(`${target.taskId}/${phase.id}`, phase)
+					}
+					const relevantTaskIds = new Set([
+						...(target.taskId ? [target.taskId] : []),
+						...(epic?.data.tasks.map((child: Dependency) => child.id) ?? []),
+					])
+					for (const taskId of relevantTaskIds) {
+						let document = taskDocuments.get(taskId)
+						if (!document) {
+							const archived = yield* Effect.either(
+								readOptionalDocument(
+									taskId,
+									join(archivedTaskDirectory(root, taskId), "TASK.md"),
+									TaskFrontmatter,
+								),
+							)
+							document = Either.isRight(archived)
+								? (archived.right ?? undefined)
+								: undefined
+							if (document) taskDocuments.set(taskId, document)
+						}
+						if (!document || !("phases" in document.data)) continue
+						for (const child of document.data.phases) {
+							const key = `${taskId}/${child.id}`
+							if (phaseDocuments.has(key)) continue
+							const archived = yield* Effect.either(
+								readOptionalDocument(
+									child.id,
+									join(
+										archivedPhaseDirectory(root, taskId, child.id),
+										"PHASE.md",
+									),
+									PhaseFrontmatter,
+								),
+							)
+							if (Either.isRight(archived) && archived.right) {
+								phaseDocuments.set(key, archived.right)
 							}
 						}
 					}
@@ -720,9 +669,6 @@ export class ContextService extends Effect.Service<ContextService>()(
 						})
 					}
 
-					const validation = yield* provideContextServices(
-						workbase.validate(root),
-					)
 					const relevantPaths = new Set<string>(
 						[epic?.path, task?.path, phase?.path]
 							.filter((path): path is string => Boolean(path))
@@ -1017,9 +963,11 @@ export class ContextService extends Effect.Service<ContextService>()(
 					const codePath = join(entityDirectory, "code")
 					const inspectionWarnings: string[] = []
 					const repositories = new Map(
-						(yield* provideContextServices(repositoryService.list(root))).map(
-							(repository) => [repository.alias, repository],
-						),
+						reviewData
+							? (yield* provideContextServices(
+									repositoryService.list(root),
+								)).map((repository) => [repository.alias, repository])
+							: [],
 					)
 
 					const inspectCheckout = (
@@ -1027,12 +975,18 @@ export class ContextService extends Effect.Service<ContextService>()(
 						checkoutPath: string,
 					) =>
 						Effect.gen(function* (): Generator<any, CheckoutInspection, any> {
-							const materialized = yield* fs.isDirectory(checkoutPath)
-							const listed = yield* runGit(fs, repositoryPath, [
-								"worktree",
-								"list",
-								"--porcelain",
-							])
+							const [materialized, listed, canonicalRoot] = yield* Effect.all(
+								[
+									fs.isDirectory(checkoutPath),
+									runGit(fs, repositoryPath, [
+										"worktree",
+										"list",
+										"--porcelain",
+									]),
+									fs.realPath(root),
+								],
+								{ concurrency: "unbounded" },
+							)
 							if (listed === null) {
 								inspectionWarnings.push(
 									`Unable to inspect worktree registrations for ${repositoryPath}`,
@@ -1040,7 +994,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 							}
 							const listedPaths = worktreePaths(listed)
 							const canonicalCheckoutPath = join(
-								yield* fs.realPath(root),
+								canonicalRoot,
 								relative(root, checkoutPath),
 							)
 							let registered =
@@ -1056,21 +1010,25 @@ export class ContextService extends Effect.Service<ContextService>()(
 									dirty: null,
 								}
 							}
-							const checkoutCommit = yield* runGit(fs, checkoutPath, [
-								"rev-parse",
-								"HEAD",
-							])
-							const checkoutBranch = yield* runGit(fs, checkoutPath, [
-								"symbolic-ref",
-								"--quiet",
-								"--short",
-								"HEAD",
-							])
-							const checkoutStatus = yield* runGitText(fs, checkoutPath, [
-								"status",
-								"--porcelain",
-							])
-							const resolvedCheckoutPath = yield* fs.realPath(checkoutPath)
+							const [
+								checkoutCommit,
+								checkoutBranch,
+								checkoutStatus,
+								resolvedCheckoutPath,
+							] = yield* Effect.all(
+								[
+									runGit(fs, checkoutPath, ["rev-parse", "HEAD"]),
+									runGit(fs, checkoutPath, [
+										"symbolic-ref",
+										"--quiet",
+										"--short",
+										"HEAD",
+									]),
+									runGitText(fs, checkoutPath, ["status", "--porcelain"]),
+									fs.realPath(checkoutPath),
+								],
+								{ concurrency: "unbounded" },
+							)
 							registered = registered || listedPaths.has(resolvedCheckoutPath)
 							if (checkoutCommit === null) {
 								inspectionWarnings.push(
@@ -1094,17 +1052,16 @@ export class ContextService extends Effect.Service<ContextService>()(
 								const repositoryPath =
 									repository?.path ?? join(root, "repos", executionData.repo)
 								const checkoutPath = join(codePath, executionData.repo)
-								const branchCommit = yield* backend.resolveRevision(
-									repositoryPath,
-									executionData.branch,
-								)
-								const baseCommit = yield* backend.resolveRevision(
-									repositoryPath,
-									executionData.base,
-								)
-								const checkout = yield* inspectCheckout(
-									repositoryPath,
-									checkoutPath,
+								const [branchCommit, baseCommit, checkout] = yield* Effect.all(
+									[
+										backend.resolveRevision(
+											repositoryPath,
+											executionData.branch,
+										),
+										backend.resolveRevision(repositoryPath, executionData.base),
+										inspectCheckout(repositoryPath, checkoutPath),
+									],
+									{ concurrency: "unbounded" },
 								)
 								if (branchCommit === null) {
 									inspectionWarnings.push(