@markjaquith/agency 2.27.0 → 2.28.1

package/src/services/DoctorService.ts

@@ -0,0 +1,419 @@
+import { Effect, Either } from "effect"
+import { constants } from "node:fs"
+import { access } from "node:fs/promises"
+import { isAbsolute, join, resolve } from "node:path"
+import { EpicService } from "./EpicService"
+import { FileSystemService } from "./FileSystemService"
+import { IntegrationService } from "./IntegrationService"
+import { PhaseService } from "./PhaseService"
+import { RepositoryService } from "./RepositoryService"
+import { TaskService } from "./TaskService"
+import { WorkbaseService } from "./WorkbaseService"
+import { WorktreeService } from "./WorktreeService"
+
+type DoctorCheckLevel = "error" | "warning" | "optional"
+
+interface DoctorCheck {
+	readonly id: string
+	readonly category:
+		| "tool"
+		| "integration"
+		| "workbase"
+		| "repository"
+		| "ref"
+		| "worktree"
+		| "permission"
+	readonly level: DoctorCheckLevel
+	readonly status: "pass" | "fail"
+	readonly message: string
+	readonly remediation: string | null
+}
+
+interface DoctorReport {
+	readonly version: 1
+	readonly root: string
+	readonly healthy: boolean
+	readonly summary: {
+		readonly passed: number
+		readonly errors: number
+		readonly warnings: number
+		readonly optional: number
+	}
+	readonly checks: readonly DoctorCheck[]
+}
+
+const executableAvailable = (executable: string, root: string) =>
+	Effect.tryPromise({
+		try: async () => {
+			if (executable.includes("/")) {
+				const path = isAbsolute(executable)
+					? executable
+					: resolve(root, executable)
+				await access(path, constants.X_OK)
+				return true
+			}
+			return Bun.which(executable) !== null
+		},
+		catch: () => false,
+	}).pipe(Effect.catchAll(() => Effect.succeed(false)))
+
+const permissionAvailable = (path: string, mode: number) =>
+	Effect.tryPromise({
+		try: () => access(path, mode).then(() => true),
+		catch: () => false,
+	}).pipe(Effect.catchAll(() => Effect.succeed(false)))
+
+const messageOf = (error: unknown) =>
+	error instanceof Error
+		? error.message
+		: typeof error === "object" &&
+			  error !== null &&
+			  "message" in error &&
+			  typeof error.message === "string"
+			? error.message
+			: String(error)
+
+export class DoctorService extends Effect.Service<DoctorService>()(
+	"DoctorService",
+	{
+		sync: () => ({
+			inspect: (startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const epics = yield* EpicService
+					const fs = yield* FileSystemService
+					const integrations = yield* IntegrationService
+					const phases = yield* PhaseService
+					const repositories = yield* RepositoryService
+					const tasks = yield* TaskService
+					const workbases = yield* WorkbaseService
+					const worktrees = yield* WorktreeService
+					const { root, config } = yield* workbases.loadConfig(startPath)
+					const checks: DoctorCheck[] = []
+					const add = (
+						check: Omit<DoctorCheck, "remediation"> & {
+							readonly remediation?: string
+						},
+					) =>
+						checks.push({
+							...check,
+							remediation:
+								check.status === "fail"
+									? (check.remediation ?? "Remediation is unknown.")
+									: null,
+						})
+
+					const tool = function* (
+						id: string,
+						executable: string,
+						level: DoctorCheckLevel,
+						label: string,
+					) {
+						const available = yield* executableAvailable(executable, root)
+						add({
+							id,
+							category: id.startsWith("tool.") ? "tool" : "integration",
+							level,
+							status: available ? "pass" : "fail",
+							message: available
+								? `${label} executable '${executable}' is available`
+								: `${label} executable '${executable}' is unavailable`,
+							remediation:
+								level === "optional"
+									? `Install '${executable}' to enable ${label.toLowerCase()}, or leave it unavailable if unused.`
+									: `Install '${executable}' and ensure it is executable on PATH.`,
+						})
+						return available
+					}
+
+					const gitAvailable = yield* tool("tool.git", "git", "error", "Git")
+					yield* tool(
+						"capability.runner.opencode",
+						"opencode",
+						"optional",
+						"OpenCode runner",
+					)
+					yield* tool(
+						"capability.runner.claude",
+						"claude",
+						"optional",
+						"Claude runner",
+					)
+
+					const configuredCommands: readonly (readonly [
+						string,
+						readonly string[],
+						string,
+					])[] = [
+						...(config.chooserCommand
+							? [
+									[
+										"integration.chooser",
+										config.chooserCommand,
+										"Chooser",
+									] as const,
+								]
+							: []),
+						...(config.worktreeCreateCommand
+							? [
+									[
+										"integration.worktree-create",
+										config.worktreeCreateCommand,
+										"Worktree creator",
+									] as const,
+								]
+							: []),
+						...Object.entries(config.runners ?? {}).map(
+							([name, runner]) =>
+								[
+									`integration.runner.${name}`,
+									runner.command,
+									`Configured runner '${name}'`,
+								] as const,
+						),
+						...Object.entries(config.runners ?? {}).flatMap(([name, runner]) =>
+							runner.resumeCommand
+								? [
+										[
+											`integration.runner.${name}.resume`,
+											runner.resumeCommand,
+											`Configured runner '${name}' resume`,
+										] as const,
+									]
+								: [],
+						),
+						...(config.delivery
+							? [
+									[
+										`integration.delivery.${config.delivery.provider}`,
+										config.delivery.createCommand,
+										`Delivery provider '${config.delivery.provider}'`,
+									] as const,
+									[
+										`integration.delivery.${config.delivery.provider}.query`,
+										config.delivery.queryCommand,
+										`Delivery provider '${config.delivery.provider}' query`,
+									] as const,
+								]
+							: []),
+					]
+					for (const [id, command, label] of configuredCommands) {
+						yield* tool(id, command[0]!, "error", label)
+					}
+
+					const validation = yield* workbases.validate(root)
+					add({
+						id: "workbase.validation",
+						category: "workbase",
+						level: "error",
+						status: validation.valid ? "pass" : "fail",
+						message: validation.valid
+							? "Workbase documents and relationships are valid"
+							: `Workbase validation found ${validation.issues.length} issue(s): ${validation.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`,
+						remediation:
+							"Run 'agency validate' and correct every reported issue.",
+					})
+
+					for (const [id, mode, level, label, remediation] of [
+						[
+							"permission.workbase.read",
+							constants.R_OK,
+							"error",
+							"readable",
+							`Grant the current user read access to ${root}.`,
+						],
+						[
+							"permission.workbase.write",
+							constants.W_OK,
+							"warning",
+							"writable",
+							`Grant the current user write access to ${root} before running mutation commands.`,
+						],
+					] as const) {
+						const available = yield* permissionAvailable(root, mode)
+						add({
+							id,
+							category: "permission",
+							level,
+							status: available ? "pass" : "fail",
+							message: `Workbase root is ${available ? "" : "not "}${label}`,
+							remediation,
+						})
+					}
+
+					const integrationStatus = yield* integrations.status(root)
+					for (const file of integrationStatus.files) {
+						const failed = file.state === "missing" || file.state === "drifted"
+						add({
+							id: `integration.file.${file.name}`,
+							category: "integration",
+							level: 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.",
+						})
+					}
+
+					const refs = new Map<string, Set<string>>()
+					const declareRef = (repo: string, ref: string) => {
+						const values = refs.get(repo) ?? new Set<string>()
+						values.add(ref)
+						refs.set(repo, values)
+					}
+					if (validation.valid) {
+						for (const epic of yield* epics.list(root)) {
+							for (const reference of epic.data.repos)
+								declareRef(reference.repo, reference.ref)
+						}
+						for (const task of yield* tasks.list(root)) {
+							if ("repo" in task.data) {
+								declareRef(task.data.repo, task.data.base)
+								for (const reference of task.data.repos ?? [])
+									declareRef(reference.repo, reference.ref)
+							} else {
+								for (const phase of yield* phases.list(task.id, root)) {
+									declareRef(phase.data.repo, phase.data.base)
+									for (const reference of phase.data.repos ?? [])
+										declareRef(reference.repo, reference.ref)
+								}
+							}
+						}
+					}
+
+					const repositoryList = gitAvailable
+						? yield* repositories.list(root)
+						: []
+					if (!gitAvailable) {
+						add({
+							id: "repository.inspection",
+							category: "repository",
+							level: "warning",
+							status: "fail",
+							message:
+								"Repository, ref, remote, and worktree checks were skipped because Git is unavailable",
+							remediation: "Install 'git' and rerun 'agency doctor'.",
+						})
+					}
+					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
+						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.`,
+						})
+						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`,
+							remediation: `Run 'agency repo remote ${repository.alias} <url>' to configure origin.`,
+						})
+
+						for (const ref of [...(refs.get(repository.alias) ?? [])].sort()) {
+							const local = yield* fs.runCommand(
+								[
+									"git",
+									"-C",
+									repository.path,
+									"rev-parse",
+									"--verify",
+									`${ref}^{commit}`,
+								],
+								{ captureOutput: true },
+							)
+							const remote =
+								local.exitCode === 0
+									? local
+									: yield* fs.runCommand(
+											[
+												"git",
+												"-C",
+												repository.path,
+												"rev-parse",
+												"--verify",
+												`origin/${ref}^{commit}`,
+											],
+											{ captureOutput: true },
+										)
+							const found = local.exitCode === 0 || remote.exitCode === 0
+							add({
+								id: `ref.${repository.alias}.${ref}`,
+								category: "ref",
+								level: "error",
+								status: found ? "pass" : "fail",
+								message: `Declared ref '${ref}' for '${repository.alias}' is ${found ? "available" : "missing"}`,
+								remediation: `Run 'agency repo fetch ${repository.alias}' and verify that ref '${ref}' exists on origin.`,
+							})
+						}
+					}
+
+					if (validation.valid && gitAvailable) {
+						const inspected = yield* Effect.either(worktrees.list(root))
+						if (Either.isLeft(inspected)) {
+							add({
+								id: "worktree.inspection",
+								category: "worktree",
+								level: "warning",
+								status: "fail",
+								message: `Worktree inspection failed: ${messageOf(inspected.left)}`,
+								remediation:
+									"Remediation is unknown; inspect repositories with 'agency worktree list --json'.",
+							})
+						} else {
+							for (const inspection of inspected.right) {
+								const target =
+									inspection.owner.kind === "phase"
+										? `${inspection.owner.taskId}.${inspection.owner.phaseId}`
+										: inspection.owner.taskId
+								add({
+									id: `worktree.${inspection.owner.kind}.${target}`,
+									category: "worktree",
+									level: "error",
+									status: inspection.conflicts.length === 0 ? "pass" : "fail",
+									message:
+										inspection.conflicts.length === 0
+											? `Worktree registrations for '${target}' are consistent`
+											: inspection.conflicts
+													.map((conflict) => conflict.message)
+													.join("; "),
+									remediation: `Run 'agency worktree inspect ${inspection.owner.taskId}${inspection.owner.phaseId ? ` ${inspection.owner.phaseId}` : ""}', then use 'agency worktree repair' if appropriate.`,
+								})
+							}
+						}
+					}
+
+					const summary = {
+						passed: checks.filter((check) => check.status === "pass").length,
+						errors: checks.filter(
+							(check) => check.status === "fail" && check.level === "error",
+						).length,
+						warnings: checks.filter(
+							(check) => check.status === "fail" && check.level === "warning",
+						).length,
+						optional: checks.filter(
+							(check) => check.status === "fail" && check.level === "optional",
+						).length,
+					}
+					return {
+						version: 1,
+						root,
+						healthy: summary.errors === 0,
+						summary,
+						checks,
+					} satisfies DoctorReport
+				}),
+		}),
+	},
+) {}

