@markjaquith/agency 2.61.1 → 2.61.3

package/README.md

@@ -527,6 +527,12 @@ and reference authority, local checkout and resolved-commit state, recorded PR
 state, and validation warnings. Only `done` satisfies a dependency; `dropped` is
 terminal but remains a blocker.
 
+`authority.writable` identifies the writable repository checkout, while
+`authority.documents.writable` lists the absolute paths of Agency documents the
+target may maintain. A single-phase task lists its `TASK.md`; a phase lists its
+owning `TASK.md` and active `PHASE.md`; orchestration targets list none. Use
+Agency commands rather than direct edits for structural frontmatter mutations.
+
 Complete output is the default for entity targets. Pass `--compact` explicitly
 to omit document prose and low-level Git details while retaining identity,
 hashes, authority, paths, graph state, materialization state, and validation

package/package.json

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

package/src/commands/context.test.ts

@@ -208,6 +208,10 @@ Phase prose.
 		expect(result.documents.task.body).toContain("Task prose.")
 		expect(result.documents.phase.body).toContain("Phase prose.")
 		expect(result.documents.phase.sha256).toMatch(/^[a-f0-9]{64}$/)
+		expect(result.authority.documents.writable).toEqual([
+			join(root, "tasks/agent-contract/TASK.md"),
+			join(root, "tasks/agent-contract/phases/context-command/PHASE.md"),
+		])
 		expect(result.workspace.writable.branchCommit).toMatch(/^[a-f0-9]{40}$/)
 		expect(result.workspace.writable.baseCommit).toMatch(/^[a-f0-9]{40}$/)
 		expect(result.workspace.references[0].resolvedCommit).toMatch(
@@ -232,6 +236,10 @@ Phase prose.
 			registered: true,
 		})
 		expect(result.authority.writable.checkoutPath).toContain("code/agency")
+		expect(result.authority.documents.writable).toEqual([
+			join(root, "tasks/agent-contract/TASK.md"),
+			join(root, "tasks/agent-contract/phases/context-command/PHASE.md"),
+		])
 	})
 
 	test("reports dependency and validation blockers deterministically", async () => {
@@ -275,6 +283,12 @@ status: dropped
 			taskId: "agent-contract",
 		})
 		expect(task.graph.parent).toEqual({ kind: "epic", id: "contract" })
