@markjaquith/agency 3.2.14 → 3.3.0

package/README.md

@@ -1033,12 +1033,29 @@ 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. 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
+without applying them. Validation reuse never skips
 readiness, repository, ownership, reference-drift, dirty-workspace, or worktree
 safety checks.
 
+Both `work` and `work prepare` accept `--allow-working-dependencies` with an
+explicit execution-unit target (task ID, directory, or `--task` with optional
+`--phase`). This narrowly admits an `open` unit whose blockers are exclusively
+dependencies with status `working`. Open, delegated, dropped, or missing
+dependencies and mixed validation/status blockers remain blocked; terminal
+targets cannot be reopened. Ready and normally resumable working units retain
+their existing behavior. Interactive target selection, orchestration targets,
+and combining this option with `--force` are rejected. Validation,
+repository/reference checks, dirty-worktree protections, and active worktree
+locks are unchanged, including in dry-run mode.
+
+Preparation never launches or changes status. Its `commands.work.argv` preserves
+the explicit opt-in, but validation evidence does not store it or authorize later
+calls: pass the flag again for each prepare/work invocation. Dependency changes
+invalidate evidence normally, and readiness and locks are checked again even
+when evidence is reused. Execution identity and evidence schemas are unchanged.
+The existing broader `--force` behavior, including lock overrides and reopening
+terminal work on launch, is unchanged for callers using it alone.
+
 The authoritative implementation locations for this contract are
 `src/commands/task.ts` (creation output),
 `src/workbase/execution-contract.ts` (evidence and execution schemas),

package/cli-main.ts

@@ -533,6 +533,7 @@ const commands: Record<string, Command> = {
 					auto: options.auto,
 					printCommand: options["print-command"],
 					force: options.force,
+					allowWorkingDependencies: options["allow-working-dependencies"],
 					inputAllowed: options.inputAllowed,
 					cwd: options.cwd,
 					taskId: options.task,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "3.2.14",
+  "version": "3.3.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",
@@ -22,10 +22,15 @@
     "cli.ts",
     "cli-main.ts",
     "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/test-utils.ts",
     "pi-extensions",
+    "!pi-extensions/**/*.test.ts",
     "scripts/install-pi-extension.ts",
     "schemas",
-    "fixtures/protocol",
+    "fixtures/protocol/success.json",
+    "fixtures/protocol/error.json",
     "README.md",
     "LICENSE"
   ],

package/src/cli-parser.ts

@@ -845,6 +845,7 @@ const commands = {
 			opencode: { type: "boolean" },
 			claude: { type: "boolean" },
 			force: { type: "boolean" },
+			"allow-working-dependencies": { type: "boolean" },
 			evidence: { type: "string" },
 		},
 		command: {
@@ -865,12 +866,14 @@ const commands = {
 				"claude",
 				"force",
 				"evidence",
+				"allow-working-dependencies",
 			],
 			conflicts: [
 				["opencode", "claude"],
 				["agent", "opencode"],
 				["agent", "claude"],
 				["epic", "$positional"],
+				["force", "allow-working-dependencies"],
 			],
 		},
 	},
@@ -1618,6 +1621,16 @@ export function parseCli(args: readonly string[]): ParsedCli {
 				spec.usage,
 			)
 		}