package/src/services/IntegrationService.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
 import { createHash } from "node:crypto"
-import { mkdir, symlink, unlink } from "node:fs/promises"
+import { mkdir, stat, symlink, unlink, utimes } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { managedWorkbaseAgents } from "../workbase/agents-file"
@@ -19,6 +19,9 @@ const managed = (prefix: string, body: string, suffix = "") => {
 	return `${prefix}${checksum}${suffix}\n\n${body}`
 }
 
+const managedBody = (content: string) =>
+	content.slice(content.indexOf("\n\n") + 2)
+
 const status = (root: string) =>
 	runTestEffect(
 		IntegrationService.pipe(Effect.flatMap((service) => service.status(root))),
@@ -47,7 +50,7 @@ describe("IntegrationService", () => {
 		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
 
 		await write(root, "AGENTS.md", managedWorkbaseAgents)
-		await write(root, ".opencode/opencode.jsonc", managedWorkbaseOpencode(root))
+		await write(root, ".opencode/opencode.jsonc", managedWorkbaseOpencode)
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"managed",
 			"managed",
@@ -68,6 +71,48 @@ describe("IntegrationService", () => {
 		])
 	})
 
+	test("generates context-first safety and execution closeout guidance", () => {
+		const body = managedBody(managedWorkbaseAgents)
+
+		expect(body).toContain("agency context . --json")
+		expect(body).toContain("authority.writable.checkoutPath")
+		expect(body).toContain("Do not begin execution without a claim")
+		expect(body).toContain("Run `agency validate`")
+		expect(body).toContain("only with explicit user intent")
+		expect(body).toContain("An execution unit is `working`")
+		expect(body).toContain("It becomes `done`")
+		expect(body).toContain("solely because its PR")
+		expect(body).toContain("creating or updating a PR")
+		expect(body).toContain("marking it ready")
+		expect(body).toMatch(/completing\s+a refinement loop/)
+		expect(body).toContain("pausing or handing off")
+		expect(body).toContain("`agency task status` or `agency phase status`")
+		expect(body).toContain("`TASK.md` or `PHASE.md`")
+		expect(body).toContain("PR state, current head, diff summary")
+		expect(body).toContain("Run `agency validate` before reporting completion")
+		expect(body).toContain("agency integration status")
+	})
+
+	test("grants OpenCode access to the complete workbase", () => {
+		const config = JSON.parse(managedBody(managedWorkbaseOpencode))
+
+		expect(config.references).toEqual({
+			tasks: {
+				path: "../tasks",
+				description:
+					"Agency task definitions and execution context; authority still comes from agency context",
+			},
+			epics: {
+				path: "../epics",
+				description:
+					"Agency epic definitions and orchestration context; no implementation write authority",
+			},
+		})
+		expect(config.permission).toEqual({
+			external_directory: { "../**": "allow" },
+		})
+	})
+
 	test("treats an existing JSON OpenCode config as customized", async () => {
 		await write(root, ".opencode/opencode.json", '{"model":"test/model"}\n')
 
@@ -95,7 +140,7 @@ describe("IntegrationService", () => {
 		])
 		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(customAgents)
 		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
-			managedWorkbaseOpencode(root),
+			managedWorkbaseOpencode,
 		)
 
 		await unlink(join(root, "AGENTS.md"))
@@ -106,6 +151,21 @@ describe("IntegrationService", () => {
 		)
 	})
 
+	test("does not rewrite an already-current OpenCode configuration", async () => {
+		const path = join(root, ".opencode/opencode.jsonc")
+		await write(root, ".opencode/opencode.jsonc", managedWorkbaseOpencode)
+		const timestamp = new Date("2000-01-01T00:00:00.000Z")
+		await utimes(path, timestamp, timestamp)
+
+		const result = await sync(root)
+
+		expect(result.files[1]).toMatchObject({
+			state: "managed",
+			changed: false,
+		})
+		expect((await stat(path)).mtimeMs).toBe(timestamp.getTime())
+	})
+
 	test("does not overwrite managed files whose checksums no longer match", async () => {
 		const tampered = `${managed(
 			"<!-- agency-managed: sha256=",
@@ -122,6 +182,23 @@ describe("IntegrationService", () => {
 		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(tampered)
 	})
 
+	test("does not overwrite a user-modified OpenCode configuration", async () => {
+		const tampered = `${managed(
+			"// agency-managed: sha256=",
+			'{"references":{}}\n',
+		)}// User edit\n`
+		await write(root, ".opencode/opencode.jsonc", tampered)
+
+		const result = await sync(root)
+		expect(result.files[1]).toMatchObject({
+			state: "customized",
+			changed: false,
+		})
+		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
+			tampered,
+		)
+	})
+
 	test("does not follow symlinked integration files", async () => {
 		const target = join(root, "custom-agents.md")
 		await Bun.write(target, "# External instructions\n")

package/src/services/IntegrationService.ts

@@ -75,7 +75,7 @@ const inspect = (root: string) =>
 					"opencode",
 					opencodePath,
 					yield* fs.readFile(opencodePath),
-					managedWorkbaseOpencode(root),
+					managedWorkbaseOpencode,
 					canUpdateManagedWorkbaseOpencode,
 				),
 			)