+		expect(task.authority.documents.writable).toEqual([])
+
+		const executionTask = await readContext(root, "foundations")
+		expect(executionTask.authority.documents.writable).toEqual([
+			join(root, "tasks/foundations/TASK.md"),
+		])
 
 		const workbase = await readContext(root, ".")
 		expect(workbase).toMatchObject({

package/src/commands/sync.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
-import { mkdir } from "node:fs/promises"
+import { chmod, mkdir } from "node:fs/promises"
 import { join } from "node:path"
 import { TaskService } from "../services/TaskService"
 import {
@@ -99,6 +99,44 @@ describe("sync command", () => {
 		})
 	})
 
+	test("groups repeated human-readable warnings by affected target", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "second",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/second",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const originalPath = process.env.PATH
+		const bin = join(root, "bin")
+		await mkdir(bin)
+		await Bun.write(
+			join(bin, "gh"),
+			'#!/bin/sh\necho "provider unavailable" >&2\nexit 1\n',
+		)
+		await chmod(join(bin, "gh"), 0o755)
+		process.env.PATH = `${bin}:${originalPath}`
+		try {
+			const logs = await captureLogs(() =>
+				runTestEffect(sync({ cwd: root, dryRun: true })),
+			)
+			expect(
+				logs.filter((line) => line.includes("provider unavailable")),
+			).toEqual(["Warning 'task:example', 'task:second': provider unavailable"])
+		} finally {
+			process.env.PATH = originalPath
+		}
+	})
+
 	test("reports human-readable progress without polluting JSON output", async () => {
 		const updates: string[] = []
 		const progress: Progress = {

package/src/commands/sync.ts

@@ -8,6 +8,27 @@ interface SyncCommandOptions extends BaseCommandOptions {
 	readonly dryRun?: boolean
 }
 
+interface Notice {
+	readonly kind: string
+	readonly target: string
+	readonly message: string
+	readonly action?: string
+}
+
+const groupedNotices = <T extends Notice>(notices: readonly T[]) => {
+	const groups = new Map<string, { notice: T; targets: string[] }>()
+	for (const notice of notices) {
+		const key = JSON.stringify([notice.kind, notice.message, notice.action])
+		const group = groups.get(key)
+		if (group) group.targets.push(notice.target)
+		else groups.set(key, { notice, targets: [notice.target] })
+	}
+	return groups.values()
+}
+
+const formatTargets = (targets: readonly string[]) =>
+	targets.map((target) => `'${target}'`).join(", ")
+
 export const sync = (
 	options: SyncCommandOptions = {},
 	progress: Progress = createProgress({
@@ -62,9 +83,11 @@ export const sync = (
 				`${change.status === "applied" ? "Applied" : "Planned"} ${change.kind} '${change.target}': ${change.message}`,
 			)
 		}
-		for (const warning of result.warnings) {
+		for (const { notice: warning, targets } of groupedNotices(
+			result.warnings,
+		)) {
 			log(
-				`Warning '${warning.target}': ${warning.message}${warning.action ? `. ${warning.action}` : ""}`,
+				`Warning ${formatTargets(targets)}: ${warning.message}${warning.action ? `. ${warning.action}` : ""}`,
 			)
 		}
 		for (const issue of result.repositories.unresolved) {
@@ -72,9 +95,11 @@ export const sync = (
 				`Unresolved repository '${issue.alias}': ${issue.message}. ${issue.action}`,
 			)
 		}
-		for (const issue of result.unresolved) {
+		for (const { notice: issue, targets } of groupedNotices(
+			result.unresolved,
+		)) {
 			log(
-				`Unresolved '${issue.target}': ${issue.message}${issue.action ? `. ${issue.action}` : ""}`,
+				`Unresolved ${formatTargets(targets)}: ${issue.message}${issue.action ? `. ${issue.action}` : ""}`,
 			)
 		}
 		if (

package/src/services/ContextService.ts

@@ -784,6 +784,15 @@ export class ContextService extends Effect.Service<ContextService>()(
 							: null
 					const reviewData =
 						task?.data && "review" in task.data ? task.data.review : null
+					const writableDocuments = reviewData
+						? task
+							? [task.path]
+							: []
+						: executionData && task
+							? phase
+								? [task.path, phase.path]
+								: [task.path]
+							: []
 					const references: readonly RepositoryReference[] = reviewData
 						? [{ repo: reviewData.repo, ref: reviewData.commit }]
 						: executionData
@@ -1078,7 +1087,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 								checkoutPath: reference.checkoutPath,
 							})),
 							documents: {
-								writable: reviewData && task ? [task.path] : [],
+								writable: writableDocuments,
 							},
 						},
 						workspace: options.compact

package/src/services/IntegrationService.test.ts

@@ -418,6 +418,7 @@ describe("IntegrationService", () => {
 		expect(body).toContain("agency next --json")
 		expect(body).toContain("agency <command> --help")
 		expect(body).toContain("authority.writable.checkoutPath")
+		expect(body).toContain("authority.documents.writable")
 		expect(body).toContain("Only `done` satisfies a dependency")
 		expect(body).toContain("Require explicit user intent")
 		expect(body).toContain(

package/src/services/SyncService.test.ts

@@ -64,14 +64,17 @@ case "$*" in
 *mergeable*) ;;
 *) echo "mergeable field was not requested" >&2; exit 2 ;;
 esac
+case "$*" in
+*baseRepository*) echo "unsupported baseRepository field was requested" >&2; exit 3 ;;
+esac
 if [ "$2" = "view" ]; then
 cat <<'JSON'
-{"number":42,"state":"MERGED","title":"Ship","isDraft":false,"headRefName":"feat/example","baseRefName":"main","headRepository":{"nameWithOwner":"example/agency"},"baseRepository":{"nameWithOwner":"example/agency"},"url":"https://github.com/example/agency/pull/42","mergedAt":"2100-01-01T00:00:00Z","mergeCommit":{"oid":"abc"},"mergeable":"MERGEABLE"}
+{"number":42,"state":"MERGED","title":"Ship","isDraft":false,"headRefName":"feat/example","baseRefName":"main","headRepository":{"nameWithOwner":"example/agency"},"url":"https://github.com/example/agency/pull/42","mergedAt":"2100-01-01T00:00:00Z","mergeCommit":{"oid":"abc"},"mergeable":"MERGEABLE"}
 JSON
 exit 0
 fi
 cat <<'JSON'
-[{"number":42,"state":"MERGED","title":"Ship","isDraft":false,"headRefName":"feat/example","baseRefName":"main","headRepository":{"nameWithOwner":"example/agency"},"baseRepository":{"nameWithOwner":"example/agency"},"url":"https://github.com/example/agency/pull/42","mergedAt":"2100-01-01T00:00:00Z","mergeCommit":{"oid":"abc"},"mergeable":"MERGEABLE"}]
+[{"number":42,"state":"MERGED","title":"Ship","isDraft":false,"headRefName":"feat/example","baseRefName":"main","headRepository":{"nameWithOwner":"example/agency"},"url":"https://github.com/example/agency/pull/42","mergedAt":"2100-01-01T00:00:00Z","mergeCommit":{"oid":"abc"},"mergeable":"MERGEABLE"}]
 JSON
 `,
 		)
@@ -172,6 +175,7 @@ pr: null
 		)
 		const invocation = await Bun.file(capture).text()
 		expect(invocation).toContain("--repo\n")
+		expect(invocation).not.toContain("baseRepository")
 		expect(invocation).toContain("GIT_DIR=")
 		expect(invocation).toContain(".jj")
 
@@ -1013,4 +1017,44 @@ exit 9
 			),
 		).toEqual([])
 	})
+
+	test("keeps pull request query failures concise", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "unavailable",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/unavailable",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await Bun.write(
+			join(root, "bin", "gh"),
+			`#!/bin/sh
+echo "Unknown JSON field: unsupported" >&2
+echo "Available fields:" >&2
+echo "  additions" >&2
+exit 1
+`,
+		)
+		await chmod(join(root, "bin", "gh"), 0o755)
+
+		const result = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) => service.reconcile({ cwd: root })),
+			),
+		)
+		expect(result.warnings).toContainEqual({
+			kind: "pr-discovery-unavailable",
+			target: "task:unavailable",
+			message: "Unknown JSON field: unsupported",
+		})
+	})
 })

package/src/services/SyncService.ts

@@ -153,6 +153,15 @@ const isCommitId = (ref: string) => /^[0-9a-f]{40,64}$/i.test(ref)
 const originRef = (ref: string) =>
 	ref.replace(/^refs\/remotes\/origin\//, "").replace(/^origin\//, "")
 
+const GITHUB_PR_FIELDS =
+	"number,state,title,isDraft,headRefName,baseRefName,headRepository,url,mergedAt,mergeCommit,mergeable"
+
+const commandErrorSummary = (stderr: string, fallback: string) =>
+	stderr
+		.split("\n")
+		.map((line) => line.trim())
+		.find(Boolean) ?? fallback
+
 export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 	sync: () => ({
 		reconcile: (
@@ -349,7 +358,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 											"view",
 											existing.url,
 											"--json",
-											"number,state,title,isDraft,headRefName,baseRefName,headRepository,baseRepository,url,mergedAt,mergeCommit,mergeable",
+											GITHUB_PR_FIELDS,
 										],
 										{
 											cwd: repositoryPath,
@@ -372,7 +381,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 											"--state",
 											"all",
 											"--json",
-											"number,state,title,isDraft,headRefName,baseRefName,headRepository,baseRepository,url,mergedAt,mergeCommit,mergeable",
+											GITHUB_PR_FIELDS,
 										],
 										{
 											cwd: repositoryPath,
@@ -824,8 +833,10 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 							warnings.push({
 								kind: existing ? "pr-unavailable" : "pr-discovery-unavailable",
 								target: record.key,
-								message:
-									queried.stderr.trim() || "Could not query delivery provider",
+								message: commandErrorSummary(
+									queried.stderr,
+									"Could not query delivery provider",
+								),
 							})
 						}
 					} else if (existing) {
@@ -858,7 +869,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 							warnings.push({
 								kind: "pr-unavailable",
 								target: record.key,
-								message: `Could not inspect ${existing.url}: ${viewed.stderr.trim()}`,
+								message: `Could not inspect ${existing.url}: ${commandErrorSummary(viewed.stderr, "GitHub query failed")}`,
 							})
 						}
 					} else {
@@ -901,8 +912,10 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 							warnings.push({
 								kind: "pr-discovery-unavailable",
 								target: record.key,
-								message:
-									listed.stderr.trim() || "Could not discover pull requests",
+								message: commandErrorSummary(
+									listed.stderr,
+									"Could not discover pull requests",
+								),
 							})
 						}
 					}

package/src/workbase/AGENTS.md

@@ -48,10 +48,11 @@ agency validate --json
 - A single-phase task or phase is an execution unit with one writable `repo` and
   optional read-only `repos`. Only `done` satisfies a dependency; `dropped` is
   terminal but leaves dependents blocked.
-- For an execution unit, write code only at
+- For an execution unit, write repository content 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
+- Maintain only the Agency documents listed in `authority.documents.writable`:
+  keep task-wide decisions in `TASK.md` and phase-specific delivery context in
   `PHASE.md`. Use Agency commands for structural frontmatter mutations.
 
 ## Consent Boundaries