+		if (
+			parsed.values["allow-working-dependencies"] &&
+			(parsed.values.epic ||
+				(!parsed.values.task && !commandPositionals[preparing ? 1 : 0]))
+		) {
+			throw usageError(
+				"Option '--allow-working-dependencies' requires an explicit execution-unit target (task ID, directory, or --task with optional --phase).",
+				spec.usage,
+			)
+		}
 		if (
 			(!preparing && commandPositionals.length > 1) ||
 			(preparing &&

package/src/commands/work.ts

@@ -49,6 +49,7 @@ export interface WorkOptions extends BaseCommandOptions {
 	readonly printCommand?: boolean
 	readonly auto?: boolean
 	readonly force?: boolean
+	readonly allowWorkingDependencies?: boolean
 	readonly evidence?: string
 }
 
@@ -93,6 +94,22 @@ export const work = (
 	pickBase: PickWorkbase = pickWorkbase,
 ) =>
 	Effect.gen(function* () {
+		if (options.allowWorkingDependencies && options.force) {
+			return yield* Effect.fail(
+				new Error("Cannot combine --force with --allow-working-dependencies"),
+			)
+		}
+		if (
+			options.allowWorkingDependencies &&
+			!options.directory &&
+			!options.taskId
+		) {
+			return yield* Effect.fail(
+				new Error(
+					"--allow-working-dependencies requires an explicit execution-unit target",
+				),
+			)
+		}
 		if (
 			(options.opencode && options.claude) ||
 			(options.agent && (options.opencode || options.claude))
@@ -201,6 +218,13 @@ export const work = (
 		}
 
 		if (!target) {
+			if (options.allowWorkingDependencies) {
+				return yield* Effect.fail(
+					new Error(
+						"--allow-working-dependencies requires an explicit execution-unit target",
+					),
+				)
+			}
 			if (!inputAllowed) {
 				return yield* Effect.fail(
 					new Error(
@@ -237,7 +261,24 @@ export const work = (
 			target = yield* pick(choices, config.chooserCommand)
 			if (!target) return
 		}
-		yield* readiness.guardWorkTarget(targetNodeId(target), root, options.force)
+		if (
+			options.allowWorkingDependencies &&
+			(target.kind === "epic" || (target.kind === "task" && target.multiPhase))
+		) {
+			return yield* Effect.fail(
+				new Error(
+					"--allow-working-dependencies requires an execution-unit target",
+				),
+			)
+		}
+		yield* readiness.guardWorkTarget(
+			targetNodeId(target),
+			root,
+			options.force,
+			{
+				allowWorkingDependencies: options.allowWorkingDependencies,
+			},
+		)
 		const validationAlreadyPerformed = !options.force
 
 		const continuing =
@@ -427,6 +468,22 @@ export const work = (
 
 export const workPrepare = (options: WorkOptions = {}) =>
 	Effect.gen(function* () {
+		if (options.allowWorkingDependencies && options.force) {
+			return yield* Effect.fail(
+				new Error("Cannot combine --force with --allow-working-dependencies"),
+			)
+		}
+		if (
+			options.allowWorkingDependencies &&
+			!options.directory &&
+			!options.taskId
+		) {
+			return yield* Effect.fail(
+				new Error(
+					"--allow-working-dependencies requires an explicit execution-unit target",
+				),
+			)
+		}
 		const fs = yield* FileSystemService
 		const workbase = yield* WorkbaseService
 		const tasks = yield* TaskService
@@ -538,7 +595,9 @@ export const workPrepare = (options: WorkOptions = {}) =>
 				})
 			}
 		}
-		yield* readiness.guardWorkTarget(target, root, options.force)
+		yield* readiness.guardWorkTarget(target, root, options.force, {
+			allowWorkingDependencies: options.allowWorkingDependencies,
+		})
 		const workspace = yield* worktrees.materialize(taskId, phaseId, root, {
 			...options,
 			dryRun: options.dryRun,
@@ -571,6 +630,7 @@ export const workPrepare = (options: WorkOptions = {}) =>
 				checkoutPath: workspace.writablePath ?? workspace.reviewPath,
 				documentRevision: document.revision,
 				dryRun: options.dryRun === true,
+				allowWorkingDependencies: options.allowWorkingDependencies,
 			}),
 		}
 		if (options.json) {
@@ -602,6 +662,13 @@ repository mapping remain unchanged. Dynamic readiness and workspace safety chec
 always run. With prepare, --force overrides readiness without launching or changing
 lifecycle status.
 
+For an explicit execution-unit target, --allow-working-dependencies admits open
+work blocked only by dependencies whose status is working. It does not override
+validation, lifecycle, or workspace safety checks and cannot be combined with
+--force or interactive target selection. Ready and resumable working targets keep
+their normal behavior. Preparation includes the opt-in in commands.work; validation
+evidence does not grant it to later calls.
+
 Options:
   --epic <id>          Work on an epic
   --task <id>          Work on a task
@@ -614,6 +681,7 @@ Options:
   --opencode           Require the OpenCode preset
   --claude             Require the Claude Code preset
   --force              Override readiness; launched terminal work is reopened
+  --allow-working-dependencies  Allow only working dependency blockers
   --evidence <value>   Validation evidence JSON or a path to JSON (prepare only)
   --no-input           Never open an interactive selector
 

package/src/services/ReadinessService.ts

@@ -175,8 +175,16 @@ export class ReadinessService extends Effect.Service<ReadinessService>()(
 				target: string,
 				cwd: string = process.cwd(),
 				override = false,
+				options: { readonly allowWorkingDependencies?: boolean } = {},
 			) =>
 				Effect.gen(function* () {
+					if (override && options.allowWorkingDependencies) {
+						return yield* Effect.fail(
+							new Error(
+								"Cannot combine --force with --allow-working-dependencies",
+							),
+						)
+					}
 					const graphs = yield* GraphService
 					const graph = yield* graphs.get({ cwd })
 					const node = graph.nodes.find((candidate) => candidate.id === target)
@@ -192,6 +200,18 @@ export class ReadinessService extends Effect.Service<ReadinessService>()(
 						})
 					}
 					if (override) return
+					if (
+						options.allowWorkingDependencies &&
+						node.kind === "execution-unit" &&
+						node.status === "open" &&
+						!node.readiness.terminal &&
+						node.readiness.blockers.length > 0 &&
+						node.readiness.blockers.every(
+							(blocker) =>
+								blocker.kind === "dependency" && blocker.status === "working",
+						)
+					)
+						return
 					if (!node.readiness.ready && !isResumableWork(node)) {
 						const item = {
 							key: node.key,

package/src/workbase/execution-contract.ts

@@ -267,6 +267,7 @@ export const buildExecutionContract = (input: {
 	readonly checkoutPath?: string | null
 	readonly documentRevision: string
 	readonly dryRun: boolean
+	readonly allowWorkingDependencies?: boolean
 }) => {
 	const executionDirectory = dirname(input.phasePath ?? input.taskPath)
 	const key = digest({
@@ -308,7 +309,15 @@ export const buildExecutionContract = (input: {
 		commands: {
 			work: {
 				cwd: executionDirectory,
-				argv: ["agency", "work", ".", "--auto"],
+				argv: [
+					"agency",
+					"work",
+					".",
+					"--auto",
+					...(input.allowWorkingDependencies
+						? ["--allow-working-dependencies"]
+						: []),
+				],
 			},
 			context: {
 				cwd: executionDirectory,

package/src/workbase/schemas.ts

@@ -42,6 +42,18 @@ export const WorkStatus = Schema.Literal(
 
 const IsoTimestamp = NonEmptyString.pipe(
 	Schema.pattern(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/),
+	Schema.filter(
+		(value) => {
+			const timestamp = Date.parse(value)
+			return (
+				Number.isFinite(timestamp) &&
+				new Date(timestamp).toISOString() === value
+			)
+		},
+		{
+			message: () => "Expected a canonical ISO-8601 timestamp",
+		},
+	),
 )
 
 const GitCommit = Schema.String.pipe(Schema.pattern(/^[a-f0-9]{40}$/))

package/fixtures/protocol/orchestration-recipes.json

@@ -1,53 +0,0 @@
-[
-  ["context", "--task", "checkout", "--phase", "ui", "--json"],
-  ["worktree", "inspect", "checkout", "ui", "--json"],
-  ["next", "--json"],
-  ["graph", "--ready", "--json"],
-  [
-    "task",
-    "create",
-    "investigate-checkout",
-    "--purpose",
-    "investigation",
-    "--repo",
-    "agency",
-    "--json"
-  ],
-  [
-    "task",
-    "handoff",
-    "investigate-checkout",
-    "implement-checkout",
-    "--repo",
-    "agency",
-    "--json"
-  ],
-  [
-    "work",
-    "prepare",
-    "--task",
-    "checkout",
-    "--phase",
-    "ui",
-    "--dry-run",
-    "--json"
-  ],
-  ["work", "prepare", "--task", "checkout", "--phase", "ui", "--json"],
-  ["work", "tasks/checkout/phases/ui", "--agent", "opencode"],
-  ["sync", "--dry-run", "--json"],
-  ["sync", "--json"],
-  [
-    "task",
-    "status",
-    "implement-checkout",
-    "done",
-    "--no-pull-request",
-    "--summary",
-    "Completed without a pull request",
-    "--json"
-  ],
-  ["pr", "create", "checkout", "ui", "--json"],
-  ["sync", "checkout", "ui", "--json"],
-  ["doctor", "--json"],
-  ["worktree", "repair", "checkout", "ui", "--dry-run", "--json"]
-]

package/pi-extensions/agency.test.ts

@@ -1,117 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test"
-import { mkdir } from "node:fs/promises"
-import { join } from "node:path"
-import { cleanupTempDir, createTempDir } from "../src/test-utils"
-import agencyExtension from "./agency"
-
-describe("global Pi extension", () => {
-	let root: string
-
-	beforeEach(async () => {
-		root = await createTempDir()
-	})
-
-	afterEach(async () => cleanupTempDir(root))
-
-	const load = (response?: object) => {
-		const handlers = new Map<string, (...args: any[]) => any>()
-		const pi = {
-			exec: async () => ({
-				code: response ? 0 : 1,
-				stdout: response ? JSON.stringify(response) : "",
-				stderr: "",
-			}),
-			on: (name: string, handler: (...args: any[]) => any) => {
-				handlers.set(name, handler)
-			},
-		}
-		agencyExtension(pi as never)
-		return handlers
-	}
-
-	test("no-ops outside Agency workbases without invoking the CLI", async () => {
-		let executions = 0
-		const handlers = new Map<string, (...args: any[]) => any>()
-		agencyExtension({
-			exec: async () => {
-				executions += 1
-				return { code: 1, stdout: "", stderr: "" }
-			},
-			on: (name: string, handler: (...args: any[]) => any) => {
-				handlers.set(name, handler)
-			},
-		} as never)
-
-		expect(
-			await handlers.get("resources_discover")?.({ cwd: root }),
-		).toBeUndefined()
-		expect(
-			await handlers.get("before_agent_start")?.(
-				{ systemPrompt: "Base" },
-				{ cwd: root },
-			),
-		).toBeUndefined()
-		expect(executions).toBe(0)
-	})
-
-	test("uses CLI context from nested directories for skills and authority", async () => {
-		const task = join(root, "tasks", "example")
-		const nested = join(task, "code", "agency", "src")
-		const checkout = join(task, "code", "agency")
-		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
-		await mkdir(join(root, ".agency"), { recursive: true })
-		await Bun.write(
-			join(root, ".agency", "AGENTS.md"),
-			"# Managed instructions\n",
-		)
-		await mkdir(join(checkout, ".agents", "skills"), { recursive: true })
-		await mkdir(nested, { recursive: true })
-
-		const handlers = load({
-			ok: true,
-			result: {
-				workbase: { root },
-				target: {
-					kind: "task",
-					taskId: "example",
-					path: join(task, "TASK.md"),
-				},
-				authority: { mode: "execution", writable: { checkoutPath: checkout } },
-				documents: { task: { data: { status: "working" } } },
-				validation: { valid: true },
-			},
-		})
-		const resources = await handlers.get("resources_discover")?.({
-			cwd: nested,
-		})
-		expect(resources.skillPaths).toEqual([join(checkout, ".agents", "skills")])
-
-		const prompt = await handlers.get("before_agent_start")?.(
-			{ systemPrompt: "Base" },
-			{ cwd: nested },
-		)
-		expect(prompt.systemPrompt).toContain("# Managed instructions")
-		expect(prompt.systemPrompt).toContain(
-			`${checkout} as the default implementation directory`,
-		)
-	})
-
-	test("rejects CLI context for a different workbase", async () => {
-		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
-		const handlers = load({
-			ok: true,
-			result: {
-				workbase: { root: join(root, "other") },
-				target: { kind: "epic", epicId: "example" },
-				validation: { valid: true },
-			},
-		})
-
-		expect(
-			await handlers.get("before_agent_start")?.(
-				{ systemPrompt: "Base" },
-				{ cwd: root },
-			),
-		).toBeUndefined()
-	})
-})

package/src/check-commits.test.ts

@@ -1,58 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test"
-import { writeFileSync } from "node:fs"
-import { join } from "node:path"
-import { cleanupTempDir, createTempDir } from "./test-utils"
-
-const checkCommits = join(import.meta.dir, "../scripts/check-commits")
-
-describe("check-commits", () => {
-	let root: string
-
-	function git(...args: string[]): void {
-		const result = Bun.spawnSync(["git", ...args], { cwd: root })
-		if (result.exitCode !== 0) {
-			throw new Error(new TextDecoder().decode(result.stderr))
-		}
-	}
-
-	function commit(subject: string, file: string): void {
-		writeFileSync(join(root, file), `${subject}\n`)
-		git("add", file)
-		git("commit", "-m", subject)
-	}
-
-	beforeEach(async () => {
-		root = await createTempDir()
-		git("init", "--initial-branch=main")
-		git("config", "user.email", "agency@example.com")
-		git("config", "user.name", "Agency Test")
-		commit("chore: initial commit", "initial.txt")
-		git("update-ref", "refs/remotes/origin/main", "HEAD")
-	})
-
-	afterEach(async () => cleanupTempDir(root))
-
-	test("allows merge commits with non-conventional subjects", () => {
-		git("checkout", "-b", "feature")
-		commit("feat: add feature", "feature.txt")
-		git("checkout", "-b", "topic", "main")
-		commit("fix: add topic", "topic.txt")
-		git("checkout", "feature")
-		git("merge", "--no-ff", "topic", "-m", "Combine topic into feature")
-
-		const result = Bun.spawnSync([checkCommits], { cwd: root })
-
-		expect(result.exitCode).toBe(0)
-	})
-
-	test("rejects non-conventional non-merge commits", () => {
-		commit("not a conventional commit", "invalid.txt")
-
-		const result = Bun.spawnSync([checkCommits], { cwd: root })
-
-		expect(result.exitCode).toBe(1)
-		expect(new TextDecoder().decode(result.stderr)).toContain(
-			"not a conventional commit",
-		)
-	})
-})