@@ -119,7 +119,7 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 								yield* fs.writeFile(status.path, managedWorkbaseAgents)
 							} else {
 								yield* fs.createDirectory(join(root, ".opencode"))
-								yield* fs.writeFile(status.path, managedWorkbaseOpencode(root))
+								yield* fs.writeFile(status.path, managedWorkbaseOpencode)
 							}
 						}
 						files.push({

package/src/test-utils.ts

@@ -19,6 +19,7 @@ import { ClaimService } from "./services/ClaimService"
 import { SyncService } from "./services/SyncService"
 import { ReadinessService } from "./services/ReadinessService"
 import { GraphMutationService } from "./services/GraphMutationService"
+import { DoctorService } from "./services/DoctorService"
 
 export const createTempDir = () => mkdtemp(join(tmpdir(), "agency-test-"))
 
@@ -42,6 +43,7 @@ const TestLayer = Layer.mergeAll(
 	SyncService.Default,
 	ReadinessService.Default,
 	GraphMutationService.Default,
+	DoctorService.Default,
 )
 
 export async function runTestEffect<A, E>(

package/src/workbase/AGENTS.md

@@ -4,34 +4,68 @@ This directory is an Agency workbase. Epics, tasks, and phases are durable
 Markdown documents; repository aliases and generated Git worktrees provide code
 access.
 
-## Session Context
+## Bootstrap
 
-Before doing work, identify the current entity from the working directory and
-read its context:
+Start every session with one read-only command:
 
-- In `epics/<epic>/`, read `EPIC.md`. Coordinate the epic's tasks without
-  writing implementation code.
-- In `tasks/<task>/`, read `TASK.md`. A task with `phases` is an orchestration
-  session; a task without `phases` is a single execution unit.
-- In `tasks/<task>/phases/<phase>/`, read both `../../TASK.md` and `PHASE.md`.
-  The phase is the execution unit.
+```bash
+agency context . --json
+```
 
-For execution units, writable and reference checkouts live under `code/` when
-materialized. Write only through the checkout named by the singular `repo`
-field. Repositories listed in plural `repos` are read-only references.
+Use the returned target, document paths and revisions, dependency readiness,
+authority, checkout state, PR state, and validation result. Do not infer these
+from directory names or stale prose.
+
+## Authority
+
+- An epic or multi-phase task is orchestration context and has no implementation
+  write authority.
+- For an execution unit, write code only at
+  `authority.writable.checkoutPath`. Every `authority.references` checkout is
+  read-only, even if filesystem permissions allow writes.
+- Keep task-wide decisions in `TASK.md` and phase-specific delivery context in
+  `PHASE.md`. Use Agency commands for structural frontmatter mutations.
 
 ## Safety
 
-- Discovery and observational commands are read-only; use
-  `agency integration sync` to update managed agent files explicitly.
-- Keep task-level decisions in `TASK.md` and phase-specific delivery context in
-  `PHASE.md`.
-- Coordinate execution ownership with `agency claim`, `agency release`, and
-  `agency finish`; `agency work` claims execution units before launch.
+- Stop on validation errors, dependency blockers, an unexpected writable
+  repository, or a conflicting active claim.
+- Do not begin execution without a claim. `agency work` claims before launch;
+  external orchestrators use `agency claim` with the revision from context.
 - Do not manually create, move, or remove worktrees under `code/`.
 - Use `agency archive`, rather than moving work item folders manually.
 - Do not edit bare repositories or repository symlinks under `repos/`.
 - Do not run `agency work` from an active agent session unless the user
   explicitly asks to launch another agent.
 - Run `agency validate` before worktree or pull-request operations.
-- Create a pull request only when the user explicitly requests it.
+- Create a pull request only with explicit user intent, using
+  `agency pr create <task> [phase]` so the URL is recorded durably.
+
+## Closeout
+
+An execution unit is `working` while implementation or requested delivery work
+remains. It becomes `done` when both are complete, even if its PR remains open
+for review or merge. Do not leave a task or phase `working` solely because its PR
+is open; if merge was requested, merge remains delivery work.
+
+At each closeout trigger (creating or updating a PR, marking it ready, completing
+a refinement loop, or pausing or handing off completed implementation work):
+
+- Use `agency task status` or `agency phase status` to set the execution unit's
+  current status. Finish an active claim with the current revision via
+  `agency finish`.
+- Refresh durable delivery context in `TASK.md` or `PHASE.md`, including recorded
+  PR state, current head, diff summary, and verification results after later
+  pushes when those details are maintained there.
+- Run `agency validate` before reporting completion.
+
+## Managed Integration
+
+`agency integration status` reports `managed`, `drifted`, `customized`, or
+`missing` generated files. `agency integration sync` updates only missing or
+checksum-safe drifted files and preserves user-customized files. `agency init`
+creates these files, and `agency work` reconciles them before launching an agent.
+
+OpenCode can access the complete workbase tree, but this filesystem permission
+does not expand Agency write authority beyond the checkout reported by
+`agency context`.