@markjaquith/agency 2.29.0 → 2.30.1

package/src/readiness.test.ts

@@ -1,10 +1,21 @@
 import { describe, expect, test } from "bun:test"
 import {
+	WORK_STATUS_TRANSITIONS,
 	aggregateProgress,
 	canTransitionStatus,
 	isDependencySatisfied,
+	isTerminalStatus,
 	readinessState,
 } from "./readiness"
+import type { WorkStatus } from "./workbase/schemas"
+
+const statuses: readonly WorkStatus[] = [
+	"open",
+	"working",
+	"delegated",
+	"done",
+	"dropped",
+]
 
 describe("readiness model", () => {
 	test("only done satisfies dependencies and terminal states remain distinct", () => {
@@ -24,24 +35,71 @@ describe("readiness model", () => {
 		})
 	})
 
-	test("rolls child statuses into deterministic aggregate progress", () => {
-		expect(aggregateProgress(["done", "dropped"])).toEqual({
-			status: "dropped",
-			total: 2,
-			open: 0,
-			working: 0,
-			delegated: 0,
-			done: 1,
-			dropped: 1,
-			terminal: 2,
-		})
+	test("classifies every status and dependency state", () => {
+		expect(statuses.map(isTerminalStatus)).toEqual([
+			false,
+			false,
+			false,
+			true,
+			true,
+		])
+		expect([...statuses, undefined].map(isDependencySatisfied)).toEqual([
+			false,
+			false,
+			false,
+			true,
+			false,
+			false,
+		])
 	})
 
-	test("requires terminal work to reopen before changing its outcome", () => {
-		expect(canTransitionStatus("open", "done")).toBe(true)
-		expect(canTransitionStatus("working", "delegated")).toBe(true)
-		expect(canTransitionStatus("done", "dropped")).toBe(false)
-		expect(canTransitionStatus("dropped", "done")).toBe(false)
-		expect(canTransitionStatus("done", "open")).toBe(true)
+	test("covers the complete status transition matrix", () => {
+		for (const from of statuses) {
+			for (const to of statuses) {
+				expect(canTransitionStatus(from, to), `${from} -> ${to}`).toBe(
+					WORK_STATUS_TRANSITIONS[from].includes(to as never),
+				)
+			}
+		}
+	})
+
+	test("rolls every status-precedence branch into aggregate progress", () => {
+		const cases: readonly [readonly WorkStatus[], WorkStatus][] = [
+			[[], "open"],
+			[["done", "done"], "done"],
+			[["done", "dropped"], "dropped"],
+			[["open", "working", "delegated"], "working"],
+			[["open", "delegated"], "delegated"],
+			[["open", "done"], "open"],
+		]
+
+		for (const [input, status] of cases) {
+			const result = aggregateProgress(input)
+			expect(result.status, input.join(",") || "empty").toBe(status)
+			expect(result.total).toBe(input.length)
+			expect(result.terminal).toBe(
+				input.filter((value) => value === "done" || value === "dropped").length,
+			)
+			for (const value of statuses) {
+				expect(result[value]).toBe(
+					input.filter((candidate) => candidate === value).length,
+				)
+			}
+		}
+	})
+
+	test("deduplicates and sorts blockers while honoring explicit readiness", () => {
+		expect(
+			readinessState(
+				"open",
+				[{ id: "task:z" }, { id: "task:a" }, { id: "task:z" }],
+				true,
+			),
+		).toEqual({
+			ready: true,
+			blocked: false,
+			blockedBy: ["task:a", "task:z"],
+			terminal: false,
+		})
 	})
 })

package/src/services/DoctorService.ts

@@ -242,15 +242,20 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 
 					const integrationStatus = yield* integrations.status(root)
 					for (const file of integrationStatus.files) {
-						const failed = file.state === "missing" || file.state === "drifted"
+						const failed =
+							file.state === "missing" ||
+							file.state === "drifted" ||
+							(file.name === "opencode" && file.state === "customized")
 						add({
 							id: `integration.file.${file.name}`,
 							category: "integration",
-							level: file.state === "customized" ? "optional" : "warning",
+							level:
+								file.name === "agents" && file.state === "customized"
+									? "optional"
+									: "warning",
 							status: failed ? "fail" : "pass",
-							message: `${file.name} integration file is ${file.state}: ${file.path}`,
-							remediation:
-								"Run 'agency integration sync' to restore managed content.",
+							message: `${file.name} integration file is ${file.state}: ${file.path}. ${file.diagnostic}`,
+							remediation: file.remediation ?? undefined,
 						})
 					}
 
@@ -295,31 +300,40 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 						})
 					}
 					for (const repository of repositoryList) {
-						const verified = yield* fs.runCommand(
-							["git", "-C", repository.path, "rev-parse", "--git-dir"],
-							{ captureOutput: true },
-						)
-						const repositoryValid = verified.exitCode === 0
+						const missing = repository.states.includes("missing")
+						const repositoryValid =
+							!missing && !repository.states.includes("invalid")
 						add({
 							id: `repository.${repository.alias}.valid`,
 							category: "repository",
 							level: "error",
 							status: repositoryValid ? "pass" : "fail",
-							message: repositoryValid
-								? `Repository '${repository.alias}' is a valid Git repository`
-								: `Repository '${repository.alias}' is not a valid Git repository`,
-							remediation: `Run 'agency repo verify ${repository.alias}', then repair or relink the repository.`,
+							message: missing
+								? `Repository '${repository.alias}' is declared but not materialized`
+								: repositoryValid
+									? `Repository '${repository.alias}' is a valid Git repository`
+									: `Repository '${repository.alias}' is not a valid Git repository`,
+							remediation: missing
+								? "Run 'agency repo setup --apply'."
+								: `Run 'agency repo verify ${repository.alias}', then repair or relink the repository.`,
 						})
 						add({
 							id: `repository.${repository.alias}.remote`,
 							category: "repository",
 							level: "warning",
-							status: repository.remote ? "pass" : "fail",
-							message: repository.remote
-								? `Repository '${repository.alias}' origin is ${repository.remote}`
-								: `Repository '${repository.alias}' has no origin remote`,
+							status:
+								repository.declaredRemote &&
+								!repository.states.includes("remote-drifted")
+									? "pass"
+									: "fail",
+							message: repository.states.includes("remote-drifted")
+								? `Repository '${repository.alias}' origin differs from ${repository.declaredRemote}`
+								: repository.declaredRemote
+									? `Repository '${repository.alias}' portable origin is ${repository.declaredRemote}`
+									: `Repository '${repository.alias}' has no portable origin declaration`,
 							remediation: `Run 'agency repo remote ${repository.alias} <url>' to configure origin.`,
 						})
+						if (!repositoryValid) continue
 
 						for (const ref of [...(refs.get(repository.alias) ?? [])].sort()) {
 							const local = yield* fs.runCommand(

package/src/services/EpicService.ts

@@ -81,7 +81,7 @@ export class EpicService extends Effect.Service<EpicService>()("EpicService", {
 				}
 
 				for (const { repo: alias } of data.repos) {
-					if (!(yield* fs.exists(join(root, "repos", alias)))) {
+					if (!(yield* workbase.hasRepositoryAlias(alias, root))) {
 						return yield* new EpicError({
 							message: `Unknown repository alias '${alias}'`,
 						})

package/src/services/GraphMutationService.ts

@@ -309,7 +309,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 						"epic metadata",
 					)
 					for (const reference of data.repos) {
-						if (!(yield* fs.exists(join(root, "repos", reference.repo)))) {
+						if (!(yield* workbase.hasRepositoryAlias(reference.repo, root))) {
 							return yield* new GraphMutationError({
 								message: `Unknown repository alias '${reference.repo}'`,
 							})
@@ -420,7 +420,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 							})
 						}
 						for (const alias of aliases) {
-							if (!(yield* fs.exists(join(root, "repos", alias)))) {
+							if (!(yield* workbase.hasRepositoryAlias(alias, root))) {
 								return yield* new GraphMutationError({
 									message: `Unknown repository alias '${alias}'`,
 								})
@@ -538,7 +538,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 						})
 					}
 					for (const alias of aliases) {
-						if (!(yield* fs.exists(join(root, "repos", alias)))) {
+						if (!(yield* workbase.hasRepositoryAlias(alias, root))) {
 							return yield* new GraphMutationError({
 								message: `Unknown repository alias '${alias}'`,
 							})

package/src/services/GraphService.ts

@@ -197,13 +197,20 @@ export class GraphService extends Effect.Service<GraphService>()(
 						}
 					}
 
-					const repositoryRecords: RepositoryRecord[] = []
+					const repositoryRecords = new Map<string, RepositoryRecord>()
 					const reposPath = join(root, "repos")
+					for (const alias of Object.keys(config.repositories ?? {}).sort()) {
+						repositoryRecords.set(alias, {
+							alias,
+							path: join(reposPath, alias),
+							target: null,
+						})
+					}
 					if (yield* fs.isDirectory(reposPath)) {
 						for (const entry of (yield* fs.readDirectory(reposPath))
-							.filter((item) => item.isDirectory || item.isSymlink)
+							.filter((item) => !item.name.startsWith(".agency-"))
 							.sort((a, b) => a.name.localeCompare(b.name))) {
-							repositoryRecords.push({
+							repositoryRecords.set(entry.name, {
 								alias: entry.name,
 								path: join(reposPath, entry.name),
 								target: entry.isSymlink
@@ -760,7 +767,9 @@ export class GraphService extends Effect.Service<GraphService>()(
 							...(yield* executionDetails(phase.path, phase.data)),
 						})
 					}
-					for (const repository of repositoryRecords) {
+					for (const repository of [...repositoryRecords.values()].sort(
+						(a, b) => a.alias.localeCompare(b.alias),
+					)) {
 						nodes.push({
 							id: repositoryNodeId(repository.alias),
 							kind: "repository",

package/src/services/IntegrationService.test.ts

@@ -97,30 +97,55 @@ describe("IntegrationService", () => {
 		const config = JSON.parse(managedBody(managedWorkbaseOpencode))
 
 		expect(config.references).toEqual({
-			tasks: {
-				path: "../tasks",
+			workbase: {
+				path: "..",
 				description:
-					"Agency task definitions and execution context; authority still comes from agency context",
+					"Complete Agency workbase context; write authority still comes only from agency context",
 			},
-			epics: {
-				path: "../epics",
-				description:
-					"Agency epic definitions and orchestration context; no implementation write authority",
-			},
-		})
-		expect(config.permission).toEqual({
-			external_directory: { "../**": "allow" },
 		})
+		expect(config.permission).toBeUndefined()
+		expect(managedBody(managedWorkbaseOpencode)).not.toContain(process.cwd())
 	})
 
 	test("treats an existing JSON OpenCode config as customized", async () => {
 		await write(root, ".opencode/opencode.json", '{"model":"test/model"}\n')
 
 		const result = await status(root)
-		expect(result.files[1]).toEqual({
+		expect(result.files[1]).toMatchObject({
 			name: "opencode",
 			path: join(root, ".opencode/opencode.json"),
 			state: "customized",
+			diagnostic: expect.stringContaining("cannot guarantee"),
+			remediation: expect.stringContaining("global config"),
+		})
+	})
+
+	test("treats a JSON config beside managed JSONC as customized", async () => {
+		await write(root, ".opencode/opencode.jsonc", managedWorkbaseOpencode)
+		await write(root, ".opencode/opencode.json", '{"model":"test/model"}\n')
+
+		const result = await status(root)
+		expect(result.files[1]).toMatchObject({
+			name: "opencode",
+			path: join(root, ".opencode/opencode.json"),
+			state: "customized",
+		})
+	})
+
+	test("reports actionable whole-workbase access diagnostics", async () => {
+		let result = await status(root)
+		expect(result.files[1]).toMatchObject({
+			state: "missing",
+			diagnostic: expect.stringContaining("cannot load"),
+			remediation: expect.stringContaining("integration sync"),
+		})
+
+		await write(root, ".opencode/opencode.jsonc", '{"model":"test/model"}\n')
+		result = await status(root)
+		expect(result.files[1]).toMatchObject({
+			state: "customized",
+			diagnostic: expect.stringContaining("cannot guarantee"),
+			remediation: expect.stringContaining("global config"),
 		})
 	})
 

package/src/services/IntegrationService.ts

@@ -17,28 +17,79 @@ interface IntegrationFileStatus {
 	readonly name: "agents" | "opencode"
 	readonly path: string
 	readonly state: IntegrationFileState
+	readonly diagnostic: string
+	readonly remediation: string | null
 }
 
 interface IntegrationSyncFile extends IntegrationFileStatus {
 	readonly changed: boolean
 }
 
+const describe = (
+	name: IntegrationFileStatus["name"],
+	state: IntegrationFileState,
+) => {
+	if (name === "opencode") {
+		if (state === "managed") {
+			return {
+				diagnostic:
+					"Agency's managed OpenCode launch config is ready to provide whole-workbase read access.",
+				remediation: null,
+			}
+		}
+		if (state === "customized") {
+			return {
+				diagnostic:
+					"Agency cannot guarantee whole-workbase read access from this customized OpenCode config.",
+				remediation:
+					"Back up and remove the customized file, run 'agency integration sync', then move any retained custom settings to OpenCode's global config.",
+			}
+		}
+		return {
+			diagnostic:
+				"Agency OpenCode launches cannot load current whole-workbase access.",
+			remediation:
+				"Run 'agency integration sync' to install whole-workbase OpenCode access.",
+		}
+	}
+
+	return state === "missing" || state === "drifted"
+		? {
+				diagnostic: "Managed workbase instructions need synchronization.",
+				remediation:
+					"Run 'agency integration sync' to restore managed instructions.",
+			}
+		: {
+				diagnostic:
+					state === "managed"
+						? "Managed workbase instructions are current."
+						: "Customized workbase instructions are preserved.",
+				remediation: null,
+			}
+}
+
+const fileStatus = (
+	name: IntegrationFileStatus["name"],
+	path: string,
+	state: IntegrationFileState,
+): IntegrationFileStatus => ({ name, path, state, ...describe(name, state) })
+
 const classify = (
 	name: IntegrationFileStatus["name"],
 	path: string,
 	content: string,
 	managed: string,
 	canUpdate: (content: string) => boolean,
-): IntegrationFileStatus => ({
-	name,
-	path,
-	state:
+): IntegrationFileStatus =>
+	fileStatus(
+		name,
+		path,
 		content === managed
 			? "managed"
 			: canUpdate(content)
 				? "drifted"
 				: "customized",
-})
+	)
 
 const inspect = (root: string) =>
 	Effect.gen(function* () {
@@ -51,7 +102,7 @@ const inspect = (root: string) =>
 
 		files.push(
 			(yield* fs.readSymlinkTarget(agentsPath)) !== null
-				? { name: "agents", path: agentsPath, state: "customized" }
+				? fileStatus("agents", agentsPath, "customized")
 				: (yield* fs.exists(agentsPath))
 					? classify(
 							"agents",
@@ -60,15 +111,16 @@ const inspect = (root: string) =>
 							managedWorkbaseAgents,
 							canUpdateManagedWorkbaseAgents,
 						)
-					: { name: "agents", path: agentsPath, state: "missing" },
+					: fileStatus("agents", agentsPath, "missing"),
 		)
 
 		if ((yield* fs.readSymlinkTarget(opencodePath)) !== null) {
-			files.push({
-				name: "opencode",
-				path: opencodePath,
-				state: "customized",
-			})
+			files.push(fileStatus("opencode", opencodePath, "customized"))
+		} else if (
+			(yield* fs.readSymlinkTarget(opencodeJsonPath)) !== null ||
+			(yield* fs.exists(opencodeJsonPath))
+		) {
+			files.push(fileStatus("opencode", opencodeJsonPath, "customized"))
 		} else if (yield* fs.exists(opencodePath)) {
 			files.push(
 				classify(
@@ -79,14 +131,8 @@ const inspect = (root: string) =>
 					canUpdateManagedWorkbaseOpencode,
 				),
 			)
-		} else if (yield* fs.exists(opencodeJsonPath)) {
-			files.push({
-				name: "opencode",
-				path: opencodeJsonPath,
-				state: "customized",
-			})
 		} else {
-			files.push({ name: "opencode", path: opencodePath, state: "missing" })
+			files.push(fileStatus("opencode", opencodePath, "missing"))
 		}
 
 		return files
@@ -123,8 +169,11 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 							}
 						}
 						files.push({
-							...status,
-							state: changed ? "managed" : status.state,
+							...fileStatus(
+								status.name,
+								status.path,
+								changed ? "managed" : status.state,
+							),
 							changed,
 						})
 					}

package/src/services/PhaseService.ts

@@ -174,7 +174,7 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 						})
 					}
 					for (const alias of aliases) {
-						if (!(yield* fs.exists(join(root, "repos", alias)))) {
+						if (!(yield* workbase.hasRepositoryAlias(alias, root))) {
 							return yield* new PhaseError({
 								message: `Unknown repository alias '${alias}'`,
 							})

package/src/services/ReadinessService.test.ts

@@ -187,6 +187,53 @@ describe("ReadinessService", () => {
 		})
 	})
 
+	test("returns ready target IDs and guards structural work targets", async () => {
+		const root = await createWorkbase()
+		roots.push(root)
+
+		const readyIds = await service((readiness) =>
+			readiness.getReadyWorkTargetIds(root),
+		)
+		expect([...readyIds].sort()).toEqual([
+			"epic:delivery",
+			"execution-unit:phase/ship/implement",
+			"phase:ship/implement",
+			"task:ship",
+		])
+		await service((readiness) =>
+			readiness.guardWorkTarget("phase:ship/implement", root),
+		)
+
+		const blocked = await service((readiness) =>
+			Effect.either(readiness.guardWorkTarget("phase:ship/verify", root)),
+		)
+		expect(blocked).toMatchObject({
+			_tag: "Left",
+			left: {
+				_tag: "ExecutionGuardError",
+				action: "work",
+				target: "phase:ship/verify",
+				status: "open",
+				blockedBy: ["phase:ship/implement"],
+			},
+		})
+
+		const missing = await service((readiness) =>
+			Effect.either(readiness.guardWorkTarget("task:missing", root)),
+		)
+		expect(missing).toMatchObject({
+			_tag: "Left",
+			left: {
+				_tag: "ExecutionGuardError",
+				target: "task:missing",
+				blockers: [],
+			},
+		})
+		await service((readiness) =>
+			readiness.guardWorkTarget("task:missing", root, true),
+		)
+	})
+
 	test("uses the same readiness for work and PR guards", async () => {
 		const root = await createWorkbase()
 		roots.push(root)